nexus-ai-pro 1.5.0 → 1.6.0

package/API_STABILITY.md

@@ -131,6 +131,33 @@ and are overridable through `embeddings.models.registry`. Which concrete model a
 not interchangeable, so pin a concrete model whenever a stored index must stay valid across
 upgrades. Provider payloads under `raw` and reported token counts are controlled by the provider.
 
+## Operations API stage
+
+The `nexus-ai-pro/operations` family is public and follows the 1.x rules, including the
+`operations/adapters` and `operations/webhooks` subpaths. This covers `OperationRunner`,
+`LocalOperationHandle`, `MemoryOperationStore`, the `OperationStore` and `OperationDispatcher`
+contracts, the Redis and BullMQ adapters, the webhook signing and verification helpers, the state
+machine predicates, and the normalized record, event, and error shapes.
+
+The lifecycle types moved out of `types/images.ts` and are re-exported from it, so existing image
+imports of `OperationStatus`, `OperationEvent`, `OperationHandle`, `OperationEventBase`, and
+`OperationErrorDescriptor` resolve unchanged. `OperationStatus` gained `retrying`, and
+`OperationEvent` gained `progress` and `retrying` variants and an `attempt` field on `running` —
+additive changes this policy permits in a minor release. Code that switches exhaustively on either
+union should add the new members.
+
+Three behaviors are guaranteed. Terminal statuses are final, so a late provider callback cannot
+resurrect a settled operation. Store writes are compare-and-set on `sequence`, so a losing writer
+is told it lost rather than silently overwriting. And a record carrying raw bytes is refused with
+`OperationSerializationError` rather than persisted, because a base64 round trip through a queue
+payload is a failure mode that otherwise appears only as a truncated job.
+
+Durability is a property of the configured store, not of the runner. `MemoryOperationStore` does
+not survive a restart and does not promise cross-process recovery. `RedisOperationStore` is atomic
+only when the client exposes `eval`; without it the compare-and-set degrades to a read-compare-write
+that narrows but does not close the race, and that limitation is documented rather than hidden.
+Webhook delivery is best-effort and never fails the operation it describes.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,61 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-09-03
+
+Durable operations, the first half of the theme *work that outlives a process*. Long-running work now
+runs through one lifecycle that survives a worker crash. Everything here is additive.
+
+The rest of the theme — provider batch APIs, distributed rate limiting and circuit breaking,
+filesystem and S3 asset stores, a generated model registry, and cross-family observability — moves to
+1.7.0. The operation handle they all sit behind ships here, which is what unblocks them.
+
+### Added
+
+- **`OperationRunner` and a shared operation lifecycle.** `queued → running → succeeded | failed`,
+  with `retrying`, `cancelling`, `cancelled`, and `expired` covering the rest, exposed through the
+  new `nexus-ai-pro/operations` subpath. The runner persists a record before doing any work, claims
+  a lease, heartbeats while the executor runs, retries with backoff and jitter, dead-letters what
+  never succeeds, and emits signed webhooks.
+- **Restart survival through leases rather than locks.** A worker that dies leaves a record whose
+  lease lapses; another worker's `recover()` sweep resumes it. Every store write is a compare-and-set
+  on the record's `sequence`, so two workers racing on one operation cannot both win, and the loser
+  is told it lost instead of silently overwriting.
+- **`RedisOperationStore` and `BullMQOperationDispatcher`.** Redis persists records, with the
+  compare-and-set done in one Lua call when the client exposes `eval`. BullMQ dispatch queues the
+  operation id and its routing metadata only, never a payload.
+- **Idempotency keys.** A key matching an existing record replays that operation instead of starting
+  a second one, so an ambiguous timeout cannot produce a duplicate charge.
+- **Progress and cancellation.** An executor reports progress through `context.report()`, which
+  reaches both `handle.events()` and the persisted record. `runner.cancel()` settles an operation
+  owned by another worker, observed there through its heartbeat.
+- **Signed webhooks, with the verifying half included.** Deliveries are HMAC-SHA256 over
+  `${timestamp}.${body}`, so a captured delivery cannot be replayed indefinitely.
+  `verifyOperationWebhook()` ships alongside `signOperationWebhook()` rather than leaving every
+  receiver to hand-roll a constant-time comparison. A failed delivery is reported and never fails
+  the operation it describes.
+- **A binary-payload guard.** Persisting a result carrying a `Uint8Array`, `Buffer`, `Blob`, or
+  stream throws `OperationSerializationError` naming the exact path and pointing at `AssetStore`.
+  Base64 in a job payload inflates it by a third and most queue backends cap job size well below one
+  image, so this fails loudly at the boundary instead of appearing later as a truncated job.
+- New subpaths `nexus-ai-pro/operations`, `operations/adapters`, and `operations/webhooks`.
+
+### Changed
+
+- The operation lifecycle types moved from `types/images.ts` to a family-neutral `types/operations.ts`
+  and are re-exported from their old home, so existing image imports resolve unchanged. The image
+  family's private handle was replaced by the shared `LocalOperationHandle`, which is told to reject
+  with `ImageOperationCancelledError` so callers catching that error see no difference.
+- `OperationStatus` gained `retrying`; `OperationEvent` gained `progress` and `retrying` variants and
+  an `attempt` field on `running`. Additive, but code switching exhaustively on either union should
+  add the new members.
+
+### Fixed
+
+- A handle driven by the runner stayed in `queued` for the whole run, so no `running` event was
+  emitted and every `context.report()` call was silently dropped. Found while testing the runner's
+  event sequence; the handle now exposes `markRunning()` and the runner calls it before each attempt.
+
 ## [1.5.0] - 2026-08-31
 
 Embeddings become a first-class operation. `ai.embed()` gets the routing, caching, batching, budget,
