nexus-ai-pro 1.6.0 → 1.7.0

package/API_STABILITY.md

@@ -158,6 +158,73 @@ only when the client exposes `eval`; without it the compare-and-set degrades to
 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.
 
+## Resilience API stage
+
+`CircuitBreaker`, the `RateLimitStore` contract, `MemoryRateLimitStore`, `RedisRateLimitStore`, and
+the `ops/circuit-breaker` and `ops/rate-limit-adapters` subpaths are public and follow the 1.x rules,
+together with `circuitBreaker` and `rateLimit.store` in `NexusAIConfig`.
+
+`RateLimiter.check()` keeps its synchronous signature and in-memory behavior; `checkAsync()` is the
+additive store-aware path. `NexusRateLimitError` gained an optional `resetAt` and a
+`retryAfterSeconds` accessor. `RouterContext` gained an optional `openCircuits`, and `Router.route()`
+an optional trailing parameter, both additive.
+
+Which provider a breaker excludes at a given moment is a runtime decision, not a compatibility
+guarantee: thresholds, scoring, and the exact ordering of candidates can change in a minor release.
+What is guaranteed is the state machine — closed, open after a threshold is crossed, half-open after
+the cooldown, closed again only after the configured probe successes — and that routing still selects
+a provider when every circuit is open rather than failing the request untried.
+
+Breaker state is per process by design. Two workers can disagree about a provider, and neither the
+breaker nor its snapshot promises cluster-wide consensus. Rate-limit counters are the opposite: they
+are only shared when a store is configured, and the default in-memory counter gives each worker its
+own budget.
+
+## Batch API stage
+
+`BatchManager`, the `BatchProvider` contract, the OpenAI and Anthropic adapters, the deterministic
+mock, and the `nexus-ai-pro/batch`, `batch/openai`, `batch/anthropic`, and `batch/mock` subpaths are
+public and follow the 1.x rules, as are the normalized request, ref, state, and result shapes.
+
+`BatchJobRef` is guaranteed to stay JSON-serializable and sufficient on its own to poll, collect, or
+cancel a batch. That is what makes a persisted ref survive a restart, and narrowing it would break
+every stored ref, so it requires a major release.
+
+Two behaviors are guaranteed. Results are matched by `customId`, never by position, and a duplicate
+`customId` is refused before submission. And a failed batch returns no items rather than fabricated
+ones.
+
+Provider vocabulary is not normalized beyond `BatchJobStatus`. Anthropic reports only `in_progress`
+and `ended`, with the real outcome on the per-item results; that adapter maps `ended` to `completed`
+and lets item errors carry the detail rather than inventing a batch-level failure. Payloads under
+`raw`, provider quotas, completion windows, and the discount rate itself are provider-controlled and
+may change without a major release.
+
+## Asset store stage
+
+`FilesystemAssetStore`, `S3AssetStore`, the `S3LikeClient` contract, and the
+`nexus-ai-pro/images/stores` subpath are public under the 1.x rules and implement the existing
+`AssetStore` contract unchanged. The shared contract, errors, and validation moved to an internal
+`asset-support` module and are re-exported from `images/assets`, so every existing import resolves
+as before.
+
+All three stores guarantee that a missing asset and one owned by another tenant are
+indistinguishable, that stored bytes carry a SHA-256 checksum, and that a lapsed asset is unreadable
+before it is purged. `S3AssetStore.purgeExpired()` lists the record prefix on every call; on a large
+bucket prefer the provider lifecycle rules. Neither durable store coordinates concurrent deletes
+across processes.
+
+## Model registry generation stage
+
+`data/models/*.json` is the versioned source of truth in the repository, and
+`scripts/generate-model-registry.mjs` emits `src/models/generated.ts` from it.
+
+Neither is published, and neither is public API. They duplicate `KNOWN_MODELS` exactly, so shipping
+them would add roughly 310KB to every install for data nothing reads. Generation is a build-time
+guarantee about how the registry is maintained, not a runtime surface: the resolver continues to read
+`KNOWN_MODELS`, and a test asserts the two match. Switching the resolver over is a later change, so
+that introducing generation cannot alter pricing behavior in the same release.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,82 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-09-08
+
+Batch economics, distributed limits, and durable assets: the rest of the theme *work that
+outlives a process*. The half-price asynchronous tier is reachable, one rate-limit budget covers
+every worker, a failing provider leaves routing until it recovers, generated media persists
+outside the process, and every operation family reports into the same metrics and audit log.
+
+### Added
+
+- **Circuit breaking.** `CircuitBreaker` consumes the same attempt signals as `ProviderHealthMonitor`
+  and trips routing away from a failing provider entirely, rather than merely ranking it lower. Two
+  independent triggers: consecutive failures, and a failure rate over a rolling window that catches a
+  provider failing half its calls without ever failing several in a row. After a cooldown the circuit
+  admits a limited number of probes; a success closes it, a failure reopens it and restarts the
+  cooldown. Exposed through `circuitBreaker` config, `ai.getCircuitBreakerStatus()`,
+  `ai.resetCircuitBreaker()`, and the `nexus-ai-pro/ops/circuit-breaker` subpath.
+- **Distributed rate limiting.** A `RateLimitStore` contract with `MemoryRateLimitStore` and
+  `RedisRateLimitStore`, set through `rateLimit.store`, so one budget covers every worker instead of
+  each process getting the full limit. The Redis store does the increment and the expiry in one
+  atomic Lua call when the client exposes `eval`, and re-arms a missing TTL on the fallback path so a
+  crash between `INCR` and `PEXPIRE` cannot block a key forever. Completions and embeddings share the
+  limiter, so they share the budget.
+- `NexusRateLimitError` now carries `resetAt` and a `retryAfterSeconds` accessor, so a gateway can
+  answer with a real `Retry-After` header.
+- New subpaths `nexus-ai-pro/ops/circuit-breaker` and `nexus-ai-pro/ops/rate-limit-adapters`.
+- **Provider batch tiers.** `BatchManager` puts OpenAI Batch and Anthropic Message Batches behind one
+  operation handle, reaching the roughly half-price asynchronous tier that local `runBatch()`
+  concurrency cannot. Results are matched by a required `customId` rather than by position, since a
+  batch provider does not guarantee output order; a duplicate id is refused before submission.
+  Polling backs off up to a configurable ceiling, an idempotency key replays instead of submitting
+  twice, and `resume()` collects a batch from its `BatchJobRef` alone so a restarted worker can
+  finish what another submitted. Ships with a deterministic `MockBatchProvider`.
+- **Filesystem and S3 asset stores.** `FilesystemAssetStore` and `S3AssetStore` implement the
+  existing `AssetStore` contract, with tenant isolation, retention, SHA-256 checksums, and signing.
+  A missing asset and one owned by another tenant are indistinguishable, because a distinguishable
+  error leaks the existence of another tenant asset. Both write bytes and a JSON sidecar per asset
+  rather than a shared index, so concurrent writers do not contend and a torn write loses at most
+  one record. `S3LikeClient` is structural, so S3, R2, and MinIO all work without an SDK dependency.
+- **Generated model registry.** `data/models/*.json` is now the versioned source of truth, and
+  `scripts/generate-model-registry.mjs` emits `src/models/generated.ts` from it. The generator
+  validates required fields, price signs, context bounds, status values, and dangling aliases;
+  `npm run registry:check` runs inside `npm run check` so committed data and output cannot drift.
+  The runtime still reads `KNOWN_MODELS`, and a test asserts the two match exactly. The generated
+  module and its data are build-time artifacts and are not published: they duplicate `KNOWN_MODELS`
+  exactly, so shipping them would add roughly 310KB to every install for data nothing reads.
+- New subpaths `nexus-ai-pro/batch`, `batch/openai`, `batch/anthropic`, `batch/mock`, and
+  `nexus-ai-pro/images/stores`.
+- **Cross-family observability.** Image, voice, and telephony operations now report into the same
+  metrics collector, audit log, and rate limiter as completions and embeddings, closing the gap where
+  an application running phone agents and image generation had observability for only part of its
+  spend. Metrics carry `family` and `operation` labels, and one rate-limit budget now covers every
+  family. `FamilyTelemetry` is exported for a family an application adds itself.
+
+### Changed
+
+- `RateLimiter` gained `checkAsync()` for the store-aware path. `check()` keeps its synchronous
+  signature and behavior, and the runtime only awaits when a store is configured, so a request
+  without one pays no extra microtask.
+- `ImageManager`, `VoiceManager`, and `TelephonyManager` accept an optional second constructor
+  argument carrying the shared observability objects. It defaults to empty, so constructing one
+  standalone is unchanged and simply records nothing.
+- The shared asset contract, errors, and validation moved from `images/assets` to an internal
+  `asset-support` module so the filesystem, S3, and memory stores cannot drift on what a valid asset
+  is. `images/assets` re-exports all of it, so existing imports are unchanged.
+- Documentation consolidated from nine files to seven. `NEXUS.md` and `EXPLANATION.md` were four
+  releases stale and largely restated the README; their unique content moved to `CONTRIBUTING.md`
+  (real-provider test setup, the public-feature checklist, the manual smoke checklist) and to a new
+  README "Known Limitations" section. The published package now carries only `README.md`,
+  `API_STABILITY.md`, `CHANGELOG.md`, `SECURITY.md`, and `LICENSE`; `ROADMAP.md` is a design proposal
+  and stays on GitHub.
+- `SECURITY.md` no longer names a specific supported version line. It claimed `0.9.x` while 1.6.0 was
+  the published release, so the wording is now version-independent and cannot go stale again.
+- `RouterContext` gained an optional `openCircuits`, and `Router.route()` an optional trailing
+  parameter. When every candidate's circuit is open the router routes anyway: that usually means a
+  shared dependency is down, and one attempt beats a certain failure with no attempt at all.
+
 ## [1.6.0] - 2026-09-03
 
 Durable operations, the first half of the theme *work that outlives a process*. Long-running work now
