@niadra/sdk 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -29,8 +29,11 @@ type VerifyMethod = "otp_whatsapp" | "otp_sms" | "login" | "kba" | "network_atte
  * control group: the pack is intentionally empty and the SDK treats it as a normal answer.
  */
 type DeliveryPath = "t0" | "t1" | "t2" | "t3" | "t4" | "holdout" | "not_modified";
-/** Kinds of history items the navigation calls can filter on. */
-type HistoryItemKind = "episode" | "fact" | "open_item" | "action" | "system_event" | "object" | "trait";
+/**
+ * Kinds of history items the navigation calls can filter on. A system event is never an item: it
+ * changes its object's state, so filter on `object`.
+ */
+type HistoryItemKind = "episode" | "fact" | "open_item" | "action" | "object" | "trait";
 /**
  * The shape of the pack. Channel views (`voice`, `chat`) size it for the medium; `account`
  * and `partner` read an organization; `task:<name>` views serve internal agents.
@@ -271,6 +274,17 @@ interface TimelineRequest {
     verification?: Verification;
     conversation_id?: string | null;
 }
+/**
+ * Body of `POST /v1/history/open`. A conversation id may be a phone number or an e-mail, and the
+ * customer is personal data, so neither goes in a URL.
+ */
+interface OpenItemRequest {
+    item_id: string;
+    /** The customer the item must belong to; any other item answers 404. */
+    subject?: Handle | null;
+    verification?: Verification;
+    conversation_id?: string | null;
+}
 interface TimelineResponse {
     items: HistoryItem[];
     next_cursor?: string | null;
@@ -295,7 +309,7 @@ interface OpenedItem {
     resolution?: string | null;
     derived: HistoryItem[];
     timeline: HistoryItem[];
-    /** Literal transcript excerpt. Only returned to keys with an elevated scope. */
+    /** The server no longer sends a transcript excerpt; the field stays for code that reads it. */
     excerpt?: string | null;
     as_of?: string | null;
 }
@@ -470,6 +484,23 @@ interface ContextStamp {
     etag?: string | null;
     injected_at: string;
 }
+/**
+ * What the model provider reported for the call behind an agent's turn. `wrap()` reads it from every
+ * call it sees; without `wrap()`, pass it with the turn: `agent(text, { usage: response })` takes an
+ * OpenAI or Anthropic response or a `ModelUsage`.
+ */
+interface ModelUsage {
+    /** Who served the call, lowercase: `openai`, `anthropic`, a router or a cloud. */
+    provider: string;
+    /** The model the provider says answered, such as `gpt-4.1-2025-04-14`. */
+    model: string;
+    /** Every input token, cached ones included. */
+    prompt_tokens: number;
+    /** Input tokens read from the provider's prompt cache. */
+    cached_tokens?: number;
+    /** Input tokens written to the cache (Anthropic's cache creation). */
+    cache_write_tokens?: number;
+}
 /** A message, a system event or an agent action, exactly as sent on the wire. */
 interface EventItem {
     type: "event";
@@ -496,6 +527,8 @@ interface EventItem {
     corrects_event_id?: string | null;
     voice?: VoiceInfo | null;
     context_stamp?: ContextStamp | null;
+    /** The model call behind an `ai_agent` message: tokens and prompt cache. */
+    usage?: ModelUsage | null;
 }
 /** States that several handles belong to the same subject. */
 interface IdentifyItem {
@@ -648,6 +681,8 @@ interface TrackEvent extends EventBase {
     fields?: Record<string, unknown>;
     /** Required for `action`, and only valid there. */
     action?: ActionInfo | null;
+    /** What the provider reported for the model call behind an `ai_agent` message; only valid there. */
+    usage?: ModelUsage | null;
 }
 /** An agent action for `action()`: what an agent did in a system of record. */
 interface ActionEvent extends EventBase {
@@ -807,6 +842,12 @@ interface TurnOptions {
     voice?: VoiceInfo;
     /** Overrides the stamp an agent turn would carry from `markInjected()`. */
     context_stamp?: ContextStamp;
+    /**
+     * Agent turns only: what the model provider reported for the call behind the answer, as the
+     * provider's response (OpenAI or Anthropic) or a `ModelUsage`. `wrap()` passes it for you. A
+     * response without usage is left out; the turn is recorded either way.
+     */
+    usage?: ModelUsage | object | null;
 }
 type ConversationEvent = Omit<TrackEvent, "channel" | "conversation_id"> & {
     channel?: string;
@@ -956,11 +997,15 @@ interface Timeouts {
     navigation: number;
     /** Navigation calls made through a voice conversation or voice-bound tools. */
     navigationVoice: number;
-    /** Each attempt of a batch upload. Writes happen off the hot path, so this one is generous. */
+    /**
+     * The whole of a write the caller waits for: `identify()`, `verify()`, `handoff()`,
+     * `feedback()` and the reservation in `uploadMedia()`, retries included. Also each attempt
+     * of a background batch, which never holds a caller.
+     */
     write: number;
     /** `subjectToken()`, usually called once when a session starts. */
     token: number;
-    /** Each attempt of sending media bytes to storage in `uploadMedia()`, off the hot path. */
+    /** The whole of sending media bytes to storage in `uploadMedia()`, retries included. */
     upload: number;
 }
 declare const DEFAULT_TIMEOUTS: Timeouts;
@@ -988,6 +1033,11 @@ interface QueueOptions {
     flushAt: number;
     /** Send whatever is waiting at least this often. */
     flushIntervalMs: number;
+    /**
+     * Send a conversation turn (a message with a `conversation_id`) at most this long after it was
+     * queued, with whatever else is waiting. It is what the other agents read in `live`.
+     */
+    turnFlushIntervalMs: number;
     /** Items per request. The server accepts up to 500. */
     maxBatchSize: number;
     /** Items held in memory before new ones are dropped. Keeps a long outage from exhausting memory. */
@@ -1148,7 +1198,13 @@ type WriteResult = {
 interface OpenParams {
     verification?: Verification;
     conversation_id?: string;
+    /** Kept for callers of 0.1.0; the server never read it on this route, so it is not sent. */
     task_id?: string;
+    /**
+     * The customer the item must belong to: the server opens it only when it is theirs, and answers
+     * 404 otherwise. `tools()` passes the bound customer.
+     */
+    subject?: Handle;
 }
 /**
  * The Niadra client.
@@ -1199,12 +1255,12 @@ declare class Niadra {
      * topic and kind. The answer includes how often the same kind of issue came back.
      */
     search(params: SearchRequest, options?: RequestOptions): Promise<Result<SearchResponse>>;
-    /** The customer's history in chronological order, one line per item, paginated by cursor. */
+    /** The customer's history, newest first, one line per item, paginated by cursor. */
     timeline(params: TimelineRequest, options?: RequestOptions): Promise<Result<TimelineResponse>>;
     /**
      * Opens one history item from `search()` or `timeline()`: summary, request, commitments,
-     * outcome and resolution. The literal transcript excerpt only comes back to keys with an
-     * elevated scope.
+     * outcome and resolution. Sent as `POST /v1/history/open`: the conversation id and `subject` go
+     * in the body, never in a URL.
      */
     open(id: string, params?: OpenParams, options?: RequestOptions): Promise<Result<OpenedItem>>;
     /**
@@ -1332,7 +1388,11 @@ declare class Niadra {
  * leading system or developer messages, and the suffix (deltas and live turns) as a system
  * message at the end. The pack goes after the caller's instructions because those are the same
  * for every customer: kept first, they stay the cacheable prefix of the prompt. The injection is
- * stamped on the conversation, and the model's answer is recorded as the agent's turn.
+ * stamped on the conversation, and the model's answer is recorded as the agent's turn, with the
+ * usage the provider reported for the call: the prompt's tokens, the ones read from the provider's
+ * prompt cache and the ones written to it (see `modelUsage()`). A stream reports its usage only when
+ * the caller asks for it (`stream_options: { include_usage: true }`); the wrapper never changes the
+ * request to get it.
  *
  * Nothing the wrapper does can fail the model call: a context that cannot be fetched is left
  * out, and a failure to record the answer is logged, without content, and swallowed.
@@ -1342,7 +1402,9 @@ declare class Niadra {
 interface WrapSession {
     context(): Promise<ContextResult>;
     markInjected(context?: ContextResult | null): void;
-    agent(text: string): string | null;
+    agent(text: string, options?: {
+        usage?: ModelUsage | null;
+    }): string | null;
     readonly logger: Logger;
 }
 /** A session, or a function that finds the one the current call belongs to (`null` passes the call through). */
@@ -1366,6 +1428,38 @@ declare function wrap<C extends object>(client: C, session: SessionSource): C;
  */
 declare function injectContext(context: ContextResult, messages: readonly unknown[]): unknown[];
 
+/**
+ * Reads what a model provider reported for one call: every input token, the ones read from the
+ * provider's prompt cache and the ones written to it.
+ *
+ * Two shapes are understood, from the response or its `usage` (plain objects or class instances):
+ *
+ * - OpenAI chat completions and compatible gateways: `usage.prompt_tokens` (cached tokens included)
+ *   and `usage.prompt_tokens_details.cached_tokens`; the Responses API's `input_tokens` with
+ *   `input_tokens_details.cached_tokens` too. Gateways that pass Anthropic's cache fields through
+ *   (`cache_read_input_tokens`, `cache_creation_input_tokens`) are read as well.
+ * - Anthropic messages: `usage.input_tokens` counts only the uncached rest, so the prompt is
+ *   `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`.
+ *
+ * Nothing here throws: a response without usage gives `null`.
+ */
+
+/** `prompt_tokens`, `cached_tokens` and `cache_write_tokens` from a provider's usage, or `null`. */
+declare function tokenCounts(usage: unknown): Pick<ModelUsage, "prompt_tokens" | "cached_tokens" | "cache_write_tokens"> | null;
+/**
+ * Who served the call: the router prefix of `vendor/model` names, else what the name or the usage
+ * shape says, else `openai` (the client `wrap()` takes).
+ */
+declare function providerOf(model: string, usage?: unknown): string;
+/**
+ * The usage of an OpenAI or Anthropic response (or of its bare `usage`, with `options.model`), for
+ * the agent's turn: `convo.agent(text, { usage: modelUsage(response) })`. `null` without usage.
+ */
+declare function modelUsage(response: unknown, options?: {
+    provider?: string;
+    model?: string;
+}): ModelUsage | null;
+
 interface HandleOptions {
     /** Overrides the subject kind the server would infer from the handle type. */
     subjectKind?: SubjectKind;
@@ -1410,7 +1504,7 @@ declare function toObjectRef(object: ObjectRef | string): ObjectRef;
 interface ParsedApiKey {
     /** `live` keys reach production spaces, `test` keys reach sandbox spaces. */
     mode: "live" | "test";
-    /** Data region, such as `sa-east-1`. */
+    /** Data region, such as `us-east-2`. */
     region: string;
     /** The space (project and environment) the key belongs to. */
     space: string;
@@ -1436,6 +1530,6 @@ declare function baseURLFromKey(key: ParsedApiKey): string;
  */
 declare function uuidv7(now?: number): string;
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.1";
 
-export { type ActionEvent, type ActionInfo, type AssertionMethod, type BatchItem, type BatchRequest, type BatchResponse, type BoundTools, type CacheDirectives, type CacheOptions, type ClientOptions, type Closes, type Commitment, type Content, type ContextOptions, type ContextParams, type ContextRequest, type ContextResponse, type ContextResult, type ContextSource, type ContextStamp, Conversation, type ConversationAction, type ConversationEndedItem, type ConversationEvent, type ConversationParams, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, type DeliveryPath, type EventItem, type EventKind, type FeedbackAction, type FeedbackParams, type FeedbackRequest, type Handle, type HandleType, type HandoffItem, type HandoffParams, type HeartbeatItem, type HistoryFilters, type HistoryItem, type HistoryItemKind, type IdentifyItem, type IdentifyParams, type ItemError, type LiveTurn, type Logger, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, type MediaUpload, type MediaUploadRequest, type MediaUploadResponse, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, type ObjectRef, type ObjectState, type ObjectTimeline, type ObjectTimelineParams, type OpenParams, type OpenedItem, type ParsedApiKey, type Problem, type QueueOptions, type Recurrence, type RequestOptions, type Result, type SearchRequest, type SearchResponse, type SessionSource, type SourceCoverage, type Speaker, type SpeakerRef, type Subject, type SubjectKind, type SubjectToken, type SubjectTokenRequest, TOOL_DEFINITIONS, TOOL_NAMES, type TargetModel, Task, type TaskAction, type TaskEndedItem, type TaskEvent, type TaskParams, type TimelineRequest, type TimelineResponse, type Timeouts, type Timestamp, type Timings, type ToolBinding, type ToolDefinition, type TrackEvent, type TurnOptions, type UploadParams, VERSION, type Verification, type VerificationResult, type VerifyItem, type VerifyMethod, type VerifyParams, type View, type Visibility, type VoiceInfo, type WrapSession, type WriteResult, baseURLFromKey, consoleLogger, handles, injectContext, parseApiKey, renderLive, renderSuffix, silentLogger, toObjectRef, uuidv7, wrap };
+export { type ActionEvent, type ActionInfo, type AssertionMethod, type BatchItem, type BatchRequest, type BatchResponse, type BoundTools, type CacheDirectives, type CacheOptions, type ClientOptions, type Closes, type Commitment, type Content, type ContextOptions, type ContextParams, type ContextRequest, type ContextResponse, type ContextResult, type ContextSource, type ContextStamp, Conversation, type ConversationAction, type ConversationEndedItem, type ConversationEvent, type ConversationParams, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, type DeliveryPath, type EventItem, type EventKind, type FeedbackAction, type FeedbackParams, type FeedbackRequest, type Handle, type HandleType, type HandoffItem, type HandoffParams, type HeartbeatItem, type HistoryFilters, type HistoryItem, type HistoryItemKind, type IdentifyItem, type IdentifyParams, type ItemError, type LiveTurn, type Logger, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, type MediaUpload, type MediaUploadRequest, type MediaUploadResponse, type ModelUsage, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, type ObjectRef, type ObjectState, type ObjectTimeline, type ObjectTimelineParams, type OpenItemRequest, type OpenParams, type OpenedItem, type ParsedApiKey, type Problem, type QueueOptions, type Recurrence, type RequestOptions, type Result, type SearchRequest, type SearchResponse, type SessionSource, type SourceCoverage, type Speaker, type SpeakerRef, type Subject, type SubjectKind, type SubjectToken, type SubjectTokenRequest, TOOL_DEFINITIONS, TOOL_NAMES, type TargetModel, Task, type TaskAction, type TaskEndedItem, type TaskEvent, type TaskParams, type TimelineRequest, type TimelineResponse, type Timeouts, type Timestamp, type Timings, type ToolBinding, type ToolDefinition, type TrackEvent, type TurnOptions, type UploadParams, VERSION, type Verification, type VerificationResult, type VerifyItem, type VerifyMethod, type VerifyParams, type View, type Visibility, type VoiceInfo, type WrapSession, type WriteResult, baseURLFromKey, consoleLogger, handles, injectContext, modelUsage, parseApiKey, providerOf, renderLive, renderSuffix, silentLogger, toObjectRef, tokenCounts, uuidv7, wrap };

package/dist/index.d.ts

@@ -29,8 +29,11 @@ type VerifyMethod = "otp_whatsapp" | "otp_sms" | "login" | "kba" | "network_atte
  * control group: the pack is intentionally empty and the SDK treats it as a normal answer.
  */
 type DeliveryPath = "t0" | "t1" | "t2" | "t3" | "t4" | "holdout" | "not_modified";
-/** Kinds of history items the navigation calls can filter on. */
-type HistoryItemKind = "episode" | "fact" | "open_item" | "action" | "system_event" | "object" | "trait";
+/**
+ * Kinds of history items the navigation calls can filter on. A system event is never an item: it
+ * changes its object's state, so filter on `object`.
+ */
+type HistoryItemKind = "episode" | "fact" | "open_item" | "action" | "object" | "trait";
 /**
  * The shape of the pack. Channel views (`voice`, `chat`) size it for the medium; `account`
  * and `partner` read an organization; `task:<name>` views serve internal agents.
@@ -271,6 +274,17 @@ interface TimelineRequest {
     verification?: Verification;
     conversation_id?: string | null;
 }
+/**
+ * Body of `POST /v1/history/open`. A conversation id may be a phone number or an e-mail, and the
+ * customer is personal data, so neither goes in a URL.
+ */
+interface OpenItemRequest {
+    item_id: string;
+    /** The customer the item must belong to; any other item answers 404. */
+    subject?: Handle | null;
+    verification?: Verification;
+    conversation_id?: string | null;
+}
 interface TimelineResponse {
     items: HistoryItem[];
     next_cursor?: string | null;
@@ -295,7 +309,7 @@ interface OpenedItem {
     resolution?: string | null;
     derived: HistoryItem[];
     timeline: HistoryItem[];
-    /** Literal transcript excerpt. Only returned to keys with an elevated scope. */
+    /** The server no longer sends a transcript excerpt; the field stays for code that reads it. */
     excerpt?: string | null;
     as_of?: string | null;
 }
@@ -470,6 +484,23 @@ interface ContextStamp {
     etag?: string | null;
     injected_at: string;
 }
+/**
+ * What the model provider reported for the call behind an agent's turn. `wrap()` reads it from every
+ * call it sees; without `wrap()`, pass it with the turn: `agent(text, { usage: response })` takes an
+ * OpenAI or Anthropic response or a `ModelUsage`.
+ */
+interface ModelUsage {
+    /** Who served the call, lowercase: `openai`, `anthropic`, a router or a cloud. */
+    provider: string;
+    /** The model the provider says answered, such as `gpt-4.1-2025-04-14`. */
+    model: string;
+    /** Every input token, cached ones included. */
+    prompt_tokens: number;
+    /** Input tokens read from the provider's prompt cache. */
+    cached_tokens?: number;
+    /** Input tokens written to the cache (Anthropic's cache creation). */
+    cache_write_tokens?: number;
+}
 /** A message, a system event or an agent action, exactly as sent on the wire. */
 interface EventItem {
     type: "event";
@@ -496,6 +527,8 @@ interface EventItem {
     corrects_event_id?: string | null;
     voice?: VoiceInfo | null;
     context_stamp?: ContextStamp | null;
+    /** The model call behind an `ai_agent` message: tokens and prompt cache. */
+    usage?: ModelUsage | null;
 }
 /** States that several handles belong to the same subject. */
 interface IdentifyItem {
@@ -648,6 +681,8 @@ interface TrackEvent extends EventBase {
     fields?: Record<string, unknown>;
     /** Required for `action`, and only valid there. */
     action?: ActionInfo | null;
+    /** What the provider reported for the model call behind an `ai_agent` message; only valid there. */
+    usage?: ModelUsage | null;
 }
 /** An agent action for `action()`: what an agent did in a system of record. */
 interface ActionEvent extends EventBase {
@@ -807,6 +842,12 @@ interface TurnOptions {
     voice?: VoiceInfo;
     /** Overrides the stamp an agent turn would carry from `markInjected()`. */
     context_stamp?: ContextStamp;
+    /**
+     * Agent turns only: what the model provider reported for the call behind the answer, as the
+     * provider's response (OpenAI or Anthropic) or a `ModelUsage`. `wrap()` passes it for you. A
+     * response without usage is left out; the turn is recorded either way.
+     */
+    usage?: ModelUsage | object | null;
 }
 type ConversationEvent = Omit<TrackEvent, "channel" | "conversation_id"> & {
     channel?: string;
@@ -956,11 +997,15 @@ interface Timeouts {
     navigation: number;
     /** Navigation calls made through a voice conversation or voice-bound tools. */
     navigationVoice: number;
-    /** Each attempt of a batch upload. Writes happen off the hot path, so this one is generous. */
+    /**
+     * The whole of a write the caller waits for: `identify()`, `verify()`, `handoff()`,
+     * `feedback()` and the reservation in `uploadMedia()`, retries included. Also each attempt
+     * of a background batch, which never holds a caller.
+     */
     write: number;
     /** `subjectToken()`, usually called once when a session starts. */
     token: number;
-    /** Each attempt of sending media bytes to storage in `uploadMedia()`, off the hot path. */
+    /** The whole of sending media bytes to storage in `uploadMedia()`, retries included. */
     upload: number;
 }
 declare const DEFAULT_TIMEOUTS: Timeouts;
@@ -988,6 +1033,11 @@ interface QueueOptions {
     flushAt: number;
     /** Send whatever is waiting at least this often. */
     flushIntervalMs: number;
+    /**
+     * Send a conversation turn (a message with a `conversation_id`) at most this long after it was
+     * queued, with whatever else is waiting. It is what the other agents read in `live`.
+     */
+    turnFlushIntervalMs: number;
     /** Items per request. The server accepts up to 500. */
     maxBatchSize: number;
     /** Items held in memory before new ones are dropped. Keeps a long outage from exhausting memory. */
@@ -1148,7 +1198,13 @@ type WriteResult = {
 interface OpenParams {
     verification?: Verification;
     conversation_id?: string;
+    /** Kept for callers of 0.1.0; the server never read it on this route, so it is not sent. */
     task_id?: string;
+    /**
+     * The customer the item must belong to: the server opens it only when it is theirs, and answers
+     * 404 otherwise. `tools()` passes the bound customer.
+     */
+    subject?: Handle;
 }
 /**
  * The Niadra client.
@@ -1199,12 +1255,12 @@ declare class Niadra {
      * topic and kind. The answer includes how often the same kind of issue came back.
      */
     search(params: SearchRequest, options?: RequestOptions): Promise<Result<SearchResponse>>;
-    /** The customer's history in chronological order, one line per item, paginated by cursor. */
+    /** The customer's history, newest first, one line per item, paginated by cursor. */
     timeline(params: TimelineRequest, options?: RequestOptions): Promise<Result<TimelineResponse>>;
     /**
      * Opens one history item from `search()` or `timeline()`: summary, request, commitments,
-     * outcome and resolution. The literal transcript excerpt only comes back to keys with an
-     * elevated scope.
+     * outcome and resolution. Sent as `POST /v1/history/open`: the conversation id and `subject` go
+     * in the body, never in a URL.
      */
     open(id: string, params?: OpenParams, options?: RequestOptions): Promise<Result<OpenedItem>>;
     /**
@@ -1332,7 +1388,11 @@ declare class Niadra {
  * leading system or developer messages, and the suffix (deltas and live turns) as a system
  * message at the end. The pack goes after the caller's instructions because those are the same
  * for every customer: kept first, they stay the cacheable prefix of the prompt. The injection is
- * stamped on the conversation, and the model's answer is recorded as the agent's turn.
+ * stamped on the conversation, and the model's answer is recorded as the agent's turn, with the
+ * usage the provider reported for the call: the prompt's tokens, the ones read from the provider's
+ * prompt cache and the ones written to it (see `modelUsage()`). A stream reports its usage only when
+ * the caller asks for it (`stream_options: { include_usage: true }`); the wrapper never changes the
+ * request to get it.
  *
  * Nothing the wrapper does can fail the model call: a context that cannot be fetched is left
  * out, and a failure to record the answer is logged, without content, and swallowed.
@@ -1342,7 +1402,9 @@ declare class Niadra {
 interface WrapSession {
     context(): Promise<ContextResult>;
     markInjected(context?: ContextResult | null): void;
-    agent(text: string): string | null;
+    agent(text: string, options?: {
+        usage?: ModelUsage | null;
+    }): string | null;
     readonly logger: Logger;
 }
 /** A session, or a function that finds the one the current call belongs to (`null` passes the call through). */
@@ -1366,6 +1428,38 @@ declare function wrap<C extends object>(client: C, session: SessionSource): C;
  */
 declare function injectContext(context: ContextResult, messages: readonly unknown[]): unknown[];
 
+/**
+ * Reads what a model provider reported for one call: every input token, the ones read from the
+ * provider's prompt cache and the ones written to it.
+ *
+ * Two shapes are understood, from the response or its `usage` (plain objects or class instances):
+ *
+ * - OpenAI chat completions and compatible gateways: `usage.prompt_tokens` (cached tokens included)
+ *   and `usage.prompt_tokens_details.cached_tokens`; the Responses API's `input_tokens` with
+ *   `input_tokens_details.cached_tokens` too. Gateways that pass Anthropic's cache fields through
+ *   (`cache_read_input_tokens`, `cache_creation_input_tokens`) are read as well.
+ * - Anthropic messages: `usage.input_tokens` counts only the uncached rest, so the prompt is
+ *   `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`.
+ *
+ * Nothing here throws: a response without usage gives `null`.
+ */
+
+/** `prompt_tokens`, `cached_tokens` and `cache_write_tokens` from a provider's usage, or `null`. */
+declare function tokenCounts(usage: unknown): Pick<ModelUsage, "prompt_tokens" | "cached_tokens" | "cache_write_tokens"> | null;
+/**
+ * Who served the call: the router prefix of `vendor/model` names, else what the name or the usage
+ * shape says, else `openai` (the client `wrap()` takes).
+ */
+declare function providerOf(model: string, usage?: unknown): string;
+/**
+ * The usage of an OpenAI or Anthropic response (or of its bare `usage`, with `options.model`), for
+ * the agent's turn: `convo.agent(text, { usage: modelUsage(response) })`. `null` without usage.
+ */
+declare function modelUsage(response: unknown, options?: {
+    provider?: string;
+    model?: string;
+}): ModelUsage | null;
+
 interface HandleOptions {
     /** Overrides the subject kind the server would infer from the handle type. */
     subjectKind?: SubjectKind;
@@ -1410,7 +1504,7 @@ declare function toObjectRef(object: ObjectRef | string): ObjectRef;
 interface ParsedApiKey {
     /** `live` keys reach production spaces, `test` keys reach sandbox spaces. */
     mode: "live" | "test";
-    /** Data region, such as `sa-east-1`. */
+    /** Data region, such as `us-east-2`. */
     region: string;
     /** The space (project and environment) the key belongs to. */
     space: string;
@@ -1436,6 +1530,6 @@ declare function baseURLFromKey(key: ParsedApiKey): string;
  */
 declare function uuidv7(now?: number): string;
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.1";
 
-export { type ActionEvent, type ActionInfo, type AssertionMethod, type BatchItem, type BatchRequest, type BatchResponse, type BoundTools, type CacheDirectives, type CacheOptions, type ClientOptions, type Closes, type Commitment, type Content, type ContextOptions, type ContextParams, type ContextRequest, type ContextResponse, type ContextResult, type ContextSource, type ContextStamp, Conversation, type ConversationAction, type ConversationEndedItem, type ConversationEvent, type ConversationParams, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, type DeliveryPath, type EventItem, type EventKind, type FeedbackAction, type FeedbackParams, type FeedbackRequest, type Handle, type HandleType, type HandoffItem, type HandoffParams, type HeartbeatItem, type HistoryFilters, type HistoryItem, type HistoryItemKind, type IdentifyItem, type IdentifyParams, type ItemError, type LiveTurn, type Logger, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, type MediaUpload, type MediaUploadRequest, type MediaUploadResponse, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, type ObjectRef, type ObjectState, type ObjectTimeline, type ObjectTimelineParams, type OpenParams, type OpenedItem, type ParsedApiKey, type Problem, type QueueOptions, type Recurrence, type RequestOptions, type Result, type SearchRequest, type SearchResponse, type SessionSource, type SourceCoverage, type Speaker, type SpeakerRef, type Subject, type SubjectKind, type SubjectToken, type SubjectTokenRequest, TOOL_DEFINITIONS, TOOL_NAMES, type TargetModel, Task, type TaskAction, type TaskEndedItem, type TaskEvent, type TaskParams, type TimelineRequest, type TimelineResponse, type Timeouts, type Timestamp, type Timings, type ToolBinding, type ToolDefinition, type TrackEvent, type TurnOptions, type UploadParams, VERSION, type Verification, type VerificationResult, type VerifyItem, type VerifyMethod, type VerifyParams, type View, type Visibility, type VoiceInfo, type WrapSession, type WriteResult, baseURLFromKey, consoleLogger, handles, injectContext, parseApiKey, renderLive, renderSuffix, silentLogger, toObjectRef, uuidv7, wrap };
+export { type ActionEvent, type ActionInfo, type AssertionMethod, type BatchItem, type BatchRequest, type BatchResponse, type BoundTools, type CacheDirectives, type CacheOptions, type ClientOptions, type Closes, type Commitment, type Content, type ContextOptions, type ContextParams, type ContextRequest, type ContextResponse, type ContextResult, type ContextSource, type ContextStamp, Conversation, type ConversationAction, type ConversationEndedItem, type ConversationEvent, type ConversationParams, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, type DeliveryPath, type EventItem, type EventKind, type FeedbackAction, type FeedbackParams, type FeedbackRequest, type Handle, type HandleType, type HandoffItem, type HandoffParams, type HeartbeatItem, type HistoryFilters, type HistoryItem, type HistoryItemKind, type IdentifyItem, type IdentifyParams, type ItemError, type LiveTurn, type Logger, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, type MediaUpload, type MediaUploadRequest, type MediaUploadResponse, type ModelUsage, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, type ObjectRef, type ObjectState, type ObjectTimeline, type ObjectTimelineParams, type OpenItemRequest, type OpenParams, type OpenedItem, type ParsedApiKey, type Problem, type QueueOptions, type Recurrence, type RequestOptions, type Result, type SearchRequest, type SearchResponse, type SessionSource, type SourceCoverage, type Speaker, type SpeakerRef, type Subject, type SubjectKind, type SubjectToken, type SubjectTokenRequest, TOOL_DEFINITIONS, TOOL_NAMES, type TargetModel, Task, type TaskAction, type TaskEndedItem, type TaskEvent, type TaskParams, type TimelineRequest, type TimelineResponse, type Timeouts, type Timestamp, type Timings, type ToolBinding, type ToolDefinition, type TrackEvent, type TurnOptions, type UploadParams, VERSION, type Verification, type VerificationResult, type VerifyItem, type VerifyMethod, type VerifyParams, type View, type Visibility, type VoiceInfo, type WrapSession, type WriteResult, baseURLFromKey, consoleLogger, handles, injectContext, modelUsage, parseApiKey, providerOf, renderLive, renderSuffix, silentLogger, toObjectRef, tokenCounts, uuidv7, wrap };