@evomap/evolver-core 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/exec/runnerRegistry.d.ts

@@ -1,7 +1,11 @@
 export declare const DEFAULT_TIMEOUT_MS = 600000;
+/** Per-stream stdout/stderr capture ceiling. A child can emit indefinitely without growing the parent heap. */
+export declare const DEFAULT_MAX_CAPTURE_BYTES = 1048576;
 export interface AgentRunContext {
     cwd: string;
     timeoutMs?: number;
+    /** Cooperative cancellation. The runner kills the whole spawned process tree when aborted. */
+    signal?: AbortSignal;
     /** Environment for the spawned agent. The bridge passes a scrubbed env here (see scrubAgentEnv); undefined → inherit. */
     env?: NodeJS.ProcessEnv;
 }
@@ -9,6 +13,8 @@ export interface AgentRunResult {
     ok: boolean;
     output: string;
     error?: string;
+    failureKind?: 'spawn_failed' | 'timeout' | 'cancelled' | 'permission_denied' | 'non_zero_exit' | 'invalid_output' | 'runtime_error';
+    exitCode?: number | null;
 }
 /** Run a coding agent against a working directory with the given instruction. */
 export type AgentRunner = (prompt: string, ctx: AgentRunContext) => Promise<AgentRunResult>;
@@ -20,40 +26,99 @@ export declare class UnboundedSkipPermissionsError extends Error {
 export declare class UnsupportedCursorSkipPermissionsError extends Error {
     constructor();
 }
-/** Thrown when Cursor's built-in runner is requested on Windows before its launcher path is run-verified. */
+/** Thrown when Gemini permission options cannot be mapped to a verified bounded CLI contract. */
+export declare class UnsupportedGeminiPermissionOptionsError extends Error {
+    constructor();
+}
+/** Thrown when Cursor's Windows installation cannot be reduced to a shell-free node.exe + index.js launch. */
 export declare class UnsupportedCursorWindowsRunnerError extends Error {
     constructor();
 }
-export declare function assertCursorRunnerPlatformSupported(platform?: NodeJS.Platform): void;
+export declare function assertCursorRunnerPlatformSupported(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): void;
 /**
  * Make a bare command name spawnable shell-free on Windows. `spawn(shell:false)` cannot execute an npm CLI
  * shim (a `.cmd`/`.bat`), and routing through a shell would expose the prompt arg to cmd.exe quoting
  * (injection). npm shims are node wrappers, so we resolve the bare name on PATH and, when it's a node shim,
- * run `node <entry.js>` directly (shell-free, args passed safely). A native `.exe` (claude) resolves to itself.
- * No-op on POSIX and for any command that is already a path or has an extension. Surfaced by codex on Windows
- * (codex is `codex.cmd`, while claude is `claude.exe`), #66.
+ * run `node <entry.js>` directly. Cursor's installer uses a PowerShell shim around a bundled
+ * `versions/<version>/node.exe + index.js`; that known layout is resolved directly too, without invoking
+ * cmd.exe or PowerShell. A native `.exe` (claude) resolves to itself. No-op on POSIX and for any command that
+ * is already a path or has an extension. Surfaced by codex/cursor-agent on Windows (#66).
  */
-export declare function resolveSpawnCommand(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv): {
+export declare function resolveSpawnCommand(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): {
     cmd: string;
     args: string[];
 };
-/**
- * Promise wrapper over spawn (shell:false). Optionally writes `input` to stdin; resolves with stdout/exit.
- * On timeout the WHOLE process group is killed, not just the direct child (finding #39.5): an agent spawns
- * tool subprocesses (grandchildren) that would otherwise orphan and leak. On POSIX we spawn detached (the
- * child becomes its own group leader) and SIGKILL the group via the negative pid; Windows falls back to a
- * direct kill (different process-group semantics).
- */
-export declare function spawnCapture(cmd: string, args: readonly string[], opts: {
+export interface WindowsTreeKillCommand {
+    command: 'taskkill.exe';
+    args: ['/PID', string, '/T', '/F'];
+}
+export interface WindowsTreeKillChild {
+    once(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'close', listener: (code: number | null) => void): this;
+    kill?(signal?: NodeJS.Signals | number): boolean;
+}
+export type WindowsTreeKillSpawn = (command: string, args: readonly string[], options: {
+    shell: false;
+    windowsHide: true;
+    stdio: 'ignore';
+}) => WindowsTreeKillChild;
+type WindowsProcessTreeKiller = (pid: number) => Promise<boolean>;
+/** Build the shell-free taskkill invocation used for Windows process-tree termination. */
+export declare function windowsTreeKillCommand(pid: number): WindowsTreeKillCommand;
+/** Run taskkill and report whether Windows accepted the process-tree termination request. */
+export declare function killWindowsProcessTree(pid: number, spawnCommand?: WindowsTreeKillSpawn, timeoutMs?: number): Promise<boolean>;
+export interface SpawnCaptureOptions {
     cwd: string;
     timeoutMs: number;
     input?: string;
     env?: NodeJS.ProcessEnv;
-}): Promise<{
+    signal?: AbortSignal;
+    /** Cleanup subprocesses can shield themselves from repeated SIGINT/SIGTERM instead of cancelling. */
+    processSignalMode?: 'cancel' | 'ignore';
+    /** Maximum retained bytes for each of stdout and stderr. The original byte count is still reported. */
+    maxOutputBytes?: number;
+    /** Stream stdout directly to a file when the complete artifact must outlive the subprocess. */
+    stdoutFile?: string;
+    /** Ownership hook fired only after an exclusive redirected stdout artifact is opened successfully. */
+    onStdoutFileOpened?: (path: string) => void;
+    /** Test seam for redirected stdout finalization; production callers should use the filesystem defaults. */
+    stdoutFileOps?: {
+        size(fd: number): number;
+        close(fd: number): void;
+    };
+    resolvePlatform?: NodeJS.Platform;
+    /** Test seam for Windows process behavior; production callers should use the default. */
+    processPlatform?: NodeJS.Platform;
+    /** Test seam for the shell-free Windows taskkill invocation. */
+    windowsProcessTreeKiller?: WindowsProcessTreeKiller;
+}
+export interface SpawnCaptureResult {
     code: number | null;
     stdout: string;
     stderr: string;
-}>;
+    termination: 'exit' | 'timeout' | 'cancelled';
+    /** Present on real spawn results; optional so injected legacy test seams remain source-compatible. */
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    stdoutRedirected?: boolean;
+}
+/** A redirected stdout artifact could not be finalized; the subprocess outcome remains available for classification. */
+export declare class SpawnCaptureFinalizeError extends Error {
+    readonly result: SpawnCaptureResult;
+    constructor(result: SpawnCaptureResult, cause?: unknown);
+}
+/**
+ * Promise wrapper over spawn (shell:false). Optionally writes `input` to stdin; resolves with stdout/exit.
+ * On timeout the WHOLE process group is killed, not just the direct child (finding #39.5): an agent spawns
+ * tool subprocesses (grandchildren) that would otherwise orphan and leak. On POSIX we spawn detached (the
+ * child becomes its own group leader) and SIGKILL the group via the negative pid. Windows runs
+ * `taskkill.exe /PID <pid> /T /F` without a shell and waits for that command before resolving.
+ */
+export declare function spawnCapture(cmd: string, args: readonly string[], opts: SpawnCaptureOptions): Promise<SpawnCaptureResult>;
+/** Map the shared process result into the failure taxonomy used by plain-text runners. */
+export declare function classifyBasicRunnerResult(runner: 'claude' | 'codex' | 'cursor', result: SpawnCaptureResult, timeoutMs: number): AgentRunResult;
 /** Options for a built-in headless runner (claude / codex share the shape and the skip⇒bounded invariant). */
 export interface AgentRunnerOptions {
     /** Bypass permission prompts so the agent can edit autonomously (required for unattended use). Default off.
@@ -95,6 +160,12 @@ export declare const claudeHeadlessRunner: AgentRunner;
 export declare function codexRunnerArgs(opts?: AgentRunnerOptions): string[];
 /** Headless `codex exec` runner. Working root pinned with `--cd`; prompt is the trailing positional arg (shell:false). */
 export declare function makeCodexHeadlessRunner(opts?: AgentRunnerOptions): AgentRunner;
+/** Interpret one bounded Gemini subprocess result. Structured output and diagnostics require complete capture. */
+export declare function classifyGeminiRunnerResult(result: SpawnCaptureResult, timeoutMs: number): AgentRunResult;
+/** Build verified Gemini CLI argv. The prompt is appended separately as one argv element with shell:false. */
+export declare function geminiRunnerArgs(opts?: AgentRunnerOptions): string[];
+/** Headless Gemini runner with structured failure classification; stdout text alone never proves execution success. */
+export declare function makeGeminiHeadlessRunner(opts?: AgentRunnerOptions): AgentRunner;
 /**
  * Build the `cursor-agent` argv (pure). Ground-truth from `cursor-agent --help` (#66): base `-p --output-format
  * text` (headless, write+shell access). `--model` is a real flag. skipPermissions is rejected until Cursor has a
@@ -108,7 +179,7 @@ export declare function cursorRunnerArgs(opts?: AgentRunnerOptions): string[];
  */
 export declare function makeCursorHeadlessRunner(opts?: AgentRunnerOptions, platform?: NodeJS.Platform): AgentRunner;
 /** A built-in coding-agent harness (#66). cursor is a SCAFFOLD — its runner is unverified (see cursorRunnerArgs). */
-export type RunnerName = 'claude' | 'codex' | 'cursor';
+export type RunnerName = 'claude' | 'codex' | 'cursor' | 'gemini';
 /** A harness runner: how to launch it + which env auth prefixes it (and ONLY it) may keep (#66). */
 export interface AgentRunnerSpec {
     name: RunnerName;
@@ -120,4 +191,5 @@ export interface AgentRunnerSpec {
     };
 }
 /** Resolve a runner spec by name (default 'claude' — byte-identical to the pre-registry behavior). */
-export declare function getRunnerSpec(name?: RunnerName): AgentRunnerSpec;
+export declare function getRunnerSpec(name?: RunnerName): AgentRunnerSpec;
+export {};