@niadra/sdk 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to this package are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.1] - 2026-09-24
+
+### Added
+
+- The agent's turn carries the usage the model provider reported for the call behind it, as
+  `usage` (`ModelUsage`: provider, model, prompt tokens with the cached ones included, cached
+  tokens, tokens written to the cache). `wrap()` reads it from every OpenAI-compatible response
+  and from the last chunk of a stream that asked for it (`stream_options: { include_usage: true }`),
+  and never changes the request. Niadra sums it per agent, vendor and model, and the Console shows
+  the prompt cache's hit rate and estimated savings.
+- `agent(text, { usage })` on conversations and tasks takes the provider's response (OpenAI chat
+  completions or Responses, Anthropic messages) or a `ModelUsage`, for agents that do not use
+  `wrap()`; `modelUsage()` reads one yourself. A response without usage is left out; the turn is
+  recorded either way.
+- CI runs the build on Deno (with no permissions), Bun, workerd (Cloudflare Workers) and the Vercel
+  Edge Runtime (`pnpm runtimes`), and the README names them.
+
+### Changed
+
+- `engines` asks for Node 20 or later, the versions the CI tests. The README no longer claims Node 18.
+- A conversation turn (a message with a `conversation_id`) leaves the queue at most 200 ms after it
+  was queued, taking whatever else is waiting along, instead of up to a second: it is what the other
+  agents read in `live`. `queue.turnFlushIntervalMs` sets it; other items still wait for
+  `flushIntervalMs` (1 s) or `flushAt` (15).
+- The timeline tool says the history comes newest first, as the server returns it, instead of
+  "in chronological order".
+- The search tool no longer offers the model a `system_event` item kind, and its description names
+  business objects instead of system events: a system event is never an item, it changes its object,
+  so the filter is `object`. The server still reads `system_event` from 0.1.0 as `object`.
+- `open()` sends `POST /v1/history/open` with the item id, the level and the conversation id in the
+  body, instead of `GET /v1/history/items/{id}` with the conversation id in the query: a
+  conversation id may be a phone number or an e-mail, and a URL reaches access logs.
+- `open()` takes `subject`, the customer the item must belong to; the server opens any other item
+  as 404. The tool kit passes its bound customer, so `open_history_item` opens only that
+  customer's items.
+- `task_id` on `open()` is no longer sent: the server never read it on this route. The field stays
+  in `OpenParams` for code written against 0.1.0.
+- The `excerpt` field of an opened item says the server no longer sends it.
+
+### Fixed
+
+- Building a client on Deno without `--allow-env` no longer throws: a runtime that refuses to read
+  the environment now counts as one without `NIADRA_API_KEY` and `NIADRA_BASE_URL`.
+- `feedback()` and the reservation in `uploadMedia()` end within `timeouts.write` (5 s) in total,
+  retries and backoff included, instead of 5 s per attempt.
+- The transfer in `uploadMedia()` ends within `timeouts.upload` (60 s) in total instead of per attempt.
+- `identify()`, `verify()` and `handoff()` resolve by `timeouts.write` with a `NiadraTimeoutError`
+  when the queue could not confirm them in time; the item stays queued and is still sent.
+
 ## [0.1.0] - 2026-09-23
 
 First public release, with the same surface as the Python SDK.

package/README.md

@@ -5,10 +5,11 @@
 
 **Niadra is the shared customer memory for every AI agent in a company.** The WhatsApp agent, the
 voice agent, the billing agent and the human team read the same memory before they act and write
-back what they said and did. This package connects a TypeScript or JavaScript agent to it, on Node
-18+ and on edge runtimes (Vercel, Cloudflare Workers, Deno).
+back what they said and did. This package connects a TypeScript or JavaScript agent to it, on
+Node 20+, Deno, Bun, Cloudflare Workers and the Vercel Edge Runtime: it needs only `fetch` and
+Web Crypto, and CI runs the build on each of them.
 
