@arnilo/prism 0.0.1 → 0.0.2

package/dist/contracts.d.ts

@@ -1,7 +1,10 @@
+import type { AgentInput } from "./input.js";
 import type { ContributionRegistries } from "./contributions.js";
 import type { Middleware, MiddlewareHookName, MiddlewareRegistry } from "./middleware.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { PermissionPolicy } from "./security.js";
+import type { ManifestContributionDeclaration } from "./manifests.js";
+import type { ToolValidator } from "./tools.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
@@ -13,7 +16,7 @@ export interface ErrorInfo {
     readonly code?: string | number;
     readonly cause?: unknown;
 }
-export type ContentBlock = TextContent | ImageContent | ThinkingContent | ToolCallContent | ToolResultContent;
+export type ContentBlock = TextContent | ImageContent | ThinkingContent | ToolCallDeltaContent | ToolCallContent | ToolResultContent;
 export interface TextContent {
     readonly type: "text";
     readonly text: string;
@@ -29,6 +32,13 @@ export interface ThinkingContent {
     readonly text: string;
     readonly signature?: string;
 }
+export interface ToolCallDeltaContent {
+    readonly type: "tool_call_delta";
+    readonly index: number;
+    readonly id?: string;
+    readonly name?: string;
+    readonly argumentsText?: string;
+}
 export interface ToolCallContent {
     readonly type: "tool_call";
     readonly id: string;
@@ -55,6 +65,7 @@ export interface ModelConfig {
     readonly capabilities?: ModelCapabilities;
     readonly limits?: ModelLimits;
     readonly cost?: ModelCost;
+    readonly cache?: ModelCacheCapabilities;
     readonly compat?: JsonObject;
     readonly parameters?: Readonly<Record<string, unknown>>;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -88,13 +99,39 @@ export interface Usage {
     readonly currency?: string;
 }
 export type CacheRetention = "none" | "short" | "long";
+export type PromptCacheKind = "implicit" | "openai_key" | "cache_control" | "provider_specific" | "none";
+export interface ModelCacheCapabilities {
+    readonly kind?: PromptCacheKind;
+    readonly maxKeyLength?: number;
+    readonly maxBreakpoints?: number;
+    readonly minCacheableTokens?: number;
+    readonly longRetention?: boolean;
+}
+export type PromptCacheMode = "auto" | "on" | "off";
+export type PromptCacheBreakpointLocation = "system_prompt" | "tools" | "stable_context" | "last_stable_message" | "last_user_message" | "message_id";
+export type PromptCacheBreakpointTtl = "short" | "long";
+export interface PromptCacheBreakpoint {
+    readonly location: PromptCacheBreakpointLocation;
+    readonly messageId?: string;
+    readonly ttl?: PromptCacheBreakpointTtl;
+}
+export interface PromptCacheHints {
+    readonly mode?: PromptCacheMode;
+    readonly key?: string;
+    readonly retention?: CacheRetention;
+    readonly breakpoints?: readonly PromptCacheBreakpoint[];
+}
 export interface ProviderRequestOptions {
     readonly sessionId?: string;
     readonly cacheRetention?: CacheRetention;
     readonly cacheKey?: string;
+    readonly cache?: PromptCacheHints;
     readonly headers?: Readonly<Record<string, string>>;
+    /** @deprecated Provider-level timeout is inert in first-party providers; pass an AbortSignal/RunOptions.signal instead. */
     readonly timeoutMs?: number;
+    /** @deprecated Provider-level retry is inert in first-party providers; use AgentConfig.retry/RunOptions.retry instead. */
     readonly maxRetries?: number;
+    /** @deprecated Provider-level retry is inert in first-party providers; use AgentConfig.retry/RunOptions.retry instead. */
     readonly maxRetryDelayMs?: number;
     readonly compat?: JsonObject;
     readonly extra?: JsonObject;
@@ -137,9 +174,12 @@ export interface AIProvider {
     readonly id: string;
     generate(request: ProviderRequest): AsyncIterable<ProviderEvent>;
 }
+export type ProviderResolver = (model: ModelConfig) => AIProvider | undefined;
+export type InputAssemblyLayout = "legacy" | "cache_aware";
 export interface RunOptions {
     readonly signal?: AbortSignal;
     readonly model?: ModelConfig;
+    readonly providerSource?: ProviderResolver;
     readonly maxToolRounds?: number;
     readonly providerOptions?: ProviderRequestOptions;
     readonly providerRequestPolicies?: ProviderRequestPolicy | readonly ProviderRequestPolicy[];
@@ -148,12 +188,44 @@ export interface RunOptions {
     readonly retry?: false | RetryOptions;
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly redactor?: SecretRedactor;
+    readonly runLedger?: RunLedger;
+    readonly ownership?: OwnershipScope;
+    readonly idempotencyKey?: string;
+    readonly validate?: ToolValidator;
+    readonly activeSkills?: readonly string[];
+    readonly skills?: readonly Skill[];
+    readonly instructionInjectors?: readonly InstructionInjector[];
+    readonly inputLayout?: InputAssemblyLayout;
+    readonly loop?: AgentLoopStrategy | AgentLoopOptions;
 }
 export interface AgentDefinition {
     readonly name: string;
     readonly description?: string;
-    create(config?: AgentConfig): Promise<Agent> | Agent;
+    /** Direct model config, or a model id resolved from `registries.models`. */
+    readonly model?: ModelConfig | string;
+    /** Tool names to activate from the active tool registry / `registries.tools`. */
+    readonly tools?: readonly string[];
+    /** Skill names resolved through `resolveActiveSkills()`; `toolNames` enforcement applies. */
+    readonly skills?: readonly string[];
+    /** Context provider names from `registries.contextProviders`. */
+    readonly context?: readonly string[];
+    readonly systemPrompt?: SystemPromptConfig;
+    readonly instructions?: string;
+    readonly loop?: AgentLoopStrategy | AgentLoopOptions;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Optional escape hatch. When present, overrides declarative resolution. */
+    create?(config?: AgentConfig): Promise<Agent> | Agent;
+}
+/** Input to {@link resolveAgentDefinition}. All fields are optional; the host
+ *  controls scope by which registries it passes. */
+export interface AgentDefinitionResolutionContext {
+    readonly registries?: ContributionRegistries;
+    readonly providerSource?: ProviderResolver;
+    readonly tools?: ToolRegistry | readonly ToolDefinition[];
+    readonly skillsRegistry?: SkillRegistry;
+    /** Migration-only: omitted `tools`/`skills` activate every in-scope tool/skill. Defaults to fail-closed. */
+    readonly activateAllCapabilities?: true;
+    readonly overrides?: Partial<AgentConfig>;
 }
 export interface AgentConfig {
     readonly id?: string;
@@ -161,6 +233,7 @@ export interface AgentConfig {
     readonly instructions?: string;
     readonly model: ModelConfig;
     readonly provider?: AIProvider;
+    readonly providerSource?: ProviderResolver;
     readonly tools?: ToolRegistry | readonly ToolDefinition[];
     readonly context?: readonly ContextProvider[];
     readonly skills?: SkillRegistry | readonly Skill[];
@@ -168,18 +241,28 @@ export interface AgentConfig {
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
     readonly resourceLoader?: ResourceLoader;
+    /** Host-owned metadata only: createAgent/session.run do not load or run these extensions. */
     readonly extensions?: readonly Extension[];
     readonly store?: SessionStore;
+    /** Host-owned metadata only: createAgent/session.run do not read settings. */
     readonly settings?: SettingsProvider;
+    /** Host-owned metadata only: createAgent/session.run do not resolve credentials. Pass resolvers to provider edges explicitly. */
     readonly credentials?: CredentialResolver;
     readonly permission?: PermissionPolicy;
     readonly providerOptions?: ProviderRequestOptions;
     readonly providerRequestPolicies?: ProviderRequestPolicy | readonly ProviderRequestPolicy[];
     readonly systemPrompt?: SystemPromptConfig;
     readonly redactor?: SecretRedactor;
+    readonly runLedger?: RunLedger;
+    readonly ownership?: OwnershipScope;
+    readonly idempotencyKey?: string;
     readonly compaction?: false | CompactionOptions;
     readonly retry?: false | RetryOptions;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly validator?: ToolValidator;
+    readonly instructionInjectors?: readonly InstructionInjector[];
+    readonly inputLayout?: InputAssemblyLayout;
+    readonly loop?: AgentLoopStrategy | AgentLoopOptions;
 }
 export interface Agent {
     readonly config: AgentConfig;
@@ -199,12 +282,22 @@ export interface AgentSessionCloneOptions {
     readonly id?: string;
     readonly leafId?: string;
 }
+export type SubscriberOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
+export interface SubscribeOptions {
+    /** Maximum queued events for a subscriber that is not actively awaiting `next()`. Defaults to 1024. */
+    readonly maxQueuedEvents?: number;
+    /** What to do when `maxQueuedEvents` is reached. Defaults to `close`. */
+    readonly overflow?: SubscriberOverflowPolicy;
+}
 export interface AgentSession {
     readonly id: string;
+    /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
+     *  Undefined until the first entry lands (a fresh session with no history). */
+    readonly leafId: string | undefined;
     run(input: string | Message | readonly Message[], options?: RunOptions): Promise<void>;
     prompt(input: string, options?: RunOptions): Promise<void>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
-    subscribe(): AsyncIterable<AgentEvent>;
+    subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;
@@ -282,6 +375,13 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly size: number;
+} | {
+    readonly type: "event_subscriber_overflow";
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly droppedEvents: number;
+    readonly maxQueuedEvents: number;
+    readonly overflow: SubscriberOverflowPolicy;
 } | {
     readonly type: "compaction_started";
     readonly sessionId: string;
@@ -303,6 +403,40 @@ export type AgentEvent = {
     readonly sessionId?: string;
     readonly runId?: string;
     readonly error: ErrorInfo;
+} | {
+    readonly type: "artifact_validation_started";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly attempt: number;
+} | {
+    readonly type: "artifact_validation_finished";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly attempt: number;
+    readonly result: ArtifactValidation;
+} | {
+    readonly type: "artifact_revision_started";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly attempt: number;
+    readonly failure: ArtifactValidation;
+} | {
+    readonly type: "artifact_finished";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly attempt: number;
+    readonly result: ArtifactValidation;
+} | {
+    readonly type: "artifact_failed";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly attempt: number;
+    readonly result: ArtifactValidation;
 };
 export interface ToolDefinition {
     readonly name: string;
@@ -370,12 +504,44 @@ export interface ContextResolutionContext {
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }
+/** When an {@link InstructionInjector} contributes to the assembled provider input. */
+export type InstructionTiming = "first_turn" | "every_turn" | "on_input";
+/** Runtime turn scope handed to an {@link InstructionInjector}. Mirrors {@link LoopContext}
+ *  scope using already-redacted input/history so predicates cannot recover secrets. */
+export interface InstructionContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly input: readonly Message[];
+    readonly history: readonly Message[];
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+}
+/** Output of an {@link InstructionInjector}. Only `instructions` and `contextBlocks` are
+ *  honored; other fields grant nothing (no tools, skills, or permissions). */
+export interface InstructionContribution {
+    readonly instructions?: string;
+    readonly contextBlocks?: readonly ContextBlock[];
+    readonly when: InstructionTiming;
+    /** Used only when `when === "on_input"`; absent predicate means apply every turn. */
+    readonly predicate?: (ctx: InstructionContext) => boolean;
+}
+/** Additive instruction/context contribution that a package registers through
+ *  {@link ExtensionAPI.registerInstructionInjector} and the host selects on
+ *  {@link AgentConfig.instructionInjectors} / {@link RunOptions.instructionInjectors}.
+ *  Inert until selected; cannot grant privileges beyond text/context blocks. */
+export interface InstructionInjector {
+    readonly name: string;
+    readonly description?: string;
+    apply(ctx: InstructionContext): InstructionContribution;
+}
 export interface InputBuilder {
     readonly name: string;
     build(input: string | Message | readonly Message[], context?: InputBuildContext): Promise<readonly Message[]> | readonly Message[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface InputBuildContext {
+    readonly inputLayout?: InputAssemblyLayout;
     readonly sessionId?: string;
     readonly runId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -408,6 +574,25 @@ export interface SkillRegistry {
     resolve(name: string): Skill;
     list(): readonly Skill[];
 }
+/** Directory-name spelling for discovered contribution kinds. Maps to a
+ *  {@link ManifestContributionDeclaration} kind for non-skill kinds:
+ *  `context` → `contextProvider`, `instructions` → `systemPromptContribution`. */
+export type ContributionFileKind = "skill" | "tool" | "context" | "instructions";
+/** Inert envelope emitted by the host/CLI discovery scanner. Carries the
+ *  realized {@link Skill} for skill kinds and a manifest-referenced
+ *  {@link ManifestContributionDeclaration} for other kinds; the host owns
+ *  any executable behavior. Contains no code, no credential. */
+export interface DiscoveredContribution {
+    readonly kind: ContributionFileKind;
+    readonly name: string;
+    readonly origin: "global" | "workspace";
+    readonly path: string;
+    /** Present when `kind === "skill"`. */
+    readonly skill?: Skill;
+    /** Present for non-skill kinds. */
+    readonly declaration?: ManifestContributionDeclaration;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 export type ExtensionLifecycleEventName = "resource_discovery" | "session_start" | "session_shutdown" | "before_agent_start" | "turn" | "context" | "provider_request" | "tool_call" | "tool_result" | "compaction" | "retry";
 export interface ExtensionEvent {
     readonly type: ExtensionLifecycleEventName | "extension_error" | string;
@@ -534,13 +719,19 @@ export interface ExtensionAPI {
     registerAuthMethod(method: AuthMethod): void;
     registerProviderRequestPolicy(policy: ProviderRequestPolicy): void;
     registerSystemPromptContribution(contribution: SystemPromptContribution): void;
+    registerInstructionInjector(injector: InstructionInjector): void;
 }
+export type SessionEntryKind = "message" | "event" | "summary" | "metadata" | "model_change" | "label" | "custom" | "compaction";
+export declare const SESSION_ENTRY_KINDS: readonly SessionEntryKind[];
+export declare const SESSION_ENTRY_SCHEMA_VERSION = 1;
+export declare function isSessionEntryKind(value: unknown): value is SessionEntryKind;
 export interface SessionEntry {
     readonly id: string;
     readonly parentId?: string;
     readonly sessionId: string;
     readonly timestamp: string;
-    readonly kind: "message" | "event" | "summary" | "metadata" | "model_change" | "label" | "custom" | "compaction";
+    readonly kind: SessionEntryKind;
+    readonly schemaVersion?: 1;
     readonly runId?: string;
     readonly message?: Message;
     readonly event?: AgentEvent;
@@ -552,15 +743,341 @@ export interface SessionEntry {
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface SessionStore {
-    append(entry: SessionEntry): Promise<void>;
+    append(entry: SessionEntry, options?: SessionAppendOptions): Promise<void>;
     list(sessionId: string): Promise<readonly SessionEntry[]>;
     get?(id: string): Promise<SessionEntry | undefined>;
-}
+    /** DB-friendly branch read: return one branch's ancestor chain as a page so adapters
+     *  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>>;
+}
+/** 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). */
+export interface SessionBranchRead {
+    readonly sessionId: string;
+    readonly leafId?: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+/** Database-neutral callable returning one branch's ancestor chain as a page. Implementations
+ *  issue a single recursive CTE / ancestor walk; the pure helpers follow `nextCursor` to
+ *  completion. Returns redacted `SessionEntry` values only (stores already persist redacted
+ *  entries; the runtime redacts before append). */
+export type BranchReader = (query: SessionBranchRead) => Promise<PersistencePage<SessionEntry>>;
+/**
+ * Options for `SessionStore.append`. Stores that honor them reject dangling
+ * `expectedParentId` values and deduplicate exact retries by `idempotencyKey` +
+ * parent. Production stores may add stricter branch-tip CAS and report
+ * `currentLeafId` in `SessionAppendConflictError`. `idempotencyKey` is an opaque
+ * host string; stores redact it like metadata when persisted. Carries no
+ * credentials, credential resolvers, provider instances, or unredacted secrets.
+ */
+export interface SessionAppendOptions {
+    /** Parent entry the new entry should attach to. Must exist when provided. */
+    readonly expectedParentId?: string;
+    /** Opaque host idempotency key; exact retries for one parent deduplicate. */
+    readonly idempotencyKey?: string;
+}
+/**
+ * Durable pointer to a branch tip. One session may own many handles (one per
+ * leaf). `BranchRecord.leafEntryId` is the persistence-side equivalent.
+ */
+export interface SessionBranchHandle {
+    readonly sessionId: string;
+    readonly leafId: string;
+}
+/** Stable error code carried by `SessionAppendConflictError`. */
+export declare const SESSION_APPEND_CONFLICT_CODE: "session_append_conflict";
+/** Conflict details carried by `SessionAppendConflictError`. Carries no secrets. */
+export interface SessionAppendConflict {
+    readonly code: typeof SESSION_APPEND_CONFLICT_CODE;
+    readonly expectedParentId?: string;
+    readonly currentLeafId?: string;
+    readonly idempotencyDuplicate?: boolean;
+}
+/**
+ * Thrown when `SessionStore.append` rejects an entry under `SessionAppendOptions`
+ * (dangling/stale `expectedParentId`, stricter adapter CAS failure, or duplicate
+ * idempotency key for the same parent). Recognize via the stable `code` and
+ * `isSessionAppendConflict`, not message text.
+ */
+export declare class SessionAppendConflictError extends Error {
+    readonly conflict: SessionAppendConflict;
+    readonly code: "session_append_conflict";
+    constructor(conflict: SessionAppendConflict);
+}
+/** Type guard keyed off the stable `code` (works across bundles; not message text). */
+export declare function isSessionAppendConflict(error: unknown): error is SessionAppendConflictError;
 export interface StoreFactory {
     readonly name: string;
     create(config?: JsonObject): Promise<SessionStore> | SessionStore;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Ownership scope identifiers. Hosts may use these for multi-tenant isolation. */
+export interface OwnershipScope {
+    readonly tenantId?: string;
+    readonly accountId?: string;
+    readonly userId?: string;
+}
+/** Cursor-paginated result page. */
+export interface PersistencePage<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+    readonly total?: number;
+}
+/** Common query controls for cursor-based pagination. */
+export interface PersistenceQuery {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly order?: "asc" | "desc";
+}
+/** Stored session record. Does not include provider objects or credentials. */
+export interface SessionRecord extends OwnershipScope {
+    readonly id: string;
+    readonly parentSessionId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly expiresAt?: string;
+    readonly retentionPolicyId?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored branch handle / leaf pointer. The leaf is the current entry id for the branch. */
+export interface BranchRecord {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly name?: string;
+    readonly rootEntryId?: string;
+    readonly parentBranchId?: string;
+    /** Durable leaf entry id for this branch (the persistence-side branch tip). */
+    readonly leafEntryId?: string;
+    readonly createdAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "aborted";
+/** Stored run record. */
+export interface RunRecord extends OwnershipScope {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly branchId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly model?: ModelConfig;
+    readonly provider?: string;
+    readonly idempotencyKey?: string;
+    readonly status?: RunStatus;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    readonly abortReason?: string;
+    readonly error?: ErrorInfo;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export type AgentEventType = AgentEvent["type"];
+/** Stored agent event ledger row. The `event` payload should be redacted before storage when secrets are present. */
+export interface AgentEventRecord extends OwnershipScope {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly type: AgentEventType;
+    readonly timestamp: string;
+    readonly event: AgentEvent;
+    readonly redacted: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+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 {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly toolCallId: string;
+    readonly name: string;
+    readonly arguments: JsonObject;
+    readonly result?: ToolResult;
+    readonly status?: ToolCallStatus;
+    readonly reason?: string;
+    readonly progress?: unknown;
+    readonly progressMetadata?: Readonly<Record<string, unknown>>;
+    readonly progressAt?: string;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    readonly redacted: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored usage row. */
+export interface UsageRecord extends OwnershipScope {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly usage: Usage;
+    readonly recordedAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Host-implemented write-side ledger for runs, events, tool calls, and usage. */
+export interface RunLedger {
+    appendRun(record: RunRecord): Promise<void> | void;
+    appendEvent(record: AgentEventRecord): Promise<void> | void;
+    appendToolCall(record: ToolCallRecord): Promise<void> | void;
+    appendUsage(record: UsageRecord): Promise<void> | void;
+}
+/** Union of records that may be handed to a {@link RunLedger}. */
+export type RunLedgerRecord = RunRecord | AgentEventRecord | ToolCallRecord | UsageRecord;
+/** Stored agent definition version. Does not include provider credentials/resolvers/provider instances. */
+export interface AgentDefinitionRecord extends OwnershipScope {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly source?: string;
+    readonly agentDefinition: AgentDefinition;
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored retention policy. */
+export interface RetentionPolicy extends OwnershipScope {
+    readonly id: string;
+    readonly name?: string;
+    readonly maxAgeDays?: number;
+    readonly maxEntriesPerSession?: number;
+    readonly maxTotalBytes?: number;
+    readonly archiveStore?: string;
+    readonly appliedKinds?: readonly SessionEntryKind[];
+    readonly createdAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored migration record. */
+export interface MigrationRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly appliedAt: string;
+    readonly appliedBy?: string;
+    readonly checksum?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Query for sessions. */
+export interface SessionQuery extends PersistenceQuery, OwnershipScope {
+    readonly parentSessionId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly retentionPolicyId?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+    readonly fromUpdatedAt?: string;
+    readonly toUpdatedAt?: string;
+    readonly hasExpired?: boolean;
+}
+/** Query for session entries. */
+export interface SessionEntryQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly parentId?: string;
+    /** Filter to entries on the branch ending at this leaf id. */
+    readonly leafId?: string;
+    readonly kind?: SessionEntryKind | readonly SessionEntryKind[];
+    readonly fromTimestamp?: string;
+    readonly toTimestamp?: string;
+}
+/** Query for branch handles/leaves. */
+export interface BranchQuery extends PersistenceQuery {
+    readonly sessionId?: string;
+    readonly name?: string;
+    readonly parentBranchId?: string;
+    readonly hasLeaf?: boolean;
+}
+/** Query for runs. */
+export interface RunQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly branchId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly status?: RunStatus | readonly RunStatus[];
+    readonly fromStartedAt?: string;
+    readonly toStartedAt?: string;
+    readonly fromFinishedAt?: string;
+    readonly toFinishedAt?: string;
+    readonly isFinished?: boolean;
+}
+/** Query for agent event ledger rows. */
+export interface AgentEventQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly type?: AgentEventType | readonly AgentEventType[];
+    readonly fromTimestamp?: string;
+    readonly toTimestamp?: string;
+    readonly redacted?: boolean;
+}
+/** Query for tool-call rows. */
+export interface ToolCallQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly name?: string;
+    readonly status?: ToolCallStatus | readonly ToolCallStatus[];
+    readonly fromStartedAt?: string;
+    readonly toStartedAt?: string;
+    readonly fromFinishedAt?: string;
+    readonly toFinishedAt?: string;
+    readonly redacted?: boolean;
+}
+/** Query for usage rows. */
+export interface UsageQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly fromRecordedAt?: string;
+    readonly toRecordedAt?: string;
+}
+/** Query for agent definition versions. */
+export interface AgentDefinitionQuery extends PersistenceQuery, OwnershipScope {
+    readonly name?: string;
+    readonly version?: string;
+    readonly source?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+}
+/** Query for retention policies. */
+export interface RetentionPolicyQuery extends PersistenceQuery, OwnershipScope {
+    readonly name?: string;
+    readonly archiveStore?: string;
+}
+/** Query for migration records. */
+export interface MigrationQuery extends PersistenceQuery {
+    readonly name?: string;
+    readonly version?: string;
+    readonly fromAppliedAt?: string;
+    readonly toAppliedAt?: string;
+}
+/**
+ * Production database-neutral persistence store contract.
+ * Hosts implement this interface to provide durable, paginated storage
+ * for sessions, entries, runs, events, tool calls, usage, agent definitions,
+ * and migrations. No SQL client, ORM, host file storage, or network dependency is
+ * required by the contract.
+ */
+export interface ProductionPersistenceStore {
+    readonly name?: string;
+    querySessions(query: SessionQuery): Promise<PersistencePage<SessionRecord>>;
+    queryBranches(query: BranchQuery): Promise<PersistencePage<BranchRecord>>;
+    queryEntries(query: SessionEntryQuery): Promise<PersistencePage<SessionEntry>>;
+    queryRuns(query: RunQuery): Promise<PersistencePage<RunRecord>>;
+    queryEvents(query: AgentEventQuery): Promise<PersistencePage<AgentEventRecord>>;
+    queryToolCalls(query: ToolCallQuery): Promise<PersistencePage<ToolCallRecord>>;
+    queryUsage(query: UsageQuery): Promise<PersistencePage<UsageRecord>>;
+    queryAgentDefinitions(query: AgentDefinitionQuery): Promise<PersistencePage<AgentDefinitionRecord>>;
+    queryRetentionPolicies(query: RetentionPolicyQuery): Promise<PersistencePage<RetentionPolicy>>;
+    queryMigrations(query: MigrationQuery): Promise<PersistencePage<MigrationRecord>>;
+    /** 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>>;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 export interface CompactionStrategy {
     readonly name: string;
     compact(context: CompactionContext): Promise<CompactionResult> | CompactionResult;
@@ -668,3 +1185,61 @@ export interface CredentialResolverSource {
 export interface OAuthCredentialStore {
     set(provider: string, credentials: OAuthCredentials): void | Promise<void>;
 }
+export interface ProviderTurnResult {
+    readonly content: readonly ContentBlock[];
+    readonly calls: readonly ToolCallContent[];
+    readonly messageId?: string;
+    readonly started: boolean;
+    readonly usage?: Usage;
+}
+export interface LoopContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+    readonly history: Message[];
+    readonly input: AgentInput;
+    readonly inputMessages: readonly Message[];
+    readonly maxToolRounds: number;
+    assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
+    generate(request: ProviderRequest): Promise<ProviderTurnResult>;
+    dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
+    appendMessage(message: Message): Promise<void>;
+    emit(event: AgentEvent): void;
+}
+export interface AgentLoopStrategy {
+    readonly name: string;
+    run(ctx: LoopContext): Promise<Usage | undefined>;
+}
+export type AgentLoopOptions = {
+    readonly strategy: "single-shot";
+} | {
+    readonly strategy: "generate-validate-revise";
+    readonly validator: ArtifactValidator<unknown>;
+    readonly parser?: ArtifactParser<unknown>;
+    readonly repairer?: ArtifactRepairer<unknown>;
+    readonly maxRevisions?: number;
+};
+export interface ArtifactValidation {
+    readonly ok: boolean;
+    readonly errors?: readonly {
+        readonly path?: string;
+        readonly message: string;
+    }[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly signal: AbortSignal;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactParseResult<T> {
+    readonly ok: boolean;
+    readonly value?: T;
+    readonly error?: string;
+}
+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>;