@hesohq/sdk 0.1.2-dev.21

package/dist/adapters/ai-sdk.d.ts

@@ -0,0 +1,43 @@
+import { type GateOptions } from '../capture.js';
+/**
+ * The structural slice of a Vercel AI SDK v5 tool this adapter needs: an optional
+ * `execute`. Declared here (not imported from 'ai') so the SDK is an optional dep.
+ * Provider/client tools omit `execute`; those are returned unchanged.
+ */
+export interface ToolLike {
+    execute?: (...args: unknown[]) => unknown;
+}
+/**
+ * Wrap one AI SDK v5 tool so its `execute` is gated by heso. The tool's name is
+ * supplied by the caller (AI SDK tool objects don't carry their own name). A tool
+ * with no `execute` (a provider/client tool) is returned unchanged. The gate runs
+ * BEFORE the original `execute`, so a blocked action throws — which AI SDK v5 turns
+ * into a tool-error the model sees — before any side effect.
+ *
+ * @example
+ * import { streamText, tool } from 'ai'
+ * // Reached via the `./adapters/*` subpath declared in package.json `exports`.
+ * import { gateTool } from '@hesohq/sdk/adapters/ai-sdk'
+ *
+ * streamText({
+ *   model,
+ *   tools: {
+ *     search: gateTool('search', tool({ inputSchema, execute })),
+ *   },
+ * })
+ */
+export declare function gateTool<T extends ToolLike>(name: string, tool: T, opts?: GateOptions): T;
+/**
+ * Wrap a whole AI SDK v5 `tools` record, gating each tool by its record key (the
+ * name the model calls). Provider/client tools (no `execute`) pass through
+ * unchanged. The same {@link GateOptions} apply to every tool.
+ *
+ * @example
+ * import { streamText } from 'ai'
+ * // Reached via the `./adapters/*` subpath declared in package.json `exports`.
+ * import { gateTools } from '@hesohq/sdk/adapters/ai-sdk'
+ *
+ * streamText({ model, tools: gateTools({ search, sendEmail }) })
+ */
+export declare function gateTools<R extends Record<string, ToolLike>>(tools: R, opts?: GateOptions): R;
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/adapters/ai-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,CAAC,CAUzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,CAAC,CAM7F"}

package/dist/adapters/ai-sdk.js

