@fusionkit/handoff 0.1.0

package/dist/run.js

@@ -0,0 +1,159 @@
+import { isTerminalStatus } from "@fusionkit/protocol";
+import { pullRun } from "@fusionkit/workspace";
+import { DEFAULT_POLL_INTERVAL_MS, DEFAULT_WAIT_TIMEOUT_MS } from "./defaults.js";
+/**
+ * A continuation that became a governed run. Wraps the plane API with the
+ * operations a continuation caller needs: wait, approve, receipt, pull.
+ */
+export class HandoffRun {
+    runId;
+    target;
+    envelope;
+    envelopeHash;
+    /** Human-readable planner explanation for why this continuation ran. */
+    explanation;
+    /** Isolation strategy applied at pull time. */
+    isolate;
+    client;
+    actor;
+    workspaceDir;
+    onTerminal;
+    onPulled;
+    constructor(input) {
+        this.runId = input.runId;
+        this.target = input.target;
+        this.envelope = input.envelope;
+        this.envelopeHash = input.envelopeHash;
+        this.explanation = input.explanation ?? "";
+        if (input.isolate)
+            this.isolate = input.isolate;
+        this.client = input.client;
+        this.actor = input.actor;
+        this.workspaceDir = input.workspaceDir;
+        this.onTerminal = input.onTerminal;
+        this.onPulled = input.onPulled;
+    }
+    /** The checkpoint tier this continuation carried. */
+    get tier() {
+        return this.envelope.checkpoint.tier;
+    }
+    /** Deep link to this run in the control panel. */
+    get url() {
+        return this.client.runUiUrl(this.runId);
+    }
+    /** Where the signed evidence lives: bundle download via the CLI. */
+    get auditUrl() {
+        return this.client.runBundleUrl(this.runId);
+    }
+    async status() {
+        const view = await this.client.getRun(this.runId);
+        return view.status;
+    }
+    async events() {
+        const view = await this.client.getRun(this.runId);
+        return view.events;
+    }
+    /**
+     * Poll until the run is terminal or blocked on consent. Consent is a
+     * human decision; the SDK surfaces it instead of spinning forever.
+     */
+    async wait(options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const pollMs = options.pollMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const deadline = Date.now() + timeoutMs;
+        // Polling against a consistent per-iteration snapshot: terminal states
+        // are absorbing, so a status flip between polls is observed on the next
+        // iteration rather than lost. The interval and ceiling are shared with
+        // Handoff.stream via ./defaults.js and caller-tunable per wait().
+        for (;;) {
+            const view = await this.client.getRun(this.runId);
+            if (isTerminalStatus(view.status)) {
+                this.onTerminal(this.runId, view.status);
+                return { status: view.status, consentRequirements: [] };
+            }
+            if (view.status === "awaiting_approval") {
+                return {
+                    status: view.status,
+                    consentRequirements: view.consentRequirements
+                };
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`run ${this.runId} did not finish within ${timeoutMs}ms`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    /**
+     * The session's combined stdout/stderr, fetched by the content hash
+     * recorded in the event chain. Empty when the session produced no output.
+     */
+    async sessionLog() {
+        const events = await this.events();
+        // Reverse scan returns the newest log artifact, which by the harness
+        // convention supersedes earlier ones — exactly the right pick when a
+        // session emitted more than one.
+        for (let i = events.length - 1; i >= 0; i--) {
+            const entry = events[i];
+            if (!entry)
+                continue;
+            const event = entry.event;
+            if (event.type === "artifact.created" && event.kind === "log") {
+                const blob = await this.client.getBlob(event.hash);
+                return blob.toString("utf8");
+            }
+        }
+        return "";
+    }
+    /**
+     * Exit code of the session's final harness command (the run's overall
+     * outcome by convention). Sessions that execute multiple commands surface
+     * each one as its own command.executed entry in events() for callers that
+     * need per-command results.
+     */
+    async commandExitCode() {
+        const events = await this.events();
+        for (let i = events.length - 1; i >= 0; i--) {
+            const entry = events[i];
+            if (!entry)
+                continue;
+            if (entry.event.type === "command.executed") {
+                return entry.event.exitCode;
+            }
+        }
+        return undefined;
+    }
+    /** Grant required consent as the given actor (defaults to the context actor). */
+    async approve(actor) {
+        const result = await this.client.approve(this.runId, actor ?? this.actor);
+        return result.status;
+    }
+    /** Cancel the run if it has not been claimed by a runner yet. */
+    async cancel(actor) {
+        const result = await this.client.cancel(this.runId, actor ?? this.actor);
+        return result.status;
+    }
+    /** The signed, offline-verifiable receipt bundle. */
+    receipt() {
+        return this.client.getBundle(this.runId);
+    }
+    /**
+     * Divergence-safe pull of the run's output into the local workspace:
+     * applied in place when the workspace is clean at the contract base ref,
+     * otherwise materialized on a dedicated branch. A `branch()` isolation
+     * strategy (set here or at continueIn/parallel time) always lands on a
+     * branch and never touches the working tree.
+     */
+    async pull(options = {}) {
+        const bundle = await this.receipt();
+        const diffHash = bundle.receipt.workspaceOut.diffHash;
+        if (!diffHash) {
+            this.onPulled(this.runId, "empty");
+            return { mode: "empty" };
+        }
+        const isolate = options.isolate ?? this.isolate;
+        const diff = await this.client.getBlob(diffHash);
+        const result = pullRun(options.repoDir ?? this.workspaceDir, this.runId, bundle.contract.workspace.baseRef, diff, { forceBranch: isolate?.id === "branch" });
+        this.onPulled(this.runId, result.mode);
+        return result;
+    }
+}

package/dist/targets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed runtime-target descriptors. No magic strings in the hot path:
+ * `targets.pool("eng-prod")` instead of `"eng-prod"`.
+ */
+export type RuntimeTarget = {
+    kind: "runtime-target";
+    id: string;
+    locality: "customer-runner";
+    pool: string;
+};
+export declare const targets: {
+    /** A named runner pool: outbound-only runners enrolled with the plane. */
+    pool(name: string): RuntimeTarget;
+};

package/dist/targets.js

@@ -0,0 +1,20 @@
+/**
+ * Typed runtime-target descriptors. No magic strings in the hot path:
+ * `targets.pool("eng-prod")` instead of `"eng-prod"`.
+ */
+export const targets = {
+    /** A named runner pool: outbound-only runners enrolled with the plane. */
+    pool(name) {
+        if (!name)
+            throw new Error("a pool name is required");
+        return {
+            kind: "runtime-target",
+            id: `pool:${name}`,
+            // The only locality this runtime offers: every pool is served by
+            // customer-enrolled runners. The field exists on RuntimeTarget so new
+            // localities (managed pools) are an additive change for callers.
+            locality: "customer-runner",
+            pool: name
+        };
+    }
+};

package/dist/test/plan.test.d.ts

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

package/dist/test/plan.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { agents } from "../agents.js";
+import { localFirst, planContinuation } from "../policy.js";
+import { targets } from "../targets.js";
+test("typed descriptors carry no magic strings", () => {
+    const target = targets.pool("eng-prod");
+    assert.deepEqual(target, {
+        kind: "runtime-target",
+        id: "pool:eng-prod",
+        locality: "customer-runner",
+        pool: "eng-prod"
+    });
+    assert.throws(() => targets.pool(""));
+    assert.deepEqual(agents.mock(), { kind: "mock" });
+    assert.deepEqual(agents.claudeCode({ version: ">=2.1" }), {
+        kind: "claude-code",
+        version: ">=2.1"
+    });
+    assert.deepEqual(agents.codex(), { kind: "codex" });
+    assert.deepEqual(agents.pi(), { kind: "pi" });
+});
+test("planner allows within policy and explains why", () => {
+    const decision = planContinuation(localFirst({ allowPools: ["eng-prod"] }), {
+        target: targets.pool("eng-prod"),
+        secrets: ["NPM_TOKEN"],
+        budget: {},
+        parallelism: 1
+    });
+    assert.equal(decision.decision, "continue");
+    assert.equal(decision.tier, "workspace");
+    assert.ok(decision.reasons.some((r) => r.includes("eng-prod")));
+    assert.ok(decision.reasons.some((r) => r.includes("NPM_TOKEN")));
+});
+test("planner fails closed on pool, budget, and parallelism violations", () => {
+    const policy = localFirst({
+        allowPools: ["eng-prod"],
+        denyPools: ["prod-db"],
+        maxSpendUsd: 10,
+        maxDurationMin: 30,
+        maxParallelRuns: 2
+    });
+    const denied = planContinuation(policy, {
+        target: targets.pool("untrusted"),
+        secrets: [],
+        budget: {},
+        parallelism: 1
+    });
+    assert.equal(denied.decision, "deny");
+    assert.ok(denied.reasons.some((r) => r.includes("not in the continuation allowlist")));
+    const hardDeny = planContinuation(policy, {
+        target: targets.pool("prod-db"),
+        secrets: [],
+        budget: {},
+        parallelism: 1
+    });
+    assert.equal(hardDeny.decision, "deny");
+    assert.ok(hardDeny.reasons.some((r) => r.includes("denied by continuation policy")));
+    const overBudget = planContinuation(policy, {
+        target: targets.pool("eng-prod"),
+        secrets: [],
+        budget: { maxSpendUsd: 100 },
+        parallelism: 1
+    });
+    assert.equal(overBudget.decision, "deny");
+    const overDuration = planContinuation(policy, {
+        target: targets.pool("eng-prod"),
+        secrets: [],
+        budget: { maxDurationMin: 120 },
+        parallelism: 1
+    });
+    assert.equal(overDuration.decision, "deny");
+    const tooParallel = planContinuation(policy, {
+        target: targets.pool("eng-prod"),
+        secrets: [],
+        budget: {},
+        parallelism: 3
+    });
+    assert.equal(tooParallel.decision, "deny");
+    assert.ok(tooParallel.reasons.some((r) => r.includes("parallel")));
+});
+test("default policy allows any pool with bounded fan-out", () => {
+    const policy = localFirst();
+    assert.equal(policy.maxParallelRuns, 4);
+    assert.equal(policy.disclosure, "minimal-context");
+    const decision = planContinuation(policy, {
+        target: targets.pool("anything"),
+        secrets: [],
+        budget: {},
+        parallelism: 4
+    });
+    assert.equal(decision.decision, "continue");
+});

package/dist/test/tools.test.d.ts

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

package/dist/test/tools.test.js

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { MODEL_FUSION_SCHEMA_BUNDLE_HASH } from "@fusionkit/protocol";
+import { handoff } from "../handoff.js";
+import { HandoffToolJournal } from "../tool-journal.js";
+import { targets } from "../targets.js";
+import { localFirst } from "../policy.js";
+function context(policy = localFirst()) {
+    // No network traffic occurs until a checkpoint or continuation moves data,
+    // so a dummy plane address is fine for pure tool/needs behavior.
+    return handoff({
+        workspace: ".",
+        plane: { url: "http://127.0.0.1:9", adminToken: "unused" },
+        policy
+    });
+}
+test("h.tools wraps execute, preserves results, and journals calls", async () => {
+    const h = context();
+    const seen = [];
+    const toolset = {
+        add: {
+            description: "adds two numbers",
+            execute: async (input) => {
+                seen.push(input);
+                return { sum: input.a + input.b };
+            }
+        },
+        schemaOnly: { description: "no execute; provider-executed" }
+    };
+    const wrapped = h.tools(toolset);
+    assert.equal(wrapped.schemaOnly, toolset.schemaOnly, "tools without execute pass through");
+    assert.equal(wrapped.add.description, "adds two numbers");
+    const result = await wrapped.add.execute({ a: 2, b: 3 });
+    assert.deepEqual(result, { sum: 5 });
+    assert.deepEqual(seen, [{ a: 2, b: 3 }]);
+    const events = h.trace().filter((e) => e.type === "tool.called");
+    assert.equal(events.length, 1);
+    const event = events[0];
+    assert.ok(event && event.type === "tool.called");
+    assert.equal(event.toolName, "add");
+    assert.equal(event.ok, true);
+    assert.match(event.inputHash, /^[0-9a-f]{64}$/);
+    assert.match(event.outputHash ?? "", /^[0-9a-f]{64}$/);
+});
+test("h.tools journals failures and rethrows them", async () => {
+    const h = context();
+    const wrapped = h.tools({
+        boom: {
+            execute: async () => {
+                throw new Error("tool exploded");
+            }
+        }
+    });
+    await assert.rejects(() => Promise.resolve(wrapped.boom.execute()), /tool exploded/);
+    const events = h.trace().filter((e) => e.type === "tool.called");
+    assert.equal(events.length, 1);
+    const event = events[0];
+    assert.ok(event && event.type === "tool.called");
+    assert.equal(event.ok, false);
+    assert.equal(event.outputHash, undefined);
+});
+test("h.needs is a pure policy check that records nothing", () => {
+    const h = context(localFirst({ allowPools: ["eng-prod"] }));
+    assert.equal(h.needs(targets.pool("eng-prod")), true);
+    assert.equal(h.needs(targets.pool("untrusted")), false);
+    assert.equal(h.trace().length, 0, "needs() must not pollute the trace");
+});
+test("h.summary recomputes counts from the trace", async () => {
+    const h = context();
+    const wrapped = h.tools({
+        noop: { execute: async () => "ok" }
+    });
+    await wrapped.noop.execute();
+    await wrapped.noop.execute();
+    h.plan(targets.pool("anywhere"));
+    const summary = await h.summary();
+    assert.equal(summary.toolCalls, 2);
+    assert.equal(summary.continuations.planned, 1);
+    assert.equal(summary.continuations.denied, 0);
+    assert.equal(summary.checkpoints, 0);
+    assert.deepEqual(summary.runs, []);
+});
+test("tool journal can append ToolExecutor results without replacing existing wrapper", () => {
+    const journal = new HandoffToolJournal();
+    const result = {
+        record: {
+            schema: "tool-execution-record.v1",
+            schema_version: "v1",
+            schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+            producer: "test",
+            producer_version: "0.1.0",
+            producer_git_sha: "0".repeat(40),
+            created_at: "2026-06-16T00:00:00.000Z",
+            execution_id: "exec_read",
+            plan_id: "plan_read",
+            status: "succeeded",
+            output_hash: "sha256:" + "a".repeat(64)
+        },
+        output: { ok: true },
+        deduped: false,
+        decision: { decision: "allow", reason: "test" }
+    };
+    journal.appendExecutionResult(result);
+    assert.equal(journal.length, 1);
+    assert.ok(journal.snapshot()?.hash.match(/^[0-9a-f]{64}$/));
+});

package/dist/test/triggers.test.d.ts

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

package/dist/test/triggers.test.js

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { defineHandoffConfig, handoff } from "../handoff.js";
+import { localFirst } from "../policy.js";
+import { targets } from "../targets.js";
+import { evaluateTriggers, triggers } from "../triggers.js";
+function context(policy = localFirst()) {
+    return handoff({
+        workspace: ".",
+        plane: { url: "http://127.0.0.1:9", adminToken: "unused" },
+        policy
+    });
+}
+test("evaluateTriggers fires deterministically against observable state", () => {
+    const list = [
+        triggers.userRequested(),
+        triggers.toolFailed(),
+        triggers.slowTools({ thresholdMs: 1000 }),
+        triggers.modelEscalated()
+    ];
+    const idle = evaluateTriggers(list, {
+        userRequested: false,
+        toolFailures: 0,
+        totalToolDurationMs: 0,
+        modelEscalations: 0
+    });
+    assert.deepEqual(idle, []);
+    const busy = evaluateTriggers(list, {
+        userRequested: true,
+        toolFailures: 2,
+        totalToolDurationMs: 5000,
+        modelEscalations: 1
+    });
+    assert.deepEqual(busy.map((f) => f.trigger.id).sort(), ["model-escalated", "slow-tools", "tool-failed", "user-requested"]);
+    for (const fired of busy) {
+        assert.ok(fired.reason.length > 0, "every fired trigger explains itself");
+    }
+});
+test("needs() honors continueWhen: allowed pool but no fired trigger means no", async () => {
+    const h = context(localFirst({
+        allowPools: ["eng-prod"],
+        continueWhen: [triggers.toolFailed(), triggers.userRequested()]
+    }));
+    const target = targets.pool("eng-prod");
+    assert.equal(h.needs(target), false, "no trigger has fired yet");
+    assert.deepEqual(h.firedTriggers(), []);
+    // A journaled tool failure flips the answer.
+    const tools = h.tools({
+        flaky: {
+            execute: async () => {
+                throw new Error("network blip");
+            }
+        }
+    });
+    await assert.rejects(() => Promise.resolve(tools.flaky.execute()));
+    assert.equal(h.needs(target), true);
+    assert.equal(h.firedTriggers()[0]?.trigger.id, "tool-failed");
+    // Policy still fails closed on a disallowed pool, triggers or not.
+    assert.equal(h.needs(targets.pool("untrusted")), false);
+});
+test("requestContinuation is the explicit user gesture", () => {
+    const h = context(localFirst({ continueWhen: [triggers.userRequested()] }));
+    assert.equal(h.needs(targets.pool("anywhere")), false);
+    h.requestContinuation("user closed the laptop lid");
+    assert.equal(h.needs(targets.pool("anywhere")), true);
+    const requested = h
+        .trace()
+        .find((event) => event.type === "continuation.requested");
+    assert.ok(requested && requested.type === "continuation.requested");
+    assert.equal(requested.reason, "user closed the laptop lid");
+});
+test("model escalation decisions feed triggers and the trace", async () => {
+    const h = context(localFirst({ continueWhen: [triggers.modelEscalated()] }));
+    assert.equal(h.needs(targets.pool("anywhere")), false);
+    h.noteModelDecision({
+        model: "local-small",
+        route: "local",
+        escalated: false,
+        reason: "local-first policy"
+    });
+    assert.equal(h.needs(targets.pool("anywhere")), false, "local routes do not fire");
+    h.noteModelDecision({
+        model: "cloud-frontier",
+        route: "cloud",
+        escalated: true,
+        reason: "local model failed (context-overflow)"
+    });
+    assert.equal(h.needs(targets.pool("anywhere")), true);
+    const summary = await h.summary();
+    assert.deepEqual(summary.modelRoutes, { local: 1, cloud: 1, escalations: 1 });
+});
+test("defineHandoffConfig supplies defaults; explicit config wins", () => {
+    defineHandoffConfig({
+        plane: { url: "http://127.0.0.1:9", adminToken: "from-defaults" },
+        policy: localFirst({ allowPools: ["from-defaults"] })
+    });
+    try {
+        const fromDefaults = handoff({ workspace: "." });
+        assert.equal(fromDefaults.needs(targets.pool("from-defaults")), true);
+        assert.equal(fromDefaults.needs(targets.pool("other")), false);
+        const explicit = handoff({
+            workspace: ".",
+            policy: localFirst({ allowPools: ["explicit"] })
+        });
+        assert.equal(explicit.needs(targets.pool("explicit")), true);
+        assert.equal(explicit.needs(targets.pool("from-defaults")), false);
+    }
+    finally {
+        defineHandoffConfig({});
+    }
+});
+test("handoff without a plane anywhere fails loudly", () => {
+    assert.throws(() => handoff({ workspace: "." }), /requires a plane/);
+});

package/dist/tool-journal.d.ts

@@ -0,0 +1,13 @@
+import type { ToolCallRecord, ToolExecutionResult } from "@fusionkit/protocol";
+export declare class HandoffToolJournal {
+    private readonly entries;
+    get length(): number;
+    append(record: ToolCallRecord): void;
+    appendExecutionResult(result: ToolExecutionResult): void;
+    failureCount(): number;
+    totalDurationMs(): number;
+    snapshot(): {
+        blob: Buffer;
+        hash: string;
+    } | undefined;
+}

package/dist/tool-journal.js

@@ -0,0 +1,37 @@
+import { canonicalize, PROTOCOL_VERSIONS, sha256Hex } from "@fusionkit/protocol";
+export class HandoffToolJournal {
+    entries = [];
+    get length() {
+        return this.entries.length;
+    }
+    append(record) {
+        this.entries.push(record);
+    }
+    appendExecutionResult(result) {
+        this.entries.push({
+            seq: this.entries.length + 1,
+            ts: result.record.created_at,
+            toolName: result.record.execution_id,
+            input: { plan_id: result.record.plan_id },
+            ...(result.output !== undefined ? { output: result.output } : {}),
+            ...(result.record.error?.message ? { error: result.record.error.message } : {}),
+            durationMs: 0
+        });
+    }
+    failureCount() {
+        return this.entries.filter((entry) => entry.error !== undefined).length;
+    }
+    totalDurationMs() {
+        return this.entries.reduce((total, entry) => total + entry.durationMs, 0);
+    }
+    snapshot() {
+        if (this.entries.length === 0)
+            return undefined;
+        const journal = {
+            version: PROTOCOL_VERSIONS.toolJournal,
+            entries: [...this.entries]
+        };
+        const blob = Buffer.from(canonicalize(journal), "utf8");
+        return { blob, hash: sha256Hex(blob) };
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,22 @@
+import type { ToolCallRecord } from "@fusionkit/protocol";
+/**
+ * Structural stand-in for an AI SDK tool (or any tool object). The wrapper
+ * only cares whether an `execute` function is present at runtime, so the
+ * constraint is deliberately loose: concrete tool types (including the `ai`
+ * package's `Tool`) remain assignable without this package depending on it.
+ */
+export type ToolLike = object;
+export type ToolCallObservation = {
+    record: ToolCallRecord;
+    inputHash: string;
+    outputHash?: string;
+    ok: boolean;
+};
+/**
+ * Wrap a toolset so every invocation is journaled: raw input/output go to
+ * the journal (carried as content-addressed semantic state at the next
+ * checkpoint), and the observer receives hashes for the local trace.
+ * Everything else about each tool — description, schema, identity — is
+ * preserved, so the wrapped set drops into generateText unchanged.
+ */
+export declare function wrapTools<T extends Record<string, ToolLike>>(toolset: T, nextSeq: () => number, observe: (observation: ToolCallObservation) => void): T;