nexus-ai-pro 1.17.0 → 1.19.0

package/API_STABILITY.md

@@ -426,6 +426,35 @@ patch release. None is exported from the root.
 - 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.
+
+## Studio stage (1.19.0)
+
+`nexus-ai-pro-studio` is a separate package, experimental in production readiness. It is versioned
+with nexus-ai-pro and declares the core versions it works with as a peer dependency.
+
+- The `nexus-studio` command, its flags, and the shape of the config module's default export follow
+  the 1.x rules. A minor release may add sources and flags.
+- `createStudio()`, `startStudio()`, and the exported types follow the 1.x rules.
+- The JSON routes behind the page are for the page and may change in any release; build on the
+  stores themselves rather than on the studio's routes.
+- The access rules are a guarantee: loopback binding by default, a token on every request, the token
+  in a header for every change, and loopback hosts only unless others are allowed.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,120 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-09-28
+
+A studio to look at it all. `nexus-ai-pro-studio` is a separate package — so the core install never
+carries a UI — that shows what an application records, from its own stores, on the developer's
+machine, with no hosted service.
+
+### Added
+
+- **`nexus-ai-pro-studio`**, experimental, with the `nexus-studio` command. Given a config module
+  whose default export lists the application's stores, it serves eight views:
+  - **Traces**: filtered run lists, run trees with inputs, outputs, cost, and latency, trace
+    comparison, and feedback on a run.
+  - **Threads**: each graph's diagram with the next nodes highlighted, state at any step, and fork,
+    edit, and resume.
+  - **Inbox**: every thread waiting for a human and every review item waiting for a grade.
+  - **Experiments**: experiment and dataset lists, and comparisons with per-metric intervals and a
+    verdict.
+  - **Prompts**: versions, labels, history, diffs, gated promotion, rollback, and a playground.
+  - **Costs**: cost per day and per model, the most expensive runs, and budgets.
+  - **Health**: provider health, local and shared circuit state, metrics, and cache statistics.
+  - **Operations**: the operation queue by status, and asset store totals.
+- **Locked down for a local tool.** It binds `127.0.0.1`, requires a token that moves from the URL
+  into an HTTP-only same-site cookie, requires the token in a header for every change, refuses
+  non-loopback `Host` headers against DNS rebinding, and serves every page under a strict content
+  security policy with every value inserted as text.
+- `startStudio()` and `createStudio()` start it from code or mount it in an existing server.
+- `npm run studio:demo` starts it on a demo application with something in every view.
+- The operation-store checkpointer — the one behind Redis and Postgres — lists its threads through
+  `threadIds()`, as the in-memory one already did, and `GraphCheckpointer` declares it as optional.
+
+### Fixed
+
+- **Secret detection on input now detects under every action.** It only scanned when the action
+  was `mask`. Under the default action, `block`, and under `flag`, a request carrying a private
+  key, a cloud or payment key, a token, or a secret assignment went out with no finding. Such a
+  request is now blocked by default, at every level but `off`. Set `input.secrets.action` to `flag`
+  to record secrets without blocking.
+- The PII action `remove` deletes the matched data. It was accepted but behaved like `flag`, so the
+  data stayed in the request.
+- The semantic injection check no longer re-embeds its example attacks on every request.
+- `McpServer` answers an unknown method with the JSON-RPC method-not-found code, and an unknown
+  resource with invalid-params, instead of an internal error, so a client can tell an unsupported
+  feature from a failure.
+- `McpClient` requests made together before the handshake finished each sent `initialize`; they now
+  share one handshake.
+- `summarizeVerifyFormat()`'s verify step sent the summary to the model with no instruction, so the
+  model answered the summary instead of restating it, and that reply was what got checked against
+  the sources. It now asks for a restatement against the sources. The final format is applied only in
+  the last step, and a verify step that was skipped is no longer recorded in `steps`.
+- `traceModelClient()` records the model and provider that answered on the run itself. It recorded
+  the model the request asked for — often `auto` — and left `provider` empty, so a `provider` query
+  never matched a model run and per-model views showed `auto`. `FinishRunOptions` gains `model` and
+  `provider` for the same purpose in your own instrumentation.
+
+### Deprecated
+
+- `InjectionDetectionConfig.sensitivity` and `ToolPolicyConfig.requiresApproval` have never been
+  read. Both will be removed in 2.0; approval before a tool runs belongs to the agent loop.
+
+### Changed
+
+- Nineteen guides under `docs/` — agents, batch, caching, core, graphs, grounding, MCP, memory,
+  Postgres, prompts, providers, resilience, security, server, telephony, testing, tracing, voice, and
+  workflows — now explain each export they list in their text, not only in the generated reference.
+  The security configuration's nested settings have doc comments.
+- The documentation coverage check also covers the studio package's exports.
+
+## [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,
@@ -894,7 +1008,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.17.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...HEAD
+[1.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...v1.19.0
+[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

package/README.md

@@ -118,12 +118,15 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Resilience and observability](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/resilience.md) | Circuit breaking, distributed rate limits, metrics, logs, and audit |
 | [Batch tiers](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/batch.md) | The providers' discounted batch APIs, resumable from any process |
 | [Caching](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/caching.md) | Exact and semantic response caches, with memory, Redis, and SQLite adapters |
+| [Grounding](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/grounding.md) | Retrieval, citations, verification, self-consistency, and knowledge graphs |
 | [Embeddings and retrieval](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/embeddings.md) | Embeddings as a routed operation family, and RAG helpers |
 | [Images (experimental)](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/images.md) | Generation and masked edits over three backends, input safety, moderation, asset stores |
 | [Voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/voice.md) | Transcription, speech, voice turns, and voice sessions |
 | [Realtime voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/realtime.md) | Browser and server realtime sessions with barge-in, tools, and exports |
 | [Telephony](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/telephony.md) | Calls, webhooks, phone numbers, and phone agents on realtime sessions |
 | [Testing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/testing.md) | Recording and replaying provider traffic, and conformance suites |
+| [Studio](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/studio.md) | A local UI for traces, threads, approvals, experiments, prompts, costs, and health, as a separate package |
+| [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron |
 | [Workflows](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/workflows.md) | Ready-made chains and domain workflows |
 | [Command line](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/cli.md) | The `nexus` command |
 | [Packaging and install weight](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) | Every entry point and what it costs |

package/dist/graph/checkpointer.d.ts

@@ -66,6 +66,11 @@ export declare class OperationStoreCheckpointer implements GraphCheckpointer {
     history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
     /** Deletes a thread's checkpoints and its head. */
     delete(threadId: string): Promise<void>;
+    /**
+     * Every thread with a checkpoint, read from the head records. Empty when the store cannot list,
+     * since finding heads any other way would mean scanning every key.
+     */
+    threadIds(): Promise<string[]>;
     private readHead;
     /**
      * Writes one record, creating it when absent and otherwise updating in place.

package/dist/graph/checkpointer.js

@@ -86,6 +86,15 @@ export class OperationStoreCheckpointer {
             await this.store.delete?.(stepId(threadId, step));
         await this.store.delete?.(threadId);
     }
+    async threadIds() {
+        if (!this.store.list)
+            return [];
+        const records = await this.store.list();
+        return records
+            .filter((record) => record.result !== undefined && isHead(record.result))
+            .map((record) => record.id)
+            .sort();
+    }
     async readHead(threadId) {
         const record = await this.store.read(threadId);
         return record?.result && isHead(record.result) ? record.result : undefined;

package/dist/mcp/client.d.ts

@@ -62,13 +62,18 @@ export declare class McpClient {
     private readonly pending;
     private nextId;
     private initialized;
+    private connecting;
     private serverInfo;
     constructor(transport: McpTransport, options?: McpClientOptions);
-    /** Performs the handshake. Called automatically by the first request that needs it. */
+    /**
+     * Performs the handshake and returns the server's name and version. Called automatically by the
+     * first request that needs it; requests made together share one handshake.
+     */
     connect(): Promise<{
         name?: string;
         version?: string;
     }>;
+    private handshake;
     /** Lists the server's tools. */
     listTools(): Promise<McpToolDescriptor[]>;
     /**

package/dist/mcp/client.js

@@ -5,6 +5,7 @@ export class McpClient {
     pending = new Map();
     nextId = 1;
     initialized = false;
+    connecting;
     serverInfo = {};
     constructor(transport, options = {}) {
         this.transport = transport;
@@ -15,6 +16,12 @@ export class McpClient {
     async connect() {
         if (this.initialized)
             return this.serverInfo;
+        this.connecting ??= this.handshake().finally(() => {
+            this.connecting = undefined;
+        });
+        return this.connecting;
+    }
+    async handshake() {
         await this.transport.start?.();
         const result = (await this.request('initialize', {
             protocolVersion: MCP_PROTOCOL_VERSION,

package/dist/mcp/server.js

@@ -1,4 +1,4 @@
-import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, textContent, } from './protocol.js';
+import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, textContent, } from './protocol.js';
 export class McpServer {
     options;
     tools = new Map();
@@ -35,7 +35,7 @@ export class McpServer {
                 jsonrpc: '2.0',
                 id: message.id,
                 error: {
-                    code: JSON_RPC_ERRORS.internal,
+                    code: error instanceof McpError ? error.code : JSON_RPC_ERRORS.internal,
                     message: error instanceof Error ? error.message : String(error),
                 },
             });
@@ -89,7 +89,7 @@ export class McpServer {
                 const uri = String(params.uri ?? '');
                 const resource = this.options.resources?.find((item) => item.uri === uri);
                 if (!resource)
-                    throw new Error(`Unknown resource "${uri}"`);
+                    throw new McpError(`Unknown resource "${uri}"`, JSON_RPC_ERRORS.invalidParams);
                 const value = await resource.read();
                 return {
                     contents: [
@@ -102,7 +102,7 @@ export class McpServer {
                 };
             }
             default:
-                throw new Error(`Unknown method "${request.method}"`);
+                throw new McpError(`Unknown method "${request.method}"`, JSON_RPC_ERRORS.methodNotFound);
         }
     }
 }

package/dist/operations/runner.js

@@ -233,6 +233,10 @@ export class OperationRunner {
                 handle.settleFailure(new OperationLeaseLostError(latest.id, current.lease.owner));
                 return;
             }
+            if (isTerminalOperationStatus(current.status)) {
+                handle.settleFailure(new OperationLeaseLostError(latest.id, current.lease?.owner ?? 'another worker'));
+                return;
+            }
             const renewed = this.advance(current, 'running');
             renewed.lease = {
                 owner: this.owner,
@@ -243,7 +247,13 @@ export class OperationRunner {
             if (await this.store.update(renewed, current.sequence))
                 latest = renewed;
         };
-        const timer = setInterval(() => void beat(), this.heartbeatMs);
+        const timer = setInterval(() => {
+            void beat().catch((error) => {
+                stopped = true;
+                clearInterval(timer);
+                handle.settleFailure(error);
+            });
+        }, this.heartbeatMs);
         timer.unref?.();
         return {
             stop: () => {

package/dist/security/index.js

@@ -63,9 +63,9 @@ export class SecurityPipeline {
             findings.push(...piiFindings);
             guardrailsApplied.push('pii-detection');
             const action = piiConfig.action || (level === 'strict' || level === 'paranoid' ? 'mask' : 'flag');
-            if (piiFindings.length > 0 && action === 'mask') {
-                safeRequest = this.piiDetector.mask(safeRequest, piiConfig);
-                guardrailsApplied.push('pii-masking');
+            if (piiFindings.length > 0 && (action === 'mask' || action === 'remove')) {
+                safeRequest = this.piiDetector.mask(safeRequest, { ...piiConfig, action });
+                guardrailsApplied.push(action === 'remove' ? 'pii-removal' : 'pii-masking');
             }
         }
         const blockingFindings = this.getBlockingFindings(findings, level, normalized);

package/dist/security/input-guard.js

@@ -103,8 +103,13 @@ export class InputGuard {
             });
             return output;
         };
-        if (action !== 'mask')
+        if (action !== 'mask') {
+            request.messages.forEach((message, index) => {
+                for (const text of this.extractText(message))
+                    maskText(text, `messages.${index}.content`);
+            });
             return request;
+        }
         return {
             ...request,
             messages: request.messages.map((message, index) => ({

package/dist/security/pii-detector.d.ts

@@ -4,7 +4,7 @@ import type { PIIConfig, SecurityFinding } from '../types/security.js';
 export declare class PIIDetector {
     /** Finds personal data in a request's messages. */
     detect(request: CompletionRequest, config?: PIIConfig): SecurityFinding[];
-    /** Returns the request with personal data masked. */
+    /** Returns the request with personal data masked, or removed when the action is `remove`. */
     mask(request: CompletionRequest, config?: PIIConfig): CompletionRequest;
     private maskText;
     private extractText;

package/dist/security/pii-detector.js

@@ -35,22 +35,28 @@ export class PIIDetector {
     mask(request, config = {}) {
         const enabledTypes = config.detect || ['email', 'phone', 'credit-card', 'ip-address', 'aws-key', 'private-key'];
         const maskChar = config.maskChar || '█';
+        const remove = config.action === 'remove';
         return {
             ...request,
             messages: request.messages.map((message) => ({
                 ...message,
                 content: typeof message.content === 'string'
-                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false)
+                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false, remove)
                     : message.content.map((part) => part.type === 'text'
-                        ? { ...part, text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false) }
+                        ? {
+                            ...part,
+                            text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false, remove),
+                        }
                         : part),
             })),
         };
     }