@@ -0,0 +1,86 @@
+"use strict";
+// Vercel AI SDK v5 drop-in for the shared capture core. The 'ai' package defines a
+// tool as `tool({ inputSchema, execute })`, where `execute(input, options)` runs
+// the tool body and returns its result (or a Promise of it). Crucially, AI SDK v5
+// does NOT carry a tool's name on the tool object — the name is the record key the
+// tool is registered under (`tools: { search: ... }`) — so the adapter takes the
+// name from the caller.
+//
+// THE THROW->TOOL-ERROR CONTRACT: when an `execute` throws, AI SDK v5 catches it
+// and converts it into a tool-error result the model sees; the tool body never
+// fires and the model learns the call was refused. That makes THROWING the correct
+// way to abort. So this adapter gates BEFORE awaiting the original `execute` (a
+// blocked/suspended action throws BlockedError/SuspendedError from gate() in
+// blocking mode, so the wrapped body never runs ungated) and deliberately does NOT
+// catch the heso error — it must propagate out of `execute` into the SDK's own
+// tool-error path. On allow, the original runs and recordResult() binds its output
+// to a follow-up receipt (best-effort).
+//
+// OPTIONAL DEP: the 'ai' package is never imported here. We wrap a structural,
+// tool-like shape ({ execute? }) so importing @hesohq/sdk does not require 'ai'.
+//
+// TWO-PHASE APPROVAL — the adapter handles PHASE ONE only:
+//   Phase 1 (here): gate() throws SuspendedError(actionHash) the instant an action
+//     is gated to a human. The adapter CANNOT block execute() waiting for the human
+//     — AI SDK turns the throw into a tool-error the model sees, and execute returns.
+//     The action_hash rides on the SuspendedError; capture it there.
+//   Phase 2 (out-of-band): once the approval resolves, the caller polls
+//     cloud.waitForApproval(actionHash) (or getL1Parts), then calls finalizeL1(
+//     suspendedContent, relayedParts) to assemble + mirror the L1 receipt. This is a
+//     SEPARATE call keyed on the action_hash — never inside execute(). A rejected
+//     decision makes finalizeL1 throw ApprovalRejectedError and never mints an L1.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateTool = gateTool;
+exports.gateTools = gateTools;
+const capture_js_1 = require("../capture.js");
+/**
+ * Wrap one AI SDK v5 tool so its `execute` is gated by heso. The tool's name is
+ * supplied by the caller (AI SDK tool objects don't carry their own name). A tool
+ * with no `execute` (a provider/client tool) is returned unchanged. The gate runs
+ * BEFORE the original `execute`, so a blocked action throws — which AI SDK v5 turns
+ * into a tool-error the model sees — before any side effect.
+ *
+ * @example
+ * import { streamText, tool } from 'ai'
+ * // Reached via the `./adapters/*` subpath declared in package.json `exports`.
+ * import { gateTool } from '@hesohq/sdk/adapters/ai-sdk'
+ *
+ * streamText({
+ *   model,
+ *   tools: {
+ *     search: gateTool('search', tool({ inputSchema, execute })),
+ *   },
+ * })
+ */
+function gateTool(name, tool, opts) {
+    const original = tool.execute;
+    if (typeof original !== 'function')
+        return tool;
+    const execute = async (input, ...rest) => {
+        const action = (0, capture_js_1.gate)(name, input, opts ?? {});
+        const result = await original(input, ...rest);
+        (0, capture_js_1.recordResult)(action, result);
+        return result;
+    };
+    return { ...tool, execute };
+}
+/**
+ * Wrap a whole AI SDK v5 `tools` record, gating each tool by its record key (the
+ * name the model calls). Provider/client tools (no `execute`) pass through
+ * unchanged. The same {@link GateOptions} apply to every tool.
+ *
+ * @example
+ * import { streamText } from 'ai'
+ * // Reached via the `./adapters/*` subpath declared in package.json `exports`.
+ * import { gateTools } from '@hesohq/sdk/adapters/ai-sdk'
+ *
+ * streamText({ model, tools: gateTools({ search, sendEmail }) })
+ */
+function gateTools(tools, opts) {
+    const out = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        out[name] = gateTool(name, tool, opts);
+    }
+    return out;
+}
+//# sourceMappingURL=ai-sdk.js.map

package/dist/adapters/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":";AAAA,mFAAmF;AACnF,iFAAiF;AACjF,kFAAkF;AAClF,mFAAmF;AACnF,iFAAiF;AACjF,wBAAwB;AACxB,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,mFAAmF;AACnF,gFAAgF;AAChF,6EAA6E;AAC7E,mFAAmF;AACnF,+EAA+E;AAC/E,mFAAmF;AACnF,wCAAwC;AACxC,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,EAAE;AACF,2DAA2D;AAC3D,mFAAmF;AACnF,oFAAoF;AACpF,sFAAsF;AACtF,qEAAqE;AACrE,wEAAwE;AACxE,gFAAgF;AAChF,qFAAqF;AACrF,kFAAkF;AAClF,mFAAmF;;AAgCnF,4BAUC;AAcD,8BAMC;AA5DD,8CAAoE;AAWpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,QAAQ,CAAqB,IAAY,EAAE,IAAO,EAAE,IAAkB;IACpF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAA;IAC7B,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IAC/C,MAAM,OAAO,GAAG,KAAK,EAAE,KAAc,EAAE,GAAG,IAAe,EAAoB,EAAE;QAC7E,MAAM,MAAM,GAAG,IAAA,iBAAI,EAAC,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QAC5C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAA;QAC7C,IAAA,yBAAY,EAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC5B,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAO,CAAA;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAqC,KAAQ,EAAE,IAAkB;IACxF,MAAM,GAAG,GAA6B,EAAE,CAAA;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAQ,CAAA;AACjB,CAAC"}

