toolroll 0.5.0

package/dist/exec.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Running external commands.
+ *
+ * Two rules define this module. Arguments are passed as an array and never
+ * through a shell, so a directory named `; rm -rf ~` is a string and not a
+ * command. And nothing here rejects: a failed command is a value. Discovery
+ * walks repos it has never seen, and one broken repo must not end the scan.
+ */
+import { type ProcessTreeObserver } from "./process-tree.js";
+import { type ContainmentBackendId } from "./containment.js";
+import type { Store } from "./store.js";
+export type ExecResult = {
+    /** Process exit code, or one of the synthetic codes below. */
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Killed for exceeding its timeout. */
+    timedOut: boolean;
+    /** Binary is not on PATH — distinct from "ran and failed", and worth saying so. */
+    notFound: boolean;
+    /**
+     * The OS containment this spawn had (OS containment plan). Absent under
+     * observed containment. `refused` = required containment could not be
+     * established and the target NEVER ran. Otherwise the backend, the exact
+     * OS object, and whether the OS proved it empty before this result was
+     * returned — a transport exit alone never proves that.
+     */
+    containment?: ContainmentOutcome;
+};
+export type ContainmentOutcome = {
+    refused: string;
+} | {
+    backend: ContainmentBackendId;
+    id: string;
+    empty: boolean;
+};
+/** Shell convention for "could not be executed": the refusal before any target ran. */
+export declare const CONTAINMENT_REFUSED_CODE = 126;
+export type RunOptions = ProcessTreeObserver & {
+    cwd?: string;
+    /** The agent fence (agent-fence.ts): on macOS the spawned process tree runs
+     * inside a sandbox that denies these paths. Applied here, at the one spawn
+     * road, so an injected test runner still sees the provider's own argv. */
+    fence?: readonly string[];
+    /** UTF-8 input for JSONL or buffered process-group transports; closed after delivery. */
+    stdin?: string;
+    /**
+     * Absolute wall-clock ceiling. Keep this for bounded commands and repair
+     * turns. Long-running provider sessions use idleTimeoutMs instead: useful
+     * work should not be killed merely because it has been running a while.
+     */
+    timeoutMs?: number;
+    /**
+     * No-progress watchdog for streaming children. It is re-armed whenever
+     * stdout or stderr produces bytes. When this is supplied without
+     * timeoutMs there is deliberately no absolute wall-clock ceiling.
+     */
+    idleTimeoutMs?: number;
+    maxBuffer?: number;
+    /**
+     * Extra environment, merged over the process's own. A capability probe is a
+     * question about an environment, and a test has to be able to construct the
+     * environment the question is about.
+     */
+    env?: Record<string, string>;
+    /**
+     * Names removed from the child's environment after the merge. This exists
+     * for exactly one class of variable: a secret the parent holds that the
+     * child must never see — the Telegram bot token in an agent's process
+     * would let the agent read and answer the operator's own decisions.
+     */
+    omitEnv?: readonly string[];
+    /**
+     * When set, the child's environment is EXACTLY these names, taken from
+     * the parent where present, plus whatever `env` merges on top (audit
+     * IV-5): the approved worktree setup sees an allowlist, never a clone
+     * of the operator's shell with two names scrubbed.
+     */
+    envAllowlist?: readonly string[];
+    /**
+     * Run the child in its own process group and register it as a live
+     * provider (M6.12). Set by the invocation gateway and nowhere else: an
+     * agent harness spawns shells and tools of its own, and stopping "the
+     * provider" must mean the whole tree — a kill that orphans the
+     * grandchildren stops nothing. Timeout kills become group kills too.
+     */
+    processGroup?: boolean;
+    /**
+     * Who OWNS this child (v52, safe task stop): an opaque tag — the
+     * invocation gateway and the builder's check/setup legs pass
+     * `run:<id>` — under which the live child is registered, so an
+     * operator's stop on one exact attempt can end THAT attempt's process
+     * tree through the handle this process holds, and nothing else's. A
+     * kill by tag reaches only children this process spawned and still
+     * tracks: never a pid read back from durable state.
+     */
+    owner?: string;
+    /** Rechecked at each actual spawn, including transient spawn retries. */
+    beforeSpawn?: () => boolean;
+    /**
+     * Live stdout for a process-group run, chunk by chunk as it arrives (the
+     * full buffer is still returned). A listener error never affects the run.
+     */
+    onStdout?: (chunk: string) => void;
+    /** Live stderr for a process-group run, with the same observational rules. */
+    onStderr?: (chunk: string) => void;
+    /**
+     * Called the moment the stream announces its session (codex:
+     * thread.started), so a crash mid-turn cannot lose the id (M6.9 —
+     * currently only the streaming transport can deliver this early).
+     */
+    onSessionId?: (id: string) => void;
+    /** Fires once the child exists, with its pid (the process-group id when
+     * processGroup is set) — the slot ledger records it (v14 finding 26). */
+    onSpawn?: (pid: number) => void;
+    /** Fires before any target spawn, so a crash cannot lose its OS object. */
+    onContainer?: (info: {
+        backend: ContainmentBackendId;
+        id: string;
+        identity?: string;
+    }) => void;
+    /** Fires once the OS proved this spawn's object empty (every member
+     * gone, including detached helpers). Never fires on a transport exit
+     * alone; a spawn whose object could not be proven empty reports
+     * onUnknown instead and its custody stays unproven. */
+    onContainerEmpty?: () => void;
+    /**
+     * Every parsed stream event, as it arrives (claude's streaming transport
+     * only). Purely observational: exceptions are caught and counted, and
+     * nothing about the run — retention, timeout, exit — changes because a
+     * listener misbehaved. The live window renders these; nothing else may.
+     */
+    onStreamEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * Fires ONCE, the moment the stream proves the prompt reached the agent
+     * (arc 1 finding 11): the first top-level assistant event, or a
+     * successful primary result when no assistant event preceded it. Error
+     * results never fire it — a startup death is not a delivery. Latched
+     * before invocation, so a throwing listener cannot make it fire twice.
+     */
+    onReceipt?: () => void;
+};
+/** Thrown BEFORE any spawn when required containment cannot be had. */
+export declare class ContainmentRefusal extends Error {
+    readonly name = "ContainmentRefusal";
+}
+/** Run IDs are local to a database. Connections to the same file share
+ * custody; separate files and separate in-memory databases never do. */
+export declare function runOwnerTag(store: Store, runId: number): string;
+/** How many live children this process still tracks under an owner tag. */
+export declare function ownedProcessCount(owner: string): number;
+/**
+ * The exact-attempt stop (v52): SIGKILL the process group of every live
+ * child registered under the owner tag — and only those. Returns how many
+ * were signalled. Idempotent: a child already gone was dropped at close,
+ * and a tag nobody registered kills nothing. This is the ONLY kill road a
+ * task action may take; the global sweep below is the watch's shutdown.
+ */
+export declare function terminateOwnedProcesses(owner: string): number;
+/**
+ * The hard stop (M6.12): SIGKILL every live provider's process group.
+ * Called by the watch when its stop grace expires — never on the first
+ * signal, which stays graceful. Late output cannot commit or publish:
+ * the killed process exits nonzero, the build finalizes as the failure
+ * it is, and every commit sits behind fences the corpse cannot pass.
+ */
+export declare function terminateLiveProviders(): number;
+/** Conventions from the shell and from coreutils `timeout(1)`. */
+export declare const NOT_FOUND_CODE = 127;
+export declare const TIMEOUT_CODE = 124;
+export declare const OVERFLOW_CODE = 125;
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare const DEFAULT_MAX_BUFFER: number;
+export declare const SPAWN_RETRY_DELAYS_MS: readonly number[];
+export declare function isTransientSpawnFailure(error: {
+    code?: number | string;
+} | null | undefined): boolean;
+/** One attempt's answer, with whether the process never started at all. */
+export type SpawnAttempt = {
+    result: ExecResult;
+    transient: boolean;
+};
+/**
+ * Retry `attempt` while it reports a transient spawn failure, sleeping the
+ * given delays between tries; the last answer stands when they run out.
+ * A non-transient answer — success, a real exit code, not found, timeout —
+ * is returned at once: only the never-started case is retried.
+ */
+export declare function retryTransientSpawn(attempt: () => Promise<SpawnAttempt>, delays?: readonly number[], sleep?: (ms: number) => Promise<void>): Promise<ExecResult>;
+export declare function run(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+/**
+ * Provider replies are nested inside their JSONL envelope. A 64 KiB reply
+ * therefore needs appreciably more than 64 KiB on the wire once quotes,
+ * backslashes, and control characters are escaped. 512 KiB carries that
+ * worst useful case while remaining a hard, per-event memory boundary.
+ */
+export declare const JSONL_EVENT_HARD_CAP: number;
+export declare function runStreamJsonl(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+/**
+ * The streaming transport for gemini's stream-json dialect (Phase 3 D1/A7).
+ *
+ * Retention: a bounded `init` identity witness (the first init signal, first
+ * usable session id, and first conflicting id), the FIRST
+ * `severity:"error"` error event (diagnostics),
+ * the LAST `result` event (tokens + structural status), and the assistant's
+ * text — which gemini emits only as many `message` delta lines — ASSEMBLED
+ * into one line of a dedicated internal schema the real CLI cannot emit:
+ *
+ *   {"type":"synthetic_message","content":"...","truncated":true?}
+ *
+ * Assembly rules (round-3 f9): only `role:"assistant"` events with
+ * `delta === true` concatenate; a non-delta assistant message REPLACES the
+ * buffer (full-message semantics); non-string content is dropped; the cap
+ * is enforced on the SERIALIZED UTF-8 BYTES of the complete synthetic line
+ * (marker included), so it can never violate the runner's own line
+ * discipline. Everything else — user echoes, tool_use, tool_result,
+ * warnings — is dropped. Timeout, process-group, kill, and spawn
+ * semantics match `runStreamJsonl`.
+ */
+export declare function runGeminiStreamJsonl(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+export declare function runClaudeStreamJsonl(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+/**
+ * Where the supervisor script lives: a plain-.mjs sibling of this module in
+ * BOTH layouts (src/ under tsx, dist/ after build — postbuild copies it).
+ */
+export declare function supervisorPath(): string;
+/**
+ * Darwin's sun_path is 104 bytes including the terminator; Linux allows a
+ * hair more. Refusing at spawn beats failing inside bind() with a raw
+ * ENAMETOOLONG after custody was already recorded.
+ */
+export declare const HELD_SOCKET_PATH_LIMIT = 103;
+export declare function heldSocketPathProblem(path: string): string | null;
+export type HeldSessionEvents = {
+    /** The nth system/init observed (1-based) — acceptance of the nth written turn. */
+    onTurnInit?: (seq: number) => void;
+    /** The nth primary-origin result (1-based) — settlement material for the nth turn. */
+    onTurnResult?: (seq: number, event: Record<string, unknown>) => void;
+    /** Every parsed stream event, arc-1 isolation rules unchanged. */
+    onStreamEvent?: (event: Record<string, unknown>) => void;
+    onSessionId?: (id: string) => void;
+    /** The supervisor exited: the hold is over, however it ended. */
+    onExit?: (info: {
+        code: number | null;
+    }) => void;
+};
+export type HeldSessionHandle = {
+    supervisorPid: number | null;
+    agentPgid: number | null;
+    /** One turn as a stream-json line. False = the pipe is gone; nothing was written. */
+    writeTurn(json: string): boolean;
+    /** The EOF road: the supervisor fences (EOF → grace → group kill) on its own. */
+    endInput(): void;
+    /** SIGTERM the supervisor — the same fence, for expiry/revocation/lapse. */
+    terminate(): void;
+    /** Last resort only: SIGKILL the supervisor itself (can orphan the agent). */
+    killHard(): void;
+    exited: Promise<{
+        code: number | null;
+    }>;
+};
+export type HeldSessionStart = {
+    ok: true;
+    handle: HeldSessionHandle;
+} | {
+    ok: false;
+    reason: "socket-path" | "spawn-failed" | "ready-timeout";
+    message: string;
+};
+/**
+ * Hold one claude process open across stream-json turns, under a
+ * supervisor whose parenthood makes the eventual kill provable. Returns
+ * once the supervisor's control frame settles the spawn either way.
+ *
+ * No timers live here: the per-turn wall deadline, liveness lapse, and
+ * absolute expiry are the coordinator's exact timers (v2 S1d) — this
+ * transport only moves bytes and counts the protocol's own marks.
+ */
+export declare function startClaudeHeldSession(file: string, args: readonly string[], options: RunOptions & {
+    socketPath: string;
+    cookie: string;
+    graceMs?: number;
+    events?: HeldSessionEvents;
+    readyTimeoutMs?: number;
+}): Promise<HeldSessionStart>;