@arnilo/prism 0.0.23 → 0.0.25

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

@@ -1,19 +1,44 @@
-import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, AgentRunStatusResult, CheckpointRecord, CheckpointStore, Message, ModelConfig, OwnershipScope, RunLimitCounters, ToolCallContent } from "./contracts.js";
+import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, AgentRunStatusResult, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.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;
+/** One gated tool call awaiting or holding a decision inside a suspended durable run. */
+export interface PendingToolCall {
+    readonly call: ToolCallContent;
+    readonly status: "ready" | "dispatched";
+    readonly approvalId: string;
+    /** Decision persisted by a partial batch; applied when the run finally resumes. */
+    readonly decision?: RunDecision;
+}
 export interface StoredAgentRunState extends AgentRunState {
     readonly input?: readonly Message[];
+    /** Legacy single gated call (pre-0.0.25 checkpoints). New states write `pendingCalls`. */
     readonly pending?: {
         readonly call: ToolCallContent;
         readonly status: "ready" | "dispatched";
     };
+    /** Gated calls of the current suspension, in provider-turn order. */
+    readonly pendingCalls?: readonly PendingToolCall[];
+    /** Suspended nested runs (supervisor children) whose pending decisions surface at this root. */
+    readonly nestedRuns?: readonly NestedRunRef[];
+    /** Run-scoped sticky decisions; exact scope match, dropped at any terminal status. */
+    readonly stickyDecisions?: readonly StickyDecision[];
     readonly interruptBeforeTool?: boolean;
     readonly counters: RunLimitCounters;
     readonly deadlineAt: string;
+    /** Loop-local durable state captured by the strategy's snapshot hook at suspension. */
+    readonly loopState?: {
+        readonly name: string;
+        readonly revision: string;
+        readonly snapshot: JsonValue;
+    };
 }
+/** 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. */
+export declare function boundedLoopSnapshot(name: string, revision: string, snapshot: JsonValue): StoredAgentRunState["loopState"];
 export declare function agentFingerprint(agent: Agent, revision: string): string;
 export declare function agentId(agent: Agent): string;
 export declare function validateRunStateOptions(options: AgentRunStateOptions): void;
@@ -48,6 +73,7 @@ export declare function initialAgentRunState(input: {
     readonly interruption?: AgentRunInterruption;
     readonly messages?: readonly Message[];
     readonly pending?: StoredAgentRunState["pending"];
+    readonly pendingCalls?: StoredAgentRunState["pendingCalls"];
     readonly interruptBeforeTool?: boolean;
 }): StoredAgentRunState;
 export declare function parseAgentRunState(value: unknown, version?: number): StoredAgentRunState;

package/dist/agent-run-state.js

@@ -1,11 +1,50 @@
 import { createHash } from "node:crypto";
-import { AgentRunStateError } from "./contracts.js";
+import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
 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;
 const MAX_DEPTH = 32;
 const MAX_PROPERTIES = 256;
+/** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
+export const BUILT_IN_LOOP_REVISIONS = {
+    "single-shot": "1",
+    "generate-validate-revise": "1",
+};
+/** Validate a strategy snapshot as JSON-compatible and package it for the durable envelope. */
+export function boundedLoopSnapshot(name, revision, snapshot) {
+    try {
+        assertJsonValue(snapshot, 0);
+    }
+    catch (error) {
+        if (error instanceof AgentLoopStateError)
+            throw error;
+        throw new AgentLoopStateError("ERR_PRISM_LOOP_SNAPSHOT", "Loop snapshot must be JSON-compatible", { cause: error });
+    }
+    return { name, revision, snapshot };
+}
+function assertJsonValue(value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new AgentLoopStateError("ERR_PRISM_LOOP_SNAPSHOT", `Loop snapshot exceeds depth ${MAX_DEPTH}`);
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return;
+        case "number":
+            if (!Number.isFinite(value))
+                throw new AgentLoopStateError("ERR_PRISM_LOOP_SNAPSHOT", "Loop snapshot numbers must be finite");
+            return;
+        case "object": {
+            if (value === null)
+                return;
+            for (const item of Object.values(value))
+                assertJsonValue(item, depth + 1);
+            return;
+        }
+        default:
+            throw new AgentLoopStateError("ERR_PRISM_LOOP_SNAPSHOT", "Loop snapshot must be JSON-compatible");
+    }
+}
 export function agentFingerprint(agent, revision) {
     const config = agent.config;
     const tools = !config.tools ? [] : "list" in config.tools ? config.tools.list() : config.tools;
@@ -28,11 +67,17 @@ export function agentFingerprint(agent, revision) {
         instructions: config.instructions ?? null,
         systemPrompt,
         skills: skills.map((skill) => ({ name: skill.name, instructions: skill.instructions, toolNames: skill.toolNames })),
-        tools: tools.map((tool) => ({ name: tool.name, parameters: tool.parameters, exclusive: tool.exclusive })),
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            parameters: tool.parameters,
+            exclusive: tool.exclusive,
+            effect: typeof tool.effect === "function" ? "classifier" : tool.effect,
+        })),
         guardrails: guardrails.map((guardrail) => ({ name: guardrail.name, stage: guardrail.stage, revision: guardrail.revision })),
