@arnilo/prism 0.0.23 → 0.0.24

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [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 +36,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 +63,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 +186,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-run-state.js

@@ -28,7 +28,12 @@ export function agentFingerprint(agent, revision) {
         instructions: config.instructions ?? null,
         systemPrompt,
         skills: skills.map((skill) => ({ name: skill.name, instructions: skill.instructions, toolNames: skill.toolNames })),
-        tools: tools.map((tool) => ({ name: tool.name, parameters: tool.parameters, exclusive: tool.exclusive })),
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            parameters: tool.parameters,
+            exclusive: tool.exclusive,
+            effect: typeof tool.effect === "function" ? "classifier" : tool.effect,
+        })),
         guardrails: guardrails.map((guardrail) => ({ name: guardrail.name, stage: guardrail.stage, revision: guardrail.revision })),
         loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop
             ? config.loop.strategy

package/dist/agents.js

@@ -160,6 +160,7 @@ class RuntimeAgentSession {
     activeRedactor;
     activeProvider;
     activeLedger;
+    activeEffectStore;
     activeOwnership;
     activeIdentity;
     activeIdempotencyKey;
@@ -244,6 +245,7 @@ class RuntimeAgentSession {
             (options.redactor !== undefined ||
                 options.ownership !== undefined ||
                 options.validate !== undefined ||
+                options.effectStore !== undefined ||
                 options.runState !== undefined)) {
             throw new AgentRunStateError("Secure agent defaults cannot be replaced per run");
         }
@@ -257,8 +259,8 @@ class RuntimeAgentSession {
         }
         if (durableOptions) {
             validateRunStateOptions(durableOptions);
-            if (options.model || options.guardrails || options.loop)
-                throw new AgentRunStateError("Durable runs require model, guardrails, and loop on AgentConfig for fingerprinting");
+            if (options.model || options.guardrails || options.loop || options.effectStore)
+                throw new AgentRunStateError("Durable runs require model, guardrails, loop, and effect store on AgentConfig for fingerprinting");
             const configuredLoop = this.agent.config.loop;
             if (configuredLoop && !isBuiltInLoop(configuredLoop))
                 throw new AgentRunStateError("Custom AgentLoopStrategy is not durable");
@@ -277,6 +279,7 @@ class RuntimeAgentSession {
         this.pendingSoftInterrupt = false;
         this.activeRedactor = options.redactor ?? this.agent.config.redactor;
         this.activeLedger = options.runLedger ?? this.agent.config.runLedger;
+        this.activeEffectStore = options.effectStore ?? this.agent.config.effectStore;
         this.activeOwnership = options.ownership ?? this.agent.config.ownership;
         this.activeIdentity = resolveRunIdentity(options.identity, this.agent.config.identity, this.activeOwnership);
         if (this.activeIdentity && !this.activeOwnership)
@@ -492,6 +495,7 @@ class RuntimeAgentSession {
                     trust: this.agent.config.trust,
                     redactor: this.activeRedactor,
                     ledger: this.activeLedger,
+                    effectStore: this.activeEffectStore,
                     ownership: this.activeOwnership,
                     identity: this.activeIdentity,
                     guardrails: this.activeGuardrails,
@@ -644,6 +648,7 @@ class RuntimeAgentSession {
             }
             finally {
                 this.activeLedger = undefined;
+                this.activeEffectStore = undefined;
                 this.activeOwnership = undefined;
                 this.activeIdentity = undefined;
                 this.activeIdempotencyKey = undefined;