[vinniefalco]

This PR gives section Lua one way to offer tools and turns prompt-written Lua tools into real tools with ids. It follows the plans in vibe/2026-10-23-1-one-offer-api.md and vibe/2026-10-24-1-one-offer-api-debt.md.

tools.offer now takes tool ids, Pack ids, tool objects, Pack objects, or an array of them. Each offer is checked when it is made and rendered in call order at the section's first loop round. tools.adhoc(attrs, f) defines a Lua tool with an id under an always-present adhoc Pack, without offering it. tools.packs replaces the packs global and the tools.required() and tools.extras() lists. Tool objects gain parameters, tool events record the vendor of the Pack that answered, and the Workshop's ask, search, and fetch views match only runvil's own tools. A debt pass at the end bounds offer arrays, fixes call-count seeding after the render, makes tools.adhoc all or nothing, and makes the config UI tests build their bundle first.

One offer verb

What changes

• tools.offer and tools.offer_dynamic take one argument. A string with a slash is a tool id and a string without one is a Pack id. A tool object, a Pack object, or an array mixing all four forms is also accepted. Arrays are read through __len and __index.
• Every entry is checked before any is recorded, and an entry identical to one already recorded is skipped. The fixed-list refusal after the first loop round still comes first.
• ToolRuntime holds one ordered list of Offer { target, mode }, where the target is a ToolId or a PackId. No offer holds a wire name.
• The first loop round renders the static offers in call order, appending and skipping tools already listed. A Pack offer expands to its tools in id order at render time. For example, tools.offer('web') then tools.offer('web/search') renders web_fetch, web_search, and the reverse order renders web_search, web_fetch.
• When an offered adhoc tool and an offered catalog tool share a wire name, the adhoc tool is rendered and the catalog tool is dropped. That rule moved out of the Engine's prepare_scoped_tools into the Lua static pass, so the Engine receives one finished list.
• tools.offer_dynamic is a scaffold. The render fills RenderedTools.dynamic with dynamically offered tools that are not in the static list, and nothing reads it yet. The rendered schemas are byte for byte the same with or without dynamic offers.
• tools.packs is a read-only proxy with a protected metatable. Integer keys, #, ipairs, and pairs walk the Pack objects in name order, adhoc included. get(name) returns a Pack object or nil, and extras() returns a fresh array of the usable Packs not declared under uses:. Pack objects have exactly name, tools, and required.
• tool_route takes the call site. A model call resolves its wire name through the current section's rendered list, never the chain's advertised map, and a script call routes by id. The adhoc arm moves to scheduler/tool_call-adhoc.rs.

Changes callers will notice

• Removed, with no shim: the packs global (including packs.offer), tools.offer_local, tools.required(), and tools.extras(). RESERVED_NAMES goes from 63 to 62.
• Extras are opt-in per section through tools.offer(tools.packs.extras()).
• tools.call by bare name raises tools.call: "grab" is not a tool id. Call by id (tools.call('adhoc/grab')) or by object.
• tools.offer(nil) and malformed arrays raise. A gap, a stray key, or a nested table raises, so a mistyped tools.get id fails at the offer line.
• Render order follows the offer lines instead of grouping single tools, Packs, and Lua tools.
• Prompts. The Workshop chat agent offers web and then the extras through tools.offer.

Adhoc tools

What changes

• The local-tool concept is renamed adhoc everywhere in the code, including the internal protocol names (the adhoc_tool_done op and the runvil.tools.adhoc_handlers registry key) and two test files. The rename commit changes no behavior except the wording of the jump refusal inside a handler.
• tools.adhoc(attrs, f) gives a tool the id adhoc/<name lowercased> and keeps name as its wire name, so Shout gets the id adhoc/shout and the wire name Shout. It returns the tool object without offering it. Defining works after the render; only offers are refused there.
• attrs takes exactly name, description, and an optional parameters. parameters is either the existing short form or a JSON Schema object, told apart by type = 'object', so parameters = tools.get('web/search').parameters wraps a catalog tool exactly. The name and the schema are checked on the defining line.
• The adhoc Pack exists in every section VM from the start, the H1 pass included, with required false.
• Adhoc calls, counts, and events use the id. tools.calls['adhoc/grab'] counts, and tool-call and tool-result events for adhoc tools carry tool: Some("adhoc/<name>").

