@fusionkit/handoff 0.1.0

package/dist/agents.d.ts

@@ -0,0 +1,21 @@
+import type { AgentSpec } from "@fusionkit/protocol";
+export declare const agents: {
+    claudeCode(options?: {
+        version?: string;
+    }): AgentSpec;
+    codex(options?: {
+        version?: string;
+    }): AgentSpec;
+    /**
+     * Pi: a host-runtime coding harness driven through the AI SDK harness
+     * backend. Runs only on a session tier that registers the pi binding
+     * (the swarm's local-model workers); never spawned as a vendor CLI.
+     */
+    pi(options?: {
+        version?: string;
+    }): AgentSpec;
+    /** Built-in mock harness: runs without vendor CLIs or API keys. */
+    mock(): AgentSpec;
+    /** One governed shell command; the task prompt is the command. */
+    command(): AgentSpec;
+};

package/dist/agents.js

@@ -0,0 +1,33 @@
+/**
+ * Typed agent constructors, mirroring the AI SDK provider pattern:
+ * `agents.claudeCode()` instead of `"claude-code"`. Strings remain
+ * acceptable as CLI aliases; the SDK contract is the protocol's
+ * `AgentSpec` — there is no separate descriptor shape to convert.
+ */
+function spec(kind, version) {
+    return { kind, ...(version ? { version } : {}) };
+}
+export const agents = {
+    claudeCode(options = {}) {
+        return spec("claude-code", options.version);
+    },
+    codex(options = {}) {
+        return spec("codex", options.version);
+    },
+    /**
+     * Pi: a host-runtime coding harness driven through the AI SDK harness
+     * backend. Runs only on a session tier that registers the pi binding
+     * (the swarm's local-model workers); never spawned as a vendor CLI.
+     */
+    pi(options = {}) {
+        return spec("pi", options.version);
+    },
+    /** Built-in mock harness: runs without vendor CLIs or API keys. */
+    mock() {
+        return spec("mock");
+    },
+    /** One governed shell command; the task prompt is the command. */
+    command() {
+        return spec("command");
+    }
+};

package/dist/checkpoint-manager.d.ts

@@ -0,0 +1,14 @@
+import type { Checkpoint } from "@fusionkit/protocol";
+import type { CapturedWorkspace } from "@fusionkit/workspace";
+export declare class HandoffCheckpointManager {
+    private readonly history;
+    get count(): number;
+    snapshot(): Checkpoint[];
+    create(input: {
+        captured: CapturedWorkspace;
+        message?: string;
+        transcriptHash?: string;
+        toolJournalHash?: string;
+        remember?: boolean;
+    }): Checkpoint;
+}

package/dist/checkpoint-manager.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { PROTOCOL_VERSIONS } from "@fusionkit/protocol";
+export class HandoffCheckpointManager {
+    history = [];
+    get count() {
+        return this.history.length;
+    }
+    snapshot() {
+        return [...this.history];
+    }
+    create(input) {
+        const semantic = {
+            ...(input.transcriptHash ? { transcriptHash: input.transcriptHash } : {}),
+            ...(input.toolJournalHash ? { toolJournalHash: input.toolJournalHash } : {}),
+            ...(input.message ? { note: input.message } : {})
+        };
+        const hasSemantic = input.transcriptHash !== undefined || input.toolJournalHash !== undefined;
+        const parent = this.history.at(-1)?.checkpointId;
+        const checkpoint = {
+            version: PROTOCOL_VERSIONS.checkpoint,
+            checkpointId: `chk_${randomUUID()}`,
+            createdAt: new Date().toISOString(),
+            tier: "workspace",
+            ...(input.message ? { message: input.message } : {}),
+            ...(hasSemantic ? { semantic } : {}),
+            workspace: input.captured.manifest,
+            ...(parent ? { parent } : {})
+        };
+        if (input.remember !== false)
+            this.history.push(checkpoint);
+        return checkpoint;
+    }
+}

package/dist/defaults.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared polling and identity defaults used by Handoff.stream and
+ * HandoffRun.wait so the two code paths cannot drift apart.
+ *
+ * The plane API is deliberately poll-based (plain, stateless HTTP): these
+ * intervals are the supported transport, and both consumers accept
+ * per-call overrides (`pollMs` / `timeoutMs`).
+ */
+/** Interval between status polls. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 300;
+/** Default ceiling for HandoffRun.wait. */
+export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
+/** Default ceiling for Handoff.stream. */
+export declare const DEFAULT_STREAM_TIMEOUT_MS: number;
+/** Actor id recorded when no actor is configured and USER is unset. */
+export declare const DEFAULT_ACTOR_ID = "developer";
+/** Concurrent blob uploads during workspace checkpointing. */
+export declare const BLOB_UPLOAD_CONCURRENCY = 4;

