@niadra/sdk 0.9.0 → 0.10.3

package/dist/index.js

@@ -4,6 +4,46 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/ids.ts
+var lastMs = -1;
+var counter = 0;
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues) {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return bytes;
+}
+function uuidv7(now = Date.now()) {
+  let ms = now;
+  if (ms <= lastMs) {
+    ms = lastMs;
+    counter = counter + 1 & 4095;
+    if (counter === 0) ms += 1;
+  } else {
+    counter = (randomBytes(2)[0] ?? 0) & 127;
+  }
+  lastMs = ms;
+  const bytes = randomBytes(16);
+  const high = Math.floor(ms / 2 ** 16);
+  const low = ms % 2 ** 16;
+  bytes[0] = high >>> 24 & 255;
+  bytes[1] = high >>> 16 & 255;
+  bytes[2] = high >>> 8 & 255;
+  bytes[3] = high & 255;
+  bytes[4] = low >>> 8 & 255;
+  bytes[5] = low & 255;
+  bytes[6] = 112 | counter >>> 8 & 15;
+  bytes[7] = counter & 255;
+  bytes[8] = 128 | (bytes[8] ?? 0) & 63;
+  let hex2 = "";
+  for (const byte of bytes) hex2 += byte.toString(16).padStart(2, "0");
+  return `${hex2.slice(0, 8)}-${hex2.slice(8, 12)}-${hex2.slice(12, 16)}-${hex2.slice(16, 20)}-${hex2.slice(20)}`;
+}
+
 // src/errors.ts
 var NiadraError = class extends Error {
   name = "NiadraError";
@@ -47,11 +87,12 @@ var NiadraAPIError = class extends NiadraError {
   constructor(status, problem, requestId, retryAfterMs = null) {
     const code = problem?.code ?? `http_${status}`;
     const detail = problem?.detail ? `: ${problem.detail}` : "";
-    super(`${status} ${code}${detail}`);
+    const id = requestId ?? problem?.request_id ?? null;
+    super(`${status} ${code}${detail}${id ? ` (request ${id})` : ""}`);
     this.status = status;
     this.code = code;
     this.problem = problem;
-    this.requestId = requestId ?? problem?.request_id ?? null;
+    this.requestId = id;
     this.retryAfterMs = retryAfterMs;
   }
 };
@@ -75,45 +116,11 @@ function toNiadraError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new NiadraError(message, { cause: error });
 }
