@nookplot/runtime 0.5.100 → 0.5.106

package/dist/episodicMemoryHook.d.ts

@@ -0,0 +1,39 @@
+/**
+ * episodicMemoryHook — installs a `chat_turn_complete` listener that persists
+ * each turn into the agent's episodic memory tier.
+ *
+ * Replaces the inlined `runtime.memory.storeMemory("episodic", …)` call that
+ * previously lived in `chat/chatEngine.ts`. Behavior is byte-for-byte
+ * preserved when the engine emits `enableMemory: true` — see the
+ * `chatEngine.episodicHook.test.ts` regression suite for proof.
+ *
+ * Auto-installed by `NookplotRuntime.connect()` unless the runtime was
+ * constructed with `{ autoInstallHooks: false }`. Opt-out, not opt-in —
+ * existing agents get the prior behavior for free.
+ *
+ * @example
+ * ```ts
+ * const dispose = installEpisodicMemoryHook(runtime, { tagPrefix: "myagent" });
+ * // ...later
+ * dispose(); // stop the hook (also called automatically on runtime.disconnect)
+ * ```
+ *
+ * @module episodicMemoryHook
+ */
+import type { NookplotRuntime } from "./index.js";
+import type { HookRegistry } from "./hooks.js";
+export interface EpisodicHookOptions {
+    /** Override the registry the hook subscribes to. Defaults to `runtime.hooks`. */
+    hooks?: HookRegistry;
+    /** Extra tags appended to every stored entry (e.g. ["env:prod"]). */
+    extraTags?: string[];
+    /** Override the agent name used in the formatted line. Defaults to payload.agentName. */
+    agentName?: string;
+}
+/**
+ * Subscribe to `chat_turn_complete` and write each turn to episodic memory.
+ *
+ * Returns a disposer that removes the listener.
+ */
+export declare function installEpisodicMemoryHook(runtime: NookplotRuntime, opts?: EpisodicHookOptions): () => void;
+//# sourceMappingURL=episodicMemoryHook.d.ts.map

package/dist/episodicMemoryHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodicMemoryHook.d.ts","sourceRoot":"","sources":["../src/episodicMemoryHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,YAAY,CAAC;AAGxE,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,mBAAwB,GAC7B,MAAM,IAAI,CAoCZ"}

package/dist/episodicMemoryHook.js

@@ -0,0 +1,58 @@
+/**
+ * episodicMemoryHook — installs a `chat_turn_complete` listener that persists
+ * each turn into the agent's episodic memory tier.
+ *
+ * Replaces the inlined `runtime.memory.storeMemory("episodic", …)` call that
+ * previously lived in `chat/chatEngine.ts`. Behavior is byte-for-byte
+ * preserved when the engine emits `enableMemory: true` — see the
+ * `chatEngine.episodicHook.test.ts` regression suite for proof.
+ *
+ * Auto-installed by `NookplotRuntime.connect()` unless the runtime was
+ * constructed with `{ autoInstallHooks: false }`. Opt-out, not opt-in —
+ * existing agents get the prior behavior for free.
+ *
+ * @example
+ * ```ts
+ * const dispose = installEpisodicMemoryHook(runtime, { tagPrefix: "myagent" });
+ * // ...later
+ * dispose(); // stop the hook (also called automatically on runtime.disconnect)
+ * ```
+ *
+ * @module episodicMemoryHook
+ */
+import { hooks as defaultHooks } from "./hooks.js";
+/**
+ * Subscribe to `chat_turn_complete` and write each turn to episodic memory.
+ *
+ * Returns a disposer that removes the listener.
+ */
+export function installEpisodicMemoryHook(runtime, opts = {}) {
+    const hooks = opts.hooks ?? runtime.hooks ?? defaultHooks;
+    const listener = (payload) => {
+        // Respect the engine's enableMemory flag — when memory is disabled at
+        // the engine level, suppress writes regardless of hook registration.
+        if (payload.enableMemory === false)
+            return;
+        const { platform, sender, message, response, toolsUsed, toolCallCount, senderId, channelId } = payload;
+        const agentName = opts.agentName ?? payload.agentName ?? "Agent";
+        const extraTags = opts.extraTags ?? [];
+        runtime.memory
+            .storeMemory("episodic", `[${platform}] ${sender}: ${message}\n${agentName}: ${response}`, {
+            tags: ["conversation", platform, ...(toolsUsed ? ["tool_use"] : []), ...extraTags],
+            metadata: {
+                platform,
+                senderId: senderId ?? null,
+                senderName: sender ?? null,
+                channelId: channelId ?? null,
+                toolsUsed,
+                toolCallCount,
+                messageLength: message.length,
+                responseLength: response.length,
+                timestamp: new Date().toISOString(),
+            },
+        })
+            .catch(() => { });
+    };
+    return hooks.register("chat_turn_complete", listener);
+}
+//# sourceMappingURL=episodicMemoryHook.js.map

