@fusionkit/adapter-compute 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fusionkit/adapter-compute — a ComputeSDK-shaped compute surface over
+ * governed runner sessions.
+ *
+ * The shape matches what ComputeSDK users already write —
+ * `compute.sandbox.create()`, `sandbox.runCommand(...)`,
+ * `sandbox.filesystem.writeFile(...)` — but the substrate is Warrant:
+ * every command is a signed run contract executed in a governed session
+ * with an offline-verifiable receipt. Honest semantics, stated plainly:
+ *
+ * - Each command runs in a *fresh* session materialized from the current
+ *   workspace state; continuity flows through the workspace's git history,
+ *   not through a long-lived remote process.
+ * - The adapter stages inputs as commits and pulls outputs back after each
+ *   command, so sequential commands compose.
+ * - `filesystem.writeFile` stages input files locally for the next command;
+ *   it is not a remote mutation (nothing exists remotely between commands).
+ */
+export { governedCompute, GovernedSandbox, withCompute } from "./sandbox.js";
+export type { CommandResult, GovernedCompute, GovernedComputeConfig, SandboxRunRecord } from "./sandbox.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fusionkit/adapter-compute — a ComputeSDK-shaped compute surface over
+ * governed runner sessions.
+ *
+ * The shape matches what ComputeSDK users already write —
+ * `compute.sandbox.create()`, `sandbox.runCommand(...)`,
+ * `sandbox.filesystem.writeFile(...)` — but the substrate is Warrant:
+ * every command is a signed run contract executed in a governed session
+ * with an offline-verifiable receipt. Honest semantics, stated plainly:
+ *
+ * - Each command runs in a *fresh* session materialized from the current
+ *   workspace state; continuity flows through the workspace's git history,
+ *   not through a long-lived remote process.
+ * - The adapter stages inputs as commits and pulls outputs back after each
+ *   command, so sequential commands compose.
+ * - `filesystem.writeFile` stages input files locally for the next command;
+ *   it is not a remote mutation (nothing exists remotely between commands).
+ */
+export { governedCompute, GovernedSandbox, withCompute } from "./sandbox.js";

package/dist/sandbox.d.ts

@@ -0,0 +1,89 @@
+import { Handoff } from "@fusionkit/handoff";
+import type { CommandHarnessConfig, GovernedRunRecord } from "@fusionkit/handoff";
+import type { RunStatus, SessionIsolation } from "@fusionkit/protocol";
+/**
+ * The shared command-harness configuration, with one compute-specific
+ * default applied at sandbox creation: untracked-file capture allows
+ * everything ("**"), because a sandbox is expected to see the files staged
+ * into it; secret-pattern denials still apply and are recorded in the
+ * manifest.
+ */
+export type GovernedComputeConfig = CommandHarnessConfig;
+export type CommandResult = {
+    runId: string;
+    status: RunStatus;
+    exitCode: number | undefined;
+    output: string;
+};
+export type SandboxRunRecord = GovernedRunRecord & {
+    sandboxId: string;
+};
+export type GovernedCompute = {
+    sandbox: {
+        create(): Promise<GovernedSandbox>;
+    };
+};
+/** Wiring for a sandbox: a continuation context plus its execution pool. */
+export type SandboxBinding = {
+    context: Handoff;
+    pool: string;
+    timeoutMs?: number;
+    session?: SessionIsolation;
+    committer?: {
+        name: string;
+        email: string;
+    };
+};
+export declare class GovernedSandbox {
+    readonly sandboxId: string;
+    readonly filesystem: {
+        writeFile(path: string, content: string): Promise<void>;
+        readFile(path: string): Promise<string>;
+        exists(path: string): Promise<boolean>;
+    };
+    private readonly context;
+    private readonly pool;
+    private readonly timeoutMs;
+    private readonly session?;
+    private readonly committer;
+    private readonly workspaceDir;
+    private readonly records;
+    private destroyed;
+    constructor(binding: SandboxBinding);
+    private assertLive;
+    private resolveInside;
+    /**
+     * Commit staged inputs (and prior outputs) so the next capture is clean at
+     * a fresh base ref; that lets the post-run pull apply on the fast path.
+     */
+    private commitIfDirty;
+    /** Execute one command in a fresh governed session and pull its output. */
+    runCommand(command: string): Promise<CommandResult>;
+    /** One record per executed command, each backed by a signed receipt. */
+    runs(): SandboxRunRecord[];
+    /** The underlying continuation context (trace, lastEnvelope, …). */
+    get handoffContext(): Handoff;
+    /**
+     * Stop accepting operations. Sessions are already ephemeral; what remains
+     * is the workspace state and the receipts, which is the point.
+     */
+    destroy(): Promise<void>;
+}
+/** Create a ComputeSDK-shaped compute surface over governed sessions. */
+export declare function governedCompute(config: GovernedComputeConfig): GovernedCompute;
+/**
+ * Attach the compute surface to an existing continuation context — the
+ * golden-shape composition. Sandboxes created here share the context's
+ * workspace, policy, and trace, so tool calls, continuations, and sandbox
+ * commands all land in one explainable history:
+ *
+ *   const h = withCompute(handoff({ workspace, plane, policy }), { pool });
+ *   const sandbox = await h.compute.sandbox.create();
+ */
+export declare function withCompute<H extends Handoff>(h: H, options: {
+    pool: string;
+    timeoutMs?: number;
+    session?: SessionIsolation;
+}): H & {
+    compute: GovernedCompute;
+};

