[vinniefalco]

Summary

master carries five changes that landed in sequence. They ship in one pull request because each was read closely while the next was planned, and the later ones are the debt that reading the earlier ones raised.

Part	Commits	Files	What it is
the std Pack	7357dd23e, 08801150f	26	a new plugin crate holding Cursor's six file tools as stubs
the gateway's API principle	c73db8f7f	1	crates/gateway/README.md states the rule its wire API follows
the Engine cleanup	beb5a43ff through 4eb444630	90	ten steps from a vibelight pass over runvil-internal/engine
the Lua cleanup	0c2477ab2 through 9b4c21a39	136	eight steps from a vibelight pass over runvil-internal/lua
the model-client cleanup	8e763fef2 through 157bc77e9	28	three steps from a vibelight pass over runvil-internal/model-client

24 commits, 238 files, 7203 insertions, 3455 deletions.

The three cleanups are one method applied to three crates: outline the crate with vibelight, raise slop candidates from the outline alone, verify every candidate against the repository and the docs, keep only the ones with a consequence, then deliver a plan whose steps each land as one commit against a green suite. Each plan stays in vibe/ with its findings, its operator answers, and its steps marked completed.

Part 1: the std Pack

This adds plugin-std, the Pack that gives a Runvil agent the file tools every coding agent has, and it copies Cursor's surface rather than inventing one. A model already trained on Cursor's tools then needs no new instructions: it calls Read, Write, StrReplace, Delete, Glob, and Grep, with Cursor's parameter names and Cursor's own descriptions.

Every tool is a stub. A well-formed call answers a text saying the implementation is missing; a call whose arguments miss the schema fails with the parameter named. The stubs exist so the crate, the definitions, the ids, the wire names, and the Lua path are all proven before any file logic lands.

• crates/plugin-std installs runvil/std, so its Pack id is std and every tool id sits under it: std/read, std/write, std/replace, std/rm, std/glob, std/grep.
• Lua calls a tool by its id, tools.call("std/read", { path = "/notes.md" }), and offers the Pack with tools.offer("std"). The model calls the same tool by its wire name, Read, which ToolInfo::wire_name sets. The two layers are deliberately separate: the Lua ids stay short and prefixed, and the wire names copy Cursor exactly.
• Each tool's description and parameter schema are checked in under crates/plugin-std/schemas/ and embedded with include_str!. schemas/EDITS.md records every departure from Cursor's text, per file, each with its reason: Read loses its image and PDF promises because this build reads text only, and three of its sentences stop saying "local filesystem", "the machine", and "the User"; Glob and Grep defaults that said "Cursor workspace root" say the run's filesystem root instead; Grep stops pointing at rg and at the Shell tool, because this Pack offers no shell; Write and StrReplace keep Cursor's parameters, types, and required lists with wording of ours; Delete is kept verbatim.
• src/check.rs validates a call against the stored schema, honoring type, properties, required, enum, and items. It runs before anything else, so a malformed call cannot reach an operation.
• A refusal is an InvalidArguments ToolError that names the parameter and, where it helps, the value it received: std_Grep: 'pattern' is required, and the call left it out.
• A schema keyword the check does not understand is not a reason to refuse a call, and an undeclared parameter passes through, so the tool's own operation decides what it can do with the value.
• A well-formed call returns ToolOutput::trusted rather than a ToolError, so the success path and the failure path are both exercised end to end.
• crates/workshop/server/src/agents.rs installs the Pack in every agent run's Host, beside web, user-input, and mcp. The existing test that lists every installed Pack now expects std too.
• crates/workshop/ui/test/docs-claims.mjs gains the crate to its Plugin doc list, so the wording scan reads its comments for the defined terms and the Pack-activation ban.
• No new outside dependency: serde and serde_json are already in the workspace.

The stub text names the tool twice and says a repeat call is safe but identical, because a model that reads only "not implemented" may retry and conclude its arguments were wrong.

Nothing here touches the filesystem, so the VFS Mode policy gates nothing yet.

What is deliberately not here

• Shell. An in-process shell over the same filesystem is a separate Pack, so a run that wants one declares it.
• Images and PDFs. Read is text only.
• User approval for mutations. The VFS already answers an approval-required error under Ask mode; wiring it to an operator flow is later work.
• ListDir. Cursor gates it behind enableDeprecatedLsTool, which defaults to false, and its replacement exists only as proto, so there is no model-facing definition worth copying.

Part 2: the gateway's API principle

crates/gateway/README.md now states the rule that the gateway's wire API follows. The rule says to follow the standard shape, to add the smallest opt-in extension, and to keep working when the extension is absent.

