@rarebit-one/harness-kernel 0.6.0 → 0.8.0

package/dist/engines/acp.d.ts

@@ -0,0 +1,121 @@
+import type { McpServer } from "@zed-industries/agent-client-protocol";
+import type { RunOutcome } from "../events.js";
+import type { StoppedBy } from "../signals.js";
+import type { AgentEngine, EngineContext, EngineResult, EngineSupport, RunSpec } from "./types.js";
+/**
+ * A named external agent this engine can drive over the Agent Client Protocol.
+ * ACP is a JSON-RPC-over-stdio protocol between a *client* (this engine) and a
+ * coding *agent* running as a separate process, so every ACP agent reduces to
+ * "which subprocess to spawn, with what argv and env". The capability MCP server
+ * and the run's connectors are handed to the agent through `session/new`, so a
+ * spec never has to describe those — only its own launch.
+ *
+ * External agent product names appearing here follow the existing `claude-code`
+ * / `codex` precedent: an adapter's honest identity is the tool it drives, not a
+ * consumer's brand.
+ */
+export interface AcpAgentSpec {
+    /** Engine name; also the `provider.engine` value that selects it. */
+    readonly name: string;
+    /** Env var that must equal `"1"` for {@link AcpEngine.supports} to allow this agent. */
+    readonly enableEnv: string;
+    /** The executable to spawn — an ACP server over stdio. */
+    readonly command: string;
+    /** The process argv for a run (e.g. the ACP subcommand). */
+    args(spec: RunSpec): string[];
+    /** Extra process env — e.g. the provider credentials the agent reads for itself. */
+    env(spec: RunSpec): Record<string, string>;
+}
+/**
+ * Driver-neutral options the engine derives from a {@link RunSpec} and hands to
+ * the ACP driver. The default driver spawns `command`+`args` and speaks ACP over
+ * its stdio; tests inject a fake driver and assert this mapping.
+ */
+export interface AcpOptions {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    /** The prepared sandbox working tree — the agent's cwd and ACP `session/new` cwd. */
+    cwd: string;
+    /** The run's MCP servers (connectors + the capability server) for `session/new`. */
+    mcpServers: McpServer[];
+    /** The task prompt (workflow prompt + inputs). */
+    prompt: string;
+    /** Wall-clock budget in ms; undefined means no engine-imposed limit. */
+    maxDurationMs?: number;
+    /** Append a line to the run log (the driver surfaces the agent's stderr here). */
+    log: (line: string) => void;
+    /** The caller's cancel; the driver merges it with its own `maxDurationMs` timer. */
+    signal?: AbortSignal;
+    /**
+     * How long the agent gets to answer `session/cancel` after a stop before its
+     * process is killed. Defaults to 5s. Bounds every stop, so a hung agent
+     * cannot keep a canceled or timed-out run alive.
+     */
+    cancelGraceMs?: number;
+}
+/** Streaming callbacks the driver invokes as ACP `session/update`s arrive. */
+export interface AcpClientEvents {
+    /** An `agent_message_chunk` — accumulated into the run's prose result. */
+    onAssistantChunk(text: string): void;
+    /** A human-readable line for the run log (thoughts, tool-call titles). */
+    onLog(line: string): void;
+}
+/** What one ACP prompt turn resolved to. */
+export interface AcpOutcome {
+    /** The ACP `stopReason` (`end_turn`, `cancelled`, `refusal`, …). */
+    stopReason: string;
+    /** Set when the driver stopped the turn itself: its own timer
+     *  (`"deadline"`) or the caller's signal (`"signal"`). */
+    stoppedBy?: StoppedBy;
+}
+/** The injectable boundary to the ACP transport. Tests supply a fake. */
+export type AcpDriver = (opts: AcpOptions, events: AcpClientEvents) => Promise<AcpOutcome>;
+/**
+ * Drives a run with any ACP-speaking coding agent (Claude Code, Codex, eve, …)
+ * against the sandbox working tree. One engine, one transport: where the codex
+ * engine wrote a `config.toml` and the Claude Code engine mounted an in-process
+ * SDK MCP server, this hands the run's connectors + the runner-hosted capability
+ * server to the agent through the ACP `session/new` `mcpServers` field, and reads
+ * back the capability server's emissions file — so an ACP agent reaches emit
+ * parity with native.
+ *
+ * Because an ACP agent runs arbitrary code, `supports()` refuses unless the
+ * operator enabled this specific agent AND the run is on the ephemeral runner
+ * profile (one throwaway container per run is the safety boundary). File edits
+ * are out-of-band: the agent edits `cwd` directly and the caller's change-set
+ * diff captures them, so this engine advertises no client filesystem capability.
+ */
+export declare class AcpEngine implements AgentEngine {
+    readonly name: string;
+    private readonly agent;
+    private readonly capabilityServerScript;
+    private readonly drive;
+    /**
+     * `capabilityServerScript` is REQUIRED, exactly as for codex: the capability
+     * surface is injected, and a child process cannot be handed a closure, so the
+     * application must supply the entrypoint that serves its own tools over stdio.
+     */
+    constructor(agent: AcpAgentSpec, capabilityServerScript: string, drive?: AcpDriver);
+    supports(spec: RunSpec): EngineSupport;
+    run(spec: RunSpec, ctx: EngineContext): Promise<EngineResult>;
+}
+/**
+ * Map an ACP turn's ending onto the run outcome vocabulary. Who stopped it
+ * wins when the driver knows (`stoppedBy`); otherwise the ACP `stopReason`
+ * decides. `max_turn_requests` is the agent's own step budget; `max_tokens`
+ * still produced an answer (truncated), so it stays `completed`; a `refusal`
+ * did not do the work, so it is `failed`. An agent-side `cancelled` with no
+ * known stopper is reported as `canceled`.
+ */
+export declare function acpRunOutcome(outcome: AcpOutcome): RunOutcome;
+/**
+ * The eve agent (Vercel's open-source framework), driven over `eve acp` — its
+ * stdio ACP server surface. eve reads its own model/provider from the authored
+ * eve application in the workdir; we pass through whatever provider credentials
+ * the run carries so a BYO key reaches it. (Open: an eve "agent" is an authored
+ * app, so the workdir must contain one — a workflow-declared app path with an
+ * `agent/`-root default is the follow-up; today it runs the app at the workdir root.)
+ */
+export declare const EVE_AGENT: AcpAgentSpec;
+//# sourceMappingURL=acp.d.ts.map