Changes callers will notice

• tools.offer_local(...) becomes tools.offer(tools.adhoc({ name = ..., description = ..., parameters = ... }, f)).
• Events. A reader that treated tool: None as a Lua tool now sees an adhoc id. The Workshop UI labels an adhoc call as <name> in adhoc.
• The jump refusal reads jump is unavailable inside an adhoc tool handler: return a value from the handler and call jump from the block after the tool call returns.

Tool metadata, vendors, listings, and the adhoc reservation

What changes

• tool.parameters returns a fresh Lua table holding the tool's schema on every read, converted the way json.decode converts, so json.encode gives back [] and json.null intact. Tool and Pack metadata (id, description, parameters, pack, and a Pack's name, required, and tools) never arrives in the untrusted envelope.
• Vendors in events. The Harness reports each usable Pack's vendor from the FQN it picked: runvil for a bare uses: entry or an undeclared Pack, acme for acme/kit. ToolCallEvent and Event::ToolResult gain an optional vendor, omitted when absent. Adhoc tools record none, and Lua never sees vendors.
• The Workshop names its special tools by vendor. The ask, search, and fetch views appear only for runvil/user-input/ask, runvil/web/search, and runvil/web/fetch. Another vendor's same id, a call with no vendor, or an adhoc tool named ask shows as an ordinary tool. The server frames a script's result as the operator's message only when both the vendor and the id match.
• Tool listings. ToolInfo gains describes_tools, set only on mcp/get_dynamic_tools. A script's call to it receives the listing as plain text, still marked untrusted, while a model's call still receives the envelope. An adhoc call whose own function fetched a listing during that call returns its result wrapped and untrusted, so an adhoc wrapper of get_dynamic_tools gives the model the same envelope, byte for byte, as a direct model call.
• The adhoc Pack id is reserved. The plugin registry refuses it with the new InstallError::AdhocPackId, and the parser refuses uses: [adhoc] or uses: [acme/adhoc] with the new PackListError::Adhoc. RunContext::prepare sets the new Requirements.reserved_adhoc when the catalog or the roster names the Pack id adhoc, so the run fails with RequirementsUnmet and a one-line notice.

Changes callers will notice

• RunContext::packs takes Vec<UsablePack> in place of Vec<PackId>. UsablePack::new(pack, vendor) is new in the facade, so every caller of RunContext::packs changes.
• New public items in crates/runvil/public-api.txt: UsablePack, Requirements::reserved_adhoc, ToolInfo::describes_tools (field and builder), ToolCallEvent::vendor with with_vendor, and Event::ToolResult::vendor.
• Logs. A log written before this change has no vendor and reads back as naming no vendor. Nothing treats such a log as naming a runvil tool.

Debt removal

• Offer arrays are bounded. An array whose #t is greater than 100,000 (HELD_KEY_LIMIT, the limit json.encode already applies) raises <verb> takes an array of at most 100000 entries, got <n> before anything is allocated or read. Before this fix, a script's __len could make the offer decoder panic the run on a capacity overflow or abort the process on a failed allocation, and a plain array of more than about a million entries panicked on an exhausted mlua reference stack.
• Counts seed from the rendered list after the render. An adhoc tool defined after the first loop round, which the model cannot call, read 0 in tools.calls after a later dispatch. It now raises the usual has no seeded count error with the adhoc hint. Seeding before the first render is unchanged.
• tools.adhoc is all or nothing. The handler and the tool object are written first and registration runs last, and a failed registration clears both. When one of the Lua writes failed, for example on a memory error the script caught, the definition used to leave a registered tool with no object, whose name could not be defined again.
• A catalog tool object under the adhoc Pack is refused at the offer line with the ordinary tools.offer: "adhoc/x" is not a tool in this run, where it used to reach an internal error at render. This is reachable only when a caller ignores the prepare refusal, because Run::new accepts an unprepared context.
• The config UI tests build their bundle first. crates/gateway/config-ui/ui/package.json gains a pretest script, so npm test never runs against a missing or stale dist/. Three test comments that said a debug cargo build produces dist/ are corrected.