-[Website](https://niadra.com/en) · [Documentation](https://niadra.com/en/docs) ·
+[Website](https://niadra.com/en) · [Documentation](https://docs.niadra.com/en) ·
 [Talk to us](https://niadra.com/en/enterprise) · [Python SDK](https://github.com/ainiadra/niadra-sdk-python)
 
 ```sh
@@ -90,7 +91,8 @@ exported on request. The SDK never logs handles or message text.
 
 **Which models and frameworks does it work with?** Any. The context is text you place in your
 prompt, the tools follow the common function-calling format, and `wrap()` covers
-OpenAI-compatible clients.
+OpenAI-compatible clients; `agent(text, { usage })` takes the usage of an OpenAI or Anthropic
+response.
 
 ## Concepts
 
@@ -168,6 +170,22 @@ const completion = await openai.chat.completions.create({ model: "gpt-4.1", mess
 
 Every `chat.completions.create` and `chat.completions.parse` call through the wrapper, streaming or not, gets the pack after your leading system messages and the suffix at the end. The injection is stamped, and the model's answer (its first choice) is recorded as the agent's turn: at once, or when a stream ends or you stop reading it. `.withResponse()` keeps working and records too; `.asResponse()` returns the raw HTTP response, so nothing is recorded then. Pass a function instead of a conversation to pick one per call; when it returns `null`, the call passes through untouched. Nothing the wrapper does can fail your call: a context it cannot fetch is left out, and a failure to record the answer is logged, without content.
 
+#### The provider's prompt cache
+
+The agent's turn also carries the usage the provider reported for the call: every input token (`usage.prompt_tokens`), the ones read from its prompt cache (`usage.prompt_tokens_details.cached_tokens`) and, through gateways that pass Anthropic's fields along, the ones written to it. A stream reports usage only when you ask for it with `stream_options: { include_usage: true }`; the wrapper never changes your request to get it. Niadra sums the usage per agent, vendor and model, and the Console shows the cache's hit rate and the estimated savings next to the rest of the space's usage.
+
+Without `wrap()`, pass the provider's response with the turn. An OpenAI response and an Anthropic one are both understood (Anthropic's `usage.input_tokens`, `cache_read_input_tokens` and `cache_creation_input_tokens`):
+
+```ts
+const message = await anthropic.messages.create({ model: "claude-sonnet-4-5", max_tokens: 1024, system, messages });
+convo.agent(textOf(message), { usage: message });
+
+// or build it yourself
+convo.agent(reply, { usage: { provider: "openai", model: "gpt-4.1", prompt_tokens: 3000, cached_tokens: 2048 } });
+```
+
+`modelUsage(response)` reads one yourself. A response without usage is left out, and the turn is recorded either way.
+
 ### Tasks
 
 Internal agents (billing, collections, triage) work in tasks rather than conversations. A task centers its pack on its object, keeps deltas and stamps like a conversation, scopes the cache, groups events and ends with `task.ended`.
@@ -191,6 +209,8 @@ await task.end();
 | `handoff({ conversation_id, target })` | A transfer to a human or another agent | Sent at once |
 | `feedback({ subject, action, ... })` | A correction of what Niadra derived: `retract_fact`, `correct_fact`, `resolve_open_item`, `conversation_outcome` | Sent at once |
 
+Queued items leave in batches when 15 are waiting or a second after the first one, whichever comes first. A message with a `conversation_id` is a turn the other agents read in `live`, so it leaves within 200 ms (`queue.turnFlushIntervalMs`), taking whatever else is waiting along.
+
 Every item carries an idempotency key: the provider's message id when you pass one, a UUIDv7 otherwise. Retrying the same event is harmless.
 
 `identify()`, `verify()`, `handoff()` and `feedback()` resolve to `{ ok, idempotency_key, error }` once the server has answered. A correction is recorded as an event, so it is audited like any other. A `context()` call made after `identify()` or `verify()` resolves already reflects it.
@@ -211,6 +231,8 @@ if (first) {
 
 `search()` also reports recurrence: how many times the same kind of issue came back, and how it was last resolved.
 
+The handle, the search and the conversation id go in request bodies, never in a URL: a conversation id may be a phone number or an e-mail. `open()` sends `POST /v1/history/open`, and the tool kit adds the bound customer to it, so the server opens only that customer's items.
+
 ### Business objects
 
 ```ts
@@ -229,7 +251,7 @@ if (upload) {
 }
 ```
 
-Media never travels inside an event. `uploadMedia()` takes a `Uint8Array`, `ArrayBuffer` or `Blob`, reserves an upload, sends the bytes straight to storage over a signed URL (HTTPS only, with exactly the headers the signature covers and nothing else, so never your key or default headers; storage checks the body against the declared size and digest), and resolves with the reference and digest for the event. With `subject`, the file is stored under that person, so erasing them erases it even if no event ever references it. Hashing uses Web Crypto, which Node 18 only exposes behind a flag.
+Media never travels inside an event. `uploadMedia()` takes a `Uint8Array`, `ArrayBuffer` or `Blob`, reserves an upload, sends the bytes straight to storage over a signed URL (HTTPS only, with exactly the headers the signature covers and nothing else, so never your key or default headers; storage checks the body against the declared size and digest), and resolves with the reference and digest for the event. With `subject`, the file is stored under that person, so erasing them erases it even if no event ever references it. Hashing uses Web Crypto.
 
 ### Tools for any model
 
@@ -273,17 +295,17 @@ Memory should make an agent better, never make it fail. By default:
 | Queue full (10,000 items) | New events are dropped and logged. |
 | Server rejects one item of a batch (207) | Only that item fails; the rest are stored. |
 
-Every read has its own time budget, independent of your platform's:
+Every call you wait for has its own time budget for the whole call, retries and waits included, independent of your platform's:
 
 | Call | Default |
 | --- | --- |
 | `context()` | 300 ms, 150 ms with `view: "voice"` |
 | `search()`, `timeline()`, `open()`, `objectState()`, `objectTimeline()` | 600 ms, 300 ms through voice conversations and voice-bound tools |
 | `subjectToken()` | 2 s |
-| Each attempt of a batch, `feedback()` or an upload reservation | 5 s |
-| Each attempt of an `uploadMedia()` transfer | 60 s |
+| `identify()`, `verify()`, `handoff()`, `feedback()` and the reservation in `uploadMedia()` | 5 s |
+| The transfer in `uploadMedia()` | 60 s |
 
-Override them with `timeouts`, or per call with `{ timeout }`. Pass `{ signal }` to cancel a call.
+An `identify()`, `verify()` or `handoff()` that runs out of time resolves with a `NiadraTimeoutError` and stays in the queue, which keeps sending it. `track()` never waits; each attempt of a background batch has 5 s. Override them with `timeouts`, or per call with `{ timeout }`. Pass `{ signal }` to cancel a call.
 
 ### The context cache
 
@@ -310,7 +332,6 @@ Configure it with `cache: { ttlMs, staleWhileRevalidateMs, maxStaleMs, maxEntrie
 
 - **Long-running Node services:** queued events are flushed when the event loop runs out of work (`beforeExit`). That event does not fire on signals or `process.exit()`, so call `await niadra.shutdown()` in your SIGTERM handler.
 - **Serverless functions:** `await niadra.flush()` before returning.
-- **Edge runtimes:** pass the flush to the platform, for example `ctx.waitUntil(niadra.flush())`.
 
 Create one client per process and share it: it owns the queue and the cache.
 
@@ -322,7 +343,7 @@ new Niadra({
   baseURL: "http://localhost:4010",          // default: NIADRA_BASE_URL, then derived from the key
   timeouts: { context: 300, contextVoice: 150, navigation: 600, navigationVoice: 300, write: 5000, token: 2000, upload: 60_000 },
   cache: { ttlMs: 10_000, staleWhileRevalidateMs: 600_000, maxStaleMs: 1_800_000, maxEntries: 1000 },
-  queue: { flushAt: 15, flushIntervalMs: 1000, maxBatchSize: 100, maxQueueSize: 10_000, maxAttempts: 3 },
+  queue: { flushAt: 15, flushIntervalMs: 1000, turnFlushIntervalMs: 200, maxBatchSize: 100, maxQueueSize: 10_000, maxAttempts: 3 },
   strict: false,
   flushOnExit: true,
   logger: console,                           // anything with debug, warn and error
@@ -347,14 +368,10 @@ pnpm check     # typecheck, lint, tests
 pnpm build     # ESM and CommonJS into dist/
 ```
 
-## Em português
+## Documentation in Portuguese
 
-A Niadra é a memória de clientes compartilhada por todos os agentes de IA de uma empresa: o agente
-do WhatsApp, o de voz, o de cobrança e o time humano leem a mesma memória antes de agir e registram
-o que disseram e fizeram. Este pacote conecta um agente em TypeScript ou JavaScript a essa memória:
-`context()` antes de chamar o modelo, `track()` depois, e `action()` quando o agente faz algo num
-sistema. Documentação em [niadra.com/docs](https://niadra.com/docs) e contato em
-[niadra.com/enterprise](https://niadra.com/enterprise).
+The documentation is also available in Portuguese at [docs.niadra.com](https://docs.niadra.com),
+and the contact page in Portuguese at [niadra.com/enterprise](https://niadra.com/enterprise).
 
 ## License
 

package/dist/index.cjs

@@ -360,6 +360,15 @@ function checkCloses(closes) {
   const byObject = Boolean(closes.object && closes.operation);
   if (byId === byObject) fail("closes takes either item_id, or object and operation");
 }
+function checkUsage(usage) {
+  if (!/^[a-z0-9][a-z0-9_.-]{0,63}$/.test(usage.provider)) fail("usage.provider must be lowercase, like `openai`");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:/@-]{0,127}$/.test(usage.model)) fail("usage.model is not a model name");
+  const counts = [usage.prompt_tokens, usage.cached_tokens ?? 0, usage.cache_write_tokens ?? 0];
+  if (!counts.every((n) => Number.isInteger(n) && n >= 0)) fail("usage counts are whole numbers from 0");
+  if ((usage.cached_tokens ?? 0) + (usage.cache_write_tokens ?? 0) > usage.prompt_tokens) {
+    fail("cached and written tokens are part of prompt_tokens");
+  }
+}
 function checkContent(content) {
   if (!content) return;
   if ((content.text?.length ?? 0) > MAX_EVENT_TEXT) fail(`content.text is longer than ${MAX_EVENT_TEXT}`);
@@ -390,6 +399,10 @@ function buildEvent(input) {
     if ((input.action.result?.length ?? 0) > 2e3) fail("action.result is longer than 2000");
     checkCloses(input.action.closes);
   }
+  if (input.usage) {
+    if (kind !== "message" || speaker.role !== "ai_agent") fail("`usage` is only valid on a message of the `ai_agent`");
+    checkUsage(input.usage);
+  }
   const event = {
     type: "event",
     kind,
@@ -405,6 +418,7 @@ function buildEvent(input) {
   if (input.canonical_type) event.canonical_type = input.canonical_type;
   if (input.fields) event.fields = input.fields;
   if (input.action) event.action = input.action;
+  if (input.usage) event.usage = input.usage;
   copyOptional(event, input);
   assertSerializable(event);
   return event;
@@ -579,6 +593,76 @@ function withDeltas(result, response, deltas) {
   return { ...result, response: merged, suffix: renderSuffix(merged) };
 }
 
+// src/usage.ts
+var PROVIDER = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+var MODEL = /^[A-Za-z0-9][A-Za-z0-9_.:/@-]{0,127}$/;
+function get(value, name) {
+  return (typeof value === "object" || typeof value === "function") && value !== null ? value[name] : void 0;
+}
+function count(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function tokenCounts(usage) {
+  const read = count(get(usage, "cache_read_input_tokens")) ?? 0;
+  const written = count(get(usage, "cache_creation_input_tokens")) ?? 0;
+  let prompt = count(get(usage, "prompt_tokens"));
+  let cached;
+  if (prompt !== null) {
+    const reported = count(get(get(usage, "prompt_tokens_details"), "cached_tokens"));
+    cached = reported !== null && reported > 0 ? reported : read;
+  } else {
+    const inputs = count(get(usage, "input_tokens"));
+    if (inputs === null) return null;
+    const details = get(usage, "input_tokens_details");
+    if (details !== void 0 && details !== null) {
+      prompt = inputs;
+      cached = count(get(details, "cached_tokens")) ?? 0;
+    } else {
+      prompt = inputs + read + written;
+      cached = read;
+    }
+  }
+  return { prompt_tokens: Math.max(prompt, cached + written), cached_tokens: cached, cache_write_tokens: written };
+}
+function providerOf(model, usage) {
+  const slash = model.indexOf("/");
+  if (slash > 0) return model.slice(0, slash).trim().toLowerCase();
+  const name = model.trim().toLowerCase();
+  if (name.startsWith("claude") || `.${name}`.includes(".anthropic.")) return "anthropic";
+  if (name.startsWith("gemini")) return "google";
+  if (get(usage, "prompt_tokens") === void 0 && get(usage, "cache_read_input_tokens") !== void 0) {
+    return "anthropic";
+  }
+  return "openai";
+}
+function modelUsage(response, options = {}) {
+  try {
+    let usage = get(response, "usage");
+    if (usage === void 0 || usage === null || typeof usage !== "object") usage = response;
+    const counts = tokenCounts(usage);
+    const name = options.model ?? get(response, "model");
+    if (!counts || typeof name !== "string" || !MODEL.test(name)) return null;
+    const provider = (options.provider ?? providerOf(name, usage)).toLowerCase();
+    if (!PROVIDER.test(provider)) return null;
+    return { provider, model: name, ...counts };
+  } catch {
+    return null;
+  }
+}
+function asModelUsage(value) {
+  if (value === void 0 || value === null) return null;
+  if (isModelUsage(value)) return value;
+  return modelUsage(value);
+}
+function isModelUsage(value) {
+  const provider = get(value, "provider");
+  const model = get(value, "model");
+  const prompt = count(get(value, "prompt_tokens"));
+  const cached = get(value, "cached_tokens") === void 0 ? 0 : count(get(value, "cached_tokens"));
+  const written = get(value, "cache_write_tokens") === void 0 ? 0 : count(get(value, "cache_write_tokens"));
+  return typeof provider === "string" && PROVIDER.test(provider) && typeof model === "string" && MODEL.test(model) && prompt !== null && cached !== null && written !== null && cached + written <= prompt;
+}
+
 // src/conversation.ts
 var Conversation = class {
   constructor(client, params, hooks) {
@@ -738,6 +822,8 @@ var Conversation = class {
     if (options.visibility) event.visibility = options.visibility;
     if (options.voice) event.voice = options.voice;
     if (options.context_stamp) event.context_stamp = options.context_stamp;
+    const usage = role === "ai_agent" ? asModelUsage(options.usage) : null;
+    if (usage) event.usage = usage;
     return this.client.track(event);
   }
 };
@@ -881,6 +967,7 @@ var DEFAULT_CACHE = {
 var DEFAULT_QUEUE = {
   flushAt: 15,
   flushIntervalMs: 1e3,
+  turnFlushIntervalMs: 200,
   maxBatchSize: 100,
   maxQueueSize: 1e4,
   maxAttempts: 3,
@@ -904,6 +991,7 @@ var EventQueue = class {
   now;
   items = [];
   timer = null;
+  timerDueAt = Number.POSITIVE_INFINITY;
   tail = Promise.resolve();
   closed = false;
   droppedSinceWarning = 0;
@@ -928,7 +1016,8 @@ var EventQueue = class {
     if (this.items.length >= this.options.flushAt) {
       this.flushInBackground();
     } else {
-      this.schedule();
+      const { flushIntervalMs, turnFlushIntervalMs } = this.options;
+      this.schedule(isTurn(item) ? Math.min(turnFlushIntervalMs, flushIntervalMs) : flushIntervalMs);
     }
     return true;
   }
@@ -1018,20 +1107,29 @@ var EventQueue = class {
     this.sentInWindow = 0;
     return item;
   }
-  schedule() {
-    if (this.timer !== null) return;
+  /** Sends what is waiting in `delayMs`, unless a send is already due sooner. */
+  schedule(delayMs) {
+    const dueAt = this.now() + delayMs;
+    if (this.timer !== null && this.timerDueAt <= dueAt) return;
+    this.cancelTimer();
+    this.timerDueAt = dueAt;
     this.timer = setTimeout(() => {
       this.timer = null;
+      this.timerDueAt = Number.POSITIVE_INFINITY;
       this.flushInBackground();
-    }, this.options.flushIntervalMs);
+    }, delayMs);
     unref(this.timer);
   }
   cancelTimer() {
     if (this.timer === null) return;
     clearTimeout(this.timer);
     this.timer = null;
+    this.timerDueAt = Number.POSITIVE_INFINITY;
   }
 };
+function isTurn(item) {
+  return item.type === "event" && item.kind === "message" && Boolean(item.conversation_id);
+}
 function unref(timer) {
   if (typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function") {
     timer.unref();
@@ -1108,6 +1206,8 @@ var Task = class {
     if (options.idempotency_key) event.idempotency_key = options.idempotency_key;
     if (options.occurred_at) event.occurred_at = options.occurred_at;
     if (options.visibility) event.visibility = options.visibility;
+    const usage = asModelUsage(options.usage);
+    if (usage) event.usage = usage;
     return this.track(event);
   }
   /**
@@ -1179,7 +1279,7 @@ var TOOL_NAMES = {
   timeline: "get_customer_timeline",
   open: "open_history_item"
 };
-var ITEM_KINDS = ["episode", "fact", "open_item", "action", "system_event", "object", "trait"];
+var ITEM_KINDS = ["episode", "fact", "open_item", "action", "object", "trait"];
 var period = {
   since: { type: "string", format: "date-time", description: "Only items at or after this ISO 8601 time." },
   until: { type: "string", format: "date-time", description: "Only items before this ISO 8601 time." },
@@ -1199,7 +1299,7 @@ var TOOL_DEFINITIONS = [
     type: "function",
     function: {
       name: TOOL_NAMES.search,
-      description: "Search this customer's past conversations, actions and system events by meaning and keywords. Use it when the customer refers to something that happened before and the details are not in the customer context you already have. Do not use it for facts already listed there. The result also says how often the same kind of issue came back. To read one result in full, call open_history_item.",
+      description: "Search this customer's past conversations, actions and business objects by meaning and keywords. Use it when the customer refers to something that happened before and the details are not in the customer context you already have. Do not use it for facts already listed there. The result also says how often the same kind of issue came back. To read one result in full, call open_history_item.",
       parameters: {
         type: "object",
         properties: {
@@ -1217,7 +1317,7 @@ var TOOL_DEFINITIONS = [
     type: "function",
     function: {
       name: TOOL_NAMES.timeline,
-      description: "List this customer's history in chronological order, one line per item. Use it when you need the sequence of events, for example what happened since a given date. Prefer search_customer_history when you are looking for something specific.",
+      description: "List this customer's history, newest first, one line per item. Use it when you need the sequence of events, for example what happened since a given date. Prefer search_customer_history when you are looking for something specific.",
       parameters: {
         type: "object",
         properties: {
@@ -1311,7 +1411,7 @@ function bindTools(subject, binding, navigator, strict) {
       case TOOL_NAMES.open: {
         const id = str(args, "id");
         if (!id) throw new NiadraValidationError("open_history_item needs an id");
-        return navigator.open(id, binding, voice);
+        return navigator.open(id, subject, binding, voice);
       }
       default:
         throw new NiadraValidationError(`unknown tool: ${name}`);
@@ -1350,7 +1450,7 @@ function cloneDefinition(definition) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 
 // src/transport.ts
 var RETRYABLE_WRITE_STATUS = /* @__PURE__ */ new Set([408, 421, 429, 500, 502, 503, 504]);
@@ -1403,13 +1503,17 @@ var Transport = class {
     );
   }
   async retrying(timeoutMs, policy, signal, attempt) {
-    for (let count = 1; ; count++) {
-      const deadline = new Deadline(timeoutMs, signal);
+    const end = policy.totalMs === void 0 ? Number.POSITIVE_INFINITY : Date.now() + policy.totalMs;
+    for (let count2 = 1; ; count2++) {
+      const left = end - Date.now();
+      if (left <= 0) throw new NiadraTimeoutError(policy.totalMs ?? timeoutMs);
+      const deadline = new Deadline(Math.min(timeoutMs, left), signal);
       try {
         return await attempt(deadline);
       } catch (error) {
-        if (count >= policy.maxAttempts || !isTransient(error)) throw error;
-        const delay = retryDelay(error, count, policy.baseDelayMs, policy.maxDelayMs);
+        if (count2 >= policy.maxAttempts || !isTransient(error)) throw error;
+        const delay = retryDelay(error, count2, policy.baseDelayMs, policy.maxDelayMs);
+        if (Date.now() + delay >= end) throw error;
         await sleep(delay, signal);
       } finally {
         deadline.clear();
@@ -1560,9 +1664,13 @@ function sleep(ms, signal) {
 
 // src/client.ts
 function readEnv(name) {
-  const env = globalThis.process?.env;
-  const value = env?.[name];
-  return value === "" ? void 0 : value;
+  try {
+    const env = globalThis.process?.env;
+    const value = env?.[name];
+    return value === "" ? void 0 : value;
+  } catch {
+    return void 0;
+  }
 }
 function describe(error) {
   if (error instanceof NiadraAPIError) {
@@ -1702,7 +1810,7 @@ var Niadra = class {
       return this.readSpec("POST", "/v1/history/search", params, this.timeouts.navigation, options);
     });
   }
-  /** 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. */
   async timeline(params, options = {}) {
     return this.navigate(
       () => this.readSpec("POST", "/v1/history/timeline", params, this.timeouts.navigation, options)
@@ -1710,20 +1818,17 @@ var Niadra = class {
   }
   /**
    * 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.
    */
   async open(id, params = {}, options = {}) {
     return this.navigate(() => {
       if (!id) throw new NiadraValidationError("open() needs an item id");
-      const path = `/v1/history/items/${encodeURIComponent(id)}`;
-      const spec = this.readSpec("GET", path, void 0, this.timeouts.navigation, options);
-      spec.query = {
-        verification: params.verification,
-        conversation_id: params.conversation_id,
-        task_id: params.task_id
-      };
-      return spec;
+      const body = { item_id: id };
+      if (params.subject) body.subject = params.subject;
+      if (params.verification) body.verification = params.verification;
+      if (params.conversation_id) body.conversation_id = params.conversation_id;
+      return this.readSpec("POST", "/v1/history/open", body, this.timeouts.navigation, options);
     });
   }
   /**
@@ -1764,11 +1869,10 @@ var Niadra = class {
     const navigator = {
       search: (params, voice) => this.search(params, this.voiceBudget(voice)),
       timeline: (params, voice) => this.timeline(params, this.voiceBudget(voice)),
-      open: (id, bound, voice) => {
-        const scope = {};
+      open: (id, customer, bound, voice) => {
+        const scope = { subject: customer };
         if (bound.verification) scope.verification = bound.verification;
         if (bound.conversation_id) scope.conversation_id = bound.conversation_id;
-        if (bound.task_id) scope.task_id = bound.task_id;
         return this.open(id, scope, this.voiceBudget(voice));
       }
     };
@@ -1831,7 +1935,7 @@ var Niadra = class {
         body: request,
         headers: { "idempotency-key": key },
         timeoutMs: this.timeouts.write,
-        retry: core.writes
+        retry: { ...core.writes, totalMs: this.timeouts.write }
       });
       const [rejected] = response.data?.errors ?? [];
       if (rejected) {
@@ -1862,7 +1966,7 @@ var Niadra = class {
         path: "/v1/media/uploads",
         body: request,
         timeoutMs: this.timeouts.write,
-        retry: core.writes,
+        retry: { ...core.writes, totalMs: this.timeouts.write },
         signal: options.signal
       });
       const media_ref = reserved.data?.media_ref;
@@ -1875,7 +1979,7 @@ var Niadra = class {
           body: bytes,
           headers: uploadHeaders(reserved.data?.upload_headers, request.content_type),
           timeoutMs: this.timeouts.upload,
-          retry: core.writes,
+          retry: { ...core.writes, totalMs: this.timeouts.upload },
           signal: options.signal
         });
       }
@@ -2062,11 +2166,20 @@ var Niadra = class {
     }
     return new Promise((resolve, reject) => {
       const key = item.idempotency_key;
-      core.queue.push(item, (error) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        this.logger.warn(`write not confirmed within ${this.timeouts.write} ms; it stays queued`);
+        settle(new NiadraTimeoutError(this.timeouts.write));
+      }, this.timeouts.write);
+      const settle = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
         if (!error) resolve({ ok: true, idempotency_key: key, error: null });
         else if (this.strict) reject(error);
         else resolve({ ok: false, idempotency_key: key, error });
-      });
+      };
+      core.queue.push(item, settle);
       core.queue.flushInBackground();
     });
   }
@@ -2253,22 +2366,22 @@ var Answer = class {
   parsed(value) {
     try {
       if (!this.stream) {
-        this.record(messageText(value));
+        this.record(messageText(value), modelUsage(value));
         return value;
       }
-      return isAsyncIterable(value) ? captureStream(value, (text) => {
-        this.record(text);
+      return isAsyncIterable(value) ? captureStream(value, (text, usage) => {
+        this.record(text, usage);
       }) : value;
     } catch (error) {
       this.session.logger.warn(`could not capture the model's answer (${errorName(error)})`);
       return value;
     }
   }
-  record(text) {
+  record(text, usage) {
     if (this.recorded || !text) return;
     this.recorded = true;
     try {
-      this.session.agent(text);
+      this.session.agent(text, usage ? { usage } : {});
     } catch (error) {
       this.session.logger.warn(`could not record the model's answer (${errorName(error)})`);
     }
@@ -2276,11 +2389,19 @@ var Answer = class {
 };
 function captureStream(stream, done) {
   const parts = [];
+  let usage = null;
+  let model;
   let finished = false;
+  const observe = (chunk) => {
+    const reported = property(chunk, "usage");
+    if (isRecord(reported)) usage = reported;
+    const name = property(chunk, "model");
+    if (typeof name === "string" && name) model = name;
+  };
   const finish = () => {
     if (finished) return;
     finished = true;
-    done(parts.join(""));
+    done(parts.join(""), usage ? modelUsage(usage, model ? { model } : {}) : null);
   };
   return new Proxy(stream, {
     get(target, prop) {
@@ -2292,7 +2413,10 @@ function captureStream(stream, done) {
               try {
                 const step = await inner.next();
                 if (step.done) finish();
-                else parts.push(deltaText(step.value));
+                else {
+                  parts.push(deltaText(step.value));
+                  observe(step.value);
+                }
                 return step;
               } catch (error) {
                 finish();
@@ -2378,11 +2502,14 @@ exports.baseURLFromKey = baseURLFromKey;
 exports.consoleLogger = consoleLogger;
 exports.handles = handles;
 exports.injectContext = injectContext;
+exports.modelUsage = modelUsage;
 exports.parseApiKey = parseApiKey;
+exports.providerOf = providerOf;
 exports.renderLive = renderLive;
 exports.renderSuffix = renderSuffix;
 exports.silentLogger = silentLogger;
 exports.toObjectRef = toObjectRef;
+exports.tokenCounts = tokenCounts;
 exports.uuidv7 = uuidv7;
 exports.wrap = wrap;
 //# sourceMappingURL=index.cjs.map