@wenathlan/devthink 1.1.1

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@wenathlan/devthink",
+  "version": "1.1.1",
+  "description": "DevThink is an AI development workbench with provider-owned endpoints, normalized streaming, sessions, memory, an embedded gateway and a terminal/web interface.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "devthink": "./devthink.ts"
+  },
+  "exports": {
+    ".": "./devthink.ts",
+    "./config": "./config.ts",
+    "./identity": "./identity.ts",
+    "./memory": "./memory.ts",
+    "./modes": "./modes.ts",
+    "./plugin": "./plugin.ts",
+    "./providers": "./providers.ts",
+    "./server": "./server.ts",
+    "./session": "./session.ts",
+    "./stream": "./stream.ts",
+    "./sync": "./sync.ts"
+  },
+  "files": [
+    "*.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "release-notes"
+  ],
+  "scripts": {
+    "start": "bun run devthink.ts",
+    "dev": "bun --watch run devthink.ts",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "check": "bun run check:secrets && bun run test",
+    "check:secrets": "bun run check-secrets.ts",
+    "build:binary": "bun run build.ts",
+    "build": "bun build ./devthink.ts --outdir dist --target bun",
+    "release": "bun run check && bun run build:binary"
+  },
+  "engines": {
+    "bun": ">=1.1.1",
+    "node": ">=26.7.0"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "developer-tools",
+    "llm",
+    "streaming",
+    "terminal",
+    "provider-endpoints",
+    "embedded-gateway",
+    "web-workbench"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
+  "homepage": "https://wenathlan.github.io/devthink/",
+  "bugs": {
+    "url": "https://github.com/wenathlan/devthink/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/plugin.ts

@@ -0,0 +1,68 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export type PluginContext = {
+  cwd: string;
+  log: (message: string) => void;
+};
+
+export type PluginDefinition = {
+  name: string;
+  version?: string;
+  hooks?: Record<string, (payload: unknown, context: PluginContext) => unknown | Promise<unknown>>;
+};
+
+export type PluginManifest = {
+  name: string;
+  entry: string;
+  enabled?: boolean;
+};
+
+function pluginRoot(): string {
+  return join(process.env.DEVTHINK_HOME || join(process.cwd(), ".devthink"), "plugins");
+}
+
+function readManifest(path: string): PluginManifest | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as PluginManifest;
+    if (!parsed.name || !parsed.entry) return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+async function importPlugin(manifestPath: string, manifest: PluginManifest): Promise<PluginDefinition> {
+  const entry = resolve(join(manifestPath, "..", manifest.entry));
+  const loaded = (await import(pathToFileURL(entry).href)) as { default?: PluginDefinition } & PluginDefinition;
+  return loaded.default || loaded;
+}
+
+export function listPluginManifests(root = pluginRoot()): PluginManifest[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter((item) => item.isDirectory()).map((item) => readManifest(join(root, item.name, "devthink.plugin.json"))).filter((item): item is PluginManifest => Boolean(item));
+}
+
+export async function loadPlugins(root = pluginRoot()): Promise<PluginDefinition[]> {
+  const manifests = listPluginManifests(root).filter((manifest) => manifest.enabled !== false);
+  const plugins: PluginDefinition[] = [];
+  for (const manifest of manifests) {
+    const path = join(root, manifest.name, "devthink.plugin.json");
+    try {
+      plugins.push(await importPlugin(path, manifest));
+    } catch {
+      // A broken optional plugin does not prevent the core CLI from starting.
+    }
+  }
+  return plugins;
+}
+
+export async function runHook(plugins: PluginDefinition[], hook: string, payload: unknown, context: PluginContext): Promise<unknown[]> {
+  const results: unknown[] = [];
+  for (const plugin of plugins) {
+    const handler = plugin.hooks?.[hook];
+    if (handler) results.push(await handler(payload, context));
+  }
+  return results;
+}

package/providers.ts

@@ -0,0 +1,179 @@
+import { resolveCredential, type DevThinkConfig, type DevThinkPaths } from "./config.ts";
+import { redactProviderError, retryDelay, type ProviderProtocol } from "./compatibility.ts";
+import { parseEventStream, type ChatEvent } from "./stream.ts";
+
+export type ChatRole = "system" | "user" | "assistant";
+
+export type ChatMessage = {
+  role: ChatRole;
+  content: string;
+};
+
+export type ChatRequest = {
+  provider: string;
+  model: string;
+  messages: ChatMessage[];
+  temperature?: number;
+  maxTokens?: number;
+  signal?: AbortSignal;
+};
+
+export type ModelInfo = {
+  id: string;
+  provider: string;
+  contextWindow?: number;
+  supportsStreaming: boolean;
+};
+
+type ProviderDefinition = {
+  id: string;
+  baseUrl?: string;
+  protocol: ProviderProtocol;
+  env: string;
+};
+
+const PROVIDERS: ProviderDefinition[] = [
+  { id: "openai", baseUrl: "https://api.openai.com/v1", protocol: "openai", env: "OPENAI_API_KEY" },
+  { id: "zai", baseUrl: "https://api.z.ai/api/paas/v4", protocol: "openai", env: "ZAI_API_KEY" },
+  { id: "openrouter", baseUrl: "https://openrouter.ai/api/v1", protocol: "openai", env: "OPENROUTER_API_KEY" },
+  { id: "anthropic", baseUrl: "https://api.anthropic.com", protocol: "anthropic", env: "ANTHROPIC_API_KEY" },
+  { id: "google", baseUrl: "https://generativelanguage.googleapis.com/v1beta", protocol: "google", env: "GEMINI_API_KEY" },
+  { id: "qwen", baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", protocol: "openai", env: "QWEN_API_KEY" },
+  { id: "deepseek", baseUrl: "https://api.deepseek.com", protocol: "openai", env: "DEEPSEEK_API_KEY" },
+  { id: "groq", baseUrl: "https://api.groq.com/openai/v1", protocol: "openai", env: "GROQ_API_KEY" },
+  { id: "mistral", baseUrl: "https://api.mistral.ai/v1", protocol: "openai", env: "MISTRAL_API_KEY" },
+  { id: "xai", baseUrl: "https://api.x.ai/v1", protocol: "openai", env: "XAI_API_KEY" },
+  { id: "ollama", protocol: "openai", env: "OLLAMA_API_KEY" },
+  { id: "mimo", baseUrl: "https://api.xiaomimimo.com/v1", protocol: "openai", env: "MIMO_API_KEY" },
+];
+
+function findProvider(provider: string): ProviderDefinition {
+  const definition = PROVIDERS.find((item) => item.id === provider.toLowerCase());
+  if (!definition) throw new Error(`Unknown provider: ${provider}. Use devthink providers.`);
+  return definition;
+}
+
+function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+}
+
+function cleanError(body: string, status: number): Error {
+  let detail = body.trim();
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    const error = (parsed.error || parsed.message || parsed.detail) as unknown;
+    if (typeof error === "string") detail = error;
+    if (error && typeof error === "object") detail = JSON.stringify(error);
+  } catch {
+    detail = body.trim();
+  }
+  const safe = redactProviderError(detail);
+  return new Error(`${status} ${safe || "Provider request failed."}`);
+}
+
+/** Uses the provider's configured endpoint directly; custom gateways are represented by `providers.<id>.baseUrl`. */
+async function fetchWithRetry(input: string, init: RequestInit, attempts = 3): Promise<Response> {
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const response = await fetch(input, init);
+      if (response.ok || response.status < 500 || attempt === attempts) return response;
+      await new Promise((resolve) => setTimeout(resolve, retryDelay(attempt - 1)));
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts) throw error;
+      await new Promise((resolve) => setTimeout(resolve, retryDelay(attempt - 1)));
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Provider request failed.");
+}
+
+function buildOpenAiHeaders(credential: string): HeadersInit {
+  return { accept: "text/event-stream", "content-type": "application/json", authorization: `Bearer ${credential}` };
+}
+
+function buildAnthropicHeaders(credential: string): HeadersInit {
+  return { accept: "text/event-stream", "content-type": "application/json", "x-api-key": credential, "anthropic-version": "2023-06-01" };
+}
+
+function buildGoogleBody(request: ChatRequest): Record<string, unknown> {
+  const system = request.messages.filter((message) => message.role === "system").map((message) => ({ text: message.content }));
+  const contents = request.messages.filter((message) => message.role !== "system").map((message) => ({
+    role: message.role === "assistant" ? "model" : "user",
+    parts: [{ text: message.content }],
+  }));
+  return {
+    ...(system.length ? { systemInstruction: { parts: system } } : {}),
+    contents,
+    generationConfig: {
+      ...(request.temperature === undefined ? {} : { temperature: request.temperature }),
+      ...(request.maxTokens === undefined ? {} : { maxOutputTokens: request.maxTokens }),
+    },
+  };
+}
+
+function buildAnthropicBody(request: ChatRequest): Record<string, unknown> {
+  const system = request.messages.filter((message) => message.role === "system").map((message) => message.content).join("\n\n");
+  return {
+    model: request.model,
+    messages: request.messages.filter((message) => message.role !== "system"),
+    max_tokens: request.maxTokens ?? 4096,
+    stream: true,
+    ...(system ? { system } : {}),
+    ...(request.temperature === undefined ? {} : { temperature: request.temperature }),
+  };
+}
+
+function buildOpenAiBody(request: ChatRequest): Record<string, unknown> {
+  return {
+    model: request.model,
+    messages: request.messages,
+    stream: true,
+    ...(request.temperature === undefined ? {} : { temperature: request.temperature }),
+    ...(request.maxTokens === undefined ? {} : { max_tokens: request.maxTokens }),
+  };
+}
+
+export function listProviders(): ProviderDefinition[] {
+  return PROVIDERS.map((provider) => ({ ...provider }));
+}
+
+export function resolveProvider(provider: string, config: DevThinkConfig, paths?: DevThinkPaths): ProviderDefinition & { baseUrl: string; credential: string } {
+  const definition = findProvider(provider);
+  const isActive = provider === (config.activeProvider || config.provider);
+  const baseUrl = config.providers?.[provider]?.baseUrl || (isActive ? config.baseUrl : undefined) || definition.baseUrl;
+  if (!baseUrl) throw new Error(`Provider ${provider} requires baseUrl in config or --base-url.`);
+  const credential = resolveCredential(provider, config, paths);
+  if (!credential) throw new Error(`No credential found for ${provider}. Set ${definition.env} or configure it explicitly.`);
+  return { ...definition, baseUrl, credential };
+}
+
+export async function streamChat(request: ChatRequest, config: DevThinkConfig, paths?: DevThinkPaths): Promise<AsyncGenerator<ChatEvent>> {
+  const provider = resolveProvider(request.provider, config, paths);
+  const url = provider.protocol === "google"
+    ? `${joinUrl(provider.baseUrl, `models/${encodeURIComponent(request.model)}:streamGenerateContent`)}?alt=sse`
+    : joinUrl(provider.baseUrl, provider.protocol === "anthropic" ? "/v1/messages" : "/chat/completions");
+  const headers = provider.protocol === "google"
+    ? { accept: "text/event-stream", "content-type": "application/json", "x-goog-api-key": provider.credential }
+    : provider.protocol === "anthropic" ? buildAnthropicHeaders(provider.credential) : buildOpenAiHeaders(provider.credential);
+  const body = provider.protocol === "google" ? buildGoogleBody(request) : provider.protocol === "anthropic" ? buildAnthropicBody(request) : buildOpenAiBody(request);
+  const response = await fetchWithRetry(url, { method: "POST", headers, body: JSON.stringify(body), signal: request.signal });
+  if (!response.ok) throw cleanError(await response.text(), response.status);
+  return parseEventStream(response, { provider: provider.id, model: request.model, signal: request.signal });
+}
+
+export async function listModels(providerName: string, config: DevThinkConfig, paths?: DevThinkPaths): Promise<ModelInfo[]> {
+  const provider = resolveProvider(providerName, config, paths);
+  if (provider.protocol === "google") {
+    const response = await fetchWithRetry(joinUrl(provider.baseUrl, "models"), { headers: { "x-goog-api-key": provider.credential } });
+    if (!response.ok) throw cleanError(await response.text(), response.status);
+    const payload = (await response.json()) as { models?: Array<{ name?: string; inputTokenLimit?: number }> };
+    return (payload.models || []).map((model) => ({ id: (model.name || "").replace(/^models\//, ""), provider: provider.id, contextWindow: model.inputTokenLimit, supportsStreaming: true }));
+  }
+  const path = provider.protocol === "anthropic" ? "/v1/models" : "/models";
+  const headers = provider.protocol === "anthropic" ? buildAnthropicHeaders(provider.credential) : buildOpenAiHeaders(provider.credential);
+  const response = await fetchWithRetry(joinUrl(provider.baseUrl, path), { headers });
+  if (!response.ok) throw cleanError(await response.text(), response.status);
+  const payload = (await response.json()) as { data?: Array<{ id?: string; context_length?: number }> };
+  return (payload.data || []).filter((model) => model.id).map((model) => ({ id: model.id as string, provider: provider.id, contextWindow: model.context_length, supportsStreaming: true }));
+}

package/server.ts

@@ -0,0 +1,227 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { randomInt } from "node:crypto";
+import { isAllowedOrigin } from "./compatibility.ts";
+import { listModels, listProviders, streamChat, type ChatMessage } from "./providers.ts";
+import { ensurePaths, resolvePaths, saveConfig, type DevThinkConfig, type DevThinkPaths } from "./config.ts";
+import { consumePairing, getIdentity, pairingStatus, revokeBrowserSessions, verifyBrowserSession } from "./identity.ts";
+import { appendMessage, createSession, createTab, listSessions, loadSession, loadWorkspace, updateTab, type SessionSection } from "./session.ts";
+
+export type ServerOptions = {
+  port?: number;
+  config: DevThinkConfig;
+  paths?: DevThinkPaths;
+};
+
+export type ServerHandle = {
+  address: string;
+  port: number;
+  stop: () => Promise<void>;
+};
+
+function writeJson(response: ServerResponse, status: number, payload: unknown, origin?: string): void {
+  if (origin) response.setHeader("access-control-allow-origin", origin);
+  response.setHeader("vary", "Origin");
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(payload));
+}
+
+function safeOrigin(request: IncomingMessage, config: DevThinkConfig): string | undefined {
+  const origin = request.headers.origin;
+  return isAllowedOrigin(origin, config.web?.allowedOrigins) ? origin : undefined;
+}
+
+function bearerToken(request: IncomingMessage): string | undefined {
+  const value = request.headers.authorization;
+  return value?.startsWith("Bearer ") ? value.slice("Bearer ".length).trim() || undefined : undefined;
+}
+
+function writeEvent(response: ServerResponse, type: string, payload: unknown): void {
+  response.write(`event: ${type}\ndata: ${JSON.stringify(payload)}\n\n`);
+}
+
+async function readBody(request: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) chunks.push(Buffer.from(chunk));
+  const raw = Buffer.concat(chunks).toString("utf8");
+  const parsed: unknown = raw ? JSON.parse(raw) : {};
+  return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+}
+
+function messagesFromBody(value: unknown): ChatMessage[] {
+  if (!Array.isArray(value)) throw new Error("messages must be an array.");
+  return value.map((item) => {
+    const message = item as Record<string, unknown>;
+    if (!message.content || !["system", "user", "assistant"].includes(String(message.role))) throw new Error("Each message needs a supported role and content.");
+    return { role: message.role as ChatMessage["role"], content: String(message.content) };
+  });
+}
+
+function sectionFrom(value: unknown): SessionSection {
+  return ["chat", "inspector", "settings", "memory", "providers", "projects", "routes", "usage"].includes(String(value)) ? value as SessionSection : "chat";
+}
+
+function routeParts(pathname: string): string[] {
+  return pathname.split("/").filter(Boolean).map(decodeURIComponent);
+}
+
+async function streamChatRoute(request: IncomingMessage, response: ServerResponse, config: DevThinkConfig, paths: DevThinkPaths, origin?: string): Promise<void> {
+  const body = await readBody(request);
+  const provider = String(body.provider || config.provider || "");
+  const model = String(body.model || config.model || "");
+  if (!provider || !model) return writeJson(response, 400, { error: "provider and model are required." }, origin);
+  const incoming = messagesFromBody(body.messages);
+  const prompt = [...incoming].reverse().find((message) => message.role === "user");
+  if (!prompt) return writeJson(response, 400, { error: "messages must include a user message." }, origin);
+  const sessionId = typeof body.sessionId === "string" ? body.sessionId : undefined;
+  const workspaceId = typeof body.workspaceId === "string" ? body.workspaceId : undefined;
+  const tabId = typeof body.tabId === "string" ? body.tabId : undefined;
+  const sectionId = sectionFrom(body.sectionId);
+  let session = sessionId ? loadSession(paths, sessionId) : undefined;
+  if (sessionId && !session) return writeJson(response, 404, { error: "Session not found." }, origin);
+  if (!session) session = createSession(paths, { mode: typeof body.mode === "string" ? body.mode : "chat", model, provider, workspaceId, tabId, sectionId, title: typeof body.title === "string" ? body.title : undefined });
+  if (workspaceId && session.workspaceId !== workspaceId) return writeJson(response, 409, { error: "workspaceId does not match the session." }, origin);
+  if (tabId && !session.tabs.some((tab) => tab.id === tabId)) return writeJson(response, 404, { error: "Tab not found." }, origin);
+  session = appendMessage(paths, session, prompt, { tabId: tabId || session.activeTabId, sectionId });
+  const history = session.messages.map(({ role, content }) => ({ role, content }));
+  const events = await streamChat({ provider, model, messages: history, temperature: typeof body.temperature === "number" ? body.temperature : config.temperature, maxTokens: typeof body.maxTokens === "number" ? body.maxTokens : config.maxTokens }, config, paths);
+  if (origin) response.setHeader("access-control-allow-origin", origin);
+  response.setHeader("vary", "Origin");
+  response.writeHead(200, { "cache-control": "no-cache", connection: "keep-alive", "content-type": "text/event-stream; charset=utf-8" });
+  writeEvent(response, "identity", { workspaceId: session.workspaceId, sessionId: session.id, tabId: tabId || session.activeTabId, sectionId });
+  let text = "";
+  for await (const event of events) {
+    if (event.type === "text") text += event.text;
+    writeEvent(response, event.type, event);
+  }
+  const persisted = appendMessage(paths, session, { role: "assistant", content: text }, { tabId: tabId || session.activeTabId, sectionId });
+  writeEvent(response, "persisted", { workspaceId: persisted.workspaceId, sessionId: persisted.id, tabId: tabId || persisted.activeTabId, messageId: persisted.messages.at(-1)?.id });
+  response.end();
+}
+
+async function route(request: IncomingMessage, response: ServerResponse, config: DevThinkConfig, paths: DevThinkPaths): Promise<void> {
+  const url = new URL(request.url || "/", "http://127.0.0.1");
+  const origin = safeOrigin(request, config);
+  if (request.method === "OPTIONS") {
+    if (origin) response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("access-control-allow-methods", "GET, POST, PATCH, PUT, OPTIONS");
+    response.setHeader("access-control-allow-headers", "authorization, content-type");
+    response.setHeader("vary", "Origin");
+    response.writeHead(204);
+    return response.end();
+  }
+  if (request.headers.origin && !origin) return writeJson(response, 403, { error: "Origin is not allowed by web.allowedOrigins." });
+  if (request.method === "GET" && url.pathname === "/health") return writeJson(response, 200, { status: "ok", service: "devthink" }, origin);
+  if (request.method === "GET" && url.pathname === "/providers") return writeJson(response, 200, listProviders().map(({ id, protocol, env }) => ({ id, protocol, env })), origin);
+  if (request.method === "GET" && url.pathname === "/models") {
+    const provider = url.searchParams.get("provider") || config.provider;
+    if (!provider) return writeJson(response, 400, { error: "provider is required." }, origin);
+    return writeJson(response, 200, await listModels(provider, config, paths), origin);
+  }
+  const parts = routeParts(url.pathname);
+  if (request.method === "POST" && url.pathname === "/pairings/consume") {
+    const body = await readBody(request);
+    const pairingId = typeof body.pairingId === "string" ? body.pairingId : "";
+    const code = typeof body.code === "string" ? body.code.trim().toUpperCase() : "";
+    const paired = consumePairing(paths, pairingId, code);
+    return paired ? writeJson(response, 201, { token: paired.token, userId: paired.identity.userId, expiresAt: paired.expiresAt }, origin) : writeJson(response, 401, { error: "Pairing code is invalid, expired, or already used." }, origin);
+  }
+  const browserSession = origin ? verifyBrowserSession(paths, bearerToken(request)) : undefined;
+  if (origin && !browserSession) return writeJson(response, 401, { error: "A current browser pairing token is required." }, origin);
+  if (request.method === "GET" && url.pathname === "/identity") return writeJson(response, 200, { identity: getIdentity(paths), pairing: pairingStatus(paths) }, origin);
+  if (request.method === "POST" && url.pathname === "/pairings/revoke") return writeJson(response, 200, { revoked: revokeBrowserSessions(paths) }, origin);
+  if (request.method === "GET" && url.pathname === "/sessions") return writeJson(response, 200, { sessions: listSessions(paths) }, origin);
+  if (request.method === "GET" && url.pathname === "/workspaces") {
+    const workspaces = new Map<string, { id: string; title: string; updatedAt: string; sessionCount: number }>();
+    for (const session of listSessions(paths)) {
+      const current = workspaces.get(session.workspaceId);
+      workspaces.set(session.workspaceId, { id: session.workspaceId, title: current?.title || session.title.replace(/^Untitled session$/, "Untitled workspace"), updatedAt: current?.updatedAt && current.updatedAt > session.updatedAt ? current.updatedAt : session.updatedAt, sessionCount: (current?.sessionCount || 0) + 1 });
+    }
+    return writeJson(response, 200, { workspaces: [...workspaces.values()].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)) }, origin);
+  }
+  if (request.method === "GET" && url.pathname === "/usage") {
+    const sessions = listSessions(paths);
+    const tabCount = sessions.reduce((total, session) => total + session.tabs.length, 0);
+    const messageCount = sessions.reduce((total, session) => total + session.messages.length, 0);
+    return writeJson(response, 200, { workspaces: new Set(sessions.map((session) => session.workspaceId)).size, sessions: sessions.length, tabs: tabCount, messages: messageCount, providers: listProviders().length, paired: pairingStatus(paths).activeSessions > 0 }, origin);
+  }
+  if (request.method === "PATCH" && url.pathname === "/providers/active") {
+    const body = await readBody(request);
+    const provider = typeof body.provider === "string" ? body.provider : "";
+    const model = typeof body.model === "string" ? body.model : undefined;
+    if (!listProviders().some((item) => item.id === provider)) return writeJson(response, 400, { error: "provider is not registered." }, origin);
+    const next = { ...config, activeProvider: provider, ...(model ? { activeModel: model } : {}) };
+    saveConfig(next, paths);
+    Object.assign(config, next);
+    return writeJson(response, 200, { activeProvider: next.activeProvider, activeModel: next.activeModel }, origin);
+  }
+  if (request.method === "GET" && parts[0] === "workspaces" && parts[1] && parts.length === 2) {
+    const workspace = loadWorkspace(paths, parts[1]);
+    if (!workspace) return writeJson(response, 404, { error: "Workspace not found." }, origin);
+    return writeJson(response, 200, { workspace, sessions: listSessions(paths).filter((session) => session.workspaceId === workspace.id) }, origin);
+  }
+  if (request.method === "POST" && parts[0] === "sessions" && parts.length === 1) {
+    const body = await readBody(request);
+    const session = createSession(paths, { mode: typeof body.mode === "string" ? body.mode : "chat", model: typeof body.model === "string" ? body.model : config.activeModel, provider: typeof body.provider === "string" ? body.provider : config.activeProvider, workspaceId: typeof body.workspaceId === "string" ? body.workspaceId : undefined, tabId: typeof body.tabId === "string" ? body.tabId : undefined, sectionId: sectionFrom(body.sectionId), title: typeof body.title === "string" ? body.title : undefined });
+    return writeJson(response, 201, session, origin);
+  }
+  if (parts[0] === "sessions" && parts[1] && parts.length === 2 && request.method === "GET") {
+    const session = loadSession(paths, parts[1]);
+    return session ? writeJson(response, 200, session, origin) : writeJson(response, 404, { error: "Session not found." }, origin);
+  }
+  if (parts[0] === "sessions" && parts[1] && parts[2] === "tabs" && parts.length === 3 && request.method === "POST") {
+    const session = loadSession(paths, parts[1]);
+    if (!session) return writeJson(response, 404, { error: "Session not found." }, origin);
+    const body = await readBody(request);
+    return writeJson(response, 201, createTab(paths, session, { id: typeof body.id === "string" ? body.id : undefined, label: typeof body.label === "string" ? body.label : undefined, provider: typeof body.provider === "string" ? body.provider : undefined, sectionId: sectionFrom(body.sectionId) }), origin);
+  }
+  if (parts[0] === "sessions" && parts[1] && parts[2] === "tabs" && parts[3] && parts.length === 4 && request.method === "PATCH") {
+    const session = loadSession(paths, parts[1]);
+    if (!session) return writeJson(response, 404, { error: "Session not found." }, origin);
+    const body = await readBody(request);
+    return writeJson(response, 200, updateTab(paths, session, parts[3], { label: typeof body.label === "string" ? body.label : undefined, provider: typeof body.provider === "string" ? body.provider : undefined, sectionId: body.sectionId === undefined ? undefined : sectionFrom(body.sectionId) }), origin);
+  }
+  if (request.method === "POST" && url.pathname === "/chat") return streamChatRoute(request, response, config, paths, origin);
+  return writeJson(response, 404, { error: "Route not found." }, origin);
+}
+
+function randomPort(): number {
+  return randomInt(1, 65_535);
+}
+
+function bind(server: Server, port: number): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const onError = (error: NodeJS.ErrnoException) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      const address = server.address();
+      resolve(typeof address === "object" && address ? address.port : port);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+export async function startServer(options: ServerOptions): Promise<ServerHandle> {
+  const paths = ensurePaths(options.paths || resolvePaths());
+  const server = createServer((request, response) => {
+    route(request, response, options.config, paths).catch((error: unknown) => writeJson(response, 500, { error: error instanceof Error ? error.message : "Request failed." }, safeOrigin(request, options.config)));
+  });
+  server.setMaxListeners(0);
+  let port = options.port || randomPort();
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    try {
+      port = await bind(server, port);
+      const address = `http://127.0.0.1:${port}`;
+      return { address, port, stop: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())) };
+    } catch (error) {
+      lastError = error;
+      port = randomPort();
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Could not bind the local server.");
+}