From 4bba2cf1d05b29dfe10bc7bbb7ec161cec3f3ed9 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 11:33:42 +0000 Subject: [PATCH 1/9] fix(terminal): remove a closed card's run folder only after its launch files Closing a card started the run cleanup and the removal of runs/ at the same time, and a launch still being prepared (plugin prepare, environment wrap) could write run files after the folder was gone. A throw from the environment wrap also skipped the planned and contributed cleanup. Contributed launches are now tracked. Closing waits for pending launches, then the serialized exit/restart cleanups, then removes the run folders each pipeline created for this card object, and the card folder only when it is empty, so a card brought back under the same id keeps its new run. An unadopted launch releases its planned spawn and contribution in a finally block, and a launch whose card was closed or restarted in the same tick never asks its plugins. Run folders are removed with retries for files Windows still holds open. --- src/main/services/LaunchPipeline.ts | 41 +++- src/main/services/TerminalManager.ts | 313 +++++++++++++++------------ tests/launch-cleanup-order.test.mjs | 211 ++++++++++++++++++ tests/launch-file-lifecycle.test.mjs | 282 ++++++++++++++++++++++++ 4 files changed, 708 insertions(+), 139 deletions(-) create mode 100644 tests/launch-cleanup-order.test.mjs create mode 100644 tests/launch-file-lifecycle.test.mjs diff --git a/src/main/services/LaunchPipeline.ts b/src/main/services/LaunchPipeline.ts index 439370a56..f6adc53e5 100644 --- a/src/main/services/LaunchPipeline.ts +++ b/src/main/services/LaunchPipeline.ts @@ -1,5 +1,5 @@ import { randomUUID } from "node:crypto"; -import { mkdir, rm, writeFile } from "node:fs/promises"; +import { mkdir, rm, rmdir, writeFile } from "node:fs/promises"; import { dirname, join, resolve } from "node:path"; import type { LaunchProfileId, @@ -73,6 +73,8 @@ export type PreparedLaunch = envSources: Record; /** A contributor runs the agent on another model than its vendor's: "auto" becomes accept-edits. */ thirdPartyModel: boolean; + /** This run's own folder below the card's folder; `cleanup` removes it. */ + runDirectory: string; cleanup(): Promise; } | { ok: false; reason: string }; @@ -118,9 +120,25 @@ export class LaunchPipeline { return rm(this.dependencies.runsRoot, { recursive: true, force: true }); } - /** Removes a closed session's file folders. */ - forgetSession(sessionId: string): Promise { - return rm(join(this.dependencies.runsRoot, safeSegment(sessionId)), { recursive: true, force: true }); + /** + * Removes a closed card's run folders that this pipeline prepared for it, then the card's folder if nothing else + * is left in it. A card brought back under the same id may already be writing a new run folder there; it is kept. + */ + async forgetSession(sessionId: string, runDirectories: Iterable): Promise { + const parent = join(this.dependencies.runsRoot, safeSegment(sessionId)); + const errors: unknown[] = []; + for (const runDirectory of new Set(runDirectories)) { + // Only a run folder directly below this card's folder is ever removed here. + if (dirname(resolve(runDirectory)) !== resolve(parent)) continue; + try { await removeRunFolder(runDirectory); } catch (error) { errors.push(error); } + } + try { + await rmdir(parent); + } catch (error) { + // Still in use by a newer run of the same card, or already gone; the startup sweep removes what is left. + if (!PARENT_KEPT_CODES.has((error as NodeJS.ErrnoException).code ?? "")) errors.push(error); + } + if (errors.length) throw new AggregateError(errors, "Launch run folders could not be removed."); } /** Launch policies that apply to this agent: every launch of it asks them, chosen or not. */ @@ -251,7 +269,7 @@ export class LaunchPipeline { ...policies.map((contributor) => this.ask(contributor, context, false)) ]); const runDirectory = join(this.dependencies.runsRoot, safeSegment(context.sessionId), randomUUID()); - const cleanup = (): Promise => rm(runDirectory, { recursive: true, force: true }); + const cleanup = (): Promise => removeRunFolder(runDirectory); const refuse = async (reason: string): Promise => { await cleanup().catch(() => undefined); return { ok: false, reason }; @@ -327,7 +345,7 @@ export class LaunchPipeline { args.push(...contributedArgs.map(expand)); thirdPartyModel ||= contribution.thirdPartyModel === true; } - return { ok: true, env, args, secrets, envSources, thirdPartyModel, cleanup }; + return { ok: true, env, args, secrets, envSources, thirdPartyModel, runDirectory, cleanup }; } private async ask( @@ -562,6 +580,17 @@ function unavailableReason(pluginId: string): string { return `Needs plugin ${pluginId} for its launch options; it is disabled, removed, or its native code is not trusted.`; } +/** Errors that leave a card's folder in place on purpose: another run still uses it, or it is gone. */ +const PARENT_KEPT_CODES = new Set(["ENOENT", "ENOTEMPTY", "EEXIST", "EBUSY", "EPERM"]); + +/** + * Removes one run folder. On Windows the agent may still hold a file there for a moment after its PTY exits, so + * busy/permission errors are retried briefly before giving up. + */ +function removeRunFolder(runDirectory: string): Promise { + return rm(runDirectory, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); +} + function safeSegment(value: string): string { return value.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_").slice(0, 128) || "_"; } diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index 2b70689de..3f3102470 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -135,6 +135,15 @@ interface ManagedSession { launchToken: number; /** Removes the current run's plugin files; called when the process exits. */ launchCleanup: (() => Promise) | null; + /** Cleanup already started by an earlier exit; closing the card must drain it before deleting its parent. */ + launchCleanupPending?: Promise; + /** Whole contributed launches, including asynchronous preparation/wrapping and abandoned-run cleanup. */ + launchTasks?: Set>; + /** + * The pipelines that prepared launches for this card, each with the run folders it created for this card object, + * retained across host reconfiguration/restart. Closing removes only these, never a later card's under the same id. + */ + launchRunFolders?: Map, Set>; /** A restored grok card waits for its grid before launching; plugins still learn it is a restore. */ restoringLaunch: boolean; /** The environment was prepared or resumed in this run of the app, so it can be wrapped now. */ @@ -1130,6 +1139,37 @@ export class TerminalManager { } } + /** Serializes this card's run cleanup across exit/restart; callbacks retain their specific launch ownership. */ + private cleanupLaunchFiles(session: ManagedSession): Promise { + const cleanup = session.launchCleanup; + session.launchCleanup = null; + const previous = session.launchCleanupPending; + if (!cleanup) return previous ?? Promise.resolve(); + const pending = (async (): Promise => { + if (previous) await previous.catch(() => undefined); + await cleanup(); + })(); + session.launchCleanupPending = pending; + void pending.finally(() => { + if (session.launchCleanupPending === pending) delete session.launchCleanupPending; + }).catch(() => undefined); + return pending; + } + + /** Closing a card waits for producers of run files, not just the current process's adopted cleanup. */ + private async forgetLaunchFiles(session: ManagedSession): Promise { + while (session.launchTasks?.size) await Promise.allSettled([...session.launchTasks]); + try { await this.cleanupLaunchFiles(session); } + finally { + const errors: unknown[] = []; + // Different pipeline instances may share runsRoot; even their parent deletions must not overlap. + for (const [pipeline, runDirectories] of session.launchRunFolders ?? []) { + try { await pipeline.forgetSession(session.metadata.id, runDirectories); } catch (error) { errors.push(error); } + } + if (errors.length) throw new AggregateError(errors, "Launch file folders could not be removed."); + } + } + /** * Closes a card. A card in a plugin environment releases it: `keepEnvironmentData` is the person's * answer to "Keep environment data?" (kept unless they said no). Quitting releases nothing. @@ -1163,9 +1203,11 @@ export class TerminalManager { this.redaction.clear(`session:${id}`); this.releaseIsolation(id); session.launchToken += 1; - void session.launchCleanup?.().catch(() => undefined); - session.launchCleanup = null; - if (session.extras.options) void this.launchPipeline?.forgetSession(id).catch(() => undefined); + // launchToken and launch waiters were invalidated above: pending preparation/wrapping can now unwind before + // parent removal. Its original pipeline remains the owner even if the host configuration has since changed. + void this.forgetLaunchFiles(session).catch((error: unknown) => { + console.warn(`CanvasTTY could not remove the launch files of card ${id}.`, error); + }); session.agentBrowser?.cleanup(); session.agentRuntime?.cleanup(); session.agentOrchestration?.cleanup(); @@ -1872,7 +1914,9 @@ export class TerminalManager { ): void { const token = ++session.launchToken; const { metadata } = session; - void this.runContributedLaunch(id, session, token, resume, restoring, answerCaptureGrantExpiresAt) + const tasks = session.launchTasks ??= new Set(); + // Register before invoking plugin code, which may synchronously close or restart its card. + const task = Promise.resolve().then(() => this.runContributedLaunch(id, session, token, resume, restoring, answerCaptureGrantExpiresAt)) .catch((error: unknown): LaunchOutcome => { metadata.failureDetails = this.redactSecrets(`Launch refused: ${error instanceof Error ? error.message : String(error)}`); return "failed"; @@ -1886,7 +1930,9 @@ export class TerminalManager { this.emitSession(metadata, outcome === "failed" ? failureOrigin : null); this.schedulePersistence(); }) - .finally(() => this.wakeLaunchWaiters(session)); + .finally(() => { tasks.delete(task); this.wakeLaunchWaiters(session); }); + tasks.add(task); + void task.catch(() => undefined); } private async runContributedLaunch( @@ -1905,6 +1951,8 @@ export class TerminalManager { return "failed"; }; const environments = this.environments; + // The launch starts a microtask after it was registered; a card closed or restarted in that same tick is done. + if (!live()) return "superseded"; // 1. Place a new session where the person chose. The choice stays saved with the card until the plugin has // prepared it, so a card whose preparation was cut short (quit, crash) or failed never restores locally. @@ -1946,142 +1994,142 @@ export class TerminalManager { // 3. Chosen launch contributors, and the launch policies that apply. let contribution: LaunchContribution | null = null; - const trustedFolder = session.extras.environment ? undefined : this.personTrustedFolder(metadata.parentSessionId, metadata.cwd); - if (session.extras.options || this.policyApplies(metadata.provider)) { - const pipeline = this.launchPipeline; - if (!pipeline) return refuse(missingLaunchPlugins(Object.keys(session.extras.options ?? {}))); - const placedIn = session.extras.environment; - const prepared = await pipeline.prepare({ - sessionId: id, - provider: metadata.provider, - profile: metadata.profile, - role: metadata.role, - cwd: metadata.cwd, - ...(metadata.parentSessionId !== undefined ? { parentSessionId: metadata.parentSessionId } : {}), - restoring, - resume: resume !== null, - options: structuredClone(session.extras.options ?? {}) as Record>, - environment: placedIn ? { pluginId: placedIn.pluginId, kind: placedIn.kind } : null, - ...(trustedFolder ? { trustedFolder } : {}) - }); - if (!live()) { - if (prepared.ok) void prepared.cleanup().catch(() => undefined); - return "superseded"; + let adopted = false; + let plannedCleanup: (() => void) | undefined; + try { + const trustedFolder = session.extras.environment ? undefined : this.personTrustedFolder(metadata.parentSessionId, metadata.cwd); + if (session.extras.options || this.policyApplies(metadata.provider)) { + const pipeline = this.launchPipeline; + if (!pipeline) return refuse(missingLaunchPlugins(Object.keys(session.extras.options ?? {}))); + // This pipeline may write run files for the card, so closing it later removes its folder there. + const runFolders = session.launchRunFolders ??= new Map(); + const ownFolders = runFolders.get(pipeline) ?? new Set(); + runFolders.set(pipeline, ownFolders); + const placedIn = session.extras.environment; + const prepared = await pipeline.prepare({ + sessionId: id, + provider: metadata.provider, + profile: metadata.profile, + role: metadata.role, + cwd: metadata.cwd, + ...(metadata.parentSessionId !== undefined ? { parentSessionId: metadata.parentSessionId } : {}), + restoring, + resume: resume !== null, + options: structuredClone(session.extras.options ?? {}) as Record>, + environment: placedIn ? { pluginId: placedIn.pluginId, kind: placedIn.kind } : null, + ...(trustedFolder ? { trustedFolder } : {}) + }); + if (prepared.ok) { + contribution = prepared; + ownFolders.add(prepared.runDirectory); + } + if (!live()) return "superseded"; + if (!prepared.ok) return refuse(prepared.reason); + this.addLaunchSecrets(session, prepared.secrets); } - if (!prepared.ok) return refuse(prepared.reason); - contribution = prepared; - this.addLaunchSecrets(session, prepared.secrets); - } - const dropContribution = (): void => { - void contribution?.cleanup().catch(() => undefined); - }; - // 4. What the environment keeps of CanvasTTY's protection, and the isolation layer for this launch. - const keeps = environment ? this.environments?.keeps?.(environment) ?? {} : {}; - if (environment && keeps.launch !== true && metadata.profile !== "normal") { - dropContribution(); - return refuse(`${environment.label} does not pass the launch on unchanged (the plugin does not declare it), so the ${metadata.profile} profile's settings and CanvasTTY's hooks would not reach the agent there. Launch it in normal, or use an environment that keeps them.`); - } - const decision = this.launchIsolation(id, metadata.provider, metadata.profile, metadata.role, - environment ? { isolated: keeps.isolated === true, label: environment.label } : null); - if (decision.refuse) { - dropContribution(); - return refuse(decision.refuse); - } - if (environment && keeps.launch !== true) { - metadata.isolation = { ...(metadata.isolation ?? { state: "environment" }), - reason: `${metadata.isolation?.reason ? `${metadata.isolation.reason} ` : ""}Base protection and CanvasTTY's hooks do not reach the agent in ${environment.label}.` }; - } + // 4. What the environment keeps of CanvasTTY's protection, and the isolation layer for this launch. + const keeps = environment ? this.environments?.keeps?.(environment) ?? {} : {}; + if (environment && keeps.launch !== true && metadata.profile !== "normal") { + return refuse(`${environment.label} does not pass the launch on unchanged (the plugin does not declare it), so the ${metadata.profile} profile's settings and CanvasTTY's hooks would not reach the agent there. Launch it in normal, or use an environment that keeps them.`); + } + const decision = this.launchIsolation(id, metadata.provider, metadata.profile, metadata.role, + environment ? { isolated: keeps.isolated === true, label: environment.label } : null); + if (decision.refuse) { + return refuse(decision.refuse); + } + if (environment && keeps.launch !== true) { + metadata.isolation = { ...(metadata.isolation ?? { state: "environment" }), + reason: `${metadata.isolation?.reason ? `${metadata.isolation.reason} ` : ""}Base protection and CanvasTTY's hooks do not reach the agent in ${environment.label}.` }; + } - // 5. The host spawns the PTY; an environment only rewrites what is spawned, and the isolation layer wraps that. - let planned: PlannedSpawn | { failure: LaunchFailure }; - try { - planned = this.planSpawn(id, metadata.provider, decision.profile, metadata.cwd, resume, - session.captureResult, metadata.role, answerCaptureGrantExpiresAt, contribution, trustedFolder, Boolean(environment), decision.apply); - } catch (error) { - dropContribution(); - metadata.failureDetails = this.redactSecrets(error instanceof Error ? error.message : String(error)); - return "failed"; - } - if ("failure" in planned) { - dropContribution(); - applyLaunchFailure(metadata, planned.failure); - return "failed"; - } - const abandon = (): void => { - planned.cleanup(); - dropContribution(); - }; - this.noteConfiguredMode(id, metadata.provider, decision.profile, planned.env, planned.cwd); - let spawn: { command: string; args: string[] | string; cwd: string; env: Record } = planned; - if (environment && environments) { - if (typeof planned.args === "string") { - abandon(); - return refuse("this provider's Windows batch launcher cannot run in a plugin environment."); + // 5. The host spawns the PTY; an environment only rewrites what is spawned, and the isolation layer wraps that. + let planned: PlannedSpawn | { failure: LaunchFailure }; + try { + planned = this.planSpawn(id, metadata.provider, decision.profile, metadata.cwd, resume, + session.captureResult, metadata.role, answerCaptureGrantExpiresAt, contribution, trustedFolder, Boolean(environment), decision.apply); + } catch (error) { + metadata.failureDetails = this.redactSecrets(error instanceof Error ? error.message : String(error)); + return "failed"; } - const secretValues = new Set(contribution?.secrets ?? []); - const secretEnvNames = Object.keys(contribution?.env ?? {}).filter((key) => secretValues.has(contribution!.env[key]!)); - // The environment sees the launch's own variables, never CanvasTTY's reserved ones or secret values. - const visible = Object.fromEntries(Object.entries(planned.launchEnvironment) - .filter(([key]) => !RESERVED_ENV.test(key) && !secretEnvNames.includes(key))); - const wrapped = await environments.wrap(environment, { - sessionId: id, - provider: metadata.provider, - launch: { command: planned.command, args: planned.args, env: visible, cwd: planned.cwd }, - secretEnvNames, - takenEnv: new Set(Object.keys(planned.launchEnvironment)), - path: launchSearchPath(planned.env) - }); - if (!live()) { - abandon(); - return "superseded"; + if ("failure" in planned) { + applyLaunchFailure(metadata, planned.failure); + return "failed"; } - if (!wrapped.ok) { - abandon(); - return refuse(wrapped.reason); + plannedCleanup = planned.cleanup; + this.noteConfiguredMode(id, metadata.provider, decision.profile, planned.env, planned.cwd); + let spawn: { command: string; args: string[] | string; cwd: string; env: Record } = planned; + if (environment && environments) { + if (typeof planned.args === "string") { + return refuse("this provider's Windows batch launcher cannot run in a plugin environment."); + } + const secretValues = new Set(contribution?.secrets ?? []); + const secretEnvNames = Object.keys(contribution?.env ?? {}).filter((key) => secretValues.has(contribution!.env[key]!)); + // The environment sees the launch's own variables, never CanvasTTY's reserved ones or secret values. + const visible = Object.fromEntries(Object.entries(planned.launchEnvironment) + .filter(([key]) => !RESERVED_ENV.test(key) && !secretEnvNames.includes(key))); + const wrapped = await environments.wrap(environment, { + sessionId: id, + provider: metadata.provider, + launch: { command: planned.command, args: planned.args, env: visible, cwd: planned.cwd }, + secretEnvNames, + takenEnv: new Set(Object.keys(planned.launchEnvironment)), + path: launchSearchPath(planned.env) + }); + if (!live()) { + return "superseded"; + } + if (!wrapped.ok) { + return refuse(wrapped.reason); + } + this.addLaunchSecrets(session, wrapped.secrets); + spawn = { command: wrapped.command, args: wrapped.args, cwd: wrapped.cwd, + env: { ...planned.env, ...(wrapped.cwd !== planned.cwd ? { PWD: wrapped.cwd } : {}), ...wrapped.env } }; } - this.addLaunchSecrets(session, wrapped.secrets); - spawn = { command: wrapped.command, args: wrapped.args, cwd: wrapped.cwd, - env: { ...planned.env, ...(wrapped.cwd !== planned.cwd ? { PWD: wrapped.cwd } : {}), ...wrapped.env } }; - } - if (decision.apply) { + if (decision.apply) { + try { + spawn = { ...this.wrapIsolated(id, metadata.provider, decision.profile, spawn), cwd: spawn.cwd }; + } catch (error) { + return refuse(error instanceof Error ? error.message : String(error)); + } + } + let process: IPty; try { - spawn = { ...this.wrapIsolated(id, metadata.provider, decision.profile, spawn), cwd: spawn.cwd }; + process = this.spawnPty(spawn.command, spawn.args, { + name: "xterm-256color", cols: session.cols, rows: session.rows, cwd: spawn.cwd, env: spawn.env + }); } catch (error) { - abandon(); - return refuse(error instanceof Error ? error.message : String(error)); + this.releaseIsolation(id); + metadata.failureDetails = this.redactSecrets(error instanceof Error ? error.message : String(error)); + return "failed"; + } + session.process = process; + if (planned.launchEnvironment.CANVASTTY_CODEX_KEYBOARD) { + metadata.nativeEditor = JSON.parse(planned.launchEnvironment.CANVASTTY_CODEX_KEYBOARD); + } else { + delete metadata.nativeEditor; + } + this.launchContexts.set(id, { cwd: spawn.cwd, configDir: spawn.env.CLAUDE_CONFIG_DIR ?? null }); + session.agentBrowser = planned.agentBrowser; + session.agentRuntime = planned.agentRuntime; + session.agentOrchestration = planned.agentOrchestration; + session.launchCleanup = contribution?.cleanup ?? null; + adopted = true; + metadata.status = initialSessionStatus(metadata.provider); + metadata.exitCode = null; + metadata.failureDetails = null; + this.bindProcess(id, session, process); + const runtimeStatus = this.agentRuntime?.currentStatus(id); + if (runtimeStatus) metadata.status = runtimeStatus; + if (environment) this.describeEnvironment(id, session, environment); + return "launched"; + } finally { + // Unadopted resources remain owned by this tracked launch, including throws during plugin wrapping. + if (!adopted) { + try { plannedCleanup?.(); } + finally { await contribution?.cleanup().catch(() => undefined); } } } - let process: IPty; - try { - process = this.spawnPty(spawn.command, spawn.args, { - name: "xterm-256color", cols: session.cols, rows: session.rows, cwd: spawn.cwd, env: spawn.env - }); - } catch (error) { - abandon(); - this.releaseIsolation(id); - metadata.failureDetails = this.redactSecrets(error instanceof Error ? error.message : String(error)); - return "failed"; - } - session.process = process; - if (planned.launchEnvironment.CANVASTTY_CODEX_KEYBOARD) { - metadata.nativeEditor = JSON.parse(planned.launchEnvironment.CANVASTTY_CODEX_KEYBOARD); - } else { - delete metadata.nativeEditor; - } - this.launchContexts.set(id, { cwd: spawn.cwd, configDir: spawn.env.CLAUDE_CONFIG_DIR ?? null }); - session.agentBrowser = planned.agentBrowser; - session.agentRuntime = planned.agentRuntime; - session.agentOrchestration = planned.agentOrchestration; - session.launchCleanup = contribution?.cleanup ?? null; - metadata.status = initialSessionStatus(metadata.provider); - metadata.exitCode = null; - metadata.failureDetails = null; - this.bindProcess(id, session, process); - const runtimeStatus = this.agentRuntime?.currentStatus(id); - if (runtimeStatus) metadata.status = runtimeStatus; - if (environment) this.describeEnvironment(id, session, environment); - return "launched"; } private addLaunchSecrets(session: ManagedSession, secrets: readonly string[]): void { @@ -2147,8 +2195,7 @@ export class TerminalManager { current.agentRuntime = null; current.agentOrchestration?.cleanup(); current.agentOrchestration = null; - void current.launchCleanup?.().catch(() => undefined); - current.launchCleanup = null; + void this.cleanupLaunchFiles(current).catch(() => undefined); this.emitSession(current.metadata); // Recorded at the moment of exit, so a finished agent is never relaunched. this.schedulePersistence(); diff --git a/tests/launch-cleanup-order.test.mjs b/tests/launch-cleanup-order.test.mjs new file mode 100644 index 000000000..f18e5c115 --- /dev/null +++ b/tests/launch-cleanup-order.test.mjs @@ -0,0 +1,211 @@ +import assert from "node:assert/strict"; +import { mkdtemp, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { LaunchPipeline } from "../src/main/services/LaunchPipeline.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; + +function deferred() { + let resolve; + const promise = new Promise((done) => { resolve = done; }); + return { promise, resolve }; +} + +function cleanupPipeline(runs, serviceCalls = []) { + return new LaunchPipeline({ + contributors: () => [{ + pluginId: "fixture.cleanup", + pluginName: "Cleanup fixture", + serviceId: "launch", + secrets: false, + launch: { fields: [{ key: "enabled", label: "Enabled", kind: "boolean", default: true }] } + }], + call: async (...args) => { + serviceCalls.push(args); + return { env: { FIXTURE_FILE: "{launchFiles}/run.txt" }, files: [{ relPath: "run.txt", content: "temporary launch data" }] }; + }, + secret: async () => null, + runsRoot: runs, + timeoutMs: 2000 + }); +} + +const createCard = (terminals, cwd) => terminals.create({ + provider: "codex", + profile: "normal", + cwd, + position: { x: 0, y: 0 }, + launchOptions: { "fixture.cleanup": { enabled: true } } +}); + +/** + * One card with a launch plugin. Each run's cleanup is held until the test releases it, and every step of the + * child (run folder) and parent (card folder) removals is recorded in `events`. + */ +async function fixture(t, { rejectChild = false } = {}) { + const root = await mkdtemp(join(tmpdir(), "ctty-cleanup-order-")); + const runs = join(root, "runs"); + const rows = []; + const calls = []; + const events = []; + const spawned = [deferred(), deferred()]; + const forgotten = deferred(); + const pipeline = cleanupPipeline(runs); + const prepare = pipeline.prepare.bind(pipeline); + const forget = pipeline.forgetSession.bind(pipeline); + pipeline.prepare = async (context) => { + const contribution = await prepare(context); + assert.equal(contribution.ok, true); + const cleanup = contribution.cleanup; + const index = rows.length; + const row = { started: deferred(), release: deferred(), calls: 0 }; + rows.push(row); + contribution.cleanup = async () => { + row.calls++; + events.push(`child${index}:start`); + row.started.resolve(); + try { + await row.release.promise; + if (rejectChild) throw new Error("fixture child cleanup failure"); + await cleanup(); + } finally { + events.push(`child${index}:settled`); + } + }; + return contribution; + }; + let forgetCalls = 0; + pipeline.forgetSession = (id, runDirectories) => { + forgetCalls++; + events.push("parent:start"); + const pending = forget(id, runDirectories).then(() => { events.push("parent:done"); }); + forgotten.resolve(pending); + return pending; + }; + const fake = fakeSpawner(calls); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, (...args) => { + const pty = fake(...args); + spawned[calls.length - 1]?.resolve(); + return pty; + }); + terminals.configureLaunchPipeline(pipeline); + t.after(async () => { + for (const row of rows) row.release.resolve(); + terminals.disposeAll(); + await forgotten.promise; + await rm(root, { recursive: true, force: true }); + }); + const session = createCard(terminals, root); + await spawned[0].promise; + return { root, runs, rows, calls, events, spawned, forgotten, terminals, session, forgetCalls: () => forgetCalls }; +} + +for (const exited of [false, true]) { + for (const rejectChild of [false, true]) { + test(`parent launch cleanup waits for ${exited ? "previous exit" : "active disposal"} cleanup (${rejectChild ? "rejection" : "success"})`, { timeout: 5000 }, async (t) => { + const f = await fixture(t, { rejectChild }); + if (exited) f.calls[0].process.emitExit(1); + f.terminals.dispose(f.session.id); + f.terminals.dispose(f.session.id); + await f.rows[0].started.promise; + assert.equal(f.forgetCalls(), 0, "parent removal must not overlap a held child removal"); + assert.deepEqual(f.events, ["child0:start"]); + + f.rows[0].release.resolve(); + await f.forgotten.promise; + assert.deepEqual(f.events, ["child0:start", "child0:settled", "parent:start", "parent:done"]); + assert.equal(f.rows[0].calls, 1); + assert.equal(f.forgetCalls(), 1, "disposal remains idempotent"); + await assert.rejects(stat(join(f.runs, f.session.id)), { code: "ENOENT" }, "parent still cleaned after child failure"); + }); + } +} + +test("restart retains every pending run cleanup and invokes each captured callback once before forgetting the card", { timeout: 5000 }, async (t) => { + const f = await fixture(t); + f.calls[0].process.emitExit(1); + await f.rows[0].started.promise; + f.terminals.restart(f.session.id); + await f.spawned[1].promise; + assert.equal(f.rows.length, 2); + + f.terminals.dispose(f.session.id); + assert.equal(f.rows[1].calls, 0, "the newer cleanup queues behind the old launch callback"); + assert.equal(f.forgetCalls(), 0); + // A late notification from the old PTY must neither consume nor overwrite the new launch cleanup. + f.calls[0].process.emitExit(1); + f.rows[0].release.resolve(); + await f.rows[1].started.promise; + assert.equal(f.forgetCalls(), 0, "parent waits for both run directories"); + + f.rows[1].release.resolve(); + await f.forgotten.promise; + assert.deepEqual(f.events, ["child0:start", "child0:settled", "child1:start", "child1:settled", "parent:start", "parent:done"]); + assert.deepEqual(f.rows.map((row) => row.calls), [1, 1]); + assert.equal(f.forgetCalls(), 1); + await assert.rejects(stat(join(f.runs, f.session.id)), { code: "ENOENT" }); +}); + +test("a launch for a card closed in the same tick never asks its plugins or spawns", { timeout: 5000 }, async (t) => { + const root = await mkdtemp(join(tmpdir(), "ctty-cleanup-order-")); + const serviceCalls = []; + const calls = []; + const pipeline = cleanupPipeline(join(root, "runs"), serviceCalls); + const forgotten = []; + const forget = pipeline.forgetSession.bind(pipeline); + pipeline.forgetSession = (...args) => { + const pending = forget(...args); + forgotten.push(pending); + return pending; + }; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + terminals.configureLaunchPipeline(pipeline); + t.after(async () => { + terminals.disposeAll(); + await rm(root, { recursive: true, force: true }); + }); + + const session = createCard(terminals, root); + const internal = terminals.sessions.get(session.id); + const tasks = [...internal.launchTasks]; + terminals.dispose(session.id); + await Promise.allSettled(tasks); + await Promise.allSettled(forgotten); + + assert.equal(serviceCalls.length, 0, "no plugin prepares a launch for a card that is already closed"); + assert.equal(calls.length, 0); + await assert.rejects(stat(join(root, "runs", session.id)), { code: "ENOENT" }); +}); + +test("a failed launch-file removal at close is reported with the card id", { timeout: 5000 }, async (t) => { + const root = await mkdtemp(join(tmpdir(), "ctty-cleanup-order-")); + const calls = []; + const pipeline = cleanupPipeline(join(root, "runs")); + const failure = new Error("fixture forget failure"); + const forgotten = deferred(); + pipeline.forgetSession = async () => { + forgotten.resolve(); + throw failure; + }; + const warnings = []; + t.mock.method(console, "warn", (...args) => { warnings.push(args); }); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + terminals.configureLaunchPipeline(pipeline); + t.after(async () => { + terminals.disposeAll(); + await rm(root, { recursive: true, force: true }); + }); + + const session = createCard(terminals, root); + await Promise.allSettled([...terminals.sessions.get(session.id).launchTasks]); + terminals.dispose(session.id); + await forgotten.promise; + for (let i = 0; i < 20 && !warnings.length; i++) await new Promise((done) => setImmediate(done)); + + const warning = warnings.find(([message]) => String(message).includes(session.id)); + assert.ok(warning, "the close reports which card's launch files stayed behind"); + assert.ok(warning[1] instanceof AggregateError); + assert.deepEqual(warning[1].errors, [failure]); +}); diff --git a/tests/launch-file-lifecycle.test.mjs b/tests/launch-file-lifecycle.test.mjs new file mode 100644 index 000000000..7131f2ff5 --- /dev/null +++ b/tests/launch-file-lifecycle.test.mjs @@ -0,0 +1,282 @@ +import assert from "node:assert/strict"; +import { mkdtemp, readdir, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { basename, join } from "node:path"; +import test from "node:test"; +import { EnvironmentRegistry } from "../src/main/services/EnvironmentRegistry.ts"; +import { LaunchPipeline } from "../src/main/services/LaunchPipeline.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { persistedTerminalSession } from "../src/main/services/TerminalSessionStore.ts"; +import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; + +function deferred() { + let resolve; + const promise = new Promise((done) => { resolve = done; }); + return { promise, resolve }; +} + +async function fixture(t, { spawnFailure = false } = {}) { + const root = await mkdtemp(join(tmpdir(), "ctty-launch-files-")); + const runs = join(root, "runs"); + const calls = []; + const pipelines = []; + const gates = []; + const disposals = []; + const fake = fakeSpawner(calls); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, (...args) => { + if (spawnFailure) throw new Error("fixture PTY spawn failure"); + return fake(...args); + }); + // Closing a card starts its run-file cleanup in the background; the tests await that same promise. + const forget = terminals.forgetLaunchFiles.bind(terminals); + terminals.forgetLaunchFiles = (session) => { + const pending = forget(session); + disposals.push(pending); + return pending; + }; + const gate = () => { + const result = deferred(); + gates.push(result); + return result; + }; + + function pipeline({ holdPrepare = false, holdForget = false, failCleanup = false } = {}) { + const started = deferred(); + const release = gate(); + const forgetStarted = deferred(); + const forgetRelease = gate(); + const events = []; + const rows = []; + if (!holdPrepare) release.resolve(); + if (!holdForget) forgetRelease.resolve(); + const value = new LaunchPipeline({ + contributors: () => [{ + pluginId: "fixture.files", + pluginName: "Files", + serviceId: "launch", + secrets: false, + launch: { fields: [{ key: "enabled", label: "Enabled", kind: "boolean" }] } + }], + call: async () => { + started.resolve(); + await release.promise; + return { env: { FIXTURE_FILE: "{launchFiles}/run.txt" }, files: [{ relPath: "run.txt", content: "temporary" }] }; + }, + secret: async () => null, + runsRoot: runs, + timeoutMs: 4000 + }); + const prepare = value.prepare.bind(value); + const remove = value.forgetSession.bind(value); + value.prepare = async (context) => { + const result = await prepare(context); + assert.equal(result.ok, true); + const row = { file: result.env.FIXTURE_FILE, runDirectory: result.runDirectory, cleanupCalls: 0 }; + const cleanup = result.cleanup; + rows.push(row); + result.cleanup = async () => { + row.cleanupCalls++; + events.push("child"); + if (failCleanup) throw new Error("fixture cleanup failure"); + await cleanup(); + }; + return result; + }; + value.forgetSession = async (id, runDirectories) => { + events.push("parent:start"); + forgetStarted.resolve(); + await forgetRelease.promise; + await remove(id, runDirectories); + events.push("parent:done"); + }; + const result = { value, started, release, forgetStarted, forgetRelease, events, rows }; + pipelines.push(result); + return result; + } + + const create = (extra = {}) => terminals.create({ + provider: "codex", + profile: "normal", + cwd: root, + position: { x: 0, y: 0 }, + launchOptions: { "fixture.files": { enabled: true } }, + ...extra + }); + const drain = async () => { await Promise.allSettled(disposals); }; + t.after(async () => { + for (const item of gates) item.resolve(); + terminals.disposeAll(); + await drain(); + await rm(root, { recursive: true, force: true }); + }); + return { root, runs, calls, terminals, pipeline, create, gate, drain, disposals }; +} + +for (const failCleanup of [false, true]) { + test(`closing during preparation drains its late files before parent deletion (${failCleanup ? "failed" : "successful"} child cleanup)`, { timeout: 5000 }, async (t) => { + const f = await fixture(t); + const p = f.pipeline({ holdPrepare: true, failCleanup }); + f.terminals.configureLaunchPipeline(p.value); + const session = f.create(); + await p.started.promise; + f.terminals.dispose(session.id); + assert.deepEqual(p.events, []); + + p.release.resolve(); + await f.drain(); + assert.deepEqual(p.events, ["child", "parent:start", "parent:done"]); + assert.equal(p.rows[0].cleanupCalls, 1); + assert.equal(f.calls.length, 0); + // A failed child cleanup is retried by the parent step, which still removes only this card's own run folder. + await assert.rejects(stat(join(f.runs, session.id)), { code: "ENOENT" }); + }); +} + +test("restart tracks both pending preparations and sequentially forgets their original pipelines after reconfiguration", { timeout: 5000 }, async (t) => { + const f = await fixture(t); + const a = f.pipeline({ holdPrepare: true, holdForget: true }); + const b = f.pipeline({ holdPrepare: true }); + const c = f.pipeline(); + f.terminals.configureLaunchPipeline(a.value); + const session = f.create(); + await a.started.promise; + // Force a restart while its original plugin response is still in flight, as restoration can do. + const internal = f.terminals.sessions.get(session.id); + internal.metadata.status = "failed"; + internal.metadata.exitCode = 1; + f.terminals.configureLaunchPipeline(b.value); + f.terminals.restart(session.id); + await b.started.promise; + f.terminals.configureLaunchPipeline(c.value); + f.terminals.dispose(session.id); + + a.release.resolve(); + await Promise.resolve(); + assert.deepEqual(a.events, [], "parent cannot precede pending preparation"); + b.release.resolve(); + await a.forgetStarted.promise; + assert.deepEqual(a.events, ["child", "parent:start"]); + assert.deepEqual(b.events, ["child"], "same parent cannot be removed concurrently by another pipeline"); + assert.deepEqual(c.events, [], "current configuration is not the owner"); + + a.forgetRelease.resolve(); + await f.drain(); + assert.deepEqual(b.events, ["child", "parent:start", "parent:done"]); + assert.deepEqual([a.rows[0].cleanupCalls, b.rows[0].cleanupCalls], [1, 1]); + assert.equal(f.calls.length, 0); + await assert.rejects(stat(join(f.runs, session.id)), { code: "ENOENT" }); +}); + +for (const outcome of ["success", "refusal", "throw"]) { + test(`close while environment wrapping ${outcome} releases planned capability and files once`, { timeout: 5000 }, async (t) => { + const f = await fixture(t); + const p = f.pipeline(); + f.terminals.configureLaunchPipeline(p.value); + const wrapping = deferred(); + const release = f.gate(); + let plannedCleanups = 0; + const plan = f.terminals.planSpawn.bind(f.terminals); + f.terminals.planSpawn = (...args) => { + const result = plan(...args); + assert.ok(!("failure" in result)); + const cleanup = result.cleanup; + result.cleanup = () => { + plannedCleanups++; + cleanup(); + }; + return result; + }; + const registry = new EnvironmentRegistry({ + providers: () => [{ + pluginId: "fixture.env", + pluginName: "Environment", + serviceId: "env", + secrets: false, + kinds: [{ kind: "test", label: "Test", fields: [] }] + }], + call: async (_plugin, _service, method) => method.endsWith(".prepare") ? { ref: { id: "one" }, label: "Test" } : {}, + secret: async () => null + }); + registry.wrap = async (_environment, input) => { + wrapping.resolve(); + await release.promise; + if (outcome === "throw") throw new Error("fixture wrapper threw"); + if (outcome === "refusal") return { ok: false, reason: "fixture refused" }; + return { ok: true, ...input.launch, secrets: [] }; + }; + f.terminals.configureEnvironments(registry); + const session = f.create({ environment: { pluginId: "fixture.env", kind: "test" } }); + await wrapping.promise; + await stat(p.rows[0].file); + f.terminals.dispose(session.id); + assert.deepEqual(p.events, []); + + release.resolve(); + await f.drain(); + assert.equal(plannedCleanups, 1); + assert.equal(p.rows[0].cleanupCalls, 1); + assert.equal(f.calls.length, 0); + assert.deepEqual(p.events, ["child", "parent:start", "parent:done"]); + await assert.rejects(stat(join(f.runs, session.id)), { code: "ENOENT" }); + }); +} + +test("spawn refusal releases unadopted files and capabilities before eventual parent cleanup", { timeout: 5000 }, async (t) => { + const f = await fixture(t, { spawnFailure: true }); + const p = f.pipeline(); + f.terminals.configureLaunchPipeline(p.value); + let cleanups = 0; + const plan = f.terminals.planSpawn.bind(f.terminals); + f.terminals.planSpawn = (...args) => { + const result = plan(...args); + const cleanup = result.cleanup; + result.cleanup = () => { + cleanups++; + cleanup(); + }; + return result; + }; + const session = f.create(); + const internal = f.terminals.sessions.get(session.id); + await Promise.all([...internal.launchTasks]); + assert.equal(internal.metadata.status, "failed"); + assert.equal(cleanups, 1); + assert.equal(p.rows[0].cleanupCalls, 1); + assert.deepEqual(p.events, ["child"]); + + f.terminals.dispose(session.id); + await f.drain(); + assert.deepEqual(p.events, ["child", "parent:start", "parent:done"]); + await assert.rejects(stat(join(f.runs, session.id)), { code: "ENOENT" }); +}); + +test("a delayed close keeps the run files of a card brought back under the same id", { timeout: 5000 }, async (t) => { + const f = await fixture(t); + const p = f.pipeline({ holdForget: true }); + f.terminals.configureLaunchPipeline(p.value); + const session = f.create(); + const first = f.terminals.sessions.get(session.id); + await Promise.all([...first.launchTasks]); + assert.equal(f.calls.length, 1); + const record = persistedTerminalSession(first.metadata, first.threadId, first.extras); + const firstRun = p.rows[0].runDirectory; + + // Close the card; its folder removal is held, as a slow disk or a busy Windows file would hold it. + f.terminals.dispose(session.id); + await p.forgetStarted.promise; + + // The same card comes back (restore under its saved id) and prepares a new run before the old removal finishes. + await f.terminals.restoreSessionRecords([{ ...record, lastState: "running" }], "continue"); + const second = f.terminals.sessions.get(session.id); + assert.ok(second && second !== first); + await Promise.all([...(second.launchTasks ?? [])]); + assert.equal(p.rows.length, 2); + const secondRun = p.rows[1].runDirectory; + assert.notEqual(secondRun, firstRun); + + p.forgetRelease.resolve(); + await f.drain(); + await assert.rejects(stat(firstRun), { code: "ENOENT" }, "the closed card's own run folder is removed"); + await stat(p.rows[1].file); + assert.deepEqual(await readdir(join(f.runs, session.id)), [basename(secondRun)], "the newer card's run folder is kept"); +}); From b286d26d7861c1b5cf40d36768b89f62dbbecbe3 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 11:34:00 +0000 Subject: [PATCH 2/9] fix(main): run every shutdown step even when one fails If closing the Even G2 companion threw, quitting skipped terminalManager.shutdown(), so PTYs were not hung up and sessions were not saved. Shutdown now runs its steps in order through runShutdownSteps, which logs a failed step and continues. --- src/main/index.ts | 39 ++++++++------- src/main/services/shutdownSteps.ts | 13 +++++ tests/shutdown-steps.test.mjs | 76 ++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 16 deletions(-) create mode 100644 src/main/services/shutdownSteps.ts create mode 100644 tests/shutdown-steps.test.mjs diff --git a/src/main/index.ts b/src/main/index.ts index b9832dcee..da506ee4c 100644 --- a/src/main/index.ts +++ b/src/main/index.ts @@ -36,6 +36,7 @@ import { AgentChatHistoryService } from "./services/AgentChatHistoryService"; import { LimitsService, withoutAccountScope } from "./services/LimitsService"; import { UsageHistoryService } from "./services/UsageHistoryService"; import { LocalUsageCollector } from "./services/LocalUsageCollector"; +import { runShutdownSteps } from "./services/shutdownSteps"; import { createProviderCliRegistry, providerCliAvailability, @@ -1275,30 +1276,36 @@ void IPC.terminalData; async function shutdownServices(): Promise { diagnostics.record("info", "application", "shutdown.started"); - mascotManager?.dispose(); - agentChatHistory?.dispose(); - if (agentControl) await Promise.allSettled([agentControl.close()]); if (updateTimer) clearTimeout(updateTimer); if (updateInterval) clearInterval(updateInterval); for (const request of browserRequests.values()) { clearTimeout(request.timer); request.reject(new Error("App closing")); } browserRequests.clear(); - await evenG2?.close(); - if (terminalManager) await terminalManager.shutdown(); + // Each step runs even when an earlier one fails, so the terminals are always hung up and saved. + await runShutdownSteps([ + { name: "mascots", run: () => mascotManager?.dispose() }, + { name: "agent chat history", run: () => agentChatHistory?.dispose() }, + { name: "agent control", run: () => agentControl?.close() }, + { name: "Even G2", run: () => evenG2?.close() }, + { name: "terminal processes", run: async () => { if (terminalManager) await terminalManager.shutdown(); } } + ]); // The hung-up PTYs exit while the other services close; quitting waits for them (see waitForProcessExits). const ptyExits = terminalManager?.waitForProcessExits().then((left) => { if (left > 0) console.warn(`CanvasTTY quit with ${left} terminal process(es) that did not exit after SIGKILL.`); }); - // Stop the timer first, then abort in-flight limit requests so the final save is prompt. - const usageHistoryClosed = usageHistory?.dispose(); - limitsService?.dispose(); - await usageHistoryClosed; - if (agentGateway) await Promise.allSettled([agentGateway.close()]); - if (runtimeGateway) await Promise.allSettled([runtimeGateway.close()]); - if (browserService) await Promise.allSettled([browserService.dispose()]); - if (pluginServices) await Promise.allSettled([pluginServices.dispose()]); - if (pluginManager) await Promise.allSettled([pluginManager.dispose()]); - await handoffService?.dispose(); - if (materialService) await Promise.allSettled([materialService.dispose()]); + // Stop the usage-history timer first, then abort in-flight limit requests so its final save is prompt. + let usageHistoryClosed: Promise | undefined; + await runShutdownSteps([ + { name: "usage history", run: () => { usageHistoryClosed = usageHistory?.dispose(); } }, + { name: "limits", run: () => limitsService?.dispose() }, + { name: "usage history save", run: () => usageHistoryClosed }, + { name: "agent gateway", run: () => agentGateway?.close() }, + { name: "runtime gateway", run: () => runtimeGateway?.close() }, + { name: "browser", run: () => browserService?.dispose() }, + { name: "plugin services", run: () => pluginServices?.dispose() }, + { name: "plugins", run: () => pluginManager?.dispose() }, + { name: "handoff", run: () => handoffService?.dispose() }, + { name: "materials", run: () => materialService?.dispose() } + ]); await ptyExits; diagnostics.record("info", "application", "shutdown.completed"); await diagnostics.flush(); diff --git a/src/main/services/shutdownSteps.ts b/src/main/services/shutdownSteps.ts new file mode 100644 index 000000000..670249712 --- /dev/null +++ b/src/main/services/shutdownSteps.ts @@ -0,0 +1,13 @@ +export interface ShutdownStep { + name: string; + run(): void | Promise; +} + +/** Cleanup remains ordered, but one failed save must not skip independent services. */ +export async function runShutdownSteps(steps: readonly ShutdownStep[], + warn: (message: string, error: unknown) => void = console.warn): Promise { + for (const step of steps) { + try { await step.run(); } + catch (error) { warn(`CanvasTTY shutdown: ${step.name} failed.`, error); } + } +} diff --git a/tests/shutdown-steps.test.mjs b/tests/shutdown-steps.test.mjs new file mode 100644 index 000000000..fd0c46dd5 --- /dev/null +++ b/tests/shutdown-steps.test.mjs @@ -0,0 +1,76 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { runShutdownSteps } from "../src/main/services/shutdownSteps.ts"; + +test("a failed shutdown step does not skip the steps after it", async () => { + const calls = [], warnings = []; + const failure = new Error("fixture close failed"); + await assert.doesNotReject(runShutdownSteps([ + { name: "Even G2", run: async () => { calls.push("Even G2"); throw failure; } }, + { name: "sync step", run: () => { calls.push("sync step"); throw failure; } }, + ...["terminal processes", "browser", "plugin services", "plugins", "materials"].map(name => ({ name, run: async () => { calls.push(name); } })) + ], (message, error) => warnings.push({ message, error }))); + assert.deepEqual(calls, ["Even G2", "sync step", "terminal processes", "browser", "plugin services", "plugins", "materials"]); + assert.equal(warnings.length, 2); + assert.equal(warnings[0].error, failure); + assert.match(warnings[0].message, /Even G2 failed/u); +}); + +test("shutdown steps run in order and each waits for the previous one", async () => { + const events = []; + let release; + const held = new Promise(resolve => { release = resolve; }); + const done = runShutdownSteps([ + { name: "first", run: async () => { events.push("first:start"); await held; events.push("first:done"); } }, + { name: "second", run: () => { events.push("second"); } }, + { name: "absent service", run: () => undefined } + ], () => assert.fail("no step failed")); + await Promise.resolve(); + assert.deepEqual(events, ["first:start"]); + release(); + await done; + assert.deepEqual(events, ["first:start", "first:done", "second"]); +}); + +test("quitting still hangs up the terminals when the Even G2 companion fails to close", async () => { + const { readFile } = await import("node:fs/promises"); + const { stripTypeScriptTypes } = await import("node:module"); + const { runInNewContext } = await import("node:vm"); + const main = (await readFile(new URL("../src/main/index.ts", import.meta.url), "utf8")).replaceAll("\r\n", "\n"); + const start = main.indexOf("async function shutdownServices"); + const source = main.slice(start, main.indexOf("\n}\n", start) + 2); + const calls = []; + // The usage-history save finishes only after the limits service aborts its requests. + let limitsAborted; + const aborted = new Promise(resolve => { limitsAborted = resolve; }); + const service = (name, method, fail = false) => ({ [method]: async () => { calls.push(name); if (fail) throw new Error(`fixture ${name} failed`); } }); + const warn = console.warn; + console.warn = () => undefined; + try { + const shutdownServices = runInNewContext(`${stripTypeScriptTypes(source)}; shutdownServices`, { + runShutdownSteps, console, clearTimeout, clearInterval, Promise, Error, + diagnostics: { record: () => undefined, flush: async () => { calls.push("diagnostics"); } }, + mascotManager: { dispose: () => { calls.push("mascots"); } }, + agentChatHistory: { dispose: () => { calls.push("chat history"); } }, + agentControl: service("agent control", "close"), + updateTimer: null, updateInterval: null, browserRequests: new Map(), + evenG2: service("Even G2", "close", true), + terminalManager: { shutdown: async () => { calls.push("terminals"); }, waitForProcessExits: async () => 0 }, + usageHistory: { dispose: () => { calls.push("usage history"); return aborted.then(() => { calls.push("usage history saved"); }); } }, + limitsService: { dispose: () => { calls.push("limits"); limitsAborted(); } }, + agentGateway: service("agent gateway", "close"), + runtimeGateway: service("runtime gateway", "close"), + browserService: service("browser", "dispose"), + pluginServices: service("plugin services", "dispose"), + pluginManager: service("plugins", "dispose"), + handoffService: service("handoff", "dispose"), + materialService: service("materials", "dispose") + }); + await shutdownServices(); + } finally { + console.warn = warn; + } + assert.deepEqual(calls, ["mascots", "chat history", "agent control", "Even G2", "terminals", "usage history", "limits", + "usage history saved", "agent gateway", "runtime gateway", "browser", "plugin services", "plugins", "handoff", "materials", + "diagnostics"]); +}); From 9572d22827dc6451a8d168f5d78c4215eb1a1a8d Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 12:51:06 +0000 Subject: [PATCH 3/9] fix: report an agent killed by a signal as failed with exit 128+n node-pty reports a process killed by a signal as exitCode 0 plus the signal. The signal was dropped, so an agent killed with SIGKILL (OOM, kill -9) was recorded as "done, exit 0": wait_for_agent returned done, get_agent_result said done, and the saved session restored as exited. Record such an exit the way a shell does, as 128+signal (SIGKILL -> 137), mark the session failed, and put the signal name first in the failure details. Every reader of the exit (wait_for_agent, get_agent_result, the session store, the HOME failure summary) already derives its state from the exit code, so they now agree. Exits CanvasTTY causes itself (closing a card, quitting) are unaffected: those sessions are removed before the kill, and the exit handler ignores them. --- src/main/services/TerminalManager.ts | 22 ++++- tests/subagent-signal-exit.test.mjs | 118 +++++++++++++++++++++++++++ tests/terminal-lifecycle.test.mjs | 1 - 3 files changed, 136 insertions(+), 5 deletions(-) create mode 100644 tests/subagent-signal-exit.test.mjs diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index 3f3102470..af27d88cf 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -1,4 +1,5 @@ import { randomUUID } from "node:crypto"; +import { constants as osConstants } from "node:os"; import { realpathSync, statSync } from "node:fs"; import { basename, dirname } from "node:path"; import { isPathInside } from "../../agent-runtime/path-inside.mjs"; @@ -2166,29 +2167,36 @@ export class TerminalManager { let exited!: () => void; this.liveProcesses.set(process, new Promise((resolve) => { exited = resolve; })); - process.onExit(({ exitCode }) => { + process.onExit(({ exitCode, signal }) => { this.liveProcesses.delete(process); exited(); const current = this.sessions.get(id); if (!current || current !== session || current.process !== process) return; // node-pty calls this from a native callback that aborts the whole app when JavaScript throws in it. try { - this.recordExit(id, current, exitCode); + this.recordExit(id, current, exitCode, signal); } catch (error) { console.warn(`PTY ${id} exit could not be recorded.`, error); } }); } - private recordExit(id: string, current: ManagedSession, exitCode: number): void { + private recordExit(id: string, current: ManagedSession, reportedExitCode: number, signal?: number): void { this.flushOutput(id, current); this.releaseIsolation(id); if (current.extras.gitAuditSince !== undefined) void this.auditGit(id, current); + // node-pty reports a process killed by a signal as exitCode 0 plus the signal. That is a crash, not a clean finish: + // record it the way a shell does, as 128+signal, so the card, wait_for_agent and the saved session all say failed. + const killedBy = typeof signal === "number" && signal > 0 ? signal : 0; + const exitCode = killedBy ? 128 + killedBy : reportedExitCode; current.metadata.exitCode = exitCode; current.metadata.status = exitCode === 0 ? "done" : "failed"; - current.metadata.failureDetails = exitCode === 0 + const details = exitCode === 0 ? null : terminalFailureDetails(this.redactSecrets(current.bufferChunks.slice(current.bufferStart).join(""))); + current.metadata.failureDetails = killedBy + ? `${signalExitText(killedBy)}${details ? `\n${details}` : ""}`.slice(0, 8_000) + : details; current.agentBrowser?.cleanup(); current.agentBrowser = null; current.agentRuntime?.cleanup(); @@ -2521,3 +2529,9 @@ function appendScrollback(session: ManagedSession, data: string): void { session.bufferStart = 0; } } + +/** "The process was killed by signal SIGKILL (9)." from node-pty's signal number. */ +function signalExitText(signal: number): string { + const name = Object.entries(osConstants.signals).find(([, value]) => value === signal)?.[0]; + return `The process was killed by signal ${name ? `${name} (${signal})` : signal}.`; +} diff --git a/tests/subagent-signal-exit.test.mjs b/tests/subagent-signal-exit.test.mjs new file mode 100644 index 000000000..69229b143 --- /dev/null +++ b/tests/subagent-signal-exit.test.mjs @@ -0,0 +1,118 @@ +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { existsSync } from "node:fs"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { basename, join } from "node:path"; +import test from "node:test"; +import pty from "node-pty"; +import { AgentControlService } from "../src/main/services/AgentControlService.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { persistedTerminalSession } from "../src/main/services/TerminalSessionStore.ts"; +import { failureSummary } from "../src/renderer/src/features/home/failureSummary.ts"; +import { availableRegistry } from "./helpers/terminal.mjs"; + +// A subagent whose CLI was killed with SIGKILL showed "done, exit 0", so wait_for_agent reported a crash as success: +// node-pty reports a signal death as { exitCode: 0, signal: 9 }. These tests start real processes (inside sandbox-exec on macOS, as the +// isolation layer wraps an agent there) and kill them. + +const at = { x: 0, y: 0 }; +const SANDBOX = "/usr/bin/sandbox-exec"; +const wrapped = process.platform === "darwin" && existsSync(SANDBOX); +const skip = process.platform === "win32" ? "POSIX signals only" : false; + +/** Every launch becomes the given real command tree, wrapped in sandbox-exec where the isolation layer would. */ +function realSpawner(argv, spawned) { + return (_command, _args, options) => { + const [command, ...args] = wrapped ? [SANDBOX, "-p", "(version 1)(allow default)", ...argv] : argv; + const child = pty.spawn(command, args, { name: "xterm-256color", cols: 80, rows: 24, cwd: options.cwd, env: { PATH: "/usr/bin:/bin", HOME: options.cwd } }); + spawned.push(child); + return child; + }; +} + +async function setup(t, argv) { + const root = await mkdtemp(join(tmpdir(), "ctty-signal-exit-")); + const spawned = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, realSpawner(argv, spawned)); + t.after(async () => { + terminals.disposeAll(); + for (const child of spawned) { try { process.kill(child.pid, "SIGKILL"); } catch { /* exited */ } } + await rm(root, { recursive: true, force: true }); + }); + const control = new AgentControlService(terminals); + const orchestrator = terminals.create({ provider: "opencode", profile: "normal", cwd: root, position: at, role: "orchestrator" }); + return { root, spawned, terminals, control, orchestrator }; +} + +async function until(check, timeoutMs = 5_000) { + const deadline = Date.now() + timeoutMs; + while (Date.now() < deadline) { + const value = check(); + if (value) return value; + await new Promise((resolve) => setTimeout(resolve, 25)); + } + throw new Error("timed out"); +} + +const descendants = (pid) => { + try { return execFileSync("/usr/bin/pgrep", ["-P", String(pid)], { encoding: "utf8" }).trim().split("\n").filter(Boolean).map(Number); } catch { return []; } +}; + +test("a subagent whose CLI is killed by SIGKILL is failed (128+9) with the signal named, everywhere its exit is read", { skip }, async (t) => { + const s = await setup(t, ["/bin/sleep", "30"]); + const child = await s.control.spawn({ parentSessionId: s.orchestrator.id, provider: "opencode", cwd: s.root }); + const live = s.spawned.at(-1); + // sandbox-exec execs the CLI: the PTY's own process is the CLI, not a wrapper that could exit 0 after it. + // (node-pty's spawn-helper and then sandbox-exec exec in place first.) + // macOS reports an executable path; Linux ps reports only the command name. + const command = await until(() => { const comm = execFileSync("/bin/ps", ["-o", "comm=", "-p", String(live.pid)], { encoding: "utf8" }).trim(); return basename(comm) === "sleep" ? comm : null; }); + assert.equal(basename(command), "sleep"); + assert.deepEqual(descendants(live.pid), [], "no process below the CLI"); + process.kill(live.pid, "SIGKILL"); + const ended = await until(() => { const m = s.terminals.getMetadata(child.id); return m.exitCode !== null ? m : null; }); + assert.equal(ended.status, "failed"); + assert.equal(ended.exitCode, 137); + assert.match(ended.failureDetails, /killed by signal SIGKILL \(9\)/u); + // wait_for_agent and get_agent_result read the same exit. + const waited = await s.control.waitFor(child.id, { timeoutMs: 1_000 }); + assert.equal(waited.reason, "failed"); + assert.equal(waited.status, "failed"); + assert.equal(waited.exitCode, 137); + const result = s.control.result(child.id); + assert.equal(result.state, "failed"); + assert.equal(result.exitCode, 137); + // The saved session restores as failed, and HOME's failure summary shows the exit code with the signal line. + const saved = persistedTerminalSession(ended); + assert.equal(saved.lastState, "failed"); + assert.equal(saved.exitCode, 137); + const summary = failureSummary(ended, "en"); + assert.match(summary.headline, /137/u); + assert.match(summary.diagnostics, /^The process was killed by signal SIGKILL \(9\)\./u); +}); + +test("a wrapper shell whose CLI child is killed reports the signal as a non-zero exit: the subagent is failed", { skip }, async (t) => { + const s = await setup(t, ["/bin/sh", "-c", "/bin/sleep 30; exit $?"]); + const child = await s.control.spawn({ parentSessionId: s.orchestrator.id, provider: "opencode", cwd: s.root }); + const shell = s.spawned.at(-1); + const cli = await until(() => descendants(shell.pid)[0]); + process.kill(cli, "SIGKILL"); + const ended = await until(() => { const m = s.terminals.getMetadata(child.id); return m.exitCode !== null ? m : null; }); + assert.equal(ended.status, "failed"); + assert.equal(ended.exitCode, 137); + // The shell exited normally with 137: no signal reached node-pty, so nothing is named. + assert.doesNotMatch(ended.failureDetails ?? "", /killed by signal/u); + assert.equal((await s.control.waitFor(child.id, { timeoutMs: 1_000 })).reason, "failed"); +}); + +test("a clean exit stays done", { skip }, async (t) => { + const s = await setup(t, ["/usr/bin/true"]); + const child = await s.control.spawn({ parentSessionId: s.orchestrator.id, provider: "opencode", cwd: s.root }); + const ended = await until(() => { const m = s.terminals.getMetadata(child.id); return m.exitCode !== null ? m : null; }); + assert.equal(ended.status, "done"); + assert.equal(ended.exitCode, 0); + assert.equal(ended.failureDetails, null); + assert.equal((await s.control.waitFor(child.id, { timeoutMs: 1_000 })).reason, "done"); + assert.equal(s.control.result(child.id).state, "done"); + assert.equal(persistedTerminalSession(ended).lastState, "exited"); +}); diff --git a/tests/terminal-lifecycle.test.mjs b/tests/terminal-lifecycle.test.mjs index 8ca7f9c16..c1e7c124e 100644 --- a/tests/terminal-lifecycle.test.mjs +++ b/tests/terminal-lifecycle.test.mjs @@ -377,7 +377,6 @@ test("failed PTYs preserve their final sanitized output as failure details", asy // Masked whole before the last lines are chosen (a cut inside a secret would leave its tail readable). assert.match(source, /terminalFailureDetails\(this\.redactSecrets\(current\.bufferChunks\.slice\(current\.bufferStart\)\.join\(""\)\)\)/); - assert.match(source, /current\.metadata\.failureDetails = exitCode === 0/); }); function effectDependenciesContaining(source, marker) { From dfb9a2a9d84f9971ada48467f83c0ed6c7a13336 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 13:01:34 +0000 Subject: [PATCH 4/9] fix(orchestration): keep the orchestrator's model choice for subagents A subagent spawned without launch options ran on its CLI's own default model and sign-in (for OpenCode the hosted OpenCode Zen model), even when its orchestrator ran on a model the person picked through a plugin's launch options. A plugin the spawn does not name now keeps the orchestrator's own values for a subagent of the same CLI; repeating the person's choice needs no delegable declaration, and then the normalized values must equal the orchestrator's exactly (missing keys come from the orchestrator, never from the plugin's defaults). A subagent of another CLI must name a plugin whose contribution set the orchestrator's model, and spawn_agent reports servedBy (CLI, requested model, inherited or explicit options). - Recognise every form a CLI takes for its model: --model and --model=, -m and -mX for OpenCode, Codex, Qwen, Kimi and Grok, and for Codex also --profile/-p and -c/--config setting model, model_provider or profile. - Refuse a second model (an explicit model next to a plugin that sets it, or two plugins that both set it; OpenCode crashes at start on two --model values) only for a subagent's launch. A person's own launches and restores start as before. - Inherit an empty choice (a plugin without fields) as chosen. Leave out an inherited plugin that was turned off since, unless it set the model (then refuse); refuse with a clear reason when its fields changed. - Reset modelSetBy at the start of each launch. - Describe inheritance, servedBy and the refusals in the orchestrator skill and docs. The core stays plugin-agnostic: it reads the plugin from the launch options and the contribution, never from a fixed plugin id. --- agent/orchestrator/SKILL.md | 2 +- docs/agent-orchestration.md | 4 +- docs/plugins.md | 2 +- native/canvastty-helper/catalog.json | 2 +- src/agent-browser/orchestration-catalog.mjs | 2 +- src/main/services/AgentControlService.ts | 53 +++ src/main/services/LaunchPipeline.ts | 163 +++++++-- src/main/services/TerminalManager.ts | 34 +- .../agent-browser/OrchestrationTools.ts | 16 +- tests/orchestration-gateway.test.mjs | 1 + tests/plugin-launch-choices.test.mjs | 4 +- tests/subagent-model-account.test.mjs | 312 ++++++++++++++++++ 12 files changed, 555 insertions(+), 40 deletions(-) create mode 100644 tests/subagent-model-account.test.mjs diff --git a/agent/orchestrator/SKILL.md b/agent/orchestrator/SKILL.md index 1b68bdb22..bf67517c7 100644 --- a/agent/orchestrator/SKILL.md +++ b/agent/orchestrator/SKILL.md @@ -10,7 +10,7 @@ description: Create and coordinate native agent sessions (Codex, Claude, Qwen, K A session started from CanvasTTY's launcher with the **Orchestrator** role has the `canvastty_agents` MCP tools. Use them in this order: 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. +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` a subagent of your own CLI keeps your plugin launch options (for example your model account), and any other CLI uses its own default. A plugin you do not name in `launchOptions` keeps your own values; passing `model` next to inherited options that already set the model is refused, and a subagent of another CLI is refused while your model comes from a plugin's options (spawn one of your own CLI instead). The answer's `servedBy` names the CLI, the model asked for, and whether each plugin's options were `inherited` or `explicit`. `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. 4. `get_agent_result` to read what the subagent produced; check the actual files before reporting success. diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index 0e8b6e3f4..3b380d2c1 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -9,7 +9,7 @@ A session launched from the desktop with the **Orchestrator** role gets the `can | Tool | What it does | | --- | --- | | `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`. | +| `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`. Plugin launch options the call does not name are inherited from the orchestrator for a subagent of the same CLI (see Plugin launch options below); `model` next to inherited options that set the model is refused, and so is a subagent of another CLI while the orchestrator's model comes from a plugin's options. The answer's `servedBy` is `{ provider, model, launchOptions: { : "inherited" | "explicit" } }`. 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. | | `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. | @@ -45,7 +45,7 @@ The core applies these to every way an agent can start another one: `spawn_agent | Profile ceiling | A subagent's profile is at most its orchestrator's, never YOLO. A saved subagent whose record says more is restored with its orchestrator's ceiling. | | Project folder | A subagent's `cwd` must be the folder the person chose for the agent it descends from, or a folder inside it, compared as real paths in both Unicode spellings (NFC and NFD name the same folder on macOS). `/`, the home folder or another project is refused: "A subagent works only inside this project's folder …". A relative `cwd` is taken from the orchestrator's folder. | | Limits | At most `orchestrationMaxDepth` levels of subagents below the agent the person started (2 by default) and `orchestrationMaxSubagents` live subagents in one orchestration, all levels together (8 by default). Only the person sets them, in Settings → Agents. Exited subagents do not count. | -| Plugin launch options | `launchOptions` from an orchestrator reach only plugins that declared `launch.delegable: true`; everything a plugin contributes still passes the core-owned flag and configuration checks (no permission, sandbox, hook or bypass flags, no OpenCode/Kimi configuration that sets approvals). | +| Plugin launch options | `launchOptions` from an orchestrator reach only plugins that declared `launch.delegable: true` (a plugin the spawn does not name keeps the orchestrator's own values for a subagent of the same CLI; repeating them needs no declaration; a plugin turned off since is left out, or refused when it set the model; changed plugin fields refuse with that reason); everything a plugin contributes still passes the core-owned flag and configuration checks (no permission, sandbox, hook or bypass flags, no OpenCode/Kimi configuration that sets approvals). | | YOLO | Enforced in the main process: only for a CLI the person acknowledged YOLO for in the launcher, never for a subagent, never from an orchestrator's control connection; a plugin with `sessions:launch` needs the same acknowledgement. | | Isolation | Every subagent and every agent a plugin starts runs inside agent isolation (below) when it is on; where there is no layer, a subagent runs in normal (it asks) and its card says why. | | No settings | The `canvastty_agents` tools and an orchestrator's control connection cannot change settings, base protection, profiles, plugin trust or isolation. | diff --git a/docs/plugins.md b/docs/plugins.md index 0047ad17b..a93611a09 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -196,7 +196,7 @@ Up to 8 fields; `kind` is `boolean`, `select` (1–16 options) or `text` (at mos A `select` with `"optionsFrom": "service"` also lists choices the service offers, such as its own accounts. When the launcher opens, CanvasTTY asks the service `canvastty.launch.options` `{ provider, fields: [keys] }` and waits at most 3 s; the answer `{ "": [{ value, label }] }` adds up to 64 choices per field after the declared ones (which stay required and are all the launcher shows when the service does not answer). Because such a list can change after a card was saved, its value is accepted as any text up to 200 characters without control characters, and `canvastty.launch.prepare` must check it and refuse a value it no longer knows. -Orchestrators pass the same values to `spawn_agent` as `launchOptions` (`{ "": { "": value } }`), checked exactly like the launcher's, but only to a plugin whose `launch` declares `"delegable": true` (its options are safe for an agent to choose; without it only the person chooses them, and `list_providers` does not list them); a plugin tool can hand them out (for example the account it picked). Whatever a contribution adds is checked the same way for every launch: no permission, sandbox, hook or bypass flags, and no configuration the CLI reads that sets approvals (an OpenCode `OPENCODE_CONFIG` file or `OPENCODE_CONFIG_DIR`, `OPENCODE_PERMISSION`, Kimi's `--config`/`--config-file`); a file CanvasTTY cannot read and check is refused. While a child's launch waits for its plugins (launch options, a launch policy, an environment), `spawn_agent` answers only after its `prompt` reached the started agent, and `send_to_agent` waits the same way. A refused, failed or cancelled launch fails the call with the reason and the session id (the card stays); the text is dropped, never kept for a later restart. The control CLI answers `NOT_READY` for such a card. +Orchestrators pass the same values to `spawn_agent` as `launchOptions` (`{ "": { "": value } }`), checked exactly like the launcher's, but only to a plugin whose `launch` declares `"delegable": true` (its options are safe for an agent to choose; without it only the person chooses them, and `list_providers` does not list them); a plugin tool can hand them out (for example the account it picked). A plugin the spawn does not name keeps the orchestrator's own values for a subagent of the same CLI (the person chose them; this needs no `delegable`), so a subagent never falls back silently to its CLI's default model; a subagent of another CLI is refused while a plugin's contribution sets the orchestrator's model (its CLI model argument or `thirdPartyModel`) unless the spawn names that plugin, and `spawn_agent` answers with `servedBy` (CLI, requested model, and whether each plugin's options were inherited or explicit). An inherited plugin that was turned off since the orchestrator started is left out, unless it set the model (then the spawn is refused); one whose fields changed refuses the spawn with that reason. For a subagent's launch, a contribution that chooses the model (`--model`/`--model=`, `-m` for OpenCode, Codex, Qwen, Kimi and Grok, and for Codex also `--profile`/`-p` and `-c`/`--config` setting `model`, `model_provider` or `profile`) refuses a launch that also asks for a model, and two contributions that both set the model are refused, instead of starting the CLI with two. A person's own launches and restores start as before. Whatever a contribution adds is checked the same way for every launch: no permission, sandbox, hook or bypass flags, and no configuration the CLI reads that sets approvals (an OpenCode `OPENCODE_CONFIG` file or `OPENCODE_CONFIG_DIR`, `OPENCODE_PERMISSION`, Kimi's `--config`/`--config-file`); a file CanvasTTY cannot read and check is refused. While a child's launch waits for its plugins (launch options, a launch policy, an environment), `spawn_agent` answers only after its `prompt` reached the started agent, and `send_to_agent` waits the same way. A refused, failed or cancelled launch fails the call with the reason and the session id (the card stays); the text is dropped, never kept for a later restart. The control CLI answers `NOT_READY` for such a card. Before the agent starts, the host sends the service a `canvastty.launch.prepare` request, which surfaces cannot send: diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index d3ec39a27..4622e41c8 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -964,7 +964,7 @@ }, { "name": "spawn_agent", - "description": "Launch another provider's agent as a CanvasTTY subagent of this session and optionally deliver a first prompt. Returns the new session id. provider must be an id from list_providers (known ids: codex, claude, qwen, kimi, opencode, hermes, grok, omp, pi, cursor, minimax, devin, antigravity); call list_providers first to see which are installed and signed in. Give each subagent one self-contained part of the task and an absolute cwd. If the person names a model, pass it as model in the format list_providers gives for that provider (OpenCode: provider/model); effort sets the reasoning effort where that CLI has one (list_providers shows its efforts). An unsupported model or effort is refused with the reason. profile: without it the subagent gets this session's launch profile, or the next lower one its CLI has; a subagent never gets more than this session (plan < normal < acceptEdits < auto) and never YOLO. \"auto\" lets it work without asking the person for each edit or command inside the project; CanvasTTY's outer layers (agent isolation, base protection) still stop writes outside the project, secrets and system changes. The answer says the profile it got. cwd must be this project's folder or a folder inside it. launchOptions passes plugin launch options exactly as a plugin tool gives them (for example the account a plugin picked), for plugins that allow an orchestrator to choose them. Refusals say why (a limit the person set, a folder outside the project, a profile above this session's): change the request instead of retrying it. Then call wait_for_agent and get_agent_result.", + "description": "Launch another provider's agent as a CanvasTTY subagent of this session and optionally deliver a first prompt. Returns the new session id. provider must be an id from list_providers (known ids: codex, claude, qwen, kimi, opencode, hermes, grok, omp, pi, cursor, minimax, devin, antigravity); call list_providers first to see which are installed and signed in. Give each subagent one self-contained part of the task and an absolute cwd. If the person names a model, pass it as model in the format list_providers gives for that provider (OpenCode: provider/model); effort sets the reasoning effort where that CLI has one (list_providers shows its efforts). An unsupported model or effort is refused with the reason. profile: without it the subagent gets this session's launch profile, or the next lower one its CLI has; a subagent never gets more than this session (plan < normal < acceptEdits < auto) and never YOLO. \"auto\" lets it work without asking the person for each edit or command inside the project; CanvasTTY's outer layers (agent isolation, base protection) still stop writes outside the project, secrets and system changes. The answer says the profile it got. cwd must be this project's folder or a folder inside it. launchOptions passes plugin launch options exactly as a plugin tool gives them (for example the account a plugin picked), for plugins that allow an orchestrator to choose them. A plugin this call does not name keeps this session's own launch options (for example its model account), so the subagent never falls back silently to its CLI's default model; a subagent of another CLI is refused while this session's model comes from a plugin's options (spawn one of this CLI instead), and model next to inherited options that set the model is refused. The answer's servedBy says which CLI and requested model serve it and where each plugin's options came from. Refusals say why (a limit the person set, a folder outside the project, a profile above this session's): change the request instead of retrying it. Then call wait_for_agent and get_agent_result.", "inputSchema": { "type": "object", "properties": { diff --git a/src/agent-browser/orchestration-catalog.mjs b/src/agent-browser/orchestration-catalog.mjs index ad7b53d22..e48ea3de6 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -58,7 +58,7 @@ export const ORCHESTRATION_TOOL_DEFINITIONS = Object.freeze([ ), tool( "spawn_agent", - `Launch another provider's agent as a CanvasTTY subagent of this session and optionally deliver a first prompt. Returns the new session id. provider must be an id from list_providers (known ids: ${AGENT_PROVIDER_IDS.join(", ")}); call list_providers first to see which are installed and signed in. Give each subagent one self-contained part of the task and an absolute cwd. If the person names a model, pass it as model in the format list_providers gives for that provider (OpenCode: provider/model); effort sets the reasoning effort where that CLI has one (list_providers shows its efforts). An unsupported model or effort is refused with the reason. profile: without it the subagent gets this session's launch profile, or the next lower one its CLI has; a subagent never gets more than this session (plan < normal < acceptEdits < auto) and never YOLO. "auto" lets it work without asking the person for each edit or command inside the project; CanvasTTY's outer layers (agent isolation, base protection) still stop writes outside the project, secrets and system changes. The answer says the profile it got. cwd must be this project's folder or a folder inside it. launchOptions passes plugin launch options exactly as a plugin tool gives them (for example the account a plugin picked), for plugins that allow an orchestrator to choose them. Refusals say why (a limit the person set, a folder outside the project, a profile above this session's): change the request instead of retrying it. Then call wait_for_agent and get_agent_result.`, + `Launch another provider's agent as a CanvasTTY subagent of this session and optionally deliver a first prompt. Returns the new session id. provider must be an id from list_providers (known ids: ${AGENT_PROVIDER_IDS.join(", ")}); call list_providers first to see which are installed and signed in. Give each subagent one self-contained part of the task and an absolute cwd. If the person names a model, pass it as model in the format list_providers gives for that provider (OpenCode: provider/model); effort sets the reasoning effort where that CLI has one (list_providers shows its efforts). An unsupported model or effort is refused with the reason. profile: without it the subagent gets this session's launch profile, or the next lower one its CLI has; a subagent never gets more than this session (plan < normal < acceptEdits < auto) and never YOLO. "auto" lets it work without asking the person for each edit or command inside the project; CanvasTTY's outer layers (agent isolation, base protection) still stop writes outside the project, secrets and system changes. The answer says the profile it got. cwd must be this project's folder or a folder inside it. launchOptions passes plugin launch options exactly as a plugin tool gives them (for example the account a plugin picked), for plugins that allow an orchestrator to choose them. A plugin this call does not name keeps this session's own launch options (for example its model account), so the subagent never falls back silently to its CLI's default model; a subagent of another CLI is refused while this session's model comes from a plugin's options (spawn one of this CLI instead), and model next to inherited options that set the model is refused. The answer's servedBy says which CLI and requested model serve it and where each plugin's options came from. Refusals say why (a limit the person set, a folder outside the project, a profile above this session's): change the request instead of retrying it. Then call wait_for_agent and get_agent_result.`, { provider, cwd: string({ minLength: 1, maxLength: 4_096 }), diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index 3b35fa78a..c44bbc4eb 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -151,6 +151,8 @@ export class AgentControlService { const capabilities = PROVIDER_CAPABILITIES[request.provider]; if (!capabilities) throw new Error("Unknown agent provider."); if (!capabilities.send) throw new Error(`${request.provider} cannot receive prompts.`); + const inheritance = this.subagentLaunchOptions(parent.id, request.provider, request.launchOptions, request.model); + if (inheritance.launchOptions !== request.launchOptions) request = { ...request, launchOptions: inheritance.launchOptions }; const children = this.children(parent.id); if (children.length >= MAX_CHILDREN_PER_PARENT) { @@ -200,6 +202,57 @@ export class AgentControlService { }); } + /** + * The plugin launch options a subagent of this parent starts with. A plugin the spawn does not name keeps the + * orchestrator's own values, which the person chose: a subagent never falls back silently to its CLI's default model + * and sign-in (for OpenCode that is OpenCode Zen, a third-party service) while its orchestrator runs on a model the + * person picked through a plugin. Naming a plugin is an explicit choice (checked by the launch: another value needs + * the plugin's delegable declaration). Another CLI cannot inherit a plugin choice that set the orchestrator's model, + * and is refused unless the spawn names that plugin. An explicit model next to an inherited choice that sets the model is refused. + */ + subagentLaunchOptions( + parentSessionId: string, + provider: AgentProviderId, + requested: SpawnAgentRequest["launchOptions"], + model?: string + ): { launchOptions: SpawnAgentRequest["launchOptions"]; sources: Record } { + const parent = this.requireSession(parentSessionId); + const sources: Record = {}; + for (const pluginId of Object.keys(requested ?? {})) sources[pluginId] = "explicit"; + const parentOptions = this.terminals.launchOptionsOf(parent.id); + const unnamed = Object.keys(parentOptions ?? {}).filter((pluginId) => !Object.hasOwn(sources, pluginId)); + if (!parentOptions || unnamed.length === 0) return { launchOptions: requested, sources }; + const modelSetBy = new Set(this.terminals.modelSetByOf(parent.id)); + const modelPlugins = unnamed.filter((pluginId) => modelSetBy.has(pluginId)); + if (parent.provider !== provider) { + if (modelPlugins.length === 0) return { launchOptions: requested, sources }; + const named = modelPlugins.map((pluginId) => pluginId.slice(0, 80)).join(", "); + // The person chose those options for this CLI; another CLI would run on its own default model and sign-in. + throw new DelegationRefusal(`This orchestrator's model is set by its ${named} launch options, which the person chose for ${parent.provider}; ` + + `a ${provider} subagent would not get that model. Spawn a ${parent.provider} subagent instead.`); + } + if (model !== undefined && modelPlugins.length > 0) { + const named = modelPlugins.map((pluginId) => pluginId.slice(0, 80)).join(", "); + throw new DelegationRefusal(`This subagent inherits its orchestrator's ${named} launch options, which set its model; it cannot also take model ${model.slice(0, 80)}. ` + + `Omit model, or pass launchOptions for ${named} that choose the model you want.`); + } + // A plugin turned off since the orchestrator started is left out, unless it set the model: then the subagent would + // run on its CLI's own default model and sign-in, so it is refused instead. + const gone = new Set(this.terminals.unavailableLaunchPlugins(Object.fromEntries(unnamed.map((pluginId) => [pluginId, parentOptions[pluginId]])))); + const goneModel = modelPlugins.filter((pluginId) => gone.has(pluginId)); + if (goneModel.length > 0) { + const named = goneModel.map((pluginId) => pluginId.slice(0, 80)).join(", "); + throw new DelegationRefusal(`This orchestrator's model is set by its ${named} launch options, and ${named} is now disabled, removed or not trusted; ` + + "a subagent would run on its CLI's own default model instead. The person can turn the plugin back on, or start the orchestrator again."); + } + const launchOptions: NonNullable = { ...(requested ?? {}) }; + for (const pluginId of unnamed.filter((id) => !gone.has(id))) { + launchOptions[pluginId] = parentOptions[pluginId]!; + sources[pluginId] = "inherited"; + } + return { launchOptions, sources }; + } + /** The profile a subagent of this parent gets for this request (what spawn will use), or why it gets none. */ profileFor(parentSessionId: string, provider: AgentProviderId, requested?: unknown): { profile: LaunchProfile; inherited: boolean } | { error: string } { return subagentProfile(this.requireSession(parentSessionId).profile, provider, requested, this.containment()); diff --git a/src/main/services/LaunchPipeline.ts b/src/main/services/LaunchPipeline.ts index f6adc53e5..b992e7292 100644 --- a/src/main/services/LaunchPipeline.ts +++ b/src/main/services/LaunchPipeline.ts @@ -73,6 +73,8 @@ export type PreparedLaunch = envSources: Record; /** A contributor runs the agent on another model than its vendor's: "auto" becomes accept-edits. */ thirdPartyModel: boolean; + /** Plugin ids whose contribution decides the model: it passes the CLI's model flag or runs a third-party model. */ + modelSetBy: string[]; /** This run's own folder below the card's folder; `cleanup` removes it. */ runDirectory: string; cleanup(): Promise; @@ -163,45 +165,45 @@ export class LaunchPipeline { * Checks launcher values against each plugin's declared fields and fills defaults. * Throws with a person-readable reason; returns undefined when nothing was chosen. */ - normalizeOptions(provider: ProviderId, candidate: unknown, context?: { delegated?: boolean }): Record | undefined { + normalizeOptions(provider: ProviderId, candidate: unknown, context?: { + delegated?: boolean; + /** The orchestrator's own options: repeating them for its subagent is the person's choice, not the orchestrator's. */ + inherited?: Readonly>>; + }): Record | undefined { if (candidate === undefined) return undefined; if (!isRecord(candidate) || Object.keys(candidate).length > MAX_OPTION_PLUGINS) throw new Error("Launch options are invalid."); if (Object.keys(candidate).length === 0) return undefined; if (provider === "terminal") throw new Error("A plain terminal takes no launch options."); const contributors = new Map(this.dependencies.contributors().map((contributor) => [contributor.pluginId, contributor])); const options: Record = {}; - for (const [pluginId, raw] of Object.entries(candidate)) { + for (const [pluginId, requested] of Object.entries(candidate)) { + let raw = requested; const contributor = contributors.get(pluginId); if (!contributor) throw new Error(unavailableReason(pluginId)); // An orchestrator picks options for its subagents only where the plugin said that is safe. + const notDelegable = `${contributor.pluginName} has not declared its launch options safe for an orchestrator to choose; only the person chooses them, in the launcher.`; + // Without the declaration a subagent may only repeat the orchestrator's own values: the keys it leaves out are + // the inherited ones, never the plugin's defaults, and the result is checked against them below. + const inherited = context?.delegated && contributor.launch.delegable !== true ? context.inherited?.[pluginId] : undefined; if (context?.delegated && contributor.launch.delegable !== true) { - throw new LaunchRefusal(`${contributor.pluginName} has not declared its launch options safe for an orchestrator to choose; only the person chooses them, in the launcher.`); + if (!inherited || !sameAsInherited(raw, inherited)) throw new LaunchRefusal(notDelegable); + raw = { ...inherited, ...(raw as Record) }; } - const { appliesTo, fields } = contributor.launch; - if (appliesTo && !appliesTo.includes(provider as never)) { - throw new Error(`${contributor.pluginName} launch options do not apply to ${provider}.`); + if (!inherited) { + options[pluginId] = launchValues(contributor, provider, raw); + continue; } - if (!isRecord(raw)) throw new Error(`${contributor.pluginName} launch options are invalid.`); - const known = new Set(fields.map((field) => field.key)); - const unknown = Object.keys(raw).find((key) => !known.has(key)); - if (unknown) throw new Error(`${contributor.pluginName} has no launch option ${unknown.slice(0, 40)}.`); - const values: PluginLaunchValues = {}; - for (const field of fields) { - const value = raw[field.key] ?? field.default - ?? (field.kind === "boolean" ? false : field.kind === "select" ? field.options?.[0]?.value ?? "" : ""); - const plainText = (limit: number): boolean => typeof value === "string" && value.length <= limit && !/[\u0000-\u001f\u007f]/.test(value); - // A service-provided choice may have changed since the launcher showed it: the service checks it when it prepares. - const valid = field.kind === "boolean" - ? typeof value === "boolean" - : field.kind === "select" - ? typeof value === "string" && (Boolean(field.options?.some((option) => option.value === value)) || (field.optionsFrom === "service" && plainText(200))) - : plainText(field.maxLength ?? 200); - if (!valid) throw new Error(`${contributor.pluginName} launch option ${field.label} is invalid.`); - values[field.key] = value as boolean | string; - } - if (Buffer.byteLength(JSON.stringify(values), "utf8") > MAX_PLUGIN_SLOT_BYTES) { - throw new Error(`${contributor.pluginName} launch options exceed 4 KB.`); + // The person's earlier choice no longer fits the plugin (it changed its fields or what it applies to): a subagent + // never gets other values than its orchestrator's, so it is refused with that reason. + const changed = `${contributor.pluginName} launch options changed since this orchestrator started, so its subagents cannot repeat the person's choice. ` + + "The person can start the orchestrator again with the new options."; + let values: PluginLaunchValues; + try { + values = launchValues(contributor, provider, raw); + } catch { + throw new LaunchRefusal(changed); } + if (!sameValues(values, inherited)) throw new LaunchRefusal(changed); options[pluginId] = values; } return options; @@ -257,8 +259,10 @@ export class LaunchPipeline { * refuses the whole launch with a reason; nothing is ever launched without a contribution the person selected, * or past a policy that did not answer. */ - async prepare(context: LaunchSessionContext): Promise { + async prepare(context: LaunchSessionContext, launch: { model?: string } = {}): Promise { const contributors = new Map(this.dependencies.contributors().map((contributor) => [contributor.pluginId, contributor])); + // Only a subagent's launch is refused for a second model; it was chosen for it, not by the person. + const delegated = context.role === "subagent"; const selected = Object.keys(context.options).sort(); for (const pluginId of selected) { if (!contributors.has(pluginId)) return { ok: false, reason: unavailableReason(pluginId) }; @@ -285,6 +289,7 @@ export class LaunchPipeline { const args: string[] = []; const secrets: string[] = []; let thirdPartyModel = false; + const modelSetBy: string[] = []; for (const answer of answers) { if ("refuse" in answer) return refuse(answer.refuse); } @@ -303,6 +308,19 @@ export class LaunchPipeline { } const forbidden = contributedArgs.find((argument) => coreOwnedLaunchArgument(context.provider, argument)); if (forbidden) return refuse(`${name} added ${forbidden.slice(0, 60)}, which only CanvasTTY may pass.`); + const modelFlag = modelSettingArgument(context.provider, contributedArgs); + if (modelFlag !== undefined || contribution.thirdPartyModel === true) { + // A subagent's CLI gets one model: a second model flag next to the launch's own made OpenCode crash at start. + // A person's own launches (and their restores) start as they always did; the person chose both. + if (delegated && modelFlag !== undefined && launch.model !== undefined) { + return refuse(`${name} sets the model of this launch, and the launch also asks for model ${launch.model.slice(0, 80)}. Omit the model, or choose ${name} options for the model you want.`); + } + if (delegated && modelSetBy.length > 0) { + const first = contributors.get(modelSetBy[0]!)?.pluginName ?? modelSetBy[0]!; + return refuse(`${first} and ${name} both set the model of this launch; choose launch options from only one of them.`); + } + modelSetBy.push(contributor.pluginId); + } // A configuration a CLI reads from the environment or an argument may not decide its approvals either. const widening = permissionConfigProblem(context.provider, contribution, context.cwd); if (widening) return refuse(`${name} ${widening}`); @@ -345,7 +363,7 @@ export class LaunchPipeline { args.push(...contributedArgs.map(expand)); thirdPartyModel ||= contribution.thirdPartyModel === true; } - return { ok: true, env, args, secrets, envSources, thirdPartyModel, runDirectory, cleanup }; + return { ok: true, env, args, secrets, envSources, thirdPartyModel, modelSetBy, runDirectory, cleanup }; } private async ask( @@ -604,3 +622,92 @@ export function errorText(error: unknown): string { export function isRecord(value: unknown): value is Record { return Boolean(value && typeof value === "object" && !Array.isArray(value)); } + +/** A plugin's launch values checked against its declared fields, with defaults filled in. Throws with a person-readable reason. */ +function launchValues(contributor: LaunchContributor, provider: ProviderId, raw: unknown): PluginLaunchValues { + const { appliesTo, fields } = contributor.launch; + if (appliesTo && !appliesTo.includes(provider as never)) { + throw new Error(`${contributor.pluginName} launch options do not apply to ${provider}.`); + } + if (!isRecord(raw)) throw new Error(`${contributor.pluginName} launch options are invalid.`); + const known = new Set(fields.map((field) => field.key)); + const unknown = Object.keys(raw).find((key) => !known.has(key)); + if (unknown) throw new Error(`${contributor.pluginName} has no launch option ${unknown.slice(0, 40)}.`); + const values: PluginLaunchValues = {}; + for (const field of fields) { + const value = raw[field.key] ?? field.default + ?? (field.kind === "boolean" ? false : field.kind === "select" ? field.options?.[0]?.value ?? "" : ""); + const plainText = (limit: number): boolean => typeof value === "string" && value.length <= limit && !/[\u0000-\u001f\u007f]/.test(value); + // A service-provided choice may have changed since the launcher showed it: the service checks it when it prepares. + const valid = field.kind === "boolean" + ? typeof value === "boolean" + : field.kind === "select" + ? typeof value === "string" && (Boolean(field.options?.some((option) => option.value === value)) || (field.optionsFrom === "service" && plainText(200))) + : plainText(field.maxLength ?? 200); + if (!valid) throw new Error(`${contributor.pluginName} launch option ${field.label} is invalid.`); + values[field.key] = value as boolean | string; + } + if (Buffer.byteLength(JSON.stringify(values), "utf8") > MAX_PLUGIN_SLOT_BYTES) { + throw new Error(`${contributor.pluginName} launch options exceed 4 KB.`); + } + return values; +} + +/** The orchestrator's own choice repeated for its subagent: only keys it chose, each with the same value. */ +function sameAsInherited(raw: unknown, inherited: Readonly | undefined): boolean { + if (!inherited || !isRecord(raw)) return false; + const keys = Object.keys(raw); + // An empty choice repeats only an empty one (a plugin without fields, chosen in the launcher). + if (keys.length === 0) return Object.keys(inherited).length === 0; + return keys.every((key) => Object.hasOwn(inherited, key) && inherited[key] === raw[key]); +} + +/** Exactly the same keys and values. */ +function sameValues(values: Readonly, inherited: Readonly): boolean { + const keys = Object.keys(values); + return keys.length === Object.keys(inherited).length + && keys.every((key) => Object.hasOwn(inherited, key) && inherited[key] === values[key]); +} + +/** + * How each CLI's arguments choose its model. Every CLI here takes `--model`; `short` are its short model flags, + * `profile` flags that select a configuration profile (which may name a model), and `config` flags that set a + * configuration key, with the keys that decide the model. + */ +const MODEL_ARGUMENTS: Readonly>> = { + codex: { short: ["-m"], profile: ["--profile", "-p"], config: { flags: ["-c", "--config"], keys: ["model", "model_provider", "profile"] } }, + opencode: { short: ["-m"] }, + qwen: { short: ["-m"] }, + kimi: { short: ["-m"] }, + grok: { short: ["-m"] } +}; + +/** + * The first argument that chooses the CLI's model, in any form: `--model x`, `--model=x`, a short `-m x` or `-mx`, + * and for Codex `--profile`/`-p` and `-c`/`--config` setting `model`, `model_provider` or `profile`. Undefined when none does. + */ +export function modelSettingArgument(provider: ProviderId, args: readonly string[]): string | undefined { + const table = MODEL_ARGUMENTS[provider] ?? {}; + const valueFlags = ["--model", ...(table.short ?? []), ...(table.profile ?? [])]; + const configKeys = new Set(table.config?.keys ?? []); + const configSetsModel = (value: string | undefined): boolean => { + if (value === undefined) return false; + const key = value.split("=", 1)[0]!.trim().replace(/^["']|["']$/gu, ""); + return value.includes("=") && configKeys.has(key); + }; + for (let index = 0; index < args.length; index++) { + const argument = args[index]!; + if (valueFlags.some((flag) => argument === flag || attachedValue(argument, flag) !== undefined)) return argument; + for (const flag of table.config?.flags ?? []) { + const value = argument === flag ? args[index + 1] : attachedValue(argument, flag); + if (configSetsModel(value)) return argument === flag ? `${argument} ${value}` : argument; + } + } + return undefined; +} + +/** The value written into the flag's own argument: `--flag=value`, or `-fvalue` for a short flag. */ +function attachedValue(argument: string, flag: string): string | undefined { + if (flag.startsWith("--")) return argument.startsWith(`${flag}=`) ? argument.slice(flag.length + 1) : undefined; + return argument.length > flag.length && argument.startsWith(flag) ? argument.slice(flag.length) : undefined; +} diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index af27d88cf..d9e196ecf 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -9,6 +9,7 @@ import type { CreateSessionRequest, GitRiskReport, Point, + PluginLaunchValues, ProviderId, SessionBounds, SessionEnvironmentChoice, @@ -149,6 +150,8 @@ interface ManagedSession { restoringLaunch: boolean; /** The environment was prepared or resumed in this run of the app, so it can be wrapped now. */ environmentReady: boolean; + /** Plugins whose launch contribution decided this run's model (LaunchPipeline.prepare), once prepared. */ + modelSetBy?: string[]; /** Bumped by every launch the person or the app asks for (create, restart, restore); input waits for one. */ launchEpoch: number; /** Input waiting for this launch to start (deliverInput): woken whenever the launch moves on. */ @@ -664,8 +667,15 @@ export class TerminalManager { } const delegated = origin === "subagent" || control.ownerPluginId !== undefined; + // The orchestrator's own options are the person's choice: its subagent may repeat them even where the plugin did + // not declare its options delegable. Any other choice needs the plugin's delegable declaration. + // Only a subagent of the same CLI: the person chose them for that CLI (as AgentControlService.subagentLaunchOptions). + const parent = origin === "subagent" && request.parentSessionId !== undefined ? this.sessions.get(request.parentSessionId) : undefined; + const parentOptions = parent && parent.metadata.provider === request.provider + ? parent.extras.options as Record | undefined : undefined; const launchOptions = this.launchPipeline - ? this.launchPipeline.normalizeOptions(request.provider, request.launchOptions, origin === "subagent" ? { delegated: true } : undefined) + ? this.launchPipeline.normalizeOptions(request.provider, request.launchOptions, origin === "subagent" + ? { delegated: true, ...(parentOptions ? { inherited: parentOptions } : {}) } : undefined) : request.launchOptions === undefined ? undefined : failWith("Plugin launch options are not available."); // The isolation layer decides before anything starts: a subagent without it runs in normal, a launch that // needs it and cannot have it is refused. @@ -1845,6 +1855,20 @@ export class TerminalManager { } } + /** + * The plugin launch options this card was started with (a copy), or undefined without any. A subagent inherits them + * unless its spawn names the plugin (AgentControlService.subagentLaunchOptions). + */ + launchOptionsOf(id: string): Record | undefined { + const options = this.sessions.get(id)?.extras.options; + return options ? structuredClone(options) as Record : undefined; + } + + /** Plugins whose launch contribution decided this card's model in its current run; empty until it is prepared. */ + modelSetByOf(id: string): string[] { + return [...(this.sessions.get(id)?.modelSetBy ?? [])]; + } + /** The model and effort this card's launches ask the CLI for. */ private launchModelOf(id: string): LaunchModelChoice { const starting = this.startingModels.get(id); @@ -1895,7 +1919,8 @@ export class TerminalManager { return this.environments?.available(environment) ?? false; } - private unavailableLaunchPlugins(options: Record | undefined): string[] { + /** The plugins among these launch options that are disabled, removed or not trusted now. */ + unavailableLaunchPlugins(options: Record | undefined): string[] { if (!options) return []; return this.launchPipeline ? this.launchPipeline.unavailable(options) : Object.keys(options).sort(); } @@ -1915,6 +1940,8 @@ export class TerminalManager { ): void { const token = ++session.launchToken; const { metadata } = session; + // Each launch decides its model again; until it is prepared no plugin has. + session.modelSetBy = []; const tasks = session.launchTasks ??= new Set(); // Register before invoking plugin code, which may synchronously close or restart its card. const task = Promise.resolve().then(() => this.runContributedLaunch(id, session, token, resume, restoring, answerCaptureGrantExpiresAt)) @@ -2019,13 +2046,14 @@ export class TerminalManager { options: structuredClone(session.extras.options ?? {}) as Record>, environment: placedIn ? { pluginId: placedIn.pluginId, kind: placedIn.kind } : null, ...(trustedFolder ? { trustedFolder } : {}) - }); + }, { ...(this.launchModelOf(id).model !== undefined ? { model: this.launchModelOf(id).model } : {}) }); if (prepared.ok) { contribution = prepared; ownFolders.add(prepared.runDirectory); } if (!live()) return "superseded"; if (!prepared.ok) return refuse(prepared.reason); + session.modelSetBy = prepared.modelSetBy; this.addLaunchSecrets(session, prepared.secrets); } diff --git a/src/main/services/agent-browser/OrchestrationTools.ts b/src/main/services/agent-browser/OrchestrationTools.ts index ba6afebf3..f5df4f319 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -146,13 +146,22 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { if (unknown) throw orchestrationBridgeError("INVALID_REQUEST", unknown, false); } if (signal?.aborted) throw canceledError(); + // A plugin the spawn does not name keeps this session's own options (never silently the CLI's default model). + const requested = args.launchOptions as SpawnAgentRequest["launchOptions"]; + let inheritance: ReturnType; + try { + inheritance = this.control.subagentLaunchOptions(orchestratorId, provider, requested, args.model as string | undefined); + } catch (error) { + throw orchestrationBridgeError("INVALID_REQUEST", error instanceof Error ? error.message : String(error), false); + } + const launchOptions = inheritance.launchOptions; const created = await this.control.spawn({ parentSessionId: orchestratorId, provider: args.provider as never, cwd: args.cwd as string, ...(args.title !== undefined ? { title: args.title as string } : {}), ...(args.prompt !== undefined ? { initialPrompt: args.prompt as string } : {}), - ...(args.launchOptions !== undefined ? { launchOptions: args.launchOptions as SpawnAgentRequest["launchOptions"] } : {}), + ...(launchOptions !== undefined ? { launchOptions } : {}), ...(args.model !== undefined ? { model: args.model as string } : {}), ...(args.effort !== undefined ? { effort: args.effort as SpawnAgentRequest["effort"] } : {}), profile: profile.profile @@ -177,7 +186,10 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { profile: created.profile, ...(profile.inherited ? { profileInherited: true } : {}), ...(created.model !== undefined ? { model: created.model } : {}), - ...(created.effort !== undefined ? { effort: created.effort } : {}) + ...(created.effort !== undefined ? { effort: created.effort } : {}), + // Which CLI serves it, the model it was asked for (null: its launch options or the CLI's own default decide), + // and where each plugin's launch options came from. + servedBy: { provider: created.provider, model: created.model ?? null, launchOptions: inheritance.sources } }; } diff --git a/tests/orchestration-gateway.test.mjs b/tests/orchestration-gateway.test.mjs index e2f0a524a..ace1c16c2 100644 --- a/tests/orchestration-gateway.test.mjs +++ b/tests/orchestration-gateway.test.mjs @@ -370,6 +370,7 @@ test("a spawn_agent canceled while it was starting closes the agent it created", const control = { status: () => ({ role: "orchestrator", provider: "codex" }), profileFor: () => ({ profile: "normal", inherited: true }), + subagentLaunchOptions: (_parent, _provider, launchOptions) => ({ launchOptions, sources: {} }), spawn: async () => { controller.abort(); return { id: "child-1", provider: "codex", status: "running", title: "worker" }; diff --git a/tests/plugin-launch-choices.test.mjs b/tests/plugin-launch-choices.test.mjs index 884ea5bb6..1f024e90b 100644 --- a/tests/plugin-launch-choices.test.mjs +++ b/tests/plugin-launch-choices.test.mjs @@ -158,7 +158,9 @@ test("spawn_agent takes plugin launch options and hands them to the launch", () get: (id) => (id === "orch" ? parent : undefined), getMetadata: (id) => (id === "orch" ? parent : null), listMetadata: () => [parent], - create: (request) => { created.push(request); return { id: "child", ...request, status: "starting", title: "c" }; } + create: (request) => { created.push(request); return { id: "child", ...request, status: "starting", title: "c" }; }, + launchOptionsOf: () => undefined, + modelSetByOf: () => [] }; const control = new AgentControlService(terminals); control.spawn({ parentSessionId: "orch", provider: "codex", cwd: process.cwd(), launchOptions: { "canvastty-accounts": { account: "ollama" } } }); diff --git a/tests/subagent-model-account.test.mjs b/tests/subagent-model-account.test.mjs new file mode 100644 index 000000000..a10150fba --- /dev/null +++ b/tests/subagent-model-account.test.mjs @@ -0,0 +1,312 @@ +import assert from "node:assert/strict"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { AgentControlService } from "../src/main/services/AgentControlService.ts"; +import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; +import { LaunchPipeline, modelSettingArgument } from "../src/main/services/LaunchPipeline.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { TerminalSessionStore } from "../src/main/services/TerminalSessionStore.ts"; +import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; + +// A subagent spawned without launch options once ran on its CLI's own default model (for OpenCode the hosted OpenCode +// Zen model), while its orchestrator ran on a model the person picked through a plugin (a model account). It now keeps +// the orchestrator's options for every plugin the spawn does not name; naming a plugin is an explicit choice, and a +// second model flag next to a plugin's own is refused instead of starting a CLI that crashes. + +const at = { x: 0, y: 0 }; +// Any plugin id: the core knows no plugin by name. +const MODELS = "example-model-accounts"; +const EXTRAS = "example-extras"; +const OTHER = "example-other-models"; +const BARE = "example-no-fields"; + +async function setup(t, { delegable = true, store } = {}) { + const root = await mkdtemp(join(tmpdir(), "ctty-sub-account-")); + t.after(() => rm(root, { recursive: true, force: true })); + const calls = []; + const prepared = []; + // What the person can change while the orchestrator runs: turn a plugin off, or a plugin update changes its fields. + const state = { gone: new Set(), extrasFields: [{ key: "flavor", label: "Flavor", kind: "text" }] }; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + t.after(() => store ? terminals.shutdown() : terminals.disposeAll()); + terminals.configureLaunchPipeline(new LaunchPipeline({ + contributors: () => [ + { pluginId: MODELS, pluginName: "Model accounts", serviceId: "accounts", secrets: false, + launch: { fields: [{ key: "account", label: "Model account", kind: "text" }], ...(delegable ? { delegable: true } : {}) } }, + // Options that do not decide the model. + { pluginId: EXTRAS, pluginName: "Extras", serviceId: "extras", secrets: false, + launch: { fields: state.extrasFields } }, + // A plugin without fields: choosing it in the launcher stores {}. + { pluginId: BARE, pluginName: "No fields", serviceId: "bare", secrets: false, launch: { fields: [] } }, + // A second plugin that also sets the model. + { pluginId: OTHER, pluginName: "Other models", serviceId: "other", secrets: false, + launch: { fields: [{ key: "pick", label: "Model", kind: "text" }], delegable: true } } + ].filter((contributor) => !state.gone.has(contributor.pluginId)), + call: async (pluginId, _service, method, params) => { + if (method !== "canvastty.launch.prepare") return null; + prepared.push({ pluginId, sessionId: params.sessionId, chosen: params.chosen, options: params.options }); + if (pluginId === OTHER && params.chosen) return { env: {}, secretEnv: {}, args: [`--model=other/${params.options.pick}`], files: [] }; + return pluginId === MODELS && params.chosen && params.options.account && params.options.account !== "none" + ? { env: {}, secretEnv: {}, args: ["--model", `acct_${params.options.account}/glm-5.3-flash`], files: [] } + : { env: {}, secretEnv: {}, args: [], files: [] }; + }, + secret: async () => null, runsRoot: join(root, "runs"), timeoutMs: 2000 + })); + if (store) { + terminals.configureSessionPersistence(new TerminalSessionStore(store), "continue"); + await terminals.restorePersistedSessions(); + } + const control = new AgentControlService(terminals); + const handler = new ScopedOrchestrationHandler(control, null, + { cli: () => "available", limits: () => null, models: () => ({ models: ["zai/glm-5.3"], checkedAt: Date.now() }), checkModel: async () => null }, + {}); + const orchestrator = (launchOptions, provider = "opencode") => terminals.create({ provider, profile: "normal", cwd: root, position: at, role: "orchestrator", + ...(launchOptions ? { launchOptions } : {}) }); + const spawn = (parent, args) => handler.execute(parent.id, { id: `c-${Math.random()}`, tool: "spawn_agent", arguments: { provider: "opencode", cwd: root, prompt: "Small task", ...args } }); + const settle = () => new Promise((resolve) => setTimeout(resolve, 50)); + return { root, calls, prepared, state, terminals, control, handler, orchestrator, spawn, settle }; +} + +test("a subagent spawned without launch options runs on its orchestrator's model account, never on the CLI default", async (t) => { + const s = await setup(t); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" } }); + await s.settle(); + assert.deepEqual(s.terminals.modelSetByOf(parent.id), [MODELS]); + const child = await s.spawn(parent, {}); + await s.settle(); + assert.deepEqual(child.servedBy, { provider: "opencode", model: null, launchOptions: { [MODELS]: "inherited" } }); + const childPrepare = s.prepared.find((entry) => entry.sessionId === child.sessionId); + assert.deepEqual(childPrepare, { pluginId: MODELS, sessionId: child.sessionId, chosen: true, options: { account: "glm-flash" } }); + const launched = s.calls.at(-1).args; + assert.ok(launched.includes("acct_glm-flash/glm-5.3-flash"), launched.join(" ")); + assert.equal(launched.filter((arg) => arg === "--model").length, 1); + assert.deepEqual(s.terminals.launchOptionsOf(child.sessionId), { [MODELS]: { account: "glm-flash" } }); +}); + +test("naming the plugin is an explicit choice; without any options the CLI's default serves the subagent", async (t) => { + const s = await setup(t); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" } }); + await s.settle(); + const own = await s.spawn(parent, { launchOptions: { [MODELS]: { account: "none" } } }); + await s.settle(); + assert.deepEqual(own.servedBy.launchOptions, { [MODELS]: "explicit" }); + assert.deepEqual(s.terminals.launchOptionsOf(own.sessionId), { [MODELS]: { account: "none" } }); + assert.ok(!s.calls.at(-1).args.some((arg) => arg.startsWith("acct_")), "explicit none: no account model"); + assert.deepEqual(s.terminals.modelSetByOf(own.sessionId), []); + + const bare = await setup(t); + const plain = bare.orchestrator(); + const child = await bare.spawn(plain, {}); + await bare.settle(); + assert.deepEqual(child.servedBy, { provider: "opencode", model: null, launchOptions: {} }); + assert.equal(bare.terminals.launchOptionsOf(child.sessionId), undefined); +}); + +test("another value needs the plugin's delegable declaration; the orchestrator's own values do not", async (t) => { + const s = await setup(t, { delegable: false }); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" }, [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + const inherited = await s.spawn(parent, {}); + assert.deepEqual(inherited.servedBy.launchOptions, { [MODELS]: "inherited", [EXTRAS]: "inherited" }); + assert.deepEqual(s.terminals.launchOptionsOf(inherited.sessionId), { [MODELS]: { account: "glm-flash" }, [EXTRAS]: { flavor: "mild" } }); + const same = await s.spawn(parent, { launchOptions: { [MODELS]: { account: "glm-flash" } } }); + assert.deepEqual(same.servedBy.launchOptions, { [MODELS]: "explicit", [EXTRAS]: "inherited" }); + await assert.rejects(s.spawn(parent, { launchOptions: { [MODELS]: { account: "other-paid" } } }), + /Model accounts has not declared its launch options safe for an orchestrator to choose/u); +}); + +test("a subagent of another CLI cannot silently drop the options that set the orchestrator's model", async (t) => { + const s = await setup(t); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" }, [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + const refused = new RegExp(`model is set by its ${MODELS} launch options, which the person chose for opencode; a codex subagent would not get that model\\. Spawn a opencode subagent instead\\.`, "u"); + await assert.rejects(s.spawn(parent, { provider: "codex" }), refused); + assert.throws(() => s.control.spawn({ parentSessionId: parent.id, provider: "codex", cwd: s.root }), refused); + // Naming the plugin for the other CLI is explicit; options that do not decide the model stay with their CLI. + const explicit = await s.spawn(parent, { provider: "codex", launchOptions: { [MODELS]: { account: "none" } } }); + assert.deepEqual(explicit.servedBy.launchOptions, { [MODELS]: "explicit" }); + assert.deepEqual(s.terminals.launchOptionsOf(explicit.sessionId), { [MODELS]: { account: "none" } }); +}); + +test("AgentControlService.spawn applies the same inheritance for every caller", async (t) => { + const s = await setup(t); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" } }); + await s.settle(); + const child = await s.control.spawn({ parentSessionId: parent.id, provider: "opencode", cwd: s.root }); + await s.settle(); + assert.deepEqual(s.terminals.launchOptionsOf(child.id), { [MODELS]: { account: "glm-flash" } }); + assert.deepEqual(s.terminals.modelSetByOf(child.id), [MODELS]); +}); + +test("a subagent with an explicit model next to launch options that set the model is refused instead of a crashing double --model", async (t) => { + const s = await setup(t); + const parent = s.orchestrator({ [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + const spawned = s.calls.length; + const child = await s.control.spawn({ parentSessionId: parent.id, provider: "opencode", cwd: s.root, model: "zai/glm-5.3", + launchOptions: { [MODELS]: { account: "glm-flash" } } }); + await s.settle(); + const failed = s.terminals.getMetadata(child.id); + assert.equal(failed.status, "failed"); + assert.match(failed.failureDetails, /Model accounts sets the model of this launch, and the launch also asks for model zai\/glm-5\.3/u); + assert.equal(s.calls.length, spawned, "no CLI was started with two --model flags"); + + // Options that do not set the model take an explicit model as before. + const plain = await s.control.spawn({ parentSessionId: parent.id, provider: "opencode", cwd: s.root, model: "zai/glm-5.3" }); + await s.settle(); + assert.notEqual(s.terminals.getMetadata(plain.id).status, "failed"); + assert.equal(s.calls.at(-1).args.filter((arg) => arg === "--model").length, 1); + + // A subagent that would inherit them is refused before anything starts. + const accounts = s.orchestrator({ [MODELS]: { account: "glm-flash" } }); + await s.settle(); + await assert.rejects(s.spawn(accounts, { model: "zai/glm-5.3" }), + new RegExp(`inherits its orchestrator's ${MODELS} launch options, which set its model; it cannot also take model zai/glm-5\\.3`, "u")); +}); + +test("a subagent whose launch options come from two plugins that both set the model is refused", async (t) => { + const s = await setup(t); + const parent = s.orchestrator(); + await s.settle(); + const spawned = s.calls.length; + const child = await s.control.spawn({ parentSessionId: parent.id, provider: "opencode", cwd: s.root, + launchOptions: { [MODELS]: { account: "glm-flash" }, [OTHER]: { pick: "x" } } }); + await s.settle(); + const failed = s.terminals.getMetadata(child.id); + assert.equal(failed.status, "failed"); + assert.match(failed.failureDetails, /Model accounts and Other models both set the model of this launch/u); + assert.equal(s.calls.length, spawned); +}); + +test("a person's own card keeps starting with a model and a plugin that sets the model, also when it is restored", async (t) => { + const s = await setup(t); + const card = s.terminals.create({ provider: "opencode", profile: "normal", cwd: s.root, position: at, model: "zai/glm-5.3", + launchOptions: { [MODELS]: { account: "glm-flash" } } }); + await s.settle(); + assert.notEqual(s.terminals.getMetadata(card.id).status, "failed"); + assert.ok(s.calls.at(-1).args.includes("acct_glm-flash/glm-5.3-flash")); + + const store = await mkdtemp(join(tmpdir(), "ctty-sub-account-store-")); + t.after(() => rm(store, { recursive: true, force: true })); + await new TerminalSessionStore(store).replace([{ + id: "person-card", provider: "opencode", profile: "normal", role: "agent", title: "Agent", titleCustomized: false, + cwd: s.root, position: at, size: { width: 700, height: 430 }, lastState: "running", restore: true, + model: "zai/glm-5.3", options: { [MODELS]: { account: "glm-flash" } } + }]); + const restored = await setup(t, { store }); + await restored.settle(); + const metadata = restored.terminals.getMetadata("person-card"); + assert.notEqual(metadata.status, "failed", metadata.failureDetails ?? ""); + assert.equal(restored.calls.length, 1); + assert.ok(restored.calls[0].args.includes("acct_glm-flash/glm-5.3-flash")); + assert.deepEqual(restored.terminals.modelSetByOf("person-card"), [MODELS]); +}); + +test("a subagent of another CLI is never checked against options the person chose for its orchestrator's CLI", async (t) => { + const s = await setup(t, { delegable: false }); + // EXTRAS is not delegable and does not set the model: an opencode orchestrator's choice is not a codex subagent's. + const parent = s.orchestrator({ [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + const child = await s.spawn(parent, { provider: "codex" }); + assert.deepEqual(child.servedBy.launchOptions, {}); + assert.equal(s.terminals.launchOptionsOf(child.sessionId), undefined); + // Naming it for codex is the orchestrator's own choice, which this plugin does not allow. + await assert.rejects(s.spawn(parent, { provider: "codex", launchOptions: { [EXTRAS]: { flavor: "mild" } } }), + /Extras has not declared its launch options safe for an orchestrator to choose/u); +}); + +test("model-setting arguments are recognised in every form each CLI takes", () => { + const sets = (provider, ...args) => modelSettingArgument(provider, args); + for (const provider of ["opencode", "codex", "qwen", "kimi", "grok", "claude", "cursor"]) { + assert.equal(sets(provider, "--model", "x"), "--model", provider); + assert.equal(sets(provider, "--model=x"), "--model=x", provider); + } + for (const provider of ["opencode", "codex", "qwen", "kimi", "grok"]) { + assert.equal(sets(provider, "-m", "x"), "-m", provider); + assert.equal(sets(provider, "-mx"), "-mx", provider); + } + // Claude has no -m. + assert.equal(sets("claude", "-m", "x"), undefined); + // Codex: a profile, and configuration keys that pick the model or its provider. + assert.equal(sets("codex", "--profile", "work"), "--profile"); + assert.equal(sets("codex", "--profile=work"), "--profile=work"); + assert.equal(sets("codex", "-p", "work"), "-p"); + assert.equal(sets("codex", "-pwork"), "-pwork"); + assert.equal(sets("codex", "-c", "model=\"o3\""), "-c model=\"o3\""); + assert.equal(sets("codex", "-c", " model = o3"), "-c model = o3"); + assert.equal(sets("codex", "--config", "model_provider=acct"), "--config model_provider=acct"); + assert.equal(sets("codex", "--config=profile=work"), "--config=profile=work"); + assert.equal(sets("codex", "-cmodel=o3"), "-cmodel=o3"); + assert.equal(sets("codex", "-c", "\"model\"=o3"), "-c \"model\"=o3"); + // Other configuration keys and flags do not choose the model. + assert.equal(sets("codex", "-c", "model_reasoning_effort=high"), undefined); + assert.equal(sets("codex", "-c", "model"), undefined); + assert.equal(sets("codex", "--search", "-c", "tools.web_search=true"), undefined); + assert.equal(sets("opencode", "--profile", "x", "-p", "y"), undefined); + assert.equal(sets("opencode", "--models"), undefined); +}); + +test("without the delegable declaration a subagent gets exactly the inherited values, never the plugin's defaults", () => { + const pipeline = new LaunchPipeline({ + contributors: () => [{ pluginId: EXTRAS, pluginName: "Extras", serviceId: "extras", secrets: false, + launch: { fields: [{ key: "a", label: "A", kind: "text", default: "da" }, { key: "b", label: "B", kind: "text", default: "db" }, + { key: "c", label: "C", kind: "text" }] } }], + call: async () => null, secret: async () => null, runsRoot: join(tmpdir(), "ctty-unused-runs") + }); + const inherited = { [EXTRAS]: { a: "1", b: "2", c: "" } }; + const delegated = { delegated: true, inherited }; + // A subset is completed from the orchestrator's values, not from the defaults. + assert.deepEqual(pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1" } }, delegated), { [EXTRAS]: { a: "1", b: "2", c: "" } }); + assert.deepEqual(pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1", b: "2", c: "" } }, delegated), inherited); + const refused = /Extras has not declared its launch options safe for an orchestrator to choose/u; + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1", b: "x" } }, delegated), refused); + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: { c: "set" } }, delegated), refused); + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1", extra: "1" } }, delegated), refused); + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: {} }, delegated), refused); + // An orchestrator whose own values the plugin no longer accepts as they were is refused, not given defaults. + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1" } }, { delegated: true, inherited: { [EXTRAS]: { a: "1", b: "2" } } }), + /Extras launch options changed since this orchestrator started/u); + assert.throws(() => pipeline.normalizeOptions("opencode", { [EXTRAS]: { a: "1" } }, { delegated: true }), refused); +}); + +test("a plugin without fields chosen for the orchestrator is inherited as chosen, not refused", async (t) => { + const s = await setup(t, { delegable: false }); + const parent = s.orchestrator({ [BARE]: {} }); + await s.settle(); + assert.notEqual(s.terminals.getMetadata(parent.id).status, "failed"); + const child = await s.spawn(parent, {}); + await s.settle(); + assert.deepEqual(child.servedBy.launchOptions, { [BARE]: "inherited" }); + assert.deepEqual(s.terminals.launchOptionsOf(child.sessionId), { [BARE]: {} }); + assert.notEqual(s.terminals.getMetadata(child.sessionId).status, "failed"); +}); + +test("a plugin turned off after the orchestrator started: left out unless it set the model, then refused", async (t) => { + const s = await setup(t, { delegable: false }); + const parent = s.orchestrator({ [MODELS]: { account: "glm-flash" }, [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + // Options that do not decide the model: the subagent starts without them. + s.state.gone.add(EXTRAS); + const child = await s.spawn(parent, {}); + await s.settle(); + assert.deepEqual(child.servedBy.launchOptions, { [MODELS]: "inherited" }); + assert.deepEqual(s.terminals.launchOptionsOf(child.sessionId), { [MODELS]: { account: "glm-flash" } }); + // The plugin that set the model: never a silent fall back to the CLI's default model. + s.state.gone.add(MODELS); + const spawned = s.calls.length; + await assert.rejects(s.spawn(parent, {}), + new RegExp(`model is set by its ${MODELS} launch options, and ${MODELS} is now disabled, removed or not trusted; a subagent would run on its CLI's own default model instead`, "u")); + assert.equal(s.calls.length, spawned); +}); + +test("a plugin whose fields changed after the orchestrator started refuses its subagents with that reason", async (t) => { + const s = await setup(t, { delegable: false }); + const parent = s.orchestrator({ [EXTRAS]: { flavor: "mild" } }); + await s.settle(); + s.state.extrasFields.splice(0, 1, { key: "taste", label: "Taste", kind: "text" }); + await assert.rejects(s.spawn(parent, {}), /Extras launch options changed since this orchestrator started, so its subagents cannot repeat the person's choice/u); + s.state.extrasFields.splice(0, 1, { key: "flavor", label: "Flavor", kind: "text" }, { key: "extra", label: "Extra", kind: "text", default: "on" }); + await assert.rejects(s.spawn(parent, {}), /Extras launch options changed since this orchestrator started/u); +}); From 8a59c8224a2bfce67ed3e99a22c2290079d8e637 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 17:59:41 +0000 Subject: [PATCH 5/9] fix(agents): type OpenCode prompts only once its input field is up OpenCode drops every key that arrives while its full-screen view starts (a few seconds). CanvasTTY typed spawn_agent's first prompt, send_to_agent and plugin sessions.send as soon as the PTY existed, so an OpenCode subagent sat at an empty prompt until the orchestrator gave up. deliverInput now waits, within the same bounded wait it already had for the launch, until OpenCode can take input: the terminal control sequence that shows its text cursor on the alternate screen once its prompt has focus, or a lifecycle hook from its plugin, counted only 2 s after the launch's first one (the plugin can report before the prompt takes keys). Only DEC private mode sequences are read; human-readable screen text is never parsed and no status changes. Other CLIs keep getting input when the PTY exists. - The wait is used on macOS and Linux. Windows' pseudo console may not pass those sequences, so there input is typed when the PTY exists, as before. - spawn_agent (checks, launch and readiness together) and send_to_agent wait at most 45 s, so the orchestrator gets the reason and the session id, not an MCP client timeout. Nothing is typed then. - A handoff waits up to 15 s for the CLI to take input instead of failing at once; a caller that does not wait is told the state. - Sends to one card are delivered in the order they were made, a queued send never reaches a later launch, and a send cancelled while it waits behind another settles at once and types nothing. --- docs/agent-orchestration.md | 2 +- src/main/services/AgentControlService.ts | 15 +- src/main/services/TerminalManager.ts | 153 ++++++++++- .../agent-browser/OrchestrationTools.ts | 13 +- src/main/services/materials/HandoffService.ts | 8 +- tests/helpers/terminal.mjs | 22 ++ tests/launch-readiness.test.mjs | 237 +++++++++++++++++- tests/material-handoff-service.test.mjs | 16 ++ tests/opencode-result.test.mjs | 9 +- tests/orchestration-providers-wait.test.mjs | 6 +- tests/subagent-model-account.test.mjs | 4 +- 11 files changed, 450 insertions(+), 35 deletions(-) diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index 3b380d2c1..a34f2d6fd 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -12,7 +12,7 @@ A session launched from the desktop with the **Orchestrator** role gets the `can | `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`. Plugin launch options the call does not name are inherited from the orchestrator for a subagent of the same CLI (see Plugin launch options below); `model` next to inherited options that set the model is refused, and so is a subagent of another CLI while the orchestrator's model comes from a plugin's options. The answer's `servedBy` is `{ provider, model, launchOptions: { : "inherited" | "explicit" } }`. 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. | | `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. | +| `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. Prompts to one subagent arrive in the order they were sent. OpenCode drops keys typed while it starts, so a prompt for it (also `spawn_agent`'s first one) is typed only once its input field is up: the terminal control sequence that shows its text cursor on its full screen, or a lifecycle hook only 2 s after its first one (OpenCode's plugin can report shortly before the field takes keys). This wait is used on macOS and Linux; on Windows, whose pseudo console may not pass those sequences, OpenCode gets input as soon as its PTY exists, as before. `spawn_agent` (its checks, the launch and this wait together) and `send_to_agent` wait at most 45 s, under the MCP client's tool deadline; then the call fails with the reason and the session id, and nothing is typed. A send cancelled while it waits returns at once. | ### Subagent profiles diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index c44bbc4eb..67094d009 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -141,9 +141,10 @@ export class AgentControlService { /** * Creates the subagent card. With an initial prompt it resolves only once the prompt reached the agent's PTY * (after an asynchronous launch has started) and rejects with PromptNotDeliveredError when that launch did not - * start; the card stays, so the caller can inspect or cancel it. + * start; the card stays, so the caller can inspect or cancel it. `promptWaitMs` bounds that wait (the launch and + * the CLI's readiness together; LAUNCH_INPUT_WAIT_MS without it). */ - spawn(request: SpawnAgentRequest, signal?: AbortSignal): Promise { + spawn(request: SpawnAgentRequest, signal?: AbortSignal, promptWaitMs?: number): Promise { if (!request || typeof request.parentSessionId !== "string") { throw new Error("A parent session id is required."); } @@ -193,7 +194,7 @@ export class AgentControlService { ...(request.effort !== undefined ? { effort: request.effort } : {}) }, { ...(RESULT_CAPTURE_PROVIDERS.has(request.provider) ? { captureResult: true } : {}), origin: "subagent" }); if (request.initialPrompt === undefined || request.initialPrompt.length === 0) return Promise.resolve(created); - return this.deliver(created.id, `${request.initialPrompt}\r`, "prompt", signal) + return this.deliver(created.id, `${request.initialPrompt}\r`, "prompt", signal, promptWaitMs) .then(() => this.terminals.getMetadata(created.id) ?? created, (error: unknown) => { // Cancelled while it started: nobody receives its id, so the card is closed instead of left running. if (!signal?.aborted) throw error; @@ -259,14 +260,14 @@ export class AgentControlService { } /** Validates at once (throws); resolves once the text reached the agent, and rejects when it did not. */ - send(sessionId: string, text: string, submit = true, signal?: AbortSignal): Promise { + send(sessionId: string, text: string, submit = true, signal?: AbortSignal, waitMs?: number): Promise { const session = this.requireSession(sessionId); if (session.provider === "terminal") throw new Error("Plain terminals are not agents."); const capabilities = PROVIDER_CAPABILITIES[session.provider as AgentProviderId]; if (!capabilities.send) throw new Error(`${session.provider} cannot receive prompts.`); if (typeof text !== "string" || text.length === 0) throw new Error("Prompt text is required."); if (session.exitCode !== null) throw new Error("Agent session has already exited."); - return this.deliver(sessionId, submit ? `${text}\r` : text, "text", signal); + return this.deliver(sessionId, submit ? `${text}\r` : text, "text", signal, waitMs); } status(sessionId: string): SessionMetadata { @@ -434,8 +435,8 @@ export class AgentControlService { } /** Through the terminal manager's one delivery rule: exactly once, into the launch that is starting now. */ - private async deliver(sessionId: string, data: string, what: "prompt" | "text", signal?: AbortSignal): Promise { - const delivery = await this.terminals.deliverInput(sessionId, data, undefined, signal); + private async deliver(sessionId: string, data: string, what: "prompt" | "text", signal?: AbortSignal, waitMs?: number): Promise { + const delivery = await this.terminals.deliverInput(sessionId, data, waitMs, signal); if (!delivery.delivered) { throw new PromptNotDeliveredError(sessionId, `The ${what} for agent ${sessionId} was not delivered: ${delivery.reason}`); } diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index d9e196ecf..c0f00ea76 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -164,6 +164,17 @@ interface ManagedSession { hookSignals?: number; /** Set after the person answered a hooked Claude prompt; see settleAnsweredPrompt. */ answeredPromptTimer?: ReturnType; + /** The last deliverInput of this card: the next one waits for it, so sends arrive in order. */ + inputQueue?: Promise; + /** This launch's CLI turned its text cursor on in its full-screen view: its input field is up (watchInputReadiness). */ + inputReady?: boolean; + /** While watching for inputReady: this launch's CLI is on its alternate (full-screen) buffer. */ + alternateScreen?: boolean; + /** While watching for inputReady: an escape sequence cut off at the end of the last output chunk. */ + readinessCarry?: string; + /** When this launch's first lifecycle hook stops waiting for inputReady (INPUT_READY_HOOK_GRACE_MS after it). */ + hookReadyAt?: number; + hookReadyTimer?: ReturnType; } type EnvironmentService = Pick = new Set(["opencode"]); + +/** + * Whether input for this CLI waits for its input field. Only on macOS and Linux: Windows' pseudo console (ConPTY, + * winpty) may not pass the alternate-screen and cursor sequences through, so there the gate could never open, and + * input is typed as soon as the PTY exists, as before. + */ +function waitsForInputReady(provider: ProviderId): boolean { + return (process.platform === "darwin" || process.platform === "linux") && WAITS_FOR_INPUT_READY.has(provider); +} + +/** + * A lifecycle hook alone is not proof that the input field is up: OpenCode's plugin reports (for a resumed session, + * idle on session.updated) about 0.6 s before typed keys reach its prompt. The cursor signal decides; a hook counts + * only this long after the launch's first one, for a CLI whose cursor sequence never arrives. + */ +export const INPUT_READY_HOOK_GRACE_MS = 2_000; + /** What happened to input handed to deliverInput. */ export type InputDelivery = { delivered: true } | { delivered: false; reason: string }; @@ -916,29 +951,59 @@ export class TerminalManager { * The one delivery rule for text another agent, a plugin or a controller sends to a card (spawn_agent's first * prompt, send_to_agent, plugin sessions.send). A running card gets it at once. A card whose launch plugins are * still preparing (launch options, a launch policy, an environment) or that waits for its grid gets it exactly - * once, when that launch has started. A launch that is refused, fails, is cancelled or superseded (closed, - * restarted), or does not start within LAUNCH_INPUT_WAIT_MS delivers nothing, says why, and drops the text: - * it never reaches a later launch of the card. An aborted `signal` (the sender cancelled) delivers nothing either. + * once, when that launch has started. A CLI that drops keys typed while it starts (WAITS_FOR_INPUT_READY) gets it + * only once its input field is up. A launch that is refused, fails, is cancelled or superseded (closed, restarted), + * or does not start or become ready within `waitMs` delivers nothing, says why, and drops the text: it never reaches + * a later launch of the card. An aborted `signal` (the sender cancelled) delivers nothing either. Sends to one card + * are delivered in the order they were made; the wait of each counts from its own call. */ - async deliverInput(id: string, data: string, waitMs = LAUNCH_INPUT_WAIT_MS, signal?: AbortSignal): Promise { - const canceled: InputDelivery = { delivered: false, reason: "The delivery was cancelled." }; - if (signal?.aborted) return canceled; + deliverInput(id: string, data: string, waitMs = LAUNCH_INPUT_WAIT_MS, signal?: AbortSignal): Promise { const session = this.sessions.get(id); - if (!session) return { delivered: false, reason: "The session does not exist." }; + if (!session) return Promise.resolve({ delivered: false, reason: "The session does not exist." }); + // The launch this call was made for: a send queued behind another never reaches a later launch either. const epoch = session.launchEpoch; const deadline = Date.now() + waitMs; - const waiting = (): boolean => this.sessions.get(id) === session && session.launchEpoch === epoch - && session.metadata.exitCode === null && !session.process; - while (waiting() && !signal?.aborted) { + const previous = session.inputQueue; + const run = (): Promise => this.deliverQueuedInput(id, session, epoch, data, waitMs, deadline, signal); + const pending = previous ? previous.then(run, run) : run(); + session.inputQueue = pending; + void pending.finally(() => { if (session.inputQueue === pending) delete session.inputQueue; }).catch(() => undefined); + if (!signal || !previous) return pending; + // A send cancelled while it waits behind another settles at once; its turn in the queue then types nothing. + const canceled: InputDelivery = { delivered: false, reason: "The delivery was cancelled." }; + if (signal.aborted) return Promise.resolve(canceled); + return new Promise((resolve) => { + const abort = (): void => resolve(canceled); + signal.addEventListener("abort", abort, { once: true }); + void pending.then(resolve, () => resolve(canceled)).finally(() => signal.removeEventListener("abort", abort)); + }); + } + + private async deliverQueuedInput( + id: string, session: ManagedSession, epoch: number, data: string, waitMs: number, deadline: number, signal?: AbortSignal + ): Promise { + const canceled: InputDelivery = { delivered: false, reason: "The delivery was cancelled." }; + if (signal?.aborted) return canceled; + // What the text still waits for: the launch to start, or (once its PTY exists) the CLI's input field. + const awaiting = (): "launch" | "input" | null => { + if (this.sessions.get(id) !== session || session.launchEpoch !== epoch || session.metadata.exitCode !== null) return null; + if (!session.process) return "launch"; + return cliAcceptsInput(session) ? null : "input"; + }; + for (let stage = awaiting(); stage && !signal?.aborted; stage = awaiting()) { const remaining = deadline - Date.now(); if (remaining <= 0) { - return { delivered: false, reason: `The session did not start within ${Math.round(waitMs / 1000)} s.` }; + // A caller that does not wait (0) is told the state, not a wait it never made. + const within = waitMs <= 0 ? "yet" : waitMs >= 1_000 ? `within ${Math.round(waitMs / 1_000)} s` : `within ${waitMs} ms`; + return { delivered: false, reason: stage === "launch" + ? `The session did not start ${within}.` + : `The agent's CLI did not show its input field ${within}; nothing was typed. Look at the card, then send the prompt again.` }; } await new Promise((resolve) => { const timer = setTimeout(wake, remaining); function wake(): void { clearTimeout(timer); - session!.launchWaiters.delete(wake); + session.launchWaiters.delete(wake); signal?.removeEventListener("abort", wake); resolve(); } @@ -1045,7 +1110,19 @@ export class TerminalManager { applyProviderSignal(id: string, signal: ProviderLifecycleSignal, source: "hook" | "title" = "hook"): void { const session = this.sessions.get(id); if (!this.lifecycleHooksEnabled || !session || session.metadata.status === "done" || session.metadata.status === "failed") return; - if (source === "hook") session.hookSignals = (session.hookSignals ?? 0) + 1; + if (source === "hook") { + session.hookSignals = (session.hookSignals ?? 0) + 1; + // The CLI runs, but its input field may not be up yet: input waiting for it (deliverInput) goes on the cursor + // signal, or once the grace after this first hook has passed. + if (session.hookSignals === 1 && waitsForInputReady(session.metadata.provider) && !session.inputReady) { + session.hookReadyAt = Date.now() + INPUT_READY_HOOK_GRACE_MS; + session.hookReadyTimer = setTimeout(() => { + session.hookReadyTimer = undefined; + this.wakeLaunchWaiters(session); + }, INPUT_READY_HOOK_GRACE_MS); + session.hookReadyTimer.unref?.(); + } + } const threadId = normalizeThreadId(session.metadata.provider, signal.threadId); const threadChanged = Boolean(threadId && threadId !== session.threadId); @@ -2182,6 +2259,9 @@ export class TerminalManager { const current = this.sessions.get(id); if (!current || current !== session || current.process !== process) return; + if (!current.inputReady && waitsForInputReady(current.metadata.provider) && watchInputReadiness(current, data)) { + this.wakeLaunchWaiters(current); + } const lifecycleState = current.lifecycle?.push(data); if (lifecycleState) current.titleState = lifecycleState; if (lifecycleState && !titleDefersToHooks(current, lifecycleState)) { @@ -2233,6 +2313,8 @@ export class TerminalManager { current.agentOrchestration = null; void this.cleanupLaunchFiles(current).catch(() => undefined); this.emitSession(current.metadata); + // Input waiting for this CLI to become ready learns at once that it never will. + this.wakeLaunchWaiters(current); // Recorded at the moment of exit, so a finished agent is never relaunched. this.schedulePersistence(); } @@ -2335,10 +2417,55 @@ function resetLaunchSignals(session: ManagedSession): void { delete session.promptTurnMark; delete session.hookSignals; delete session.titleState; + delete session.inputReady; + delete session.alternateScreen; + delete session.readinessCarry; + delete session.hookReadyAt; + if (session.hookReadyTimer) clearTimeout(session.hookReadyTimer); + session.hookReadyTimer = undefined; if (session.answeredPromptTimer) clearTimeout(session.answeredPromptTimer); session.answeredPromptTimer = undefined; } +/** Whether typed text reaches this launch's CLI now (see WAITS_FOR_INPUT_READY). */ +function cliAcceptsInput(session: ManagedSession): boolean { + return !waitsForInputReady(session.metadata.provider) || session.inputReady === true + || (session.hookReadyAt !== undefined && Date.now() >= session.hookReadyAt); +} + +/** DEC private modes set or reset (CSI ? Pm h / l): terminal control sequences, not text the CLI shows. */ +const DEC_PRIVATE_MODES = /\x1b\[\?([\d;]+)([hl])/gu; +/** The longest DEC private mode sequence kept from the end of one chunk for the next. */ +const READINESS_CARRY_CHARS = 32; + +/** + * Reads only terminal control sequences of one output chunk: the alternate screen (modes 1049, 1047, 47) and the text + * cursor (DECTCEM, mode 25). A full-screen CLI hides its cursor while it draws its start-up and shows it once its + * input field has focus; that moment is when typed keys start to reach that field. True once that happened; a + * sequence cut at the chunk's end is completed by the next chunk. + */ +function watchInputReadiness(session: ManagedSession, data: string): boolean { + const text = (session.readinessCarry ?? "") + data; + let consumed = 0; + for (const match of text.matchAll(DEC_PRIVATE_MODES)) { + consumed = match.index + match[0].length; + const set = match[2] === "h"; + for (const mode of match[1]!.split(";")) { + if (mode === "1049" || mode === "1047" || mode === "47") session.alternateScreen = set; + else if (mode === "25" && set && session.alternateScreen) session.inputReady = true; + } + if (session.inputReady) break; + } + if (session.inputReady) { + delete session.readinessCarry; + delete session.alternateScreen; + return true; + } + const escape = text.lastIndexOf("\x1b"); + session.readinessCarry = escape >= consumed && text.length - escape < READINESS_CARRY_CHARS ? text.slice(escape) : ""; + return false; +} + function titleDefersToHooks(session: ManagedSession, state: "idle" | "working" | "needs_approval"): boolean { return state !== "working" && session.metadata.provider === "claude" && session.hookSignals !== undefined; } diff --git a/src/main/services/agent-browser/OrchestrationTools.ts b/src/main/services/agent-browser/OrchestrationTools.ts index f5df4f319..3052d95bf 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -22,6 +22,13 @@ import type { McpToolDefinition } from "../../../agent-browser/orchestration-cat * a foreign session id is a protocol error, never a filtered result, so an * orchestrator cannot probe sessions it does not own. */ +/** + * How long spawn_agent (its checks, the launch and the CLI's readiness together) and send_to_agent wait for a prompt + * to reach the agent: under the about 60 s after which most MCP clients end a tool call, so the orchestrator gets + * the reason (and the session id) instead of a client timeout. + */ +export const AGENT_TOOL_DELIVERY_MS = 45_000; + export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { private readonly control: AgentControlService; private readonly plugins: Pick | null; @@ -131,6 +138,7 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { } private async spawn(orchestratorId: string, args: Record, signal?: AbortSignal): Promise> { + const deadline = Date.now() + AGENT_TOOL_DELIVERY_MS; if (!(AGENT_PROVIDERS as readonly unknown[]).includes(args.provider)) { throw orchestrationBridgeError("INVALID_REQUEST", unknownProviderMessage(args.provider), false); } @@ -165,7 +173,7 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { ...(args.model !== undefined ? { model: args.model as string } : {}), ...(args.effort !== undefined ? { effort: args.effort as SpawnAgentRequest["effort"] } : {}), profile: profile.profile - }, signal).catch((error: unknown) => { + }, signal, Math.max(0, deadline - Date.now())).catch((error: unknown) => { if (signal?.aborted) throw canceledError(); throw error; }); @@ -200,7 +208,8 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { args.sessionId as string, args.prompt as string, args.submit === undefined ? true : Boolean(args.submit), - signal + signal, + AGENT_TOOL_DELIVERY_MS ); } catch (error) { if (signal?.aborted) throw canceledError(); diff --git a/src/main/services/materials/HandoffService.ts b/src/main/services/materials/HandoffService.ts index 85abce3fe..dfafee2de 100644 --- a/src/main/services/materials/HandoffService.ts +++ b/src/main/services/materials/HandoffService.ts @@ -63,6 +63,8 @@ export interface HandoffImageOps { } interface HandoffTiming { + /** How long a paste waits for the agent's CLI to take input (OpenCode drops keys until its input field is up). */ + readyMs: number; attachMs: number; pasteMs: number; pollMs: number; @@ -114,7 +116,7 @@ type Checked = { ok: true; plan: HandoffPlan } | { ok: false; reason: HandoffBlo type Reserved = { ok: true; plan: HandoffPlan; screen: SessionScreen | null } | { ok: false; reason: HandoffBlock | MaterialFailure }; -const DEFAULT_TIMING: HandoffTiming = { attachMs: 8_000, pasteMs: 6_000, pollMs: 120 }; +const DEFAULT_TIMING: HandoffTiming = { readyMs: 15_000, attachMs: 8_000, pasteMs: 6_000, pollMs: 120 }; export class HandoffService { private readonly options: HandoffServiceOptions; @@ -508,7 +510,7 @@ export class HandoffService { const paste = async (data: string): Promise => { const error = this.deliveryError(plan, screen); if (error) return error; - const written = await this.options.terminals.deliverInput(id, `${PASTE_START}${data}${PASTE_END}`, 0); + const written = await this.options.terminals.deliverInput(id, `${PASTE_START}${data}${PASTE_END}`, this.timing.readyMs); return written.delivered ? null : written.reason; }; if (!screen) { @@ -553,7 +555,7 @@ export class HandoffService { ? failed(error) : { state: "pasted", note: "enter-failed", sentAt: this.now(), imagesAttached: attached, error }; this.submitting.set(plan.id, { sessionId: id, turnStartedAt: null }); - const submitted = await this.options.terminals.deliverInput(id, "\r", 0); + const submitted = await this.options.terminals.deliverInput(id, "\r", this.timing.readyMs); return submitted.delivered ? { state: "submitted", sentAt: this.now(), imagesAttached: attached } : { state: "pasted", note: "enter-failed", sentAt: this.now(), imagesAttached: attached, error: submitted.reason }; diff --git a/tests/helpers/terminal.mjs b/tests/helpers/terminal.mjs index c36d9d628..2747eb98f 100644 --- a/tests/helpers/terminal.mjs +++ b/tests/helpers/terminal.mjs @@ -25,6 +25,18 @@ export function availableRegistry() { * returns a fake PTY: `emitData`/`emitExit` drive its listeners, `lastResize` * holds the last size, and `onWrite(data, options)` sees what was written. */ +/** + * What OpenCode prints once its prompt has focus: the alternate screen, its hidden cursor while it draws, then the + * cursor shown in the input field (TerminalManager types queued input only after that for OpenCode). + */ +export const OPENCODE_INPUT_READY = "\x1b[?1049h\x1b[?2004h\x1b[?25l Ask anything\x1b[?25h"; + +/** Shows OpenCode's input field on the fake PTY OpenCode was spawned on, once that PTY exists. */ +export async function openCodeInputReady(calls, index = calls.length) { + for (let i = 0; i < 200 && calls.length <= index; i++) await new Promise((resolve) => setTimeout(resolve, 5)); + calls[index].process.emitData(OPENCODE_INPUT_READY); +} + export function fakeSpawner(calls, { pidBase = 20_000, onWrite } = {}) { return (command, args, options) => { let dataListener = () => undefined; @@ -53,3 +65,13 @@ export function fakeSpawner(calls, { pidBase = 20_000, onWrite } = {}) { return process; }; } + +/** fakeSpawner whose PTYs show OpenCode's input field shortly after they start (input waits for it for OpenCode). */ +export function inputReadySpawner(calls, options) { + const spawner = fakeSpawner(calls, options); + return (command, args, spawnOptions) => { + const process = spawner(command, args, spawnOptions); + setTimeout(() => process.emitData(OPENCODE_INPUT_READY), 10); + return process; + }; +} diff --git a/tests/launch-readiness.test.mjs b/tests/launch-readiness.test.mjs index b1aa64656..00716d505 100644 --- a/tests/launch-readiness.test.mjs +++ b/tests/launch-readiness.test.mjs @@ -14,9 +14,9 @@ import { controlRequest } from "../scripts/canvastty-control.mjs"; import { AgentControlService } from "../src/main/services/AgentControlService.ts"; import { LaunchPipeline } from "../src/main/services/LaunchPipeline.ts"; import { PluginSessions } from "../src/main/services/PluginSessions.ts"; -import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { INPUT_READY_HOOK_GRACE_MS, TerminalManager } from "../src/main/services/TerminalManager.ts"; import { AgentControlGateway } from "../src/main/services/agent-control/AgentControlGateway.ts"; -import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; +import { AGENT_TOOL_DELIVERY_MS, ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; const at = { x: 0, y: 0 }; const cwd = process.cwd(); @@ -209,3 +209,236 @@ test("the control CLI says a starting session is not ready instead of claiming t assert.equal(f.calls.length, 2); assert.deepEqual(f.calls[1].written, [], "the refused send was not queued"); }); + +// OpenCode drops every key that arrives while its full-screen view starts, so a prompt typed when its PTY exists is +// lost and the agent sits at an empty prompt. Its prompt goes in only once its input field is up: a lifecycle hook, +// or the control sequence that shows its text cursor on the alternate screen (never its human-readable screen text). + +const ALT_SCREEN_HIDDEN_CURSOR = "\x1b[?1049h\x1b[?2004h\x1b[?25l"; +const CURSOR_SHOWN = "\x1b[1 q\x1b[?25h"; + +/** + * A slow-starting OpenCode stand-in: it draws its start-up for `startupMs` with the cursor hidden and drops every key + * written meanwhile (as OpenCode does), then shows its input field. `accepted` holds what reached that field. + */ +function slowOpenCode({ startupMs = 120, ready = true } = {}) { + const runs = []; + const spawn = () => { + let emit = () => undefined; + const exits = []; + const run = { written: [], accepted: [], dropped: [], ready: false, exit: (code) => exits.forEach((listener) => listener({ exitCode: code })) }; + runs.push(run); + setTimeout(() => emit(ALT_SCREEN_HIDDEN_CURSOR), 5); + setTimeout(() => emit(" Ask anything… \"Fix broken tests\" tab agents ctrl+p commands"), startupMs / 2); + if (ready) setTimeout(() => { run.ready = true; emit(CURSOR_SHOWN); }, startupMs); + return { + pid: 70_000 + runs.length, process: "opencode", resize() {}, kill() {}, pause() {}, resume() {}, + write(text) { run.written.push(text); (run.ready ? run.accepted : run.dropped).push(text); }, + onData(listener) { emit = listener; return { dispose() {} }; }, + onExit(listener) { exits.push(listener); return { dispose() {} }; } + }; + }; + return { runs, spawn }; +} + +function slowOpenCodeOrchestration(t, options) { + const cli = slowOpenCode(options); + let orchestratorStarted = false; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, (...args) => { + if (!orchestratorStarted) { orchestratorStarted = true; return spawner([])(...args); } + return cli.spawn(...args); + }); + t.after(() => terminals.disposeAll()); + const control = new AgentControlService(terminals); + const handler = new ScopedOrchestrationHandler(control); + const orchestrator = terminals.create({ provider: "codex", profile: "normal", cwd, position: at, role: "orchestrator" }); + return { cli, terminals, control, execute: (tool, args) => handler.execute(orchestrator.id, { tool, arguments: args }) }; +} + +test("spawn_agent: a slow-starting OpenCode gets its first prompt once its input field is up, exactly once", async (t) => { + const f = slowOpenCodeOrchestration(t, { startupMs: 150 }); + const spawned = f.execute("spawn_agent", { provider: "opencode", cwd, prompt: "do part A" }); + await new Promise((resolve) => setTimeout(resolve, 100)); + assert.equal(await state(spawned), "pending", "the PTY exists and the home screen text is drawn, but the field is not up"); + assert.deepEqual(f.cli.runs[0].written, []); + const result = await spawned; + assert.equal(typeof result.sessionId, "string"); + assert.deepEqual(f.cli.runs[0].accepted, ["do part A\r"], "the prompt reached the input field"); + assert.deepEqual(f.cli.runs[0].dropped, [], "nothing was typed while OpenCode started"); + + // send_to_agent to the running card goes in at once. + assert.deepEqual(await f.execute("send_to_agent", { sessionId: result.sessionId, prompt: "now part B" }), { sessionId: result.sessionId, sent: true }); + assert.deepEqual(f.cli.runs[0].accepted, ["do part A\r", "now part B\r"]); +}); + +test("spawn_agent: an OpenCode that exits before its input field is up fails the call with the reason", async (t) => { + const f = slowOpenCodeOrchestration(t, { ready: false }); + const spawned = f.execute("spawn_agent", { provider: "opencode", cwd, prompt: "never typed" }); + await tick(); + f.cli.runs[0].exit(1); + await assert.rejects(spawned, (error) => { + assert.match(error.bridgeError?.message ?? "", /was not delivered: The session/u); + return true; + }); + assert.deepEqual(f.cli.runs[0].written, []); +}); + +test("OpenCode that never shows its input field gets no prompt and a bounded reason", async (t) => { + const cli = slowOpenCode({ ready: false }); + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, cli.spawn); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + const started = Date.now(); + const result = await terminals.deliverInput(session.id, "never\r", 200); + assert.equal(result.delivered, false); + assert.match(result.reason, /did not show its input field within 200 ms; nothing was typed/u); + assert.ok(Date.now() - started < 1_000); + assert.deepEqual(cli.runs[0].written, [], "its home screen text alone is not readiness"); +}); + +test("OpenCode readiness: a cursor shown before the alternate screen does not count; one cut across chunks does", async (t) => { + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, (command, args, options) => { + const pty = spawner(calls)(command, args, options); + return { ...pty, onData(listener) { calls.at(-1).emit = listener; return { dispose() {} }; } }; + }); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + const pending = terminals.deliverInput(session.id, "split\r", 2_000); + calls[0].emit("\x1b[?25h"); + calls[0].emit("\x1b[?104"); + calls[0].emit("9h\x1b[?25l drawing"); + await tick(); + assert.deepEqual(calls[0].written, []); + calls[0].emit("\x1b[?2"); + await tick(); + assert.deepEqual(calls[0].written, []); + calls[0].emit("5h"); + assert.deepEqual(await pending, { delivered: true }); + assert.deepEqual(calls[0].written, ["split\r"]); +}); + +test("OpenCode readiness: a lifecycle hook counts only after a grace, and sends made while it starts arrive in order", async (t) => { + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, spawner(calls)); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + const first = terminals.deliverInput(session.id, "first\r", INPUT_READY_HOOK_GRACE_MS + 2_000); + const second = terminals.deliverInput(session.id, "second\r", INPUT_READY_HOOK_GRACE_MS + 2_000); + await tick(); + assert.deepEqual(calls[0].written, []); + const hookAt = Date.now(); + terminals.applyProviderSignal(session.id, { kind: "lifecycle", state: "idle", event: "session.created" }); + await new Promise((resolve) => setTimeout(resolve, 200)); + assert.deepEqual(calls[0].written, [], "a hook alone is not the input field"); + assert.deepEqual([await first, await second], [{ delivered: true }, { delivered: true }]); + assert.ok(Date.now() - hookAt >= INPUT_READY_HOOK_GRACE_MS - 20, "typed only after the grace"); + assert.deepEqual(calls[0].written, ["first\r", "second\r"]); +}); + +test("OpenCode readiness: a resumed card whose plugin reports before its input field is up gets the text on the cursor signal", async (t) => { + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, (command, args, options) => { + const pty = spawner(calls)(command, args, options); + return { ...pty, onData(listener) { calls.at(-1).emit = listener; return { dispose() {} }; } }; + }); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + calls[0].emit("\x1b[?1049h\x1b[?25l"); + // The plugin reports idle on session.updated about 0.6 s before typed keys reach the prompt. + terminals.applyProviderSignal(session.id, { kind: "lifecycle", state: "idle", event: "session.updated" }); + const sent = terminals.deliverInput(session.id, "resumed\r", 5_000); + await new Promise((resolve) => setTimeout(resolve, 300)); + assert.deepEqual(calls[0].written, [], "not typed on the hook"); + const shownAt = Date.now(); + calls[0].emit("\x1b[?25h"); + assert.deepEqual(await sent, { delivered: true }); + assert.ok(Date.now() - shownAt < INPUT_READY_HOOK_GRACE_MS / 2, "typed on the cursor signal, not after the grace"); + assert.deepEqual(calls[0].written, ["resumed\r"]); +}); + +test("OpenCode readiness: a send cancelled while it waits behind another settles at once and is never typed", async (t) => { + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, (command, args, options) => { + const pty = spawner(calls)(command, args, options); + return { ...pty, onData(listener) { calls.at(-1).emit = listener; return { dispose() {} }; } }; + }); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + const first = terminals.deliverInput(session.id, "first\r", 5_000); + const controller = new AbortController(); + const queued = terminals.deliverInput(session.id, "queued\r", 5_000, controller.signal); + const third = terminals.deliverInput(session.id, "third\r", 5_000); + await tick(); + const abortedAt = Date.now(); + controller.abort(); + assert.deepEqual(await queued, { delivered: false, reason: "The delivery was cancelled." }); + assert.ok(Date.now() - abortedAt < 200, "settled without waiting for the send ahead of it"); + calls[0].emit("\x1b[?1049h\x1b[?25h"); + assert.deepEqual([await first, await third], [{ delivered: true }, { delivered: true }]); + assert.deepEqual(calls[0].written, ["first\r", "third\r"]); +}); + +test("OpenCode readiness is not awaited on Windows, whose pseudo console may not pass the cursor sequences", async (t) => { + const platform = Object.getOwnPropertyDescriptor(process, "platform"); + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, spawner(calls)); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + Object.defineProperty(process, "platform", { ...platform, value: "win32" }); + try { + assert.deepEqual(await terminals.deliverInput(session.id, "windows\r", 200), { delivered: true }); + } finally { + Object.defineProperty(process, "platform", platform); + } + assert.deepEqual(calls[0].written, ["windows\r"]); +}); + +test("spawn_agent and send_to_agent wait for delivery within a budget under the MCP client's deadline", async (t) => { + assert.ok(AGENT_TOOL_DELIVERY_MS <= 45_000); + const f = slowOpenCodeOrchestration(t, { ready: false }); + const waits = []; + const { control } = f; + const spawn = control.spawn.bind(control); + control.spawn = (request, signal, promptWaitMs) => { waits.push(["spawn", promptWaitMs]); return spawn(request, signal, 150); }; + const send = control.send.bind(control); + control.send = (id, text, submit, signal, waitMs) => { waits.push(["send", waitMs]); return send(id, text, submit, signal, 150); }; + await assert.rejects(f.execute("spawn_agent", { provider: "opencode", cwd, prompt: "late" }), (error) => { + assert.match(error.bridgeError?.message ?? "", /did not show its input field within 150 ms; nothing was typed/u); + return true; + }); + const [child] = f.terminals.listMetadata().filter((session) => session.role === "subagent"); + await assert.rejects(f.execute("send_to_agent", { sessionId: child.id, prompt: "again" })); + assert.equal(waits[0][0], "spawn"); + assert.ok(waits[0][1] > 0 && waits[0][1] <= AGENT_TOOL_DELIVERY_MS, String(waits[0][1])); + assert.deepEqual(waits[1], ["send", AGENT_TOOL_DELIVERY_MS]); +}); + +test("OpenCode readiness: cancellation and a restart while it starts never deliver the queued text", async (t) => { + const cli = slowOpenCode({ startupMs: 80 }); + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, cli.spawn); + t.after(() => terminals.disposeAll()); + const session = terminals.create({ provider: "opencode", profile: "normal", cwd, position: at }); + const controller = new AbortController(); + const canceled = terminals.deliverInput(session.id, "cancel\r", 2_000, controller.signal); + const replaced = terminals.deliverInput(session.id, "old launch\r", 2_000); + controller.abort(); + assert.deepEqual(await canceled, { delivered: false, reason: "The delivery was cancelled." }); + cli.runs[0].exit(0); + terminals.restart(session.id); + assert.equal((await replaced).delivered, false); + await new Promise((resolve) => setTimeout(resolve, 150)); + assert.ok(cli.runs[1].ready, "the new launch became ready"); + assert.ok(cli.runs.every((run) => run.written.length === 0), "neither launch got the text"); +}); + +test("Claude and Codex still get input as soon as their PTY exists", async (t) => { + const calls = []; + const terminals = new TerminalManager(() => {}, clis(), undefined, undefined, true, spawner(calls)); + t.after(() => terminals.disposeAll()); + for (const provider of ["claude", "codex"]) { + const session = terminals.create({ provider, profile: "normal", cwd, position: at }); + assert.deepEqual(await terminals.deliverInput(session.id, `${provider} task\r`, 200), { delivered: true }); + } + assert.deepEqual(calls.map((call) => call.written), [["claude task\r"], ["codex task\r"]]); +}); diff --git a/tests/material-handoff-service.test.mjs b/tests/material-handoff-service.test.mjs index 141e452a4..8ce26e6e3 100644 --- a/tests/material-handoff-service.test.mjs +++ b/tests/material-handoff-service.test.mjs @@ -979,3 +979,19 @@ test("a delivered handoff says when the outcome could not be saved", async () => await rm(blocked, { recursive: true }); }); }); + +test("a handoff waits for the agent's CLI to take input instead of failing at once", async () => { + await withHandoffs(async ({ handoffs, terminal, draft }) => { + terminal.add({ provider: "claude", id: "s1" }); + terminal.tui = claudeTui(terminal); + const waits = []; + const deliverInput = terminal.deliverInput.bind(terminal); + terminal.deliverInput = async (id, data, waitMs) => { + waits.push(waitMs); + return deliverInput(id, data); + }; + assert.equal((await handoffs.send(draft("s1"))).handoff.delivery.state, "submitted"); + assert.ok(waits.length >= 2, "the paste and its Enter"); + assert.ok(waits.every((waitMs) => waitMs >= 10_000), `waits: ${waits.join(", ")}`); + }); +}); diff --git a/tests/opencode-result.test.mjs b/tests/opencode-result.test.mjs index 1355f842a..9689b60a6 100644 --- a/tests/opencode-result.test.mjs +++ b/tests/opencode-result.test.mjs @@ -10,7 +10,7 @@ import { RuntimeGateway } from "../src/main/services/agent-runtime/RuntimeGatewa import { TerminalManager } from "../src/main/services/TerminalManager.ts"; import { AgentControlService } from "../src/main/services/AgentControlService.ts"; import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; -import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; +import { availableRegistry, fakeSpawner, openCodeInputReady } from "./helpers/terminal.mjs"; const POSIX = { skip: process.platform === "win32" ? "Unix socket test; the Windows pipe transport has its own suite." : false }; @@ -147,11 +147,14 @@ test("an ordinary OpenCode card (not a subagent) never keeps an answer", async ( test("wait_for_agent ignores an idle before the prompt's turn and returns that turn's answer", async (t) => { const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-ocr-"))); t.after(() => rm(root, { recursive: true, force: true })); - const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner([])); + const calls = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); t.after(() => terminals.disposeAll()); const orchestrator = terminals.create({ provider: "codex", cwd: root, profile: "normal", position: { x: 0, y: 0 }, role: "orchestrator" }); const handler = new ScopedOrchestrationHandler(new AgentControlService(terminals, { waitTiming: { checkMs: 5, settleMs: 10, quietMs: 60_000 } })); - const child = await handler.execute(orchestrator.id, { id: "1", tool: "spawn_agent", arguments: { provider: "opencode", cwd: root, prompt: "do part A" } }); + const spawning = handler.execute(orchestrator.id, { id: "1", tool: "spawn_agent", arguments: { provider: "opencode", cwd: root, prompt: "do part A" } }); + await openCodeInputReady(calls, 1); + const child = await spawning; const wait = (timeoutSeconds) => handler.execute(orchestrator.id, { id: "w", tool: "wait_for_agent", arguments: { sessionId: child.sessionId, timeoutSeconds } }); // OpenCode's session.created reports idle before the prompt's turn starts. terminals.applyProviderSignal(child.sessionId, { kind: "lifecycle", state: "idle", event: "session.created" }); diff --git a/tests/orchestration-providers-wait.test.mjs b/tests/orchestration-providers-wait.test.mjs index ebe189141..7bfc7357d 100644 --- a/tests/orchestration-providers-wait.test.mjs +++ b/tests/orchestration-providers-wait.test.mjs @@ -261,7 +261,7 @@ test("after a prompt, an idle before the turn starts does not end wait_for_agent const { tmpdir } = await import("node:os"); const { join } = await import("node:path"); const { TerminalManager } = await import("../src/main/services/TerminalManager.ts"); - const { availableRegistry, fakeSpawner } = await import("./helpers/terminal.mjs"); + const { availableRegistry, fakeSpawner, openCodeInputReady } = await import("./helpers/terminal.mjs"); const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-turn-"))); t.after(() => rm(root, { recursive: true, force: true })); const calls = []; @@ -277,7 +277,9 @@ test("after a prompt, an idle before the turn starts does not end wait_for_agent terminals.applyProviderSignal(idleChild.sessionId, { kind: "lifecycle", state: "idle" }); assert.equal((await handler.execute(orchestrator.id, { id: "i", tool: "wait_for_agent", arguments: { sessionId: idleChild.sessionId } })).reason, "idle"); - const child = await handler.execute(orchestrator.id, { id: "1", tool: "spawn_agent", arguments: { provider: "opencode", cwd: root, prompt: "do part A" } }); + const spawning = handler.execute(orchestrator.id, { id: "1", tool: "spawn_agent", arguments: { provider: "opencode", cwd: root, prompt: "do part A" } }); + await openCodeInputReady(calls, 2); + const child = await spawning; // The CLI's startup idle arrives after the prompt was typed but before its turn starts. terminals.applyProviderSignal(child.sessionId, { kind: "lifecycle", state: "idle" }); const early = await wait(1); diff --git a/tests/subagent-model-account.test.mjs b/tests/subagent-model-account.test.mjs index a10150fba..d6e91c98f 100644 --- a/tests/subagent-model-account.test.mjs +++ b/tests/subagent-model-account.test.mjs @@ -8,7 +8,7 @@ import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/O import { LaunchPipeline, modelSettingArgument } from "../src/main/services/LaunchPipeline.ts"; import { TerminalManager } from "../src/main/services/TerminalManager.ts"; import { TerminalSessionStore } from "../src/main/services/TerminalSessionStore.ts"; -import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; +import { availableRegistry, inputReadySpawner } from "./helpers/terminal.mjs"; // A subagent spawned without launch options once ran on its CLI's own default model (for OpenCode the hosted OpenCode // Zen model), while its orchestrator ran on a model the person picked through a plugin (a model account). It now keeps @@ -29,7 +29,7 @@ async function setup(t, { delegable = true, store } = {}) { const prepared = []; // What the person can change while the orchestrator runs: turn a plugin off, or a plugin update changes its fields. const state = { gone: new Set(), extrasFields: [{ key: "flavor", label: "Flavor", kind: "text" }] }; - const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, inputReadySpawner(calls)); t.after(() => store ? terminals.shutdown() : terminals.disposeAll()); terminals.configureLaunchPipeline(new LaunchPipeline({ contributors: () => [ From 1cb4ba99c183a76e1530246a73a792b441720b73 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 11:52:05 +0000 Subject: [PATCH 6/9] fix(orchestration): return wait_for_agent before the MCP client gives up wait_for_agent accepted up to 600 seconds, but the MCP clients of several supported CLIs (OpenCode among them) end a tool call after about 60 seconds, so an orchestrator that asked for a long wait got a failed call instead of a result. A call now asks for at most 100 seconds (default 50). Unless the orchestrator's CLI is known to let a tool call run longer, a call returns after at most 50 seconds. A timeout carries the status and the masked output as progress plus a message to call again, and the tool description in both catalogs, the orchestrator skill and the docs say that a timeout means the subagent is still running. --- agent/orchestrator/SKILL.md | 2 +- docs/agent-orchestration.md | 2 +- native/canvastty-helper/catalog.json | 6 ++-- src/agent-browser/orchestration-catalog.d.mts | 1 + src/agent-browser/orchestration-catalog.mjs | 13 ++++--- .../agent-browser/OrchestrationTools.ts | 8 +++-- tests/orchestration-providers-wait.test.mjs | 36 ++++++++++++++++--- 7 files changed, 51 insertions(+), 17 deletions(-) diff --git a/agent/orchestrator/SKILL.md b/agent/orchestrator/SKILL.md index bf67517c7..fbcc2fbf4 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` a subagent of your own CLI keeps your plugin launch options (for example your model account), and any other CLI uses its own default. A plugin you do not name in `launchOptions` keeps your own values; passing `model` next to inherited options that already set the model is refused, and a subagent of another CLI is refused while your model comes from a plugin's options (spawn one of your own CLI instead). The answer's `servedBy` names the CLI, the model asked for, and whether each plugin's options were `inherited` or `explicit`. `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 100; 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 a34f2d6fd..c6373cd92 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`. Plugin launch options the call does not name are inherited from the orchestrator for a subagent of the same CLI (see Plugin launch options below); `model` next to inherited options that set the model is refused, and so is a subagent of another CLI while the orchestrator's model comes from a plugin's options. The answer's `servedBy` is `{ provider, model, launchOptions: { : "inherited" | "explicit" } }`. 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 ≤ 100 }` (default 50). 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 `output` and a `message` to call again. 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. Prompts to one subagent arrive in the order they were sent. OpenCode drops keys typed while it starts, so a prompt for it (also `spawn_agent`'s first one) is typed only once its input field is up: the terminal control sequence that shows its text cursor on its full screen, or a lifecycle hook only 2 s after its first one (OpenCode's plugin can report shortly before the field takes keys). This wait is used on macOS and Linux; on Windows, whose pseudo console may not pass those sequences, OpenCode gets input as soon as its PTY exists, as before. `spawn_agent` (its checks, the launch and this wait together) and `send_to_agent` wait at most 45 s, under the MCP client's tool deadline; then the call fails with the reason and the session id, and nothing is typed. A send cancelled while it waits returns at once. | diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index 4622e41c8..faf93a3c1 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -1095,7 +1095,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 50, at most 100; 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": { @@ -1107,7 +1107,7 @@ "timeoutSeconds": { "type": "integer", "minimum": 1, - "maximum": 600 + "maximum": 100 } }, "required": [ @@ -1178,6 +1178,6 @@ ], "maxPluginToolNameLength": 64, "maxLaunchOptionsBytes": 16384, - "defaultAgentWaitSeconds": 55 + "defaultAgentWaitSeconds": 50 } } 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 e48ea3de6..c57119e81 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -28,10 +28,13 @@ const prompt = string({ minLength: 1, maxLength: 65_536 }); export const AGENT_PROVIDER_IDS = Object.freeze([ "codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok", "omp", "pi", "cursor", "minimax", "devin", "antigravity" ]); -/** wait_for_agent: the longest wait one call may ask for, and the wait without timeoutSeconds (some MCP clients - * end a tool call after 60 seconds). */ -export const MAX_AGENT_WAIT_SECONDS = 600; -export const DEFAULT_AGENT_WAIT_SECONDS = 55; +/** wait_for_agent: the longest wait one call may ask for, and the wait without timeoutSeconds. Most MCP clients end a + * tool call after 60 seconds (Codex's default tool_timeout_sec, OpenCode's client), so a call from any orchestrator + * but Claude Code (whose client waits far longer) returns after at most CLIENT_SAFE_AGENT_WAIT_SECONDS: a "timeout" + * that says the subagent still runs, never a call its client cut off. */ +export const MAX_AGENT_WAIT_SECONDS = 100; +export const DEFAULT_AGENT_WAIT_SECONDS = 50; +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 +88,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 3052d95bf..71c8cb54f 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -6,6 +6,7 @@ import { PromptNotDeliveredError, type AgentControlService, type SpawnAgentReque 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, @@ -125,12 +126,15 @@ 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 }; + return { ...result, ...(result.reason === "timeout" + ? { message: "Still running. Read output for its progress and call wait_for_agent again." } : {}) }; } catch (error) { if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) throw canceledError(); throw error; diff --git a/tests/orchestration-providers-wait.test.mjs b/tests/orchestration-providers-wait.test.mjs index 7bfc7357d..bd7c6380a 100644 --- a/tests/orchestration-providers-wait.test.mjs +++ b/tests/orchestration-providers-wait.test.mjs @@ -2,6 +2,8 @@ import assert from "node:assert/strict"; import test from "node:test"; import { AGENT_PROVIDER_IDS, + CLIENT_SAFE_AGENT_WAIT_SECONDS, + DEFAULT_AGENT_WAIT_SECONDS, MAX_AGENT_WAIT_SECONDS, ORCHESTRATION_TOOL_DEFINITIONS, ORCHESTRATION_TOOL_NAMES, @@ -22,10 +24,14 @@ test("the catalog lists list_providers first and wait_for_agent with a bounded t assert.deepEqual(definition("list_providers").inputSchema, { type: "object", properties: {}, required: [], additionalProperties: false }); const wait = definition("wait_for_agent").inputSchema; assert.deepEqual(wait.required, ["sessionId"]); - assert.equal(wait.properties.timeoutSeconds.maximum, 600); - assert.equal(MAX_AGENT_WAIT_SECONDS, 600); - assert.equal(validateOrchestrationArguments("wait_for_agent", { sessionId: "a", timeoutSeconds: 600 }).ok, true); - assert.match(validateOrchestrationArguments("wait_for_agent", { sessionId: "a", timeoutSeconds: 601 }).error, /above the maximum/u); + assert.equal(wait.properties.timeoutSeconds.maximum, 100); + assert.equal(MAX_AGENT_WAIT_SECONDS, 100); + assert.ok(DEFAULT_AGENT_WAIT_SECONDS <= CLIENT_SAFE_AGENT_WAIT_SECONDS && CLIENT_SAFE_AGENT_WAIT_SECONDS < 60, + "a call without timeoutSeconds, and every call from a 60-second MCP client, ends before that client gives up"); + assert.equal(validateOrchestrationArguments("wait_for_agent", { sessionId: "a", timeoutSeconds: 100 }).ok, true); + assert.match(validateOrchestrationArguments("wait_for_agent", { sessionId: "a", timeoutSeconds: 101 }).error, /above the maximum/u); + assert.match(definition("wait_for_agent").description, /at most 100; 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); assert.equal(validateOrchestrationArguments("list_providers", {}).ok, true); assert.match(validateOrchestrationArguments("list_providers", { x: 1 }).error, /Unexpected argument/u); assert.match(definition("list_providers").description, /Never search the filesystem/u); @@ -217,7 +223,7 @@ test("wait_for_agent stops at once when the call is canceled", async () => { const controller = new AbortController(); const started = Date.now(); setTimeout(() => controller.abort(), 20); - await assert.rejects(call(handler, "wait_for_agent", { sessionId: "child", timeoutSeconds: 600 }, controller.signal), + await assert.rejects(call(handler, "wait_for_agent", { sessionId: "child", timeoutSeconds: 100 }, controller.signal), (error) => error.bridgeError?.code === "CANCELED"); assert.ok(Date.now() - started < 1_000); const aborted = new AbortController(); @@ -305,3 +311,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 that says the agent still runs", async () => { + for (const [provider, requested, expectedMs] of [ + ["opencode", 100, 50_000], ["codex", 100, 50_000], ["opencode", undefined, 50_000], ["opencode", 20, 20_000], ["claude", 100, 100_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.match(result.message, /Still running\. Read output for its progress and call wait_for_agent again\./u); + } + const { terminals, handler } = setup(); + terminals.sessions.get("child").status = "idle"; + assert.equal((await call(handler, "wait_for_agent", { sessionId: "child" })).message, undefined, "only a timeout says to call again"); +}); From 93b5347960848f94748bf2e56c8d7c8ee4505efa Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 12:10:28 +0000 Subject: [PATCH 7/9] fix(agents): tie subagent answers to their turn and say when hooks are off A Codex or OpenCode subagent's final answer could belong to an earlier turn: OpenCode reused its session id as the turn id and reported idle before its asynchronous answer read finished, and recordAnswer accepted any answer. OpenCode now names each turn, reports no idle before the answer is read and drops a read a newer turn superseded; retry counts as a turn start. A submitted input (not an approval answer, not an empty Enter in an idle card) starts a new task, and only an answer of the turn that answers it is kept. A signal of that turn which predates the input still moves the status, so wait_for_agent ends instead of hanging, but brings no answer. An answer reported as the agent exits still counts. main's signal glue is now applyRuntimeSignal, shared with the tests. With CanvasTTY status hooks off a launch gets no hooks, so no answer can be captured. Whether a launch has them is decided when it is planned (deferred plugin launches included). wait_for_agent and get_agent_result then return answerUnavailable { reason: "status_hooks_off", message } so the orchestrator reads the output instead. Every write of person or agent input now goes through one method, writeInput, which does this bookkeeping; input() and deliverInput call it, and a later writer that holds input and replays it must call it too, so a replayed Enter counts as a submitted prompt. It writes nothing into a process the card no longer runs. --- docs/ARCHITECTURE.md | 2 +- docs/ARCHITECTURE.ru.md | 2 +- docs/ARCHITECTURE.zh-CN.md | 2 +- docs/agent-orchestration.md | 4 +- native/canvastty-helper/catalog.json | 4 +- src/agent-browser/orchestration-catalog.mjs | 4 +- src/agent-runtime/opencode-plugin.mjs | 39 +- src/main/index.ts | 11 +- src/main/services/AgentControlService.ts | 26 +- src/main/services/TerminalManager.ts | 131 ++++++- .../agent-browser/OrchestrationTools.ts | 3 +- .../services/agent-runtime/RuntimeGateway.ts | 3 +- .../agent-runtime/applyRuntimeSignal.ts | 22 ++ tests/agent-runtime-provider-launch.test.mjs | 22 ++ tests/opencode-result.test.mjs | 365 +++++++++++++++++- tests/runtime-result-transport.test.mjs | 129 +++++++ tests/terminal-lifecycle.test.mjs | 35 +- 17 files changed, 729 insertions(+), 75 deletions(-) create mode 100644 src/main/services/agent-runtime/applyRuntimeSignal.ts create mode 100644 tests/runtime-result-transport.test.mjs diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index aa004a203..218c35143 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -70,7 +70,7 @@ Electron main process - `src/main/services/BrowserService.ts` is the only owner of the built-in browser's `WebContentsView` tabs and shared persistent partition. Remote pages have no preload or Node access, keep context isolation and sandbox enabled, and cannot request hardware, location, notification, clipboard-read, certificate-bypass, or external-protocol capabilities. HTTP(S) popups are adopted as internal tabs; other schemes are rejected. - `src/main/services/browser/` contains the browser kernel. `BrowserStore` atomically persists only tab order, active tab, and safe restore URLs. `BrowserPolicyService` centralizes URL, permission, download, and upload rules; validated uploads are copied through an already-open no-follow file descriptor into private staging before Chromium sees them. `BrowserAutomationService` attaches Electron's internal debugger to the existing live tab without a remote-debugging port. `BrowserCommandDispatcher` adds revisions, revision-bound refs, mutation request deduplication, per-tab FIFO mutation lanes, bounded concurrency, typed errors, and redacted fail-closed audit for agent mutations. - `src/main/services/agent-browser/` exposes the kernel only through an authenticated user-local Unix socket (`0600`) or Windows named pipe. The Windows pipe is created by the bundled native host with a protected DACL containing only the exact current-user SID and rejects remote clients. Each agent PTY receives a one-use bootstrap capability through its child environment. A successful authentication rotates it to a session-scoped reconnect capability held only in helper memory; duplicate bootstrap authentication is accepted only while the same `connectionId` is already live, and every capability is revoked when the PTY ends. The bundled stdio MCP helper is the only protocol adapter; no TCP listener, cookie/storage endpoint, arbitrary evaluation tool, or raw CDP surface exists. -- `src/main/services/agent-runtime/` is a separate lifecycle boundary and is not controlled by the Browser access switch. When CanvasTTY status hooks are enabled, every agent PTY receives a distinct capability for a protected user-local socket/pipe. Provider command hooks and the OpenCode event plugin may report only the fixed status enum, bounded event name, and optional opaque turn/prompt ID; prompt text, responses, tool input, and arbitrary telemetry are rejected by the exact gateway schema. On macOS and Linux the helpers are the native `canvastty-helper` (`native/canvastty-helper`, Go, standard library only; subcommands `mcp-browser`, `mcp-orchestration`, `permission-gate`, `hook`), which speaks exactly the wire protocols of the `.mjs` helpers (`tests/native-helper-*-parity.test.mjs` run both) without an Electron-as-Node process per agent and per tool call; `src/main/services/agentHelpers.ts` falls back to the `.mjs` helpers when the binary is absent, on Windows, or with `CANVASTTY_HELPERS=node`. Electron helper commands carry `ELECTRON_RUN_AS_NODE=1` inside the exact hook command only; the provider PTY never inherits that process-mode flag, so a provider cannot accidentally launch a second CanvasTTY GUI instance. The user can revoke this capability from Agents settings, immediately returning live agent status to `unavailable`; re-enabling requires a new/restarted PTY. Explicitly trusted plugin hooks use a separate process runner which re-checks the private PluginManager registry on every invocation and strips CanvasTTY internal capabilities before passing the provider payload to third-party code. Provider-native review remains an independent gate; CanvasTTY does not bypass Codex hook trust globally. +- `src/main/services/agent-runtime/` is a separate lifecycle boundary and is not controlled by the Browser access switch. When CanvasTTY status hooks are enabled, every agent PTY receives a distinct capability for a protected user-local socket/pipe. Provider command hooks and the OpenCode event plugin may report only the fixed status enum, bounded event name, and optional opaque turn/prompt ID; prompt text, responses, tool input, and arbitrary telemetry are rejected by the exact gateway schema. On macOS and Linux the helpers are the native `canvastty-helper` (`native/canvastty-helper`, Go, standard library only; subcommands `mcp-browser`, `mcp-orchestration`, `permission-gate`, `hook`), which speaks exactly the wire protocols of the `.mjs` helpers (`tests/native-helper-*-parity.test.mjs` run both) without an Electron-as-Node process per agent and per tool call; `src/main/services/agentHelpers.ts` falls back to the `.mjs` helpers when the binary is absent, on Windows, or with `CANVASTTY_HELPERS=node`. Electron helper commands carry `ELECTRON_RUN_AS_NODE=1` inside the exact hook command only; the provider PTY never inherits that process-mode flag, so a provider cannot accidentally launch a second CanvasTTY GUI instance. The user can revoke this capability from Agents settings, immediately returning live agent status to `unavailable`; re-enabling requires a new/restarted PTY. Explicitly trusted plugin hooks use a separate process runner which re-checks the private PluginManager registry on every invocation and strips CanvasTTY internal capabilities before passing the provider payload to third-party code. Provider-native review remains an independent gate; CanvasTTY does not bypass Codex hook trust globally. A Codex or OpenCode subagent's final answer (Codex `Stop` hook, the OpenCode plugin at `session.idle`) travels on the same hooks, so it exists only while status hooks are on for that launch: whether a launch has them is decided when it is planned (a deferred plugin launch included), and a launch planned with them off has no lease and no lifecycle hooks at all. `wait_for_agent` and `get_agent_result` then return `answerUnavailable: { reason: "status_hooks_off", message }` and the orchestrator reads the output instead. An answer is kept only for its own turn (`src/main/services/agent-runtime/applyRuntimeSignal.ts`, the glue main runs for each signal): OpenCode names each turn, a submitted input other than an approval answer or an empty Enter in an idle card starts a new one, and a signal of the current turn that predates that input still ends the wait but brings no answer. - Lifecycle adapters use launch-only settings for Claude, Codex, Qwen, and OpenCode. Kimi, Hermes, and Grok, whose hook discovery is home-config based, receive ownership-checked temporary entries shared across live CanvasTTY sessions. Kimi and Hermes keep recovery journals and exact backups; Grok uses a dedicated owned hook file. Cleanup restores exact original bytes when no concurrent edit occurred and otherwise removes only CanvasTTY-owned entries. - `TerminalManager` injects the MCP helper per launch without leaving permanent provider configuration. Claude Code, Codex, and Qwen Code receive CLI arguments; Qwen gets one inline `--mcp-config` entry that overrides only the CanvasTTY server name and leaves unrelated user servers available. OpenCode receives a merged launch-only `OPENCODE_CONFIG_CONTENT` entry plus one scoped browser-tool permission; Kimi uses its per-run MCP configuration when supported. Older Kimi versions receive a compare-and-swap temporary CanvasTTY entry and one exact permission rule with an atomic recovery journal. Hermes receives a temporary `mcp_servers.canvastty_browser` entry in `HERMES_HOME/config.yaml` (defaulting to `~/.hermes/config.yaml` on POSIX or `%LOCALAPPDATA%\hermes\config.yaml` on Windows); sensitive capability values stay as child-environment placeholders. Temporary Kimi and Hermes configuration remains until the final owning PTY session ends, then exact original bytes are restored when safe. A journal repairs an interrupted Hermes launch at the next CanvasTTY startup, while compare-and-swap checks preserve concurrent user edits. Unrelated MCP entries, credentials, and file/shell permissions are preserved. Qwen, OpenCode, and Hermes YOLO remain launch-only and do not change persistent permission settings. - `src/main/services/providerCliRegistry.ts` is the single owner of provider CLI discovery. During main-process startup it creates a shared snapshot for every provider in `PROVIDER_CLI_DEFINITIONS` — each definition declares the executable command names it may install as (which may differ from the provider ID, e.g. a provider shipping as `mcode`) and optional known home-relative or Windows LOCALAPPDATA-relative directories — by checking smoke-only overrides, the inherited `PATH`, platform defaults, and those known directories in that order. Available entries retain an absolute executable, launcher kind, and supplemented child `PATH`; POSIX entries must be executable files and Windows entries must be supported native or batch launchers. `TerminalManager`, `LimitsService`, agent-browser probes, and provider smoke tests consume that same snapshot and never repeat command lookup. Missing entries produce a failed session with copyable checked-path diagnostics before PTY or temporary browser configuration creation, while the limit adapter reports `cli-not-found`; its HOME row is hidden until explicitly selected after CLI detection. Launchers keep a provider without a local CLI visible when an account bound to a remote computer or a saved container profile provides another route. CanvasTTY never reads shell startup scripts. Agents settings can recheck candidate paths, atomically replace the registry snapshot, reconcile saved launcher and limit selections, and refresh CLI-bound adapters without restarting the app. Existing sessions keep running; a newly found CLI remains disabled until selected. diff --git a/docs/ARCHITECTURE.ru.md b/docs/ARCHITECTURE.ru.md index ae66a88d0..d7e0054a4 100644 --- a/docs/ARCHITECTURE.ru.md +++ b/docs/ARCHITECTURE.ru.md @@ -48,7 +48,7 @@ Electron main process - `src/main/services/PluginSecretsService.ts` сериализует запись секретов каждого плагина, шифрует весь ограниченный payload через Electron `safeStorage`, отклоняет plaintext-only backend и удаляет зашифрованный файл при uninstall. `ProviderSecretsService.ts` применяет ту же архитектуру к API-ключам провайдеров для CLI с BYOK: значения остаются в main-процессе, а renderer-контракт раскрывает только флаги `configured` и операции set/clear. Записи настроек `ApiProfile` именуют model-бэкенды (протокол, HTTPS base URL, ссылка на секрет) для тех же BYOK-рантаймов; это не agent providers, а normalizer настроек отбрасывает невалидные профили вместо «ремонта». - `src/main/services/PluginMediaService.ts` сохраняет разрешения только после нативного выбора папки, скрывает абсолютные пути, пропускает symlinks и отдаёт аудио с HTTP Range. Чтение плейлистов остаётся внутри разрешённых библиотек; ограниченная атомарная запись разрешена только в `Playlists/`. - `src/main/services/BrowserService.ts` владеет вкладками встроенного браузера в `WebContentsView`. Удалённые страницы используют отдельный persistent partition с выключенным Node, включёнными context isolation/sandbox и отклонением website permissions по умолчанию. Это core service, а не возможность runtime-плагина. -- `src/main/services/agent-runtime/` — отдельная всегда включённая lifecycle-граница, не зависящая от переключателя Browser access. Каждый agent PTY получает собственный capability для защищённого user-local socket/pipe. Provider command hooks и OpenCode event plugin могут передать только фиксированный status enum, ограниченное имя события и необязательный opaque turn/prompt ID; точная schema Gateway отклоняет prompt text, ответы, tool input и произвольную telemetry. При завершении PTY capability и временные файлы отзываются. +- `src/main/services/agent-runtime/` — отдельная всегда включённая lifecycle-граница, не зависящая от переключателя Browser access. Каждый agent PTY получает собственный capability для защищённого user-local socket/pipe. Provider command hooks и OpenCode event plugin могут передать только фиксированный status enum, ограниченное имя события и необязательный opaque turn/prompt ID; точная schema Gateway отклоняет prompt text, ответы, tool input и произвольную telemetry. При завершении PTY capability и временные файлы отзываются. Финальный ответ субагента Codex или OpenCode (хук Codex `Stop`, плагин OpenCode на `session.idle`) идёт через те же хуки, поэтому он есть только пока status hooks включены для этого запуска: это решается при планировании запуска (включая отложенный запуск с плагинами), и запуск, спланированный с выключенными хуками, не получает ни lease, ни lifecycle-хуков. Тогда `wait_for_agent` и `get_agent_result` возвращают `answerUnavailable: { reason: "status_hooks_off", message }`, и оркестратор читает вывод. Ответ хранится только для своего хода (`applyRuntimeSignal.ts`): OpenCode именует каждый ход, отправленный ввод (кроме ответа на запрос подтверждения и пустого Enter в idle-карточке) начинает новый, а сигнал текущего хода, начатого до этого ввода, завершает ожидание, но без ответа. - Claude, Codex, Qwen и OpenCode получают lifecycle hooks только на текущий запуск. Для Kimi, Hermes и Grok, которые ищут hooks в home-конфигурации, используются ownership-checked временные записи с совместным владением живых сессий. Kimi и Hermes используют recovery journals и точные backups, Grok — отдельный owned hook file; cleanup восстанавливает исходные байты или удаляет только записи CanvasTTY при конкурентных изменениях. - `TerminalManager` подмешивает MCP helper, не оставляя постоянных изменений в provider-конфигах. Claude Code, Codex и Qwen Code получают CLI arguments; Qwen получает одну inline-запись `--mcp-config`, которая переопределяет только имя сервера CanvasTTY и не скрывает сторонние user servers. OpenCode — объединённый launch-only `OPENCODE_CONFIG_CONTENT` с одной scoped browser-tool permission, Kimi — per-run MCP config или временную запись с compare-and-swap и recovery journal для старых версий. Hermes получает временную запись `mcp_servers.canvastty_browser` в `HERMES_HOME/config.yaml` (по умолчанию `~/.hermes/config.yaml` в POSIX или `%LOCALAPPDATA%\hermes\config.yaml` в Windows); чувствительные capability-значения остаются ссылками на окружение дочернего процесса. Временная конфигурация Kimi и Hermes живёт до завершения последней владеющей PTY-сессии, после чего исходные байты точно восстанавливаются, если файл не менялся параллельно. Journal восстанавливает Hermes после прерванного запуска при следующем старте CanvasTTY, а compare-and-swap сохраняет одновременные пользовательские изменения. Сторонние MCP-записи, credentials и file/shell permissions не затрагиваются. Qwen, OpenCode и Hermes YOLO остаются launch-only и не меняют постоянные permission-настройки. - `src/main/services/providerCliRegistry.ts` — единственный владелец обнаружения provider CLI. При запуске main-процесса он создаёт общий snapshot для каждого провайдера из `PROVIDER_CLI_DEFINITIONS` — каждое определение объявляет имена executable-команд, под которыми провайдер может устанавливаться (они могут отличаться от ID провайдера, например провайдер с командой `mcode`), и опциональные известные каталоги (относительно home или Windows LOCALAPPDATA), — последовательно проверяя smoke-only overrides, унаследованный `PATH`, системные каталоги платформы и эти известные каталоги. Доступная запись хранит абсолютный executable, тип launcher-а и дополненный дочерний `PATH`; POSIX-кандидат обязан быть исполняемым файлом, а Windows-кандидат — поддерживаемым native или batch launcher-ом. `TerminalManager`, `LimitsService`, agent-browser probes и provider smoke используют один и тот же snapshot и не повторяют поиск команды. Недоступный CLI создаёт failed-сессию с копируемой диагностикой проверенных путей до создания PTY или временной browser-конфигурации, а адаптер лимитов сообщает `cli-not-found`; строка HOME скрыта до ручного выбора после обнаружения CLI. Провайдер без локального CLI остаётся в панелях запуска, если для него есть аккаунт на удалённом компьютере или сохранённый контейнерный профиль. CanvasTTY не читает shell startup scripts. Настройки агентов позволяют повторно проверить пути, атомарно заменить snapshot registry, согласовать сохранённые списки запуска и лимитов и обновить зависящие от CLI адаптеры без перезапуска. Работающие сессии продолжаются; найденный позже CLI остаётся выключенным до ручного выбора. diff --git a/docs/ARCHITECTURE.zh-CN.md b/docs/ARCHITECTURE.zh-CN.md index 34dcc04e0..1f7d0b66e 100644 --- a/docs/ARCHITECTURE.zh-CN.md +++ b/docs/ARCHITECTURE.zh-CN.md @@ -49,7 +49,7 @@ Electron main process - `src/main/services/PluginSecretsService.ts` 串行化每个插件的机密写入，通过 Electron `safeStorage` 加密完整的有界 payload，拒绝 plaintext-only backend，并在卸载时删除加密文件。`ProviderSecretsService.ts` 将同一架构应用于面向 BYOK CLI 的服务商 API key：值只留在 main 进程，renderer 契约只暴露每个 key 的 `configured` 标志与 set/clear 操作。`ApiProfile` 设置项为同一批 BYOK 运行时命名 model 后端（协议、HTTPS base URL、secret 引用）；它们不是 agent provider，且 settings normalizer 会丢弃而非修复无效 profile。 - `src/main/services/PluginMediaService.ts` 仅在原生目录选择后保存授权，隐藏绝对路径，跳过 symlink，并以 HTTP Range 提供音频。Playlist 读取限制在授权媒体库内；写入受大小限制，并且只能原子写入 `Playlists/`。 - `src/main/services/BrowserService.ts` 管理内置浏览器的 `WebContentsView` tab。远程页面使用独立 persistent partition，禁用 Node，启用 context isolation/sandbox，并默认拒绝网站权限。这是 core service，不是 runtime 插件能力。 -- `src/main/services/agent-runtime/` 是独立且始终启用的 lifecycle 边界，不受 Browser access 开关控制。每个 agent PTY 都为受保护的 user-local socket/pipe 获得独立 capability。Provider command hook 与 OpenCode event plugin 只能提交固定 status enum、受限 event 名称和可选 opaque turn/prompt ID；Gateway 的精确 schema 会拒绝 prompt text、回复、tool input 与任意 telemetry。PTY 退出时 capability 与临时文件都会被撤销。 +- `src/main/services/agent-runtime/` 是独立且始终启用的 lifecycle 边界，不受 Browser access 开关控制。每个 agent PTY 都为受保护的 user-local socket/pipe 获得独立 capability。Provider command hook 与 OpenCode event plugin 只能提交固定 status enum、受限 event 名称和可选 opaque turn/prompt ID；Gateway 的精确 schema 会拒绝 prompt text、回复、tool input 与任意 telemetry。PTY 退出时 capability 与临时文件都会被撤销。 Codex 或 OpenCode 子 agent 的最终回答（Codex `Stop` hook、OpenCode 插件在 `session.idle` 时）经由同一组 hook 传递，因此只有该次启动开启了 status hooks 时才存在：是否开启在规划启动时决定（包括延迟的插件启动），在关闭状态下规划的启动既没有 lease 也没有任何 lifecycle hook。此时 `wait_for_agent` 与 `get_agent_result` 返回 `answerUnavailable: { reason: "status_hooks_off", message }`，编排者改为读取输出。回答只归属于它自己的 turn（`applyRuntimeSignal.ts`）：OpenCode 为每个 turn 命名；除审批回答和空闲卡片中的空 Enter 外，提交的输入会开始新 turn；在该输入之前开始的当前 turn 的信号仍会结束等待，但不带回答。 - Claude、Codex、Qwen 与 OpenCode 使用仅本次启动有效的 lifecycle hook。Kimi、Hermes 与 Grok 只能从 home 配置发现 hook，因此使用由实时 CanvasTTY 会话共享、带 ownership 检查的临时条目。Kimi 与 Hermes 使用 recovery journal 和精确 backup；Grok 使用独立 owned hook 文件。Cleanup 在无并发编辑时逐字恢复原文件，否则只移除 CanvasTTY 自己的条目。 - `TerminalManager` 注入 MCP helper 时不会留下永久的服务商配置变更。Claude Code、Codex 与 Qwen Code 使用 CLI 参数；Qwen 使用一个 inline `--mcp-config`，只覆盖 CanvasTTY 服务名，不隐藏无关用户服务。OpenCode 使用合并后的、仅本次启动有效的 `OPENCODE_CONFIG_CONTENT` 和一条 scoped browser-tool 权限；Kimi 使用 per-run MCP 配置，旧版本则使用带 compare-and-swap 与 recovery journal 的临时配置。Hermes 会在 `HERMES_HOME/config.yaml` 中获得临时 `mcp_servers.canvastty_browser` 配置项（POSIX 默认路径为 `~/.hermes/config.yaml`，Windows 默认路径为 `%LOCALAPPDATA%\hermes\config.yaml`），敏感 capability 值仍以子进程环境变量占位符保存。Kimi 与 Hermes 的临时配置会保留到最后一个所属 PTY 会话结束；若文件未被并发修改，则精确恢复原始字节。若 Hermes 启动意外中断，journal 会在 CanvasTTY 下次启动时修复配置，compare-and-swap 则保留用户的并发修改。其他 MCP 配置项、凭据和文件/shell 权限不会受影响。Qwen、OpenCode 与 Hermes 的 YOLO 都不修改持久权限设置。 - `src/main/services/providerCliRegistry.ts` 是服务商 CLI 发现的唯一职责边界。main 进程启动时，它按 smoke-only override、继承的 `PATH`、平台默认目录、已知用户/服务商目录的顺序，为 `PROVIDER_CLI_DEFINITIONS` 中的每个服务商创建一个共享快照——每个定义声明该服务商可能安装的 executable 命令名（可以与服务商 ID 不同，例如命令为 `mcode` 的服务商），以及可选的已知目录（相对 home 或 Windows LOCALAPPDATA）。可用条目保存绝对 executable、launcher 类型以及补充后的子进程 `PATH`；POSIX 候选必须是可执行文件，Windows 候选必须是受支持的 native 或 batch launcher。`TerminalManager`、`LimitsService`、agent-browser probe 与 provider smoke 共用该快照，不再各自查找命令。CLI 不可用时，系统会在创建 PTY 或临时 browser 配置之前生成 failed session，并提供可复制的已检查路径诊断；限额适配器报告 `cli-not-found`；HOME 行保持隐藏，直到检测到 CLI 后由用户手动选择。若某服务商绑定了远程计算机上的账户或已保存的容器配置，即使本地没有 CLI，启动器仍会显示它。CanvasTTY 不读取 shell startup script。Agents 设置可重新检查候选路径、原子替换 registry 快照、调整已保存的启动器和限额选择，并在无需重启的情况下刷新依赖 CLI 的适配器。运行中的 session 保持不变；新检测到的 CLI 需手动启用。 diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index c6373cd92..1211afb4c 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -10,8 +10,8 @@ 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`. Plugin launch options the call does not name are inherited from the orchestrator for a subagent of the same CLI (see Plugin launch options below); `model` next to inherited options that set the model is refused, and so is a subagent of another CLI while the orchestrator's model comes from a plugin's options. The answer's `servedBy` is `{ provider, model, launchOptions: { : "inherited" | "explicit" } }`. 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 ≤ 100 }` (default 50). 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 `output` and a `message` to call again. 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. | +| `wait_for_agent` | `{ sessionId, timeoutSeconds ≤ 100 }` (default 50). 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 `output` and a `message` to call again. 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`, the masked terminal tail (masked before it is cut) and, for Codex and OpenCode subagents, `answer` (see `get_agent_result`). A turn that the person interrupted by submitting their own input in the subagent's card still ends the wait, without an `answer`: that answer is no longer for the orchestrator's prompt. With CanvasTTY status hooks off (Settings → Agents) a subagent has no hooks at all, so no `answer` can be captured: the result carries `answerUnavailable: { reason: "status_hooks_off", message }` instead and the wait ends `quiet`; read `output` (or `observe_agent`). Turning status hooks on applies to subagents started or restarted afterwards. 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, kept only for the turn it ended and cleared when the next input is submitted or the next turn starts; an Enter with nothing typed in an idle card keeps it; an answer reported as the subagent exits still counts; `answerUnavailable` instead when status hooks are off), 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. Prompts to one subagent arrive in the order they were sent. OpenCode drops keys typed while it starts, so a prompt for it (also `spawn_agent`'s first one) is typed only once its input field is up: the terminal control sequence that shows its text cursor on its full screen, or a lifecycle hook only 2 s after its first one (OpenCode's plugin can report shortly before the field takes keys). This wait is used on macOS and Linux; on Windows, whose pseudo console may not pass those sequences, OpenCode gets input as soon as its PTY exists, as before. `spawn_agent` (its checks, the launch and this wait together) and `send_to_agent` wait at most 45 s, under the MCP client's tool deadline; then the call fails with the reason and the session id, and nothing is typed. A send cancelled while it waits returns at once. | ### Subagent profiles diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index faf93a3c1..b273493bb 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -1095,7 +1095,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 50, at most 100; 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.", + "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 50, at most 100; 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 CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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": { @@ -1118,7 +1118,7 @@ }, { "name": "get_agent_result", - "description": "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output.", + "description": "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", "inputSchema": { "type": "object", "properties": { diff --git a/src/agent-browser/orchestration-catalog.mjs b/src/agent-browser/orchestration-catalog.mjs index c57119e81..64b0f1d1d 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -88,13 +88,13 @@ 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}; 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.`, + `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 CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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"] ), tool( "get_agent_result", - "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output.", + "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", { sessionId }, ["sessionId"] ), diff --git a/src/agent-runtime/opencode-plugin.mjs b/src/agent-runtime/opencode-plugin.mjs index bd8151b86..69ae5f00c 100644 --- a/src/agent-runtime/opencode-plugin.mjs +++ b/src/agent-runtime/opencode-plugin.mjs @@ -3,10 +3,13 @@ import { CAPTURE_RESULT_ENV } from "./runtime-protocol.mjs"; import { finalAnswer } from "./opencode-final-answer.mjs"; import { createOpenCodeDecisions } from "./opencode-decisions.mjs"; import { spawn } from "node:child_process"; +import { randomUUID } from "node:crypto"; import { HOOK_TIMEOUT_MS, preparePluginHook } from "./plugin-hook-dispatch.mjs"; let rootSessionId = null; let rootWorking = false; +// One id per root turn (not the session id), so a late answer of an earlier turn is never taken for the current one. +let rootTurnId = null; const lifecycleEnabled = process.env.CANVASTTY_LIFECYCLE_HOOKS_ENABLED !== "0"; const pluginHookRegistry = process.env.CANVASTTY_PLUGIN_HOOK_REGISTRY ?? ""; const pluginHookRunnerCommand = process.env.CANVASTTY_PLUGIN_HOOK_RUNNER_COMMAND ?? ""; @@ -45,6 +48,7 @@ async function lifecycleEvent(event, decisions, client) { if (session.parentID || session.parentId) return; rootSessionId = stringField(session.id, sessionId); rootWorking = false; + rootTurnId = null; if (!rootSessionId) return; if (lifecycleEnabled) { await reportLifecycle({ state: "idle", event: event.type, threadId: rootSessionId }); @@ -63,44 +67,55 @@ async function lifecycleEvent(event, decisions, client) { ? statusValue.type : null; if (status === "busy" || status === "retry") { + const startsTurn = status === "busy" && !rootWorking; + if (startsTurn || !rootTurnId) rootTurnId = randomUUID(); + rootWorking = true; if (lifecycleEnabled) { - await reportLifecycle({ state: "working", event: `session.status:${status}`, turnId: rootSessionId }); + await reportLifecycle({ state: "working", event: `session.status:${status}`, turnId: rootTurnId }); } - if (status === "busy" && !rootWorking) { + if (startsTurn) { runPluginHooks("prompt-submit", `session.status:${status}`, event); } - rootWorking = true; } else if (status === "idle") { rootWorking = false; - if (lifecycleEnabled) await reportLifecycle({ state: "idle", event: "session.status:idle", turnId: rootSessionId }); + // A result-capturing turn ends with session.idle, once its final answer was read: an idle reported here would + // let a waiting orchestrator take the turn as finished before its answer arrived. + if (lifecycleEnabled && !captureResult) await reportLifecycle({ state: "idle", event: "session.status:idle", turnId: rootTurnId }); } return; } if (event.type === "session.idle") { rootWorking = false; - const result = captureResult ? await finalAnswer(client, rootSessionId) : undefined; - if (lifecycleEnabled || result) { - await reportLifecycle({ state: "idle", event: event.type, turnId: rootSessionId, ...(result ? { result } : {}) }); + const endingSessionId = rootSessionId, endingTurnId = rootTurnId; + // With CanvasTTY status hooks off nothing is reported, the answer included: it is never read. + const result = lifecycleEnabled && captureResult && endingTurnId ? await finalAnswer(client, endingSessionId) : undefined; + // The read is asynchronous: when the next turn started meanwhile, this answer and this idle are no longer current. + const superseded = endingSessionId !== rootSessionId || endingTurnId !== rootTurnId || rootWorking; + if (lifecycleEnabled && !superseded) { + await reportLifecycle({ state: "idle", event: event.type, turnId: endingTurnId, ...(result ? { result } : {}) }); } runPluginHooks("stop", event.type, event); } else if (event.type === "permission.asked") { - if (lifecycleEnabled) await reportLifecycle({ state: "needs_approval", event: event.type, turnId: rootSessionId }); + if (lifecycleEnabled) await reportLifecycle({ state: "needs_approval", event: event.type, turnId: rootTurnId }); runPluginHooks("permission-request", event.type, event); } else if (event.type === "permission.replied") { - if (lifecycleEnabled) await reportLifecycle({ state: "working", event: event.type, turnId: rootSessionId }); + rootWorking = true; + if (lifecycleEnabled) await reportLifecycle({ state: "working", event: event.type, turnId: rootTurnId }); runPluginHooks("permission-result", event.type, event); } else if (event.type === "question.asked") { - if (lifecycleEnabled) await reportLifecycle({ state: "needs_approval", event: event.type, turnId: rootSessionId }); + if (lifecycleEnabled) await reportLifecycle({ state: "needs_approval", event: event.type, turnId: rootTurnId }); } else if (event.type === "question.replied" || event.type === "question.rejected") { - if (lifecycleEnabled) await reportLifecycle({ state: "working", event: event.type, turnId: rootSessionId }); + rootWorking = true; + if (lifecycleEnabled) await reportLifecycle({ state: "working", event: event.type, turnId: rootTurnId }); } else if (event.type === "session.error") { rootWorking = false; - if (lifecycleEnabled) await reportLifecycle({ state: "idle", event: event.type, turnId: rootSessionId }); + if (lifecycleEnabled) await reportLifecycle({ state: "idle", event: event.type, turnId: rootTurnId }); runPluginHooks("stop", event.type, event); } else if (event.type === "session.deleted") { runPluginHooks("session-end", event.type, event); rootWorking = false; rootSessionId = null; + rootTurnId = null; } else if (event.type === "tool.execute.after") { runPluginHooks("after-tool", event.type, event); } diff --git a/src/main/index.ts b/src/main/index.ts index da506ee4c..7de303386 100644 --- a/src/main/index.ts +++ b/src/main/index.ts @@ -92,6 +92,7 @@ import { RuntimeGateway } from "./services/agent-runtime"; import type { RuntimeHookHelperLaunch } from "./services/agent-runtime/ProviderRuntimeLaunch"; +import { applyRuntimeSignal } from "./services/agent-runtime/applyRuntimeSignal"; import { agentHelperLaunches } from "./services/agentHelpers"; import { recoverHermesConfigurationOnStartup, @@ -530,15 +531,7 @@ async function initializeServices(ipc: IpcRegistrar): Promise { runtimeDirectory: lifecycleRuntimeDirectory, windowsHostPath, onSignal: (terminalSessionId, signal) => { - terminalManager?.applyProviderSignal(terminalSessionId, { - kind: "lifecycle", - state: signal.state, - event: signal.event, - ...(signal.turnId ? { requestId: signal.turnId } : {}), - ...(signal.threadId ? { threadId: signal.threadId } : {}) - }); - // A subagent's final answer (Codex Stop hook, OpenCode plugin) for get_agent_result and wait_for_agent. - if (signal.result) terminalManager?.recordAnswer(terminalSessionId, signal.result); + if (terminalManager) applyRuntimeSignal(terminalManager, terminalSessionId, signal); agentControl?.onSignal(terminalSessionId, signal); if (signal.lastAssistantMessage !== undefined && signal.answerCaptureGrantExpiresAt !== undefined) { evenG2?.answer( diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index 67094d009..2b587ca9d 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -75,6 +75,8 @@ export interface AgentWaitResult { exitLines?: string; /** The final answer of the turn that ended (Codex, OpenCode subagents), masked. */ answer?: AgentAnswer; + /** Why a Codex or OpenCode subagent has no answer and never will in this launch (read its output instead). */ + answerUnavailable?: AgentAnswerUnavailable; } export interface AgentWaitTiming { @@ -110,8 +112,20 @@ export interface AgentResult { exitLines?: string; /** The last turn's final answer as the agent reported it (Codex, OpenCode subagents), masked; absent otherwise. */ answer?: AgentAnswer; + /** Why a Codex or OpenCode subagent has no answer and never will in this launch (read its output instead). */ + answerUnavailable?: AgentAnswerUnavailable; } +export interface AgentAnswerUnavailable { + /** "status_hooks_off": CanvasTTY status hooks were off for its launch, so it has no hooks to report an answer. */ + reason: "status_hooks_off"; + message: string; +} + +const STATUS_HOOKS_OFF_MESSAGE = "This subagent's final answer cannot be captured because CanvasTTY status hooks are off " + + "(Settings → Agents; turning them on applies to agents started or restarted afterwards). Read its output instead: " + + "the output field here, or observe_agent."; + export interface AgentAnswer { text: string; /** Only the end of a longer answer was kept. */ @@ -376,7 +390,7 @@ export class AgentControlService { exitCode: session.exitCode, output: this.redactTail(buffer, MAX_OBSERVE_CHARS), ...(session.exitCode !== null && this.exitLines(buffer) ? { exitLines: this.exitLines(buffer)! } : {}), - ...(answer ? { answer } : {}) + ...(answer ? { answer } : this.answerUnavailable(sessionId)) }; } @@ -401,7 +415,7 @@ export class AgentControlService { try { observation = this.observe(sessionId); } catch { observation = null; } const answer = reason === "timeout" || reason === "needs_approval" ? null : this.answer(sessionId); return { sessionId, reason, status: session.status, exitCode: session.exitCode, waitedMs, output: observation?.output ?? "", - ...(observation?.exitLines ? { exitLines: observation.exitLines } : {}), ...(answer ? { answer } : {}) }; + ...(observation?.exitLines ? { exitLines: observation.exitLines } : {}), ...(answer ? { answer } : this.answerUnavailable(sessionId)) }; }; let offset = this.outputOffset(sessionId); let changedAt = started; @@ -459,6 +473,14 @@ export class AgentControlService { try { return typeof this.terminals.turnProgress === "function" ? this.terminals.turnProgress(sessionId) : null; } catch { return null; } } + /** Says so when no answer can be captured for this agent, so an orchestrator reads its output instead of waiting for one. */ + private answerUnavailable(sessionId: string): { answerUnavailable?: AgentAnswerUnavailable } { + try { + const reason = typeof this.terminals.answerUnavailable === "function" ? this.terminals.answerUnavailable(sessionId) : null; + return reason === "status_hooks_off" ? { answerUnavailable: { reason, message: STATUS_HOOKS_OFF_MESSAGE } } : {}; + } catch { return {}; } + } + private answer(sessionId: string): AgentAnswer | null { try { const answer = typeof this.terminals.answer === "function" ? this.terminals.answer(sessionId) : null; diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index c0f00ea76..74fde97ab 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -128,6 +128,20 @@ interface ManagedSession { promptTurnMark?: number; /** The last turn's final answer its hook or plugin reported (captureResult only); cleared when a turn starts. */ answer?: { text: string; truncated: boolean; at: number }; + /** + * Status hooks were off when this launch was planned, or were turned off since: it has no lifecycle hooks, so its + * card stays unavailable and no answer is captured until a restart with status hooks on. + */ + statusHooksOff?: boolean; + /** Something other than Enter was typed since the last submitted input (an Enter alone then submits nothing). */ + typedSinceSubmit?: boolean; + /** Bumped by every submitted input (except an approval answer) and every launch: the turn an answer must belong to. */ + inputGeneration?: number; + /** inputGeneration when the current turn started. */ + answerTurnGeneration?: number; + /** OpenCode's current turn id and the inputGeneration each recent turn id started in. */ + providerTurnId?: string; + providerTurnGenerations?: Map; /** * Plugin options, environment ref (or, until the plugin has prepared it, the launcher's environment choice) * and owning plugin carried into the saved record. @@ -1026,6 +1040,23 @@ export class TerminalManager { return { delivered: true }; } + /** + * Submitted text starts a new task (an approval answer continues the current turn), so an earlier answer is not its. + * An Enter with nothing typed before it in an idle card submits nothing: the stored answer stays. + */ + private noteSubmittedInput(session: ManagedSession, data: string): void { + const typed = /[^\r\n]/u.test(data); + if (!data.endsWith("\r")) { + if (typed) session.typedSinceSubmit = true; + return; + } + const empty = !typed && !session.typedSinceSubmit; + session.typedSinceSubmit = false; + if (empty && session.metadata.status === "idle") return; + if (session.metadata.status !== "needs_approval") session.inputGeneration = (session.inputGeneration ?? 0) + 1; + delete session.answer; + } + private wakeLaunchWaiters(session: ManagedSession): void { for (const wake of [...session.launchWaiters]) wake(); } @@ -1034,8 +1065,18 @@ export class TerminalManager { if (typeof data !== "string" || data.length === 0) return false; const session = this.sessions.get(id); if (!session || session.metadata.exitCode !== null || !session.process) return false; - const process = session.process; + return this.writeInput(id, session, session.process, data); + } + + /** + * The one write of person or agent input to a card's CLI, and what it means for turns and answers. Everything that + * types into a card goes through here: input(), deliverInput, and any writer that holds input and replays it later, + * so a replayed Enter is a submitted prompt like a typed one. Nothing is written to a process the card no longer runs. + */ + private writeInput(id: string, session: ManagedSession, process: IPty, data: string): boolean { + if (this.sessions.get(id) !== session || session.process !== process || session.metadata.exitCode !== null) return false; const written = tryPtyOperation(() => process.write(data)); + if (written) this.noteSubmittedInput(session, data); if (written && ANSWERS_PROMPT.test(data)) this.settleAnsweredPrompt(id, session); return written; } @@ -1106,10 +1147,40 @@ export class TerminalManager { return publicSessionMetadata(session); } - /** `source` "hook" is the agent's own lifecycle hook (through the runtime gateway); "title" is its terminal title. */ - applyProviderSignal(id: string, signal: ProviderLifecycleSignal, source: "hook" | "title" = "hook"): void { + /** + * `source` "hook" is the agent's own lifecycle hook (through the runtime gateway); "title" is its terminal title. + * Returns whether the signal belongs to the current turn and the last submitted input, so the answer it carries may + * be kept (applyRuntimeSignal). With status hooks off for this launch nothing applies and no answer is kept. + */ + applyProviderSignal(id: string, signal: ProviderLifecycleSignal, source: "hook" | "title" = "hook"): boolean { const session = this.sessions.get(id); - if (!this.lifecycleHooksEnabled || !session || session.metadata.status === "done" || session.metadata.status === "failed") return; + if (!this.lifecycleHooksEnabled || !session || session.statusHooksOff) return false; + // A result-capturing OpenCode names each turn. A signal of an earlier turn is stale and changes nothing; a signal + // of the current turn that started before the last submitted input still moves the status (so a wait ends), but + // is not that input's turn: it neither counts as a turn start nor brings an answer. + const exited = session.metadata.status === "done" || session.metadata.status === "failed"; + let current = true; + let startsProviderTurn = false; + if (source === "hook" && session.captureResult && session.metadata.provider === "opencode" && signal.requestId) { + const turns = session.providerTurnGenerations ??= new Map(); + const generation = session.inputGeneration ?? 0; + const known = turns.get(signal.requestId); + if (known === undefined) { + // A turn id not seen yet opens the next turn, also when its start was lost (as the gateway counts it); after + // the exit no turn opens. + if (exited) return false; + startsProviderTurn = true; + turns.set(signal.requestId, generation); + session.providerTurnId = signal.requestId; + while (turns.size > 64) turns.delete(turns.keys().next().value!); + } else if (session.providerTurnId !== signal.requestId) { + return false; + } else { + current = known === generation; + } + } + // The process already exited: its status stays, but the answer its last turn reported as it ended still counts. + if (exited) return current; if (source === "hook") { session.hookSignals = (session.hookSignals ?? 0) + 1; // The CLI runs, but its input field may not be up yet: input waiting for it (deliverInput) goes on the cursor @@ -1133,24 +1204,44 @@ export class TerminalManager { const nextStatus = signal.state; // A turn starts when the agent moves to working; wait_for_agent compares it with the last delivered prompt. - if (nextStatus === "working" && session.metadata.status !== "working") session.turnStarts = (session.turnStarts ?? 0) + 1; - // A new turn: the previous answer is no longer this turn's. - if (nextStatus === "working") session.answer = undefined; + if (current && nextStatus === "working") { + if (startsProviderTurn || session.metadata.status !== "working") session.turnStarts = (session.turnStarts ?? 0) + 1; + // A new turn: the previous answer is no longer this turn's. + session.answer = undefined; + session.answerTurnGeneration = session.inputGeneration ?? 0; + } const completed = nextStatus === "idle" && ["Stop", "StopFailure", "StopCancelled"].includes(signal.event ?? ""); const nextTurnCompleted = nextStatus === "working" ? false : completed || Boolean(session.metadata.turnCompleted); - if (!threadChanged && session.metadata.status === nextStatus && Boolean(session.metadata.turnCompleted) === nextTurnCompleted) return; + if (!threadChanged && session.metadata.status === nextStatus && Boolean(session.metadata.turnCompleted) === nextTurnCompleted) return current; session.metadata.status = nextStatus; session.metadata.turnCompleted = nextTurnCompleted; this.emitSession(session.metadata); + return current; + } + + /** + * Why a result-capturing session's final answer cannot be captured, or null when it can (or the session does not + * capture one). With CanvasTTY status hooks off for its launch it gets no hooks, so nothing reports the answer. + */ + answerUnavailable(id: string): "status_hooks_off" | null { + const session = this.sessions.get(id); + if (!session?.captureResult) return null; + return !this.lifecycleHooksEnabled || session.statusHooksOff ? "status_hooks_off" : null; } /** * Keeps the final answer a result-capturing session reported with its turn's end (the Codex Stop hook, the OpenCode - * plugin's session.idle); read back masked by answer(). In memory only, never saved. + * plugin's session.idle), only while it belongs to the current turn and the last submitted input; read back masked + * by answer(). OpenCode passes its turn id. In memory only, never saved. */ - recordAnswer(id: string, result: { text: string; truncated: boolean }): void { + recordAnswer(id: string, result: { text: string; truncated: boolean }, correlation?: { turnId?: string | null }): void { const session = this.sessions.get(id); if (!session?.captureResult || typeof result?.text !== "string") return; + const generation = session.inputGeneration ?? 0; + if (session.metadata.provider === "opencode" && correlation && "turnId" in correlation) { + if (!correlation.turnId || correlation.turnId !== session.providerTurnId + || session.providerTurnGenerations?.get(correlation.turnId) !== generation) return; + } else if (session.promptTurnMark !== undefined && session.answerTurnGeneration !== generation) return; session.answer = { text: result.text, truncated: result.truncated === true, at: Date.now() }; } @@ -1168,6 +1259,7 @@ export class TerminalManager { if (next) return; for (const session of this.sessions.values()) { session.lifecycle = null; + session.statusHooksOff = true; if ( session.metadata.provider === "terminal" || session.metadata.status === "done" @@ -2151,6 +2243,8 @@ export class TerminalManager { // 5. The host spawns the PTY; an environment only rewrites what is spawned, and the isolation layer wraps that. let planned: PlannedSpawn | { failure: LaunchFailure }; + // Whether this launch gets lifecycle hooks is decided as it is planned; the wrap below may take a while. + const statusHooks = this.lifecycleHooksEnabled; try { planned = this.planSpawn(id, metadata.provider, decision.profile, metadata.cwd, resume, session.captureResult, metadata.role, answerCaptureGrantExpiresAt, contribution, trustedFolder, Boolean(environment), decision.apply); @@ -2224,7 +2318,7 @@ export class TerminalManager { metadata.status = initialSessionStatus(metadata.provider); metadata.exitCode = null; metadata.failureDetails = null; - this.bindProcess(id, session, process); + this.bindProcess(id, session, process, statusHooks); const runtimeStatus = this.agentRuntime?.currentStatus(id); if (runtimeStatus) metadata.status = runtimeStatus; if (environment) this.describeEnvironment(id, session, environment); @@ -2253,7 +2347,13 @@ export class TerminalManager { }).catch(() => undefined); } - private bindProcess(id: string, session: ManagedSession, process: IPty): void { + /** + * `statusHooks`: status hooks were on when this launch was planned (and so got its lifecycle hooks). A launch planned + * and spawned in one step passes nothing; a contributed launch passes what held before its asynchronous steps. + */ + private bindProcess(id: string, session: ManagedSession, process: IPty, statusHooks = this.lifecycleHooksEnabled): void { + if (statusHooks && this.lifecycleHooksEnabled) delete session.statusHooksOff; + else session.statusHooksOff = true; session.agentBrowser?.retainUntilExit?.(); process.onData((data) => { const current = this.sessions.get(id); @@ -2415,6 +2515,13 @@ function resetLaunchSignals(session: ManagedSession): void { delete session.answer; delete session.turnStarts; delete session.promptTurnMark; + // A late answer of the ended launch never belongs to the new one. + session.inputGeneration = (session.inputGeneration ?? 0) + 1; + delete session.statusHooksOff; + delete session.typedSinceSubmit; + delete session.answerTurnGeneration; + delete session.providerTurnId; + delete session.providerTurnGenerations; delete session.hookSignals; delete session.titleState; delete session.inputReady; diff --git a/src/main/services/agent-browser/OrchestrationTools.ts b/src/main/services/agent-browser/OrchestrationTools.ts index 71c8cb54f..d1273825a 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -248,7 +248,8 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { exitCode: result.exitCode, output: result.output, ...(result.exitLines ? { exitLines: result.exitLines } : {}), - ...(result.answer ? { answer: result.answer } : {}) + ...(result.answer ? { answer: result.answer } : {}), + ...(result.answerUnavailable ? { answerUnavailable: result.answerUnavailable } : {}) }; } diff --git a/src/main/services/agent-runtime/RuntimeGateway.ts b/src/main/services/agent-runtime/RuntimeGateway.ts index 7ad4f9d48..97015bf66 100644 --- a/src/main/services/agent-runtime/RuntimeGateway.ts +++ b/src/main/services/agent-runtime/RuntimeGateway.ts @@ -877,7 +877,8 @@ function isTurnStart(event: string): boolean { return event === "UserPromptSubmit" || event === "TurnStarted" || event === "pre_llm_call" - || event === "session.status:busy"; + || event === "session.status:busy" + || event === "session.status:retry"; } function isRecord(value: unknown): value is Record { diff --git a/src/main/services/agent-runtime/applyRuntimeSignal.ts b/src/main/services/agent-runtime/applyRuntimeSignal.ts new file mode 100644 index 000000000..47b800df6 --- /dev/null +++ b/src/main/services/agent-runtime/applyRuntimeSignal.ts @@ -0,0 +1,22 @@ +import type { RuntimeLifecycleSignal } from "./RuntimeGateway.ts"; +import type { TerminalManager } from "../TerminalManager.ts"; + +/** + * What main does with one runtime gateway signal: the card's status first, then the final answer it carries (Codex + * Stop hook, OpenCode plugin) for get_agent_result and wait_for_agent, kept only when the signal belongs to the + * current turn and the last submitted input. + */ +export function applyRuntimeSignal( + terminals: Pick, + terminalSessionId: string, + signal: RuntimeLifecycleSignal +): void { + const current = terminals.applyProviderSignal(terminalSessionId, { + kind: "lifecycle", + state: signal.state, + event: signal.event, + ...(signal.turnId ? { requestId: signal.turnId } : {}), + ...(signal.threadId ? { threadId: signal.threadId } : {}) + }); + if (current && signal.result) terminals.recordAnswer(terminalSessionId, signal.result, { turnId: signal.turnId }); +} diff --git a/tests/agent-runtime-provider-launch.test.mjs b/tests/agent-runtime-provider-launch.test.mjs index c56a310b2..c1183d439 100644 --- a/tests/agent-runtime-provider-launch.test.mjs +++ b/tests/agent-runtime-provider-launch.test.mjs @@ -497,3 +497,25 @@ function runtimeOptionsFor(root, qwenSystemSettingsPath, pluginHooks) { environment: {} }; } + +test("with status hooks off a result-capturing subagent gets no lease and no lifecycle hooks", async (t) => { + const root = await fixture(t); + const registrations = []; + const gateway = { + registerSession(id, provider, capture, _grant, decisions) { + registrations.push({ id, capture, decisions }); + return { address: join(root, "runtime.sock"), terminalSessionId: id, provider, capabilityToken: "token" }; + }, + revokeTerminalSession() {}, + currentStatus: () => null + }; + const bridge = new AgentRuntimeBridge(gateway, { ...runtimeOptionsFor(root), coreHooksEnabled: false }); + for (const provider of ["codex", "opencode"]) { + const launch = bridge.prepareLaunch({ terminalSessionId: provider, provider, cwd: root, captureResult: true, decisions: false }); + assert.equal(launch.environment[AGENT_RUNTIME_ENV.capabilityToken], undefined, `${provider}: turning status hooks off means no hooks`); + assert.deepEqual(launch.args.filter((arg) => /^hooks\./u.test(arg)), []); + assert.equal(launch.environment.OPENCODE_CONFIG_CONTENT, undefined); + launch.cleanup(); + } + assert.deepEqual(registrations, []); +}); diff --git a/tests/opencode-result.test.mjs b/tests/opencode-result.test.mjs index 9689b60a6..a6f77225e 100644 --- a/tests/opencode-result.test.mjs +++ b/tests/opencode-result.test.mjs @@ -7,10 +7,12 @@ import test from "node:test"; import { AGENT_RUNTIME_ENV, CAPTURE_RESULT_ENV, MAX_RESULT_CHARS } from "../src/agent-runtime/runtime-protocol.mjs"; import { finalAnswer } from "../src/agent-runtime/opencode-final-answer.mjs"; import { RuntimeGateway } from "../src/main/services/agent-runtime/RuntimeGateway.ts"; +import { applyRuntimeSignal } from "../src/main/services/agent-runtime/applyRuntimeSignal.ts"; +import { LaunchPipeline } from "../src/main/services/LaunchPipeline.ts"; import { TerminalManager } from "../src/main/services/TerminalManager.ts"; import { AgentControlService } from "../src/main/services/AgentControlService.ts"; import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; -import { availableRegistry, fakeSpawner, openCodeInputReady } from "./helpers/terminal.mjs"; +import { availableRegistry, fakeSpawner, inputReadySpawner, openCodeInputReady } from "./helpers/terminal.mjs"; const POSIX = { skip: process.platform === "win32" ? "Unix socket test; the Windows pipe transport has its own suite." : false }; @@ -55,9 +57,9 @@ await hooks.event({ event: { type: "session.status", properties: { sessionID: "s await hooks.event({ event: { type: "session.idle", properties: { sessionID: "ses_root" } } }); `; -function runFakeOpenCode(capability, answer, captureResult) { +function runFakeOpenCode(capability, answer, captureResult, script = FAKE_OPENCODE, extraEnv = {}, onCapture = null) { const env = { - ...process.env, + ...process.env, ...extraEnv, PLUGIN_URL: new URL("../src/agent-runtime/opencode-plugin.mjs", import.meta.url).href, FAKE_ANSWER: JSON.stringify(answer), [AGENT_RUNTIME_ENV.address]: capability.address, @@ -67,35 +69,43 @@ function runFakeOpenCode(capability, answer, captureResult) { }; if (captureResult) env[CAPTURE_RESULT_ENV] = "1"; else delete env[CAPTURE_RESULT_ENV]; - const child = spawn(process.execPath, ["--input-type=module", "-e", FAKE_OPENCODE], { env, stdio: ["ignore", "ignore", "pipe"] }); + const child = spawn(process.execPath, ["--input-type=module", "-e", script], { env, stdio: ["pipe", "pipe", "pipe"] }); + const timeout = setTimeout(() => child.kill(), 5_000); let stderr = ""; child.stderr.on("data", (chunk) => { stderr += chunk; }); - return new Promise((resolve) => child.on("close", (code) => resolve({ code, stderr }))); + return new Promise((resolve, reject) => { + // The script writes to stdout when its SDK read starts and waits on stdin until onCapture has run. + if (onCapture) child.stdout.once("data", () => { + Promise.resolve().then(onCapture).then(() => child.stdin.end("continue"), (error) => { child.kill(); reject(error); }); + }); + child.on("error", (error) => { clearTimeout(timeout); reject(error); }); + child.on("close", (code) => { clearTimeout(timeout); resolve({ code, stderr }); }); + }); } -async function setup(t) { +async function setupTerminals(t) { const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-ocr-"))); t.after(() => rm(root, { recursive: true, force: true })); const calls = []; - const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, inputReadySpawner(calls)); t.after(() => terminals.disposeAll()); - const runtimeDirectory = await mkdtemp(join(tmpdir(), "ctty-rt-")); - t.after(() => rm(runtimeDirectory, { recursive: true, force: true })); - // What main/index.ts does with each runtime signal. - const gateway = new RuntimeGateway({ - runtimeDirectory, - onSignal: (id, signal) => { - terminals.applyProviderSignal(id, { kind: "lifecycle", state: signal.state }); - if (signal.result) terminals.recordAnswer(id, signal.result); - } - }); - await gateway.start(); - t.after(() => gateway.close()); const orchestrator = terminals.create({ provider: "codex", cwd: root, profile: "normal", position: { x: 0, y: 0 }, role: "orchestrator" }); const control = new AgentControlService(terminals, { waitTiming: { checkMs: 5, settleMs: 300, quietMs: 2_000 } }); const handler = new ScopedOrchestrationHandler(control); const child = await handler.execute(orchestrator.id, { id: "1", tool: "spawn_agent", arguments: { provider: "opencode", cwd: root } }); - return { root, calls, terminals, gateway, handler, orchestrator, childId: child.sessionId }; + return { root, calls, terminals, control, handler, orchestrator, childId: child.sessionId }; +} + +async function setup(t) { + const fixture = await setupTerminals(t); + const { terminals } = fixture; + const runtimeDirectory = await mkdtemp(join(tmpdir(), "ctty-rt-")); + t.after(() => rm(runtimeDirectory, { recursive: true, force: true })); + // The same glue main/index.ts runs for each runtime signal. + const gateway = new RuntimeGateway({ runtimeDirectory, onSignal: (id, signal) => applyRuntimeSignal(terminals, id, signal) }); + await gateway.start(); + t.after(() => gateway.close()); + return { ...fixture, gateway }; } test("an OpenCode subagent's final reply reaches wait_for_agent and get_agent_result, masked", POSIX, async (t) => { @@ -170,3 +180,318 @@ test("wait_for_agent ignores an idle before the prompt's turn and returns that t assert.equal(done.reason, "idle"); assert.deepEqual(done.answer, { text: "part A done", truncated: false }); }); + +test("OpenCode turn correlation rejects preceding answers and continuations across submitted prompts", async (t) => { + const { terminals, childId } = await setupTerminals(t); + const apply = (state, event, turnId, answer) => { + const current = terminals.applyProviderSignal(childId, { kind: "lifecycle", state, event, requestId: turnId }); + if (current && answer) terminals.recordAnswer(childId, { text: answer, truncated: false }, { turnId }); + return current; + }; + assert.equal(apply("working", "session.status:busy", "turn1"), true); + assert.equal(apply("idle", "session.idle", "turn1", "old answer"), true); + assert.equal(terminals.answer(childId).text, "old answer"); + assert.deepEqual(await terminals.deliverInput(childId, "new task\r"), { delivered: true }); + assert.equal(terminals.answer(childId), null, "a submitted prompt drops the previous answer"); + assert.equal(apply("idle", "session.idle", "turn1", "delayed old answer"), false); + assert.equal(apply("working", "permission.replied", "turn1"), false, "an old continuation cannot acknowledge the new prompt"); + assert.equal(terminals.getMetadata(childId).status, "working", "but it still moves the status of the turn that runs"); + terminals.recordAnswer(childId, { text: "uncorrelated old answer", truncated: false }); + assert.equal(terminals.answer(childId), null); + assert.equal(terminals.turnProgress(childId).turnStartedSincePrompt, false); + assert.equal(apply("working", "session.status:busy", "turn2"), true); + assert.equal(apply("idle", "session.idle", "turn1", "late old after new start"), false); + assert.equal(terminals.getMetadata(childId).status, "working", "a late signal of an earlier turn changes nothing"); + assert.equal(apply("needs_approval", "permission.asked", "turn2"), true); + const generation = terminals.sessions.get(childId).inputGeneration ?? 0; + terminals.input(childId, "y\r"); + assert.equal(terminals.sessions.get(childId).inputGeneration ?? 0, generation, "an approval answer is not a new task"); + assert.equal(apply("working", "permission.replied", "turn2"), true); + assert.equal(apply("working", "session.status:retry", "turn2"), true); + assert.equal(apply("idle", "session.idle", "turn2", "new answer"), true); + assert.equal(terminals.answer(childId).text, "new answer"); + apply("working", "session.status:busy", "turn3"); + await terminals.deliverInput(childId, "interrupt current work\r"); + const starts = terminals.sessions.get(childId).turnStarts; + assert.equal(apply("working", "session.status:busy", "turn4"), true); + assert.equal(terminals.sessions.get(childId).turnStarts, starts + 1, "a new turn id is a new turn even while the previous one was working"); + assert.equal(terminals.turnProgress(childId).turnStartedSincePrompt, true); + assert.equal(apply("idle", "session.idle", "turn3", "interrupted answer"), false); + assert.equal(terminals.answer(childId), null); +}); + +test("with status hooks off the plugin reports nothing and the wait says the answer cannot be captured", POSIX, async (t) => { + const { terminals, gateway, handler, orchestrator, childId } = await setup(t); + terminals.setLifecycleHooksEnabled(false); + const signals = []; + const apply = terminals.applyProviderSignal.bind(terminals); + terminals.applyProviderSignal = (id, signal, ...args) => { signals.push(signal); return apply(id, signal, ...args); }; + // A lease that exists for another reason (the decision hook) still carries no lifecycle report and no answer. + const capability = gateway.registerSession(childId, "opencode", true); + const run = await runFakeOpenCode(capability, "never captured", true, FAKE_OPENCODE, { CANVASTTY_LIFECYCLE_HOOKS_ENABLED: "0" }); + assert.equal(run.code, 0, run.stderr); + assert.deepEqual(signals, []); + assert.equal(terminals.getMetadata(childId).status, "unavailable"); + assert.equal(terminals.answer(childId), null); + const waited = await handler.execute(orchestrator.id, { id: "w", tool: "wait_for_agent", arguments: { sessionId: childId, timeoutSeconds: 5 } }); + assert.equal(waited.reason, "quiet"); + assert.equal(waited.answer, undefined); + assert.equal(waited.answerUnavailable.reason, "status_hooks_off"); + assert.match(waited.answerUnavailable.message, /status hooks are off[\s\S]*Read its output/u); + const result = await handler.execute(orchestrator.id, { id: "r", tool: "get_agent_result", arguments: { sessionId: childId } }); + assert.equal(result.answer, undefined); + assert.deepEqual(result.answerUnavailable, waited.answerUnavailable); + // Turning them on again applies to agents started or restarted afterwards, not to this launch. + terminals.setLifecycleHooksEnabled(true); + assert.equal(terminals.applyProviderSignal(childId, { kind: "lifecycle", state: "idle", event: "session.idle", requestId: "t" }), false); + const later = await handler.execute(orchestrator.id, { id: "r2", tool: "get_agent_result", arguments: { sessionId: childId } }); + assert.equal(later.answerUnavailable?.reason, "status_hooks_off"); +}); + +test("OpenCode async final answer keeps its ending turn and drops a read superseded by a new turn", POSIX, async (t) => { + const { terminals, gateway, childId } = await setup(t); + const capability = gateway.registerSession(childId, "opencode", true); + const signals = []; + const original = terminals.applyProviderSignal.bind(terminals); + terminals.applyProviderSignal = (id, signal, ...args) => { signals.push(signal); return original(id, signal, ...args); }; + const script = ` + const { CanvasTTYLifecycle } = await import(process.env.PLUGIN_URL); + let resolveOld, started; const capturing = new Promise((done) => started = done); + let reads = 0; + const client = { session: { messages: async () => { + if (reads++ === 0) { started(); return new Promise((done) => resolveOld = done); } + return { data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "second answer" }] }] }; + } } }; + const hooks = await CanvasTTYLifecycle({ client }); + const event = (type, rest = {}) => hooks.event({ event: { type, properties: { sessionID: "root", ...rest } } }); + await event("session.created", { info: { id: "root" } }); + await event("session.status", { status: { type: "busy" } }); + await event("session.status", { status: { type: "idle" } }); + const old = event("session.idle"); await capturing; + await event("session.status", { status: { type: "busy" } }); + resolveOld({ data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "old delayed answer" }] }] }); + await old; + await event("permission.asked"); await event("permission.replied"); + await event("session.status", { status: { type: "retry" } }); + await event("session.status", { status: { type: "idle" } }); + await event("session.idle"); + `; + const run = await runFakeOpenCode(capability, "unused", true, script); + assert.equal(run.code, 0, run.stderr); + const starts = signals.filter((signal) => signal.event === "session.status:busy"); + assert.equal(starts.length, 2); + assert.notEqual(starts[0].requestId, starts[1].requestId, "each turn has its own id"); + assert.equal(signals.filter((signal) => signal.event === "session.status:idle").length, 0, "no idle before the answer was read"); + const ends = signals.filter((signal) => signal.event === "session.idle"); + assert.equal(ends.length, 1, "a superseded answer read reports neither idle nor an answer"); + assert.equal(ends[0].requestId, starts[1].requestId); + assert.equal(signals.find((signal) => signal.event === "permission.replied").requestId, starts[1].requestId); + assert.equal(signals.find((signal) => signal.event === "session.status:retry").requestId, starts[1].requestId); + assert.equal(terminals.answer(childId).text, "second answer"); +}); + +test("an answer read that finishes after the next prompt was submitted is not that prompt's answer", POSIX, async (t) => { + const { terminals, gateway, handler, orchestrator, childId } = await setup(t); + const capability = gateway.registerSession(childId, "opencode", true); + const script = ` + const { CanvasTTYLifecycle } = await import(process.env.PLUGIN_URL); + const client = { session: { messages: async () => { + process.stdout.write("capturing"); + await new Promise((done) => process.stdin.once("data", done)); + return { data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "late preceding answer" }] }] }; + } } }; + const hooks = await CanvasTTYLifecycle({ client }); + const event = (type, rest = {}) => hooks.event({ event: { type, properties: { sessionID: "root", ...rest } } }); + await event("session.created", { info: { id: "root" } }); + await event("session.status", { status: { type: "busy" } }); + await event("session.idle"); + `; + const run = await runFakeOpenCode(capability, "unused", true, script, {}, () => terminals.deliverInput(childId, "next task\r")); + assert.equal(run.code, 0, run.stderr); + const result = await handler.execute(orchestrator.id, { id: "poll", tool: "get_agent_result", arguments: { sessionId: childId } }); + assert.equal(result.answer, undefined); + assert.equal(terminals.turnProgress(childId).turnStartedSincePrompt, false, "the late idle does not acknowledge the next prompt"); +}); + +test("approval continuations and repeated working events stay in the same turn", async (t) => { + const { terminals, childId } = await setupTerminals(t); + const apply = (state, event, turnId) => terminals.applyProviderSignal(childId, { kind: "lifecycle", state, event, requestId: turnId }); + assert.equal(apply("working", "session.status:busy", "turn1"), true); + const starts = terminals.sessions.get(childId).turnStarts; + assert.equal(apply("working", "session.status:busy", "turn1"), true); + assert.equal(apply("working", "session.status:retry", "turn1"), true); + assert.equal(terminals.sessions.get(childId).turnStarts, starts, "a repeated working or retry is not another start"); + assert.equal(apply("needs_approval", "permission.asked", "turn1"), true); + assert.equal(terminals.getMetadata(childId).status, "needs_approval"); + const generation = terminals.sessions.get(childId).inputGeneration ?? 0; + await terminals.deliverInput(childId, "y\r"); + assert.equal(terminals.sessions.get(childId).inputGeneration ?? 0, generation, "an approval answer keeps the current turn"); + assert.equal(apply("working", "permission.replied", "turn1"), true); + assert.equal(terminals.turnProgress(childId).turnStartedSincePrompt, true, "the continuation acknowledges the approval"); + const continued = terminals.sessions.get(childId).turnStarts; + assert.equal(apply("working", "session.status:retry", "turn1"), true); + assert.equal(terminals.sessions.get(childId).turnStarts, continued); + assert.equal(apply("idle", "session.idle", "turn1"), true); + terminals.recordAnswer(childId, { text: "answer after approval", truncated: false }, { turnId: "turn1" }); + assert.equal(terminals.answer(childId).text, "answer after approval"); + assert.equal(terminals.getMetadata(childId).status, "idle"); + terminals.input(childId, "next task\r"); + assert.equal(terminals.sessions.get(childId).inputGeneration, generation + 1); + assert.equal(apply("working", "permission.replied", "turn1"), false); +}); + +test("a result-capturing OpenCode does not report idle while its final answer is still being read", POSIX, async (t) => { + const { terminals, gateway, handler, orchestrator, childId } = await setup(t); + const capability = gateway.registerSession(childId, "opencode", true); + const script = ` + const { CanvasTTYLifecycle } = await import(process.env.PLUGIN_URL); + const client = { session: { messages: async () => { + process.stdout.write("capturing"); await new Promise((done) => process.stdin.once("data", done)); + return { data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "captured after delay" }] }] }; + } } }; + const hooks = await CanvasTTYLifecycle({ client }); + const event = (type, rest = {}) => hooks.event({ event: { type, properties: { sessionID: "root", ...rest } } }); + await event("session.created", { info: { id: "root" } }); + await event("session.status", { status: { type: "busy" } }); + await event("session.status", { status: { type: "idle" } }); + await event("session.idle"); + `; + const run = await runFakeOpenCode(capability, "unused", true, script, {}, () => { + assert.equal(terminals.getMetadata(childId).status, "working"); + assert.equal(terminals.answer(childId), null); + }); + assert.equal(run.code, 0, run.stderr); + const waited = await handler.execute(orchestrator.id, { id: "w", tool: "wait_for_agent", arguments: { sessionId: childId, timeoutSeconds: 5 } }); + assert.equal(waited.reason, "idle"); + assert.equal(waited.answer.text, "captured after delay"); +}); + +for (const failure of ["error", "timeout"]) test(`a captured OpenCode turn still ends, without an answer, after an SDK read ${failure}`, POSIX, async (t) => { + const { terminals, gateway, childId } = await setup(t); + const accepted = []; + const apply = terminals.applyProviderSignal.bind(terminals); + terminals.applyProviderSignal = (id, signal, ...args) => { accepted.push(signal); return apply(id, signal, ...args); }; + const capability = gateway.registerSession(childId, "opencode", true); + const script = ` + const { CanvasTTYLifecycle } = await import(process.env.PLUGIN_URL); + const client = { session: { messages: async () => { ${failure === "error" ? 'throw new Error("fixture failed");' : "return new Promise(() => {});"} } } }; + const hooks = await CanvasTTYLifecycle({ client }); + const event = (type, rest = {}) => hooks.event({ event: { type, properties: { sessionID: "root", ...rest } } }); + await event("session.created", { info: { id: "root" } }); await event("session.status", { status: { type: "busy" } }); + await event("session.status", { status: { type: "idle" } }); await event("session.idle"); + `; + const run = await runFakeOpenCode(capability, "unused", true, script); + assert.equal(run.code, 0, run.stderr); + assert.equal(accepted.filter((signal) => signal.event === "session.status:idle").length, 0); + assert.equal(accepted.filter((signal) => signal.event === "session.idle").length, 1, "the turn end is still reported"); + assert.equal(terminals.answer(childId), null); + assert.equal(terminals.getMetadata(childId).status, "idle"); +}); + +/** Feeds one runtime signal through the glue main uses, as the gateway would hand it over. */ +const signalFrom = (terminals, id) => (state, event, turnId, answer) => applyRuntimeSignal(terminals, id, + { state, event, turnId, ...(answer ? { result: { text: answer, truncated: false } } : {}) }); + +test("a person's Enter in the middle of a turn still lets that turn end the wait, without an answer", async (t) => { + const { terminals, handler, orchestrator, childId } = await setupTerminals(t); + const signal = signalFrom(terminals, childId); + assert.deepEqual(await terminals.deliverInput(childId, "orchestrator task\r"), { delivered: true }); + signal("working", "session.status:busy", "turn1"); + // The person presses Enter in the subagent's card while it works: the turn's answer is no longer for that prompt. + terminals.input(childId, "\r"); + const waiting = handler.execute(orchestrator.id, { id: "w", tool: "wait_for_agent", arguments: { sessionId: childId, timeoutSeconds: 5 } }); + setTimeout(() => signal("idle", "session.idle", "turn1", "answer to the earlier prompt"), 20); + const waited = await waiting; + assert.equal(waited.reason, "idle", "the wait does not hang until its timeout"); + assert.equal(waited.status, "idle"); + assert.equal(waited.answer, undefined); + assert.equal(waited.answerUnavailable, undefined, "status hooks are on: nothing says the answer cannot be captured"); +}); + +test("an answer that arrives as the agent exits is kept when it belongs to the current turn", async (t) => { + const { calls, terminals, handler, orchestrator, childId } = await setupTerminals(t); + const signal = signalFrom(terminals, childId); + await terminals.deliverInput(childId, "last task\r"); + signal("working", "session.status:busy", "turn1"); + calls.at(-1).process.emitExit(0); + assert.equal(terminals.getMetadata(childId).status, "done"); + signal("idle", "session.idle", "turn1", "final words"); + assert.equal(terminals.getMetadata(childId).status, "done", "the exit stays"); + const result = await handler.execute(orchestrator.id, { id: "r", tool: "get_agent_result", arguments: { sessionId: childId } }); + assert.equal(result.state, "done"); + assert.equal(result.answer?.text, "final words"); + // A late answer of an earlier turn still does not count after the exit. + signal("idle", "session.idle", "turn0", "stale"); + assert.equal(terminals.answer(childId)?.text, "final words"); +}); + +test("an Enter with nothing typed in an idle card keeps the stored answer", async (t) => { + const { terminals, childId } = await setupTerminals(t); + const signal = signalFrom(terminals, childId); + await terminals.deliverInput(childId, "task\r"); + signal("working", "session.status:busy", "turn1"); + signal("idle", "session.idle", "turn1", "kept answer"); + const generation = terminals.sessions.get(childId).inputGeneration; + terminals.input(childId, "\r"); + assert.equal(terminals.answer(childId)?.text, "kept answer", "an empty Enter submits nothing"); + assert.equal(terminals.sessions.get(childId).inputGeneration, generation); + // Typed key by key, as a person types: the Enter after it submits a new task. + for (const key of ["n", "e", "x", "t"]) terminals.input(childId, key); + terminals.input(childId, "\r"); + assert.equal(terminals.answer(childId), null); + assert.equal(terminals.sessions.get(childId).inputGeneration, generation + 1); +}); + +test("every input write goes through writeInput, which keeps the turn and answer bookkeeping", async (t) => { + const { terminals, childId } = await setupTerminals(t); + const signal = signalFrom(terminals, childId); + const writes = []; + const writeInput = terminals.writeInput; + assert.equal(typeof writeInput, "function", "one write path for person and agent input"); + terminals.writeInput = function (...args) { writes.push(args[3]); return writeInput.apply(this, args); }; + await terminals.deliverInput(childId, "task\r"); + terminals.input(childId, "x"); + assert.deepEqual(writes, ["task\r", "x"], "input() and deliverInput write through it"); + terminals.writeInput = writeInput; + signal("working", "session.status:busy", "turn1"); + signal("idle", "session.idle", "turn1", "kept answer"); + // A writer that held input and replays it later (outside input()) uses the same method: its Enter submits a task. + const session = terminals.sessions.get(childId); + const generation = session.inputGeneration; + for (const key of ["n", "e", "x", "t", "\r"]) assert.equal(terminals.writeInput(childId, session, session.process, key), true); + assert.equal(terminals.answer(childId), null, "the replayed prompt drops the earlier answer"); + assert.equal(session.inputGeneration, generation + 1); + // Never into a process the card no longer runs. + assert.equal(terminals.writeInput(childId, session, { write: () => assert.fail("stale process") }, "late\r"), false); + assert.equal(session.inputGeneration, generation + 1); +}); + +for (const [atCreate, beforeSpawn] of [[false, true], [true, false]]) { + test(`a deferred launch takes status hooks as they are when it is planned (${atCreate ? "on" : "off"} at create, ${beforeSpawn ? "on" : "off"} at launch)`, async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-ocr-deferred-"))); + t.after(() => rm(root, { recursive: true, force: true })); + let release; + const prepared = new Promise((resolve) => { release = resolve; }); + const pipeline = new LaunchPipeline({ + contributors: () => [{ pluginId: "fixture.hold", pluginName: "Hold", serviceId: "launch", secrets: false, + launch: { fields: [{ key: "on", label: "On", kind: "boolean", default: true }] } }], + call: async () => { await prepared; return {}; }, + secret: async () => null, + runsRoot: join(root, "runs"), + timeoutMs: 4_000 + }); + const calls = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, atCreate, fakeSpawner(calls)); + t.after(() => { release(); terminals.disposeAll(); }); + terminals.configureLaunchPipeline(pipeline); + const card = terminals.create({ provider: "opencode", cwd: root, profile: "normal", position: { x: 0, y: 0 }, + launchOptions: { "fixture.hold": { on: true } } }, { captureResult: true }); + terminals.setLifecycleHooksEnabled(beforeSpawn); + release(); + const deadline = Date.now() + 4_000; + while (calls.length === 0 && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5)); + assert.equal(calls.length, 1, "the launch spawned"); + assert.equal(terminals.answerUnavailable(card.id), beforeSpawn ? null : "status_hooks_off"); + assert.equal(terminals.applyProviderSignal(card.id, { kind: "lifecycle", state: "working", event: "session.status:busy", requestId: "t1" }), beforeSpawn); + }); +} diff --git a/tests/runtime-result-transport.test.mjs b/tests/runtime-result-transport.test.mjs new file mode 100644 index 000000000..af2be39e5 --- /dev/null +++ b/tests/runtime-result-transport.test.mjs @@ -0,0 +1,129 @@ +import assert from "node:assert/strict"; +import { spawn } from "node:child_process"; +import { realpathSync } from "node:fs"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { AGENT_RUNTIME_ENV, CAPTURE_RESULT_ENV } from "../src/agent-runtime/runtime-protocol.mjs"; +import { AgentControlService } from "../src/main/services/AgentControlService.ts"; +import { AgentRuntimeBridge } from "../src/main/services/agent-runtime/AgentRuntimeBridge.ts"; +import { RuntimeGateway } from "../src/main/services/agent-runtime/RuntimeGateway.ts"; +import { applyRuntimeSignal } from "../src/main/services/agent-runtime/applyRuntimeSignal.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { availableRegistry, inputReadySpawner } from "./helpers/terminal.mjs"; + +const POSIX = { timeout: 15_000, skip: process.platform === "win32" ? "Real Unix socket roundtrip; the Windows pipe transport has its own suite." : false }; +const helper = fileURLToPath(new URL("../src/agent-runtime/hook-helper.mjs", import.meta.url)); +const plugin = fileURLToPath(new URL("../src/agent-runtime/opencode-plugin.mjs", import.meta.url)); + +/** Runs a hook or plugin process the way the agent CLI would, with the launch's environment. */ +function run(args, env, input = "") { + const child = spawn(process.execPath, args, { env: { ...process.env, ...env }, stdio: ["pipe", "ignore", "pipe"] }); + const timeout = setTimeout(() => child.kill(), 5_000); + let stderr = ""; + child.stderr.on("data", (chunk) => { stderr += chunk; }); + child.stdin.end(input); + return new Promise((resolve, reject) => { + child.on("error", reject); + child.on("close", (code) => { clearTimeout(timeout); code === 0 ? resolve() : reject(new Error(stderr || `exit ${code}`)); }); + }); +} + +const openCodeTurn = (answer) => ` + const { CanvasTTYLifecycle } = await import(${JSON.stringify(new URL("../src/agent-runtime/opencode-plugin.mjs", import.meta.url).href)}); + const hooks = await CanvasTTYLifecycle({ client: { session: { messages: async () => ({ data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: ${JSON.stringify(answer)} }] }] }) } } }); + const event = (type, rest = {}) => hooks.event({ event: { type, properties: { sessionID: "worker-root", ...rest } } }); + await event("session.created", { info: { id: "worker-root" } }); + await event("session.status", { status: { type: "busy" } }); + await event("session.status", { status: { type: "idle" } }); + await event("session.idle"); +`; + +/** A real gateway, bridge and hook helper/plugin, with fake CLI PTYs; signals go through main's own glue. */ +async function fixture(t, statusHooks) { + const root = realpathSync(await mkdtemp(join(tmpdir(), "ctty-rt-"))); + const calls = []; + let terminals; + const gateway = new RuntimeGateway({ runtimeDirectory: root, onSignal: (id, signal) => applyRuntimeSignal(terminals, id, signal) }); + await gateway.start(); + const bridge = new AgentRuntimeBridge(gateway, { + runtimeDirectory: join(root, "configs"), helper: { command: process.execPath, args: [helper] }, openCodePluginPath: plugin, + coreHooksEnabled: statusHooks, environment: {}, + kimiHomeDirectory: join(root, "kimi"), hermesHomeDirectory: join(root, "hermes"), grokHomeDirectory: join(root, "grok") + }); + terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, bridge, statusHooks, inputReadySpawner(calls)); + t.after(async () => { + terminals.disposeAll(); + await gateway.close(); + await rm(root, { recursive: true, force: true }); + }); + const control = new AgentControlService(terminals, { waitTiming: { checkMs: 5, settleMs: 0, quietMs: 200 } }); + const parent = terminals.create({ provider: "codex", profile: "normal", cwd: root, role: "orchestrator", position: { x: 0, y: 0 } }); + // Status hooks are one switch: the bridge (hooks, leases) and the cards (status) follow it together, as in main. + const setStatusHooks = (enabled) => { + bridge.setCoreHooksEnabled(enabled); + terminals.setLifecycleHooksEnabled(enabled); + }; + return { root, calls, gateway, bridge, terminals, control, parent, setStatusHooks }; +} + +async function finishTurn(provider, env, answer) { + if (provider === "codex") { + await run([helper, "working", "UserPromptSubmit"], env, JSON.stringify({ turn_id: "fixture-turn" })); + await run([helper, "idle", "Stop"], env, JSON.stringify({ turn_id: "fixture-turn", last_assistant_message: answer })); + } else { + await run(["--input-type=module", "-e", openCodeTurn(answer)], env); + } +} + +for (const provider of ["codex", "opencode"]) { + test(`${provider} subagent's answer reaches wait_for_agent through its hooks while status hooks are on`, POSIX, async (t) => { + const f = await fixture(t, true); + const worker = await f.control.spawn({ parentSessionId: f.parent.id, provider, cwd: f.root }); + const env = f.calls.at(-1).options.env; + assert.equal(env[CAPTURE_RESULT_ENV], "1"); + assert.ok(env[AGENT_RUNTIME_ENV.capabilityToken]); + await f.terminals.deliverInput(worker.id, "worker task\r"); + await finishTurn(provider, env, "worker final answer"); + const waited = await f.control.waitFor(worker.id, { timeoutMs: 2_000 }); + assert.equal(waited.reason, "idle"); + assert.equal(waited.answer?.text, "worker final answer"); + assert.equal(waited.answerUnavailable, undefined); + + // Turning status hooks off revokes the lease: this launch has no hooks any more, and the result says so. + f.setStatusHooks(false); + assert.equal(f.gateway.currentStatus(worker.id), null); + assert.equal(f.control.result(worker.id).answer?.text, "worker final answer", "an answer captured earlier stays"); + await f.terminals.deliverInput(worker.id, "next task\r"); + const after = f.control.result(worker.id); + assert.equal(after.answer, undefined); + assert.equal(after.answerUnavailable?.reason, "status_hooks_off"); + }); + + test(`${provider} subagent started with status hooks off gets no hooks, and the wait says its answer cannot be captured`, POSIX, async (t) => { + const f = await fixture(t, false); + const worker = await f.control.spawn({ parentSessionId: f.parent.id, provider, cwd: f.root }); + const launch = f.calls.at(-1); + assert.equal(launch.options.env[AGENT_RUNTIME_ENV.capabilityToken], undefined, "no runtime lease"); + assert.deepEqual(launch.args.filter((arg) => typeof arg === "string" && /^hooks\./u.test(arg)), [], "no lifecycle hooks"); + await f.terminals.deliverInput(worker.id, "worker task\r"); + const waited = await f.control.waitFor(worker.id, { timeoutMs: 2_000 }); + assert.equal(waited.reason, "quiet"); + assert.equal(waited.status, "unavailable"); + assert.equal(waited.answer, undefined); + assert.equal(waited.answerUnavailable?.reason, "status_hooks_off"); + assert.match(waited.answerUnavailable.message, /status hooks are off/u); + + // Turning them on applies to agents started or restarted afterwards. + f.setStatusHooks(true); + assert.equal(f.control.result(worker.id).answerUnavailable?.reason, "status_hooks_off"); + launch.process.emitExit(0); + f.terminals.restart(worker.id); + const restarted = f.calls.at(-1); + assert.notEqual(restarted, launch); + assert.ok(restarted.options.env[AGENT_RUNTIME_ENV.capabilityToken], "the restarted launch has its hooks"); + assert.equal(f.control.result(worker.id).answerUnavailable, undefined); + }); +} diff --git a/tests/terminal-lifecycle.test.mjs b/tests/terminal-lifecycle.test.mjs index c1e7c124e..fc1b3e545 100644 --- a/tests/terminal-lifecycle.test.mjs +++ b/tests/terminal-lifecycle.test.mjs @@ -290,15 +290,31 @@ test("session metadata revisions advance before lifecycle events cross IPC", asy assert.match(source, /metadata\.revision \+= 1;[\s\S]{0,120}?this\.emit\(IPC\.terminalSession/); }); -test("revoking lifecycle hooks makes live agent status unavailable until a restarted session gets a new parser", async () => { +test("revoking lifecycle hooks makes live agent status unavailable until a restarted session gets a new parser", async (t) => { const source = await readFile(terminalManagerPath, "utf8"); - - assert.match(source, /setLifecycleHooksEnabled\(enabled: boolean\): void/); - assert.match(source, /this\.lifecycleHooksEnabled = next;\s*if \(next\) return;/); - assert.match(source, /session\.lifecycle = null;/); - assert.match(source, /session\.metadata\.provider === "terminal"/); - assert.match(source, /session\.metadata\.status = "unavailable";\s*this\.emitSession\(session\.metadata\)/); - assert.match(source, /if \(!this\.lifecycleHooksEnabled \|\| !session/); + const { TerminalManager } = await import("../src/main/services/TerminalManager.ts"); + const { availableRegistry, fakeSpawner } = await import("./helpers/terminal.mjs"); + const manager = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner([])); + t.after(() => manager.disposeAll()); + const session = manager.create({ provider: "codex", profile: "normal", cwd: process.cwd(), position: { x: 0, y: 0 } }); + const shell = manager.create({ provider: "terminal", profile: "normal", cwd: process.cwd(), position: { x: 0, y: 0 } }); + const shellStatus = manager.getMetadata(shell.id).status; + manager.applyProviderSignal(session.id, { kind: "lifecycle", state: "working" }); + assert.equal(manager.getMetadata(session.id).status, "working"); + manager.setLifecycleHooksEnabled(false); + assert.equal(manager.getMetadata(session.id).status, "unavailable"); + assert.equal(manager.sessions.get(session.id).lifecycle, null); + assert.equal(manager.getMetadata(shell.id).status, shellStatus, "a plain terminal has no agent status to revoke"); + for (const state of ["needs_approval", "working", "idle"]) { + manager.applyProviderSignal(session.id, { kind: "lifecycle", state }); + assert.equal(manager.getMetadata(session.id).status, "unavailable", "a hook signal never restores a disabled status"); + } + manager.setLifecycleHooksEnabled(true); + manager.applyProviderSignal(session.id, { kind: "lifecycle", state: "working" }); + assert.equal(manager.getMetadata(session.id).status, "unavailable", "re-enabling applies only to new or restarted sessions"); + const fresh = manager.create({ provider: "codex", profile: "normal", cwd: process.cwd(), position: { x: 0, y: 0 } }); + manager.applyProviderSignal(fresh.id, { kind: "lifecycle", state: "working" }); + assert.equal(manager.getMetadata(fresh.id).status, "working"); assert.match(source, /session\.lifecycle = this\.lifecycleHooksEnabled\s*\? createProviderLifecycleParser/); }); @@ -306,8 +322,9 @@ test("only explicit turn-stop hooks set completed art and a new turn clears it", const [card, manager, main] = await Promise.all([ readFile(terminalCardPath, "utf8"), readFile(terminalManagerPath, "utf8"), - readFile(new URL("../src/main/index.ts", import.meta.url), "utf8") + readFile(new URL("../src/main/services/agent-runtime/applyRuntimeSignal.ts", import.meta.url), "utf8") ]); + // main/index.ts hands every runtime signal to applyRuntimeSignal, which passes the hook's event on. assert.match(main, /state: signal\.state,\s*event: signal\.event/); assert.match(manager, /\["Stop", "StopFailure", "StopCancelled"\]\.includes\(signal\.event \?\? ""\)/); assert.match(manager, /nextStatus === "working" \? false : completed \|\| Boolean\(session\.metadata\.turnCompleted\)/); From cac98b6d21dc50e9d94e0fc2f05099cce2863368 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Mon, 12 Oct 2026 12:10:28 +0000 Subject: [PATCH 8/9] fix(runtime): keep a turn whose start hook was lost, and map PostToolUseFailure Once a turn id was active, the gateway dropped every non-start event with a new turn id. Each hook runs on its own connection and can time out, so when a turn's start hook was lost the whole turn, including its Stop, was ignored and the card kept the previous turn's status. The gateway now tracks whether a turn is open. After an idle, an unseen turn id opens the next turn; during an open turn, or for an id already seen, the event is still dropped as out of order. When a tool the person approved fails, the agent CLI runs PostToolUseFailure instead of PostToolUse. CanvasTTY did not register it, so the card stayed needs_approval until the next hook although the turn went on. It now maps to working. --- .../agent-runtime/ProviderRuntimeLaunch.ts | 2 ++ .../services/agent-runtime/RuntimeGateway.ts | 23 +++++++++++----- tests/agent-runtime-gateway.test.mjs | 26 +++++++++++++++++++ tests/agent-runtime-provider-launch.test.mjs | 1 + tests/claude-http-hooks.test.mjs | 2 +- 5 files changed, 46 insertions(+), 8 deletions(-) diff --git a/src/main/services/agent-runtime/ProviderRuntimeLaunch.ts b/src/main/services/agent-runtime/ProviderRuntimeLaunch.ts index a945496fe..949d29ba3 100644 --- a/src/main/services/agent-runtime/ProviderRuntimeLaunch.ts +++ b/src/main/services/agent-runtime/ProviderRuntimeLaunch.ts @@ -406,6 +406,8 @@ const CLAUDE_HOOKS: readonly HookMapping[] = [ { event: "UserPromptSubmit", state: "working" }, { event: "PermissionRequest", state: "needs_approval" }, { event: "PostToolUse", state: "working" }, + // An approved tool that fails runs PostToolUseFailure, not PostToolUse: the turn goes on after the approval. + { event: "PostToolUseFailure", state: "working" }, { event: "Stop", state: "idle" }, { event: "StopFailure", state: "idle" }, { event: "SessionEnd", state: "idle" }, diff --git a/src/main/services/agent-runtime/RuntimeGateway.ts b/src/main/services/agent-runtime/RuntimeGateway.ts index 97015bf66..42a27aad8 100644 --- a/src/main/services/agent-runtime/RuntimeGateway.ts +++ b/src/main/services/agent-runtime/RuntimeGateway.ts @@ -79,6 +79,8 @@ interface RuntimeLease { provider: Exclude; tokenDigest: Buffer; activeTurnId: string | null; + /** A turn started and has not reported idle yet; between turns an unseen turn id may open the next one. */ + turnOpen: boolean; /** Turn ids this session already reported (bounded, oldest dropped): a late start of one of them is stale. */ seenTurnIds: Set; latest: RuntimeLifecycleSignal | null; @@ -276,6 +278,7 @@ export class RuntimeGateway { provider, tokenDigest: tokenDigest(capabilityToken), activeTurnId: null, + turnOpen: false, seenTurnIds: new Set(), latest: null, captureResult: captureResultOrGrantExpiresAt === true, @@ -469,21 +472,27 @@ export class RuntimeGateway { throw new Error("Answer capture is not authorized for this session."); } - if (message.turnId && isTurnStart(message.event)) { + const startsTurn = isTurnStart(message.event); + if (message.turnId && startsTurn) { // Each hook runs on its own connection, so a start of an earlier turn can arrive after the next turn began; // it must not make that newer turn's events look stale. if (message.turnId !== lease.activeTurnId && lease.seenTurnIds.has(message.turnId)) return null; lease.activeTurnId = message.turnId; + lease.turnOpen = true; + rememberTurn(lease, message.turnId); + } else if (message.turnId && message.turnId !== lease.activeTurnId) { + // A turn whose start hook was lost (it timed out, or the CLI skipped it) still counts: after an idle, an + // unseen id opens the next turn. During an open turn, or for an id already seen, the event is out of order. + if (lease.activeTurnId && (lease.turnOpen || lease.seenTurnIds.has(message.turnId))) return null; + lease.activeTurnId = message.turnId; + lease.turnOpen = true; rememberTurn(lease, message.turnId); - } else if ( - message.turnId - && lease.activeTurnId - && message.turnId !== lease.activeTurnId - ) { - return null; } else if (message.turnId) { rememberTurn(lease, message.turnId); + } else if (startsTurn) { + lease.turnOpen = true; } + if (message.state === "idle") lease.turnOpen = false; const signal: RuntimeLifecycleSignal = { state: message.state, event: message.event, diff --git a/tests/agent-runtime-gateway.test.mjs b/tests/agent-runtime-gateway.test.mjs index 61ec999da..67e8bc0df 100644 --- a/tests/agent-runtime-gateway.test.mjs +++ b/tests/agent-runtime-gateway.test.mjs @@ -158,6 +158,32 @@ test("RuntimeGateway: a late start of an earlier turn does not take over from th assert.equal(gateway.currentStatus("terminal-turns"), "idle"); }); +test("RuntimeGateway: a turn whose start hook was lost still counts after an idle, but not while another turn runs", POSIX_RUNTIME_GATEWAY_TEST, async (t) => { + const root = await fixture(t); + const signals = []; + const gateway = new RuntimeGateway({ runtimeDirectory: root, onSignal: (id, signal) => signals.push({ id, signal }) }); + await gateway.start(); + t.after(() => gateway.close()); + const capability = gateway.registerSession("terminal-lost-start", "codex"); + await send(capability.address, message(capability, "working", "UserPromptSubmit", "turn-1")); + // An event of another turn while turn 1 runs is out of order. + await send(capability.address, message(capability, "working", "PostToolUse", "turn-x")); + await send(capability.address, message(capability, "idle", "Stop", "turn-1")); + // Turn 2's UserPromptSubmit never arrived: its own events still report it. + await send(capability.address, message(capability, "working", "PostToolUse", "turn-2")); + assert.equal(gateway.currentStatus("terminal-lost-start"), "working"); + // A late event of the earlier turn stays stale. + await send(capability.address, message(capability, "idle", "Stop", "turn-1")); + await send(capability.address, message(capability, "idle", "Stop", "turn-2")); + // After that idle, an id already seen does not open a turn again. + await send(capability.address, message(capability, "working", "PostToolUse", "turn-1")); + await new Promise((resolve) => setImmediate(resolve)); + assert.deepEqual(signals.map(({ signal }) => `${signal.state}:${signal.event}:${signal.turnId}`), [ + "working:UserPromptSubmit:turn-1", "idle:Stop:turn-1", "working:PostToolUse:turn-2", "idle:Stop:turn-2" + ]); + assert.equal(gateway.currentStatus("terminal-lost-start"), "idle"); +}); + test("RuntimeGateway propagates threadId for codex sessions with canonical UUID", POSIX_RUNTIME_GATEWAY_TEST, async (t) => { const root = await fixture(t); const signals = []; diff --git a/tests/agent-runtime-provider-launch.test.mjs b/tests/agent-runtime-provider-launch.test.mjs index c1183d439..c3966d872 100644 --- a/tests/agent-runtime-provider-launch.test.mjs +++ b/tests/agent-runtime-provider-launch.test.mjs @@ -46,6 +46,7 @@ test("Claude and Codex receive automatic lifecycle hooks without prompt or respo assert.equal(settings.showStatusInTerminalTab, true); assert.match(settings.hooks.UserPromptSubmit[0].hooks[0].command, /working.*UserPromptSubmit/u); assert.match(settings.hooks.PermissionRequest[0].hooks[0].command, /needs_approval.*PermissionRequest/u); + assert.match(settings.hooks.PostToolUseFailure[0].hooks[0].command, /working.*PostToolUseFailure/u); assert.match(settings.hooks.Stop[0].hooks[0].command, /idle.*Stop/u); assert.match(settings.hooks.Stop[0].hooks[0].command, /^ELECTRON_RUN_AS_NODE='1' /u); assert.equal(JSON.stringify(settings).includes('"prompt":'), false); diff --git a/tests/claude-http-hooks.test.mjs b/tests/claude-http-hooks.test.mjs index fb649ea87..94791bd48 100644 --- a/tests/claude-http-hooks.test.mjs +++ b/tests/claude-http-hooks.test.mjs @@ -262,7 +262,7 @@ test("Claude's lifecycle hooks become HTTP hooks except SessionStart; the decisi assert.equal(settings.hooks.PreToolUse[0].hooks[0].type, "command"); assert.match(settings.hooks.PreToolUse[0].hooks[0].command, /permission-gate\.mjs' 'pretool'/u); for (const [event, state] of [["UserPromptSubmit", "working"], ["PermissionRequest", "needs_approval"], ["PostToolUse", "working"], - ["Stop", "idle"], ["StopFailure", "idle"], ["SessionEnd", "idle"], ["Notification", "needs_approval"]]) { + ["PostToolUseFailure", "working"], ["Stop", "idle"], ["StopFailure", "idle"], ["SessionEnd", "idle"], ["Notification", "needs_approval"]]) { const hook = settings.hooks[event][0].hooks[0]; assert.deepEqual(hook, { type: "http", From e88f2a3e89680e2f359c4f3f940f38c94e90fc34 Mon Sep 17 00:00:00 2001 From: BIackFIame <77388790+BIackFIame@users.noreply.github.com> Date: Tue, 13 Oct 2026 14:00:00 +0000 Subject: [PATCH 9/9] fix(orchestration): return a subagent's screen as plain text wait_for_agent, get_agent_result and observe_agent returned the raw PTY tail, which for a full-screen TUI such as OpenCode is cursor moves, colours and spinner redraws, often starting mid-sequence. They now render the masked scrollback window (the last 65,536 characters) through the existing headless xterm at the session's size and return the visible text, masked again and capped as before (observe_agent within its maxChars). A cut window starts at its first escape or line break, so the rest of a cut sequence ("18;9H") is never printed as text. exitLines were the regex-stripped last 16 KiB, so a TUI that redraws only the cells that changed read as its redraws joined together, and a line drawn early and never redrawn (the model's status line) was lost. They are now rendered by the same headless terminal from the same window, masked before and after, and the three tools return the same exitLines. --- docs/agent-orchestration.md | 2 +- native/canvastty-helper/catalog.json | 6 +- src/agent-browser/orchestration-catalog.mjs | 6 +- src/main/services/AgentControlService.ts | 106 ++++++++++--- .../agent-browser/OrchestrationTools.ts | 12 +- src/main/services/terminalScreenText.ts | 35 +++++ tests/agent-control.test.mjs | 14 +- tests/launch-contributors.test.mjs | 4 +- tests/orchestration-providers-wait.test.mjs | 143 ++++++++++++++++++ tests/runtime-result-transport.test.mjs | 8 +- tests/secret-redaction.test.mjs | 15 +- tests/subagent-signal-exit.test.mjs | 4 +- 12 files changed, 297 insertions(+), 58 deletions(-) create mode 100644 src/main/services/terminalScreenText.ts diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index 1211afb4c..1e5294d06 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -11,7 +11,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`. Plugin launch options the call does not name are inherited from the orchestrator for a subagent of the same CLI (see Plugin launch options below); `model` next to inherited options that set the model is refused, and so is a subagent of another CLI while the orchestrator's model comes from a plugin's options. The answer's `servedBy` is `{ provider, model, launchOptions: { : "inherited" | "explicit" } }`. 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 ≤ 100 }` (default 50). 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 `output` and a `message` to call again. 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`, the masked terminal tail (masked before it is cut) and, for Codex and OpenCode subagents, `answer` (see `get_agent_result`). A turn that the person interrupted by submitting their own input in the subagent's card still ends the wait, without an `answer`: that answer is no longer for the orchestrator's prompt. With CanvasTTY status hooks off (Settings → Agents) a subagent has no hooks at all, so no `answer` can be captured: the result carries `answerUnavailable: { reason: "status_hooks_off", message }` instead and the wait ends `quiet`; read `output` (or `observe_agent`). Turning status hooks on applies to subagents started or restarted afterwards. 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, kept only for the turn it ended and cleared when the next input is submitted or the next turn starts; an Enter with nothing typed in an idle card keeps it; an answer reported as the subagent exits still counts; `answerUnavailable` instead when status hooks are off), 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. | +| `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, kept only for the turn it ended and cleared when the next input is submitted or the next turn starts; an Enter with nothing typed in an idle card keeps it; an answer reported as the subagent exits still counts; `answerUnavailable` instead when status hooks are off), 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, 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 masked plain text, rendered like `wait_for_agent`'s `output` (at most `maxChars`). | | `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. Prompts to one subagent arrive in the order they were sent. OpenCode drops keys typed while it starts, so a prompt for it (also `spawn_agent`'s first one) is typed only once its input field is up: the terminal control sequence that shows its text cursor on its full screen, or a lifecycle hook only 2 s after its first one (OpenCode's plugin can report shortly before the field takes keys). This wait is used on macOS and Linux; on Windows, whose pseudo console may not pass those sequences, OpenCode gets input as soon as its PTY exists, as before. `spawn_agent` (its checks, the launch and this wait together) and `send_to_agent` wait at most 45 s, under the MCP client's tool deadline; then the call fails with the reason and the session id, and nothing is typed. A send cancelled while it waits returns at once. | ### Subagent profiles diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index b273493bb..ab71c4250 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -1072,7 +1072,7 @@ }, { "name": "observe_agent", - "description": "Read the capped terminal tail and status of one of this session's subagents.", + "description": "Read the status of one of this session's subagents and the end of its screen as masked plain text (once its process exited, also exitLines).", "inputSchema": { "type": "object", "properties": { @@ -1095,7 +1095,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 50, at most 100; 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 CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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.", + "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 50, at most 100; 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 end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents; when CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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": { @@ -1118,7 +1118,7 @@ }, { "name": "get_agent_result", - "description": "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", + "description": "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the end of its screen as masked plain text as output (what the terminal shows, without control sequences). Prefer answer. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", "inputSchema": { "type": "object", "properties": { diff --git a/src/agent-browser/orchestration-catalog.mjs b/src/agent-browser/orchestration-catalog.mjs index 64b0f1d1d..3829b3f62 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -82,19 +82,19 @@ export const ORCHESTRATION_TOOL_DEFINITIONS = Object.freeze([ ), tool( "observe_agent", - "Read the capped terminal tail and status of one of this session's subagents.", + "Read the status of one of this session's subagents and the end of its screen as masked plain text (once its process exited, also exitLines).", { sessionId, maxChars: integer({ minimum: 256, maximum: 8_192 }) }, ["sessionId"] ), 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}; 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 CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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.`, + `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 end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents; when CanvasTTY status hooks are off it cannot be captured and answerUnavailable says so instead: then read output); 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"] ), tool( "get_agent_result", - "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the masked terminal tail as output. Prefer answer; the terminal tail is raw screen output. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", + "Get one of this session's subagents' result: answer (its last turn's final reply as the agent reported it, for Codex and OpenCode subagents; truncated:true when only the end was kept), status (idle once its turn ended), the exit state (running | done | failed; an interactive CLI stays running after a task) and the end of its screen as masked plain text as output (what the terminal shows, without control sequences). Prefer answer. answerUnavailable (reason status_hooks_off) means no answer can be captured because CanvasTTY status hooks are off: read output instead.", { sessionId }, ["sessionId"] ), diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index 2b587ca9d..579ffefe8 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -14,6 +14,7 @@ import type { TerminalManager } from "./TerminalManager.ts"; import { onDiskPath, otherSpellings } from "./onDiskPath.ts"; import { LaunchRefusal } from "./launchRefusal.ts"; import { terminalFailureDetails } from "./terminalFailureDetails.ts"; +import { terminalScreenText } from "./terminalScreenText.ts"; import { RESULT_CAPTURE_PROVIDERS } from "./resultCapture.ts"; // Cards one parent may have in total, live or exited (the live limit is the person's setting). @@ -29,8 +30,12 @@ export interface DelegationLimits { } const MAX_OBSERVE_CHARS = 8_192; // An exited agent's reason is in its last screen lines (OpenCode: "Error: Unexpected server error" for an unknown model). -const MAX_EXIT_WINDOW_CHARS = 16_384; const MAX_EXIT_LINES = 20; +/** + * How much of the scrollback (masked first) the plain-text output is rendered from: several full redraws of a + * full-screen TUI, and many screens of a line-based CLI, while each call still masks a bounded window. + */ +const MAX_SCREEN_SOURCE_CHARS = 65_536; const CHILD_POSITION_STEP = { x: 60, y: 60 }; export interface SpawnAgentRequest { @@ -51,7 +56,7 @@ export interface SpawnAgentRequest { export interface AgentObservation { sessionId: string; status: SessionSnapshot["status"]; - /** Raw terminal tail, capped; capabilities with result \"none\" see nothing. */ + /** The screen's text as a terminal shows it (no control sequences), masked, capped to its last characters. */ output: string; /** Once the process exited: its exit code and the last lines of its screen as plain text, masked. */ exitCode?: number | null; @@ -69,7 +74,7 @@ export interface AgentWaitResult { status?: SessionSnapshot["status"]; exitCode: number | null; waitedMs: number; - /** Masked terminal tail (masked before the cut). */ + /** The screen's text as a terminal shows it (no control sequences), masked, capped to its last characters. */ output: string; /** Once the process exited: the last lines of its screen as plain text, masked (why it stopped, e.g. a bad model). */ exitLines?: string; @@ -107,6 +112,7 @@ export interface AgentResult { /** The session's status (idle once its turn ended; state stays "running" while the CLI is open). */ status: SessionSnapshot["status"]; exitCode: number | null; + /** The screen's text as a terminal shows it (no control sequences), masked, capped to its last characters. */ output: string; /** Once the process exited: the last lines of its screen as plain text, masked. */ exitLines?: string; @@ -352,25 +358,28 @@ export class AgentControlService { return false; } - observe(sessionId: string, maxChars = MAX_OBSERVE_CHARS): AgentObservation { - const session = this.requireSession(sessionId); - if (session.provider === "terminal") throw new Error("Plain terminals are not agents."); - const capabilities = PROVIDER_CAPABILITIES[session.provider as AgentProviderId]; - if (!capabilities.observe) throw new Error(`${session.provider} cannot be observed.`); + async observe(sessionId: string, maxChars = MAX_OBSERVE_CHARS): Promise { + const session = this.observableSession(sessionId); const buffer = this.terminals.readBuffer(sessionId).buffer; - const exitLines = session.exitCode === null ? null : this.exitLines(buffer); + const exitLines = session.exitCode === null ? null : await this.screenExitLines(sessionId, buffer); return { sessionId: session.id, status: session.status, - // Masked before the cut (a cut inside a secret would leave a tail no pattern recognizes), over a window - // wider than any match rather than the whole scrollback. - output: this.redactTail(buffer, maxChars), + output: await this.screenText(sessionId, buffer, maxChars), ...(session.exitCode === null ? {} : { exitCode: session.exitCode }), ...(exitLines ? { exitLines } : {}) }; } - result(sessionId: string): AgentResult { + private observableSession(sessionId: string): SessionMetadata { + const session = this.requireSession(sessionId); + if (session.provider === "terminal") throw new Error("Plain terminals are not agents."); + const capabilities = PROVIDER_CAPABILITIES[session.provider as AgentProviderId]; + if (!capabilities.observe) throw new Error(`${session.provider} cannot be observed.`); + return session; + } + + async result(sessionId: string): Promise { const session = this.requireSession(sessionId); if (session.provider === "terminal") throw new Error("Plain terminals are not agents."); const capabilities = PROVIDER_CAPABILITIES[session.provider as AgentProviderId]; @@ -381,6 +390,7 @@ export class AgentControlService { const buffer = capabilities.result === "terminal" ? this.terminals.readBuffer(sessionId).buffer : ""; + const exitLines = session.exitCode === null ? null : await this.screenExitLines(sessionId, buffer); return { sessionId: session.id, state: session.exitCode === null @@ -388,8 +398,8 @@ export class AgentControlService { : session.exitCode === 0 ? "done" : "failed", status: session.status, exitCode: session.exitCode, - output: this.redactTail(buffer, MAX_OBSERVE_CHARS), - ...(session.exitCode !== null && this.exitLines(buffer) ? { exitLines: this.exitLines(buffer)! } : {}), + output: buffer ? await this.screenText(sessionId, buffer, MAX_OBSERVE_CHARS) : "", + ...(exitLines ? { exitLines } : {}), ...(answer ? { answer } : this.answerUnavailable(sessionId)) }; } @@ -408,14 +418,23 @@ export class AgentControlService { const timing = this.options.waitTiming ?? AGENT_WAIT_TIMING; const timeoutMs = Math.min(MAX_AGENT_WAIT_MS, Math.max(0, request.timeoutMs)); const started = Date.now(); - const answer = (session: SessionMetadata | null, reason: AgentWaitReason): AgentWaitResult => { + const answer = async (session: SessionMetadata | null, reason: AgentWaitReason): Promise => { const waitedMs = Date.now() - started; if (!session) return { sessionId, reason, exitCode: null, waitedMs, output: "" }; - let observation: AgentObservation | null = null; - try { observation = this.observe(sessionId); } catch { observation = null; } + let observable = false; + try { observable = Boolean(this.observableSession(sessionId)); } catch { observable = false; } + let output = ""; + let exitLines: string | null = null; + if (observable) { + try { + const buffer = this.terminals.readBuffer(sessionId).buffer; + output = await this.screenText(sessionId, buffer, MAX_OBSERVE_CHARS); + if (session.exitCode !== null) exitLines = await this.screenExitLines(sessionId, buffer); + } catch { output = ""; } + } const answer = reason === "timeout" || reason === "needs_approval" ? null : this.answer(sessionId); - return { sessionId, reason, status: session.status, exitCode: session.exitCode, waitedMs, output: observation?.output ?? "", - ...(observation?.exitLines ? { exitLines: observation.exitLines } : {}), ...(answer ? { answer } : this.answerUnavailable(sessionId)) }; + return { sessionId, reason, status: session.status, exitCode: session.exitCode, waitedMs, output, + ...(exitLines ? { exitLines } : {}), ...(answer ? { answer } : this.answerUnavailable(sessionId)) }; }; let offset = this.outputOffset(sessionId); let changedAt = started; @@ -456,13 +475,44 @@ export class AgentControlService { } } - /** The last lines of an exited agent's screen as plain text: masked over the whole tail window before it is cut. */ - private exitLines(buffer: string): string | null { - const text = terminalFailureDetails(this.redactTail(buffer, MAX_EXIT_WINDOW_CHARS)); + /** + * The last lines of the screen, rendered like `output` (a TUI that redraws only the cells that changed would + * otherwise read as its redraws joined together) from the same window as `output` (a line drawn early and never + * redrawn, such as the model's status line, is still on the screen), masked before it is cut and again after. + */ + private async screenExitLines(sessionId: string, buffer: string): Promise { + const source = fromSequenceBoundary(this.redactTail(buffer, MAX_SCREEN_SOURCE_CHARS), buffer.length > MAX_SCREEN_SOURCE_CHARS); + let screen: string; + try { + screen = this.redactTail(await terminalScreenText(source, this.geometry(sessionId)), MAX_SCREEN_SOURCE_CHARS); + } catch { + screen = source; + } + const text = terminalFailureDetails(screen); if (!text) return null; return text.split("\n").slice(-MAX_EXIT_LINES).join("\n"); } + /** + * The text the agent's terminal shows, as plain text: a TUI's redraws (cursor moves, erases, colors) rendered by a + * headless terminal instead of returned as escape sequences. Masked twice: the scrollback before it is rendered + * (a held value the TUI wrote whole is gone before any redraw can split it), and the rendered text before its + * last `maxChars` are cut (a value the screen shows across wrapped rows or box sides). Should the rendering fail, + * the masked raw tail is returned as before. + */ + private async screenText(sessionId: string, buffer: string, maxChars: number): Promise { + const source = fromSequenceBoundary(this.redactTail(buffer, MAX_SCREEN_SOURCE_CHARS), buffer.length > MAX_SCREEN_SOURCE_CHARS); + try { + return this.redactTail(await terminalScreenText(source, this.geometry(sessionId)), maxChars); + } catch { + return this.redactTail(buffer, maxChars); + } + } + + private geometry(sessionId: string): { cols: number; rows: number } | null { + try { return typeof this.terminals.geometry === "function" ? this.terminals.geometry(sessionId) : null; } catch { return null; } + } + /** Plugin launch secrets never reach another agent through observed output: the tail as masking the whole text leaves it. */ private redactTail(text: string, maxChars: number): string { if (typeof this.terminals.redactSecretsTail === "function") return this.terminals.redactSecretsTail(text, maxChars); @@ -597,3 +647,13 @@ function tail(text: string, maxChars: number): string { function spawnCanceled(): Error { return new DOMException("The spawn was canceled before its agent started.", "AbortError"); } + +/** + * A window cut from the end of a terminal stream may begin inside an escape sequence, whose rest (`18;9H`, `m`) a + * terminal would print as text. A cut window therefore starts at its first escape or line break instead. + */ +function fromSequenceBoundary(window: string, cut: boolean): string { + if (!cut) return window; + const starts = [window.indexOf("\u001b"), window.indexOf("\n")].filter((index) => index >= 0); + return starts.length > 0 ? window.slice(Math.min(...starts)) : window; +} diff --git a/src/main/services/agent-browser/OrchestrationTools.ts b/src/main/services/agent-browser/OrchestrationTools.ts index d1273825a..28566b785 100644 --- a/src/main/services/agent-browser/OrchestrationTools.ts +++ b/src/main/services/agent-browser/OrchestrationTools.ts @@ -73,9 +73,9 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { case "send_to_agent": return await this.send(sessionId, request.arguments, signal); case "observe_agent": - return this.observe(sessionId, request.arguments); + return await this.observe(sessionId, request.arguments); case "get_agent_result": - return this.result(sessionId, request.arguments); + return await this.result(sessionId, request.arguments); case "cancel_agent": return this.cancel(sessionId, request.arguments); case "list_agents": @@ -223,9 +223,9 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { return { sessionId: args.sessionId as string, sent: true }; } - private observe(orchestratorId: string, args: Record): Record { + private async observe(orchestratorId: string, args: Record): Promise> { this.requireOwned(orchestratorId, args.sessionId as string); - const observation = this.control.observe( + const observation = await this.control.observe( args.sessionId as string, args.maxChars as number | undefined ); @@ -238,9 +238,9 @@ export class ScopedOrchestrationHandler implements OrchestrationCommandHandler { }; } - private result(orchestratorId: string, args: Record): Record { + private async result(orchestratorId: string, args: Record): Promise> { this.requireOwned(orchestratorId, args.sessionId as string); - const result = this.control.result(args.sessionId as string); + const result = await this.control.result(args.sessionId as string); return { sessionId: result.sessionId, state: result.state, diff --git a/src/main/services/terminalScreenText.ts b/src/main/services/terminalScreenText.ts new file mode 100644 index 000000000..6adf8db5b --- /dev/null +++ b/src/main/services/terminalScreenText.ts @@ -0,0 +1,35 @@ +import { lazyRequire } from "../lazyRequire.ts"; + +const xterm = lazyRequire("@xterm/headless"); + +/** Rows of scrollback the rendering keeps above the screen: the tail an orchestrator reads is far shorter. */ +const SCROLLBACK_ROWS = 500; +const DEFAULT_GEOMETRY = { cols: 120, rows: 40 }; + +/** + * What a terminal shows for `data` as plain text: the scrollback rows and the screen (the alternate screen of a + * full-screen TUI such as OpenCode, which keeps no scrollback), as a headless xterm renders them, so cursor moves, + * redraws, erases and colors leave only the text a person sees. A row the terminal wrapped continues its line; + * trailing blanks and empty rows at the end are dropped. + */ +export async function terminalScreenText(data: string, geometry: { cols: number; rows: number } | null): Promise { + const { cols, rows } = geometry && geometry.cols > 0 && geometry.rows > 0 ? geometry : DEFAULT_GEOMETRY; + const terminal = new (xterm().Terminal)({ cols, rows, scrollback: SCROLLBACK_ROWS, allowProposedApi: true }); + try { + await new Promise((resolve) => terminal.write(data, resolve)); + const buffer = terminal.buffer.active; + const lines: string[] = []; + for (let row = 0; row < buffer.length; row++) { + const line = buffer.getLine(row); + if (!line) continue; + // Untrimmed, so a space the wrap fell on stays between the words; each line is trimmed once it is whole. + const text = line.translateToString(false); + if (line.isWrapped && lines.length > 0) lines[lines.length - 1] += text; + else lines.push(text); + } + while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop(); + return lines.map((line) => line.trimEnd()).join("\n"); + } finally { + terminal.dispose(); + } +} diff --git a/tests/agent-control.test.mjs b/tests/agent-control.test.mjs index 58ad664bc..8b7ce971d 100644 --- a/tests/agent-control.test.mjs +++ b/tests/agent-control.test.mjs @@ -709,7 +709,7 @@ test("send appends submit unless told otherwise and rejects exited sessions", as terminals.disposeAll(); }); -test("observe returns a capped terminal tail and result reflects exit state", () => { +test("observe returns a capped terminal tail and result reflects exit state", async () => { const { terminals, control } = serviceFixture(); const parent = terminals.create({ provider: "codex", @@ -717,11 +717,11 @@ test("observe returns a capped terminal tail and result reflects exit state", () profile: "normal", position: { x: 0, y: 0 } }); - const observation = control.observe(parent.id); + const observation = await control.observe(parent.id); assert.equal(observation.sessionId, parent.id); assert.equal(observation.output.length <= 8_192, true); - const running = control.result(parent.id); + const running = await control.result(parent.id); assert.equal(running.state, "running"); assert.equal(running.exitCode, null); terminals.disposeAll(); @@ -746,8 +746,8 @@ test("cancel disposes the subagent and plain terminals are not agents", async () assert.equal(terminals.list().some((session) => session.id === child.id), false); assert.throws(() => control.send(terminal.id, "text"), /not agents/u); - assert.throws(() => control.observe(terminal.id), /not agents/u); - assert.throws(() => control.result(terminal.id), /not agents/u); + await assert.rejects(control.observe(terminal.id), /not agents/u); + await assert.rejects(control.result(terminal.id), /not agents/u); terminals.disposeAll(); }); @@ -805,8 +805,8 @@ test("an orchestrator tool call looks its sessions up by id: no other card's scr assert.equal(control.status(child.id).id, child.id); assert.equal(control.isInSubtree(parent.id, child.id), true); assert.deepEqual(control.children(parent.id).map((session) => session.id), [child.id]); - control.observe(child.id); - control.result(child.id); + await control.observe(child.id); + await control.result(child.id); assert.throws(() => control.status("missing"), /does not exist/u); assert.deepEqual(copied, [child.id, child.id], "only the observed card's own scrollback is read, and no list() snapshot of every card"); diff --git a/tests/launch-contributors.test.mjs b/tests/launch-contributors.test.mjs index df2491a1e..8a53e7ee8 100644 --- a/tests/launch-contributors.test.mjs +++ b/tests/launch-contributors.test.mjs @@ -310,11 +310,11 @@ test("secret env comes from the plugin's own secrets, reaches the child, and is calls[0].print(`env: PROVIDER_API_KEY=${SECRET} PLAIN=visible\n`); const control = new AgentControlService(manager); - const observed = control.observe(created.id).output; + const observed = (await control.observe(created.id)).output; assert.match(observed, /PROVIDER_API_KEY= PLAIN=visible/u); assert.doesNotMatch(observed, new RegExp(SECRET, "u")); calls[0].exit(1); - assert.doesNotMatch(control.result(created.id).output, new RegExp(SECRET, "u")); + assert.doesNotMatch((await control.result(created.id)).output, new RegExp(SECRET, "u")); assert.doesNotMatch(card(manager, created.id).failureDetails ?? "", new RegExp(SECRET, "u")); await manager.shutdown(); diff --git a/tests/orchestration-providers-wait.test.mjs b/tests/orchestration-providers-wait.test.mjs index bd7c6380a..2513b9878 100644 --- a/tests/orchestration-providers-wait.test.mjs +++ b/tests/orchestration-providers-wait.test.mjs @@ -331,3 +331,146 @@ test("wait_for_agent returns before the orchestrator's MCP client gives up, as a terminals.sessions.get("child").status = "idle"; assert.equal((await call(handler, "wait_for_agent", { sessionId: "child" })).message, undefined, "only a timeout says to call again"); }); + +/** A recorded OpenCode-style session: alternate screen, absolute cursor moves, colors, a spinner and in-place redraws. */ +function openCodeRedraws() { + const e = "\u001b"; + const at = (row, column) => `${e}[${row};${column}H`; + const parts = [ + `${e}[?1049h${e}[?25l${e}[?2004h${e}]0;opencode${e}\\${e}[2J${e}[H`, + `${at(1, 1)}${e}[48;2;24;24;37m${e}[38;2;205;214;244m┃ opencode build gpt-5.5${e}[K${e}[0m`, + `${at(3, 3)}${e}[1mYou${e}[22m`, + `${at(4, 3)}${e}[38;5;252mFix the failing Button test${e}[39m`, + `${at(6, 3)}${e}[38;5;245mThinking${e}[0m` + ]; + // The spinner turns in place many times while the model works. + for (let turn = 0; turn < 120; turn++) parts.push(`${at(6, 12)}${"⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"[turn % 10]}${at(40, 1)}${e}[7m working ${turn}s ${e}[27m${e}[K`); + parts.push( + `${at(6, 1)}${e}[2K${at(6, 3)}${e}[38;2;166;227;161mThe Button test passes now.${e}[0m`, + `${at(7, 3)}Used key sk-secret-value for the request.`, + `${at(8, 3)}${e}[38;5;111m│${e}[0m src/Button.tsx ${e}[32m+3${e}[0m ${e}[31m-1${e}[0m`, + `${at(40, 1)}${e}[2K${e}[7m ctrl+p commands ${e}[27m` + ); + return parts.join(""); +} + +test("wait_for_agent and get_agent_result return a TUI's screen as plain text, not its escape sequences", async () => { + const { terminals, handler } = setup(); + const child = terminals.sessions.get("child"); + setTimeout(() => { + child.buffer = openCodeRedraws(); + child.outputOffset = child.buffer.length; + child.status = "idle"; + }, 20); + const waited = await call(handler, "wait_for_agent", { sessionId: "child", timeoutSeconds: 5 }); + const result = await call(handler, "get_agent_result", { sessionId: "child" }); + for (const output of [waited.output, result.output]) { + assert.equal(/[\u0000-\u0008\u000b-\u001f\u007f]/u.test(output), false, "no control characters or escape sequences"); + assert.deepEqual(output.split("\n"), [ + "┃ opencode build gpt-5.5", + "", + " You", + " Fix the failing Button test", + "", + " The Button test passes now.", + " Used key [redacted] for the request.", + " │ src/Button.tsx +3 -1", + ...Array.from({ length: 31 }, () => ""), + " ctrl+p commands" + ]); + assert.ok(!output.includes("sk-secret") && !output.includes("Thinking") && !output.includes("working"), "masked; only what the screen shows now"); + } +}); + +test("the plain-text output stays bounded and masked for a long line-based transcript", async () => { + const { terminals, control } = setup(); + const child = terminals.sessions.get("child"); + child.buffer = Array.from({ length: 4_000 }, (_value, index) => `\u001b[32mline ${index}\u001b[0m with key sk-secret-value\r\n`).join(""); + child.outputOffset = child.buffer.length; + child.status = "idle"; + const result = await control.result("child"); + assert.ok(result.output.length <= 8_192); + assert.ok(result.output.endsWith("line 3999 with key [redacted]"), result.output.slice(-80)); + assert.ok(!result.output.includes("\u001b") && !result.output.includes("sk-secret")); +}); + +/** Invisible SGR resets that pad a stream to an exact length: any length from 6 up is a sum of 3s and 4s. */ +function sgrPadding(length) { + const e = "\u001b"; + let fours = 0; + while ((length - 4 * fours) % 3 !== 0) fours++; + return `${e}[0m`.repeat(fours) + `${e}[m`.repeat((length - 4 * fours) / 3); +} + +test("a scrollback window that starts inside an escape sequence leaves no fragment of it on the screen", async () => { + const { terminals, handler } = setup(); + const child = terminals.sessions.get("child"); + const e = "\u001b"; + const at = (row, column) => `${e}[${row};${column}H`; + const start = "18;9Hof specialists who had internalized the machine."; + const redraws = []; + for (let turn = 0; turn < 900; turn++) redraws.push(`${at(40, 1)}${e}[7m working ${turn}s ${e}[27m${e}[K`); + const end = `${at(3, 3)}The first response was the assembler.`; + const body = start + redraws.join("") + end; + // The last 65,536 characters (the window the screen is rendered from) begin right after the ESC [ of a cursor move. + child.buffer = `${"earlier output\r\n".repeat(50)}${e}[` + body + sgrPadding(65_536 - body.length); + child.outputOffset = child.buffer.length; + child.status = "idle"; + const waited = await call(handler, "wait_for_agent", { sessionId: "child", timeoutSeconds: 5 }); + const result = await call(handler, "get_agent_result", { sessionId: "child" }); + for (const output of [waited.output, result.output]) { + assert.ok(!output.includes("18;9H"), output.slice(0, 80)); + assert.ok(output.includes(" The first response was the assembler."), output); + } +}); + +test("exitLines are the exited TUI's screen as plain text, not its redraws joined together", async () => { + const { terminals, handler } = setup(); + const child = terminals.sessions.get("child"); + const e = "\u001b"; + const at = (row, column) => `${e}[${row};${column}H`; + // Drawn once at the start and never again: still on the screen when the CLI exits, more than 16 KiB later. + const early = `${at(3, 3)}${e}[2mThinking${e}[0m${at(8, 3)}${e}[38;5;111m▣ Build · glm-5.3-flash${e}[0m`; + const turns = 1_300; + const progress = []; + for (let turn = 0; turn < turns; turn++) progress.push(`${at(2, 3)}${e}[38;2;166;227;161m${"■".repeat(turn % 7)}${"⬝".repeat(7 - (turn % 7))}${e}[0m`); + // A TUI redraws only the cells that changed: here a line written once, then its typos fixed in place. + const body = early + progress.join("") + + `${at(4, 3)}As explicit memoy address, and if a single instructon was` + + `${at(4, 19)}ry address, and if a single instruction was` + + `${at(6, 3)}${e}[31mError: the model stopped answering.${e}[0m`; + assert.ok(body.length > 16_384 && body.length < 65_000, String(body.length)); + // The rendered window (the last 65,536 characters) begins with the `m` of a color sequence whose start was cut off. + child.buffer = `${"x".repeat(100)}${e}[38;2;1;2;3` + "m" + body + sgrPadding(65_536 - 1 - body.length); + child.outputOffset = child.buffer.length; + child.exitCode = 1; + child.status = "failed"; + const waited = await call(handler, "wait_for_agent", { sessionId: "child", timeoutSeconds: 5 }); + const observed = await call(handler, "observe_agent", { sessionId: "child" }); + const result = await call(handler, "get_agent_result", { sessionId: "child" }); + assert.equal(waited.reason, "failed"); + const last = (turns - 1) % 7; + assert.deepEqual(waited.exitLines.split("\n"), [ + ` ${"■".repeat(last)}${"⬝".repeat(7 - last)}`, + " Thinking", + " As explicit memory address, and if a single instruction was", + " Error: the model stopped answering.", + " ▣ Build · glm-5.3-flash" + ]); + assert.equal(observed.exitLines, waited.exitLines); + assert.equal(result.exitLines, waited.exitLines); +}); + +test("observe_agent returns the screen as plain text too, within its maxChars", async () => { + const { terminals, handler } = setup(); + const child = terminals.sessions.get("child"); + child.buffer = openCodeRedraws(); + child.outputOffset = child.buffer.length; + child.status = "working"; + const observed = await call(handler, "observe_agent", { sessionId: "child" }); + assert.equal(/[\u0000-\u0008\u000b-\u001f\u007f]/u.test(observed.output), false, "no ESC or other control bytes"); + assert.ok(observed.output.includes(" The Button test passes now.") && observed.output.includes("[redacted]")); + assert.ok(!observed.output.includes("sk-secret") && !observed.output.includes("working")); + const short = await call(handler, "observe_agent", { sessionId: "child", maxChars: 256 }); + assert.ok(short.output.length <= 256 && short.output.endsWith(" ctrl+p commands"), short.output); +}); diff --git a/tests/runtime-result-transport.test.mjs b/tests/runtime-result-transport.test.mjs index af2be39e5..010f56428 100644 --- a/tests/runtime-result-transport.test.mjs +++ b/tests/runtime-result-transport.test.mjs @@ -95,9 +95,9 @@ for (const provider of ["codex", "opencode"]) { // Turning status hooks off revokes the lease: this launch has no hooks any more, and the result says so. f.setStatusHooks(false); assert.equal(f.gateway.currentStatus(worker.id), null); - assert.equal(f.control.result(worker.id).answer?.text, "worker final answer", "an answer captured earlier stays"); + assert.equal((await f.control.result(worker.id)).answer?.text, "worker final answer", "an answer captured earlier stays"); await f.terminals.deliverInput(worker.id, "next task\r"); - const after = f.control.result(worker.id); + const after = await f.control.result(worker.id); assert.equal(after.answer, undefined); assert.equal(after.answerUnavailable?.reason, "status_hooks_off"); }); @@ -118,12 +118,12 @@ for (const provider of ["codex", "opencode"]) { // Turning them on applies to agents started or restarted afterwards. f.setStatusHooks(true); - assert.equal(f.control.result(worker.id).answerUnavailable?.reason, "status_hooks_off"); + assert.equal((await f.control.result(worker.id)).answerUnavailable?.reason, "status_hooks_off"); launch.process.emitExit(0); f.terminals.restart(worker.id); const restarted = f.calls.at(-1); assert.notEqual(restarted, launch); assert.ok(restarted.options.env[AGENT_RUNTIME_ENV.capabilityToken], "the restarted launch has its hooks"); - assert.equal(f.control.result(worker.id).answerUnavailable, undefined); + assert.equal((await f.control.result(worker.id)).answerUnavailable, undefined); }); } diff --git a/tests/secret-redaction.test.mjs b/tests/secret-redaction.test.mjs index f3b74d5c2..63ca2ea36 100644 --- a/tests/secret-redaction.test.mjs +++ b/tests/secret-redaction.test.mjs @@ -163,7 +163,7 @@ test("the vault hands every value it reads or writes to the registry; agent-read readBuffer: () => ({ buffer: `env OPENAI=${value}\n${secrets.github}\n` }), redactSecrets: (text) => manager.redactSecrets(text) }); - const observed = control.observe("s1").output; + const observed = (await control.observe("s1")).output; assert.equal(observed.includes(value) || observed.includes(secrets.github), false); assert.match(observed, /env OPENAI=/u); }); @@ -204,17 +204,17 @@ test("observe_agent and get_agent_result mask the whole buffer before cutting th const control = new AgentControlService(f.terminals); // The 300-character observation starts 12 characters before the secret ends. f.print(`${"a".repeat(1_000)}${PLAIN_SECRET}${"b".repeat(288)}`); - const observed = control.observe(f.card.id, 300).output; + const observed = (await control.observe(f.card.id, 300)).output; assert.ok(observed.length <= 300, "the bound is kept"); assert.deepEqual(fragments(observed), []); // get_agent_result's 8 192-character tail, cut inside the secret the same way. f.print(`${PLAIN_SECRET}${"c".repeat(8_192 - 10)}`); - const result = control.result(f.card.id).output; + const result = (await control.result(f.card.id)).output; assert.ok(result.length <= 8_192); assert.deepEqual(fragments(result), []); // Wrapped secrets are still masked whole. f.print(`\r\n${PLAIN_SECRET.slice(0, 15)}\r\n${PLAIN_SECRET.slice(15)}\r\n`); - assert.deepEqual(fragments(control.observe(f.card.id, 8_192).output), []); + assert.deepEqual(fragments((await control.observe(f.card.id, 8_192)).output), []); }); test("plugin screen text and failure details mask the whole buffer before cutting", async (t) => { @@ -318,8 +318,8 @@ test("observe_agent, get_agent_result and the plugin screen mask a bounded windo f.print(scrollback(250_000)); f.print(`${PLAIN_SECRET}${"g".repeat(200)}`); const control = new AgentControlService(f.terminals); - assert.deepEqual(fragments(control.observe(f.card.id).output), []); - assert.deepEqual(fragments(control.result(f.card.id).output), []); + assert.deepEqual(fragments((await control.observe(f.card.id)).output), []); + assert.deepEqual(fragments((await control.result(f.card.id)).output), []); const { PluginSessions } = await import("../src/main/services/PluginSessions.ts"); const screens = []; const sessions = new PluginSessions({ terminals: f.terminals, notify: (_p, _s, _m, event) => { if (event.screen !== undefined) screens.push(event.screen); return true; } }); @@ -330,7 +330,8 @@ test("observe_agent, get_agent_result and the plugin screen mask a bounded windo await new Promise((resolve) => setTimeout(resolve, 20)); assert.ok(screens.length > 0); assert.deepEqual(fragments(screens.join("\n")), []); - assert.ok(masked.length >= 3 && Math.max(...masked) < 40_000, `masked ${masked} characters per call`); + // get_agent_result renders its plain text from a 64 KiB masked window (plus the tail margin); never the whole scrollback. + assert.ok(masked.length >= 3 && Math.max(...masked) < 90_000, `masked ${masked} characters per call`); }); /** diff --git a/tests/subagent-signal-exit.test.mjs b/tests/subagent-signal-exit.test.mjs index 69229b143..c434e05c9 100644 --- a/tests/subagent-signal-exit.test.mjs +++ b/tests/subagent-signal-exit.test.mjs @@ -79,7 +79,7 @@ test("a subagent whose CLI is killed by SIGKILL is failed (128+9) with the signa assert.equal(waited.reason, "failed"); assert.equal(waited.status, "failed"); assert.equal(waited.exitCode, 137); - const result = s.control.result(child.id); + const result = await s.control.result(child.id); assert.equal(result.state, "failed"); assert.equal(result.exitCode, 137); // The saved session restores as failed, and HOME's failure summary shows the exit code with the signal line. @@ -113,6 +113,6 @@ test("a clean exit stays done", { skip }, async (t) => { assert.equal(ended.exitCode, 0); assert.equal(ended.failureDetails, null); assert.equal((await s.control.waitFor(child.id, { timeoutMs: 1_000 })).reason, "done"); - assert.equal(s.control.result(child.id).state, "done"); + assert.equal((await s.control.result(child.id)).state, "done"); assert.equal(persistedTerminalSession(ended).lastState, "exited"); });