Commits

• 858aaa233 Rename local tools to adhoc. A pure rename across the Engine, the Lua crate, and the event doc comments.
• 97d8de2ef Add tool parameters, vendors, listing trust; reserve adhoc. The groundwork that works against the old offer surface.
• 6a521c27b Collapse tool offering into tools.offer with adhoc tools. The offer verbs, tools.packs, tools.adhoc, the ordered render, and routing by call site.
• 838458243 Close plan: one-offer-api
• 1f0c75b90 Build the config UI bundle before its tests.
• a259b241c Bound offer arrays at the held key limit.
• 086887609 Refuse offered adhoc objects that no adhoc tool holds.
• 4c5a0dbe0 Make tools.adhoc all or nothing.
• f7c54f412 Seed tool call counts from the rendered list.
• 5ddfac479 Close plan: one-offer-api-debt

This branch is rebased on dff58bbe1. An earlier commit here that bumped tokio and ctutils for RUSTSEC-2026-0385 and RUSTSEC-2026-0386 was dropped, because dff58bbe1 makes the same fix with newer versions. The other new commit on master, c18df6b7b, touches only gateway code and shares no file with this PR.

Testing

After the rebase onto dff58bbe1, these passed locally on Windows:

• cargo nextest run --locked --workspace --exclude workshop --exclude workshop-server --exclude workshop-server-api --all-features, with 5422 tests passing and 76 skipped
• cargo nextest run --locked -p workshop -p workshop-server -p workshop-server-api, with 308 tests passing and 4 skipped
• cargo check --workspace --all-targets --all-features --locked, cargo fmt --all --check, and the docs-claims wording scan
• the pre-push hook: the headless gateway check, the workspace clippy run with warnings denied, and cargo deny check, with advisories, bans, licenses, and sources all ok

Before the rebase, the plans record each step as completed only after the gates it lists passed, before the next step started. Those gates include both clippy runs with warnings denied, the rustdoc builds with -D warnings, cargo +nightly-2026-09-05 xtask api --check against the updated public-api.txt, the Workshop and config UI Node tests, and the runvil-docs site build. Each debt-pass regression test was confirmed to fail before its fix, including the offer-limit cases that panicked at the pre-fix code. The Workshop clippy run, the rustdoc builds, and the API check were not rerun after the rebase, which moves these commits onto upstream's newer tokio and ctutils and the gateway change in c18df6b7b.

Known gaps

• tools.offer_dynamic records a list that nothing reads. Connecting it to discovery tools is deferred until MCP servers' tools become catalog tools.
• Offer filters, Pack-chosen wire names for catalog tools, shaped Packs (the core file tools and subagents), and structured output from adhoc tools are deferred.
• Replays of records written before this change no longer match their Chat effects, because the advertised order and the adhoc events' tool field change. Nothing was added for old records.
• Before a section's first render, call counts still seed from the live scope at each dispatch.
• When a caller bypasses the prepare refusal, tools.call('adhoc/x') runs the catalog tool adhoc/x rather than raising. It reaches no internal error.
• UsablePack's vendor is a plain string and is not checked to be one segment.

Related

• The language guide changes are two commits in the runvil-docs repository and are not part of this PR. 24e8143 documents the one offer API and also removes tools.allow_tasks, the task built-ins, model tasks, and task origin, which the code no longer has. dd8a245 documents the offer array limit.