@fusionkit/handoff 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,69 @@
+import type { CheckpointTier, DisclosureMode } from "@fusionkit/protocol";
+import type { RuntimeTarget } from "./targets.js";
+import type { Trigger } from "./triggers.js";
+/**
+ * Client-side continuation policy. This is the SDK's own fail-closed gate,
+ * evaluated before anything moves; the plane's org policy is still
+ * evaluated independently at contract time. Both must pass.
+ */
+export type ContinuationPolicy = {
+    kind: "continuation-policy";
+    id: "local-first";
+    /** Pools work may continue to. Undefined means any pool. */
+    allowPools?: string[];
+    /** Pools that are always denied, evaluated before the allowlist. */
+    denyPools?: string[];
+    maxSpendUsd?: number;
+    maxDurationMin?: number;
+    /** Ceiling for `parallel(...)` fan-out. */
+    maxParallelRuns: number;
+    disclosure: DisclosureMode;
+    /**
+     * Conditions under which `h.needs(target)` reports that work should
+     * continue. Empty or absent means "needs" reduces to "allowed by policy".
+     */
+    continueWhen?: Trigger[];
+};
+export type LocalFirstOptions = {
+    allowPools?: string[];
+    denyPools?: string[];
+    maxSpendUsd?: number;
+    maxDurationMin?: number;
+    maxParallelRuns?: number;
+    disclosure?: DisclosureMode;
+    continueWhen?: Trigger[];
+};
+/**
+ * localFirst() defaults: a modest fan-out ceiling and the most conservative
+ * disclosure mode. Orgs override per policy via LocalFirstOptions.
+ */
+export declare const DEFAULT_MAX_PARALLEL_RUNS = 4;
+export declare const DEFAULT_DISCLOSURE: "minimal-context";
+/**
+ * Local-first: work stays local until the app explicitly continues it,
+ * and continuation is allowed only within the configured bounds.
+ */
+export declare function localFirst(options?: LocalFirstOptions): ContinuationPolicy;
+/** Deterministic, explainable continuation-planning outcome. */
+export type PlanningDecision = {
+    decision: "continue" | "deny";
+    target: RuntimeTarget;
+    tier: CheckpointTier;
+    disclosure: DisclosureMode;
+    reasons: string[];
+};
+export type PlanInput = {
+    target: RuntimeTarget;
+    secrets: string[];
+    budget: {
+        maxSpendUsd?: number;
+        maxDurationMin?: number;
+    };
+    parallelism: number;
+};
+/**
+ * The v1 planner is deterministic policy logic, not a model. Every
+ * decision carries human-readable reasons so the trace can explain why
+ * the runtime boundary changed (or refused to).
+ */
+export declare function planContinuation(policy: ContinuationPolicy, input: PlanInput): PlanningDecision;

package/dist/policy.js

