@jxburros/ai-nugget 0.4.1 → 0.7.0

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,16 @@ 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 } })),
   };
+  // First-class reasoning effort → Ollama's `think` flag (reasoning arrives in
+  // `message.thinking`, which this engine already routes to `reasoning` events).
+  // Ollama has no graded effort for most models, so anything but `'none'` is
+  // `true`. Only sent when asked for: a model without thinking support rejects it.
+  if (req.reasoningEffort !== undefined) base.think = req.reasoningEffort !== 'none';
+  // 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 +190,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,32 @@ 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);
+      let res: Response;
+      try {
+        res = await postResponse(urlFor(conn, this.profile, req), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+      } catch (error) {
+        // OpenAI's `/chat/completions` refuses function tools on a reasoning model
+        // unless `reasoning_effort` is `'none'` ("Function tools with reasoning_effort
+        // are not supported … use /v1/responses or set reasoning_effort to 'none'").
+        // The nugget never sets `reasoning_effort` itself, so the provider default
+        // applies and every tool-using turn 400s. Rather than make each app learn
+        // this the hard way, retry the one request once with the effort disabled
+        // and say so on the stream. Reactive on purpose: sending
+        // `reasoning_effort` up front would 400 on non-reasoning models instead.
+        // A caller-requested effort is overridden too — the alternative is a hard
+        // 400 with no tool call at all — and the context event says so.
+        if (!shouldRetryWithoutReasoningEffort(error, req)) throw error;
+        yield {
+          type: 'context',
+          kind: 'reasoning_effort_disabled_for_tools',
+          data: {
+            reason: 'provider rejected function tools with reasoning_effort; retried with reasoning_effort: none',
+            requested: req.providerOptions?.reasoning_effort ?? req.reasoningEffort ?? null,
+          },
+        };
+        const retryReq: ChatRequest = { ...req, providerOptions: { ...req.providerOptions, reasoning_effort: 'none' } };
+        res = await postResponse(urlFor(conn, this.profile, retryReq), openAiBody(retryReq, 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 +72,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 +90,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 +120,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 +137,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 +186,15 @@ 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;
+  // First-class reasoning effort → OpenAI's `reasoning_effort`. Only sent when
+  // asked for: non-reasoning models reject the parameter outright.
+  if (req.reasoningEffort !== undefined) body.reasoning_effort = req.reasoningEffort;
+  // 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 +219,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 +278,20 @@ 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)}`;
+/**
+ * True when a `/chat/completions` 400 is the "function tools with reasoning_effort
+ * are not supported" refusal AND the request actually carried tools AND the caller
+ * did not already pin `reasoning_effort` (in which case the choice is theirs).
+ */
+export function shouldRetryWithoutReasoningEffort(error: unknown, req: ChatRequest): boolean {
+  if (!(error instanceof AIError) || error.status !== 400) return false;
+  if (!req.tools || req.tools.length === 0) return false;
+  // Already `'none'` (from either knob) — the refusal is about something else.
+  const effective = req.providerOptions && 'reasoning_effort' in req.providerOptions
+    ? req.providerOptions.reasoning_effort
+    : req.reasoningEffort;
+  if (effective === 'none') return false;
+  const text = `${error.raw ?? ''} ${error.message}`.toLowerCase();
+  return text.includes('reasoning_effort') && text.includes('tool');
 }

package/nugget/src/adapters/profiles.ts

@@ -34,6 +34,20 @@ export interface ProviderProfile {
     maxTokensRequired?: boolean;
     maxTokensParam?: 'max_tokens' | 'max_completion_tokens';
     supportsJsonSchema?: boolean;
+    /**
+     * Default value for the `{apiVersion}` token in `urlTemplate` (Azure OpenAI).
+     * Overridable per call via `ChatRequest.providerOptions.apiVersion`, so a
+     * retired Azure api-version never requires a library release.
+     */
+    apiVersion?: string;
+    /**
+     * Provider honors an `Idempotency-Key` request header. When set, the handler
+     * attaches one key per logical call and reuses it across retries, so a retry
+     * after a connection drops post-generation is deduped by the provider rather
+     * than billed twice. Left off unless the provider documents the header —
+     * sending an unknown header is harmless, but claiming the guarantee is not.
+     */
+    supportsIdempotencyKey?: boolean;
   };
   listModelsPath?: string;
   healthPath?: string;
@@ -42,20 +56,46 @@ export interface ProviderProfile {
 const HOSTED_CLOUD: ProviderCapabilities = { nativeTools: true, jsonMode: true, local: false, embeddable: false };
 const LOCAL_RUNTIME: ProviderCapabilities = { nativeTools: false, jsonMode: false, local: true, embeddable: true };
 
-export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
+/**
+ * The provider keys that have a profile in {@link PROVIDER_PROFILES}. Used to
+ * type `Connection.provider` so IDEs autocomplete valid names and typos are a
+ * compile error rather than a silent fall-through to `openai-compat`.
+ */
+export type KnownProvider =
+  | 'openai'
+  | 'azure-openai'
+  | 'openrouter'
+  | 'groq'
+  | 'deepseek'
+  | 'mistral'
+  | 'together'
+  | 'fireworks'
+  | 'cerebras'
+  | 'moonshot'
+  | 'cohere'
+  | 'perplexity'
+  | 'lmstudio'
+  | 'llamacpp'
+  | 'vllm'
+  | 'ollama'
+  | 'anthropic'
+  | 'google'
+  | 'openai-compat';
+
+export const PROVIDER_PROFILES: Record<KnownProvider, ProviderProfile> & Record<string, ProviderProfile> = {
   openai: {
     engine: 'openaiChat',
     defaultBaseUrl: 'https://api.openai.com/v1',
     auth: 'bearer',
     listModelsPath: '/models',
     capabilities: HOSTED_CLOUD,
-    quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+    quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true, supportsIdempotencyKey: true },
   },
   'azure-openai': {
     engine: 'openaiChat',
     auth: 'api-key-header',
     capabilities: HOSTED_CLOUD,
-    quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version=2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+    quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version={apiVersion}', apiVersion: '2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
   },
   openrouter: {
     engine: 'openaiChat',
@@ -71,6 +111,12 @@ export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
   mistral: { engine: 'openaiChat', defaultBaseUrl: 'https://api.mistral.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
   together: { engine: 'openaiChat', defaultBaseUrl: 'https://api.together.xyz/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
   fireworks: { engine: 'openaiChat', defaultBaseUrl: 'https://api.fireworks.ai/inference/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  cerebras: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cerebras.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  moonshot: { engine: 'openaiChat', defaultBaseUrl: 'https://api.moonshot.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  // Cohere's OpenAI-compatible surface lives under /compatibility/v1.
+  cohere: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cohere.ai/compatibility/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  // Perplexity has no public model-listing endpoint, so listModels resolves empty.
+  perplexity: { engine: 'openaiChat', defaultBaseUrl: 'https://api.perplexity.ai', auth: 'bearer', capabilities: HOSTED_CLOUD },
   lmstudio: {
     engine: 'openaiChat',
     defaultBaseUrl: 'http://localhost:1234/v1',
@@ -128,6 +174,10 @@ export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
     // Unknown endpoint — usually pointed at a local/self-hosted server, so
     // assume the conservative local-runtime defaults rather than the hosted-cloud ones.
     capabilities: LOCAL_RUNTIME,
+    // Most servers reached through this escape hatch (JX Runtime and other
+    // local OpenAI-compatible runtimes) don't require a key at all; keep
+    // `auth: 'bearer'` for the ones that do (a key is only sent if provided).
+    quirks: { keyOptional: true },
   },
 };