@jxburros/ai-nugget 0.3.1 → 0.6.0

package/nugget/src/adapters/engines/base.ts

@@ -1,7 +1,7 @@
 import { AIError, fromUnknown } from '../../errors.js';
 import { fetchJson, withTimeout } from '../../transport.js';
 import type { ModelInfo, ResolvedConnection } from '../../types.js';
-import { asRecord, asString } from '../../util.js';
+import { asRecord, asString, joinUrl } from '../../util.js';
 import type { ProviderProfile } from '../profiles.js';
 
 export const DEFAULT_TIMEOUT_MS = 120_000;
@@ -17,14 +17,18 @@ export function streamError(error: unknown, timeout: { timedOut(): boolean }, pr
   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: ResolvedConnection, signal?: AbortSignal): ReturnType<typeof withTimeout> {
-  return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal);
+  return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal, conn.idleTimeoutMs);
 }
 
 export async function listOpenModels(conn: ResolvedConnection, profile: ProviderProfile): Promise<ModelInfo[]> {
   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,
@@ -54,7 +58,7 @@ export async function health(conn: ResolvedConnection, profile: ProviderProfile)
   const path = profile.healthPath ?? profile.listModelsPath;
   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),
@@ -66,8 +70,47 @@ export async function health(conn: ResolvedConnection, profile: ProviderProfile)
   }
 }
 