@@ -0,0 +1,79 @@
+/**
+ * localFirst() defaults: a modest fan-out ceiling and the most conservative
+ * disclosure mode. Orgs override per policy via LocalFirstOptions.
+ */
+export const DEFAULT_MAX_PARALLEL_RUNS = 4;
+export const DEFAULT_DISCLOSURE = "minimal-context";
+/**
+ * Local-first: work stays local until the app explicitly continues it,
+ * and continuation is allowed only within the configured bounds.
+ */
+export function localFirst(options = {}) {
+    return {
+        kind: "continuation-policy",
+        id: "local-first",
+        ...(options.allowPools ? { allowPools: options.allowPools } : {}),
+        ...(options.denyPools ? { denyPools: options.denyPools } : {}),
+        ...(options.maxSpendUsd !== undefined
+            ? { maxSpendUsd: options.maxSpendUsd }
+            : {}),
+        ...(options.maxDurationMin !== undefined
+            ? { maxDurationMin: options.maxDurationMin }
+            : {}),
+        maxParallelRuns: options.maxParallelRuns ?? DEFAULT_MAX_PARALLEL_RUNS,
+        disclosure: options.disclosure ?? DEFAULT_DISCLOSURE,
+        ...(options.continueWhen ? { continueWhen: options.continueWhen } : {})
+    };
+}
+/**
+ * The v1 planner is deterministic policy logic, not a model. Every
+ * decision carries human-readable reasons so the trace can explain why
+ * the runtime boundary changed (or refused to).
+ */
+export function planContinuation(policy, input) {
+    const denials = [];
+    const pool = input.target.pool;
+    if (policy.denyPools?.includes(pool)) {
+        denials.push(`pool "${pool}" is denied by continuation policy`);
+    }
+    if (policy.allowPools && !policy.allowPools.includes(pool)) {
+        denials.push(`pool "${pool}" is not in the continuation allowlist`);
+    }
+    // An omitted budget field means "inherit the policy ceiling": the request
+    // is still bounded, because the plane enforces budget ceilings again at
+    // contract issuance and the runner applies a hard session timeout. Only
+    // an explicit value above the ceiling is a denial.
+    if (policy.maxSpendUsd !== undefined &&
+        (input.budget.maxSpendUsd ?? 0) > policy.maxSpendUsd) {
+        denials.push(`requested budget $${input.budget.maxSpendUsd} exceeds policy ceiling $${policy.maxSpendUsd}`);
+    }
+    if (policy.maxDurationMin !== undefined &&
+        (input.budget.maxDurationMin ?? 0) > policy.maxDurationMin) {
+        denials.push(`requested duration ${input.budget.maxDurationMin}m exceeds policy ceiling ${policy.maxDurationMin}m`);
+    }
+    if (input.parallelism > policy.maxParallelRuns) {
+        denials.push(`requested ${input.parallelism} parallel runs exceeds policy ceiling ${policy.maxParallelRuns}`);
+    }
+    if (denials.length > 0) {
+        return {
+            decision: "deny",
+            target: input.target,
+            tier: "workspace",
+            disclosure: policy.disclosure,
+            reasons: denials
+        };
+    }
+    return {
+        decision: "continue",
+        target: input.target,
+        tier: "workspace",
+        disclosure: policy.disclosure,
+        reasons: [
+            `pool "${pool}" is allowed`,
+            `disclosure mode "${policy.disclosure}"`,
+            input.secrets.length > 0
+                ? `secret release requested: ${input.secrets.join(", ")} (subject to org policy)`
+                : "no secrets requested"
+        ]
+    };
+}

package/dist/review.d.ts

@@ -0,0 +1,57 @@
+import type { ReceiptBundle } from "@fusionkit/protocol";
+import { PlaneClient } from "@fusionkit/sdk";
+import { HandoffRun } from "./run.js";
+/**
+ * Typed review strategies for choosing among fan-out attempts.
+ * Deterministic and explainable, like the planner.
+ */
+export type ReviewStrategy = {
+    kind: "review-strategy";
+    id: "smallest-diff" | "first-completed" | "tests-pass-smallest-diff";
+};
+export declare const reviewStrategies: {
+    /** Prefer the completed attempt with the smallest output diff. */
+    smallestDiff(): ReviewStrategy;
+    /** Prefer the completed attempt that finished first. */
+    firstCompleted(): ReviewStrategy;
+    /**
+     * The spec's flagship strategy: among attempts whose harness exited
+     * cleanly (the "tests pass" signal at the session boundary), prefer the
+     * smallest output diff.
+     */
+    testsPassSmallestDiff(): ReviewStrategy;
+};
+/** Deterministic, evidence-derived comparison data for one attempt. */
+export type Scorecard = {
+    status: ReceiptBundle["receipt"]["status"];
+    exitCode?: number;
+    diffBytes: number;
+    filesChanged: number;
+    durationMs: number;
+    eventCount: number;
+    blockedEgressAttempts: number;
+    secretsReleased: number;
+};
+export type ReviewedRun = {
+    run: HandoffRun;
+    bundle: ReceiptBundle;
+    scorecard: Scorecard;
+    /** Kept for convenience; equals scorecard.diffBytes. */
+    diffBytes: number;
+    endedAt: string;
+};
+export type ReviewResult = {
+    chosen: ReviewedRun;
+    candidates: ReviewedRun[];
+    strategy: ReviewStrategy;
+    reason: string;
+};
+/**
+ * Build the deterministic, evidence-derived scorecard for one run from its
+ * receipt bundle and output diff size. Exposed so adapters that judge runs
+ * outside the fan-out review path (e.g. the swarm tools, where a cloud model
+ * judges each worker) consume the exact same deterministic evidence the
+ * review strategies do, rather than reconstructing it.
+ */
+export declare function scorecardFor(bundle: ReceiptBundle, diffBytes: number): Scorecard;
+export declare function reviewRuns(client: PlaneClient, runs: HandoffRun[], strategy: ReviewStrategy): Promise<ReviewResult>;

package/dist/review.js