• The file orders the principle as: the standard rule, extensions, capability discovery, one worked example, the fallback, exclusions, and a check to run before a route or a wire type changes.
• Each addition must be named in the standard's own namespace, documented beside the standard shape that it extends, and opt-in wherever the protocol offers a way to ask.
• POST /v1/chat/completions, POST /v1/embeddings, GET /v1/models, POST /v1/audio/speech, POST /v1/audio/transcriptions, and /v1/realtime follow OpenAI shapes, and /v1/rerank follows the Jina and Cohere shape because OpenAI publishes none.
• The worked extension is a replacement snapshot for realtime transcription, requested through session.include with item.input_audio_transcription.hypothesis, because delta events only append and cannot retract a word.
• The capability endpoint stays a rule only: the file states that no such endpoint exists yet, and this commit changes no route, wire type, or test.

Part 3: the Engine cleanup

vibe/2026-10/2026-10-28-1-engine-vibelight-cleanup.md is a vibelight pass over crates/runvil-internal/engine. 116 findings were raised, 86 accepted and 30 rejected; each accepted one lands as a step.

Two of the ten steps hold the changes that alter what the code can express. The rest are documentation, plus one visibility narrowing.

The two structural changes

One map for the Pack roster. The run context and the shared tool set each kept two maps keyed by Pack name: one recorded whether a Pack could serve the run, and the other the vendor of every Pack that could. Nothing held them in step, so a Pack could carry a vendor while also being refused, and the second map was only ever the usable subset of the first. Both now hold a single map whose entry says either that a Pack can serve, with its vendor, or that it cannot, with the reason. RosterEntry replaces the bare reason, so the disagreement has no shape left to take. vendors is gone with nothing in its place: no field, no constructor argument, no accessor.

Infallible VM access. SectionContext::vm was an Option whose None no live frame could reach, so five error branches promised a failure that could not happen. Only a frame's own destruction clears the slot, so live_vm is now the single read and the accessor hands the VM back directly. Twelve scheduler call sites drop a question mark. Section setup also receives the argument table already marked writable or frozen, in place of a separate optional value and a writable flag, so the mode cannot travel apart from the value it qualifies and nothing can turn a frozen table writable after construction.

The remaining steps

• Root starts. start_root_chain fills the root lineage and root call depth itself and enqueues the chain before returning, so start_h1, end_h1, and start_root_walk lose their own pushes and no caller can set the two root constants. The admission records that track a chain giving its slots back are named for what the slots do rather than for the event that produced them, and ChainOps drops its copy of the run context.
• One producer for the Pack order. A section's render is now asked about exactly the Packs the section stored. SetEvidence splits the render's asked and answered Packs away from the rules that name tools, so a tool-shaped rule can never be built with an empty tool list.
• One owner for the empty-reply message. The Engine's scripted model and the gateway reader kept private copies under a "change together" note, and the copies had already diverged on whitespace-only reasoning. CompletionError::empty_reply is now the one builder, and it settles the disagreement: a reasoning channel holding only whitespace counts as absent.
• Chat effects. Effect::Chat carried a second copy of the completion settings the binding beside it already fixes, so a hand-built effect could send one request while its record logged another. The effect keeps only the binding, and every site that performs a round asks the binding for its settings as it sends.
• Documentation. The Engine's doc comments now describe what its error surface, its run bindings, and its effect records actually do. Three modules that re-exported their dependencies state that as a rule and name the groups that still reach those dependencies directly, and the re-export sets gain the two items callers were reaching past them for. README.md gains the fifth effect kind and scopes the file case to outside a prelude's install.

Part 4: the Lua cleanup

vibe/2026-10-29-1-lua-slop-cleanup.md is the same method applied to crates/runvil-internal/lua, the largest Engine crate at 135 files and 28,852 lines. 130 findings were raised, 15 rejected, 11 duplicates and 6 same-cause findings merged, and 98 kept: 86 cheap and 12 substantial. Both operator decisions were answered in favor.

The goal was one crate that names each fact once, in the file that owns it, with no doc contradicting its own body, and no author-visible behavior change. Every Lua global, table shape, and message the guide documents stays as documented.

What the twelve substantial findings changed

• The instruction quota is gone. HOOK_BUDGET was u64::MAX, so the quota could never trip, and the guide states three times that no instruction limit exists. InstructionBudget became CancelHook, named for the one job the hook still performs, and the firing counter went with it.
• A refusal cannot skip its event. prepare_dispatch took an Option publicly and its None arm fired no ToolResult at all, so a caller could report nothing. It now takes the report it must produce and keeps an Option body private, which makes the silent path unrepresentable.
• Answer carries one failure side. Every variant wrapped its own Result while the failure was identical for all of them. The failure side moved off the variants.
• TaskStatus.ok is gone. It restated what the phase already decided for every phase but Done.
• The compacting flag and its snapshot became two phases. They were hand-paired across five sites with one arm unreachable, and the snapshot outlives the flag by design, so merging them into one would have dropped the retry state.
• sys_live is not an Option. The typestate already guarantees injection before every reader, so the mirror is built at injection and every dead None arm is gone.
• The counts API cannot be misused. increment used to error on an unseeded id, so every dispatch site had to seed first and the error arm was unreachable; counts now seed on increment.
• Offers and ModelSelection name what their locks hold. SectionOffers was the working name, but the Engine already owns a type by that name at the crate seam.
• Request::ToolCall lost its third state. It paired two Options whose only other combination existed for a test hook.
• attach_rendered_tools returns the tools it attached, so its Engine caller stops re-reading a slot it just filled.
• ModelReport names its turn turn, not script.