package/dist/episodicMemoryHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodicMemoryHook.js","sourceRoot":"","sources":["../src/episodicMemoryHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,KAAK,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAWnD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAwB,EACxB,OAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAE1D,MAAM,QAAQ,GAAG,CAAC,OAAgC,EAAQ,EAAE;QAC1D,sEAAsE;QACtE,qEAAqE;QACrE,IAAI,OAAO,CAAC,YAAY,KAAK,KAAK;YAAE,OAAO;QAE3C,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,GAC1F,OAAO,CAAC;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QACjE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;QAEvC,OAAO,CAAC,MAAM;aACX,WAAW,CACV,UAAU,EACV,IAAI,QAAQ,KAAK,MAAM,KAAK,OAAO,KAAK,SAAS,KAAK,QAAQ,EAAE,EAChE;YACE,IAAI,EAAE,CAAC,cAAc,EAAE,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC;YAClF,QAAQ,EAAE;gBACR,QAAQ;gBACR,QAAQ,EAAE,QAAQ,IAAI,IAAI;gBAC1B,UAAU,EAAE,MAAM,IAAI,IAAI;gBAC1B,SAAS,EAAE,SAAS,IAAI,IAAI;gBAC5B,SAAS;gBACT,aAAa;gBACb,aAAa,EAAE,OAAO,CAAC,MAAM;gBAC7B,cAAc,EAAE,QAAQ,CAAC,MAAM;gBAC/B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF,CACF;aACA,KAAK,CAAC,GAAG,EAAE,GAAuC,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACxD,CAAC"}

