nexus-ai-pro 1.16.0 → 1.18.0

package/API_STABILITY.md

@@ -412,6 +412,36 @@ The `nexus-ai-pro/postgres` subpaths, `nexus-ai-pro/ops/circuit-store`, and
   so recordings made with one release keep replaying with the next. A change that would invalidate
   recordings waits for 2.0.
 
+## Prompt stages (1.17.0)
+
+The `nexus-ai-pro/prompts` subpaths and `nexus-ai-pro/postgres/prompts` are experimental in
+production readiness, as the image family is: their exported types, functions, and classes follow the
+1.x semantic versioning rules, and the experimental label does not permit an incompatible minor or
+patch release. None is exported from the root.
+
+- The content version algorithm is a guarantee. `promptVersion()` gives the same version for the
+  same content in every 1.x release, so an upgrade never re-versions a committed prompt.
+- Version, label, and history records only gain fields in the 1.x line, and the Postgres schema
+  follows the additive rule above.
+- The wording of gate reasons, of the note a forced promotion records, and of `formatPromptDiff()`
+  output is for people and may improve in any release.
+
+## Agent server stage (1.18.0)
+
+The `nexus-ai-pro/server` subpaths are experimental in production readiness, as the image and prompt
+families are: their exported types, functions, and classes follow the 1.x semantic versioning rules,
+and the experimental label does not permit an incompatible minor or patch release. Neither is exported
+from the root.
+
+- The routes listed in the server guide, their status codes, and the shape of `RunRecord`,
+  `ThreadRecord`, and `RunEvent` follow the 1.x rules. A minor release may add routes and fields.
+- Event ids are per run and strictly increasing, which is what `Last-Event-ID` depends on. A client
+  that reconnects with an id never receives it again.
+- The server is not a security boundary on its own: authentication, authorization beyond tenancy and
+  scopes, and rate limiting are the application's, through the hooks.
+- Recovery re-runs a whole run rather than the step it died on, so an assistant with side effects
+  should be idempotent or be left at a single attempt.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,101 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-09-25
+
+A server you can host. Assistants get an HTTP surface — threads, background runs, resumable event
+streams, and cron jobs — on top of the durability that already existed: a run is an operation, so it
+outlives the request that started it and the worker that was running it.
+
+### Added
+
+- **The agent server** (`nexus-ai-pro/server`, experimental). `createAgentServer()` serves assistants,
+  threads, runs, and cron jobs as one `Request`-to-`Response` handler. `toNodeListener()` runs it on
+  Node's `http`, and as Express or Fastify middleware.
+- **Assistants are structural.** `graphAssistant()` serves a compiled graph, mapping threads to graph
+  threads; `functionAssistant()` serves a plain function. The entry point imports neither runtime.
+- **Runs are durable operations**, so leases, heartbeats, retries, idempotency, dead-lettering, and
+  webhooks come from the operations family. A run abandoned by a crashed worker is re-claimed by
+  another replica through `start()` or `runs.recover()`.
+- **Resumable streaming.** `GET /runs/:id/events` is a server-sent event stream whose events carry
+  their log id, so a client reconnects with `Last-Event-ID` and gets exactly what it missed.
+  `MemoryRunEventLog` covers one replica; `RedisRunEventLog` lets a client reconnect to any replica.
+- **A busy thread is configurable**: `reject`, `enqueue`, `interrupt`, or `rollback`, per server or
+  per run.
+- **Cron jobs.** `CronScheduler` fires `{ everyMs }` or five-field cron schedules, parsed by
+  `parseCron()`. Every replica ticks and every firing carries the idempotency key `<job>:<slot>`, so a
+  job runs once however many replicas are up, with no lock and no leader election.
+- **Authentication and tenancy hooks.** `authenticate` returns a `Principal`; threads, runs, and cron
+  jobs record their tenant, and another tenant's resource is a `404`.
+- **`createRemoteGraph()`** (`nexus-ai-pro/server/remote`), the client: `invoke()`, `stream()` with
+  reconnection, `resume()`, and `asNode()`, which makes a deployed assistant a node in a local graph.
+- **Deployment templates**: `deploy/Dockerfile`, `deploy/compose.yaml` for two replicas behind Redis,
+  and an nginx configuration that does not buffer event streams. `examples/agent-server.ts` is a
+  runnable server.
+
+### Changed
+
+- **Every feature's exports are documented in that feature's guide.** A guide can now claim exports by
+  source directory, so features reachable only from the root — guardrails, grounding, workflows,
+  metrics, conformance, routing — no longer pile into the client guide, which drops from 249 exports
+  to 141. Retrieval, citations, and verification get a guide of their own, and the agents, batch,
+  caching, and client guides now explain every export they cover.
+
+### Fixed
+
+- An operation whose record was settled by another worker — after its lease lapsed and the work was
+  taken over — crashed the original worker with an unhandled `OperationTransitionError` from its
+  heartbeat. The heartbeat now stops and fails its local run instead, and a heartbeat that throws for
+  any other reason no longer becomes an unhandled rejection.
+
+## [1.17.0] - 2026-09-23
+
+Prompt versioning, and documentation you can navigate. Prompts are defined with typed variables,
+versioned by their content, promoted between labels only after their gates agree, and served through
+registry outages; every feature now has its own guide, and the README is an overview that links to them.
+
+### Added
+
+- **Prompt templates** (`nexus-ai-pro/prompts`). `definePrompt()` types a prompt's variables from its
+  template text, so a missing or misspelled variable is a compile-time error. Templates support dot
+  paths, partials, placeholders for whole messages, defaults, and a request configuration versioned
+  with the prompt. `promptVersion()` derives a version from the content, identical in every runtime.
+- **A prompt registry** (`nexus-ai-pro/prompts/registry`). `PromptRegistry` commits versions, points
+  labels such as `staging` and `production` at them, and records every change. `promote()` runs the
+  gates registered for the destination label: `experimentGate()` requires a passing experiment for
+  the exact version, with thresholds and an optional no-regression check, and `servedByGate()` requires
+  a version to be served by another label first. `rollback()`, `split()` for sticky A/B tests, and
+  `diff()` with `formatPromptDiff()` complete it. Label writes are compare-and-set, and changes can be
+  posted to signed webhooks, verified with `verifyPromptWebhook()`.
+- **`evaluatePrompt()`**, the headless playground: runs a prompt version over a dataset and stores an
+  experiment tagged with that version, which is what `experimentGate()` looks for.
+- **A serving client** (`nexus-ai-pro/prompts/client`). `PromptClient` caches labels with a TTL and a
+  stale-while-revalidate window, shares concurrent refreshes, keeps serving the last version seen when
+  the registry is unreachable, falls back to prompts bundled in code on a cold start, and picks a
+  sticky A/B arm per key.
+- **Prompt stores**: `MemoryPromptStore`, `FilePromptStore` (`/prompts/file`), `RedisPromptStore`
+  (`/prompts/redis`), and `PostgresPromptStore` (`/postgres/prompts`), all tested against one
+  contract. `postgresMigration()` and `nexus db sql` include the prompt tables.
+- A model call traced with `traceModelClient()` records the prompt name, version, label, and arm it
+  was rendered from.
+- **A guide for every feature**, under `docs/`. Each guide covers every export of its entry points and
+  ends with a reference generated from the doc comments. `npm run docs:guides` fails when an export
+  is not named in a guide or a reference is stale, and runs in `npm test`; `npm run docs:update`
+  regenerates the references.
+- `BinaryBuffer`: Node's `Buffer` when Node's types are loaded, otherwise `Uint8Array`.
+
+### Changed
+
+- The README is an overview that links to the guides; the moved sections live in `docs/`, and the
+  size table is in `docs/packaging.md`.
+- The combined Postgres migration creates three more tables, for prompts.
+
+### Fixed
+
+- The message types referred to Node's `Buffer` and `NodeJS.ReadableStream`, so a project without
+  Node's type definitions, such as a browser app, failed to type-check anything that reached them.
+  They now compile either way, and are unchanged for Node projects.
+
 ## [1.16.0] - 2026-09-22
 
 Shared state and the command line. Everything that has to outlive a process or be shared between
@@ -846,7 +941,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...HEAD
+[1.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.17.0...v1.18.0
+[1.17.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.12.0...v1.14.0