@jxburros/ai-nugget 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jxburros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# AI Nugget
+
+`AI Nugget` is a small, zero-dependency, isomorphic TypeScript nugget for
+talking to AI model providers through one pipeline:
+
+```
+policy → key resolution → beforeCall hook → concurrency/retry → provider adapter → redacted telemetry
+```
+
+It runs identically in Node ≥ 20, the browser main thread, and Web Workers using
+only `fetch`, `ReadableStream`, `AbortController`, and `TextDecoder`. It is
+intentionally **not** a router, prompt library, memory system, or secrets vault:
+apps choose models, own prompts, store secrets, and decide what policy to enforce.
+The package is MIT licensed.
+
+See `design.md` for the full contract. The original evidence base, phased
+build/adoption plan, and dev handoff are archived under `docs/archive/`.
+
+## Install / use
+
+```ts
+import { AIHandler, envKeySource } from '@jxburros/ai-nugget';
+
+const handler = new AIHandler({ keySource: envKeySource() });
+
+// Non-streaming
+const result = await handler.chat(
+  { id: 'main', provider: 'openai', keyRef: { kind: 'env', name: 'OPENAI_API_KEY' } },
+  { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] },
+);
+console.log(result.text, result.usage, result.finishReason);
+
+// Streaming (works in Node route handlers, React, and Web Workers)
+for await (const event of handler.stream(conn, req)) {
+  if (event.type === 'delta') process.stdout.write(event.text);
+  if (event.type === 'done') console.log('\n', event.result.usage);
+}
+```
+
+Repos that cannot take a package dependency can vendor the generated `nugget/`
+folder (see below).
+
+## Providers
+
+Four **protocol engines** own the wire formats; a data-driven **profile table**
+turns each named provider into defaults + quirks on top of an engine, so adding
+an OpenAI-compatible provider is a table row, not another copy of the SSE loop.
+
+| Engine | Providers | Streaming | Tools | JSON mode |
+|---|---|---|---|---|
+| `openaiChat` | `openai`, `azure-openai`, `openrouter`, `groq`, `deepseek`, `mistral`, `together`, `fireworks`, `lmstudio`, `llamacpp`, `vllm`, `openai-compat` | SSE + `stream_options.include_usage` | `tools`/`tool_calls` deltas | `response_format` (`json_schema` where supported, otherwise `json_object`) |
+| `anthropic` | `anthropic` | SSE (`content_block_delta`) | `tool_use` blocks (streamed) | forced-tool JSON mode |
+| `google` | `google` | SSE (`streamGenerateContent`) | `functionDeclarations` | `responseMimeType` |
+| `ollama` | `ollama` | NDJSON | native `tools` | `format: json` |
+
+`adapterFor(provider)` lives once, in `adapters/index.ts`. Unknown provider keys
+with a `baseUrl` resolve to the `openai-compat` escape hatch. **Grok/xAI is not
+blocked and is never officially integrated** — point `openai-compat` at any
+endpoint if you must; that is your configuration, not a supported profile.
+
+Model identity is always `(source, model)` — `modelRef(source, model)` gives the
+canonical `provider/model` key so the same weights served by different hosts stay
+distinct and comparable.
+
+### Provider capabilities
+
+Beyond wire-format `quirks` (auth, URL templates, whether a stream reports
+usage), each profile also carries `capabilities` — the higher-level questions
+apps need answered before they pick behavior:
+
+```ts
+interface ProviderCapabilities {
+  nativeTools: boolean;   // reliable native tool/function-calling for this
+                          // provider's protocol (not just model-dependent)
+  jsonMode: boolean;      // a provider-enforced structured-output mode exists
+  local: boolean;         // runs on localhost / user-controlled infra
+  embeddable: boolean;    // meant to run as a local sidecar, not a hosted service
+}
+```
+
+Hosted cloud providers (`openai`, `azure-openai`, `openrouter`, `groq`,
+`deepseek`, `mistral`, `together`, `fireworks`, `anthropic`, `google`) ship
+`{ nativeTools: true, jsonMode: true, local: false, embeddable: false }`. Local
+runtimes (`lmstudio`, `llamacpp`, `vllm`, and the `openai-compat` escape hatch)
+ship the conservative `{ nativeTools: false, jsonMode: false, local: true,
+embeddable: true }`, since native tool support there is model-dependent, not
+protocol-guaranteed. `ollama` is the one exception with `jsonMode: true` —
+its `format: 'json'` is engine-enforced regardless of which model is loaded.
+These are per-provider defaults, not per-model guarantees: a caller that knows
+its specific loaded model better should configure behavior explicitly (e.g.
+`toolMode: 'native'`) rather than rely on the default.
+
+Access via `profileFor(provider, baseUrl).capabilities`.
+
+**These are provider-level defaults, not per-model guarantees.** A specific
+model behind a "hosted" provider can still lack reliable native tool-calling
+(and a specific local model behind a "local" provider can have it) — this
+matters most for OpenRouter, Ollama, LM Studio, vLLM, and any
+`openai-compat` endpoint, where the model actually loaded is opaque to the
+profile table. A caller that knows its model better should pass an explicit
+`toolMode` (agent layer) rather than rely on the capability default.
+
+**`listModels()` is optional per adapter — two engines never return anything.**
+`ProviderAdapter.listModels` is `?`-optional, and `AIHandler.listModels()`
+falls back to `[]` when an adapter doesn't implement it. Concretely: the
+`openaiChat` and `ollama` engines implement it (`GET /models` /
+`GET /api/tags`); the `anthropic` and `google` engines currently don't, so
+`handler.listModels()` for those providers always resolves to `[]`, not an
+error. This is easy to miss because `capabilities` doesn't surface it — an
+app building a model picker on top of `listModels()` should treat an empty
+result as "this provider doesn't support discovery," not "this provider has
+no models," and have a fallback (e.g. an app-configured default model per
+connection) ready for `anthropic`/`google` rather than showing an empty list.
+
+### Letting an app's users pick a model (best practice)
+
+The nugget deliberately has no concept of "the app's currently selected
+model" — that's app policy, same as governance (see Non-goals). The pattern
+that has worked well for apps building a model-picker UI on top of the
+AI Nugget handler:
+
+1. **Keep `provider`/`baseUrl` on a server-side allowlist; never take them
+   from client input.** A `Connection`'s `provider`/`baseUrl` decide where
+   the server's resolved API key gets sent (via `KeySource` → `applyAuth`);
+   letting a client control either directly is effectively letting it
+   redirect a real credential to an arbitrary endpoint (SSRF plus key
+   exposure). Define your app's available connections server-side (e.g. a
+   small config list, each with its own `KeyRef`), and only let the client
+   choose a `connectionId` out of that list.
+2. **`model` is fine as ordinary client input.** Unlike `provider`/`baseUrl`,
+   a bad or unexpected `model` string just comes back as a normal provider
+   error (unknown model) from `chat()`/`stream()` — there's no equivalent
+   security concern, so there's no need to allowlist it server-side beyond
+   what the provider itself enforces.
+3. **Use `handler.listModels(connection)` to populate the picker live**, and
+   fall back to an app-configured default model for connections whose engine
+   doesn't implement discovery (see above).
+
+See `examples/model-picker.mjs` for a minimal runnable reference implementing
+this pattern.
+
+## What's implemented
+
+- **Core:** message-based contracts (`types.ts`), typed `AIError` + `classify()`,
+  timeout/abort merging and SSE/NDJSON readers (`transport.ts`), defensive JSON
+  extraction with array support + schema guards (`json.ts`), token estimation with
+  an explicit `estimated` flag (`tokens.ts`).
+- **Adapters:** all four engines with streaming, native tool-calling, JSON modes,
+  `finishReason` mapping, buffered-`stream:true` fallback, first-token latency,
+  and usage normalization; the full v1 provider profile table. The
+  OpenAI-compatible engine only sends `stream_options: { include_usage: true }`
+  when the profile's `supportsUsageInStream` quirk confirms the server expects
+  it — local servers (llama.cpp, LM Studio, vLLM) that don't have the quirk set
+  never receive the option. The OpenAI and Azure OpenAI profiles send
+  `max_completion_tokens` for `maxTokens`; local/OpenAI-compatible profiles keep
+  `max_tokens` for compatibility. Google receives `responseSchema` for JSON mode
+  only when native tools are absent, avoiding Gemini's JSON-with-tools rejection.
+- **Pipeline (`AIHandler`):** policy → keys → `beforeCall` → concurrency/min-interval
+  → jittered retry (honoring `Retry-After`) → redacted `CallRecord` telemetry →
+  `afterCall`, with `chat`, `stream`, `listModels`, `testConnection`. Every call —
+  success, failure, or consumer-abandoned stream — produces one redacted telemetry
+  record. Retries stop once user-visible output has been emitted, and telemetry
+  or `afterCall` failures never re-execute an already-successful provider call.
+  `listModels()` and `testConnection()` use explicit operation IDs
+  (`__listModels__`, `__testConnection__`) so policy and telemetry can see those
+  key-bearing probes too.
+- **Seams:** `KeySource` (`env`/`literal`/`memory`/chain + ref parsing),
+  `Redactor` (default secret patterns + session-resolved key redaction),
+  neutral `GovernancePolicy` (`blocklistPolicy`/`allowlistPolicy`/`composePolicies`).
+  `allowlistPolicy` fails closed for providers omitted from the configured map;
+  use `'*'` in a provider's prefix list to allow non-chat operation IDs.
+  The default redactor covers common provider token formats and generic bearer
+  tokens, with session-resolved keys always added exactly.
+- **Agent layer (`@jxburros/ai-nugget/agent`):** `defineTool` + light JSON-schema
+  arg validation (object-ness, `required`, top-level `properties[key].type` —
+  not full JSON Schema: no `enum`, nested schemas, `oneOf`, bounds, `pattern`,
+  array `items`, or `additionalProperties`; validate again inside
+  `tool.execute` if you need stricter guarantees), `runAgent()` model↔tool loop
+  over the full handler pipeline,
+  streamed `AgentEvent`s, budgets (`maxSteps`/`maxTokens`/`deadlineMs`) with honest
+  `stopReason`s, `ApprovalGate` for side-effecting tools (deny is fed back to the
+  model as data), and `native` / `promptJson` / `auto` tool modes. `auto` (the
+  default) resolves per call from the connection's provider capability profile
+  (`profileFor(provider).capabilities.nativeTools`) — hosted providers get
+  `native`, local runtimes and the `openai-compat` escape hatch get
+  `promptJson`, and an explicit `toolMode` always overrides the default.
+  `promptJson` mode accepts a single `{"tool","input"}` directive or a batched
+  `{"tools":[…]}` (a bare array works too), so the model can request several
+  tools in one turn just like native tool-calling. Prompt-JSON history is
+  serialized as plain text turns, not provider-native tool-call wire format.
+
+```ts
+import { runAgent, defineTool } from '@jxburros/ai-nugget/agent';
+```
+
+## Commands
+
+```bash
+npm install
+npm test            # Vitest contract suite in Node (97 tests; live tests skipped unless env-gated)
+npm run test:browser   # same suite in headless Chromium (proves isomorphism)
+npm run build       # tsc → dist/ (also the typecheck)
+npm run build:nugget   # writes a vendorable nugget/ stamped with version + content hash
+```
+
+### Live smoke tests (optional, env-gated)
+
+`tests/live-smoke.test.ts` exercises the real wire path against a live provider.
+It is **skipped unless `AI_HANDLER_LIVE=1`**, so it never runs in the default
+suite or in CI:
+
+```bash
+# Local Ollama (defaults: provider=ollama, model=llama3.2)
+AI_HANDLER_LIVE=1 npm run test:live
+
+# A cloud provider, with JSON-mode and agent tool-loop checks enabled
+AI_HANDLER_LIVE=1 AI_HANDLER_LIVE_PROVIDER=openai AI_HANDLER_LIVE_MODEL=gpt-4o-mini \
+  AI_HANDLER_LIVE_KEY_ENV=OPENAI_API_KEY AI_HANDLER_LIVE_JSON=1 AI_HANDLER_LIVE_TOOLS=1 \
+  npm run test:live
+```
+
+Config env vars: `AI_HANDLER_LIVE_PROVIDER`, `AI_HANDLER_LIVE_MODEL`,
+`AI_HANDLER_LIVE_BASE_URL`, `AI_HANDLER_LIVE_KEY` (literal) or
+`AI_HANDLER_LIVE_KEY_ENV` (key from an env var), `AI_HANDLER_LIVE_JSON`,
+`AI_HANDLER_LIVE_TOOLS`.
+
+**Live provider matrix (`.github/workflows/live-matrix.yml`).** The default
+CI workflow only exercises mocked fetch responses, so subtle live-wire
+behavior differences (OpenAI, Anthropic, Google, OpenRouter, and local
+runtimes each drift independently) can't surface there. `live-matrix.yml`
+runs the same `tests/live-smoke.test.ts` suite against real endpoints —
+manually (`workflow_dispatch`) or on a weekly schedule — never on push/PR, so
+it can't block or flake a normal CI run. Each matrix entry reads its API key
+from a same-named repository secret (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`GOOGLE_API_KEY`, `OPENROUTER_API_KEY`) and skips itself with a notice if that
+secret isn't configured, so you only need to add secrets for the providers
+you actually use. Local runtimes (Ollama, llama.cpp, LM Studio, vLLM) aren't
+in the matrix since they need a reachable server; smoke-test those manually
+with the local `test:live` invocation above.
+
+## Distribution
+
+Three supported paths, in order of preference:
+
+1. **npm registry (primary).** `@jxburros/ai-nugget` publishes to
+   [npmjs.org](https://www.npmjs.com/package/@jxburros/ai-nugget) on every
+   published GitHub release (`.github/workflows/publish.yml`). Consumers install
+   from the normal npm registry:
+
+   ```bash
+   npm install @jxburros/ai-nugget@^0.3.1
+   ```
+
+   This is the default dependency path for apps: fix once here, bump the
+   dependency in each app, and let npm resolve it normally.
+2. **GitHub Packages (kept).** The same release workflow also publishes
+   `@jxburros/ai-nugget` to GitHub Packages for GitHub-native workflows and
+   existing portfolio consumers that already point at that registry. Those apps
+   add a project `.npmrc`:
+
+   ```
+   @jxburros:registry=https://npm.pkg.github.com
+   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+   ```
+
+   (GitHub Packages requires an authenticated token even for public-repo
+   packages.) Then `npm install @jxburros/ai-nugget@^0.3.1`.
+3. **Vendored `nugget/` (fallback).** `nugget/` is a generated single-folder
+   build (`src/` + `VERSION.txt` with a version + content-hash stamp) for repos
+   that cannot take a package dependency. Copy it in; `VERSION.txt` makes drift
+   from the source of truth detectable. (Bundlers that don't resolve
+   `.ts`+`.js`-suffixed imports the way `tsc` does — e.g. Turbopack — should
+   vendor `dist/` instead; see below.)
+
+`dist/` (ESM + `.d.ts`) is the package's own build output. `dist/` and
+`nugget/` are both committed and regenerated from `src/`; `prepublishOnly`
+rebuilds both, and CI fails if either is stale.
+
+**Bundler compatibility for the vendored `nugget/` path.** `nugget/src/*.ts`
+uses NodeNext-style relative imports with explicit `.js` extensions (e.g.
+`export * from './types.js'`), which `tsc` needs to resolve `.ts` files under
+`moduleResolution: bundler`/`nodenext`. Not every bundler's runtime module
+graph treats `.ts`/`.js` as interchangeable the way `tsc` does — confirmed
+with Next.js 16's Turbopack: aliasing straight at `nugget/src/index.ts`
+type-checks but fails to resolve at build/dev time (`Module not found: Can't
+resolve './types.js'`), and aliasing at the compiled `dist/index.d.ts` builds
+but silently resolves some named exports to `undefined` at runtime. If your
+bundler hits this, vendor `dist/` (real `.js` + `.d.ts` pairs) instead of
+`nugget/`, and point path aliases at its `.js` entry points (e.g.
+`dist/index.js`, `dist/agent/index.js`) — TypeScript picks up the sibling
+`.d.ts` automatically.
+
+## Examples
+
+`examples/` has runnable scripts against local Ollama and llama.cpp servers,
+`promptJson` vs. native tool-calling, an `ApprovalGate`, and telemetry — see
+`examples/README.md`.
+
+## Agent skills
+
+`.claude/skills/` contains Agent Skills — task-specific guides that Claude Code
+picks up automatically and that any AI agent (or human) can read as plain
+Markdown: `use-ai-nugget` (integrating the nugget into an app),
+`build-agent-loop` (the agent/tool-calling layer), `add-provider` (extending
+the provider profile table), and `develop-nugget` (invariants and validation
+for changes to this repo). `AGENTS.md` remains the always-on baseline; the
+skills carry the per-task detail.
+
+## Non-goals
+
+Not a full agent framework (no planning/memory/RAG/multi-agent — the loop
+consumes `messages` and stops there), not a router/recommender (apps choose
+models; the handler exposes a `route`/`context` event so apps can report what they
+chose), not a secrets vault (`KeySource` is a seam), and not a UI. The governance
+seam ships neutral: it is where an app *can* enforce rules, not a place the
+library imposes its own.

package/dist/adapters/engines/anthropic.d.ts

@@ -0,0 +1,8 @@
+import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+export declare class AnthropicAdapter implements ProviderAdapter {
+    readonly provider: string;
+    constructor(provider: string);
+    chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/adapters/engines/anthropic.js

@@ -0,0 +1,278 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { postResponse, sseLines } from '../../transport.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { streamError, streamTimeout } from './base.js';
+const JSON_MODE_TOOL = 'json_output';
+export class AnthropicAdapter {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async chat(conn, req) {
+        let result;
+        for await (const event of this.stream(conn, req)) {
+            if (event.type === 'done')
+                result = event.result;
+            if (event.type === 'error')
+                throw event.error;
+        }
+        if (!result)
+            throw new AIError('Anthropic stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+        return result;
+    }
+    async *stream(conn, req) {
+        const started = Date.now();
+        const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+        let firstTokenMs = null;
+        let text = '';
+        let inputTokens;
+        let outputTokens;
+        let stopReason;
+        const emittedTools = [];
+        // Partial tool_use blocks keyed by content-block index (input_json_delta accumulation).
+        const blocks = new Map();
+        const timeout = streamTimeout(conn, req.signal);
+        yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        try {
+            const res = await postResponse(`${conn.baseUrl}/v1/messages`, body(req, jsonMode), conn.headers, timeout.signal, conn.provider);
+            const contentType = res.headers.get('content-type') ?? '';
+            if (!contentType.includes('text/event-stream')) {
+                const data = await res.json();
+                const parsed = parseResponse(data);
+                inputTokens = parsed.inputTokens;
+                outputTokens = parsed.outputTokens;
+                stopReason = parsed.stopReason;
+                if (jsonMode) {
+                    text = jsonTextFrom(parsed.toolCalls, parsed.text);
+                    if (text)
+                        yield { type: 'delta', text };
+                }
+                else {
+                    text = parsed.text;
+                    if (text)
+                        yield { type: 'delta', text };
+                    for (const call of parsed.toolCalls) {
+                        emittedTools.push(call);
+                        yield { type: 'tool_call', call };
+                    }
+                }
+            }
+            else {
+                for await (const line of sseLines(res)) {
+                    const record = asRecord(safeParse(line));
+                    if (!record)
+                        continue;
+                    const type = asString(record.type);
+                    if (type === 'message_start') {
+                        const usage = asRecord(asRecord(record.message)?.usage);
+                        inputTokens = asNumber(usage?.input_tokens) ?? inputTokens;
+                        outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
+                    }
+                    else if (type === 'content_block_start') {
+                        const index = asNumber(record.index) ?? 0;
+                        const block = asRecord(record.content_block);
+                        if (block?.type === 'tool_use') {
+                            blocks.set(index, { id: asString(block.id) ?? randomId(), name: asString(block.name) ?? 'unknown', raw: '' });
+                        }
+                    }
+                    else if (type === 'content_block_delta') {
+                        const index = asNumber(record.index) ?? 0;
+                        const delta = asRecord(record.delta);
+                        if (delta?.type === 'text_delta') {
+                            const piece = asString(delta.text) ?? '';
+                            if (piece) {
+                                if (firstTokenMs === null)
+                                    firstTokenMs = Date.now() - started;
+                                text += piece;
+                                yield { type: 'delta', text: piece };
+                            }
+                        }
+                        else if (delta?.type === 'input_json_delta') {
+                            const partial = blocks.get(index);
+                            if (partial)
+                                partial.raw += asString(delta.partial_json) ?? '';
+                        }
+                    }
+                    else if (type === 'content_block_stop') {
+                        const index = asNumber(record.index) ?? 0;
+                        const partial = blocks.get(index);
+                        if (partial) {
+                            const call = { id: partial.id, name: partial.name, raw: partial.raw, arguments: parseArgs(partial.raw) };
+                            blocks.delete(index);
+                            if (jsonMode && call.name === JSON_MODE_TOOL) {
+                                text = jsonTextFrom([call], text);
+                                if (firstTokenMs === null)
+                                    firstTokenMs = Date.now() - started;
+                                yield { type: 'delta', text };
+                            }
+                            else {
+                                emittedTools.push(call);
+                                yield { type: 'tool_call', call };
+                            }
+                        }
+                    }
+                    else if (type === 'message_delta') {
+                        const delta = asRecord(record.delta);
+                        stopReason = asString(delta?.stop_reason) ?? stopReason;
+                        const usage = asRecord(record.usage);
+                        outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
+                    }
+                }
+            }
+            const hasTools = emittedTools.length > 0;
+            yield { type: 'done', result: {
+                    text,
+                    toolCalls: hasTools ? emittedTools : undefined,
+                    finishReason: mapStop(stopReason, hasTools),
+                    usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+                    timing: { firstTokenMs, totalMs: Date.now() - started },
+                    model: req.model,
+                    source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+                } };
+        }
+        catch (error) {
+            throw streamError(error, timeout, conn.provider);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+}
+function body(req, jsonMode) {
+    const system = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n') || undefined;
+    const base = {
+        model: req.model,
+        max_tokens: req.maxTokens ?? 4096,
+        temperature: req.temperature,
+        top_p: req.topP,
+        stop_sequences: req.stopSequences,
+        system,
+        messages: toAnthropicMessages(req.messages.filter((m) => m.role !== 'system')),
+        stream: true,
+    };
+    if (jsonMode) {
+        // Forced-tool JSON mode: Anthropic has no response_format, so we make the
+        // model answer through a single required tool whose input is the JSON we want.
+        base.tools = [{ name: JSON_MODE_TOOL, description: 'Return the answer as a JSON object.', input_schema: schemaFor(req) }];
+        base.tool_choice = { type: 'tool', name: JSON_MODE_TOOL };
+    }
+    else if (req.tools?.length) {
+        base.tools = req.tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.parameters }));
+        if (typeof req.toolChoice === 'object')
+            base.tool_choice = { type: 'tool', name: req.toolChoice.name };
+        else if (req.toolChoice === 'auto')
+            base.tool_choice = { type: 'auto' };
+        else if (req.toolChoice === 'none')
+            base.tool_choice = { type: 'none' };
+    }
+    return base;
+}
+function toAnthropicMessages(messages) {
+    const out = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message.role !== 'tool') {
+            out.push(toAnthropicMessage(message));
+            continue;
+        }
+        const content = [];
+        while (index < messages.length && messages[index]?.role === 'tool') {
+            const toolMessage = messages[index];
+            content.push({ type: 'tool_result', tool_use_id: toolMessage.toolCallId ?? '', content: textContent(toolMessage.content) });
+            index += 1;
+        }
+        index -= 1;
+        out.push({ role: 'user', content });
+    }
+    return out;
+}
+function toAnthropicMessage(m) {
+    // tool result messages map to a user turn carrying a tool_result content block.
+    if (m.role === 'tool') {
+        return {
+            role: 'user',
+            content: [{ type: 'tool_result', tool_use_id: m.toolCallId ?? '', content: typeof m.content === 'string' ? m.content : '' }],
+        };
+    }
+    // assistant turns that carried tool calls replay them as tool_use blocks.
+    if (m.role === 'assistant' && m.toolCalls?.length) {
+        const content = [];
+        if (typeof m.content === 'string' && m.content)
+            content.push({ type: 'text', text: m.content });
+        for (const call of m.toolCalls)
+            content.push({ type: 'tool_use', id: call.id, name: call.name, input: call.arguments ?? {} });
+        return { role: 'assistant', content };
+    }
+    return {
+        role: m.role === 'assistant' ? 'assistant' : 'user',
+        content: typeof m.content === 'string' ? m.content : m.content.map((part) => part.type === 'image'
+            ? { type: 'image', source: { type: 'base64', media_type: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+            : { type: 'text', text: part.text ?? '' }),
+    };
+}
+function textContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!content)
+        return '';
+    return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+function parseResponse(data) {
+    const record = asRecord(data);
+    const content = Array.isArray(record?.content) ? record.content : [];
+    let text = '';
+    const toolCalls = [];
+    for (const blockValue of content) {
+        const block = asRecord(blockValue);
+        if (block?.type === 'text')
+            text += asString(block.text) ?? '';
+        if (block?.type === 'tool_use') {
+            toolCalls.push({
+                id: asString(block.id) ?? randomId(),
+                name: asString(block.name) ?? 'unknown',
+                arguments: block.input ?? {},
+                raw: JSON.stringify(block.input ?? {}),
+            });
+        }
+    }
+    const usage = asRecord(record?.usage);
+    return { text, inputTokens: asNumber(usage?.input_tokens), outputTokens: asNumber(usage?.output_tokens), stopReason: asString(record?.stop_reason), toolCalls };
+}
+function schemaFor(req) {
+    const schema = req.responseFormat?.type === 'json' ? req.responseFormat.schema : undefined;
+    return schema ?? { type: 'object' };
+}
+function jsonTextFrom(toolCalls, fallback) {
+    const json = toolCalls.find((call) => call.name === JSON_MODE_TOOL) ?? toolCalls[0];
+    if (json)
+        return json.raw && json.raw.trim() ? json.raw : JSON.stringify(json.arguments ?? {});
+    return fallback;
+}
+function mapStop(stop, hasTools) {
+    if (stop === 'tool_use' && hasTools)
+        return 'tool';
+    if (stop === 'max_tokens')
+        return 'length';
+    return 'stop';
+}
+function parseArgs(raw) {
+    try {
+        return raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function safeParse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/adapters/engines/base.d.ts

@@ -0,0 +1,23 @@
+import { AIError } from '../../errors.js';
+import { withTimeout } from '../../transport.js';
+import type { ModelInfo, ResolvedConnection } from '../../types.js';
+import type { ProviderProfile } from '../profiles.js';
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * Maps a raw streaming failure onto a typed {@link AIError}. A fired timeout is
+ * reported as `timeout` regardless of how the underlying `fetch` surfaced the
+ * abort; anything else is normalized through {@link fromUnknown} (which passes
+ * an existing {@link AIError} through untouched, preserving retryability).
+ */
+export declare function streamError(error: unknown, timeout: {
+    timedOut(): boolean;
+}, provider: string): AIError;
+/** Create a timeout/abort scope covering the full stream lifetime. */
+export declare function streamTimeout(conn: ResolvedConnection, signal?: AbortSignal): ReturnType<typeof withTimeout>;
+export declare function listOpenModels(conn: ResolvedConnection, profile: ProviderProfile): Promise<ModelInfo[]>;
+export declare function health(conn: ResolvedConnection, profile: ProviderProfile): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
+export declare function requireResponse(condition: unknown, message: string): asserts condition;
+//# sourceMappingURL=base.d.ts.map