@fusionkit/runner 0.1.0

package/dist/agents.d.ts

@@ -0,0 +1,15 @@
+import type { AgentKind } from "@fusionkit/protocol";
+export type AgentCommand = {
+    cmd: string;
+    args: string[];
+};
+export type AgentContext = {
+    /** Absolute path to the built-in mock agent script (dist). */
+    mockScriptPath: string;
+};
+/**
+ * Agent adapters build the command line for a vendor harness, unmodified.
+ * The labs' RL investment lands in their CLIs; Warrant wraps them in a
+ * governed session rather than reimplementing them.
+ */
+export declare function buildAgentCommand(kind: AgentKind, prompt: string, ctx: AgentContext): AgentCommand;

package/dist/agents.js

@@ -0,0 +1,48 @@
+/**
+ * Agent adapters build the command line for a vendor harness, unmodified.
+ * The labs' RL investment lands in their CLIs; Warrant wraps them in a
+ * governed session rather than reimplementing them.
+ */
+export function buildAgentCommand(kind, prompt, ctx) {
+    switch (kind) {
+        case "claude-code":
+            return {
+                // The vendor CLI invocation, wrapped as-is. These names and flags
+                // are the vendor's contract, not Warrant's to abstract away.
+                cmd: "claude",
+                args: ["-p", prompt, "--permission-mode", "acceptEdits"]
+            };
+        case "codex":
+            return {
+                cmd: "codex",
+                args: ["exec", "--skip-git-repo-check", prompt]
+            };
+        case "pi":
+            // Pi is a host-runtime harness with no vendor CLI to wrap: it runs only
+            // through the AI SDK harness session backend, which ignores this argv
+            // (exactly as the harness path ignores the claude-code argv). The argv
+            // is a non-spawnable placeholder that exists only so the prepared
+            // execution has a stable shape to hash; the process backend refuses to
+            // spawn pi outright, so this command line is never executed.
+            return {
+                cmd: "pi",
+                args: ["--harness-only"]
+            };
+        case "mock":
+            return {
+                cmd: process.execPath,
+                args: [ctx.mockScriptPath, prompt]
+            };
+        case "command":
+            // The task itself is the harness: one governed shell command. Used by
+            // app-owned loops (AI SDK adapter) and the compute adapter.
+            return {
+                cmd: "sh",
+                args: ["-c", prompt]
+            };
+        default: {
+            const exhausted = kind;
+            throw new Error(`unsupported agent kind: ${String(exhausted)}`);
+        }
+    }
+}

package/dist/backend.d.ts

@@ -0,0 +1,32 @@
+import type { RunContract, RunEvent, SessionIsolation } from "@fusionkit/protocol";
+import type { BackendExecutionKind, PreparedExecution } from "./execution.js";
+/** Everything a backend needs to execute one governed session. */
+export type SessionExecution = {
+    contract: RunContract;
+    /** Materialized workspace on the runner host. */
+    repoDir: string;
+    secrets: {
+        name: string;
+        value: string;
+    }[];
+    /** The backend-ready invocation prepared once by the runner. */
+    execution: PreparedExecution;
+    emit: (event: RunEvent) => void;
+};
+export type SessionBackendResult = {
+    exitCode: number;
+    log: Buffer;
+};
+/**
+ * A session isolation backend. The runner owns workspace materialization,
+ * output collection, event flushing, and receipt signing; the backend owns
+ * only the execution boundary itself. The built-in backend is "process";
+ * stronger tiers (hermetic interpreter, microVMs) are injected so the
+ * runner kernel stays dependency-free.
+ */
+export type SessionBackend = {
+    readonly isolation: SessionIsolation;
+    /** Execution kinds this backend can execute. Undefined means all. */
+    supports?(kind: BackendExecutionKind, contract: RunContract): boolean;
+    execute(input: SessionExecution): Promise<SessionBackendResult>;
+};

package/dist/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/egress.d.ts

@@ -0,0 +1,34 @@
+export type EgressEvent = {
+    host: string;
+    decision: "allowed" | "blocked";
+};
+export type EgressProxy = {
+    port: number;
+    close(): Promise<void>;
+};
+/**
+ * Deny-by-default egress proxy for agent sessions. The session environment
+ * points HTTP(S)_PROXY at this proxy; CONNECT tunnels and absolute-form HTTP
+ * requests are allowed only for allowlisted hosts, and every decision is
+ * reported as a network event.
+ *
+ * Honest limitation (documented in the spec): this is process-level
+ * enforcement. A malicious binary can ignore proxy variables; container or
+ * microVM network namespaces close that gap and are the roadmap isolation
+ * modes (the hermetic and Vercel Sandbox backends already do). Every allowed
+ * and blocked attempt is still recorded.
+ *
+ * The proxy is intentionally implemented on Node's http primitives rather
+ * than a third-party proxy library: it is a security enforcement point, so
+ * its full behavior lives here, auditable, and does no more than allowlist
+ * checks plus pass-through.
+ */
+/**
+ * Parse a CONNECT authority (`host:port`) into host and port, handling
+ * bracketed IPv6 literals (`[2001:db8::1]:443`). Defaults to port 443.
+ */
+export declare function parseConnectAuthority(authority: string): {
+    host: string;
+    port: number;
+};
+export declare function startEgressProxy(allowHosts: string[], defaultDeny: boolean, onEvent: (event: EgressEvent) => void): Promise<EgressProxy>;

package/dist/egress.js

