nexus-ai-pro 1.17.0 → 1.18.0

package/API_STABILITY.md

@@ -426,6 +426,22 @@ 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.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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,
@@ -894,7 +941,8 @@ 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.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

package/README.md

@@ -118,12 +118,14 @@ 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 |
+| [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/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/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 {};

package/dist/server/cron.js

@@ -0,0 +1,172 @@
+import { BadRequestError } from './errors.js';
+import { MemoryServerStore } from './state.js';
+const CRONS = ['nexus', 'server', 'crons'];
+export class CronScheduler {
+    options;
+    state;
+    now;
+    timer;
+    lastTick = 0;
+    constructor(options = {}) {
+        this.options = options;
+        this.state = options.state ?? new MemoryServerStore();
+        this.now = options.now ?? (() => new Date());
+    }
+    async add(job) {
+        if ('cron' in job.schedule)
+            parseCron(job.schedule.cron);
+        else if (!(job.schedule.everyMs > 0))
+            throw new BadRequestError('"everyMs" must be a positive number');
+        const record = {
+            ...job,
+            id: job.id?.trim() || `cron-${Math.random().toString(36).slice(2, 10)}`,
+            createdAt: job.createdAt ?? this.now().toISOString(),
+        };
+        await this.state.put(CRONS, record.id, record);
+        return record;
+    }
+    async get(id) {
+        return this.state.get(CRONS, id);
+    }
+    async list() {
+        return this.state.list(CRONS, { limit: 500 });
+    }
+    async remove(id) {
+        await this.state.delete(CRONS, id);
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.lastTick = this.now().getTime();
+        const tickMs = this.options.tickMs ?? 30_000;
+        let running = false;
+        this.timer = setInterval(() => {
+            if (running)
+                return;
+            running = true;
+            void this.tick().finally(() => {
+                running = false;
+            });
+        }, tickMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    async tick(at = this.now()) {
+        const now = at.getTime();
+        const since = this.lastTick || now - (this.options.tickMs ?? 30_000);
+        this.lastTick = now;
+        const fired = [];
+        for (const job of await this.list()) {
+            if (job.paused)
+                continue;
+            const slot = dueSlot(job, since, now);
+            if (slot === undefined)
+                continue;
+            const due = { ...job, slot };
+            try {
+                const run = await this.options.start?.(due);
+                await this.state.put(CRONS, job.id, {
+                    ...job,
+                    lastRunAt: new Date(slot).toISOString(),
+                    lastRunId: run?.id ?? job.lastRunId,
+                });
+                fired.push(due);
+            }
+            catch (error) {
+                this.options.onError?.(error, job);
+            }
+        }
+        return fired;
+    }
+}
+function dueSlot(job, since, now) {
+    if ('everyMs' in job.schedule) {
+        const every = job.schedule.everyMs;
+        const last = job.lastRunAt ? Date.parse(job.lastRunAt) : undefined;
+        const previous = last ?? since;
+        if (now - previous < every)
+            return undefined;
+        return Math.floor(now / every) * every;
+    }
+    const fields = parseCron(job.schedule.cron);
+    const lastRun = job.lastRunAt ? Date.parse(job.lastRunAt) : 0;
+    for (let minute = Math.floor(now / 60_000) * 60_000; minute > since - 60_000 && minute > lastRun; minute -= 60_000) {
+        if (matches(fields, new Date(minute)))
+            return minute;
+    }
+    return undefined;
+}
+export function parseCron(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new BadRequestError(`"${expression}" is not a 5-field cron expression`, 'BAD_CRON');
+    }
+    const ranges = [
+        [0, 59],
+        [0, 23],
+        [1, 31],
+        [1, 12],
+        [0, 6],
+    ];
+    const fields = parts.map((part, index) => {
+        const [min, max] = ranges[index];
+        return field(part, min, max, expression);
+    });
+    return {
+        minute: fields[0],
+        hour: fields[1],
+        day: fields[2],
+        month: fields[3],
+        weekday: fields[4].map((value) => value % 7),
+    };
+}
+function field(part, min, max, expression) {
+    const values = new Set();
+    for (const item of part.split(',')) {
+        const [range, stepText] = item.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new BadRequestError(`"${expression}" has an invalid step`, 'BAD_CRON');
+        let start = min;
+        let end = max;
+        if (range !== '*' && range !== undefined && range !== '') {
+            const bounds = range.split('-').map(Number);
+            start = bounds[0];
+            end = bounds.length > 1 ? bounds[1] : bounds[0];
+            if (!Number.isInteger(start) || !Number.isInteger(end) || start < min || end > max || end < start) {
+                throw new BadRequestError(`"${expression}" has a field outside ${min}-${max}`, 'BAD_CRON');
+            }
+            if (stepText !== undefined && bounds.length === 1)
+                end = max;
+        }
+        for (let value = start; value <= end; value += step)
+            values.add(value);
+    }
+    return [...values].sort((a, b) => a - b);
+}
+function matches(fields, at) {
+    if (!fields.minute.includes(at.getUTCMinutes()))
+        return false;
+    if (!fields.hour.includes(at.getUTCHours()))
+        return false;
+    if (!fields.month.includes(at.getUTCMonth() + 1))
+        return false;
+    const byDay = isRestricted(fields.day, 1, 31);
+    const byWeekday = isRestricted(fields.weekday, 0, 6);
+    const dayMatches = fields.day.includes(at.getUTCDate());
+    const weekdayMatches = fields.weekday.includes(at.getUTCDay());
+    if (byDay && byWeekday)
+        return dayMatches || weekdayMatches;
+    if (byDay)
+        return dayMatches;
+    if (byWeekday)
+        return weekdayMatches;
+    return true;
+}
+function isRestricted(values, min, max) {
+    return values.length !== max - min + 1;
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,56 @@
+/** Base class for server errors. Each carries the HTTP status the server answers with. */
+export declare class ServerError extends Error {
+    /** Stable code, such as `THREAD_BUSY`, sent in the error body. */
+    readonly code: string;
+    /** HTTP status the server answers with. */
+    readonly status: number;
+    constructor(message: string, 
+    /** Stable code, such as `THREAD_BUSY`, sent in the error body. */
+    code: string, 
+    /** HTTP status the server answers with. */
+    status: number);
+}
+/** Raised when a request names something that does not exist, or belongs to another tenant. */
+export declare class NotFoundError extends ServerError {
+    constructor(what: string, id: string);
+}
+/** Raised when a request is malformed: bad JSON, a missing field, or an unknown assistant. */
+export declare class BadRequestError extends ServerError {
+    constructor(message: string, code?: string);
+}
+/** Raised when a request carries no usable credentials. */
+export declare class UnauthorizedError extends ServerError {
+    constructor(message?: string);
+}
+/** Raised when a principal is known but not allowed to do this. */
+export declare class ForbiddenError extends ServerError {
+    /** The scope the route required. */
+    readonly scope: string;
+    constructor(
+    /** The scope the route required. */
+    scope: string);
+}
+/** Raised when a thread is already running something and the busy policy is `reject`. */
+export declare class ThreadBusyError extends ServerError {
+    /** The thread. */
+    readonly threadId: string;
+    /** The run already in flight. */
+    readonly runId: string;
+    constructor(
+    /** The thread. */
+    threadId: string, 
+    /** The run already in flight. */
+    runId: string);
+}
+/** Raised when an assistant cannot do what a request needs, such as resuming or rolling back. */
+export declare class AssistantCapabilityError extends ServerError {
+    /** The assistant. */
+    readonly assistant: string;
+    /** What it cannot do. */
+    readonly capability: string;
+    constructor(
+    /** The assistant. */
+    assistant: string, 
+    /** What it cannot do. */
+    capability: string);
+}

package/dist/server/errors.js

@@ -0,0 +1,56 @@
+export class ServerError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'ServerError';
+    }
+}
+export class NotFoundError extends ServerError {
+    constructor(what, id) {
+        super(`${what} "${id}" was not found`, 'NOT_FOUND', 404);
+        this.name = 'NotFoundError';
+    }
+}
+export class BadRequestError extends ServerError {
+    constructor(message, code = 'BAD_REQUEST') {
+        super(message, code, 400);
+        this.name = 'BadRequestError';
+    }
+}
+export class UnauthorizedError extends ServerError {
+    constructor(message = 'Authentication is required') {
+        super(message, 'UNAUTHORIZED', 401);
+        this.name = 'UnauthorizedError';
+    }
+}
+export class ForbiddenError extends ServerError {
+    scope;
+    constructor(scope) {
+        super(`This request requires the "${scope}" scope`, 'FORBIDDEN', 403);
+        this.scope = scope;
+        this.name = 'ForbiddenError';
+    }
+}
+export class ThreadBusyError extends ServerError {
+    threadId;
+    runId;
+    constructor(threadId, runId) {
+        super(`Thread "${threadId}" is already running "${runId}"`, 'THREAD_BUSY', 409);
+        this.threadId = threadId;
+        this.runId = runId;
+        this.name = 'ThreadBusyError';
+    }
+}
+export class AssistantCapabilityError extends ServerError {
+    assistant;
+    capability;
+    constructor(assistant, capability) {
+        super(`Assistant "${assistant}" does not support ${capability}`, 'ASSISTANT_CAPABILITY', 409);
+        this.assistant = assistant;
+        this.capability = capability;
+        this.name = 'AssistantCapabilityError';
+    }
+}

package/dist/server/events.d.ts

@@ -0,0 +1,91 @@
+import type { RunEvent, RunEventLog } from '../types/server.js';
+/** Options for the in-memory run event log. */
+export interface MemoryRunEventLogOptions {
+    /** Events kept per run before the oldest are dropped. Defaults to 1,000. */
+    maxEventsPerRun?: number;
+    /** Runs kept before the least recently written is dropped. Defaults to 1,000. */
+    maxRuns?: number;
+}
+/**
+ * Run events in process memory, with waiters woken as events arrive.
+ *
+ * The default, and all a single-process server needs: a client that reconnects reads what it missed
+ * from here. Across replicas the log has to be shared, which is what `RedisRunEventLog` is for.
+ */
+export declare class MemoryRunEventLog implements RunEventLog {
+    private readonly runs;
+    private readonly waiters;
+    private readonly maxEvents;
+    private readonly maxRuns;
+    constructor(options?: MemoryRunEventLogOptions);
+    /** Appends an event, numbering it, and wakes anything waiting on this run. */
+    append(runId: string, event: Omit<RunEvent, 'id' | 'runId'>): RunEvent;
+    /** Events of a run after an id, oldest first. */
+    read(runId: string, options?: {
+        after?: number;
+        limit?: number;
+    }): RunEvent[];
+    /** Resolves as soon as an event after `after` exists, or when the wait is aborted or times out. */
+    wait(runId: string, after: number, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Forgets a run's events. */
+    clear(runId: string): void;
+}
+/**
+ * The Redis commands the event log needs, in `ioredis` argument order.
+ *
+ * Structural, as with the other Redis adapters, so no Redis client becomes a dependency.
+ */
+export interface RedisEventLogLikeClient {
+    /** Appends to a list and returns its new length, which numbers the event. */
+    rpush(key: string, value: string): Promise<number | unknown> | number | unknown;
+    /** Reads a range of a list. */
+    lrange(key: string, start: number, stop: number): Promise<string[]> | string[];
+    /** Trims a list to a range. */
+    ltrim(key: string, start: number, stop: number): Promise<unknown> | unknown;
+    /** Sets a key's lifetime in seconds. */
+    expire(key: string, seconds: number): Promise<unknown> | unknown;
+    /** Deletes a key. */
+    del(key: string): Promise<unknown> | unknown;
+}
+/** Options for the Redis run event log. */
+export interface RedisRunEventLogOptions {
+    /** Key prefix. Defaults to `nexus-ai-pro:runs:`. */
+    prefix?: string;
+    /** Events kept per run. Defaults to 1,000. */
+    maxEventsPerRun?: number;
+    /** How long a run's events live after the last append, in seconds. Defaults to one day. */
+    ttlSeconds?: number;
+    /** How often a waiting reader looks again, in milliseconds. Defaults to 250. */
+    pollIntervalMs?: number;
+}
+/**
+ * Run events in Redis, so a client can reconnect to any replica and resume.
+ *
+ * One list per run, whose length numbers each event, which is what makes ids stable without a second
+ * counter. Waiting readers poll rather than subscribe, so the log needs no second connection and no
+ * pub/sub delivery guarantees; the poll interval is the only latency a reconnecting client sees.
+ */
+export declare class RedisRunEventLog implements RunEventLog {
+    private readonly client;
+    private readonly options;
+    private readonly prefix;
+    constructor(client: RedisEventLogLikeClient, options?: RedisRunEventLogOptions);
+    /** Appends an event, numbered by the list's new length. */
+    append(runId: string, event: Omit<RunEvent, 'id' | 'runId'>): Promise<RunEvent>;
+    /** Events of a run after an id, oldest first. */
+    read(runId: string, options?: {
+        after?: number;
+        limit?: number;
+    }): Promise<RunEvent[]>;
+    /** Polls until an event after `after` exists, or the wait is aborted or times out. */
+    wait(runId: string, after: number, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Forgets a run's events. */
+    clear(runId: string): Promise<void>;
+    private key;
+}