@fusionkit/handoff 0.1.0

package/dist/tools.js

@@ -0,0 +1,99 @@
+import { hashCanonical } from "@fusionkit/protocol";
+/**
+ * The journal's canonicalization contract: entries store the JSON
+ * projection of tool inputs/outputs (what JSON.stringify yields — Dates as
+ * ISO strings, undefined/functions/symbols dropped), and journal hashes
+ * are defined over that projection. Values JSON cannot represent at all
+ * (BigInt, circular structures) are recorded as their string form. This is
+ * deterministic for any given value, which is what continuation replay
+ * needs; it does not claim byte-fidelity with tool-native serialization.
+ */
+function toJsonValue(value) {
+    if (value === undefined)
+        return null;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Flatten an error (with its cause chain) into a journalable string. */
+function describeError(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const parts = [`${error.name}: ${error.message}`];
+    let cause = error.cause;
+    for (let depth = 0; cause !== undefined && depth < 5; depth++) {
+        parts.push(cause instanceof Error
+            ? `caused by ${cause.name}: ${cause.message}`
+            : `caused by ${String(cause)}`);
+        cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return parts.join(" — ");
+}
+/**
+ * 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 function wrapTools(toolset, nextSeq, observe) {
+    const wrapped = {};
+    for (const [name, original] of Object.entries(toolset)) {
+        // The journal is an observer, not a validator: input validation is the
+        // tool's own contract (AI SDK tools validate against their inputSchema
+        // before execute runs), and the journal faithfully records whatever was
+        // actually executed — including calls a tool later rejects.
+        const execute = original.execute;
+        if (typeof execute !== "function") {
+            wrapped[name] = original;
+            continue;
+        }
+        const callable = execute;
+        wrapped[name] = {
+            ...original,
+            execute: async (input, options) => {
+                const started = Date.now();
+                const ts = new Date(started).toISOString();
+                const inputJson = toJsonValue(input);
+                const inputHash = hashCanonical(inputJson);
+                try {
+                    const output = await callable.call(original, input, options);
+                    const outputJson = toJsonValue(output);
+                    observe({
+                        record: {
+                            seq: nextSeq(),
+                            ts,
+                            toolName: name,
+                            input: inputJson,
+                            output: outputJson,
+                            durationMs: Date.now() - started
+                        },
+                        inputHash,
+                        outputHash: hashCanonical(outputJson),
+                        ok: true
+                    });
+                    return output;
+                }
+                catch (error) {
+                    observe({
+                        record: {
+                            seq: nextSeq(),
+                            ts,
+                            toolName: name,
+                            input: inputJson,
+                            error: describeError(error),
+                            durationMs: Date.now() - started
+                        },
+                        inputHash,
+                        ok: false
+                    });
+                    throw error;
+                }
+            }
+        };
+    }
+    return wrapped;
+}

package/dist/trace-log.d.ts

@@ -0,0 +1,6 @@
+import type { HandoffTraceEvent } from "./handoff.js";
+export declare class HandoffTraceLog {
+    private readonly events;
+    append(event: HandoffTraceEvent): void;
+    snapshot(): HandoffTraceEvent[];
+}

package/dist/trace-log.js

@@ -0,0 +1,9 @@
+export class HandoffTraceLog {
+    events = [];
+    append(event) {
+        this.events.push(event);
+    }
+    snapshot() {
+        return [...this.events];
+    }
+}

package/dist/triggers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed continuation triggers. Deterministic and explainable: every trigger
+ * evaluates against observable context state (the tool journal, explicit
+ * requests, model routing decisions) — never against a model's opinion.
+ */
+export type Trigger = {
+    kind: "trigger";
+    id: "user-requested";
+} | {
+    kind: "trigger";
+    id: "tool-failed";
+} | {
+    kind: "trigger";
+    id: "slow-tools";
+    thresholdMs: number;
+} | {
+    kind: "trigger";
+    id: "model-escalated";
+};
+export declare const triggers: {
+    /** The user (or app) explicitly asked via h.requestContinuation(). */
+    userRequested(): Trigger;
+    /** Any journaled tool call failed. */
+    toolFailed(): Trigger;
+    /** Cumulative journaled tool time exceeded the threshold. */
+    slowTools(options: {
+        thresholdMs: number;
+    }): Trigger;
+    /** h.model escalated from the local model to the cloud model. */
+    modelEscalated(): Trigger;
+};
+/** Observable context state that triggers evaluate against. */
+export type TriggerState = {
+    userRequested: boolean;
+    toolFailures: number;
+    totalToolDurationMs: number;
+    modelEscalations: number;
+};
+export type FiredTrigger = {
+    trigger: Trigger;
+    reason: string;
+};
+export declare function evaluateTriggers(list: Trigger[], state: TriggerState): FiredTrigger[];

package/dist/triggers.js

@@ -0,0 +1,64 @@
+/**
+ * Typed continuation triggers. Deterministic and explainable: every trigger
+ * evaluates against observable context state (the tool journal, explicit
+ * requests, model routing decisions) — never against a model's opinion.
+ */
+export const triggers = {
+    /** The user (or app) explicitly asked via h.requestContinuation(). */
+    userRequested() {
+        return { kind: "trigger", id: "user-requested" };
+    },
+    /** Any journaled tool call failed. */
+    toolFailed() {
+        return { kind: "trigger", id: "tool-failed" };
+    },
+    /** Cumulative journaled tool time exceeded the threshold. */
+    slowTools(options) {
+        return { kind: "trigger", id: "slow-tools", thresholdMs: options.thresholdMs };
+    },
+    /** h.model escalated from the local model to the cloud model. */
+    modelEscalated() {
+        return { kind: "trigger", id: "model-escalated" };
+    }
+};
+export function evaluateTriggers(list, state) {
+    const fired = [];
+    for (const trigger of list) {
+        switch (trigger.id) {
+            case "user-requested":
+                if (state.userRequested) {
+                    fired.push({ trigger, reason: "continuation explicitly requested" });
+                }
+                break;
+            case "tool-failed":
+                if (state.toolFailures > 0) {
+                    fired.push({
+                        trigger,
+                        reason: `${state.toolFailures} journaled tool call(s) failed`
+                    });
+                }
+                break;
+            case "slow-tools":
+                if (state.totalToolDurationMs > trigger.thresholdMs) {
+                    fired.push({
+                        trigger,
+                        reason: `tools consumed ${state.totalToolDurationMs}ms locally (threshold ${trigger.thresholdMs}ms)`
+                    });
+                }
+                break;
+            case "model-escalated":
+                if (state.modelEscalations > 0) {
+                    fired.push({
+                        trigger,
+                        reason: `the model escalated ${state.modelEscalations} time(s)`
+                    });
+                }
+                break;
+            default: {
+                const exhausted = trigger;
+                throw new Error(`unreachable trigger: ${String(exhausted)}`);
+            }
+        }
+    }
+    return fired;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fusionkit/handoff",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/handoff"
+  },
+  "description": "Handoff SDK: continuation-first developer surface (checkpoint, continueIn, parallel, review, pull) built entirely on Warrant primitives.",
+  "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/protocol": "0.1.0",
+    "@fusionkit/sdk": "0.1.0",
+    "@fusionkit/workspace": "0.1.0"
+  }
+}