@@ -0,0 +1,110 @@
+import { createServer, request as httpRequest } from "node:http";
+import { connect as netConnect } from "node:net";
+/**
+ * Deny-by-default egress proxy for agent sessions. The session environment
+ * points HTTP(S)_PROXY at this proxy; CONNECT tunnels and absolute-form HTTP
+ * requests are allowed only for allowlisted hosts, and every decision is
+ * reported as a network event.
+ *
+ * Honest limitation (documented in the spec): this is process-level
+ * enforcement. A malicious binary can ignore proxy variables; container or
+ * microVM network namespaces close that gap and are the roadmap isolation
+ * modes (the hermetic and Vercel Sandbox backends already do). Every allowed
+ * and blocked attempt is still recorded.
+ *
+ * The proxy is intentionally implemented on Node's http primitives rather
+ * than a third-party proxy library: it is a security enforcement point, so
+ * its full behavior lives here, auditable, and does no more than allowlist
+ * checks plus pass-through.
+ */
+/**
+ * Parse a CONNECT authority (`host:port`) into host and port, handling
+ * bracketed IPv6 literals (`[2001:db8::1]:443`). Defaults to port 443.
+ */
+export function parseConnectAuthority(authority) {
+    const trimmed = authority.trim();
+    if (trimmed.startsWith("[")) {
+        const close = trimmed.indexOf("]");
+        if (close !== -1) {
+            const host = trimmed.slice(1, close);
+            const rest = trimmed.slice(close + 1);
+            const port = rest.startsWith(":") ? Number(rest.slice(1)) : 443;
+            return { host, port: Number.isFinite(port) ? port : 443 };
+        }
+    }
+    const lastColon = trimmed.lastIndexOf(":");
+    if (lastColon === -1)
+        return { host: trimmed, port: 443 };
+    const port = Number(trimmed.slice(lastColon + 1) || "443");
+    return {
+        host: trimmed.slice(0, lastColon),
+        port: Number.isFinite(port) ? port : 443
+    };
+}
+export function startEgressProxy(allowHosts, defaultDeny, onEvent) {
+    const allowed = new Set(allowHosts);
+    const isAllowed = (host) => !defaultDeny || allowed.has(host);
+    const server = createServer((req, res) => {
+        let host = "";
+        try {
+            host = new URL(req.url ?? "").hostname;
+        }
+        catch {
+            res.writeHead(400);
+            res.end("proxy requires absolute-form URLs");
+            return;
+        }
+        if (!isAllowed(host)) {
+            onEvent({ host, decision: "blocked" });
+            res.writeHead(403);
+            res.end("blocked by warrant egress policy");
+            return;
+        }
+        onEvent({ host, decision: "allowed" });
+        const target = new URL(req.url ?? "");
+        const upstream = httpRequest({
+            hostname: target.hostname,
+            port: target.port || 80,
+            path: `${target.pathname}${target.search}`,
+            method: req.method,
+            headers: req.headers
+        }, (upstreamRes) => {
+            res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+            upstreamRes.pipe(res);
+        });
+        upstream.on("error", () => {
+            res.writeHead(502);
+            res.end("upstream error");
+        });
+        req.pipe(upstream);
+    });
+    server.on("connect", (req, socket) => {
+        const { host, port } = parseConnectAuthority(req.url ?? "");
+        if (!host || !isAllowed(host)) {
+            onEvent({ host: host ?? "unknown", decision: "blocked" });
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        onEvent({ host, decision: "allowed" });
+        const upstream = netConnect(port, host, () => {
+            socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            upstream.pipe(socket);
+            socket.pipe(upstream);
+        });
+        upstream.on("error", () => socket.destroy());
+        socket.on("error", () => upstream.destroy());
+    });
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            resolve({
+                port,
+                close: () => new Promise((done) => {
+                    server.close(() => done());
+                })
+            });
+        });
+    });
+}

package/dist/execution.d.ts

@@ -0,0 +1,45 @@
+import { type ExecutionSpec, type RunContract } from "@fusionkit/protocol";
+export type PreparedExecution = {
+    kind: "argv";
+    cmd: string;
+    args: string[];
+    cwd: string;
+    timeoutMs: number;
+    logMaxBytes?: number;
+    env: Record<string, string>;
+    egressProxy: boolean;
+} | {
+    kind: "shell";
+    script: string;
+    shell: "sh" | "bash";
+    cwd: string;
+    timeoutMs: number;
+    logMaxBytes?: number;
+    env: Record<string, string>;
+    egressProxy: boolean;
+};
+export type BackendExecutionKind = PreparedExecution["kind"];
+export type PrepareExecutionInput = {
+    contract: RunContract;
+    mockScriptPath: string;
+};
+/** Session wall-clock ceiling when neither execution nor contract sets a timeout. */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/**
+ * Resolve a prepared execution env into the concrete session environment:
+ * released secrets are injected by name, `env.secrets` placeholders are
+ * substituted, and a placeholder whose secret was not released is omitted
+ * entirely (never leaked as a literal marker). Every backend uses this one
+ * resolution so the semantics cannot drift between isolation tiers.
+ */
+export declare function resolveSessionEnv(env: Record<string, string>, secrets: {
+    name: string;
+    value: string;
+}[]): Record<string, string>;
+/** The execution intent of a contract, whether explicit or defaulted. */
+export declare function executionSpecFor(contract: RunContract): ExecutionSpec;
+export declare function prepareExecution(input: PrepareExecutionInput): PreparedExecution;
+export declare function executionHash(execution: PreparedExecution): string;
+export declare function requireShellExecution(execution: PreparedExecution): Extract<PreparedExecution, {
+    kind: "shell";
+}>;

package/dist/execution.js