-
-// src/ids.ts
-var lastMs = -1;
-var counter = 0;
-function randomBytes(length) {
-  const bytes = new Uint8Array(length);
-  const webCrypto = globalThis.crypto;
-  if (webCrypto?.getRandomValues) {
-    webCrypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < length; i++) bytes[i] = Math.floor(Math.random() * 256);
-  }
-  return bytes;
-}
-function uuidv7(now = Date.now()) {
-  let ms = now;
-  if (ms <= lastMs) {
-    ms = lastMs;
-    counter = counter + 1 & 4095;
-    if (counter === 0) ms += 1;
-  } else {
-    counter = (randomBytes(2)[0] ?? 0) & 127;
-  }
-  lastMs = ms;
-  const bytes = randomBytes(16);
-  const high = Math.floor(ms / 2 ** 16);
-  const low = ms % 2 ** 16;
-  bytes[0] = high >>> 24 & 255;
-  bytes[1] = high >>> 16 & 255;
-  bytes[2] = high >>> 8 & 255;
-  bytes[3] = high & 255;
-  bytes[4] = low >>> 8 & 255;
-  bytes[5] = low & 255;
-  bytes[6] = 112 | counter >>> 8 & 15;
-  bytes[7] = counter & 255;
-  bytes[8] = 128 | (bytes[8] ?? 0) & 63;
-  let hex2 = "";
-  for (const byte of bytes) hex2 += byte.toString(16).padStart(2, "0");
-  return `${hex2.slice(0, 8)}-${hex2.slice(8, 12)}-${hex2.slice(12, 16)}-${hex2.slice(16, 20)}-${hex2.slice(20)}`;
+function explain(error) {
+  if (!(error instanceof NiadraAPIError)) return error instanceof Error ? error.name : String(error);
+  const detail = error.problem?.detail?.trim();
+  const said = `${error.status} ${error.code}${detail ? `: ${detail.slice(0, 300)}` : ""}`;
+  return error.requestId ? `${said} (request ${error.requestId})` : said;
 }
 
 // src/admin.ts
@@ -516,7 +523,7 @@ function internalRecord(span, ref, act) {
 }
 
 // src/version.ts
-var VERSION = "0.9.0";
+var VERSION = "0.10.3";
 
 // src/transport.ts
 var RETRYABLE_WRITE_STATUS = /* @__PURE__ */ new Set([408, 421, 429, 500, 502, 503, 504]);
@@ -529,8 +536,32 @@ var Transport = class {
   }
   config;
   baseURL;
+  answeredAt;
+  /** When the allowance was first given since the last answer; it holds for the calls of that moment only. */
+  grantedAt;
+  /** When the client last sent a request of its own (`RequestSpec.activity`), in epoch milliseconds. */
+  lastActivityAt;
   async request(spec) {
-    return spec.retry.kind === "read" ? this.read(spec, spec.retry) : this.write(spec, spec.retry);
+    if (spec.activity !== false) this.lastActivityAt = Date.now();
+    const budgeted = this.withAllowance(spec);
+    return budgeted.retry.kind === "read" ? this.read(budgeted, budgeted.retry) : this.write(budgeted, budgeted.retry);
+  }
+  /**
+   * `spec` with the allowance for opening a connection, when it has a budget and none is likely open. The calls
+   * that start while the first one opens it get it too; after that, none does until an answer comes, so an
+   * outage costs the allowance once, not on every turn.
+   */
+  withAllowance(spec) {
+    const allowance = this.config.coldAllowanceMs ?? 0;
+    const { retry } = spec;
+    if (allowance <= 0 || retry.kind === "write" && retry.totalMs === void 0) return spec;
+    const now = Date.now();
+    const keep = this.config.keepAliveMs ?? 0;
+    if (this.answeredAt !== void 0 && now - this.answeredAt <= keep) return spec;
+    this.grantedAt ??= now;
+    if (now - this.grantedAt > allowance) return spec;
+    const total = retry.kind === "write" && retry.totalMs !== void 0 ? { ...retry, totalMs: retry.totalMs + allowance } : retry;
+    return { ...spec, timeoutMs: spec.timeoutMs + allowance, retry: total };
   }
   async read(spec, policy) {
     const deadline = new Deadline(spec.timeoutMs, spec.signal);
@@ -601,7 +632,18 @@ var Transport = class {
       headers["content-type"] = "application/json";
       init.body = JSON.stringify(spec.body);
     }
-    return this.exchange(this.url(spec.path, spec.query), init, deadline);
+    try {
+      const answer = await this.exchange(this.url(spec.path, spec.query), init, deadline);
+      this.answered();
+      return answer;
+    } catch (error) {
+      if (error instanceof NiadraAPIError) this.answered();
+      throw error;
+    }
+  }
+  answered() {
+    this.answeredAt = Date.now();
+    this.grantedAt = void 0;
   }
   async exchange(url, init, deadline) {
     let response;
@@ -610,6 +652,7 @@ var Transport = class {
     } catch (error) {
       throw deadline.explain(error);
     }
+    warnIfDeprecated(this.config.logger, init.method ?? "GET", url, response.headers);
     const requestId = response.headers.get("x-request-id");
     let payload;
     try {
@@ -679,6 +722,29 @@ var Deadline = class {
     return new NiadraConnectionError(`connection failed: ${message}`, { cause: error });
   }
 };
+var VERSIONING_DOCS = "https://docs.niadra.com/en/security/api-versioning";
+var DEPRECATION_LINK = /<([^>]*)>[^,]*;\s*rel="?deprecation"?/gi;
+var deprecationsSeen = /* @__PURE__ */ new Set();
+function warnIfDeprecated(logger, method, url, headers) {
+  const since = headers.get("deprecation");
+  if (since === null) return;
+  const links = [...(headers.get("link") ?? "").matchAll(DEPRECATION_LINK)].map((match) => match[1] ?? "");
+  const key2 = `${method} ${links.join(" ") || (url.split("?")[0] ?? url)}`;
+  if (deprecationsSeen.has(key2)) return;
+  deprecationsSeen.add(key2);
+  const sunset = headers.get("sunset");
+  logger.warn(
+    `the API deprecated a ${method} route this client calls, since ${deprecatedSince(since)}; it stops answering on ${sunset === null ? "a date not announced yet" : sunsetDay(sunset)}. See ${links.join(", ") || VERSIONING_DOCS}`
+  );
+}
+function deprecatedSince(value) {
+  const seconds = Number(value.trim().replace(/^@/, ""));
+  return Number.isInteger(seconds) ? new Date(seconds * 1e3).toISOString().slice(0, 10) : value;
+}
+function sunsetDay(value) {
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? value : new Date(time).toISOString().slice(0, 10);
+}
 async function readBody(response) {
   const text2 = await response.text();
   if (text2.length === 0) return null;
@@ -4018,8 +4084,7 @@ var TurnSender = class {
         return true;
       }
     }
-    const code = error instanceof NiadraAPIError ? error.code : toNiadraError(error).name;
-    this.recorder.rejected(batch.frames.length, [code]);
+    this.recorder.rejected(batch.frames.length, [explain(error)]);
     return true;
   }
   accepted(batch, answer) {
@@ -4027,8 +4092,8 @@ var TurnSender = class {
     this.resumeAt = 0;
     this.recorder.sent(answer.accepted, answer.duplicates);
     const again = [];
-    const codes2 = /* @__PURE__ */ new Set();
-    let refused2 = 0;
+    const reasons = /* @__PURE__ */ new Set();
+    let refused3 = 0;
     for (const error of answer.errors ?? []) {
       const frame = batch.frames[error.index];
       if (frame === void 0) continue;
@@ -4037,12 +4102,12 @@ var TurnSender = class {
         this.recorder.modeRefused();
         again.push(frame);
       } else {
-        refused2++;
-        codes2.add(error.code);
+        refused3++;
+        reasons.add(error.detail ? `${error.code}: ${error.detail.slice(0, 300)}` : error.code);
       }
     }
     if (again.length > 0) this.queue.requeue(again);
-    if (refused2 > 0) this.recorder.rejected(refused2, [...codes2]);
+    if (refused3 > 0) this.recorder.rejected(refused3, [...reasons]);
   }
 };
 
@@ -4164,9 +4229,12 @@ var TurnRecorder = class {
     this.accepted += accepted;
     this.duplicates += duplicates;
   }
-  rejected(count3, codes2) {
+  /** `reasons`: the API's code and detail of each refusal (field paths and rules, never a value). */
+  rejected(count3, reasons) {
     this.rejectedTurns += count3;
-    this.logger.warn(`${count3} turn records were refused (${[...codes2].sort().join(", ")})`);
+    const shown = [...new Set(reasons)].sort();
+    const more = shown.length > 3 ? ` (and ${shown.length - 3} more)` : "";
+    this.logger.warn(`${count3} turn records were refused: ${shown.slice(0, 3).join("; ")}${more}`);
   }
   /** The space does not record turns: these are dropped, and with `off` (a 404) recording stops a while. */
   notRecorded(count3, off) {
@@ -4236,6 +4304,10 @@ async function hex(text2) {
 }
 
 // src/coordination/client.ts
+var REFUSED = /* @__PURE__ */ new Set([400, 401, 403, 422]);
+function refused(error) {
+  return error instanceof NiadraAPIError && REFUSED.has(error.status);
+}
 var FAIL_CLOSED = /* @__PURE__ */ new Set(["marketing", "retention", "collection"]);
 var CHECK_BUDGET_MS = 200;
 function fallback(request, suppressed, failOpen) {
@@ -4257,15 +4329,22 @@ function claimed(data, error) {
   return { held: false, claim: null, error: code };
 }
 var Coordinator = class {
-  constructor(outbox, suppressions, declareNow) {
+  constructor(outbox, suppressions, declareNow, logger) {
     this.outbox = outbox;
     this.suppressions = suppressions;
     this.declareNow = declareNow;
+    this.logger = logger;
   }
   outbox;
   suppressions;
   declareNow;
+  logger;
   async failed(request, failOpen, error) {
+    if (refused(error)) {
+      this.logger?.warn(`the coordination check was refused: ${explain(error)}`);
+      const decision = request.direction === "inbound" ? "allow" : "defer";
+      return recorded({ decision, decision_id: uuidv7(), reasons: ["invalid_request"], valid_for_s: 0 });
+    }
     const off = error instanceof NiadraAPIError && error.status === 404;
     const suppressed = request.subject != null && request.direction === "outbound" ? !await this.suppressions.mayContact(request.subject, request.purpose, { channel: request.channel ?? null, failOpen: true }) : false;
     const plain2 = off ? { ...request, effect_key: null } : request;
@@ -4286,7 +4365,7 @@ var Coordinator = class {
     if (who.subject) body.subject = who.subject;
     if (who.object) body.object = who.object;
     const key2 = uuidv7();
-    this.outbox.put({ send: () => this.declareNow(body, key2) });
+    this.outbox.put({ send: () => this.declareNow(body, key2), route: "POST /v1/coordination/declare" });
     return key2;
   }
 };
@@ -4393,26 +4472,42 @@ async function suppressionKey(salt, canonical2) {
   const key2 = await subtle.importKey("raw", saltBytes(salt), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
   return toBase64url(new Uint8Array(await subtle.sign("HMAC", key2, new TextEncoder().encode(canonical2))));
 }
+var AREA_CODES = new Set(
+  "11 12 13 14 15 16 17 18 19 21 22 24 27 28 31 32 33 34 35 37 38 41 42 43 44 45 46 47 48 49 51 53 54 55 61 62 63 64 65 66 67 68 69 71 73 74 75 77 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99".split(" ")
+);
+var FORMAT_CHARACTERS = /\p{Cf}/gu;
 function phone(value) {
-  const raw = value.trim().replace(SEPARATORS2, "");
-  const international = raw.startsWith("+") || raw.startsWith("00");
+  let text2 = value.normalize("NFKC").replace(FORMAT_CHARACTERS, "").trim();
+  if (text2.slice(0, 4).toLowerCase() === "tel:") text2 = text2.slice(4);
+  const international = text2.startsWith("+") || text2.startsWith("00");
+  if (international) text2 = text2.replaceAll("(0)", "");
+  const raw = text2.replace(SEPARATORS2, "");
   let digits = raw.startsWith("+") ? raw.slice(1) : international ? raw.slice(2) : raw;
   if (!DIGITS2.test(digits)) throw new NiadraDestinationError("invalid_handle");
-  const national = digits.replace(/^0+/, "");
-  if (!international && (national.length === 10 || national.length === 11) && isArea(national.slice(0, 2))) {
-    digits = `55${national}`;
+  if (!international) {
+    const national = digits.replace(/^0+/, "");
+    if (isBrazilianNational(national)) {
+      digits = `55${national}`;
+    } else if (digits.startsWith("0") && (national.length === 12 || national.length === 13)) {
+      if (isBrazilianNational(national.slice(2))) digits = `55${national.slice(2)}`;
+    }
   }
   if (digits.length < 8 || digits.length > 15 || digits.startsWith("0")) {
     throw new NiadraDestinationError("invalid_handle");
   }
   const rest = digits.slice(2);
-  if (digits.startsWith("55") && rest.length === 10 && isArea(rest.slice(0, 2)) && "6789".includes(rest.charAt(2))) {
+  if (digits.startsWith("55") && rest.length === 10 && AREA_CODES.has(rest.slice(0, 2)) && "6789".includes(rest.charAt(2))) {
     digits = `55${rest.slice(0, 2)}9${rest.slice(2)}`;
   }
+  if (digits.length === 13 && (digits.startsWith("521") || digits.startsWith("549"))) {
+    digits = digits.slice(0, 2) + digits.slice(3);
+  }
   return `phone:+${digits}`;
 }
-function isArea(code) {
-  return /^[1-9]{2}$/.test(code);
+function isBrazilianNational(national) {
+  if (!AREA_CODES.has(national.slice(0, 2))) return false;
+  if (national.length === 10) return "23456789".includes(national.charAt(2));
+  return national.length === 11 && national.charAt(2) === "9";
 }
 function saltBytes(salt) {
   const bytes = fromBase64url(salt);
@@ -4789,7 +4884,7 @@ var Outbox = class {
         return false;
       }
       this.writes.shift();
-      this.logger.warn(`a write was refused (${error instanceof NiadraAPIError ? error.code : String(error)})`);
+      this.logger.warn(`${write.route ?? "a write"} was refused: ${explain(error)}`);
       this.settle(write, void 0, error);
       return true;
     }
@@ -5679,9 +5774,17 @@ var handles = {
   appUserId: (value, options) => build("app_user_id", value, void 0, options),
   /** The id of a person or organization in a system of record; `system` names that system, such as `crm`. */
   systemId: (value, system, options) => build("system_id", value, system, options),
-  /** An HMAC of a national document number; `country` is its ISO 3166-1 alpha-2 code. */
+  /**
+   * A person's national document, such as a CPF: `govIdHmac("529.982.247-25", "BR")`. Send the number
+   * itself, never a hash of it: the server checks its check digits, then keeps only a keyed hash with your
+   * space's secret and an encrypted copy, and shows it masked. `country` is its ISO 3166-1 alpha-2 code.
+   */
   govIdHmac: (value, country, options) => build("gov_id_hmac", value, country, options),
-  /** An HMAC of a company registry number. Identifies an organization. */
+  /**
+   * A company's registry number, such as a CNPJ: `orgRegistryHmac("11.222.333/0001-81", "BR")`. As with
+   * `govIdHmac`, send the number itself; the server checks it and keeps only a keyed hash. Identifies an
+   * organization.
+   */
   orgRegistryHmac: (value, country) => build("org_registry_hmac", value, country, { subjectKind: "account" }),
   /** An e-mail domain, such as `acme.com`. Identifies an organization. */
   emailDomain: (domain) => build("email_domain", domain, void 0, { subjectKind: "account" }),
@@ -6355,6 +6458,7 @@ var AgentSession = class {
     try {
       return this.host.coordinator.decided(await this.host.check(request, options.timeoutMs ?? CHECK_BUDGET_MS), request, this.checked);
     } catch (error) {
+      if (this.host.strict && refused(error)) throw error;
       return this.host.coordinator.failed(request, options.failOpen, error);
     }
   }
@@ -6966,6 +7070,7 @@ var SessionState = class {
   /** The guards of the last read: they hold the answers to the turn they were written for. */
   guards = /* @__PURE__ */ new Map();
   lastReport = null;
+  unlinkedSaid = false;
   /** After the first pack, every read also asks what changed since. */
   get wantsDelta() {
     return this.etag !== null;
@@ -6994,6 +7099,19 @@ var SessionState = class {
     this.last = absorbed;
     return absorbed;
   }
+  /**
+   * Once per session: the read named an organization (`about`) with no active link to the subject, so it went
+   * on with the subject's own memory, never the organization's.
+   */
+  sayUnlinked(result2, logger) {
+    if (result2.response?.about_unlinked && !this.unlinkedSaid) {
+      this.unlinkedSaid = true;
+      logger.warn(
+        "`about` names an organization with no active link to the subject; the context is the subject's own, without that organization's memory. Create the link to read it."
+      );
+    }
+    return result2;
+  }
   /** The last backing check of an agent's answer. */
   get lastBacking() {
     return this.lastReport;
@@ -7241,7 +7359,7 @@ var Conversation = class {
    * `query` picks this read's slots by other words than the turn; the pack is the pinned one.
    */
   async context(options = {}) {
-    const { query, turn, format, explain, include, ...requestOptions } = options;
+    const { query, turn, format, explain: explain2, include, ...requestOptions } = options;
     const params = {
       subject: this.subject,
       view: this.view,
@@ -7250,7 +7368,7 @@ var Conversation = class {
       ...this.params.about ? { about: this.params.about } : {},
       ...this.params.target ? { target: this.params.target } : {},
       ...format === "json" ? { format } : {},
-      ...explain ? { explain } : {}
+      ...explain2 ? { explain: explain2 } : {}
     };
     if (query) params.query = query;
     if (include?.length) params.include = include;
@@ -7258,7 +7376,7 @@ var Conversation = class {
     params.turn = turn === void 0 ? this.turnText : turn;
     const result2 = await this.client.context(params, requestOptions);
     this.features.observe(result2);
-    return this.state.observe(this.state.absorb(result2));
+    return this.state.observe(this.state.sayUnlinked(this.state.absorb(result2), this.logger));
   }
   /**
    * Starts this conversation's first read now, in the background: call it when the call starts
@@ -7438,6 +7556,35 @@ function withHandles(base, extra) {
   return all;
 }
 
+// src/warm.ts
+var EVERY_MS = 1e5;
+var IDLE_MS = 9e4;
+var WARM_FOR_MS = 6e5;
+var KeepWarm = class {
+  constructor(enabled) {
+    this.enabled = enabled;
+  }
+  enabled;
+  open = /* @__PURE__ */ new Map();
+  openedAt = 0;
+  /** Notes an open conversation or task. */
+  add(scope, session, now) {
+    if (!this.enabled || typeof WeakRef === "undefined") return;
+    this.open.set(scope, new WeakRef(session));
+    this.openedAt = now;
+  }
+  /** The conversation or task ended. */
+  end(scope) {
+    this.open.delete(scope);
+  }
+  step(now, lastActivityAt, idleMs = IDLE_MS, warmForMs = WARM_FOR_MS) {
+    for (const [scope, ref] of this.open) if (ref.deref() === void 0) this.open.delete(scope);
+    const used = Math.max(lastActivityAt ?? 0, this.openedAt);
+    if (this.open.size === 0 || now - used > warmForMs) return "stop";
+    return now - used >= idleMs ? "ping" : "wait";
+  }
+};
+
 // src/exit.ts
 var registered = /* @__PURE__ */ new Set();
 var installedOn = null;
@@ -7568,8 +7715,10 @@ var DEFAULT_TIMEOUTS = {
   write: 5e3,
   token: 2e3,
   upload: 6e4,
-  prefetch: 1e3
+  prefetch: 1e3,
+  connect: 1e3
 };
+var FETCH_KEEPALIVE_MS = 4e3;
 var DEFAULT_CACHE = {
   ttlMs: 1e4,
   staleWhileRevalidateMs: 10 * 6e4,
@@ -7676,7 +7825,7 @@ var Task = class {
    * Resolves with an empty result, never rejects, unless the client is strict.
    */
   async context(options = {}) {
-    const { query, format, explain, include, ...requestOptions } = options;
+    const { query, format, explain: explain2, include, ...requestOptions } = options;
     const target = this.object ? { object: this.object } : this.params.subject ? { subject: this.params.subject } : {};
     const params = {
       ...target,
@@ -7686,18 +7835,18 @@ var Task = class {
       ...this.level ? { verification: this.level } : {},
       ...this.params.target ? { target: this.params.target } : {},
       ...format === "json" ? { format } : {},
-      ...explain ? { explain } : {},
+      ...explain2 ? { explain: explain2 } : {},
       ...include?.length ? { include } : {}
     };
     if (query) {
       const answered = await this.client.context({ ...params, query }, requestOptions);
       this.features.observe(answered);
-      return this.state.observe(answered);
+      return this.state.observe(this.state.sayUnlinked(answered, this.logger));
     }
     if (this.state.wantsDelta) params.delta = true;
     const result2 = await this.client.context(params, requestOptions);
     this.features.observe(result2);
-    return this.state.observe(this.state.absorb(result2));
+    return this.state.observe(this.state.sayUnlinked(this.state.absorb(result2), this.logger));
   }
   /**
    * The agent's own working notes for this task's prompt, as `niadra.agentMemory()` with
@@ -7827,14 +7976,14 @@ var AGENT_MEMORY_TOOL_NAMES = {
   search: "search_agent_memory",
   remember: "remember"
 };
-var ITEM_KINDS = ["episode", "fact", "open_item", "action", "object", "trait"];
+var ITEM_KINDS = ["episode", "fact", "open_item", "action", "object", "trait", "system_event"];
 var NOTE_KINDS = ["procedure", "tool_note", "process_note", "pitfall"];
 var TOOL_DEFINITIONS = [
   {
     "type": "function",
     "function": {
       "name": "search_customer_history",
-      "description": "Search everything that already happened with this customer: past conversations, promises, agent actions, orders and invoices. Use it when the customer refers to something earlier or asks whether a problem happened before. Do not call it when the answer is already in the context block, including its 'Do hist\xF3rico' line, which already counts recurrences. Returns short items with date, channel and outcome, plus a recurrence count. Open one with open_history_item.",
+      "description": "Search everything that already happened with this customer: past conversations, promises, agent actions, orders and invoices. Use it when the customer refers to something earlier or asks whether a problem happened before. Do not call it when the answer is already in the context block, including its 'Hist\xF3rico' line, which already counts recurrences. Returns short items with date, channel and outcome, plus a recurrence count. Open a conversation (`episode:`) or an object (`object:`) with open_history_item; the other items are complete as listed.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -7878,7 +8027,8 @@ var TOOL_DEFINITIONS = [
                     "open_item",
                     "action",
                     "object",
-                    "trait"
+                    "trait",
+                    "system_event"
                   ]
                 }
               },
@@ -7905,7 +8055,7 @@ var TOOL_DEFINITIONS = [
     "type": "function",
     "function": {
       "name": "get_customer_timeline",
-      "description": "List this customer's conversations and agent actions in order, newest first, one line each. Use it to leaf through the history when you do not know what to search for. Pass next_cursor to continue. Prefer search_customer_history for a specific question.",
+      "description": "List this customer's conversations, agent actions and system events in order, newest first, one line each. Use it to leaf through the history when you do not know what to search for; filters.item_kinds also lists the open items, facts, patterns or objects it names. Pass next_cursor to continue. Prefer search_customer_history for a specific question.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -7953,7 +8103,8 @@ var TOOL_DEFINITIONS = [
                     "open_item",
                     "action",
                     "object",
-                    "trait"
+                    "trait",
+                    "system_event"
                   ]
                 }
               },
@@ -7972,7 +8123,7 @@ var TOOL_DEFINITIONS = [
     "type": "function",
     "function": {
       "name": "open_history_item",
-      "description": "Open one conversation or business object returned by search_customer_history or get_customer_timeline: what was asked, what was promised and by whom, the outcome and what memory came from it. Use it only after a search or timeline pointed to the item.",
+      "description": "Open one conversation (`episode:`) or business object (`object:`) returned by search_customer_history or get_customer_timeline: what was asked, what was promised and by whom, the outcome and what memory came from it. Actions, events, facts and promises are complete as listed and do not open. Use it only after a search or timeline pointed to the item.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -8343,6 +8494,13 @@ function compose(body, read) {
   const pack = body.pack ? { pack: { ...body.pack, slots: fetched?.pack?.slots ?? [] } } : {};
   return { ...body, slots: fetched?.slots ?? null, guards: fetched?.guards ?? [], ...pack };
 }
+var RTT_MARGIN_MS = 50;
+function budgetWarnings(rttMs, timeouts, explicit) {
+  const ms = Math.round(rttMs);
+  return [...explicit].sort().filter((name) => timeouts[name] < rttMs + RTT_MARGIN_MS).map(
+    (name) => `timeouts.${name} (${timeouts[name]} ms) is shorter than the round trip to the region (${ms} ms) plus ${RTT_MARGIN_MS} ms for the API: its reads will run out of time. Leave it at its default, which adds the measured round trip, or raise it`
+  );
+}
 function rttWarnings(rttMs, timeouts) {
   const ms = Math.round(rttMs);
   const found2 = [];
@@ -8380,6 +8538,12 @@ var Niadra = class _Niadra {
   enabled;
   core;
   timeouts;
+  keepWarm;
+  warmTimer;
+  /** The read budgets the caller left at their defaults: they take the measured round trip on top. */
+  defaultReads;
+  voiceStarted = false;
+  voiceWarned = false;
   strict;
   /** Where the client reports what it swallows in fail-open mode. */
   logger;
@@ -8424,6 +8588,8 @@ var Niadra = class _Niadra {
     this.strict = options.strict ?? false;
     this.logger = options.logger ?? consoleLogger;
     this.timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+    this.keepWarm = new KeepWarm(options.keepWarm ?? true);
+    this.defaultReads = new Set(["context", "navigation"].filter((name) => options.timeouts?.[name] === void 0));
     this.voice = new VoiceLines(
       options.voice === false ? { ...DEFAULT_VOICE, enabled: false } : { ...DEFAULT_VOICE, ...options.voice }
     );
@@ -8449,13 +8615,14 @@ var Niadra = class _Niadra {
     this.coordinator = new Coordinator(
       this.outbox,
       this.suppressions,
-      (body, key2) => this.api.declare(body, { idempotency_key: key2 })
+      (body, key2) => this.api.declare(body, { idempotency_key: key2 }),
+      this.logger
     );
     this.states = new AgentStates(
       this.outbox,
       {
-        read: (scope, agent) => this.api.readAgentState({ scope, agent }, { timeout: this.timeouts.navigation }),
-        write: (write) => this.api.writeAgentState(write, { timeout: this.timeouts.navigation })
+        read: (scope, agent) => this.api.readAgentState({ scope, agent }, { timeout: this.readBudget("navigation") }),
+        write: (write) => this.api.writeAgentState(write, { timeout: this.readBudget("navigation") })
       },
       this.logger
     );
@@ -8482,6 +8649,7 @@ var Niadra = class _Niadra {
     this.core = setup;
     this.enabled = true;
     this.disabledReason = null;
+    this.probe(setup);
     if (options.flushOnExit ?? true) this.unregisterExit = registerExitFlush(this);
   }
   setup(options) {
@@ -8503,7 +8671,10 @@ var Niadra = class _Niadra {
       baseURL,
       apiKey,
       fetch: fetchImpl,
-      defaultHeaders: options.defaultHeaders ?? {}
+      defaultHeaders: options.defaultHeaders ?? {},
+      logger: this.logger,
+      coldAllowanceMs: this.timeouts.connect,
+      keepAliveMs: options.keepAliveMs ?? FETCH_KEEPALIVE_MS
     });
     const queueOptions = { ...DEFAULT_QUEUE, ...options.queue };
     queueOptions.maxBatchSize = Math.min(queueOptions.maxBatchSize, 499);
@@ -8559,7 +8730,7 @@ var Niadra = class _Niadra {
     return result2;
   }
   readContext(core, params, request, options) {
-    const timeout = options.timeout ?? (request.view === "voice" ? this.timeouts.contextVoice : this.timeouts.context);
+    const timeout = options.timeout ?? (request.view === "voice" ? this.timeouts.contextVoice : this.readBudget("context"));
     const { query: own3, ...pinned2 } = request;
     const query = turnText(own3 ?? params.turn);
     const voiceCache = this.voiceCache(core, pinned2, options.cache);
@@ -8575,7 +8746,7 @@ var Niadra = class _Niadra {
    */
   async profile() {
     if (!this.core) return null;
-    return this.profileCache.refresh(() => this.api.sdkProfile({ timeout: this.timeouts.navigation }));
+    return this.profileCache.refresh(() => this.api.sdkProfile({ timeout: this.readBudget("navigation") }));
   }
   /**
    * Checks outputs against this claim contract instead of the one the profile serves (a company's own copy,
@@ -8600,7 +8771,7 @@ var Niadra = class _Niadra {
    */
   async mayContact(handle, purpose, options = {}) {
     if (this.core && this.suppressions.due()) {
-      const read = this.readSuppressions(this.suppressions.held ? this.timeouts.write : this.timeouts.navigation);
+      const read = this.readSuppressions(this.suppressions.held ? this.timeouts.write : this.readBudget("navigation"));
       if (!this.suppressions.held) await read;
     }
     const checkOptions = { channel: options.channel ?? null };
@@ -8610,8 +8781,8 @@ var Niadra = class _Niadra {
   readSuppressions(budgetMs) {
     return this.suppressions.read(
       {
-        salt: () => this.api.suppressionSalt({ timeout: this.timeouts.navigation }),
-        page: (cursor, limit3) => this.api.suppressions({ cursor, limit: limit3 }, { timeout: this.timeouts.navigation })
+        salt: () => this.api.suppressionSalt({ timeout: this.readBudget("navigation") }),
+        page: (cursor, limit3) => this.api.suppressions({ cursor, limit: limit3 }, { timeout: this.readBudget("navigation") })
       },
       budgetMs
     );
@@ -8690,6 +8861,7 @@ var Niadra = class _Niadra {
   }
   /** What a conversation or a task needs of its client for the agent features. */
   get agentHost() {
+    const client = this;
     return {
       recorder: this.turns,
       coordinator: this.coordinator,
@@ -8703,7 +8875,10 @@ var Niadra = class _Niadra {
       claim: (request, timeoutMs) => this.api.claim(request, {}, { timeout: timeoutMs }),
       verifyClaim: (ref, field, value, options) => this.verifyClaim(ref, field, value, options),
       enabled: this.enabled,
-      navigationMs: this.timeouts.navigation
+      strict: this.strict,
+      get navigationMs() {
+        return client.readBudget("navigation");
+      }
     };
   }
   /**
@@ -8731,7 +8906,7 @@ var Niadra = class _Niadra {
     if (!cache) return false;
     const key2 = cacheKey(request);
     const line = this.voice.line(cacheScope(request) ?? "");
-    this.probe(core);
+    this.startVoice(core);
     line.request = request;
     if (!cache.has(key2) && line.inFlight().length === 0) {
       this.voiceRead(core, cache, line, key2, request, null, this.timeouts.contextVoiceStart);
@@ -8868,13 +9043,13 @@ var Niadra = class _Niadra {
       if (!params.query || params.query.length > 2e3) {
         throw new NiadraValidationError("query must be 1 to 2000 characters");
       }
-      return this.readSpec("POST", "/v1/history/search", params, this.timeouts.navigation, options);
+      return this.readSpec("POST", "/v1/history/search", params, this.readBudget("navigation"), options);
     });
   }
   /** 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)
+      () => this.readSpec("POST", "/v1/history/timeline", params, this.readBudget("navigation"), options)
     );
   }
   /**
@@ -8887,9 +9062,10 @@ var Niadra = class _Niadra {
       if (!id) throw new NiadraValidationError("open() needs an item id");
       const body = { item_id: id };
       if (params.subject) body.subject = params.subject;
+      if (params.about) body.about = params.about;
       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);
+      return this.readSpec("POST", "/v1/history/open", body, this.readBudget("navigation"), options);
     });
   }
   /**
@@ -8901,7 +9077,7 @@ var Niadra = class _Niadra {
    * const { data: invoice } = await niadra.objectState("invoice:erp:0823");
    */
   async objectState(object, options = {}) {
-    return this.navigate(() => this.readSpec("GET", objectPath(object), void 0, this.timeouts.navigation, options));
+    return this.navigate(() => this.readSpec("GET", objectPath(object), void 0, this.readBudget("navigation"), options));
   }
   /**
    * System events and agent actions about one object, newest first, one line each and never
@@ -8914,7 +9090,7 @@ var Niadra = class _Niadra {
         throw new NiadraValidationError("limit must be between 1 and 100");
       }
       const path = `${objectPath(object)}/timeline`;
-      const spec = this.readSpec("GET", path, void 0, this.timeouts.navigation, options);
+      const spec = this.readSpec("GET", path, void 0, this.readBudget("navigation"), options);
       spec.query = { cursor: params.cursor, limit: String(limit3) };
       return spec;
     });
@@ -8933,6 +9109,7 @@ var Niadra = class _Niadra {
       timeline: (params, voice) => this.timeline(params, this.voiceBudget(voice)),
       open: (id, customer, bound, voice) => {
         const scope = { subject: customer };
+        if (bound.about) scope.about = bound.about;
         if (bound.verification) scope.verification = bound.verification;
         if (bound.conversation_id) scope.conversation_id = bound.conversation_id;
         return this.open(id, scope, this.voiceBudget(voice));
@@ -8967,7 +9144,7 @@ var Niadra = class _Niadra {
     const key2 = AgentMemoryCache.key(params);
     const fresh = cache?.fresh(key2);
     if (fresh) return blockResult(fresh, "cache");
-    const timeout = options.timeout ?? (params.view === "voice" ? this.timeouts.contextVoice : this.timeouts.context);
+    const timeout = options.timeout ?? (params.view === "voice" ? this.timeouts.contextVoice : this.readBudget("context"));
     const spec = this.readSpec("GET", "/v1/agent-memory/block", void 0, timeout, options);
     spec.query = {
       max_tokens: String(params.max_tokens ?? 300),
@@ -9004,7 +9181,7 @@ var Niadra = class _Niadra {
       if (params.limit !== void 0) body.limit = params.limit;
       if (params.conversation_id) body.conversation_id = params.conversation_id;
       if (params.task_id) body.task_id = params.task_id;
-      return this.readSpec("POST", "/v1/agent-memory/search", body, this.timeouts.navigation, options);
+      return this.readSpec("POST", "/v1/agent-memory/search", body, this.readBudget("navigation"), options);
     });
     return result2.error ? result2 : { data: result2.data.notes, error: null };
   }
@@ -9098,6 +9275,41 @@ var Niadra = class _Niadra {
       return { ok: false, idempotency_key: key2, error: this.swallow(error, "feedback") };
     }
   }
+  /**
+   * How the space's agents used the context they read (`GET /v1/context-use`): sessions, deliveries, use,
+   * repetition, transfers and recontact, with intervals, grouped by `group_by`. A key of an `analyst` source
+   * with the `analytics` scope reads every source of the space; a key with `admin` reads its own source.
+   */
+  contextUse(params = {}, options = {}) {
+    return this.navigate(() => {
+      const { group_by: groups, ...filters } = params;
+      const query = { ...filters };
+      if (groups?.length) query.group_by = groups;
+      return { ...this.readSpec("GET", "/v1/context-use", void 0, this.timeouts.write, options), query };
+    });
+  }
+  /**
+   * Links a person to the organization they act for (an account or a partner), as a system of record that
+   * knows who works for whom: a CRM, an HR system. Needs a key with the `identity:link` scope (or `admin`);
+   * `can_see_contacts` needs `admin`. Reads with `about` reach the organization through the link.
+   */
+  link(params, options = {}) {
+    const { idempotency_key: key2, ...rest } = params;
+    const body = { can_see_contacts: false, method: "system_import", ...rest };
+    return this.navigate(() => this.writeSpec("/v1/identity/links", body, key2 ?? uuidv7(), options));
+  }
+  /**
+   * Ends a link, from `valid_to` (now when absent): the person no longer acts for the organization, and reads
+   * with `about` for the pair go on with the person's own memory. Needs `identity:link` or `admin`.
+   */
+  endLink(linkId, params = {}, options = {}) {
+    return this.navigate(() => {
+      if (!linkId) throw new NiadraValidationError("endLink() needs a link id");
+      const body = params.valid_to ? { valid_to: params.valid_to } : {};
+      const path = `/v1/identity/links/${encodeURIComponent(linkId)}/end`;
+      return this.writeSpec(path, body, params.idempotency_key ?? uuidv7(), options);
+    });
+  }
   /**
    * Up to 500 corrections in one call, each with its own idempotency key (minted when missing).
    * Resolves with `accepted`, `duplicates` for replayed keys and one error per refused item, by index.
@@ -9190,16 +9402,20 @@ var Niadra = class _Niadra {
    * emits `conversation.ended` when you call `end()`.
    */
   conversation(params) {
-    return new Conversation(this, params, {
+    const conversation = new Conversation(this, params, {
       endConversation: (id) => this.endScope(buildConversationEnded(id), `conversation:${id}`)
     });
+    this.warm(`conversation:${conversation.id}`, conversation);
+    return conversation;
   }
   /** A helper for one internal-agent task: binds `task_id` to reads and writes and emits `task.ended`. */
   task(params) {
-    return new Task(this, params, {
+    const task = new Task(this, params, {
       endTask: (id) => this.endScope(buildTaskEnded(id), `task:${id}`),
       verifyTask: (verify) => this.verifyWith(verify)
     });
+    this.warm(`task:${task.id}`, task);
+    return task;
   }
   /**
    * Sends every queued event and resolves when done. Call it before a serverless function
@@ -9219,6 +9435,8 @@ var Niadra = class _Niadra {
    */
   async shutdown() {
     this.unregisterExit();
+    clearInterval(this.warmTimer);
+    this.warmTimer = void 0;
     if (!this.core) return;
     await this.turnSender?.stop(this.timeouts.write);
     await this.outbox.stop(this.timeouts.write);
@@ -9322,9 +9540,9 @@ var Niadra = class _Niadra {
       const response = await core.transport.request(this.readSpec("POST", "/v1/context", request, timeout, { signal, headers }));
       return normalizeContext(response.data);
     } catch (error) {
-      const refused2 = error instanceof NiadraAPIError && error.status === 404;
+      const refused3 = error instanceof NiadraAPIError && error.status === 404;
       const left = timeout - (Date.now() - started);
-      if (!request.include?.length || !refused2 || left <= 0) throw error;
+      if (!request.include?.length || !refused3 || left <= 0) throw error;
       for (const name of request.include) this.refusedBlocks.set(name, Date.now() + BLOCK_RECHECK_AFTER_MS);
       const { include: _dropped, ...plain2 } = request;
       const response = await core.transport.request(this.readSpec("POST", "/v1/context", plain2, left, { signal, headers }));
@@ -9412,9 +9630,32 @@ var Niadra = class _Niadra {
       const rtt = Math.min(...samples);
       this.voice.rtt = rtt;
       this.logger.debug(`round trip to the region ${Math.round(rtt)} ms`);
-      for (const warning of rttWarnings(rtt, this.timeouts)) this.logger.warn(warning);
+      const explicit = ["context", "navigation"].filter((name) => !this.defaultReads.has(name));
+      for (const warning of budgetWarnings(rtt, this.timeouts, explicit)) this.logger.warn(warning);
+      if (this.voiceStarted) this.warnVoice();
     })();
   }
+  /**
+   * A read budget: one the caller left at its default is what the API may take, and the measured round trip
+   * to the region goes on top, so an agent far from the region (Sao Paulo, 170 ms from us-east-2) is not
+   * timed out by the network; one the caller set is a ceiling.
+   */
+  readBudget(name) {
+    const rtt = this.voice.rtt;
+    return rtt !== null && this.defaultReads.has(name) ? this.timeouts[name] + rtt : this.timeouts[name];
+  }
+  /** The client reads in voice: the voice budgets' warnings matter from now on. */
+  startVoice(core) {
+    this.voiceStarted = true;
+    this.probe(core);
+    this.warnVoice();
+  }
+  warnVoice() {
+    const rtt = this.voice.rtt;
+    if (this.voiceWarned || rtt === null) return;
+    this.voiceWarned = true;
+    for (const warning of rttWarnings(rtt, this.timeouts)) this.logger.warn(warning);
+  }
   /**
    * A voice turn: the pinned body from memory, and the slots of the read of its words when that
    * read lands within `timeout`. See `voice.ts`.
@@ -9424,7 +9665,7 @@ var Niadra = class _Niadra {
     const key2 = cacheKey(request);
     const deadline = Date.now() + timeout;
     const line = this.voice.line(scope);
-    this.probe(core);
+    this.startVoice(core);
     line.request = request;
     const words2 = wordsOf(query);
     const background = this.timeouts.prefetch;
@@ -9610,8 +9851,39 @@ var Niadra = class _Niadra {
       core.queue.flushInBackground(true);
     });
   }
+  /** Notes an open conversation or task; the first one starts the keep-warm timer (`warm.ts`). */
+  warm(scope, session) {
+    const core = this.core;
+    if (!core || !this.keepWarm.enabled) return;
+    this.keepWarm.add(scope, session, Date.now());
+    if (this.warmTimer !== void 0) return;
+    const timer = setInterval(() => {
+      this.warmTick(core);
+    }, EVERY_MS);
+    timer.unref?.();
+    this.warmTimer = timer;
+  }
+  warmTick(core) {
+    const step = this.keepWarm.step(Date.now(), core.transport.lastActivityAt);
+    if (step === "stop") {
+      clearInterval(this.warmTimer);
+      this.warmTimer = void 0;
+      return;
+    }
+    if (step !== "ping") return;
+    core.transport.request({
+      method: "GET",
+      path: "/healthz",
+      timeoutMs: 2e3,
+      retry: { kind: "read", maxAttempts: 1 },
+      activity: false
+    }).catch((error) => {
+      this.logger.debug(`keep-warm ping failed: ${describe(toNiadraError(error))}`);
+    });
+  }
   async endScope(item, scope) {
     this.forgetScope(scope);
+    this.keepWarm.end(scope);
     return this.sendNow(() => item);
   }
   async sendBatch(transport, items2, maxAttempts, backoff) {
@@ -11466,7 +11738,7 @@ var Replayer = class {
     try {
       answer = await this.niadra.callRoute({ method: "POST", path: "/v1/scenario-runs", body, idempotencyKey: uuidv7() });
     } catch (error) {
-      if (error instanceof NiadraAPIError && error.code === "pin_mismatch") return refused(scenarioIds, results);
+      if (error instanceof NiadraAPIError && error.code === "pin_mismatch") return refused2(scenarioIds, results);
       throw error;
     }
     let run = runOf(answer);
@@ -11569,7 +11841,7 @@ var Replayer = class {
     return result(scenarioId, turnId, caseId, run, "completed", { paraphrase: rephrased, assertions, divergent_calls: played.divergent, latency_ms: latency });
   }
 };
-function refused(scenarioIds, results) {
+function refused2(scenarioIds, results) {
   const scenarios = scenarioIds.map((id) => {
     const mine = results.filter((r) => r.scenario_id === id);
     return {