@arnilo/prism 0.0.23 → 0.0.25

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;
@@ -504,14 +508,144 @@ export interface SubscribeOptions {
     readonly overflow?: SubscriberOverflowPolicy;
 }
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
-export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval";
+export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
+export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
+export type PendingDecisionKind = "tool_approval" | "elicitation";
+/** Redacted match scope for one pending or sticky decision; never contains raw tool arguments. */
+export interface DecisionScope {
+    readonly toolName?: string;
+    readonly effectKind?: ToolEffectKind;
+    /** Redacted principal reference (tenant/kind/id); never a credential. */
+    readonly identity?: string;
+    /** Bounded argument-value constraints; deep-equal matched per key. */
+    readonly actionConstraints?: Readonly<Record<string, JsonValue>>;
+    /** SHA-256 of canonical JSON arguments; present instead of raw arguments. */
+    readonly argumentsHash?: string;
+}
+/** One redacted, unresolved approval request inside a suspended durable run. */
+export interface PendingDecision {
+    /** Unique within the run; nested runs use supervisor-prefixed ids. */
+    readonly approvalId: string;
+    readonly kind: PendingDecisionKind;
+    readonly toolCallId?: string;
+    readonly scope: DecisionScope;
+    /** Bounded, redacted. */
+    readonly reason: string;
+    /** Typed payload contract for elicitation decisions. */
+    readonly elicitationSchema?: JsonObject;
+    /** Delegation chain, root-first; core-written, never client-supplied. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
 /** Redacted safe-boundary descriptor; never contains tool arguments. */
 export interface AgentRunInterruption {
     readonly kind: AgentRunInterruptionKind;
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
+    readonly pendingDecisions?: readonly PendingDecision[];
+}
+/** One host decision applied to one pending approval request. */
+export interface RunDecision {
+    readonly approvalId: string;
+    readonly outcome: ApprovalOutcome;
+    /** Bounded to 2 KiB; redacted. */
+    readonly reason?: string;
+    /** Revalidated (schema, guardrails, policy) before dispatch; produces a new arguments hash. */
+    readonly modifiedArguments?: JsonObject;
+    /** Elicitation payload; validated against the pending decision's elicitationSchema. */
+    readonly elicitation?: JsonObject;
+}
+/** Run-scoped sticky decision; exact scope match, rechecked against policy, dropped at run end. */
+export interface StickyDecision {
+    readonly scope: DecisionScope;
+    readonly outcome: "allow_for_run" | "reject_for_run";
+    readonly reason?: string;
+    readonly decidedAt: string;
+    /** Delegation path when the sticky was created for a nested-run decision. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
+/** Root-visible link between one nested approval and the child-run approval id. */
+export interface NestedRunApproval {
+    /** Root-visible approval id (hashed, non-enumerating across runs). */
+    readonly id: string;
+    /** Approval id as the nested run recorded it. */
+    readonly childApprovalId: string;
+}
+/** Root-visible link between a suspended nested run and the tool call that hosted it. */
+export interface NestedRunRef {
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly toolCallId: string;
+    /** Redacted delegation path (child ids, root first). */
+    readonly path: readonly string[];
+    readonly approvals: readonly NestedRunApproval[];
+    /** Decisions persisted by a partial batch, keyed by root-visible approval id. */
+    readonly decisions?: Readonly<Record<string, RunDecision>>;
+}
+/** Outcome of resuming a nested run through the host-supplied hook. */
+export type NestedRunOutcome = {
+    readonly status: "suspended";
+    readonly pendingDecisions: readonly PendingDecision[];
+} | {
+    readonly status: "completed";
+    readonly value?: JsonValue;
+} | {
+    readonly status: "failed";
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Host hook that resumes a nested run (supervisor child) with child-visible decisions.
+ * Used both when a nested suspension first surfaces (sticky auto-apply) and when root
+ * decisions route back to the child on resume.
+ */
+export type ResumeNestedRun = (nested: {
+    readonly ref: AgentRunRef;
+    readonly toolCallId: string;
+    readonly path: readonly string[];
+}, decisions: readonly RunDecision[]) => Promise<NestedRunOutcome>;
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export declare class AgentDelegationSuspendedError extends Error {
+    readonly ref: AgentRunRef;
+    readonly pendingDecisions: readonly PendingDecision[];
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    readonly path?: readonly string[] | undefined;
+    readonly code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall?: ToolCallContent;
+    constructor(ref: AgentRunRef, pendingDecisions: readonly PendingDecision[], 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path?: readonly string[] | undefined);
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export declare class AgentDecisionError extends Error {
+    readonly code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT";
+    constructor(code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT", message: string, options?: {
+        readonly cause?: unknown;
+    });
 }
+export declare const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export declare const HARD_MAX_PENDING_DECISIONS = 128;
+export declare const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export declare const HARD_MAX_STICKY_DECISIONS = 256;
+export declare const MAX_DECISION_REASON_BYTES: number;
+export declare const HARD_MAX_DECISION_REASON_BYTES: number;
+export declare const MAX_ELICITATION_BYTES: number;
+export declare const HARD_MAX_ELICITATION_BYTES: number;
+export declare const MAX_ACTION_CONSTRAINTS = 32;
+export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export declare const MAX_ATTRIBUTION_DEPTH = 8;
+export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
+export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
@@ -520,6 +654,8 @@ export interface AgentRunStateOptions {
     readonly interruptBeforeTool?: boolean;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
+    /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Versioned, redacted checkpoint payload. Treat as opaque except status/version/interruption. */
 export interface AgentRunState {
@@ -536,8 +672,11 @@ export interface AgentRunState {
     readonly version?: number;
 }
 export interface AgentRunResume {
-    readonly decision: "approve" | "deny";
     readonly expectedVersion: number;
+    /** Legacy single-approval path; `approve` allows all pending once, `deny` terminates the run denied. */
+    readonly decision?: "approve" | "deny";
+    /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
+    readonly decisions?: readonly RunDecision[];
 }
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
@@ -545,6 +684,8 @@ export interface AgentRunResumeOptions {
     readonly definitionRevision: string;
     readonly ownership?: OwnershipScope;
     readonly fencingToken?: number;
+    /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Bounded, abortable options for `resumeAgentRunStream()`. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
@@ -562,6 +703,13 @@ export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message: string);
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export declare class AgentLoopStateError extends Error {
+    readonly code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION";
+    constructor(code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION", message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
 /** Terminal result of `session.run()` / `session.prompt()`. Failed and aborted runs throw {@link AgentRunError} with this shape attached. */
 export interface AgentRunResult {
     readonly sessionId: string;
@@ -834,12 +982,38 @@ 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;
+/**
+ * Elicitation contract declared by a tool. When a durable gated run suspends on this tool,
+ * the pending decision has kind `elicitation` and carries this schema as its payload contract;
+ * the resume decision's `elicitation` payload resolves the call without executing it.
+ */
+export interface ToolElicitationRequest {
+    /** Typed payload contract; bounded to HARD_MAX_ELICITATION_BYTES when serialized. */
+    readonly schema: JsonObject;
+    /** Human-facing reason (e.g. the question); bounded to MAX_DECISION_REASON_BYTES. */
+    readonly reason?: string;
+    /** Answer-shape validation beyond structural schema checks; throw to reject the payload. */
+    readonly validate?: (payload: JsonObject) => void;
+}
 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;
+    /** Optional elicitation contract for durable gating; return undefined to fall back to plain tool approval. */
+    readonly elicitation?: (args: JsonObject, context: ToolExecutionContext) => ToolElicitationRequest | undefined;
     execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> | ToolResult;
 }
 export interface ToolRegistry {
@@ -856,6 +1030,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 +1042,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 +1706,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 +1715,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 +2029,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>>;
@@ -1865,8 +2181,13 @@ export interface LoopContext {
     /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
     readonly toolConcurrency: number;
     assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
-    /** Charges a complete tool round before any call in it can start. */
-    chargeToolRound?(calls: readonly ToolCallContent[]): void;
+    /**
+     * Charges a complete tool round before any call in it can start. On durable interrupt
+     * runs this is also the round-level approval gate: it collects every gated call of the
+     * round into one suspension. Loops must await it; dispatch without it falls back to
+     * per-call single-decision suspensions.
+     */
+    chargeToolRound?(calls: readonly ToolCallContent[]): void | Promise<void>;
     generate(request: ProviderRequest): Promise<ProviderTurnResult>;
     dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
     isToolCallExclusive?(call: ToolCallContent): boolean;
@@ -1876,10 +2197,23 @@ export interface LoopContext {
     hasPendingSteers?(): boolean;
     /** Drain pending steers into history/session. Returns true when any were applied. */
     applyPendingSteers?(): Promise<boolean>;
+    /** Snapshot captured at the last suspension when the strategy declared snapshot/restore. Present only on resume. */
+    readonly restoredLoopState?: JsonValue;
 }
 export interface AgentLoopStrategy {
     readonly name: string;
+    /** Host-authored loop revision. Joins the durable-run fingerprint when snapshot hooks are present. */
+    readonly revision?: string;
     run(ctx: LoopContext): Promise<Usage | undefined>;
+    /**
+     * Capture loop-local resumable state at suspension. Must return a JSON-compatible value;
+     * core bounds and redacts it inside the durable run-state envelope. Declare together with
+     * `restore`; a custom strategy without both hooks is rejected before any provider call on
+     * durable runs (`AgentLoopStateError` / `ERR_PRISM_LOOP_NOT_DURABLE`).
+     */
+    snapshot?(): JsonValue;
+    /** Rehydrate from a previously captured snapshot; must throw on drift. Called before `run` on resume. */
+    restore?(snapshot: JsonValue): void;
 }
 export type AgentLoopOptions = {
     readonly strategy: "single-shot";

package/dist/contracts.js

@@ -1,3 +1,47 @@
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export class AgentDelegationSuspendedError extends Error {
+    ref;
+    pendingDecisions;
+    path;
+    code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall;
+    constructor(ref, pendingDecisions, 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path) {
+        super("Delegated run suspended");
+        this.ref = ref;
+        this.pendingDecisions = pendingDecisions;
+        this.path = path;
+        this.name = "AgentDelegationSuspendedError";
+    }
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export class AgentDecisionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentDecisionError";
+    }
+}
+export const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export const HARD_MAX_PENDING_DECISIONS = 128;
+export const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export const HARD_MAX_STICKY_DECISIONS = 256;
+export const MAX_DECISION_REASON_BYTES = 2 * 1024;
+export const HARD_MAX_DECISION_REASON_BYTES = 8 * 1024;
+export const MAX_ELICITATION_BYTES = 16 * 1024;
+export const HARD_MAX_ELICITATION_BYTES = 64 * 1024;
+export const MAX_ACTION_CONSTRAINTS = 32;
+export const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export const MAX_ATTRIBUTION_DEPTH = 8;
+export const MAX_ACTION_CONSTRAINT_BYTES = 4 * 1024;
+export const HARD_MAX_ACTION_CONSTRAINT_BYTES = 16 * 1024;
 export class AgentRunStateError extends Error {
     code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message) {
@@ -5,6 +49,15 @@ export class AgentRunStateError extends Error {
         this.name = "AgentRunStateError";
     }
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export class AgentLoopStateError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentLoopStateError";
+    }
+}
 export class AgentRunError extends Error {
     result;
     constructor(result, options) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { resolveAgentDefinition } from "./agent-definitions.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export type { AgentRunLifecycle, AgentRunLifecycleAgent, AgentRunLifecycleOptions, AgentRunLifecycleRequest, AgentRunLifecycleStreamRequest, } from "./agent-run-lifecycle.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
-export type { StoredAgentRunState } from "./agent-run-state.js";
+export type { PendingToolCall, StoredAgentRunState } from "./agent-run-state.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export type { ArtifactApproval, ArtifactApprovalState, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
@@ -20,8 +20,8 @@ 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 { 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 type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, ResumeNestedRun, RunDecision, StickyDecision, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, 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";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } 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.25";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -10,12 +10,14 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.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 { 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 { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, 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 { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 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.25";
 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>;