@arnilo/prism 0.0.96 → 0.1.1

package/dist/agent-loops.js

@@ -1,5 +1,7 @@
-import { inputMessages } from "./input.js";
+import { AgentLoopStateError } from "./contracts.js";
 import { createId } from "./ids.js";
+import { inputMessages } from "./input.js";
+import { artifactStructuredOutputRequest, withoutStructuredOutput } from "./structured-output.js";
 function throwIfAborted(signal) {
     if (signal.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
@@ -7,7 +9,10 @@ function throwIfAborted(signal) {
 function toolResultMessage(result) {
     return {
         role: "tool",
-        content: [{ type: "tool_result", toolCallId: result.toolCallId, name: result.name, result: result.value, error: result.error }, ...(result.content ?? [])],
+        content: [
+            { type: "tool_result", toolCallId: result.toolCallId, name: result.name, result: result.value, error: result.error },
+            ...(result.content ?? []),
+        ],
         metadata: result.metadata,
     };
 }
@@ -17,12 +22,15 @@ 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;
         let nextInput = ctx.input;
         for (let turn = 1;; turn += 1) {
             throwIfAborted(ctx.signal);
+            await ctx.applyPendingSteers?.();
             ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
             const request = await ctx.assemble(nextInput, undefined, turn);
             throwIfAborted(ctx.signal);
@@ -37,10 +45,17 @@ export const singleShotLoop = {
                 ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
             }
             ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
-            if (calls.length === 0 || toolRounds >= ctx.maxToolRounds)
+            const dispatchable = dispatchableToolCalls(calls);
+            if (dispatchable.length === 0 || toolRounds >= ctx.maxToolRounds) {
+                // Soft-interrupt / late steer: keep same run going when queue still has text.
+                if (await ctx.applyPendingSteers?.()) {
+                    nextInput = [];
+                    continue;
+                }
                 break;
+            }
             toolRounds += 1;
-            await dispatchToolCallsInOrder(calls, ctx);
+            await dispatchToolCallsInOrder(dispatchable, ctx);
             nextInput = [];
         }
         return usage;
@@ -61,18 +76,56 @@ function defaultRepairer() {
 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;
             for (let turn = 1; attempts <= max; turn += 1) {
                 throwIfAborted(ctx.signal);
+                await ctx.applyPendingSteers?.();
                 ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
-                const request = await ctx.assemble(nextInput, undefined, turn);
+                let request = await ctx.assemble(nextInput, undefined, turn);
+                if (request.options?.structuredOutput)
+                    savedSchema ??= request.options.structuredOutput;
+                if (finalOnly) {
+                    if (!artifactPhase && toolRounds < ctx.maxToolRounds) {
+                        request = withoutStructuredOutput(request);
+                    }
+                    else {
+                        artifactPhase = true;
+                        request = artifactStructuredOutputRequest(request, savedSchema);
+                    }
+                }
                 throwIfAborted(ctx.signal);
                 const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
                 usage = turnUsage ?? usage;
@@ -90,13 +143,34 @@ export function generateValidateReviseLoop(opts) {
                 }
                 ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
                 if (opts.toolCalls === "bounded" && calls.length > 0) {
+                    const dispatchable = dispatchableToolCalls(calls);
+                    if (dispatchable.length === 0) {
+                        // Only provider-hosted calls; no host tool to run. Continue without charging a round.
+                        nextInput = [];
+                        continue;
+                    }
                     if (toolRounds >= ctx.maxToolRounds) {
-                        const result = { ok: false, errors: [{ message: "maximum tool rounds exceeded" }], metadata: { reason: "tool_round_limit" } };
+                        const result = {
+                            ok: false,
+                            errors: [{ message: "maximum tool rounds exceeded" }],
+                            metadata: { reason: "tool_round_limit" },
+                        };
                         ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt: attempts + 1, result });
                         return usage;
                     }
                     toolRounds += 1;
-                    await dispatchToolCallsInOrder(calls, { ...ctx, toolConcurrency: 1 });
+                    await dispatchToolCallsInOrder(dispatchable, { ...ctx, toolConcurrency: 1 });
+                    nextInput = [];
+                    continue;
+                }
+                // Soft-interrupt / late steer before treating empty/final output as artifact work.
+                if (await ctx.applyPendingSteers?.()) {
+                    nextInput = [];
+                    continue;
+                }
+                // Call-free during tool phase → one more turn with schema on / tools off.
+                if (finalOnly && !artifactPhase) {
+                    artifactPhase = true;
                     nextInput = [];
                     continue;
                 }
@@ -125,7 +199,7 @@ export function generateValidateReviseLoop(opts) {
                     : undefined;
                 const attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
-                const result = parseFailure ?? await opts.validator(parsed.value, artifactCtx);
+                const result = parseFailure ?? (await opts.validator(parsed.value, artifactCtx));
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                 if (result.ok) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -161,14 +235,18 @@ export function resolveToolConcurrency(options, config) {
         return 1;
     return Math.floor(value);
 }
+/** Calls the host must dispatch. Provider-hosted calls (`authority: "provider-hosted"`)
+ *  were already executed server-side; the assistant response text carries their effect, so
+ *  the host neither dispatches them nor appends a `tool_result`. */
+export function dispatchableToolCalls(calls) {
+    return calls.filter((call) => call.authority !== "provider-hosted");
+}
 /** Dispatch tool calls with bounded concurrency; append transcript rows in call order. */
 export async function dispatchToolCallsInOrder(calls, ctx) {
     if (calls.length === 0)
         return;
-    ctx.chargeToolRound?.(calls);
-    const concurrency = calls.some((call) => ctx.isToolCallExclusive?.(call))
-        ? 1
-        : Math.max(1, Math.min(ctx.toolConcurrency, calls.length));
+    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) {
             const result = await ctx.dispatchToolCall(call);
@@ -191,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);
@@ -214,6 +298,7 @@ export function resolveLoop(options, config) {
                 repairer: loop.repairer,
                 maxRevisions: loop.maxRevisions,
                 toolCalls: loop.toolCalls,
+                structuredOutputTiming: loop.structuredOutputTiming,
             });
         }
         throw new Error(`Unknown agent loop strategy: ${strategy}`);

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

@@ -1,5 +1,4 @@
-import type { Agent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunStatusResult, OwnershipScope } from "./contracts.js";
-import type { CheckpointStore } from "./contracts.js";
+import type { Agent, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
 export interface AgentRunLifecycleAgent {
     readonly agent: Agent;
     /** Current host-authored revision; it must match the stored revision. */
@@ -20,9 +19,13 @@ export interface AgentRunLifecycleRequest {
     /** Adapter-selected capability; stored runs for another agent are non-enumerable. */
     readonly agentId?: string;
 }
+/** Bounded live-event options for a durable lifecycle resume. */
+export interface AgentRunLifecycleStreamRequest extends AgentRunLifecycleRequest, SubscribeOptions {
+}
 export interface AgentRunLifecycle {
     status(ref: AgentRunRef, options?: AgentRunLifecycleRequest): Promise<AgentRunStatusResult>;
     resume(ref: AgentRunRef, resume: AgentRunResume, options?: AgentRunLifecycleRequest): Promise<AgentRunResult>;
+    resumeStream(ref: AgentRunRef, resume: AgentRunResume, options?: AgentRunLifecycleStreamRequest): AsyncIterable<AgentEvent>;
 }
 /** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
 export declare function createAgentRunLifecycle(options: AgentRunLifecycleOptions): AgentRunLifecycle;

package/dist/agent-run-lifecycle.js

@@ -1,6 +1,6 @@
-import { AgentRunStateError } from "./contracts.js";
 import { loadAgentRunState, publicState } from "./agent-run-state.js";
-import { resumeAgentRun } from "./agents.js";
+import { resumeAgentRun, resumeAgentRunStream } from "./agents.js";
+import { AgentRunStateError } from "./contracts.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
         throw new AgentRunStateError("Agent run capability mismatch");
@@ -28,6 +28,22 @@ export function createAgentRunLifecycle(options) {
                 definitionRevision: resolved.definitionRevision,
             });
         },
+        async *resumeStream(ref, resume, request = {}) {
+            request.signal?.throwIfAborted();
+            const { state } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
+            assertAgentId(state.agentId, request.agentId);
+            const resolved = await options.resolveAgent({ agentId: state.agentId, ownership: request.ownership, signal: request.signal });
+            request.signal?.throwIfAborted();
+            yield* resumeAgentRunStream(resolved.agent, ref, resume, {
+                checkpoints: options.checkpoints,
+                ownership: request.ownership,
+                fencingToken: options.fencingToken,
+                definitionRevision: resolved.definitionRevision,
+                signal: request.signal,
+                maxQueuedEvents: request.maxQueuedEvents,
+                overflow: request.overflow,
+            });
+        },
     };
 }
 //# sourceMappingURL=agent-run-lifecycle.js.map

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,27 +1,83 @@
 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;
+    const skills = !config.skills ? [] : "list" in config.skills ? config.skills.list() : config.skills;
     const guardrails = [
         ...(config.guardrails?.input ?? []),
         ...(config.guardrails?.output ?? []),
         ...(config.guardrails?.toolInput ?? []),
         ...(config.guardrails?.toolOutput ?? []),
     ];
+    const systemPrompt = config.systemPrompt === false || config.systemPrompt === undefined
+        ? (config.systemPrompt ?? null)
+        : (Array.isArray(config.systemPrompt) ? config.systemPrompt : [config.systemPrompt]).map((c) => ({ id: c.id, text: c.text }));
     const value = JSON.stringify({
         id: config.id ?? config.name ?? "agent",
         revision,
         model: config.model,
-        tools: tools.map((tool) => ({ name: tool.name, parameters: tool.parameters, exclusive: tool.exclusive })),
+        // Instructions/prompt text shapes agent behavior as much as the tool set; a change
+        // without a definitionRevision bump must not resume stale durable runs silently.
+        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,
+            effect: typeof tool.effect === "function" ? "classifier" : tool.effect,
+        })),
         guardrails: guardrails.map((guardrail) => ({ name: guardrail.name, stage: guardrail.stage, revision: guardrail.revision })),
-        loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop ? config.loop.strategy : config.loop?.name ?? "single-shot",
+        // Loop revision participates so a loop change without a definitionRevision bump fails closed.
+        loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop
+            ? { 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");
 }
@@ -43,7 +99,10 @@ export async function loadAgentRunState(checkpoints, ref, ownership) {
     const record = await checkpoints.loadCheckpoint({ namespace: AGENT_RUN_STATE_NAMESPACE, key: ref.runId, ...ownership });
     if (!record)
         throw new AgentRunStateError(`No durable agent run ${ref.runId}`);
-    if (ref.sessionId && record.value && typeof record.value === "object" && record.value.sessionId !== ref.sessionId) {
+    if (ref.sessionId &&
+        record.value &&
+        typeof record.value === "object" &&
+        record.value.sessionId !== ref.sessionId) {
         throw new AgentRunStateError("Agent run session mismatch");
     }
     return { record, state: parseAgentRunState(record.value, record.version) };
@@ -66,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) {
@@ -84,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,
@@ -95,10 +155,56 @@ export function parseAgentRunState(value, version) {
     const state = value;
     if (state.schemaVersion !== AGENT_RUN_STATE_SCHEMA_VERSION)
         throw new AgentRunStateError(`Unsupported agent run state schemaVersion ${String(state.schemaVersion)}`);
-    if (!state.agentId || !state.definitionRevision || !state.fingerprint || !state.runId || !state.sessionId || !state.model || !state.status || !state.counters || !state.deadlineAt) {
+    if (!state.agentId ||
+        !state.definitionRevision ||
+        !state.fingerprint ||
+        !state.runId ||
+        !state.sessionId ||
+        !state.model ||
+        !state.status ||
+        !state.counters ||
+        !state.deadlineAt) {
         throw new AgentRunStateError("Malformed agent run state");
     }
-    return boundState({ ...state, version }, DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    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.
+    return boundState({ ...state, version }, HARD_MAX_AGENT_RUN_STATE_BYTES);
 }
 function boundState(state, maxBytes) {
     checkShape(state, 0);

package/dist/agents.d.ts

@@ -1,7 +1,9 @@
-import type { Agent, AgentConfig, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunRef, AgentSession, AgentSessionConfig } from "./contracts.js";
+import type { Agent, AgentConfig, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentSession, AgentSessionConfig } from "./contracts.js";
 export declare function createAgent(config: AgentConfig): Agent;
 export declare function createAgentSession(config: AgentSessionConfig & {
     readonly agent: Agent;
 }): AgentSession;
 /** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
 export declare function resumeAgentRun(agent: Agent, ref: AgentRunRef, resume: AgentRunResume, options: AgentRunResumeOptions): Promise<AgentRunResult>;
+/** Subscribe before resuming one durable run. Early consumer return aborts that resumed execution. */
+export declare function resumeAgentRunStream(agent: Agent, ref: AgentRunRef, resume: AgentRunResume, options: AgentRunResumeStreamOptions): AsyncGenerator<AgentEvent>;