feat: ship the AI assistant as a first-party in-process plugin

Moves src/backend/ai and its routes into plugins/ai, mounted through a
small /ai dispatcher instead of its own port. Moves the ai-enabled and
ai-private-endpoints settings routes out of user-settings-routes.ts
into the plugin too, so it has no leftover core dependents.

plugins/ai/backend/providers/anthropic.ts

@@ -0,0 +1,162 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { providerFetch } from "./http.js";
+import type {
+  ChatChunk,
+  ChatRequest,
+  ProviderAdapter,
+  ProviderConfig,
+} from "./types.js";
+import { AiProviderError } from "./types.js";
+
+/**
+ * Model ids offered in the picker. Users can type any other id; this is a
+ * convenience list, not a restriction.
+ */
+export const ANTHROPIC_MODELS = [
+  "claude-opus-5",
+  "claude-sonnet-5",
+  "claude-haiku-4-5",
+];
+
+function createClient(config: ProviderConfig): Anthropic {
+  if (!config.apiKey) {
+    throw new AiProviderError("This provider needs an API key");
+  }
+  return new Anthropic({
+    apiKey: config.apiKey,
+    ...(config.baseUrl?.trim() ? { baseURL: config.baseUrl.trim() } : {}),
+    // Routes the SDK's HTTP through the shared egress guard.
+    fetch: providerFetch as unknown as typeof fetch,
+  });
+}
+
+function toAnthropicMessages(request: ChatRequest): Anthropic.MessageParam[] {
+  const messages: Anthropic.MessageParam[] = [];
+
+  for (const message of request.messages) {
+    if (message.role === "tool") {
+      messages.push({
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: message.toolCallId ?? "",
+            content: message.content,
+          },
+        ],
+      });
+      continue;
+    }
+
+    if (message.role === "assistant" && message.toolCalls?.length) {
+      const content: Anthropic.ContentBlockParam[] = [];
+      if (message.content)
+        content.push({ type: "text", text: message.content });
+      for (const call of message.toolCalls) {
+        content.push({
+          type: "tool_use",
+          id: call.id,
+          name: call.name,
+          input: call.arguments,
+        });
+      }
+      messages.push({ role: "assistant", content });
+      continue;
+    }
+
+    if (message.role === "system") continue;
+    messages.push({ role: message.role, content: message.content });
+  }
+
+  return messages;
+}
+
+/**
+ * The SDK throws its own typed errors rather than going through assertOk, so
+ * they are translated here to match what every other provider reports.
+ */
+function translateSdkError(error: unknown): never {
+  const status =
+    typeof (error as { status?: unknown })?.status === "number"
+      ? (error as { status: number }).status
+      : undefined;
+  const detail = error instanceof Error ? error.message : String(error);
+
+  if (status === 429) {
+    throw new AiProviderError(
+      `Anthropic rate limit reached. Wait a moment and try again, or check your plan's quota. (${detail})`,
+      429,
+    );
+  }
+  if (status === 401 || status === 403) {
+    throw new AiProviderError(
+      `Anthropic rejected the API key. Check that it is correct and still active. (${detail})`,
+      status,
+    );
+  }
+  throw new AiProviderError(
+    status ? `Anthropic request failed (${status}): ${detail}` : detail,
+    status,
+  );
+}
+
+export const anthropicAdapter: ProviderAdapter = {
+  async *streamChat(
+    config: ProviderConfig,
+    request: ChatRequest,
+  ): AsyncIterable<ChatChunk> {
+    const client = createClient(config);
+
+    const stream = client.messages.stream({
+      model: request.model,
+      max_tokens: 16000,
+      system: request.system,
+      messages: toAnthropicMessages(request),
+      thinking: { type: "adaptive" },
+      ...(request.tools.length
+        ? {
+            tools: request.tools.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              input_schema: tool.parameters as Anthropic.Tool.InputSchema,
+            })),
+          }
+        : {}),
+      ...(request.signal ? { signal: request.signal } : {}),
+    });
+
+    let final: Anthropic.Message;
+    try {
+      for await (const event of stream) {
+        if (
+          event.type === "content_block_delta" &&
+          event.delta.type === "text_delta"
+        ) {
+          yield { type: "text", text: event.delta.text };
+        }
+      }
+      final = await stream.finalMessage();
+    } catch (error) {
+      translateSdkError(error);
+    }
+
+    for (const block of final.content) {
+      if (block.type === "tool_use") {
+        yield {
+          type: "tool_call",
+          call: {
+            id: block.id,
+            name: block.name,
+            arguments: (block.input ?? {}) as Record<string, unknown>,
+          },
+        };
+      }
+    }
+
+    yield { type: "done", stopReason: final.stop_reason ?? undefined };
+  },
+
+  async listModels(): Promise<string[]> {
+    return [...ANTHROPIC_MODELS];
+  },
+};

