@arnilo/prism 0.0.96 → 0.1.1

package/dist/contracts.d.ts

@@ -1,11 +1,11 @@
-import type { AgentInput } from "./input.js";
+import type { AudioContent, DocumentContent, FileContent } from "./content.js";
 import type { ContributionRegistries } from "./contributions.js";
+import type { AgentInput } from "./input.js";
+import type { ManifestContributionDeclaration } from "./manifests.js";
 import type { Middleware, MiddlewareHookName, MiddlewareRegistry } from "./middleware.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { PermissionPolicy, TrustPolicy } from "./security.js";
-import type { ManifestContributionDeclaration } from "./manifests.js";
 import type { ToolValidator } from "./tools.js";
-import type { AudioContent, DocumentContent, FileContent } from "./content.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
@@ -15,6 +15,9 @@ export interface ErrorInfo {
     readonly name?: string;
     readonly message: string;
     readonly code?: string | number;
+    /** Provider backpressure hint (e.g. from a `Retry-After` header); retry policies
+     *  honor it capped at their own `maxDelayMs`. */
+    readonly retryAfterMs?: number;
     readonly cause?: unknown;
 }
 export type { AudioContent, DocumentContent, FileContent } from "./content.js";
@@ -43,7 +46,11 @@ export interface ToolCallDeltaContent {
     readonly id?: string;
     readonly name?: string;
     readonly argumentsText?: string;
+    /** Who executes the call. `"provider-hosted"` = the provider runs it server-side;
+     *  the host must NOT dispatch it or send a `tool_result`. Defaults to `"host"`. */
+    readonly authority?: ToolCallAuthority;
 }