@@ -266,7 +321,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.5.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.1...v1.3.0

package/README.md

@@ -84,6 +84,7 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - cache exact or semantically similar prompts
 - add tools, agents, RAG context, evals, batch jobs, and queues
 - embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
+- run long operations that survive a restart, with leases, retries, dead-lettering, and signed webhooks
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
 - keep TypeScript types around every request and response
 
@@ -417,6 +418,96 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Durable Operations
+
+Long-running work — an image render, a batch, anything asynchronous — runs through one lifecycle:
+`queued → running → succeeded | failed`, with `retrying`, `cancelling`, `cancelled`, and `expired`
+covering the rest. `OperationRunner` owns it end to end, so a crashed worker does not lose work.
+
+The default store is in-process, so the small case needs no infrastructure:
+
+```ts
+import { OperationRunner } from 'nexus-ai-pro/operations';
+
+const runner = new OperationRunner<string>({ retry: { maxAttempts: 3, baseDelayMs: 500 } });
+
+const handle = await runner.submit(async (context) => {
+  context.report({ completed: 1, total: 3 });
+  return doTheWork(context.signal);
+});
+
+for await (const event of handle.events()) {
+  console.log(event.type, event.sequence);
+}
+
+const value = await handle.result();
+```
+
+Swapping the store makes the same code survive a restart. Nothing else changes:
+
+```ts
+import { OperationRunner } from 'nexus-ai-pro/operations';
+import { BullMQOperationDispatcher, RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+
+const runner = new OperationRunner({
+  store: new RedisOperationStore(redis),
+  dispatcher: new BullMQOperationDispatcher(queue),
+  owner: process.env.HOSTNAME,
+  leaseMs: 30_000,
+  webhook: { url: 'https://app.example/hooks/operations', secret: process.env.HOOK_SECRET! },
+});
+```
+
+**How restart survival actually works.** A worker claims a lease before running and heartbeats
+while it works. If the process dies, the lease simply lapses; another worker's `recover()` sweep
+finds the record and resumes it. There is no distributed lock — every store write is a
+compare-and-set on the record's `sequence`, so two workers racing on the same operation cannot both
+win.
+
+```ts
+// On startup, in each worker.
+const resumed = await runner.recover(executor);
+```
+
+Recovery is deliberately conservative: a record past its `expiresAt` is **expired** rather than
+re-run, and one that has used every attempt is **dead-lettered** and parked for inspection, so a
+permanently failing operation cannot be recovered forever.
+
+**Idempotency.** An `idempotencyKey` that matches an existing record replays that operation instead
+of starting a second one, which is what stops an ambiguous timeout from double-charging:
+
+```ts
+const handle = await runner.submit(chargeAndRender, { idempotencyKey: `render:${orderId}` });
+```
+
+**Webhooks** are signed with HMAC-SHA256 over `${timestamp}.${body}`, so a captured delivery cannot
+be replayed indefinitely. The verifying half ships too — a receiver should never have to hand-roll a
+constant-time comparison:
+
+```ts
+import { OPERATION_WEBHOOK_SIGNATURE_HEADER, verifyOperationWebhook } from 'nexus-ai-pro/operations/webhooks';
+
+app.post('/hooks/operations', (request, response) => {
+  const ok = verifyOperationWebhook(
+    request.rawBody,
+    request.header(OPERATION_WEBHOOK_SIGNATURE_HEADER),
+    process.env.HOOK_SECRET!,
+  );
+  response.sendStatus(ok ? 204 : 400);
+});
+```
+
+A failed delivery is reported through `onWebhookError` and never turns a completed operation into a
+failed one.
+
+**Binary payloads are refused, not truncated.** Persisting a result that carries a `Uint8Array`,
+`Buffer`, or `Blob` throws `OperationSerializationError` naming the exact path. Base64 in a job
+payload inflates it by a third and most queue backends cap job size well below one image, so the
+bytes belong in an `AssetStore` with only a reference on the record. The BullMQ dispatcher likewise
+queues the operation id and nothing else.
+
+The image family already runs on this lifecycle, so `ai.images.submit()` reports the same events.
+
 ## Embeddings
 
 `ai.embed()` is a first-class operation, not a helper: it gets the same routing, caching, batching,
