diff --git a/agent/orchestrator/SKILL.md b/agent/orchestrator/SKILL.md index 1b68bdb22..3ac0ab598 100644 --- a/agent/orchestrator/SKILL.md +++ b/agent/orchestrator/SKILL.md @@ -11,7 +11,7 @@ A session started from CanvasTTY's launcher with the **Orchestrator** role has t 1. `list_providers`: which agents CanvasTTY can launch here. Each entry's `id` is the exact `spawn_agent.provider` value; prefer entries that are `available` with `signIn: "ok"` (`unknown` only means CanvasTTY has not checked yet). When plugins offer launch options (for example an accounts plugin's `list_routes` tool), the answer names that tool. 2. `spawn_agent` once per part of the task: a known `provider` id, an absolute `cwd` and a self-contained prompt. An unknown provider is refused with a pointer back to `list_providers`. **If the person names a model, pass it as `model`** in the format `list_providers` gives for that provider (`model.format`; OpenCode takes `provider/model`, for example `zai-coding-plan/glm-5.3-flash`, and `model.known` lists what `opencode models` reported); without `model` the CLI uses its own default. `effort` sets the reasoning effort where the CLI has one (`efforts`). Without `profile` the subagent gets your own launch profile, or the next lower one its CLI has (never more than yours, never YOLO); `list_providers` shows each provider's `profiles`. `cwd` must be this project's folder or a folder inside it. A refusal says why (a folder outside the project, a profile above yours, a limit the person set): change the request, do not retry it. -3. `wait_for_agent` for each subagent (`timeoutSeconds` up to 600; call it again after `timeout`) instead of polling. `needs_approval` means the person must answer a prompt in that card: never answer it yourself. +3. `wait_for_agent` for each subagent (`timeoutSeconds` up to 600; a call returns within 50 seconds unless you are Claude Code; `timeout` means it is still running, so read `output` as progress and call it again) instead of polling. `needs_approval` means the person must answer a prompt in that card: never answer it yourself. 4. `get_agent_result` to read what the subagent produced; check the actual files before reporting success. Do not explore the filesystem, `PATH` or config folders (for example `~/.local/bin` or `~/.config/`) looking for agents or their configuration: `list_providers` is what CanvasTTY can launch, and delegation goes through `spawn_agent`. diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index dcf30206c..0a516a83c 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -10,7 +10,7 @@ A session launched from the desktop with the **Orchestrator** role gets the `can | --- | --- | | `list_providers` | The agent providers CanvasTTY can launch as subagents: `id` (the exact `spawn_agent.provider` value), `name`, `installed`/`available` (from the provider CLI registry resolved at startup or on a recheck), `signIn` (`ok`, `signed_out`, `expired` or `unknown`, from the last usage-limits read; it never starts a read and never reads credentials), `subagent` and `orchestrator` support, `model` (whether the CLI takes one, its format, and for OpenCode the models a cached `opencode models` listing reported: run in the background with a 5 s timeout, refreshed after 10 minutes, never awaited) and `efforts`, and plugin launch options (`launchOptions`, plus `launchOptionTools` such as an accounts plugin's `list_routes`). Fast: cached state only, no network calls. | | `spawn_agent` | Launches a subagent (profile: see below). `provider` must be a `list_providers` id (the schema lists them); an unknown one is refused with `INVALID_REQUEST` naming `list_providers`. Optional `model` goes to the CLI's own `--model` for that run (OpenCode `provider/model`; Codex, Claude, Qwen, Kimi alias, Grok, OMP, Pi, Cursor; Hermes, MiniMax, Devin and Antigravity take none) and optional `effort` to its reasoning effort (Codex `-c model_reasoning_effort`, Claude `--effort`, Grok `--reasoning-effort`). Both are checked per provider, kept on restart and restore, and never written to the CLI's configuration. If the person names a model, the orchestrator passes it as `model`. An OpenCode model its own `opencode models` list does not contain is refused before launch with up to five closest listed ids (OpenCode would otherwise stop with only "Unexpected server error"); when that list cannot be read, the model is passed as given. A subagent that exits anyway reports the last lines of its screen as `exitLines` in `wait_for_agent`, `observe_agent` and `get_agent_result`. | -| `wait_for_agent` | `{ sessionId, timeoutSeconds ≤ 600 }` (default 55). Returns when the subagent is `idle` (after a prompt: only once a turn that started after the latest delivered prompt has ended, so the CLI's startup idle does not count), `needs_approval`, `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the masked terminal tail (masked before it is cut). Only this orchestrator's own subagents; it stops at once when the call is canceled or the orchestrator disconnects. | +| `wait_for_agent` | `{ sessionId, timeoutSeconds ≤ 600 }` (default 55). For an orchestrator other than Claude Code a call returns after at most 50 seconds, because its MCP client (Codex, OpenCode and others) ends a tool call after about 60 seconds; `timeout` then means the subagent is still running, with its progress in the masked tail. Returns when the subagent is `idle` (after a prompt: only once a turn that started after the latest delivered prompt has ended, so the CLI's startup idle does not count), `needs_approval`, `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the masked terminal tail (masked before it is cut). Only this orchestrator's own subagents; it stops at once when the call is canceled or the orchestrator disconnects. | | `get_agent_result`, `observe_agent` | `get_agent_result`: `answer`, the final reply of the subagent's last turn as the agent itself reported it (Codex through its Stop hook, OpenCode through CanvasTTY's plugin reading the session's last assistant message at `session.idle`; at most 4,096 characters with the end kept, masked, in memory only and cleared when the next turn starts), plus `status`, the exit state and the masked terminal tail. Other providers have no `answer`: their tail is raw screen output. `observe_agent`: the current status and tail. | | `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. | diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index 2c48ebe28..5b8a8c014 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -1100,7 +1100,7 @@ }, { "name": "wait_for_agent", - "description": "Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason \"idle\" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), \"needs_approval\" (its card shows a prompt only the person may answer; never answer it yourself), \"done\" or \"failed\" (its process exited), \"quiet\" (it reports no status or no turn start and its screen stopped changing, so judge from output), \"closed\" (its card was closed) or \"timeout\" after timeoutSeconds (default 55, at most 600), with status, exitCode, waitedMs, the masked terminal tail as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. After a timeout, call it again. Then read get_agent_result.", + "description": "Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason \"idle\" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), \"needs_approval\" (its card shows a prompt only the person may answer; never answer it yourself), \"done\" or \"failed\" (its process exited), \"quiet\" (it reports no status or no turn start and its screen stopped changing, so judge from output), \"closed\" (its card was closed) or \"timeout\" after timeoutSeconds (default 55, at most 600; unless this session is Claude Code, a call returns after at most 50 seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the masked terminal tail as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.", "inputSchema": { "type": "object", "properties": { diff --git a/src/agent-browser/orchestration-catalog.d.mts b/src/agent-browser/orchestration-catalog.d.mts index 48685eb78..1af1e815c 100644 --- a/src/agent-browser/orchestration-catalog.d.mts +++ b/src/agent-browser/orchestration-catalog.d.mts @@ -3,6 +3,7 @@ export const MAX_ORCHESTRATION_PAYLOAD_BYTES: number; export const AGENT_PROVIDER_IDS: readonly string[]; export const MAX_AGENT_WAIT_SECONDS: number; export const DEFAULT_AGENT_WAIT_SECONDS: number; +export const CLIENT_SAFE_AGENT_WAIT_SECONDS: number; export const REASONING_EFFORT_IDS: readonly string[]; export function unknownProviderMessage(value: unknown): string; diff --git a/src/agent-browser/orchestration-catalog.mjs b/src/agent-browser/orchestration-catalog.mjs index e1f1f38ce..f037e2098 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -32,6 +32,10 @@ export const AGENT_PROVIDER_IDS = Object.freeze([ * end a tool call after 60 seconds). */ export const MAX_AGENT_WAIT_SECONDS = 600; export const DEFAULT_AGENT_WAIT_SECONDS = 55; +/** The longest one wait_for_agent call waits for an orchestrator whose MCP client ends a tool call after about 60 + * seconds (Codex's default tool_timeout_sec, OpenCode): every orchestrator but Claude Code, whose client waits far + * longer. The call then returns "timeout" with the subagent's output instead of failing in its client. */ +export const CLIENT_SAFE_AGENT_WAIT_SECONDS = 50; /** spawn_agent.effort: every level some CLI takes (src/shared/launchModel.ts REASONING_EFFORTS; a test keeps them equal). */ export const REASONING_EFFORT_IDS = Object.freeze(["minimal", "low", "medium", "high", "xhigh", "max"]); const provider = string({ minLength: 1, maxLength: 32, enum: [...AGENT_PROVIDER_IDS] }); @@ -85,7 +89,7 @@ export const ORCHESTRATION_TOOL_DEFINITIONS = Object.freeze([ ), tool( "wait_for_agent", - `Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason "idle" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), "needs_approval" (its card shows a prompt only the person may answer; never answer it yourself), "done" or "failed" (its process exited), "quiet" (it reports no status or no turn start and its screen stopped changing, so judge from output), "closed" (its card was closed) or "timeout" after timeoutSeconds (default ${DEFAULT_AGENT_WAIT_SECONDS}, at most ${MAX_AGENT_WAIT_SECONDS}), with status, exitCode, waitedMs, the masked terminal tail as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. After a timeout, call it again. Then read get_agent_result.`, + `Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason "idle" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), "needs_approval" (its card shows a prompt only the person may answer; never answer it yourself), "done" or "failed" (its process exited), "quiet" (it reports no status or no turn start and its screen stopped changing, so judge from output), "closed" (its card was closed) or "timeout" after timeoutSeconds (default ${DEFAULT_AGENT_WAIT_SECONDS}, at most ${MAX_AGENT_WAIT_SECONDS}; unless this session is Claude Code, a call returns after at most ${CLIENT_SAFE_AGENT_WAIT_SECONDS} seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the masked terminal tail as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.`, { sessionId, timeoutSeconds: integer({ minimum: 1, maximum: MAX_AGENT_WAIT_SECONDS }) }, ["sessionId"] ), diff --git a/src/main/services/agent-browser/OrchestrationTools.ts b/src/main/services/agent-browser/OrchestrationTools.ts index db65986fa..da0a610f6 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -7,6 +7,7 @@ import type { PromptDeliveryReceipt } from "../promptDelivery.ts"; import { LaunchRefusal } from "../launchRefusal.ts"; import type { PluginAgentTools } from "../PluginAgentTools.ts"; import { + CLIENT_SAFE_AGENT_WAIT_SECONDS, DEFAULT_AGENT_WAIT_SECONDS, MAX_AGENT_WAIT_SECONDS, ORCHESTRATION_TOOL_DEFINITIONS, @@ -119,9 +120,11 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { } this.requireOwned(orchestratorId, target); const seconds = typeof args.timeoutSeconds === "number" ? args.timeoutSeconds : DEFAULT_AGENT_WAIT_SECONDS; + // Shorter than the orchestrator's MCP client lets a tool call run, so it gets "timeout" and progress, not an error. + const limit = this.control.status(orchestratorId).provider === "claude" ? MAX_AGENT_WAIT_SECONDS : CLIENT_SAFE_AGENT_WAIT_SECONDS; try { const result = await this.control.waitFor(target, { - timeoutMs: Math.min(MAX_AGENT_WAIT_SECONDS, Math.max(1, seconds)) * 1_000, + timeoutMs: Math.min(limit, Math.max(1, seconds)) * 1_000, ...(signal ? { signal } : {}) }); return { ...result }; diff --git a/tests/orchestration-providers-wait.test.mjs b/tests/orchestration-providers-wait.test.mjs index 748cc024d..53d9c501f 100644 --- a/tests/orchestration-providers-wait.test.mjs +++ b/tests/orchestration-providers-wait.test.mjs @@ -2,6 +2,7 @@ import assert from "node:assert/strict"; import test from "node:test"; import { AGENT_PROVIDER_IDS, + CLIENT_SAFE_AGENT_WAIT_SECONDS, MAX_AGENT_WAIT_SECONDS, ORCHESTRATION_TOOL_DEFINITIONS, ORCHESTRATION_TOOL_NAMES, @@ -307,3 +308,23 @@ test("the skill tells the orchestrator to pass a model the person names", async const skill = await readFile(new URL("../agent/orchestrator/SKILL.md", import.meta.url), "utf8"); assert.match(skill, /If the person names a model, pass it as `model`/u); }); + +test("wait_for_agent returns before the orchestrator's MCP client gives up, as a timeout with the subagent's output", async () => { + for (const [provider, requested, expectedMs] of [ + ["opencode", 600, 50_000], ["codex", 120, 50_000], ["opencode", undefined, 50_000], ["opencode", 20, 20_000], + ["claude", 600, 600_000], ["claude", undefined, 55_000] + ]) { + const { terminals, control, handler } = setup(); + terminals.sessions.get("orch").provider = provider; + let received; + const real = control.waitFor.bind(control); + control.waitFor = (id, request) => { received = request.timeoutMs; return real(id, { ...request, timeoutMs: 30 }); }; + terminals.sessions.get("child").buffer = "step 3 of 5"; + const result = await call(handler, "wait_for_agent", { sessionId: "child", ...(requested ? { timeoutSeconds: requested } : {}) }); + assert.equal(received, expectedMs, `${provider} asking for ${requested ?? "the default"}`); + assert.deepEqual([result.reason, result.status, result.output], ["timeout", "working", "step 3 of 5"]); + } + assert.ok(CLIENT_SAFE_AGENT_WAIT_SECONDS < 60, "below the 60-second tool deadline of Codex's and OpenCode's MCP clients"); + assert.match(definition("wait_for_agent").description, /unless this session is Claude Code, a call returns after at most 50 seconds/u); + assert.match(definition("wait_for_agent").description, /A timeout means it is still running: read output as its progress and call wait_for_agent again/u); +});