@arnilo/prism 0.8.0 → 0.10.0

package/dist/agent-run-state.d.ts

@@ -1,11 +1,13 @@
-import { type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
-import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
+import { type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
+import type { Agent, AgentRunCheckpointMetadata, AgentRunCheckpointMetadataSource, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, GuardrailRule, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export declare const AGENT_RUN_STATE_SCHEMA_VERSION: 1;
 export declare const DEFAULT_MAX_AGENT_RUN_STATE_BYTES: number;
 export declare const HARD_MAX_AGENT_RUN_STATE_BYTES: number;
+/** Sidecar metadata ceiling per checkpoint record (not the run-state value). */
+export declare const MAX_AGENT_RUN_METADATA_BYTES: number;
 /** One gated tool call awaiting or holding a decision inside a suspended durable run. */
 export interface PendingToolCall {
     readonly call: ToolCallContent;
@@ -50,6 +52,13 @@ export interface StoredAgentRunState extends AgentRunState {
         /** Plan 074 P3: sticky attention mutations (thinking hashes + tool-call ids), so a durable
          *  resume keeps its stubs instead of re-deciding on the first turn. Validated on load. */
         readonly attentionSticky?: PersistedAttentionStickyFrontier;
+        /** Plan 086 T3: folded bodies (`attention.compiler.durable`), so a resumed fold re-applies
+         *  the same stub bytes instead of re-summarizing. Written and restored independently of
+         *  `persistSessionState`. Validated on load. */
+        readonly attentionFold?: PersistedAttentionFoldLedger;
+        /** Plan 104 T2: compiled pack refs plus pack-owned state, so a resume re-enforces exactly what
+         *  the suspended run enforced. Written only with `persistSessionState`; validated on load. */
+        readonly guardrailPacks?: PersistedGuardrailPacks;
     };
     /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */
     readonly toolNames?: readonly string[];
@@ -60,17 +69,34 @@ export interface StoredAgentRunState extends AgentRunState {
      */
     readonly checkpointPolicy?: "every-turn";
     /**
-     * Set when a terminal state was written by a `RunOptions.turnPolicy` stop (plan 084 Task 2):
-     * the run succeeded cleanly but its frontier is intact, so `decision: "continue"` may resume
-     * it. Absent on every other state — a naturally finished run is never continuable.
+     * Set when a terminal state was written by a clean run-end stop that leaves the frontier intact:
+     * a `RunOptions.turnPolicy` stop (`host_policy`, plan 084 Task 2) or a stop-hook continuation cap
+     * (`hook_limit`, plan 106 R1). The run succeeded but `decision: "continue"` may resume it. Absent
+     * on every other state — a naturally finished run is never continuable.
      */
-    readonly stopReason?: "host_policy";
+    readonly stopReason?: "host_policy" | "hook_limit";
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;
 export declare const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
 /** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
 export declare const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
+/** Plan 104 T2: one replayable pack row — the id, the version it was compiled at, and host options. */
+interface PersistedGuardrailPackRef {
+    readonly id: string;
+    readonly version: number;
+    readonly options?: Readonly<Record<string, unknown>>;
+    /** Inline pattern rules; closures and `RegExp` patterns never reach a checkpoint (refused at save). */
+    readonly rules?: readonly GuardrailRule[];
+}
+/**
+ * Plan 104 T2: the checkpoint-side pack block written with `persistSessionState`. Rows replay a
+ * registered pack by `id`/`version` or an inline pack by its pattern `rules` (plan 104 T3).
+ */
+export interface PersistedGuardrailPacks {
+    readonly packs: readonly PersistedGuardrailPackRef[];
+    readonly state?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export declare const BUILT_IN_LOOP_REVISIONS: Readonly<Record<string, string>>;
 /** Validate a strategy snapshot as JSON-compatible and package it for the durable envelope. */
@@ -81,7 +107,20 @@ export declare function validateRunStateOptions(options: AgentRunStateOptions):
 export declare function loadAgentRunState(checkpoints: CheckpointStore, ref: AgentRunRef, ownership?: OwnershipScope): Promise<{
     readonly record: CheckpointRecord;
     readonly state: StoredAgentRunState;
+    readonly metadata?: AgentRunCheckpointMetadata;
 }>;
+/** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */
+export declare function resolveCheckpointMetadata(source: AgentRunCheckpointMetadataSource | undefined): AgentRunCheckpointMetadata | undefined;
+/**
+ * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings;
+ * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling.
+ */
+export declare function boundCheckpointMetadata(metadata: AgentRunCheckpointMetadata, redactor?: SecretRedactor): AgentRunCheckpointMetadata;
+/**
+ * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are
+ * dropped, never thrown — a malformed sidecar must not block a resume.
+ */
+export declare function readCheckpointMetadata(metadata: unknown): AgentRunCheckpointMetadata | undefined;
 export declare function saveAgentRunState(input: {
     readonly checkpoints: CheckpointStore;
     readonly state: StoredAgentRunState;
@@ -90,6 +129,7 @@ export declare function saveAgentRunState(input: {
     readonly fencingToken?: number;
     readonly redactor?: SecretRedactor;
     readonly maxStateBytes?: number;
+    readonly metadata?: AgentRunCheckpointMetadata;
 }): Promise<{
     readonly record: CheckpointRecord;
     readonly state: StoredAgentRunState;
@@ -112,3 +152,4 @@ export declare function initialAgentRunState(input: {
     readonly interruptBeforeTool?: boolean;
 }): StoredAgentRunState;
 export declare function parseAgentRunState(value: unknown, version?: number): StoredAgentRunState;
+export {};

package/dist/agent-run-state.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
+import { parseAttentionStickyFrontier, restoreAttentionFoldLedger, } from "./attention-compiler.js";
 import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
 import { validateLoadedSkillBodies } from "./skill-load.js";
 import { HARD_RUN_TOOL_NAMES } from "./tools.js";
@@ -7,6 +7,8 @@ export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
 export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
 export const HARD_MAX_AGENT_RUN_STATE_BYTES = 1024 * 1024;
+/** Sidecar metadata ceiling per checkpoint record (not the run-state value). */
+export const MAX_AGENT_RUN_METADATA_BYTES = 4 * 1024;
 const MAX_DEPTH = 32;
 const MAX_PROPERTIES = 256;
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
@@ -14,6 +16,12 @@ export const MAX_PERSISTED_SKILL_NAMES = 64;
 export const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
 /** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
 export const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
+/** Plan 104 T2: persisted pack refs and state (cap matches `MAX_GUARDRAIL_PACKS`; ids match the pack cap). */
+const MAX_PERSISTED_GUARDRAIL_PACKS = 8;
+const MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS = 96;
+const MAX_PERSISTED_GUARDRAIL_PACK_RULES = 64;
+/** Per-pack options/state byte ceiling; the whole session state is still bounded by `maxStateBytes`. */
+const MAX_PERSISTED_GUARDRAIL_PACK_BYTES = 8 * 1024;
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export const BUILT_IN_LOOP_REVISIONS = {
     "single-shot": "1",
@@ -116,10 +124,55 @@ export async function loadAgentRunState(checkpoints, ref, ownership) {
         record.value.sessionId !== ref.sessionId) {
         throw new AgentRunStateError("Agent run session mismatch");
     }
-    return { record, state: parseAgentRunState(record.value, record.version) };
+    const metadata = readCheckpointMetadata(record.metadata);
+    return { record, state: parseAgentRunState(record.value, record.version), ...(metadata ? { metadata } : {}) };
+}
+/** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */
+export function resolveCheckpointMetadata(source) {
+    return typeof source === "function" ? source() : source;
+}
+function checkpointMetadataBytes(metadata) {
+    return Buffer.byteLength(JSON.stringify(metadata), "utf8");
+}
+/**
+ * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings;
+ * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling.
+ */
+export function boundCheckpointMetadata(metadata, redactor) {
+    const redacted = redactor?.redact(metadata) ?? metadata;
+    if (!redacted || typeof redacted !== "object" || Array.isArray(redacted)) {
+        throw new AgentRunStateError("Checkpoint metadata must be an object");
+    }
+    const bounded = {};
+    for (const [key, value] of Object.entries(redacted)) {
+        if (typeof value !== "string")
+            throw new AgentRunStateError(`Checkpoint metadata value for ${key} must be a string`);
+        bounded[key] = value;
+    }
+    if (checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES) {
+        throw new AgentRunStateError(`Checkpoint metadata exceeds ${MAX_AGENT_RUN_METADATA_BYTES} bytes`);
+    }
+    return Object.freeze(bounded);
+}
+/**
+ * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are
+ * dropped, never thrown — a malformed sidecar must not block a resume.
+ */
+export function readCheckpointMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return undefined;
+    const bounded = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value === "string")
+            bounded[key] = value;
+    }
+    if (Object.keys(bounded).length === 0 || checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES)
+        return undefined;
+    return Object.freeze(bounded);
 }
 export async function saveAgentRunState(input) {
     const bounded = boundState(input.redactor?.redact(input.state) ?? input.state, input.maxStateBytes ?? DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    const metadata = input.metadata === undefined ? undefined : boundCheckpointMetadata(input.metadata, input.redactor);
     const record = await input.checkpoints.saveCheckpoint({
         namespace: AGENT_RUN_STATE_NAMESPACE,
         key: bounded.runId,
@@ -128,6 +181,7 @@ export async function saveAgentRunState(input) {
         fencingToken: input.fencingToken,
         value: bounded,
         category: "agent-run",
+        ...(metadata ? { metadata } : {}),
         ...input.ownership,
     });
     return { record, state: { ...bounded, version: record.version } };
@@ -222,7 +276,7 @@ export function parseAgentRunState(value, version) {
     if (state.checkpointPolicy !== undefined && state.checkpointPolicy !== "every-turn") {
         throw new AgentRunStateError("Malformed agent run checkpoint policy");
     }
-    if (state.stopReason !== undefined && state.stopReason !== "host_policy") {
+    if (state.stopReason !== undefined && state.stopReason !== "host_policy" && state.stopReason !== "hook_limit") {
         throw new AgentRunStateError("Malformed agent run stop reason");
     }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
@@ -294,12 +348,106 @@ function validateSessionState(sessionState) {
         }
     }
     const attention = sessionState.attentionSticky;
-    if (attention === undefined)
-        return;
     // Both arrays are capped by the parser, and a malformed frontier is dropped rather than
     // failing the resume: re-deciding a mutation is safe, refusing to resume is not.
-    if (parseAttentionStickyFrontier(attention) === undefined) {
+    if (attention !== undefined && parseAttentionStickyFrontier(attention) === undefined) {
         throw new AgentRunStateError("Malformed agent run attention frontier");
     }
+    // Plan 086 T3: the fold ledger gets the same treatment — malformed entries are dropped by the
+    // parser, a malformed shape fails the load rather than the first provider turn.
+    const fold = sessionState.attentionFold;
+    if (fold !== undefined && restoreAttentionFoldLedger(fold) === undefined) {
+        throw new AgentRunStateError("Malformed agent run attention fold ledger");
+    }
+    validateGuardrailPackState(sessionState.guardrailPacks);
+}
+/**
+ * Plan 104 T2/T3: bounds for the persisted pack block. Rows replay a registered pack by id/version or
+ * an inline pack by its pattern rules, and state may only name those rows — anything else fails the
+ * load, because a dropped pack silently re-allows what it existed to deny. Rule data is re-validated
+ * (pattern compile, id/reason caps) by the compiler that replays it; this checks the JSON envelope.
+ */
+function validateGuardrailPackState(value) {
+    if (value === undefined)
+        return;
+    const raw = value;
+    if (!raw || typeof raw !== "object" || !Array.isArray(raw.packs)) {
+        throw new AgentRunStateError("Malformed agent run guardrail pack state");
+    }
+    if (raw.packs.length > MAX_PERSISTED_GUARDRAIL_PACKS) {
+        throw new AgentRunStateError(`Persisted guardrail packs exceed ${MAX_PERSISTED_GUARDRAIL_PACKS} entries`);
+    }
+    const ids = new Set();
+    for (const row of raw.packs) {
+        if (!isPlainObject(row))
+            throw new AgentRunStateError("Malformed agent run guardrail pack row");
+        const { id, version, options } = row;
+        if (typeof id !== "string" || !id.trim() || id.length > MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS) {
+            throw new AgentRunStateError(`Persisted guardrail pack ids must be non-empty strings of at most ${MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS} chars`);
+        }
+        if (ids.has(id))
+            throw new AgentRunStateError(`Duplicate persisted guardrail pack id "${id}"`);
+        ids.add(id);
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" version must be a positive integer`);
+        }
+        if (options !== undefined && !isPlainObject(options)) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" options must be an object`);
+        }
+        if (options !== undefined)
+            boundPackBytes(options, `Pack "${id}" options`);
+        validatePersistedPackRules(id, row);
+    }
+    if (raw.state === undefined)
+        return;
+    if (!isPlainObject(raw.state))
+        throw new AgentRunStateError("Malformed agent run guardrail pack state");
+    for (const [id, state] of Object.entries(raw.state)) {
+        if (!ids.has(id))
+            throw new AgentRunStateError(`Persisted guardrail pack state names unknown pack "${id}"`);
+        if (!isPlainObject(state))
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" state must be an object`);
+        boundPackBytes(state, `Pack "${id}" state`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Plan 104 T3: a persisted inline pack must be pattern data — a closure or `RegExp` cannot restore. */
+function validatePersistedPackRules(id, row) {
+    if (row.rules === undefined)
+        return;
+    if (!Array.isArray(row.rules))
+        throw new AgentRunStateError(`Persisted guardrail pack "${id}" rules must be an array`);
+    if (row.rules.length === 0 || row.rules.length > MAX_PERSISTED_GUARDRAIL_PACK_RULES) {
+        throw new AgentRunStateError(`Persisted guardrail pack "${id}" rules must number 1..${MAX_PERSISTED_GUARDRAIL_PACK_RULES}`);
+    }
+    for (const rule of row.rules) {
+        if (!isPlainObject(rule))
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule must be an object`);
+        const { id: ruleId, pattern, deny } = rule;
+        if (typeof ruleId !== "string" || !ruleId.trim() || ruleId.length > MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule ids must be non-empty strings`);
+        }
+        if (deny !== undefined)
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule "${ruleId}" carries a deny predicate`);
+        if (pattern !== undefined && typeof pattern !== "string") {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule "${ruleId}" pattern must be a string`);
+        }
+        boundPackBytes(rule, `Pack "${id}" rule "${ruleId}"`);
+    }
+}
+/** A pack's state must be JSON and under its per-pack ceiling: refuse, never truncate. */
+function boundPackBytes(value, label) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        throw new AgentRunStateError(`${label} must be JSON serializable`);
+    }
+    if ((text ? Buffer.byteLength(text) : 0) > MAX_PERSISTED_GUARDRAIL_PACK_BYTES) {
+        throw new AgentRunStateError(`${label} exceeds ${MAX_PERSISTED_GUARDRAIL_PACK_BYTES} bytes`);
+    }
 }
 //# sourceMappingURL=agent-run-state.js.map

package/dist/agent-session/event-subscriber.d.ts

@@ -3,6 +3,8 @@ import type { AgentEvent, SubscribeOptions } from "../contracts.js";
 export declare class EventSubscriber implements AsyncIterable<AgentEvent>, AsyncIterator<AgentEvent> {
     private readonly sessionId;
     private readonly onClose;
+    /** Plan 104 T5: run-scoped unless the host opted into `acrossRuns`. */
+    readonly acrossRuns: boolean;
     private readonly queue;
     private readonly waiters;
     private readonly maxQueuedEvents;

package/dist/agent-session/event-subscriber.js

@@ -1,6 +1,8 @@
 export class EventSubscriber {
     sessionId;
     onClose;
+    /** Plan 104 T5: run-scoped unless the host opted into `acrossRuns`. */
+    acrossRuns;
     queue = [];
     waiters = [];
     maxQueuedEvents;
@@ -12,6 +14,7 @@ export class EventSubscriber {
         const maxQueuedEvents = options.maxQueuedEvents ?? 1024;
         this.maxQueuedEvents = Number.isFinite(maxQueuedEvents) ? Math.max(1, Math.floor(maxQueuedEvents)) : 1024;
         this.overflow = options.overflow ?? "close";
+        this.acrossRuns = options.acrossRuns === true;
     }
     [Symbol.asyncIterator]() {
         return this;

package/dist/agent-session/helpers.js

@@ -160,6 +160,8 @@ export function createUsageAccumulator() {
     const sums = new Map();
     let costCurrency;
     let costCompatible = true;
+    let estimated = false;
+    let confidence;
     return {
         add(usage) {
             for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
@@ -181,6 +183,13 @@ export function createUsageAccumulator() {
                 if (costCompatible)
                     sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
             }
+            // Run totals keep estimate provenance (plan 091 T2): one estimated turn
+            // labels the total, and the weakest confidence wins.
+            if (usage.estimated === true) {
+                estimated = true;
+                if (usage.confidence !== undefined && (confidence === undefined || usage.confidence === "low"))
+                    confidence = usage.confidence;
+            }
         },
         value() {
             if (sums.size === 0)
@@ -192,6 +201,11 @@ export function createUsageAccumulator() {
             }
             if (costCompatible && sums.has("cost") && costCurrency !== undefined)
                 usage.currency = costCurrency;
+            if (estimated) {
+                usage.estimated = true;
+                if (confidence !== undefined)
+                    usage.confidence = confidence;
+            }
             return Object.keys(usage).length > 0 ? usage : undefined;
         },
     };