@arnilo/prism 0.9.0 → 0.11.0

package/dist/extensions.d.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, ToolDefinition } from "./contracts.js";
+import type { AgentEvent, CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, StopHook, ToolDefinition } from "./contracts.js";
 import { type ContributionRegistries } from "./contributions.js";
 import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
@@ -40,6 +40,18 @@ export interface ExtensionKernel {
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;
+export interface AgentEventBridgeOptions {
+    /** Bridge-side failure (a source error, or a bus listener that throws under `errorPolicy: "throw"`).
+     *  Never rethrown — the bridge must not fail the run it is observing. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export declare function forwardAgentEvents(source: AsyncIterable<AgentEvent>, events: Pick<ExtensionEventBus, "emit">, options?: AgentEventBridgeOptions): () => void;
 /** Host-owned activation: copy contributed entries into the `createAgent()`
  *  fields that accept plain arrays. Contributions stay inert until the host
  *  passes the returned fields into runtime config. Array slots only —
@@ -51,6 +63,8 @@ export interface ActivatedKernelConfig {
     readonly skills: readonly Skill[];
     readonly instructionInjectors: readonly InstructionInjector[];
     readonly context: readonly ContextProvider[];
+    /** Run-end stop hooks (plan 106 R1); pass to `createAgent({ stopHooks })`. */
+    readonly stopHooks: readonly StopHook[];
     /** For host command surfaces (CLI/RPC/UI); not part of `AgentConfig`. */
     readonly commands: readonly CommandDefinition[];
     /** The kernel middleware registry itself; runs only when passed to runtime config. */

package/dist/extensions.js

@@ -143,6 +143,10 @@ export function createExtensionKernel(options = {}) {
             registries.instructionInjectors.register(injector.name, injector);
             track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+        registerStopHook(hook) {
+            registries.stopHooks.register(hook.name, hook);
+            track?.(() => registries.stopHooks.unregister(hook.name));
+        },
     });
     const unwind = (undo) => {
         for (const fn of undo.reverse()) {
@@ -190,12 +194,76 @@ export function createExtensionKernel(options = {}) {
         },
     };
 }
+/**
+ * Lifecycle hook each forwarded `AgentEvent` maps onto (plan 106 R2). Notification only: the bus
+ * receives the original event as `payload` and nothing is transformed. Events not listed here are
+ * ignored — notably `agent_finished` stays an AgentEvent and is not re-emitted as a bus event.
+ */
+const AGENT_EVENT_BRIDGE = {
+    agent_started: "before_agent_start",
+    turn_started: "turn",
+    turn_finished: "turn",
+    tool_execution_started: "tool_call",
+    tool_execution_finished: "tool_result",
+};
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export function forwardAgentEvents(source, events, options = {}) {
+    const iterator = source[Symbol.asyncIterator]();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A throwing error callback must not become an unhandled rejection.
+        }
+    };
+    let stopped = false;
+    // Serially chained so a listener that awaits keeps event order; the run never awaits this chain.
+    let pending = Promise.resolve();
+    void (async () => {
+        try {
+            while (!stopped) {
+                const { value, done } = await iterator.next();
+                if (done || stopped)
+                    return;
+                const type = AGENT_EVENT_BRIDGE[value.type];
+                if (type === undefined)
+                    continue;
+                const event = { type, payload: value };
+                pending = pending.then(() => events.emit(event)).catch(report);
+            }
+        }
+        catch (error) {
+            if (!stopped)
+                report(error);
+        }
+    })();
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        void (async () => {
+            try {
+                await iterator.return?.();
+            }
+            catch (error) {
+                report(error);
+            }
+        })();
+    };
+}
 export function activateKernel(kernel) {
     return {
         tools: kernel.registries.tools.list(),
         skills: kernel.registries.skills.list(),
         instructionInjectors: kernel.registries.instructionInjectors.list(),
         context: kernel.registries.contextProviders.list(),
+        stopHooks: kernel.registries.stopHooks.list(),
         commands: kernel.registries.commands.list(),
         middleware: kernel.middleware,
     };

package/dist/guardrail-packs/types.d.ts

@@ -1,11 +1,20 @@
 /** Internal guardrail-pack definition types (plan 092 Task 2). Not SDK surface; hosts configure packs via `AgentSessionConfig.guardrailPacks`. */
 import type { GuardrailRule, GuardrailRuleContext } from "../contracts-core/guardrail-packs.js";
 import type { ToolResult } from "../contracts-protocol.js";
+/** Plan 104 Task 2: pack-owned durable-state codec. The pack decides what a checkpoint carries. */
+interface GuardrailPackStateCodec {
+    /** Serialize the live state for a checkpoint; `undefined` when nothing needs persisting. */
+    readonly snapshot: (state: Record<string, unknown>) => Readonly<Record<string, unknown>> | undefined;
+    /** Parse a persisted snapshot back into state fields; throw `GuardrailPackError` on a malformed value. */
+    readonly parse: (json: unknown) => Record<string, unknown>;
+}
 /** What a pack's `build` returns: restrictive rules plus an optional pure result observer. */
 export interface GuardrailPackRules {
     readonly rules: readonly GuardrailRule[];
     /** Records tool results into pack-local state (never denies); a throw fails closed as a guardrail tripwire. */
     readonly observe?: (state: Record<string, unknown>, result: ToolResult, context: GuardrailRuleContext) => void;
+    /** Optional codec making the pack's state survive a durable resume; a pack without one persists nothing. */
+    readonly state?: GuardrailPackStateCodec;
 }
 export interface GuardrailPackDefinition {
     readonly id: string;
@@ -14,3 +23,4 @@ export interface GuardrailPackDefinition {
     /** Pure factory: options in, rules out. No session access, no I/O. */
     readonly build: (options: Readonly<Record<string, unknown>>) => GuardrailPackRules;
 }
+export {};

package/dist/guardrail-packs/validation-respect.js

@@ -3,6 +3,7 @@ const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
 /** Validation-style tool names. `shell` is opt-in (`validationTools`): a non-zero shell exit is a failure signal too. */
 const DEFAULT_VALIDATION_TOOLS = ["test", "run_tests", "validate", "validation", "lint", "typecheck", "check"];
 const MAX_VALIDATION_TOOLS = 16;
+const MAX_VALIDATION_TOOL_CHARS = 128;
 /** A tool result failed when it carries an error, or reported a non-zero `exitCode` (the shell tool's shape). */
 function resultFailed(result) {
     if (result.error !== undefined)
@@ -39,6 +40,21 @@ export const validationRespectPack = {
                     return;
                 state.validationFailed = resultFailed(result) ? context.toolName : undefined;
             },
+            // Plan 104 Task 2: one tool name (or nothing) survives a resume, so a mutation the suspended
+            // run denied stays denied. The codec is the pack's own bound: 128 chars, never arguments.
+            state: {
+                snapshot: (state) => (typeof state.validationFailed === "string" ? { validationFailed: state.validationFailed } : undefined),
+                parse: (json) => {
+                    const record = typeof json === "object" && json !== null ? json : {};
+                    const failed = record.validationFailed;
+                    if (failed === undefined)
+                        return {};
+                    if (typeof failed !== "string" || !failed.trim() || failed.length > MAX_VALIDATION_TOOL_CHARS) {
+                        throw new GuardrailPackError(`validation-respect persisted state.validationFailed must be a non-empty string of at most ${MAX_VALIDATION_TOOL_CHARS} chars`);
+                    }
+                    return { validationFailed: failed };
+                },
+            },
             rules: [
                 {
                     id: "no-mutation-after-failed-validation",

package/dist/guardrails.d.ts

@@ -1,10 +1,20 @@
-import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailRule, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
 export { GuardrailPackError } from "./guardrail-packs/errors.js";
 import type { SecretRedactor } from "./redaction.js";
 export declare const MAX_GUARDRAIL_CONCURRENCY = 16;
 /** Guardrail pack compile bounds (plan 092 Task 2). All ceilings are config-shape limits, not runtime budgets. */
 export declare const MAX_GUARDRAIL_PACKS = 8;
 export declare const MAX_GUARDRAIL_PACK_RULES = 64;
+/**
+ * Plan 104 T4/T6: the bounded, redacted refusal line for a terminal record that came from a compiled
+ * pack rule — `<prefix> by guardrail rule pack:<pack>/<rule>`, plus the pack's own reason when it set
+ * one — or `undefined` for any other guardrail, so the caller keeps its own neutral text. Only the
+ * compiler writes the `pack`/`rule` metadata, so a host-written guardrail named `pack:…` is never
+ * presented as a pack rule. Reasons are redacted where the record is built, pack names are
+ * compiler-bounded to 128 bytes (the identity always survives the cap), and a long reason is
+ * truncated, so the same derivation serves the tool refusal and decision-time revalidation.
+ */
+export declare function guardrailRefusalText(record: GuardrailRecord, prefix?: string): string | undefined;
 export declare class GuardrailError extends Error {
     readonly code: string;
     readonly record: GuardrailRecord;
@@ -33,6 +43,30 @@ export interface GuardrailPackRow {
     readonly stage: "tool_input" | "tool_output";
     readonly revision: string | null;
 }
+/** Plan 104 Task 2: one replayable pack row of a durable checkpoint (`id`, resolved version, host options). */
+interface GuardrailPackRefRow {
+    readonly id: string;
+    readonly version: number;
+    /** Host options the pack was compiled with, replayed verbatim on resume so enforcement is identical. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * Plan 104 T3: the host's own rule list for an inline pack. Patterns are data and ride the
+     * checkpoint; a `deny` predicate or a `RegExp` pattern cannot round-trip and is refused at save.
+     */
+    readonly rules?: readonly GuardrailRule[];
+}
+/** Plan 104 Task 2: a compile result that can round-trip through a durable checkpoint. */
+interface CompiledGuardrailPacks {
+    readonly guardrails: Guardrails | undefined;
+    /** Rows a durable checkpoint replays; empty when no packs are configured. */
+    readonly packs: readonly GuardrailPackRefRow[];
+    /** Plan 104 T3: `ask` rules as the charge-time durable gate — a match records `interrupt`. */
+    readonly askGate?: Guardrails;
+    /** Plan 104 T3: the same rules as plain blocks, merged into a run that cannot suspend. */
+    readonly askBlocks?: Guardrails;
+    /** Pack-owned state snapshot (`{ <packId>: <pack state> }`); `undefined` when nothing needs persisting. */
+    readonly snapshotState: () => Record<string, Readonly<Record<string, unknown>>> | undefined;
+}
 /**
  * Compiles `guardrailPacks` config onto the existing tool interception seams: one `tool_input`
  * guardrail per rule (`name = pack:<pack>/<rule>`), plus one `tool_output` recorder for packs that
@@ -40,5 +74,12 @@ export interface GuardrailPackRow {
  * Throws `GuardrailPackError` on malformed config (fail closed); returns `undefined` when unset.
  */
 export declare function compileGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): Guardrails | undefined;
+/**
+ * Plan 104 Task 2: the internal compile entry behind `compileGuardrailPacks`. Passing `initial`
+ * marks a durable restore — rows must then come from the installed registry, match its version, and
+ * parse through the pack's own state codec, so a mismatch fails closed instead of restoring a
+ * weaker policy. `snapshotState` is the checkpoint-side counterpart.
+ */
+export declare function compileGuardrailPacksWithState(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>, initial?: Readonly<Record<string, unknown>>): CompiledGuardrailPacks;
 /** Stable identity rows for the same config `compileGuardrailPacks` accepts (no state, no guardrails built). */
 export declare function describeGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): readonly GuardrailPackRow[];

package/dist/guardrails.js

@@ -17,6 +17,28 @@ const MAX_ARG_SCAN_STRINGS = 64;
 const MAX_ARG_STRING_BYTES = 16 * 1024;
 const MAX_PACK_NAME_BYTES = 128;
 const OBSERVE_RULE_ID = "observe";
+/** Bytes allowed for a rule-naming refusal line, so no rule text can grow a model or host message. */
+const MAX_GUARDRAIL_REFUSAL_BYTES = 200;
+/**
+ * Plan 104 T4/T6: the bounded, redacted refusal line for a terminal record that came from a compiled
+ * pack rule — `<prefix> by guardrail rule pack:<pack>/<rule>`, plus the pack's own reason when it set
+ * one — or `undefined` for any other guardrail, so the caller keeps its own neutral text. Only the
+ * compiler writes the `pack`/`rule` metadata, so a host-written guardrail named `pack:…` is never
+ * presented as a pack rule. Reasons are redacted where the record is built, pack names are
+ * compiler-bounded to 128 bytes (the identity always survives the cap), and a long reason is
+ * truncated, so the same derivation serves the tool refusal and decision-time revalidation.
+ */
+export function guardrailRefusalText(record, prefix = "Blocked") {
+    const pack = record.metadata?.pack;
+    const rule = record.metadata?.rule;
+    if (typeof pack !== "string" || typeof rule !== "string")
+        return undefined;
+    const line = `${prefix} by guardrail rule ${record.guardrail}`;
+    // The compiler synthesizes `guardrail pack rule <pack>/<rule>` when the rule set no reason; the
+    // identity already implies it, so only a real reason is appended.
+    const text = record.reason && record.reason !== `guardrail pack rule ${pack}/${rule}` ? `${line}: ${record.reason}` : line;
+    return boundText(text, MAX_GUARDRAIL_REFUSAL_BYTES);
+}
 export class GuardrailError extends Error {
     code;
     record;
@@ -76,6 +98,7 @@ export function assertGuardrailsAllowed(result) {
     if (result.terminal)
         throw new GuardrailError(result.terminal);
 }
+const EMPTY_COMPILED_PACKS = { guardrails: undefined, packs: [], snapshotState: () => undefined };
 /**
  * Compiles `guardrailPacks` config onto the existing tool interception seams: one `tool_input`
  * guardrail per rule (`name = pack:<pack>/<rule>`), plus one `tool_output` recorder for packs that
@@ -83,19 +106,60 @@ export function assertGuardrailsAllowed(result) {
  * Throws `GuardrailPackError` on malformed config (fail closed); returns `undefined` when unset.
  */
 export function compileGuardrailPacks(refs, registry = BUILT_IN_GUARDRAIL_PACKS) {
-    const packs = resolveGuardrailPacks(refs, registry);
+    return compileGuardrailPacksWithState(refs, registry).guardrails;
+}
+/**
+ * Plan 104 Task 2: the internal compile entry behind `compileGuardrailPacks`. Passing `initial`
+ * marks a durable restore — rows must then come from the installed registry, match its version, and
+ * parse through the pack's own state codec, so a mismatch fails closed instead of restoring a
+ * weaker policy. `snapshotState` is the checkpoint-side counterpart.
+ */
+export function compileGuardrailPacksWithState(refs, registry = BUILT_IN_GUARDRAIL_PACKS, initial) {
+    const packs = resolveGuardrailPacks(refs, registry, initial);
     if (packs.length === 0)
-        return undefined;
+        return EMPTY_COMPILED_PACKS;
     const toolInput = [];
     const toolOutput = [];
+    const askGate = [];
+    const askBlocks = [];
     for (const pack of packs) {
-        const state = {};
         if (pack.observe)
-            toolOutput.push(observeGuardrail(pack, pack.observe, state));
-        for (const resolved of pack.rules)
-            toolInput.push(ruleGuardrail(pack, resolved, state));
+            toolOutput.push(observeGuardrail(pack, pack.observe, pack.state));
+        for (const resolved of pack.rules) {
+            if (resolved.action === "ask") {
+                // Plan 104 T3: `ask` is not an ordinary stage decision. A run that can suspend gates the
+                // call at charge time (`interrupt` is the record meaning "awaiting a decision"), while a run
+                // that cannot suspend evaluates the same rule as a plain block through `activeGuardrails`.
+                askGate.push(ruleGuardrail(pack, resolved, pack.state, "interrupt"));
+                askBlocks.push(ruleGuardrail(pack, resolved, pack.state, "block"));
+                continue;
+            }
+            toolInput.push(ruleGuardrail(pack, resolved, pack.state));
+        }
     }
-    return toolOutput.length > 0 ? { toolInput, toolOutput } : { toolInput };
+    return {
+        guardrails: toolOutput.length > 0 ? { toolInput, toolOutput } : { toolInput },
+        packs: packs.map((pack) => pack.row),
+        ...(askGate.length > 0 ? { askGate: { toolInput: askGate }, askBlocks: { toolInput: askBlocks } } : {}),
+        snapshotState: () => {
+            const state = {};
+            for (const pack of packs) {
+                // Plan 104 T3: an inline pack now rides the checkpoint as rules, so only the rule shapes
+                // that cannot round-trip matter: a closure has no JSON form, and a `RegExp` serializes to
+                // `{}`, which would restore as an invalid (or, worse, absent) pattern.
+                const unpersistable = pack.inline
+                    ? pack.rules.find((resolved) => resolved.rule.deny !== undefined || resolved.rule.pattern instanceof RegExp)
+                    : undefined;
+                if (unpersistable) {
+                    throw new GuardrailPackError(`guardrail pack "${pack.id}" rule "${unpersistable.rule.id}" cannot be persisted (deny predicate or RegExp pattern); use a pattern string or a registered pack id when \`persistSessionState\` is on`);
+                }
+                const snapshot = pack.stateCodec?.snapshot(pack.state);
+                if (snapshot !== undefined)
+                    state[pack.id] = snapshot;
+            }
+            return Object.keys(state).length > 0 ? state : undefined;
+        },
+    };
 }
 /** Stable identity rows for the same config `compileGuardrailPacks` accepts (no state, no guardrails built). */
 export function describeGuardrailPacks(refs, registry = BUILT_IN_GUARDRAIL_PACKS) {
@@ -114,13 +178,14 @@ function packRevision(pack) {
 function packRuleName(packId, ruleId) {
     return `pack:${packId}/${ruleId}`;
 }
-function resolveGuardrailPacks(refs, registry) {
+function resolveGuardrailPacks(refs, registry, initial) {
     if (refs === undefined)
         return [];
     if (!Array.isArray(refs))
         throw new GuardrailPackError("guardrailPacks must be an array of pack ids or pack input objects");
     if (refs.length > MAX_GUARDRAIL_PACKS)
         throw new GuardrailPackError(`guardrailPacks accepts at most ${MAX_GUARDRAIL_PACKS} packs`);
+    const restoring = initial !== undefined;
     const seenPacks = new Set();
     return refs.map((ref) => {
         const input = (typeof ref === "string" ? { id: ref } : ref) ?? {};
@@ -135,7 +200,22 @@ function resolveGuardrailPacks(refs, registry) {
         }
         const definition = registry.get(input.id);
         if (definition === undefined && input.rules === undefined) {
-            throw new GuardrailPackError(`unknown guardrail pack "${input.id}"; known packs: ${[...registry.keys()].join(", ") || "none"}`);
+            throw unknownGuardrailPack(input.id, registry);
+        }
+        // A restored checkpoint replays rows, so a registered id must still match its installed version
+        // while an inline pack needs its pattern rules back (a closure cannot ride a checkpoint, and a
+        // pack replaying without it would enforce less than it did).
+        if (restoring) {
+            if (input.rules === undefined) {
+                if (definition === undefined)
+                    throw unknownGuardrailPack(input.id, registry);
+                if (input.version !== definition.version) {
+                    throw new GuardrailPackError(`guardrail pack "${input.id}" was persisted at version ${input.version} but the installed version is ${definition.version}`);
+                }
+            }
+            else if (input.rules.some((rule) => rule?.deny !== undefined)) {
+                throw new GuardrailPackError(`persisted guardrail pack "${input.id}" carries a deny predicate; only pattern rules can be restored`);
+            }
         }
         let built;
         if (input.rules !== undefined) {
@@ -144,6 +224,8 @@ function resolveGuardrailPacks(refs, registry) {
             built = { rules: input.rules };
         }
         else {
+            if (definition === undefined)
+                throw unknownGuardrailPack(input.id, registry);
             built = definition.build(Object.freeze({ ...input.options }));
         }
         if (!built || !Array.isArray(built.rules) || built.rules.length === 0) {
@@ -155,19 +237,43 @@ function resolveGuardrailPacks(refs, registry) {
         if (built.observe !== undefined && typeof built.observe !== "function") {
             throw new GuardrailPackError(`guardrail pack "${input.id}" observe must be a function`);
         }
+        if (built.state !== undefined && (typeof built.state.snapshot !== "function" || typeof built.state.parse !== "function")) {
+            throw new GuardrailPackError(`guardrail pack "${input.id}" state codec must declare snapshot and parse`);
+        }
         const seenRules = new Set();
         const rules = built.rules.map((rule) => resolveRule(input.id, rule, seenRules));
         if (built.observe && byteLength(packRuleName(input.id, OBSERVE_RULE_ID)) > MAX_PACK_NAME_BYTES) {
             throw new GuardrailPackError(`guardrail pack "${input.id}" name exceeds ${MAX_PACK_NAME_BYTES} bytes`);
         }
+        const version = input.version ?? definition?.version ?? 1;
+        const state = {};
+        const persisted = initial === undefined ? undefined : initial[input.id];
+        if (persisted !== undefined) {
+            if (built.state === undefined) {
+                throw new GuardrailPackError(`guardrail pack "${input.id}" has persisted state but declares no state codec`);
+            }
+            Object.assign(state, built.state.parse(persisted));
+        }
         return {
             id: input.id,
-            version: input.version ?? definition?.version ?? 1,
+            version,
             rules,
+            state,
+            inline: input.rules !== undefined,
+            row: {
+                id: input.id,
+                version,
+                ...(input.options !== undefined ? { options: input.options } : {}),
+                ...(input.rules !== undefined ? { rules: input.rules } : {}),
+            },
             ...(built.observe ? { observe: built.observe } : {}),
+            ...(built.state !== undefined ? { stateCodec: built.state } : {}),
         };
     });
 }
+function unknownGuardrailPack(id, registry) {
+    return new GuardrailPackError(`unknown guardrail pack "${id}"; known packs: ${[...registry.keys()].join(", ") || "none"}`);
+}
 function resolveRule(packId, rule, seenRules) {
     const where = `guardrail pack "${packId}"`;
     if (!rule || typeof rule.id !== "string" || !rule.id.trim() || byteLength(rule.id) > MAX_RULE_ID_BYTES) {
@@ -177,8 +283,11 @@ function resolveRule(packId, rule, seenRules) {
         throw new GuardrailPackError(`${where} has a duplicate rule id "${rule.id}"`);
     seenRules.add(rule.id);
     const action = rule.action ?? "deny";
-    if (action !== "deny" && action !== "tripwire") {
-        throw new GuardrailPackError(`${where} rule "${rule.id}" action must be "deny" or "tripwire" ("ask" has no deterministic seam)`);
+    if (action !== "deny" && action !== "tripwire" && action !== "ask") {
+        throw new GuardrailPackError(`${where} rule "${rule.id}" action must be "deny", "tripwire", or "ask"`);
+    }
+    if (action === "ask" && rule.deny !== undefined) {
+        throw new GuardrailPackError(`${where} rule "${rule.id}" action "ask" requires "pattern": an opaque deny predicate cannot raise an approval`);
     }
     const hasPattern = rule.pattern !== undefined;
     const hasDeny = rule.deny !== undefined;
@@ -229,7 +338,7 @@ function compileRulePattern(packId, ruleId, pattern) {
         throw new GuardrailPackError(`${where} has an invalid pattern`, { cause: error });
     }
 }
-function ruleGuardrail(pack, resolved, state) {
+function ruleGuardrail(pack, resolved, state, askAction = "interrupt") {
     return {
         name: packRuleName(pack.id, resolved.rule.id),
         revision: packRevision(pack),
@@ -244,8 +353,8 @@ function ruleGuardrail(pack, resolved, state) {
             if (!matched)
                 return { action: "allow" };
             return {
-                // Pack vocabulary is `deny`; the core guardrail action for a denial is `block`.
-                action: resolved.action === "deny" ? "block" : "tripwire",
+                // Pack vocabulary is `deny`/`ask`; the core guardrail actions are `block`/`interrupt`.
+                action: resolved.action === "deny" ? "block" : resolved.action === "ask" ? askAction : "tripwire",
                 reason: resolved.reason,
                 metadata: { pack: pack.id, rule: resolved.rule.id, version: pack.version },
             };

package/dist/index.d.ts

@@ -4,8 +4,6 @@ export { AgentEventSourceError, createMemoryAgentEventSource, isTerminalAgentEve
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export type { AgentRunLifecycle, AgentRunLifecycleAgent, AgentRunLifecycleOptions, AgentRunLifecycleRequest, AgentRunLifecycleStreamRequest, } from "./agent-run-lifecycle.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
-export type { CheckpointRestoreAudit, CheckpointRestoreAuditEntry, CheckpointRestoreHook, RunCheckpointRestoreHooksOptions, } from "./checkpoint-restore.js";
-export { CheckpointRestoreError, DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS, runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 export type { PendingToolCall, StoredAgentRunState } from "./agent-run-state.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, boundCheckpointMetadata, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, MAX_AGENT_RUN_METADATA_BYTES, readCheckpointMetadata, resolveCheckpointMetadata, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
@@ -19,6 +17,8 @@ export type { CacheTelemetry, CacheTelemetryOptions, CacheTelemetryReport, Cache
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export type { ProviderCapture, ProviderCaptureEntry, ProviderCaptureOptions, ProviderCapturePolicy } from "./capture.js";
 export { createProviderCapture } from "./capture.js";
+export type { CheckpointRestoreAudit, CheckpointRestoreAuditEntry, CheckpointRestoreCompensation, CheckpointRestoreHandler, CheckpointRestoreHook, RunCheckpointRestoreHooksOptions, } from "./checkpoint-restore.js";
+export { CheckpointRestoreError, DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS, runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 export type { MemoryCheckpointStoreOptions } from "./checkpoints.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export type { DefaultCompactionStrategyOptions } from "./compaction.js";
@@ -49,15 +49,15 @@ export type { ClaimGroundingEvidence, ClaimGroundingEvidenceExtractor, ClaimGrou
 export { createClaimGroundingGuardrail } from "./evidence-grounding.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export type { ActivatedKernelConfig, ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
-export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export type { ActivatedKernelConfig, AgentEventBridgeOptions, ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel, forwardAgentEvents } from "./extensions.js";
 export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export type { ApplyFieldPolicyOptions, AuditFieldRedaction, AuditFieldRedactorLike, AuditFieldRedactorOptions, FieldPolicy, FieldPolicyAction, FieldPolicyDecision, FieldPolicyInput, ProtectedFieldPolicyOptions, } from "./field-policy.js";
 export { ALLOW_FIELD_POLICY, applyFieldPolicy, createAuditFieldRedactor, createProtectedFieldPolicy, FIELD_POLICY_LIMITS, FieldPolicyError, } from "./field-policy.js";
+export { BUILT_IN_GUARDRAIL_PACK_IDS } from "./guardrail-packs/index.js";
 export type { GuardrailPackRow, GuardrailRunResult, RunGuardrailsOptions, } from "./guardrails.js";
 export { assertGuardrailsAllowed, compileGuardrailPacks, describeGuardrailPacks, GuardrailError, GuardrailPackError, MAX_GUARDRAIL_CONCURRENCY, MAX_GUARDRAIL_PACK_RULES, MAX_GUARDRAIL_PACKS, runGuardrails, } from "./guardrails.js";
-export { BUILT_IN_GUARDRAIL_PACK_IDS } from "./guardrail-packs/index.js";
 export type { AgentIdentity, AssertIdentityActiveOptions, IdentityLimits, IdentityVerifier, NarrowIdentityOptions, Principal, ResolvedIdentityLimits, } from "./identity.js";
 export { assertIdentityActive, assertIdentityMatchesOwnership, assertIdentityPropagation, DEFAULT_IDENTITY_LIMITS, HARD_IDENTITY_LIMITS, IdentityError, identityTelemetryAttributes, narrowIdentity, ownershipFromIdentity, resolveIdentityLimits, resolveRunIdentity, } from "./identity.js";
 export type { AgentInput, AssembleProviderInputOptions, DefaultInputBuildContext, DefaultInputBuilder, DefaultPromptBuilder, InputAttachment, PromptInstruction, PromptTemplateOptions, ResolveContextOptions, } from "./input.js";
@@ -96,7 +96,7 @@ export type { RunBundleSnapshot, RunBundleSnapshotInput } from "./run-bundle.js"
 export { RUN_BUNDLE_SCHEMA_VERSION, snapshotRunBundle } from "./run-bundle.js";
 export type { BatchedRunLedgerOptions } from "./run-ledger.js";
 export { createBatchedRunLedger, DEFAULT_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_ENTRIES, isFlushableRunLedger, } from "./run-ledger.js";
-export type { RunLimitTrackerOptions } from "./run-limits.js";
+export type { BudgetExhaustionAttribution, RunLimitTrackerOptions } from "./run-limits.js";
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits, } from "./run-limits.js";
 export type { HostCompositionGovernance, HostCompositionOptions, HostCompositionProfile, HostCompositionReport, HostCompositionToolReport, } from "./secure-agent.js";
 export { assertHostCompositionReadiness, createSecureAgent, HostCompositionError, inspectHostComposition, } from "./secure-agent.js";
@@ -131,5 +131,5 @@ export { MODEL_FAMILY_TOKENS, resolveModelFamily } from "./usage-estimation.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.9.0";
+export declare const version = "0.11.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -2,7 +2,6 @@ export { resolveAgentDefinition } from "./agent-definitions.js";
 export { AgentEventSourceError, createMemoryAgentEventSource, isTerminalAgentEventType } from "./agent-event-source.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
-export { CheckpointRestoreError, DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS, runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, boundCheckpointMetadata, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, MAX_AGENT_RUN_METADATA_BYTES, readCheckpointMetadata, resolveCheckpointMetadata, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, approvalEvidenceIntact, artifactApprovalState, artifactCheckpointKey, checkCitationIntegrity, citationBindingDigest, HARD_CITATION_EXCERPT_BYTES, } from "./artifacts.js";
@@ -10,6 +9,7 @@ export { ATTENTION_BUDGET_ERROR_CODE, AttentionBudgetError, createAttentionCompi
 export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, resolveBreakpoint, sanitizeCacheKey, systemCacheControlField, } from "./cache-helpers.js";
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export { createProviderCapture } from "./capture.js";
+export { CheckpointRestoreError, DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS, runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
@@ -25,11 +25,11 @@ export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, D
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { createClaimGroundingGuardrail } from "./evidence-grounding.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel, forwardAgentEvents } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export { ALLOW_FIELD_POLICY, applyFieldPolicy, createAuditFieldRedactor, createProtectedFieldPolicy, FIELD_POLICY_LIMITS, FieldPolicyError, } from "./field-policy.js";
-export { assertGuardrailsAllowed, compileGuardrailPacks, describeGuardrailPacks, GuardrailError, GuardrailPackError, MAX_GUARDRAIL_CONCURRENCY, MAX_GUARDRAIL_PACK_RULES, MAX_GUARDRAIL_PACKS, runGuardrails, } from "./guardrails.js";
 export { BUILT_IN_GUARDRAIL_PACK_IDS } from "./guardrail-packs/index.js";
+export { assertGuardrailsAllowed, compileGuardrailPacks, describeGuardrailPacks, GuardrailError, GuardrailPackError, MAX_GUARDRAIL_CONCURRENCY, MAX_GUARDRAIL_PACK_RULES, MAX_GUARDRAIL_PACKS, runGuardrails, } from "./guardrails.js";
 export { assertIdentityActive, assertIdentityMatchesOwnership, assertIdentityPropagation, DEFAULT_IDENTITY_LIMITS, HARD_IDENTITY_LIMITS, IdentityError, identityTelemetryAttributes, narrowIdentity, ownershipFromIdentity, resolveIdentityLimits, resolveRunIdentity, } from "./identity.js";
 export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, EMPTY_TOOL_RESULT_TEXT, renderPromptTemplate, resolveContextProviders, } from "./input.js";
 export { resolveInstructionInjectors, runInstructionInjectors } from "./instruction-injection.js";
@@ -72,6 +72,6 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { MODEL_FAMILY_TOKENS, resolveModelFamily } from "./usage-estimation.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.9.0";
+export const version = "0.11.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map