Rust-backed messages and models.loop, tools by canonical id, and a plugins table

[vinniefalco]

This branch lands five plans on the prompt-author surface, in 29 commits.

• Message lists. messages.new() lists move from a pure-Lua table to a Rust-backed list that the Engine owns, so each model round's Chat record logs only what changed since that list's previous round. Before this, every round recorded the whole conversation again, so a conversation of k rounds logged on the order of k squared message bodies. Each Chat record now names the round it extends (after), says how many leading messages it repeats from that round's request (keep), and stores only the messages after those.
• The model loop in Rust. The models.loop rules move out of the Lua coroutine shim into a typed Rust state machine behind a small Lua trampoline. Model handles gain loop and infer methods, so the namespace functions no longer guess which argument is a handle. Pending task notices now ride the chat round itself instead of a separate drain request.
• The author API. Lua names every catalog tool by its canonical id, such as web/fetch, and the frontmatter declares Plugins only. Role labels and tool aliases stop being Lua globals. A new plugins table reports the run's Plugins, tools and Plugins are shared read-only objects, and model handles report their provider from the gateway catalog.
• Two debt removals follow debt reviews of the loop work and the author API work.

Plans:

• vibe/2026-10-09-2-messages-userdata-refactor.md
• vibe/2026-10-09-3-models-loop-in-rust.md
• vibe/2026-10-09-4-models-loop-debt-removal.md
• vibe/2026-10-09-5-author-api-reshape.md
• vibe/2026-10-10-1-author-api-debt-removal.md

Changes

Message list:

• Honor userdata __pairs in sandbox pairs
• Add the Rust-backed MessageList core
• Add read-only record views and iteration to MessageList
• Back messages.new() with the Rust MessageList
• Record after and keep on Chat effects
• Fix models.loop compactor error and bound list pairs (follow-up from a debt review, no plan)

Model loop:

• Give model handles loop and infer methods
• Record the guide update for handle methods (the guide change is promptforge-docs commit 44ff253)
• Pin models.loop behavior with contract tests
• Run models.loop rules in a Rust state machine
• Fold the task-notice drain into the chat dispatch
• Resume the chat answer as an opaque ChatResult

Model loop debt removal:

• Keep shim raises working when author code rebinds error
• Drop model and metrics from ChatResult and fix stale docs

Author API:

• Stop installing role labels as Lua globals
• Drop tool slots from the Workshop contract and run panel
• Name tools by canonical id and remove tool slots
• Add the plugins table over shared plugin objects
• Report an optional model provider in the gateway catalog
• Expose the model provider on model handles

Author API debt removal:

• Run the docs-claims wording scan from local gates
• Resolve model tool names by wire name only
• Rename Lua tool internals to match the offer API
• Describe ToolPerformer alias as wire name or canonical id

The five Close plan commits only retire each plan's active marker.

Behavior changes

For prompt authors, message lists:

