@arnilo/prism 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.1.5] - 2026-08-11
+
+### Changed
+- **Release 0.1.5 (plan 017)** is the **documented breaking cut** on the frozen 0.1.x line — deprecated-option removal with the full removed-symbols list, replacements, before/after examples, dynamic-config refusal behavior, store compatibility, and rollback in the top `docs/migration.md` `0.1.4 → 0.1.5` section (three stale roadmap labels corrected there: `RunOptions.maxToolRounds` not `AgentConfig.maxToolRounds`, `autoResizeImages` removed with `transformImage` retained, `INIT_PROVIDERS` removed with `listInitProviders()` retained). (1) **Provider run-option aliases** (Task 1): `ProviderRequestOptions.timeoutMs`/`maxRetries`/`maxRetryDelayMs` (inert in first-party providers; host-side abort/retry is the replacement — `RunOptions.signal`, `AgentConfig.retry`/`RunOptions.retry`) and `RunOptions.maxToolRounds` (→ `limits.maxToolRounds`, defaults/caps unchanged) removed; untyped legacy run input is refused at the `runInternal` choke point before the agent starts; CLI `--max-tool-rounds` maps to the nested limit. (2) **Observational-memory compatibility surface** (Task 2): the 10 pre-0.0.19 flat settings keys and top-level `workerProvider`/`workerModel` aliases removed — settings resolution is nested-only with `assertNoRemovedFlatKeys` failing closed (settings-provider JSON or untyped overrides throw naming the key + nested replacement before any worker/provider call, compaction, or session append); `fallbackWorker`/`assertWorkerModelCompatibility`/`conflict()` deleted; workers resolve only from `observation`/`reflection`/`dropper` configs plus `sessionModel` fallback. (3) **Read alias + CLI constant** (Task 3): `ReadToolOptions.autoResizeImages` removed (`transformImage` is the only resize path; untyped callers fail closed at `createReadTool` before filesystem access) and `INIT_PROVIDERS` removed (`listInitProviders()` is the single provider-list API). Compat baselines regenerated after the reviewed `--allow-break` break report (root `arnilo__prism.txt` drops the `INIT_PROVIDERS` line; interface-member removals are verified by the phase-17 direct declaration scanner, not baseline text). Exit gate green (core tests + script gates incl. phase17-freeze 20/20, `sdk:ready`, audit 0, pack dry-run 49/49 twice byte-identical, evidence in `scripts/phase17-baseline.json`). Store compatibility with 0.1.4: **compatible, no migration** (removed options were inert aliases; rollback = restore the 0.1.4 manifests/tag). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.1.5 publish handoff` — signed `v0.1.5` tag + npm OIDC).
+
+## [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

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. */
@@ -31,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");
@@ -48,4 +49,211 @@ export function createAgentRunLifecycle(options) {
         },
     };
 }
+// 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-session.d.ts

@@ -0,0 +1,98 @@
+import { type StoredAgentRunState } from "./agent-run-state.js";
+import type { Agent, AgentConfig, AgentEvent, AgentRunResult, AgentRunStateOptions, AgentSession, AgentSessionConfig, CompactionOptions, CompactionResult, OwnershipScope, RunDecision, RunOptions, SessionEntry, SteerOptions, SubscribeOptions } from "./contracts.js";
+import { type AgentInput } from "./input.js";
+export declare function createAgent(config: AgentConfig): Agent;
+export declare function createAgentSession(config: AgentSessionConfig & {
+    readonly agent: Agent;
+}): AgentSession;
+export declare class RuntimeAgentSession implements AgentSession {
+    readonly id: string;
+    private readonly agent;
+    private readonly metadata?;
+    private readonly store;
+    private readonly subscribers;
+    private currentLeafId?;
+    private history;
+    private activeRun?;
+    private activeRunId?;
+    private activeProviderTurnAbort?;
+    private pendingSoftInterrupt;
+    private pendingSteers;
+    private pendingSteerBytes;
+    private activeRedactor?;
+    private activeProvider?;
+    private activeLedger?;
+    private activeEffectStore?;
+    private activeOwnership?;
+    private activeIdentity?;
+    private activeIdempotencyKey?;
+    private activeGuardrails?;
+    private activeMetadata?;
+    private activeLimits?;
+    private activeLimitOutputBuffer;
+    private activeDurable?;
+    private activeLoop?;
+    /** Gated calls of the current tool round awaiting one collected suspension. */
+    private activeGatedRound?;
+    private activeLoopTurn;
+    private readonly loadedSkills;
+    /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
+    restoreLoadedSkills(names: readonly string[]): void;
+    private ledgerChain;
+    private ledgerFailure;
+    private snapshotGeneration;
+    private snapshotCache?;
+    constructor(config: AgentSessionConfig & {
+        readonly agent: Agent;
+    });
+    get leafId(): string | undefined;
+    subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    run(input: AgentInput, options?: RunOptions): Promise<AgentRunResult>;
+    steer(input: AgentInput, options?: SteerOptions): void;
+    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>): Promise<AgentRunResult>;
+    recordDurableResumption(runId: string, interruption: import("./contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
+    recordDurableDenial(runId: string, interruption: import("./contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
+    private runInternal;
+    prompt(input: string, options?: RunOptions): Promise<AgentRunResult>;
+    stream(input: AgentInput, options?: RunOptions & SubscribeOptions): AsyncGenerator<AgentEvent>;
+    private buildRunResult;
+    private suspendDurable;
+    /** First attributed sticky whose scope and delegation path exactly match a nested decision. */
+    private matchNestedSticky;
+    /** First sticky decision whose scope exactly matches this call, if any. */
+    private matchStickyDecision;
+    /** Redacted pending-decision descriptor for one gated call; never carries raw arguments. */
+    private buildPendingDecision;
+    private persistDurable;
+    compact(options?: CompactionOptions): Promise<CompactionResult>;
+    abort(reason?: unknown): void;
+    entries(): Promise<readonly SessionEntry[]>;
+    checkout(leafId?: string): Promise<void>;
+    fork(options?: {
+        readonly leafId?: string;
+    }): AgentSession;
+    clone(options?: {
+        readonly id?: string;
+        readonly leafId?: string;
+    }): Promise<AgentSession>;
+    private branchReader;
+    private resolveRunProvider;
+    private resolveRunSkills;
+    private emit;
+    private closeSubscribers;
+    private drainLedger;
+    private generateWithRetry;
+    private generateProviderTurn;
+    private applyPendingSteers;
+    private applyProviderRequestPolicies;
+    private appendMessage;
+    private autoCompact;
+    private compactBranch;
+    private appendEntry;
+    private invalidateSnapshot;
+    private redact;
+    private redactProviderRequest;
+    private rebuildHistory;
+    private snapshot;
+}
+export declare function throwIfAbortedSignal(signal: AbortSignal | undefined): void;