@niadra/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 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/).
 
+## [Unreleased]
+
+## [0.9.0] - 2026-09-30
+
+### Added
+
+- `ContextResult.ageMs`: how long ago Niadra sent or confirmed the pack a read served. It is 0 for an answer
+  just received and grows while the cache serves the pack (`cache`, `stale`, or `fallback` with Niadra down).
+- The chaos test (`test/chaos.test.ts`): Niadra's process killed, its network gone silent, answering 503 and
+  answering past the deadline, in the middle of a conversation.
+- A state read's objects carry `derived`: the type's derived fields over its related objects (a look's
+  `all_pieces_available`), computed at the read, each with `v`, `logic`, `over` and `unknown`
+  (`DerivedState`). A shared object of a derived type carries `derived_status`, and its push's `inputs` name
+  shared objects.
+
+### Fixed
+
+- The local copy of the suppression list is read to its end against the server: a page shorter than the limit
+  ends a read, and its cursor is where the next read starts. The server names the cursor on the last page
+  too, so the copy read 50 pages of nothing and was never held: `mayContact()` and a check that Niadra did not
+  answer fell back on the purpose's direction. The stand-in cell answers as the server does.
+- A batch of events that still fails after its attempts with an error that may pass goes back to the front of
+  the queue and leaves again after a pause, doubling up to a minute, instead of being dropped: what an agent
+  said during an outage longer than a few seconds reached Niadra only in part.
+- A check about an outbound contact keeps the local copy of the suppression list, read in the background once
+  a minute. Before, only `mayContact()` read it, so an agent that only called `check()` had no copy when Niadra
+  went down, and a purpose that fails open (`service`, `transactional`) went out to a customer who had opted
+  out of it.
+
+## [0.8.0] - 2026-09-30
+
+### Added
+
+- The claim guard takes the offers a context read served as evidence: each object in the constraints block's
+  `already_presented` carries the numbers it was last shown with (`values`: price, total, discount,
+  installment), each with its role and whether it may be claimed now, and `blockValues()` turns them into
+  values the guard checks a number against, as it checks a tool's result. An offer shown too long ago to claim makes the
+  number `stale`, and a price only the pack's text states is still `unsupported`. The constraints block's
+  `Shown` model gains `values` (`ShownValue`).
+
+### Removed
+
+- `tool(..., { binding })`, `new Counterfactual(..., { bindings })` and `niadra counterfactual --bindings`: a
+  tool's binding comes only from the space's `tool-bindings` document, which the SDK profile serves. A
+  counterfactual for a tool the space does not bind stops before calling it.
+
 ## [0.7.0] - 2026-09-30
 
 The agent core. Every turn an agent takes is recorded in its own process; what it says is checked against

package/README.md

@@ -691,10 +691,11 @@ await convo.turn({ build: Niadra.build({ prompts: { store: "v16" }, model: "gpt-
   without `include` keeps its suffix. With Niadra down, the last good blocks serve.
 - **Coordination** decides by each purpose's direction when Niadra does not answer within 200 ms: a
   customer's message and service go, marketing, retention, collection and an effect with a key wait, and
-  the local copy of the opt-out list always holds.
-- **Tool bindings** the space declares come in the SDK profile: a tool without `binding` in code measures the
-  constraints block through the one served for its name, and its `capabilities.mask_output` decides the
-  masking when the code leaves `maskOutput` unset.
+  the local copy of the opt-out list always holds. Every check about an outbound contact keeps that copy,
+  read again in the background once a minute.
+- **Tool bindings** live in the space's `tool-bindings` document and come in the SDK profile, never in code: a
+  tool measures the constraints block through the one served for its name, the counterfactual runs through it,
+  and its `capabilities.mask_output` decides the masking when the code leaves `maskOutput` unset.
 - **The `niadra` command** (Node) runs `replay`, `counterfactual`, `resolver-worker` (the space's refresh
   requests, read with your resolvers inside your boundary; a watch fires only on a value the worker
   confirmed, and a resolver returns `NOT_FOUND` when the source no longer has the object), `types derive` and
@@ -714,10 +715,16 @@ Memory should make an agent better, never make it fail. By default:
 | 401 or 403 | Not treated as an outage: the cached packs are dropped (all of them on 401, the one requested on 403) and `context()` returns empty. Revoking a key also stops what the process had cached. |
 | 421 (the space moved to another cell) | Retried at once, up to three attempts. |
 | 429 on a batch | Retried after `Retry-After`. |
-| Batch failure | Retried with exponential backoff and jitter, three attempts. 4xx answers other than 408, 421 and 429 are never retried. A batch that still fails is dropped and logged. |
+| Batch failure | Retried with exponential backoff and jitter, three attempts. 4xx answers other than 408, 421 and 429 are never retried. A batch that still fails goes back to the front of the queue and leaves again after a pause that doubles, up to a minute, while Niadra stays down; each event keeps its idempotency key, so it is stored once. |
 | 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. |
 
+With Niadra down, a read serves the conversation's last good pack (`source: "fallback"`) with `ageMs`
+saying how old it is; the opt-out holds by the local copy of the suppression list; turn records, events
+and declarations wait in their queues and leave once Niadra answers again, each stored once.
+`test/chaos.test.ts` kills Niadra's process, silences its network, answers 503 and answers late in the
+middle of a conversation, and checks all of it.
+
 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 |
@@ -729,7 +736,7 @@ Every call you wait for has its own time budget for the whole call, retries and
 | `identify()`, `verify()`, `handoff()`, `feedback()` and the reservation in `uploadMedia()` | 5 s |
 | The transfer in `uploadMedia()` | 60 s |
 
-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.
+An `identify()`, `verify()` or `handoff()` that runs out of time, or that Niadra cannot take for now (a network error, a 5xx), resolves with that error 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
 
@@ -740,6 +747,8 @@ Inside a conversation or task, packs are cached in memory:
 - when a request fails: the last good pack, if it is less than 30 minutes old;
 - at most 1,000 packs, the least recently used evicted first.
 
+`source` says which of these served the read, and `ageMs` how long ago Niadra sent or confirmed that pack.
+
 Refreshes send the cached ETag, so an unchanged pack costs a `not_modified` answer instead of the
 full text, and only one background refresh per pack runs at a time. A 401 or 403 is not an
 outage: the cached packs go (all of them on 401, the one requested on 403), so cutting a vendor's

package/dist/ai-sdk.cjs

@@ -385,7 +385,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;
@@ -500,8 +500,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;
@@ -527,7 +526,7 @@ function measure(frame, raw, args) {
 
 // src/context.ts
 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 };
 }
 
 // src/integrations/shared.ts