package/dist/adapters/mastra.d.ts

@@ -0,0 +1,34 @@
+import { type GateOptions } from '../capture.js';
+/**
+ * The structural slice of a Mastra tool this adapter needs: an optional `id` (the
+ * tool name) and an optional `execute`. Declared here (not imported from
+ * '@mastra/core') so Mastra stays an optional dep. Tools without `execute`
+ * (provider/client tools) are returned unchanged.
+ */
+export interface ToolLike {
+    id?: string;
+    execute?: (...args: unknown[]) => unknown;
+}
+/**
+ * Wrap one Mastra tool so its `execute` is gated by heso. The tool's name is taken
+ * from `tool.id` (falling back to `'mastra_tool'`), and the gated input is unwrapped
+ * from Mastra's `execute` argument (`.context` / `.inputData` / the argument itself).
+ * A tool with no `execute` (a provider/client tool) is returned unchanged. The gate
+ * runs BEFORE the original `execute`, so a blocked action throws — which Mastra turns
+ * into an aborted tool call — before any side effect.
+ *
+ * @example
+ * import { createTool } from '@mastra/core/tools'
+ * import { gateTool } from '@hesohq/sdk/adapters/mastra'
+ *
+ * const search = gateTool(
+ *   createTool({
+ *     id: 'search',
+ *     description: 'Search the web',
+ *     inputSchema,
+ *     execute: async ({ context }) => runSearch(context),
+ *   }),
+ * )
+ */
+export declare function gateTool<T extends ToolLike>(tool: T, opts?: GateOptions): T;
+//# sourceMappingURL=mastra.d.ts.map

package/dist/adapters/mastra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../src/adapters/mastra.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAC1C;AAgBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,CAAC,CAW3E"}

package/dist/adapters/mastra.js

@@ -0,0 +1,84 @@
+"use strict";
+// Mastra drop-in for the shared capture core. A Mastra tool is built with
+// `createTool({ id, description, inputSchema, outputSchema, execute })`, where
+// `id` is the tool name the agent calls and `execute` is an async function that
+// runs the tool body. Unlike the AI SDK, `execute` receives ONE argument that
+// carries the tool input — and across Mastra versions that input lives under
+// `.context` or `.inputData`, or the argument IS the input object itself. So the
+// adapter takes the tool's name from `tool.id` and unwraps the input from
+// whichever shape the running version uses.
+//
+// THE THROW->ABORT CONTRACT: when a Mastra `execute` throws, Mastra aborts the
+// tool call — the body never produces a result and the failure surfaces to the
+// agent. That makes THROWING the correct way to refuse. So this adapter gates
+// BEFORE awaiting the original `execute` (a blocked/suspended action throws
+// BlockedError/SuspendedError from gate() in blocking mode, so the wrapped body
+// never runs ungated) and deliberately does NOT catch the heso error — it must
+// propagate out of `execute` into Mastra's own abort path. On allow, the original
+// runs and recordResult() binds its output to a follow-up receipt (best-effort).
+//
+// OPTIONAL DEP: the '@mastra/core' package is never imported here. We wrap a
+// structural, tool-like shape ({ id?, execute? }) so importing @hesohq/sdk does not
+// require Mastra to be installed.
+//
+// TWO-PHASE APPROVAL — the adapter handles PHASE ONE only:
+//   Phase 1 (here): gate() throws SuspendedError(actionHash) the instant an action
+//     is gated to a human. The adapter CANNOT block execute() waiting for the human
+//     — Mastra aborts the tool call on the throw and execute returns. The action_hash
+//     rides on the SuspendedError; capture it there.
+//   Phase 2 (out-of-band): once the approval resolves, the caller polls
+//     cloud.waitForApproval(actionHash) (or getL1Parts), then calls finalizeL1(
+//     suspendedContent, relayedParts) to assemble + mirror the L1 receipt. This is a
+//     SEPARATE call keyed on the action_hash — never inside execute(). A rejected
+//     decision makes finalizeL1 throw ApprovalRejectedError and never mints an L1.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateTool = gateTool;
+const capture_js_1 = require("../capture.js");
+/**
+ * Unwrap the tool input from Mastra's `execute` argument. Mastra passes ONE
+ * argument that, depending on version, carries the input under `.context` or
+ * `.inputData`, or simply IS the input object. We prefer `context`, then
+ * `inputData`, then the argument itself; a non-object argument is returned as-is.
+ */
+function extractInput(arg) {
+    if (arg !== null && typeof arg === 'object') {
+        const rec = arg;
+        return rec.context ?? rec.inputData ?? arg;
+    }
+    return arg;
+}
+/**
+ * Wrap one Mastra tool so its `execute` is gated by heso. The tool's name is taken
+ * from `tool.id` (falling back to `'mastra_tool'`), and the gated input is unwrapped
+ * from Mastra's `execute` argument (`.context` / `.inputData` / the argument itself).
+ * A tool with no `execute` (a provider/client tool) is returned unchanged. The gate
+ * runs BEFORE the original `execute`, so a blocked action throws — which Mastra turns
+ * into an aborted tool call — before any side effect.
+ *
+ * @example
+ * import { createTool } from '@mastra/core/tools'
+ * import { gateTool } from '@hesohq/sdk/adapters/mastra'
+ *
+ * const search = gateTool(
+ *   createTool({
+ *     id: 'search',
+ *     description: 'Search the web',
+ *     inputSchema,
+ *     execute: async ({ context }) => runSearch(context),
+ *   }),
+ * )
+ */
+function gateTool(tool, opts) {
+    const name = typeof tool.id === 'string' && tool.id ? tool.id : 'mastra_tool';
+    const original = tool.execute;
+    if (typeof original !== 'function')
+        return tool;
+    const execute = async (arg, ...rest) => {
+        const action = (0, capture_js_1.gate)(name, extractInput(arg), opts ?? {});
+        const result = await original(arg, ...rest);
+        (0, capture_js_1.recordResult)(action, result);
+        return result;
+    };
+    return { ...tool, execute };
+}
+//# sourceMappingURL=mastra.js.map