@@ -1226,6 +1317,9 @@ import { negotiateCompletionRequest } from 'nexus-ai-pro/capabilities';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
+import { OperationRunner } from 'nexus-ai-pro/operations';
+import { RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+import { verifyOperationWebhook } from 'nexus-ai-pro/operations/webhooks';
 import { EmbeddingManager } from 'nexus-ai-pro/embeddings';
 import { OpenAIEmbeddingProvider } from 'nexus-ai-pro/embeddings/adapters';
 import { MockEmbeddingProvider } from 'nexus-ai-pro/embeddings/mock';

package/ROADMAP.md

@@ -3,9 +3,9 @@
 This roadmap is a design proposal, not a compatibility promise. Stable and experimental
 surfaces are defined in [API_STABILITY.md](./API_STABILITY.md).
 
-Status baseline: **1.5.0**. 59 export subpaths, 12 completion providers, 5 embedding providers, 99
-completion registry models plus 63 aliases, and 11 embedding models plus 5 aliases. 234 unit tests
-pass; coverage sits at **85.7% lines / 70.9% branches / 80.8% functions** against gates of
+Status baseline: **1.6.0**. 62 export subpaths, 12 completion providers, 5 embedding providers, 99
+completion registry models plus 63 aliases, and 11 embedding models plus 5 aliases. 292 unit tests
+pass; coverage sits at **86.3% lines / 71.6% branches / 81.4% functions** against gates of
 82/67/73. CI verifies lint, format, build, tests, coverage, mock conformance, packed-package smoke,
 API contract, consumer type resolution, and clean install on Node 22 and 24.
 
@@ -102,7 +102,16 @@ deduplication, per-input caching, cost budgets, retry, structured usage and nume
 refusal rather than silent option dropping, `toEmbeddingFunction()` for existing vector stores, a
 deterministic mock, and a conformance harness.
 
-### 1.9 Operations, evaluation, and packaging
+### 1.9 Durable operations
+
+Delivered in 1.6.0. `OperationRunner` over an `OperationStore` contract, with a checked state
+machine, leases and heartbeats, delayed retry with backoff and jitter, dead-lettering, progress
+events, idempotency replay, crash recovery, and HMAC-signed webhooks with a matching verifier.
+`MemoryOperationStore` keeps the single-process case dependency-free; `RedisOperationStore` and
+`BullMQOperationDispatcher` make the same code survive a restart. Persisting raw bytes is refused
+so binary media cannot end up in a queue payload.
+
+### 1.10 Operations, evaluation, and packaging
 
 Rate limiting, audit logging, in-memory and OpenTelemetry metrics sinks, Prometheus export, an
 OpenTelemetry trace exporter, provider health monitoring, `EvalRunner` with LLM-as-judge and a
@@ -147,13 +156,17 @@ visible. The data itself is still a hand-written TypeScript literal of 99 models
 Generation from versioned provider data remains outstanding, and the Claude 5 reasoning bug 1.4.0
 fixed is the kind of error generation would have prevented.
 
-### 2.4 Durable-execution primitives are process-local
+### 2.4 Durable execution is only half distributed
+
+Closed in 1.6.0 for operations: `OperationHandle` is no longer process-bound, cross-process recovery
+works through lapsed leases, and idempotency keys deduplicate across workers.
 
-`RateLimiter` is an in-memory token bucket with no distributed adapter. There is no circuit breaker
-(health monitoring exists, but nothing opens a circuit). `OperationHandle` is process-bound;
-`MemoryAssetStore` is process-local. Realtime conversation snapshots and exports live in memory.
-Cross-process recovery, distributed deduplication, and provider-state replay remain application
-responsibilities.
+Still process-local: `RateLimiter` is an in-memory token bucket with no distributed adapter, there is
+no circuit breaker (health monitoring exists, but nothing opens a circuit), `MemoryAssetStore` holds
+assets in one process, and realtime conversation snapshots and exports live in memory. Provider-state
+replay remains an application responsibility. One caveat on what did land: `RedisOperationStore` is
+atomic only when the client exposes `eval`; without it the compare-and-set degrades to a
+read-compare-write that narrows but does not close the race.
 
 ### 2.5 Image family blockers
 
@@ -247,15 +260,33 @@ vector is silently incompatible with a populated store rather than merely differ
 Deliberately deferred: the provider batch-API tier, which belongs with the durable operation handle
 below rather than with the synchronous path.
 
-## 5. Next release: 1.6.0 — durable operations and batch economics
+## 5. Shipped in 1.6.0 — durable operations
+
+The first half of *work that outlives a process*. One lifecycle now covers every long-running
+family, and it survives a worker crash.
+
+- **Operation state machine.** `queued → running → retrying → succeeded | failed | cancelling |
+  cancelled | expired`, with leases, heartbeats, progress events, delayed retry, dead-letter
+  handling, timestamps, signed webhooks, and trace propagation. The image family runs on it, and the
+  lifecycle types moved to a family-neutral `types/operations.ts` re-exported from their old home.
+- **Durable operation adapters.** `RedisOperationStore` persists records with a compare-and-set on
+  `sequence`, done in one Lua call when the client exposes `eval`. `BullMQOperationDispatcher`
+  queues the operation id only. A record carrying raw bytes is refused rather than serialized.
+- **Idempotency and recovery.** A matching key replays an accepted operation instead of starting a
+  second; `recover()` resumes records whose lease lapsed, expiring those past their deadline and
+  dead-lettering those that used every attempt.
+
+Restart survival comes from leases rather than locks. There is no distributed lock anywhere: every
+store write is a compare-and-set, so a losing writer is told it lost instead of overwriting.
+
+Deliberately deferred: everything below, which needed the operation handle to exist first.
+
+---
+
+## 6. Next release: 1.7.0 — batch economics and distributed limits
 
-The theme is work that outlives a process.
+The rest of the theme, now that the handle they sit behind exists.
 
-- **Operation state machine.** `queued → running → succeeded | failed | cancelling | cancelled | expired`,
-  with leases, heartbeats, progress events, delayed retry, dead-letter handling, timestamps, signed
-  webhooks, and trace propagation. Applies to images first, then to any long-running family.
-- **Durable operation adapters.** Redis and BullMQ-backed handles so `submit()` survives a restart.
-  Queue asset references only; never JSON-serialize binary media into job payloads.
 - **Provider batch APIs.** OpenAI Batch and Anthropic Message Batches behind the same operation
   handle, exposing the discounted asynchronous tier that local `runBatch()` concurrency cannot reach.
   Idempotency keys replay an accepted operation; ambiguous timeouts must not produce duplicate
@@ -273,7 +304,7 @@ The theme is work that outlives a process.
 
 ---
 
-## 6. 1.7.0 — image portability, then promotion
+## 7. 1.8.0 — image portability, then promotion
 
 Images cannot leave experimental until the neutral contract survives a second wire protocol.
 
@@ -301,7 +332,7 @@ label come off.
 
 ---
 
-## 7. 2.0 candidate — one lifecycle for every operation
+## 8. 2.0 candidate — one lifecycle for every operation
 
 Create an internal typed lifecycle and adapt every family to it:
 
@@ -324,7 +355,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 8. Longer-term backlog
+## 9. Longer-term backlog
 
 1. MCP client and server adapters with asset and tool interoperability.
 2. Video generation through the same asynchronous operation, job, and asset contracts.
@@ -349,7 +380,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 9. Design notes carried forward
+## 10. Design notes carried forward
 
 These decisions predate this revision and still hold.
 
@@ -401,7 +432,7 @@ await ai.images.edit({
 
 ---
 
-## 10. How an item graduates
+## 11. How an item graduates
 
 1. Provider-neutral types and a deterministic mock land first.
 2. One real adapter proves the contract; conformance fixtures cover it.

package/dist/images/manager.js

@@ -1,117 +1,5 @@
 import { ImageCapabilityError, ImageError, ImageOperationCancelledError, ImageProviderError, ImageProviderNotFoundError, ImageProviderResponseError, ImageSafetyError, ImageValidationError, } from './errors.js';
-const TERMINAL_STATUSES = new Set(['succeeded', 'failed', 'cancelled', 'expired']);
-class LocalOperationHandle {
-    id;
-    now;
-    controller = new AbortController();
-    history = [];
-    waiters = new Set();
-    resultPromise;
-    resolveResult;
-    rejectResult;
-    currentStatus = 'queued';
-    sequence = 0;
-    constructor(id, now) {
-        this.id = id;
-        this.now = now;
-        this.resultPromise = new Promise((resolve, reject) => {
-            this.resolveResult = resolve;
-            this.rejectResult = reject;
-        });
-        // Consumers may choose events() without calling result(); keep that valid without hiding rejection from result().
-        void this.resultPromise.catch(() => undefined);
-        this.emit({ ...this.eventBase(), type: 'queued', status: 'queued' });
-    }
-    status() {
-        return this.currentStatus;
-    }
-    result() {
-        return this.resultPromise;
-    }
-    cancel(reason) {
-        if (TERMINAL_STATUSES.has(this.currentStatus) || this.currentStatus === 'cancelling')
-            return false;
-        this.currentStatus = 'cancelling';
-        this.emit({ ...this.eventBase(), type: 'cancelling', status: 'cancelling', reason });
-        this.controller.abort(reason);
-        this.currentStatus = 'cancelled';
-        this.emit({ ...this.eventBase(), type: 'cancelled', status: 'cancelled', reason });
-        this.rejectResult(new ImageOperationCancelledError(this.id, reason));
-        return true;
-    }
-    events() {
-        return this.iterateEvents();
-    }
-    start(executor) {
-        queueMicrotask(() => {
-            void this.run(executor);
-        });
-    }
-    async run(executor) {
-        if (TERMINAL_STATUSES.has(this.currentStatus))
-            return;
-        this.currentStatus = 'running';
-        this.emit({ ...this.eventBase(), type: 'running', status: 'running' });
-        try {
-            const value = await executor(this.controller.signal);
-            if (TERMINAL_STATUSES.has(this.currentStatus))
-                return;
-            this.currentStatus = 'succeeded';
-            this.emit({ ...this.eventBase(), type: 'succeeded', status: 'succeeded', result: value });
-            this.resolveResult(value);
-        }
-        catch (error) {
-            if (TERMINAL_STATUSES.has(this.currentStatus))
-                return;
-            this.currentStatus = 'failed';
-            this.emit({ ...this.eventBase(), type: 'failed', status: 'failed', error: describeError(error) });
-            this.rejectResult(error);
-        }
-    }
-    async *iterateEvents() {
-        let index = 0;
-        let waiter;
-        try {
-            while (true) {
-                const event = this.history[index];
-                if (event) {
-                    index += 1;
-                    yield event;
-                    if (TERMINAL_STATUSES.has(event.status))
-                        return;
-                    continue;
-                }
-                if (TERMINAL_STATUSES.has(this.currentStatus))
-                    return;
-                await new Promise((resolve) => {
-                    waiter = resolve;
-                    this.waiters.add(resolve);
-                });
-                if (waiter)
-                    this.waiters.delete(waiter);
-                waiter = undefined;
-            }
-        }
-        finally {
-            if (waiter)
-                this.waiters.delete(waiter);
-        }
-    }
-    eventBase() {
-        return {
-            operationId: this.id,
-            sequence: ++this.sequence,
-            timestamp: this.now().toISOString(),
-        };
-    }
-    emit(event) {
-        this.history.push(event);
-        const waiters = [...this.waiters];
-        this.waiters.clear();
-        for (const wake of waiters)
-            wake();
-    }
-}
+import { LocalOperationHandle } from '../operations/handle.js';
 export class ImageManager {
     config;
     providers = new Map();
@@ -148,7 +36,12 @@ export class ImageManager {
     submit(input, request) {
         const submission = normalizeSubmission(input, request);
         const operationId = this.createOperationId();
-        const handle = new LocalOperationHandle(operationId, this.now);
+        // The shared handle is told to reject with the image family's own cancellation error, so this
+        // refactor is invisible to existing callers catching ImageOperationCancelledError.
+        const handle = new LocalOperationHandle(operationId, {
+            now: this.now,
+            cancellationError: (id, reason) => new ImageOperationCancelledError(id, reason),
+        });
         const externalSignal = submission.request.signal;
         const onAbort = () => {
             handle.cancel(abortReason(externalSignal));
@@ -550,13 +443,6 @@ function knownImageMimeType(format) {
 function normalizeMimeType(value) {
     return value.split(';', 1)[0]?.trim().toLowerCase() ?? '';
 }
-function describeError(error) {
-    if (error instanceof ImageError)
-        return { name: error.name, message: error.message, code: error.code };
-    if (error instanceof Error)
-        return { name: error.name, message: error.message };
-    return { name: 'Error', message: String(error) };
-}
 function assertSafetyFindings(message, findings) {
     const blocked = findings.filter((finding) => finding.action === 'block');
     if (blocked.length > 0)

package/dist/index.d.ts

@@ -12,6 +12,14 @@ export { SemanticCache, type SemanticCacheOptions } from './cache/semantic-cache
 export { ResponseFormatError } from './core/response-format.js';
 export { ContextWindowManager, type ContextWindowRuntime, } from './context/index.js';
 export { VoiceManager, VoiceSession, VoiceProviderError, VoiceCapabilityError, type VoiceCompletionClient, type VoiceSessionCompletionClient, type VoiceSessionRuntime, } from './voice/index.js';
+export { OperationRunner } from './operations/runner.js';
+export { LocalOperationHandle, describeOperationError } from './operations/handle.js';
+export { MemoryOperationStore, assertSerializableRecord } from './operations/store.js';
+export { BullMQOperationDispatcher, RedisOperationStore, type BullMQLikeOperationQueue, type RedisOperationLikeClient, } from './operations/adapters.js';
+export { OPERATION_WEBHOOK_SIGNATURE_HEADER, deliverOperationWebhook, signOperationWebhook, verifyOperationWebhook, } from './operations/webhooks.js';
+export { TERMINAL_OPERATION_STATUSES } from './types/operations.js';
+export { allowedTransitions, assertTransition, canTransition, isClaimable, isSettled, isTerminalOperationStatus, } from './operations/state-machine.js';
+export { OperationCancelledError, OperationConflictError, OperationError, OperationExpiredError, OperationLeaseLostError, OperationNotFoundError, OperationSerializationError, OperationTransitionError, } from './operations/errors.js';
 export { ImageManager } from './images/manager.js';
 export { ImageCapabilityError, ImageError, ImageOperationCancelledError, ImageProviderError, ImageProviderNotFoundError, ImageProviderResponseError, ImageSafetyError, ImageValidationError, } from './images/errors.js';
 export { TelephonyManager, TelephonyProviderError, TelephonyCapabilityError, createVoiceTwiML, } from './telephony/index.js';
@@ -79,6 +87,7 @@ export type { ContextSummaryConfig, ContextSummaryInput, ContextSummaryMode, Con
 export type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionWord, VoiceAudioFormat, VoiceAudioInput, VoiceAudioOutput, VoiceConfig, VoicePromptText, VoiceProvider, VoiceProviderInfo, VoiceSessionConfig, VoiceSessionToolStep, VoiceSessionTurnInput, VoiceSessionTurnResponse, VoiceTaskPrompt, VoiceTaskPromptMatcher, VoiceTaskPromptMatcherInput, VoiceTranscriptMessageConfig, VoiceTurnRequest, VoiceTurnResponse, } from './types/voice.js';
 export type { AssetBytesLocation, AssetChecksum, AssetDescriptor, AssetInput, AssetLocation, AssetLocationKind, AssetProvenance, AssetStoredLocation, AssetUrlLocation, ImageBackground, ImageConfig, ImageDelivery, ImageDimensions, ImageEditRequest, ImageGenerateRequest, ImageManagerConfig, ImageMaskInput, ImageOperation, ImageOperationSubmission, ImageOutputFormat, ImageProvider, ImageProviderCallContext, ImageProviderCapabilities, ImageProviderInfo, ImageQuality, ImageRequestBase, ImageResult, ImageSafetyContext, ImageSafetyPolicy, ImageWarning, MediaSafetyFinding, MediaUsage, OperationErrorDescriptor, OperationEvent, OperationEventBase, OperationHandle, OperationMeta, OperationStatus, } from './types/images.js';
 export type { AssetCapacityConstraint, AssetPutOptions, AssetSignOptions, AssetSigner, AssetSignerContext, AssetStat, AssetStore, AssetStoreResult, ByteAssetDescriptor, ByteAssetInput, MemoryAssetStoreOptions, MemoryAssetStoreSnapshot, } from './images/assets.js';
+export type { DurableOperationHandle, OperationContext, OperationDispatcher, OperationExecutor, OperationLease, OperationRecord, OperationRetryConfig, OperationRunnerConfig, OperationStore, OperationSubmitOptions, OperationWebhookConfig, } from './types/operations.js';
 export type { Embedding, EmbeddingConfig, EmbeddingCostBudgetConfig, EmbeddingEncodingFormat, EmbeddingInput, EmbeddingInputType, EmbeddingMeta, EmbeddingModelCapabilities, EmbeddingModelRegistryConfig, EmbeddingProviderCallContext, EmbeddingProviderCapabilities, EmbeddingProviderInfo, EmbeddingProviderRequest, EmbeddingProviderResult, EmbeddingProviderUsage, EmbeddingRequest, EmbeddingResponse, EmbeddingTruncateMode, EmbeddingsProvider, } from './types/embeddings.js';
 export type { CreateCallRequest, CreateCallResponse, TelephonyAudioEncoding, TelephonyCallDirection, TelephonyCallStatus, TelephonyConfig, TelephonyConnectedEvent, TelephonyDtmfEvent, TelephonyGatherConfig, TelephonyHttpMethod, TelephonyMarkEvent, TelephonyMediaEvent, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyProviderInfo, TelephonyResponseRequest, TelephonyStartEvent, TelephonyStopEvent, TelephonyStreamConfig, TelephonyStreamMode, TelephonyStreamTrack, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, } from './types/telephony.js';
 export type { AliasMetadata, AliasStage, CacheTtl, Modality, ModelCapabilities, ModelEndpoint, ModelStatus, PromptCachingCapability, ProviderCapabilities, ReasoningEffort, RoutingModelPreference, } from './types/providers.js';

package/dist/index.js

@@ -12,6 +12,14 @@ export { SemanticCache } from './cache/semantic-cache.js';
 export { ResponseFormatError } from './core/response-format.js';
 export { ContextWindowManager, } from './context/index.js';
 export { VoiceManager, VoiceSession, VoiceProviderError, VoiceCapabilityError, } from './voice/index.js';
+export { OperationRunner } from './operations/runner.js';
+export { LocalOperationHandle, describeOperationError } from './operations/handle.js';
+export { MemoryOperationStore, assertSerializableRecord } from './operations/store.js';
+export { BullMQOperationDispatcher, RedisOperationStore, } from './operations/adapters.js';
+export { OPERATION_WEBHOOK_SIGNATURE_HEADER, deliverOperationWebhook, signOperationWebhook, verifyOperationWebhook, } from './operations/webhooks.js';
+export { TERMINAL_OPERATION_STATUSES } from './types/operations.js';
+export { allowedTransitions, assertTransition, canTransition, isClaimable, isSettled, isTerminalOperationStatus, } from './operations/state-machine.js';
+export { OperationCancelledError, OperationConflictError, OperationError, OperationExpiredError, OperationLeaseLostError, OperationNotFoundError, OperationSerializationError, OperationTransitionError, } from './operations/errors.js';
 export { ImageManager } from './images/manager.js';
 export { ImageCapabilityError, ImageError, ImageOperationCancelledError, ImageProviderError, ImageProviderNotFoundError, ImageProviderResponseError, ImageSafetyError, ImageValidationError, } from './images/errors.js';
 export { TelephonyManager, TelephonyProviderError, TelephonyCapabilityError, createVoiceTwiML, } from './telephony/index.js';

package/dist/operations/adapters.d.ts

@@ -0,0 +1,69 @@
+import type { OperationDispatcher, OperationRecord, OperationStore } from '../types/operations.js';
+/**
+ * The Redis commands the operation store needs.
+ *
+ * Structural rather than tied to one client, so `ioredis`, `node-redis`, or a cluster proxy all
+ * satisfy it without this package depending on any of them.
+ */
+export interface RedisOperationLikeClient {
+    hget(key: string, field: string): Promise<string | null> | string | null;
+    hset(key: string, field: string, value: string): Promise<unknown> | unknown;
+    hdel(key: string, field: string): Promise<unknown> | unknown;
+    hvals(key: string): Promise<string[]> | string[];
+    /** Optional CAS primitive. When absent the store falls back to a read-compare-write. */
+    eval?(script: string, numKeys: number, ...args: string[]): Promise<unknown> | unknown;
+}
+export interface RedisOperationStoreOptions {
+    prefix?: string;
+    /** Disables the Lua compare-and-set even when the client exposes `eval`. */
+    useEval?: boolean;
+}
+/**
+ * Redis-backed operation storage, so a submitted operation survives a restart.
+ *
+ * Updates are a compare-and-set on `sequence`. When the client exposes `eval` the comparison and
+ * the write happen in one Lua call, which is genuinely atomic; otherwise the store falls back to a
+ * read-compare-write that narrows the race but cannot close it. Prefer a client with `eval`
+ * whenever more than one worker can touch the same operation.
+ */
+export declare class RedisOperationStore<TResult = unknown> implements OperationStore<TResult> {
+    private readonly client;
+    private readonly prefix;
+    private readonly useEval;
+    constructor(client: RedisOperationLikeClient, options?: RedisOperationStoreOptions);
+    create(record: OperationRecord<TResult>): Promise<void>;
+    read(id: string): Promise<OperationRecord<TResult> | undefined>;
+    update(record: OperationRecord<TResult>, expectedSequence: number): Promise<boolean>;
+    delete(id: string): Promise<boolean>;
+    claimExpired(now: string, limit: number): Promise<Array<OperationRecord<TResult>>>;
+    findByIdempotencyKey(key: string): Promise<OperationRecord<TResult> | undefined>;
+    list(): Promise<Array<OperationRecord<TResult>>>;
+    private recordsKey;
+    private idempotencyKey;
+}
+export interface BullMQLikeOperationQueue {
+    add(name: string, data: unknown, options?: Record<string, unknown>): Promise<{
+        id?: string | number;
+    }> | {
+        id?: string | number;
+    };
+}
+export interface BullMQOperationDispatcherOptions {
+    /** Job name used for every dispatched operation. Defaults to `nexus-operation`. */
+    jobName?: string;
+    /** Merged into the BullMQ job options, for priority, delay, or removal policy. */
+    jobOptions?: Record<string, unknown>;
+}
+/**
+ * Hands accepted operations to a BullMQ queue for a worker process to execute.
+ *
+ * Only the operation id and its routing metadata are queued — never the record's result or any
+ * payload — so the job stays small and the store remains the single source of truth. The worker
+ * reads the record by id, which is also what makes a redelivered job safe.
+ */
+export declare class BullMQOperationDispatcher implements OperationDispatcher {
+    private readonly queue;
+    private readonly options;
+    constructor(queue: BullMQLikeOperationQueue, options?: BullMQOperationDispatcherOptions);
+    dispatch(record: OperationRecord<unknown>): Promise<void>;
+}