@@ -321,7 +397,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.6.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...v1.7.0
 [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

package/README.md

@@ -6,8 +6,8 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
-- Full technical notes and manual test cases: [NEXUS.md](./NEXUS.md)
-- Image generation status and remaining infrastructure work: [ROADMAP.md](./ROADMAP.md)
+- Contributing, testing, and release procedure: [CONTRIBUTING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CONTRIBUTING.md)
+- Delivered work and what is planned next: [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md)
 
 ## Install
 
@@ -85,6 +85,9 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - 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
+- trip routing away from a failing provider, and share one rate-limit budget across workers
+- reach the providers' half-price asynchronous batch tier behind one operation handle
+- persist generated media to disk or S3 with tenant isolation, retention, and checksums
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
 - keep TypeScript types around every request and response
 
@@ -418,6 +421,199 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Provider Batch Tiers
+
+Both OpenAI and Anthropic sell an asynchronous tier at roughly half price, in exchange for a
+completion window measured in hours. Local `runBatch()` concurrency cannot reach it — it is a
+different API. `BatchManager` puts both behind one operation handle.
+
+```ts
+import { BatchManager } from 'nexus-ai-pro/batch';
+import { OpenAIBatchProvider } from 'nexus-ai-pro/batch/openai';
+
+const batch = new BatchManager({
+  providers: { openai: new OpenAIBatchProvider({ apiKey: process.env.OPENAI_API_KEY! }) },
+  defaultProvider: 'openai',
+});
+
+const handle = await batch.submit({
+  model: 'gpt-5.4-mini',
+  idempotencyKey: `nightly-${date}`,
+  items: documents.map((document) => ({
+    customId: document.id,
+    request: { model: 'gpt-5.4-mini', messages: [{ role: 'user', content: document.text }] },
+  })),
+});
+
+console.log(handle.id);        // persist this, do not block a request on the result
+```
+
+`customId` is required, not optional. A batch provider does not guarantee output order, and matching
+results by position is exactly the bug that silently mislabels every row. Duplicates are refused
+before submission for the same reason.
+
+The handle settles when the provider finishes, which can be hours later, so treat it as a background
+operation:
+
+```ts
+const result = await handle.result();
+
+result.status;              // completed | failed | expired | cancelled
+result.counts;              // { total, completed, failed }
+result.items;               // one entry per customId, with response or error
+result.cost.amount;         // priced per item, then discounted at the provider's batch rate
+```
+
+A mixed batch is normal: individual items carry their own `error` while the batch still reports
+`completed`. Nothing is invented for a failed batch — `items` comes back empty rather than padded.
+
+**Surviving a restart.** Everything after `submit` takes only a `BatchJobRef`, which is
+JSON-serializable. A worker that never submitted the batch can collect it:
+
+```ts
+const ref = { id: savedBatchId, provider: 'openai' };
+
+await batch.status(ref);     // provider-side state, without waiting
+const result = await batch.resume(ref);
+await batch.cancel(ref);
+```
+
+Polling backs off from the configured interval up to `maxPollIntervalMs`, so a 24-hour batch does
+not generate 2,880 polls while a fast one is still caught by the first few short intervals.
+
+## Asset Stores
+
+`AssetStore` has three implementations. They share one contract, so retention, tenant isolation, and
+checksums behave identically:
+
+```ts
+import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
+import { FilesystemAssetStore, S3AssetStore } from 'nexus-ai-pro/images/stores';
+
+const store = new FilesystemAssetStore({ directory: '/var/lib/app/assets', defaultTtlSeconds: 86_400 });
+
+const s3 = new S3AssetStore({
+  client,                    // structural: S3, R2, MinIO, or a test double
+  bucket: 'generated-media',
+  prefix: 'nexus-assets/',
+});
+```
+
+A missing asset and one owned by another tenant are **indistinguishable** — both return `undefined`
+rather than a permission error, because a distinguishable error leaks the existence of another
+tenant's asset.
+
+Both durable stores write two objects per asset: the bytes, and a JSON sidecar holding the
+descriptor, tenant, and expiry. A single shared index would be a write-contention point and a
+corruption blast radius; per-asset sidecars let concurrent writers proceed and lose at most one
+record. `purgeExpired()` is exact but costs a directory listing, so on a large S3 bucket prefer the
+provider's own lifecycle rules and keep this as the fallback.
+
+## Model Registry Generation
+
+The registry is generated from versioned provider data in `data/models/`, not hand-edited. The
+Claude 5 reasoning bug fixed in 1.4.0 was exactly the kind of error a hand-written literal of 100+
+models invites.
+
+```bash
+npm run registry:generate   # data/models/*.json -> src/models/generated.ts
+npm run registry:check      # fails if the committed output is stale
+```
+
+`registry:check` runs as part of `npm run check`, so committed data and committed output cannot
+drift apart. The generator validates required fields, price signs, context bounds, status values,
+and that every alias points at a model that exists — a dangling alias otherwise fails only when a
+request happens to use it.
+
+The runtime still reads the hand-written `KNOWN_MODELS`; a test asserts the generated registry
+matches it exactly. Swapping the runtime over is deliberately a separate change, so introducing the
+generator cannot quietly alter pricing data in the same release.
+
+`src/models/generated.ts` and `data/` are build-time artifacts and are **not** published. They
+duplicate `KNOWN_MODELS` exactly, and shipping them in both builds would add roughly 310KB to every
+install for data nothing reads. Both live in the repository, where a diff is what you actually want.
+
+## Resilience: Circuit Breaking and Distributed Limits
+
+Health monitoring ranks a struggling provider lower. A circuit breaker is the stronger step: while a
+circuit is open the provider is removed from routing entirely, so a hard-down provider stops
+absorbing one failed attempt per request.
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! }, anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } },
+  health: { enabled: true },
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 5,        // consecutive failures that open the circuit
+    failureRateThreshold: 0.5,  // or half the calls failing in the window
+    minimumThroughput: 10,
+    resetTimeoutMs: 30_000,     // cooldown before a probe
+    halfOpenMaxCalls: 1,
+    onStateChange: (event) => logger.warn('circuit', event),
+  },
+});
+
+ai.getCircuitBreakerStatus();   // state, failure rate, retryAt per provider
+ai.resetCircuitBreaker('openai');
+```
+
+Two independent triggers, because they catch different failures. A consecutive count catches a
+provider that is hard down. A failure *rate* catches one that fails half its calls without ever
+failing several in a row — invisible to a consecutive counter. The rate is only considered once
+`minimumThroughput` calls have been seen, since one failure out of two is not evidence of anything.
+
+After the cooldown the circuit goes half-open and admits a limited number of probes. A successful
+probe closes it; a failed probe reopens it and restarts the cooldown. If *every* circuit is open the
+router routes anyway — that usually means a shared dependency is down, and one attempt beats a
+certain failure with no attempt at all.
+
+`isFailure` keeps errors that are not the provider's fault out of the calculation:
+
+```ts
+circuitBreaker: {
+  enabled: true,
+  isFailure: (error) => !(error instanceof Error && error.name === 'AbortError'),
+}
+```
+
+**Distributed rate limiting.** The built-in limiter is process-local, which multiplies the real
+limit by the number of workers. Pointing it at a shared store fixes that, and the same budget then
+covers completions and embeddings alike:
+
+```ts
+import { RedisRateLimitStore } from 'nexus-ai-pro/ops/rate-limit-adapters';
+
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  rateLimit: {
+    enabled: true,
+    maxRequests: 100,
+    windowMs: 60_000,
+    key: 'userId',
+    store: new RedisRateLimitStore(redis),
+  },
+});
+```
+
+Prefer a client exposing `eval`: the increment and the expiry then happen in one atomic round trip.
+Without it the store falls back to `INCR` plus `PEXPIRE` and re-arms any missing TTL it sees, so a
+crash between the two calls cannot block a key forever.
+
+`NexusRateLimitError` carries `resetAt` and `retryAfterSeconds`, so a gateway can answer with a
+real `Retry-After` header:
+
+```ts
+catch (error) {
+  if (error instanceof NexusRateLimitError) {
+    response.setHeader('Retry-After', String(error.retryAfterSeconds ?? 60));
+  }
+}
+```
+
+Omitting `store` keeps the original synchronous in-memory path, which costs no extra microtask per
+request.
+
 ## Durable Operations
 
 Long-running work — an image render, a batch, anything asynchronous — runs through one lifecycle:
@@ -427,6 +623,11 @@ covering the rest. `OperationRunner` owns it end to end, so a crashed worker doe
 The default store is in-process, so the small case needs no infrastructure:
 
 ```ts
