@niadra/sdk 0.1.1 → 0.7.0

package/CHANGELOG.md

@@ -2,76 +2,168 @@
 
 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
+## [0.7.0] - 2026-09-30
 
-### 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
+The agent core. Every turn an agent takes is recorded in its own process; what it says is checked against
+what its tools returned; agents, people and systems coordinate before they contact a customer or act; the
+objects a company's systems push reach the agent as typed state with the freshness to say them; each agent
+keeps its working state; and a company replays turns, derives its types and measures a tool's
+counterfactual in its own CI. The framework adapters record turns. Every feature is off until the space
+turns it on, and a space that did not ask sees no change.
 
-First public release, with the same surface as the Python SDK.
+The versions published before it were previews: nothing of theirs carries over, and none of their names,
+options or fallbacks is kept.
 
 ### Added
 
-- `Niadra` client with the endpoint derived from the source key (`https://<space>.<region>.api.niadra.com`), overridable with `baseURL`.
-- `context()` with a per-conversation cache: TTL, stale-while-revalidate with one deduplicated refresh per pack, last good value on failure, and ETag revalidation through `known_etag`. 401 and 403 drop cached packs, and a `degraded` answer never replaces a good one. Plain and delta reads of a conversation share one entry, and each delta is handed out once.
-- History navigation: `search()`, `timeline()` and `open()`.
-- `tools(subject)`: the navigation kit as function-calling definitions, with the customer bound outside the model.
-- `subjectToken()` for binding a customer to an MCP session.
-- Writes: `track()`, `action()`, `identify()`, `verify()` and `handoff()`, through a bounded queue that batches by count and time, retries with backoff and sends a coverage heartbeat once a minute.
-- `conversation()` helper that reads the pack the server pins, asks for deltas after the first read and keeps them until the pack changes, captures turns and emits `conversation.ended`.
-- `task()` helper for internal agents that centers its pack on its object, keeps deltas and stamps like a conversation, captures the agent's answers and emits `task.ended`; `verify()` on a task, whose `tools()` follow its level.
-- `markInjected()` and `contextStamp` on conversations and tasks: the agent's turns and actions carry the etag of the pack its prompt held and when it went in, as the event's `context_stamp`.
-- `wrap()` for OpenAI-compatible clients: injects the pack and the suffix into `chat.completions.create` and `parse` (also under `beta`), stamps the injection, records the answer, streams included, keeps `.withResponse()` working, and never lets a capture failure reach the caller. `injectContext()` places a pack in a message list by the same rule.
-- `objectState()` and `objectTimeline()` for business objects.
-- `feedback()` to retract or correct a fact, resolve an open item or record a conversation's outcome.
-- `uploadMedia()`: reserves an upload, sends the bytes to the signed URL with exactly the headers it names (HTTPS
-  only, never the key) and resolves with `media_ref` and `media_sha256`; optionally bound to a `subject`.
-- Fail-open behavior on every public method, and `strict: true` to throw instead.
-- Per-method time budgets, 421 retries for moved spaces, and `problem+json` errors mapped to typed classes.
-- Flush on `beforeExit` in Node, `flush()` and `shutdown()` everywhere else.
-- Handle builders and wire types for every contract model.
+- `Niadra`, with the endpoint derived from the source key and fail-open behavior on every public method
+  (`strict: true` to throw instead), in Node, Deno, Bun, Cloudflare Workers and edge runtimes.
+- `context()` before the model call, cached per conversation and revalidated by ETag, with the customer's
+  last turn as `query` (the turn's `slots`), `prefetch()` while the customer speaks, the voice read path,
+  `format: "json"` for the pack as data (`context-pack.v1`) and `explain: true` for why each slot was chosen.
+- History navigation (`search()`, `timeline()`, `open()`) and `tools()`, the same navigation as
+  function-calling tools bound to one customer, with `subjectToken()` for MCP.
+- Writes through a bounded queue with one batch in flight (`track()`, `action()`, `identify()`, `verify()`,
+  `handoff()`), `conversation()` and `task()`, `feedback()`, `feedbackBatch()`, `uploadMedia()`,
+  `ingestStatus()`, `whoami()`, `objectState()` (the object as a state read serves it, `ObjectRead`) and
+  `objectTimeline()`.
+- Agent memory (`agentMemory()`, `searchAgentMemory()`, `remember()`), backed answers and the guard lines a
+  read carries; `niadra.admin` for a key with the `admin` scope.
+- `wrap()` for OpenAI-compatible clients and the adapters under `@niadra/sdk/<integration>`; the n8n and
+  Flowise nodes in `packages/`.
+- `niadra.api` (`Api`): one method per route of turn records, replay and scenarios, typed state and the
+  agent's working state, subject signals and measurement, and coordination, named in camelCase as the
+  server names the operation. Unlike the rest of the client they never fail open.
+- The types of those routes (`TurnRecord`, `StateReadRequest`, `CheckResult` and the rest), generated
+  from the server's OpenAPI document by `scripts/sync-spec.ts`.
+- Turn records: `conversation.turn()` records what one turn read, called and said, with the build it ran
+  on (`Niadra.build()`), and `tool()` wraps a tool of yours so each call inside a turn is recorded, copied
+  as JSON at the moment, with the objects its result showed. The turn in progress follows the async
+  context (`AsyncLocalStorage`; `useAsyncLocalStorage()` supplies one where `node:async_hooks` is missing),
+  so parallel sub-agents keep their own turns. A bounded queue keeps the closed turns (values of unflagged
+  turns go first when it is full) and a background sender posts them to `POST /v1/turns` in the space's
+  content mode, with the values in your own bucket in `pointer` mode (`niadra.turns.store()`). Closing a
+  turn never waits for the network, and a recorded tool call costs under 2 ms at the 95th percentile.
+- The warm cache for when Niadra is down: `niadra.profile()` keeps the SDK profile (features, claim
+  contract); `context({ include: ["constraints", "state"] })` reads the constraints block and the state view
+  with the pack, and a failed read serves the last good ones; `niadra.mayContact()` checks an outbound
+  contact against the local copy of the suppression list, which keeps applying with Niadra out of reach.
+- The claim contract inside a turn: what the agent says is checked against what its tools returned and
+  each claim goes to the turn record with its verdict (count mode never changes an output).
+  `conversation.claims.guard(stream)` holds what could start a claim until its sentence ends (150 ms at
+  most, 300 ms a message) and lets it go as the contract's actions say: a blocked sentence gives way to the
+  category's caveat, a stale copy of one field becomes its fresh value only when that is unequivocal, a
+  warning marks the claim. `claims.guardText()` does the same on a whole output. An immutable output never
+  changes: a block sends it to a person.
+- Coordination: `conversation.check()` asks before acting and, when Niadra does not answer within 200 ms,
+  decides by the purpose's direction (a customer's message and service go, marketing, retention,
+  collection and an effect with a key wait, the local opt-out always holds); `conversation.declare` sends
+  what happened in the background until Niadra takes it; `conversation.claim()` holds a lease or a task
+  lock. `task()` takes the same calls.
+- `niadra.contactGateway()` and `verifyContactToken()`: the contact token's offline check at your gateway
+  (Ed25519 through Web Crypto), with the space's public keys kept while Niadra is down and each token let
+  through once.
+- The agent's working state: `conversation.agentState.get()` and `put()`, compare-and-swap or merge by key
+  (`DELETE` removes a key), reading its own writes, kept and sent again while Niadra is down.
+- `niadra.resolvers` and `verifyClaim()`: a value not safe to claim is read again by your resolver, inside
+  your boundary and within 300 ms, and the fresh value decides. `ContentResolver` puts back the text a
+  pointer-mode space keeps in your storage, and `ResolverWorker` serves the space's refresh requests with
+  your resolvers.
+- Replay inside your boundary: `Replayer` runs the turns of a scenario N times with the build you pin,
+  answers your tools from the record (`tool(name, fn, { dryRun: true })` lets one run for real when the
+  record has no answer), keeps everything the agent sends from leaving, evaluates the assertions and
+  reports the run, and Niadra answers with the statistical verdict. Runs are numbered from 1, as the
+  replay spec numbers them.
+- `overlapAtK()`: the depth-weighted overlap of two ranked lists that the tool counterfactual reports
+  (`spec/counterfactual.md`, 4); it passes the `counterfactual-overlap` vectors.
+- The recording the SDK profile serves: a turn leaves in the content mode the space names for the source,
+  and a turn without a pin the space requires for replay is kept with a warning, once.
+- Turn records from the framework adapters. LangChain.js and LangGraph.js:
+  `new NiadraCallbackHandler(conversation, { turns: true })` records each top-level run as a turn, with its
+  tool calls (the provider's call ids) and its model calls with their tokens. Mastra:
+  `niadraProcessor({ turns: true })` records each request as a turn. Vercel AI SDK: `niadraMiddleware`
+  records each model call in the turn in progress, `recordTools(tools)` records each tool call with the
+  provider's call id, and `niadraTurn()` keeps a `streamText` turn open until the stream finishes. A run
+  inside a turn in progress records into it, and a function wrapped with `tool()` inside a framework's tool
+  takes over its call, so a replay answers it from the record.
+- `conversation.activeTurn()`: the turn in progress, from the async context or the newest the session
+  opened and has not closed; `tool()` takes `callId` and `frame` for frameworks that run tools elsewhere.
+- `canonicalJson()` and `jsonDigest()`: the digest of a turn record's value, SHA-256 over its canonical
+  JSON (RFC 8785), as every producer computes it.
+- `expr`: niadra-expr, the language of the type registry's conditions, timers, keys and readings.
+  `expr.parse()` reads an expression, `expr.compileExpression()` resolves its names against a type's
+  declarations, and `expr.evaluate()` computes it over an object's slots with the four logical values,
+  as the server does; it passes every case of `spec/vectors/niadra-expr.v0.json`. Dates and times are
+  integers (days, milliseconds), never the machine's time zone.
+- The conformance vectors of the open specifications, run by `test/vectors.test.ts`, and the design of
+  the turn capture (`docs/design/turn-capture.md`).
+- `canonicalDestination()` and `suppressionKey()`: a handle's canonical destination (`phone:+<E.164>`
+  with the Brazilian ninth digit, `email:<address>`) and its key per reader,
+  `base64url(HMAC-SHA256(salt, ...))`, as the suppression list and the contact token compute them.
+  `suppressionKey()` is async (Web Crypto); errors are `NiadraDestinationError`.
+- `exposureToken()` and `parseExposureToken()`: the exposure token a card carries,
+  `nx1.<id>.<position>.<verifier>`, built synchronously and read with the refusals of its spec
+  (`NiadraExposureTokenError`).
+- `renderConstraints()` and `honoredConstraints()`: the constraints block rendered for one tool call
+  through the tool's binding, in advisory or apply mode, and the count of what the call's results
+  honored.
+- `claims`: the claim contract's reference checker, pure and without a model. `mentions()` reads the
+  numbers of an output in Portuguese, English or Spanish (class, normalized value, span in code points),
+  `rolesOf()` their roles, `check()` the claims each category of a contract detects with their nature,
+  verdict and action, `detected()` what a phrase of the negative corpus must never trigger, and `score()`
+  the text anchor. It passes the claim-parser, claim-detect and claim-anchor vectors and finds nothing in
+  the negative corpus of the three example contracts.
+- The `niadra` command for Node (`npx niadra`): `resolver-worker`, `replay`, `counterfactual`,
+  `types derive` (with `--check`) and `contract test`, with the Python command's arguments and exit codes.
+  `types derive` reads one PostgreSQL table's catalog (never a row), computes the same fingerprint as the
+  Python SDK and passes the `type-derive` vectors; `--check` sends Niadra only the fingerprint and the
+  counts.
+- The blocks a read asks for reach the model: with `include`, the state view's lines and the constraints
+  block go in `suffix` after the slots, inside one `<niadra>` section in the pack's language, byte for byte
+  what the Python SDK writes; a read without blocks keeps its suffix. The context answer also carries the
+  coordination block.
+- `niadra.internalText`: fingerprints of the company's own prompt (the same SHA-256 shingles as the Python
+  SDK); a repeated passage gives way to the claim contract's `redact` line and is recorded with
+  `internal_text_found`, never the text.
+- `tool(name, fn, { binding })` records what a call did with the constraints block, and `maskOutput: true`
+  keeps the fields the key may not read from the model (the last profile read while Niadra is down,
+  `onUnknown: "block"` to fail closed). A turn keeps the pack, the block and the working state it read, and
+  what the person was shown or engaged with (`frame.interact`).
+- The tool counterfactual: `Counterfactual` behaves as the Python runner, sending Niadra only overlaps and
+  positions.
+- A replay starts from the working state the recorded turn read, and a sub-turn of a replayed turn is
+  replayed and never sent. Mastra tools answer from the record; LangChain tools passed through
+  `recordTools()` too, and the handler refuses any other with `NiadraReplayRefusedError` before it runs.
+- Turn records from OpenAI Agents JS, Google ADK and VoltAgent with `turns: true`: each run is a turn, with
+  each tool call (the framework's own call id) and each model call. ADK tools answer from the record in a
+  replay; OpenAI Agents JS and VoltAgent cannot stop a tool from their hooks, so wrap those tools with
+  `tool()` to replay them.
+- One example per concept of the agent core (`examples/claim-guard.ts`, `coordination.ts`, `object-state.ts`,
+  `working-state.ts`, `masked-tool.ts`, `tool-counterfactual.ts`) and `examples/ci/niadra-checks.yml`, each
+  run by the tests.
+- `ContextResponse.budget` (`BudgetBlock`, with `BudgetPack`, `BudgetUse` and `BudgetCut`): with
+  `include: ["budget"]`, what the pack costs per section, what this agent already spent in the conversation
+  and the case, and the units the measurement says it leaves unused. Shown, never enforced.
+- `niadra.api.overview()`: the coordination overview in counts (`GET /v1/coordination/overview`).
+- `pnpm sync-spec --spec` also copies the Context Pack schema (`spec/context-pack.v1.json`), and
+  `test/spec.test.ts` holds `ContextResponse` and every include block to it.
+- The tool bindings the space declares come in the SDK profile (`SdkProfile.tool_bindings`, typed
+  `ToolBinding`), for this source's tools. A tool without a binding in code measures the constraints block
+  and runs its counterfactual through the binding served for its name, and `binding` in code wins.
+  Left unset, `maskOutput` follows the served binding's `capabilities.mask_output`. `api.constraints()` with
+  `tool` answers the block rendered for that tool, as advice.
+- Watch revalidation in `ResolverWorker` and `npx niadra resolver-worker`: a watch fires only on a value its
+  source confirmed. The worker serves `watch_revalidation` requests first, pushes every object it read with
+  the `request_id` it answers (which settles the request and decides the object's due watches even when the
+  value did not change), and releases a request it cannot answer
+  (`POST /v1/state/refresh-requests/{id}/release`), as `not_found` when the resolver returns `NOT_FOUND` and
+  `failed` when it fails. A type without a resolver, or whose resolver's circuit is open, still waits out its
+  lease. `Resolvers.fetch()` says why a read brought no object.
+- `ConstraintsBlock.text`: the constraints block as the server writes it for a model, each field by its
+  type's label and each operator in words, in the space's language. The suffix places it as it places the
+  state view's text.
+- The claim contract reads the computed values a state read serves as evidence, by their name, while they
+  are claim-safe, and the claim guard takes as evidence every value the include blocks placed in the turn
+  block. A value that is not claim-safe backs nothing.
+- A hedged number is no claim (the claim contract spec, 5.4): "I can't confirm the $24.90 still applies" or
+  "$689.00, not $612.00" state no such price.