@fusionkit/session-harness 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Fail-closed mapping from a governed session's resolved environment (the
+ * contract's env policy plus broker-released secrets) onto the explicit
+ * auth settings of the `@ai-sdk/harness-claude-code` adapter.
+ *
+ * The adapter's default behavior resolves credentials from the *host*
+ * process environment — which on a Warrant runner would bypass the secret
+ * broker entirely (the runner operator's own ANTHROPIC_API_KEY would leak
+ * into the session). This module therefore always constructs an explicit
+ * auth object, and fills unset credential fields with empty strings: the
+ * adapter treats "" as present-but-falsy, so it neither falls back to the
+ * host environment nor exports the variable into the bridge.
+ */
+import type { ClaudeCodeAuthOptions } from "@ai-sdk/harness-claude-code";
+import type { PiAuthOptions } from "@ai-sdk/harness-pi";
+/**
+ * Build the explicit claude-code auth settings from the session env.
+ *
+ * Fails closed when the env carries variables this path cannot deliver to
+ * the agent runtime, and when no credential is present at all (the adapter
+ * would otherwise fall back to the runner host's own credentials).
+ */
+export declare function claudeCodeAuthFromEnv(env: Record<string, string>): ClaudeCodeAuthOptions;
+/**
+ * Build explicit Pi auth from the session env, fail-closed.
+ *
+ * Pi's default resolution reaches into the *host* process environment for an
+ * AI Gateway key or `VERCEL_OIDC_TOKEN`. On a Warrant runner that would
+ * bypass the secret broker, so this always passes an explicit `customEnv`
+ * built only from broker-released vars. It fails closed when the env carries
+ * a variable Pi cannot honor, and when no provider key is present at all
+ * (otherwise Pi would fall back to the host environment).
+ */
+export declare function piAuthFromEnv(env: Record<string, string>): PiAuthOptions;

package/dist/auth.js