+import { BatchManager } from 'nexus-ai-pro/batch';
+import { OpenAIBatchProvider } from 'nexus-ai-pro/batch/openai';
+import { FilesystemAssetStore, S3AssetStore } from 'nexus-ai-pro/images/stores';
+import { CircuitBreaker } from 'nexus-ai-pro/ops/circuit-breaker';
+import { RedisRateLimitStore } from 'nexus-ai-pro/ops/rate-limit-adapters';
 import { OperationRunner } from 'nexus-ai-pro/operations';
 
 const runner = new OperationRunner<string>({ retry: { maxAttempts: 3, baseDelayMs: 500 } });
@@ -1385,12 +1586,33 @@ npm run test:conformance:real
 
 ## Roadmap
 
+See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what has
+shipped and what is planned. It is a design proposal, not a compatibility promise; the guarantees
+live in [API_STABILITY.md](./API_STABILITY.md).
+
 1.4.0 closed the completion-request gap: prompt caching, reasoning controls, tool and sampling
 controls, structured usage with numeric cost, and capability negotiation with registry provenance.
 
 Next is durable execution — an operation state machine, provider batch APIs, distributed rate
 limiting and circuit breaking, first-class embeddings, and filesystem/S3 asset stores — followed by
-image portability and promotion out of experimental. See [ROADMAP.md](./ROADMAP.md).
+image portability and promotion out of experimental. See
+[ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md).
+
+## Known Limitations
+
+- Voice, telephony, images, local models, and custom providers are optional layers; enable only what
+  you use.
+- Audio and video preprocessing is limited, and provider modality support differs.
+- Bundled model metadata is a routing and estimation convenience, not a pricing contract.
+- Process-memory cache, queues, and asset storage are not enough for a distributed deployment; use
+  the Redis, BullMQ, filesystem, or S3 adapters instead.
+- Default hash embeddings suit tests and demos, not strong semantic search. Register a real
+  embedding provider for production retrieval.
+- NLI verification is an interface; bring a specialized verifier for high-confidence entailment.
+- Guardrails reduce risk but do not replace application authorization, provider-side moderation, or
+  human review of high-impact actions.
+- Circuit-breaker state is per process, and realtime sessions are not yet routed through the metrics,
+  audit, and rate-limit path that every other family uses.
 
 ## Production Notes
 

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published minor release. Users should upgrade to the newest `0.9.x` patch as fixes become available.
+Security fixes are provided for the latest published minor release. Upgrade to the newest patch of that line as fixes become available; older minor releases do not receive backports.
 
 ## Reporting a vulnerability
 

