@mccaskie-labs/workbench-ai 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @mccaskie-labs/workbench-ai
+
+## 0.1.2
+
+### Patch Changes
+
+- The build always rebuilds workbench-config first, so a stale config dist/ can't break it.
+
+## 0.1.1
+
+### Patch Changes
+
+- Add `ai.images.generate` and `ai.images.search` (step 4.8), with image routes on `createFakeAi`'s fake Gateway. Needs `workbench-config` 0.1.2 for the images manifest.
+
+## 0.1.0
+
+- First version: `createAi` (`text`, `structured`, `stream`, `countTokens`, `budget`, `anthropic`), `createFakeAi`, `cachedSystem`, `cachedBlocks`, `provenance` and `WorkbenchAiError` (`docs/spec.md` §3).

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @mccaskie-labs/workbench-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude for apps built on Workbench, a private platform. Calls go through the Workbench Gateway, which holds the Anthropic key, resolves model aliases, checks the project's budget, retries transient failures and meters every call. The app holds only its Gateway key. Published publicly so Workbench projects can install it with no token; it is not supported for other uses.
+
+```sh
+npm install @mccaskie-labs/workbench-ai @mccaskie-labs/workbench-config zod
+```
+
+```ts
+import { createAi } from '@mccaskie-labs/workbench-ai'
+import { workbenchEnv } from '@mccaskie-labs/workbench-config'
+
+const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })
+const r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })
+await save({ text: r.text, model: r.model, requestId: r.requestId })
+```
+
+| Export | What it does |
+| --- | --- |
+| `createAi({ key, env, url?, fetch? })` | The client. Throws `invalid_config` at once if the key isn't for `env` (`wbk_dev_`, `wbk_stg_`, `wbk_prd_`) |
+| `ai.text(req)` | One reply as text. Throws `refused` on a refusal and `truncated` on `max_tokens`; never returns partial text |
+| `ai.structured({ ...req, schema, mayLack? })` | JSON matching a zod schema, through structured outputs (`output_config.format`, not forced tool use). Asks once more for required fields left empty, except those in `mayLack`; throws `invalid_output` if they're still empty |
+| `ai.stream(req)` | Async iterable of Anthropic stream events, then `finalMessage()`, which throws like `text` |
+| `ai.countTokens(req)` | Input tokens for a prompt. Free |
+| `ai.budget()` | `{ status: 'ok' \| 'warn' \| 'reached', leftUsd, monthlyUsd, spentUsd, mode, month }` for this key's project and environment, cached 60 s |
+| `ai.images.generate({ prompt, aspectRatio, job, model?, references? })` | One image: `{ bytes, mimeType, model, requestId, costUsd }`. `model` is `image-default` (the default), `image-pro` or `image-openai`; `references` work on the Google aliases only. Needs the `images` scope |
+| `ai.images.search({ q, job, num?, gl?, hl? })` | Serper image search: a list of `{ title, imageUrl, thumbnailUrl, width, height, source, pageUrl }` that also carries `requestId`, `costUsd` and `credits`. Needs the `search` scope |
+| `ai.anthropic` | The official `@anthropic-ai/sdk` client pointed at the Gateway, for anything else |
+| `createFakeAi(script)` | The real client against a scripted fake Gateway, for tests: replies in order, refusals, truncations and Gateway errors, every call recorded in `.calls`. No key, no network |
+| `cachedSystem(stable, ...volatile)`, `cachedBlocks(...texts)` | System blocks with a prompt-cache breakpoint |
+| `provenance(result, promptVersion)` | The record to store with an output: resolved model, request id, prompt version, cost |
+| `WorkbenchAiError` | Every failure: `code`, `retryable`, `requestId`, `upstreamStatus`, `details` |
+
+Every result carries the **resolved** model id (never the alias), the Gateway's request id (it matches a usage row) and the cost in US dollars. `model` is a Workbench alias (`claude-default`, `claude-best`, `claude-fast`) or an allowlisted id; anything else is refused with `model_not_allowed`. `job` (`[a-z0-9._-]{1,64}`) says what the call is for and is recorded with usage.
+
+The package doesn't retry: the Gateway already does (3 attempts on transient failures). Error codes: `refused`, `truncated`, `invalid_output`, `unexpected_stop`, and the Gateway's `unauthorised`, `forbidden_scope`, `invalid_request`, `model_not_allowed`, `budget_exceeded`, `rate_limited`, `not_found`, `not_available`, `upstream_error`, `upstream_timeout`, `internal_error`, plus `network` and `invalid_config`.
+
+Runs on Node 24 and the Cloudflare Workers runtime. `zod` 4 is a peer dependency.

package/dist/ai.d.ts

@@ -0,0 +1,17 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { type GatewayMeta } from "./capture.ts";
+import type { Ai, AiOptions, TextResult } from "./types.ts";
+/**
+ * Claude through the Workbench Gateway (docs/spec.md §3). The app holds only
+ * its Gateway key; the Gateway resolves aliases, checks the budget, retries,
+ * and meters every call.
+ */
+export declare function createAi(opts: AiOptions): Ai;
+/** Turns a Message into a result, or throws: a refusal or a truncation is never a success (audit F18). */
+export declare function toTextResult(message: Anthropic.Message, meta: GatewayMeta): TextResult;
+/**
+ * Top-level fields the model left empty (`""`, `null`, `[]`), except those it
+ * may lack. Structured outputs guarantees the keys are present; this catches
+ * the empty answers it can't rule out (lifted from Imprint's `missingRequired`).
+ */
+export declare function missingRequired(value: unknown, mayLack: readonly string[]): string[];

package/dist/ai.js

@@ -0,0 +1,318 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
+import { DEFAULT_GATEWAY_URL } from "@mccaskie-labs/workbench-config";
+import { createCapture, isGatewayMeta, REQUEST_ID_HEADER } from "./capture.js";
+import { errorFromGateway, WorkbenchAiError } from "./errors.js";
+import { gatewayFetch } from "./http.js";
+import { createImages } from "./images.js";
+const KEY_PREFIX = {
+    development: "wbk_dev_",
+    staging: "wbk_stg_",
+    production: "wbk_prd_",
+};
+const JOB = /^[a-z0-9._-]{1,64}$/;
+const SUBJECT = /^[a-z0-9_-]+:[^\s]{1,128}$/;
+const DEFAULT_MAX_TOKENS = 16000;
+const DEFAULT_STREAM_MAX_TOKENS = 64000;
+const BUDGET_CACHE_MS = 60_000;
+/**
+ * Claude through the Workbench Gateway (docs/spec.md §3). The app holds only
+ * its Gateway key; the Gateway resolves aliases, checks the budget, retries,
+ * and meters every call.
+ */
+export function createAi(opts) {
+    const env = opts.env;
+    const prefix = KEY_PREFIX[env];
+    if (!prefix)
+        throw new WorkbenchAiError("invalid_config", `Unknown Workbench environment`);
+    if (typeof opts.key !== "string" || opts.key === "") {
+        throw new WorkbenchAiError("invalid_config", "WORKBENCH_GATEWAY_KEY is missing");
+    }
+    // Checked before any call, so a staging key in production fails at start-up
+    // rather than on the first request. The key itself is never in the message.
+    if (!opts.key.startsWith(prefix)) {
+        throw new WorkbenchAiError("invalid_config", `WORKBENCH_GATEWAY_KEY is not a ${env} key (expected the ${prefix} prefix)`);
+    }
+    const url = (opts.url ?? DEFAULT_GATEWAY_URL).replace(/\/+$/, "");
+    const baseFetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const client = (f) => new Anthropic({
+        apiKey: opts.key,
+        // Never pick up ANTHROPIC_AUTH_TOKEN or a local `ant` profile: the Gateway key is the only credential.
+        authToken: null,
+        baseURL: `${url}/anthropic`,
+        fetch: f,
+        // The Gateway retries transient failures itself (docs/spec.md §2.3);
+        // retrying here too would multiply attempts and spend.
+        maxRetries: 0,
+        defaultHeaders: { "X-Workbench-Env": env },
+    });
+    const anthropic = client(baseFetch);
+    let budgetCache;
+    function headers(req) {
+        if (!JOB.test(req.job))
+            throw new WorkbenchAiError("invalid_request", "job must match [a-z0-9._-]{1,64}");
+        const h = { "X-Workbench-Job": req.job };
+        if (req.promptVersion !== undefined)
+            h["X-Workbench-Prompt-Version"] = req.promptVersion;
+        if (req.subject !== undefined) {
+            if (!SUBJECT.test(req.subject))
+                throw new WorkbenchAiError("invalid_request", "subject must be type:id");
+            h["X-Workbench-Subject"] = req.subject;
+        }
+        return h;
+    }
+    async function create(body, req) {
+        const cap = createCapture(baseFetch);
+        try {
+            const message = await client(cap.fetch).messages.create(body, { headers: headers(req) });
+            return { message, meta: metaOf(message, cap), cap };
+        }
+        catch (err) {
+            throw mapError(err, cap.requestId());
+        }
+    }
+    async function text(req) {
+        const { message, meta } = await create(params(req, DEFAULT_MAX_TOKENS), req);
+        return toTextResult(message, meta);
+    }
+    async function structured(req) {
+        const base = params(req, DEFAULT_MAX_TOKENS);
+        const format = zodOutputFormat(req.schema);
+        const body = {
+            ...base,
+            output_config: { ...(base.output_config ?? {}), format },
+        };
+        const first = await create(body, req);
+        let result = toTextResult(first.message, first.meta);
+        let parsed = parseStructured(req, result);
+        let usage = result.usage;
+        let cost = result.costUsd;
+        const missing = missingRequired(parsed.value, req.mayLack ?? []);
+        if (missing.length > 0) {
+            // Ask once more for the required fields left empty (docs/spec.md §3),
+            // replaying the first reply unchanged, thinking blocks included.
+            const again = {
+                ...body,
+                messages: [
+                    ...body.messages,
+                    { role: "assistant", content: first.message.content },
+                    {
+                        role: "user",
+                        content: `These required fields are empty: ${missing.join(", ")}. Reply again with the complete JSON object, filling them in.`,
+                    },
+                ],
+            };
+            const second = await create(again, req);
+            result = toTextResult(second.message, second.meta);
+            parsed = parseStructured(req, result);
+            usage = addUsage(usage, result.usage);
+            cost += result.costUsd;
+            const still = missingRequired(parsed.value, req.mayLack ?? []);
+            if (still.length > 0) {
+                throw new WorkbenchAiError("invalid_output", `Required fields still empty after a re-ask: ${still.join(", ")}`, {
+                    requestId: result.requestId,
+                    model: result.model,
+                    missing: still,
+                });
+            }
+        }
+        return { data: parsed.data, model: result.model, requestId: result.requestId, usage, costUsd: round6(cost) };
+    }
+    function stream(req) {
+        const cap = createCapture(baseFetch);
+        let ms;
+        try {
+            ms = client(cap.fetch).messages.stream(params(req, DEFAULT_STREAM_MAX_TOKENS), { headers: headers(req) });
+        }
+        catch (err) {
+            const e = mapError(err, cap.requestId());
+            return failedStream(e);
+        }
+        // finalMessage() must not leave an unhandled rejection if the caller only iterates.
+        const final = ms.finalMessage().then((message) => {
+            const meta = cap.streamMeta();
+            if (!meta) {
+                throw new WorkbenchAiError("internal_error", "The Gateway's stream ended without its workbench.usage event", {
+                    ...(cap.requestId() ? { requestId: cap.requestId() } : {}),
+                });
+            }
+            return toTextResult(message, meta);
+        }, (err) => {
+            throw mapError(err, cap.requestId());
+        });
+        final.catch(() => { });
+        return {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    for await (const event of ms)
+                        yield event;
+                }
+                catch (err) {
+                    throw mapError(err, cap.requestId());
+                }
+            },
+            finalMessage: () => final,
+        };
+    }
+    async function countTokens(req) {
+        const cap = createCapture(baseFetch);
+        try {
+            const r = await client(cap.fetch).messages.countTokens({
+                model: req.model,
+                messages: [{ role: "user", content: req.prompt }],
+                ...(req.system !== undefined ? { system: req.system } : {}),
+            }, { headers: headers(req) });
+            return { inputTokens: r.input_tokens };
+        }
+        catch (err) {
+            throw mapError(err, cap.requestId());
+        }
+    }
+    async function budget() {
+        const now = Date.now();
+        if (budgetCache && now - budgetCache.at < BUDGET_CACHE_MS)
+            return budgetCache.value;
+        const { response, requestId } = await gatewayFetch({ url, key: opts.key, env, fetch: baseFetch }, "/v1/usage");
+        const body = await response.json().catch(() => undefined);
+        const value = budgetFrom(body, requestId);
+        budgetCache = { at: now, value };
+        return value;
+    }
+    const images = createImages({ url, key: opts.key, env, fetch: baseFetch });
+    return { anthropic, text, structured, stream, countTokens, budget, images };
+}
+function params(req, defaultMax) {
+    const body = {
+        model: req.model,
+        max_tokens: req.maxTokens ?? defaultMax,
+        messages: [{ role: "user", content: req.prompt }],
+    };
+    if (req.system !== undefined)
+        body.system = req.system;
+    if (req.effort !== undefined)
+        body.output_config = { effort: req.effort };
+    return body;
+}
+function metaOf(message, cap) {
+    const meta = message.workbench;
+    if (isGatewayMeta(meta))
+        return meta;
+    const requestId = cap.requestId();
+    throw new WorkbenchAiError("internal_error", "The Gateway's reply carried no workbench usage object", {
+        ...(requestId ? { requestId } : {}),
+    });
+}
+/** Turns a Message into a result, or throws: a refusal or a truncation is never a success (audit F18). */
+export function toTextResult(message, meta) {
+    const base = { requestId: meta.request_id, model: meta.model };
+    if (message.stop_reason === "refusal" || meta.refused === true) {
+        const category = message.stop_details?.category ?? null;
+        throw new WorkbenchAiError("refused", "Claude declined the request", { ...base, refusalCategory: category });
+    }
+    if (message.stop_reason === "max_tokens") {
+        throw new WorkbenchAiError("truncated", "The reply hit max_tokens before it finished", base);
+    }
+    if (message.stop_reason !== "end_turn" && message.stop_reason !== "stop_sequence") {
+        throw new WorkbenchAiError("unexpected_stop", `The reply stopped with ${String(message.stop_reason)}`, base);
+    }
+    const text = message.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+    return { text, model: meta.model, requestId: meta.request_id, usage: usageOf(message.usage), costUsd: meta.cost_usd };
+}
+function usageOf(u) {
+    return {
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheWriteTokens: u.cache_creation_input_tokens ?? 0,
+    };
+}
+function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+    };
+}
+function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+function parseStructured(req, r) {
+    let value;
+    try {
+        value = JSON.parse(r.text);
+    }
+    catch {
+        throw new WorkbenchAiError("invalid_output", "The reply wasn't JSON", { requestId: r.requestId, model: r.model });
+    }
+    const parsed = req.schema.safeParse(value);
+    if (!parsed.success) {
+        throw new WorkbenchAiError("invalid_output", `The reply didn't match the schema: ${parsed.error.message}`, {
+            requestId: r.requestId,
+            model: r.model,
+        });
+    }
+    return { value, data: parsed.data };
+}
+/**
+ * Top-level fields the model left empty (`""`, `null`, `[]`), except those it
+ * may lack. Structured outputs guarantees the keys are present; this catches
+ * the empty answers it can't rule out (lifted from Imprint's `missingRequired`).
+ */
+export function missingRequired(value, mayLack) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return [];
+    const out = [];
+    for (const [k, v] of Object.entries(value)) {
+        if (mayLack.includes(k))
+            continue;
+        if (v === null || (typeof v === "string" && v.trim() === "") || (Array.isArray(v) && v.length === 0))
+            out.push(k);
+    }
+    return out;
+}
+function mapError(err, requestId) {
+    if (err instanceof WorkbenchAiError)
+        return err;
+    if (err instanceof Anthropic.APIConnectionError) {
+        return new WorkbenchAiError("network", "Couldn't reach the Gateway", requestId ? { requestId } : {});
+    }
+    if (err instanceof Anthropic.APIError) {
+        const rid = err.headers?.get?.(REQUEST_ID_HEADER) ?? requestId;
+        return errorFromGateway(err.status, err.error, rid ?? undefined);
+    }
+    return new WorkbenchAiError("internal_error", err instanceof Error ? err.message : "Unknown failure", requestId ? { requestId } : {});
+}
+function failedStream(e) {
+    const final = Promise.reject(e);
+    final.catch(() => { });
+    return {
+        // eslint-disable-next-line require-yield
+        async *[Symbol.asyncIterator]() {
+            throw e;
+        },
+        finalMessage: () => final,
+    };
+}
+function budgetFrom(body, requestId) {
+    const b = body;
+    const budget = b?.budget;
+    if (!budget) {
+        throw new WorkbenchAiError("not_found", "No budget is set for this project and environment", requestId ? { requestId } : {});
+    }
+    const status = budget.status;
+    if (status !== "ok" && status !== "warn" && status !== "reached") {
+        throw new WorkbenchAiError("internal_error", "The Gateway's usage reply had no budget status", requestId ? { requestId } : {});
+    }
+    return {
+        status,
+        leftUsd: Math.max(0, Number(budget.left_usd)),
+        monthlyUsd: Number(budget.monthly_usd),
+        spentUsd: Number(b.spent_usd),
+        mode: budget.mode === "shadow" ? "shadow" : "enforce",
+        month: typeof b.month === "string" ? b.month : "",
+    };
+}

package/dist/capture.d.ts

@@ -0,0 +1,26 @@
+export declare const REQUEST_ID_HEADER = "x-workbench-request-id";
+/** What the Gateway reports about a call: the `workbench` object, or the `workbench.usage` event. */
+export interface GatewayMeta {
+    request_id: string;
+    /** The resolved model id, never the alias (audit F17). */
+    model: string;
+    cost_usd: number;
+    refused?: boolean;
+    alias?: string | null;
+    attempts?: number;
+}
+export interface Capture {
+    fetch: typeof fetch;
+    /** The request id from the last response's header, if one came back. */
+    requestId(): string | undefined;
+    /** The `workbench.usage` event, once the stream has finished. */
+    streamMeta(): GatewayMeta | undefined;
+}
+export declare function isGatewayMeta(value: unknown): value is GatewayMeta;
+export declare function createCapture(base: typeof fetch): Capture;
+/**
+ * Passes SSE events through unchanged, except `workbench.usage`, which is
+ * parsed and handed to `onMeta` instead. Event boundaries are blank lines
+ * (LF or CRLF), as the SSE spec has them.
+ */
+export declare function stripUsageEvent(onMeta: (meta: GatewayMeta) => void): TransformStream<Uint8Array, Uint8Array>;

package/dist/capture.js

@@ -0,0 +1,90 @@
+// A fetch wrapper that reads what the Gateway adds to an Anthropic response,
+// so the official SDK never has to know about it (docs/spec.md §2.3):
+//
+// - `X-Workbench-Request-Id` on every response;
+// - on a non-streamed reply, a `workbench` object beside the Message, which
+//   the SDK passes through untouched;
+// - on a stream, a final `event: workbench.usage` after `message_stop`. The
+//   wrapper takes that event out of the stream before the SDK parses it.
+//
+// One capture is made per call, so nothing is shared between requests.
+export const REQUEST_ID_HEADER = "x-workbench-request-id";
+export function isGatewayMeta(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return typeof v["request_id"] === "string" && typeof v["model"] === "string" && typeof v["cost_usd"] === "number";
+}
+export function createCapture(base) {
+    let requestId;
+    let meta;
+    const wrapped = (async (input, init) => {
+        const res = await base(input, init);
+        requestId = res.headers.get(REQUEST_ID_HEADER) ?? requestId;
+        const type = res.headers.get("content-type") ?? "";
+        if (!res.body || !type.includes("text/event-stream"))
+            return res;
+        const body = res.body.pipeThrough(stripUsageEvent((m) => (meta = m)));
+        return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+    });
+    return {
+        fetch: wrapped,
+        requestId: () => requestId,
+        streamMeta: () => meta,
+    };
+}
+const USAGE_EVENT = "workbench.usage";
+/**
+ * Passes SSE events through unchanged, except `workbench.usage`, which is
+ * parsed and handed to `onMeta` instead. Event boundaries are blank lines
+ * (LF or CRLF), as the SSE spec has them.
+ */
+export function stripUsageEvent(onMeta) {
+    const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
+    let buffer = "";
+    function flushEvents(controller, final) {
+        buffer = buffer.replace(/\r\n/g, "\n");
+        let cut;
+        while ((cut = buffer.indexOf("\n\n")) !== -1) {
+            const block = buffer.slice(0, cut);
+            buffer = buffer.slice(cut + 2);
+            emit(block, controller);
+        }
+        if (final && buffer.trim() !== "") {
+            emit(buffer, controller);
+            buffer = "";
+        }
+    }
+    function emit(block, controller) {
+        const lines = block.split("\n");
+        const event = lines.find((l) => l.startsWith("event:"))?.slice(6).trim();
+        if (event === USAGE_EVENT) {
+            const data = lines
+                .filter((l) => l.startsWith("data:"))
+                .map((l) => l.slice(5).replace(/^ /, ""))
+                .join("\n");
+            try {
+                const parsed = JSON.parse(data);
+                if (isGatewayMeta(parsed))
+                    onMeta(parsed);
+            }
+            catch {
+                // A malformed usage event is dropped; the caller then reports no cost
+                // rather than a wrong one.
+            }
+            return;
+        }
+        controller.enqueue(encoder.encode(`${block}\n\n`));
+    }
+    return new TransformStream({
+        transform(chunk, controller) {
+            buffer += decoder.decode(chunk, { stream: true });
+            flushEvents(controller, false);
+        },
+        flush(controller) {
+            buffer += decoder.decode();
+            flushEvents(controller, true);
+        },
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+export type AiErrorCode = "refused" | "truncated" | "invalid_output" | "unexpected_stop" | "unauthorised" | "forbidden_scope" | "invalid_request" | "model_not_allowed" | "budget_exceeded" | "rate_limited" | "not_found" | "not_available" | "upstream_error" | "upstream_timeout" | "internal_error" | "network" | "invalid_config";
+export interface AiErrorDetails {
+    requestId?: string;
+    upstreamStatus?: number;
+    /** The resolved model, when the Gateway got as far as resolving one. */
+    model?: string;
+    /** For `invalid_output`: the required fields still missing after the re-ask. */
+    missing?: string[];
+    /** For `refused`: the refusal category Anthropic gave, if any. */
+    refusalCategory?: string | null;
+    /** For `budget_exceeded`. */
+    month?: string;
+    spentUsd?: number;
+    capUsd?: number;
+}
+export declare class WorkbenchAiError extends Error {
+    readonly code: AiErrorCode;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly upstreamStatus?: number;
+    readonly details: AiErrorDetails;
+    constructor(code: AiErrorCode, message: string, details?: AiErrorDetails);
+}
+/** Maps an HTTP status to a code, for an error body that carries none. */
+export declare function codeForStatus(status: number | undefined): AiErrorCode;
+/** Picks the Workbench code out of either error shape the Gateway sends. */
+export declare function codeFromBody(body: unknown): string | undefined;
+/**
+ * Builds a WorkbenchAiError from a Gateway error response: `/anthropic/*`
+ * keeps Anthropic's shape with `error.workbench_code`; the `/v1/*` paths use
+ * `{ error: { code, message, request_id, retryable, upstream_status? } }`.
+ */
+export declare function errorFromGateway(status: number | undefined, body: unknown, requestId?: string): WorkbenchAiError;

package/dist/errors.js

@@ -0,0 +1,100 @@
+// Every failure the package raises is a WorkbenchAiError with a stable code
+// (docs/spec.md §3). Callers branch on `code`, never on the message. A refusal
+// or a max_tokens truncation is an error, never a partial success (audit F18).
+const RETRYABLE = new Set(["rate_limited", "upstream_error", "upstream_timeout", "network"]);
+export class WorkbenchAiError extends Error {
+    code;
+    retryable;
+    requestId;
+    upstreamStatus;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "WorkbenchAiError";
+        this.code = code;
+        this.retryable = RETRYABLE.has(code);
+        this.details = details;
+        if (details.requestId !== undefined)
+            this.requestId = details.requestId;
+        if (details.upstreamStatus !== undefined)
+            this.upstreamStatus = details.upstreamStatus;
+    }
+}
+const KNOWN = new Set([
+    "unauthorised",
+    "forbidden_scope",
+    "invalid_request",
+    "model_not_allowed",
+    "budget_exceeded",
+    "rate_limited",
+    "not_found",
+    "not_available",
+    "upstream_error",
+    "upstream_timeout",
+    "internal_error",
+]);
+/** Maps an HTTP status to a code, for an error body that carries none. */
+export function codeForStatus(status) {
+    switch (status) {
+        case 400:
+        case 413:
+        case 422:
+            return "invalid_request";
+        case 401:
+            return "unauthorised";
+        case 402:
+            return "budget_exceeded";
+        case 403:
+            return "forbidden_scope";
+        case 404:
+            return "not_found";
+        case 429:
+            return "rate_limited";
+        case 501:
+            return "not_available";
+        case 504:
+            return "upstream_timeout";
+        case undefined:
+            return "network";
+        default:
+            return status >= 500 ? "upstream_error" : "invalid_request";
+    }
+}
+/** Picks the Workbench code out of either error shape the Gateway sends. */
+export function codeFromBody(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const err = body.error;
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const e = err;
+    if (typeof e.workbench_code === "string")
+        return e.workbench_code;
+    if (typeof e.code === "string")
+        return e.code;
+    return undefined;
+}
+/**
+ * Builds a WorkbenchAiError from a Gateway error response: `/anthropic/*`
+ * keeps Anthropic's shape with `error.workbench_code`; the `/v1/*` paths use
+ * `{ error: { code, message, request_id, retryable, upstream_status? } }`.
+ */
+export function errorFromGateway(status, body, requestId) {
+    const raw = codeFromBody(body);
+    const code = raw !== undefined && KNOWN.has(raw) ? raw : codeForStatus(status);
+    const err = (typeof body === "object" && body !== null ? body.error : undefined) ?? {};
+    const message = typeof err["message"] === "string" ? err["message"] : `Gateway answered ${status ?? "nothing"}`;
+    const details = {};
+    const rid = requestId ?? (typeof err["request_id"] === "string" ? err["request_id"] : undefined);
+    if (rid)
+        details.requestId = rid;
+    if (typeof err["upstream_status"] === "number")
+        details.upstreamStatus = err["upstream_status"];
+    if (typeof err["month"] === "string")
+        details.month = err["month"];
+    if (typeof err["spent_usd"] === "number")
+        details.spentUsd = err["spent_usd"];
+    if (typeof err["cap_usd"] === "number")
+        details.capUsd = err["cap_usd"];
+    return new WorkbenchAiError(code, message, details);
+}