@jxburros/ai-nugget 0.4.1 → 0.7.0

package/UPGRADING.md

@@ -0,0 +1,182 @@
+# Upgrading
+
+## 0.6.x → 0.7.0
+
+**Backward-compatible for ordinary consumers.** Two additive changes and one
+default-behaviour change worth knowing about:
+
+- **Inline reasoning is stripped by default.** A model that writes
+  `<think>…</think>` (or `<thinking>`, `<reasoning>`, `<|begin_of_thought|>`)
+  into its answer no longer has that text in `delta` events or
+  `ChatResult.text`; it arrives as `{ type: 'reasoning', text }` events, the
+  same channel a provider-native thinking field already used. If your app
+  parsed or displayed those tags itself, either delete that code or pass
+  `new AIHandler({ stripInlineReasoning: false })` to keep the raw text.
+
+- **`ChatRequest.reasoningEffort`** (and `AgentOptions.reasoningEffort`) — a
+  new optional field. Nothing is sent to any provider unless you set it. If you
+  already pass `reasoning_effort` / `thinking` / `thinkingConfig` / `think`
+  through `providerOptions`, that keeps winning on collision.
+- **A new `context` stream event, `reasoning_effort_disabled_for_tools`** — the
+  `openaiChat` engine emits it when it retried a tool-using request with
+  `reasoning_effort: 'none'` after OpenAI refused the first attempt. Ignoring
+  it keeps the old behaviour minus the 400. If you *want* the hard failure
+  instead (to route to `/v1/responses` yourself), set `reasoningEffort: 'none'`
+  explicitly on tool-using turns — then no retry happens and any 400 is yours.
+
+## 0.5.x → 0.6.0
+
+Behavior-compatible for ordinary consumers, with **two things worth checking**.
+
+### 1. `not_found` is a new `AIErrorKind`
+
+404 and 410 responses now classify as `not_found` instead of
+`invalid_request`, so a wrong `baseUrl`/model or a misrouted edge is
+distinguishable from a malformed request body. It is non-retryable by default.
+
+- **If you `switch` exhaustively over `AIErrorKind`** (with a `never` default),
+  TypeScript will require a new branch. Map it like `auth`/`key_unavailable` —
+  it's a *server-side configuration* problem, not the caller's fault:
+
+  ```ts
+  case 'not_found': return { status: 502, message: 'The AI service is not configured correctly.' };
+  ```
+
+- **If you switch non-exhaustively** with a fallback, nothing breaks: a 404 that
+  used to produce "that request was invalid" now falls into your default branch
+  instead. That is the intended improvement, but check the resulting message
+  still reads correctly.
+
+### 2. A startup notice when no policy is configured
+
+`new AIHandler({ keySource })` with no `policy` now logs one line at
+construction: every provider and model is allowed. `allowAllPolicy()` is still
+the default — nothing is blocked. To silence it, say what you mean:
+
+```ts
+new AIHandler({ keySource, policy: allowAllPolicy() });        // deliberate, no warning
+new AIHandler({ keySource, silencePolicyWarning: true });      // same, if you prefer
+```
+
+### Also new, no action required
+
+- **`Connection.provider` is now typed** `KnownProvider | (string & {})`. You get
+  autocomplete and typo-catching; arbitrary strings still compile and still
+  resolve through `openai-compat`.
+- **`beforeCall` hooks get a scrubbed connection.** `info.connection.keyRef` is
+  masked for literal refs, and `info.resolved.headers` masks auth headers. If a
+  hook was reading `info.connection.keyRef.value` to get the key — don't; resolve
+  it through your `KeySource` instead.
+- **`Idempotency-Key` on OpenAI requests.** One key per logical call, reused
+  across retries. A header you set yourself on `Connection.headers` wins.
+- **New `context` stream events**: `json_mode_downgraded` (Google/Anthropic drop
+  JSON mode when tools are present) and `stream_anomaly` on all four engines
+  (previously `openaiChat` only). Both are informational; ignoring them keeps
+  the old behavior.
+- **Documentation moved.** `README.md` is now a front door; reference material
+  lives under `docs/` (`providers`, `reliability`, `security`, `agent-loop`,
+  `recipes`, `integrations`, `distribution`). Deep links into the old README
+  anchors will need updating.
+
+## 0.4.x → 0.5.0
+
+**0.5.0 is backward-compatible.** Every change below is additive — new optional
+fields, new methods, new exports, and a new `require` entry point. No existing
+signature changed and no default behavior changed, so an app on 0.4.x can bump
+without code edits and adopt the new capabilities as needed.
+
+The numbers in brackets are the suggestion numbers from the AI Server Studio
+production friction report (`docs/reviews/2026-08-09-ai-server-studio-friction-report.md`),
+so you can trace each change back to the friction it resolves.
+
+### Packaging
+
+- **[1] Dual ESM + CommonJS build.** The package now exposes a `require`
+  condition (`dist/cjs/`) in addition to ESM. CommonJS hosts can
+  `const { AIHandler } = require('@jxburros/ai-nugget')` with no dynamic-import
+  shim. ESM consumers are unaffected.
+- **[2] Vendorable compiled output.** `npm run build:nugget` now emits both
+  `nugget/src` (TypeScript) and `nugget/dist` (compiled ESM `.js` + `.d.ts`), so
+  bundlers that can't resolve `.ts` via `.js`-suffixed imports (e.g. Turbopack)
+  can vendor `nugget/dist`.
+
+### Requests & providers
+
+- **[4] `ChatRequest.providerOptions`.** A provider-native passthrough merged
+  into the outgoing request body (shallow top-level; one level deep into Ollama
+  `options` and Google `generationConfig`). Reach fields the nugget doesn't
+  model — Ollama `num_ctx`/`keep_alive`, OpenAI `reasoning_effort`, Anthropic
+  `thinking`, Google `safetySettings` — without waiting for a release.
+- **[16] `Connection.idleTimeoutMs`.** An idle timeout for streams, distinct from
+  the total `timeoutMs`: it aborts only when no chunk arrives for that long, and
+  resets on every chunk — so a slow-but-healthy long local generation isn't
+  killed mid-stream.
+- **[17] `reasoning` stream events.** Reasoning/thinking tokens (Anthropic
+  `thinking_delta`, OpenAI `reasoning_content`, Gemini `thought` parts, Ollama
+  `thinking`) surface as `{ type: 'reasoning', text }` instead of being dropped
+  or blended into `delta`.
+- **[18] `listModels()` for Anthropic & Google.** Both now query the real
+  endpoints (`/v1/models`, `/v1beta/models`) instead of returning `[]`.
+- **[19] Faster Ollama discovery.** `/api/show` probes run with bounded
+  concurrency instead of serially.
+- **[20] New provider profiles + Azure api-version override.** Added `cerebras`,
+  `moonshot`, `cohere`, and `perplexity`. The Azure `api-version` is now
+  overridable per call via `providerOptions.apiVersion` (default unchanged).
+- **[21] Safer URL joining** in the `openai-compat` engine (no accidental double
+  slash even if `baseUrl` ends in `/`).
+- **[23] Embeddings.** `AIHandler.embed(conn, req)` plus `EmbedRequest` /
+  `EmbedResult`, implemented for Ollama (`/api/embed`) and OpenAI-compatible
+  providers (`/embeddings`) — through the same policy/key/telemetry pipeline as
+  chat. Providers without embeddings throw a typed `invalid_request` error.
+
+### Structured output & typed results
+
+- **[15] `AIHandler.chatParsed(conn, req, schema)`.** Requests JSON, extracts it,
+  and validates against any [Standard Schema](https://standardschema.dev)
+  validator (Zod / Valibot / ArkType) — with one automatic corrective retry on a
+  validation miss. No schema library is bundled; you pass your own.
+
+### Agent loop (`@jxburros/ai-nugget/agent`)
+
+- **[5] Option passthrough.** `AgentOptions` now forwards `temperature`,
+  `maxTokens`, `topP`, `stopSequences`, and `providerOptions` to every turn.
+- **[6] Capability-aware `toolMode`.** `AgentOptions.modelCapabilities` — when
+  `toolMode: 'auto'`, a model advertising `"tools"` uses native tool-calling even
+  on a local runtime whose profile default is `promptJson`.
+- **[7] No leaked directives + `tool_mode` event.** In `promptJson` mode, tool
+  directives are withheld from the visible `delta` stream, and a `tool_mode`
+  event discloses the resolved protocol.
+- **[8] Parameter schemas in the `promptJson` prompt**, so the model isn't
+  guessing argument shape.
+- **[9] `undefined` tool results no longer crash a run.**
+- **[10] `AgentResult.error`** is populated when `stopReason === 'error'`.
+- **[11] Structured tool errors.** A tool returning `{ ok: false, ... }` is
+  surfaced with `isError: true` so the model can recover in-turn.
+- **[12] `AgentOptions.toolResult`.** Opt-in `maxChars` cap and `wrapUntrusted`
+  framing for tool results re-entering context.
+- **[14] `AgentOptions.approvalMode: 'all'`.** Gate every tool (not just
+  `sideEffects` ones) so `tool_denied` is reachable without per-tool flags.
+
+### Handler, telemetry & security
+
+- **[3] `AIHandler.prewarm(conn)`.** A no-throw warm-up (health probe) to move
+  cold DNS/TLS/daemon-spin-up cost off the first real call.
+- **[22] `CallInfo.resolved`.** The `beforeCall` hook now receives the resolved
+  connection (base URL + headers, key omitted) so it can validate the effective
+  endpoint — e.g. a request-time SSRF re-check — without hijacking `keySource`.
+- **[24] `HandlerOptions.pricing`.** An optional cost estimator whose result is
+  recorded on `CallRecord.costUsd`.
+
+### Tooling & hygiene
+
+- **[25]** Assistant messages with both content parts and tool calls no longer
+  drop their text/image parts on replay (Anthropic & Google); dead `role:'tool'`
+  branches removed; the `403 → non-retryable` policy is documented; ESLint and
+  Vitest coverage are wired up (`npm run lint`, `npm run test:coverage`).
+
+### Not changed (deliberately)
+
+- No provider policy ships as a library default (blocklists/allowlists remain the
+  app's configuration at the seam).
+- Zero runtime dependencies — everything above is implemented with the isomorphic
+  core (`fetch`/`ReadableStream`/`AbortController`/`TextDecoder`) only.

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

@@ -1,8 +1,14 @@
-import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ChatRequest, ChatResult, ModelInfo, 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>;
+    /**
+     * Lists models from Anthropic's `/v1/models` endpoint (auth + version headers
+     * already applied to `conn.headers`). The endpoint does not report a context
+     * window, so `contextWindow` is left undefined rather than guessed.
+     */
+    listModels(conn: ResolvedConnection): Promise<ModelInfo[]>;
 }
 //# sourceMappingURL=anthropic.d.ts.map

package/dist/adapters/engines/anthropic.js

@@ -1,8 +1,8 @@
 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';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
+import { applyProviderOptions, REASONING_BUDGET_TOKENS, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, parseArgs, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 const JSON_MODE_TOOL = 'json_output';
 export class AnthropicAdapter {
     provider;
@@ -29,11 +29,22 @@ export class AnthropicAdapter {
         let inputTokens;
         let outputTokens;
         let stopReason;
+        let sawTerminal = false;
         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 };
+        // Anthropic JSON mode is implemented as a forced `json_output` tool, which
+        // cannot coexist with the caller's own tools — same silent-downgrade shape
+        // as Gemini, so it gets the same signal rather than quietly dropping.
+        if (req.responseFormat?.type === 'json' && req.tools?.length) {
+            yield {
+                type: 'context',
+                kind: 'json_mode_downgraded',
+                data: { reason: 'Anthropic JSON mode uses a forced tool and cannot be combined with caller tools; the request was sent without JSON mode', provider: conn.provider },
+            };
+        }
         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') ?? '';
@@ -43,6 +54,7 @@ export class AnthropicAdapter {
                 inputTokens = parsed.inputTokens;
                 outputTokens = parsed.outputTokens;
                 stopReason = parsed.stopReason;
+                sawTerminal = true;
                 if (jsonMode) {
                     text = jsonTextFrom(parsed.toolCalls, parsed.text);
                     if (text)
@@ -60,6 +72,7 @@ export class AnthropicAdapter {
             }
             else {
                 for await (const line of sseLines(res)) {
+                    timeout.bump();
                     const record = asRecord(safeParse(line));
                     if (!record)
                         continue;
@@ -88,6 +101,12 @@ export class AnthropicAdapter {
                                 yield { type: 'delta', text: piece };
                             }
                         }
+                        else if (delta?.type === 'thinking_delta') {
+                            // Extended-thinking tokens ride the reasoning channel, kept out of `text`.
+                            const piece = asString(delta.thinking) ?? '';
+                            if (piece)
+                                yield { type: 'reasoning', text: piece };
+                        }
                         else if (delta?.type === 'input_json_delta') {
                             const partial = blocks.get(index);
                             if (partial)
@@ -112,14 +131,21 @@ export class AnthropicAdapter {
                             }
                         }
                     }
+                    else if (type === 'message_stop') {
+                        sawTerminal = true;
+                    }
                     else if (type === 'message_delta') {
                         const delta = asRecord(record.delta);
+                        if (asString(delta?.stop_reason))
+                            sawTerminal = true;
                         stopReason = asString(delta?.stop_reason) ?? stopReason;
                         const usage = asRecord(record.usage);
                         outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
                     }
                 }
             }
+            if (!sawTerminal)
+                yield streamAnomaly('stream ended without a stop_reason or message_stop');
             const hasTools = emittedTools.length > 0;
             yield { type: 'done', result: {
                     text,
@@ -138,6 +164,24 @@ export class AnthropicAdapter {
             timeout.done();
         }
     }
+    /**
+     * Lists models from Anthropic's `/v1/models` endpoint (auth + version headers
+     * already applied to `conn.headers`). The endpoint does not report a context
+     * window, so `contextWindow` is left undefined rather than guessed.
+     */
+    async listModels(conn) {
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/v1/models'), {
+            method: 'GET',
+            headers: conn.headers,
+            timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 15_000),
+            provider: conn.provider,
+        });
+        const rows = Array.isArray(asRecord(data)?.data) ? asRecord(data).data : [];
+        return rows
+            .map((row) => asString(asRecord(row)?.id))
+            .filter((id) => Boolean(id))
+            .map((id) => ({ id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } }));
+    }
 }
 function body(req, jsonMode) {
     const system = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n') || undefined;
@@ -166,7 +210,27 @@ function body(req, jsonMode) {
         else if (req.toolChoice === 'none')
             base.tool_choice = { type: 'none' };
     }
-    return base;
+    if (req.reasoningEffort !== undefined) {
+        // First-class reasoning effort → extended thinking. Anthropic requires
+        // `budget_tokens < max_tokens` and rejects temperature/top_p alongside
+        // thinking, so the budget is fitted under max_tokens (raising max_tokens
+        // when the caller's value leaves no room) and the samplers are dropped.
+        if (req.reasoningEffort === 'none') {
+            base.thinking = { type: 'disabled' };
+        }
+        else {
+            const budget = REASONING_BUDGET_TOKENS[req.reasoningEffort];
+            const maxTokens = typeof base.max_tokens === 'number' ? base.max_tokens : 4096;
+            if (maxTokens <= budget)
+                base.max_tokens = budget + 1024;
+            base.thinking = { type: 'enabled', budget_tokens: budget };
+            delete base.temperature;
+            delete base.top_p;
+        }
+    }
+    // providerOptions carries Anthropic-native fields (`thinking`, `metadata`,
+    // top-level `cache_control` extras, `service_tier`, …) without a release.
+    return applyProviderOptions(base, req.providerOptions);
 }
 function toAnthropicMessages(messages) {
     const out = [];
@@ -188,29 +252,29 @@ function toAnthropicMessages(messages) {
     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.
+    // Tool-role messages are handled by toAnthropicMessages' batching loop and
+    // never reach here, so no tool branch is needed.
+    // assistant turns that carried tool calls replay them as tool_use blocks,
+    // preserving any text/image content parts that accompanied the calls.
     if (m.role === 'assistant' && m.toolCalls?.length) {
-        const content = [];
-        if (typeof m.content === 'string' && m.content)
-            content.push({ type: 'text', text: m.content });
+        const content = [...contentBlocks(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 ?? '' }),
+        content: typeof m.content === 'string' ? m.content : contentBlocks(m.content),
     };
 }
+/** Maps text/image content — a string or a ContentPart[] — onto Anthropic content blocks. */
+function contentBlocks(content) {
+    if (typeof content === 'string')
+        return content ? [{ type: 'text', text: content }] : [];
+    return 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;
@@ -256,23 +320,4 @@ function mapStop(stop, hasTools) {
         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

@@ -12,12 +12,39 @@ export declare const DEFAULT_TIMEOUT_MS = 120000;
 export declare function streamError(error: unknown, timeout: {
     timedOut(): boolean;
 }, provider: string): AIError;
-/** Create a timeout/abort scope covering the full stream lifetime. */
+/**
+ * Create a timeout/abort scope covering the full stream lifetime, plus an
+ * optional idle timeout (`conn.idleTimeoutMs`) that the engine rearms via
+ * `bump()` on each received chunk.
+ */
 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;
+/**
+ * Coerce a provider's tool-call `arguments` into an object. Providers disagree
+ * on the shape: OpenAI/Anthropic stream a JSON *string*, Google and Ollama send
+ * a native object — but Ollama-compatible backends (llama.cpp and friends)
+ * sometimes send a string too. Malformed JSON degrades to `{}` so a single bad
+ * tool call surfaces as an argument-validation error rather than a stream crash.
+ */
+export declare function parseArgs(raw: unknown): unknown;
+/** JSON.parse that returns undefined instead of throwing — for per-line stream frames. */
+export declare function safeParse(line: string): unknown;
+/** Stable-enough id for a tool call a provider didn't give one for. */
+export declare function randomId(): string;
+/**
+ * A stream that ended without the provider's terminal marker (an OpenAI
+ * `finish_reason`, an Anthropic `message_delta.stop_reason`, a Google
+ * `finishReason`, an Ollama `done`) was almost certainly truncated. Every
+ * engine yields this so a dropped connection is diagnosable identically
+ * regardless of provider.
+ */
+export declare function streamAnomaly(reason?: string): {
+    type: 'context';
+    kind: string;
+    data: unknown;
+};
 //# sourceMappingURL=base.d.ts.map

package/dist/adapters/engines/base.js

@@ -1,6 +1,6 @@
 import { AIError, fromUnknown } from '../../errors.js';
 import { fetchJson, withTimeout } from '../../transport.js';
-import { asRecord, asString } from '../../util.js';
+import { asRecord, asString, joinUrl } from '../../util.js';
 export const DEFAULT_TIMEOUT_MS = 120_000;
 /**
  * Maps a raw streaming failure onto a typed {@link AIError}. A fired timeout is
@@ -13,14 +13,18 @@ export function streamError(error, timeout, provider) {
         return new AIError('Request timed out', { kind: 'timeout', provider });
     return fromUnknown(error, provider);
 }
-/** Create a timeout/abort scope covering the full stream lifetime. */
+/**
+ * Create a timeout/abort scope covering the full stream lifetime, plus an
+ * optional idle timeout (`conn.idleTimeoutMs`) that the engine rearms via
+ * `bump()` on each received chunk.
+ */
 export function streamTimeout(conn, signal) {
-    return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal);
+    return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal, conn.idleTimeoutMs);
 }
 export async function listOpenModels(conn, profile) {
     if (!profile.listModelsPath)
         return [];
-    const { data } = await fetchJson(`${conn.baseUrl}${profile.listModelsPath}`, {
+    const { data } = await fetchJson(joinUrl(conn.baseUrl, profile.listModelsPath), {
         method: 'GET',
         headers: conn.headers,
         timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
@@ -53,7 +57,7 @@ export async function health(conn, profile) {
     if (!path)
         return { ok: true };
     try {
-        await fetchJson(`${conn.baseUrl}${path}`, {
+        await fetchJson(joinUrl(conn.baseUrl, path), {
             method: 'GET',
             headers: conn.headers,
             timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
@@ -65,9 +69,49 @@ export async function health(conn, profile) {
         return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
     }
 }
-export function requireResponse(condition, message) {
-    if (!condition)
-        throw new AIError(message, { kind: 'invalid_response' });
+/**
+ * Coerce a provider's tool-call `arguments` into an object. Providers disagree
+ * on the shape: OpenAI/Anthropic stream a JSON *string*, Google and Ollama send
+ * a native object — but Ollama-compatible backends (llama.cpp and friends)
+ * sometimes send a string too. Malformed JSON degrades to `{}` so a single bad
+ * tool call surfaces as an argument-validation error rather than a stream crash.
+ */
+export function parseArgs(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'string')
+        return raw;
+    if (!raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/** JSON.parse that returns undefined instead of throwing — for per-line stream frames. */
+export function safeParse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Stable-enough id for a tool call a provider didn't give one for. */
+export function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+/**
+ * A stream that ended without the provider's terminal marker (an OpenAI
+ * `finish_reason`, an Anthropic `message_delta.stop_reason`, a Google
+ * `finishReason`, an Ollama `done`) was almost certainly truncated. Every
+ * engine yields this so a dropped connection is diagnosable identically
+ * regardless of provider.
+ */
+export function streamAnomaly(reason = 'stream ended without a terminal finish reason') {
+    return { type: 'context', kind: 'stream_anomaly', data: { reason } };
 }
 /**
  * Pulls a context-window figure out of the many shapes providers use for it

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

@@ -1,4 +1,4 @@
-import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
 export declare class GoogleAdapter implements ProviderAdapter {
     readonly provider: string;
     constructor(provider: string);
@@ -14,5 +14,11 @@ export declare class GoogleAdapter implements ProviderAdapter {
         ok: boolean;
         detail?: string;
     }>;
+    /**
+     * Lists models from Google's `/v1beta/models`. Strips the `models/` name
+     * prefix, and maps `inputTokenLimit` → `contextWindow` and
+     * `supportedGenerationMethods` → `capabilities`.
+     */
+    listModels(conn: ResolvedConnection): Promise<ModelInfo[]>;
 }
 //# sourceMappingURL=google.d.ts.map