-export function requireResponse(condition: unknown, message: string): asserts condition {
-  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: unknown): unknown {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== 'string') return raw;
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+/** JSON.parse that returns undefined instead of throwing — for per-line stream frames. */
+export function safeParse(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Stable-enough id for a tool call a provider didn't give one for. */
+export function randomId(): string {
+  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'): { type: 'context'; kind: string; data: unknown } {
+  return { type: 'context', kind: 'stream_anomaly', data: { reason } };
 }
 
 /**

package/nugget/src/adapters/engines/google.ts

@@ -1,9 +1,9 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
-import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { streamError, streamTimeout } from './base.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 
 export class GoogleAdapter implements ProviderAdapter {
   readonly provider: string;
@@ -31,12 +31,23 @@ export class GoogleAdapter implements ProviderAdapter {
     const toolCalls: ToolCall[] = [];
     const timeout = streamTimeout(conn, req.signal);
     yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+    // Gemini rejects `responseMimeType: application/json` combined with function
+    // declarations, so `body()` drops JSON mode when tools are present. Surface
+    // that downgrade instead of silently returning unstructured text.
+    if (jsonModeDowngraded(req)) {
+      yield {
+        type: 'context',
+        kind: 'json_mode_downgraded',
+        data: { reason: 'Gemini does not accept JSON response mode together with tools; the request was sent without JSON mode', provider: conn.provider },
+      };
+    }
     try {
       const streamUrl = `${conn.baseUrl}/v1beta/models/${encodeURIComponent(req.model)}:streamGenerateContent?alt=sse`;
       const res = await postResponse(streamUrl, body(req), conn.headers, timeout.signal, conn.provider);
       const contentType = res.headers.get('content-type') ?? '';
       const chunks = contentType.includes('text/event-stream') ? sseLines(res) : singleJsonLine(res);
       for await (const line of chunks) {
+        timeout.bump();
         const parsed = safeParse(line);
         const record = asRecord(parsed);
         const promptFeedback = asRecord(record?.promptFeedback);
@@ -44,6 +55,12 @@ export class GoogleAdapter implements ProviderAdapter {
         for (const part of candidateParts(record)) {
           const partText = asString(asRecord(part)?.text);
           if (partText) {
+            // Gemini marks reasoning parts with `thought: true`; route those to
+            // the reasoning channel so they don't blend into the answer text.
+            if (asRecord(part)?.thought === true) {
+              yield { type: 'reasoning', text: partText };
+              continue;
+            }
             if (firstTokenMs === null) firstTokenMs = Date.now() - started;
             text += partText;
             yield { type: 'delta', text: partText };
@@ -65,6 +82,7 @@ export class GoogleAdapter implements ProviderAdapter {
         inputTokens = asNumber(usage?.promptTokenCount) ?? inputTokens;
         outputTokens = asNumber(usage?.candidatesTokenCount) ?? outputTokens;
       }
+      if (!finish) yield streamAnomaly('stream ended without a finishReason');
       const hasTools = toolCalls.length > 0;
       yield { type: 'done', result: {
         text,
@@ -81,6 +99,60 @@ export class GoogleAdapter implements ProviderAdapter {
       timeout.done();
     }
   }
+
+  /**
+   * `GoogleAdapter` has no `listModels`, so without a `health` probe
+   * `AIHandler.testConnection` would report `ok: true` without ever making a
+   * network call. `/v1beta/models` is a lightweight, key-authenticated GET
+   * that gives an honest connectivity/auth check.
+   */
+  async health(conn: ResolvedConnection): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      await fetchJson(joinUrl(conn.baseUrl, '/v1beta/models'), {
+        method: 'GET',
+        headers: conn.headers,
+        timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
+        provider: conn.provider,
+      });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
+    }
+  }
+
+  /**
+   * Lists models from Google's `/v1beta/models`. Strips the `models/` name
+   * prefix, and maps `inputTokenLimit` → `contextWindow` and
+   * `supportedGenerationMethods` → `capabilities`.
+   */
+  async listModels(conn: ResolvedConnection): Promise<ModelInfo[]> {
+    const { data } = await fetchJson(joinUrl(conn.baseUrl, '/v1beta/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)?.models) ? asRecord(data)!.models as unknown[] : [];
+    const models: ModelInfo[] = [];
+    for (const value of rows) {
+      const row = asRecord(value);
+      const name = asString(row?.name);
+      if (!name) continue;
+      const id = name.startsWith('models/') ? name.slice('models/'.length) : name;
+      const model: ModelInfo = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
+      const contextWindow = asNumber(row?.inputTokenLimit);
+      if (contextWindow !== undefined) model.contextWindow = contextWindow;
+      const methods = row?.supportedGenerationMethods;
+      if (Array.isArray(methods) && methods.every((m) => typeof m === 'string')) model.capabilities = methods as string[];
+      models.push(model);
+    }
+    return models;
+  }
+}
+
+/** True when the caller asked for JSON mode but tools force it off. */
+function jsonModeDowngraded(req: ChatRequest): boolean {
+  return req.responseFormat?.type === 'json' && !!req.tools?.length;
 }
 
 function body(req: ChatRequest): Record<string, unknown> {
@@ -106,7 +178,10 @@ function body(req: ChatRequest): Record<string, unknown> {
     if (typeof req.toolChoice === 'object') config.allowedFunctionNames = [req.toolChoice.name];
     payload.toolConfig = { functionCallingConfig: config };
   }
-  return payload;
+  // providerOptions reaches Google-native fields: top-level `safetySettings`,
+  // `cachedContent`, and `generationConfig` extras (`thinkingConfig`,
+  // `responseModalities`, …) merged one level deep into generationConfig.
+  return applyProviderOptions(payload, req.providerOptions, ['generationConfig']);
 }
 
 function toGoogleContents(messages: ChatMessage[]): Record<string, unknown>[] {
@@ -130,28 +205,27 @@ function toGoogleContents(messages: ChatMessage[]): Record<string, unknown>[] {
 }
 
 function toGoogleContent(m: ChatMessage): Record<string, unknown> {
-  if (m.role === 'tool') {
-    return {
-      role: 'user',
-      parts: [{ functionResponse: { name: m.name ?? 'unknown', response: toolResponseObject(m) } }],
-    };
-  }
+  // Tool-role messages are handled by toGoogleContents' batching loop and never
+  // reach here, so no tool branch is needed.
   if (m.role === 'assistant' && m.toolCalls?.length) {
-    const parts: unknown[] = [];
-    if (typeof m.content === 'string' && m.content) parts.push({ text: m.content });
+    const parts: unknown[] = [...googleParts(m.content)];
     for (const call of m.toolCalls) parts.push({ functionCall: { name: call.name, args: call.arguments ?? {} } });
     return { role: 'model', parts };
   }
   return {
     role: m.role === 'assistant' ? 'model' : 'user',
-    parts: typeof m.content === 'string'
-      ? [{ text: m.content }]
-      : m.content.map((part) => part.type === 'image'
-        ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
-        : { text: part.text ?? '' }),
+    parts: googleParts(m.content),
   };
 }
 
+/** Maps text/image content — a string or a ContentPart[] — onto Google parts. */
+function googleParts(content: ChatMessage['content']): unknown[] {
+  if (typeof content === 'string') return content ? [{ text: content }] : [];
+  return content.map((part) => part.type === 'image'
+    ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+    : { text: part.text ?? '' });
+}
+
 function textContent(content: ChatMessage['content']): string {
   if (typeof content === 'string') return content;
   if (!content) return '';
@@ -196,14 +270,3 @@ function mapFinish(finish: string | undefined, hasTools: boolean): ChatResult['f
   return 'stop';
 }
 
-function safeParse(line: string): unknown {
-  try {
-    return JSON.parse(line) as unknown;
-  } catch {
-    return undefined;
-  }
-}
-
-function randomId(): string {
-  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}

package/nugget/src/adapters/engines/ollama.ts

@@ -1,9 +1,12 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, ndjsonLines, postResponse } from '../../transport.js';
-import type { ChatMessage, ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+import type { ChatMessage, ChatRequest, ChatResult, EmbedRequest, EmbedResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, mapWithConcurrency, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, parseArgs, randomId, streamAnomaly, streamError, streamTimeout } from './base.js';
+
+/** Max concurrent /api/show probes when listing models — enough to be fast, few enough to be polite to a local daemon. */
+const SHOW_CONCURRENCY = 6;
 
 export class OllamaAdapter implements ProviderAdapter {
   readonly provider: string;
@@ -28,14 +31,18 @@ export class OllamaAdapter implements ProviderAdapter {
     let inputTokens: number | undefined;
     let outputTokens: number | undefined;
     let doneReason: string | undefined;
+    let sawTerminal = false;
     const toolCalls: ToolCall[] = [];
     const timeout = streamTimeout(conn, req.signal);
     yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
     try {
-      const res = await postResponse(`${conn.baseUrl}/api/chat`, body(req), conn.headers, timeout.signal, conn.provider);
+      const res = await postResponse(joinUrl(conn.baseUrl, '/api/chat'), body(req), conn.headers, timeout.signal, conn.provider);
       for await (const value of ndjsonLines(res)) {
+        timeout.bump();
         const record = asRecord(value);
         const message = asRecord(record?.message);
+        const thinking = asString(message?.thinking);
+        if (thinking) yield { type: 'reasoning', text: thinking };
         const piece = asString(message?.content);
         if (piece) {
           if (firstTokenMs === null) firstTokenMs = Date.now() - started;
@@ -45,6 +52,7 @@ export class OllamaAdapter implements ProviderAdapter {
         inputTokens = asNumber(record?.prompt_eval_count) ?? inputTokens;
         outputTokens = asNumber(record?.eval_count) ?? outputTokens;
         doneReason = asString(record?.done_reason) ?? doneReason;
+        if (record?.done === true) sawTerminal = true;
         const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
         for (const callValue of calls) {
           const fn = asRecord(asRecord(callValue)?.function);
@@ -52,13 +60,17 @@ export class OllamaAdapter implements ProviderAdapter {
           const toolCall: ToolCall = {
             id: randomId(),
             name: asString(fn?.name) ?? 'unknown',
-            arguments: args,
+            // Ollama itself sends a native object, but llama.cpp-style backends
+            // behind the same protocol send a JSON *string* — coerce either into
+            // the object `validateToolArgs` expects.
+            arguments: parseArgs(args),
             raw: typeof args === 'string' ? args : JSON.stringify(args),
           };
           toolCalls.push(toolCall);
           yield { type: 'tool_call', call: toolCall };
         }
       }
+      if (!sawTerminal) yield streamAnomaly('NDJSON stream ended without a done record');
       const hasTools = toolCalls.length > 0;
       yield { type: 'done', result: {
         text,
@@ -85,17 +97,38 @@ export class OllamaAdapter implements ProviderAdapter {
     });
     const models = Array.isArray(asRecord(data)?.models) ? asRecord(data)!.models as unknown[] : [];
     const ids = models.map((model) => asString(asRecord(model)?.name) ?? asString(asRecord(model)?.model) ?? '').filter(Boolean);
-    // Probe /api/show per model for context window + capabilities (best effort, sequential
-    // to avoid overwhelming a local Ollama instance).
-    const results: ModelInfo[] = [];
-    for (const id of ids) {
+    // Probe /api/show per model for context window + capabilities (best effort),
+    // with bounded concurrency so a large model list resolves quickly without
+    // opening an unbounded number of sockets against a local daemon.
+    return mapWithConcurrency(ids, SHOW_CONCURRENCY, async (id) => {
       const info: ModelInfo = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
       const probed = await this.showModel(conn, id).catch(() => undefined);
       if (probed?.contextWindow !== undefined) info.contextWindow = probed.contextWindow;
       if (probed?.capabilities) info.capabilities = probed.capabilities;
-      results.push(info);
-    }
-    return results;
+      return info;
+    });
+  }
+
+  async embed(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult> {
+    const inputs = Array.isArray(req.input) ? req.input : [req.input];
+    const { data } = await fetchJson(joinUrl(conn.baseUrl, '/api/embed'), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...conn.headers },
+      body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+      timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      provider: conn.provider,
+    });
+    const record = asRecord(data);
+    const rows = Array.isArray(record?.embeddings) ? record.embeddings : [];
+    const embeddings = rows.map((row) => (Array.isArray(row) ? row.filter((n): n is number => typeof n === 'number') : []));
+    const inputTokens = asNumber(record?.prompt_eval_count);
+    return {
+      embeddings,
+      model: req.model,
+      usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+      source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+      raw: data,
+    };
   }
 
   private async showModel(conn: ResolvedConnection, model: string): Promise<{ contextWindow?: number; capabilities?: string[] }> {
@@ -124,7 +157,7 @@ export class OllamaAdapter implements ProviderAdapter {
 }
 
 function body(req: ChatRequest): Record<string, unknown> {
-  return {
+  const base: Record<string, unknown> = {
     model: req.model,
     messages: req.messages.map(toOllamaMessage),
     stream: true,
@@ -132,6 +165,11 @@ function body(req: ChatRequest): Record<string, unknown> {
     format: req.responseFormat?.type === 'json' ? (req.responseFormat.schema ?? 'json') : undefined,
     tools: req.tools?.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })),
   };
+  // providerOptions reaches Ollama's real request fields — `options.num_ctx`,
+  // `options.num_keep`, top-level `keep_alive`, `think`, etc. `options` is
+  // merged one level deep so num_ctx joins the samplers above rather than
+  // replacing them.
+  return applyProviderOptions(base, req.providerOptions, ['options']);
 }
 
 function toOllamaMessage(m: ChatMessage): Record<string, unknown> {
@@ -147,7 +185,3 @@ function toOllamaMessage(m: ChatMessage): Record<string, unknown> {
   }
   return message;
 }
-
-function randomId(): string {
-  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}

package/nugget/src/adapters/engines/openaiChat.ts

@@ -1,10 +1,10 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
-import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, EmbedRequest, EmbedResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
 import type { ProviderProfile } from '../profiles.js';
-import { health, listOpenModels, streamError, streamTimeout } from './base.js';
+import { DEFAULT_TIMEOUT_MS, health, listOpenModels, parseArgs, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 
 export class OpenAIChatAdapter implements ProviderAdapter {
   readonly provider: string;
@@ -34,7 +34,7 @@ export class OpenAIChatAdapter implements ProviderAdapter {
     const timeout = streamTimeout(conn, req.signal);
     yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
     try {
-      const res = await postResponse(urlFor(conn, this.profile, req.model), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+      const res = await postResponse(urlFor(conn, this.profile, req), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
       const contentType = res.headers.get('content-type') ?? '';
       if (!contentType.includes('text/event-stream')) {
         // Server ignored stream:true (or is a buffered gateway) — recover the whole body.
@@ -47,11 +47,13 @@ export class OpenAIChatAdapter implements ProviderAdapter {
         outputTokens = parsed.outputTokens;
         finish = parsed.finish;
         sawTerminal = true;
+        if (parsed.reasoning) yield { type: 'reasoning', text: parsed.reasoning };
         if (text) yield { type: 'delta', text };
         for (const call of toolCalls) yield { type: 'tool_call', call };
       } else {
         const partialTools = new Map<number, { id?: string; name?: string; raw: string }>();
         for await (const line of sseLines(res)) {
+          timeout.bump();
           const chunk = safeParse(line);
           const record = asRecord(chunk);
           if (!record) continue;
@@ -63,6 +65,10 @@ export class OpenAIChatAdapter implements ProviderAdapter {
           finish = asString(choice?.finish_reason) ?? finish;
           if (choice?.finish_reason) sawTerminal = true;
           const delta = asRecord(choice?.delta);
+          // Reasoning tokens (DeepSeek `reasoning_content`, others `reasoning`)
+          // ride their own channel so they don't contaminate the answer text.
+          const reasoning = asString(delta?.reasoning_content) ?? asString(delta?.reasoning);
+          if (reasoning) yield { type: 'reasoning', text: reasoning };
           const piece = asString(delta?.content);
           if (piece) {
             if (firstTokenMs === null) firstTokenMs = Date.now() - started;
@@ -89,9 +95,7 @@ export class OpenAIChatAdapter implements ProviderAdapter {
         }));
         for (const call of toolCalls) yield { type: 'tool_call', call };
       }
-      if (!sawTerminal) {
-        yield { type: 'context', kind: 'stream_anomaly', data: { reason: 'stream ended without a finish_reason' } };
-      }
+      if (!sawTerminal) yield streamAnomaly('stream ended without a finish_reason');
       const result = makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens);
       yield { type: 'done', result };
     } catch (error) {
@@ -108,6 +112,36 @@ export class OpenAIChatAdapter implements ProviderAdapter {
   health(conn: ResolvedConnection) {
     return health(conn, this.profile);
   }
+
+  async embed(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult> {
+    const inputs = Array.isArray(req.input) ? req.input : [req.input];
+    const { data } = await fetchJson(joinUrl(conn.baseUrl, '/embeddings'), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...conn.headers },
+      body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+      timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      provider: conn.provider,
+    });
+    const record = asRecord(data);
+    const rows = Array.isArray(record?.data) ? record.data : [];
+    // Order by the `index` each row reports, falling back to array order.
+    const byIndex = rows
+      .map((row, i) => ({ index: asNumber(asRecord(row)?.index) ?? i, embedding: asEmbedding(asRecord(row)?.embedding) }))
+      .sort((a, b) => a.index - b.index);
+    const usage = asRecord(record?.usage);
+    const inputTokens = asNumber(usage?.prompt_tokens);
+    return {
+      embeddings: byIndex.map((row) => row.embedding),
+      model: req.model,
+      usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+      source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+      raw: data,
+    };
+  }
+}
+
+function asEmbedding(value: unknown): number[] {
+  return Array.isArray(value) ? value.filter((n): n is number => typeof n === 'number') : [];
 }
 
 function openAiBody(req: ChatRequest, profile: ProviderProfile): Record<string, unknown> {
@@ -127,7 +161,12 @@ function openAiBody(req: ChatRequest, profile: ProviderProfile): Record<string,
     stream_options: profile.quirks?.supportsUsageInStream ? { include_usage: true } : undefined,
   };
   if (req.maxTokens !== undefined) body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
-  return body;
+  // providerOptions carries OpenAI-native fields the nugget doesn't model
+  // (`reasoning_effort`, `parallel_tool_calls`, `seed`, `logprobs`, …). `apiVersion`
+  // is consumed by urlFor for Azure and stripped here so it never hits the body.
+  const { apiVersion, ...passthrough } = req.providerOptions ?? {};
+  void apiVersion;
+  return applyProviderOptions(body, Object.keys(passthrough).length ? passthrough : undefined);
 }
 
 function responseFormatFor(req: ChatRequest, profile: ProviderProfile): Record<string, unknown> | undefined {
@@ -152,22 +191,31 @@ function toOpenAiMessage(message: ChatMessage): Record<string, unknown> {
   };
 }
 
-function urlFor(conn: ResolvedConnection, profile: ProviderProfile, model: string): string {
+function urlFor(conn: ResolvedConnection, profile: ProviderProfile, req: ChatRequest): string {
   if (profile.quirks?.urlTemplate) {
-    return profile.quirks.urlTemplate.replace('{baseUrl}', conn.baseUrl).replace('{model}', encodeURIComponent(model));
+    // `{apiVersion}` (Azure) is filled from a per-call override, then the
+    // profile default — so a retired Azure api-version is fixable without a
+    // library release: pass `providerOptions: { apiVersion: '2025-01-01-preview' }`.
+    const apiVersion = asString(req.providerOptions?.apiVersion) ?? profile.quirks.apiVersion ?? '';
+    return profile.quirks.urlTemplate
+      .replace('{baseUrl}', conn.baseUrl)
+      .replace('{model}', encodeURIComponent(req.model))
+      .replace('{apiVersion}', apiVersion);
   }
-  return `${conn.baseUrl}/chat/completions`;
+  return joinUrl(conn.baseUrl, '/chat/completions');
 }
 
-function parseOpenAiResponse(raw: unknown): { text: string; toolCalls: ToolCall[]; inputTokens?: number; outputTokens?: number; finish?: string } {
+function parseOpenAiResponse(raw: unknown): { text: string; reasoning?: string; toolCalls: ToolCall[]; inputTokens?: number; outputTokens?: number; finish?: string } {
   const record = asRecord(raw);
   const usage = asRecord(record?.usage);
   const choice = asRecord(Array.isArray(record?.choices) ? record.choices[0] : undefined);
   const message = asRecord(choice?.message);
   const text = asString(message?.content) ?? asString(record?.text) ?? '';
+  const reasoning = asString(message?.reasoning_content) ?? asString(message?.reasoning);
   const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
   return {
     text,
+    reasoning,
     finish: asString(choice?.finish_reason),
     toolCalls: calls.map((value) => {
       const call = asRecord(value);
@@ -202,22 +250,3 @@ function mapFinish(finish: string | undefined, hasToolCalls: boolean): ChatResul
   return 'stop';
 }
 
-function parseArgs(raw: string): unknown {
-  try {
-    return raw ? JSON.parse(raw) as unknown : {};
-  } catch {
-    return {};
-  }
-}
-
-function safeParse(line: string): unknown {
-  try {
-    return JSON.parse(line) as unknown;
-  } catch {
-    return undefined;
-  }
-}
-
-function randomId(): string {
-  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}