Handle routing failures

[hanna-paasivirta]

Short Description

Gives global chat's subagents a way to recover when the router sends a request to the wrong place, instead of telling the user "I can't see your job code". Misrouted requests are now handled invisibly: the subagent either pulls the context it's missing or hands the request back for rerouting to the planner.

Fixes #506

Implementation Details

Global chat presents as a single assistant, but the router will inevitably misroute some requests. Today a misrouted subagent dead-ends: job_chat can't see the workflow, workflow_chat declines code questions and tells the user to navigate to the Inspector. Both replies leak the internal architecture and strand the user. This PR adds two recovery mechanisms, following the principle that the subagent should either get what it needs or get out of the way.

Pull missing context. In subagent mode, job_chat receives the workflow structure (bodies redacted, ids stripped to save tokens) and an inspect_job_code tool to read other steps' code on demand; this is the same tool the planner uses, moved to a shared module. This keeps the fast direct route viable for requests that reference other steps, rather than paying for a planner run.

Example: The job code subagent can examine other steps and has better knowledge of when this might be relevant because it's given the workflow outline:

Hand back when the request lands elsewhere. Changes beyond the focused step can't be done from job_chat, so it gets an inspect_workflow tool that immediately returns the request to the router, which re-runs it through the planner as if routed there first. The tool is deliberately framed as a capability rather than an escalation: models narrate before acting, and a slipped sentence should read "I'll take a look at your workflow", which stays truthful once the planner takes over. workflow_chat hands back through a handover field in its structured output schema instead of a tool, because mixing tools into forced structured output has produced garbled output before; the field is generated first, so streaming can suppress all output before anything reaches the user. A shared stream manager across router, subagents and planner keeps a handover to a single message lifecycle, so the user never sees the aborted attempt.

Example:

Logs for the example, showing the initial misrouting to the job code agent that can only edit one step, and how it hands over back to the planner agent that can orchestrate several step edits in one go:

INFO:global_chat.global_chat:Global agent called with content: like all waves...
INFO:global_chat.router:RouterAgent initialized with model: claude-haiku-4-5-20251001
INFO:global_chat.router:Router.route_and_execute() called
INFO:global_chat.router:Router decision: job_code_agent (confidence: 4, job_key: create-demo-in-sf)
**INFO:global_chat.router:Routing to job_chat**
INFO:search_adaptor_docs:Checking/loading adaptor docs for @openfn/language-salesforce@4.8.6
INFO:load_adaptor_docs:Checking if docs already exist in database
INFO:load_adaptor_docs:✓ Docs already exist for @openfn/language-salesforce@4.8.6 (44 functions)
INFO:search_adaptor_docs:Adaptor docs for @openfn/language-salesforce@4.8.6 already exist (checked in 0.008s)
INFO:job_chat:Making streaming API call
**INFO:job_chat:job_chat round 0: model called inspect_workflow**
INFO:job_chat:job_chat handing over: Remove all wave emojis from the console.log banners across all Salesforce steps
**WARNING:global_chat.router:job_code_agent handed over: Remove all wave emojis from the console.log banners across all Salesforce steps. Rerouting to planner**
**INFO:global_chat.router:Routing to planner**
INFO:global_chat.planner:PlannerAgent initialized with model: claude-opus-4-8
INFO:global_chat.planner:Planner.run() called
INFO:global_chat.planner:Claude API call 1: stop_reason=tool_use
INFO:global_chat.planner:Executing 3 tool(s): ['call_job_code_agent', 'call_job_code_agent', 'call_job_code_agent']
INFO:global_chat.subagent_caller:Calling job_agent (job_key=create-demo-in-sf): Remove all wave emojis (🌊) from the console.log banner at the top of the step. Leave the rest of the banner and code unc
INFO:global_chat.subagent_caller:Calling job_agent (job_key=create-in-SF): Remove all wave emojis (🌊) from the console.log banner at the top of the step. Leave the rest of the banner and code unc
INFO:global_chat.subagent_caller:Calling job_agent (job_key=update-in-SF): Remove all wave emojis (🌊) from the console.log banner at the top of the step. Leave the rest of the banner and code unc

There is a new Langfuse tag for conversations that have been handed over to the planner not via the router, so that we can keep an eye on how many requests were misrouted.

Prompt updates Both subagents' prompts drop the outdated "send the user to another page" instructions in subagent mode rather than contradicting them: what the model never reads, it can't say. In job_chat this is done by composing the system role from parts; in workflow_chat by a guarded string replace, since its YAML prompt templating makes placeholder slots risky. Production behaviour is unchanged: neither the subagent flag nor workflow_yaml is sent by direct callers, and unit tests pin that the production prompts and response shapes are untouched.

The router also now reroutes low-confidence direct routes (confidence < 3) to the planner, using the confidence score it already produces. It rarely outputs low-confidence scores however, so this will have little impact without further adjustments.

Adds unit tests for the routing, handover parsing and prompt gating, and live integration tests (marked integration, manual/nightly) covering curated misroutes, including oblique phrasings and a wrong-focused-step case.

AI Usage

Please disclose whether you've used AI in this work (it's cool, we just want to
know!):

• Yes, I have not used AI
• No, I have not used AI

You can read more details in our
Responsible AI Policy