The rest

The remaining steps are renaming, placement, and documentation: splitting handles and sys, one walkable read-only proxy, one coroutine shim installer, the parse-module names, the protocol docs, the store and key-order modules, and the Error::Lua doc rule stated once across 29 # Errors sections.

Part 5: the model-client cleanup

vibe/2026-10-29-2-model-client-slop.md covers crates/runvil-internal/model-client. 21 findings were accepted, 2 rejected, 18 cheap and 3 substantial, and no operator decision was needed.

• Tool arguments are a map, not a value. ToolCall::arguments was a serde_json::Value documented as always a JSON object, yet the view type modeled a null payload with an Option and a Value::Null arm reachable only from a hand-built literal in a test. The field now holds a Map, and the object check returns the map it proved, so no constructor has to unwrap and no site parses twice.
• CompletionOptions holds one ModelInvocation. It kept its own copies of the three request settings, with its own getters and setters, and a binding copied the three across by hand, so a missed copy would compile and silently send nothing.
• A binding's provider comes from its catalog. provider() read only its own field, so a binding filled from a catalog reported no provider while render_info() reported the catalog's. One expression now answers for both readers, and the Engine's now-redundant copy call is gone.
• Five surface members are gone. ModelSet::from_parts had eleven callers and every one was a test; ModelView::bindings was the only read that cloned a whole list and no Engine path called it; TryFrom<f64> for Temperature was a second spelling of new that nothing used; ModelView::default shadowed Default::default where ModelSet calls the same fact default_alias; and five of six runvil_types re-exports kept paths nothing names resolving.

Facade impact

crates/runvil/public-api.txt changes by six lines:

+pub fn runvil::model::CompletionError::empty_reply(reasoning_present: bool) -> runvil::model::CompletionError
+pub fn runvil::model::CompletionOptions::invocation(&self) -> &runvil::model::ModelInvocation
+pub fn runvil::model::CompletionOptions::with_invocation(self, invocation: runvil::model::ModelInvocation) -> runvil::model::CompletionOptions
-pub runvil::effect::Effect::Chat::options: runvil::model::CompletionOptions
-impl core::convert::TryFrom<f64> for runvil::model::Temperature
-impl core::convert::TryFrom<f64> for runvil::model::Temperature { type Error = runvil::model::TemperatureError }

Effect::Chat loses a field, Temperature loses a conversion, and CompletionError and CompletionOptions each gain published members. Every crate here is publish = false, so none of it is a semver commitment.

Breaking changes

None outside crates/runvil/public-api.txt, which is checked against the code and updated in this pull request. A Plugin crate is not part of the Engine's facade, the std Pack touches no existing type, and the Engine cleanup's one cross-crate interface move is RosterEntry, which replaces a bare String inside an unpublished crate. The Lua and model-client cleanups change no author-visible behavior.

Test plan

Results as the gates report them at 157bc77e9:

• workspace nextest: 5615 tests run, 5615 passed, 76 skipped
• the Workshop partition: 308 tests run, 308 passed, 4 skipped
• the Engine and Lua components: 1624 tests run, 1624 passed
• harness-gateway-client: 431 tests run, 431 passed, 2 skipped
• plugin-std: 32 tests, covering the definitions, the argument check, the PackInfo and install contract, and every stub answer
• the facade gate: build-xtask api --check reports 0 violations and the listing matches public-api.txt
• both clippy runs with warnings denied, plus the headless cargo check -p gateway --no-default-features
• cargo fmt --all --check
• the workspace rustdoc gate with warnings denied, and the facade docs build
• cargo test -p build-xtask for the boundary and structural checks
• the docs-claims wording scan
• cargo deny check and cargo audit

The plans

Five plans ship with the change and use the same contract format as the rest of vibe/:

• vibe/2026-10-27-2-plugin-std-file-tools.md records the std Pack's shipped work as its first step, then specifies what is left: one schema correction, the six real operations over the call's VFS access, approval, and the shell.
• vibe/2026-10/2026-10-28-1-engine-vibelight-cleanup.md carries the Engine findings, the operator answers, and all ten steps, each marked completed.
• vibe/2026-10-29-1-lua-slop-cleanup.md carries the Lua findings, the operator answers, and all eight steps, each marked completed.
• vibe/2026-10-29-2-model-client-slop.md carries the model-client findings and all three steps, each marked completed.
• vibe/2026-10-27-1-pr172-debt-removal.md, from the earlier pass this one builds on.

A note on the runvil-docs steps

Three of the cleanup steps fix guide sentences, and they live in runvil-docs because that checkout is a separate repository. Its commits, 4f537d5, b6c0d90, and faacbf9, are pushed to its master and need their own pull request. They are not part of this one.