@jxburros/ai-nugget 0.3.1 → 0.6.0

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 },
   },
 };
 

package/nugget/src/agent/loop.ts

@@ -3,8 +3,8 @@ import { AIError } from '../errors.js';
 import { extractJson } from '../json.js';
 import { mergeUsage } from '../tokens.js';
 import type { AIHandler } from '../handler.js';
-import type { ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
-import { sleep } from '../util.js';
+import type { AIErrorKind, ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import { asRecord, sleep } from '../util.js';
 import type { ToolSpec } from './tools.js';
 import { validateToolArgs } from './tools.js';
 
@@ -25,12 +25,40 @@ export interface AgentOptions {
    * dependent, not protocol-guaranteed.
    */
   toolMode?: 'native' | 'promptJson' | 'auto';
+  /**
+   * Discovered capabilities of the specific model (e.g. Ollama `/api/show`
+   * `["tools"]`). When `toolMode` is `auto`, a `tools` capability here upgrades a
+   * local model to `native` tool-calling instead of the profile's conservative
+   * `promptJson` default — so a capable local model isn't forced onto the fallback.
+   */
+  modelCapabilities?: string[];
+  /** Sampler/decoding options forwarded to every model turn (parity with a plain chat call). */
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  stopSequences?: string[];
+  /** Provider-native passthrough forwarded to every turn — see {@link ChatRequest.providerOptions}. */
+  providerOptions?: Record<string, unknown>;
   budget?: {
     maxSteps?: number;
     maxTokens?: number;
     deadlineMs?: number;
   };
   approval?: ApprovalGate;
+  /**
+   * Which tools require the approval gate. `sideEffectsOnly` (default) gates only
+   * tools declared `sideEffects: true`; `all` gates every tool — so `tool_denied`
+   * is reachable without marking each tool, and a consumer can require approval
+   * for a whole run in one place.
+   */
+  approvalMode?: 'sideEffectsOnly' | 'all';
+  /**
+   * Bounds and framing applied to each tool result before it re-enters the
+   * model's context. `maxChars` truncates oversized results (with a notice) so a
+   * single large return can't blow the next turn's window; `wrapUntrusted` fences
+   * the result in an `<untrusted_tool_output>` envelope. Both are opt-in.
+   */
+  toolResult?: { maxChars?: number; wrapUntrusted?: boolean };
   onEvent?: (e: AgentEvent) => void;
   signal?: AbortSignal;
   metadata?: Record<string, unknown>;
@@ -45,6 +73,9 @@ export type ApprovalGate = (req: {
 export type AgentEvent =
   | StreamEvent
   | { type: 'step_start'; step: number }
+  // Discloses which tool-calling protocol this run resolved to, so a
+  // `promptJson` fallback is visible rather than silent.
+  | { type: 'tool_mode'; mode: 'native' | 'promptJson' }
   | { type: 'tool_start'; step: number; call: ToolCall }
   | { type: 'tool_result'; step: number; call: ToolCall; result: unknown; isError: boolean }
   | { type: 'tool_denied'; step: number; call: ToolCall; reason: string }
@@ -56,6 +87,11 @@ export interface AgentResult {
   usage: Usage;
   steps: number;
   stopReason: 'finished' | 'max_steps' | 'budget' | 'deadline' | 'canceled' | 'error';
+  /**
+   * Populated when `stopReason` is `error`: the failure that ended the run, so
+   * the caller can see what went wrong without replaying the event stream.
+   */
+  error?: { kind: AIErrorKind; message: string };
 }
 
 export function runAgent(opts: AgentOptions): AsyncIterable<AgentEvent> & { result: Promise<AgentResult> } {
@@ -77,6 +113,10 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
   let step = 0;
   let settled = false;
 
+  // Disclose the resolved tool protocol once up front (a silent promptJson
+  // fallback was the friction behind FR‑2).
+  yield emit(opts, { type: 'tool_mode', mode: toolMode });
+
   try {
     while (step < maxSteps) {
       step += 1;
@@ -86,15 +126,31 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
       const calls: ToolCall[] = [];
       let stepText = '';
       let streamFailure: AIError | undefined;
+      // In promptJson mode a tool directive must not leak into the visible
+      // stream, so directive-looking text is withheld from `delta` events (still
+      // accumulated in `stepText` for parsing). Prose streams normally.
+      const filter = toolMode === 'promptJson' ? new PromptJsonDeltaFilter() : undefined;
       const requestMessages = toolMode === 'promptJson' ? withPromptJsonInstruction(messages, opts.tools) : messages;
       for await (const event of opts.handler.stream(opts.connection, {
         model: opts.model,
         messages: requestMessages,
         tools: toolMode === 'promptJson' ? undefined : opts.tools,
+        temperature: opts.temperature,
+        maxTokens: opts.maxTokens,
+        topP: opts.topP,
+        stopSequences: opts.stopSequences,
+        providerOptions: opts.providerOptions,
         signal: agentSignal.signal,
         metadata: { ...opts.metadata, agentStep: step },
       })) {
-        if (event.type === 'delta') stepText += event.text;
+        if (event.type === 'delta') {
+          stepText += event.text;
+          if (filter) {
+            const visible = filter.push(event.text);
+            if (visible) yield emit(opts, { type: 'delta', text: visible });
+            continue;
+          }
+        }
         if (event.type === 'tool_call') calls.push(event.call);
         if (event.type === 'error') streamFailure = event.error;
         if (event.type === 'done') {
@@ -103,10 +159,16 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
         }
         yield emit(opts, event);
       }
+      // If withheld text turned out not to be a real directive, flush it so the
+      // user still sees the model's answer.
+      if (filter && calls.length === 0) {
+        const flushed = filter.flush();
+        if (flushed) yield emit(opts, { type: 'delta', text: flushed });
+      }
 
       // A handler-level failure (auth, policy, cancel, exhausted retries) must
       // stop the loop honestly rather than looking like an empty completion.
-      if (streamFailure) return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : streamFailure.kind === 'canceled' ? 'canceled' : 'error');
+      if (streamFailure) return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : streamFailure.kind === 'canceled' ? 'canceled' : 'error', errorInfo(streamFailure));
 
       finalText = stepText;
       messages.push(toolMode === 'promptJson'
@@ -127,7 +189,8 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
           continue;
         }
         let args = validation.args;
-        if (tool.sideEffects) {
+        const requiresApproval = tool.sideEffects || opts.approvalMode === 'all';
+        if (requiresApproval) {
           if (!opts.approval) {
             yield* appendToolDenied(opts, messages, step, call, 'No approval gate configured');
             continue;
@@ -165,8 +228,16 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
           continue;
         }
         try {
-          messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: JSON.stringify(executed.result) });
-          yield emit(opts, { type: 'tool_result', step, call, result: executed.result, isError: false });
+          // Guard against a tool returning `undefined` (JSON.stringify(undefined)
+          // is the value `undefined`, not a string) — an unguarded value here
+          // used to crash the next step's message mapper and kill the whole run.
+          const serialized = JSON.stringify(executed.result) ?? 'null';
+          messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: formatToolResult(serialized, opts.toolResult) });
+          // A tool that returns a structured `{ ok: false, ... }` is a recoverable
+          // error the model should react to — surface it as an error result.
+          const record = asRecord(executed.result);
+          const isError = record?.ok === false;
+          yield emit(opts, { type: 'tool_result', step, call, result: executed.result, isError });
         } catch (error) {
           const message = error instanceof Error ? error.message : 'Tool result was not serializable';
           yield* appendToolError(opts, messages, step, call, message);
@@ -179,7 +250,8 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
     }
     return yield* yieldDone('max_steps');
   } catch (error) {
-    const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, agentSignal.timedOut() ? 'deadline' : (agentSignal.signal?.aborted || (error instanceof AIError && error.kind === 'canceled')) ? 'canceled' : 'error');
+    const stopReason = agentSignal.timedOut() ? 'deadline' : (agentSignal.signal?.aborted || (error instanceof AIError && error.kind === 'canceled')) ? 'canceled' : 'error';
+    const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason, stopReason === 'error' ? errorInfo(error) : undefined);
     settled = true;
     resolveResult(result);
     yield emit(opts, { type: 'agent_done', result });
@@ -191,8 +263,8 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
     }
   }
 
