@arnilo/prism 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.1.4] - 2026-08-10
+
+### Changed
+- **Release 0.1.4 (plan 016)** is the internal god-module split, compat-preserving on the frozen 0.1.x line. (1) **Contracts split** (Task 1): `src/contracts.ts` (2,549 lines) split by concern into `src/contracts-core.ts`, `src/contracts-run-state.ts`, and `src/contracts-protocol.ts` behind a pure `export *` barrel — the 295-name public surface is unchanged (0 added/0 removed/0 changed vs the 0.1.3 baseline, 702 = 702 at the entry). (2) **Agents split** (Task 2): `src/agents.ts` (2,576 lines) split into `src/agent-session.ts` (`RuntimeAgentSession` + factories + shared helpers), `src/agent-run-lifecycle.ts` (resume lifecycle), `src/agent-approval.ts`, `src/agent-tool-dispatch.ts`, with `agent-run-state.ts`/`agent-loops.ts`/`compaction.ts` reused — `agents.ts` is now a barrel of the four public functions; 14 internal cross-module helper exports joined the union `.d.ts` surface but are not consumer-importable (documented deviation #1, `scripts/phase16-freeze-manifest.json`). (3) **Tree-shake verification** (Task 3): measured in `scripts/phase16-baseline.json` — `dist/agents.js` 111,049 → 982 B, `dist/contracts.js` 9,420 → 418 B, `dist/contracts.d.ts` 98,825 → 1,029 B, dist module count 64 → 70 (static-import reachability reported, not gated). (4) **`@arnilo/prism-browser` CDP capabilities** (Tasks 4-5): additive Chrome DevTools Protocol surface riding playwright-core's existing transport — `browser_evaluate` (bounded `Runtime.evaluate`, policy-gated), `browser_observe` (console/network rings, bodies never captured), `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions, and raw `{ css }`/`{ xpath }` targets; capability-gated via `BrowserCdpOptions.mode` with `ERR_PRISM_BROWSER_CDP_UNAVAILABLE`; documented additive deltas vs the 0.1.3 prism-browser baseline (41 added / 0 removed / 18 changed — 15 statement-text artifacts + 3 optional-member/signature-widening, deviation #2), root `@arnilo/prism` zero deltas. Zero new dependencies across the milestone; exit gate green (npm test core 1,425/1,425 + 151 script gates, `sdk:ready`, audit 0, pack dry-run 49/49 twice byte-identical, tree-shake + benchmark evidence in `scripts/phase16-baseline.json`). Store compatibility with 0.1.3: **compatible, no migration** (rollback = restore the 0.1.3 manifests/tag). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.1.4 publish handoff` — signed `v0.1.4` tag + npm OIDC).
+
+## [0.1.3] - 2026-08-10
+
+### Changed
+- **Release 0.1.3 (plan 015)** is the dead-code and deprecation hygiene patch on the frozen 0.1.x line, additive-only vs 0.1.2 (freeze manifest `scripts/phase15-freeze-manifest.json`). (1) **Benchmark-runner consolidation** (Task 1): one parameterized runner `scripts/benchmark.mjs --scenario <name>` replaces the per-version runners; the six live legs moved to `scripts/benchmark-scenarios/` as named scenarios (`phase6-postgres`, `phase7-postgres`, `phase8-loops-hitl`, `phase9-coding`, `phase10-acp`, `phase11-auth`) and the 0.1.0 envelope orchestrator composes them through the runner; **removed files**: `scripts/benchmark-0.0.{8,9,10,11,12,13,14,15,16}.mjs` and `scripts/benchmark-0.0.{9,10,11,12,13,14,15}.test.mjs` (orphaned, unreferenced by `npm test`); all `benchmark-*.json` evidence files kept byte-identical; the CI benchmark-schema leg now runs `scripts/benchmark.test.mjs`. (2) **Review-coverage archive** (Task 2): the 12 `docs/review-coverage-2026-07-*.md` per-phase evidence files moved to `docs/_evidence/` (tarball-excluded via the `files` field; index/migration/performance links updated; archived evidence is not part of the shipped docs surface). (3) **Non-blocking unused-code sweep** (Task 3): `npm run sweep:unused` runs tsc `--noUnusedLocals`/`--noUnusedParameters` over core + every workspace tsconfig plus a zero-dep dead-export scan (`scripts/dead-exports.mjs`), writes the combined report to `scripts/unused-sweep-report.txt`, and always exits 0; CI runs it as a `continue-on-error` step with a retained artifact; 43 internal unused diagnostics (22 test files + 13 source files) removed in-tree, public-but-unused exports are report-only (removal is the 0.1.5 breaking cut). (4) **Opt-in checkpoint persistence** (Task 4): durable runs may set `persistSessionState: true` on the run and resume options — the loaded-skill **name catalog** (≤64 names, ≤256 chars each, validated fail-closed on every save and load) rides the run-state checkpoint and is restored into the resumed session's `LoadedSkillSet`; skill **bodies are never persisted** and re-resolve from the live registry; flag off keeps the checkpoint shape byte-identical to 0.1.2. `@arnilo/prism-coding-agent` adds `createReadPathSetPersistence({ checkpoints, key, ownership })` for the read-before-write path set (≤1024 paths / ≤1024 chars each, CAS read-modify-write, cross-ownership restore fails closed). Store compatibility with 0.1.2: **compatible, no migration**; declaration surface additive-only vs the frozen 0.1.x contract.
+
 ## [0.1.2] - 2026-08-10
 
 ### Changed

package/dist/agent-approval.d.ts

@@ -0,0 +1,49 @@
+import type { StoredAgentRunState } from "./agent-run-state.js";
+import { Agent, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
+import type { AgentIdentity } from "./identity.js";
+/** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
+export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly PendingDecision[] | undefined;
+interface ResolvedRunDecisions {
+    readonly decisionsById: ReadonlyMap<string, RunDecision>;
+    readonly stickyDecisions: readonly StickyDecision[];
+    readonly remaining: readonly PendingDecision[];
+}
+/**
+ * Validate one decision batch against the suspended state. Fail-closed and atomic: any
+ * invalid entry rejects the whole batch before any CAS, leaving state and version untouched.
+ * Unknown and foreign approval ids share one non-enumerating error.
+ */
+export declare function resolveRunDecisions(input: {
+    readonly agent: Agent;
+    readonly state: StoredAgentRunState;
+    readonly decisions: readonly RunDecision[];
+    readonly signal?: AbortSignal;
+}): Promise<ResolvedRunDecisions>;
+/**
+ * Resolve a tool's declared elicitation contract for a gated call. A throwing hook falls back to
+ * plain tool approval: malformed model args then surface as a tool error after approval, never
+ * as a run failure at the gate. Output is bounded before it enters the pending-decision record.
+ */
+export declare class AgentRunSuspended extends Error {
+    readonly state: AgentRunState;
+    readonly interruption: import("./contracts.js").AgentRunInterruption;
+    readonly code = "ERR_PRISM_AGENT_RUN_SUSPENDED";
+    constructor(state: AgentRunState, interruption: import("./contracts.js").AgentRunInterruption);
+}
+/** Root-visible nested approval id: hashed so it stays bounded and non-enumerating at any depth. */
+export declare function nestedApprovalId(runId: string, childApprovalId: string): string;
+export declare function pathsEqual(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean;
+export declare function decisionScopesEqual(a: DecisionScope, b: DecisionScope): boolean;
+export declare function nestedOutcomeToolResult(outcome: Exclude<NestedRunOutcome, {
+    status: "suspended";
+}>, toolCallId: string, name: string): ToolResult;
+export interface ActiveDurableRun {
+    readonly options: AgentRunStateOptions;
+    state?: StoredAgentRunState;
+    version: number;
+    /** Validated decisions driving the pending-call replay on a resumed run. */
+    readonly decisions?: ReadonlyMap<string, RunDecision>;
+}
+/** Compact redacted principal reference used in decision scopes; never a credential. */
+export declare function decisionIdentityRef(identity: AgentIdentity | undefined): string | undefined;
+export {};

package/dist/agent-approval.js

@@ -0,0 +1,178 @@
+// Approval / pending-decision helpers split from agents.ts at 0.1.4 (verbatim move; internal, not public API).
+import { createHash } from "node:crypto";
+import { activeTools, validateElicitationPayload } from "./agent-tool-dispatch.js";
+import { AgentDecisionError, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, } from "./contracts.js";
+import { runGuardrails } from "./guardrails.js";
+import { canonicalToolEffectJson } from "./tool-effects.js";
+/** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
+export function pendingDecisionsOf(state) {
+    if (state.interruption?.pendingDecisions)
+        return state.interruption.pendingDecisions;
+    if (state.pending) {
+        return [
+            {
+                approvalId: state.pending.call.id,
+                kind: "tool_approval",
+                toolCallId: state.pending.call.id,
+                scope: { toolName: state.pending.call.name },
+                reason: state.interruption?.reason ?? "Tool side effect requires approval",
+            },
+        ];
+    }
+    return undefined;
+}
+/**
+ * Validate one decision batch against the suspended state. Fail-closed and atomic: any
+ * invalid entry rejects the whole batch before any CAS, leaving state and version untouched.
+ * Unknown and foreign approval ids share one non-enumerating error.
+ */
+export async function resolveRunDecisions(input) {
+    const { agent, state, decisions } = input;
+    if (decisions.length === 0)
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Decision batch must not be empty");
+    if (decisions.length > HARD_MAX_PENDING_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision batch exceeds ${HARD_MAX_PENDING_DECISIONS} entries`);
+    }
+    const pending = pendingDecisionsOf(state);
+    if (!pending?.length)
+        throw new AgentDecisionError("ERR_PRISM_DECISION_UNKNOWN", "No pending approval decisions for this run");
+    const byId = new Map(pending.map((entry) => [entry.approvalId, entry]));
+    const seen = new Set();
+    const decisionsById = new Map();
+    const stickies = [];
+    const decidedAt = new Date().toISOString();
+    const { registry } = activeTools(agent.config.tools);
+    for (const decision of decisions) {
+        if (seen.has(decision.approvalId)) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_DUPLICATE", "Duplicate approval decision in batch");
+        }
+        seen.add(decision.approvalId);
+        const target = byId.get(decision.approvalId);
+        if (!target)
+            throw new AgentDecisionError("ERR_PRISM_DECISION_UNKNOWN", "Unknown approval decision");
+        if (decision.reason !== undefined && Buffer.byteLength(decision.reason, "utf8") > MAX_DECISION_REASON_BYTES) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision reason exceeds ${MAX_DECISION_REASON_BYTES} bytes`);
+        }
+        if (decision.outcome !== "allow_once" &&
+            decision.outcome !== "allow_for_run" &&
+            decision.outcome !== "reject_once" &&
+            decision.outcome !== "reject_for_run") {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Unknown approval outcome");
+        }
+        if (decision.modifiedArguments !== undefined) {
+            if (target.kind !== "tool_approval" || !target.toolCallId) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_SCOPE", "Modified arguments apply only to tool approvals");
+            }
+            await validateModifiedArguments(agent, registry, state, target, decision.modifiedArguments, input.signal);
+        }
+        if (decision.elicitation !== undefined) {
+            if (target.kind !== "elicitation") {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_SCOPE", "Elicitation payload applies only to elicitation decisions");
+            }
+            await validateElicitationPayload(agent, state, target, decision.elicitation, input.signal);
+        }
+        decisionsById.set(decision.approvalId, decision);
+        if (decision.outcome === "allow_for_run" || decision.outcome === "reject_for_run") {
+            stickies.push({
+                // A decision with modified arguments must not stick to the original arguments hash:
+                // the modification is one-off, so the sticky scope matches by name/effect/identity only.
+                scope: decision.modifiedArguments !== undefined ? { ...target.scope, argumentsHash: undefined } : target.scope,
+                outcome: decision.outcome,
+                ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+                // Root-owned sticky scope includes the delegation path for nested decisions.
+                ...(target.attribution ? { attribution: target.attribution } : {}),
+                decidedAt,
+            });
+        }
+    }
+    const stickyDecisions = [...(state.stickyDecisions ?? []), ...stickies];
+    if (stickyDecisions.length > DEFAULT_MAX_STICKY_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Sticky decisions exceed ${DEFAULT_MAX_STICKY_DECISIONS} per run`);
+    }
+    return {
+        decisionsById,
+        stickyDecisions,
+        remaining: pending.filter((entry) => !seen.has(entry.approvalId)),
+    };
+}
+/** Decision-time revalidation of modified arguments: schema, then input guardrails. Policy and trust re-run at dispatch. */
+async function validateModifiedArguments(agent, registry, state, target, modified, signal) {
+    const invalid = (message, cause) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message, { cause });
+    if (JSON.stringify(modified) === undefined || Buffer.byteLength(JSON.stringify(modified), "utf8") > MAX_ELICITATION_BYTES) {
+        throw invalid("Modified arguments must be a bounded JSON object");
+    }
+    const call = state.pendingCalls?.find((entry) => entry.approvalId === target.approvalId)?.call ??
+        (state.pending && state.pending.call.id === target.toolCallId ? state.pending.call : undefined);
+    const toolName = target.scope.toolName ?? call?.name ?? "";
+    const tool = registry.get(toolName);
+    const context = { sessionId: state.sessionId, runId: state.runId, toolCallId: target.toolCallId ?? "", signal };
+    if (agent.config.validator && tool) {
+        const validation = await agent.config.validator(tool, modified, context);
+        if (validation)
+            throw invalid("Modified arguments failed schema validation");
+    }
+    const value = call
+        ? { ...call, arguments: modified }
+        : { type: "tool_call", id: target.toolCallId ?? "", name: toolName, arguments: modified };
+    const guarded = await runGuardrails({
+        stage: "tool_input",
+        guardrails: agent.config.guardrails,
+        value,
+        context: {
+            sessionId: state.sessionId,
+            runId: state.runId,
+            toolCallId: target.toolCallId,
+            toolName,
+            metadata: {},
+            signal,
+        },
+        redactor: agent.config.redactor,
+    });
+    if (guarded.terminal)
+        throw invalid("Modified arguments blocked by guardrail");
+}
+/**
+ * Resolve a tool's declared elicitation contract for a gated call. A throwing hook falls back to
+ * plain tool approval: malformed model args then surface as a tool error after approval, never
+ * as a run failure at the gate. Output is bounded before it enters the pending-decision record.
+ */
+export class AgentRunSuspended extends Error {
+    state;
+    interruption;
+    code = "ERR_PRISM_AGENT_RUN_SUSPENDED";
+    constructor(state, interruption) {
+        super("Agent run suspended");
+        this.state = state;
+        this.interruption = interruption;
+        this.name = "AgentRunSuspended";
+    }
+}
+/** Root-visible nested approval id: hashed so it stays bounded and non-enumerating at any depth. */
+export function nestedApprovalId(runId, childApprovalId) {
+    return `sub_${createHash("sha256").update(`${runId}:${childApprovalId}`).digest("hex")}`;
+}
+export function pathsEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+export function decisionScopesEqual(a, b) {
+    if (a.toolName !== b.toolName || a.argumentsHash !== b.argumentsHash || a.effectKind !== b.effectKind || a.identity !== b.identity)
+        return false;
+    if (a.actionConstraints === undefined || b.actionConstraints === undefined)
+        return a.actionConstraints === b.actionConstraints;
+    const keys = Object.keys(a.actionConstraints);
+    return (keys.length === Object.keys(b.actionConstraints).length &&
+        keys.every((key) => key in b.actionConstraints &&
+            canonicalToolEffectJson(a.actionConstraints[key]) === canonicalToolEffectJson(b.actionConstraints[key])));
+}
+export function nestedOutcomeToolResult(outcome, toolCallId, name) {
+    return outcome.status === "completed"
+        ? { toolCallId, name, ...(outcome.value !== undefined ? { value: outcome.value } : {}) }
+        : { toolCallId, name, error: { code: outcome.code, message: outcome.message } };
+}
+/** Compact redacted principal reference used in decision scopes; never a credential. */
+export function decisionIdentityRef(identity) {
+    return identity ? `${identity.tenantId}:${identity.principal.kind}:${identity.principal.id}` : undefined;
+}
+//# sourceMappingURL=agent-approval.js.map

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

@@ -1,4 +1,4 @@
-import type { Agent, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
+import type { Agent, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
 export interface AgentRunLifecycleAgent {
     readonly agent: Agent;
     /** Current host-authored revision; it must match the stored revision. */
@@ -18,6 +18,8 @@ export interface AgentRunLifecycleRequest {
     readonly signal?: AbortSignal;
     /** Adapter-selected capability; stored runs for another agent are non-enumerable. */
     readonly agentId?: string;
+    /** Opt-in (plan 015 Task 4): restore persisted loaded-skill names on resume. */
+    readonly persistSessionState?: boolean;
 }
 /** Bounded live-event options for a durable lifecycle resume. */
 export interface AgentRunLifecycleStreamRequest extends AgentRunLifecycleRequest, SubscribeOptions {
@@ -29,3 +31,7 @@ export interface AgentRunLifecycle {
 }
 /** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
 export declare function createAgentRunLifecycle(options: AgentRunLifecycleOptions): AgentRunLifecycle;
+/** 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>;

package/dist/agent-run-lifecycle.js

@@ -1,6 +1,7 @@
-import { loadAgentRunState, publicState } from "./agent-run-state.js";
-import { resumeAgentRun, resumeAgentRunStream } from "./agents.js";
-import { AgentRunStateError } from "./contracts.js";
+import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
+import { AgentDecisionError, AgentRunStateError } from "./contracts.js";
+import { pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
+import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
         throw new AgentRunStateError("Agent run capability mismatch");
@@ -26,6 +27,7 @@ export function createAgentRunLifecycle(options) {
                 ownership: request.ownership,
                 fencingToken: options.fencingToken,
                 definitionRevision: resolved.definitionRevision,
+                persistSessionState: request.persistSessionState,
             });
         },
         async *resumeStream(ref, resume, request = {}) {
@@ -42,8 +44,216 @@ export function createAgentRunLifecycle(options) {
                 signal: request.signal,
                 maxQueuedEvents: request.maxQueuedEvents,
                 overflow: request.overflow,
+                persistSessionState: request.persistSessionState,
             });
         },
     };
 }
+// Resume free functions moved from agents.ts at 0.1.4 (verbatim; the barrel re-exports the two public ones).
+/** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
+export async function resumeAgentRun(agent, ref, resume, options) {
+    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options));
+}
+/** Subscribe before resuming one durable run. Early consumer return aborts that resumed execution. */
+export async function* resumeAgentRunStream(agent, ref, resume, options) {
+    throwIfAbortedSignal(options.signal);
+    const prepared = await prepareAgentRunResume(agent, ref, resume, options, options.signal);
+    const subscription = prepared.session.subscribe(options);
+    let settled = false;
+    const runPromise = executePreparedAgentRunResume(prepared, options.signal).finally(() => {
+        settled = true;
+    });
+    try {
+        for await (const event of subscription) {
+            if ("runId" in event && event.runId !== ref.runId)
+                continue;
+            yield event;
+        }
+        await runPromise;
+    }
+    finally {
+        if (!settled) {
+            prepared.session.abort(new Error("resume stream consumer closed"));
+            await runPromise.catch(() => undefined);
+        }
+    }
+}
+async function prepareAgentRunResume(agent, ref, resume, options, signal) {
+    throwIfAbortedSignal(signal);
+    const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    if (state.definitionRevision !== options.definitionRevision ||
+        state.agentId !== (agent.config.id ?? agent.config.name) ||
+        state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
+        throw new AgentRunStateError("Agent definition revision or fingerprint mismatch on resume");
+    }
+    if (record.version !== resume.expectedVersion || state.status !== "suspended") {
+        throw new AgentRunStateError("Stale or non-suspended agent run resume");
+    }
+    const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
+    // Opt-in session-state restore (plan 015 Task 4): names only; bodies re-resolve from
+    // the live registry the next time the model (re)loads them via load_skill.
+    if (options.persistSessionState && state.sessionState?.loadedSkillNames) {
+        session.restoreLoadedSkills(state.sessionState.loadedSkillNames);
+    }
+    if (resume.decision !== undefined && resume.decisions !== undefined) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume accepts exactly one of decision or decisions");
+    }
+    const pendingDecisions = pendingDecisionsOf(state);
+    // Legacy approve maps to allow-once on every pending decision; legacy deny keeps its
+    // terminal-denied behavior. Batch decisions are validated and applied atomically below.
+    const resolved = resume.decisions !== undefined
+        ? await resolveRunDecisions({ agent, state, decisions: resume.decisions, signal })
+        : resume.decision === "approve" && pendingDecisions
+            ? await resolveRunDecisions({
+                agent,
+                state,
+                decisions: pendingDecisions.map((pending) => ({ approvalId: pending.approvalId, outcome: "allow_once" })),
+                signal,
+            })
+            : undefined;
+    if (resume.decision === undefined && resume.decisions === undefined) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume requires a decision or decisions");
+    }
+    if (resolved && resolved.remaining.length > 0) {
+        throwIfAbortedSignal(signal);
+        const single = resolved.remaining.length === 1 ? resolved.remaining[0] : undefined;
+        const interruption = {
+            kind: state.interruption?.kind ?? "tool_approval",
+            reason: `${resolved.remaining.length} approval request(s) remain`,
+            ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
+            ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+            pendingDecisions: resolved.remaining,
+        };
+        const resuspended = await saveAgentRunState({
+            checkpoints: options.checkpoints,
+            state: {
+                ...state,
+                status: "suspended",
+                interruption,
+                pending: undefined,
+                // Decided approvals persist on their entries so a partial batch never loses them;
+                // they dispatch (or synthesize their result) when the run finally resumes.
+                pendingCalls: state.pendingCalls?.map((entry) => {
+                    const decision = resolved.decisionsById.get(entry.approvalId);
+                    return decision ? { ...entry, decision } : entry;
+                }),
+                // Decided nested approvals persist on their nested-run entries, keyed by
+                // root-visible approval id, so a partial batch never loses them either.
+                nestedRuns: state.nestedRuns?.map((entry) => {
+                    const decided = entry.approvals.filter((approval) => resolved.decisionsById.has(approval.id));
+                    if (decided.length === 0)
+                        return entry;
+                    return {
+                        ...entry,
+                        decisions: {
+                            ...entry.decisions,
+                            ...Object.fromEntries(decided.map((approval) => [approval.id, resolved.decisionsById.get(approval.id)])),
+                        },
+                    };
+                }),
+                stickyDecisions: resolved.stickyDecisions,
+            },
+            expectedVersion: record.version,
+            ownership: options.ownership,
+            fencingToken: options.fencingToken,
+        });
+        return {
+            kind: "resuspend",
+            session,
+            interruption,
+            version: resuspended.record.version,
+            ownership: options.ownership,
+            result: {
+                sessionId: state.sessionId,
+                runId: state.runId,
+                status: "suspended",
+                leafId: state.leafId,
+                text: "",
+                content: [],
+                runState: publicState(resuspended.state),
+                interruption,
+            },
+        };
+    }
+    if (resume.decision === "deny") {
+        throwIfAbortedSignal(signal);
+        const denied = await saveAgentRunState({
+            checkpoints: options.checkpoints,
+            state: {
+                ...state,
+                status: "denied",
+                loopState: undefined,
+                pendingCalls: undefined,
+                nestedRuns: undefined,
+                stickyDecisions: undefined,
+            },
+            expectedVersion: record.version,
+            ownership: options.ownership,
+            fencingToken: options.fencingToken,
+        });
+        return {
+            kind: "deny",
+            session,
+            interruption: state.interruption,
+            version: denied.record.version,
+            ownership: options.ownership,
+            result: {
+                sessionId: state.sessionId,
+                runId: state.runId,
+                status: "denied",
+                leafId: state.leafId,
+                text: "",
+                content: [],
+                runState: publicState(denied.state),
+                interruption: state.interruption,
+            },
+        };
+    }
+    if (state.pending?.status === "dispatched" || state.pendingCalls?.some((entry) => entry.status === "dispatched")) {
+        throw new AgentRunStateError("Ambiguous dispatched tool requires operator resolution");
+    }
+    const configured = agent.config.runState;
+    if (configured && (configured.checkpoints !== options.checkpoints || configured.definitionRevision !== options.definitionRevision)) {
+        throw new AgentRunStateError("Agent durable run-state configuration mismatch on resume");
+    }
+    throwIfAbortedSignal(signal);
+    const claimed = await saveAgentRunState({
+        checkpoints: options.checkpoints,
+        state: {
+            ...state,
+            status: "running",
+            interruption: undefined,
+            stickyDecisions: resolved?.stickyDecisions ?? state.stickyDecisions,
+        },
+        expectedVersion: record.version,
+        ownership: options.ownership,
+        fencingToken: options.fencingToken,
+    });
+    return {
+        kind: "approve",
+        session,
+        state: claimed.state,
+        decisions: resolved?.decisionsById,
+        ownership: options.ownership,
+        runState: configured ?? {
+            checkpoints: options.checkpoints,
+            definitionRevision: options.definitionRevision,
+            interruptBeforeTool: state.interruptBeforeTool,
+            fencingToken: options.fencingToken,
+            resumeNestedRun: options.resumeNestedRun,
+        },
+    };
+}
+/** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
+async function executePreparedAgentRunResume(prepared, signal) {
+    if (prepared.kind === "deny") {
+        await prepared.session.recordDurableDenial(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
+        return prepared.result;
+    }
+    if (prepared.kind === "resuspend") {
+        await prepared.session.recordDurableResumption(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
+        return prepared.result;
+    }
+    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions);
+}
 //# sourceMappingURL=agent-run-lifecycle.js.map

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

@@ -34,7 +34,18 @@ export interface StoredAgentRunState extends AgentRunState {
         readonly revision: string;
         readonly snapshot: JsonValue;
     };
+    /**
+     * Opt-in session-level state (plan 015 Task 4): loaded-skill names only; bodies are
+     * never persisted and reload on demand from the live registry via `load_skill`.
+     * Absent by default (0.1.x checkpoints parse unchanged).
+     */
+    readonly sessionState?: {
+        readonly loadedSkillNames?: readonly string[];
+    };
 }
+/** 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;
 /** 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. */

package/dist/agent-run-state.js

@@ -6,6 +6,9 @@ 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;
+/** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
+export const MAX_PERSISTED_SKILL_NAMES = 64;
+export const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export const BUILT_IN_LOOP_REVISIONS = {
     "single-shot": "1",
@@ -207,6 +210,7 @@ export function parseAgentRunState(value, version) {
     return boundState({ ...state, version }, HARD_MAX_AGENT_RUN_STATE_BYTES);
 }
 function boundState(state, maxBytes) {
+    validateSessionState(state.sessionState);
     checkShape(state, 0);
     let text;
     try {
@@ -230,4 +234,23 @@ function checkShape(value, depth) {
     for (const item of entries)
         checkShape(item, depth + 1);
 }
+/** Fail-closed validation of the opt-in session-state block (load and save sides). */
+function validateSessionState(sessionState) {
+    if (sessionState === undefined)
+        return;
+    if (!sessionState || typeof sessionState !== "object") {
+        throw new AgentRunStateError("Malformed agent run session state");
+    }
+    const names = sessionState.loadedSkillNames;
+    if (names === undefined)
+        return;
+    if (!Array.isArray(names) || names.length > MAX_PERSISTED_SKILL_NAMES) {
+        throw new AgentRunStateError(`Loaded-skill names exceed ${MAX_PERSISTED_SKILL_NAMES} entries`);
+    }
+    for (const name of names) {
+        if (typeof name !== "string" || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
+            throw new AgentRunStateError(`Loaded-skill name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
+        }
+    }
+}
 //# sourceMappingURL=agent-run-state.js.map