-    maskText(text, types, maskChar, preserveFormat) {
+    maskText(text, types, maskChar, preserveFormat, remove = false) {
         let masked = text;
         for (const type of types) {
             masked = masked.replace(PII_PATTERNS[type], (value) => {
+                if (remove)
+                    return '';
                 if (!preserveFormat)
                     return maskChar.repeat(Math.min(value.length, 12));
                 return value.replace(/[A-Za-z0-9]/g, maskChar);

package/dist/security/prompt-hardening.d.ts

@@ -1,6 +1,9 @@
 import type { CompletionRequest } from '../types/messages.js';
+/** Options for `hardenPrompt()`. */
 export interface PromptHardeningOptions {
+    /** What user text is wrapped in. Defaults to `"""`. */
     delimiter?: string;
+    /** The system message placed first, telling the model to treat delimited text as data. */
     systemInstruction?: string;
 }
 /**

package/dist/security/semantic-injection-classifier.d.ts

@@ -1,10 +1,15 @@
 import type { CompletionRequest } from '../types/messages.js';
 import type { SecurityFinding } from '../types/security.js';
 import { type EmbeddingProvider } from '../hallucination/retrieval.js';
+/** Options for `SemanticInjectionClassifier`. */
 export interface SemanticInjectionClassifierOptions {
+    /** `false` turns `detect()` off. */
     enabled?: boolean;
+    /** Similarity at which a prompt is flagged, from 0 to 1. Defaults to 0.78; above 0.88 is critical. */
     threshold?: number;
+    /** Embeds text for `detect()`. Defaults to hashed term vectors; `detectSync()` always uses those. */
     embed?: EmbeddingProvider;
+    /** Example attacks to compare against, instead of the built-in ones. */
     examples?: string[];
 }
 /**
@@ -16,6 +21,7 @@ export declare class SemanticInjectionClassifier {
     private examples;
     private embed;
     private exampleEmbeddings?;
+    private hashedExamples?;
     constructor(options?: SemanticInjectionClassifierOptions);
     /** Finds injection attempts, using the configured embedding function. */
     detect(request: CompletionRequest): Promise<SecurityFinding[]>;

package/dist/security/semantic-injection-classifier.js

@@ -12,6 +12,7 @@ export class SemanticInjectionClassifier {
     examples;
     embed;
     exampleEmbeddings;
+    hashedExamples;
     constructor(options = {}) {
         this.options = options;
         this.examples = options.examples || DEFAULT_ATTACK_EXAMPLES;
@@ -43,7 +44,8 @@ export class SemanticInjectionClassifier {
     detectSync(request) {
         const findings = [];
         const threshold = this.options.threshold ?? 0.78;
-        const exampleEmbeddings = createHashEmbeddings(this.examples);
+        this.hashedExamples ??= createHashEmbeddings(this.examples);
+        const exampleEmbeddings = this.hashedExamples;
         for (const [index, message] of request.messages.entries()) {
             for (const text of extractText(message)) {
                 const [embedding] = createHashEmbeddings([text]);

package/dist/server/assistant.d.ts

@@ -0,0 +1,52 @@
+import type { AssistantRunContext, ServerAssistant } from '../types/server.js';
+/**
+ * The part of a compiled graph the adapter uses.
+ *
+ * Structural, so the server entry point never imports the graph runtime: an application that serves
+ * plain functions does not load it, and one that serves graphs already has it.
+ */
+export interface GraphLike {
+    /** Runs an input, yielding one event per superstep. */
+    stream(input: unknown, options: {
+        threadId?: string;
+        signal?: AbortSignal;
+        metadata?: Record<string, unknown>;
+    }): AsyncIterable<unknown>;
+    /** Answers an interrupt and continues the thread. */
+    resume(threadId: string, value: unknown, options: {
+        signal?: AbortSignal;
+        metadata?: Record<string, unknown>;
+    }): AsyncIterable<unknown>;
+    /** The thread's checkpoint, at its latest step or at one given. */
+    state(threadId: string, step?: number): Promise<{
+        step?: number;
+        state?: unknown;
+    } | undefined>;
+    /** Writes values into a thread's state, which is how a rollback is applied. */
+    updateState?(threadId: string, values: Record<string, unknown>, options?: {
+        asNode?: string;
+    }): Promise<unknown>;
+}
+/** Options for `graphAssistant()`. */
+export interface GraphAssistantOptions {
+    /** What the assistant is, reported by the assistants endpoint. */
+    description?: string;
+    /** Metadata recorded on every checkpoint the server's runs create. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serves a compiled graph as an assistant.
+ *
+ * Threads map to graph threads, so state, interrupts, history, and checkpoints are the graph's own;
+ * the server adds only the record of which run owns a thread. A graph compiled without a
+ * checkpointer still works for stateless runs, but cannot resume or roll back.
+ */
+export declare function graphAssistant(graph: GraphLike, options?: GraphAssistantOptions): ServerAssistant;
+/**
+ * Serves a plain function as an assistant, for work that is not a graph.
+ *
+ * The function may return a value or yield events; the last value it yields is the run's output.
+ */
+export declare function functionAssistant(run: (input: unknown, context: AssistantRunContext) => AsyncIterable<unknown> | Promise<unknown> | unknown, options?: {
+    description?: string;
+}): ServerAssistant;

package/dist/server/assistant.js

@@ -0,0 +1,45 @@
+export function graphAssistant(graph, options = {}) {
+    return {
+        description: options.description,
+        stream(input, context) {
+            return graph.stream(input ?? {}, {
+                threadId: context.threadId,
+                signal: context.signal,
+                metadata: { ...options.metadata, runId: context.runId },
+            });
+        },
+        resume(threadId, value, context) {
+            return graph.resume(threadId, value, {
+                signal: context.signal,
+                metadata: { ...options.metadata, runId: context.runId },
+            });
+        },
+        async state(threadId) {
+            return (await graph.state(threadId))?.state;
+        },
+        async step(threadId) {
+            return (await graph.state(threadId))?.step;
+        },
+        async restore(threadId, step) {
+            if (!graph.updateState)
+                return;
+            const checkpoint = await graph.state(threadId, step);
+            if (!checkpoint?.state)
+                return;
+            await graph.updateState(threadId, checkpoint.state);
+        },
+    };
+}
+export function functionAssistant(run, options = {}) {
+    return {
+        description: options.description,
+        async *stream(input, context) {
+            const result = run(input, context);
+            if (result !== null && typeof result === 'object' && Symbol.asyncIterator in result) {
+                yield* result;
+                return;
+            }
+            yield { type: 'done', status: 'succeeded', state: await result };
+        },
+    };
+}

package/dist/server/cron.d.ts

@@ -0,0 +1,69 @@
+import type { CronRecord, RunRecord, ServerStateStore } from '../types/server.js';
+/** A cron job that is due, with the slot it is due for. */
+export interface DueCronJob extends CronRecord {
+    /** The firing this is: the epoch millisecond of the slot, which makes the run idempotent. */
+    slot: number;
+}
+/** Options for the cron scheduler. */
+export interface CronSchedulerOptions {
+    /** Starts a run for a due job. */
+    start?: (job: DueCronJob) => Promise<RunRecord>;
+    /** Where jobs are recorded. Defaults to memory; share it to schedule across replicas. */
+    state?: ServerStateStore;
+    /** How often due jobs are looked for, in milliseconds. Defaults to 30 seconds. */
+    tickMs?: number;
+    /** Receives errors from a firing, which never stop the scheduler. */
+    onError?: (error: unknown, job: CronRecord) => void;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
+}
+/**
+ * Fires scheduled runs.
+ *
+ * Every replica ticks, and every firing is submitted with the idempotency key `<job>:<slot>`, so the
+ * operation store decides which replica's submission wins and the job runs once however many
+ * replicas are up. That is the whole coordination mechanism: no lock, no leader election, and a
+ * replica that misses a tick simply does not win that slot.
+ */
+export declare class CronScheduler {
+    private readonly options;
+    private readonly state;
+    private readonly now;
+    private timer;
+    private lastTick;
+    constructor(options?: CronSchedulerOptions);
+    /** Adds a job, validating its schedule. */
+    add(job: Omit<CronRecord, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): Promise<CronRecord>;
+    /** Reads a job. */
+    get(id: string): Promise<CronRecord | undefined>;
+    /** Every job. */
+    list(): Promise<CronRecord[]>;
+    /** Removes a job. */
+    remove(id: string): Promise<void>;
+    /** Starts ticking. Ticks are skipped while one is still running. */
+    start(): void;
+    /** Stops ticking. */
+    stop(): void;
+    /**
+     * Fires every job due since the last tick. Call it directly to drive the scheduler from a test or
+     * from an external scheduler such as Kubernetes.
+     */
+    tick(at?: Date): Promise<DueCronJob[]>;
+}
+interface CronFields {
+    minute: number[];
+    hour: number[];
+    day: number[];
+    month: number[];
+    weekday: number[];
+}
+/**
+ * Parses the five-field cron syntax: `*`, numbers, `a-b` ranges, `a,b` lists, and `*​/n` steps.
+ *
+ * Times are UTC, so a schedule means the same thing on every replica whatever its timezone is set to.
+ */
+export declare function parseCron(expression: string): CronFields;
+export {};