package/dist/engines/acp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../../src/engines/acp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAQlG;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4DAA4D;IAC5D,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAAA;IAC7B,oFAAoF;IACpF,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3B,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAA;IACX,oFAAoF;IACpF,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,kFAAkF;IAClF,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,0EAA0E;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAClB;8DAC0D;IAC1D,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAE1F;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAU,YAAW,WAAW;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IAEjC;;;;OAIG;gBAED,KAAK,EAAE,YAAY,EACnB,sBAAsB,EAAE,MAAM,EAC9B,KAAK,GAAE,SAA4B;IAQrC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa;IAgBhC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAgFpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAa7D;AA8CD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,YAavB,CAAA"}

package/dist/engines/acp.js

@@ -0,0 +1,219 @@
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CAPABILITY_SERVER_NAME } from "./capabilityMcp.js";
+import { connectorServers } from "./connectorMcp.js";
+import { readEmissions } from "./capabilityEmissions.js";
+import { defaultAcpDriver } from "./acpDriver.js";
+const LOG_TRUNCATE = 2000;
+/**
+ * Drives a run with any ACP-speaking coding agent (Claude Code, Codex, eve, …)
+ * against the sandbox working tree. One engine, one transport: where the codex
+ * engine wrote a `config.toml` and the Claude Code engine mounted an in-process
+ * SDK MCP server, this hands the run's connectors + the runner-hosted capability
+ * server to the agent through the ACP `session/new` `mcpServers` field, and reads
+ * back the capability server's emissions file — so an ACP agent reaches emit
+ * parity with native.
+ *
+ * Because an ACP agent runs arbitrary code, `supports()` refuses unless the
+ * operator enabled this specific agent AND the run is on the ephemeral runner
+ * profile (one throwaway container per run is the safety boundary). File edits
+ * are out-of-band: the agent edits `cwd` directly and the caller's change-set
+ * diff captures them, so this engine advertises no client filesystem capability.
+ */
+export class AcpEngine {
+    name;
+    agent;
+    capabilityServerScript;
+    drive;
+    /**
+     * `capabilityServerScript` is REQUIRED, exactly as for codex: the capability
+     * surface is injected, and a child process cannot be handed a closure, so the
+     * application must supply the entrypoint that serves its own tools over stdio.
+     */
+    constructor(agent, capabilityServerScript, drive = defaultAcpDriver) {
+        this.agent = agent;
+        this.name = agent.name;
+        this.capabilityServerScript = capabilityServerScript;
+        this.drive = drive;
+    }
+    supports(spec) {
+        if (process.env[this.agent.enableEnv] !== "1") {
+            return {
+                ok: false,
+                reason: `${this.name} engine is disabled (set ${this.agent.enableEnv}=1)`,
+            };
+        }
+        if (spec.workflow.runner?.profile !== "ephemeral") {
+            return {
+                ok: false,
+                reason: `${this.name} engine requires the ephemeral runner profile (per-run container isolation)`,
+            };
+        }
+        return { ok: true };
+    }
+    async run(spec, ctx) {
+        // Emissions land OUTSIDE the sandbox so the bookkeeping file is never captured
+        // by the change set; the capability server (an external process) writes here and
+        // we read it back after the run.
+        const emissionsDir = await mkdtemp(path.join(tmpdir(), "harness-emit-"));
+        const emissionsFile = path.join(emissionsDir, "emissions.json");
+        const capabilityEnv = {
+            HARNESS_WORKSPACE_ID: spec.workspaceId,
+            HARNESS_WORKDIR: spec.workdir,
+            HARNESS_EMISSIONS_FILE: emissionsFile,
+        };
+        const servers = {
+            ...connectorServers(spec.connectors),
+            [CAPABILITY_SERVER_NAME]: {
+                type: "stdio",
+                command: process.execPath,
+                args: [this.capabilityServerScript],
+                env: capabilityEnv,
+            },
+        };
+        const options = {
+            command: this.agent.command,
+            args: this.agent.args(spec),
+            // The capability env also rides on the process env so the stdio capability
+            // server inherits it regardless of how the agent forwards `session/new` env.
+            env: { ...this.agent.env(spec), ...capabilityEnv },
+            cwd: spec.workdir,
+            mcpServers: toAcpMcpServers(servers),
+            prompt: buildPrompt(spec),
+            ...(spec.limits?.maxDurationMs !== undefined
+                ? { maxDurationMs: spec.limits.maxDurationMs }
+                : {}),
+            log: ctx.log,
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        };
+        ctx.log(`${this.name}: driving ACP agent in ${spec.workdir}`);
+        const chunks = [];
+        let outcome;
+        try {
+            outcome = await this.drive(options, {
+                onAssistantChunk: (text) => {
+                    if (text)
+                        chunks.push(text);
+                },
+                onLog: (line) => {
+                    if (line)
+                        ctx.log(`${this.name}: ${truncate(line, LOG_TRUNCATE)}`);
+                },
+            });
+        }
+        catch (err) {
+            // A driver that throws on the caller's abort was still canceled, not broken.
+            if (!ctx.signal?.aborted)
+                throw err;
+            outcome = { stopReason: "cancelled", stoppedBy: "signal" };
+        }
+        if (outcome.stopReason && outcome.stopReason !== "end_turn") {
+            ctx.log(`${this.name}: stopped (${outcome.stopReason})`);
+        }
+        // Report whether the emissions round trip HAPPENED, not what it carried —
+        // presence plus size separates "the server never wrote" from "it wrote and the
+        // run emitted nothing"; the byte count comes from the file (see codex engine).
+        const emissionsStat = await stat(emissionsFile).then((st) => st, () => undefined);
+        const emissions = await readEmissions(emissionsFile);
+        ctx.log(`${this.name}: capability emissions — file ${emissionsStat ? `present (${emissionsStat.size} bytes)` : "absent"}` +
+            `${emissionsStat && emissions === undefined ? ", unreadable" : ""}`);
+        await rm(emissionsDir, { recursive: true, force: true });
+        return {
+            text: chunks.join("").trim() || "(no output)",
+            ...(emissions !== undefined ? { emissions } : {}),
+            outcome: acpRunOutcome(outcome),
+        };
+    }
+}
+/**
+ * Map an ACP turn's ending onto the run outcome vocabulary. Who stopped it
+ * wins when the driver knows (`stoppedBy`); otherwise the ACP `stopReason`
+ * decides. `max_turn_requests` is the agent's own step budget; `max_tokens`
+ * still produced an answer (truncated), so it stays `completed`; a `refusal`
+ * did not do the work, so it is `failed`. An agent-side `cancelled` with no
+ * known stopper is reported as `canceled`.
+ */
+export function acpRunOutcome(outcome) {
+    if (outcome.stoppedBy === "deadline")
+        return "timed_out";
+    if (outcome.stoppedBy === "signal")
+        return "canceled";
+    switch (outcome.stopReason) {
+        case "cancelled":
+            return "canceled";
+        case "max_turn_requests":
+            return "steps_exhausted";
+        case "refusal":
+            return "failed";
+        default:
+            return "completed";
+    }
+}
+/**
+ * Translate the run's serializable MCP servers into ACP's `McpServer[]`. Same
+ * source data every other engine consumes (`connectorServers`), reshaped to the
+ * ACP wire form: env and headers become `{ name, value }` arrays.
+ */
+function toAcpMcpServers(servers) {
+    return Object.entries(servers).map(([name, server]) => {
+        if (server.type === "stdio") {
+            return {
+                name,
+                command: server.command,
+                args: server.args ?? [],
+                env: Object.entries(server.env ?? {}).map(([key, value]) => ({ name: key, value })),
+            };
+        }
+        return {
+            name,
+            type: server.type,
+            url: server.url,
+            headers: Object.entries(server.headers ?? {}).map(([key, value]) => ({ name: key, value })),
+        };
+    });
+}
+function buildPrompt(spec) {
+    const inputs = JSON.stringify(spec.inputs ?? {}, null, 2);
+    return [
+        spec.workflow.prompt ?? `Execute the "${spec.workflow.name ?? spec.workflowPath}" workflow.`,
+        "",
+        "## Inputs",
+        "```json",
+        inputs,
+        "```",
+        "",
+        "You are running as an autonomous workflow. The current working directory is the",
+        "workspace — inspect and edit its files directly with your tools. When finished,",
+        "reply with the workflow's output as Markdown.",
+    ].join("\n");
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/**
+ * The eve agent (Vercel's open-source framework), driven over `eve acp` — its
+ * stdio ACP server surface. eve reads its own model/provider from the authored
+ * eve application in the workdir; we pass through whatever provider credentials
+ * the run carries so a BYO key reaches it. (Open: an eve "agent" is an authored
+ * app, so the workdir must contain one — a workflow-declared app path with an
+ * `agent/`-root default is the follow-up; today it runs the app at the workdir root.)
+ */
+export const EVE_AGENT = {
+    name: "eve",
+    enableEnv: "RUNNER_ENABLE_EVE",
+    command: "eve",
+    args: () => ["acp"],
+    env: (spec) => {
+        const env = {};
+        const creds = spec.provider.credentials;
+        if (creds?.anthropic)
+            env.ANTHROPIC_API_KEY = creds.anthropic;
+        if (creds?.openai)
+            env.OPENAI_API_KEY = creds.openai;
+        if (creds?.openrouter)
+            env.OPENROUTER_API_KEY = creds.openrouter;
+        return env;
+    },
+};
+//# sourceMappingURL=acp.js.map

package/dist/engines/acp.js.map

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

package/dist/engines/acpDriver.d.ts

@@ -0,0 +1,33 @@
+import { type StoppedBy } from "../signals.js";
+import type { AcpClientEvents, AcpOptions, AcpOutcome } from "./acp.js";
+/**
+ * The outcome of a prompt turn that returned. A stop is credited only when the
+ * agent actually answered `cancelled`: a stop that lands just after a clean
+ * `end_turn` must not relabel a finished run as canceled or timed out.
+ */
+export declare function promptOutcome(stopReason: string, stoppedBy: StoppedBy | undefined): AcpOutcome;
+/**
+ * The default ACP driver: the single integration boundary to an ACP agent
+ * subprocess, mirroring `defaultCodexDriver`'s injectable shape. It spawns the
+ * agent, wires an {@link ClientSideConnection} over its stdio via
+ * {@link ndJsonStream}, and runs one ACP turn: `initialize` → `session/new`
+ * (with the run's cwd + MCP servers) → `session/prompt`.
+ *
+ * The host `Client` it implements is deliberately minimal:
+ *   - `sessionUpdate` accumulates `agent_message_chunk`s (the run's prose) and
+ *     surfaces thoughts / tool-call titles to the log.
+ *   - `requestPermission` AUTO-APPROVES (selects an `allow_*` option). This is
+ *     the ACP equivalent of the codex driver's `--dangerously-bypass-approvals`
+ *     and the Claude Code driver's `bypassPermissions`, justified the same way:
+ *     an ACP agent only runs inside a throwaway ephemeral container, so the
+ *     container — not an approval prompt — is the safety boundary.
+ *   - No `readTextFile`/`writeTextFile`/terminal capability is advertised, so the
+ *     agent edits `cwd` directly and the caller's change-set diff is the sole
+ *     edit path (no second, protocol-level way for a file to change).
+ *
+ * Exercised only when the operator enables the agent (per-agent env flag) on the
+ * ephemeral profile; every test injects a fake driver, so no binary/network is
+ * touched in CI.
+ */
+export declare function defaultAcpDriver(opts: AcpOptions, events: AcpClientEvents): Promise<AcpOutcome>;
+//# sourceMappingURL=acpDriver.d.ts.map

package/dist/engines/acpDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acpDriver.d.ts","sourceRoot":"","sources":["../../src/engines/acpDriver.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEvE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAE9F;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,UAAU,CAAC,CA6GrB"}

package/dist/engines/acpDriver.js

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@zed-industries/agent-client-protocol";
+import { runStop } from "../signals.js";
+/**
+ * The outcome of a prompt turn that returned. A stop is credited only when the
+ * agent actually answered `cancelled`: a stop that lands just after a clean
+ * `end_turn` must not relabel a finished run as canceled or timed out.
+ */
+export function promptOutcome(stopReason, stoppedBy) {
+    return stopReason === "cancelled" && stoppedBy ? { stopReason, stoppedBy } : { stopReason };
+}
+/** How long an agent gets to honour `session/cancel` before it is killed. */
+const DEFAULT_CANCEL_GRACE_MS = 5_000;
+/**
+ * The default ACP driver: the single integration boundary to an ACP agent
+ * subprocess, mirroring `defaultCodexDriver`'s injectable shape. It spawns the
+ * agent, wires an {@link ClientSideConnection} over its stdio via
+ * {@link ndJsonStream}, and runs one ACP turn: `initialize` → `session/new`
+ * (with the run's cwd + MCP servers) → `session/prompt`.
+ *
+ * The host `Client` it implements is deliberately minimal:
+ *   - `sessionUpdate` accumulates `agent_message_chunk`s (the run's prose) and
+ *     surfaces thoughts / tool-call titles to the log.
+ *   - `requestPermission` AUTO-APPROVES (selects an `allow_*` option). This is
+ *     the ACP equivalent of the codex driver's `--dangerously-bypass-approvals`
+ *     and the Claude Code driver's `bypassPermissions`, justified the same way:
+ *     an ACP agent only runs inside a throwaway ephemeral container, so the
+ *     container — not an approval prompt — is the safety boundary.
+ *   - No `readTextFile`/`writeTextFile`/terminal capability is advertised, so the
+ *     agent edits `cwd` directly and the caller's change-set diff is the sole
+ *     edit path (no second, protocol-level way for a file to change).
+ *
+ * Exercised only when the operator enables the agent (per-agent env flag) on the
+ * ephemeral profile; every test injects a fake driver, so no binary/network is
+ * touched in CI.
+ */
+export async function defaultAcpDriver(opts, events) {
+    const child = spawn(opts.command, opts.args, {
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stderr = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    // A spawn failure (e.g. the agent binary is absent) surfaces here; the awaited
+    // protocol calls below then reject and we rethrow with the stderr tail.
+    child.on("error", (err) => {
+        stderr += `\n${String(err)}`;
+    });
+    const client = {
+        // Not `async`: these return a resolved promise directly (the ACP `Client`
+        // methods are `Promise`-typed, but there is nothing to await).
+        sessionUpdate({ update }) {
+            switch (update.sessionUpdate) {
+                case "agent_message_chunk":
+                    if (update.content.type === "text")
+                        events.onAssistantChunk(update.content.text);
+                    break;
+                case "agent_thought_chunk":
+                    if (update.content.type === "text")
+                        events.onLog(`thought: ${update.content.text}`);
+                    break;
+                case "tool_call":
+                    events.onLog(`tool: ${update.title}`);
+                    break;
+                default:
+                    break;
+            }
+            return Promise.resolve();
+        },
+        requestPermission({ options }) {
+            const allow = options.find((o) => o.kind === "allow_always") ??
+                options.find((o) => o.kind === "allow_once");
+            return Promise.resolve(allow
+                ? { outcome: { outcome: "selected", optionId: allow.optionId } }
+                : { outcome: { outcome: "cancelled" } });
+        },
+    };
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    const conn = new ClientSideConnection(() => client, stream);
+    // The run's own timer merged with the caller's cancel. Once a session exists
+    // the stop is a protocol-level `session/cancel` (the agent winds the turn
+    // down and answers `cancelled`), with a bounded grace period: an agent that
+    // is hung or ignores the cancel is killed, so a stop can never hang the run.
+    // Before a session exists there is nothing to cancel, so it is killed at once.
+    //
+    // Every protocol await races `forced`, which rejects on a force-stop: a
+    // killed agent never answers, and its pending requests would otherwise wait
+    // forever.
+    let sessionId = "";
+    let forceTimer;
+    let rejectForced = () => { };
+    const forced = new Promise((_, reject) => {
+        rejectForced = reject;
+    });
+    forced.catch(() => { }); // observed via the races below; never unhandled
+    const guarded = (call) => Promise.race([call, forced]);
+    const forceStop = () => {
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill("SIGKILL");
+        rejectForced(new Error(`${opts.command}: agent force-stopped`));
+    };
+    const stop = runStop(opts.maxDurationMs, opts.signal);
+    const onStop = () => {
+        if (!sessionId)
+            return forceStop();
+        void conn.cancel({ sessionId }).catch(() => { });
+        forceTimer = setTimeout(forceStop, opts.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS);
+    };
+    if (stop.signal?.aborted)
+        onStop();
+    else
+        stop.signal?.addEventListener("abort", onStop, { once: true });
+    try {
+        await guarded(conn.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }));
+        const session = await guarded(conn.newSession({ cwd: opts.cwd, mcpServers: opts.mcpServers }));
+        sessionId = session.sessionId;
+        // A stop that landed while the session was being created killed nothing
+        // yet (there was no session): honour it now rather than run the turn.
+        const early = stop.stoppedBy();
+        if (early)
+            return { stopReason: "cancelled", stoppedBy: early };
+        const res = await guarded(conn.prompt({ sessionId, prompt: [{ type: "text", text: opts.prompt }] }));
+        return promptOutcome(res.stopReason, stop.stoppedBy());
+    }
+    catch (err) {
+        // A force-stop (or the kill-before-session path) rejects the pending
+        // protocol call; that is the stop, not an agent failure.
+        const stoppedBy = stop.stoppedBy();
+        if (stoppedBy)
+            return { stopReason: "cancelled", stoppedBy };
+        if (stderr.trim()) {
+            const tail = stderr.length > 4000 ? `…${stderr.slice(-4000)}` : stderr;
+            opts.log(`${opts.command} stderr:\n${tail}`);
+        }
+        throw err;
+    }
+    finally {
+        if (forceTimer)
+            clearTimeout(forceTimer);
+        stop.signal?.removeEventListener("abort", onStop);
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill();
+    }
+}
+//# sourceMappingURL=acpDriver.js.map

package/dist/engines/acpDriver.js.map

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

package/dist/engines/claudeCode.d.ts

@@ -1,3 +1,4 @@
+import { type StoppedBy } from "../signals.js";
 import type { ConnectorConfig } from "../types.js";
 import type { AgentEngine, EngineContext, EngineResult, EngineSupport, RunSpec } from "./types.js";
 import { type CapabilityContext, type CapabilityTool } from "./capability.js";
@@ -25,6 +26,8 @@ export interface ClaudeCodeOptions {
     /** The run's external MCP connectors; the driver mounts them as SDK mcpServers so
      *  they become tools inside Claude Code (parity with the native engine). */
     connectors?: ConnectorConfig[];
+    /** The caller's cancel; the driver merges it with its own `maxDurationMs` timer. */
+    signal?: AbortSignal;
 }
 /** A normalized message from the harness (driver-agnostic). */
 export type ClaudeCodeMessage = {
@@ -34,6 +37,9 @@ export type ClaudeCodeMessage = {
     kind: "result";
     text: string;
     isError: boolean;
+    /** Set when the driver stopped the harness early: its own timer
+     *  (`"deadline"`) or the caller's signal (`"signal"`). */
+    stoppedBy?: StoppedBy;
 };
 /**
  * The injectable boundary to the Claude Code harness: given mapped options, yield

package/dist/engines/claudeCode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claudeCode.d.ts","sourceRoot":"","sources":["../../src/engines/claudeCode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAElG,OAAO,EAAuB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAElG;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;sFACkF;IAClF,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAA;IAC3B;gFAC4E;IAC5E,UAAU,CAAC,EAAE,eAAe,EAAE,CAAA;CAC/B;AAED,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAE1F;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,aAAa,CAAC,iBAAiB,CAAC,CAAA;AAK5F;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,cAAc,EAAE,CAAA;AAEhF,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,EAAE,qBAA2D,CAAA;AAEhG;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,iBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;gBAGrD,KAAK,GAAE,gBAA0C,EACjD,eAAe,GAAE,qBAA8C;IAMjE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa;IAiBhC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CA4CpE"}
+{"version":3,"file":"claudeCode.d.ts","sourceRoot":"","sources":["../../src/engines/claudeCode.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAElG,OAAO,EAAuB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAElG;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;sFACkF;IAClF,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAA;IAC3B;gFAC4E;IAC5E,UAAU,CAAC,EAAE,eAAe,EAAE,CAAA;IAC9B,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB;8DAC0D;IAC1D,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,CAAA;AAEL;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,aAAa,CAAC,iBAAiB,CAAC,CAAA;AAK5F;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,cAAc,EAAE,CAAA;AAEhF,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,EAAE,qBAA2D,CAAA;AAEhG;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,iBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;gBAGrD,KAAK,GAAE,gBAA0C,EACjD,eAAe,GAAE,qBAA8C;IAMjE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa;IAiBhC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CA+DpE"}

package/dist/engines/claudeCode.js

@@ -1,3 +1,4 @@
+import { harnessOutcome } from "../signals.js";
 import { defaultClaudeCodeDriver } from "./claudeCodeDriver.js";
 import { writeFileCapability } from "./capability.js";
 const DEFAULT_MODEL = "claude-opus-4-8";
@@ -62,21 +63,42 @@ export class ClaudeCodeEngine {
             ...(spec.limits?.maxDurationMs !== undefined
                 ? { maxDurationMs: spec.limits.maxDurationMs }
                 : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
         };
         ctx.log(`claude-code: driving model ${model} in ${spec.workdir}`);
         let finalText = "";
-        for await (const message of this.drive(options)) {
-            if (message.kind === "assistant") {
-                if (message.text)
-                    ctx.log(`claude-code: ${truncate(message.text, LOG_TRUNCATE)}`);
-            }
-            else {
-                finalText = message.text;
-                if (message.isError)
-                    ctx.log("claude-code: harness reported an error");
+        let lastAssistantText = "";
+        let outcome = "completed";
+        try {
+            for await (const message of this.drive(options)) {
+                if (message.kind === "assistant") {
+                    if (message.text) {
+                        lastAssistantText = message.text;
+                        ctx.log(`claude-code: ${truncate(message.text, LOG_TRUNCATE)}`);
+                    }
+                }
+                else {
+                    finalText = message.text;
+                    outcome = harnessOutcome(message.isError, message.stoppedBy);
+                    if (message.stoppedBy)
+                        ctx.log(`claude-code: stopped (${outcome})`);
+                    else if (message.isError)
+                        ctx.log("claude-code: harness reported an error");
+                }
             }
         }
-        return { text: finalText || "(no output)" };
+        catch (err) {
+            // A driver that throws on the caller's abort was still canceled, not broken.
+            if (!ctx.signal?.aborted)
+                throw err;
+            outcome = "canceled";
+            ctx.log("claude-code: stopped (canceled)");
+        }
+        const stopped = outcome === "canceled" || outcome === "timed_out";
+        return {
+            text: finalText || (stopped ? lastAssistantText : "") || "(no output)",
+            outcome,
+        };
     }
 }
 function buildPrompt(spec) {