@@ -0,0 +1,119 @@
+import { CapabilityMismatchError } from "@fusionkit/runner";
+/**
+ * The only environment variables this harness path can honor: the adapter
+ * forwards exactly these to the in-sandbox bridge. Pinned here so anything
+ * else in the contract's env policy fails closed instead of being silently
+ * dropped.
+ */
+const SUPPORTED_AUTH_VARS = [
+    "AI_GATEWAY_API_KEY",
+    "AI_GATEWAY_BASE_URL",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL"
+];
+/**
+ * The adapter's documented default gateway URL. Passed explicitly when the
+ * session selects gateway auth without a base URL, so the adapter never
+ * consults the host environment for it.
+ */
+const DEFAULT_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh";
+/**
+ * Build the explicit claude-code auth settings from the session env.
+ *
+ * Fails closed when the env carries variables this path cannot deliver to
+ * the agent runtime, and when no credential is present at all (the adapter
+ * would otherwise fall back to the runner host's own credentials).
+ */
+export function claudeCodeAuthFromEnv(env) {
+    const supported = new Set(SUPPORTED_AUTH_VARS);
+    const unsupported = Object.keys(env).filter((name) => !supported.has(name));
+    if (unsupported.length > 0) {
+        throw new CapabilityMismatchError(`ai-sdk harness backend cannot deliver env vars [${unsupported.join(", ")}] ` +
+            `to the agent runtime; supported: ${SUPPORTED_AUTH_VARS.join(", ")}`);
+    }
+    if (env.AI_GATEWAY_API_KEY) {
+        return {
+            gateway: {
+                apiKey: env.AI_GATEWAY_API_KEY,
+                baseUrl: env.AI_GATEWAY_BASE_URL || DEFAULT_GATEWAY_BASE_URL
+            }
+        };
+    }
+    if (env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN) {
+        // Empty strings deliberately occupy the unset fields: the adapter's
+        // `explicit ?? process.env.*` resolution then never reaches the host
+        // environment, and falsy values are not exported to the bridge.
+        return {
+            anthropic: {
+                apiKey: env.ANTHROPIC_API_KEY ?? "",
+                authToken: env.ANTHROPIC_AUTH_TOKEN ?? "",
+                baseUrl: env.ANTHROPIC_BASE_URL ?? ""
+            }
+        };
+    }
+    throw new CapabilityMismatchError("claude-code over the ai-sdk harness requires a credential released into the " +
+        "session env (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or AI_GATEWAY_API_KEY); " +
+        "refusing to fall back to the runner host environment");
+}
+/**
+ * The provider env-var pairs the Pi adapter understands. Pi maps each
+ * `<PREFIX>_API_KEY` (with an optional `<PREFIX>_BASE_URL`) to a provider:
+ * OPENAI → openai, ANTHROPIC → anthropic, AI_GATEWAY → vercel-ai-gateway.
+ * For the swarm's local-model workers the meaningful pair is
+ * `OPENAI_BASE_URL` + `OPENAI_API_KEY` pointing at a local OpenAI-compatible
+ * endpoint (Ollama / mlx-lm), where the key is typically a dummy value.
+ *
+ * Pinned here so anything else in the contract's env policy fails closed
+ * rather than being silently dropped, exactly like the claude-code path.
+ */
+const PI_SUPPORTED_AUTH_VARS = [
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "AI_GATEWAY_API_KEY",
+    "AI_GATEWAY_BASE_URL",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL"
+];
+/** A `<PREFIX>_API_KEY` is what actually selects a provider for Pi. */
+const PI_API_KEY_VARS = [
+    "OPENAI_API_KEY",
+    "AI_GATEWAY_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN"
+];
+/**
+ * Build explicit Pi auth from the session env, fail-closed.
+ *
+ * Pi's default resolution reaches into the *host* process environment for an
+ * AI Gateway key or `VERCEL_OIDC_TOKEN`. On a Warrant runner that would
+ * bypass the secret broker, so this always passes an explicit `customEnv`
+ * built only from broker-released vars. It fails closed when the env carries
+ * a variable Pi cannot honor, and when no provider key is present at all
+ * (otherwise Pi would fall back to the host environment).
+ */
+export function piAuthFromEnv(env) {
+    const supported = new Set(PI_SUPPORTED_AUTH_VARS);
+    const unsupported = Object.keys(env).filter((name) => !supported.has(name));
+    if (unsupported.length > 0) {
+        throw new CapabilityMismatchError(`pi over the ai-sdk harness cannot deliver env vars [${unsupported.join(", ")}] ` +
+            `to the agent runtime; supported: ${PI_SUPPORTED_AUTH_VARS.join(", ")}`);
+    }
+    const hasKey = PI_API_KEY_VARS.some((name) => env[name]);
+    if (!hasKey) {
+        throw new CapabilityMismatchError("pi over the ai-sdk harness requires a provider credential released into the " +
+            "session env (OPENAI_API_KEY with OPENAI_BASE_URL for a local endpoint, " +
+            "ANTHROPIC_API_KEY, or AI_GATEWAY_API_KEY); refusing to fall back to the " +
+            "runner host environment");
+    }
+    // Forward only the recognized, present pairs as resolved customEnv. Pi
+    // honors customEnv ahead of any ambient gateway credential, so the host
+    // environment is never consulted.
+    const customEnv = {};
+    for (const name of PI_SUPPORTED_AUTH_VARS) {
+        if (env[name])
+            customEnv[name] = env[name];
+    }
+    return { customEnv };
+}

package/dist/backend.d.ts