package/dist/sandbox.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createCommandContext, executeGovernedCommand, targets, toGovernedRunRecord } from "@fusionkit/handoff";
+import { gitText, resolveInsideWorkspace } from "@fusionkit/workspace";
+function git(cwd, args) {
+    return gitText(cwd, args);
+}
+/** Default per-command wait ceiling for sandbox commands. */
+const DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60 * 1000;
+/** Identity used for the sandbox's staging commits. */
+const SANDBOX_COMMITTER = {
+    name: "warrant-sandbox",
+    email: "sandbox@warrant.local"
+};
+export class GovernedSandbox {
+    sandboxId;
+    filesystem;
+    context;
+    pool;
+    timeoutMs;
+    session;
+    committer;
+    workspaceDir;
+    records = [];
+    destroyed = false;
+    constructor(binding) {
+        this.sandboxId = `sbx_${randomUUID()}`;
+        this.context = binding.context;
+        this.pool = binding.pool;
+        this.timeoutMs = binding.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS;
+        this.session = binding.session;
+        this.committer = binding.committer ?? SANDBOX_COMMITTER;
+        this.workspaceDir = binding.context.workspacePath;
+        this.filesystem = {
+            writeFile: async (path, content) => {
+                this.assertLive();
+                const target = this.resolveInside(path);
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, content);
+            },
+            readFile: async (path) => {
+                this.assertLive();
+                return readFileSync(this.resolveInside(path), "utf8");
+            },
+            exists: async (path) => {
+                this.assertLive();
+                return existsSync(this.resolveInside(path));
+            }
+        };
+    }
+    assertLive() {
+        if (this.destroyed) {
+            throw new Error(`sandbox ${this.sandboxId} has been destroyed`);
+        }
+    }
+    resolveInside(path) {
+        return resolveInsideWorkspace(this.workspaceDir, path);
+    }
+    /**
+     * Commit staged inputs (and prior outputs) so the next capture is clean at
+     * a fresh base ref; that lets the post-run pull apply on the fast path.
+     */
+    commitIfDirty(message) {
+        git(this.workspaceDir, ["add", "-A"]);
+        const dirty = git(this.workspaceDir, ["status", "--porcelain"]).trim();
+        if (dirty.length === 0)
+            return;
+        git(this.workspaceDir, [
+            "-c",
+            `user.name=${this.committer.name}`,
+            "-c",
+            `user.email=${this.committer.email}`,
+            "commit",
+            "--quiet",
+            "-m",
+            message
+        ]);
+    }
+    /** Execute one command in a fresh governed session and pull its output. */
+    async runCommand(command) {
+        this.assertLive();
+        this.commitIfDirty(`sandbox ${this.sandboxId}: stage state`);
+        const result = await executeGovernedCommand(this.context, {
+            command,
+            target: targets.pool(this.pool),
+            reason: `sandbox ${this.sandboxId} command`,
+            timeoutMs: this.timeoutMs,
+            pullResults: true,
+            ...(this.session ? { session: this.session } : {})
+        });
+        this.records.push({
+            sandboxId: this.sandboxId,
+            ...toGovernedRunRecord(command, result)
+        });
+        return {
+            runId: result.run.runId,
+            status: result.status,
+            exitCode: result.exitCode,
+            output: result.output
+        };
+    }
+    /** One record per executed command, each backed by a signed receipt. */
+    runs() {
+        return [...this.records];
+    }
+    /** The underlying continuation context (trace, lastEnvelope, …). */
+    get handoffContext() {
+        return this.context;
+    }
+    /**
+     * Stop accepting operations. Sessions are already ephemeral; what remains
+     * is the workspace state and the receipts, which is the point.
+     */
+    destroy() {
+        this.destroyed = true;
+        return Promise.resolve();
+    }
+}
+/** Create a ComputeSDK-shaped compute surface over governed sessions. */
+export function governedCompute(config) {
+    return {
+        sandbox: {
+            create: () => {
+                const context = createCommandContext({
+                    ...config,
+                    workspace: resolve(config.workspace),
+                    allowUntracked: config.allowUntracked ?? ["**"]
+                });
+                return Promise.resolve(new GovernedSandbox({
+                    context,
+                    pool: config.pool,
+                    ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+                    ...(config.session ? { session: config.session } : {})
+                }));
+            }
+        }
+    };
+}
+/**
+ * Attach the compute surface to an existing continuation context — the
+ * golden-shape composition. Sandboxes created here share the context's
+ * workspace, policy, and trace, so tool calls, continuations, and sandbox
+ * commands all land in one explainable history:
+ *
+ *   const h = withCompute(handoff({ workspace, plane, policy }), { pool });
+ *   const sandbox = await h.compute.sandbox.create();
+ */
+export function withCompute(h, options) {
+    const compute = {
+        sandbox: {
+            create: () => Promise.resolve(new GovernedSandbox({
+                context: h,
+                pool: options.pool,
+                ...(options.timeoutMs !== undefined
+                    ? { timeoutMs: options.timeoutMs }
+                    : {}),
+                ...(options.session ? { session: options.session } : {})
+            }))
+        }
+    };
+    return Object.assign(h, { compute });
+}