+        // Loop revision participates so a loop change without a definitionRevision bump fails closed.
         loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop
-            ? config.loop.strategy
-            : (config.loop?.name ?? "single-shot"),
+            ? { name: config.loop.strategy, revision: BUILT_IN_LOOP_REVISIONS[config.loop.strategy] ?? null }
+            : { name: config.loop?.name ?? "single-shot", revision: config.loop?.revision ?? BUILT_IN_LOOP_REVISIONS["single-shot"] },
     });
     return createHash("sha256").update(value).digest("hex");
 }
@@ -80,7 +125,7 @@ export function statusFromState(state, version) {
     return { state: publicState({ ...state, version }), version };
 }
 export function publicState(state) {
-    const { input: _input, pending: _pending, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, ...publicValue } = state;
+    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, ...publicValue } = state;
     return publicValue;
 }
 export function initialAgentRunState(input) {
@@ -98,6 +143,7 @@ export function initialAgentRunState(input) {
         interruption: input.interruption,
         input: input.messages,
         pending: input.pending,
+        pendingCalls: input.pendingCalls,
         interruptBeforeTool: input.interruptBeforeTool,
         counters: input.counters,
         deadlineAt: input.deadlineAt,
@@ -120,6 +166,41 @@ export function parseAgentRunState(value, version) {
         !state.deadlineAt) {
         throw new AgentRunStateError("Malformed agent run state");
     }
+    if (state.pendingCalls !== undefined &&
+        (!Array.isArray(state.pendingCalls) ||
+            state.pendingCalls.some((entry) => !entry ||
+                typeof entry !== "object" ||
+                !entry.call ||
+                typeof entry.approvalId !== "string" ||
+                (entry.status !== "ready" && entry.status !== "dispatched")))) {
+        throw new AgentRunStateError("Malformed agent run pending calls");
+    }
+    if (state.stickyDecisions !== undefined &&
+        (!Array.isArray(state.stickyDecisions) ||
+            state.stickyDecisions.some((entry) => !entry ||
+                typeof entry !== "object" ||
+                !entry.scope ||
+                (entry.outcome !== "allow_for_run" && entry.outcome !== "reject_for_run")))) {
+        throw new AgentRunStateError("Malformed agent run sticky decisions");
+    }
+    if (state.nestedRuns !== undefined &&
+        (!Array.isArray(state.nestedRuns) ||
+            state.nestedRuns.some((entry) => !entry ||
+                typeof entry !== "object" ||
+                typeof entry.runId !== "string" ||
+                typeof entry.toolCallId !== "string" ||
+                !Array.isArray(entry.path) ||
+                !Array.isArray(entry.approvals) ||
+                entry.approvals.some((approval) => typeof approval?.id !== "string" || typeof approval?.childApprovalId !== "string")))) {
+        throw new AgentRunStateError("Malformed agent run nested runs");
+    }
+    if (state.loopState !== undefined &&
+        (typeof state.loopState !== "object" ||
+            typeof state.loopState.name !== "string" ||
+            typeof state.loopState.revision !== "string" ||
+            !("snapshot" in state.loopState))) {
+        throw new AgentRunStateError("Malformed agent run loop state");
+    }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
     // save-side policy knob, while the load-side bound is only a DoS ceiling. States saved
     // with a raised maxStateBytes must remain resumable.