@@ -0,0 +1,63 @@
+import type { HarnessAgentAdapter, HarnessAgentSettings } from "@ai-sdk/harness/agent";
+import type { AgentKind, RunContract, SessionIsolation } from "@fusionkit/protocol";
+import type { BackendExecutionKind, SessionBackend, SessionBackendResult, SessionExecution } from "@fusionkit/runner";
+/**
+ * A harness adapter regardless of its builtin tool set, typed from the agent
+ * module itself so the seam always matches what `HarnessAgent` accepts.
+ * (`HarnessV1`'s default `ToolSet` parameter rejects concrete adapters like
+ * `createClaudeCode()`/`createPi()` because tool input schemas are not
+ * assignable across the index signature; the AI SDK's own settings use the
+ * same `any`-tools parameterization.)
+ */
+export type HarnessAdapter = HarnessAgentAdapter<any>;
+/**
+ * The sandbox provider type `HarnessAgent` expects, derived from its settings
+ * rather than imported from `@ai-sdk/harness` directly: pnpm can instantiate
+ * that package once per zod peer context, and deriving the type keeps this
+ * seam pinned to the agent's own instance.
+ */
+export type HarnessSandboxProvider = HarnessAgentSettings["sandbox"];
+export type CreateHarnessInput = {
+    /** Resolved session env: contract env policy plus released secrets. */
+    env: Record<string, string>;
+    contract: RunContract;
+};
+export type CreateSandboxProviderInput = {
+    contract: RunContract;
+    timeoutMs: number;
+};
+/**
+ * Everything a single harness contributes to the generic backend: which agent
+ * kind it serves, the isolation tier its runs are labeled with, how to build
+ * the adapter and the sandbox provider for a given session, and any
+ * session-state directories that are runtime plumbing rather than workspace
+ * output (excluded from both staging and mirror-back).
+ */
+export type HarnessBinding = {
+    readonly agentKind: AgentKind;
+    readonly isolation: SessionIsolation;
+    createHarness(input: CreateHarnessInput): HarnessAdapter | Promise<HarnessAdapter>;
+    createSandboxProvider(input: CreateSandboxProviderInput): HarnessSandboxProvider | Promise<HarnessSandboxProvider>;
+    readonly extraIgnores?: readonly string[];
+};
+/** True when the contract's execution is an agent run of the given kind. */
+export declare function isAgentRunFor(contract: RunContract, kind: AgentKind): boolean;
+export declare class AiSdkHarnessBackend implements SessionBackend {
+    readonly isolation: SessionIsolation;
+    private readonly binding;
+    private readonly fallback;
+    private readonly ignoredSegments;
+    constructor(input: {
+        binding: HarnessBinding;
+        fallback: SessionBackend;
+    });
+    private isBindingRun;
+    supports(kind: BackendExecutionKind, contract: RunContract): boolean;
+    execute(input: SessionExecution): Promise<SessionBackendResult>;
+    private executeHarness;
+}
+/** Host a single harness binding plus a fallback backend for its tier. */
+export declare function harnessBackend(input: {
+    binding: HarnessBinding;
+    fallback: SessionBackend;
+}): AiSdkHarnessBackend;

package/dist/backend.js