package/dist/guardrails.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Guardrails — declarative per-action parameter validation.
+ *
+ * A guardrail is a function attached to a specific `actionType`. It can:
+ *   - **Pass** by returning `undefined` / nothing.
+ *   - **Mutate args** by returning `Partial<TArgs>` — declared keys overwrite,
+ *     undeclared keys are preserved.
+ *   - **Block** by throwing `InputGuardrailTripped` (input) or
+ *     `OutputGuardrailTripped` (output). The wrapped dispatcher converts any
+ *     other error into an `InputGuardrailTripped` so callers always observe
+ *     a single error class for "validation failure".
+ *
+ * This is a SEPARATE concern from `contentSafety` (string sanitizers) and
+ * `ContentScanner` (gateway threat-detection) — guardrails operate on typed
+ * arg objects scoped to a specific action, see those args, and can short-
+ * circuit the dispatch. All three layers can run on the same call.
+ *
+ * Composition order at the dispatcher (`runtime/src/autonomous.ts`
+ * `handleActionRequest`):
+ *   1. `action_start` hook fires.
+ *   2. `tool_input` hook fires.
+ *   3. Input guardrails run in declared order; first throw → `action_error`.
+ *   4. Action body executes.
+ *   5. `tool_output` hook fires.
+ *   6. Output guardrails run; first throw → `action_error`.
+ *   7. `action_end` hook fires.
+ *
+ * @example
+ * ```ts
+ * runtime.guardrails.register("send_dm", {
+ *   input: [
+ *     ({ to }) => {
+ *       if (!/^0x[0-9a-fA-F]{40}$/.test(to as string)) {
+ *         throw new InputGuardrailTripped("`to` must be a 0x-prefixed 40-hex address");
+ *       }
+ *     },
+ *     ({ content }) => ({ content: sanitizeForPrompt(content as string, 2000) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @module guardrails
+ */
+import { type HookRegistry } from "./hooks.js";
+/** Base class for guardrail short-circuits. Catch this to handle either side. */
+export declare class GuardrailTripped extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when an input guardrail rejects or any guardrail callback throws
+ *  during the input phase. The dispatcher converts this into `action_error`. */
+export declare class InputGuardrailTripped extends GuardrailTripped {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when an output guardrail rejects. The dispatcher converts this
+ *  into `action_error` after the action body has already executed. */
+export declare class OutputGuardrailTripped extends GuardrailTripped {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * An input guardrail. Receives the (possibly mutated) args from prior
+ * guardrails. Returns `void` to pass, `Partial<TArgs>` to mutate, or throws
+ * `InputGuardrailTripped` to block.
+ *
+ * TS does not introspect parameter names — the caller declares which keys
+ * the guardrail accepts via the `Pick<TArgs, …>` type. Returned objects are
+ * shallow-merged onto args; undeclared keys in the return value are still
+ * applied (TS can't enforce param-binding at runtime), but agents should
+ * stick to the declared keys for parity with the Python `inspect.signature`
+ * extraction.
+ */
+export type InputGuardrail<TArgs extends Record<string, unknown> = Record<string, unknown>> = (args: TArgs) => void | undefined | Partial<TArgs> | Promise<void | undefined | Partial<TArgs>>;
+/**
+ * An output guardrail. Receives the action result. Returns `void` to pass,
+ * `Partial<TResult>` to mutate, or throws `OutputGuardrailTripped` to block.
+ *
+ * Output guardrails CANNOT replace the entire result — the merge is shallow
+ * AND `undefined` values in the return are filtered out before merge. This
+ * means a guardrail cannot silently drop security-critical fields (`txHash`,
+ * `signature`) by returning `{ txHash: undefined }`. To intentionally clear
+ * a field, throw `OutputGuardrailTripped` instead.
+ */
+export type OutputGuardrail<TResult = unknown> = (result: TResult) => void | undefined | Partial<TResult> | Promise<void | undefined | Partial<TResult>>;
+export interface GuardrailSet<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> {
+    input?: InputGuardrail<TArgs>[];
+    output?: OutputGuardrail<TResult>[];
+}
+/**
+ * Per-action guardrail registry. Keyed on `actionType` (the same string the
+ * dispatcher uses, e.g. `"send_dm"` or `"create_bounty"`). Multiple `register`
+ * calls APPEND — guardrails compose in registration order so an early
+ * mutation is visible to later validators.
+ *
+ * `runInput` / `runOutput` are the dispatcher integration points. They:
+ *   - Apply guardrails sequentially (not in parallel — order matters).
+ *   - Shallow-merge any returned `Partial<>` onto the working args.
+ *   - Re-throw `InputGuardrailTripped` / `OutputGuardrailTripped` as-is.
+ *   - Wrap any other thrown error in `InputGuardrailTripped` / `OutputGuardrailTripped`
+ *     with the original attached as `cause`.
+ *
+ * Tool hooks (`tool_input` / `tool_output`) are emitted by the dispatcher,
+ * not by the registry — keeps the emit point next to the action boundary.
+ */
+export declare class GuardrailRegistry {
+    private readonly inputs;
+    private readonly outputs;
+    private readonly hooks;
+    constructor(hooks?: HookRegistry);
+    /**
+     * Register one or more guardrails for an action. Returns a disposer that
+     * removes only the guardrails added by this call.
+     *
+     * `actionType` is deliberately typed as `string`, not a union of known
+     * action names. The registry does NOT validate against `ON_CHAIN_ACTIONS`
+     * — agents can attach guardrails to custom off-chain handlers, to internal
+     * action names, or to third-party actions added via SDK extension. The
+     * dispatcher only invokes guardrails whose key matches the actionType it's
+     * currently handling, so registering for an unknown key is harmless (the
+     * guardrail simply never runs).
+     *
+     * If you need strict validation — e.g. a CI check that a guardrail is
+     * actually wired to a real action — use {@link countInput} /
+     * {@link countOutput} in a test that asserts against the exported
+     * `ON_CHAIN_ACTIONS` set from `autonomous.ts`.
+     */
+    register<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(actionType: string, set: GuardrailSet<TArgs, TResult>): () => void;
+    /** Number of registered input guardrails for an action (test inspection). */
+    countInput(actionType: string): number;
+    /** Number of registered output guardrails for an action (test inspection). */
+    countOutput(actionType: string): number;
+    /** Test helper. With no arg, clears all guardrails. */
+    clear(actionType?: string): void;
+    /**
+     * Run input guardrails in declared order and return the (possibly mutated)
+     * args. Throws `InputGuardrailTripped` if any guardrail rejects.
+     *
+     * The original `args` object is not mutated — a new shallow copy is
+     * returned even when no mutations occurred, to keep caller semantics
+     * predictable.
+     */
+    runInput<TArgs extends Record<string, unknown>>(actionType: string, args: TArgs): Promise<TArgs>;
+    /**
+     * Run output guardrails in declared order and return the (possibly
+     * mutated) result. Throws `OutputGuardrailTripped` on rejection. Like
+     * `runInput`, the working object is shallow-cloned for each mutation so
+     * the caller's `result` reference is untouched until the call returns.
+     */
+    runOutput<TResult>(actionType: string, result: TResult): Promise<TResult>;
+}
+/**
+ * Decorator-style wrapper for a single action handler. Convenient when an
+ * agent wants to attach guardrails to a one-off handler (a custom CLI tool,
+ * a unit-test fixture) without registering them globally.
+ *
+ * For the dispatcher integration, prefer `GuardrailRegistry.register()` +
+ * `registry.runInput` / `registry.runOutput` — that path is what
+ * `runtime/src/autonomous.ts:handleActionRequest` calls.
+ *
+ * @example
+ * ```ts
+ * const sendDm = withGuardrails(rawSendDm, {
+ *   input: [({ to }) => { if (!to.startsWith("0x")) throw new InputGuardrailTripped("bad addr"); }],
+ *   output: [({ messageId }) => { if (!messageId) throw new OutputGuardrailTripped("missing id"); }],
+ * });
+ * ```
+ */
+export declare function withGuardrails<TArgs extends Record<string, unknown>, TResult>(handler: (args: TArgs) => Promise<TResult> | TResult, opts: {
+    input?: InputGuardrail<TArgs>[];
+    output?: OutputGuardrail<TResult>[];
+}): (args: TArgs) => Promise<TResult>;
+/**
+ * Module singleton. `NookplotRuntime` exposes its own `runtime.guardrails`
+ * which is the same object as this — `import { guardrails } from
+ * "@nookplot/runtime"` and `runtime.guardrails` are interchangeable.
+ */
+export declare const guardrails: GuardrailRegistry;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/guardrails.d.ts.map

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

package/dist/guardrails.js

@@ -0,0 +1,277 @@
+/**
+ * Guardrails — declarative per-action parameter validation.
+ *
+ * A guardrail is a function attached to a specific `actionType`. It can:
+ *   - **Pass** by returning `undefined` / nothing.
+ *   - **Mutate args** by returning `Partial<TArgs>` — declared keys overwrite,
+ *     undeclared keys are preserved.
+ *   - **Block** by throwing `InputGuardrailTripped` (input) or
+ *     `OutputGuardrailTripped` (output). The wrapped dispatcher converts any
+ *     other error into an `InputGuardrailTripped` so callers always observe
+ *     a single error class for "validation failure".
+ *
+ * This is a SEPARATE concern from `contentSafety` (string sanitizers) and
+ * `ContentScanner` (gateway threat-detection) — guardrails operate on typed
+ * arg objects scoped to a specific action, see those args, and can short-
+ * circuit the dispatch. All three layers can run on the same call.
+ *
+ * Composition order at the dispatcher (`runtime/src/autonomous.ts`
+ * `handleActionRequest`):
+ *   1. `action_start` hook fires.
+ *   2. `tool_input` hook fires.
+ *   3. Input guardrails run in declared order; first throw → `action_error`.
+ *   4. Action body executes.
+ *   5. `tool_output` hook fires.
+ *   6. Output guardrails run; first throw → `action_error`.
+ *   7. `action_end` hook fires.
+ *
+ * @example
+ * ```ts
+ * runtime.guardrails.register("send_dm", {
+ *   input: [
+ *     ({ to }) => {
+ *       if (!/^0x[0-9a-fA-F]{40}$/.test(to as string)) {
+ *         throw new InputGuardrailTripped("`to` must be a 0x-prefixed 40-hex address");
+ *       }
+ *     },
+ *     ({ content }) => ({ content: sanitizeForPrompt(content as string, 2000) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @module guardrails
+ */
+import { hooks as defaultHooks } from "./hooks.js";
+// ── Errors ───────────────────────────────────────────────────
+/** Base class for guardrail short-circuits. Catch this to handle either side. */
+export class GuardrailTripped extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "GuardrailTripped";
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+/** Thrown when an input guardrail rejects or any guardrail callback throws
+ *  during the input phase. The dispatcher converts this into `action_error`. */
+export class InputGuardrailTripped extends GuardrailTripped {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "InputGuardrailTripped";
+    }
+}
+/** Thrown when an output guardrail rejects. The dispatcher converts this
+ *  into `action_error` after the action body has already executed. */
+export class OutputGuardrailTripped extends GuardrailTripped {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "OutputGuardrailTripped";
+    }
+}
+// ── Registry ─────────────────────────────────────────────────
+/**
+ * Per-action guardrail registry. Keyed on `actionType` (the same string the
+ * dispatcher uses, e.g. `"send_dm"` or `"create_bounty"`). Multiple `register`
+ * calls APPEND — guardrails compose in registration order so an early
+ * mutation is visible to later validators.
+ *
+ * `runInput` / `runOutput` are the dispatcher integration points. They:
+ *   - Apply guardrails sequentially (not in parallel — order matters).
+ *   - Shallow-merge any returned `Partial<>` onto the working args.
+ *   - Re-throw `InputGuardrailTripped` / `OutputGuardrailTripped` as-is.
+ *   - Wrap any other thrown error in `InputGuardrailTripped` / `OutputGuardrailTripped`
+ *     with the original attached as `cause`.
+ *
+ * Tool hooks (`tool_input` / `tool_output`) are emitted by the dispatcher,
+ * not by the registry — keeps the emit point next to the action boundary.
+ */
+export class GuardrailRegistry {
+    inputs = new Map();
+    outputs = new Map();
+    hooks;
+    constructor(hooks = defaultHooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Register one or more guardrails for an action. Returns a disposer that
+     * removes only the guardrails added by this call.
+     *
+     * `actionType` is deliberately typed as `string`, not a union of known
+     * action names. The registry does NOT validate against `ON_CHAIN_ACTIONS`
+     * — agents can attach guardrails to custom off-chain handlers, to internal
+     * action names, or to third-party actions added via SDK extension. The
+     * dispatcher only invokes guardrails whose key matches the actionType it's
+     * currently handling, so registering for an unknown key is harmless (the
+     * guardrail simply never runs).
+     *
+     * If you need strict validation — e.g. a CI check that a guardrail is
+     * actually wired to a real action — use {@link countInput} /
+     * {@link countOutput} in a test that asserts against the exported
+     * `ON_CHAIN_ACTIONS` set from `autonomous.ts`.
+     */
+    register(actionType, set) {
+        const inputs = (set.input ?? []);
+        const outputs = (set.output ?? []);
+        if (inputs.length === 0 && outputs.length === 0)
+            return () => { };
+        const inputBucket = this.inputs.get(actionType) ?? [];
+        const outputBucket = this.outputs.get(actionType) ?? [];
+        inputBucket.push(...inputs);
+        outputBucket.push(...outputs);
+        if (inputBucket.length > 0)
+            this.inputs.set(actionType, inputBucket);
+        if (outputBucket.length > 0)
+            this.outputs.set(actionType, outputBucket);
+        return () => {
+            const ib = this.inputs.get(actionType);
+            if (ib) {
+                for (const cb of inputs) {
+                    const idx = ib.indexOf(cb);
+                    if (idx >= 0)
+                        ib.splice(idx, 1);
+                }
+                if (ib.length === 0)
+                    this.inputs.delete(actionType);
+            }
+            const ob = this.outputs.get(actionType);
+            if (ob) {
+                for (const cb of outputs) {
+                    const idx = ob.indexOf(cb);
+                    if (idx >= 0)
+                        ob.splice(idx, 1);
+                }
+                if (ob.length === 0)
+                    this.outputs.delete(actionType);
+            }
+        };
+    }
+    /** Number of registered input guardrails for an action (test inspection). */
+    countInput(actionType) {
+        return this.inputs.get(actionType)?.length ?? 0;
+    }
+    /** Number of registered output guardrails for an action (test inspection). */
+    countOutput(actionType) {
+        return this.outputs.get(actionType)?.length ?? 0;
+    }
+    /** Test helper. With no arg, clears all guardrails. */
+    clear(actionType) {
+        if (actionType) {
+            this.inputs.delete(actionType);
+            this.outputs.delete(actionType);
+        }
+        else {
+            this.inputs.clear();
+            this.outputs.clear();
+        }
+    }
+    /**
+     * Run input guardrails in declared order and return the (possibly mutated)
+     * args. Throws `InputGuardrailTripped` if any guardrail rejects.
+     *
+     * The original `args` object is not mutated — a new shallow copy is
+     * returned even when no mutations occurred, to keep caller semantics
+     * predictable.
+     */
+    async runInput(actionType, args) {
+        const list = this.inputs.get(actionType);
+        let working = { ...args };
+        if (!list || list.length === 0)
+            return working;
+        for (const guardrail of list) {
+            try {
+                const ret = await guardrail(working);
+                if (ret && typeof ret === "object") {
+                    mergeDropUndefined(working, ret);
+                }
+            }
+            catch (err) {
+                if (err instanceof InputGuardrailTripped)
+                    throw err;
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new InputGuardrailTripped(`Input guardrail for "${actionType}" failed: ${msg}`, { cause: err });
+            }
+        }
+        return working;
+    }
+    /**
+     * Run output guardrails in declared order and return the (possibly
+     * mutated) result. Throws `OutputGuardrailTripped` on rejection. Like
+     * `runInput`, the working object is shallow-cloned for each mutation so
+     * the caller's `result` reference is untouched until the call returns.
+     */
+    async runOutput(actionType, result) {
+        const list = this.outputs.get(actionType);
+        if (!list || list.length === 0)
+            return result;
+        let working = result;
+        for (const guardrail of list) {
+            try {
+                const ret = await guardrail(working);
+                if (ret && typeof ret === "object" && working && typeof working === "object") {
+                    const clone = { ...working };
+                    mergeDropUndefined(clone, ret);
+                    working = clone;
+                }
+            }
+            catch (err) {
+                if (err instanceof OutputGuardrailTripped)
+                    throw err;
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new OutputGuardrailTripped(`Output guardrail for "${actionType}" failed: ${msg}`, { cause: err });
+            }
+        }
+        return working;
+    }
+}
+/**
+ * Shallow-merge `patch` into `target`, skipping keys whose value is
+ * `undefined`. This is the single defensive merge used by both input and
+ * output guardrails. The rule: a guardrail can SET a field to anything
+ * (including `null` or an empty string — semantically meaningful), but
+ * cannot DROP a field by returning `undefined`. To drop, throw.
+ */
+function mergeDropUndefined(target, patch) {
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        target[key] = value;
+    }
+}
+// ── withGuardrails wrapper (standalone helper) ───────────────
+/**
+ * Decorator-style wrapper for a single action handler. Convenient when an
+ * agent wants to attach guardrails to a one-off handler (a custom CLI tool,
+ * a unit-test fixture) without registering them globally.
+ *
+ * For the dispatcher integration, prefer `GuardrailRegistry.register()` +
+ * `registry.runInput` / `registry.runOutput` — that path is what
+ * `runtime/src/autonomous.ts:handleActionRequest` calls.
+ *
+ * @example
+ * ```ts
+ * const sendDm = withGuardrails(rawSendDm, {
+ *   input: [({ to }) => { if (!to.startsWith("0x")) throw new InputGuardrailTripped("bad addr"); }],
+ *   output: [({ messageId }) => { if (!messageId) throw new OutputGuardrailTripped("missing id"); }],
+ * });
+ * ```
+ */
+export function withGuardrails(handler, opts) {
+    const registry = new GuardrailRegistry();
+    const ACTION = "__withGuardrails__";
+    registry.register(ACTION, opts);
+    return async (args) => {
+        const validatedArgs = await registry.runInput(ACTION, args);
+        const result = await handler(validatedArgs);
+        return registry.runOutput(ACTION, result);
+    };
+}
+// ── Module-level singleton ───────────────────────────────────
+/**
+ * Module singleton. `NookplotRuntime` exposes its own `runtime.guardrails`
+ * which is the same object as this — `import { guardrails } from
+ * "@nookplot/runtime"` and `runtime.guardrails` are interchangeable.
+ */
+export const guardrails = new GuardrailRegistry();
+//# sourceMappingURL=guardrails.js.map

package/dist/guardrails.js.map

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