package/dist/test/sandbox.test.d.ts

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

package/dist/test/sandbox.test.js

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { rmSync } from "node:fs";
+import { after, before, test } from "node:test";
+import { handoff, localFirst } from "@fusionkit/handoff";
+import { makeRepo, startStack } from "@fusionkit/testkit";
+import { resolveInsideWorkspace } from "@fusionkit/workspace";
+import { governedCompute, withCompute } from "../sandbox.js";
+const POOL = "eng-prod";
+const FAKE_COMMAND_HASH = "0".repeat(64);
+let stack;
+let repoDir;
+let sandbox;
+before(async () => {
+    stack = await startStack({
+        pool: POOL,
+        startRunner: true,
+        backends: [
+            {
+                isolation: "vercel-sandbox",
+                execute: async (input) => {
+                    const { execution } = input;
+                    const cwd = resolveInsideWorkspace(input.repoDir, execution.cwd);
+                    const env = { ...process.env, ...execution.env };
+                    const chunks = [];
+                    let capturedBytes = 0;
+                    let killChild = () => undefined;
+                    const push = (chunk) => {
+                        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                        chunks.push(buffer);
+                        capturedBytes += buffer.byteLength;
+                        if (execution.logMaxBytes !== undefined &&
+                            capturedBytes > execution.logMaxBytes) {
+                            killChild();
+                        }
+                    };
+                    const exitCode = await new Promise((resolve) => {
+                        const child = execution.kind === "argv"
+                            ? spawn(execution.cmd, execution.args, { cwd, env })
+                            : spawn(execution.shell, ["-c", execution.script], { cwd, env });
+                        killChild = () => {
+                            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);
+                            resolve(127);
+                        });
+                        child.on("close", (code) => {
+                            clearTimeout(timer);
+                            resolve(code ?? 1);
+                        });
+                    });
+                    input.emit({
+                        type: "command.executed",
+                        argvHash: FAKE_COMMAND_HASH,
+                        exitCode
+                    });
+                    return { exitCode, log: Buffer.concat(chunks) };
+                }
+            }
+        ],
+        policy: (policy) => {
+            policy.agents.allow = ["command"];
+        }
+    });
+    repoDir = makeRepo({ files: { "README.md": "# sandbox fixture\n" } });
+    const compute = governedCompute({
+        workspace: repoDir,
+        plane: { url: stack.planeUrl, adminToken: stack.adminToken },
+        pool: POOL,
+        actor: { kind: "human", id: "sandbox-user" }
+    });
+    sandbox = await compute.sandbox.create();
+});
+after(async () => {
+    await stack.stop();
+    rmSync(repoDir, { recursive: true, force: true });
+});
+test("staged files are visible to commands; outputs persist across commands", async () => {
+    await sandbox.filesystem.writeFile("task.md", "build the report\nwith two lines\n");
+    const first = await sandbox.runCommand("cat task.md | wc -l | tr -d ' ' > lines.txt && cat lines.txt");
+    assert.equal(first.status, "completed");
+    assert.equal(first.exitCode, 0);
+    assert.equal(first.output.trim(), "2");
+    // Sequential composition: the second command sees the first one's output.
+    const second = await sandbox.runCommand("cat lines.txt && echo done >> log.txt");
+    assert.equal(second.status, "completed");
+    assert.equal(second.output.trim(), "2");
+    assert.equal(await sandbox.filesystem.readFile("lines.txt"), "2\n");
+    assert.equal(await sandbox.filesystem.exists("log.txt"), true);
+    const runs = sandbox.runs();
+    assert.equal(runs.length, 2);
+    for (const run of runs) {
+        assert.equal(run.receiptVerified, true, "every command carries a verified receipt");
+        assert.match(run.contractHash, /^[0-9a-f]{64}$/);
+        assert.equal(run.isolation, "process");
+        assert.equal(run.sandboxId, sandbox.sandboxId);
+    }
+    assert.notEqual(runs[0]?.runId, runs[1]?.runId);
+});
+test("failing commands report their exit code and keep their receipt", async () => {
+    const failed = await sandbox.runCommand("ls /nonexistent-path-zz");
+    assert.equal(failed.status, "failed");
+    assert.notEqual(failed.exitCode, 0);
+    assert.ok(failed.output.length > 0, "stderr is captured in the session log");
+    const last = sandbox.runs().at(-1);
+    assert.ok(last);
+    assert.equal(last.receiptVerified, true);
+});
+test("paths cannot escape the sandbox workspace", async () => {
+    await assert.rejects(() => sandbox.filesystem.writeFile("../escape.txt", "nope"));
+    await assert.rejects(() => sandbox.filesystem.readFile("/etc/hostname"));
+});
+test("withCompute attaches the compute surface to an existing context with one shared trace", async () => {
+    const sharedRepo = makeRepo({ files: { "README.md": "# golden compute\n" } });
+    try {
+        const h = withCompute(handoff({
+            workspace: sharedRepo,
+            plane: { url: stack.planeUrl, adminToken: stack.adminToken },
+            policy: localFirst({ allowPools: [POOL] })
+        }), { pool: POOL });
+        const box = await h.compute.sandbox.create();
+        const result = await box.runCommand("echo golden > golden.txt && cat golden.txt");
+        assert.equal(result.status, "completed");
+        assert.equal(result.output.trim(), "golden");
+        assert.equal(await box.filesystem.readFile("golden.txt"), "golden\n");
+        // The sandbox command and the context share one trace and one summary.
+        const types = h.trace().map((e) => e.type);
+        assert.ok(types.includes("envelope.created"));
+        assert.ok(types.includes("results.pulled"));
+        const summary = await h.summary();
+        assert.equal(summary.runs.length, 1);
+        assert.equal(summary.runs[0]?.status, "completed");
+    }
+    finally {
+        rmSync(sharedRepo, { recursive: true, force: true });
+    }
+});
+test("session config requests vercel-sandbox without changing the sandbox API", async () => {
+    const microvmRepo = makeRepo({ files: { "README.md": "# microvm compute\n" } });
+    try {
+        const compute = governedCompute({
+            workspace: microvmRepo,
+            plane: { url: stack.planeUrl, adminToken: stack.adminToken },
+            pool: POOL,
+            actor: { kind: "human", id: "sandbox-user" },
+            session: "vercel-sandbox"
+        });
+        const box = await compute.sandbox.create();
+        await box.filesystem.writeFile("input.txt", "microvm\n");
+        const result = await box.runCommand("cat input.txt > microvm.txt && cat microvm.txt");
+        assert.equal(result.status, "completed");
+        assert.equal(result.exitCode, 0);
+        assert.equal(result.output.trim(), "microvm");
+        assert.equal(await box.filesystem.readFile("microvm.txt"), "microvm\n");
+        assert.equal(box.handoffContext.lastEnvelope()?.isolation, "vercel-sandbox");
+        const runs = box.runs();
+        assert.equal(runs.length, 1);
+        assert.equal(runs[0]?.receiptVerified, true);
+        assert.equal(runs[0]?.isolation, "vercel-sandbox");
+    }
+    finally {
+        rmSync(microvmRepo, { recursive: true, force: true });
+    }
+});
+test("destroyed sandboxes refuse further operations", async () => {
+    await sandbox.destroy();
+    await assert.rejects(() => sandbox.runCommand("echo too-late"), (error) => {
+        assert.ok(error instanceof Error);
+        assert.match(error.message, /destroyed/);
+        return true;
+    });
+    await assert.rejects(() => sandbox.filesystem.readFile("task.md"));
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@fusionkit/adapter-compute",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/adapter-compute"
+  },
+  "description": "ComputeSDK-shaped compute surface over governed runner sessions: sandbox.create(), runCommand, and filesystem, where every operation is a signed contract with a receipt.",
+  "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/handoff": "0.1.0",
+    "@fusionkit/protocol": "0.1.0",
+    "@fusionkit/workspace": "0.1.0",
+    "@fusionkit/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@fusionkit/testkit": "0.1.0"
+  }
+}