package/dist/defaults.js

@@ -0,0 +1,18 @@
+/**
+ * Shared polling and identity defaults used by Handoff.stream and
+ * HandoffRun.wait so the two code paths cannot drift apart.
+ *
+ * The plane API is deliberately poll-based (plain, stateless HTTP): these
+ * intervals are the supported transport, and both consumers accept
+ * per-call overrides (`pollMs` / `timeoutMs`).
+ */
+/** Interval between status polls. */
+export const DEFAULT_POLL_INTERVAL_MS = 300;
+/** Default ceiling for HandoffRun.wait. */
+export const DEFAULT_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+/** Default ceiling for Handoff.stream. */
+export const DEFAULT_STREAM_TIMEOUT_MS = 10 * 60 * 1000;
+/** Actor id recorded when no actor is configured and USER is unset. */
+export const DEFAULT_ACTOR_ID = "developer";
+/** Concurrent blob uploads during workspace checkpointing. */
+export const BLOB_UPLOAD_CONCURRENCY = 4;

package/dist/handoff.d.ts

@@ -0,0 +1,303 @@
+import type { ActorRef, AgentSpec, ArtifactKind, BudgetSpec, ChainedEvent, Checkpoint, CheckpointTier, DisclosureReport, ExecutionSpec, HandoffEnvelope, RunStatus, SessionIsolation } from "@fusionkit/protocol";
+import { PlaneClient } from "@fusionkit/sdk";
+import type { PullResult } from "@fusionkit/workspace";
+import type { IsolationStrategy } from "./isolation.js";
+import type { ContinuationPolicy, PlanningDecision } from "./policy.js";
+import type { FiredTrigger } from "./triggers.js";
+import type { ReviewResult, ReviewStrategy } from "./review.js";
+import { HandoffRun } from "./run.js";
+import type { RuntimeTarget } from "./targets.js";
+import type { ToolLike } from "./tools.js";
+export type HandoffConfig = {
+    /** Path to the local git workspace this work starts in. */
+    workspace: string;
+    /** Plane connection: an existing client or url + admin token. */
+    plane: PlaneClient | {
+        url: string;
+        adminToken: string;
+    };
+    /** Who is asking. Defaults to the OS user. */
+    actor?: ActorRef;
+    /** Default agent for continuations. Defaults to the mock harness. */
+    agent?: AgentSpec;
+    /** Client-side continuation policy. Defaults to `localFirst()`. */
+    policy?: ContinuationPolicy;
+    /** Secret names continuations may request by default. */
+    secrets?: string[];
+    /** Hosts continuations may reach by default (deny-by-default egress). */
+    allowHosts?: string[];
+    /** Untracked-file glob allowlist applied at workspace capture. */
+    allowUntracked?: string[];
+    budget?: BudgetSpec;
+};
+export type ContinueOptions = {
+    task: string;
+    agent?: AgentSpec;
+    /** Durable machine intent. Defaults from the selected agent and task. */
+    execution?: ExecutionSpec;
+    reason?: string;
+    secrets?: string[];
+    allowHosts?: string[];
+    /** Free-form transcript to carry as semantic state. */
+    transcript?: string;
+    /** Reuse an existing checkpoint instead of capturing a fresh one. */
+    checkpoint?: Checkpoint;
+    budget?: BudgetSpec;
+    /** How results land at pull time. Defaults to divergence-safe auto. */
+    isolate?: IsolationStrategy;
+    /** Requested session isolation on the runner. Defaults to "process". */
+    session?: SessionIsolation;
+};
+export type ParallelOptions = Omit<ContinueOptions, "task">;
+/**
+ * Register provider-style defaults once; subsequent `handoff({...})` calls
+ * merge them under their explicit config (explicit values win):
+ *
+ *   defineHandoffConfig({ plane, agent: agents.claudeCode(), policy: localFirst() });
+ *   const h = handoff({ workspace: "." });
+ */
+export declare function defineHandoffConfig(defaults: Partial<HandoffConfig>): Partial<HandoffConfig>;
+/** Configuration accepted by handoff(): defaults can supply everything but the workspace. */
+export type HandoffInit = Partial<HandoffConfig> & {
+    workspace: string;
+};
+export type HandoffTraceEvent = {
+    type: "checkpoint.created";
+    ts: string;
+    checkpointId: string;
+    tier: CheckpointTier;
+    message?: string;
+} | {
+    type: "continuation.planned";
+    ts: string;
+    decision: PlanningDecision["decision"];
+    target: string;
+    reasons: string[];
+} | {
+    type: "continuation.requested";
+    ts: string;
+    reason?: string;
+} | {
+    type: "envelope.created";
+    ts: string;
+    envelopeId: string;
+    envelopeHash: string;
+    target: string;
+} | {
+    type: "run.requested";
+    ts: string;
+    runId: string;
+    status: RunStatus;
+    task: string;
+} | {
+    type: "run.terminal";
+    ts: string;
+    runId: string;
+    status: RunStatus;
+} | {
+    type: "results.pulled";
+    ts: string;
+    runId: string;
+    mode: PullResult["mode"];
+} | {
+    type: "tool.called";
+    ts: string;
+    toolName: string;
+    inputHash: string;
+    outputHash?: string;
+    ok: boolean;
+    durationMs: number;
+} | {
+    type: "model.routed";
+    ts: string;
+    model: string;
+    route: "local" | "cloud";
+    escalated: boolean;
+    reason: string;
+};
+/** A model routing decision reported by h.model (see withModel). */
+export type ModelDecision = {
+    model: string;
+    route: "local" | "cloud";
+    escalated: boolean;
+    reason: string;
+};
+/** Where the work stands: derivable, recomputed, never source of truth. */
+export type HandoffSummary = {
+    workspace: string;
+    checkpoints: number;
+    toolCalls: number;
+    continuations: {
+        planned: number;
+        denied: number;
+        requested: number;
+    };
+    modelRoutes: {
+        local: number;
+        cloud: number;
+        escalations: number;
+    };
+    runs: {
+        runId: string;
+        task: string;
+        target: string;
+        status: RunStatus;
+    }[];
+    pulls: number;
+};
+/** Live event stream over a set of runs (see Handoff.stream). */
+export type HandoffStreamEvent = {
+    type: "run.status";
+    runId: string;
+    status: RunStatus;
+} | {
+    type: "run.event";
+    runId: string;
+    event: ChainedEvent;
+} | {
+    type: "artifact.ready";
+    runId: string;
+    kind: ArtifactKind;
+    hash: string;
+} | {
+    type: "run.terminal";
+    runId: string;
+    status: RunStatus;
+};
+/**
+ * The continuation context. One object that can checkpoint local work,
+ * plan a continuation under policy, hand the work to a governed runner
+ * pool, and pull the results (and the receipts) back.
+ *
+ * Built entirely on Warrant primitives: every continuation is a signed
+ * run contract, every result is an offline-verifiable receipt, and the
+ * envelope hash is pinned inside the contract.
+ */
+export declare class Handoff {
+    private readonly client;
+    private readonly workspaceDir;
+    private readonly actor;
+    private readonly agent;
+    private readonly policy;
+    private readonly secrets;
+    private readonly allowHosts;
+    private readonly allowUntracked;
+    private readonly budget;
+    private readonly traceLog;
+    private readonly toolJournal;
+    private readonly requestedRuns;
+    private readonly checkpointsState;
+    private lastEnvelopeValue?;
+    private userRequestedContinuation;
+    private modelEscalationCount;
+    constructor(init: HandoffInit);
+    /** The local workspace this context is bound to. */
+    get workspacePath(): string;
+    /** Local trace: every planning, envelope, run, pull, and tool decision. */
+    trace(): HandoffTraceEvent[];
+    /**
+     * Wrap an AI SDK-shaped toolset (any tools with `execute`) so every call
+     * is journaled. The journal travels as content-addressed semantic state
+     * in the next checkpoint, so a continuation carries what the loop's tools
+     * saw and did. Tools still execute locally, in the caller's process —
+     * this is capture, not orchestration. For governed *remote* execution,
+     * use @fusionkit/adapter-ai-sdk's remoteTools instead.
+     */
+    tools<T extends Record<string, ToolLike>>(toolset: T): T;
+    /** Snapshot of the observable state that continuation triggers evaluate. */
+    private triggerState;
+    /** Which of the policy's continueWhen triggers currently fire, and why. */
+    firedTriggers(): FiredTrigger[];
+    /**
+     * Explicitly request continuation (the user gesture). Makes
+     * triggers.userRequested() fire on the next needs() check.
+     */
+    requestContinuation(reason?: string): void;
+    /**
+     * Report a model routing decision (wired up by withModel from
+     * @fusionkit/adapter-ai-sdk). Escalations feed triggers.modelEscalated().
+     */
+    noteModelDecision(decision: ModelDecision): void;
+    /**
+     * Deterministic check: should this work continue on the target?
+     * True when the continuation policy permits the target AND — if the
+     * policy declares continueWhen triggers — at least one trigger fires
+     * against observable context state (tool failures, slow tools, explicit
+     * requests, model escalations). Pure: records nothing, moves nothing.
+     */
+    needs(target: RuntimeTarget, options?: Partial<ContinueOptions> & {
+        parallelism?: number;
+    }): boolean;
+    /** Recomputed view over the trace plus live run statuses from the plane. */
+    summary(): Promise<HandoffSummary>;
+    /** Every checkpoint this context created, oldest first (lineage intact). */
+    checkpoints(): Checkpoint[];
+    /**
+     * Live, typed event stream over a set of runs: status transitions, every
+     * appended chained event, artifact availability, and terminal states.
+     * Completes when all runs are terminal.
+     */
+    stream(runs: HandoffRun[], options?: {
+        pollMs?: number;
+        timeoutMs?: number;
+    }): AsyncGenerator<HandoffStreamEvent, void, void>;
+    /** The most recent envelope this context produced. */
+    lastEnvelope(): HandoffEnvelope | undefined;
+    private record;
+    private capture;
+    /**
+     * Upload the captured workspace with bounded concurrency. Blobs are
+     * content-addressed and idempotent, so a partial failure simply leaves
+     * already-uploaded blobs in place — retried checkpoints reuse them and
+     * the plane's reference-counting GC reclaims any that end up orphaned.
+     */
+    private uploadCapture;
+    /** Snapshot the tool journal as a content-addressed blob payload. */
+    private journalSnapshot;
+    /**
+     * Capture resumable state: the workspace manifest (git base ref, dirty
+     * diff, allowlisted untracked files) plus an optional transcript as
+     * semantic state. Content moves to the plane blob store; secret-pattern
+     * files are denied capture and the denial is recorded in the manifest.
+     */
+    checkpoint(message?: string, options?: {
+        transcript?: string;
+    }): Promise<Checkpoint>;
+    /** Deterministic continuation planning; never moves anything. */
+    plan(target: RuntimeTarget, options?: Partial<ContinueOptions>, parallelism?: number): PlanningDecision;
+    private buildEnvelope;
+    private buildRunRequest;
+    /**
+     * "What would move?" — the disclosure report for a continuation,
+     * computed without uploading, issuing, or executing anything.
+     */
+    dryRun(target: RuntimeTarget, options: ContinueOptions): Promise<{
+        report: DisclosureReport;
+        envelope: HandoffEnvelope;
+        decision: PlanningDecision;
+    }>;
+    /**
+     * Continue this work in the target pool: plan under policy (fail
+     * closed), checkpoint, wrap the continuation in a content-addressed
+     * envelope, and submit it as a governed run whose signed contract pins
+     * the envelope hash.
+     */
+    continueIn(target: RuntimeTarget, options: ContinueOptions): Promise<HandoffRun>;
+    private submit;
+    /**
+     * Fan the same checkpoint out across several isolated attempts. Each
+     * attempt is its own governed run with its own contract, envelope, and
+     * receipt; outputs land on separate branches at pull time.
+     */
+    parallel(tasks: string[], target: RuntimeTarget, options?: ParallelOptions): Promise<HandoffRun[]>;
+    /** Compare fan-out attempts with a typed, deterministic strategy. */
+    review(runs: HandoffRun[], options?: {
+        choose?: ReviewStrategy;
+    }): Promise<ReviewResult>;
+}
+/**
+ * Create a continuation context bound to a workspace and a plane. Anything
+ * not supplied here falls back to defaults registered via
+ * defineHandoffConfig; the workspace is always explicit.
+ */
+export declare function handoff(init: HandoffInit): Handoff;