@arnilo/prism 0.9.0 → 0.10.0

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, 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";
@@ -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.10.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.10.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/middleware.d.ts

@@ -1,5 +1,5 @@
 import type { ContentBlock, ExtensionEvent } from "./contracts.js";
-export type MiddlewareHookName = "beforeProviderTurn" | "provider_request" | "input_assembly" | "prompt_build" | "context" | "tool_call" | "tool_result" | "retry" | "compaction" | "session_start" | "session_shutdown";
+export type MiddlewareHookName = "beforeProviderTurn" | "provider_request" | "input_assembly" | "prompt_build" | "context" | "tool_call" | "tool_result" | "retry" | "compaction_request" | "compaction" | "session_start" | "session_shutdown";
 /** Provenance of a host-answered turn (plan 096). An id, never free host code. */
 export interface DeterministicTurnProvenance {
     /** Answering middleware id; bounded, replay-stable, and auditable. */

package/dist/run-bundle.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentSessionConfig, GuardrailStage, RunOptions } from "./contracts.js";
+import type { Agent, AgentSessionConfig, GuardrailPackRef, GuardrailStage, RunOptions } from "./contracts.js";
 /** Report format revision. Any shape change bumps this so pinned digests cannot compare across formats. */
 export declare const RUN_BUNDLE_SCHEMA_VERSION = 1;
 /** Inspectable projection of the inputs a run actually resolves to. Frozen JSON, safe to persist and diff. */
@@ -81,6 +81,11 @@ export interface RunBundleSnapshotInput {
     readonly run?: RunOptions;
     /** Optional memory store instance; only its kind/durability label is read, never its contents. */
     readonly memory?: unknown;
+    /**
+     * Plan 104 Task 2: effective pack refs (`session.guardrailPackRefs`) to report instead of the
+     * caller-supplied `config.guardrailPacks` — a resumed session's enforced rows.
+     */
+    readonly packs?: readonly GuardrailPackRef[];
 }
 /**
  * Snapshots the effective run bundle: synchronous, in-memory, zero network and zero store reads.

package/dist/run-bundle.js

@@ -52,7 +52,10 @@ export function snapshotRunBundle(input) {
             effect: tool.effect === undefined ? null : typeof tool.effect === "function" ? "classifier" : tool.effect.kind,
         })),
         activeSkills: run?.activeSkills ?? null,
-        guardrails: [...guardrailRows(config.guardrails, run?.guardrails), ...describeGuardrailPacks(input.config?.guardrailPacks)],
+        guardrails: [
+            ...guardrailRows(config.guardrails, run?.guardrails),
+            ...describeGuardrailPacks(input.packs ?? input.config?.guardrailPacks),
+        ],
         loop: loopIdentity(effectiveLoop),
         thinkingLevel: run?.thinkingLevel ?? config.thinkingLevel ?? null,
         limits: resolveRunLimits(config.limits, run?.limits),

package/dist/run-limits.js

@@ -10,6 +10,8 @@ export const DEFAULT_RUN_LIMITS = Object.freeze({
     maxOutputTokens: 10_000,
     maxTotalTokens: 50_000,
 });
+/** Stop-hook continuation cap when no layer configures one (plan 106 R1). Not a counter axis. */
+const DEFAULT_MAX_STOP_CONTINUATIONS = 3;
 /**
  * Process-safety ceilings that exist so a bug cannot OOM the host via JSON.parse of giant
  * provider frames. Product axes (turns, wall time, tokens, …) have no hard cap: hosts set
@@ -83,8 +85,13 @@ export function resolveRunLimits(agent, run) {
             resolved.maxProviderAttempts = turns;
     }
     const maxCost = override?.maxCost ?? base?.maxCost;
+    // Stop-hook continuation cap (plan 106 R1): no counters-table row — the wrapper turns it into a
+    // clean `hook_limit` stop, not a breach — so it resolves outside the counter-backed axes and
+    // keeps the same narrowing-only law (min, `null` = uncapped).
+    const stopContinuations = minCap(base?.maxStopContinuations, override?.maxStopContinuations);
     return Object.freeze({
         ...resolved,
+        maxStopContinuations: stopContinuations !== undefined ? stopContinuations : DEFAULT_MAX_STOP_CONTINUATIONS,
         ...(maxCost
             ? {
                 maxCost: base?.maxCost && override?.maxCost
@@ -121,6 +128,12 @@ function validateLimits(input) {
         if (!Number.isFinite(amount) || amount < 0 || !currency.trim())
             throw new TypeError("maxCost requires a finite non-negative amount and currency");
     }
+    const stopContinuations = input.maxStopContinuations;
+    if (stopContinuations !== undefined &&
+        stopContinuations !== null &&
+        (!Number.isSafeInteger(stopContinuations) || stopContinuations < 0)) {
+        throw new TypeError("maxStopContinuations must be a non-negative safe integer or null to disable the cap");
+    }
     return input;
 }
 export class RunLimitTracker {

package/dist/testing/prefix-stability-conformance.d.ts

@@ -10,14 +10,39 @@ export interface PrefixStabilityConformanceOptions {
     readonly skills: readonly [Skill, Skill];
     /** Minimum shared byte-prefix fraction between consecutive requests. Default `0.95`. */
     readonly minContinuity?: number;