@@ -0,0 +1,154 @@
+/**
+ * Generic AI SDK harness session backend: drives one vendor agent harness
+ * through the AI SDK harness abstraction (`HarnessAgent`) inside a sandbox,
+ * under the same governed-session contract as every other backend.
+ *
+ * What varies between harnesses — which adapter runs, which sandbox provider
+ * hosts it, which isolation tier the run is labeled with, and how credentials
+ * map into the adapter's explicit auth — is captured by a `HarnessBinding`.
+ * Everything that does *not* vary lives here once: workspace staging into the
+ * sandbox, the structured transcript artifact, git-based mirror-back, the
+ * boundary event, and delegation of non-matching runs to a fallback backend.
+ *
+ * Concrete bindings live alongside this file: `claudeCodeBinding` (Claude
+ * Code in a Vercel Sandbox microVM) and `piBinding` (Pi on a local just-bash
+ * sandbox driving a local model). A backend hosts exactly one binding plus a
+ * fallback for everything else in its tier — the single sanctioned way to
+ * combine behaviors within an isolation tier (see runner `runSession`).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { HarnessAgent } from "@ai-sdk/harness/agent";
+import { CapabilityMismatchError, executionHash, executionSpecFor, resolveSessionEnv } from "@fusionkit/runner";
+import { SANDBOX_IGNORED_DIRS, listWorkspaceFiles, shellQuote, writeMirroredFile } from "@fusionkit/session-vercel-sandbox";
+import { TranscriptRecorder } from "./transcript.js";
+function posixJoin(base, rel) {
+    return `${base}/${rel.split("\\").join("/")}`;
+}
+/** True when the contract's execution is an agent run of the given kind. */
+export function isAgentRunFor(contract, kind) {
+    const spec = executionSpecFor(contract);
+    return spec.kind === "agent" && spec.agent.kind === kind;
+}
+export class AiSdkHarnessBackend {
+    isolation;
+    binding;
+    fallback;
+    ignoredSegments;
+    constructor(input) {
+        this.binding = input.binding;
+        this.fallback = input.fallback;
+        this.isolation = input.binding.isolation;
+        this.ignoredSegments = new Set([
+            ...SANDBOX_IGNORED_DIRS,
+            ...(input.binding.extraIgnores ?? [])
+        ]);
+    }
+    isBindingRun(contract) {
+        return isAgentRunFor(contract, this.binding.agentKind);
+    }
+    supports(kind, contract) {
+        if (this.isBindingRun(contract))
+            return true;
+        return this.fallback.supports ? this.fallback.supports(kind, contract) : true;
+    }
+    async execute(input) {
+        if (!this.isBindingRun(input.contract)) {
+            return this.fallback.execute(input);
+        }
+        return this.executeHarness(input);
+    }
+    async executeHarness(input) {
+        const { contract, repoDir, secrets, execution, emit } = input;
+        const spec = executionSpecFor(contract);
+        if (spec.kind !== "agent") {
+            throw new CapabilityMismatchError("harness path requires an agent execution spec");
+        }
+        const env = resolveSessionEnv(execution.env, secrets);
+        const extraIgnores = this.binding.extraIgnores ?? [];
+        const harness = await this.binding.createHarness({ env, contract });
+        const provider = await this.binding.createSandboxProvider({
+            contract,
+            timeoutMs: execution.timeoutMs
+        });
+        // One signal covers session creation, sandbox startup, and the turn.
+        const abortSignal = AbortSignal.timeout(execution.timeoutMs);
+        let staged;
+        const agent = new HarnessAgent({
+            harness,
+            sandbox: provider,
+            onSandboxSession: async ({ session, sessionWorkDir }) => {
+                staged = { session, workDir: sessionWorkDir };
+                for (const rel of listWorkspaceFiles(repoDir, extraIgnores)) {
+                    await session.writeBinaryFile({
+                        path: posixJoin(sessionWorkDir, rel),
+                        content: readFileSync(join(repoDir, rel))
+                    });
+                }
+            }
+        });
+        const transcript = new TranscriptRecorder();
+        const session = await agent.createSession({ abortSignal });
+        try {
+            try {
+                const result = await agent.stream({
+                    session,
+                    prompt: spec.prompt,
+                    abortSignal
+                });
+                for await (const part of result.fullStream) {
+                    transcript.ingest(part);
+                }
+            }
+            catch (error) {
+                // A failed turn is still evidence: record it, mirror back whatever
+                // the harness already changed, and report a non-zero exit code.
+                transcript.fail(error);
+            }
+            if (staged) {
+                await mirrorBack(staged.session, staged.workDir, repoDir, this.ignoredSegments);
+            }
+            const exitCode = transcript.exitCode();
+            emit({
+                type: "command.executed",
+                argvHash: executionHash(execution),
+                exitCode
+            });
+            return { exitCode, log: transcript.toBuffer(execution.logMaxBytes) };
+        }
+        finally {
+            await session.destroy().catch(() => undefined);
+        }
+    }
+}
+/**
+ * Mirror the session working tree back onto the local checkout so the runner's
+ * standard git-based output collection sees the changes. The sandbox FS
+ * surface has no directory listing, so the file list comes from one `find`
+ * inside the sandbox; every path is validated before it is written inside the
+ * local workspace.
+ */
+async function mirrorBack(session, workDir, repoDir, ignoredSegments) {
+    const listing = await session.run({
+        command: `find ${shellQuote(workDir)} -type f`
+    });
+    if (listing.exitCode !== 0) {
+        throw new CapabilityMismatchError(`harness mirror-back failed to list session files: ${listing.stderr}`);
+    }
+    for (const line of listing.stdout.split("\n")) {
+        const remote = line.trim();
+        if (!remote.startsWith(`${workDir}/`))
+            continue;
+        const rel = remote.slice(workDir.length + 1);
+        if (rel.split("/").some((segment) => ignoredSegments.has(segment)))
+            continue;
+        const content = await session.readBinaryFile({ path: remote });
+        if (content === null)
+            continue;
+        writeMirroredFile(repoDir, rel, content);
+    }
+}
+/** Host a single harness binding plus a fallback backend for its tier. */
+export function harnessBackend(input) {
+    return new AiSdkHarnessBackend(input);
+}

package/dist/claude-code.d.ts