package/dist/adapters/mastra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.js","sourceRoot":"","sources":["../../src/adapters/mastra.ts"],"names":[],"mappings":";AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,6EAA6E;AAC7E,iFAAiF;AACjF,0EAA0E;AAC1E,4CAA4C;AAC5C,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,gFAAgF;AAChF,+EAA+E;AAC/E,kFAAkF;AAClF,iFAAiF;AACjF,EAAE;AACF,6EAA6E;AAC7E,oFAAoF;AACpF,kCAAkC;AAClC,EAAE;AACF,2DAA2D;AAC3D,mFAAmF;AACnF,oFAAoF;AACpF,sFAAsF;AACtF,qDAAqD;AACrD,wEAAwE;AACxE,gFAAgF;AAChF,qFAAqF;AACrF,kFAAkF;AAClF,mFAAmF;;AAkDnF,4BAWC;AA3DD,8CAAoE;AAapE;;;;;GAKG;AACH,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,GAAG,GAAG,GAA8B,CAAA;QAC1C,OAAO,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAA;IAC5C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,QAAQ,CAAqB,IAAO,EAAE,IAAkB;IACtE,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAA;IAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAA;IAC7B,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IAC/C,MAAM,OAAO,GAAG,KAAK,EAAE,GAAY,EAAE,GAAG,IAAe,EAAoB,EAAE;QAC3E,MAAM,MAAM,GAAG,IAAA,iBAAI,EAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QACxD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;QAC3C,IAAA,yBAAY,EAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC5B,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAO,CAAA;AAClC,CAAC"}

package/dist/capture.d.ts

