@alma-harness/providers 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,8 @@
 Anthropic and OpenAI first-party, plus the OpenRouter gateway bridge, over one
 neutral message format.
 
-> **Status: pre-release.** Not yet published to npm.
+> **Status: 0.2.0 on npm, pre-1.0.** The API is still moving; see the
+> [roadmap](../../docs/architecture.md#12-adoption-roadmap) for where it stands.
 
 ## What it owns
 
@@ -44,6 +45,64 @@ const client = new AnthropicModelClient();          // reads ANTHROPIC_API_KEY
 const explicit = new AnthropicModelClient({ apiKey }); // or inject it
 ```
 
+## Jobs
+
+`AnthropicJobClient` (Message Batches) and `OpenAIJobClient` (the Batch API,
+over a JSONL file of `/v1/responses` requests) implement the `ModelJobClient`
+seam (spec: model-jobs): the same request translations, minus streaming, and
+a non-streaming translation of the complete answer. OpenRouter has no batch
+API.
+
+## Reasoning
+
+When the policy sets `ModelChoice.reasoning` (spec: reasoning-blocks), each
+adapter asks for it and hands it back as one complete block per step:
+
+| effort | Anthropic | OpenAI | OpenRouter |
+|---|---|---|---|
+| absent | nothing sent; default output dropped | nothing sent; default items dropped | nothing sent |
+| `none` | `thinking: disabled` | `reasoning.effort: none` | `reasoning.enabled: false` |
+| others | `thinking: adaptive` + `output_config.effort` | `reasoning.effort` + encrypted content | `reasoning.effort` |
+
+An adapter replays only its own blocks, and only when reasoning is on for the
+request; every other reasoning block in the history is skipped.
+
+## Provider-executed web search
+
+`ModelRequest.providerTools` (spec: provider-tools) declares the provider's
+own search beside the registered tools; what comes back is two neutral
+blocks, `provider_tool_call` and `provider_tool_result`, the provider's
+payload kept `opaque` for replay.
+
+| | Anthropic | OpenAI | OpenRouter |
+|---|---|---|---|
+| declaration | `web_search_20250305` (the direct search; the agentic 2026-03-18 version drives `code_execution` and is another kind) with `max_uses`, `allowed_domains`, `blocked_domains` | `{ type: "web_search", filters: { allowed_domains } }` + `include: ["web_search_call.action.sources"]`; `blockedDomains` is REFUSED before the network; `maxUses` is the loop's to enforce | refused before the network |
+| on the stream | `server_tool_use` → call; `web_search_tool_result` → result (url, title, page age; an error code as `error`); `usage.server_tool_use.web_search_requests` | a completed `web_search_call` item → call (`input: action`) and result (the sources; `failed` as an error), counted | — |
+| replay | its own two blocks as `server_tool_use` + `web_search_tool_result` with the encrypted content, only while the request declares the kind (a capped step replays the text and skips the search); another provider's skipped | its own result's `opaque` as the item, only while the request declares the kind; the call block skipped | skipped |
+| `pause_turn` | → the neutral `pause`: the loop re-sends | — | — |
+
+## Arguments the wire cut
+
+A tool call whose arguments do not parse — a response cut by `max_tokens`
+mid-arguments, or a model that emitted broken JSON — is still a `tool_call`
+(spec: what-the-wire-cuts): `input: {}` and the raw text as `malformed`,
+followed by the wire's own stop reason. The loop answers a malformed call
+with an invalid-input result on `tool_use`, and closes it on `max_tokens`.
+The translators never throw on it.
+
+## Errors
+
+What an SDK throws leaves every client as a `ProviderError` from
+`@alma-harness/core` (spec: error-taxonomy), classified through one
+duck-typed table over the fields the SDKs share: 429 → `rate_limited`
+(OpenAI's `insufficient_quota` → `rejected`); 529, 503 or an overloaded body
+→ `overloaded`; no status or 5xx → `unavailable`; a 400 that says the prompt
+does not fit → `context_window`; the other 4xx → `rejected`. A user abort
+passes through untouched. The translation error classes are
+`ProviderError`s too — `rejected` before the network, `provider_drift`
+mid-stream — and `toProviderError` / `classifyFailure` are exported for a
+product wrapping its own client.
+
 ## What it must never do
 
 - Decide routing, spend, or capability. Those are core, not adapter.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ModelClient, ModelRequest, ModelEvent } from '@alma-harness/core';
-export { ModelClient, ModelEvent, ModelRef, ModelRequest, ProviderId } from '@alma-harness/core';
+import { ModelClient, ModelRequest, ModelEvent, ProviderError, ProviderFailureKind, ModelJobClient, JobItem, JobHandle, JobProgress, JobResult, JobOutput, ProviderId } from '@alma-harness/core';
+export { ModelClient, ModelEvent, ModelJobClient, ModelRef, ModelRequest, ProviderId } from '@alma-harness/core';
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 
@@ -11,7 +11,8 @@ interface AnthropicModelClientOptions {
 /**
  * `ModelClient` adapter for the Anthropic Messages API — §6.2, spec 002.
  * A thin shell: request/stream translation lives in ./translate (pure);
- * this class only owns the SDK client. SDK typed errors propagate as-is.
+ * this class only owns the SDK client. What the SDK throws leaves as a
+ * `ProviderError` (spec: error-taxonomy); a user abort passes through.
  */
 declare class AnthropicModelClient implements ModelClient {
     #private;
@@ -26,9 +27,14 @@ declare class AnthropicModelClient implements ModelClient {
  * Messages API — spec 002. Everything here is side-effect-free so the wire
  * mapping is testable without a network.
  */
-/** Raised when a request or stream cannot be represented faithfully. */
-declare class AnthropicTranslationError extends Error {
-    constructor(message: string);
+/**
+ * Raised when a request or stream cannot be represented faithfully. A
+ * `ProviderError` since spec: error-taxonomy — `rejected` before the network
+ * (the request as built cannot be sent), `provider_drift` mid-stream (the
+ * wire sent something this adapter does not know).
+ */
+declare class AnthropicTranslationError extends ProviderError {
+    constructor(message: string, kind?: ProviderFailureKind);
 }
 declare function toAnthropicParams(req: ModelRequest): Anthropic.MessageCreateParamsStreaming;
 /**
@@ -40,6 +46,27 @@ declare function toAnthropicParams(req: ModelRequest): Anthropic.MessageCreatePa
  */
 declare function translateStream(events: AsyncIterable<Anthropic.RawMessageStreamEvent>): AsyncGenerator<ModelEvent>;
 
+/**
+ * `ModelJobClient` over the Anthropic Message Batches API — spec: model-jobs.
+ * Each item's request is translated with the same function the stream uses,
+ * minus `stream`; a succeeded result is a complete `Message`, translated
+ * here into the neutral output the runner prices and returns.
+ */
+/** A complete message → neutral blocks, usage and stop — the non-streaming half of spec 002. */
+declare function translateMessage(message: Anthropic.Message): JobOutput;
+interface AnthropicJobClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+declare class AnthropicJobClient implements ModelJobClient {
+    #private;
+    constructor(opts?: AnthropicJobClientOptions);
+    submit(items: readonly JobItem[]): Promise<JobHandle>;
+    status(handle: JobHandle): Promise<JobProgress>;
+    results(handle: JobHandle): AsyncIterable<JobResult>;
+    cancel(handle: JobHandle): Promise<void>;
+}
+
 interface OpenAIModelClientOptions {
     /** Omit to use the SDK's environment resolution (OPENAI_API_KEY). */
     apiKey?: string;
@@ -48,7 +75,8 @@ interface OpenAIModelClientOptions {
 /**
  * `ModelClient` adapter for the OpenAI Responses API — §6.2, spec 003.
  * A thin shell: request/stream translation lives in ./translate (pure);
- * this class only owns the SDK client. SDK typed errors propagate as-is.
+ * this class only owns the SDK client. What the SDK throws leaves as a
+ * `ProviderError` (spec: error-taxonomy); a user abort passes through.
  */
 declare class OpenAIModelClient implements ModelClient {
     #private;
@@ -62,8 +90,9 @@ declare class OpenAIModelClient implements ModelClient {
  * Pure translation between Alma's neutral vocabulary (§6.2) and the OpenAI
  * Responses API — spec 003. Side-effect-free; testable without a network.
  */
-declare class OpenAITranslationError extends Error {
-    constructor(message: string);
+/** A `ProviderError` since spec: error-taxonomy — see `AnthropicTranslationError`. */
+declare class OpenAITranslationError extends ProviderError {
+    constructor(message: string, kind?: ProviderFailureKind);
 }
 declare function toOpenAIParams(req: ModelRequest): OpenAI.Responses.ResponseCreateParamsStreaming;
 /**
@@ -75,6 +104,35 @@ declare function toOpenAIParams(req: ModelRequest): OpenAI.Responses.ResponseCre
  */
 declare function translateOpenAIStream(events: AsyncIterable<OpenAI.Responses.ResponseStreamEvent>): AsyncGenerator<ModelEvent>;
 
+/**
+ * `ModelJobClient` over the OpenAI Batch API — spec: model-jobs. Items become
+ * one JSONL file of `/v1/responses` requests, uploaded with purpose `batch`;
+ * results come back as a JSONL file of complete `Response` objects, each
+ * translated here into the neutral output the runner prices and returns.
+ */
+/** One line of the batch input file. */
+interface BatchLine {
+    custom_id: string;
+    method: "POST";
+    url: "/v1/responses";
+    body: OpenAI.Responses.ResponseCreateParamsNonStreaming;
+}
+declare function toBatchLines(items: readonly JobItem[]): BatchLine[];
+/** A complete response → neutral blocks, usage and stop — the non-streaming half of spec 003. */
+declare function translateResponse(response: OpenAI.Responses.Response): JobOutput;
+interface OpenAIJobClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+declare class OpenAIJobClient implements ModelJobClient {
+    #private;
+    constructor(opts?: OpenAIJobClientOptions);
+    submit(items: readonly JobItem[]): Promise<JobHandle>;
+    status(handle: JobHandle): Promise<JobProgress>;
+    results(handle: JobHandle): AsyncIterable<JobResult>;
+    cancel(handle: JobHandle): Promise<void>;
+}
+
 /**
  * Pure translation between Alma's neutral vocabulary (§6.2) and OpenRouter's
  * chat-completions wire — spec 014. A SECOND translator over the neutral
@@ -82,8 +140,9 @@ declare function translateOpenAIStream(events: AsyncIterable<OpenAI.Responses.Re
  * Responses API, and nothing in its translation is reusable here.
  * Side-effect-free; testable without a network.
  */
-declare class OpenRouterTranslationError extends Error {
-    constructor(message: string);
+/** A `ProviderError` since spec: error-taxonomy — see `AnthropicTranslationError`. */
+declare class OpenRouterTranslationError extends ProviderError {
+    constructor(message: string, kind?: ProviderFailureKind);
 }
 /**
  * The upstream routing policy — spec 014's core constraint: for a gateway,
@@ -118,8 +177,14 @@ interface OpenRouterProviderBlock {
     zdr?: boolean;
     require_parameters?: boolean;
 }
+/** OpenRouter's reasoning block — a gateway extension the OpenAI SDK does not type. */
+interface OpenRouterReasoningBlock {
+    effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    enabled?: boolean;
+}
 type OpenRouterParams = OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming & {
     provider: OpenRouterProviderBlock;
+    reasoning?: OpenRouterReasoningBlock;
 };
 declare function toOpenRouterParams(req: ModelRequest, routing: OpenRouterRouting): OpenRouterParams;
 /**
@@ -155,6 +220,15 @@ declare class OpenRouterModelClient implements ModelClient {
     }): AsyncIterable<ModelEvent>;
 }
 
+/**
+ * Wraps anything but a user abort. The abort passes through untouched: the
+ * loop already reads its own signal, and a wrapped abort would classify a
+ * cancellation as a provider failure.
+ */
+declare function toProviderError(provider: ProviderId, err: unknown): unknown;
+/** The table. Exported for the one caller that has a code and no thrown error: a failure the wire REPORTED. */
+declare function classifyFailure(name: string, status: number | undefined, hints: string): ProviderFailureKind;
+
 /**
  * @alma-harness/providers — `ModelClient` adapters (§6.2).
  * Bi-provider from birth — `AnthropicModelClient` (spec 002) and
@@ -169,4 +243,4 @@ declare class OpenRouterModelClient implements ModelClient {
  */
 declare const SUPPORTED_PROVIDERS: readonly ["anthropic", "openai", "openrouter"];
 
-export { AnthropicModelClient, type AnthropicModelClientOptions, AnthropicTranslationError, OpenAIModelClient, type OpenAIModelClientOptions, OpenAITranslationError, OpenRouterModelClient, type OpenRouterModelClientOptions, type OpenRouterParams, type OpenRouterRouting, OpenRouterTranslationError, SUPPORTED_PROVIDERS, toAnthropicParams, toOpenAIParams, toOpenRouterParams, translateOpenAIStream, translateOpenRouterStream, translateStream };
+export { AnthropicJobClient, type AnthropicJobClientOptions, AnthropicModelClient, type AnthropicModelClientOptions, AnthropicTranslationError, type BatchLine, OpenAIJobClient, type OpenAIJobClientOptions, OpenAIModelClient, type OpenAIModelClientOptions, OpenAITranslationError, OpenRouterModelClient, type OpenRouterModelClientOptions, type OpenRouterParams, type OpenRouterRouting, OpenRouterTranslationError, SUPPORTED_PROVIDERS, classifyFailure, toAnthropicParams, toBatchLines, toOpenAIParams, toOpenRouterParams, toProviderError, translateMessage, translateOpenAIStream, translateOpenRouterStream, translateResponse, translateStream };