+export type ToolCallAuthority = "host" | "provider-hosted";
 export interface ToolCallContent {
     readonly type: "tool_call";
     readonly id: string;
@@ -51,6 +58,10 @@ export interface ToolCallContent {
     readonly arguments: JsonObject;
     /** Set when streamed arguments failed JSON parse; dispatch blocks without execute(). */
     readonly argumentsError?: ErrorInfo;
+    /** Who executes the call. `"provider-hosted"` = the provider already ran it
+     *  server-side; the host must NOT dispatch it or append a `tool_result`. The
+     *  assistant response text already incorporates the call's effect. */
+    readonly authority?: ToolCallAuthority;
 }
 export interface ToolResultContent {
     readonly type: "tool_result";
@@ -229,6 +240,11 @@ export interface ProviderRequestOptions {
     readonly extra?: JsonObject;
     /** Provider-neutral JSON-schema structured output request. Requires model `capabilities.structuredOutput`. */
     readonly structuredOutput?: StructuredOutputOptions;
+    /** Opaque provider continuation cursor (e.g. OpenAI `previous_response_id`). When set,
+     *  the provider resumes from this cursor instead of re-sending full history. */
+    readonly continuation?: {
+        readonly cursor: string;
+    };
 }
 export interface ProviderRequest {
     readonly model: ModelConfig;
@@ -251,12 +267,17 @@ export type ProviderEvent = {
     readonly id?: string;
     readonly name?: string;
     readonly argumentsText?: string;
+    readonly authority?: ToolCallAuthority;
 } | {
     readonly type: "tool_call";
     readonly call: ToolCallContent;
 } | {
     readonly type: "usage";
     readonly usage: Usage;
+} | {
+    readonly type: "continuation_required";
+    readonly cursor: string;
+    readonly reason?: string;
 } | {
     readonly type: "done";
     readonly usage?: Usage;
@@ -269,6 +290,64 @@ export interface AIProvider {
     generate(request: ProviderRequest): AsyncIterable<ProviderEvent>;
 }
 export type ProviderResolver = (model: ModelConfig) => AIProvider | undefined;
+/** Realtime audio/session event. Realtime is a bidirectional session, not a request/response
+ *  stream, so it is a separate neutral seam from `AIProvider.generate()`. Credentials are
+ *  bound to the session handshake only and never appear in events. */
+export type RealtimeEvent = {
+    readonly type: "session_started";
+    readonly sessionId?: string;
+} | {
+    readonly type: "audio_delta";
+    readonly audio: Uint8Array;
+} | {
+    readonly type: "transcript_delta";
+    readonly text: string;
+    readonly role: "user" | "assistant";
+} | {
+    readonly type: "tool_call";
+    readonly call: ToolCallContent;
+} | {
+    readonly type: "interrupted";
+} | {
+    readonly type: "session_closed";
+    readonly reason?: string;
+} | {
+    readonly type: "error";
+    readonly error: ErrorInfo;
+};
+/** Neutral bidirectional realtime session seam. The provider owns the transport
+ *  (e.g. WebSocket); the host owns audio capture/playback and session lifecycle. */
+export interface RealtimeSession {
+    readonly id: string;
+    readonly provider: string;
+    /** Send an audio chunk (PCM/Opus; provider-specific format set at creation). */
+    sendAudio(chunk: Uint8Array, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Inbound events (audio out, transcripts, hosted tool calls, interruption, close, error). */
+    events(): AsyncIterable<RealtimeEvent>;
+    /** Request the provider stop the current response mid-stream. */
+    interrupt(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Close the session and release the transport. Idempotent. */
+    close(reason?: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Factory a provider exposes for realtime sessions; not part of `AIProvider`. */
+export type RealtimeSessionFactory = (options: RealtimeSessionOptions) => RealtimeSession;
+export interface RealtimeSessionOptions {
+    readonly model: ModelConfig;
+    readonly signal?: AbortSignal;
+    /** Provider-specific caps override; providers enforce finite defaults. */
+    readonly caps?: RealtimeCaps;
+}
+export interface RealtimeCaps {
+    readonly maxAudioEventsPerSecond?: number;
+    readonly maxBytesPerSecond?: number;
+    readonly maxWallMs?: number;
+}
 export type InputAssemblyLayout = "legacy" | "cache_aware";
 export interface RunOptions {
     readonly signal?: AbortSignal;
@@ -286,11 +365,21 @@ 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;
     readonly idempotencyKey?: string;
     readonly validate?: ToolValidator;
     readonly activeSkills?: readonly string[];
     readonly skills?: readonly Skill[];
+    /** Migration opt-in: activate every skill in a configured `SkillRegistry` when `activeSkills` / `skills` are unset. */
+    readonly activateAllSkills?: true;
+    /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
+    readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
     readonly instructionInjectors?: readonly InstructionInjector[];
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
@@ -338,6 +427,12 @@ export interface AgentConfig {
     readonly tools?: ToolRegistry | readonly ToolDefinition[];
     readonly context?: readonly ContextProvider[];
     readonly skills?: SkillRegistry | readonly Skill[];
+    /** Migration opt-in: activate every registry skill by default when run options do not narrow activation. */
+    readonly activateAllSkills?: true;
+    /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
+    readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -351,7 +446,11 @@ 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;
     readonly idempotencyKey?: string;
     readonly compaction?: false | CompactionOptions;
     readonly retry?: false | RetryOptions;
@@ -369,7 +468,7 @@ export interface AgentConfig {
     readonly secure?: true;
 }
 /** Opt-in fail-closed composition over the normal explicit AgentConfig API. */
-export interface SecureAgentOptions extends Omit<AgentConfig, "tools" | "validator" | "redactor" | "permission" | "trust" | "ownership" | "limits" | "runState" | "secure"> {
+export interface SecureAgentOptions extends Omit<AgentConfig, "tools" | "validator" | "redactor" | "permission" | "trust" | "ownership" | "identity" | "limits" | "runState" | "secure"> {
     readonly id: string;
     readonly tools: readonly ToolDefinition[];
     readonly toolArgumentValidator: import("./tools.js").ToolArgumentValidator;
@@ -377,6 +476,8 @@ export interface SecureAgentOptions extends Omit<AgentConfig, "tools" | "validat
     readonly permission: PermissionPolicy;
     readonly trust: TrustPolicy;
     readonly ownership: OwnershipScope;
+    /** Optional host-verified identity; when set must match `ownership`. */
+    readonly identity?: import("./identity.js").AgentIdentity;
     readonly limits: RunLimits;
     readonly definitionRevision: string;
     readonly runState: Omit<AgentRunStateOptions, "definitionRevision" | "interruptBeforeTool">;
@@ -407,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. */
@@ -423,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 {
@@ -439,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;
@@ -448,6 +684,12 @@ 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 {
+    readonly signal?: AbortSignal;
 }
 export interface AgentRunRef {
     readonly runId: string;
@@ -461,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;
@@ -493,6 +742,22 @@ export declare class AgentRunError extends Error {
         readonly cause?: unknown;
     });
 }
+/** Mid-run steer queue: default pending message count (fail closed at this cap). */
+export declare const DEFAULT_MAX_PENDING_STEERS = 8;
+/** Absolute pending steer count ceiling if hosts later expose overrides. */
+export declare const HARD_MAX_PENDING_STEERS = 32;
+/** Mid-run steer queue: default total UTF-8 byte budget across pending messages. */
+export declare const DEFAULT_MAX_PENDING_STEER_BYTES: number;
+/** Absolute pending steer byte ceiling if hosts later expose overrides. */
+export declare const HARD_MAX_PENDING_STEER_BYTES: number;
+export interface SteerOptions {
+    /**
+     * When true, abort the in-flight provider stream and continue the same run after
+     * injecting steered user text. Default false: inject before the next provider turn
+     * (after the current tool batch completes).
+     */
+    readonly softInterrupt?: boolean;
+}
 export interface AgentSession {
     readonly id: string;
     /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
@@ -500,6 +765,12 @@ export interface AgentSession {
     readonly leafId: string | undefined;
     run(input: string | Message | readonly Message[], options?: RunOptions): Promise<AgentRunResult>;
     prompt(input: string, options?: RunOptions): Promise<AgentRunResult>;
+    /**
+     * Enqueue user text into an active run. Default injects before the next provider turn.
+     * `softInterrupt: true` aborts the current provider stream, then continues the same run.
+     * Fails closed when no run is active or the pending queue exceeds caps.
+     */
+    steer(input: string | Message | readonly Message[], options?: SteerOptions): void;
     /** Subscribe first, then start exactly one run and yield only that run's events until it terminates. */
     stream(input: string | Message | readonly Message[], options?: RunOptions & SubscribeOptions): AsyncIterable<AgentEvent>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
@@ -641,6 +912,13 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly size: number;
+} | {
+    /** A steered message was dropped by a terminal input guardrail; the run continues without it. */
+    readonly type: "steer_rejected";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly message: Message;
+    readonly record: GuardrailRecord;
 } | {
     readonly type: "event_subscriber_overflow";
     readonly sessionId: string;
@@ -704,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 {
@@ -724,6 +1028,10 @@ export interface ToolExecutionContext {
     readonly toolCallId: string;
     readonly signal?: AbortSignal;
     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 {
@@ -734,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;
@@ -826,7 +1218,14 @@ export interface PromptBuildRequest {
     readonly messages: readonly Message[];
     readonly context?: readonly ContextBlock[];
     readonly skills?: readonly Skill[];
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    readonly loadedSkills?: import("./skill-disclosure.js").LoadedSkillSet;
+    /** Skills demoted to catalog-only by context budget this turn. */
+    readonly demotedSkillBodies?: readonly string[];
     readonly tools?: readonly ToolDefinition[];
+    /** Model being prompted; lets builders adapt composition to declared capabilities
+     *  (e.g. the default builder omits the `Available tools:` text for tool-capable models). */
+    readonly model?: ModelConfig;
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }
@@ -874,6 +1273,9 @@ export interface ExtensionEvent {
 export interface Extension {
     readonly name: string;
     setup(api: ExtensionAPI): void | Promise<void>;
+    /** Host-attested signature/digest for `ExtensionLoadPolicy.verifySignature`. */
+    readonly signature?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ProviderPackage {
     readonly name: string;
@@ -931,6 +1333,8 @@ export interface OAuthProvider {
     readonly id: string;
     login(callbacks?: OAuthLoginCallbacks): Promise<OAuthCredentials> | OAuthCredentials;
     refresh?(credentials: OAuthCredentials): Promise<OAuthCredentials> | OAuthCredentials;
+    /** Best-effort upstream revocation; the store delete is what fails closed locally. */
+    revoke?(credentials: OAuthCredentials): Promise<void> | void;
     getCredential?(credentials: OAuthCredentials): Promise<Credential | undefined> | Credential | undefined;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -1022,7 +1426,80 @@ export interface SessionStore {
      *  avoid `list(sessionId)` (full-session scan) + in-memory rebuild. Optional — the
      *  built-in memory/JSONL stores omit it and the runtime falls back to `list()`. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;
+    /**
+     * Optional bounded session search. Prefer implementing this **or** returning a companion
+     * `SessionIndex` from the adapter factory — hosts must not need both. Call
+     * `resolveSessionSearchQuery` before scan/query. Memory defaults to capped linear
+     * search (`sessionSearchMode: "unsupported"` throws). JSONL throws unsupported.
+     */
+    searchSessions?(query: SessionSearchQuery): Promise<PersistencePage<SessionSearchHit>>;
+}
+/** Host-written `SessionRecord.metadata` / session metadata key for workspace filtering. */
+export declare const SESSION_SEARCH_WORKSPACE_METADATA_KEY: "workspaceRoot";
+export declare const DEFAULT_SESSION_SEARCH_LIMIT = 20;
+export declare const HARD_MAX_SESSION_SEARCH_LIMIT = 100;
+export declare const DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES: number;
+export declare const HARD_MAX_SESSION_SEARCH_QUERY_BYTES: number;
+export declare const DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES = 512;
+export declare const HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES: number;
+export declare const DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES: number;
+export declare const HARD_MAX_SESSION_SEARCH_CURSOR_BYTES: number;
+export declare const DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS = 1000;
+export declare const HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS = 5000;
+export declare const DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES = 10000;
+export declare const HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES = 50000;
+export declare const DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES: number;
+export declare const HARD_MAX_SESSION_SEARCH_LINEAR_BYTES: number;
+export declare const DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES = 1000;
+export declare const HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES = 5000;
+/** Bounded session search filters. Workspace matches host-written `metadata.workspaceRoot`. */
+export interface SessionSearchQuery extends PersistenceQuery, OwnershipScope {
+    readonly workspaceRoot?: string;
+    /** Optional full-text / message+summary query (adapter-defined matching). */
+    readonly query?: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly label?: string;
+    readonly summary?: string;
+    readonly fromUpdatedAt?: string;
+    readonly toUpdatedAt?: string;
+    readonly signal?: AbortSignal;
 }
+/**
+ * Safe search hit for resume/checkout. Never includes credentials or raw full transcripts.
+ * `leafId` is the branch tip for `session.checkout` when known.
+ */
+export interface SessionSearchHit {
+    readonly sessionId: string;
+    readonly leafId?: string;
+    readonly updatedAt?: string;
+    readonly label?: string;
+    readonly summary?: string;
+    readonly snippet?: string;
+    /** Safe display fields only (e.g. workspaceRoot); never credentials. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Narrow search seam; adapters may implement this instead of `SessionStore.searchSessions`. */
+export interface SessionIndex {
+    search(query: SessionSearchQuery): Promise<PersistencePage<SessionSearchHit>>;
+}
+/** Validated search query with finite `limit` / `order` filled in. */
+export interface ResolvedSessionSearchQuery extends SessionSearchQuery {
+    readonly limit: number;
+    readonly order: "asc" | "desc";
+}
+/**
+ * O(1) validation before any scan/query. Applies default page limit; rejects NaN,
+ * non-positive limits, oversize query/cursor/filter strings, and invalid order.
+ */
+export declare function resolveSessionSearchQuery(query: SessionSearchQuery): ResolvedSessionSearchQuery;
+export declare const SESSION_SEARCH_UNSUPPORTED_CODE: "session_search_unsupported";
+/** Thrown when a store opts out of `searchSessions` (memory `unsupported`, JSONL). */
+export declare class SessionSearchUnsupportedError extends Error {
+    readonly code: "session_search_unsupported";
+    constructor(message?: string);
+}
+export declare function isSessionSearchUnsupported(error: unknown): error is SessionSearchUnsupportedError;
 /** Query for a single branch's ancestor chain (DB-friendly: one recursive/ancestor query
  *  instead of a full-session scan). Honored by `SessionStore.readBranchPath` and the pure
  *  branch helpers' reader overload. `leafId` is optional (omit for the latest leaf). */
@@ -1229,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;
@@ -1236,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 {
@@ -1383,16 +1914,21 @@ export interface MigrationRecord {
 }
 /** Query for sessions. */
 export interface SessionQuery extends PersistenceQuery, OwnershipScope {
+    readonly id?: string;
     readonly parentSessionId?: string;
     readonly agentDefinitionId?: string;
     readonly agentDefinitionVersion?: string;
     readonly retentionPolicyId?: string;
+    /** Match sessions whose `metadata` object contains this top-level key (e.g. conversation marker). */
+    readonly metadataKey?: string;
     readonly fromCreatedAt?: string;
     readonly toCreatedAt?: string;
     readonly fromUpdatedAt?: string;
     readonly toUpdatedAt?: string;
     readonly hasExpired?: boolean;
 }
+/** Validate a top-level `SessionRecord.metadata` key used by `SessionQuery.metadataKey` filters. */
+export declare function assertSessionMetadataKey(key: string): string;
 /** Query for session entries. */
 export interface SessionEntryQuery extends PersistenceQuery, OwnershipScope {
     readonly sessionId?: string;
@@ -1493,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>>;
@@ -1503,9 +2041,17 @@ export interface ProductionPersistenceStore {
     queryAgentDefinitions(query: AgentDefinitionQuery): Promise<PersistencePage<AgentDefinitionRecord>>;
     queryRetentionPolicies(query: RetentionPolicyQuery): Promise<PersistencePage<RetentionPolicy>>;
     queryMigrations(query: MigrationQuery): Promise<PersistencePage<MigrationRecord>>;
+    /** Optional session-record write capability (conversation threads, host-managed sessions).
+     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update. */
+    appendSession?(record: SessionRecord): Promise<void>;
     /** DB-friendly branch read (mirrors `SessionStore.readBranchPath`): one ancestor-chain
      *  query instead of `queryEntries({ sessionId })` + in-memory walk. Optional. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;
+    /**
+     * Optional Phase 8 retention / legal-hold / export / tenant-quota lifecycle.
+     * Prefer attaching `createMemoryPersistenceLifecycle()` or adapter-native methods.
+     */
+    readonly lifecycle?: import("./persistence-lifecycle.js").PersistenceLifecycleStore;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface CompactionStrategy {
@@ -1635,17 +2181,39 @@ 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;
     appendMessage(message: Message): Promise<void>;
     emit(event: AgentEvent): void;
+    /** True when mid-run steers are queued for the next provider turn. */
+    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";
@@ -1663,6 +2231,12 @@ export type AgentLoopOptions = {
     readonly structuredOutput?: StructuredOutputOptions;
     /** `native` maps schema to capable providers; `artifact-loop` keeps repair turns only. */
     readonly structuredOutputMode?: "native" | "artifact-loop";
+    /**
+     * When to attach native `structuredOutput` under `toolCalls: "bounded"`.
+     * `every-turn` (default): schema on every provider request (legacy).
+     * `final-turn-only`: tool-eligible turns omit schema; artifact/revision turns send schema and withdraw tools.
+     */
+    readonly structuredOutputTiming?: "every-turn" | "final-turn-only";
 };
 export interface ArtifactValidation {
     readonly ok: boolean;
@@ -1687,3 +2261,11 @@ export interface ArtifactParseResult<T> {
 export type ArtifactParser<T> = (text: string, ctx: ArtifactContext) => ArtifactParseResult<T> | Promise<ArtifactParseResult<T>>;
 export type ArtifactValidator<T> = (value: T, ctx: ArtifactContext) => ArtifactValidation | Promise<ArtifactValidation>;
 export type ArtifactRepairer<T> = (value: T | undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput | Promise<AgentInput>;
+/** Alias re-exports so `dist/contracts.d.ts` exposes implementer contract names. */
+export type AgentIdentity = import("./identity.js").AgentIdentity;
+export type Principal = import("./identity.js").Principal;
+export type IdentityVerifier = import("./identity.js").IdentityVerifier;
+export type PersistenceLifecycleStore = import("./persistence-lifecycle.js").PersistenceLifecycleStore;
+export type LegalHoldRecord = import("./persistence-lifecycle.js").LegalHoldRecord;
+export type TenantQuota = import("./persistence-lifecycle.js").TenantQuota;
+export type PersistenceResourceKind = import("./persistence-lifecycle.js").PersistenceResourceKind;