@a-dray/aglib 0.1.0

package/dist/model/adapters/openai-compatible/index.js

@@ -0,0 +1,226 @@
+import { err, ok } from "../../../result.js";
+import { textOf } from "../../../content.js";
+/**
+ * The OpenAI chat-completions wire, which almost every provider now speaks —
+ * OpenRouter, Together, Groq, vLLM, Ollama. One adapter, one base URL.
+ */
+export function createOpenAiCompatibleModel(options) {
+    const call = options.fetch ?? fetch;
+    return {
+        id: `openai-compatible:${options.model}`,
+        async *generate(request) {
+            let response;
+            try {
+                response = await call(`${options.baseUrl}/chat/completions`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${options.apiKey}`,
+                        ...options.headers,
+                    },
+                    body: JSON.stringify({
+                        model: options.model,
+                        messages: request.messages.map(encodeMessage),
+                        ...(request.tools?.length ? { tools: request.tools.map(encodeTool) } : {}),
+                        ...(request.maxOutputTokens !== undefined ? { max_tokens: request.maxOutputTokens } : {}),
+                        ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+                        ...encodeEffort(request.effort, options.effortParameter ?? "reasoning_effort"),
+                        stream: true,
+                        stream_options: { include_usage: true },
+                    }),
+                    ...(request.signal ? { signal: request.signal } : {}),
+                });
+            }
+            catch (error) {
+                return err(transportError(error, request.signal));
+            }
+            if (!response.ok)
+                return err(await httpError(response));
+            if (!response.body)
+                return err({ code: "provider", message: "No response body", retryable: true });
+            const text = [];
+            const calls = new Map();
+            let finish = "stop";
+            let usage = {};
+            let model;
+            // A stream that dies mid-body — cancelled, dropped, truncated — must come
+            // back as a typed failure like any other. Without this the generator throws,
+            // `run.result` rejects instead of resolving `cancelled`, no `run.finished`
+            // is ever committed, and the activation stays open until its claim expires.
+            try {
+                for await (const event of sseLines(response.body)) {
+                    if (event === "[DONE]")
+                        break;
+                    let frame;
+                    try {
+                        frame = JSON.parse(event);
+                    }
+                    catch {
+                        continue;
+                    }
+                    model ??= frame.model;
+                    if (frame.usage)
+                        usage = decodeUsage(frame.usage);
+                    const choice = frame.choices?.[0];
+                    if (!choice)
+                        continue;
+                    if (choice.finish_reason)
+                        finish = decodeFinish(choice.finish_reason);
+                    const content = choice.delta?.content;
+                    if (content) {
+                        text.push(content);
+                        yield { type: "text.delta", text: content };
+                    }
+                    const reasoning = choice.delta?.reasoning;
+                    if (reasoning)
+                        yield { type: "reasoning.delta", text: reasoning };
+                    for (const fragment of choice.delta?.tool_calls ?? []) {
+                        // Providers stream tool arguments in fragments, keyed by position;
+                        // only the first fragment carries the id and the name.
+                        const existing = calls.get(fragment.index) ?? {
+                            callId: fragment.id ?? `call_${fragment.index}`,
+                            name: fragment.function?.name ?? "",
+                            arguments: "",
+                        };
+                        if (fragment.id)
+                            existing.callId = fragment.id;
+                        if (fragment.function?.name)
+                            existing.name = fragment.function.name;
+                        if (fragment.function?.arguments) {
+                            existing.arguments += fragment.function.arguments;
+                            yield { type: "tool-call.delta", callId: existing.callId, arguments: fragment.function.arguments };
+                        }
+                        calls.set(fragment.index, existing);
+                    }
+                }
+            }
+            catch (error) {
+                return err(transportError(error, request.signal));
+            }
+            const collected = [...calls.values()]
+                .map((call) => ({ callId: call.callId, name: call.name, arguments: call.arguments || "{}" }));
+            return ok({
+                message: { content: text.join(""), ...(collected.length ? { calls: collected } : {}) },
+                finishReason: collected.length && finish === "stop" ? "tool-calls" : finish,
+                usage,
+                ...(model ? { model } : {}),
+            });
+        },
+    };
+}
+/** OpenRouter is this wire with a fixed base URL and attribution headers. */
+export function createOpenRouterModel(input) {
+    return createOpenAiCompatibleModel({
+        apiKey: input.apiKey,
+        baseUrl: "https://openrouter.ai/api/v1",
+        model: input.model,
+        effortParameter: "reasoning",
+        headers: {
+            ...(input.appUrl ? { "http-referer": input.appUrl } : {}),
+            ...(input.appName ? { "x-title": input.appName } : {}),
+        },
+        ...(input.fetch ? { fetch: input.fetch } : {}),
+    });
+}
+function encodeEffort(effort, parameter) {
+    if (!effort || parameter === "none")
+        return {};
+    return parameter === "reasoning" ? { reasoning: { effort } } : { reasoning_effort: effort };
+}
+function encodeMessage(message) {
+    if (message.role === "tool") {
+        return { role: "tool", tool_call_id: message.callId, content: textOf(message.content) };
+    }
+    if (message.role === "assistant") {
+        return {
+            role: "assistant",
+            content: textOf(message.content) || null,
+            ...(message.calls?.length
+                ? {
+                    tool_calls: message.calls.map((call) => ({
+                        id: call.callId, type: "function",
+                        function: { name: call.name, arguments: call.arguments },
+                    })),
+                }
+                : {}),
+        };
+    }
+    return { role: message.role, content: encodeContent(message.content) };
+}
+function encodeContent(content) {
+    if (typeof content === "string")
+        return content;
+    const parts = [];
+    for (const part of content) {
+        if (part.type === "text") {
+            parts.push({ type: "text", text: part.text });
+            continue;
+        }
+        if (part.type === "image") {
+            const url = part.source.kind === "url" ? part.source.url : `data:${part.mediaType};base64,${part.source.data}`;
+            parts.push({ type: "image_url", image_url: { url } });
+        }
+        // Files and opaque blocks have no place on this wire. Dropping them beats
+        // stringifying them into something the model would read as prose.
+    }
+    const only = parts.length === 1 ? parts[0] : undefined;
+    return only?.type === "text" ? only.text : parts;
+}
+const encodeTool = (tool) => ({
+    type: "function",
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+});
+const decodeFinish = (reason) => reason === "tool_calls" ? "tool-calls"
+    : reason === "length" ? "length"
+        : reason === "content_filter" ? "refusal"
+            : "stop";
+const decodeUsage = (usage) => ({
+    // Carried, not computed. A router picks an upstream provider per request and
+    // adds its own margin, so what it charged is a thing only it can say — and
+    // the frame carrying it is the one this adapter already reads.
+    ...(typeof usage.cost === "number" ? { costUsd: usage.cost } : {}),
+    // `prompt_tokens` is the whole prompt and `cached_tokens` is counted inside
+    // it — "cached tokens present in the prompt". `Usage` keeps the three input
+    // counts disjoint, so the cached part comes out here rather than every
+    // caller having to know which wire produced the number it is holding.
+    ...(usage.prompt_tokens !== undefined
+        ? { inputTokens: Math.max(usage.prompt_tokens - (usage.prompt_tokens_details?.cached_tokens ?? 0), 0) } : {}),
+    ...(usage.completion_tokens !== undefined ? { outputTokens: usage.completion_tokens } : {}),
+    ...(usage.prompt_tokens_details?.cached_tokens !== undefined
+        ? { cacheReadTokens: usage.prompt_tokens_details.cached_tokens } : {}),
+});
+async function httpError(response) {
+    const body = await response.text().catch(() => "");
+    const code = response.status === 401 || response.status === 403 ? "auth"
+        : response.status === 429 ? "rate-limit"
+            : response.status === 400 && /context|token/i.test(body) ? "context-length"
+                : response.status >= 500 ? "provider"
+                    : "failed";
+    return {
+        code,
+        message: `${response.status} ${response.statusText}${body ? `: ${body.slice(0, 400)}` : ""}`,
+        retryable: code === "rate-limit" || code === "provider",
+    };
+}
+function transportError(error, signal) {
+    if (signal?.aborted)
+        return { code: "cancelled", message: "Generation cancelled", retryable: false };
+    return { code: "provider", message: error instanceof Error ? error.message : String(error), retryable: true };
+}
+/** Server-sent events, reassembled across chunk boundaries. */
+async function* sseLines(body) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            if (line.startsWith("data:"))
+                yield line.slice(5).trim();
+            newline = buffer.indexOf("\n");
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/model/adapters/openai-compatible/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/model/adapters/openai-compatible/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ContentPart, Message, Model, ModelDelta, ModelError, ModelRequest, ModelResponse, ToolCall, ToolSpec, Usage,\n} from \"../../model.js\";\nimport { err, ok, type Result } from \"../../../result.js\";\nimport { textOf } from \"../../../content.js\";\n\nexport interface OpenAiCompatibleOptions {\n  apiKey: string;\n  baseUrl: string;\n  model: string;\n  headers?: Readonly<Record<string, string>>;\n  /**\n   * How this endpoint spells reasoning effort. OpenAI takes `reasoning_effort`;\n   * OpenRouter takes `reasoning: { effort }` and forwards it to whoever is\n   * serving the model. Sending both is not compatibility — OpenAI rejects the\n   * request outright — so the dialect is declared rather than guessed.\n   */\n  effortParameter?: \"reasoning_effort\" | \"reasoning\" | \"none\";\n  /** Injectable for tests; defaults to global fetch. */\n  fetch?: typeof fetch;\n}\n\n/**\n * The OpenAI chat-completions wire, which almost every provider now speaks —\n * OpenRouter, Together, Groq, vLLM, Ollama. One adapter, one base URL.\n */\nexport function createOpenAiCompatibleModel(options: OpenAiCompatibleOptions): Model {\n  const call = options.fetch ?? fetch;\n  return {\n    id: `openai-compatible:${options.model}`,\n\n    async *generate(request: ModelRequest): AsyncGenerator<ModelDelta, Result<ModelResponse, ModelError>> {\n      let response: Response;\n      try {\n        response = await call(`${options.baseUrl}/chat/completions`, {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            authorization: `Bearer ${options.apiKey}`,\n            ...options.headers,\n          },\n          body: JSON.stringify({\n            model: options.model,\n            messages: request.messages.map(encodeMessage),\n            ...(request.tools?.length ? { tools: request.tools.map(encodeTool) } : {}),\n            ...(request.maxOutputTokens !== undefined ? { max_tokens: request.maxOutputTokens } : {}),\n            ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),\n            ...encodeEffort(request.effort, options.effortParameter ?? \"reasoning_effort\"),\n            stream: true,\n            stream_options: { include_usage: true },\n          }),\n          ...(request.signal ? { signal: request.signal } : {}),\n        });\n      } catch (error) {\n        return err(transportError(error, request.signal));\n      }\n\n      if (!response.ok) return err(await httpError(response));\n      if (!response.body) return err({ code: \"provider\", message: \"No response body\", retryable: true });\n\n      const text: string[] = [];\n      const calls = new Map<number, { callId: string; name: string; arguments: string }>();\n      let finish: ModelResponse[\"finishReason\"] = \"stop\";\n      let usage: Usage = {};\n      let model: string | undefined;\n\n      // A stream that dies mid-body — cancelled, dropped, truncated — must come\n      // back as a typed failure like any other. Without this the generator throws,\n      // `run.result` rejects instead of resolving `cancelled`, no `run.finished`\n      // is ever committed, and the activation stays open until its claim expires.\n      try {\n        for await (const event of sseLines(response.body)) {\n          if (event === \"[DONE]\") break;\n          let frame: ChatFrame;\n          try { frame = JSON.parse(event) as ChatFrame; } catch { continue; }\n          model ??= frame.model;\n          if (frame.usage) usage = decodeUsage(frame.usage);\n\n          const choice = frame.choices?.[0];\n          if (!choice) continue;\n          if (choice.finish_reason) finish = decodeFinish(choice.finish_reason);\n\n          const content = choice.delta?.content;\n          if (content) { text.push(content); yield { type: \"text.delta\", text: content }; }\n\n          const reasoning = choice.delta?.reasoning;\n          if (reasoning) yield { type: \"reasoning.delta\", text: reasoning };\n\n          for (const fragment of choice.delta?.tool_calls ?? []) {\n            // Providers stream tool arguments in fragments, keyed by position;\n            // only the first fragment carries the id and the name.\n            const existing = calls.get(fragment.index) ?? {\n              callId: fragment.id ?? `call_${fragment.index}`,\n              name: fragment.function?.name ?? \"\",\n              arguments: \"\",\n            };\n            if (fragment.id) existing.callId = fragment.id;\n            if (fragment.function?.name) existing.name = fragment.function.name;\n            if (fragment.function?.arguments) {\n              existing.arguments += fragment.function.arguments;\n              yield { type: \"tool-call.delta\", callId: existing.callId, arguments: fragment.function.arguments };\n            }\n            calls.set(fragment.index, existing);\n          }\n        }\n      } catch (error) {\n        return err(transportError(error, request.signal));\n      }\n\n      const collected: ToolCall[] = [...calls.values()]\n        .map((call) => ({ callId: call.callId, name: call.name, arguments: call.arguments || \"{}\" }));\n\n      return ok({\n        message: { content: text.join(\"\"), ...(collected.length ? { calls: collected } : {}) },\n        finishReason: collected.length && finish === \"stop\" ? \"tool-calls\" : finish,\n        usage,\n        ...(model ? { model } : {}),\n      });\n    },\n  };\n}\n\n/** OpenRouter is this wire with a fixed base URL and attribution headers. */\nexport function createOpenRouterModel(input: {\n  apiKey: string; model: string; appUrl?: string; appName?: string; fetch?: typeof fetch;\n}): Model {\n  return createOpenAiCompatibleModel({\n    apiKey: input.apiKey,\n    baseUrl: \"https://openrouter.ai/api/v1\",\n    model: input.model,\n    effortParameter: \"reasoning\",\n    headers: {\n      ...(input.appUrl ? { \"http-referer\": input.appUrl } : {}),\n      ...(input.appName ? { \"x-title\": input.appName } : {}),\n    },\n    ...(input.fetch ? { fetch: input.fetch } : {}),\n  });\n}\n\nfunction encodeEffort(\n  effort: ModelRequest[\"effort\"],\n  parameter: \"reasoning_effort\" | \"reasoning\" | \"none\",\n): Record<string, unknown> {\n  if (!effort || parameter === \"none\") return {};\n  return parameter === \"reasoning\" ? { reasoning: { effort } } : { reasoning_effort: effort };\n}\n\nfunction encodeMessage(message: Message): Record<string, unknown> {\n  if (message.role === \"tool\") {\n    return { role: \"tool\", tool_call_id: message.callId, content: textOf(message.content) };\n  }\n  if (message.role === \"assistant\") {\n    return {\n      role: \"assistant\",\n      content: textOf(message.content) || null,\n      ...(message.calls?.length\n        ? {\n            tool_calls: message.calls.map((call) => ({\n              id: call.callId, type: \"function\",\n              function: { name: call.name, arguments: call.arguments },\n            })),\n          }\n        : {}),\n    };\n  }\n  return { role: message.role, content: encodeContent(message.content) };\n}\n\nfunction encodeContent(content: Message[\"content\"]): unknown {\n  if (typeof content === \"string\") return content;\n  const parts: Record<string, unknown>[] = [];\n  for (const part of content as readonly ContentPart[]) {\n    if (part.type === \"text\") { parts.push({ type: \"text\", text: part.text }); continue; }\n    if (part.type === \"image\") {\n      const url = part.source.kind === \"url\" ? part.source.url : `data:${part.mediaType};base64,${part.source.data}`;\n      parts.push({ type: \"image_url\", image_url: { url } });\n    }\n    // Files and opaque blocks have no place on this wire. Dropping them beats\n    // stringifying them into something the model would read as prose.\n  }\n  const only = parts.length === 1 ? parts[0] : undefined;\n  return only?.type === \"text\" ? only.text : parts;\n}\n\nconst encodeTool = (tool: ToolSpec) => ({\n  type: \"function\",\n  function: { name: tool.name, description: tool.description, parameters: tool.parameters },\n});\n\nconst decodeFinish = (reason: string): ModelResponse[\"finishReason\"] =>\n  reason === \"tool_calls\" ? \"tool-calls\"\n  : reason === \"length\" ? \"length\"\n  : reason === \"content_filter\" ? \"refusal\"\n  : \"stop\";\n\nconst decodeUsage = (usage: ChatUsage): Usage => ({\n  // Carried, not computed. A router picks an upstream provider per request and\n  // adds its own margin, so what it charged is a thing only it can say — and\n  // the frame carrying it is the one this adapter already reads.\n  ...(typeof usage.cost === \"number\" ? { costUsd: usage.cost } : {}),\n  // `prompt_tokens` is the whole prompt and `cached_tokens` is counted inside\n  // it — \"cached tokens present in the prompt\". `Usage` keeps the three input\n  // counts disjoint, so the cached part comes out here rather than every\n  // caller having to know which wire produced the number it is holding.\n  ...(usage.prompt_tokens !== undefined\n    ? { inputTokens: Math.max(usage.prompt_tokens - (usage.prompt_tokens_details?.cached_tokens ?? 0), 0) } : {}),\n  ...(usage.completion_tokens !== undefined ? { outputTokens: usage.completion_tokens } : {}),\n  ...(usage.prompt_tokens_details?.cached_tokens !== undefined\n    ? { cacheReadTokens: usage.prompt_tokens_details.cached_tokens } : {}),\n});\n\nasync function httpError(response: Response): Promise<ModelError> {\n  const body = await response.text().catch(() => \"\");\n  const code: ModelError[\"code\"] =\n    response.status === 401 || response.status === 403 ? \"auth\"\n    : response.status === 429 ? \"rate-limit\"\n    : response.status === 400 && /context|token/i.test(body) ? \"context-length\"\n    : response.status >= 500 ? \"provider\"\n    : \"failed\";\n  return {\n    code,\n    message: `${response.status} ${response.statusText}${body ? `: ${body.slice(0, 400)}` : \"\"}`,\n    retryable: code === \"rate-limit\" || code === \"provider\",\n  };\n}\n\nfunction transportError(error: unknown, signal?: AbortSignal): ModelError {\n  if (signal?.aborted) return { code: \"cancelled\", message: \"Generation cancelled\", retryable: false };\n  return { code: \"provider\", message: error instanceof Error ? error.message : String(error), retryable: true };\n}\n\n/** Server-sent events, reassembled across chunk boundaries. */\nasync function* sseLines(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n  for await (const chunk of body as unknown as AsyncIterable<Uint8Array>) {\n    buffer += decoder.decode(chunk, { stream: true });\n    let newline = buffer.indexOf(\"\\n\");\n    while (newline >= 0) {\n      const line = buffer.slice(0, newline).trim();\n      buffer = buffer.slice(newline + 1);\n      if (line.startsWith(\"data:\")) yield line.slice(5).trim();\n      newline = buffer.indexOf(\"\\n\");\n    }\n  }\n}\n\ninterface ChatUsage {\n  prompt_tokens?: number;\n  completion_tokens?: number;\n  prompt_tokens_details?: { cached_tokens?: number };\n  /**\n   * What this generation was charged. OpenRouter sets it on every response and\n   * calls it credits, whose base currency is US dollars; plain OpenAI and the\n   * self-hosted endpoints on this wire do not send it at all, so it is absent\n   * rather than zero there.\n   */\n  cost?: number;\n}\ninterface ChatFrame {\n  model?: string;\n  usage?: ChatUsage;\n  choices?: readonly {\n    finish_reason?: string | null;\n    delta?: {\n      content?: string;\n      reasoning?: string;\n      tool_calls?: readonly { index: number; id?: string; function?: { name?: string; arguments?: string } }[];\n    };\n  }[];\n}\n"]}

package/dist/model/conformance.d.ts

@@ -0,0 +1,210 @@
+/**
+ * What any implementation of the model port must do.
+ *
+ * The port is one method, and almost everything it promises is about the shape
+ * of an answer rather than its content: exactly one result and nothing after it,
+ * a cancellation that arrives as a value, deltas that add up to the message,
+ * tool arguments that parse, counts that stay absent when nobody reported them.
+ * Those are the promises a run recovers on — and every one of them is invisible
+ * to a test that only asks a model a question and reads the reply.
+ *
+ * So the suite cannot supply requests and expect responses: what a provider says
+ * is the provider's, and two of the three implementations here reach one. What
+ * a subject is asked for instead is a model **primed to say a scripted thing** —
+ * the script in the port's own vocabulary, rendered by the subject onto whatever
+ * it actually speaks, which for a wire is a stream of frames and for a fake is a
+ * scripted response. A case then drives that model and holds the answer to the
+ * port, without ever naming a provider's fields.
+ *
+ * The same trick runs the other way. An adapter that decodes a response
+ * perfectly and never transmits the caller's tools is useless, and that half of
+ * an adapter is pure encoding — which is why a wire also hands back a
+ * `SentRequest`: its own translation of what went out, back into the port's
+ * vocabulary. The alternative was to assert on the raw body, which would make
+ * every case provider-specific and so not a shared contract at all.
+ *
+ * One request per model. Nothing in this port is a conversation — a `Model` is a
+ * value you call — so a case wanting a second answer asks for a second model,
+ * and no subject has to decide what a spent script means.
+ *
+ * Inert on purpose. Each case is a name and a function that throws, so the suite
+ * drags no test framework into the package:
+ *
+ * ```ts
+ * for (const item of defineModelConformance(subject)) test(item.name, item.run);
+ * ```
+ */
+import type { Model, ToolCall, Usage } from "./model.js";
+import type { JsonValue } from "../json.js";
+/** One case: a name, and a function that throws when the contract is broken. */
+export interface ConformanceCase {
+    name: string;
+    run(): Promise<void>;
+}
+/**
+ * What the provider should say, in the port's vocabulary.
+ *
+ * A subject renders each of these onto whatever it speaks. Two rendering rules
+ * carry cases of their own, so they are stated here rather than assumed:
+ *
+ * - **Deltas arrive one at a time.** A subject that hands the whole body over at
+ *   once cannot be cancelled part way through, and the case that pulls one delta
+ *   and then gives up would prove nothing.
+ * - **A wire behaves as `fetch` does about the signal.** An already-aborted
+ *   request never reaches the provider, and a body dies when the caller gives
+ *   up. A transport that ignores the signal lets an adapter that never forwarded
+ *   it pass both cancellation cases.
+ */
+export type ModelScript = 
+/** An answer that arrives in pieces. */
+{
+    kind: "text";
+    deltas: readonly string[];
+}
+/** An answer the model thought about first, aloud. */
+ | {
+    kind: "reasoning";
+    thoughts: readonly string[];
+    text: string;
+}
+/** A turn that asks for tools, with each call's arguments fragmented on the way. */
+ | {
+    kind: "tool-calls";
+    calls: readonly ToolCall[];
+}
+/** An answer the provider cut off at the output ceiling, mid-sentence or mid-call. */
+ | {
+    kind: "truncated";
+    text: string;
+    calls?: readonly ToolCall[];
+}
+/** An answer the provider declined to give. */
+ | {
+    kind: "refused";
+}
+/** An answer reporting exactly these counts, from exactly this model. */
+ | {
+    kind: "usage";
+    usage: Usage;
+    model: string;
+}
+/** An answer that says nothing about counts or about which model served it. */
+ | {
+    kind: "silent";
+}
+/** The provider refusing the request outright. Wires only. */
+ | {
+    kind: "status";
+    status: number;
+    body: string;
+}
+/** A body that delivers this much and then dies. Wires only. */
+ | {
+    kind: "cut";
+    text: string;
+};
+/**
+ * What one outgoing request carried, translated back out of the wire's own
+ * vocabulary by the subject. Absence is meaningful: an empty `toolNames`
+ * asserts the request advertised no tools, and a missing `effort` asserts it
+ * carried no reasoning control at all.
+ */
+export interface SentRequest {
+    /**
+     * Every text the request transmitted for the model to read, in order —
+     * instructions first, then the conversation, wherever this wire puts them.
+     * One list rather than a field per role, because the roles are exactly what
+     * the wires disagree about: a tool result is a message on one and a block
+     * inside the previous user turn on another, and what an adapter owes is that
+     * the words arrive in the order they were said.
+     */
+    text: readonly string[];
+    /** The names of the tools the request advertised. */
+    toolNames: readonly string[];
+    /** The JSON Schema the request advertised for each advertised tool. */
+    toolSchemas: Readonly<Record<string, JsonValue>>;
+    /** Each tool result the request carried, paired with the call it answers. */
+    toolResults: readonly {
+        callId: string;
+        content: string;
+    }[];
+    /** Each tool call the request carried back, so the provider can pair the result with it. */
+    toolCalls: readonly ToolCall[];
+    /** Media types of the image and file content the request transmitted, in order. */
+    mediaTypes: readonly string[];
+    /** The output ceiling the request carried, or absent where it carried none. */
+    maxOutputTokens?: number;
+    /** The provider-native reasoning control the request carried, verbatim, or absent. */
+    effort?: JsonValue;
+    /** The sampling control the request carried, or absent. */
+    temperature?: number;
+    /** How many cache breakpoints the request marked. */
+    cacheMarks: number;
+}
+/** A model primed to answer one request, and — where there is a wire — that request. */
+export interface Answering {
+    model: Model;
+    /** What the one request this model was given actually carried. Wires only. */
+    sent?(): SentRequest;
+}
+/**
+ * What this implementation does with the three request options a provider may
+ * refuse, each of which the port says is honoured or honestly ignored.
+ *
+ * Declared rather than inferred from the request, because both answers look
+ * identical from outside and only one of them is a defect: dropping `temperature`
+ * is what the current Anthropic models require, and dropping it silently on a
+ * wire that would have accepted it is a caller's control going nowhere.
+ */
+export interface Wire {
+    /** Whether a level reaches the provider as its own depth control. */
+    effort: "sent" | "ignored";
+    /** Whether a sampling control reaches a provider that accepts one. */
+    temperature: "sent" | "ignored";
+    /** Whether `cacheAfter` reaches the provider as a breakpoint. */
+    cache: "sent" | "ignored";
+}
+export interface ModelUnderTest {
+    /**
+     * A model primed to answer one request with `script`.
+     *
+     * Called once per request, so nothing leaks between cases, and never with a
+     * script this subject's declarations say it cannot play.
+     */
+    answering(script: ModelScript): Answering | Promise<Answering>;
+    /**
+     * The transport under this implementation, where there is one the subject can
+     * script and read back.
+     *
+     * `"none"` is a claim about the implementation, not a way out of the cases: a
+     * model answering from something it already holds has no status to return, no
+     * body to cut in half and no request to report — and those are the cases a
+     * provider adapter most needs, so one that declares `"none"` is untested where
+     * it matters.
+     */
+    wire: Wire | "none";
+    /**
+     * Whether a tool call's arguments reach the caller as they arrive.
+     *
+     * Declared rather than inferred from an empty stream, because "streamed
+     * nothing" and "asked for no tools this turn" look the same from outside, and
+     * an application rendering a call as it is typed would find out in production.
+     */
+    toolArguments: "streamed" | "whole";
+    /** Whether this implementation can carry a model's reasoning back as deltas. */
+    reasoning: "streamed" | "none";
+    /**
+     * Whether this wire states what a generation cost.
+     *
+     * A router does — it picks an upstream provider per request and adds its own
+     * margin, so what it charged is a thing only it can say, and no rate table an
+     * application keeps can reconstruct it. Most wires do not, and there the
+     * field stays absent rather than being estimated from one.
+     *
+     * Declared both ways, because both are a promise: one that reports a cost has
+     * to carry it, and one that does not has to leave it alone rather than
+     * inventing a zero.
+     */
+    cost: "reported" | "none";
+}
+export declare function defineModelConformance(subject: ModelUnderTest): readonly ConformanceCase[];