/** * Build the CLI argv that interrupts `sessionId`, or null for an invalid id. * Exported as a pure function so the contract can be pinned by a unit test. */ export declare function buildOpencodeInterruptArgs(sessionId: string): string[] | null; /** * Interrupt an OpenCode V2 session on the shared service. * * Best-effort by contract: a missing CLI, a stopped service, a timeout or an * idle session all answer `false` and must NEVER throw - a stop path must not * fail because the harness could not be reached. The caller logs the result; * the relay-token revocation is the independent backstop. */ export declare function interruptOpencodeSession(sessionId: string, timeoutMs?: number): Promise; export interface OpencodeShellInfo { id: string; /** 'running' | 'exited' | 'timeout' | 'killed' (the service may add more). */ status: string; command?: string; cwd?: string; pid?: number; exit?: number | null; } /** * Shell ids carried by the harness stream. * * TWO SHAPES, and missing the second one is why a running shell never fed the * activity clock (2026-11): the tool result also carries a HUMAN sentence, * `Command moved to the background (shell ID: sh_…)`, which is not a JSON key. * The activity poller therefore never recognised its own shell, reported "no * stdout for 5 min - last activity: stdout" while vitest was running, and the * run looked idle. */ export declare function extractShellIds(line: string): string[]; export declare function buildShellListArgs(cwd: string): string[] | null; export declare function buildShellGetArgs(id: string, cwd: string): string[] | null; export declare function buildShellRemoveArgs(id: string, cwd: string): string[] | null; /** List RUNNING shells for a location (exited shells are not included). */ export declare function listOpencodeShells(cwd: string, timeoutMs?: number): Promise; /** Read one shell's status/exit; null when it cannot be read. */ export declare function getOpencodeShell(id: string, cwd: string, timeoutMs?: number): Promise; /** Terminate and remove one shell (best-effort). */ export declare function removeOpencodeShell(id: string, cwd: string, timeoutMs?: number): Promise; /** * Pure: why a settled shell is a FAILURE, or null when it completed cleanly. * * A shell that is STILL RUNNING is not passed here (waiting is the caller's * job now) - `stillRunning` only describes the give-up case. `timeout`, * `killed`, an unreadable status and any non-zero exit are failures: success is * never assumed from work nobody verified. */ export declare function shellFailureReason(info: OpencodeShellInfo | null, stillRunning?: boolean): string | null; export interface ShellSettleResult { ok: boolean; /** One human-readable line per failed/unresolved shell. */ failures: string[]; /** Shells that finished CLEANLY (exit 0) while we waited. */ finished: OpencodeShellInfo[]; /** Shells still running when the wait ended (abandoned, never a success). */ pending: OpencodeShellInfo[]; /** Shells terminated/removed at session end. */ removed: number; /** Pids that survived the cleanup kill (0 = everything is really gone). */ survived: number; /** How long we waited for the shells, ms. */ waitedMs: number; /** True when shouldStop() ended the wait (claim lost / stop requested). */ interrupted: boolean; detail: string; } /** True when the OS still has this pid (EPERM = alive but not ours). */ export declare function isPidAlive(pid: number): boolean; /** * WAIT for the session's background shells, then clear them. * * THE 2026-11 RULE (this replaced "a running shell is a failure"): * an agent that backgrounds `npm run test:run` and then stops calling tools * has NOT finished - the CLI client exits when the assistant stops calling * tools, while the suite runs on the shared service. A 60 s deadline failed a * run whose tests were still executing, discarded a healthy session and left * the process tree (and its workspace lock) alive for hours. * * So a shell that is RUNNING is work in progress, not a verdict: * - wait while it is running (no ceiling by default - `shouldStop` is the * brake, and the caller ties that to the task claim lease); * - a clean exit 0 is a finished shell (the caller may continue the session); * - a non-zero exit, timeout, kill, unreadable status, or a shell we gave up * on is reported as a FAILURE **to the caller** - but it is the AGENT's * command: the caller logs it and NEVER fails the run over it (2026-11); * only `survived` (a process we could not stop) and `interrupted` are * actionable; * - every shell is DELETEd afterwards AND its pid verified dead (with a * selective tree kill as the fallback), so none can keep holding a * workspace lock or keep running after the client is gone. */ export declare function settleOpencodeShells(opts: { cwd: string; ids: string[]; /** Ceiling for the wait. 0 / undefined = no ceiling (wait while alive). */ waitMs?: number; pollMs?: number; /** Add every RUNNING shell in the location (safe for a private mirror). */ includeRunning?: boolean; /** Return true to abandon the wait (claim lost, stop requested). */ shouldStop?: () => boolean; /** Progress line (called at most once a minute while waiting). */ onProgress?: (waitedMs: number, running: OpencodeShellInfo[]) => void; log?: (line: string, level?: 'stdout' | 'stderr') => void; }): Promise; export interface SubagentSessionInfo { id: string; parentID?: string; title?: string; outcome?: string; } export declare function buildSubagentListArgs(parentId: string, cwd: string): string[] | null; export declare function buildSessionMessagesArgs(sessionId: string, cwd: string, limit?: number): string[] | null; /** Child sessions of a run's main session (subagents). Best-effort. */ export declare function listSubagentSessions(parentId: string, cwd: string, timeoutMs?: number): Promise; /** Latest assistant messages of a session, newest page reversed to oldest. */ export declare function listSessionMessages(sessionId: string, cwd: string, limit?: number, timeoutMs?: number): Promise>>; /** Human-readable line for a subagent assistant message (text or tool). */ export declare function formatSubagentMessage(message: Record): string; /** * Every DESCENDANT of a run's main session, breadth-first (2026-10-27). * * `listSubagentSessions` is one level deep, which left "processes that spin up * others" completely invisible: a subagent that spawned its own subagent was * never relayed to the console, never counted as run activity, and never * interrupted when the run ended - it could keep driving the debug browser * after "finished". Depth and session count are BOUNDED so a runaway tree * cannot turn the poll into an unbounded fan-out. */ export interface SubagentTreeEntry extends SubagentSessionInfo { /** 1 = a direct child, 2 = a grandchild, ... */ depth: number; } export declare function listSubagentTree(parentId: string, cwd: string, opts?: { maxDepth?: number; maxSessions?: number; }): Promise; /** * Interrupt every child session of `parentId` (and any already-known child * ids). Returns the number of children found. Best-effort: a child that * cannot be interrupted is logged, never thrown. * * 2026-10-27: walks the WHOLE TREE (`listSubagentTree`), not just direct * children - a grandchild kept running after its parent was interrupted and * outlived the run. */ export declare function interruptSubagentSessions(parentId: string, cwd: string, knownIds?: string[]): Promise;