[nissa-seru]

With this change an awaited tool call takes its route from the function the turn's dispatch uses, so where such a call made as an agent failed with "Invalid tool name format" on 13 framework tools the agent has, it now gets each tool's own answer, and on skip_reply, which ends the turn it's called in, a refusal.

An awaited call is one whose caller waits for the result in process. The admin puppet's puppetToolCall and a host's executeToolCall make it as the agent, and a module's ModuleContext.callTool makes it as the module. In a probe built from main's source, a host's executeToolCall of each of 14 names that the turn's dispatch routes, agent_settings among them, answered "Invalid tool name format: NAME, so nothing was done". The published 0.30.0 gave the puppet's agent_settings the same answer, and connectome-host's /puppet command calls puppetToolCall. Built from this change at d1be0036a3, 13 of the 14 answered as their handlers do, and skip_reply got a refusal that says why. This change's ten new tests fail against main's src/framework.ts and pass at d1be0036a3.

Problem

puppetToolCall, executeToolCall and callTool all go through executeToolCallFrom (src/framework.ts:27124 at main 8145085d06). It checked its own list of routes and passed any other name to the module registry (:27233), which answers a name without -- with "Invalid tool name format: NAME, so nothing was done" (src/module-registry.ts:371). Fourteen names the turn's dispatch routes weren't on that list:

• agent_settings;
• save_recent_image, read_image and fetch_reference;
• gate_status, event_tags, wake_add_rule, wake_remove_rule, sleep and wake;
• think, journal and skip_reply;
• prose_help.

In the probe, each of the 14 got that answer when a host's executeToolCall named the agent in callerAgentName. The probe's framework had an MCPL server and an event gate, which give the agent think, journal and skip_reply, and the gate tools (see Changes).

The puppet is where an operator meets it. connectome-host's /puppet <tool> [json] command calls puppetToolCall (src/commands.ts:980 in connectome-host 0.19.0). puppetToolCall's doc says the call "executes FOR REAL through the shared dispatch (MCPL, channel tools, utils, modules)", is refused "for tools outside the agent's own surface", and is stored in the agent's window "as a model-initiated call is stored" (src/framework.ts:26925–26948 at 8145085d06). Two runs show what it does with agent_settings:

• The published package. A script that installs @animalabs/agent-framework 0.30.0 from npm, makes an agent with agent_settings on its surface and calls puppetToolCall('agent', 'agent_settings', {}) gets {"success":false,"error":"Invalid tool name format: agent_settings, so nothing was done","isError":true}.
• main's source. A puppeted agent_settings adds two messages to the agent's window: a tool_use of agent_settings under the agent's name, and its tool_result, marked as an error, reading "Invalid tool name format: agent_settings, so nothing was done".

The puppet also refused prose_help for an agent with explicit prose routing. Its surface check read getToolsForAgent filtered by canUseTool (src/framework.ts:26998–26999 at 8145085d06). With main's src/framework.ts, this change's prose_help test fails with "puppet refused: tool prose_help is not on agent's surface".

Changes