• models.loop and h:loop accept only a messages.new() list. A plain Lua array fails with models.loop needs a messages.new() list; build one with messages.new() and :user, :append, or :replace. No in-tree prompt passes one.
• Each builder validates its record when it adds it, so a malformed record fails at the builder call instead of at the loop. A system record after any non-system record is refused by the edit that adds it.
• append drops fields other than role, content, tool_calls, and tool_call_id, so those fields cannot be read back from the list.
• The new replace(first, last, records...) deletes, inserts, and replaces ranges. Removing the last record is msgs:replace(#msgs, #msgs). Index assignment such as msgs[#msgs] = nil is refused.
• msgs[i] returns a read-only view whose type() is userdata. Assigning a field raises an error that points to replace. A view converts to JSON like the record table, so it still works as a tool argument and with append on another list.
• pairs(msgs) stops at the record count it started with. ipairs and numeric loops read the live list. The sandbox pairs now honors a userdata's __pairs, as stock Lua does.
• A list or a view cannot be stored directly in var or substituted with {{ }}, and a whole list no longer converts to JSON.

For prompt authors, the model loop:

• A role's handle runs its own calls with h:loop(msgs) and h:infer(prompt). models.loop and models.infer always run on the section's current model, and refuse a handle as their first argument with an error that names the method form. A dot call such as h.loop(msgs) raises an error that says to use a colon.
• Every loop entry checks its receiver, its argument count, its compactor, and its list before any request leaves, so each mistake raises at the call site.
• Pending task notices are appended to the author's list as user messages at the start of each round, so pending notices can fill an empty list. An empty list with nothing pending still raises messages must not be empty.
• The shim captures the base error at install, so author code that rebinds error can no longer turn a refused loop call into a spin.

For prompt authors, tools, Plugins, and models:

• The frontmatter tools: key is gone, and a leftover one fails the parse as an unknown key. plugins: is the only declaration. No frontmatter key creates a Lua global.
• Role labels are no longer globals: local analyst = models.get('analyst') replaces a bare analyst. Tool aliases are gone with the slots, so after setup the global table holds only Lua, Engine, and Plugin prelude names.
• Lua names catalog tools by canonical id. tools.offer and tools.always_offer replace tools.add and tools.always, and take ids, tool objects, or arrays of them, so tools.offer(plugins.get('web').tools) offers a whole Plugin. tools.required() and tools.extras() replace tools.offered(), tools.get(id) returns one tool object or nil, and tools.offer_local replaces tools.add_local with the same arguments. tools.call takes an id, a tool object, or a local tool's alias, and tools.calls is keyed by id. The removed functions are nil.
• Each tool and each Plugin is one read-only object per VM, so the same tool is == in every list. A tool object has id, description, and plugin.
• The new plugins table has plugins.required(), plugins.extras(), and plugins.get(name), and plugins is a reserved global name.
• handle.provider is the model's provider id from the gateway catalog, such as xai, or nil when the catalog names none.
• The model still sees generated wire names (web/fetch becomes web_fetch), so the shipped prompts' tools now reach the model as web_fetch and web_search instead of fetch and search. A model call that names a tool by its canonical id gets the plain out-of-scope error.
• New error texts: tools.offer: "{id}" is not a catalog tool in this run (and the same for tools.always_offer), kind unbound_tool with tool {name:?} is not a tool in this run; catalog tools: [...], and the out-of-scope suffix (a catalog tool that was not offered in this section).

For hosts:

• Effect::Chat and EffectRecord::Chat gain the public fields after: Option<RoundId> and keep: u64. Effect::Chat.messages still holds the full request. EffectRecord::Chat.messages now holds only the messages after keep, so rebuilding a round's request means following after.
• A host that logs records must record every Chat effect a step returns, including ones it drops, so that each after names a recorded round. The in-tree Harness already does this.
• A models.infer record is unchanged apart from after: null and keep: 0.
• The run-log table layout and LAYOUT_VERSION are unchanged. Only the JSON in Chat records changes, and run logs written before this PR hold whole requests with no after or keep.
• Because the notice drain no longer sends the owning chain to the back of the ready queue, the order effects are issued in can change when several chains are ready.
• The facade drops ToolSlot, ToolSlots, ToolBindings, RunContext::tool_bindings, Frontmatter::tools, and Requirements::missing_tools, and gains with_provider and provider on ModelDescriptor and ModelBinding. A declared Plugin that lacks one expected tool is no longer refused at prepare; the prompt fails at tools.offer instead. A missing declared Plugin still lands in missing_required.
• Effect::ToolCall.alias now holds the tool's wire name for every call to a tool the run can offer, and the canonical id only for a script call to a catalog tool the run could not offer.
• The gateway's [[model]] and [[local_model]] accept an optional provider of lowercase letters, digits, ., _, and -, refused at load otherwise. GET /v1/models includes it only when set.
• The Workshop prompt contract response drops its tools field, and the run panel no longer shows tool rows.

For contributors:

• The root AGENTS.md verification list and the pre-push hook now run node --test crates/workshop/ui/test/docs-claims.mjs, so an Engine doc that names a Host application fails locally before push instead of only in CI's ui job.

Known limits

• In promptforge-docs, the conversations chapter (11) and the quick reference (17) still describe plain-table lists, and the guide still documents tool slots, tools.add, and role and alias globals. Those change in separate work there. The guide already documents the handle methods.
• The per-model rewrite of model-facing tool names (such as WebSearch for Grok) is deferred. This branch only adds the provider it will key on.
• after is a run-wide round number, so, like round, it can differ between two live runs of a prompt whose tasks run concurrently. Within one run log, every after names a recorded round.
• Messages after keep are logged in full. A compaction that rewrites early messages logs the kept tail again, once.
• A catalog tool whose generated wire name repeats an earlier one is left out of the offering with a log line, a declared Plugin's tool included. No shipped configuration produces such a collision.

Testing

• The full workspace gates pass on 8cac6f030, the last code commit (the tip, abe218a36, only deletes vibe/ACTIVE). They cover cargo fmt --all --check, clippy with warnings denied on both partitions, the headless gateway check, both doc builds, the facade API check, and the Workshop and gateway config UI npm suites with the docs-claims scan. The Rust suites passed with 4,959 and 310 tests.
• The facade listing's diff is exactly the slot removals, the four provider accessors, and the four after and keep field lines.
• A rebuild test walks each case's Chat records in log order, rebuilds every request from after and keep, and checks that it equals the request the round sent. The cases are a tool round, a compaction, an add then a remove, a resend with no changes, an identical re-insert, and removing the last reply. A separate test checks that a precheck refusal writes no record and that the next send extends the last issued round.
• Contract tests written before the Rust rewrite pin the loop's observable behavior: compactors, list and arity refusals, notice draining, the clean exit, the batch rule under a raising handler, dropped and cancelled tool calls, and a full event trace. The state machine's own tests run without a Lua VM.
• Tests run prompts/research-person.md and crates/workshop/agents/agents/chat.md end to end against a canned model, on the new tool surface.
• Identity tests check that each tool and each Plugin is the same object across tools.required(), tools.extras(), tools.get, plugins.get, and a Plugin's tools, while each list call returns a new array.
• Regression tests fail before their fixes: the compactor type error without a handle, a pairs loop that appends (which raises runaway pairs after ten passes instead of hanging), a refused loop call after author code rebinds error, and a model call by canonical id that used to get the false "not offered" suffix.