@niadra/sdk 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -518,7 +518,7 @@ function internalRecord(span, ref, act) {
 }
 
 // src/version.ts
-var VERSION = "0.7.0";
+var VERSION = "0.9.0";
 
 // src/transport.ts
 var RETRYABLE_WRITE_STATUS = /* @__PURE__ */ new Set([408, 421, 429, 500, 502, 503, 504]);
@@ -2904,6 +2904,11 @@ ${change.field}`)) out.push({ ref, field: change.field, value: change.now, claim
     for (const s of constraints.soft ?? []) said.push([s.attr, s.value]);
     for (const a of constraints.attributes ?? []) said.push([a.name, a.value]);
     for (const [attr, value] of said) out.push({ ref: null, field: attr.split(".").pop() ?? attr, value, claimSafe: true });
+    for (const shown of constraints.already_presented ?? []) {
+      for (const [field, n] of Object.entries(shown.values ?? {})) {
+        out.push({ ref: shown.ref, field, value: n.v, claimSafe: n.claim_safe, role: n.role ?? null });
+      }
+    }
   }
   return out;
 }
@@ -3270,7 +3275,7 @@ function thenable(value) {
 function tool(name, fn, options = {}) {
   const isAsync = isAsyncFunction(fn);
   function bindingOf(frame) {
-    return options.binding ?? (options.served ?? frame?.profile.bindings)?.(name) ?? null;
+    return (options.served ?? frame?.profile.bindings)?.(name) ?? null;
   }
   function masks(frame) {
     return options.maskOutput ?? bindingOf(frame)?.capabilities?.mask_output ?? false;
@@ -3385,8 +3390,7 @@ function tool(name, fn, options = {}) {
   const marker = {
     name,
     dryRun: options.dryRun ?? false,
-    provenance: options.provenance ?? null,
-    binding: options.binding ?? null
+    provenance: options.provenance ?? null
   };
   Object.defineProperty(wrapped, RECORDED, { value: marker });
   return wrapped;
@@ -3648,6 +3652,7 @@ function claimsOf(frame, claims, logger) {
 
 // src/queue.ts
 var HEARTBEAT_WINDOW_MS = 6e4;
+var MAX_PAUSE_MS = 6e4;
 var EventQueue = class {
   constructor(send, options, logger, now = Date.now) {
     this.send = send;
@@ -3668,6 +3673,8 @@ var EventQueue = class {
   droppedSinceWarning = 0;
   windowStart;
   sentInWindow = 0;
+  pauseMs = 0;
+  resumeAt = 0;
   /** Items waiting to be sent, not counting a batch already in flight. */
   get size() {
     return this.items.length;
@@ -3703,10 +3710,16 @@ var EventQueue = class {
     return run;
   }
   /**
-   * Starts a flush without waiting for it. Item failures are logged and settled inside the
-   * drain, so only an unexpected error reaches this catch.
+   * Starts a flush without waiting for it: once the pause after a failed batch ends, or at once with
+   * `now` (a caller waits for an item). Item failures are logged and settled inside the drain, so only
+   * an unexpected error reaches this catch.
    */
-  flushInBackground() {
+  flushInBackground(now = false) {
+    const paused = this.resumeAt - this.now();
+    if (!now && paused > 0) {
+      this.schedule(paused);
+      return;
+    }
     this.flush().catch((error) => {
       this.logger.error(`event flush failed: ${toNiadraError(error).message}`);
     });
@@ -3723,24 +3736,36 @@ var EventQueue = class {
     while (this.items.length > 0) {
       const batch = this.items.splice(0, this.options.maxBatchSize);
       const heartbeat = this.heartbeat();
-      const wire = batch.map((pending) => pending.item);
-      if (heartbeat) wire.push(heartbeat);
-      await this.sendBatch(batch, wire, report);
+      if (heartbeat) batch.push({ item: heartbeat });
+      if (!await this.sendBatch(batch, report)) break;
     }
     return report;
   }
-  async sendBatch(batch, wire, report) {
+  /** Sends one batch; `false` when it went back to the queue and the queue pauses. */
+  async sendBatch(batch, report) {
+    const wire = batch.map((pending) => pending.item);
     let response;
     try {
       response = await this.send(wire);
     } catch (error) {
       const failure = toNiadraError(error);
-      report.failed += batch.length;
       report.errors.push(failure);
-      this.logger.warn(`dropped ${batch.length} events after retries: ${failure.message}`);
+      if (isTransient(failure)) {
+        for (const pending of batch) pending.settle?.(failure);
+        this.requeue(batch);
+        this.pauseMs = Math.min(MAX_PAUSE_MS, Math.max(this.options.flushIntervalMs, this.pauseMs * 2));
+        this.resumeAt = this.now() + this.pauseMs;
+        this.logger.warn(`could not deliver ${batch.length} events, will retry: ${failure.message}`);
+        this.schedule(this.pauseMs);
+        return false;
+      }
+      report.failed += batch.length;
+      this.logger.warn(`dropped ${batch.length} events refused by the API: ${failure.message}`);
       for (const pending of batch) pending.settle?.(failure);
-      return;
+      return true;
     }
+    this.pauseMs = 0;
+    this.resumeAt = 0;
     const rejected = /* @__PURE__ */ new Map();
     for (const itemError of response.errors) {
       const detail = itemError.detail ? `: ${itemError.detail}` : "";
@@ -3751,6 +3776,7 @@ var EventQueue = class {
       this.logger.warn(`server rejected ${rejected.size} of ${wire.length} items (${codes2})`);
     }
     batch.forEach((pending, index) => {
+      if (pending.item.type === "heartbeat") return;
       const error = rejected.get(index) ?? null;
       if (error) {
         report.failed++;
@@ -3761,6 +3787,17 @@ var EventQueue = class {
       }
       pending.settle?.(error);
     });
+    return true;
+  }
+  /** Puts a batch back at the front, keeping only what still fits; what does not is dropped. */
+  requeue(batch) {
+    const room = Math.max(0, this.options.maxQueueSize - this.items.length);
+    const lost = batch.slice(room);
+    this.items.unshift(...batch.slice(0, room));
+    if (lost.length > 0) {
+      this.logger.warn(`event queue is full; dropped ${lost.length} events`);
+      for (const pending of lost) pending.settle?.(new NiadraError("event queue is full"));
+    }
   }
   /**
    * Once a minute, the next batch carries the number of items sent in the previous window.
@@ -3811,7 +3848,7 @@ function unref(timer) {
 var MAX_TURNS = 50;
 var COMPRESSED_ROOM = 4 * 1024 * 1024 - 64 * 1024;
 var DECODED_ROOM = 16 * 1024 * 1024 - 256 * 1024;
-var MAX_PAUSE_MS = 6e4;
+var MAX_PAUSE_MS2 = 6e4;
 var encoder2 = new TextEncoder();
 async function encode(records) {
   const raw = encoder2.encode(JSON.stringify({ turns: records }));
@@ -3970,7 +4007,7 @@ var TurnSender = class {
     }
     if (isTransient(error)) {
       this.queue.requeue(batch.frames);
-      this.pause = Math.min(MAX_PAUSE_MS, Math.max(this.intervalMs, this.pause * 2));
+      this.pause = Math.min(MAX_PAUSE_MS2, Math.max(this.intervalMs, this.pause * 2));
       this.resumeAt = this.now() + this.pause;
       this.logger.warn(`could not deliver ${batch.frames.length} turns, will retry (${toNiadraError(error).name})`);
       return false;
@@ -4436,7 +4473,10 @@ var SuppressionCopy = class {
     }
     this.saltValue = salt;
   }
-  /** Applies one page, in order. `true` when more pages follow. */
+  /**
+   * Applies one page, in order. `true` when more pages follow: a full page. Every page carries the cursor to
+   * read from next, the last one too, which the next read starts from.
+   */
   apply(page) {
     if (page.salt_id !== this.saltValue?.salt_id) {
       this.saltValue = null;
@@ -4451,8 +4491,9 @@ var SuppressionCopy = class {
     }
     this.cursor = page.next_cursor ?? this.cursor;
     this.absent = false;
-    if (!page.next_cursor) this.readAt = this.now();
-    return Boolean(page.next_cursor);
+    const more = Boolean(page.next_cursor) && page.items.length >= PAGE;
+    if (!more) this.readAt = this.now();
+    return more;
   }
   /** A 404: the space keeps no list. Anything else: the copy stays as it is. */
   failed(error) {
@@ -4677,7 +4718,7 @@ var ContactGateway = class {
 
 // src/outbox.ts
 var CAPACITY = 1e3;
-var MAX_PAUSE_MS2 = 6e4;
+var MAX_PAUSE_MS3 = 6e4;
 var Outbox = class {
   constructor(logger, intervalMs = 1e3, now = Date.now) {
     this.logger = logger;
@@ -4745,7 +4786,7 @@ var Outbox = class {
       answer = await write.send();
     } catch (error) {
       if (isTransient(error)) {
-        this.pause = Math.min(MAX_PAUSE_MS2, Math.max(this.intervalMs, this.pause * 2));
+        this.pause = Math.min(MAX_PAUSE_MS3, Math.max(this.intervalMs, this.pause * 2));
         this.resumeAt = this.now() + this.pause;
         return false;
       }
@@ -5528,6 +5569,11 @@ var ContextCache = class {
     }
     return true;
   }
+  /** Milliseconds since the server last sent or confirmed the pack held for `key`; `null` when none is held. */
+  age(key2) {
+    const entry = this.entries.get(key2);
+    return entry ? this.now() - entry.confirmedAt : null;
+  }
   /** The cached pack's ETag, without touching the order of eviction. */
   etag(key2) {
     return this.entries.get(key2)?.response.etag ?? null;
@@ -5750,7 +5796,7 @@ function mergeNotModified(cached, fresh) {
     coordination: fresh.coordination ?? cached.coordination ?? null
   };
 }
-function resultFrom(response, source, error = null) {
+function resultFrom(response, source, error = null, ageMs = 0) {
   const holdout = response.path === "holdout";
   const text2 = holdout ? "" : response.text ?? "";
   const pack = holdout ? null : response.pack ?? null;
@@ -5759,10 +5805,10 @@ function resultFrom(response, source, error = null) {
     state: response.state ?? null,
     coordination: response.coordination ?? null
   };
-  return { text: text2, suffix: renderSuffix(response), variables: response.variables, pack, source, response, error, ...blocks2 };
+  return { text: text2, suffix: renderSuffix(response), variables: response.variables, pack, source, ageMs, response, error, ...blocks2 };
 }
 function emptyResult(error) {
-  return { text: "", suffix: "", variables: {}, pack: null, source: "none", response: null, error, constraints: null, state: null, coordination: null };
+  return { text: "", suffix: "", variables: {}, pack: null, source: "none", ageMs: null, response: null, error, constraints: null, state: null, coordination: null };
 }
 function renderSuffix(response) {
   if (response.path === "holdout") return "";
@@ -8556,19 +8602,29 @@ var Niadra = class _Niadra {
    */
   async mayContact(handle, purpose, options = {}) {
     if (this.core && this.suppressions.due()) {
-      const read = this.suppressions.read(
-        {
-          salt: () => this.api.suppressionSalt({ timeout: this.timeouts.navigation }),
-          page: (cursor, limit3) => this.api.suppressions({ cursor, limit: limit3 }, { timeout: this.timeouts.navigation })
-        },
-        this.suppressions.held ? this.timeouts.write : this.timeouts.navigation
-      );
+      const read = this.readSuppressions(this.suppressions.held ? this.timeouts.write : this.timeouts.navigation);
       if (!this.suppressions.held) await read;
     }
     const checkOptions = { channel: options.channel ?? null };
     if (options.failOpen !== void 0) checkOptions.failOpen = options.failOpen;
     return this.suppressions.mayContact(handle, purpose, checkOptions);
   }
+  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 })
+      },
+      budgetMs
+    );
+  }
+  /**
+   * Reads the local copy of the suppression list in the background when it is due: a check that Niadra does not
+   * answer falls back on it, so an opt-out holds through an outage.
+   */
+  keepSuppressions() {
+    if (this.core && this.suppressions.due()) void this.readSuppressions(this.timeouts.write);
+  }
   /**
    * The build a turn runs on, for `conversation.turn({ build })`: each prompt's version, the digest of the
    * corpus the agent consults (computed by you, never the files), the model, your context assembler's version
@@ -8642,7 +8698,10 @@ var Niadra = class _Niadra {
       states: this.states,
       contract: () => this.currentContract(),
       internalText: this.internalText,
-      check: (request, timeoutMs) => this.api.check(request, { timeout: timeoutMs }),
+      check: (request, timeoutMs) => {
+        if (request.direction === "outbound") this.keepSuppressions();
+        return this.api.check(request, { timeout: timeoutMs });
+      },
       claim: (request, timeoutMs) => this.api.claim(request, {}, { timeout: timeoutMs }),
       verifyClaim: (ref, field, value, options) => this.verifyClaim(ref, field, value, options),
       enabled: this.enabled,
@@ -8756,21 +8815,21 @@ var Niadra = class _Niadra {
     }
     const key2 = cacheKey(request);
     const hit = cache.lookup(key2);
-    if (hit?.freshness === "fresh") return resultFrom(delivered(hit.response, cache.take(key2)), "cache");
+    if (hit?.freshness === "fresh") return resultFrom(delivered(hit.response, cache.take(key2)), "cache", null, cache.age(key2));
     if (hit?.freshness === "stale") {
       this.revalidate(core, cache, key2, scope, request, timeout, options.headers).catch((error) => {
         this.logger.debug(`background context refresh failed: ${describe(toNiadraError(error))}`);
       });
-      return resultFrom(delivered(hit.response, cache.take(key2)), "stale");
+      return resultFrom(delivered(hit.response, cache.take(key2)), "stale", null, cache.age(key2));
     }
     try {
       const pending = this.revalidate(core, cache, key2, scope, request, timeout, options.headers);
       const { response, source } = await abortable(pending, options.signal);
-      return resultFrom(delivered(response, cache.take(key2)), source);
+      return resultFrom(delivered(response, cache.take(key2)), source, null, source === "network" ? 0 : cache.age(key2));
     } catch (error) {
       const failure = toNiadraError(error);
       const fallback2 = cache.lookup(key2);
-      return this.contextFailure(failure, fallback2 ? delivered(fallback2.response, cache.take(key2)) : null);
+      return this.contextFailure(failure, fallback2 ? delivered(fallback2.response, cache.take(key2)) : null, cache.age(key2));
     }
   }
   /**
@@ -8792,11 +8851,11 @@ var Niadra = class _Niadra {
       const failure = toNiadraError(error);
       this.observeAuth(failure, key2);
       const fallback2 = cache && key2 ? cache.lookup(key2) : null;
-      return this.contextFailure(failure, cache && key2 && fallback2 ? delivered(fallback2.response, cache.take(key2)) : null);
+      return this.contextFailure(failure, cache && key2 && fallback2 ? delivered(fallback2.response, cache.take(key2)) : null, key2 ? cache?.age(key2) ?? null : null);
     }
     if (!cache || !key2 || !scope) return resultFrom(response, "network");
     if (response.degraded && !response.not_modified && cached) {
-      return resultFrom(delivered({ ...cached.response, slots: response.slots ?? null }, cache.take(key2)), "fallback");
+      return resultFrom(delivered({ ...cached.response, slots: response.slots ?? null }, cache.take(key2)), "fallback", null, cache.age(key2));
     }
     const merged = response.not_modified && cached ? mergeNotModified(cached.response, response) : response;
     cache.store(key2, scope, withoutSlots(merged), generation);
@@ -9298,11 +9357,11 @@ var Niadra = class _Niadra {
       }
     });
   }
-  contextFailure(error, fallback2) {
+  contextFailure(error, fallback2, ageMs = null) {
     if (this.strict) throw error;
     if (fallback2) {
       this.logger.warn(`context request failed, serving the last good pack: ${describe(error)}`);
-      return resultFrom(fallback2, "fallback", error);
+      return resultFrom(fallback2, "fallback", error, ageMs);
     }
     this.logger.warn(`context unavailable: ${describe(error)}`);
     return emptyResult(error);
@@ -9403,11 +9462,11 @@ var Niadra = class _Niadra {
         });
       }
       const response = compose(delivered(hit.response, cache.take(key2)), chosen2);
-      return resultFrom(response, opening.length > 0 ? "network" : hit.freshness === "fresh" ? "cache" : "stale");
+      return resultFrom(response, opening.length > 0 ? "network" : hit.freshness === "fresh" ? "cache" : "stale", null, cache.age(key2));
     } catch (error) {
       const failure = toNiadraError(error);
       const fallback2 = cache.lookup(key2);
-      return this.contextFailure(failure, fallback2 ? delivered(fallback2.response, cache.take(key2)) : null);
+      return this.contextFailure(failure, fallback2 ? delivered(fallback2.response, cache.take(key2)) : null, cache.age(key2));
     }
   }
   /** Starts one read of a line in the background. */
@@ -9550,7 +9609,7 @@ var Niadra = class _Niadra {
         else resolve({ ok: false, idempotency_key: key2, error });
       };
       core.queue.push(item, settle2);
-      core.queue.flushInBackground();
+      core.queue.flushInBackground(true);
     });
   }
   async endScope(item, scope) {
@@ -11570,7 +11629,8 @@ var Counterfactual = class {
     const fn = this.tools[tool2];
     if (fn === void 0) throw new NiadraError(`no function for the tool ${tool2}: pass it in tools`);
     if (!Number.isInteger(k) || k < 1 || k > MAX_K) throw new RangeError(`k must be 1 to ${String(MAX_K)}`);
-    await this.niadra.profile();
+    const raw = await this.served(tool2);
+    if (raw === null) throw new NiadraError(`the space binds no tool ${tool2} for this key's source: see its tool-bindings`);
     const ids = [...turnIds];
     if ((options.scenarioIds ?? []).length > 0) {
       const found2 = await this.niadra.callRoute({ method: "GET", path: "/v1/scenarios", query: { ids: (options.scenarioIds ?? []).join(","), limit: 50 } });
@@ -11588,7 +11648,7 @@ var Counterfactual = class {
         continue;
       }
       for (const call of calls(record, tool2)) {
-        const found2 = await this.case(record, call, fn, element, k);
+        const found2 = await this.case(record, call, fn, raw, element, k);
         if (found2 === null) run.untouched++;
         else run.cases.push(found2);
       }
@@ -11598,17 +11658,15 @@ var Counterfactual = class {
     run.report = await this.niadra.callRoute({ method: "POST", path: "/v1/measure/counterfactual-runs", body: report });
     return run;
   }
-  async case(record, call, fn, element, k) {
+  async case(record, call, fn, raw, element, k) {
     const base = { turn_id: record.turn_id, call_id: call.call_id };
     const tool2 = String(call.name);
     const wrapped = recordedTool(fn);
-    const raw = this.options.bindings?.[tool2] ?? wrapped?.binding ?? await this.served(tool2);
     let block;
     let args;
     try {
       block = await this.value(record, blockBlob(record, call));
       args = { ...await this.value(record, call.args) };
-      if (raw === null) throw new BlobError("the tool has no binding");
     } catch {
       return { ...base, status: "infrastructure_error", dry_run: false };
     }