@arnilo/prism 0.0.23 → 0.0.25

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.0.25] - 2026-08-06
+
+### Added
+- Durable custom `AgentLoopStrategy` hooks: optional `revision` / `snapshot` / `restore`; `AgentLoopStateError` fail-closed codes; fingerprint includes loop `{name,revision}`.
+- Shared pending-decision model: parallel approvals, batch CAS `decisions`, sticky allow/reject for run, modified arguments, elicitation; nested supervisor attribution.
+- Protocol mappings: AG-UI/ACP/server batch resume, MCP elicitation helpers, coding `ask_user_decision` elicitation hook.
+- Opt-in A2UI painting middleware + standard AG-UI projectors (`messages`/`state`/`activity`).
+- Network-free Phase 8 conformance + `benchmark-0.0.25.json` evidence; examples `durable-loops-and-approvals.ts`, `ag-ui-a2ui.ts`.
+
+### Changed
+- Publishable graph remains **47** manifests at **0.0.25**.
+- Fingerprint loop entry shape `string` → `{name,revision}` (0.0.24 persisted durable runs fail closed on resume).
+
+### Breaking (minor, pre-1.0)
+- Custom loops on durable runs need snapshot/restore hooks or `ERR_PRISM_LOOP_NOT_DURABLE`.
+- Resume prefers `decisions: RunDecision[]`; legacy binary `decision` remains but is exclusive with the batch path.
+- ACP permission offers four outcomes; `reject_once` is blocked-continue (cancelled stays terminal deny).
+
+See [docs/migration.md](docs/migration.md) for the 0.0.24 → 0.0.25 guide.
+
+## [0.0.24] - 2026-08-04
+
+### Added
+- Durable `AgentEventSource` with append/page/subscribe/resume and PostgreSQL LISTEN/NOTIFY wakeups (schema v6 streams + v7 retention index).
+- Recoverable `ToolEffectStore` claim/CAS lifecycle; enterprise PostgreSQL `toolEffects`; coding/browser/work/MCP/supervisor effect classification.
+- AG-UI 0.0.57 full input/event/interrupt compatibility plus MCP Apps and remote A2A adapters.
+- Protected Phase 7 process conformance and `benchmark-0.0.24.json` evidence.
+- Example `examples/distributed-events-and-tool-effects.ts`; docs `docs/tool-effects.md`.
+
+### Changed
+- Work mutations require core-derived idempotency keys; ambiguous outcomes stay `unknown` (not exactly-once).
+- Publishable graph remains **47** manifests at **0.0.24**.
+
+### Breaking (minor, pre-1.0)
+- Hosts using approved work mutations must supply `effectStore` / core `idempotencyKey` (model keys ignored).
+- Durable event reconnect uses `AgentEventSource` cursors / `Last-Event-ID`; sticky sessions are optional only.
+
+See [docs/migration.md](docs/migration.md) for the 0.0.23 → 0.0.24 guide.
+
 ## [0.0.23] - 2026-08-03
 
 ### Added
@@ -17,7 +56,6 @@
 
 See [docs/migration.md](docs/migration.md) for the 0.0.22 → 0.0.23 guide.
 
-
 ## [0.0.22] - 2026-07-31
 
 ### Added
@@ -45,7 +83,6 @@ See [docs/migration.md](docs/migration.md) for the full 0.0.21 → 0.0.22 notes.
 
 See [docs/migration.md](docs/migration.md) for the full 0.0.20 → 0.0.21 notes.
 
-
 ## [0.0.20] - 2026-07-31
 
 ### Added
@@ -169,7 +206,6 @@ All notable changes to this project will be documented in this file.
 - Versioned all 35 first-party manifests and exact internal ranges to `0.0.12`; `@arnilo/prism-all` includes AG-UI while `@arnilo/prism-code` and `@arnilo/prism-sdk` remain free of UI protocol dependencies.
 - Added network-free interoperability/compaction evidence: `scripts/benchmark-0.0.12.mjs`.
 
-
 ## [0.0.11] - 2026-07-22
 
 ### Added

package/dist/agent-event-source.d.ts