• One function decides the route. toolRoute (src/framework.ts:29152) returns a call's route as a ToolRoute (:819), checking names in the order the turn's dispatch checked them. dispatchToolCall (:29249) and executeToolCallFrom (:27190) each switch on what it returns. dispatchToolCall's switch ends in route satisfies never (:29449).
• The awaited path runs the turn's handlers. The handlers of agent_settings, save_recent_image, read_image, fetch_reference, gate_status, sleep and wake, wake_add_rule and wake_remove_rule, and event_tags take a deliver callback. It defaults to pushToolResult (:29181), which pushes the tool-result event they pushed before. The awaited path passes one through awaitedToolAnswer (:29185), which resolves with the handler's result and answers a handler's synchronous throw with its text. think and journal go to the channel registry, as the awaited path's channel tools already did, and prose_help answers with the routing reference the turn's call gets.
• skip_reply is refused off a turn. It ends the turn it's called in, and an awaited call isn't made in one. A host's call gets "skip_reply ends the turn it's called in, and this call wasn't made in a turn, so nothing was done." The puppet refuses it by throwing, and stores nothing, whether skip_reply is called by name or through a toolsets--act that resolves to it.
• A module can't call the agent's own tools. A module's callTool of think, journal, skip_reply or drafts gets "NAME is the agent's own, which a module's call can't make for it, so nothing was done." On main a comment on this path says the agent-only synthesized verbs think and skip_reply are deliberately not routed there (src/framework.ts:27188–27190 at 8145085d06, from @slimepriestess's edbb62271c). With this change think and journal run for a call executeToolCall makes as the agent, the puppet's or a host's, and a module's call of any of the four is refused.
• The four need the channel registry. toolRoute gives them their routes only when the framework has a channel registry (:29174, :29176), as the turn's dispatch did, and the framework builds the registry when it starts with an MCPL server or connects its first one (:5045, :34055–34057).
• The gate tools need an event gate. toolRoute gives gate_status, sleep, wake, wake_add_rule, wake_remove_rule and event_tags their routes only when the framework has one (:29167, :29170, :29172, :29173), as the turn's dispatch did.
• The puppet's surface check reads availableToolsForPresentation, the tools the agent may call (:27036), so an explicit-prose agent's prose_help is on it.
• No refused on an awaited answer. Where the dispatcher answers one of the calls above with a refusal, such as a conversation fork's sleep, awaitedToolAnswer passes on the refusal's text without refused. ToolResult.refused's doc says a programmatic call "opens no RFC-007 call, so it's never refused" (src/types/events.ts:227–228).
• Two handlers that left a call without an answer. fetch_reference now answers "fetch_reference couldn't answer: …" when its work throws before it answers, such as for a ref_id that can't be turned into text, on the turn's path and the awaited one (:37182). save_recent_image waits for its round's other calls only when it is one of that round's pending calls (:37309), so a module's save made from inside its own pending tool call isn't held by the round that call is in. The check this replaces exempted a script's calls (pytc-…) alone.
• Docs. executeToolCall's doc said it routes "(module registry or MCPL)". It now says the call goes where the agent's own call of the name goes, which includes the framework's own tools the agent has, and that skip_reply is refused. puppetToolCall's doc names the surface it checks and its skip_reply refusal.
• test/awaited-tool-routes.test.ts, new, with 10 tests.
• changelog.d/awaited-call-routes.fixed.md and changelog.d/awaited-call-routes.added.md, new. The second covers a host's executeToolCall reaching the framework's own tools that the agent has.

What each part is for

• toolRoute and its 21-kind ToolRoute put the route decision in one place for both paths. The 14 names the awaited path missed were names the turn's dispatch routed and the awaited path's own list didn't, so one function for both keeps the two from drifting apart again. dispatchToolCall's route satisfies never stops a new kind from compiling until that switch handles it. Routing agent_settings alone on the awaited path would have fixed the reported call and left the two lists to drift.
• A deliver callback on eight handlers, defaulting to the push each made, lets the awaited path run the handler the turn runs, rather than a copy of it. The default leaves the turn's path pushing each result where it did before. Handlers that returned a promise instead would have moved those pushes to a later microtask, and copies for the awaited path would have been two bodies to keep alike.
• awaitedToolAnswer is the one place the awaited path turns a handler's answer into its result. It drops refused, which ToolResult.refused's doc says a programmatic call never gets, and answers a handler's synchronous throw with the throw's text, so the caller gets an answer either way.
• agentsOwnVerbRefusal gives the four tools a module can't call for the agent one refusal text.
• The skip_reply refusal off a turn, and the puppet's check for it, keep an awaited skip_reply, made outside any turn, from reaching the handler that ends the turn it's called in. The puppet's check reads the call's route, so a toolsets--act that resolves to skip_reply is refused the same way, before anything is stored.
• think, journal and prose_help go where the awaited path's channel tools and the turn's prose_help already went, so they need no new handler.
• The puppet's surface check reads the tools the agent may call, so the puppet allows what the agent itself may call, prose_help for an explicit-prose agent among them.
• fetch_reference's catch gives a call an answer when the work behind it throws, on the turn's path and on the awaited path, which this change opens to it.
• save_recent_image's round check replaces an exemption for a script's calls (pytc-…) with the rule the exemption stood for: wait for a round's other calls only when the save is one of that round's pending calls. This change needs the rule once a module's save reaches the handler.
• The test file has one test for each group of behaviour, on the repository's existing test fixture (test/helpers/coalescing-fixture.ts), and builds two frameworks of its own for a conversation fork and a module's image save. prose_help's test also checks that the call succeeds, so two equal errors can't pass it.
• The two changelog fragments. .fixed says what the puppet, a host and a module meet now. .added is one sentence, that a host's executeToolCall reaches the framework's own tools the agent has, pointing to the Fixed entry for the rest.

