jeo-code 0.1.0

package/src/ai/model-picker.ts

@@ -0,0 +1,73 @@
+/**
+ * Model picker — turn a live discovery result set into a flat, 1-based pick list
+ * so the TUI can select a model by number (`/model #3`) or by a fuzzy substring
+ * (`/model gpt-4`). Pure functions over `ProviderModelsResult[]`, so they are
+ * fully unit-testable and shared by `/model`, `/models`, and `/provider`.
+ */
+import type { ProviderModelsResult } from "./model-discovery";
+import type { ProviderName } from "./types";
+
+export interface PickEntry {
+  index: number; // 1-based position in the flattened list
+  provider: ProviderName;
+  model: string;
+}
+
+/** Flatten successful discovery results into an ordered, 1-based pick list. */
+export function flattenModels(results: ProviderModelsResult[]): PickEntry[] {
+  const out: PickEntry[] = [];
+  for (const r of results) {
+    if (!r.ok) continue;
+    for (const model of r.models) {
+      out.push({ index: out.length + 1, provider: r.provider, model });
+    }
+  }
+  return out;
+}
+
+/** Parse a `#N` selection token into a 1-based index, else null. */
+export function parsePickToken(token: string): number | null {
+  const m = token.trim().match(/^#(\d+)$/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return n >= 1 ? n : null;
+}
+
+/** Resolve a 1-based index into a pick entry, or undefined when out of range. */
+export function pickByIndex(flat: PickEntry[], n: number): PickEntry | undefined {
+  return flat[n - 1];
+}
+
+/** Case-insensitive substring match over the flat model ids. */
+export function matchModels(flat: PickEntry[], query: string): PickEntry[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  return flat.filter(e => e.model.toLowerCase().includes(q));
+}
+
+export type Selection =
+  | { kind: "index"; entry: PickEntry }
+  | { kind: "match"; entry: PickEntry }
+  | { kind: "ambiguous"; matches: PickEntry[] }
+  | { kind: "out-of-range"; max: number }
+  | { kind: "none" };
+
+/**
+ * Resolve a selection token against the flat list:
+ * - `#N` → exact index (or out-of-range)
+ * - substring → unique match, ambiguous (multiple), or none
+ */
+export function resolveSelection(flat: PickEntry[], token: string): Selection {
+  const idx = parsePickToken(token);
+  if (idx !== null) {
+    const entry = pickByIndex(flat, idx);
+    return entry ? { kind: "index", entry } : { kind: "out-of-range", max: flat.length };
+  }
+  // Exact id match wins over substring.
+  const exact = flat.find(e => e.model === token);
+  if (exact) return { kind: "match", entry: exact };
+  const matches = matchModels(flat, token);
+  if (matches.length === 1) return { kind: "match", entry: matches[0] };
+  if (matches.length > 1) return { kind: "ambiguous", matches };
+  return { kind: "none" };
+}

package/src/ai/model-registry.ts

@@ -0,0 +1,83 @@
+import { readGlobalConfig } from "../agent/state";
+import { findCatalogEntry } from "./model-catalog-compat";
+
+export interface ModelAliases {
+  [alias: string]: string;
+}
+
+// Built-in aliases (used when config has none for that key).
+export const BUILTIN_ALIASES: ModelAliases = {
+  fast: "ollama/qwen2.5:0.5b",
+  local: "ollama/qwen2.5:0.5b",
+  sonnet: "claude-3-5-sonnet",
+  gpt: "gpt-4o",
+  flash: "gemini-2.5-flash",
+};
+
+// Expand an alias to a concrete model id. Unknown input passes through unchanged.
+export function expandAlias(input: string, aliases: ModelAliases = BUILTIN_ALIASES): string {
+  if (Object.prototype.hasOwnProperty.call(aliases, input)) {
+    return aliases[input];
+  }
+  return input;
+}
+
+// Async: merge BUILTIN_ALIASES with config.modelAliases (config wins) and expand.
+export async function resolveModelId(input: string): Promise<string> {
+  const config = await readGlobalConfig();
+  const modelAliases = (config as any).modelAliases ?? {};
+  const merged: ModelAliases = { ...BUILTIN_ALIASES, ...modelAliases };
+  return expandAlias(input, merged);
+}
+
+// List effective aliases (builtin + config).
+export async function listAliases(): Promise<ModelAliases> {
+  const config = await readGlobalConfig();
+  const modelAliases = (config as any).modelAliases ?? {};
+  return { ...BUILTIN_ALIASES, ...modelAliases };
+}
+
+/** Alias names (sorted) whose target resolves to `id`. Reverse of `expandAlias`. */
+export function aliasesFor(id: string, aliases: ModelAliases = BUILTIN_ALIASES): string[] {
+  return Object.entries(aliases)
+    .filter(([, target]) => target === id)
+    .map(([alias]) => alias)
+    .sort();
+}
+
+/** True when `input` is a defined alias (not a concrete model id). */
+export function isAlias(input: string, aliases: ModelAliases = BUILTIN_ALIASES): boolean {
+  return Object.prototype.hasOwnProperty.call(aliases, input);
+}
+
+export interface AliasDescription {
+  alias: string;
+  target: string;
+  isAlias: boolean;
+  /** True when the target is a known catalog model id. */
+  knownTarget: boolean;
+}
+
+/** Describe an alias: its target + whether the target is a known catalog model. */
+export function describeAlias(input: string, aliases: ModelAliases = BUILTIN_ALIASES): AliasDescription {
+  const defined = isAlias(input, aliases);
+  const target = defined ? aliases[input]! : input;
+  return { alias: input, target, isAlias: defined, knownTarget: !!findCatalogEntry(target) };
+}
+
+/**
+ * Validate an alias table: flag aliases whose target is not a known catalog
+ * model (advisory — uncatalogued targets still work, but a typo usually shows up
+ * here). Returns only the suspicious entries.
+ */
+export function validateAliases(aliases: ModelAliases): { alias: string; target: string }[] {
+  return Object.entries(aliases)
+    .filter(([, target]) => !findCatalogEntry(target))
+    .map(([alias, target]) => ({ alias, target }))
+    .sort((a, b) => a.alias.localeCompare(b.alias));
+}
+
+/** Async: reverse-alias lookup against the effective (builtin + config) table. */
+export async function effectiveAliasesFor(id: string): Promise<string[]> {
+  return aliasesFor(id, await listAliases());
+}

package/src/ai/provider-status.ts

@@ -0,0 +1,77 @@
+/**
+ * Provider credential/status inventory — the shared source of truth behind
+ * `joc models`, the TUI `/provider` command, and `joc doctor`. Reports, for each
+ * provider, how it will authenticate (API key / OAuth / keyless / none), its
+ * effective base URL, and whether it is ready to serve a request.
+ */
+import { readGlobalConfig, type Config } from "../agent/state";
+import { resolveCredential, type AuthProvider } from "../auth";
+import type { ProviderName } from "./types";
+
+export const PROVIDER_NAMES: readonly ProviderName[] = ["anthropic", "openai", "gemini", "ollama"];
+
+/** Cloud providers that authenticate via API key / OAuth. Ollama is keyless. */
+export const CLOUD_PROVIDERS: readonly AuthProvider[] = ["anthropic", "openai", "gemini"];
+
+export type CredentialKind = "api_key" | "oauth" | "keyless" | "none";
+
+export interface ProviderStatus {
+  name: ProviderName;
+  kind: CredentialKind;
+  /** Display label, e.g. "API key", "OAuth", "keyless (local)", "none (run 'joc setup')". */
+  label: string;
+  /** Effective base URL when relevant (ollama / openai-compatible). */
+  baseUrl?: string;
+  /** Environment variable that would supply an API key, when applicable. */
+  envVar?: string;
+  /** True when the provider can serve a request right now. */
+  ready: boolean;
+}
+
+/** The uppercase `<PROVIDER>_API_KEY` env var name for a cloud provider. */
+export function providerEnvVar(name: ProviderName): string | undefined {
+  if (name === "ollama") return undefined;
+  return `${name.toUpperCase()}_API_KEY`;
+}
+
+/** Human label for a credential kind. */
+export function credentialLabel(kind: CredentialKind): string {
+  switch (kind) {
+    case "api_key":
+      return "API key";
+    case "oauth":
+      return "OAuth";
+    case "keyless":
+      return "keyless (local)";
+    case "none":
+      return "none (run 'joc setup' or 'joc auth login')";
+  }
+}
+
+/** Resolve the status of a single provider. */
+export async function describeProvider(name: ProviderName, config?: Config): Promise<ProviderStatus> {
+  const cfg = config ?? (await readGlobalConfig());
+  if (name === "ollama") {
+    const baseUrl = cfg.ollamaBaseUrl ?? "http://localhost:11434";
+    return { name, kind: "keyless", label: credentialLabel("keyless"), baseUrl, ready: true };
+  }
+  const cred = await resolveCredential(name as AuthProvider);
+  const kind: CredentialKind = cred.kind === "api_key" ? "api_key" : cred.kind === "oauth" ? "oauth" : "none";
+  const baseUrl = name === "openai" ? cfg.openaiBaseUrl : undefined;
+  // An OpenAI-compatible local server (LM Studio, vLLM) needs no key.
+  const ready = kind !== "none" || (name === "openai" && !!baseUrl);
+  return {
+    name,
+    kind,
+    label: ready && kind === "none" ? "keyless (local base URL)" : credentialLabel(kind),
+    baseUrl,
+    envVar: providerEnvVar(name),
+    ready,
+  };
+}
+
+/** Resolve the status of every provider (single config read). */
+export async function describeAllProviders(config?: Config): Promise<ProviderStatus[]> {
+  const cfg = config ?? (await readGlobalConfig());
+  return Promise.all(PROVIDER_NAMES.map(name => describeProvider(name, cfg)));
+}

package/src/ai/providers/anthropic.ts

@@ -0,0 +1,87 @@
+import type { Credential } from "../../auth";
+import type { CallOptions, Message, ProviderAdapter } from "../types";
+import { readSse } from "../sse";
+import { providerHttpError } from "./errors";
+
+const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+
+function anthropicPayload(messages: Message[], options: CallOptions, stream: boolean): string {
+  const resolvedModel = options.model.startsWith("anthropic/") ? options.model.slice(10) : options.model;
+  const model = resolvedModel.includes("sonnet") ? "claude-3-5-sonnet-20241022" : resolvedModel;
+  const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
+  const anthropicMessages = messages.filter(m => m.role !== "system").map(m => ({ role: m.role, content: m.content }));
+  const payload: Record<string, unknown> = {
+    model,
+    messages: anthropicMessages,
+    max_tokens: options.maxTokens ?? 4000,
+    temperature: options.temperature ?? 0.2,
+  };
+  if (systemPrompt) payload.system = systemPrompt;
+  if (stream) payload.stream = true;
+  return JSON.stringify(payload);
+}
+
+export const anthropicAdapter: ProviderAdapter = {
+  name: "anthropic",
+  async call(messages, options, credential) {
+    const response = await fetch(ANTHROPIC_URL, {
+      method: "POST",
+      headers: headersFor(credential),
+      body: anthropicPayload(messages, options, false),
+      signal: options.signal,
+    });
+    if (!response.ok) throw await providerHttpError("Anthropic", response);
+    const result = (await response.json()) as { content: { type: string; text: string }[]; usage?: { input_tokens?: number; output_tokens?: number } };
+    if (result.usage) options.onUsage?.({ inputTokens: result.usage.input_tokens, outputTokens: result.usage.output_tokens });
+    return result.content.find(c => c.type === "text")?.text ?? "";
+  },
+  async *stream(messages, options, credential) {
+    const response = await fetch(ANTHROPIC_URL, {
+      method: "POST",
+      headers: headersFor(credential),
+      body: anthropicPayload(messages, options, true),
+      signal: options.signal,
+    });
+    if (!response.ok) throw await providerHttpError("Anthropic", response, "(stream)");
+    if (!response.body) return;
+    for await (const data of readSse(response.body)) {
+      let evt: {
+        type?: string;
+        delta?: { type?: string; text?: string };
+        message?: { usage?: { input_tokens?: number; output_tokens?: number } };
+        usage?: { output_tokens?: number };
+      };
+      try {
+        evt = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (evt.type === "content_block_delta" && evt.delta?.type === "text_delta" && evt.delta.text) {
+        yield evt.delta.text;
+      } else if (evt.type === "message_start" && evt.message?.usage) {
+        options.onUsage?.({ inputTokens: evt.message.usage.input_tokens, outputTokens: evt.message.usage.output_tokens });
+      } else if (evt.type === "message_delta" && evt.usage) {
+        options.onUsage?.({ outputTokens: evt.usage.output_tokens });
+      }
+    }
+  },
+};
+
+function headersFor(credential: Credential): Record<string, string> {
+  if (credential.kind === "oauth") {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${credential.token}`,
+      "anthropic-version": "2023-06-01",
+      "anthropic-beta": "oauth-2025-04-20",
+    };
+  }
+  if (credential.kind === "api_key") {
+    return {
+      "content-type": "application/json",
+      "x-api-key": credential.token,
+      "anthropic-version": "2023-06-01",
+    };
+  }
+  throw new Error("anthropic adapter requires a credential");
+}

package/src/ai/providers/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * Structured provider error so the retry layer can act on the HTTP status.
+ *
+ * Previously every adapter threw a bare `Error("... HTTP 429 ...")`. The retry
+ * predicate (`defaultRetryable`) inspects a numeric `.status`, so those bare
+ * errors were never retried — a 429 (rate limit) or 503/529 (overloaded) bubbled
+ * straight up instead of backing off. Carrying `.status` (and any `Retry-After`)
+ * fixes that and lets `withRetry` honor server-directed backoff.
+ */
+export class ProviderHttpError extends Error {
+  readonly status: number;
+  readonly provider: string;
+  /** Server-directed backoff from a `Retry-After` header, in ms (if present). */
+  readonly retryAfterMs?: number;
+  constructor(provider: string, status: number, detail: string, context?: string, retryAfterMs?: number) {
+    super(`${provider} request failed (HTTP ${status})${context ? ` ${context}` : ""}: ${detail}`);
+    this.name = "ProviderHttpError";
+    this.status = status;
+    this.provider = provider;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/**
+ * Parse a `Retry-After` header into ms. Supports the delta-seconds form
+ * (`"5"`) and the HTTP-date form (`"Wed, 21 Oct 2025 07:28:00 GMT"`).
+ * Returns undefined for missing/garbage values.
+ */
+export function parseRetryAfter(value: string | null | undefined): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const secs = Number(trimmed);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const when = Date.parse(trimmed);
+  if (!Number.isNaN(when)) return Math.max(0, when - Date.now());
+  return undefined;
+}
+
+/**
+ * Build a {@link ProviderHttpError} from a non-ok `Response`, capturing the body
+ * and any `Retry-After`. Use at every adapter's `!response.ok` site so the retry
+ * layer sees a uniform, status-carrying, backoff-aware error.
+ */
+export async function providerHttpError(provider: string, response: Response, context?: string): Promise<ProviderHttpError> {
+  const detail = await response.text().catch(() => "");
+  return new ProviderHttpError(provider, response.status, detail, context, parseRetryAfter(response.headers.get("retry-after")));
+}

package/src/ai/providers/gemini.ts

@@ -0,0 +1,77 @@
+import type { Credential } from "../../auth";
+import type { CallOptions, Message, ProviderAdapter } from "../types";
+import { readSse } from "../sse";
+import { providerHttpError } from "./errors";
+
+function geminiRequest(messages: Message[], options: CallOptions, credential: Credential, action: "generateContent" | "streamGenerateContent"): { url: string; headers: Record<string, string>; body: string } {
+  const resolvedModel = options.model.startsWith("google/") ? options.model.slice(7) : options.model;
+  let geminiModel = resolvedModel;
+  if (!geminiModel || geminiModel === "claude-3-5-sonnet") geminiModel = "gemini-2.0-flash";
+
+  const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
+  const contents = messages
+    .filter(m => m.role !== "system")
+    .map(m => ({ role: m.role === "assistant" ? "model" : "user", parts: [{ text: m.content }] }));
+
+  const generationConfig: Record<string, unknown> = {
+    temperature: options.temperature ?? 0.2,
+    maxOutputTokens: options.maxTokens ?? 4000,
+  };
+  if (options.jsonMode) generationConfig.responseMimeType = "application/json";
+
+  const payload: Record<string, unknown> = { contents, generationConfig };
+  if (systemPrompt) payload.systemInstruction = { parts: [{ text: systemPrompt }] };
+
+  const oauth = credential.kind === "oauth" ? credential.token : undefined;
+  const apiKey = credential.kind === "api_key" ? credential.token : undefined;
+  let url = `https://generativelanguage.googleapis.com/v1beta/models/${geminiModel}:${action}`;
+  const query = action === "streamGenerateContent" ? "alt=sse" : "";
+  if (!oauth) url += `?${query ? query + "&" : ""}key=${apiKey ?? ""}`;
+  else if (query) url += `?${query}`;
+  const headers: Record<string, string> = oauth
+    ? { "content-type": "application/json", authorization: `Bearer ${oauth}` }
+    : { "content-type": "application/json" };
+  return { url, headers, body: JSON.stringify(payload) };
+}
+
+interface GeminiChunk {
+  candidates?: { content?: { parts?: { text?: string }[] } }[];
+  usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number };
+}
+
+function textOf(chunk: GeminiChunk): string {
+  return chunk.candidates?.[0]?.content?.parts?.map(p => p.text ?? "").join("") ?? "";
+}
+
+export const geminiAdapter: ProviderAdapter = {
+  name: "gemini",
+  async call(messages, options, credential) {
+    const { url, headers, body } = geminiRequest(messages, options, credential, "generateContent");
+    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("Gemini", response);
+    const result = (await response.json()) as GeminiChunk;
+    if (result.usageMetadata) {
+      options.onUsage?.({ inputTokens: result.usageMetadata.promptTokenCount, outputTokens: result.usageMetadata.candidatesTokenCount });
+    }
+    return textOf(result);
+  },
+  async *stream(messages, options, credential) {
+    const { url, headers, body } = geminiRequest(messages, options, credential, "streamGenerateContent");
+    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("Gemini", response, "(stream)");
+    if (!response.body) return;
+    for await (const data of readSse(response.body)) {
+      let chunk: GeminiChunk;
+      try {
+        chunk = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      const delta = textOf(chunk);
+      if (delta) yield delta;
+      if (chunk.usageMetadata) {
+        options.onUsage?.({ inputTokens: chunk.usageMetadata.promptTokenCount, outputTokens: chunk.usageMetadata.candidatesTokenCount });
+      }
+    }
+  },
+};

package/src/ai/providers/ollama.ts

@@ -0,0 +1,54 @@
+import type { CallOptions, Message, ProviderAdapter } from "../types";
+import { readLines } from "../sse";
+import { providerHttpError } from "./errors";
+
+function ollamaRequest(messages: Message[], options: CallOptions, stream: boolean): { url: string; body: string } {
+  const model = options.model.startsWith("ollama/") ? options.model.slice(7) : options.model;
+  const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
+  const chatMessages: { role: string; content: string }[] = [];
+  if (systemPrompt) chatMessages.push({ role: "system", content: systemPrompt });
+  for (const msg of messages) {
+    if (msg.role !== "system") chatMessages.push({ role: msg.role, content: msg.content });
+  }
+  const payload: Record<string, unknown> = {
+    model,
+    messages: chatMessages,
+    stream,
+    options: { temperature: options.temperature ?? 0.2, num_predict: options.maxTokens ?? 4000 },
+  };
+  if (options.jsonMode) payload.format = "json";
+  const base = (options.baseUrl ?? process.env.OLLAMA_HOST ?? "http://localhost:11434").replace(/\/$/, "");
+  return { url: `${base}/api/chat`, body: JSON.stringify(payload) };
+}
+
+export const ollamaAdapter: ProviderAdapter = {
+  name: "ollama",
+  async call(messages, options) {
+    const { url, body } = ollamaRequest(messages, options, false);
+    const response = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("Ollama", response, `at ${url}`);
+    const result = (await response.json()) as { message?: { content?: string }; prompt_eval_count?: number; eval_count?: number; total_duration?: number };
+    options.onUsage?.({ inputTokens: result.prompt_eval_count, outputTokens: result.eval_count, durationMs: result.total_duration ? Math.round(result.total_duration / 1e6) : undefined });
+    return result.message?.content ?? "";
+  },
+  async *stream(messages, options) {
+    const { url, body } = ollamaRequest(messages, options, true);
+    const response = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("Ollama", response, `(stream) at ${url}`);
+    if (!response.body) return;
+    for await (const line of readLines(response.body)) {
+      let chunk: { message?: { content?: string }; done?: boolean; prompt_eval_count?: number; eval_count?: number; total_duration?: number };
+      try {
+        chunk = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const delta = chunk.message?.content;
+      if (delta) yield delta;
+      if (chunk.done) {
+        options.onUsage?.({ inputTokens: chunk.prompt_eval_count, outputTokens: chunk.eval_count, durationMs: chunk.total_duration ? Math.round(chunk.total_duration / 1e6) : undefined });
+        break;
+      }
+    }
+  },
+};

package/src/ai/providers/openai.ts

@@ -0,0 +1,67 @@
+import type { Credential } from "../../auth";
+import type { CallOptions, Message, ProviderAdapter } from "../types";
+import { readSse } from "../sse";
+import { providerHttpError } from "./errors";
+
+function openaiRequest(messages: Message[], options: CallOptions, credential: Credential, stream: boolean): { url: string; headers: Record<string, string>; body: string } {
+  const resolvedModel = options.model.startsWith("openai/") ? options.model.slice(7) : options.model;
+  const model = resolvedModel.includes("gpt-4o") ? "gpt-4o" : resolvedModel;
+  const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
+  const openaiMessages: { role: string; content: string }[] = [];
+  if (systemPrompt) openaiMessages.push({ role: "system", content: systemPrompt });
+  for (const msg of messages) {
+    if (msg.role !== "system") openaiMessages.push({ role: msg.role, content: msg.content });
+  }
+  const payload: Record<string, unknown> = {
+    model,
+    messages: openaiMessages,
+    temperature: options.temperature ?? 0.2,
+    max_tokens: options.maxTokens ?? 4000,
+  };
+  if (stream) {
+    payload.stream = true;
+    payload.stream_options = { include_usage: true };
+  }
+  if (options.jsonMode) payload.response_format = { type: "json_object" };
+  const base = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+  return {
+    url: `${base}/chat/completions`,
+    headers: { "content-type": "application/json", Authorization: `Bearer ${bearerFor(credential)}` },
+    body: JSON.stringify(payload),
+  };
+}
+
+export const openaiAdapter: ProviderAdapter = {
+  name: "openai",
+  async call(messages, options, credential) {
+    const { url, headers, body } = openaiRequest(messages, options, credential, false);
+    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("OpenAI", response);
+    const result = (await response.json()) as { choices: { message: { content: string } }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
+    if (result.usage) options.onUsage?.({ inputTokens: result.usage.prompt_tokens, outputTokens: result.usage.completion_tokens });
+    return result.choices[0]?.message?.content ?? "";
+  },
+  async *stream(messages, options, credential) {
+    const { url, headers, body } = openaiRequest(messages, options, credential, true);
+    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    if (!response.ok) throw await providerHttpError("OpenAI", response, "(stream)");
+    if (!response.body) return;
+    for await (const data of readSse(response.body)) {
+      let chunk: { choices?: { delta?: { content?: string } }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
+      try {
+        chunk = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      const delta = chunk.choices?.[0]?.delta?.content;
+      if (delta) yield delta;
+      if (chunk.usage) options.onUsage?.({ inputTokens: chunk.usage.prompt_tokens, outputTokens: chunk.usage.completion_tokens });
+    }
+  },
+};
+
+function bearerFor(credential: Credential): string {
+  if (credential.kind === "oauth") return credential.token;
+  if (credential.kind === "api_key") return credential.token;
+  return "no-key";
+}

package/src/ai/sse.ts

@@ -0,0 +1,46 @@
+export async function* readLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n");
+      buffer = parts.pop() ?? "";
+      for (const part of parts) {
+        const line = part.endsWith("\r") ? part.slice(0, -1) : part;
+        if (line !== "") {
+          yield line;
+        }
+      }
+    }
+    buffer += decoder.decode();
+    const parts = buffer.split("\n");
+    for (const part of parts) {
+      const line = part.endsWith("\r") ? part.slice(0, -1) : part;
+      if (line !== "") {
+        yield line;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export async function* readSse(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  for await (const line of readLines(stream)) {
+    if (line.startsWith("data:")) {
+      let data = line.slice(5);
+      if (data.startsWith(" ")) {
+        data = data.slice(1);
+      }
+      if (data !== "[DONE]") {
+        yield data;
+      }
+    }
+  }
+}

package/src/ai/types.ts

@@ -0,0 +1,37 @@
+import type { Credential } from "../auth";
+
+export type ProviderName = "anthropic" | "openai" | "gemini" | "ollama";
+
+export interface Message {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface Usage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Generation duration in ms, when the provider reports it. */
+  durationMs?: number;
+}
+
+export interface CallOptions {
+  model: string;
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+  jsonMode?: boolean;
+  /** Per-call base URL override (OpenAI-compat / Ollama). */
+  baseUrl?: string;
+  /** Optional sink for provider-reported token usage. */
+  onUsage?: (usage: Usage) => void;
+  /** Abort in-flight provider requests (Ctrl-C / timeout / supersede). */
+  signal?: AbortSignal;
+}
+
+export interface ProviderAdapter {
+  readonly name: ProviderName;
+  /** Local providers ignore the credential argument; cloud adapters require it. */
+  call(messages: Message[], options: CallOptions, credential: Credential): Promise<string>;
+  /** Optional token streaming. Yields text deltas; concatenation equals the `call()` result. */
+  stream?(messages: Message[], options: CallOptions, credential: Credential): AsyncIterable<string>;
+}