+    /**
+     * Which fraction gates the run: `"providerPrefix"` (default, today's behavior) asserts the
+     * provider-visible prefix; `"cacheablePrefix"` asserts the same measurement with tail segments
+     * removed, so a body-heavy or eager host is not failed for the tail it deliberately re-sends.
+     */
+    readonly assertOn?: "providerPrefix" | "cacheablePrefix";
     /** Turn inputs; defaults are fixed strings so runs are comparable across hosts. */
     readonly inputs?: readonly [string, string];
+    /**
+     * How many request pairs may break below `minContinuity` (default `0`, today's behavior). Use
+     * `1` for an assembly that folds or evicts exactly one boundary — an attention-compiler fold,
+     * a compaction, a budget eviction. More resets than declared fail, and fewer fail too: the
+     * fixture was supposed to invalidate the prefix, so a run that never did cannot pass vacuously.
+     */
+    readonly allowedResets?: number;
 }
 export interface PrefixStabilityConformanceResult {
     /** Provider requests captured by the fixture (two per turn: skill load, then completion). */
     readonly requests: number;
     /** Lowest shared-prefix fraction observed across consecutive captured requests. */
     readonly minContinuity: number;
+    /**
+     * The same lowest fraction with the session's tail segments removed from both requests of each
+     * pair — the provider-visible prefix the cache can actually keep paying for. Equals
+     * `minContinuity` when no captured request carried a tail segment.
+     */
+    readonly cacheableContinuity: number;
+    /**
+     * 1-based indexes of the captured requests whose asserted prefix broke below `minContinuity`
+     * (the later request of each pair), in ascending order — where the assembly invalidated the
+     * prefix instead of appending. Empty when every gap stayed above the minimum.
+     */
+    readonly resets: readonly number[];
 }
 /**
  * Drive a real session through two staggered skill loads and assert that each
@@ -26,5 +51,9 @@ export interface PrefixStabilityConformanceResult {
  * after the stable prefix, so the shared prefix stays intact; a host that
  * rewrites the context block, the skill catalog, or any leading message per
  * request fails with the offending request pair and the measured fraction.
+ * Reports both the provider-visible fraction and the same fraction with the
+ * session's tail segments removed; `assertOn` picks which one gates the run.
+ * A gap below the minimum is collected as a reset instead of failing in the
+ * loop, so `allowedResets` can permit the one boundary an assembly folds at.
  */
 export declare function runPrefixStabilityConformance(options: PrefixStabilityConformanceOptions): Promise<PrefixStabilityConformanceResult>;

package/dist/testing/prefix-stability-conformance.js

@@ -5,7 +5,7 @@
 // Throws plain Error; no test runner, no network, no credentials.
 import assert from "node:assert/strict";
 import { createAgent } from "../agent-session/create-agent.js";
-import { providerDone, toolCallContent } from "../provider-events.js";
+import { providerDone, providerThinkingDelta, toolCallContent } from "../provider-events.js";
 import { createLoadSkillTool } from "../skill-load.js";
 import { createSkillRegistry } from "../skills.js";
 /**
@@ -15,6 +15,10 @@ import { createSkillRegistry } from "../skills.js";
  * after the stable prefix, so the shared prefix stays intact; a host that
  * rewrites the context block, the skill catalog, or any leading message per
  * request fails with the offending request pair and the measured fraction.
+ * Reports both the provider-visible fraction and the same fraction with the
+ * session's tail segments removed; `assertOn` picks which one gates the run.
+ * A gap below the minimum is collected as a reset instead of failing in the
+ * loop, so `allowedResets` can permit the one boundary an assembly folds at.
  */
 export async function runPrefixStabilityConformance(options) {
     const { host, skills } = options;
@@ -34,7 +38,7 @@ export async function runPrefixStabilityConformance(options) {
         ...host,
         skills: registry,
         tools: [...hostTools, createLoadSkillTool({ registry })],
-        provider: fixtureProvider(requests, [first.name, second.name]),
+        provider: fixtureProvider(requests, [first.name, second.name], host.attentionCompiler === true || typeof host.attentionCompiler === "object"),
     });
     const session = agent.createSession();
     const [firstInput, secondInput] = options.inputs ?? ["Prefix stability turn one", "Prefix stability turn two"];
