genaicode 2.1.0 → 2.4.0

package/dist/agents/hosted.js

@@ -0,0 +1,129 @@
+import { RunRecorder } from './runtime.js';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+/** Adapt a `HostedAgentProvider` to `CodingAgent`, so hosted and local agents share one API. */
+export function hostedAgent(provider, options = {}) {
+    return {
+        name: provider.name,
+        command: provider.name,
+        capabilities: { ...provider.capabilities, steer: !!provider.send },
+        run: (task) => runHosted(provider, task, options.pollIntervalMs ?? 5_000),
+    };
+}
+function runHosted(provider, task, pollIntervalMs) {
+    const recorder = new RunRecorder(provider.name, provider.name);
+    const controller = new AbortController();
+    let stopReason;
+    let taskId;
+    const stop = (reason) => {
+        if (stopReason || controller.signal.aborted)
+            return;
+        stopReason = reason;
+        controller.abort();
+    };
+    const onAbort = () => stop('aborted');
+    task.signal?.addEventListener('abort', onAbort, { once: true });
+    if (task.signal?.aborted)
+        onAbort();
+    const timer = task.timeoutMs !== undefined ? setTimeout(() => stop('timeout'), task.timeoutMs) : undefined;
+    const exit = (reason, error) => ({
+        exitCode: null,
+        signal: null,
+        reason,
+        ...(error ? { error } : {}),
+    });
+    const work = async () => {
+        // Local-only fields (process env, callbacks, timers) never reach the provider.
+        const request = { ...task };
+        delete request.env;
+        delete request.signal;
+        delete request.onApproval;
+        delete request.timeoutMs;
+        try {
+            taskId = (await provider.start(request, controller.signal)).id;
+        }
+        catch (error) {
+            if (stopReason)
+                return { exit: exit(stopReason) };
+            return { exit: exit('spawn-error', error instanceof Error ? error : new Error(String(error))) };
+        }
+        recorder.emit({ type: 'session', sessionId: taskId });
+        let cursor;
+        while (!stopReason) {
+            let poll;
+            try {
+                poll = await provider.poll(taskId, cursor, controller.signal);
+            }
+            catch (error) {
+                if (stopReason)
+                    break;
+                // Do not leave a task running (and billing) that nobody watches any more.
+                await provider.cancel(taskId).catch(() => undefined);
+                const message = error instanceof Error ? error.message : String(error);
+                return { exit: exit('closed'), outcome: { ok: false, error: `Polling ${provider.name} failed: ${message}` } };
+            }
+            // Aborted while the poll was in flight: cancel, whatever state it reported.
+            if (stopReason)
+                break;
+            for (const event of poll.events ?? [])
+                recorder.emit(event);
+            cursor = poll.cursor ?? cursor;
+            if (TERMINAL.has(poll.state)) {
+                if (poll.state === 'cancelled')
+                    return { exit: exit('aborted') };
+                return {
+                    exit: exit('closed'),
+                    outcome: poll.state === 'completed'
+                        ? { ok: true }
+                        : { ok: false, error: poll.error ?? `${provider.name} task failed.` },
+                };
+            }
+            // A consumer that falls behind holds the next poll instead of buffering without bound.
+            await untilAborted(recorder.events.room(), controller.signal);
+            await delay(pollIntervalMs, controller.signal);
+        }
+        await provider.cancel(taskId).catch(() => undefined);
+        return { exit: exit(stopReason ?? 'aborted') };
+    };
+    const result = work().then(({ exit: ended, outcome }) => {
+        clearTimeout(timer);
+        task.signal?.removeEventListener('abort', onAbort);
+        return recorder.finish(ended, outcome);
+    });
+    return {
+        result,
+        abort: () => stop('aborted'),
+        ...(provider.send
+            ? {
+                steer: (text) => taskId && !stopReason
+                    ? provider.send(taskId, text)
+                    : Promise.reject(new Error(`${provider.name} is not accepting input.`)),
+            }
+            : {}),
+        [Symbol.asyncIterator]: () => recorder.events.iterate(),
+    };
+}
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener('abort', done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        }
+    });
+}
+/** Resolve when `wait` does or `signal` aborts, whichever comes first. */
+function untilAborted(wait, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            signal.removeEventListener('abort', done);
+            resolve();
+        };
+        signal.addEventListener('abort', done, { once: true });
+        void wait.then(done);
+    });
+}
+//# sourceMappingURL=hosted.js.map

