@odla-ai/ai 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -90,6 +90,7 @@ interface OracleUsage {
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
 }
+/** A fresh zeroed usage tally (0 input/output tokens, no cache fields) — the seed for accumulation. */
 declare function emptyUsage(): OracleUsage;
 /** Accumulate `more` into `into`, in place. Cache fields sum when present. */
 declare function addUsage(into: OracleUsage, more: OracleUsage): void;
@@ -140,6 +141,12 @@ interface OracleRequest {
     /** Provider-specific escape hatch, passed through opaquely. Using it gives up
      *  portability across providers. */
     providerExtras?: Record<string, unknown>;
+    /** Cancel the provider request. Adapters pass this to the vendor SDK rather
+     * than limiting cancellation to local tool handlers. */
+    signal?: AbortSignal;
+    /** Absolute Unix timestamp in milliseconds. The SDK combines this deadline
+     * with `signal`; whichever fires first cancels the provider request. */
+    deadline?: number;
 }
 type OracleStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | "pause_turn" | "refusal" | "error";
 interface OracleResponse {
@@ -155,7 +162,7 @@ interface OracleResponse {
 
 /** The closed taxonomy of normalized error codes carried by every OdlaAIError
  *  and by the streaming `error` event. */
-type OracleErrorType = "invalid_request" | "auth" | "rate_limit" | "context_window" | "tool_input_invalid" | "capability_unsupported" | "config" | "provider_error";
+type OracleErrorType = "invalid_request" | "auth" | "rate_limit" | "context_window" | "cancelled" | "deadline_exceeded" | "tool_input_invalid" | "capability_unsupported" | "config" | "provider_error";
 /** The plain-data error shape used inside the streaming `error` event. */
 interface OracleErrorShape {
     code: OracleErrorType;
@@ -219,6 +226,29 @@ declare class InvalidRequestError extends OdlaAIError {
         cause?: unknown;
     });
 }
+/** A provider returned tool arguments that are malformed or do not satisfy the
+ * declared JSON Schema. Tool handlers are never invoked for this error. */
+declare class ToolInputError extends OdlaAIError {
+    readonly tool?: string;
+    constructor(message: string, opts?: {
+        tool?: string;
+        cause?: unknown;
+    });
+}
+/** The caller cancelled a request. This is not an upstream failure and should
+ * not be retried unless the caller explicitly starts a new operation. */
+declare class CancelledError extends OdlaAIError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+/** The request's absolute deadline elapsed. Callers may choose a new deadline,
+ * but should not classify this as a provider outage. */
+declare class DeadlineExceededError extends OdlaAIError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
 /** Any other upstream provider failure (5xx, transport, unexpected shape). */
 declare class ProviderError extends OdlaAIError {
     constructor(message: string, opts?: {
@@ -281,12 +311,19 @@ interface OracleErrorEvent {
     error: OracleErrorShape;
 }
 
+/** Type guard: narrows a content block to a `TextBlock` (`type: "text"`). */
 declare function isTextBlock(b: OracleContentBlock): b is TextBlock;
+/** Type guard: narrows a content block to an `ImageBlock` (`type: "image"`). */
 declare function isImageBlock(b: OracleContentBlock): b is ImageBlock;
+/** Type guard: narrows a content block to an `AudioBlock` (`type: "audio"`). */
 declare function isAudioBlock(b: OracleContentBlock): b is AudioBlock;
+/** Type guard: narrows a content block to a `DocumentBlock` (`type: "document"`). */
 declare function isDocumentBlock(b: OracleContentBlock): b is DocumentBlock;
+/** Type guard: narrows a content block to a `ToolUseBlock` (`type: "tool_use"`). */
 declare function isToolUseBlock(b: OracleContentBlock): b is ToolUseBlock;
+/** Type guard: narrows a content block to a `ToolResultBlock` (`type: "tool_result"`). */
 declare function isToolResultBlock(b: OracleContentBlock): b is ToolResultBlock;
+/** Type guard: narrows a content block to a `ThinkingBlock` (`type: "thinking"`). */
 declare function isThinkingBlock(b: OracleContentBlock): b is ThinkingBlock;
 /** Normalize a message's `content` (string shorthand or block array) to blocks. */
 declare function blocksOf(content: string | OracleContentBlock[]): OracleContentBlock[];
@@ -295,6 +332,20 @@ declare function extractText(content: OracleContentBlock[]): string;
 /** Collect every tool_use block from response or message content. */
 declare function extractToolUses(content: OracleContentBlock[]): ToolUseBlock[];
 
+/** One deterministic validation failure at a JSONPath-like location. */
+interface JsonSchemaIssue {
+    path: string;
+    message: string;
+}
+/** Complete supported-subset schema validation result; unknown keywords fail validation. */
+interface JsonSchemaValidation {
+    valid: boolean;
+    issues: JsonSchemaIssue[];
+}
+/** Validate a JSON-compatible value against the supported JSON Schema subset.
+ * Unknown or unsupported keywords are validation failures, not ignored hints. */
+declare function validateJsonSchema(schema: unknown, value: unknown): JsonSchemaValidation;
+
 /** The kind of model — chat/multimodal is the v1 focus; the others are modeled
  *  so embeddings, transcription, TTS, and image generation slot in later. */
 type ModelKind = "chat" | "embed" | "transcribe" | "tts" | "image";
@@ -342,10 +393,13 @@ declare function chatCapabilities(overrides?: Partial<Capabilities>): Capabiliti
  */
 declare function validateRequest(spec: ModelSpec, req: OracleRequest): void;
 
+/** Built-in Anthropic (Claude) catalog: one `ModelSpec` per model (canonical id, native id, capabilities, limits). */
 declare const ANTHROPIC_MODELS: ModelSpec[];
 
+/** Built-in OpenAI catalog: one `ModelSpec` per model (canonical id == native id, capabilities, context window). */
 declare const OPENAI_MODELS: ModelSpec[];
 
+/** Built-in Google (Gemini) catalog: one `ModelSpec` per model (canonical id == native id, capabilities, context window). */
 declare const GOOGLE_MODELS: ModelSpec[];
 
 /** Canonical id → spec. */
@@ -417,6 +471,8 @@ interface ExtractCall {
     user: string | OracleContentBlock[];
     tool: ExtractTool;
     maxTokens?: number;
+    signal?: AbortSignal;
+    deadline?: number;
 }
 /** A web-search-enabled call: the model searches and returns prose. */
 interface SearchCall {
@@ -424,6 +480,8 @@ interface SearchCall {
     system?: string | TextBlock[];
     user: string | OracleContentBlock[];
     maxTokens?: number;
+    signal?: AbortSignal;
+    deadline?: number;
 }
 interface Ai {
     /** The active model catalog. */
@@ -445,11 +503,23 @@ interface Ai {
 }
 /** The minimal inference surface the agent loop and eval harness depend on. */
 type Inference = Pick<Ai, "chat" | "stream" | "catalog">;
+/**
+ * Build the `Ai` facade (bring-your-own-keys). Resolves a canonical model id to
+ * its provider, supplies keys statically (`keys`) or dynamically (`resolveKey`),
+ * validates each request against the model's capabilities, and exposes
+ * `chat`/`stream`/`extract`/`search` plus the active `catalog`. Only the SDK of a
+ * provider you actually call is loaded (via the lazy provider registry).
+ */
 declare function init(opts?: InitOptions): Ai;
 
 /** Generate the `llms.txt` context document for a given model catalog. */
 declare function generateLlmsTxt(catalog?: Catalog): string;
 
+/**
+ * Resolve the adapter for a provider, lazy-`import()`ing its module (and only
+ * that provider's SDK) on first use and caching the instance per (provider, key)
+ * so repeated calls reuse one SDK client.
+ */
 declare function getProvider(id: ProviderId, apiKey: string): Promise<Provider>;
 /** Test seam: register a provider instance directly (used to inject mocks). */
 declare function registerProvider(id: ProviderId, apiKey: string, provider: Provider): void;
@@ -458,10 +528,11 @@ declare function clearProviderCache(): void;
 
 /** Map any provider error to an OdlaAIError, returning it (does not throw).
  *  Re-returns an OdlaAIError unchanged (already normalized). */
-declare function normalizeError(err: unknown, provider: ProviderId): OdlaAIError;
+declare function normalizeError(err: unknown, provider: ProviderId, signal?: AbortSignal): OdlaAIError;
 
 type TaintLabel = "web_untrusted" | "operator_pasted_untrusted" | "llm_inherited" | `tool_untrusted:${string}`;
 type TaintSet = Set<TaintLabel>;
+/** Build a `TaintSet` from labels — the CaMeL-style taint carried through a run and checked against each tool's allowlist. */
 declare function taint(...labels: TaintLabel[]): TaintSet;
 /** Raised when a tool's taint allowlist doesn't cover the conversation's taint. */
 declare class TaintError extends OdlaAIError {
@@ -572,8 +643,20 @@ interface AgentRunInput {
     /** Or an explicit list of messages (takes precedence when both are given). */
     messages?: OracleMessage[];
     signal?: AbortSignal;
-}
-type StoppedReason = "end_turn" | "max_steps" | "refusal";
+    /** Absolute Unix timestamp in milliseconds for model requests and tools. */
+    deadline?: number;
+    /** Run-wide limits. Token limits are evaluated after each provider response;
+     * output allowance also caps the next request's maxTokens. */
+    budget?: AgentRunBudget;
+}
+/** Run-wide limits: tool calls stop before effects; token usage stops later turns after provider reporting. */
+interface AgentRunBudget {
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    maxTotalTokens?: number;
+    maxToolCalls?: number;
+}
+type StoppedReason = "end_turn" | "max_steps" | "refusal" | "budget_exhausted";
 interface AgentRun {
     /** Concatenated text of the final assistant turn. */
     finalText: string;
@@ -589,6 +672,14 @@ interface AgentRun {
     toolCalls: ToolCallRecord[];
     stoppedReason: StoppedReason;
 }
+/**
+ * Run the tool-use agent loop: model turn → execute requested tools → model turn,
+ * until the model stops asking for tools (`end_turn`), refuses (`refusal`), or
+ * `persona.maxSteps` (default 8) is hit (`max_steps`). Composes the persona's
+ * skills into its tools/system prompt, enforces per-tool taint allowlists, and
+ * loads/appends `persona.memory` when set. Returns `{ finalText, response,
+ * messages, usage, steps, toolCalls, stoppedReason }`.
+ */
 declare function runAgent(inference: Inference, persona: Persona, input: AgentRunInput): Promise<AgentRun>;
 
 /** One evaluation case — an input plus whatever the grader needs to judge it. */
@@ -643,6 +734,12 @@ interface EvaluateOptions {
     /** Max cases run concurrently (default 5). */
     concurrency?: number;
 }
+/**
+ * Eval harness: run each case through a `persona` (agent loop) or a plain `model`
+ * chat, grade it with `grader`, and return an `EvalReport` (per-case results,
+ * pass/fail counts, passRate, summed usage). Cases run concurrently up to
+ * `concurrency` (default 5); throws if neither `persona` nor `model` is given.
+ */
 declare function evaluate(opts: EvaluateOptions): Promise<EvalReport>;
 
 /** Pass when trimmed output equals `case.expected` (stringified). */
@@ -888,6 +985,12 @@ interface OdlaDbMemoryOptions {
         conversation?: string;
     };
 }
+/**
+ * A `MemoryScope` backed by odla-db. `load()` replays a session's prior turns
+ * (ordered by `seq`); `append()` upserts new turns by natural key under a
+ * deterministic `mutationId`, so a retried run never duplicates. Takes an
+ * injected odla-db client — odla-ai keeps zero runtime dependency on @odla-ai/db.
+ */
 declare class OdlaDbMemory implements MemoryScope {
     private readonly db;
     private readonly sessionId;
@@ -928,6 +1031,12 @@ interface OdlaDbKeyResolverOptions {
     secretName?: (provider: ProviderId) => string;
     /** Cache resolved keys in memory (default true). */
     cache?: boolean;
+    /** Maximum age for a cached secret (default 60 seconds; 0 disables caching).
+     * This bounds provider-key rotation propagation in warm isolates. */
+    ttlMs?: number;
+    /** Version included in the cache key. Change it to invalidate a known key
+     * generation immediately without waiting for the TTL. */
+    cacheVersion?: string | ((provider: ProviderId) => string);
 }
 /** Build a KeyResolver that reads provider keys from odla-db secrets. A missing
  *  secret resolves to `undefined` (→ that provider is simply unavailable, and
@@ -951,6 +1060,8 @@ interface InitFromPlatformOptions {
      *  owned by this helper; `defaultModel` is used only when the platform
      *  config sets no model. */
     initOptions?: Omit<InitOptions, "resolveKey">;
+    /** Secret resolver cache controls. Defaults to a finite 60-second TTL. */
+    keyResolverOptions?: OdlaDbKeyResolverOptions;
 }
 interface PlatformAi {
     ai: Ai;
@@ -960,15 +1071,14 @@ interface PlatformAi {
 /** Drop all cached platform configs (tests, or to force an immediate refetch). */
 declare function clearPlatformAiCache(): void;
 /** Build an `Ai` from the app's platform registration: provider/model from
- *  public-config (cached ~60s), API key from the tenant's odla-db secrets at
- *  call time. On cache refresh the existing `Ai` (and its warm key-resolver
- *  cache) is reused unless provider/model changed. Note the first call's
- *  `db`/`initOptions` are captured for the cache entry's lifetime. */
+ * public-config (cached ~60s), API key from the supplied tenant's odla-db
+ * secrets at call time. Only public config is shared globally; every call
+ * builds a facade bound to its own `db` and init options. */
 declare function initFromPlatform(opts: InitFromPlatformOptions): Promise<PlatformAi>;
 
 type FetchLike = typeof fetch;
 interface ProvisionContext {
-    /** The odla-db worker URL — always human-supplied, never hardcoded. */
+    /** Platform origin exposing the proxied db operator routes, normally https://odla.ai. */
     endpoint: string;
     /** Operator `ADMIN_SECRET` or an `odla_dev_...` developer token (owns the app). */
     token: string;
@@ -1050,4 +1160,4 @@ interface EntityCrudSkillOptions {
 /** Build a CRUD Skill for one odla-db entity. */
 declare function entityCrudSkill(opts: EntityCrudSkillOptions): Skill;
 
-export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };
+export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunBudget, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, CancelledError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, DeadlineExceededError, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type JsonSchemaIssue, type JsonSchemaValidation, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, ToolInputError, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateJsonSchema, validateRequest };

package/dist/index.d.ts

@@ -90,6 +90,7 @@ interface OracleUsage {
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
 }
+/** A fresh zeroed usage tally (0 input/output tokens, no cache fields) — the seed for accumulation. */
 declare function emptyUsage(): OracleUsage;
 /** Accumulate `more` into `into`, in place. Cache fields sum when present. */
 declare function addUsage(into: OracleUsage, more: OracleUsage): void;
@@ -140,6 +141,12 @@ interface OracleRequest {
     /** Provider-specific escape hatch, passed through opaquely. Using it gives up
      *  portability across providers. */
     providerExtras?: Record<string, unknown>;
+    /** Cancel the provider request. Adapters pass this to the vendor SDK rather
+     * than limiting cancellation to local tool handlers. */
+    signal?: AbortSignal;
+    /** Absolute Unix timestamp in milliseconds. The SDK combines this deadline
+     * with `signal`; whichever fires first cancels the provider request. */
+    deadline?: number;
 }
 type OracleStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | "pause_turn" | "refusal" | "error";
 interface OracleResponse {
@@ -155,7 +162,7 @@ interface OracleResponse {
 
 /** The closed taxonomy of normalized error codes carried by every OdlaAIError
  *  and by the streaming `error` event. */
-type OracleErrorType = "invalid_request" | "auth" | "rate_limit" | "context_window" | "tool_input_invalid" | "capability_unsupported" | "config" | "provider_error";
+type OracleErrorType = "invalid_request" | "auth" | "rate_limit" | "context_window" | "cancelled" | "deadline_exceeded" | "tool_input_invalid" | "capability_unsupported" | "config" | "provider_error";
 /** The plain-data error shape used inside the streaming `error` event. */
 interface OracleErrorShape {
     code: OracleErrorType;
@@ -219,6 +226,29 @@ declare class InvalidRequestError extends OdlaAIError {
         cause?: unknown;
     });
 }
+/** A provider returned tool arguments that are malformed or do not satisfy the
+ * declared JSON Schema. Tool handlers are never invoked for this error. */
+declare class ToolInputError extends OdlaAIError {
+    readonly tool?: string;
+    constructor(message: string, opts?: {
+        tool?: string;
+        cause?: unknown;
+    });
+}
+/** The caller cancelled a request. This is not an upstream failure and should
+ * not be retried unless the caller explicitly starts a new operation. */
+declare class CancelledError extends OdlaAIError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+/** The request's absolute deadline elapsed. Callers may choose a new deadline,
+ * but should not classify this as a provider outage. */
+declare class DeadlineExceededError extends OdlaAIError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
 /** Any other upstream provider failure (5xx, transport, unexpected shape). */
 declare class ProviderError extends OdlaAIError {
     constructor(message: string, opts?: {
@@ -281,12 +311,19 @@ interface OracleErrorEvent {
     error: OracleErrorShape;
 }
 
+/** Type guard: narrows a content block to a `TextBlock` (`type: "text"`). */
 declare function isTextBlock(b: OracleContentBlock): b is TextBlock;
+/** Type guard: narrows a content block to an `ImageBlock` (`type: "image"`). */
 declare function isImageBlock(b: OracleContentBlock): b is ImageBlock;
+/** Type guard: narrows a content block to an `AudioBlock` (`type: "audio"`). */
 declare function isAudioBlock(b: OracleContentBlock): b is AudioBlock;
+/** Type guard: narrows a content block to a `DocumentBlock` (`type: "document"`). */
 declare function isDocumentBlock(b: OracleContentBlock): b is DocumentBlock;
+/** Type guard: narrows a content block to a `ToolUseBlock` (`type: "tool_use"`). */
 declare function isToolUseBlock(b: OracleContentBlock): b is ToolUseBlock;
+/** Type guard: narrows a content block to a `ToolResultBlock` (`type: "tool_result"`). */
 declare function isToolResultBlock(b: OracleContentBlock): b is ToolResultBlock;
+/** Type guard: narrows a content block to a `ThinkingBlock` (`type: "thinking"`). */
 declare function isThinkingBlock(b: OracleContentBlock): b is ThinkingBlock;
 /** Normalize a message's `content` (string shorthand or block array) to blocks. */
 declare function blocksOf(content: string | OracleContentBlock[]): OracleContentBlock[];
@@ -295,6 +332,20 @@ declare function extractText(content: OracleContentBlock[]): string;
 /** Collect every tool_use block from response or message content. */
 declare function extractToolUses(content: OracleContentBlock[]): ToolUseBlock[];
 
+/** One deterministic validation failure at a JSONPath-like location. */
+interface JsonSchemaIssue {
+    path: string;
+    message: string;
+}
+/** Complete supported-subset schema validation result; unknown keywords fail validation. */
+interface JsonSchemaValidation {
+    valid: boolean;
+    issues: JsonSchemaIssue[];
+}
+/** Validate a JSON-compatible value against the supported JSON Schema subset.
+ * Unknown or unsupported keywords are validation failures, not ignored hints. */
+declare function validateJsonSchema(schema: unknown, value: unknown): JsonSchemaValidation;
+
 /** The kind of model — chat/multimodal is the v1 focus; the others are modeled
  *  so embeddings, transcription, TTS, and image generation slot in later. */
 type ModelKind = "chat" | "embed" | "transcribe" | "tts" | "image";
@@ -342,10 +393,13 @@ declare function chatCapabilities(overrides?: Partial<Capabilities>): Capabiliti
  */
 declare function validateRequest(spec: ModelSpec, req: OracleRequest): void;
 
+/** Built-in Anthropic (Claude) catalog: one `ModelSpec` per model (canonical id, native id, capabilities, limits). */
 declare const ANTHROPIC_MODELS: ModelSpec[];
 
+/** Built-in OpenAI catalog: one `ModelSpec` per model (canonical id == native id, capabilities, context window). */
 declare const OPENAI_MODELS: ModelSpec[];
 
+/** Built-in Google (Gemini) catalog: one `ModelSpec` per model (canonical id == native id, capabilities, context window). */
 declare const GOOGLE_MODELS: ModelSpec[];
 
 /** Canonical id → spec. */
@@ -417,6 +471,8 @@ interface ExtractCall {
     user: string | OracleContentBlock[];
     tool: ExtractTool;
     maxTokens?: number;
+    signal?: AbortSignal;
+    deadline?: number;
 }
 /** A web-search-enabled call: the model searches and returns prose. */
 interface SearchCall {
@@ -424,6 +480,8 @@ interface SearchCall {
     system?: string | TextBlock[];
     user: string | OracleContentBlock[];
     maxTokens?: number;
+    signal?: AbortSignal;
+    deadline?: number;
 }
 interface Ai {
     /** The active model catalog. */
@@ -445,11 +503,23 @@ interface Ai {
 }
 /** The minimal inference surface the agent loop and eval harness depend on. */
 type Inference = Pick<Ai, "chat" | "stream" | "catalog">;
+/**
+ * Build the `Ai` facade (bring-your-own-keys). Resolves a canonical model id to
+ * its provider, supplies keys statically (`keys`) or dynamically (`resolveKey`),
+ * validates each request against the model's capabilities, and exposes
+ * `chat`/`stream`/`extract`/`search` plus the active `catalog`. Only the SDK of a
+ * provider you actually call is loaded (via the lazy provider registry).
+ */
 declare function init(opts?: InitOptions): Ai;
 
 /** Generate the `llms.txt` context document for a given model catalog. */
 declare function generateLlmsTxt(catalog?: Catalog): string;
 
+/**
+ * Resolve the adapter for a provider, lazy-`import()`ing its module (and only
+ * that provider's SDK) on first use and caching the instance per (provider, key)
+ * so repeated calls reuse one SDK client.
+ */
 declare function getProvider(id: ProviderId, apiKey: string): Promise<Provider>;
 /** Test seam: register a provider instance directly (used to inject mocks). */
 declare function registerProvider(id: ProviderId, apiKey: string, provider: Provider): void;
@@ -458,10 +528,11 @@ declare function clearProviderCache(): void;
 
 /** Map any provider error to an OdlaAIError, returning it (does not throw).
  *  Re-returns an OdlaAIError unchanged (already normalized). */
-declare function normalizeError(err: unknown, provider: ProviderId): OdlaAIError;
+declare function normalizeError(err: unknown, provider: ProviderId, signal?: AbortSignal): OdlaAIError;
 
 type TaintLabel = "web_untrusted" | "operator_pasted_untrusted" | "llm_inherited" | `tool_untrusted:${string}`;
 type TaintSet = Set<TaintLabel>;
+/** Build a `TaintSet` from labels — the CaMeL-style taint carried through a run and checked against each tool's allowlist. */
 declare function taint(...labels: TaintLabel[]): TaintSet;
 /** Raised when a tool's taint allowlist doesn't cover the conversation's taint. */
 declare class TaintError extends OdlaAIError {
@@ -572,8 +643,20 @@ interface AgentRunInput {
     /** Or an explicit list of messages (takes precedence when both are given). */
     messages?: OracleMessage[];
     signal?: AbortSignal;
-}
-type StoppedReason = "end_turn" | "max_steps" | "refusal";
+    /** Absolute Unix timestamp in milliseconds for model requests and tools. */
+    deadline?: number;
+    /** Run-wide limits. Token limits are evaluated after each provider response;
+     * output allowance also caps the next request's maxTokens. */
+    budget?: AgentRunBudget;
+}
+/** Run-wide limits: tool calls stop before effects; token usage stops later turns after provider reporting. */
+interface AgentRunBudget {
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    maxTotalTokens?: number;
+    maxToolCalls?: number;
+}
+type StoppedReason = "end_turn" | "max_steps" | "refusal" | "budget_exhausted";
 interface AgentRun {
     /** Concatenated text of the final assistant turn. */
     finalText: string;
@@ -589,6 +672,14 @@ interface AgentRun {
     toolCalls: ToolCallRecord[];
     stoppedReason: StoppedReason;
 }
+/**
+ * Run the tool-use agent loop: model turn → execute requested tools → model turn,
+ * until the model stops asking for tools (`end_turn`), refuses (`refusal`), or
+ * `persona.maxSteps` (default 8) is hit (`max_steps`). Composes the persona's
+ * skills into its tools/system prompt, enforces per-tool taint allowlists, and
+ * loads/appends `persona.memory` when set. Returns `{ finalText, response,
+ * messages, usage, steps, toolCalls, stoppedReason }`.
+ */
 declare function runAgent(inference: Inference, persona: Persona, input: AgentRunInput): Promise<AgentRun>;
 
 /** One evaluation case — an input plus whatever the grader needs to judge it. */
@@ -643,6 +734,12 @@ interface EvaluateOptions {
     /** Max cases run concurrently (default 5). */
     concurrency?: number;
 }
+/**
+ * Eval harness: run each case through a `persona` (agent loop) or a plain `model`
+ * chat, grade it with `grader`, and return an `EvalReport` (per-case results,
+ * pass/fail counts, passRate, summed usage). Cases run concurrently up to
+ * `concurrency` (default 5); throws if neither `persona` nor `model` is given.
+ */
 declare function evaluate(opts: EvaluateOptions): Promise<EvalReport>;
 
 /** Pass when trimmed output equals `case.expected` (stringified). */
@@ -888,6 +985,12 @@ interface OdlaDbMemoryOptions {
         conversation?: string;
     };
 }
+/**
+ * A `MemoryScope` backed by odla-db. `load()` replays a session's prior turns
+ * (ordered by `seq`); `append()` upserts new turns by natural key under a
+ * deterministic `mutationId`, so a retried run never duplicates. Takes an
+ * injected odla-db client — odla-ai keeps zero runtime dependency on @odla-ai/db.
+ */
 declare class OdlaDbMemory implements MemoryScope {
     private readonly db;
     private readonly sessionId;
@@ -928,6 +1031,12 @@ interface OdlaDbKeyResolverOptions {
     secretName?: (provider: ProviderId) => string;
     /** Cache resolved keys in memory (default true). */
     cache?: boolean;
+    /** Maximum age for a cached secret (default 60 seconds; 0 disables caching).
+     * This bounds provider-key rotation propagation in warm isolates. */
+    ttlMs?: number;
+    /** Version included in the cache key. Change it to invalidate a known key
+     * generation immediately without waiting for the TTL. */
+    cacheVersion?: string | ((provider: ProviderId) => string);
 }
 /** Build a KeyResolver that reads provider keys from odla-db secrets. A missing
  *  secret resolves to `undefined` (→ that provider is simply unavailable, and
@@ -951,6 +1060,8 @@ interface InitFromPlatformOptions {
      *  owned by this helper; `defaultModel` is used only when the platform
      *  config sets no model. */
     initOptions?: Omit<InitOptions, "resolveKey">;
+    /** Secret resolver cache controls. Defaults to a finite 60-second TTL. */
+    keyResolverOptions?: OdlaDbKeyResolverOptions;
 }
 interface PlatformAi {
     ai: Ai;
@@ -960,15 +1071,14 @@ interface PlatformAi {
 /** Drop all cached platform configs (tests, or to force an immediate refetch). */
 declare function clearPlatformAiCache(): void;
 /** Build an `Ai` from the app's platform registration: provider/model from
- *  public-config (cached ~60s), API key from the tenant's odla-db secrets at
- *  call time. On cache refresh the existing `Ai` (and its warm key-resolver
- *  cache) is reused unless provider/model changed. Note the first call's
- *  `db`/`initOptions` are captured for the cache entry's lifetime. */
+ * public-config (cached ~60s), API key from the supplied tenant's odla-db
+ * secrets at call time. Only public config is shared globally; every call
+ * builds a facade bound to its own `db` and init options. */
 declare function initFromPlatform(opts: InitFromPlatformOptions): Promise<PlatformAi>;
 
 type FetchLike = typeof fetch;
 interface ProvisionContext {
-    /** The odla-db worker URL — always human-supplied, never hardcoded. */
+    /** Platform origin exposing the proxied db operator routes, normally https://odla.ai. */
     endpoint: string;
     /** Operator `ADMIN_SECRET` or an `odla_dev_...` developer token (owns the app). */
     token: string;
@@ -1050,4 +1160,4 @@ interface EntityCrudSkillOptions {
 /** Build a CRUD Skill for one odla-db entity. */
 declare function entityCrudSkill(opts: EntityCrudSkillOptions): Skill;
 
-export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };
+export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunBudget, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, CancelledError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, DeadlineExceededError, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type JsonSchemaIssue, type JsonSchemaValidation, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, ToolInputError, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateJsonSchema, validateRequest };