@@ -0,0 +1,110 @@
+export const reviewStrategies = {
+    /** Prefer the completed attempt with the smallest output diff. */
+    smallestDiff() {
+        return { kind: "review-strategy", id: "smallest-diff" };
+    },
+    /** Prefer the completed attempt that finished first. */
+    firstCompleted() {
+        return { kind: "review-strategy", id: "first-completed" };
+    },
+    /**
+     * The spec's flagship strategy: among attempts whose harness exited
+     * cleanly (the "tests pass" signal at the session boundary), prefer the
+     * smallest output diff.
+     */
+    testsPassSmallestDiff() {
+        return { kind: "review-strategy", id: "tests-pass-smallest-diff" };
+    }
+};
+/**
+ * Build the deterministic, evidence-derived scorecard for one run from its
+ * receipt bundle and output diff size. Exposed so adapters that judge runs
+ * outside the fan-out review path (e.g. the swarm tools, where a cloud model
+ * judges each worker) consume the exact same deterministic evidence the
+ * review strategies do, rather than reconstructing it.
+ */
+export function scorecardFor(bundle, diffBytes) {
+    const { receipt, events } = bundle;
+    // Distinct files, not raw event count: a file touched repeatedly during a
+    // session still counts once. exitCode is the session's final command —
+    // the run's overall outcome by harness convention; per-command results
+    // remain available in the event chain.
+    const changedPaths = new Set();
+    let exitCode;
+    for (const entry of events) {
+        if (entry.event.type === "file.changed")
+            changedPaths.add(entry.event.path);
+        if (entry.event.type === "command.executed")
+            exitCode = entry.event.exitCode;
+    }
+    const filesChanged = changedPaths.size;
+    return {
+        status: receipt.status,
+        ...(exitCode !== undefined ? { exitCode } : {}),
+        diffBytes,
+        filesChanged,
+        durationMs: new Date(receipt.endedAt).getTime() - new Date(receipt.startedAt).getTime(),
+        eventCount: receipt.eventCount,
+        blockedEgressAttempts: receipt.networkAccessed.filter((record) => record.decision === "blocked").length,
+        secretsReleased: receipt.secretsReleased.length
+    };
+}
+export async function reviewRuns(client, runs, strategy) {
+    const candidates = [];
+    const skipped = [];
+    for (const run of runs) {
+        const status = await run.status();
+        if (status !== "completed") {
+            skipped.push({ runId: run.runId, status });
+            continue;
+        }
+        const bundle = await run.receipt();
+        const diffHash = bundle.receipt.workspaceOut.diffHash;
+        const diffBytes = diffHash ? (await client.getBlob(diffHash)).length : 0;
+        candidates.push({
+            run,
+            bundle,
+            scorecard: scorecardFor(bundle, diffBytes),
+            diffBytes,
+            endedAt: bundle.receipt.endedAt
+        });
+    }
+    if (candidates.length === 0) {
+        const detail = skipped
+            .map((entry) => `${entry.runId}: ${entry.status}`)
+            .join(", ");
+        throw new Error(`no completed runs to review${detail ? ` (${detail})` : ""}`);
+    }
+    let chosen;
+    let reason;
+    switch (strategy.id) {
+        case "smallest-diff": {
+            chosen = candidates.reduce((a, b) => (b.diffBytes < a.diffBytes ? b : a));
+            reason = `smallest output diff (${chosen.diffBytes} bytes) among ${candidates.length} completed attempt(s)`;
+            break;
+        }
+        case "first-completed": {
+            chosen = candidates.reduce((a, b) => new Date(b.endedAt).getTime() < new Date(a.endedAt).getTime() ? b : a);
+            reason = `first attempt to complete (${chosen.endedAt}) among ${candidates.length} completed attempt(s)`;
+            break;
+        }
+        case "tests-pass-smallest-diff": {
+            // This strategy's definition of "tests pass" IS harness exit 0 — that
+            // is the session-boundary signal the spec names. Agents with custom
+            // success semantics (multiple commands, non-zero success codes) pick
+            // their winner directly from candidates' scorecards/events instead.
+            const passing = candidates.filter((candidate) => candidate.scorecard.exitCode === 0);
+            if (passing.length === 0) {
+                throw new Error("no attempt passed (harness exit 0) to review");
+            }
+            chosen = passing.reduce((a, b) => (b.diffBytes < a.diffBytes ? b : a));
+            reason = `harness exited 0 and smallest output diff (${chosen.diffBytes} bytes) among ${passing.length} passing attempt(s)`;
+            break;
+        }
+        default: {
+            const exhausted = strategy.id;
+            throw new Error(`unknown review strategy: ${String(exhausted)}`);
+        }
+    }
+    return { chosen, candidates, strategy, reason };
+}

package/dist/run-executor.d.ts