@@ -0,0 +1,147 @@
+import { defaultExecutionSpec, hashCanonical } from "@fusionkit/protocol";
+import { buildAgentCommand } from "./agents.js";
+/** Session wall-clock ceiling when neither execution nor contract sets a timeout. */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Marker the runner writes into the prepared env for `env.secrets` mappings;
+ * backends resolve it against the released secrets via `resolveSessionEnv`.
+ * The value never reaches the session: it is replaced (or dropped) before
+ * any process, interpreter, or sandbox sees the environment.
+ */
+const SECRET_PLACEHOLDER_PREFIX = "__WARRANT_SECRET__:";
+/**
+ * Resolve a prepared execution env into the concrete session environment:
+ * released secrets are injected by name, `env.secrets` placeholders are
+ * substituted, and a placeholder whose secret was not released is omitted
+ * entirely (never leaked as a literal marker). Every backend uses this one
+ * resolution so the semantics cannot drift between isolation tiers.
+ */
+export function resolveSessionEnv(env, secrets) {
+    const resolved = {};
+    for (const secret of secrets)
+        resolved[secret.name] = secret.value;
+    for (const [key, value] of Object.entries(env)) {
+        if (value.startsWith(SECRET_PLACEHOLDER_PREFIX)) {
+            const secretName = value.slice(SECRET_PLACEHOLDER_PREFIX.length);
+            const secret = secrets.find((item) => item.name === secretName);
+            if (secret)
+                resolved[key] = secret.value;
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/** The execution intent of a contract, whether explicit or defaulted. */
+export function executionSpecFor(contract) {
+    return contract.execution ?? defaultExecutionSpec(contract.agent, contract.task.prompt);
+}
+function timeoutMsFor(contract, spec) {
+    if (spec.timeoutMs !== undefined)
+        return spec.timeoutMs;
+    if (contract.budget.maxDurationMin !== undefined) {
+        return contract.budget.maxDurationMin * 60 * 1000;
+    }
+    return DEFAULT_TIMEOUT_MS;
+}
+function cwdFor(spec) {
+    return spec.kind === "agent" ? "." : spec.cwd ?? ".";
+}
+function envFor(spec) {
+    const policy = spec.env;
+    const env = {};
+    for (const key of policy?.inherit ?? []) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    Object.assign(env, policy?.vars ?? {});
+    for (const secret of policy?.secrets ?? []) {
+        env[secret.env] = `${SECRET_PLACEHOLDER_PREFIX}${secret.secretName}`;
+    }
+    return { env, egressProxy: policy?.egressProxy ?? true };
+}
+function logMaxBytesFor(spec) {
+    return spec.log?.maxBytes;
+}
+function prepareAgentExecution(spec, ctx, contract) {
+    const command = buildAgentCommand(spec.agent.kind, spec.prompt, ctx);
+    const { env, egressProxy } = envFor(spec);
+    return {
+        kind: "argv",
+        cmd: command.cmd,
+        args: command.args,
+        cwd: cwdFor(spec),
+        timeoutMs: timeoutMsFor(contract, spec),
+        logMaxBytes: logMaxBytesFor(spec),
+        env,
+        egressProxy
+    };
+}
+export function prepareExecution(input) {
+    const { contract, mockScriptPath } = input;
+    const spec = executionSpecFor(contract);
+    switch (spec.kind) {
+        case "agent":
+            return prepareAgentExecution(spec, { mockScriptPath }, contract);
+        case "argv": {
+            const { env, egressProxy } = envFor(spec);
+            return {
+                kind: "argv",
+                cmd: spec.command,
+                args: spec.args,
+                cwd: cwdFor(spec),
+                timeoutMs: timeoutMsFor(contract, spec),
+                logMaxBytes: logMaxBytesFor(spec),
+                env,
+                egressProxy
+            };
+        }
+        case "shell": {
+            const { env, egressProxy } = envFor(spec);
+            return {
+                kind: "shell",
+                script: spec.script,
+                shell: spec.shell ?? "sh",
+                cwd: cwdFor(spec),
+                timeoutMs: timeoutMsFor(contract, spec),
+                logMaxBytes: logMaxBytesFor(spec),
+                env,
+                egressProxy
+            };
+        }
+        default: {
+            const exhausted = spec;
+            throw new Error(`unsupported execution spec: ${String(exhausted)}`);
+        }
+    }
+}
+export function executionHash(execution) {
+    switch (execution.kind) {
+        case "argv":
+            return hashCanonical({
+                kind: "argv",
+                cmd: execution.cmd,
+                args: execution.args,
+                cwd: execution.cwd
+            });
+        case "shell":
+            return hashCanonical({
+                kind: "shell",
+                shell: execution.shell,
+                script: execution.script,
+                cwd: execution.cwd
+            });
+        default: {
+            const exhausted = execution;
+            throw new Error(`unsupported prepared execution: ${String(exhausted)}`);
+        }
+    }
+}
+export function requireShellExecution(execution) {
+    if (execution.kind !== "shell") {
+        throw new Error(`expected shell execution, got ${execution.kind}`);
+    }
+    return execution;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fusionkit/runner — outbound-only runner: claims signed contracts,
+ * materializes workspaces, runs vendor agent harnesses inside governed
+ * sessions, and signs receipts.
+ *
+ * The public surface is deliberately small: the Runner itself, the
+ * SessionBackend seam that isolation tiers implement, and the execution
+ * helpers those backends share. Everything else is runner-internal.
+ */
+export { Runner } from "./runner.js";
+export { CapabilityMismatchError } from "./session.js";
+export type { SessionBackend, SessionBackendResult, SessionExecution } from "./backend.js";
+export { executionHash, executionSpecFor, prepareExecution, requireShellExecution, resolveSessionEnv } from "./execution.js";
+export type { BackendExecutionKind } from "./execution.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fusionkit/runner — outbound-only runner: claims signed contracts,
+ * materializes workspaces, runs vendor agent harnesses inside governed
+ * sessions, and signs receipts.
+ *
+ * The public surface is deliberately small: the Runner itself, the
+ * SessionBackend seam that isolation tiers implement, and the execution
+ * helpers those backends share. Everything else is runner-internal.
+ */
+export { Runner } from "./runner.js";
+export { CapabilityMismatchError } from "./session.js";
+export { executionHash, executionSpecFor, prepareExecution, requireShellExecution, resolveSessionEnv } from "./execution.js";

package/dist/mock-agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mock-agent.js

@@ -0,0 +1,53 @@
+/**
+ * Built-in mock agent used for tests and demos without vendor CLIs or
+ * API keys. It behaves like a tiny coding agent:
+ *
+ * - appends its task to MOCK_AGENT.md in the workspace
+ * - reports whether the MOCK_SECRET env var was injected (never its value)
+ * - when the task mentions "network", attempts an egress call through the
+ *   session proxy so governed network enforcement can be observed
+ * - exits non-zero when the task mentions "fail"
+ */
+import { appendFileSync } from "node:fs";
+import { request } from "node:http";
+// A host that is never on any test/demo allowlist, so the probe deterministically
+// exercises deny-by-default egress. Override with MOCK_PROBE_HOST if needed.
+const PROBE_HOST = process.env.MOCK_PROBE_HOST ?? "denied.example.com";
+const prompt = process.argv[2] ?? "";
+appendFileSync("MOCK_AGENT.md", `## task\n${prompt}\n\nsecret:${process.env.MOCK_SECRET ? "present" : "absent"}\n`);
+function tryNetwork() {
+    const proxy = process.env.HTTP_PROXY;
+    if (!proxy)
+        return Promise.resolve();
+    const proxyUrl = new URL(proxy);
+    return new Promise((resolve) => {
+        const req = request({
+            hostname: proxyUrl.hostname,
+            port: Number(proxyUrl.port),
+            path: `http://${PROBE_HOST}/probe`,
+            method: "GET",
+            headers: { host: PROBE_HOST }
+        }, (res) => {
+            console.log(`network probe status: ${res.statusCode}`);
+            res.resume();
+            res.on("end", resolve);
+        });
+        req.on("error", () => {
+            console.log("network probe failed to reach proxy");
+            resolve();
+        });
+        req.end();
+    });
+}
+async function main() {
+    console.log(`mock agent received task: ${prompt}`);
+    if (prompt.includes("network")) {
+        await tryNetwork();
+    }
+    if (prompt.includes("fail")) {
+        console.error("mock agent failing as instructed");
+        process.exit(1);
+    }
+    console.log("mock agent done");
+}
+void main();

package/dist/process-backend.d.ts

@@ -0,0 +1,17 @@
+import type { SessionBackend, SessionBackendResult, SessionExecution } from "./backend.js";
+import type { BackendExecutionKind } from "./execution.js";
+/**
+ * The built-in backend: the harness runs as a child process with a
+ * scrubbed environment, injected secrets, and deny-by-default egress
+ * through the session proxy.
+ *
+ * Honest limitation (documented in the spec): this is process-level
+ * enforcement. A malicious binary can ignore proxy variables; the
+ * hermetic and microVM backends close that gap. Every allowed and
+ * blocked attempt is still recorded.
+ */
+export declare class ProcessSessionBackend implements SessionBackend {
+    readonly isolation: "process";
+    supports(_kind: BackendExecutionKind, contract: SessionExecution["contract"]): boolean;
+    execute(input: SessionExecution): Promise<SessionBackendResult>;
+}

package/dist/process-backend.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { resolveInsideWorkspace } from "@fusionkit/workspace";
+import { startEgressProxy } from "./egress.js";
+import { executionHash, resolveSessionEnv } from "./execution.js";
+/** Minimal PATH/HOME used only when the host process has none set. */
+const FALLBACK_PATH = "/usr/bin:/bin";
+const FALLBACK_HOME = "/tmp";
+/** Exit code reported when the harness binary cannot be spawned. */
+const SPAWN_ERROR_EXIT_CODE = 127;
+/**
+ * The built-in backend: the harness runs as a child process with a
+ * scrubbed environment, injected secrets, and deny-by-default egress
+ * through the session proxy.
+ *
+ * Honest limitation (documented in the spec): this is process-level
+ * enforcement. A malicious binary can ignore proxy variables; the
+ * hermetic and microVM backends close that gap. Every allowed and
+ * blocked attempt is still recorded.
+ */
+export class ProcessSessionBackend {
+    isolation = "process";
+    supports(_kind, contract) {
+        // Pi is a host-runtime harness with no vendor CLI: it runs only through
+        // the AI SDK harness backend, never as a spawned process. Refusing it
+        // here is the single enforcement point for "pi never runs as a process",
+        // so a runner that lacks a pi harness backend fails closed instead of
+        // trying to spawn the placeholder command.
+        return contract.agent.kind !== "pi";
+    }
+    async execute(input) {
+        const { contract, repoDir, secrets, execution, emit } = input;
+        const proxy = execution.egressProxy
+            ? await startEgressProxy(contract.network.allowHosts, contract.network.defaultDeny, ({ host, decision }) => emit({ type: "network.connected", host, decision }))
+            : undefined;
+        const env = {
+            PATH: process.env.PATH ?? FALLBACK_PATH,
+            HOME: process.env.HOME ?? FALLBACK_HOME
+        };
+        if (proxy) {
+            env.HTTP_PROXY = `http://127.0.0.1:${proxy.port}`;
+            env.HTTPS_PROXY = `http://127.0.0.1:${proxy.port}`;
+            env.http_proxy = `http://127.0.0.1:${proxy.port}`;
+            env.https_proxy = `http://127.0.0.1:${proxy.port}`;
+        }
+        Object.assign(env, resolveSessionEnv(execution.env, secrets));
+        const { cmd, args } = execution.kind === "argv"
+            ? { cmd: execution.cmd, args: execution.args }
+            : { cmd: execution.shell, args: ["-c", execution.script] };
+        const cwd = resolveInsideWorkspace(repoDir, execution.cwd);
+        const chunks = [];
+        let capturedBytes = 0;
+        const exitCode = await new Promise((resolve) => {
+            const child = spawn(cmd, args, { cwd, env });
+            const push = (chunk) => {
+                chunks.push(chunk);
+                capturedBytes += chunk.byteLength;
+                if (execution.logMaxBytes !== undefined && capturedBytes > execution.logMaxBytes) {
+                    child.kill("SIGKILL");
+                }
+            };
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+            }, execution.timeoutMs);
+            child.stdout.on("data", push);
+            child.stderr.on("data", push);
+            child.on("error", (error) => {
+                chunks.push(Buffer.from(`spawn error: ${error.message}\n`, "utf8"));
+                clearTimeout(timer);
+                // 127 is the conventional shell exit code for "command not found".
+                resolve(SPAWN_ERROR_EXIT_CODE);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                resolve(code ?? 1);
+            });
+        });
+        await proxy?.close();
+        emit({
+            type: "command.executed",
+            argvHash: executionHash(execution),
+            exitCode
+        });
+        return { exitCode, log: Buffer.concat(chunks) };
+    }
+}

package/dist/runner.d.ts

@@ -0,0 +1,55 @@
+import type { SessionBackend } from "./backend.js";
+export type RunnerOptions = {
+    planeUrl: string;
+    pool: string;
+    dataDir: string;
+    enrollToken?: string;
+    pollIntervalMs?: number;
+    mockScriptPath?: string;
+    /** How long to keep retrying enrollment while the plane is unreachable. */
+    enrollRetryMs?: number;
+    /**
+     * Session isolation backends beyond the built-in "process" backend
+     * (e.g. hermetic interpreter or microVM). Injected so the runner kernel
+     * stays dependency-free.
+     */
+    backends?: SessionBackend[];
+    /**
+     * How many claimed runs this runner executes at the same time.
+     * Defaults to 1, which preserves the strictly sequential claim loop.
+     * Each execution already owns all of its state (event chain, temp
+     * session dir), so concurrency is purely a claim-loop property — this
+     * is the single knob for one runner host; scale-out across hosts is
+     * more enrolled runners in the pool.
+     */
+    concurrency?: number;
+};
+type StoredIdentity = {
+    runnerId: string;
+    runnerToken: string;
+    pool: string;
+};
+export declare class Runner {
+    private readonly options;
+    private readonly client;
+    private identity?;
+    private publicKeyPem;
+    private privateKeyPem;
+    private stopped;
+    constructor(options: RunnerOptions);
+    ensureEnrolled(): Promise<StoredIdentity>;
+    /**
+     * Enroll against the plane, retrying while it is unreachable. Runners
+     * routinely start before the plane in container deployments; a transport
+     * failure here is a startup-ordering problem, not a fatal one. An invalid
+     * enroll token is rejected by the plane with a response and never retried.
+     */
+    private enrollWithRetry;
+    /** Poll once; execute at most one claimed run. Returns the run id if work was done. */
+    runOnce(): Promise<string | undefined>;
+    start(): Promise<void>;
+    stop(): void;
+    private execute;
+    private buildReceipt;
+}
+export {};

package/dist/runner.js

@@ -0,0 +1,308 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { appendEvent, contractHash, generateEd25519KeyPair, hashCanonical, keyIdFromPublicPem, signReceipt } from "@fusionkit/protocol";
+import { PlaneClient } from "@fusionkit/sdk";
+import { materializeWorkspace } from "@fusionkit/workspace";
+import { runSession } from "./session.js";
+/** Default time budget for enrollment retries while the plane is unreachable. */
+const DEFAULT_ENROLL_RETRY_MS = 60_000;
+/** Wait between enrollment retry attempts. */
+const ENROLL_RETRY_INTERVAL_MS = 2_000;
+/** Default idle poll interval between claim attempts. */
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+/** Attestation tier reported by this software runner: honestly "mock". */
+const RUNNER_ATTESTATION_TIER = "mock";
+const DEFAULT_MOCK_SCRIPT = fileURLToPath(new URL("./mock-agent.js", import.meta.url));
+const REDACTED_SECRET_PREFIX = "[REDACTED:";
+function redactSecrets(buffer, secrets) {
+    let text = buffer.toString("utf8");
+    for (const secret of secrets) {
+        if (secret.value.length === 0)
+            continue;
+        text = text.split(secret.value).join(`${REDACTED_SECRET_PREFIX}${secret.name}]`);
+    }
+    return Buffer.from(text, "utf8");
+}
+export class Runner {
+    options;
+    client;
+    identity;
+    publicKeyPem = "";
+    privateKeyPem = "";
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+        this.client = new PlaneClient(options.planeUrl);
+    }
+    async ensureEnrolled() {
+        if (this.identity)
+            return this.identity;
+        const dir = this.options.dataDir;
+        mkdirSync(dir, { recursive: true });
+        const identityPath = join(dir, "identity.json");
+        const pubPath = join(dir, "runner.pub.pem");
+        const keyPath = join(dir, "runner.key.pem");
+        if (existsSync(identityPath) && existsSync(pubPath) && existsSync(keyPath)) {
+            this.identity = JSON.parse(readFileSync(identityPath, "utf8"));
+            this.publicKeyPem = readFileSync(pubPath, "utf8");
+            this.privateKeyPem = readFileSync(keyPath, "utf8");
+            return this.identity;
+        }
+        if (!this.options.enrollToken) {
+            throw new Error("runner is not enrolled and no enroll token was provided");
+        }
+        const keys = generateEd25519KeyPair();
+        const enrolled = await this.enrollWithRetry(keys.publicKeyPem);
+        const identity = {
+            runnerId: enrolled.runnerId,
+            runnerToken: enrolled.runnerToken,
+            pool: this.options.pool
+        };
+        writeFileSync(identityPath, JSON.stringify(identity, null, 2), {
+            mode: 0o600
+        });
+        writeFileSync(pubPath, keys.publicKeyPem, { mode: 0o600 });
+        writeFileSync(keyPath, keys.privateKeyPem, { mode: 0o600 });
+        this.identity = identity;
+        this.publicKeyPem = keys.publicKeyPem;
+        this.privateKeyPem = keys.privateKeyPem;
+        return identity;
+    }
+    /**
+     * Enroll against the plane, retrying while it is unreachable. Runners
+     * routinely start before the plane in container deployments; a transport
+     * failure here is a startup-ordering problem, not a fatal one. An invalid
+     * enroll token is rejected by the plane with a response and never retried.
+     */
+    async enrollWithRetry(publicKeyPem) {
+        const deadline = Date.now() + (this.options.enrollRetryMs ?? DEFAULT_ENROLL_RETRY_MS);
+        const enrollToken = this.options.enrollToken;
+        if (!enrollToken)
+            throw new Error("no enroll token was provided");
+        for (;;) {
+            try {
+                return await this.client.enroll({
+                    enrollToken,
+                    publicKeyPem,
+                    pool: this.options.pool
+                });
+            }
+            catch (error) {
+                const transport = error instanceof TypeError;
+                if (!transport || Date.now() >= deadline)
+                    throw error;
+                console.error(`plane not reachable at ${this.options.planeUrl}; retrying enrollment...`);
+                await new Promise((resolve) => setTimeout(resolve, ENROLL_RETRY_INTERVAL_MS));
+            }
+        }
+    }
+    /** Poll once; execute at most one claimed run. Returns the run id if work was done. */
+    async runOnce() {
+        const identity = await this.ensureEnrolled();
+        const claim = await this.client.claim({
+            runnerToken: identity.runnerToken,
+            pool: identity.pool
+        });
+        if ("empty" in claim)
+            return undefined;
+        await this.execute(claim);
+        return claim.runId;
+    }
+    async start() {
+        this.stopped = false;
+        const interval = this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const concurrency = Math.max(1, Math.floor(this.options.concurrency ?? 1));
+        const inFlight = new Set();
+        const sleep = () => new Promise((resolve) => setTimeout(resolve, interval));
+        while (!this.stopped) {
+            if (inFlight.size >= concurrency) {
+                // At capacity: wait for any execution to settle before claiming
+                // again. The executions never reject (errors are caught below).
+                await Promise.race(inFlight);
+                continue;
+            }
+            try {
+                const identity = await this.ensureEnrolled();
+                const claim = await this.client.claim({
+                    runnerToken: identity.runnerToken,
+                    pool: identity.pool
+                });
+                if ("empty" in claim) {
+                    await sleep();
+                    continue;
+                }
+                const task = this.execute(claim)
+                    .catch((error) => {
+                    console.error(`runner error: ${error instanceof Error ? error.message : String(error)}`);
+                })
+                    .finally(() => {
+                    inFlight.delete(task);
+                });
+                inFlight.add(task);
+            }
+            catch (error) {
+                console.error(`runner error: ${error instanceof Error ? error.message : String(error)}`);
+                await sleep();
+            }
+        }
+        // stop() interrupts claiming, not execution: drain what was claimed so
+        // every accepted run still ends in a posted receipt.
+        await Promise.all(inFlight);
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async execute(claim) {
+        const { contract, claimToken, runId } = claim;
+        const genesis = contractHash(contract);
+        const chain = [...claim.events];
+        let flushedThrough = chain.length;
+        const emitLocal = (event) => appendEvent(chain, event, genesis);
+        const flush = async () => {
+            const pending = chain.slice(flushedThrough);
+            if (pending.length === 0)
+                return;
+            await this.client.postEvents(runId, claimToken, pending);
+            flushedThrough = chain.length;
+        };
+        const sessionDir = mkdtempSync(join(tmpdir(), "warrant-session-"));
+        try {
+            const repoDir = await materializeWorkspace(sessionDir, contract.workspace, (hash) => this.client.getBlob(hash));
+            const manifestHash = hashCanonical(contract.workspace);
+            emitLocal({ type: "workspace.materialized", manifestHash });
+            await flush();
+            const session = await runSession({
+                contract,
+                repoDir,
+                secrets: claim.secrets,
+                mockScriptPath: this.options.mockScriptPath ?? DEFAULT_MOCK_SCRIPT,
+                emit: (event) => void emitLocal(event),
+                backends: this.options.backends ?? []
+            });
+            const artifactHashes = [];
+            let diffHash = "";
+            const diff = redactSecrets(session.output.diff, claim.secrets);
+            const log = redactSecrets(session.log, claim.secrets);
+            if (diff.length > 0) {
+                diffHash = await this.client.putBlob(diff, claimToken);
+                emitLocal({ type: "artifact.created", kind: "diff", hash: diffHash });
+                emitLocal({
+                    type: "boundary.crossed",
+                    direction: "out",
+                    contentHash: diffHash,
+                    dataClass: "code-diff"
+                });
+                artifactHashes.push(diffHash);
+            }
+            if (log.length > 0) {
+                const logHash = await this.client.putBlob(log, claimToken);
+                emitLocal({ type: "artifact.created", kind: "log", hash: logHash });
+                emitLocal({
+                    type: "boundary.crossed",
+                    direction: "out",
+                    contentHash: logHash,
+                    dataClass: "session-log"
+                });
+                artifactHashes.push(logHash);
+            }
+            if (session.exitCode === 0) {
+                emitLocal({ type: "run.completed" });
+            }
+            else {
+                emitLocal({
+                    type: "run.failed",
+                    failure: "session_failed",
+                    message: `agent exited with code ${session.exitCode}`
+                });
+            }
+            await flush();
+            const receipt = this.buildReceipt({
+                runId,
+                contract,
+                chain,
+                genesis,
+                manifestHash,
+                diffHash,
+                artifactHashes,
+                isolation: session.isolation,
+                status: session.exitCode === 0 ? "completed" : "failed"
+            });
+            await this.client.complete(runId, claimToken, receipt);
+        }
+        finally {
+            rmSync(sessionDir, { recursive: true, force: true });
+        }
+    }
+    buildReceipt(input) {
+        const identity = this.identity;
+        if (!identity)
+            throw new Error("runner identity missing");
+        const { chain } = input;
+        const head = chain[chain.length - 1];
+        if (!head)
+            throw new Error("event chain is empty");
+        const secretsReleased = chain
+            .filter((e) => e.event.type === "secret.released")
+            .map((e) => e.event.type === "secret.released"
+            ? { name: e.event.name, scope: e.event.scope, ts: e.ts }
+            : { name: "", scope: "", ts: "" });
+        // Dedupe distinct (host, decision) pairs without string-packing the key,
+        // so hosts containing ":" (IPv6 literals) are handled correctly.
+        const networkSeen = new Map();
+        for (const entry of chain) {
+            if (entry.event.type === "network.connected") {
+                const decisions = networkSeen.get(entry.event.host) ?? new Set();
+                decisions.add(entry.event.decision);
+                networkSeen.set(entry.event.host, decisions);
+            }
+        }
+        const networkAccessed = [...networkSeen.entries()].flatMap(([host, decisions]) => [...decisions].map((decision) => ({ host, decision })));
+        const boundaryDisclosures = chain
+            .filter((e) => e.event.type === "boundary.crossed")
+            .map((e) => e.event.type === "boundary.crossed"
+            ? {
+                direction: e.event.direction,
+                contentHash: e.event.contentHash,
+                dataClass: e.event.dataClass
+            }
+            : { direction: "out", contentHash: "", dataClass: "" });
+        const runnerIdentity = {
+            runnerId: identity.runnerId,
+            keyId: keyIdFromPublicPem(this.publicKeyPem),
+            pool: identity.pool,
+            // Honest labeling: a software runner offers no hardware attestation,
+            // so the tier is "mock" until a TEE-backed runner reports otherwise.
+            attestationTier: RUNNER_ATTESTATION_TIER,
+            isolation: input.isolation
+        };
+        const first = chain[0];
+        const unsigned = {
+            version: "warrant.receipt.v1",
+            runId: input.runId,
+            contractHash: input.genesis,
+            runner: runnerIdentity,
+            startedAt: first ? first.ts : head.ts,
+            endedAt: head.ts,
+            status: input.status,
+            eventsHead: head.hash,
+            eventCount: chain.length,
+            workspaceIn: {
+                baseRef: input.contract.workspace.baseRef,
+                manifestHash: input.manifestHash
+            },
+            workspaceOut: {
+                diffHash: input.diffHash,
+                artifactHashes: input.artifactHashes
+            },
+            secretsReleased,
+            networkAccessed,
+            modelsUsed: [],
+            boundaryDisclosures,
+            signatures: []
+        };
+        return signReceipt(unsigned, this.privateKeyPem, this.publicKeyPem, "runner");
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,31 @@
+import type { RunContract, RunEvent, SessionIsolation } from "@fusionkit/protocol";
+import type { WorkspaceOutput } from "@fusionkit/workspace";
+import type { SessionBackend } from "./backend.js";
+export type SessionResult = {
+    exitCode: number;
+    log: Buffer;
+    output: WorkspaceOutput;
+    isolation: SessionIsolation;
+};
+/**
+ * Run the agent harness inside a governed session. The runner owns the
+ * boundary plumbing (workspace materialization, output capture, events);
+ * the selected backend owns only how the harness is isolated. An event is
+ * emitted for every observable boundary action regardless of backend.
+ */
+export declare function runSession(input: {
+    contract: RunContract;
+    repoDir: string;
+    secrets: {
+        name: string;
+        value: string;
+    }[];
+    mockScriptPath: string;
+    emit: (event: RunEvent) => void;
+    backends: SessionBackend[];
+}): Promise<SessionResult>;
+/** A requested isolation tier or agent is not available on this runner. */
+export declare class CapabilityMismatchError extends Error {
+    readonly code: "capability_mismatch";
+    constructor(message: string);
+}

package/dist/session.js

@@ -0,0 +1,54 @@
+import { collectOutput } from "@fusionkit/workspace";
+import { prepareExecution } from "./execution.js";
+import { ProcessSessionBackend } from "./process-backend.js";
+/**
+ * Run the agent harness inside a governed session. The runner owns the
+ * boundary plumbing (workspace materialization, output capture, events);
+ * the selected backend owns only how the harness is isolated. An event is
+ * emitted for every observable boundary action regardless of backend.
+ */
+export async function runSession(input) {
+    const { contract, repoDir, secrets, mockScriptPath, emit, backends } = input;
+    const requested = contract.isolation ?? "process";
+    const matching = backends.filter((b) => b.isolation === requested);
+    if (matching.length > 1) {
+        // Fail fast instead of silently letting the first registration shadow
+        // the rest: composite backends (e.g. the AI SDK harness driver, which
+        // embeds the plain vercel-sandbox backend as its fallback) are the one
+        // sanctioned way to combine behaviors within a tier.
+        throw new CapabilityMismatchError(`runner has ${matching.length} backends for isolation "${requested}"; register exactly one per tier`);
+    }
+    const backend = matching[0] ?? (requested === "process" ? new ProcessSessionBackend() : undefined);
+    if (!backend) {
+        throw new CapabilityMismatchError(`runner has no backend for isolation "${requested}"`);
+    }
+    const execution = prepareExecution({ contract, mockScriptPath });
+    if (backend.supports && !backend.supports(execution.kind, contract)) {
+        throw new CapabilityMismatchError(`backend "${requested}" cannot run ${execution.kind} execution for agent "${contract.agent.kind}"`);
+    }
+    const result = await backend.execute({
+        contract,
+        repoDir,
+        secrets,
+        execution,
+        emit
+    });
+    const output = collectOutput(repoDir, contract.workspace.baseRef);
+    for (const file of output.changedFiles) {
+        emit({ type: "file.changed", path: file.path, contentHash: file.contentHash });
+    }
+    return {
+        exitCode: result.exitCode,
+        log: result.log,
+        output,
+        isolation: backend.isolation
+    };
+}
+/** A requested isolation tier or agent is not available on this runner. */
+export class CapabilityMismatchError extends Error {
+    code = "capability_mismatch";
+    constructor(message) {
+        super(message);
+        this.name = "CapabilityMismatchError";
+    }
+}

package/dist/test/execution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/execution.test.js

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { executionSpecFor, executionHash, prepareExecution, requireShellExecution } from "../execution.js";
+import { ProcessSessionBackend } from "../process-backend.js";
+function contractFixture(overrides = {}) {
+    const contract = {
+        version: "warrant.contract.v1",
+        runId: "run_test",
+        issuedAt: "2026-06-11T00:00:00.000Z",
+        issuer: { keyId: "ed25519:0000000000000000", role: "plane" },
+        requestedBy: { kind: "human", id: "alice" },
+        agent: { kind: "command" },
+        task: { prompt: "echo hi" },
+        runner: { pool: "default" },
+        workspace: {
+            version: "warrant.manifest.v1",
+            baseRef: "abc",
+            bundleHash: "1".repeat(64),
+            untrackedFiles: [],
+            deniedPatterns: [],
+            deniedPaths: []
+        },
+        policyHash: "2".repeat(64),
+        secrets: [],
+        network: { defaultDeny: true, allowHosts: [] },
+        budget: {},
+        disclosure: "minimal-context",
+        expiresAt: "2026-06-11T01:00:00.000Z",
+        signatures: [],
+        ...overrides
+    };
+    return contract;
+}
+test("command contracts default to explicit shell execution", () => {
+    const contract = contractFixture();
+    assert.deepEqual(executionSpecFor(contract), {
+        kind: "shell",
+        script: "echo hi"
+    });
+    const execution = prepareExecution({
+        contract,
+        mockScriptPath: "/tmp/mock-agent.js"
+    });
+    const shell = requireShellExecution(execution);
+    assert.equal(shell.script, "echo hi");
+    assert.equal(shell.shell, "sh");
+    assert.equal(shell.timeoutMs, 10 * 60 * 1000);
+});
+test("agent executions prepare vendor argv without shell wrapping", () => {
+    const contract = contractFixture({
+        agent: { kind: "mock" },
+        task: { prompt: "do work" },
+        execution: { kind: "agent", agent: { kind: "mock" }, prompt: "do work" }
+    });
+    const execution = prepareExecution({
+        contract,
+        mockScriptPath: "/tmp/mock-agent.js"
+    });
+    assert.equal(execution.kind, "argv");
+    if (execution.kind === "argv") {
+        assert.equal(execution.cmd, process.execPath);
+        assert.deepEqual(execution.args, ["/tmp/mock-agent.js", "do work"]);
+    }
+});
+test("pi prepares a non-spawnable placeholder argv (harness-only)", () => {
+    // The harness backend needs a prepared execution (env, timeout, hash) just
+    // like claude-code, and ignores the argv. Preparation must therefore
+    // succeed; the placeholder argv exists only to hash. The process backend
+    // (tested separately) is what refuses to spawn pi.
+    const contract = contractFixture({
+        agent: { kind: "pi" },
+        task: { prompt: "fix the bug" },
+        execution: { kind: "agent", agent: { kind: "pi" }, prompt: "fix the bug" }
+    });
+    const execution = prepareExecution({ contract, mockScriptPath: "/tmp/mock-agent.js" });
+    assert.equal(execution.kind, "argv");
+    assert.match(executionHash(execution), /^[0-9a-f]{64}$/);
+});
+test("the process backend refuses to spawn pi", () => {
+    const backend = new ProcessSessionBackend();
+    const piContract = contractFixture({
+        agent: { kind: "pi" },
+        execution: { kind: "agent", agent: { kind: "pi" }, prompt: "fix the bug" }
+    });
+    const commandContract = contractFixture();
+    assert.equal(backend.supports?.("argv", piContract), false);
+    assert.equal(backend.supports?.("shell", commandContract), true);
+});
+test("executionHash records the prepared execution shape", () => {
+    const shell = prepareExecution({
+        contract: contractFixture({ execution: { kind: "shell", script: "echo hi" } }),
+        mockScriptPath: "/tmp/mock-agent.js"
+    });
+    const argv = prepareExecution({
+        contract: contractFixture({
+            execution: { kind: "argv", command: "echo", args: ["hi"] }
+        }),
+        mockScriptPath: "/tmp/mock-agent.js"
+    });
+    assert.notEqual(executionHash(shell), executionHash(argv));
+    assert.match(executionHash(shell), /^[0-9a-f]{64}$/);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fusionkit/runner",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/runner"
+  },
+  "description": "Warrant runner: outbound-only execution of vendor agent harnesses inside governed sessions with deny-by-default egress.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@fusionkit/protocol": "0.1.0",
+    "@fusionkit/workspace": "0.1.0",
+    "@fusionkit/sdk": "0.1.0"
+  }
+}