package/dist/batch/anthropic.d.ts

@@ -0,0 +1,26 @@
+import type { BatchJobRef, BatchJobState, BatchOutputItem, BatchProvider, BatchProviderCallContext, BatchProviderInfo, BatchSubmitRequest } from '../types/batch.js';
+export interface AnthropicBatchProviderOptions {
+    apiKey: string;
+    baseUrl?: string;
+    version?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    /** Applied to any item that names no model. */
+    defaultModel?: string;
+    maxTokens?: number;
+}
+/** Anthropic Message Batches: half price, 24-hour window. */
+export declare class AnthropicBatchProvider implements BatchProvider {
+    private readonly options;
+    readonly info: BatchProviderInfo;
+    constructor(options: AnthropicBatchProviderOptions);
+    submit(request: BatchSubmitRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
+    poll(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    results(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchOutputItem[]>;
+    cancel(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    private toState;
+    private toOutputItem;
+    private request;
+    private requestText;
+    private send;
+}

package/dist/batch/anthropic.js

@@ -0,0 +1,179 @@
+import { buildMeta } from '../core/usage.js';
+import { BatchProviderResponseError } from './errors.js';
+/**
+ * Anthropic reports only `in_progress` and `ended` for the batch itself.
+ *
+ * `ended` covers success, cancellation, and expiry alike, so the real outcome only appears on the
+ * per-item results. This adapter reports `completed` on `ended` and lets the item errors carry the
+ * detail, rather than inventing a batch-level failure the API never stated.
+ */
+const STATUS_MAP = {
+    in_progress: 'in_progress',
+    canceling: 'cancelling',
+    cancelling: 'cancelling',
+    ended: 'completed',
+};
+/** Anthropic Message Batches: half price, 24-hour window. */
+export class AnthropicBatchProvider {
+    options;
+    info = {
+        name: 'anthropic',
+        capabilities: {
+            maxItems: 100_000,
+            maxBytes: 256 * 1024 * 1024,
+            completionWindows: ['24h'],
+            supportsCancel: true,
+            discount: 0.5,
+        },
+    };
+    constructor(options) {
+        this.options = options;
+    }
+    async submit(request, context) {
+        const requests = request.items.map((item) => {
+            const { system, messages } = splitSystem(item.request.messages);
+            return {
+                custom_id: item.customId,
+                params: {
+                    model: item.request.model || request.model || this.options.defaultModel,
+                    max_tokens: item.request.maxTokens ?? this.options.maxTokens ?? 1024,
+                    temperature: item.request.temperature,
+                    system,
+                    messages,
+                },
+            };
+        });
+        const batch = (await this.request('/messages/batches', { method: 'POST', body: JSON.stringify({ requests }) }, context));
+        if (!batch.id)
+            throw new BatchProviderResponseError('anthropic', 'the batch response returned no id');
+        return { id: batch.id, provider: 'anthropic' };
+    }
+    async poll(ref, context) {
+        const batch = (await this.request(`/messages/batches/${encodeURIComponent(ref.id)}`, {}, context));
+        return this.toState(ref, batch);
+    }
+    async results(ref, context) {
+        const body = await this.requestText(`/messages/batches/${encodeURIComponent(ref.id)}/results`, context);
+        return body
+            .split('\n')
+            .filter((line) => line.trim().length > 0)
+            .map((line) => this.toOutputItem(line));
+    }
+    async cancel(ref, context) {
+        const batch = (await this.request(`/messages/batches/${encodeURIComponent(ref.id)}/cancel`, { method: 'POST' }, context));
+        return this.toState(ref, batch);
+    }
+    toState(ref, batch) {
+        const counts = batch.request_counts;
+        return {
+            ref,
+            status: STATUS_MAP[batch.processing_status ?? ''] ?? 'in_progress',
+            counts: counts
+                ? {
+                    total: (counts.processing ?? 0) +
+                        (counts.succeeded ?? 0) +
+                        (counts.errored ?? 0) +
+                        (counts.canceled ?? 0) +
+                        (counts.expired ?? 0),
+                    completed: counts.succeeded ?? 0,
+                    failed: (counts.errored ?? 0) + (counts.canceled ?? 0) + (counts.expired ?? 0),
+                }
+                : undefined,
+            createdAt: batch.created_at,
+            completedAt: batch.ended_at,
+            expiresAt: batch.expires_at,
+            raw: batch,
+        };
+    }
+    toOutputItem(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new BatchProviderResponseError('anthropic', 'a result line was not valid JSON', error);
+        }
+        const customId = parsed.custom_id ?? '';
+        const result = parsed.result;
+        if (result?.type !== 'succeeded' || !result.message) {
+            return {
+                customId,
+                error: {
+                    message: result?.error?.message ?? `batch item ${result?.type ?? 'failed'}`,
+                    code: result?.error?.type ?? result?.type,
+                },
+            };
+        }
+        const message = result.message;
+        const content = (message.content ?? [])
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text ?? '')
+            .join('');
+        const response = {
+            content,
+            role: 'assistant',
+            finishReason: message.stop_reason === 'max_tokens' ? 'length' : 'stop',
+            meta: buildMeta({
+                provider: 'anthropic',
+                model: message.model ?? '',
+                latencyMs: 0,
+                inputTokens: message.usage?.input_tokens,
+                outputTokens: message.usage?.output_tokens,
+                cachedReadTokens: message.usage?.cache_read_input_tokens,
+            }),
+        };
+        return { customId, response };
+    }
+    async request(path, init, context) {
+        const response = await this.send(path, init, context);
+        return response.json();
+    }
+    async requestText(path, context) {
+        const response = await this.send(path, {}, context);
+        return response.text();
+    }
+    async send(path, init, context) {
+        const fetchImpl = this.options.fetch ?? fetch;
+        const baseUrl = (this.options.baseUrl || 'https://api.anthropic.com/v1').replace(/\/$/, '');
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            ...init,
+            headers: {
+                'x-api-key': this.options.apiKey,
+                'anthropic-version': this.options.version ?? '2023-06-01',
+                'content-type': 'application/json',
+                ...this.options.headers,
+                ...(init.headers ?? {}),
+            },
+            signal: context.signal,
+        });
+        if (!response.ok) {
+            throw new BatchProviderResponseError('anthropic', `${path} failed: ${response.status} ${await safeText(response)}`);
+        }
+        return response;
+    }
+}
+/**
+ * Anthropic takes the system prompt as a top-level field rather than a message.
+ *
+ * Splitting it here keeps the neutral request shape unchanged for callers, who write a system
+ * message like every other provider.
+ */
+function splitSystem(messages) {
+    const system = messages
+        .filter((message) => message.role === 'system')
+        .map((message) => (typeof message.content === 'string' ? message.content : ''))
+        .join('\n')
+        .trim();
+    return {
+        system: system || undefined,
+        messages: messages.filter((message) => message.role !== 'system'),
+    };
+}
+async function safeText(response) {
+    try {
+        return (await response.text()).slice(0, 500);
+    }
+    catch {
+        return '';
+    }
+}