@fusionkit/session-harness 0.1.0

package/dist/test/pi.test.js

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import { verifyReceiptBundle } from "@fusionkit/protocol";
+import { CapabilityMismatchError } from "@fusionkit/runner";
+import { makeRepo, startStack } from "@fusionkit/testkit";
+import { captureWorkspace } from "@fusionkit/workspace";
+import { isPiAgentRun, piAuthFromEnv, piHarnessBackend } from "../index.js";
+import { emptyHarnessLog, fakeHarness, fakeLocalSandboxProvider } from "./fakes.js";
+// ---------------------------------------------------------------------------
+// auth: a local endpoint maps to explicit customEnv; everything else fails closed
+// ---------------------------------------------------------------------------
+test("pi auth: a local OpenAI-compatible endpoint maps to explicit customEnv", () => {
+    const auth = piAuthFromEnv({
+        OPENAI_BASE_URL: "http://127.0.0.1:11434/v1",
+        OPENAI_API_KEY: "local-dummy"
+    });
+    assert.deepEqual(auth, {
+        customEnv: {
+            OPENAI_API_KEY: "local-dummy",
+            OPENAI_BASE_URL: "http://127.0.0.1:11434/v1"
+        }
+    });
+});
+test("pi auth: a gateway key is forwarded as customEnv too", () => {
+    const auth = piAuthFromEnv({ AI_GATEWAY_API_KEY: "gw" });
+    assert.deepEqual(auth, { customEnv: { AI_GATEWAY_API_KEY: "gw" } });
+});
+test("pi auth: no provider credential fails closed", () => {
+    assert.throws(() => piAuthFromEnv({ OPENAI_BASE_URL: "http://127.0.0.1:11434/v1" }), (error) => error instanceof CapabilityMismatchError && /refusing to fall back/.test(error.message));
+});
+test("pi auth: env vars the pi path cannot deliver fail closed", () => {
+    assert.throws(() => piAuthFromEnv({ OPENAI_API_KEY: "k", CUSTOM_FLAG: "1" }), (error) => error instanceof CapabilityMismatchError && /CUSTOM_FLAG/.test(error.message));
+});
+// ---------------------------------------------------------------------------
+// delegation: non-pi executions go to the fallback (hermetic) backend
+// ---------------------------------------------------------------------------
+test("pi backend reports the hermetic tier and recognizes pi agent runs", () => {
+    const backend = piHarnessBackend();
+    assert.equal(backend.isolation, "hermetic");
+});
+// ---------------------------------------------------------------------------
+// end to end: a governed pi run through the real HarnessAgent
+//
+// As in the claude-code e2e, the fakes replace only what needs a live local
+// model (the pi adapter) and a real sandbox (a local directory in place of
+// just-bash). The binding wiring, generic backend, staging, mirror-back,
+// event chain, and offline verification are all real — and the run is
+// labeled with the hermetic tier the pi binding declares.
+// ---------------------------------------------------------------------------
+const POOL = "swarm-pool";
+let stack;
+let repoDir;
+let sandboxRoot;
+const harnessLog = emptyHarnessLog();
+before(async () => {
+    sandboxRoot = mkdtempSync(join(tmpdir(), "warrant-fake-pi-sandbox-"));
+    stack = await startStack({
+        pool: POOL,
+        startRunner: true,
+        backends: [
+            piHarnessBackend({
+                createHarness: ({ env }) => {
+                    harnessLog.envSeen.push(env);
+                    return fakeHarness(harnessLog, "fake-pi");
+                },
+                createSandboxProvider: () => fakeLocalSandboxProvider(sandboxRoot)
+            })
+        ],
+        policy: (policy) => {
+            policy.agents.allow = ["pi"];
+        }
+    });
+    repoDir = makeRepo({
+        files: { "README.md": "# pi fixture\n", "data.txt": "alpha\nbeta\n" }
+    });
+});
+after(async () => {
+    await stack.stop();
+    rmSync(repoDir, { recursive: true, force: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("e2e: a pi contract runs through the real HarnessAgent on the hermetic tier", async () => {
+    const captured = captureWorkspace(repoDir);
+    await stack.client.putBlob(captured.bundle);
+    if (captured.dirtyDiff)
+        await stack.client.putBlob(captured.dirtyDiff);
+    const created = await stack.client.requestRun({
+        requestedBy: { kind: "human", id: "swarm-worker" },
+        agentKind: "pi",
+        prompt: "count the lines in data.txt",
+        pool: POOL,
+        secretNames: [],
+        workspace: captured.manifest,
+        network: { defaultDeny: true, allowHosts: [] },
+        budget: {},
+        disclosure: "minimal-context",
+        isolation: "hermetic",
+        execution: {
+            kind: "agent",
+            agent: { kind: "pi" },
+            prompt: "count the lines in data.txt",
+            env: {
+                vars: {
+                    OPENAI_BASE_URL: "http://127.0.0.1:11434/v1",
+                    OPENAI_API_KEY: "local-dummy"
+                }
+            }
+        }
+    });
+    const contract = created.runId;
+    assert.ok(isPiAgentRun);
+    assert.equal(await stack.runOnce(), contract);
+    const bundle = await stack.client.getBundle(contract);
+    assert.equal(bundle.receipt.status, "completed");
+    assert.equal(bundle.receipt.runner.isolation, "hermetic");
+    assert.deepEqual(verifyReceiptBundle(bundle).problems, []);
+    // The pi adapter saw the prompt and the broker-resolved local endpoint env,
+    // never the host environment.
+    assert.deepEqual(harnessLog.prompts, ["count the lines in data.txt"]);
+    assert.deepEqual(harnessLog.envSeen, [
+        {
+            OPENAI_BASE_URL: "http://127.0.0.1:11434/v1",
+            OPENAI_API_KEY: "local-dummy"
+        }
+    ]);
+    // The worker's edit was mirrored back into the runner's checkout.
+    assert.ok(bundle.receipt.workspaceOut.diffHash, "expected a workspace diff");
+    const diff = await stack.client.getBlob(bundle.receipt.workspaceOut.diffHash);
+    assert.ok(diff.toString("utf8").includes("result.txt"));
+    const fileEvents = bundle.events.filter((e) => e.event.type === "file.changed");
+    assert.ok(fileEvents.some((e) => e.event.type === "file.changed" && e.event.path === "result.txt"), "expected the mirrored result.txt in the boundary file events");
+});

package/dist/transcript.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured session transcript: the harness's typed event stream rendered
+ * as one JSON line per part. This becomes the run's log artifact, replacing
+ * the merged stdout/stderr a CLI invocation would have produced — every
+ * tool call, file-change notice, and finish reason the harness reported is
+ * preserved verbatim and hash-addressed in the receipt.
+ *
+ * The recorder is deliberately liberal in what it accepts: harness stream
+ * parts are an experimental, evolving union (`@ai-sdk/harness` canary), so
+ * known part types are mapped to stable transcript shapes and unknown types
+ * are recorded by name only. Nothing here throws on a novel part.
+ */
+/** One JSON line of the transcript. */
+export type TranscriptLine = {
+    part: string;
+} & Record<string, unknown>;
+export declare class TranscriptRecorder {
+    private readonly lines;
+    private readonly textById;
+    private failed;
+    /** Ingest one stream part from the harness agent's full stream. */
+    ingest(value: unknown): void;
+    /** Record a turn-level failure (a thrown stream/iteration error). */
+    fail(error: unknown): void;
+    /** 0 when the turn finished cleanly, 1 when any error part was seen. */
+    exitCode(): number;
+    /** Render the transcript as a JSONL buffer, optionally truncated. */
+    toBuffer(maxBytes?: number): Buffer;
+    private push;
+    private appendText;
+    private flushText;
+    private flushAllText;
+}

package/dist/transcript.js

@@ -0,0 +1,214 @@
+/**
+ * Structured session transcript: the harness's typed event stream rendered
+ * as one JSON line per part. This becomes the run's log artifact, replacing
+ * the merged stdout/stderr a CLI invocation would have produced — every
+ * tool call, file-change notice, and finish reason the harness reported is
+ * preserved verbatim and hash-addressed in the receipt.
+ *
+ * The recorder is deliberately liberal in what it accepts: harness stream
+ * parts are an experimental, evolving union (`@ai-sdk/harness` canary), so
+ * known part types are mapped to stable transcript shapes and unknown types
+ * are recorded by name only. Nothing here throws on a novel part.
+ */
+function jsonSafe(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value, (_key, v) => (typeof v === "bigint" ? String(v) : v)));
+    }
+    catch {
+        return String(value);
+    }
+}
+export class TranscriptRecorder {
+    lines = [];
+    textById = new Map();
+    failed = false;
+    /** Ingest one stream part from the harness agent's full stream. */
+    ingest(value) {
+        if (typeof value !== "object" || value === null)
+            return;
+        const part = value;
+        if (typeof part.type !== "string")
+            return;
+        switch (part.type) {
+            case "start":
+            case "start-step":
+            case "finish-step":
+            case "text-start":
+            case "reasoning-start":
+            case "raw":
+                return; // structural framing; no evidence content of its own
+            case "stream-start": {
+                this.push({
+                    part: "stream-start",
+                    ...(part.modelId !== undefined ? { modelId: part.modelId } : {}),
+                    ...(Array.isArray(part.warnings) && part.warnings.length > 0
+                        ? { warnings: jsonSafe(part.warnings) }
+                        : {})
+                });
+                return;
+            }
+            case "text-delta": {
+                this.appendText("text", part);
+                return;
+            }
+            case "reasoning-delta": {
+                this.appendText("reasoning", part);
+                return;
+            }
+            case "text-end": {
+                this.flushText("text", part);
+                return;
+            }
+            case "reasoning-end": {
+                this.flushText("reasoning", part);
+                return;
+            }
+            case "tool-call": {
+                this.push({
+                    part: "tool-call",
+                    toolCallId: part.toolCallId,
+                    toolName: part.toolName,
+                    input: jsonSafe(part.input)
+                });
+                return;
+            }
+            case "tool-result": {
+                // HarnessV1 emits `result`; the AI SDK stream surface emits `output`.
+                const output = "output" in part ? part.output : part.result;
+                this.push({
+                    part: "tool-result",
+                    toolCallId: part.toolCallId,
+                    toolName: part.toolName,
+                    output: jsonSafe(output),
+                    ...(part.isError === true ? { isError: true } : {})
+                });
+                return;
+            }
+            case "tool-error": {
+                this.push({
+                    part: "tool-error",
+                    toolCallId: part.toolCallId,
+                    toolName: part.toolName,
+                    error: errorMessage(part.error)
+                });
+                return;
+            }
+            case "tool-approval-request": {
+                this.push({
+                    part: "tool-approval-request",
+                    approvalId: part.approvalId,
+                    toolCallId: part.toolCallId
+                });
+                return;
+            }
+            case "file-change": {
+                this.push({ part: "file-change", event: part.event, path: part.path });
+                return;
+            }
+            case "compaction": {
+                this.push({ part: "compaction", trigger: part.trigger, summary: part.summary });
+                return;
+            }
+            case "finish": {
+                const finishReason = finishReasonOf(part.finishReason);
+                if (finishReason === "error")
+                    this.failed = true;
+                this.push({
+                    part: "finish",
+                    finishReason,
+                    ...(part.totalUsage !== undefined ? { totalUsage: jsonSafe(part.totalUsage) } : {})
+                });
+                return;
+            }
+            case "error":
+            case "abort": {
+                this.failed = true;
+                this.push({ part: part.type, error: errorMessage(part.error) });
+                return;
+            }
+            default: {
+                // Unknown/novel part types: record the occurrence without an
+                // unbounded payload, so the transcript stays evidence-shaped even
+                // as the experimental harness union evolves.
+                this.push({ part: part.type });
+                return;
+            }
+        }
+    }
+    /** Record a turn-level failure (a thrown stream/iteration error). */
+    fail(error) {
+        this.failed = true;
+        this.push({ part: "turn-failed", error: errorMessage(error) });
+    }
+    /** 0 when the turn finished cleanly, 1 when any error part was seen. */
+    exitCode() {
+        return this.failed ? 1 : 0;
+    }
+    /** Render the transcript as a JSONL buffer, optionally truncated. */
+    toBuffer(maxBytes) {
+        this.flushAllText();
+        const body = this.lines.map((line) => JSON.stringify(line)).join("\n");
+        const buffer = Buffer.from(body.length > 0 ? `${body}\n` : "", "utf8");
+        if (maxBytes !== undefined && buffer.byteLength > maxBytes) {
+            return buffer.subarray(0, maxBytes);
+        }
+        return buffer;
+    }
+    push(line) {
+        this.lines.push(line);
+    }
+    appendText(kind, part) {
+        const id = typeof part.id === "string" ? part.id : `${kind}:anonymous`;
+        // HarnessV1 emits `delta`; the AI SDK stream surface emits `text`.
+        const deltaValue = "delta" in part ? part.delta : part.text;
+        const delta = typeof deltaValue === "string" ? deltaValue : "";
+        const entry = this.textById.get(id) ?? { kind, text: "" };
+        entry.text += delta;
+        this.textById.set(id, entry);
+    }
+    flushText(kind, part) {
+        const id = typeof part.id === "string" ? part.id : `${kind}:anonymous`;
+        const entry = this.textById.get(id);
+        if (!entry)
+            return;
+        this.textById.delete(id);
+        if (entry.text.length === 0)
+            return;
+        this.push({ part: entry.kind, text: entry.text });
+    }
+    flushAllText() {
+        for (const entry of this.textById.values()) {
+            if (entry.text.length > 0)
+                this.push({ part: entry.kind, text: entry.text });
+        }
+        this.textById.clear();
+    }
+}
+/**
+ * A finish reason is a plain string on the AI SDK stream surface and a
+ * `{ unified, raw? }` object at the harness/provider level; accept both.
+ */
+function finishReasonOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null && "unified" in value) {
+        const unified = value.unified;
+        if (typeof unified === "string")
+            return unified;
+    }
+    return "unknown";
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(jsonSafe(error));
+    }
+    catch {
+        return String(error);
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@fusionkit/session-harness",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/session-harness"
+  },
+  "description": "AI SDK harness session backend for Warrant runners: drives vendor agent harnesses (Claude Code) through @ai-sdk/harness inside a Vercel Sandbox microVM, capturing the structured harness event stream as governed-session evidence.",
+  "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": {
+    "@ai-sdk/harness": "1.0.0-canary.6",
+    "@ai-sdk/harness-claude-code": "1.0.0-canary.2",
+    "@ai-sdk/harness-pi": "1.0.0-canary.2",
+    "@ai-sdk/sandbox-just-bash": "1.0.0-canary.6",
+    "@ai-sdk/sandbox-vercel": "1.0.0-canary.6",
+    "ws": "8.21.0",
+    "@fusionkit/runner": "0.1.0",
+    "@fusionkit/session-hermetic": "0.1.0",
+    "@fusionkit/protocol": "0.1.0",
+    "@fusionkit/session-vercel-sandbox": "0.1.0"
+  },
+  "devDependencies": {
+    "@fusionkit/plane": "0.1.0",
+    "@fusionkit/sdk": "0.1.0",
+    "@fusionkit/testkit": "0.1.0",
+    "@fusionkit/workspace": "0.1.0"
+  }
+}