@@ -0,0 +1,76 @@
+import type { ActorRef, BundleVerification, ExecutionSpec, ReceiptBundle, RunStatus, SessionIsolation } from "@fusionkit/protocol";
+import type { PlaneClient } from "@fusionkit/sdk";
+import type { PullResult } from "@fusionkit/workspace";
+import type { Handoff } from "./handoff.js";
+import type { ContinuationPolicy } from "./policy.js";
+import type { HandoffRun } from "./run.js";
+import type { RuntimeTarget } from "./targets.js";
+/**
+ * The one configuration shape for adapters that run the "command" harness
+ * over governed sessions (the AI SDK remote tools and the compute surface
+ * extend this rather than redeclaring it).
+ */
+export type CommandHarnessConfig = {
+    /** Local git workspace whose state the governed session materializes. */
+    workspace: string;
+    plane: PlaneClient | {
+        url: string;
+        adminToken: string;
+    };
+    /** Runner pool that executes the commands. */
+    pool: string;
+    actor?: ActorRef;
+    policy?: ContinuationPolicy;
+    secrets?: string[];
+    allowHosts?: string[];
+    allowUntracked?: string[];
+    /** Requested session isolation for command runs. Defaults to "process". */
+    session?: SessionIsolation;
+    /** Per-command wait ceiling. Defaults to 5 minutes. */
+    timeoutMs?: number;
+};
+/**
+ * Build the continuation context every command-harness adapter shares:
+ * a `handoff(...)` bound to the command agent, with the optional fields
+ * spread only when present.
+ */
+export declare function createCommandContext(config: CommandHarnessConfig): Handoff;
+export type GovernedCommandOptions = {
+    command: string;
+    target: RuntimeTarget;
+    reason: string;
+    timeoutMs: number;
+    pullResults?: boolean;
+    execution?: ExecutionSpec;
+    session?: SessionIsolation;
+};
+export type GovernedCommandResult = {
+    run: HandoffRun;
+    status: RunStatus;
+    output: string;
+    exitCode: number | undefined;
+    receiptBundle: ReceiptBundle;
+    verification: BundleVerification;
+    pullResult?: PullResult;
+};
+/**
+ * The receipt-backed evidence record adapters keep for every governed
+ * command: run id, terminal status, contract hash, and the offline
+ * verification verdict. Adapter-specific fields (tool name, sandbox id)
+ * are intersected on by the caller.
+ */
+export type GovernedRunRecord = {
+    command: string;
+    runId: string;
+    status: RunStatus;
+    exitCode?: number;
+    contractHash: string;
+    /** Actual runner isolation recorded in the receipt. */
+    isolation?: SessionIsolation;
+    /** Offline verification result of the receipt bundle for this command. */
+    receiptVerified: boolean;
+    pullMode?: PullResult["mode"];
+};
+/** Distill a governed command result into its evidence record. */
+export declare function toGovernedRunRecord(command: string, result: GovernedCommandResult): GovernedRunRecord;
+export declare function executeGovernedCommand(context: Handoff, options: GovernedCommandOptions): Promise<GovernedCommandResult>;

package/dist/run-executor.js

@@ -0,0 +1,71 @@
+import { verifyReceiptBundle } from "@fusionkit/protocol";
+import { agents } from "./agents.js";
+import { handoff } from "./handoff.js";
+/**
+ * Build the continuation context every command-harness adapter shares:
+ * a `handoff(...)` bound to the command agent, with the optional fields
+ * spread only when present.
+ */
+export function createCommandContext(config) {
+    return handoff({
+        workspace: config.workspace,
+        plane: config.plane,
+        agent: agents.command(),
+        ...(config.actor ? { actor: config.actor } : {}),
+        ...(config.policy ? { policy: config.policy } : {}),
+        ...(config.secrets ? { secrets: config.secrets } : {}),
+        ...(config.allowHosts ? { allowHosts: config.allowHosts } : {}),
+        ...(config.allowUntracked ? { allowUntracked: config.allowUntracked } : {})
+    });
+}
+/** Distill a governed command result into its evidence record. */
+export function toGovernedRunRecord(command, result) {
+    return {
+        command,
+        runId: result.run.runId,
+        status: result.status,
+        ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+        contractHash: result.receiptBundle.receipt.contractHash,
+        ...(result.receiptBundle.receipt.runner.isolation
+            ? { isolation: result.receiptBundle.receipt.runner.isolation }
+            : {}),
+        receiptVerified: result.verification.ok,
+        ...(result.pullResult ? { pullMode: result.pullResult.mode } : {})
+    };
+}
+export async function executeGovernedCommand(context, options) {
+    const execution = options.execution ?? {
+        kind: "shell",
+        script: options.command
+    };
+    const run = await context.continueIn(options.target, {
+        task: options.command,
+        agent: agents.command(),
+        reason: options.reason,
+        execution,
+        ...(options.session ? { session: options.session } : {})
+    });
+    const outcome = await run.wait({ timeoutMs: options.timeoutMs });
+    if (outcome.status === "awaiting_approval") {
+        throw new Error(`run ${run.runId} is blocked on consent (${outcome.consentRequirements.join("; ")}); ` +
+            `approve it with: warrant approve ${run.runId}`);
+    }
+    const [output, exitCode, receiptBundle] = await Promise.all([
+        run.sessionLog(),
+        run.commandExitCode(),
+        run.receipt()
+    ]);
+    const verification = verifyReceiptBundle(receiptBundle);
+    const pullResult = options.pullResults === true && outcome.status === "completed"
+        ? await run.pull()
+        : undefined;
+    return {
+        run,
+        status: outcome.status,
+        output,
+        exitCode,
+        receiptBundle,
+        verification,
+        ...(pullResult ? { pullResult } : {})
+    };
+}

