@arnilo/prism 0.0.24 → 0.0.25

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.0.25] - 2026-08-06
+
+### Added
+- Durable custom `AgentLoopStrategy` hooks: optional `revision` / `snapshot` / `restore`; `AgentLoopStateError` fail-closed codes; fingerprint includes loop `{name,revision}`.
+- Shared pending-decision model: parallel approvals, batch CAS `decisions`, sticky allow/reject for run, modified arguments, elicitation; nested supervisor attribution.
+- Protocol mappings: AG-UI/ACP/server batch resume, MCP elicitation helpers, coding `ask_user_decision` elicitation hook.
+- Opt-in A2UI painting middleware + standard AG-UI projectors (`messages`/`state`/`activity`).
+- Network-free Phase 8 conformance + `benchmark-0.0.25.json` evidence; examples `durable-loops-and-approvals.ts`, `ag-ui-a2ui.ts`.
+
+### Changed
+- Publishable graph remains **47** manifests at **0.0.25**.
+- Fingerprint loop entry shape `string` → `{name,revision}` (0.0.24 persisted durable runs fail closed on resume).
+
+### Breaking (minor, pre-1.0)
+- Custom loops on durable runs need snapshot/restore hooks or `ERR_PRISM_LOOP_NOT_DURABLE`.
+- Resume prefers `decisions: RunDecision[]`; legacy binary `decision` remains but is exclusive with the batch path.
+- ACP permission offers four outcomes; `reject_once` is blocked-continue (cancelled stays terminal deny).
+
+See [docs/migration.md](docs/migration.md) for the 0.0.24 → 0.0.25 guide.
+
 ## [0.0.24] - 2026-08-04
 
 ### Added

package/dist/agent-loops.js

@@ -1,3 +1,4 @@
+import { AgentLoopStateError } from "./contracts.js";
 import { createId } from "./ids.js";
 import { inputMessages } from "./input.js";
 import { artifactStructuredOutputRequest, withoutStructuredOutput } from "./structured-output.js";
@@ -21,6 +22,8 @@ function toolResultMessage(result) {
 // fires artifact_* events here as a noop seam — single-shot emits zero.
 export const singleShotLoop = {
     name: "single-shot",
+    // Durable via the runtime's pending-call mechanism; no loop-local state to snapshot.
+    revision: "1",
     async run(ctx) {
         let usage;
         let toolRounds = 0;
@@ -74,16 +77,39 @@ export function generateValidateReviseLoop(opts) {
     const max = opts.maxRevisions ?? 3;
     const repairer = opts.repairer ?? defaultRepairer();
     const finalOnly = opts.structuredOutputTiming === "final-turn-only" && opts.toolCalls === "bounded";
+    // ponytail: per-run state hoisted to factory scope so snapshot/restore can capture it;
+    // resolveLoop invokes this factory once per run, so there is no cross-run leakage.
+    let attempts = 0;
+    let artifactPhase = !finalOnly;
+    let savedSchema;
+    let pendingHistory = [];
     return {
         name: "generate-validate-revise",
+        revision: "1",
+        snapshot() {
+            return {
+                attempts,
+                artifactPhase,
+                savedSchema: savedSchema ?? null,
+                pendingHistory,
+            };
+        },
+        restore(snapshot) {
+            const state = snapshot;
+            if (typeof state.attempts !== "number" || !Number.isInteger(state.attempts) || typeof state.artifactPhase !== "boolean") {
+                throw new AgentLoopStateError("ERR_PRISM_LOOP_SNAPSHOT", "generate-validate-revise snapshot drift");
+            }
+            attempts = state.attempts;
+            artifactPhase = state.artifactPhase;
+            savedSchema = (state.savedSchema ?? undefined);
+            // Repair messages were appended to the session before suspension, so the rebuilt
+            // history already carries them; re-applying pendingHistory would duplicate them.
+            pendingHistory = [];
+        },
         async run(ctx) {
             let usage;
             let nextInput = ctx.input;
-            let pendingHistory = [];
             let toolRounds = 0;
-            let attempts = 0;
-            let artifactPhase = !finalOnly;
-            let savedSchema;
             for (let turn = 1; attempts <= max; turn += 1) {
                 throwIfAborted(ctx.signal);
                 await ctx.applyPendingSteers?.();
@@ -219,7 +245,7 @@ export function dispatchableToolCalls(calls) {
 export async function dispatchToolCallsInOrder(calls, ctx) {
     if (calls.length === 0)
         return;
-    ctx.chargeToolRound?.(calls);
+    await ctx.chargeToolRound?.(calls);
     const concurrency = calls.some((call) => ctx.isToolCallExclusive?.(call)) ? 1 : Math.max(1, Math.min(ctx.toolConcurrency, calls.length));
     if (concurrency === 1) {
         for (const call of calls) {
@@ -243,10 +269,16 @@ export async function dispatchToolCallsInOrder(calls, ctx) {
     await Promise.all(workers);
     for (const result of results) {
         throwIfAborted(ctx.signal);
+        if (!result)
+            continue;
         await appendToolResultMessage(result, ctx);
     }
 }
 async function appendToolResultMessage(result, ctx) {
+    // Approval-gated calls return a marker instead of a real result; the transcript must not
+    // record a phantom tool_result for a call that never dispatched.
+    if (result.metadata?.approvalPending === true)
+        return;
     const message = toolResultMessage(result);
     ctx.history.push(message);
     await ctx.appendMessage(message);

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;
@@ -35,9 +74,10 @@ export function agentFingerprint(agent, revision) {
             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");
 }
@@ -85,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) {
@@ -103,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,
@@ -125,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.