plugins/ai/backend/providers/gemini.ts

@@ -0,0 +1,191 @@
+import { assertOk, providerFetch, readSseLines } from "./http.js";
+import type {
+  ChatChunk,
+  ChatRequest,
+  ProviderAdapter,
+  ProviderConfig,
+} from "./types.js";
+import { AiProviderError } from "./types.js";
+
+const GEMINI_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+function baseFor(config: ProviderConfig): string {
+  return config.baseUrl?.trim() || GEMINI_DEFAULT_BASE;
+}
+
+/**
+ * Gemini has no tool role: a tool result is a user-side functionResponse part,
+ * and an assistant tool request is a model-side functionCall part.
+ */
+function toGeminiContents(request: ChatRequest): unknown[] {
+  const contents: unknown[] = [];
+
+  for (const message of request.messages) {
+    if (message.role === "tool") {
+      contents.push({
+        role: "user",
+        parts: [
+          {
+            functionResponse: {
+              name: message.toolName ?? "tool",
+              response: { result: message.content },
+            },
+          },
+        ],
+      });
+      continue;
+    }
+
+    if (message.role === "assistant" && message.toolCalls?.length) {
+      const parts: unknown[] = [];
+      if (message.content) parts.push({ text: message.content });
+      for (const call of message.toolCalls) {
+        // thoughtSignature must be returned exactly as received or Gemini
+        // 2.5+ rejects the turn with a 400.
+        parts.push({
+          functionCall: { name: call.name, args: call.arguments },
+          ...(call.providerSignature
+            ? { thoughtSignature: call.providerSignature }
+            : {}),
+        });
+      }
+      contents.push({ role: "model", parts });
+      continue;
+    }
+
+    if (message.role === "system") continue;
+
+    contents.push({
+      role: message.role === "assistant" ? "model" : "user",
+      parts: [{ text: message.content }],
+    });
+  }
+
+  return contents;
+}
+
+/**
+ * Gemini rejects the JSON Schema keywords it does not implement, so the tool
+ * schemas are trimmed to the subset it accepts.
+ */
+function toGeminiSchema(schema: unknown): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map(toGeminiSchema);
+
+  const source = schema as Record<string, unknown>;
+  const output: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    if (key === "additionalProperties" || key === "$schema") continue;
+    if (key === "properties" && value && typeof value === "object") {
+      const properties: Record<string, unknown> = {};
+      for (const [name, child] of Object.entries(
+        value as Record<string, unknown>,
+      )) {
+        properties[name] = toGeminiSchema(child);
+      }
+      output[key] = properties;
+      continue;
+    }
+    output[key] = toGeminiSchema(value);
+  }
+
+  return output;
+}
+
+export const geminiAdapter: ProviderAdapter = {
+  async *streamChat(
+    config: ProviderConfig,
+    request: ChatRequest,
+  ): AsyncIterable<ChatChunk> {
+    if (!config.apiKey) {
+      throw new AiProviderError("This provider needs an API key");
+    }
+
+    const url = `${baseFor(config).replace(/\/+$/, "")}/models/${encodeURIComponent(request.model)}:streamGenerateContent?alt=sse`;
+
+    const response = await providerFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-goog-api-key": config.apiKey,
+      },
+      signal: request.signal,
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: request.system }] },
+        contents: toGeminiContents(request),
+        ...(request.tools.length
+          ? {
+              tools: [
+                {
+                  functionDeclarations: request.tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: toGeminiSchema(tool.parameters),
+                  })),
+                },
+              ],
+            }
+          : {}),
+      }),
+    });
+
+    await assertOk(response, "Gemini");
+
+    let index = 0;
+    let stopReason: string | undefined;
+
+    for await (const data of readSseLines(response)) {
+      let frame: any;
+      try {
+        frame = JSON.parse(data);
+      } catch {
+        continue;
+      }
+
+      const candidate = frame.candidates?.[0];
+      if (!candidate) continue;
+      if (candidate.finishReason) stopReason = candidate.finishReason;
+
+      for (const part of candidate.content?.parts ?? []) {
+        if (typeof part.text === "string" && part.text) {
+          yield { type: "text", text: part.text };
+        }
+        if (part.functionCall?.name) {
+          yield {
+            type: "tool_call",
+            call: {
+              id: `call_${part.functionCall.name}_${index++}`,
+              name: part.functionCall.name,
+              arguments: (part.functionCall.args ?? {}) as Record<
+                string,
+                unknown
+              >,
+              // Carried so the next turn can echo it back; without it Gemini
+              // 400s as soon as a tool has been used once.
+              providerSignature: part.thoughtSignature,
+            },
+          };
+        }
+      }
+    }
+
+    yield { type: "done", stopReason };
+  },
+
+  async listModels(config: ProviderConfig): Promise<string[]> {
+    if (!config.apiKey) return [];
+
+    const response = await providerFetch(
+      `${baseFor(config).replace(/\/+$/, "")}/models`,
+      { method: "GET", headers: { "x-goog-api-key": config.apiKey } },
+    );
+    await assertOk(response, "Gemini");
+
+    const body: any = await response.json();
+    return (body.models ?? [])
+      .map((entry: any) => String(entry.name ?? "").replace(/^models\//, ""))
+      .filter((name: string) => name.length > 0)
+      .sort();
+  },
+};

plugins/ai/backend/providers/http.ts

@@ -0,0 +1,174 @@
+import { fetchWithProxy } from "../../../../src/backend/utils/proxy-agent.js";
+import { safeOutboundFetch } from "../../../../src/backend/utils/safe-outbound-fetch.js";
+import { evaluateEgress, readPrivateAllowlist } from "../egress.js";
+import { AiProviderError } from "./types.js";
+
+/**
+ * Every outbound provider request goes through here so the egress rules cannot
+ * be bypassed by an adapter calling fetch directly.
+ *
+ * Public hosts use safeOutboundFetch, which re-checks the resolved address at
+ * connect time. Allowlisted private hosts cannot use it (its whole job is to
+ * refuse them), so they use the installed Undici fetch implementation with
+ * its matching proxy dispatcher -- still respecting proxy configuration.
+ */
+export async function providerFetch(
+  url: string,
+  init: RequestInit,
+): Promise<Response> {
+  const allowlist = await readPrivateAllowlist();
+  const decision = evaluateEgress(url, allowlist);
+
+  if (!decision.allowed) {
+    throw new AiProviderError(decision.reason ?? "Destination not allowed");
+  }
+
+  if (decision.isPrivate) {
+    return fetchWithProxy(url, init);
+  }
+
+  return safeOutboundFetch(url, init) as unknown as Promise<Response>;
+}
+
+export function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Yields the data payload of each SSE frame. Providers differ in what they put
+ * inside, so parsing the JSON is left to the caller.
+ */
+export async function* readSseLines(
+  response: Response,
+): AsyncGenerator<string> {
+  const body = response.body;
+  if (!body) return;
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim();
+        buffer = buffer.slice(newlineIndex + 1);
+        if (line.startsWith("data:")) {
+          yield line.slice(5).trim();
+        }
+        newlineIndex = buffer.indexOf("\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Yields one parsed JSON object per line, for newline-delimited streams. */
+export async function* readJsonLines(
+  response: Response,
+): AsyncGenerator<unknown> {
+  const body = response.body;
+  if (!body) return;
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim();
+        buffer = buffer.slice(newlineIndex + 1);
+        if (line) {
+          try {
+            yield JSON.parse(line);
+          } catch {
+            // A partial or malformed frame is skipped rather than failing the
+            // whole stream.
+          }
+        }
+        newlineIndex = buffer.indexOf("\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Digs the human-readable message out of an error body.
+ *
+ * Every provider nests it differently, and dumping the raw JSON produced
+ * something that got cut off mid-sentence. Falls back to a trimmed snippet
+ * when the shape is unfamiliar.
+ */
+function extractProviderMessage(body: string): string {
+  try {
+    const parsed = JSON.parse(body);
+    const message =
+      parsed?.error?.message ??
+      parsed?.error?.["message"] ??
+      parsed?.message ??
+      (typeof parsed?.error === "string" ? parsed.error : null);
+    if (typeof message === "string" && message.trim()) {
+      return message.trim();
+    }
+  } catch {
+    // Not JSON; fall through to the snippet.
+  }
+
+  const trimmed = body.trim();
+  if (!trimmed) return "";
+  return trimmed.length > 300 ? `${trimmed.slice(0, 300)}...` : trimmed;
+}
+
+export async function assertOk(
+  response: Response,
+  provider: string,
+): Promise<void> {
+  if (response.ok) return;
+
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    body = "";
+  }
+
+  const detail = extractProviderMessage(body);
+
+  // Rate limits and auth failures are the two the user can actually act on,
+  // so they say what to do instead of reading like an internal failure.
+  if (response.status === 429) {
+    throw new AiProviderError(
+      `${provider} rate limit reached. Wait a moment and try again, or check your plan's quota.${
+        detail ? ` (${detail})` : ""
+      }`,
+      429,
+    );
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new AiProviderError(
+      `${provider} rejected the API key. Check that it is correct and still active.${
+        detail ? ` (${detail})` : ""
+      }`,
+      response.status,
+    );
+  }
+
+  throw new AiProviderError(
+    `${provider} request failed (${response.status})${detail ? `: ${detail}` : ""}`,
+    response.status,
+  );
+}

plugins/ai/backend/providers/ollama.ts

@@ -0,0 +1,131 @@
+import { assertOk, joinUrl, providerFetch, readJsonLines } from "./http.js";
+import type {
+  ChatChunk,
+  ChatRequest,
+  ProviderAdapter,
+  ProviderConfig,
+} from "./types.js";
+
+export const OLLAMA_DEFAULT_BASE = "http://localhost:11434";
+
+function baseFor(config: ProviderConfig): string {
+  return config.baseUrl?.trim() || OLLAMA_DEFAULT_BASE;
+}
+
+function toOllamaMessages(request: ChatRequest): unknown[] {
+  const messages: unknown[] = [{ role: "system", content: request.system }];
+
+  for (const message of request.messages) {
+    if (message.role === "tool") {
+      messages.push({
+        role: "tool",
+        content: message.content,
+        ...(message.toolName ? { tool_name: message.toolName } : {}),
+      });
+      continue;
+    }
+
+    if (message.role === "assistant" && message.toolCalls?.length) {
+      messages.push({
+        role: "assistant",
+        content: message.content,
+        tool_calls: message.toolCalls.map((call) => ({
+          function: { name: call.name, arguments: call.arguments },
+        })),
+      });
+      continue;
+    }
+
+    messages.push({ role: message.role, content: message.content });
+  }
+
+  return messages;
+}
+
+export const ollamaAdapter: ProviderAdapter = {
+  async *streamChat(
+    config: ProviderConfig,
+    request: ChatRequest,
+  ): AsyncIterable<ChatChunk> {
+    const response = await providerFetch(joinUrl(baseFor(config), "api/chat"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: request.signal,
+      body: JSON.stringify({
+        model: request.model,
+        messages: toOllamaMessages(request),
+        stream: true,
+        ...(request.tools.length
+          ? {
+              tools: request.tools.map((tool) => ({
+                type: "function",
+                function: {
+                  name: tool.name,
+                  description: tool.description,
+                  parameters: tool.parameters,
+                },
+              })),
+            }
+          : {}),
+      }),
+    });
+
+    await assertOk(response, "Ollama");
+
+    let index = 0;
+    let stopReason: string | undefined;
+
+    // Ollama streams newline-delimited JSON rather than SSE.
+    for await (const frame of readJsonLines(response)) {
+      const payload = frame as any;
+
+      if (
+        typeof payload.message?.content === "string" &&
+        payload.message.content
+      ) {
+        yield { type: "text", text: payload.message.content };
+      }
+
+      for (const call of payload.message?.tool_calls ?? []) {
+        const name = call.function?.name;
+        if (!name) continue;
+        const rawArgs = call.function?.arguments;
+        // Ollama sends an object, but some builds send a JSON string.
+        let args: Record<string, unknown> = {};
+        if (rawArgs && typeof rawArgs === "object") {
+          args = rawArgs as Record<string, unknown>;
+        } else if (typeof rawArgs === "string" && rawArgs.trim()) {
+          try {
+            args = JSON.parse(rawArgs);
+          } catch {
+            args = {};
+          }
+        }
+        yield {
+          type: "tool_call",
+          call: { id: `call_${name}_${index++}`, name, arguments: args },
+        };
+      }
+
+      if (payload.done) {
+        stopReason = payload.done_reason ?? "stop";
+        break;
+      }
+    }
+
+    yield { type: "done", stopReason };
+  },
+
+  async listModels(config: ProviderConfig): Promise<string[]> {
+    const response = await providerFetch(joinUrl(baseFor(config), "api/tags"), {
+      method: "GET",
+    });
+    await assertOk(response, "Ollama");
+
+    const body: any = await response.json();
+    return (body.models ?? [])
+      .map((entry: any) => entry.name)
+      .filter((name: unknown): name is string => typeof name === "string")
+      .sort();
+  },
+};

plugins/ai/backend/providers/openai.ts

@@ -0,0 +1,182 @@
+import { assertOk, joinUrl, providerFetch, readSseLines } from "./http.js";
+import type {
+  ChatChunk,
+  ChatRequest,
+  ProviderAdapter,
+  ProviderConfig,
+  ToolCall,
+} from "./types.js";
+import { AiProviderError } from "./types.js";
+
+const OPENAI_DEFAULT_BASE = "https://api.openai.com/v1";
+
+function baseFor(config: ProviderConfig): string {
+  if (config.baseUrl?.trim()) return config.baseUrl.trim();
+  if (config.providerType === "openai") return OPENAI_DEFAULT_BASE;
+  throw new AiProviderError("This provider needs a base URL");
+}
+
+function toOpenAiMessages(request: ChatRequest): unknown[] {
+  const messages: unknown[] = [{ role: "system", content: request.system }];
+
+  for (const message of request.messages) {
+    if (message.role === "tool") {
+      messages.push({
+        role: "tool",
+        tool_call_id: message.toolCallId,
+        content: message.content,
+      });
+      continue;
+    }
+
+    if (message.role === "assistant" && message.toolCalls?.length) {
+      messages.push({
+        role: "assistant",
+        content: message.content || null,
+        tool_calls: message.toolCalls.map((call) => ({
+          id: call.id,
+          type: "function",
+          function: {
+            name: call.name,
+            arguments: JSON.stringify(call.arguments),
+          },
+        })),
+      });
+      continue;
+    }
+
+    messages.push({ role: message.role, content: message.content });
+  }
+
+  return messages;
+}
+
+/**
+ * Tool call arguments arrive as JSON fragments spread across many deltas, so
+ * they are accumulated per index and only parsed once the stream ends.
+ */
+interface PartialCall {
+  id: string;
+  name: string;
+  args: string;
+}
+
+export const openAiAdapter: ProviderAdapter = {
+  async *streamChat(
+    config: ProviderConfig,
+    request: ChatRequest,
+  ): AsyncIterable<ChatChunk> {
+    const url = joinUrl(baseFor(config), "chat/completions");
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+
+    const response = await providerFetch(url, {
+      method: "POST",
+      headers,
+      signal: request.signal,
+      body: JSON.stringify({
+        model: request.model,
+        messages: toOpenAiMessages(request),
+        stream: true,
+        ...(request.tools.length
+          ? {
+              tools: request.tools.map((tool) => ({
+                type: "function",
+                function: {
+                  name: tool.name,
+                  description: tool.description,
+                  parameters: tool.parameters,
+                },
+              })),
+            }
+          : {}),
+      }),
+    });
+
+    await assertOk(response, "OpenAI");
+
+    const partial = new Map<number, PartialCall>();
+    let stopReason: string | undefined;
+
+    for await (const data of readSseLines(response)) {
+      if (data === "[DONE]") break;
+
+      let frame: any;
+      try {
+        frame = JSON.parse(data);
+      } catch {
+        continue;
+      }
+
+      const choice = frame.choices?.[0];
+      if (!choice) continue;
+
+      if (choice.finish_reason) stopReason = choice.finish_reason;
+
+      const delta = choice.delta;
+      if (!delta) continue;
+
+      if (typeof delta.content === "string" && delta.content) {
+        yield { type: "text", text: delta.content };
+      }
+
+      for (const call of delta.tool_calls ?? []) {
+        const index = call.index ?? 0;
+        const existing = partial.get(index) ?? { id: "", name: "", args: "" };
+        if (call.id) existing.id = call.id;
+        if (call.function?.name) existing.name = call.function.name;
+        if (call.function?.arguments) existing.args += call.function.arguments;
+        partial.set(index, existing);
+      }
+    }
+
+    for (const call of partial.values()) {
+      if (!call.name) continue;
+      yield { type: "tool_call", call: finalizeCall(call) };
+    }
+
+    yield { type: "done", stopReason };
+  },
+
+  async listModels(config: ProviderConfig): Promise<string[]> {
+    const headers: Record<string, string> = {};
+    if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+
+    const response = await providerFetch(joinUrl(baseFor(config), "models"), {
+      method: "GET",
+      headers,
+    });
+    await assertOk(response, "OpenAI");
+
+    const body: any = await response.json();
+    return (body.data ?? [])
+      .map((entry: any) => entry.id)
+      .filter((id: unknown): id is string => typeof id === "string")
+      .sort();
+  },
+};
+
+export function finalizeCall(call: PartialCall): ToolCall {
+  let args: Record<string, unknown> = {};
+  if (call.args.trim()) {
+    try {
+      const parsed = JSON.parse(call.args);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        args = parsed as Record<string, unknown>;
+      }
+    } catch {
+      // A model that emitted malformed arguments gets an empty object; the
+      // tool's own schema validation reports the problem back to it.
+      args = {};
+    }
+  }
+  return {
+    id:
+      call.id || `call_${call.name}_${Math.random().toString(36).slice(2, 10)}`,
+    name: call.name,
+    arguments: args,
+  };
+}

plugins/ai/backend/providers/registry.ts

@@ -0,0 +1,64 @@
+import { anthropicAdapter } from "./anthropic.js";
+import { geminiAdapter } from "./gemini.js";
+import { ollamaAdapter } from "./ollama.js";
+import { openAiAdapter } from "./openai.js";
+import {
+  AiProviderError,
+  type AiProviderType,
+  type ProviderAdapter,
+} from "./types.js";
+
+/**
+ * openai_compatible reuses the OpenAI adapter: OpenRouter, Groq, Mistral,
+ * DeepSeek, together.ai, LM Studio and vLLM all speak the same wire format,
+ * they differ only in base URL.
+ */
+const ADAPTERS: Record<AiProviderType, ProviderAdapter> = {
+  ollama: ollamaAdapter,
+  anthropic: anthropicAdapter,
+  openai: openAiAdapter,
+  gemini: geminiAdapter,
+  openai_compatible: openAiAdapter,
+};
+
+export function getAdapter(providerType: string): ProviderAdapter {
+  const adapter = ADAPTERS[providerType as AiProviderType];
+  if (!adapter) {
+    throw new AiProviderError(`Unknown provider type: ${providerType}`);
+  }
+  return adapter;
+}
+
+/** Provider types that cannot work without a base URL. */
+export const REQUIRES_BASE_URL: AiProviderType[] = [
+  "ollama",
+  "openai_compatible",
+];
+
+/** Provider types that cannot work without an API key. */
+export const REQUIRES_API_KEY: AiProviderType[] = [
+  "anthropic",
+  "openai",
+  "gemini",
+];
+
+/**
+ * Shown when a provider's model list cannot be fetched: no key entered yet,
+ * the endpoint is unreachable, or the vendor has no list endpoint. Users can
+ * always type a model id the list does not contain, so this is a starting
+ * point rather than a restriction.
+ */
+export const FALLBACK_MODELS: Record<AiProviderType, string[]> = {
+  ollama: [
+    "llama3.2",
+    "llama3.1",
+    "qwen2.5-coder",
+    "mistral",
+    "phi4",
+    "gemma2",
+  ],
+  anthropic: ["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5"],
+  openai: ["gpt-5", "gpt-5-mini", "o4-mini", "gpt-4.1"],
+  gemini: ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.0-flash"],
+  openai_compatible: [],
+};

plugins/ai/backend/providers/types.ts

@@ -0,0 +1,90 @@
+/**
+ * The shape every provider adapter normalizes to. Adding a provider means
+ * translating its wire format into these events; nothing downstream (the
+ * engine, the tool dispatcher, the SSE route) knows which vendor is in use.
+ */
+
+export type AiProviderType =
+  "ollama" | "anthropic" | "openai" | "gemini" | "openai_compatible";
+
+export const AI_PROVIDER_TYPES: AiProviderType[] = [
+  "ollama",
+  "anthropic",
+  "openai",
+  "gemini",
+  "openai_compatible",
+];
+
+export function isAiProviderType(value: unknown): value is AiProviderType {
+  return (
+    typeof value === "string" && (AI_PROVIDER_TYPES as string[]).includes(value)
+  );
+}
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  /** Set on assistant turns that requested tools. */
+  toolCalls?: ToolCall[];
+  /** Set on tool turns, matching the id of the call being answered. */
+  toolCallId?: string;
+  toolName?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  /**
+   * Opaque provider state that has to be echoed back verbatim on the next
+   * turn. Gemini 2.5+ rejects a follow-up whose functionCall parts have lost
+   * their thoughtSignature, so this rides along rather than being dropped.
+   */
+  providerSignature?: string;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+export interface ChatRequest {
+  model: string;
+  system: string;
+  messages: ChatMessage[];
+  tools: ToolDefinition[];
+  signal?: AbortSignal;
+}
+
+export type ChatChunk =
+  | { type: "text"; text: string }
+  | { type: "tool_call"; call: ToolCall }
+  | { type: "done"; stopReason?: string }
+  | { type: "error"; message: string };
+
+export interface ProviderConfig {
+  providerType: AiProviderType;
+  baseUrl?: string | null;
+  apiKey?: string | null;
+}
+
+export interface ProviderAdapter {
+  /** Streams a single assistant turn. Tool execution happens in the engine. */
+  streamChat(
+    config: ProviderConfig,
+    request: ChatRequest,
+  ): AsyncIterable<ChatChunk>;
+  /** Model ids to offer in the picker, best effort. */
+  listModels(config: ProviderConfig): Promise<string[]>;
+}
+
+export class AiProviderError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "AiProviderError";
+  }
+}