@@ -0,0 +1,57 @@
+import type { RunContract } from "@fusionkit/protocol";
+import type { SessionBackend } from "@fusionkit/runner";
+import { AiSdkHarnessBackend } from "./backend.js";
+import type { CreateHarnessInput, CreateSandboxProviderInput, HarnessAdapter, HarnessBinding, HarnessSandboxProvider } from "./backend.js";
+export type ClaudeCodeBindingOptions = {
+    /** Sandbox runtime image for the harness bridge. Defaults to node24. */
+    runtime?: string;
+    /** Sandbox port the in-VM bridge listens on. Defaults to 4000. */
+    bridgePort?: number;
+    /** Vercel credentials; fall back to the ambient environment. */
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+    /** Anthropic model id passed to the claude-code runtime. */
+    model?: string;
+    /** Cap on internal harness turns before yielding. */
+    maxTurns?: number;
+    /** Extended-thinking behavior of the underlying runtime. */
+    thinking?: "off" | "on" | "adaptive";
+    /** Max milliseconds to wait for the in-sandbox bridge to start. */
+    startupTimeoutMs?: number;
+    /**
+     * Test/extension seam: supply the harness adapter. The default builds
+     * `createClaudeCode` with explicit auth from the session env (fail-closed,
+     * see auth.ts); overrides take on that responsibility themselves.
+     */
+    createHarness?: (input: CreateHarnessInput) => HarnessAdapter;
+    /**
+     * Test/extension seam: supply the sandbox provider. The default builds
+     * `createVercelSandbox` with the contract's network policy applied at VM
+     * creation; overrides take on that responsibility themselves.
+     */
+    createSandboxProvider?: (input: CreateSandboxProviderInput) => HarnessSandboxProvider;
+};
+/** True when the contract asks for the claude-code agent harness. */
+export declare function isClaudeCodeAgentRun(contract: RunContract): boolean;
+/** The Claude Code harness binding (vercel-sandbox isolation tier). */
+export declare function claudeCodeBinding(options?: ClaudeCodeBindingOptions): HarnessBinding;
+/**
+ * Options for the backward-compatible `aiSdkHarnessBackend()` factory: the
+ * Claude Code binding options plus a fallback backend.
+ */
+export type AiSdkHarnessBackendOptions = ClaudeCodeBindingOptions & {
+    /**
+     * Backend that executes everything this one does not (shell/argv
+     * executions, other agent kinds). Defaults to `vercelSandboxBackend()` with
+     * the same credentials, so installing this backend never narrows what the
+     * "vercel-sandbox" tier could already run.
+     */
+    fallback?: SessionBackend;
+};
+/**
+ * Create an AI SDK harness session backend for the Claude Code runtime. The
+ * historical entry point; equivalent to hosting `claudeCodeBinding(options)`
+ * with a vercel-sandbox fallback.
+ */
+export declare function aiSdkHarnessBackend(options?: AiSdkHarnessBackendOptions): AiSdkHarnessBackend;

package/dist/claude-code.js