@@ -42,27 +46,67 @@ export async function runPrefixStabilityConformance(options) {
     await session.run(firstInput, runOptions);
     await session.run(secondInput, runOptions);
     assert.equal(requests.length, 4, `prefix stability conformance expected 4 provider requests (2 per staggered turn), captured ${requests.length}`);
-    const serialized = requests.map(serializeRequest);
+    // The session's own map holds the exact `Message` objects `appendTailSegment` allocated, so the
+    // classification is exact rather than a heuristic over host-authored content. (`tailSegments` is
+    // runtime-session state, not part of the public `AgentSession` contract, hence the narrow above.)
+    const isTail = tailClassifier(session.tailSegments);
+    const captured = requests.map((request) => measureRequest(request, isTail));
     // Guard against a vacuous pass: both bodies must have been disclosed by the end.
-    const last = serialized.at(-1) ?? "";
+    const last = captured.at(-1)?.providerPrefix ?? "";
     for (const [index, skill] of skills.entries()) {
         assert.ok(last.includes(bodies[index] ?? ""), `prefix stability conformance: skill ${skill.name} body never reached the provider request — progressive disclosure did not expand it`);
     }
+    const assertOn = options.assertOn ?? "providerPrefix";
+    const allowedResets = options.allowedResets ?? 0;
+    assert.ok(Number.isSafeInteger(allowedResets) && allowedResets >= 0, "prefix stability conformance allowedResets must be a non-negative safe integer");
     let observed = 1;
-    let previous = serialized.at(0) ?? "";
-    for (let index = 1; index < serialized.length; index += 1) {
-        const next = serialized[index] ?? "";
-        const fraction = sharedPrefixFraction(previous, next);
+    let cacheableObserved = 1;
+    let previous = captured.at(0) ?? { providerPrefix: "", cacheablePrefix: "" };
+    // Collect every gap first: an allowed reset must not be hidden by a later assert, and the
+    // vacuity check needs the whole list to prove the fixture folded exactly as declared.
+    const gaps = [];
+    for (let index = 1; index < captured.length; index += 1) {
+        const next = captured[index] ?? previous;
+        const fraction = sharedPrefixFraction(previous.providerPrefix, next.providerPrefix);
+        const cacheableFraction = sharedPrefixFraction(previous.cacheablePrefix, next.cacheablePrefix);
         observed = Math.min(observed, fraction);
-        assert.ok(fraction >= minContinuity, `prefix stability conformance: request ${index} → ${index + 1} kept ${(fraction * 100).toFixed(1)}% of the previous provider prefix ` +
-            `(minimum ${(minContinuity * 100).toFixed(1)}%). Late skill bodies must append after the stable prefix; ` +
-            "recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it.");
+        cacheableObserved = Math.min(cacheableObserved, cacheableFraction);
+        const measured = assertOn === "cacheablePrefix" ? cacheableFraction : fraction;
+        if (measured < minContinuity)
+            gaps.push({ request: index + 1, fraction, cacheableFraction });
         previous = next;
     }
-    return { requests: serialized.length, minContinuity: observed };
+    const resets = gaps.map((gap) => gap.request);
+    const measuredLabel = assertOn === "cacheablePrefix" ? "previous cacheable prefix (tail segments excluded)" : "previous provider prefix";
+    const minimum = (minContinuity * 100).toFixed(1);
+    const observedResets = `resets ${formatResets(resets)} of ${captured.length - 1} request pairs`;
+    const firstGap = gaps[0];
+    if (firstGap !== undefined && gaps.length > allowedResets) {
+        const measured = assertOn === "cacheablePrefix" ? firstGap.cacheableFraction : firstGap.fraction;
+        assert.fail(`prefix stability conformance: request ${firstGap.request - 1} → ${firstGap.request} kept ${(measured * 100).toFixed(1)}% of the ${measuredLabel} ` +
+            `(minimum ${minimum}%), and ${gaps.length} pair(s) broke below it (${observedResets}, allowedResets ${allowedResets}). ` +
+            "Late skill bodies must append after the stable prefix; recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it. " +
+            "Pass allowedResets for the fold, compaction, or eviction the assembly performs per run, or fix the assembly so every other gap stays byte-stable.");
+    }
+    if (gaps.length < allowedResets) {
+        assert.fail(`prefix stability conformance: allowedResets is ${allowedResets} but only ${gaps.length} pair(s) broke below the minimum (${minimum}% of the ${measuredLabel}); ${observedResets}. ` +
+            "The fixture was supposed to invalidate the prefix at those boundaries — drop allowedResets for an append-only assembly, or check the fold trigger or eviction condition actually fired.");
+    }
+    return { requests: captured.length, minContinuity: observed, cacheableContinuity: cacheableObserved, resets };
 }
-/** Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else completes. */
-function fixtureProvider(requests, skillNames) {
+/**
+ * Deterministic reasoning block the fixture provider emits before each skill load when the host
+ * runs an attention compiler. Sized to be a real fraction of the request so the compiler's
+ * thinking stage (`thinkingKeepTurns`) has something to strip and the resulting fold is visible
+ * in the measured prefix.
+ */
+const FIXTURE_THINKING = "Prefix-stability fixture reasoning: the harness measures a byte-shared provider prefix, so this block exists only to give the attention-compiler thinking stage deterministic content to strip. ".repeat(17);
+/**
+ * Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else
+ * completes. With `reasoning` (the host runs an attention compiler) each skill-load round also
+ * carries a thinking block, so the compiler's thinking stage has real content to fold.
+ */
+function fixtureProvider(requests, skillNames, reasoning) {
     let call = 0;
     return {
         id: "prefix-stability-fixture",
@@ -72,6 +116,8 @@ function fixtureProvider(requests, skillNames) {
             call += 1;
             const skillName = skillNames[index >> 1];
             if (index % 2 === 0 && skillName !== undefined) {
+                if (reasoning)
+                    yield providerThinkingDelta(FIXTURE_THINKING);
                 yield { type: "tool_call", call: toolCallContent(`prefix-stability-${index}`, "load_skill", { name: skillName }) };
                 return;
             }
@@ -79,15 +125,37 @@ function fixtureProvider(requests, skillNames) {
         },
     };
 }
-/** Provider-visible payload only: messages plus the tool schema fields sent on the wire. */
-function serializeRequest(request) {
-    // One JSON fragment per message/tool so a structural array boundary never reads as a byte
-    // divergence: an appended message list stays an exact prefix of the next request.
-    const parts = [
-        ...(request.tools ?? []).map((tool) => JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters })),
-        ...request.messages.map((message) => JSON.stringify(message)),
-    ];
-    return parts.join("\n");
+/**
+ * Classifies a captured message as a tail segment: by object identity first (the default builder
+ * passes the session's own `Message` objects through), then by serialized equality for builders
+ * that clone messages. Takes the pre-serialized fragment so each message is serialized once.
+ */
+function tailClassifier(tailSegments) {
+    const identities = new Set(tailSegments.values());
+    const values = new Set([...identities].map((message) => JSON.stringify(message)));
+    return (message, fragment) => identities.has(message) || values.has(fragment);
+}
+/**
+ * Provider-visible payload only — messages plus the tool schema fields sent on the wire — measured
+ * twice: whole, and with tail segments dropped. One JSON fragment per message/tool so a structural
+ * array boundary never reads as a byte divergence: an appended message list stays an exact prefix
+ * of the next request.
+ */
+function measureRequest(request, isTail) {
+    const toolParts = (request.tools ?? []).map((tool) => JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters }));
+    const providerParts = [...toolParts];
+    const cacheableParts = [...toolParts];
+    for (const message of request.messages) {
+        const fragment = JSON.stringify(message);
+        providerParts.push(fragment);
+        if (!isTail(message, fragment))
+            cacheableParts.push(fragment);
+    }
+    return { providerPrefix: providerParts.join("\n"), cacheablePrefix: cacheableParts.join("\n") };
+}
+/** Bracket form for reset lists, e.g. `[3]` or `[3, 4]`. */
+function formatResets(resets) {
+    return `[${resets.join(", ")}]`;
 }
 /** Byte-shared prefix as a fraction of the previous request, so a shrink is a cache miss. */
 function sharedPrefixFraction(previous, next) {