@elevasis/sdk 1.42.0 → 1.43.0

package/dist/node/index.d.ts

@@ -289,16 +289,12 @@ type OpenAIModel = 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5.4-nano';
  * Supported OpenRouter models (explicit union for type safety)
  */
 type OpenRouterModel = 'openrouter/z-ai/glm-5';
-/**
- * Supported Google models (direct SDK access)
- */
-type GoogleModel = 'gemini-3-flash-preview' | 'gemini-3.1-flash-lite-preview';
 /**
  * Supported Anthropic models (direct SDK access via @anthropic-ai/sdk)
  */
 type AnthropicModel = 'claude-opus-5' | 'claude-sonnet-5' | 'claude-haiku-4-5-20251001' | 'claude-haiku-4-5';
 /** Supported LLM models */
-type LLMModel = OpenAIModel | OpenRouterModel | GoogleModel | AnthropicModel | 'mock';
+type LLMModel = OpenAIModel | OpenRouterModel | AnthropicModel | 'mock';
 /**
  * GPT-5 model options schema
  */
@@ -325,18 +321,6 @@ declare const OpenRouterOptionsSchema: z.ZodObject<{
         fallback: "fallback";
     }>>;
 }, z.core.$strip>;
-/**
- * Google model options schema
- * Gemini 3 specific options for thinking depth control
- */
-declare const GoogleOptionsSchema: z.ZodObject<{
-    thinkingLevel: z.ZodOptional<z.ZodEnum<{
-        minimal: "minimal";
-        low: "low";
-        medium: "medium";
-        high: "high";
-    }>>;
-}, z.core.$strip>;
 /**
  * Anthropic model options schema
  * Currently empty - future options must be added per supported model family
@@ -348,16 +332,15 @@ declare const AnthropicOptionsSchema: z.ZodObject<{}, z.core.$strict>;
 type GPT5Options = z.infer<typeof GPT5OptionsSchema>;
 type MockOptions = Record<string, never>;
 type OpenRouterOptions = z.infer<typeof OpenRouterOptionsSchema>;
-type GoogleOptions = z.infer<typeof GoogleOptionsSchema>;
 type AnthropicOptions = z.infer<typeof AnthropicOptionsSchema>;
-type ModelSpecificOptions = GPT5Options | MockOptions | OpenRouterOptions | GoogleOptions | AnthropicOptions;
+type ModelSpecificOptions = GPT5Options | MockOptions | OpenRouterOptions | AnthropicOptions;
 /**
  * Model configuration for LLM execution
  * Belongs in resource definition (AgentDefinition, WorkflowDefinition, etc.)
  */
 interface ModelConfig {
     model: LLMModel;
-    provider: 'openai' | 'anthropic' | 'openrouter' | 'google' | 'mock';
+    provider: 'openai' | 'anthropic' | 'openrouter' | 'mock';
     apiKey: string;
     temperature?: number;
     /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
@@ -372,14 +355,70 @@ interface ModelConfig {
     modelOptions?: ModelSpecificOptions;
 }
 
+/**
+ * Types for the schema compiler. `compile.ts` walks a `JsonSchema` once, driven entirely by a
+ * `ProviderDialect`, and every server adapter compiles through it.
+ */
 /**
  * What happened to `strict` on a request, recorded per call rather than inferred.
  *
- * `applied` and `notAttempted` are the two states that a refusal-only field cannot tell apart —
+ * `applied` and `notAttempted` are the two states that a refusal-only field cannot tell apart --
  * both leave `strictRefusalReasons` empty. Recording the verdict positively is what makes "was
  * this agent's output actually enforced?" answerable from an `ai_calls` row.
  */
 type StrictStatus = 'applied' | 'refused' | 'compileRejected' | 'notAttempted';
+/**
+ * A JSON Schema node, typed enough to be useful without pretending to validate the spec.
+ *
+ * The compiler has to accept schemas that arrive OUTSIDE the strict subset (that is the whole
+ * point of a dialect that can refuse or rewrite them) as well as the `$ref`/`$defs`/`const`/
+ * `$schema` shapes the strict subset has no vocabulary for at all. The index signature exists
+ * because tenant schemas carry keywords (`minLength`, `pattern`, `minimum`, ...) this compiler
+ * drops or refuses on, and they still need somewhere to type-check while they pass through
+ * `Object.entries`.
+ */
+interface JsonSchema {
+    type?: string | string[];
+    /**
+     * The value is `JsonSchema | undefined`, not `JsonSchema`, because a property really can be
+     * declared with nothing describing it. `buildIterationResponseSchema` emits one per tool as
+     * `input: tool.inputSchema`, and `ToolDefinition.inputSchema` is typed `unknown` -- a tool
+     * deployed without one puts `undefined` under a key that exists.
+     *
+     * Both readers already handle it: `compileSchema` passes each value through `convertNode`, which
+     * takes `unknown`, and `collectErrors` opens with `if (!schema || typeof schema !== 'object')`
+     * above a comment naming this exact case. Declaring the value non-optional only hid that they
+     * were right to.
+     */
+    properties?: Record<string, JsonSchema | undefined>;
+    items?: JsonSchema;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    format?: string;
+    enum?: unknown[];
+    const?: unknown;
+    description?: string;
+    default?: unknown;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
+    $schema?: string;
+    $id?: string;
+    $anchor?: string;
+    /**
+     * OpenAPI's nullability spelling, which is not JSON Schema's. It is declared because
+     * `response-schema-validator.ts` READS it (`schemaPermitsNull`) -- Google's schema dialect is
+     * OpenAPI-derived, so a schema that reaches the validator can carry it. No dialect in `compile.ts`
+     * writes or rewrites it; the canonical spelling this compiler emits is `type: ['x', 'null']`.
+     */
+    nullable?: boolean;
+    [key: string]: unknown;
+}
 
 declare const ResourceGovernanceStatusSchema: z.ZodEnum<{
     active: "active";
@@ -923,16 +962,86 @@ interface LLMMessage {
  */
 interface LLMGenerateRequest {
     messages: LLMMessage[];
-    responseSchema: unknown;
+    /**
+     * JSON Schema for structured output. Omit it for an unstructured call.
+     *
+     * Absence is what turns validation off: `runGeneratePipeline` skips `validateResponseSchema`
+     * entirely when this is missing, whatever `validationSchema` holds.
+     *
+     * This was declared `responseSchema: unknown` -- required, and typed as nothing. `unknown` admits
+     * `undefined`, so "required" only ever forced the KEY to be written, and `createLLMCallTool`
+     * writes it as `undefined` on every call where the model supplies no usable schema. There was no
+     * type error available for that, and three separate layers re-derived the same nullability at
+     * runtime under three different rules -- truthiness in the pipeline, an object check in the
+     * validator, and a `'type'`-key check in the tool. Because the pipeline's was truthiness, `null`,
+     * `0` and `''` all quietly meant "no structured output" while the type insisted a schema was
+     * mandatory. Optional-and-typed is what those three were compensating for.
+     */
+    responseSchema?: JsonSchema;
     /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
     maxOutputTokens?: number;
     temperature?: number;
     topP?: number;
     signal?: AbortSignal;
+    /**
+     * Caller-supplied acceptance step (Wave D2b / decision A15). A pipeline-aware adapter
+     * (`UniversalLLMAdapter`, via `runGeneratePipeline`) runs this once per retry attempt, right
+     * after the response has passed `responseSchema` validation. Throw to reject the attempt --
+     * rejection is classified exactly like a thrown `LLMResponseParseError` from
+     * `validateResponseSchema`: retryable, no circuit-breaker verdict, and the attempt is recorded as
+     * a failure (`ai_calls` validation-failure row) rather than a clean success. Returning normally
+     * (including `undefined`) accepts the response.
+     *
+     * Optional, and a HINT rather than a dependency -- an adapter that does not read this field
+     * simply ignores it, so a caller must not assume it ran:
+     * - A bare test-stub `LLMAdapter` (many exist in this codebase) does not invoke it.
+     * - `PostMessageLLMAdapter` (`packages/sdk/src/worker/llm-adapter.ts`) cannot forward it at all --
+     *   functions cannot be structured-cloned across the worker `postMessage` boundary, so its
+     *   `params` object is built from an explicit allowlist that omits `accept`. The field is dropped
+     *   before `postMessage` is ever called (no `DataCloneError`), and the parent-side handler that
+     *   fulfils the call (`tool-dispatcher.ts`'s `case 'llm'`) rebuilds its own `LLMGenerateRequest`
+     *   from that allowlisted payload, so there is nothing to forward even in principle. This is the
+     *   path every deployed org-bundle agent and the `command-center-assistant` static module run
+     *   through today -- `accept` does not reach their retry loop.
+     *
+     * This is not a validation mechanism on its own: it does not decide whether output is acceptable,
+     * the caller's function does, by throwing or not. `callLLMForAgentIteration`
+     * (`execution/engine/agent/reasoning/adapters/agent-adapter-helpers.ts`) passes its Zod parse of
+     * the iteration response as this field, so a malformed-but-schema-valid iteration is re-sampled
+     * inside the retry loop instead of losing the turn -- for the in-process callers that can see it.
+     */
+    accept?: (output: unknown) => void;
+    /**
+     * The schema the RESPONSE is validated against, when that must differ from the schema the
+     * provider was asked to sample against. Defaults to `responseSchema` when omitted.
+     *
+     * **This does not affect what is sent to the provider.** `responseSchema` remains the only schema
+     * an adapter puts on the wire; this one is read solely by `runGeneratePipeline`'s validation step.
+     * Whether validation happens at all is still decided by `responseSchema` -- a request with no
+     * `responseSchema` is unstructured and stays unvalidated, whatever this field holds.
+     *
+     * A caller may legitimately ACCEPT A SUPERSET of what it ASKS FOR -- a document that validates a
+     * response more leniently than the one the provider was asked to sample against. No caller in this
+     * codebase supplies one today (agent iterations validate with a single Zod parse instead, see
+     * `agent-adapter-helpers.ts`), but the mechanism stays: `validateResponseSchema` does not descend
+     * into `anyOf`/`oneOf` regardless of which document is supplied here, so this field only ever
+     * changes which top-level/required/type keywords are checked, never which acceptance contract a
+     * union is read as.
+     *
+     * Unlike `accept` above, this is DATA. It is structured-cloneable, so it survives the worker
+     * `postMessage` boundary that drops `accept`: `PostMessageLLMAdapter` forwards it in its params
+     * allowlist and `tool-dispatcher.ts`'s `case 'llm'` puts it back on the `LLMGenerateRequest` it
+     * rebuilds parent-side. That is why a divergence expressible as a schema belongs here rather than
+     * in a callback -- deployed org-bundle agents run on the far side of that boundary.
+     */
+    validationSchema?: JsonSchema;
 }
 /**
  * Generic LLM generation response
- * Usage field is internal-only (stripped by UniversalLLMAdapter wrapper)
+ * `usage`, `cost`, `strictStatus` and `strictRefusalReasons` are observability fields. They are
+ * **read** by `UniversalLLMAdapter` and lifted onto the `ai_calls` row; they are **not removed**.
+ * The wrapper returns the base adapter's response object as-is, so a caller can observe all four.
+ * Earlier revisions of this file claimed they were stripped — they never were.
  */
 interface LLMGenerateResponse<T = unknown> {
     output: T;
@@ -940,35 +1049,53 @@ interface LLMGenerateResponse<T = unknown> {
         inputTokens: number;
         outputTokens: number;
         totalTokens: number;
+        /**
+         * Anthropic-only: input tokens served from the prompt cache (`cache_read_input_tokens`), billed
+         * at 0.1x the base input rate. Optional so OpenAI/OpenRouter usage objects, which never report
+         * this, stay valid -- absent means "this provider doesn't report it," not "zero were read."
+         */
+        cacheReadInputTokens?: number;
+        /**
+         * Anthropic-only: input tokens written to the prompt cache this call
+         * (`cache_creation_input_tokens`), billed at 1.25x the base input rate. Same optionality
+         * rationale as `cacheReadInputTokens`.
+         */
+        cacheCreationInputTokens?: number;
     };
     cost?: number;
     /**
-     * What actually happened to `strict` on the request that produced this response. Every server
-     * adapter sets it on every call, so the value is a statement rather than an inference:
+     * What actually happened to `strict` on the request that produced this response.
      *
      * - `applied` — the request carried `strict: true` and the grammar was in effect
-     * - `refused` — `toStrictSchema` could not express the schema, so the request went out unstrict
-     * - `compileRejected` — the schema passed `toStrictSchema` but the provider's grammar compiler
+     * - `refused` — `compileSchema` could not express the schema, so the request went out unstrict
+     * - `compileRejected` — the schema passed `compileSchema` but the provider's grammar compiler
      *   rejected it at request time, and the call was retried unstrict
-     * - `notAttempted` — this adapter does not send strict at all (OpenAI, Google, OpenRouter)
+     * - `notAttempted` — the adapter did not send `strict` on this call
      *
      * This exists because `strictRefusalReasons` alone cannot answer the question. Its absence means
      * "strict held" OR "nothing ever tried", and a prod run that recorded zero refusals while
      * returning an array-typed field as a string is exactly the case where the difference matters.
      *
-     * Internal-only, like `usage` — `UniversalLLMAdapter` lifts it onto the `ai_calls` row and
-     * strips it before the response reaches callers.
+     * **Do not read this as "provider X never sends strict."** It describes one call, not an adapter.
+     * A previous revision of this comment enumerated OpenAI, Google and OpenRouter as adapters that
+     * never send `strict`, which was false for OpenRouter — it sends `strict: true` whenever the
+     * schema compiles, and separately reports `notAttempted`. That producer bug is still live; the
+     * fix is to make the value a return of schema compilation rather than a per-adapter literal.
+     * `MockAdapter` sets no value at all, so absence does not imply `notAttempted` either.
+     *
+     * Observability only — `UniversalLLMAdapter` lifts it onto the `ai_calls` row. It is not removed
+     * from the response.
      */
     strictStatus?: StrictStatus;
     /**
      * Why this call went out WITHOUT `strict`, on an adapter that tried to send it with one.
      *
      * The detail behind a `refused` / `compileRejected` `strictStatus` — the short, stable reason
-     * strings `toStrictSchema` computes. Read `strictStatus` to answer "was it enforced"; read this
+     * strings `compileSchema` computes. Read `strictStatus` to answer "was it enforced"; read this
      * to answer "why not".
      *
-     * Internal-only, like `usage` — `UniversalLLMAdapter` lifts it onto the `ai_calls` row and
-     * strips it before the response reaches callers.
+     * Observability only — `UniversalLLMAdapter` lifts it onto the `ai_calls` row. It is not removed
+     * from the response.
      */
     strictRefusalReasons?: string[];
 }
@@ -1001,7 +1128,7 @@ interface LLMAdapter {
  * Use-case agnostic types that describe the purpose of each entry
  * Memory types mirror action types for clarity and filtering
  */
-type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'delegation-result' | 'error';
+type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'error';
 /**
  * Who authored an entry's content.
  *
@@ -1030,6 +1157,14 @@ interface MemoryEntry {
      * starting the agent with empty memory rather than throwing.
      */
     source?: MemoryEntrySource;
+    /**
+     * Which tool produced this entry. Set on `tool-result` entries so the model can tell N parallel
+     * results apart -- the framework instructs batching independent tool calls in one iteration, and
+     * an anonymous result is unattributable the moment two land in the same iteration. `addToolError`
+     * already carries this (folded into its `content` JSON); this is the same fact for the success
+     * path, carried as a real field instead of prose the caller has to parse back out.
+     */
+    toolName?: string;
 }
 /**
  * Agent memory - Self-orchestrated memory with session + working storage
@@ -1056,7 +1191,6 @@ interface AgentMemory {
 interface MemoryStatus {
     sessionMemoryKeys: number;
     sessionMemoryLimit: number;
-    currentKeys: string[];
     sessionMemoryTokens: number;
     sessionMemoryTokenLimit: number;
     /**
@@ -1065,10 +1199,26 @@ interface MemoryStatus {
      * read as history pressure and triggered history compaction that could not relieve it.
      */
     historyPercent: number;
+    /**
+     * Tokens the history entries **in scope for the requested turn** occupy — the same set
+     * `toContextParts` puts in the envelope. Equal to `storedHistoryTokens` when `getStatus` is
+     * called without a turn.
+     *
+     * This is the number the model is shown, and it is scoped because the model is handed a scoped
+     * set. Counting the whole cross-turn array here meant the framing quoted the size of a store
+     * while the envelope beside it carried one turn's worth of it.
+     */
     historyTokens: number;
+    /**
+     * Tokens the **entire** history array occupies, across every turn the session snapshot restored.
+     *
+     * This is what compaction measures, because compaction trims that array. Scoping it to a turn
+     * would let the store grow without bound whenever the current turn happened to be small.
+     */
+    storedHistoryTokens: number;
+    /** `storedHistoryTokens` as a percentage of `historyBudget`. The auto-compaction trigger. */
+    storedHistoryPercent: number;
     historyBudget: number;
-    totalTokens: number;
-    tokenBudget: number;
 }
 /**
  * Memory constraints (optional limits)
@@ -1150,6 +1300,14 @@ declare class MemoryManager {
      * are not. Eviction is oldest-first by timestamp, matching the key-count path, and always
      * leaves at least one entry so a single oversized key degrades to "one key" rather than to
      * "memory silently emptied".
+     *
+     * The running total is **recomputed** from the survivors rather than decremented per entry.
+     * `getStatus` estimates the pool as a ceiling of the joined sum, and a per-entry decrement is a
+     * sum of ceilings — the larger of the two by up to one token per key. The running total therefore
+     * fell faster than the pool did, and the loop could exit reporting a fit while the very next
+     * `getStatus` still read over the limit. Recomputing makes the loop's exit condition and the
+     * number it is judged by the same expression. The pool is capped at `MAX_SESSION_MEMORY_KEYS`
+     * entries, so the extra passes are bounded and cheap.
      */
     private enforceSessionMemoryTokenLimit;
     /**
@@ -1159,9 +1317,13 @@ declare class MemoryManager {
     getHistoryLength(): number;
     /**
      * Get memory status for agent awareness
+     *
+     * @param currentTurn - Turn to scope `historyTokens` / `historyPercent` to. Omit to measure the
+     *   whole store, which is what the compaction paths want. Callers building something the model
+     *   reads should pass it, so the count describes the set the model is actually handed.
      * @returns Memory status with token usage and key counts
      */
-    getStatus(): MemoryStatus;
+    getStatus(currentTurn?: number): MemoryStatus;
     /**
      * Create memory snapshot for persistence
      * Caches snapshot internally for later retrieval
@@ -1200,87 +1362,6 @@ declare class MemoryManager {
     toContextParts(currentIteration: number, currentTurn?: number): MemoryContextParts;
 }
 
-/**
- * Knowledge Map Types
- *
- * Enables agents to navigate organizational knowledge through a lightweight
- * graph that lazy-loads capabilities on-demand.
- *
- * @module agent/knowledge-map
- */
-
-/**
- * Lightweight knowledge map (passed as agent property)
- *
- * Contains metadata about available knowledge nodes without loading
- * the full content upfront. Total size: ~300-500 tokens.
- *
- * Multi-tenancy is enforced via:
- * - File-scoped maps (organizations/{org-name}/knowledge/)
- * - ExecutionContext.organizationId passed to node.load()
- */
-interface KnowledgeMap {
-    /** Available knowledge nodes indexed by ID */
-    nodes: Record<string, KnowledgeNode>;
-}
-/**
- * Single knowledge source
- *
- * Represents a domain knowledge area (CRM, brand guidelines, Excel tools)
- * that can be lazy-loaded to provide instructions and tools to agents.
- */
-interface KnowledgeNode {
-    /** Unique identifier for this node (e.g., "crm", "brand-guidelines") */
-    id: string;
-    /**
-     * Description of when to use this knowledge
-     * Used for semantic matching against user intent
-     */
-    description: string;
-    /**
-     * Load knowledge content on-demand
-     *
-     * @param context - Execution context with organizationId for multi-tenancy
-     * @returns Promise resolving to knowledge content (prompt + optional tools)
-     */
-    load(context: ExecutionContext): Promise<KnowledgeContent>;
-    /**
-     * Loaded state flag
-     * Set to true after load() is called
-     */
-    loaded?: boolean;
-    /**
-     * Cached prompt (for system prompt serialization)
-     * Only the prompt is cached - tools go to toolRegistry, children flattened to nodes
-     */
-    prompt?: string;
-}
-/**
- * Content returned by knowledge node
- *
- * Separates instructions (prompt) from capabilities (tools).
- * Tools are optional - some nodes only provide context.
- *
- * Supports recursive navigation - nodes can contain child nodes
- * that are discovered when the parent node is loaded.
- */
-interface KnowledgeContent {
-    /** Instructions and context (markdown format) */
-    prompt: string;
-    /** Tool implementations (optional) */
-    tools?: Tool[];
-    /**
-     * Child knowledge nodes (optional, recursive)
-     *
-     * Enables hierarchical navigation: base → specialized → deep expertise.
-     * Child nodes are flattened into the main knowledge map when parent loads,
-     * making them available for subsequent navigate-knowledge actions.
-     *
-     * Example: CRM base node returns crm-customers and crm-deals as children
-     */
-    nodes?: Record<string, KnowledgeNode>;
-}
-
 /**
  * Agent-specific type definitions
  * Types for autonomous agents with tools, memory, and constraints
@@ -1357,11 +1438,6 @@ interface AgentDefinition {
      * Specifies provider, API key, and model-specific options
      */
     modelConfig: ModelConfig;
-    /**
-     * Optional knowledge map for lazy-loading capabilities
-     * Enables agents to navigate organizational knowledge on-demand
-     */
-    knowledgeMap?: KnowledgeMap;
     /**
      * Preload memory before execution starts
      * Handles BOTH context loading AND session restoration
@@ -1395,7 +1471,6 @@ interface IterationContext {
     logger: AgentScopedLogger;
     modelConfig: ModelConfig;
     adapterFactory: LLMAdapterFactory;
-    knowledgeMap?: KnowledgeMap;
     /**
      * The validated input for this execution, serialized. It travels here because the model gets
      * it as its own `role:'user'` message; nothing else in this context carried it, so the input
@@ -2731,6 +2806,17 @@ interface BaseAICall {
     costUsd: number;
     latencyMs: number;
     context?: AICallContext;
+    /**
+     * Anthropic-only: input tokens served from the prompt cache this call (`cache_read_input_tokens`),
+     * billed at 0.1x the base input rate. Already folded into `inputTokens`/`totalInputTokens` so
+     * aggregate totals reflect real usage -- present here as the raw breakdown, not additive on top.
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Anthropic-only: input tokens written to the prompt cache this call (`cache_creation_input_tokens`),
+     * billed at 1.25x the base input rate. Same folding rationale as `cacheReadInputTokens`.
+     */
+    cacheCreationInputTokens?: number;
     /**
      * Distinct prompt-injection pattern types detected in the request's user-role messages.
      * Present only when the input sanitizer matched something. Non-blocking matches ride along on
@@ -2796,6 +2882,41 @@ interface BaseAICall {
      * Existing readers that only look at the fields above are unaffected.
      */
     strictRefusalReasons?: string[];
+    /**
+     * Time spent in the base adapter's `generate()` call alone, excluding `responseSchema`
+     * validation. On a success or validation-failure row, `providerMs + validateMs === latencyMs`
+     * (modulo rounding) -- `latencyMs` keeps its existing meaning unchanged; this and `validateMs`
+     * are the same window split into its two components.
+     *
+     * Present on success and validation-failure rows. Absent on a blocked row (no provider call was
+     * made) and on rows written before this field existed.
+     */
+    providerMs?: number;
+    /**
+     * Time spent in `validateResponseSchema` alone. Omitted when the call carried no `responseSchema`
+     * (nothing to validate); `0` is a legitimate value meaning a schema was supplied and validation
+     * was effectively instant. See `providerMs` for how the two relate to `latencyMs`.
+     *
+     * Present on success and validation-failure rows that supplied a `responseSchema`. Absent on a
+     * blocked row and on rows written before this field existed.
+     */
+    validateMs?: number;
+    /**
+     * Total elapsed time for the WHOLE `generate()` call -- every retry attempt plus every backoff
+     * sleep between them. Unlike `latencyMs` (which is per-attempt and never includes backoff, by
+     * design -- see `runWithRetry`), this is the one number that answers "how long did the caller
+     * actually wait". On a call that never retried, `wallClockMs === latencyMs`. On a retried call,
+     * `wallClockMs` is strictly greater than any individual row's `latencyMs` from that same call, by
+     * at least the backoff time actually slept.
+     *
+     * The same value is attached to every row produced by one `generate()` call (a validation-failure
+     * row from an earlier attempt included), because it describes the call, not the attempt.
+     *
+     * Present on success and validation-failure rows. Absent on a blocked row -- a blocked call never
+     * reaches the retry loop, so `wallClockMs` would just restate `latencyMs` (0). Absent on rows
+     * written before this field existed.
+     */
+    wallClockMs?: number;
 }
 type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
 interface AgentReasoningContext {
@@ -2841,6 +2962,16 @@ interface LLMUsageData {
     latencyMs: number;
     /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
     cost?: number;
+    /**
+     * Anthropic-only: input tokens served from the prompt cache (`cache_read_input_tokens`), billed at
+     * 0.1x the base input rate. Absent for providers that never report it (OpenAI, OpenRouter).
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Anthropic-only: input tokens written to the prompt cache this call
+     * (`cache_creation_input_tokens`), billed at 1.25x the base input rate. Same absence rationale.
+     */
+    cacheCreationInputTokens?: number;
     /** Distinct prompt-injection pattern types detected in the request's user-role messages */
     inputWarnings?: string[];
     /** Additive per-source breakdown of `inputWarnings` — see `SourcedInputWarnings` */
@@ -2855,6 +2986,12 @@ interface LLMUsageData {
     strictStatus?: StrictStatus;
     /** Why the call went out unstrict, when a strict-capable adapter refused the schema */
     strictRefusalReasons?: string[];
+    /** Time in the base adapter's `generate()` alone, excluding `responseSchema` validation. See `BaseAICall.providerMs`. */
+    providerMs?: number;
+    /** Time in `validateResponseSchema` alone. Omitted when no `responseSchema` was supplied. See `BaseAICall.validateMs`. */
+    validateMs?: number;
+    /** Total elapsed for the whole `generate()` call, including every retry and every backoff sleep. See `BaseAICall.wallClockMs`. */
+    wallClockMs?: number;
 }
 interface AIUsageSummary {
     model: LLMModel;