@@ -0,0 +1,84 @@
+/**
+ * The Claude Code binding: drives the claude-code harness through the AI SDK
+ * harness abstraction inside a Vercel Sandbox microVM. The adapter bootstraps
+ * the Claude Code runtime inside the sandbox itself (pinned bridge deps,
+ * frozen lockfile), so the microVM needs no pre-baked vendor tooling.
+ *
+ * Status: experimental and integration-gated, like the plain vercel-sandbox
+ * backend. It compiles against the real canary packages; running the real
+ * path needs Vercel credentials plus a contract-released Anthropic or AI
+ * Gateway credential. Non-claude-code executions are delegated unchanged to a
+ * fallback backend (by default `vercelSandboxBackend()`), so a runner can
+ * install this backend as its single "vercel-sandbox" tier.
+ */
+import { createClaudeCode } from "@ai-sdk/harness-claude-code";
+import { createVercelSandbox } from "@ai-sdk/sandbox-vercel";
+import { toVercelNetwork, vercelCredentialsFromEnv, vercelSandboxBackend } from "@fusionkit/session-vercel-sandbox";
+import { claudeCodeAuthFromEnv } from "./auth.js";
+import { AiSdkHarnessBackend, isAgentRunFor } from "./backend.js";
+const DEFAULT_RUNTIME = "node24";
+const DEFAULT_BRIDGE_PORT = 4000;
+// On top of the shared sandbox ignore set, the harness's own session-state
+// directories are runtime plumbing, not workspace output.
+const CLAUDE_CODE_EXTRA_IGNORES = [".claude", ".agent-runs"];
+/** True when the contract asks for the claude-code agent harness. */
+export function isClaudeCodeAgentRun(contract) {
+    return isAgentRunFor(contract, "claude-code");
+}
+function defaultClaudeHarness(options) {
+    return (input) => {
+        const auth = claudeCodeAuthFromEnv(input.env);
+        const adapter = createClaudeCode({
+            auth,
+            ...(options.model !== undefined ? { model: options.model } : {}),
+            ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
+            ...(options.thinking !== undefined ? { thinking: options.thinking } : {}),
+            ...(options.startupTimeoutMs !== undefined
+                ? { startupTimeoutMs: options.startupTimeoutMs }
+                : {})
+        });
+        // pnpm gives @ai-sdk/harness-claude-code its own @ai-sdk/harness instance
+        // (different zod peer context), so its HarnessV1 is nominally distinct
+        // from the agent's despite being byte-identical. Bridge that split here.
+        return adapter;
+    };
+}
+function defaultClaudeSandbox(options) {
+    return (input) => {
+        return createVercelSandbox({
+            ...vercelCredentialsFromEnv(options),
+            runtime: options.runtime ?? DEFAULT_RUNTIME,
+            timeout: input.timeoutMs,
+            ports: [options.bridgePort ?? DEFAULT_BRIDGE_PORT],
+            // Deny-by-default egress from the signed contract, applied at the VM
+            // boundary. The bridge bootstrap and the model API are subject to it:
+            // a contract that wants this path live must allow the registry and
+            // api.anthropic.com (or the gateway host) explicitly.
+            networkPolicy: toVercelNetwork(input.contract.network)
+        });
+    };
+}
+/** The Claude Code harness binding (vercel-sandbox isolation tier). */
+export function claudeCodeBinding(options = {}) {
+    return {
+        agentKind: "claude-code",
+        isolation: "vercel-sandbox",
+        extraIgnores: CLAUDE_CODE_EXTRA_IGNORES,
+        createHarness: options.createHarness ?? defaultClaudeHarness(options),
+        createSandboxProvider: options.createSandboxProvider ?? defaultClaudeSandbox(options)
+    };
+}
+/**
+ * Create an AI SDK harness session backend for the Claude Code runtime. The
+ * historical entry point; equivalent to hosting `claudeCodeBinding(options)`
+ * with a vercel-sandbox fallback.
+ */
+export function aiSdkHarnessBackend(options = {}) {
+    const fallback = options.fallback ??
+        vercelSandboxBackend({
+            ...(options.token !== undefined ? { token: options.token } : {}),
+            ...(options.teamId !== undefined ? { teamId: options.teamId } : {}),
+            ...(options.projectId !== undefined ? { projectId: options.projectId } : {})
+        });
+    return new AiSdkHarnessBackend({ binding: claudeCodeBinding(options), fallback });
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fusionkit/session-harness — drives vendor agent harnesses through the AI SDK
+ * harness abstraction (`HarnessAgent`) inside a sandbox, under the same
+ * governed-session contract as every other backend: workspace staged in,
+ * structured evidence in the receipt, secrets via the broker.
+ *
+ * The generic backend is binding-driven. Two bindings ship here:
+ *
+ *  - `claudeCodeBinding` / `aiSdkHarnessBackend`: Claude Code in a Vercel
+ *    Sandbox microVM (vercel-sandbox tier).
+ *  - `piBinding` / `piHarnessBackend`: Pi on a local just-bash sandbox driving
+ *    a local model (hermetic tier) — the cheap worker for a local swarm.
+ */
+export { AiSdkHarnessBackend, harnessBackend, isAgentRunFor } from "./backend.js";
+export type { CreateHarnessInput, CreateSandboxProviderInput, HarnessAdapter, HarnessBinding, HarnessSandboxProvider } from "./backend.js";
+export { aiSdkHarnessBackend, claudeCodeBinding, isClaudeCodeAgentRun } from "./claude-code.js";
+export type { AiSdkHarnessBackendOptions, ClaudeCodeBindingOptions } from "./claude-code.js";
+export { isPiAgentRun, piBinding, piHarnessBackend } from "./pi.js";
+export type { PiBindingOptions, PiHarnessBackendOptions } from "./pi.js";
+export { claudeCodeAuthFromEnv, piAuthFromEnv } from "./auth.js";
+export { TranscriptRecorder } from "./transcript.js";
+export type { TranscriptLine } from "./transcript.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @fusionkit/session-harness — drives vendor agent harnesses through the AI SDK
+ * harness abstraction (`HarnessAgent`) inside a sandbox, under the same
+ * governed-session contract as every other backend: workspace staged in,
+ * structured evidence in the receipt, secrets via the broker.
+ *
+ * The generic backend is binding-driven. Two bindings ship here:
+ *
+ *  - `claudeCodeBinding` / `aiSdkHarnessBackend`: Claude Code in a Vercel
+ *    Sandbox microVM (vercel-sandbox tier).
+ *  - `piBinding` / `piHarnessBackend`: Pi on a local just-bash sandbox driving
+ *    a local model (hermetic tier) — the cheap worker for a local swarm.
+ */
+export { AiSdkHarnessBackend, harnessBackend, isAgentRunFor } from "./backend.js";
+export { aiSdkHarnessBackend, claudeCodeBinding, isClaudeCodeAgentRun } from "./claude-code.js";
+export { isPiAgentRun, piBinding, piHarnessBackend } from "./pi.js";
+export { claudeCodeAuthFromEnv, piAuthFromEnv } from "./auth.js";
+export { TranscriptRecorder } from "./transcript.js";

package/dist/pi.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The Pi binding: drives the Pi coding harness through the AI SDK harness
+ * abstraction on a local just-bash sandbox. Pi is a *host-runtime* harness —
+ * it runs in the runner's own Node process and uses the sandbox only as a
+ * virtual filesystem and shell, so there is no microVM and no per-run image
+ * to provision. That makes it the cheap worker for a swarm of local models.
+ *
+ * Two honest limits, stated here and in the README:
+ *
+ *  - just-bash is a *simulated* shell over a virtual filesystem. A Pi worker
+ *    can read, write, edit, grep, and glob the staged workspace, but cannot
+ *    run real builds or test suites. Acceptance of a worker's output is
+ *    judged from evidence (the diff and receipt), and work that genuinely
+ *    needs execution is escalated to a real-OS tier (claude-code on
+ *    process/vercel). A Pi binding over `createVercelSandbox` is possible
+ *    through the same seam when a worker truly needs execution; it is not the
+ *    default.
+ *  - Because Pi runs on the host, its model API call leaves from the host
+ *    process, not through the just-bash interpreter's network allowlist. The
+ *    contract's network policy therefore does not gate Pi's model traffic;
+ *    the governed boundary here is the workspace and the released credential
+ *    (the local endpoint URL), recorded in the receipt as every other run.
+ *
+ * Non-pi executions are delegated to a fallback backend (by default
+ * `hermeticBackend()`), so a runner can install this backend as its single
+ * "hermetic" tier.
+ */
+import type { RunContract } from "@fusionkit/protocol";
+import type { SessionBackend } from "@fusionkit/runner";
+import { AiSdkHarnessBackend } from "./backend.js";
+import type { CreateHarnessInput, CreateSandboxProviderInput, HarnessAdapter, HarnessBinding, HarnessSandboxProvider } from "./backend.js";
+export type PiBindingOptions = {
+    /** Pi model id (or name) sent to the local endpoint. */
+    model?: string;
+    /** Pi's extended-thinking budget level. */
+    thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    /**
+     * Test/extension seam: supply the harness adapter. The default builds
+     * `createPi` with explicit auth from the session env (fail-closed, see
+     * auth.ts); overrides take on that responsibility themselves.
+     */
+    createHarness?: (input: CreateHarnessInput) => HarnessAdapter;
+    /**
+     * Test/extension seam: supply the sandbox provider. The default builds a
+     * fresh just-bash sandbox per session; overrides take on that themselves.
+     */
+    createSandboxProvider?: (input: CreateSandboxProviderInput) => HarnessSandboxProvider;
+};
+/** True when the contract asks for the pi agent harness. */
+export declare function isPiAgentRun(contract: RunContract): boolean;
+/** The Pi harness binding (hermetic isolation tier). */
+export declare function piBinding(options?: PiBindingOptions): HarnessBinding;
+export type PiHarnessBackendOptions = PiBindingOptions & {
+    /**
+     * Backend that executes everything this one does not (shell commands, other
+     * agent kinds). Defaults to `hermeticBackend()`, so installing this backend
+     * never narrows what the "hermetic" tier could already run.
+     */
+    fallback?: SessionBackend;
+};
+/**
+ * Create an AI SDK harness session backend for the Pi runtime: hosts
+ * `piBinding(options)` with a hermetic fallback. This is the runner's single
+ * "hermetic" tier when local-model swarm workers are in play.
+ */
+export declare function piHarnessBackend(options?: PiHarnessBackendOptions): AiSdkHarnessBackend;