Skip to content

fix(orchestration): return wait_for_agent before the MCP client ends the call - #190

Merged
howdeploy merged 1 commit into
howdeploy:mainfrom
BIackFIame:pr185/orch-wait-deadline
Nov 1, 2026
Merged

howdeploy merged 1 commit into
howdeploy:mainfrom
BIackFIame:pr185/orch-wait-deadline

Conversation

@BIackFIame

Copy link
Copy Markdown
Contributor

Split out of #160 as a small, independent PR on 1.8.5 (it touches only what 1.8.5 does not already cover). It does not depend on the other parts.

Problem

wait_for_agent accepts timeoutSeconds up to 600, and the description invites the orchestrator to use long waits. The MCP clients of most orchestrator CLIs end a tool call after about 60 seconds (Codex's default tool_timeout_sec, OpenCode's client). The comment above MAX_AGENT_WAIT_SECONDS already notes this, but only the default (55 s) respects it.

Before:

  1. A Codex or OpenCode orchestrator calls wait_for_agent({ sessionId, timeoutSeconds: 300 }) while the subagent works.
  2. After about 60 s its MCP client gives up: the orchestrator sees a failed tool call (a client timeout error), no status and no output.
  3. Many models treat that as a broken tool and stop delegating, retry blindly or cancel the subagent.

After: the same call returns after 50 s with the existing reason: "timeout", the subagent's status and its masked output as progress. The description says that a timeout means the subagent is still running and to call wait_for_agent again.

Change

  • CLIENT_SAFE_AGENT_WAIT_SECONDS = 50 next to the existing constants in orchestration-catalog.mjs.
  • ScopedOrchestrationHandler.wait caps one call at that value unless the orchestrator is Claude Code, whose MCP client lets a tool call run far longer; for Claude Code nothing changes (up to 600 s).
  • The tool description (and the embedded native catalog regenerated from it), agent/orchestrator/SKILL.md and docs/agent-orchestration.md say so.

The schema (maximum: 600), the default (55 s) and the wait logic itself are unchanged. Five lines of code plus wording.

Why this and not less

The deadline belongs to the client, not to the subagent, so it has to be enforced where CanvasTTY knows which client is calling: the orchestration handler already knows the orchestrator's session and provider. Lowering the schema maximum alone would not help: a model can still ask for any value up to it, and Claude Code orchestrators do benefit from long waits. Raising the client's own timeout is not possible for every CLI (OpenCode has no per-server setting we write), and it would hide a long silence from the model instead of giving it progress.

What changes for existing workflows

  • Claude Code orchestrators: unchanged.
  • Other orchestrators: a wait longer than 50 s becomes several calls, each returning timeout with status and output. Calls of 50 s or less are unchanged. A wait that ends earlier (idle, done, needs_approval and so on) is unchanged.
  • No new field and no new refusal.

Validation

  • New test in tests/orchestration-providers-wait.test.mjs: for OpenCode and Codex orchestrators a request of 600 or 120 s (and the default) must reach waitFor as 50 000 ms, a 20 s request stays 20 000 ms, Claude Code keeps 600 000 ms and its 55 s default; the result is timeout with status: "working" and the subagent's output; the description states the cap.
  • On f3eee29 without the fix this test fails (actual: 600000, expected: 50000 for OpenCode asking for 600); with the fix it passes.
  • npm run build (typecheck), npm run audit:secrets, the eager renderer bundle check and the full test suite pass. Full suite: 2652 tests, 2646 pass, 0 fail, 6 skipped. The renderer is untouched (eager bundle unchanged against the other branches; renderer-bundle-splitting passes).

…the call

wait_for_agent accepts up to 600 seconds, but the MCP clients of most
orchestrator CLIs (Codex's default tool_timeout_sec, OpenCode) end a tool
call after about 60 seconds. An orchestrator that asked for a long wait
got a failed tool call instead of a result, and no progress.

For every orchestrator but Claude Code, whose client waits far longer, one
call now waits at most 50 seconds and then returns the existing "timeout"
with status and the masked output. The schema, the default and Claude
Code's limit are unchanged. The tool description (both catalogs), the
orchestrator skill and the docs say that a timeout means the subagent is
still running.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-01T10:42:41.214175Z ec3feef PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@howdeploy
howdeploy merged commit e8268aa into howdeploy:main Nov 1, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants