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

package/dist/fake.d.ts

@@ -0,0 +1,85 @@
+import { type WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+import type { Ai } from "./types.ts";
+export interface FakeReply {
+    /** Reply text. For `structured`, give `json` instead. */
+    text?: string;
+    /** Serialised as the reply text. */
+    json?: unknown;
+    stopReason?: "end_turn" | "max_tokens" | "refusal" | "stop_sequence" | "pause_turn";
+    refusalCategory?: string | null;
+    /** The resolved model to report; by default the alias's target from the manifest, or the id asked for. */
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    /** Answer with a Gateway error instead, e.g. `{ status: 402, code: "budget_exceeded" }`. */
+    error?: {
+        status: number;
+        code: string;
+        message?: string;
+        month?: string;
+        spentUsd?: number;
+        capUsd?: number;
+    };
+}
+export interface FakeCall {
+    path: string;
+    method: string;
+    job: string | null;
+    promptVersion: string | null;
+    subject: string | null;
+    /** The parsed JSON body (Anthropic Messages request), if any. */
+    body: Record<string, unknown> | null;
+    stream: boolean;
+}
+export type ReplyFor = FakeReply | ((call: FakeCall) => FakeReply);
+export interface FakeScript {
+    /** Replies in order, one per `messages` call; the last one repeats. A function answers every call. */
+    replies?: ReplyFor[] | ((call: FakeCall, index: number) => FakeReply);
+    /** What `count_tokens` reports. Default 12. */
+    inputTokens?: number;
+    /** What `budget()` reports; `null` means the environment has no budget. */
+    budget?: {
+        status: "ok" | "warn" | "reached";
+        monthlyUsd: number;
+        spentUsd: number;
+        mode?: "enforce" | "shadow";
+    } | null;
+    env?: WorkbenchEnv;
+    /** What `images.generate` and `images.search` get back. */
+    images?: {
+        /** Bytes and model for every image; by default a 1x1 PNG and the alias's target from the manifest. */
+        generate?: {
+            bytes?: Uint8Array;
+            mimeType?: string;
+            model?: string;
+            costUsd?: number;
+            error?: FakeError;
+        };
+        /** Results for every search; by default one result per `num` (at most 3). */
+        search?: {
+            results?: Array<{
+                title?: string;
+                image_url: string;
+                width?: number;
+                height?: number;
+            }>;
+            error?: FakeError;
+        };
+    };
+}
+export interface FakeError {
+    status: number;
+    code: string;
+    message?: string;
+}
+export interface FakeAi extends Ai {
+    /** Every request the fake Gateway answered, in order. */
+    readonly calls: FakeCall[];
+}
+export declare function createFakeAi(script?: FakeScript): FakeAi;
+/** The fake Gateway on its own, as a `fetch`, for tests that build their own client. */
+export declare function fakeGateway(script?: FakeScript): {
+    fetch: typeof fetch;
+    calls: FakeCall[];
+};

package/dist/fake.js

@@ -0,0 +1,215 @@
+// createFakeAi: the real client, wired to a scripted stand-in for the Gateway.
+// Tests and fresh clones run with no key and no network (audit F10), and the
+// code under test goes through exactly the paths it takes in production:
+// refusals still throw `refused`, truncations `truncated`, errors keep their
+// Gateway codes. Every call is recorded.
+import { capabilities } from "@mccaskie-labs/workbench-config";
+import { createAi } from "./ai.js";
+const FAKE_KEY = {
+    development: "wbk_dev_fakefakefake_" + "x".repeat(43),
+    staging: "wbk_stg_fakefakefake_" + "x".repeat(43),
+    production: "wbk_prd_fakefakefake_" + "x".repeat(43),
+};
+const ALIASES = new Map(capabilities.ai.allowed.aliases.map((a) => [a.alias, a.default_model]));
+/** Image aliases from the manifest (capabilities/images.json), with their providers. */
+const IMAGE_ALIASES = new Map(capabilities.images.allowed.aliases.map((a) => [a.alias, { provider: a.provider, model: a.default_model }]));
+// A 1x1 transparent PNG.
+const TINY_PNG = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGD4DwABBAEAwS2OUAAAAABJRU5ErkJggg=="), (c) => c.charCodeAt(0));
+function v1Error(status, requestId, code, message) {
+    return json(status, requestId, { error: { code, message, request_id: requestId, retryable: status === 429 || status >= 502 } });
+}
+function fakeImage(script, body, requestId) {
+    const g = script.images?.generate ?? {};
+    if (g.error)
+        return v1Error(g.error.status, requestId, g.error.code, g.error.message ?? g.error.code);
+    const alias = String(body?.["model"] ?? "image-default");
+    const target = IMAGE_ALIASES.get(alias);
+    if (!target)
+        return v1Error(400, requestId, "model_not_allowed", `${alias} isn't an image alias`);
+    const refs = body?.["references"];
+    if (target.provider === "openai" && Array.isArray(refs) && refs.length > 0) {
+        return v1Error(400, requestId, "invalid_request", `${alias} is an OpenAI model, which takes no reference images`);
+    }
+    const bytes = g.bytes ?? TINY_PNG;
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return json(200, requestId, {
+        mime_type: g.mimeType ?? "image/png",
+        data_base64: btoa(bin),
+        model: g.model ?? target.model,
+        cost_usd: g.costUsd ?? 0.0001,
+        request_id: requestId,
+    });
+}
+function fakeSearch(script, body, requestId) {
+    const s = script.images?.search ?? {};
+    if (s.error)
+        return v1Error(s.error.status, requestId, s.error.code, s.error.message ?? s.error.code);
+    const num = typeof body?.["num"] === "number" ? body["num"] : 10;
+    const results = s.results ?? Array.from({ length: Math.min(num, 3) }, (_, i) => ({ title: `Result ${i + 1}`, image_url: `https://images.fake/${i + 1}.jpg`, width: 1200, height: 800 }));
+    return json(200, requestId, {
+        results: results.map((r) => ({
+            title: r.title ?? "",
+            image_url: r.image_url,
+            thumbnail_url: r.image_url,
+            width: r.width ?? 0,
+            height: r.height ?? 0,
+            source: "fake",
+            page_url: "https://images.fake/",
+        })),
+        credits: num > 10 ? 2 : 1,
+        cost_usd: num > 10 ? 0.002 : 0.001,
+        request_id: requestId,
+    });
+}
+export function createFakeAi(script = {}) {
+    const env = script.env ?? "development";
+    const { fetch, calls } = fakeGateway(script);
+    const ai = createAi({ key: FAKE_KEY[env], env, url: "https://gateway.fake", fetch });
+    return Object.assign(ai, { calls });
+}
+/** The fake Gateway on its own, as a `fetch`, for tests that build their own client. */
+export function fakeGateway(script = {}) {
+    const calls = [];
+    let n = 0;
+    const fetchImpl = (async (input, init) => {
+        const req = new Request(input, init);
+        const url = new URL(req.url);
+        const text = req.method === "GET" ? "" : await req.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = null;
+        }
+        const call = {
+            path: url.pathname,
+            method: req.method,
+            job: req.headers.get("x-workbench-job"),
+            promptVersion: req.headers.get("x-workbench-prompt-version"),
+            subject: req.headers.get("x-workbench-subject"),
+            body,
+            stream: body?.["stream"] === true,
+        };
+        calls.push(call);
+        const requestId = `req_fake_${String(calls.length).padStart(4, "0")}`;
+        if (url.pathname === "/v1/usage") {
+            const b = script.budget === undefined ? { status: "ok", monthlyUsd: 1, spentUsd: 0 } : script.budget;
+            return json(200, requestId, {
+                project: "fake",
+                environment: env(script),
+                month: new Date().toISOString().slice(0, 7),
+                spent_usd: b?.spentUsd ?? 0,
+                budget: b
+                    ? { status: b.status, mode: b.mode ?? "enforce", monthly_usd: b.monthlyUsd, left_usd: Math.max(0, b.monthlyUsd - b.spentUsd) }
+                    : null,
+                by: [],
+                request_id: requestId,
+            });
+        }
+        if (url.pathname === "/v1/images/generate")
+            return fakeImage(script, body, requestId);
+        if (url.pathname === "/v1/images/search")
+            return fakeSearch(script, body, requestId);
+        if (url.pathname === "/anthropic/v1/messages/count_tokens") {
+            return json(200, requestId, { input_tokens: script.inputTokens ?? 12 });
+        }
+        if (url.pathname !== "/anthropic/v1/messages") {
+            return anthropicError(404, requestId, "not_found", "No such endpoint on the fake Gateway");
+        }
+        const replies = script.replies;
+        const index = n++;
+        let reply;
+        if (typeof replies === "function")
+            reply = replies(call, index);
+        else {
+            const list = replies && replies.length > 0 ? replies : [{ text: "ok" }];
+            const r = list[Math.min(index, list.length - 1)];
+            reply = typeof r === "function" ? r(call) : r;
+        }
+        if (reply.error) {
+            const e = reply.error;
+            return anthropicError(e.status, requestId, e.code, e.message ?? e.code, {
+                ...(e.month !== undefined ? { month: e.month } : {}),
+                ...(e.spentUsd !== undefined ? { spent_usd: e.spentUsd } : {}),
+                ...(e.capUsd !== undefined ? { cap_usd: e.capUsd } : {}),
+            });
+        }
+        const asked = String(body?.["model"] ?? "");
+        const model = reply.model ?? ALIASES.get(asked) ?? asked;
+        const stopReason = reply.stopReason ?? "end_turn";
+        const content = reply.json !== undefined ? JSON.stringify(reply.json) : (reply.text ?? "");
+        const message = {
+            id: `msg_fake_${index}`,
+            type: "message",
+            role: "assistant",
+            model,
+            content: stopReason === "refusal" && !content ? [] : [{ type: "text", text: content, citations: null }],
+            stop_reason: stopReason,
+            stop_sequence: null,
+            stop_details: stopReason === "refusal" ? { type: "refusal", category: reply.refusalCategory ?? null, explanation: null } : null,
+            usage: {
+                input_tokens: reply.inputTokens ?? 10,
+                output_tokens: reply.outputTokens ?? 5,
+                cache_read_input_tokens: 0,
+                cache_creation_input_tokens: 0,
+            },
+        };
+        const meta = {
+            request_id: requestId,
+            model,
+            alias: ALIASES.has(asked) ? asked : null,
+            cost_usd: reply.costUsd ?? 0.0001,
+            refused: stopReason === "refusal",
+            attempts: 1,
+        };
+        if (call.stream)
+            return sse(requestId, message, meta);
+        return json(200, requestId, { ...message, workbench: meta });
+    });
+    return { fetch: fetchImpl, calls };
+}
+function env(script) {
+    return script.env ?? "development";
+}
+function json(status, requestId, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", "x-workbench-request-id": requestId },
+    });
+}
+function anthropicError(status, requestId, code, message, extra = {}) {
+    const type = status === 401 ? "authentication_error" : status === 403 ? "permission_error" : status === 429 ? "rate_limit_error" : status >= 500 ? "api_error" : "invalid_request_error";
+    return json(status, requestId, { type: "error", error: { type, message, workbench_code: code, request_id: requestId, ...extra } });
+}
+/** The Anthropic event sequence for one text block, then the Gateway's `workbench.usage`. */
+function sse(requestId, message, meta) {
+    const events = [];
+    events.push(["message_start", { type: "message_start", message: { ...message, content: [], stop_reason: null, usage: { ...message.usage, output_tokens: 0 } } }]);
+    message.content.forEach((block, i) => {
+        events.push(["content_block_start", { type: "content_block_start", index: i, content_block: { type: "text", text: "", citations: null } }]);
+        // Two deltas per block, so a consumer sees more than one event.
+        const half = Math.ceil(block.text.length / 2);
+        for (const part of [block.text.slice(0, half), block.text.slice(half)]) {
+            events.push(["content_block_delta", { type: "content_block_delta", index: i, delta: { type: "text_delta", text: part } }]);
+        }
+        events.push(["content_block_stop", { type: "content_block_stop", index: i }]);
+    });
+    events.push([
+        "message_delta",
+        {
+            type: "message_delta",
+            delta: { stop_reason: message["stop_reason"], stop_sequence: null, stop_details: message["stop_details"] },
+            usage: { output_tokens: message.usage["output_tokens"] },
+        },
+    ]);
+    events.push(["message_stop", { type: "message_stop" }]);
+    events.push(["workbench.usage", meta]);
+    const text = events.map(([e, d]) => `event: ${e}\ndata: ${JSON.stringify(d)}\n\n`).join("");
+    return new Response(text, {
+        status: 200,
+        headers: { "content-type": "text/event-stream", "x-workbench-request-id": requestId },
+    });
+}

package/dist/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { Provenance, StructuredResult, SystemBlock, TextResult } from "./types.ts";
+/**
+ * A system prompt with its stable part cached and the volatile parts after the
+ * breakpoint, so they never invalidate the cache (lifted from Imprint's
+ * `cachedSystem`). Empty volatile parts are dropped.
+ */
+export declare function cachedSystem(stable: string, ...volatile: string[]): SystemBlock[];
+/** Text blocks with a cache breakpoint on the last one (Imprint's `cachedBlocks`). */
+export declare function cachedBlocks(...texts: string[]): SystemBlock[];
+/** The record to store with any output kept: resolved model, request id, prompt version, cost (audit F17). */
+export declare function provenance(result: TextResult | StructuredResult<unknown>, promptVersion: string): Provenance;

package/dist/helpers.js

@@ -0,0 +1,23 @@
+/**
+ * A system prompt with its stable part cached and the volatile parts after the
+ * breakpoint, so they never invalidate the cache (lifted from Imprint's
+ * `cachedSystem`). Empty volatile parts are dropped.
+ */
+export function cachedSystem(stable, ...volatile) {
+    return [
+        { type: "text", text: stable, cache_control: { type: "ephemeral" } },
+        ...volatile.filter((v) => v !== "").map((text) => ({ type: "text", text })),
+    ];
+}
+/** Text blocks with a cache breakpoint on the last one (Imprint's `cachedBlocks`). */
+export function cachedBlocks(...texts) {
+    const blocks = texts.filter((t) => t !== "").map((text) => ({ type: "text", text }));
+    const last = blocks[blocks.length - 1];
+    if (last)
+        last.cache_control = { type: "ephemeral" };
+    return blocks;
+}
+/** The record to store with any output kept: resolved model, request id, prompt version, cost (audit F17). */
+export function provenance(result, promptVersion) {
+    return { model: result.model, requestId: result.requestId, promptVersion, costUsd: result.costUsd };
+}

package/dist/http.d.ts

@@ -0,0 +1,23 @@
+import type { WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+export interface GatewayTarget {
+    url: string;
+    key: string;
+    env: WorkbenchEnv;
+    fetch: typeof fetch;
+}
+export interface GatewayCall {
+    method?: "GET" | "POST";
+    /** X-Workbench-Job; required by every metered endpoint. */
+    job?: string;
+    /** Sent as JSON. */
+    body?: unknown;
+    accept?: string;
+    headers?: Record<string, string>;
+}
+export interface GatewayResponse {
+    response: Response;
+    /** The Gateway's X-Workbench-Request-Id. */
+    requestId: string | undefined;
+}
+/** Calls `path` on the Gateway; resolves only on a 2xx, otherwise throws the coded error. */
+export declare function gatewayFetch(target: GatewayTarget, path: string, call?: GatewayCall): Promise<GatewayResponse>;

package/dist/http.js

@@ -0,0 +1,33 @@
+// Plain HTTPS calls to the Gateway's own /v1/* endpoints (usage, and the
+// images endpoints from step 4.8). /anthropic/* goes through the official SDK
+// instead. Errors become WorkbenchAiError with the Gateway's code.
+import { REQUEST_ID_HEADER } from "./capture.js";
+import { errorFromGateway, WorkbenchAiError } from "./errors.js";
+/** Calls `path` on the Gateway; resolves only on a 2xx, otherwise throws the coded error. */
+export async function gatewayFetch(target, path, call = {}) {
+    const headers = {
+        Authorization: `Bearer ${target.key}`,
+        "X-Workbench-Env": target.env,
+        Accept: call.accept ?? "application/json",
+        ...(call.job !== undefined ? { "X-Workbench-Job": call.job } : {}),
+        ...(call.body !== undefined ? { "Content-Type": "application/json" } : {}),
+        ...call.headers,
+    };
+    let response;
+    try {
+        response = await target.fetch(`${target.url}${path}`, {
+            method: call.method ?? (call.body !== undefined ? "POST" : "GET"),
+            headers,
+            ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+        });
+    }
+    catch {
+        throw new WorkbenchAiError("network", "Couldn't reach the Gateway");
+    }
+    const requestId = response.headers.get(REQUEST_ID_HEADER) ?? undefined;
+    if (!response.ok) {
+        const body = await response.json().catch(() => undefined);
+        throw errorFromGateway(response.status, body, requestId);
+    }
+    return { response, requestId };
+}

package/dist/images.d.ts

@@ -0,0 +1,4 @@
+import { type GatewayTarget } from "./http.ts";
+import type { AiImages, AspectRatio } from "./types.ts";
+export declare const ASPECT_RATIOS: readonly AspectRatio[];
+export declare function createImages(target: GatewayTarget): AiImages;

package/dist/images.js

@@ -0,0 +1,93 @@
+// ai.images: image generation and image search through the Gateway's
+// /v1/images/* endpoints (docs/spec.md §2.3, §3). Plain HTTPS through
+// gatewayFetch; errors keep the Gateway's codes as WorkbenchAiError.
+import { WorkbenchAiError } from "./errors.js";
+import { gatewayFetch } from "./http.js";
+export const ASPECT_RATIOS = ["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"];
+const JOB = /^[a-z0-9._-]{1,64}$/;
+const SUBJECT = /^[a-z0-9_-]+:[^\s]{1,128}$/;
+function headers(req) {
+    if (!JOB.test(req.job))
+        throw new WorkbenchAiError("invalid_request", "job must match [a-z0-9._-]{1,64}");
+    const h = {};
+    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;
+}
+function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+function fromBase64(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+const str = (v) => (typeof v === "string" ? v : "");
+export function createImages(target) {
+    async function generate(req) {
+        if (!ASPECT_RATIOS.includes(req.aspectRatio)) {
+            throw new WorkbenchAiError("invalid_request", `aspectRatio must be one of ${ASPECT_RATIOS.join(" ")}`);
+        }
+        const { response, requestId } = await gatewayFetch(target, "/v1/images/generate", {
+            job: req.job,
+            headers: headers(req),
+            accept: "application/json",
+            body: {
+                prompt: req.prompt,
+                aspect_ratio: req.aspectRatio,
+                ...(req.model !== undefined ? { model: req.model } : {}),
+                ...(req.references?.length ? { references: req.references.map((r) => ({ mime_type: r.mimeType, data_base64: toBase64(r.bytes) })) } : {}),
+            },
+        });
+        const body = (await response.json().catch(() => null));
+        const data = str(body?.["data_base64"]);
+        if (!body || !data)
+            throw new WorkbenchAiError("upstream_error", "The Gateway returned no image", { ...(requestId ? { requestId } : {}) });
+        return {
+            bytes: fromBase64(data),
+            mimeType: str(body["mime_type"]) || "image/png",
+            model: str(body["model"]),
+            requestId: str(body["request_id"]) || requestId || "",
+            costUsd: num(body["cost_usd"]),
+        };
+    }
+    async function search(req) {
+        const { response, requestId } = await gatewayFetch(target, "/v1/images/search", {
+            job: req.job,
+            headers: headers(req),
+            body: {
+                q: req.q,
+                ...(req.num !== undefined ? { num: req.num } : {}),
+                ...(req.gl !== undefined ? { gl: req.gl } : {}),
+                ...(req.hl !== undefined ? { hl: req.hl } : {}),
+            },
+        });
+        const body = (await response.json().catch(() => null));
+        const results = (body?.results ?? []).map((r) => ({
+            title: str(r["title"]),
+            imageUrl: str(r["image_url"]),
+            thumbnailUrl: str(r["thumbnail_url"]),
+            width: num(r["width"]),
+            height: num(r["height"]),
+            source: str(r["source"]),
+            pageUrl: str(r["page_url"]),
+        }));
+        return Object.assign(results, {
+            requestId: str(body?.request_id) || requestId || "",
+            costUsd: num(body?.cost_usd),
+            credits: num(body?.credits),
+        });
+    }
+    return { generate, search };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createAi, missingRequired } from "./ai.ts";
+export { createFakeAi, fakeGateway, type FakeScript, type FakeReply, type FakeCall, type FakeAi } from "./fake.ts";
+export { cachedSystem, cachedBlocks, provenance } from "./helpers.ts";
+export { WorkbenchAiError, type AiErrorCode, type AiErrorDetails } from "./errors.ts";
+export { REQUEST_ID_HEADER, type GatewayMeta } from "./capture.ts";
+export { ASPECT_RATIOS } from "./images.ts";
+export type { Ai, AiImages, AiOptions, AspectRatio, GeneratedImage, ImageGenerateRequest, ImageSearchRequest, ImageSearchResult, ImageSearchResults, AiStream, BudgetStatus, ContentBlockParam, CountTokensRequest, Effort, MessageStreamEvent, Provenance, StructuredRequest, StructuredResult, SystemBlock, TextRequest, TextResult, Usage, ZodLike, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createAi, missingRequired } from "./ai.js";
+export { createFakeAi, fakeGateway } from "./fake.js";
+export { cachedSystem, cachedBlocks, provenance } from "./helpers.js";
+export { WorkbenchAiError } from "./errors.js";
+export { REQUEST_ID_HEADER } from "./capture.js";
+export { ASPECT_RATIOS } from "./images.js";

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+import type Anthropic from "@anthropic-ai/sdk";
+import type { WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+export type SystemBlock = Anthropic.TextBlockParam;
+export type ContentBlockParam = Anthropic.ContentBlockParam;
+export type MessageStreamEvent = Anthropic.MessageStreamEvent;
+export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+export interface AiOptions {
+    /** The project's Gateway key for this environment (`WORKBENCH_GATEWAY_KEY`). */
+    key: string;
+    /** From `workbenchEnv(env)`. Must match the key's environment. */
+    env: WorkbenchEnv;
+    /** Gateway base URL; defaults to `DEFAULT_GATEWAY_URL`. Leave unset outside tests. */
+    url?: string;
+    fetch?: typeof fetch;
+}
+export interface TextRequest {
+    /** A Workbench alias (`claude-default`, `claude-best`, `claude-fast`) or an allowlisted model id. */
+    model: string;
+    /** What the call is for, `[a-z0-9._-]{1,64}`, e.g. `article.write`. Recorded with usage. */
+    job: string;
+    system?: string | SystemBlock[];
+    prompt: string | ContentBlockParam[];
+    /** Defaults to 16000 (64000 for `stream`). */
+    maxTokens?: number;
+    effort?: Effort;
+    promptVersion?: string;
+    /** `type:id` of the thing the call is about. */
+    subject?: string;
+}
+export interface StructuredRequest<T> extends TextRequest {
+    /** A zod schema. Its JSON Schema is sent as `output_config.format`; the reply is validated against it. */
+    schema: ZodLike<T>;
+    /** Required fields the model may leave empty without a re-ask. */
+    mayLack?: string[];
+}
+/** The part of a zod 4 schema the package uses. */
+export interface ZodLike<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            message: string;
+        };
+    };
+}
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export interface TextResult {
+    text: string;
+    /** The resolved model id (never the alias). Store it with the output (audit F17). */
+    model: string;
+    /** The Gateway's `X-Workbench-Request-Id`; matches a `usage` row. */
+    requestId: string;
+    usage: Usage;
+    costUsd: number;
+}
+export interface StructuredResult<T> {
+    data: T;
+    model: string;
+    requestId: string;
+    usage: Usage;
+    costUsd: number;
+}
+export interface CountTokensRequest {
+    model: string;
+    job: string;
+    system?: string | SystemBlock[];
+    prompt: string | ContentBlockParam[];
+}
+export interface BudgetStatus {
+    /** `ok` below the warning level, `warn` at or above it, `reached` at or above the cap. */
+    status: "ok" | "warn" | "reached";
+    /** Dollars left this month (never negative). */
+    leftUsd: number;
+    monthlyUsd: number;
+    spentUsd: number;
+    mode: "enforce" | "shadow";
+    /** `YYYY-MM`, UTC. */
+    month: string;
+}
+export interface AiStream extends AsyncIterable<MessageStreamEvent> {
+    /** Resolves once the stream ends; throws `refused` or `truncated` like `text`. */
+    finalMessage(): Promise<TextResult>;
+}
+export interface Ai {
+    /** The official SDK client pointed at the Gateway, for anything the helpers don't cover. */
+    readonly anthropic: Anthropic;
+    text(req: TextRequest): Promise<TextResult>;
+    structured<T>(req: StructuredRequest<T>): Promise<StructuredResult<T>>;
+    stream(req: TextRequest): AiStream;
+    countTokens(req: CountTokensRequest): Promise<{
+        inputTokens: number;
+    }>;
+    /** Budget status for this key's project and environment, cached 60 s. Throws if the environment has no budget. */
+    budget(): Promise<BudgetStatus>;
+    /** Image generation and image search (step 4.8). The key needs the images or search scope. */
+    readonly images: AiImages;
+}
+export type AspectRatio = "1:1" | "3:2" | "2:3" | "4:3" | "3:4" | "16:9" | "9:16";
+export interface ImageGenerateRequest {
+    prompt: string;
+    aspectRatio: AspectRatio;
+    job: string;
+    /** An image alias: `image-default` (the default), `image-pro` or `image-openai`. */
+    model?: string;
+    /** Google aliases only; an OpenAI alias refuses them with `invalid_request`. */
+    references?: {
+        bytes: Uint8Array;
+        mimeType: string;
+    }[];
+    promptVersion?: string;
+    subject?: string;
+}
+export interface GeneratedImage {
+    bytes: Uint8Array;
+    /** `image/png` or `image/jpeg`. */
+    mimeType: string;
+    /** The resolved model id. Store it with the image (audit F17). */
+    model: string;
+    requestId: string;
+    costUsd: number;
+}
+export interface ImageSearchRequest {
+    q: string;
+    job: string;
+    /** 1 to 100; the Gateway's default is 10. More than 10 costs 2 credits. */
+    num?: number;
+    /** Country, e.g. `ph`. */
+    gl?: string;
+    /** Language, e.g. `en`. */
+    hl?: string;
+    subject?: string;
+}
+export interface ImageSearchResult {
+    title: string;
+    imageUrl: string;
+    thumbnailUrl: string;
+    width: number;
+    height: number;
+    /** The site's name. */
+    source: string;
+    /** The page the image is on; empty if Serper gave none. */
+    pageUrl: string;
+}
+/** The results, plus what the search cost. */
+export interface ImageSearchResults extends Array<ImageSearchResult> {
+    requestId: string;
+    costUsd: number;
+    credits: number;
+}
+export interface AiImages {
+    generate(req: ImageGenerateRequest): Promise<GeneratedImage>;
+    search(req: ImageSearchRequest): Promise<ImageSearchResults>;
+}
+export interface Provenance {
+    model: string;
+    requestId: string;
+    promptVersion: string;
+    costUsd: number;
+}