@@ -0,0 +1,230 @@
+import type { ActionContent, ActionReceipt, RedactionMode, Verb } from './types.js';
+import type { L1Parts, QuorumParts } from './cloud.js';
+/** The native engine could not run or its output could not be parsed (fail closed). */
+export declare class BridgeError extends Error {
+    constructor(message: string);
+}
+/** A captured action was refused by policy. Thrown so the wrapped call never fires. */
+export declare class BlockedError extends Error {
+    readonly toolName: string;
+    readonly ruleId: string | null;
+    readonly reason: string | null;
+    constructor(toolName: string, ruleId: string | null, reason: string | null);
+}
+/** A captured action was gated to a human and awaits approval. Thrown so it never fires. */
+export declare class SuspendedError extends Error {
+    readonly toolName: string;
+    readonly actionHash: string | null;
+    constructor(toolName: string, actionHash: string | null);
+}
+/**
+ * A human resolved an approval as anything other than ``approved``
+ * (``rejected``/``escalated``). Thrown by {@link finalizeL1} BEFORE any assemble —
+ * a non-approval NEVER mints an L1 (M3). Carries the resolved decision so a caller
+ * can branch (e.g. surface the rejection reason).
+ */
+export declare class ApprovalRejectedError extends Error {
+    readonly actionHash: string;
+    readonly decision: string;
+    constructor(actionHash: string, decision: string);
+}
+/**
+ * The operator key loaded from the project keystore does NOT match the suspended
+ * body's ``agent_identity`` (MANDATORY-1). The action was suspended under a now-
+ * rotated key, so the in-core assemble fails closed rather than minting a receipt
+ * the verifier would reject. A DISTINCT typed signal so {@link finalizeL1} /
+ * {@link finalizeQuorum} can drive key-rotation auto-recovery (re-suspend under the new
+ * key) instead of surfacing an opaque {@link BridgeError}. Carries the
+ * ``agent_identity`` the suspended content expects so the caller can branch.
+ */
+export declare class OperatorKeyMismatchError extends Error {
+    readonly actionHash: string;
+    readonly expectedAgentIdentity: string;
+    /** The loaded operator pubkey when known (proactive path); ``null`` when the
+     * mismatch was only discovered reactively inside the native assemble. */
+    readonly loadedPublicKey: string | null;
+    constructor(actionHash: string, expectedAgentIdentity: string, 
+    /** The loaded operator pubkey when known (proactive path); ``null`` when the
+     * mismatch was only discovered reactively inside the native assemble. */
+    loadedPublicKey?: string | null);
+}
+/** Capture-point hints the engine recognizes (any other value supplies no surface fact). */
+export type Surface = 'decorator' | 'mcp_proxy' | 'http_proxy' | 'sql_proxy' | 'sdk_wrap' | 'browser_hook' | 'process_monitor';
+export type Fields = Record<string, unknown>;
+export type OutcomeKind = 'allowed' | 'blocked' | 'suspended';
+export interface GateOptions {
+    /** Escalate-only verb hint (default `tool_call`). The engine classifies structurally. */
+    verb?: Verb;
+    /** Capture-point hint (default `decorator` — the right value for a framework tool call). */
+    surface?: Surface;
+    /** Target host, when the capture observed one (lets the engine classify by host). */
+    targetHost?: string;
+    /** Extra observed signal hints (e.g. http method/path) merged under `signal`. */
+    signal?: Record<string, unknown>;
+    /** Field names whose values the engine redacts before hashing/signing (default none). */
+    redact?: string[];
+    /** How redacted fields are treated (default `destructive` — value dropped, not recoverable). */
+    redactStrategy?: RedactionMode;
+}
+/** The exact `ProcessInput` wire object (snake_case — mirrors the Rust wire type). */
+interface ProcessInput {
+    verb: Verb;
+    tool_name: string;
+    workflow: string;
+    account: string;
+    fields: Fields;
+    redact_fields: string[];
+    redact_strategy: 'destructive' | 'commit_and_reveal';
+    signal: Record<string, unknown>;
+    target_host?: string;
+    result_hash?: string;
+    clock_override?: string;
+    /** RFC-3161 TSA endpoint to mint a trusted-time anchor from at sign time. */
+    tsa_url?: string;
+    /** How a missing/failed anchor is treated (default `off` ⇒ anchorless). */
+    anchor_policy?: 'off' | 'best_effort' | 'required';
+    /** Passphrase decrypting an HSK1-encrypted operator key (else HESO_KEY_PASSPHRASE). */
+    key_passphrase?: string;
+}
+/** A captured action: the public handle + the exact wire payload recordResult re-binds. */
+export interface Action {
+    verb: Verb;
+    toolName: string;
+    fields: Fields;
+    /** @internal the wire payload, so recordResult can rebuild the same identity. */
+    readonly input: ProcessInput;
+}
+export interface Outcome {
+    kind: OutcomeKind;
+    allowed: boolean;
+    /** The signed receipt: the L0 authorization on ``allowed``; the signed,
+     * chain-free, anchorless operator-only suspended L0 receipt on ``suspended``
+     * (mirror-pushed so the byte-exact suspended content exists server-side for the
+     * later L1 relay); ``null`` on ``blocked``. */
+    receipt: ActionReceipt | null;
+    ruleId: string | null;
+    reason: string | null;
+    actionHash: string | null;
+}
+/**
+ * Build the action's `fields` from a framework's tool input: an object is used as
+ * the structured fields; a JSON-object string is parsed; anything else is recorded
+ * verbatim under `input`. Never throws — capture must not crash the agent.
+ */
+export declare function normalizeFields(input: unknown): Fields;
+/**
+ * Translate a captured call into an {@link Action}, stamping the active config's
+ * workflow/account/clock. The `verb` is an escalate-only hint — the engine
+ * classifies the `surface`/`signal` structurally and takes the stricter lane.
+ */
+export declare function buildAction(toolName: string, fields: Fields, opts?: GateOptions): Action;
+/**
+ * Capture + drive an action WITHOUT enforcing. Returns `{ outcome, action }` so an
+ * adapter can map the decision onto a framework verdict (allow/deny) instead of
+ * throwing. The returned `action` is what {@link recordResult} binds the result to.
+ */
+export declare function evaluate(toolName: string, input: unknown, opts?: GateOptions): {
+    outcome: Outcome;
+    action: Action;
+};
+/**
+ * Capture + drive + ENFORCE an action before its side effect runs. Throws
+ * {@link BlockedError} / {@link SuspendedError} on a refusal in blocking mode (so
+ * the wrapped call never fires ungated); returns the gated {@link Action} on allow
+ * (or in observe-only mode), which {@link recordResult} later binds the result to.
+ */
+export declare function gate(toolName: string, input: unknown, opts?: GateOptions): Action;
+/**
+ * Bind a finished call's result to a follow-up receipt (evidence of WHAT happened,
+ * not only what was allowed). Best-effort: a recording failure is swallowed — the
+ * load-bearing decision was the gate on the way in, and recording must never crash
+ * the agent.
+ */
+export declare function recordResult(action: Action, output: unknown): void;
+/**
+ * True when the active config enforces refusals (blocking mode), false in
+ * observe-only mode. Decision-returning adapters consult this to mirror
+ * {@link gate}'s observe-only behavior: in observe-only the verdict is "allow".
+ */
+export declare function isEnforcing(): boolean;
+/**
+ * Finalize an approved gate into a signed L1 receipt — the out-of-band SECOND call
+ * of the two-phase pattern. Phase one is {@link gate}, which throws
+ * {@link SuspendedError} (carrying the ``action_hash``) and cannot block ``execute``
+ * waiting for a human. Once the cloud relays the approver parts (poll keyed on that
+ * ``action_hash``), this assembles and mirrors the L1.
+ *
+ * Order is load-bearing:
+ *  1. Assert the relayed record is ``approved`` BEFORE touching the keystore (M3) —
+ *     a ``rejected``/``escalated`` decision throws {@link ApprovalRejectedError} and
+ *     NEVER assembles an L1.
+ *  2. Assemble in-core: the native addon loads the OPERATOR key from the project
+ *     keystore, runs the MANDATORY-1 operator-key identity check against the
+ *     suspended content's ``agent_identity``, and verifies Valid(L1) internally —
+ *     throwing on any bad part. The record is passed as the SAME bytes the cloud
+ *     stored verbatim (M2): build the L1 over the operator-stamped ``suspendedContent``.
+ *  3. Re-verify the assembled receipt locally and REFUSE to push unless it is
+ *     Valid(L1) — a defense-in-depth gate independent of the addon's internal check.
+ *  4. Mirror-push, superseding the suspended L0 entry the L1 was built from (M5).
+ *
+ * @returns the signed L1 {@link ActionReceipt} that was pushed.
+ */
+export declare function finalizeL1(suspendedContent: ActionContent, relayedParts: L1Parts, keyPassphrase?: string): Promise<ActionReceipt>;
+/** The outcome of a key-rotation re-suspend: the fresh suspended L0 the engine
+ * re-minted under the CURRENT operator key (new ``agent_identity`` + ``action_hash``),
+ * already mirror-pushed. The caller re-opens/re-routes the approval against the new
+ * hash; the stale approval on the OLD hash is non-replayable by construction. */
+export interface ReSuspendResult {
+    /** The fresh suspended L0 receipt (new identity), mirror-pushed to the cloud. */
+    receipt: ActionReceipt;
+    /** The new suspended ``action_hash`` to re-open the approval against. */
+    actionHash: string;
+    /** The current operator ``agent_identity`` the fresh suspend was minted under. */
+    agentIdentity: string;
+}
+/**
+ * Finalize an approved k-of-n gate into a signed QUORUM receipt — the multi-approver
+ * sibling of {@link finalizeL1}. Every relayed leg must be ``approved``; the native
+ * addon assembles the quorum in-core off the operator-stamped suspended content and the
+ * verbatim per-approver records + co-signatures (canonicalization stays the Rust
+ * moat), verifying Valid(L1) WITH a ``multi_approval`` block before it returns. A
+ * quorum embeds ``trust_level: 'L1'`` WITH that block — it is NOT a higher level than
+ * single-approver L1.
+ *
+ * Order is load-bearing:
+ *  1. Assert EVERY leg's ``record.decision`` is ``approved`` BEFORE touching the
+ *     keystore (M3) — any non-approval throws {@link ApprovalRejectedError} and NEVER
+ *     assembles a quorum.
+ *  2. KEY-ROTATION (proactive): if ``loadedOperatorPubkeyB64`` is supplied and does
+ *     NOT equal the suspended content's ``agent_identity``, skip the wasted assemble
+ *     and drive recovery straight away.
+ *  3. Assemble in-core (the addon runs MANDATORY-1 + verifies Valid(L1) with a
+ *     ``multi_approval`` block); a reactive ``[OperatorKeyMismatch]`` is caught and
+ *     drives the SAME recovery.
+ *  4. Re-verify locally and REFUSE to push unless Valid(L1) WITH a ``multi_approval``
+ *     block (defense in depth).
+ *  5. Mirror-push, superseding the suspended L0 entry the quorum was built from (M5:
+ *     suspended/L0 -> L1; the server rejects an already-decided L1 target).
+ *
+ * On a key mismatch (proactive or reactive) and a supplied ``onKeyRotation``
+ * recovery, this re-suspends under the new key and throws an
+ * {@link OperatorKeyMismatchError} carrying the fresh hash via ``cause`` so the
+ * caller never mistakes recovery for a successful mint. With no recovery requested
+ * it throws the typed mismatch unhandled.
+ *
+ * @returns the signed QUORUM {@link ActionReceipt} that was pushed (L1 with a
+ * ``multi_approval`` block).
+ */
+export declare function finalizeQuorum(suspendedContent: ActionContent, relayedParts: QuorumParts, options?: {
+    keyPassphrase?: string;
+    /** The loaded operator pubkey, base64 — enables the PROACTIVE key-rotation check
+     * (skip the wasted assemble when it disagrees with the suspended identity). When
+     * omitted, only the REACTIVE in-core mismatch is caught. */
+    loadedOperatorPubkeyB64?: string;
+    /** When the operator key rotated, re-suspend under the new key and return the
+     * fresh result instead of throwing the bare typed mismatch. The fresh suspended
+     * L0 is mirror-pushed; the returned hash is what the caller re-opens against. */
+    onKeyRotation?: (result: ReSuspendResult) => void;
+}): Promise<ActionReceipt>;
+export {};
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"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"}