From 62c90a04edec32bd57d2a5d2478320910ccf4a8d Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:19:01 +0000 Subject: [PATCH] fix(orchestration): count approval requests per CLI signal and report them once the prompt is drawn wait_for_agent could return an OpenCode approval before its prompt was on the screen (permission.asked comes first), report one Qwen prompt twice (its title and its PermissionRequest hook each counted a request), and miss a second Grok prompt (its permission_prompt Notification, its only request hook, was treated as an echo). TerminalManager now notes whether a request hook has named the pending request and where its output started. The first request hook after a title or echo is that same request; Grok's Notification is a request. wait_for_agent returns needs_approval once output arrived since the request and settled, or after settleMs when the screen does not change. --- docs/agent-orchestration.md | 2 +- src/main/services/AgentControlService.ts | 24 ++++- src/main/services/TerminalManager.ts | 31 +++++- tests/orchestrator-approval-answers.test.mjs | 5 +- .../wait-for-agent-approval-signals.test.mjs | 95 +++++++++++++++++++ 5 files changed, 147 insertions(+), 10 deletions(-) create mode 100644 tests/wait-for-agent-approval-signals.test.mjs diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index e664752b0..3833d3a5b 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). 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 plain-text output. 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` (once per prompt: a later wait on the same prompt waits for the person's answer instead of returning it again, while a new request, even one right after the person answered the last, returns at once), `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the end of the subagent's screen as masked plain text (as `get_agent_result`). 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 plain-text output. 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` (once per prompt: a later wait on the same prompt waits for the person's answer instead of returning it again, while a new request, even one right after the person answered the last, returns as soon as its prompt is on the screen, or after about a second if the screen does not change), `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the end of the subagent's screen as masked plain text (as `get_agent_result`). 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 a prompt is submitted or the next turn starts), plus `status`, the exit state and the end of the subagent's screen as masked plain text (a headless terminal renders the redraws of a full-screen TUI such as OpenCode from the last 64 KiB of masked output, so no control sequences remain; `wait_for_agent` returns the same). Other providers have no `answer`: read that text. `observe_agent`: the current status and the end of the screen as the same plain text (at most `maxChars`). | | `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. `send_to_agent` is refused while the subagent is `needs_approval` (any CLI's own approval or permission prompt: Claude Code, Codex, Grok, Kimi, Qwen, Hermes, OpenCode's permission and question prompts): what it typed (or its Enter) would answer the person's prompt. | diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index 0a95d0c1a..12894ac2a 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -90,7 +90,10 @@ export interface AgentWaitResult { export interface AgentWaitTiming { /** How often a waiting call reads the session again. */ checkMs: number; - /** How long the screen must stay the same before an idle status counts (a CLI may still be drawing its answer). */ + /** + * How long the screen must stay the same before an idle status counts (a CLI may still be drawing its answer), and + * the longest a needs_approval waits for its prompt to reach the screen. + */ settleMs: number; /** How long a session without status must show the same screen before it counts as "quiet". */ quietMs: number; @@ -393,12 +396,15 @@ export class AgentControlService { if (!session) return answer(null, "closed"); const now = Date.now(); const current = this.outputOffset(sessionId); - if (current !== offset) { offset = current; changedAt = now; } + const stillWriting = current !== offset; + if (stillWriting) { offset = current; changedAt = now; } const quietFor = now - changedAt; if (session.exitCode !== null) return answer(session, session.exitCode === 0 ? "done" : "failed"); // A request a wait already returned (the card shows no newer one) is the person's to answer: wait for it. const reported = this.reportedApprovals.has(sessionId) && this.reportedApprovals.get(sessionId) === this.approvalRequest(sessionId); - if (session.status === "needs_approval" && !reported) return answer(session, "needs_approval"); + if (session.status === "needs_approval" && !reported && this.approvalOnScreen(sessionId, current, stillWriting, now, timing)) { + return answer(session, "needs_approval"); + } if (session.status !== "needs_approval") this.reportedApprovals.delete(sessionId); // After a prompt, an idle that no turn followed (the CLI's startup idle, or one reported before the turn began) // is not the answer: only an idle after a turn that started since that prompt is. A CLI that never reports its @@ -483,6 +489,18 @@ export class AgentControlService { return tail(typeof this.terminals.redactSecrets === "function" ? this.terminals.redactSecrets(text) : text, maxChars); } + /** + * Whether the current approval request's prompt can be read: the screen has changed since the request was counted + * and did not change in the last check. A request signal can come before its prompt is drawn (OpenCode's + * permission.asked); one whose prompt was drawn first, or never is, counts as shown once settleMs passed. + */ + private approvalOnScreen(sessionId: string, current: number, stillWriting: boolean, now: number, timing: AgentWaitTiming): boolean { + let prompt: { outputOffset: number; at: number } | null = null; + try { prompt = typeof this.terminals.approvalPrompt === "function" ? this.terminals.approvalPrompt(sessionId) : null; } catch { prompt = null; } + if (!prompt) return true; + return (current > prompt.outputOffset && !stillWriting) || now - prompt.at >= timing.settleMs; + } + /** The card's current approval request (TerminalManager.approvalRequest); undefined when the manager has none. */ private approvalRequest(sessionId: string): number | undefined { try { return typeof this.terminals.approvalRequest === "function" ? this.terminals.approvalRequest(sessionId) ?? undefined : undefined; } diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index a9fb41588..f6507f51e 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -197,6 +197,11 @@ interface ManagedSession { * reader comparing it with an earlier value never mistakes a new request for one it already saw. */ approvalRequests?: number; + /** + * The current approval request: whether a request hook (not only a title or an echo) has told it yet, and the + * output offset and time it was counted at (see approvalPrompt). + */ + approvalRequestState?: { hooked: boolean; outputOffset: number; at: number }; } type EnvironmentService = Pick rm(root, { recursive: true, force: true })); + const calls = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + t.after(() => terminals.shutdown()); + const control = new AgentControlService(terminals, { waitTiming: timing }); + const orchestrator = terminals.create({ provider: "claude", profile: "normal", cwd: root, position: at, role: "orchestrator" }); + const child = terminals.create({ provider, profile: "normal", cwd: root, position: at, role: "subagent", parentSessionId: orchestrator.id }); + const pty = calls.at(-1).process; + const signal = (event, source = "hook") => terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event }, source); + return { terminals, control, child, pty, signal }; +} + +async function pending(promise, ms = 150) { + let settled = false; + void promise.then(() => { settled = true; }, () => { settled = true; }); + await delay(ms); + return !settled; +} + +test("an approval signalled before its prompt is drawn is reported with the prompt, and still only once", async (t) => { + const { control, child, pty, signal } = await fixture(t, "opencode", { checkMs: 5, settleMs: 2_000, quietMs: 60_000 }); + signal("permission.asked"); + const wait = control.waitFor(child.id, { timeoutMs: 5_000 }); + await delay(60); + pty.emitData(PROMPT); + const reported = await wait; + assert.equal(reported.reason, "needs_approval"); + assert.match(reported.output, /rm -rf build/, "the prompt is in the output"); + assert.ok(reported.waitedMs < 1_500, `returned once the prompt was drawn, not at the settle limit (${reported.waitedMs} ms)`); + assert.equal(await pending(control.waitFor(child.id, { timeoutMs: 5_000 })), true, "the next wait waits for the person"); +}); + +test("an approval whose screen never changes is still reported after the settle time", async (t) => { + const { control, child, signal } = await fixture(t, "opencode", { checkMs: 5, settleMs: 80, quietMs: 60_000 }); + signal("permission.asked"); + const reported = await control.waitFor(child.id, { timeoutMs: 5_000 }); + assert.equal(reported.reason, "needs_approval"); + assert.ok(reported.waitedMs < 1_000, `no wait until the timeout (${reported.waitedMs} ms)`); +}); + +test("Qwen's title and its PermissionRequest hook for one prompt are one request; a later hook is a new one", async (t) => { + const { terminals, control, child, signal } = await fixture(t, "qwen"); + signal(undefined, "title"); + assert.equal((await control.waitFor(child.id, { timeoutMs: 5_000 })).reason, "needs_approval"); + signal("PermissionRequest"); + const same = control.waitFor(child.id, { timeoutMs: 5_000 }); + assert.equal(await pending(same), true, "the same prompt is not reported again"); + + terminals.input(child.id, "1"); + signal("PermissionRequest"); + assert.equal((await same).reason, "needs_approval", "the next request is reported"); +}); + +test("an echo Notification before the PermissionRequest hook is the same request", async (t) => { + const { control, child, signal } = await fixture(t, "claude"); + signal("Notification"); + assert.equal((await control.waitFor(child.id, { timeoutMs: 5_000 })).reason, "needs_approval"); + signal("PermissionRequest"); + signal("Notification"); + assert.equal(await pending(control.waitFor(child.id, { timeoutMs: 5_000 })), true); +}); + +test("each of Grok's permission_prompt Notifications is a request, one right after another too", async (t) => { + const { terminals, control, child, signal } = await fixture(t, "grok"); + signal("Notification"); + assert.equal((await control.waitFor(child.id, { timeoutMs: 5_000 })).reason, "needs_approval"); + const same = control.waitFor(child.id, { timeoutMs: 5_000 }); + assert.equal(await pending(same), true, "the reported prompt waits for the person"); + + terminals.input(child.id, "1"); + signal("Notification"); + const next = await same; + assert.equal(next.reason, "needs_approval", "Grok's second prompt is reported"); + assert.ok(next.waitedMs < 2_000, `at once, not at the timeout (${next.waitedMs} ms)`); + assert.equal(await pending(control.waitFor(child.id, { timeoutMs: 5_000 })), true, "and only once"); +});