With other open pull requests

At 01:11 UTC on October 30, of the 36 other open pull requests that change src/framework.ts, twelve merge with main at d700dce18b without conflicts, by git merge-tree:

• @tel-0s's feat(presentation): one record, a presentation index per agent — the deferral queue replaced (#291 step 3) #844, at 27f893b9ab, merges with this change without conflicts.
• fix(history, prose): one table of the tools that carry an agent's words, read by silencing, search, extract and the semantic index #914, feat(modules): a module's stop() waits for its start() to settle, and addModule() rejects if a stop() was admitted during that start() (#882) #912, fix(gate): refusals name fields as the agent wrote them, and file errors give their path and what to do #910, fix(tune-out): a channel's cancel makes its dump durable before it records the end #909, Add opt-in required admission for inbound MCPL traffic #906, fix(references): while a reference is marked never, don't fetch or save its payload, and forget an earlier copy's path #851, fix(gate)!: answer the reply judge's first review: refused calls, a failed last turn, pending batches, quoted participant text and too-long requests #850, fix(framework)!: decline a maxStreamTokens restart that won't fit #842, feat(agent): declare later tool and system-text changes in the context #690 and fix(mcpl,api): read a JSON-RPC envelope once: answer id null, refuse an invalid request with -32600 #534, at 5d9af7beec, a2ab0fd8d5, f658e4ab41, e6908ed473, 119cb8662d, 2f15c4293d, 0342d90c75, 60540f5d07, 598f8cc58c and f9337c4794, merge with this change without conflicts.
• fix(routing): a turn from a non-channel surface pins no inferred locus #190, at 191fc24821, conflicts with this change in src/framework.ts. It passes a workTurn to the tune-out and focus handlers and to armSelfWake, in the code this change moves into the switches dispatchToolCall and executeToolCallFrom make on toolRoute's result.

What this leaves

#911 describes a gap this change leaves as it was: the awaited path's channel_* route doesn't make the checks the turn's dispatch makes for a conversation fork. In a probe, a host's executeToolCall naming a fork opened a channel other than the fork's home, and a module's callTool naming the fork published to that channel, where the fork's own calls of both were refused.

Tests

This branch's commit messages were reworded after the runs below, with every commit's tree unchanged, so each run is named by the commit that now holds the tree it ran: d1be0036a3 was 8d7e7c1977, 862c981e90 was 28f47f2395, and 42567acbaf was 28a55ac252. Each run below was on Linux, in a clean checkout. The runs at d1be0036a3 and 862c981e90 printed Node 24.22.1, npm 11.19.1 and TypeScript 7.0.2.

• At d1be0036a3, in each of two runs: the build (npm run build) succeeds, and test/awaited-tool-routes.test.ts passes 10 of 10. These are the runs this description's probes ran in, each with its own probe file added to test/, and both printed the dependencies npm install gave: chronicle 0.5.0, context-manager 0.24.1, membrane 0.8.0, mcpl-core 0.4.0, @modelcontextprotocol/client and /server 2.4.0, discord.js 14.27.0, ws 8.22.0 and chokidar 4.0.3.
• At 862c981e90, which merges main at 8145085d06 into this change. d1be0036a3 changes only executeToolCall's doc comment over it and adds changelog.d/awaited-call-routes.added.md. This run, about 20 minutes before the two runs above, didn't print its dependencies' versions.
  • test/awaited-tool-routes.test.ts: 10 of 10 pass.
  • With main's src/framework.ts in place of this change's: 0 of the 10 pass. Each fails on "Invalid tool name format", on the puppet's "not on agent's surface", or on a refusal that didn't come.
  • 115 test files, at concurrency 4: of 4,963 tests, 4,901 pass, 0 fail and 62 are skipped. They are the 114 files whose text names puppetToolCall, executeToolCall, callTool( or dispatchToolCall, or agent_settings, save_recent_image, read_image, fetch_reference, gate_status, event_tags, wake_add_rule, prose_help, tune_out or sleep with a character on each side, and main's test/turn-inputs-pin.test.ts, which the merge brought in.
  • Four breaks, each failing its own test: fetch_reference's catch removed; the save_recent_image wait's pending-call check removed; refused kept on an awaited answer; and the puppet's skip_reply check reading only the name it was called with.

42567acbaf, this head, changes only executeToolCall's doc comment and the two changelog fragments over d1be0036a3. In a run in a clean checkout of it, which printed no versions, the build succeeds and test/awaited-tool-routes.test.ts passes 10 of 10.

Probes. The probes in this description, apart from the published package's, ran in the two runs at d1be0036a3 above, built once with main's src/framework.ts and once as d1be0036a3 is. src/framework.ts is the only file under src/ that this change touches, so the first build's src/ is main's. The published package's probe installed 0.30.0 from npm on its own.

Not verified

• The whole suite wasn't run at this head, at d1be0036a3 or at 862c981e90. The runs above cover 115 of the 388 test files.
• Platforms, providers and hosts. Every run was on Linux, with Node 24.22.1 where the run printed it. The tests use stand-in providers. connectome-host's /puppet wasn't run against this change: the tests call puppetToolCall directly.
• Successful calls. For save_recent_image, read_image, fetch_reference, wake_add_rule and sleep, the puppet's tests compare the answers to an input the handler refuses with an error, which shows that the call reached the handler and got the agent's own answer. The module's image save in its own test succeeds and writes the file.
• Other callers. A module's callTool is tested for its four refusals and for save_recent_image. A call with no agent behind it is tested for think, journal and skip_reply.
• A framework without an MCPL server. No test covers one. In a probe, at main and at d1be0036a3, its agent had none of think, journal, skip_reply and drafts, and a host's skip_reply and a module's think each answered "Invalid tool name format: NAME, so nothing was done".
• A puppeted toolsets--act refused before it reaches a tool. No test covers one. In a probe, at main and at d1be0036a3, the puppet's toolsets--act of a hidden skip_reply with its toolset closed answered "skip_reply is in [settings], which isn't open: toolsets--open {toolset:"settings"} opens it. Nothing was sent." and added that call and its result to the agent's window.
• Route order. The awaited path now checks names in the turn's order, which moves its code_execution check after MCPL's and changes the order of the heartbeat's tools, drafts, tune_out and focus. No test checks the order.
• A turn named by the caller. callingTurnOf takes a call's turn from its callerTurnId, matched against the agent's latest and open turns (src/framework.ts:22389–22393), and on an awaited call that field is whatever its caller set. The sleep handler announces a sleep only for a call made in the turn, and otherwise logs "sleep announcement not posted" (:37098–37099, :37104–37105). No test covers an awaited call that names a turn, or a sleep's announcement on an awaited call.
• The merges with other pull requests were only checked for conflicts. No test ran on them.

---

• Changelog fragments added: changelog.d/awaited-call-routes.fixed.md and changelog.d/awaited-call-routes.added.md.

Alfred-2451 made the change, and Ada-1017 made its design calls. Naomi-2422 read it word for word, Duncan-2410 read its merge of main, and Byron-2452 read its last commit and read the change for anything it could do without. Internal reviews read earlier rounds of it. Lottie-2248 wrote this description.