@@ -0,0 +1,11 @@
+import type { AgentEventSource, AgentEventSourceOptions } from "./contracts.js";
+export type AgentEventSourceErrorCode = "ERR_PRISM_AGENT_EVENT_SOURCE_INPUT" | "ERR_PRISM_AGENT_EVENT_SOURCE_CURSOR" | "ERR_PRISM_AGENT_EVENT_SOURCE_RETENTION" | "ERR_PRISM_AGENT_EVENT_SOURCE_OVERFLOW" | "ERR_PRISM_AGENT_EVENT_SOURCE_CLOSED";
+export declare class AgentEventSourceError extends Error {
+    readonly code: AgentEventSourceErrorCode;
+    constructor(code: AgentEventSourceErrorCode, message: string);
+}
+/**
+ * In-process, non-production reference implementation. It has no cross-process
+ * wakeup or persistence; use a database-backed source for distributed delivery.
+ */
+export declare function createMemoryAgentEventSource(options?: AgentEventSourceOptions): AgentEventSource;

package/dist/agent-event-source.js

@@ -0,0 +1,512 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+export class AgentEventSourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AgentEventSourceError";
+    }
+}
+const DEFAULT_MAX_EVENT_BYTES = 64 * 1024;
+const HARD_MAX_EVENT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_PAGE_SIZE = 100;
+const HARD_MAX_PAGE_SIZE = 500;
+const DEFAULT_MAX_CURSOR_BYTES = 4 * 1024;
+const HARD_MAX_CURSOR_BYTES = 16 * 1024;
+const DEFAULT_MAX_QUEUED_EVENTS = 128;
+const HARD_MAX_QUEUED_EVENTS = 4096;
+const DEFAULT_MAX_SUBSCRIBERS = 256;
+const HARD_MAX_SUBSCRIBERS = 4096;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const HARD_POLL_INTERVAL_MS = 30_000;
+const DEFAULT_RECONNECT_INITIAL_MS = 100;
+const HARD_RECONNECT_INITIAL_MS = 5000;
+const DEFAULT_RECONNECT_MAX_MS = 5000;
+const HARD_RECONNECT_MAX_MS = 30_000;
+const DEFAULT_MAX_RETAINED_EVENTS_PER_RUN = 10_000;
+const HARD_MAX_RETAINED_EVENTS_PER_RUN = 100_000;
+const DEFAULT_MAX_RETENTION_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const HARD_MAX_RETENTION_AGE_MS = 365 * 24 * 60 * 60 * 1000;
+const DEFAULT_CLEANUP_BATCH = 100;
+const HARD_CLEANUP_BATCH = 500;
+/**
+ * In-process, non-production reference implementation. It has no cross-process
+ * wakeup or persistence; use a database-backed source for distributed delivery.
+ */
+export function createMemoryAgentEventSource(options = {}) {
+    const limits = resolveOptions(options);
+    const streams = new Map();
+    const byId = new Map();
+    const subscribers = new Set();
+    const secret = randomBytes(32);
+    let closed = false;
+    const source = {
+        async append(input) {
+            assertOpen();
+            const record = normalizeRecord(input, limits.maxEventBytes);
+            const existing = byId.get(record.id);
+            if (existing) {
+                if (sameRecord(existing, record))
+                    return clone(existing);
+                throw inputError();
+            }
+            const stream = getStream(record, true);
+            const sequence = record.sequence ?? stream.nextSequence;
+            if (!Number.isSafeInteger(sequence) || sequence < 1 || sequence !== stream.nextSequence)
+                throw inputError();
+            const stored = { ...record, sequence };
+            assertCursorFits(stored);
+            stream.records.set(stored.sequence, stored);
+            stream.nextSequence += 1;
+            byId.set(stored.id, stored);
+            while (stream.records.size > limits.maxRetainedEventsPerRun)
+                drop(stream, stream.records.values().next().value);
+            for (const subscriber of subscribers)
+                subscriber.notify();
+            return clone(stored);
+        },
+        async page(input) {
+            assertOpen();
+            throwIfAborted(input.signal);
+            const read = normalizeRead(input, limits.maxPageSize);
+            const stream = getStream({ ...read.ownership, sessionId: read.sessionId, runId: read.runId }, false);
+            const records = orderedRecords(stream);
+            const after = read.after === undefined ? undefined : decodeCursor(read.after, read, stream, records);
+            const start = after === undefined ? 0 : positionAfter(records, after, stream);
+            const selected = records.slice(start, start + read.limit);
+            const hasMore = start + selected.length < records.length;
+            return {
+                items: selected.map((record) => ({ record: clone(record), cursor: encodeCursor(record) })),
+                ...(hasMore && selected.length > 0 ? { nextCursor: encodeCursor(selected.at(-1)) } : {}),
+                terminal: !hasMore && terminalAt(records, after),
+            };
+        },
+        subscribe(input) {
+            return handoffAgentEvents((after) => source.page({ ...input, ...(after === undefined ? {} : { after }) }), () => createWake(input.signal), input.after, limits.maxRetainedEventsPerRun);
+        },
+        async cleanup(input) {
+            assertOpen();
+            throwIfAborted(input.signal);
+            const ownership = normalizeOwnership(input.ownership);
+            const before = parseTimestamp(input.before, "input");
+            const limit = bounded(input.limit, DEFAULT_CLEANUP_BATCH, HARD_CLEANUP_BATCH, "cleanup limit");
+            const matches = [];
+            for (const stream of streams.values()) {
+                if (!sameOwnership(ownership, stream.ownership))
+                    continue;
+                for (const record of stream.records.values()) {
+                    if (Date.parse(record.timestamp) < before)
+                        matches.push({ stream, record });
+                }
+            }
+            matches.sort((a, b) => a.record.timestamp.localeCompare(b.record.timestamp) ||
+                a.record.sequence - b.record.sequence ||
+                a.record.id.localeCompare(b.record.id));
+            for (const { stream, record } of matches.slice(0, limit))
+                drop(stream, record);
+            return { deleted: Math.min(matches.length, limit) };
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            for (const subscriber of subscribers)
+                subscriber.fail(closedError());
+            subscribers.clear();
+        },
+    };
+    return source;
+    function getStream(input, create) {
+        const ownership = normalizeOwnership(input);
+        const sessionId = requiredText(input.sessionId);
+        const runId = requiredText(input.runId);
+        const key = streamKey(ownership, sessionId, runId);
+        let stream = streams.get(key);
+        if (!stream && create) {
+            stream = { ownership, sessionId, runId, records: new Map(), nextSequence: 1 };
+            streams.set(key, stream);
+        }
+        return stream;
+    }
+    function encodeCursor(record) {
+        const payload = {
+            v: 1,
+            tenantId: record.tenantId,
+            ...(record.accountId === undefined ? {} : { accountId: record.accountId }),
+            ...(record.userId === undefined ? {} : { userId: record.userId }),
+            sessionId: record.sessionId,
+            runId: record.runId,
+            sequence: record.sequence,
+            id: record.id,
+        };
+        const body = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+        const signature = createHmac("sha256", secret).update(body).digest("base64url");
+        const encoded = `${body}.${signature}`;
+        if (Buffer.byteLength(encoded, "utf8") > limits.maxCursorBytes)
+            throw inputError();
+        return encoded;
+    }
+    function decodeCursor(encoded, input, stream, records) {
+        if (typeof encoded !== "string" || encoded.length === 0 || Buffer.byteLength(encoded, "utf8") > limits.maxCursorBytes) {
+            throw cursorError();
+        }
+        const [body, signature, extra] = encoded.split(".");
+        if (!body || !signature || extra !== undefined)
+            throw cursorError();
+        const expected = createHmac("sha256", secret).update(body).digest();
+        let actual;
+        try {
+            actual = Buffer.from(signature, "base64url");
+        }
+        catch {
+            throw cursorError();
+        }
+        if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+            throw cursorError();
+        let value;
+        try {
+            value = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+        }
+        catch {
+            throw cursorError();
+        }
+        if (!validCursor(value))
+            throw cursorError();
+        const cursor = value;
+        if (!sameOwnership(input.ownership, cursor) || cursor.sessionId !== input.sessionId || cursor.runId !== input.runId) {
+            throw cursorError();
+        }
+        if (!stream || positionOf(records, cursor) < 0)
+            throw retentionError();
+        return cursor;
+    }
+    function assertCursorFits(record) {
+        void encodeCursor(record);
+    }
+    function createWake(signal) {
+        throwIfAborted(signal);
+        if (subscribers.size >= limits.maxSubscribers)
+            throw overflowError();
+        const subscription = new WakeSubscription(limits.maxQueuedEvents, signal, () => subscribers.delete(subscription));
+        subscribers.add(subscription);
+        return subscription;
+    }
+    function drop(stream, record) {
+        if (stream.records.get(record.sequence) === record)
+            stream.records.delete(record.sequence);
+        if (byId.get(record.id) === record)
+            byId.delete(record.id);
+    }
+    function assertOpen() {
+        if (closed)
+            throw closedError();
+    }
+}
+/** Shared replay/live loop. Its live iterator is started before every page, closing the query-to-wait race. */
+function handoffAgentEvents(page, createWake, initialAfter, maxSeen) {
+    return {
+        [Symbol.asyncIterator]() {
+            const wake = createWake();
+            const iterator = run(wake);
+            return {
+                next: () => iterator.next(),
+                async return() {
+                    await wake.return?.();
+                    return (await iterator.return?.(undefined)) ?? { value: undefined, done: true };
+                },
+                async throw(error) {
+                    await wake.return?.();
+                    if (iterator.throw)
+                        return iterator.throw(error);
+                    throw error;
+                },
+            };
+        },
+    };
+    async function* run(wake) {
+        const seen = new Set();
+        let after = initialAfter;
+        let waiting = nextWake(wake); // Register live delivery before replaying durable rows.
+        try {
+            while (true) {
+                const replay = await page(after);
+                for (const item of replay.items) {
+                    after = item.cursor;
+                    if (seen.has(item.record.id))
+                        continue;
+                    seen.add(item.record.id);
+                    if (seen.size > maxSeen)
+                        seen.delete(seen.values().next().value);
+                    yield item;
+                }
+                if (replay.terminal)
+                    return;
+                const next = await waiting;
+                if (next.done)
+                    return;
+                waiting = nextWake(wake);
+            }
+        }
+        finally {
+            await wake.return?.();
+        }
+    }
+}
+function nextWake(wake) {
+    const next = wake.next();
+    // A slow subscriber can overflow while replay items are yielded. Keep the
+    // rejection observed until the generator reaches its next wait.
+    void next.catch(() => undefined);
+    return next;
+}
+class WakeSubscription {
+    maxQueuedEvents;
+    onFinish;
+    queued = 0;
+    waiting;
+    failure;
+    done = false;
+    abort;
+    constructor(maxQueuedEvents, signal, onFinish) {
+        this.maxQueuedEvents = maxQueuedEvents;
+        this.onFinish = onFinish;
+        this.abort = () => this.fail(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+        if (signal?.aborted)
+            this.abort();
+        else
+            signal?.addEventListener("abort", this.abort, { once: true });
+    }
+    notify() {
+        if (this.done)
+            return;
+        if (this.waiting) {
+            const { resolve } = this.waiting;
+            this.waiting = undefined;
+            resolve({ value: undefined, done: false });
+            return;
+        }
+        if (this.queued >= this.maxQueuedEvents) {
+            this.fail(overflowError());
+            return;
+        }
+        this.queued += 1;
+    }
+    fail(error) {
+        if (this.done)
+            return;
+        this.failure = error;
+        this.finish();
+    }
+    async next() {
+        if (this.failure !== undefined)
+            throw this.failure;
+        if (this.done)
+            return { value: undefined, done: true };
+        if (this.queued > 0) {
+            this.queued -= 1;
+            return { value: undefined, done: false };
+        }
+        return new Promise((resolve, reject) => {
+            this.waiting = { resolve, reject };
+        });
+    }
+    async return() {
+        this.finish();
+        return { value: undefined, done: true };
+    }
+    finish() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.onFinish();
+        const waiting = this.waiting;
+        this.waiting = undefined;
+        if (this.failure !== undefined)
+            waiting?.reject(this.failure);
+        else
+            waiting?.resolve({ value: undefined, done: true });
+    }
+}
+function resolveOptions(options) {
+    const resolved = {
+        maxEventBytes: bounded(options.maxEventBytes, DEFAULT_MAX_EVENT_BYTES, HARD_MAX_EVENT_BYTES, "maxEventBytes"),
+        maxPageSize: bounded(options.maxPageSize, DEFAULT_MAX_PAGE_SIZE, HARD_MAX_PAGE_SIZE, "maxPageSize"),
+        maxCursorBytes: bounded(options.maxCursorBytes, DEFAULT_MAX_CURSOR_BYTES, HARD_MAX_CURSOR_BYTES, "maxCursorBytes"),
+        maxQueuedEvents: bounded(options.maxQueuedEvents, DEFAULT_MAX_QUEUED_EVENTS, HARD_MAX_QUEUED_EVENTS, "maxQueuedEvents"),
+        maxSubscribers: bounded(options.maxSubscribers, DEFAULT_MAX_SUBSCRIBERS, HARD_MAX_SUBSCRIBERS, "maxSubscribers"),
+        pollIntervalMs: bounded(options.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS, HARD_POLL_INTERVAL_MS, "pollIntervalMs"),
+        reconnectInitialMs: bounded(options.reconnectInitialMs, DEFAULT_RECONNECT_INITIAL_MS, HARD_RECONNECT_INITIAL_MS, "reconnectInitialMs"),
+        reconnectMaxMs: bounded(options.reconnectMaxMs, DEFAULT_RECONNECT_MAX_MS, HARD_RECONNECT_MAX_MS, "reconnectMaxMs"),
+        maxRetainedEventsPerRun: bounded(options.maxRetainedEventsPerRun, DEFAULT_MAX_RETAINED_EVENTS_PER_RUN, HARD_MAX_RETAINED_EVENTS_PER_RUN, "maxRetainedEventsPerRun"),
+        maxRetentionAgeMs: bounded(options.maxRetentionAgeMs, DEFAULT_MAX_RETENTION_AGE_MS, HARD_MAX_RETENTION_AGE_MS, "maxRetentionAgeMs"),
+    };
+    if (resolved.reconnectInitialMs > resolved.reconnectMaxMs) {
+        throw new RangeError("reconnectInitialMs must not exceed reconnectMaxMs");
+    }
+    return resolved;
+}
+function normalizeRecord(input, maxEventBytes) {
+    if (!input || typeof input !== "object")
+        throw inputError();
+    const record = clone(input);
+    const ownership = normalizeOwnership(record);
+    const sessionId = requiredText(record.sessionId);
+    const runId = requiredText(record.runId);
+    const id = requiredText(record.id);
+    if (record.redacted !== true ||
+        record.type !== record.event?.type ||
+        record.event.sessionId !== sessionId ||
+        record.event.runId !== runId) {
+        throw inputError();
+    }
+    parseTimestamp(record.timestamp, "input");
+    if (record.sequence !== undefined && (!Number.isSafeInteger(record.sequence) || record.sequence < 1))
+        throw inputError();
+    if (Buffer.byteLength(JSON.stringify(record), "utf8") > maxEventBytes)
+        throw inputError();
+    return {
+        ...record,
+        ...ownership,
+        id,
+        sessionId,
+        runId,
+        ...(record.sequence === undefined ? {} : { sequence: record.sequence }),
+    };
+}
+function normalizeRead(input, maxPageSize) {
+    if (!input || typeof input !== "object")
+        throw inputError();
+    return {
+        ...input,
+        ownership: normalizeOwnership(input.ownership),
+        sessionId: requiredText(input.sessionId),
+        runId: requiredText(input.runId),
+        limit: bounded(input.limit, maxPageSize, maxPageSize, "page limit"),
+    };
+}
+function normalizeOwnership(input) {
+    if (!input || typeof input.tenantId !== "string" || input.tenantId.length === 0)
+        throw inputError();
+    if (input.accountId !== undefined && (typeof input.accountId !== "string" || input.accountId.length === 0))
+        throw inputError();
+    if (input.userId !== undefined && (typeof input.userId !== "string" || input.userId.length === 0))
+        throw inputError();
+    return {
+        tenantId: input.tenantId,
+        ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+    };
+}
+function requiredText(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw inputError();
+    return value;
+}
+function parseTimestamp(value, kind) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+        throw kind === "cursor" ? cursorError() : inputError();
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value)
+        throw kind === "cursor" ? cursorError() : inputError();
+    return parsed;
+}
+function bounded(value, fallback, hard, name) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > hard)
+        throw inputError(`${name} is outside its allowed range`);
+    return resolved;
+}
+function sameOwnership(a, b) {
+    return a.tenantId === b.tenantId && a.accountId === b.accountId && a.userId === b.userId;
+}
+function streamKey(ownership, sessionId, runId) {
+    return JSON.stringify([ownership.tenantId, ownership.accountId, ownership.userId, sessionId, runId]);
+}
+function orderedRecords(stream) {
+    return stream ? [...stream.records.values()] : [];
+}
+function positionOf(records, cursor) {
+    return records.findIndex((record) => record.sequence === cursor.sequence && record.id === cursor.id);
+}
+function positionAfter(records, cursor, stream) {
+    const position = positionOf(records, cursor);
+    if (position >= 0)
+        return position + 1;
+    if (!stream || cursor.sequence < stream.nextSequence)
+        throw retentionError();
+    throw cursorError();
+}
+function terminalAt(records, after) {
+    const last = records.at(-1);
+    if (!last || !isTerminal(last))
+        return false;
+    return after === undefined || after.sequence <= last.sequence;
+}
+function isTerminal(record) {
+    return (record.type === "agent_finished" || record.type === "agent_denied" || record.type === "run_limit_exceeded" || record.type === "error");
+}
+function sameRecord(existing, input) {
+    const { sequence: _existingSequence, ...existingWithoutSequence } = existing;
+    const { sequence: _inputSequence, ...inputWithoutSequence } = input;
+    return stableJson(existingWithoutSequence) === stableJson(inputWithoutSequence);
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+        .join(",")}}`;
+}
+function clone(value) {
+    try {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new Error("not JSON serializable");
+        return JSON.parse(encoded);
+    }
+    catch {
+        throw inputError();
+    }
+}
+function validCursor(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const cursor = value;
+    return (cursor.v === 1 &&
+        typeof cursor.tenantId === "string" &&
+        cursor.tenantId.length > 0 &&
+        (cursor.accountId === undefined || (typeof cursor.accountId === "string" && cursor.accountId.length > 0)) &&
+        (cursor.userId === undefined || (typeof cursor.userId === "string" && cursor.userId.length > 0)) &&
+        typeof cursor.sessionId === "string" &&
+        cursor.sessionId.length > 0 &&
+        typeof cursor.runId === "string" &&
+        cursor.runId.length > 0 &&
+        Number.isSafeInteger(cursor.sequence) &&
+        cursor.sequence > 0 &&
+        typeof cursor.id === "string" &&
+        cursor.id.length > 0);
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+function inputError(message = "Invalid agent event source input") {
+    return new AgentEventSourceError("ERR_PRISM_AGENT_EVENT_SOURCE_INPUT", message);
+}
+function cursorError() {
+    return new AgentEventSourceError("ERR_PRISM_AGENT_EVENT_SOURCE_CURSOR", "Invalid agent event cursor");
+}
+function retentionError() {
+    return new AgentEventSourceError("ERR_PRISM_AGENT_EVENT_SOURCE_RETENTION", "Agent event history is unavailable");
+}
+function overflowError() {
+    return new AgentEventSourceError("ERR_PRISM_AGENT_EVENT_SOURCE_OVERFLOW", "Agent event subscription overflow");
+}
+function closedError() {
+    return new AgentEventSourceError("ERR_PRISM_AGENT_EVENT_SOURCE_CLOSED", "Agent event source is closed");
+}
+//# sourceMappingURL=agent-event-source.js.map

package/dist/agent-loops.js

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