@arnilo/prism 0.0.23 → 0.0.24

package/dist/contracts.d.ts

@@ -365,6 +365,8 @@ export interface RunOptions {
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly redactor?: SecretRedactor;
     readonly runLedger?: RunLedger;
+    /** Optional durable recovery store. Per-run value overrides this agent default. */
+    readonly effectStore?: ToolEffectStore;
     readonly ownership?: OwnershipScope;
     /** Host-verified identity; when set, must project onto `ownership` without widening. */
     readonly identity?: import("./identity.js").AgentIdentity;
@@ -444,6 +446,8 @@ export interface AgentConfig {
     readonly systemPrompt?: SystemPromptConfig;
     readonly redactor?: SecretRedactor;
     readonly runLedger?: RunLedger;
+    /** Optional durable recovery store. */
+    readonly effectStore?: ToolEffectStore;
     readonly ownership?: OwnershipScope;
     /** Host-verified identity default for sessions created from this agent. */
     readonly identity?: import("./identity.js").AgentIdentity;
@@ -834,12 +838,23 @@ export type AgentEvent = {
     readonly attempt: number;
     readonly result: ArtifactValidation;
 };
+export type ToolEffectKind = "none" | "local_mutation" | "external_mutation";
+export type ToolEffectIdempotency = "none" | "optional" | "required" | "tool_managed" | "unsupported";
+/** Static or validated-argument classification of one tool call's side-effect behavior. */
+export interface ToolEffectDeclaration {
+    readonly kind: ToolEffectKind;
+    readonly idempotency: ToolEffectIdempotency;
+}
+/** Runs after argument validation. It must be synchronous, deterministic, bounded, and side-effect-free. */
+export type ToolEffectClassifier = (args: JsonObject, context: ToolExecutionContext) => ToolEffectDeclaration;
 export interface ToolDefinition {
     readonly name: string;
     readonly description?: string;
     readonly parameters?: JsonObject;
     /** Force any provider turn containing this tool to dispatch sequentially. */
     readonly exclusive?: boolean;
+    /** Optional side-effect declaration. Omitted tools retain legacy unmanaged dispatch. */
+    readonly effect?: ToolEffectDeclaration | ToolEffectClassifier;
     execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> | ToolResult;
 }
 export interface ToolRegistry {
@@ -856,6 +871,8 @@ export interface ToolExecutionContext {
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** Host-verified identity for this tool invocation, when enterprise identity is active. */
     readonly identity?: import("./identity.js").AgentIdentity;
+    /** Core-derived stable effect key. Never accept a model-supplied key as authority. */
+    readonly idempotencyKey?: string;
     progress?(progress?: unknown, metadata?: Readonly<Record<string, unknown>>): void | Promise<void>;
 }
 export interface ToolResult {
@@ -866,6 +883,90 @@ export interface ToolResult {
     readonly error?: ErrorInfo;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+export type ToolEffectStatus = "pending" | "dispatched" | "completed" | "failed_retryable" | "failed_terminal" | "unknown";
+export interface ToolEffectRecord extends OwnershipScope {
+    readonly key: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly argumentsHash: string;
+    readonly status: ToolEffectStatus;
+    readonly attempt: number;
+    readonly version: number;
+    readonly claimToken?: string;
+    readonly result?: ToolResult;
+    readonly resultRef?: string;
+    readonly failure?: {
+        readonly code: string;
+        readonly reference?: string;
+    };
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly expiresAt?: string;
+}
+export interface ToolEffectKey {
+    readonly identity: import("./identity.js").AgentIdentity;
+    readonly ownership: OwnershipScope;
+    readonly key: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly argumentsHash: string;
+    readonly signal?: AbortSignal;
+}
+export interface ToolEffectTransition extends ToolEffectKey {
+    readonly claimToken: string;
+    readonly expectedVersion: number;
+}
+/** Durable claim/CAS store for recoverable tool effects. */
+export interface ToolEffectStore {
+    get(input: ToolEffectKey): Promise<ToolEffectRecord | undefined>;
+    begin(input: ToolEffectKey & {
+        readonly claimTtlMs?: number;
+        readonly maxAttempts?: number;
+    }): Promise<{
+        readonly outcome: "acquired" | "existing";
+        readonly record: ToolEffectRecord;
+    }>;
+    markDispatched(input: ToolEffectTransition): Promise<ToolEffectRecord>;
+    complete(input: ToolEffectTransition & {
+        readonly result?: ToolResult;
+        readonly resultRef?: string;
+    }): Promise<ToolEffectRecord>;
+    fail(input: ToolEffectTransition & {
+        readonly status: "failed_retryable" | "failed_terminal";
+        readonly failure: {
+            readonly code: string;
+            readonly reference?: string;
+        };
+    }): Promise<ToolEffectRecord>;
+    markUnknown(input: ToolEffectTransition & {
+        readonly failure?: {
+            readonly code: string;
+            readonly reference?: string;
+        };
+    }): Promise<ToolEffectRecord>;
+    resolveUnknown(input: ToolEffectKey & {
+        readonly expectedVersion: number;
+        readonly status: "completed" | "failed_retryable" | "failed_terminal";
+        readonly result?: ToolResult;
+        readonly resultRef?: string;
+        readonly failure?: {
+            readonly code: string;
+            readonly reference?: string;
+        };
+    }): Promise<ToolEffectRecord>;
+    cleanup(input: {
+        readonly ownership: OwnershipScope;
+        readonly before: string;
+        readonly limit?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly deleted: number;
+    }>;
+}
 export interface CommandDefinition {
     readonly name: string;
     readonly description?: string;
@@ -1446,6 +1547,8 @@ export interface AgentEventRecord extends OwnershipScope {
     readonly id: string;
     readonly sessionId: string;
     readonly runId?: string;
+    /** Durable sources allocate positive, strictly increasing per-run positions. */
+    readonly sequence?: number;
     readonly entryId?: string;
     readonly type: AgentEventType;
     readonly timestamp: string;
@@ -1453,6 +1556,58 @@ export interface AgentEventRecord extends OwnershipScope {
     readonly redacted: boolean;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** An event record returned by an {@link AgentEventSource}. */
+export interface DurableAgentEventRecord extends AgentEventRecord {
+    readonly runId: string;
+    readonly sequence: number;
+}
+export interface AgentEventEnvelope {
+    readonly record: DurableAgentEventRecord;
+    /** Opaque cursor immediately after `record`. */
+    readonly cursor: string;
+}
+export interface AgentEventSourcePage {
+    readonly items: readonly AgentEventEnvelope[];
+    readonly nextCursor?: string;
+    /** True only after every event preceding a terminal event has been returned. */
+    readonly terminal: boolean;
+}
+/** Exact-owned, per-run durable event read. `after` is exclusive. */
+export interface AgentEventSourceRead {
+    readonly ownership: OwnershipScope;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly after?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AgentEventSourceCleanup {
+    readonly ownership: OwnershipScope;
+    readonly before: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AgentEventSourceOptions {
+    readonly maxEventBytes?: number;
+    readonly maxPageSize?: number;
+    readonly maxCursorBytes?: number;
+    readonly maxQueuedEvents?: number;
+    readonly maxSubscribers?: number;
+    readonly pollIntervalMs?: number;
+    readonly reconnectInitialMs?: number;
+    readonly reconnectMaxMs?: number;
+    readonly maxRetainedEventsPerRun?: number;
+    readonly maxRetentionAgeMs?: number;
+}
+/** Optional durable event capability. `RunLedger` remains a write-only contract. */
+export interface AgentEventSource {
+    append(record: AgentEventRecord): Promise<DurableAgentEventRecord>;
+    page(input: AgentEventSourceRead): Promise<AgentEventSourcePage>;
+    subscribe(input: AgentEventSourceRead): AsyncIterable<AgentEventEnvelope>;
+    cleanup(input: AgentEventSourceCleanup): Promise<{
+        readonly deleted: number;
+    }>;
+}
 export type ToolCallStatus = "started" | "finished" | "error" | "blocked";
 /** Stored tool-call row. The `result` payload should be redacted before storage when secrets are present. */
 export interface ToolCallRecord extends OwnershipScope {
@@ -1715,6 +1870,8 @@ export interface ProductionPersistenceStore {
     readonly leases?: LeaseStore;
     /** Optional immutable run/trace feedback storage capability. */
     readonly feedback?: RunFeedbackStore;
+    /** Optional durable, cross-replica-capable event source. */
+    readonly events?: AgentEventSource;
     querySessions(query: SessionQuery): Promise<PersistencePage<SessionRecord>>;
     queryBranches(query: BranchQuery): Promise<PersistencePage<BranchRecord>>;
     queryEntries(query: SessionEntryQuery): Promise<PersistencePage<SessionEntry>>;

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMe
 export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, } from "./context-budget.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
-export type { ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, } from "./contracts.js";
+export type { ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, } from "./contracts.js";
 export { AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
@@ -31,6 +31,9 @@ export type { CredentialRecord, CredentialValueSource, MemoryCredentialStore, Re
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
 export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConformanceResult, DeviceKind, DevicePolicyErrorCode, DevicePolicyOptions, DeviceStreamLimits, ResolvedDevicePolicy, } from "./devices.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
+export type { AgentEventSourceErrorCode } from "./agent-event-source.js";
+export { AgentEventSourceError, createMemoryAgentEventSource } from "./agent-event-source.js";
+export { assertAgentEventSourceConforms } from "./testing/agent-event-source-conformance.js";
 export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, EventOverflowPolicy } from "./event-multiplexer.js";
 export { createEventMultiplexer } from "./event-multiplexer.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
@@ -97,8 +100,10 @@ export type { ThinkingCompatFamily, ThinkingLevel } from "./thinking.js";
 export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_LEVELS, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
 export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgumentValidationResult, ToolArgumentValidator, ToolFilter, ToolFilterInput, ToolParameterValidatorOptions, ToolRegistryOptions, ToolValidator, } from "./tools.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
+export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
+export type { ToolEffectErrorCode } from "./tool-effects.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.0.23";
+export declare const version = "0.0.24";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -16,6 +16,8 @@ export { createContributionRegistries, createContributionRegistry, registerDisco
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
+export { AgentEventSourceError, createMemoryAgentEventSource } from "./agent-event-source.js";
+export { assertAgentEventSourceConforms } from "./testing/agent-event-source-conformance.js";
 export { createEventMultiplexer } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
@@ -52,8 +54,9 @@ export { artifactStructuredOutputRequest, assertStructuredOutputRequestSupported
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_LEVELS, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
+export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.0.23";
+export const version = "0.0.24";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,4 @@
+import type { AgentEventSource } from "../contracts.js";
+export type AgentEventSourceConformanceFactory = () => AgentEventSource | Promise<AgentEventSource>;
+/** Assert durable append/page/replay ownership and cursor behavior without a database dependency. */
+export declare function assertAgentEventSourceConforms(factory: AgentEventSourceConformanceFactory): Promise<void>;

package/dist/testing/agent-event-source-conformance.js

@@ -0,0 +1,54 @@
+// ponytail: runner-free durable-event contract probe for database adapters.
+/** Assert durable append/page/replay ownership and cursor behavior without a database dependency. */
+export async function assertAgentEventSourceConforms(factory) {
+    const source = await factory();
+    const ownership = { tenantId: "tenant-a", accountId: "account-a", userId: "user-a" };
+    const input = { ownership, sessionId: "session-a", runId: "run-a" };
+    const first = event("event-a", "agent_started", input);
+    const second = event("event-b", "turn_started", input, "2026-01-01T00:00:01.000Z");
+    const storedFirst = await source.append(first);
+    const storedSecond = await source.append(second);
+    equal(storedFirst.sequence, 1, "first durable event must receive sequence 1");
+    equal(storedSecond.sequence, 2, "durable sequence must increase per run");
+    equal((await source.append(first)).sequence, 1, "identical duplicate append must be idempotent");
+    await rejects(() => source.append({ ...first, timestamp: "2026-01-01T00:00:02.000Z" }), "changed duplicate append must fail");
+    const page = await source.page({ ...input, limit: 1 });
+    equal(page.items.length, 1, "page limit must be honored");
+    equal(page.items[0].record.id, first.id, "page order must follow sequence");
+    if (!page.nextCursor)
+        throw new Error("truncated page must include a cursor");
+    const secondPage = await source.page({ ...input, after: page.nextCursor, limit: 1 });
+    equal(secondPage.items[0]?.record.id, second.id, "cursor must be exclusive");
+    const iterator = source.subscribe({ ...input, after: secondPage.items[0].cursor })[Symbol.asyncIterator]();
+    const pending = iterator.next();
+    const third = await source.append(event("event-c", "turn_started", input, "2026-01-01T00:00:02.000Z"));
+    equal((await pending).value?.record.id, third.id, "replay/live handoff dropped an event");
+    await iterator.return?.();
+    const terminal = await source.append(event("event-d", "agent_finished", input, "2026-01-01T00:00:03.000Z"));
+    const final = await source.page({ ...input, after: secondPage.items[0].cursor, limit: 10 });
+    equal(final.items.at(-1)?.record.id, terminal.id, "terminal page must include its terminal event");
+    equal(final.terminal, true, "terminal event must close only after prior events are delivered");
+    await rejects(() => source.page({ ...input, ownership: { ...ownership, tenantId: "tenant-b" }, after: page.nextCursor }), "foreign cursor must fail closed");
+    await rejects(() => source.append({ ...event("event-unredacted", "turn_started", input), redacted: false }), "unredacted append must fail");
+    await rejects(() => source.page({ ...input, limit: 0 }), "invalid page limit must fail");
+}
+function event(id, type, input, timestamp = "2026-01-01T00:00:00.000Z") {
+    const event = type === "turn_started"
+        ? { type, sessionId: input.sessionId, runId: input.runId, turn: 1 }
+        : { type, sessionId: input.sessionId, runId: input.runId };
+    return { id, ...input.ownership, sessionId: input.sessionId, runId: input.runId, type, timestamp, event, redacted: true };
+}
+function equal(actual, expected, message) {
+    if (actual !== expected)
+        throw new Error(`${message}; expected ${String(expected)}, received ${String(actual)}`);
+}
+async function rejects(action, message) {
+    try {
+        await action();
+    }
+    catch {
+        return;
+    }
+    throw new Error(message);
+}
+//# sourceMappingURL=agent-event-source-conformance.js.map

package/dist/testing/persistence-schema.d.ts

@@ -1,7 +1,7 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 5;
-export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
+export declare const PERSISTENCE_SCHEMA_VERSION = 7;
+export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_agent_event_streams" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {
     readonly name: string;

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 5;
+export const PERSISTENCE_SCHEMA_VERSION = 7;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -177,6 +177,17 @@ export function createPersistenceSchemaModel() {
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
+            {
+                name: "prism_agent_event_streams",
+                primaryKey: ["session_id", "run_id"],
+                columns: [
+                    { name: "session_id", type: "text" },
+                    { name: "run_id", type: "text" },
+                    { name: "next_sequence", type: "integer" },
+                    { name: "updated_at", type: "timestamp" },
+                ],
+                foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
+            },
             {
                 name: "prism_tool_calls",
                 primaryKey: ["id"],
@@ -369,6 +380,7 @@ export function createPersistenceSchemaModel() {
                 name: "prism_agent_events_run_sequence_idx",
                 table: "prism_agent_events",
                 columns: ["run_id", "sequence"],
+                unique: true,
                 purpose: "stable per-run event timeline pagination",
             },
             {
@@ -377,6 +389,12 @@ export function createPersistenceSchemaModel() {
                 columns: ["session_id", "timestamp", "id"],
                 purpose: "event stream pagination",
             },
+            {
+                name: "prism_agent_events_owner_timestamp_sequence_idx",
+                table: "prism_agent_events",
+                columns: ["tenant_id", "account_id", "user_id", "timestamp", "sequence", "id"],
+                purpose: "owned durable event retention cleanup",
+            },
             {
                 name: "prism_tool_calls_session_name_started_idx",
                 table: "prism_tool_calls",
@@ -463,34 +481,51 @@ function migrationStep(version, name, description) {
     const content = version === 1
         ? {
             tables: model.tables
-                .filter((table) => table.name !== "prism_run_feedback")
+                .filter((table) => table.name !== "prism_run_feedback" && table.name !== "prism_agent_event_streams")
                 .map((table) => table.name === "prism_usage"
                 ? { ...table, columns: table.columns.filter((column) => !["scope", "turn", "attempt"].includes(column.name)) }
                 : table),
-            indexes: model.indexes.filter((index) => !index.name.startsWith("prism_usage_session_scope_") && !index.name.startsWith("prism_run_feedback_")),
+            indexes: model.indexes
+                .filter((index) => !index.name.startsWith("prism_usage_session_scope_") &&
+                !index.name.startsWith("prism_run_feedback_") &&
+                !index.name.startsWith("prism_agent_event_streams_") &&
+                !index.name.startsWith("prism_agent_events_owner_timestamp_"))
+                .map((index) => index.name === "prism_agent_events_run_sequence_idx"
+                ? (() => {
+                    const { unique: _unique, ...legacy } = index;
+                    return legacy;
+                })()
+                : index),
         }
-        : version === 2
-            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-            : version === 3
+        : version === 7
+            ? { indexes: ["prism_agent_events_owner_timestamp_sequence_idx"] }
+            : version === 6
                 ? {
-                    tables: ["prism_run_feedback"],
-                    indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
+                    tables: ["prism_agent_event_streams"],
+                    indexes: ["prism_agent_events_run_sequence_idx"],
                 }
-                : version === 4
-                    ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
-                        { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
-                    : version === 5
+                : version === 2
+                    ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+                    : version === 3
                         ? {
-                            tables: ["prism_legal_holds", "prism_tenant_quotas"],
-                            indexes: [
-                                "prism_legal_holds_owner_resource_idx",
-                                "prism_legal_holds_created_id_idx",
-                                "prism_tenant_quotas_owner_kind_idx",
-                            ],
+                            tables: ["prism_run_feedback"],
+                            indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
                         }
-                        : (() => {
-                            throw new Error(`Unknown migration version ${version}`);
-                        })();
+                        : version === 4
+                            ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                                { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                            : version === 5
+                                ? {
+                                    tables: ["prism_legal_holds", "prism_tenant_quotas"],
+                                    indexes: [
+                                        "prism_legal_holds_owner_resource_idx",
+                                        "prism_legal_holds_created_id_idx",
+                                        "prism_tenant_quotas_owner_kind_idx",
+                                    ],
+                                }
+                                : (() => {
+                                    throw new Error(`Unknown migration version ${version}`);
+                                })();
     return {
         version,
         name,
@@ -509,6 +544,8 @@ export function createPersistenceMigrationContract() {
             migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
             migrationStep(4, "004_session_search", "Add bounded session search indexes and adapter-local FTS objects."),
             migrationStep(5, "005_lifecycle_hold_quota", "Add legal-hold and tenant-quota tables for retention lifecycle."),
+            migrationStep(6, "006_agent_event_source", "Add transactional per-run event counters and unique durable event sequencing."),
+            migrationStep(7, "007_agent_event_retention_index", "Add an exact-owner durable-event retention cleanup index."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/tool-effect-store-conformance.d.ts

@@ -0,0 +1,9 @@
+import type { AgentIdentity, ToolEffectKey, ToolEffectStore } from "../contracts.js";
+export interface ToolEffectStoreConformanceOptions {
+    readonly identity?: AgentIdentity;
+    readonly ownership?: ToolEffectKey["ownership"];
+    readonly key?: string;
+}
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export declare function assertToolEffectStoreConforms(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;
+export declare function runToolEffectStoreConformance(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;

package/dist/testing/tool-effect-store-conformance.js

@@ -0,0 +1,85 @@
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export async function assertToolEffectStoreConforms(factory, options = {}) {
+    const store = await factory();
+    const identity = options.identity ?? testIdentity();
+    const ownership = options.ownership ?? { tenantId: identity.tenantId };
+    const base = key(identity, ownership, options.key ?? "prism:tool-effect:v1:conformance");
+    const first = await store.begin(base);
+    if (first.outcome !== "acquired" || first.record.status !== "pending" || !first.record.claimToken) {
+        throw new Error("store must acquire an absent tool effect as pending with a claim token");
+    }
+    const duplicate = await store.begin(base);
+    if (duplicate.outcome !== "existing" || duplicate.record.status !== "pending") {
+        throw new Error("store must return existing pending effects without a second claim");
+    }
+    const dispatched = await store.markDispatched(transition(base, first.record));
+    if (dispatched.status !== "dispatched" || dispatched.version !== first.record.version + 1) {
+        throw new Error("store must transition a claimed pending effect to dispatched");
+    }
+    const result = { toolCallId: base.toolCallId, name: base.toolName, value: { ok: true } };
+    const completed = await store.complete({ ...transition(base, dispatched), result });
+    if (completed.status !== "completed" || completed.result?.toolCallId !== base.toolCallId) {
+        throw new Error("store must retain a completed bounded result");
+    }
+    const replay = await store.begin(base);
+    if (replay.outcome !== "existing" || replay.record.status !== "completed") {
+        throw new Error("store must preserve completed duplicate state");
+    }
+    await expectReject(() => store.markDispatched(transition(base, dispatched)), "store must reject stale claim/version transitions");
+    const unknownKey = key(identity, ownership, `${base.key}:unknown`, "call-unknown");
+    const unknownPending = await store.begin(unknownKey);
+    const unknownDispatched = await store.markDispatched(transition(unknownKey, unknownPending.record));
+    const unknown = await store.markUnknown({ ...transition(unknownKey, unknownDispatched), failure: { code: "test" } });
+    if (unknown.status !== "unknown")
+        throw new Error("store must mark dispatched effects unknown");
+    const resolved = await store.resolveUnknown({
+        ...unknownKey,
+        expectedVersion: unknown.version,
+        status: "failed_terminal",
+        failure: { code: "test" },
+    });
+    if (resolved.status !== "failed_terminal")
+        throw new Error("store must CAS-resolve unknown effects");
+    const cleanup = await store.cleanup({ ownership, before: new Date(Date.now() + 60_000).toISOString(), limit: 100 });
+    if (cleanup.deleted < 1)
+        throw new Error("store cleanup must remove terminal effects");
+}
+export async function runToolEffectStoreConformance(factory, options = {}) {
+    await assertToolEffectStoreConforms(factory, options);
+}
+function key(identity, ownership, value, toolCallId = "call") {
+    return {
+        identity,
+        ownership,
+        key: value,
+        sessionId: "session",
+        runId: "run",
+        toolCallId,
+        toolName: "effect.tool",
+        argumentsHash: "a".repeat(64),
+    };
+}
+function transition(base, record) {
+    if (!record.claimToken)
+        throw new Error("store transition record lacks claim token");
+    return { ...base, claimToken: record.claimToken, expectedVersion: record.version };
+}
+async function expectReject(run, message) {
+    try {
+        await run();
+    }
+    catch {
+        return;
+    }
+    throw new Error(message);
+}
+function testIdentity() {
+    return {
+        tenantId: "tenant",
+        principal: { kind: "service", id: "conformance" },
+        scopes: ["tools:execute"],
+        issuedAt: "2026-01-01T00:00:00.000Z",
+        verified: true,
+    };
+}
+//# sourceMappingURL=tool-effect-store-conformance.js.map

package/dist/tool-effects.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObject, ToolEffectKey, ToolEffectStore } from "./contracts.js";
+export type ToolEffectErrorCode = "ERR_PRISM_TOOL_EFFECT_REQUIRED" | "ERR_PRISM_TOOL_EFFECT_CONFLICT" | "ERR_PRISM_TOOL_EFFECT_UNKNOWN" | "ERR_PRISM_TOOL_EFFECT_COMPLETED" | "ERR_PRISM_TOOL_EFFECT_LIMIT";
+export declare class ToolEffectError extends Error {
+    readonly code: ToolEffectErrorCode;
+    constructor(code: ToolEffectErrorCode, message: string);
+}
+/** Stable JSON representation for an already-validated tool arguments object. */
+export declare function canonicalToolEffectJson(value: unknown): string;
+export declare function toolEffectArgumentsHash(argumentsValue: JsonObject): string;
+/** Derives the only core-authoritative key. Callers never supply this from model input. */
+export declare function deriveToolEffectKey(input: Omit<ToolEffectKey, "key" | "signal">): string;
+/** In-process reference. Use a durable adapter for cross-replica claims. */
+export declare function createMemoryToolEffectStore(options?: {
+    readonly now?: () => number;
+}): ToolEffectStore;