-  function* yieldDone(stopReason: AgentResult['stopReason']): Generator<AgentEvent> {
-    const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason);
+  function* yieldDone(stopReason: AgentResult['stopReason'], error?: AgentResult['error']): Generator<AgentEvent> {
+    const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason, error);
     settled = true;
     resolveResult(result);
     yield emit(opts, { type: 'agent_done', result });
@@ -204,8 +276,68 @@ function emit<T extends AgentEvent>(opts: AgentOptions, event: T): T {
   return event;
 }
 
-function makeResult(finalText: string, messages: ChatMessage[], usage: Usage, steps: number, stopReason: AgentResult['stopReason']): AgentResult {
-  return { finalText, messages, usage, steps, stopReason };
+function makeResult(finalText: string, messages: ChatMessage[], usage: Usage, steps: number, stopReason: AgentResult['stopReason'], error?: AgentResult['error']): AgentResult {
+  return error ? { finalText, messages, usage, steps, stopReason, error } : { finalText, messages, usage, steps, stopReason };
+}
+
+function errorInfo(error: unknown): { kind: AIErrorKind; message: string } {
+  if (error instanceof AIError) return { kind: error.kind, message: error.message };
+  return { kind: 'tool_error', message: error instanceof Error ? error.message : 'Agent run failed' };
+}
+
+/**
+ * Applies the optional size cap and untrusted-content framing to a serialized
+ * tool result before it re-enters the model's context.
+ */
+function formatToolResult(serialized: string, opts: AgentOptions['toolResult']): string {
+  let out = serialized;
+  const max = opts?.maxChars;
+  if (max !== undefined && out.length > max) {
+    out = `${out.slice(0, max)}\n…[truncated ${out.length - max} chars]`;
+  }
+  if (opts?.wrapUntrusted) {
+    out = `<untrusted_tool_output>\n${out}\n</untrusted_tool_output>`;
+  }
+  return out;
+}
+
+/**
+ * Withholds a promptJson tool directive from the visible `delta` stream. Once
+ * the leading non-whitespace character is known: a `{`, `[`, or fence marks a
+ * directive candidate whose text is buffered (never streamed); anything else is
+ * prose that streams through untouched. `flush()` returns any buffered text when
+ * the stream ended without yielding a parsed directive.
+ */
+class PromptJsonDeltaFilter {
+  private decided = false;
+  private withhold = false;
+  private buffer = '';
+
+  push(text: string): string {
+    if (!this.decided) {
+      this.buffer += text;
+      const lead = this.buffer.replace(/^\s+/, '');
+      if (lead.length === 0) return '';
+      this.decided = true;
+      this.withhold = /^[[{`]/.test(lead);
+      if (this.withhold) return '';
+      const flushed = this.buffer;
+      this.buffer = '';
+      return flushed;
+    }
+    if (this.withhold) {
+      this.buffer += text;
+      return '';
+    }
+    return text;
+  }
+
+  flush(): string {
+    if (!this.withhold) return '';
+    const out = this.buffer;
+    this.buffer = '';
+    return out;
+  }
 }
 
 function* appendToolError(opts: AgentOptions, messages: ChatMessage[], step: number, call: ToolCall, message: string): Generator<AgentEvent> {
@@ -222,14 +354,22 @@ function* appendToolDenied(opts: AgentOptions, messages: ChatMessage[], step: nu
 function resolveToolMode(opts: AgentOptions): 'native' | 'promptJson' {
   const mode = opts.toolMode ?? 'auto';
   if (mode !== 'auto') return mode;
+  // A model that actually advertises tool support gets native tool-calling even
+  // on a local runtime whose profile is conservatively `nativeTools: false`.
+  if (opts.modelCapabilities?.includes('tools')) return 'native';
   return profileFor(opts.connection.provider, opts.connection.baseUrl).capabilities.nativeTools ? 'native' : 'promptJson';
 }
 
 function withPromptJsonInstruction(messages: ChatMessage[], tools: ToolSpec[]): ChatMessage[] {
+  // Include each tool's parameter schema, not just its description, so the model
+  // knows the argument shape instead of guessing it (FR‑3).
+  const catalog = tools
+    .map((tool) => `- ${tool.name}: ${tool.description}\n  parameters: ${JSON.stringify(tool.parameters)}`)
+    .join('\n');
   return [
     {
       role: 'system',
-      content: `When you need tools, respond only with JSON. For one tool: {"tool":"name","input":{...}}. For several in one turn: {"tools":[{"tool":"name","input":{...}}]}. Available tools: ${tools.map((tool) => `${tool.name}: ${tool.description}`).join('; ')}`,
+      content: `When you need tools, respond only with JSON. For one tool: {"tool":"name","input":{...}}. For several in one turn: {"tools":[{"tool":"name","input":{...}}]}. The "input" object must match the tool's parameters schema. Available tools:\n${catalog}`,
     },
     ...messages.map(toPromptJsonMessage),
   ];
@@ -268,7 +408,7 @@ function callsFromPromptJson(text: string): ToolCall[] {
     const record = entry as Record<string, unknown>;
     if (typeof record.tool !== 'string') continue;
     calls.push({
-      id: crypto.randomUUID(),
+      id: randomId(),
       name: record.tool,
       arguments: record.input && typeof record.input === 'object' ? record.input : {},
       raw: JSON.stringify(record.input ?? {}),
@@ -277,6 +417,10 @@ function callsFromPromptJson(text: string): ToolCall[] {
   return calls;
 }
 
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
 function textContent(content: ChatMessage['content']): string {
   if (typeof content === 'string') return content;
   if (!content) return '';

package/nugget/src/connect.ts

@@ -0,0 +1,48 @@
+import type { Connection } from './types.js';
+import { globalEnv } from './util.js';
+
+export interface EnvConnectionOptions {
+  /** Read from this env-like object instead of the process/global environment. */
+  env?: Record<string, string | undefined>;
+  /** Connection id. Defaults to `'app'`. */
+  id?: string;
+  /** Env var names to read (override if an app already uses different names). */
+  providerVar?: string;
+  modelVar?: string;
+  keyEnvVar?: string;
+  baseUrlVar?: string;
+  /** Fallbacks used when the corresponding env var is unset. */
+  defaultProvider?: string;
+  defaultModel?: string;
+  defaultKeyEnv?: string;
+}
+
+export interface EnvConnection {
+  connection: Connection;
+  model: string;
+}
+
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export function envConnection(options: EnvConnectionOptions = {}): EnvConnection {
+  const env = options.env ?? globalEnv();
+  const provider = env[options.providerVar ?? 'AI_PROVIDER']?.trim() || options.defaultProvider || 'openai';
+  const model = env[options.modelVar ?? 'AI_MODEL']?.trim() || options.defaultModel || 'gpt-4o-mini';
+  const keyEnvName = env[options.keyEnvVar ?? 'AI_KEY_ENV']?.trim() || options.defaultKeyEnv || 'OPENAI_API_KEY';
+  const baseUrl = env[options.baseUrlVar ?? 'AI_BASE_URL']?.trim();
+
+  const connection: Connection = {
+    id: options.id ?? 'app',
+    provider,
+    keyRef: { kind: 'env', name: keyEnvName },
+    ...(baseUrl ? { baseUrl } : {}),
+  };
+  return { connection, model };
+}

package/nugget/src/errors.ts

@@ -1,5 +1,15 @@
+import { createDefaultRedactor } from './redact.js';
 import type { AIErrorKind } from './types.js';
 
+/**
+ * Pattern-based redaction applied at the wire boundary, before an error object
+ * exists. `AIHandler` redacts again on the way out (adding session-registered
+ * exact secrets), but doing it here means a provider body that echoes a
+ * recognizable secret can never be carried by an `AIError` in the first place —
+ * including on code paths that never reach the handler's own catch blocks.
+ */
+const wireRedactor = createDefaultRedactor();
+
 export class AIError extends Error {
   kind: AIErrorKind;
   status?: number;
@@ -34,9 +44,13 @@ export function defaultRetryable(kind: AIErrorKind): boolean {
 }
 
 export function classify(status: number, body = '', provider?: string, headers?: Headers): AIError {
-  const excerpt = body.slice(0, 200);
+  const excerpt = wireRedactor.redact(body.slice(0, 200));
   const lower = body.toLowerCase();
   let kind: AIErrorKind = 'server';
+  // 403 is classified as `auth` (non-retryable) deliberately: a forbidden
+  // response almost always means a bad/insufficient credential or a blocked
+  // region/model, none of which a retry fixes. Callers that know a specific
+  // provider returns a retryable 403 can reclassify in a `beforeCall`/adapter.
   if (status === 401 || status === 403) kind = 'auth';
   else if (status === 408) kind = 'timeout';
   else if (status === 429) kind = 'rate_limit';
@@ -44,7 +58,17 @@ export function classify(status: number, body = '', provider?: string, headers?:
     kind = lower.includes('context') || lower.includes('maximum context') || lower.includes('token limit')
       ? 'context_length'
       : 'invalid_request';
+  } else if (status === 404 || status === 410) {
+    // A missing route/deployment is not a malformed request: it is usually a
+    // wrong baseUrl or model name, and sometimes a temporarily misrouted load
+    // balancer. `not_found` keeps it distinguishable from `invalid_request` so
+    // apps don't tell a user "your request was invalid" for an infra problem.
+    // Non-retryable by default — a caller that knows its 404s are transient can
+    // retry on `kind === 'not_found'` itself.
+    kind = 'not_found';
   } else if (status >= 500) kind = 'server';
+  // Everything else in 4xx (409 conflict, 405, 415, 451, …) is a genuine
+  // client-side request problem, so `invalid_request` is honest for it.
   else kind = 'invalid_request';
 
   return new AIError(`HTTP ${status}: ${excerpt}`, {