package/dist/agents/hosted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted.js","sourceRoot":"","sources":["../../src/agents/hosted.ts"],"names":[],"mappings":"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"}

package/dist/agents/live-agent.d.ts

@@ -0,0 +1,37 @@
+import { type PreparedRun } from './prepare.js';
+import { RpcPeer } from './rpc.js';
+import { type AgentOutcome } from './runtime.js';
+import type { AgentCapabilities, AgentEvent, AgentTask, ApprovalDecision, ApprovalRequest, CodingAgent } from './types.js';
+/** What a live driver gets for one task. */
+export interface LiveSession {
+    readonly task: AgentTask;
+    readonly rpc: RpcPeer;
+    emit(event: AgentEvent): void;
+    /** Called for each notification the agent sends. Set once, before the first request. */
+    onNotification(handler: (method: string, params: unknown) => void): void;
+    /** Called for each request the agent sends. Throw `RpcError` to decline. Unhandled requests are declined. */
+    onRequest(handler: (method: string, params: unknown) => unknown | Promise<unknown>): void;
+    /** Ask `task.onApproval` (deny when absent or when it throws), emitting request and decision events. */
+    approve(request: ApprovalRequest): Promise<ApprovalDecision>;
+    /** Make `AgentRun.steer` send input, or pass undefined once the task stops accepting it. */
+    setSteer(steer: ((text: string) => Promise<void>) | undefined): void;
+}
+export interface LiveAgentDefinition {
+    name: string;
+    command: string;
+    capabilities?: AgentCapabilities;
+    /** Arguments that start the agent's JSON-RPC server on stdio. */
+    args(task: AgentTask): string[];
+    /** Replaces `args` when a task needs setup: extra env, temp files to clean up. */
+    prepare?(task: AgentTask): PreparedRun;
+    env?(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    /** Run one task over the session. Resolve with the agent's verdict when its turn ends. */
+    drive(session: LiveSession): Promise<AgentOutcome>;
+}
+/**
+ * Build a `CodingAgent` from a CLI that serves JSON-RPC over stdio. The process
+ * stays up for the whole task, so the caller can `steer()` it and answer approvals.
+ */
+export declare function liveAgent(definition: LiveAgentDefinition): CodingAgent;
+/** RFC 9562 UUIDv7: time-ordered ids some agents require for idempotent commands. */
+export declare function uuidv7(now?: number): string;

package/dist/agents/live-agent.js

@@ -0,0 +1,142 @@
+import { randomBytes } from 'node:crypto';
+import { planSpawn } from './prepare.js';
+import { startProcess } from './process.js';
+import { RpcError, RpcPeer } from './rpc.js';
+import { invalidCwd, RunRecorder } from './runtime.js';
+/**
+ * Build a `CodingAgent` from a CLI that serves JSON-RPC over stdio. The process
+ * stays up for the whole task, so the caller can `steer()` it and answer approvals.
+ */
+export function liveAgent(definition) {
+    return {
+        name: definition.name,
+        command: definition.command,
+        capabilities: { steer: true, ...definition.capabilities },
+        run: (task) => runLiveAgent(definition, task),
+    };
+}
+function runLiveAgent(definition, task) {
+    const recorder = new RunRecorder(definition.name, definition.command);
+    const iterate = () => recorder.events.iterate();
+    let steer;
+    // A consumer that falls behind pauses the agent's output. A steer awaited from inside the
+    // loop needs its reply read, so output keeps flowing while one is in flight.
+    let pressure = false;
+    let steering = 0;
+    let flow = () => { };
+    const steerRun = async (text) => {
+        if (!steer)
+            throw new Error(`${definition.name} is not accepting input.`);
+        steering++;
+        flow();
+        try {
+            await steer(text);
+        }
+        finally {
+            steering--;
+            flow();
+        }
+    };
+    const plan = planSpawn(definition, task, invalidCwd(task.cwd));
+    if (!plan.ok) {
+        const result = recorder.finish({ exitCode: null, signal: null, reason: 'spawn-error', error: new Error(plan.error) }, undefined);
+        return { result: Promise.resolve(result), abort() { }, steer: steerRun, [Symbol.asyncIterator]: iterate };
+    }
+    let notificationHandler = () => { };
+    let requestHandler = (method) => {
+        throw new RpcError(`${method} is not supported by this client.`, -32601);
+    };
+    const handle = startProcess({
+        command: definition.command,
+        args: plan.args,
+        cwd: task.cwd,
+        env: plan.env,
+        timeoutMs: task.timeoutMs,
+        signal: task.signal,
+        stdin: true,
+        onLine(line) {
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                recorder.emit({ type: 'raw', line });
+                return;
+            }
+            if (!rpc.receive(value))
+                recorder.emit({ type: 'raw', line });
+        },
+        onStderr: (text) => recorder.emit({ type: 'stderr', text }),
+    });
+    flow = () => (pressure && !steering ? handle.pause() : handle.resume());
+    recorder.events.onPressure = (paused) => {
+        pressure = paused;
+        flow();
+    };
+    const rpc = new RpcPeer((line) => handle.write(line), {
+        notification: (method, params) => notificationHandler(method, params),
+        request: (method, params) => requestHandler(method, params),
+    });
+    const session = {
+        task,
+        rpc,
+        emit: (event) => recorder.emit(event),
+        onNotification(handler) {
+            notificationHandler = handler;
+        },
+        onRequest(handler) {
+            requestHandler = handler;
+        },
+        async approve(request) {
+            recorder.emit({ type: 'approval-request', request });
+            let decision = 'deny';
+            try {
+                if (task.onApproval)
+                    decision = (await task.onApproval(request)) === 'approve' ? 'approve' : 'deny';
+            }
+            catch {
+                decision = 'deny';
+            }
+            recorder.emit({ type: 'approval-resolved', id: request.id, decision });
+            return decision;
+        },
+        setSteer(next) {
+            steer = next;
+        },
+    };
+    const exited = handle.exit.then((exit) => {
+        plan.cleanup();
+        steer = undefined;
+        rpc.fail(new Error(`${definition.name} exited before the task finished.`));
+        return exit;
+    });
+    const outcome = definition.drive(session).then((verdict) => verdict, (error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+    const result = Promise.race([outcome.then(() => undefined), exited]).then(async (early) => {
+        steer = undefined;
+        // Exiting before the turn ends is a failure even with exit code 0.
+        if (early)
+            return recorder.finish(early, (await settledOrUndefined(outcome)) ?? {
+                ok: false,
+                error: `${definition.name} exited before the task finished.`,
+            });
+        handle.close();
+        return recorder.finish(await exited, await outcome);
+    });
+    return { result, abort: handle.kill, steer: steerRun, [Symbol.asyncIterator]: iterate };
+}
+/** A driver's verdict when it already settled; undefined when it was still waiting. */
+async function settledOrUndefined(outcome) {
+    const pending = Symbol('pending');
+    const value = await Promise.race([outcome, Promise.resolve(pending)]);
+    return value === pending ? undefined : value;
+}
+/** RFC 9562 UUIDv7: time-ordered ids some agents require for idempotent commands. */
+export function uuidv7(now = Date.now()) {
+    const bytes = randomBytes(16);
+    bytes.writeUIntBE(now, 0, 6);
+    bytes[6] = 0x70 | (bytes[6] & 0x0f);
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=live-agent.js.map

package/dist/agents/live-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-agent.js","sourceRoot":"","sources":["../../src/agents/live-agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/prepare.d.ts

@@ -0,0 +1,33 @@
+import type { AgentCapabilities, AgentTask, McpServer } from './types.js';
+/** Everything a driver needs to start one task's process. */
+export interface PreparedRun {
+    args: string[];
+    /** Extra environment variables for the child. */
+    env?: Record<string, string>;
+    /** Called once the process has exited (temp files, for example). */
+    cleanup?(): void;
+}
+/** Reject a task the agent cannot honor before anything is spawned. */
+export declare function unsupportedTask(name: string, capabilities: AgentCapabilities, task: AgentTask): string | undefined;
+export declare function isHttpServer(server: McpServer): server is Extract<McpServer, {
+    url: string;
+}>;
+interface SpawnDefinition {
+    name: string;
+    capabilities?: AgentCapabilities;
+    args(task: AgentTask): string[];
+    prepare?(task: AgentTask): PreparedRun;
+    env?(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+}
+export type SpawnPlan = {
+    ok: true;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cleanup(): void;
+} | {
+    ok: false;
+    error: string;
+};
+/** Check the task, then resolve arguments and environment for the child process. */
+export declare function planSpawn(definition: SpawnDefinition, task: AgentTask, cwdError: string | undefined): SpawnPlan;
+export {};

package/dist/agents/prepare.js

@@ -0,0 +1,52 @@
+const MCP_NAME = /^[A-Za-z0-9_-]+$/;
+/** Reject a task the agent cannot honor before anything is spawned. */
+export function unsupportedTask(name, capabilities, task) {
+    const servers = task.mcpServers ?? [];
+    if (servers.length && !capabilities.mcp)
+        return `${name} does not support MCP servers in this driver.`;
+    const names = new Set();
+    for (const server of servers) {
+        if (!MCP_NAME.test(server.name))
+            return `Invalid MCP server name: ${JSON.stringify(server.name)}.`;
+        if (names.has(server.name))
+            return `Duplicate MCP server name: ${server.name}.`;
+        names.add(server.name);
+    }
+    return undefined;
+}
+export function isHttpServer(server) {
+    return 'url' in server;
+}
+/** Check the task, then resolve arguments and environment for the child process. */
+export function planSpawn(definition, task, cwdError) {
+    const refused = unsupportedTask(definition.name, definition.capabilities ?? {}, task) ?? cwdError;
+    if (refused)
+        return { ok: false, error: refused };
+    let prepared;
+    try {
+        prepared = definition.prepare ? definition.prepare(task) : { args: definition.args(task) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    const base = task.env ?? process.env;
+    const env = { ...(definition.env ? definition.env(base) : base), ...prepared.env };
+    let cleaned = false;
+    return {
+        ok: true,
+        args: prepared.args,
+        env,
+        cleanup() {
+            if (cleaned)
+                return;
+            cleaned = true;
+            try {
+                prepared.cleanup?.();
+            }
+            catch {
+                // Best effort: a leftover temp file must not change the task's result.
+            }
+        },
+    };
+}
+//# sourceMappingURL=prepare.js.map

package/dist/agents/prepare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.js","sourceRoot":"","sources":["../../src/agents/prepare.ts"],"names":[],"mappings":"AAWA,MAAM,QAAQ,GAAG,kBAAkB,CAAC;AAEpC,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,YAA+B,EAAE,IAAe;IAC5F,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG;QAAE,OAAO,GAAG,IAAI,+CAA+C,CAAC;IACvG,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,4BAA4B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QACnG,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,8BAA8B,MAAM,CAAC,IAAI,GAAG,CAAC;QAChF,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,OAAO,KAAK,IAAI,MAAM,CAAC;AACzB,CAAC;AAcD,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,UAA2B,EAAE,IAAe,EAAE,QAA4B;IAClG,MAAM,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,IAAI,EAAE,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC;IAClG,IAAI,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAClD,IAAI,QAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC7F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACtF,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC;IACnF,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,GAAG;QACH,OAAO;YACL,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC;gBACH,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agents/process.d.ts

@@ -0,0 +1,39 @@
+export interface ProcessOptions {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Time between SIGTERM and SIGKILL. */
+    killGraceMs?: number;
+    /** Keep stdin open for `write()` (JSON-RPC agents). Default: stdin is closed. */
+    stdin?: boolean;
+    onLine(line: string): void;
+    onStderr(text: string): void;
+}
+export interface ProcessExit {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    /** `closed`: the caller ended a long-lived agent with `close()` after its work was done. */
+    reason: 'exit' | 'closed' | 'aborted' | 'timeout' | 'spawn-error' | 'overflow';
+    error?: Error;
+}
+export interface ProcessHandle {
+    exit: Promise<ProcessExit>;
+    /** Stop the process as aborted. */
+    kill(): void;
+    /** Stop the process as finished on purpose. */
+    close(): void;
+    /** Write one line to stdin. Requires `stdin: true`. */
+    write(line: string): void;
+    /** Stop reading stdout and stderr, so the agent blocks once the pipes fill. */
+    pause(): void;
+    /** Read again after `pause()`. */
+    resume(): void;
+}
+/**
+ * Spawn a child in its own process group and deliver stdout line by line.
+ * Stopping signals the whole group, so tools the agent started die with it.
+ */
+export declare function startProcess(options: ProcessOptions): ProcessHandle;

package/dist/agents/process.js

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+const MAX_LINE_BYTES = 16 * 1024 * 1024;
+/** After the agent exits, how long a background child that inherited its pipes may keep them open. */
+const EXIT_DRAIN_MS = 500;
+/**
+ * Spawn a child in its own process group and deliver stdout line by line.
+ * Stopping signals the whole group, so tools the agent started die with it.
+ */
+export function startProcess(options) {
+    const groupKill = process.platform !== 'win32';
+    const child = spawn(options.command, [...options.args], {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: [options.stdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        detached: groupKill,
+    });
+    let reason = 'exit';
+    let spawnError;
+    let escalation;
+    let timer;
+    const signal = (name) => {
+        try {
+            if (groupKill && child.pid)
+                process.kill(-child.pid, name);
+            else
+                child.kill(name);
+        }
+        catch {
+            child.kill(name);
+        }
+    };
+    let closed = false;
+    // Pausing holds the agent back only while it runs. Once it exits or is being stopped, the
+    // rest of its output is small, and a caller awaiting `exit` must not wait on the consumer.
+    let paused = false;
+    let pausable = true;
+    const release = () => {
+        pausable = false;
+        if (!paused)
+            return;
+        paused = false;
+        child.stdout.resume();
+        child.stderr.resume();
+    };
+    // Stops still apply after the agent exits: a leftover child in its group can hold the pipes open.
+    const stop = (why) => {
+        if (closed || reason !== 'exit')
+            return;
+        reason = why;
+        release();
+        signal('SIGTERM');
+        escalation = setTimeout(() => signal('SIGKILL'), options.killGraceMs ?? 2_000);
+        escalation.unref?.();
+    };
+    const onAbort = () => stop('aborted');
+    let buffered = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        buffered += chunk;
+        let end = buffered.indexOf('\n');
+        while (end >= 0) {
+            const line = buffered.slice(0, end).replace(/\r$/, '');
+            buffered = buffered.slice(end + 1);
+            if (line.trim())
+                options.onLine(line);
+            end = buffered.indexOf('\n');
+        }
+        if (buffered.length > MAX_LINE_BYTES) {
+            buffered = '';
+            stop('overflow');
+        }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => options.onStderr(chunk));
+    // `close` waits for every holder of stdout/stderr. After the agent exits, stop waiting for its leftovers.
+    let drain;
+    const armDrain = () => {
+        if (closed)
+            return;
+        drain = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }, EXIT_DRAIN_MS);
+        drain.unref?.();
+    };
+    const exit = new Promise((resolve) => {
+        child.once('error', (error) => {
+            spawnError = error;
+            reason = 'spawn-error';
+        });
+        child.once('exit', () => {
+            release();
+            armDrain();
+        });
+        child.once('close', (exitCode, exitSignal) => {
+            closed = true;
+            clearTimeout(drain);
+            clearTimeout(timer);
+            clearTimeout(escalation);
+            options.signal?.removeEventListener('abort', onAbort);
+            if (buffered.trim())
+                options.onLine(buffered.replace(/\r$/, ''));
+            buffered = '';
+            resolve({ exitCode, signal: exitSignal, reason, error: spawnError });
+        });
+    });
+    if (options.timeoutMs !== undefined)
+        timer = setTimeout(() => stop('timeout'), options.timeoutMs);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted)
+        onAbort();
+    child.stdin?.on('error', () => {
+        // The agent exited mid-write; its exit status reports why.
+    });
+    return {
+        exit,
+        kill: () => stop('aborted'),
+        close: () => stop('closed'),
+        write(line) {
+            if (!child.stdin || child.stdin.destroyed)
+                throw new Error(`${options.command} is not accepting input.`);
+            child.stdin.write(line.endsWith('\n') ? line : `${line}\n`);
+        },
+        pause() {
+            if (paused || !pausable || closed)
+                return;
+            paused = true;
+            child.stdout.pause();
+            child.stderr.pause();
+        },
+        resume() {
+            if (!paused)
+                return;
+            paused = false;
+            child.stdout.resume();
+            child.stderr.resume();
+        },
+    };
+}
+//# sourceMappingURL=process.js.map

package/dist/agents/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/agents/process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxC,sGAAsG;AACtG,MAAM,aAAa,GAAG,GAAG,CAAC;AAuC1B;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAuB;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE;QACtD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;QAC1D,QAAQ,EAAE,SAAS;KACpB,CAAC,CAAC;IAEH,IAAI,MAAM,GAA0B,MAAM,CAAC;IAC3C,IAAI,UAA6B,CAAC;IAClC,IAAI,UAAqD,CAAC;IAC1D,IAAI,KAAgD,CAAC;IAErD,MAAM,MAAM,GAAG,CAAC,IAAoB,EAAE,EAAE;QACtC,IAAI,CAAC;YACH,IAAI,SAAS,IAAI,KAAK,CAAC,GAAG;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;;gBACtD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,0FAA0F;IAC1F,2FAA2F;IAC3F,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,QAAQ,GAAG,KAAK,CAAC;QACjB,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,GAAG,KAAK,CAAC;QACf,KAAK,CAAC,MAAO,CAAC,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,MAAO,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC,CAAC;IACF,kGAAkG;IAClG,MAAM,IAAI,GAAG,CAAC,GAA0B,EAAE,EAAE;QAC1C,IAAI,MAAM,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO;QACxC,MAAM,GAAG,GAAG,CAAC;QACb,OAAO,EAAE,CAAC;QACV,MAAM,CAAC,SAAS,CAAC,CAAC;QAClB,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC,CAAC;QAC/E,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEtC,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,KAAK,CAAC,MAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,KAAK,CAAC,MAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;QACzC,QAAQ,IAAI,KAAK,CAAC;QAClB,IAAI,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACvD,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACnC,IAAI,IAAI,CAAC,IAAI,EAAE;gBAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACtC,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YACrC,QAAQ,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,UAAU,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,MAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,KAAK,CAAC,MAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAErE,0GAA0G;IAC1G,IAAI,KAAgD,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,MAAM;YAAE,OAAO;QACnB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,CAAC,MAAO,CAAC,OAAO,EAAE,CAAC;YACxB,KAAK,CAAC,MAAO,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,EAAE,aAAa,CAAC,CAAC;QAClB,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAClB,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,EAAE;QAChD,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC5B,UAAU,GAAG,KAAK,CAAC;YACnB,MAAM,GAAG,aAAa,CAAC;QACzB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE;YAC3C,MAAM,GAAG,IAAI,CAAC;YACd,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,YAAY,CAAC,UAAU,CAAC,CAAC;YACzB,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACtD,IAAI,QAAQ,CAAC,IAAI,EAAE;gBAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;YACjE,QAAQ,GAAG,EAAE,CAAC;YACd,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAClG,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO,EAAE,CAAC;IAEvC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QAC5B,2DAA2D;IAC7D,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC;QAC3B,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC3B,KAAK,CAAC,IAAI;YACR,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,0BAA0B,CAAC,CAAC;YACzG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK;YACH,IAAI,MAAM,IAAI,CAAC,QAAQ,IAAI,MAAM;gBAAE,OAAO;YAC1C,MAAM,GAAG,IAAI,CAAC;YACd,KAAK,CAAC,MAAO,CAAC,KAAK,EAAE,CAAC;YACtB,KAAK,CAAC,MAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QACD,MAAM;YACJ,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,GAAG,KAAK,CAAC;YACf,KAAK,CAAC,MAAO,CAAC,MAAM,EAAE,CAAC;YACvB,KAAK,CAAC,MAAO,CAAC,MAAM,EAAE,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agents/rpc.d.ts

@@ -0,0 +1,29 @@
+export interface RpcHandlers {
+    notification(method: string, params: unknown): void;
+    /** Resolve with the result, or throw to send a JSON-RPC error. */
+    request(method: string, params: unknown): unknown | Promise<unknown>;
+}
+export declare class RpcError extends Error {
+    readonly code: number;
+    constructor(message: string, code?: number);
+}
+/**
+ * Minimal JSON-RPC 2.0 peer over newline-delimited JSON. The caller owns the
+ * transport: it hands incoming values to `receive` and supplies `write`.
+ */
+export declare class RpcPeer {
+    private readonly write;
+    private readonly handlers;
+    private nextId;
+    private failure;
+    private readonly pending;
+    constructor(write: (line: string) => void, handlers: RpcHandlers);
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    /** Handle one incoming JSON value. Returns false when it is not a JSON-RPC message. */
+    receive(message: unknown): boolean;
+    /** Reject everything in flight and refuse new requests. */
+    fail(error: Error): void;
+    private answer;
+    private send;
+}