package/dist/run.d.ts

@@ -0,0 +1,88 @@
+import type { ActorRef, ChainedEvent, CheckpointTier, HandoffEnvelope, ReceiptBundle, RunStatus } from "@fusionkit/protocol";
+import { PlaneClient } from "@fusionkit/sdk";
+import type { PullResult } from "@fusionkit/workspace";
+import type { IsolationStrategy } from "./isolation.js";
+import type { RuntimeTarget } from "./targets.js";
+export type WaitOptions = {
+    timeoutMs?: number;
+    pollMs?: number;
+};
+export type WaitOutcome = {
+    status: RunStatus;
+    /** Present when the run is blocked on a human decision. */
+    consentRequirements: string[];
+};
+/**
+ * A continuation that became a governed run. Wraps the plane API with the
+ * operations a continuation caller needs: wait, approve, receipt, pull.
+ */
+export declare class HandoffRun {
+    readonly runId: string;
+    readonly target: RuntimeTarget;
+    readonly envelope: HandoffEnvelope;
+    readonly envelopeHash: string;
+    /** Human-readable planner explanation for why this continuation ran. */
+    readonly explanation: string;
+    /** Isolation strategy applied at pull time. */
+    readonly isolate?: IsolationStrategy;
+    private readonly client;
+    private readonly actor;
+    private readonly workspaceDir;
+    private readonly onTerminal;
+    private readonly onPulled;
+    constructor(input: {
+        runId: string;
+        target: RuntimeTarget;
+        envelope: HandoffEnvelope;
+        envelopeHash: string;
+        explanation?: string;
+        isolate?: IsolationStrategy;
+        client: PlaneClient;
+        actor: ActorRef;
+        workspaceDir: string;
+        onTerminal: (runId: string, status: RunStatus) => void;
+        onPulled: (runId: string, mode: PullResult["mode"]) => void;
+    });
+    /** The checkpoint tier this continuation carried. */
+    get tier(): CheckpointTier;
+    /** Deep link to this run in the control panel. */
+    get url(): string;
+    /** Where the signed evidence lives: bundle download via the CLI. */
+    get auditUrl(): string;
+    status(): Promise<RunStatus>;
+    events(): Promise<ChainedEvent[]>;
+    /**
+     * Poll until the run is terminal or blocked on consent. Consent is a
+     * human decision; the SDK surfaces it instead of spinning forever.
+     */
+    wait(options?: WaitOptions): Promise<WaitOutcome>;
+    /**
+     * The session's combined stdout/stderr, fetched by the content hash
+     * recorded in the event chain. Empty when the session produced no output.
+     */
+    sessionLog(): Promise<string>;
+    /**
+     * 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.
+     */
+    commandExitCode(): Promise<number | undefined>;
+    /** Grant required consent as the given actor (defaults to the context actor). */
+    approve(actor?: ActorRef): Promise<RunStatus>;
+    /** Cancel the run if it has not been claimed by a runner yet. */
+    cancel(actor?: ActorRef): Promise<RunStatus>;
+    /** The signed, offline-verifiable receipt bundle. */
+    receipt(): Promise<ReceiptBundle>;
+    /**
+     * 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.
+     */
+    pull(options?: {
+        repoDir?: string;
+        isolate?: IsolationStrategy;
+    }): Promise<PullResult>;
+}