import type { HarnessResumeRequest, ResumeSpec } from './resume'; export type HarnessName = 'auto' | 'opencode' | 'claude' | 'codex' | 'gemini' | 'antigravity' | 'copilot' | 'cursor' | 'goose' | 'openhands' | 'aider' | 'cline' | 'openrouter' | 'none'; /** * Harnesses that run the built-in headless LLM loop (`--self`, `runLlmSession`) * instead of spawning a local CLI binary. OpenRouter is an API gateway - there * is no adapter to spawn - so `harness = 'openrouter'` is the explicit, * discoverable alias for the self-mode execution path (vs `none`, which skips * execution entirely). */ export declare const SELF_MODE_HARNESSES: Set; /** True when this harness executes through the headless LLM loop (no CLI). */ export declare function isSelfModeHarness(name: string): boolean; export interface SpawnOpts { model?: string; temperature?: number; cwd?: string; timeoutMin?: number; title?: string; agentKey?: string; apiBaseUrl?: string; /** BYOK provider API key — wired to the harness-specific env var (e.g. GEMINI_API_KEY). */ providerKey?: string; /** Session mode for the MCP config header ('run' | 'build' | 'chat' | 'doc'). */ sessionMode?: string; /** * Run-stable OpenCode session id (`x-opencode-session` on Zen/Go). The * first-party opencode CLI sends its own header; this id is forwarded as * env (`X_OPENCODE_SESSION`) so every harness carries the same conversation * identity irrespective of execution method. */ opencodeSessionId?: string; /** * Harness session id - sent as X-TeamShare-Session-Id on MCP calls so * claims made during this session can be released in one call at exit. */ sessionId?: string; /** * QA lane (2026-10-25): a QA run **simulates a regular user**, so it gets no * shell at all. A run that lost its tools at the 63-minute mark used the shell * to inspect the operator's machine and read a live API key; the QA lane only * needs the browser + its TeamShare MCP tools. * * Enforced per harness (opencode `permission.bash = deny`, Claude allowlist) * and FAIL-CLOSED by `spawnHarness`: if the guard cannot be installed, the run * does not start rather than run unguarded. */ noShell?: boolean; /** Reasoning effort for harnesses that expose it (codex: low|medium|high|xhigh). */ effort?: string; /** Override the default workspace MCP config path (.agents/mcp_config.json). */ mcpConfigPath?: string; /** * Raw stdout line callback — fires with each unformatted line from the * harness process BEFORE formatHarnessEvent processes it. Used by * chat-reply/doc-reply to capture raw output for parseHarnessOutput * while reusing the same spawn logic as run/build. */ onRawLine?: (line: string) => void; /** * Resume a previous harness session instead of starting a new one. The * adapter's headlessArgs() translates this into the right argv (flag, * subcommand, or history restore). Omitted = fresh session. */ resume?: HarnessResumeRequest; /** * Machine-local session resume scope. When set, spawnHarness() loads/saves * the harness session id for (agentId, taskId, mode) so a later run of the * same task resumes. Omitted = always a fresh session. */ sessionStore?: { agentId: string; taskId: string; mode: string; }; /** * Project for a BRIDGE hygiene note (2026-11-18). * * When the turn watchdog warns that the model turn has gone silent, the bridge * posts a short note to the hub so the agent learns the kill deadline at its * next `get_instructions` checkpoint. The note is scoped to this project (or to * `sessionStore.taskId` when it is a real UUID, which wins). Omitted = no note * is sent; the run is unaffected either way. */ selfNoteProjectId?: string; /** Force a fresh session (ignore + clear any stored record). */ fresh?: boolean; /** * Context budget for this conversation, in tokens (2026-12). * * When the stored session's estimated context has reached it, the record is * cleared and a FRESH session starts, so a long chat/doc/board conversation * rotates instead of running into the model's window mid-answer. Omitted = * `DEFAULT_CHAT_CONTEXT_TOKENS` (400k). Only consulted when `sessionStore` is * set: a task run resumes on its own rules. */ contextLimitTokens?: number | null; /** * Fired when the context budget rotated the conversation (a NEW session was * started because the old one was full). Chat streams a short notice into the * channel; other modes just log. */ onSessionRotated?: (info: { reason: 'context-budget' | 'context-overflow'; estimatedTokens: number; limitTokens: number; previousSessionId?: string; }) => void; /** Branch the stored session instead of continuing in place (where supported). */ fork?: boolean; /** * Run in the harness's plan mode (Cline `-p`). Set by cmdPlan; all other * modes leave it unset (act/execute). Harnesses without a plan mode ignore it. */ plan?: boolean; /** * Background-shell wait policy (2026-11). * * A harness that backgrounds a long command (`npm run test:run`) and then * stops calling tools has NOT finished: the CLI client exits while the * command keeps running on the shared service. spawnHarness therefore waits * for the shell and RESUMES the session with its result, so the agent can * finish the checklist/summary/report it was waiting to write. * * `shouldStop` is the brake: the caller ties it to the task claim lease, so * the wait lasts exactly as long as this run may still hold the task. */ shellWait?: { /** Return true to stop waiting (claim lease lost, stop requested). */ shouldStop?: () => boolean; /** Hard ceiling in ms. 0 / undefined = no ceiling (shouldStop is the brake). */ maxWaitMs?: number; /** How many times a finished shell may resume the same session. */ maxContinuations?: number; }; /** * Retained for adapter compatibility. A non-zero opencode client exit is a * FAILURE under the strict 2026-10 policy; nothing recovers it. */ onRecovered?: (info: { harness: string; exitCode: number; sessionId?: string; }) => void; } export interface HarnessAdapter { /** Display name. */ name: string; /** CLI binary name (must be on PATH). */ binary: string; /** Include in 'auto' detection order. */ autoDetect: boolean; /** Priority (lower = detected first in auto mode). */ priority: number; /** * Build the CLI args for a non-interactive headless run. * When `excludePrompt` is true, return args WITHOUT the prompt element — * the caller handles prompt delivery (temp file path or native file flag). */ headlessArgs(prompt: string, opts: SpawnOpts, excludePrompt?: boolean): string[]; /** Extra env vars for this session. */ envForSession(opts: SpawnOpts): Record; /** Whether this harness supports MCP tool injection. */ supportsMcp: boolean; /** * Write a per-session MCP config override (returns file path + cleanup). * `opts` carries cwd for workspace-scoped configs (antigravity merges * `.agents/mcp_config.json` inside the working folder and restores it). * * `relayUrl`/`sessionToken` (2026-10-15) point the harness at the machine's * `/mcp-relay` instead of the API, so no API key is written to a file and the * daemon decides the identity. Only the opencode writer forwards them today: * opencode V2's shared service ignores this config and reads the GLOBAL one * (the identity hijack this fixes), while the other harnesses are handed * their config explicitly (`--mcp-config`, a workspace file, a TOML) and * honour it, so their direct-key path stays correct. */ writeMcpConfig?(agentKey: string, apiBaseUrl: string, sessionMode?: string, opts?: SpawnOpts, relayUrl?: string, sessionToken?: string): { file: string; cleanup: () => void; } | null; /** * Resume capability metadata (session addressing, id capture, failure * signatures). The argv itself is built by headlessArgs() from opts.resume. */ resume?: ResumeSpec; /** Whether the harness produces structured JSON output. */ structuredOutput: boolean; /** * The harness gates its stdout on isatty() (e.g. agy prints nothing when * piped) — spawn through a pseudo-terminal when node-pty is available. */ needsTty?: boolean; /** * Whether the harness can receive the full prompt from a temp file. * When true and the prompt exceeds argv limits, spawnHarness() writes * the prompt to a temp file and passes the path instead. */ supportsPromptFile?: boolean; /** * Native file flag for prompt delivery (e.g. '-i' for goose, '-f' for * aider/openhands). When set, spawnHarness() uses this flag directly * instead of embedding the path in the prompt text. */ promptFileFlag?: string; /** * Vision-turn image delivery for the browser auto-answer harness backend * (an OPT-IN layer on top of the direct vision loop — see * `lib/browser/browse-harness.ts`). `'path-mention'` means the CLI reads * local image files referenced by path inside the prompt text. Adapters * without this field fail fast with HARNESS_NO_VISION_INPUT instead of * running a turn the model can never see. */ visionImage?: 'path-mention'; } /** * Project-scoped opencode config in the RUN's working directory (2026-10-15). * * WHY: OpenCode V2's shared service owns the MCP clients and reads the config * for the SESSION'S DIRECTORY - a project-level `opencode.json` wins over the * global one (verified on a live machine), while the per-process * `OPENCODE_CONFIG` override is ignored for MCP. That is where a run's own * identity can live: * - the GLOBAL entry stays the HUMAN's (direct API + their personal key), so * interactive sessions act as the person AND work with the daemon stopped; * - a run's directory config points at the local relay with the run's * per-session token, so the run acts as its OWN agent - no API key written * anywhere (the daemon injects it from memory). * * MERGE + RESTORE, like `workspaceMcpWriter` (cline/cursor/copilot): an * existing `.opencode/opencode.json` survives untouched (and a file we cannot * parse is left alone entirely), and a file we created is deleted again. * Cleanup runs when the harness exits - before the git pipeline - so a run * tree never gets committed with it. * * EXCEPTION (2026-11): `keepWritten` leaves the run's own entry in place. A * KEPT run scope belongs to one resumable conversation, and restoring the * previous entry there means restoring a POISONED identity - the resumed * session then comes up with no `teamshare` MCP server and the agent cannot * reply at all. */ export declare function writeOpencodeWorkspaceMcp(cwd: string, entry: { url: string; headers: Record; }, options?: { noShell?: boolean; /** * Leave the written entry in place instead of restoring what was there * before the run (2026-11). * * For a KEPT run scope (one chat/doc/board/plan conversation, resumed in * the same directory every time) restoring is actively harmful: it puts the * PREVIOUS run's identity back, and when that previous entry was a revoked * one the resumed opencode session comes up with no `teamshare` server at * all - the agent has no `whoami`, no `create_document`, no * `post_chat_message`, and a full reply is lost. Leaving this run's entry * means the next run resumes with a working identity, and it is overwritten * again on that run's first spawn. */ keepWritten?: boolean; }): { file: string; cleanup: () => void; } | null; /** Installed Claude Code version (e.g. "2.1.276"), or null when unknown. */ export declare function claudeVersion(): string | null; /** True when the installed Claude Code is at least major.minor.patch. */ export declare function claudeAtLeast(major: number, minor: number, patch: number): boolean; /** `--strict-mcp-config` (exclusive MCP + no project approval) needs v2.1.246+. */ export declare function claudeStrictMcpSupported(): boolean; export declare const CLAUDE_ALLOWED_TOOLS: string; /** The allowlist for one run; `noShell` drops Bash and subagents. */ export declare function claudeAllowedTools(noShell?: boolean): string; /** Get a specific adapter by name. Throws if unknown. */ export declare function getAdapter(name: string): HarnessAdapter; /** All registered adapter names (excludes 'auto' and 'none'). */ export declare const HARNESS_NAMES: string[]; /** Auto-detect the first available harness on PATH. Returns 'none' if nothing found. */ export declare function detectHarness(): string; /** Resolve 'auto' to a concrete harness, or pass through an explicit name. */ export declare function resolveHarness(name: string): string; /** Check if a harness binary exists on PATH. */ export declare function harnessAvailable(name: string): boolean;