@taicho-ai/framework 0.1.0

package/src/core/mcp/manager.ts

@@ -0,0 +1,145 @@
+/** Connects to MCP servers and exposes their tools to agents. Dynamically mutable so the `/mcp`
+ *  command works without a restart: add/remove/login/reconnect mutate the live connection map, and
+ *  because toolsForAgent reads the manager at run time, changes are picked up on the next run.
+ *  A server that fails to connect is recorded (status) and skipped — it never crashes the REPL. */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { ToolSet } from "ai";
+import { isStdioServer, interpolateEnv, type McpServerConfig } from "../../store/config";
+import { mcpToolToAiTool, type McpCallResult } from "./adapter";
+import { createMcpOAuthProvider, runMcpOAuth, defaultOpenBrowser, McpAuthRequiredError } from "./oauth";
+
+export type McpStatus = "connected" | "error" | "needs-auth";
+export interface McpServerStatus { name: string; kind: "stdio" | "http"; status: McpStatus; toolCount: number; error?: string }
+
+export interface McpManager {
+  /** Resolve a per-agent MCP grant ("server" or "server/tool", from an agent's `mcp:<…>` tool ref)
+   *  to namespaced AI-SDK tools. This is the ONLY way MCP tools reach an agent — there is no blanket
+   *  "all tools to all agents" grant (Plan 08 security hardening). */
+  toolsForRef(ref: string): ToolSet;
+  list(): McpServerStatus[];
+  addServer(name: string, spec: McpServerConfig): Promise<McpServerStatus>;
+  removeServer(name: string): Promise<boolean>;
+  login(name: string): Promise<McpServerStatus>;
+  reconnect(name: string): Promise<McpServerStatus>;
+  closeAll(): Promise<void>;
+}
+
+interface Entry { spec: McpServerConfig; kind: "stdio" | "http"; client?: Client; status: McpStatus; toolCount: number; error?: string; set: ToolSet }
+
+const sanitize = (s: string): string => s.replace(/[^a-zA-Z0-9_-]/g, "_");
+// Namespaced + capped at 64 chars (the model-provider tool-name limit) to avoid a call-time 400.
+const toolKey = (server: string, tool: string): string => `${sanitize(server)}_${sanitize(tool)}`.slice(0, 64);
+
+export interface McpManagerOptions {
+  ws: string;
+  servers: Record<string, McpServerConfig>;
+  onUrl?: (url: string) => void;             // print the OAuth URL (paste fallback)
+  openBrowser?: (url: string) => void;
+}
+
+export async function createMcpManager(opts: McpManagerOptions): Promise<McpManager> {
+  const entries = new Map<string, Entry>();
+  const openBrowser = opts.openBrowser ?? defaultOpenBrowser;
+
+  /** Connect one server. interactive=true permits the OAuth browser flow; false (boot) refuses it. */
+  async function connectOne(name: string, spec: McpServerConfig, interactive: boolean): Promise<Entry> {
+    const kind: Entry["kind"] = isStdioServer(spec) ? "stdio" : "http";
+    const client = new Client({ name: "taicho", version: "0.0.1" }, { capabilities: {} });
+    try {
+      if (isStdioServer(spec)) {
+        const env = Object.fromEntries(Object.entries(spec.env ?? {}).map(([k, v]) => [k, interpolateEnv(v)]));
+        await client.connect(new StdioClientTransport({ command: spec.command, args: spec.args, env: { ...getDefaultEnvironment(), ...env } }));
+      } else if (spec.auth === "oauth") {
+        // Fresh provider+transport per attempt — the OAuth reconnect after finishAuth needs a new
+        // transport (the first one is already started), so runMcpOAuth calls makeTransport twice.
+        const makeTransport = () => new StreamableHTTPClientTransport(new URL(interpolateEnv(spec.url)), {
+          authProvider: createMcpOAuthProvider({
+            ws: opts.ws,
+            serverName: name,
+            redirectToAuthorization: interactive
+              ? (url) => { opts.onUrl?.(url.toString()); openBrowser(url.toString()); }
+              : () => { throw new McpAuthRequiredError(name); },
+          }),
+        });
+        if (interactive) await runMcpOAuth({ makeTransport, connect: (t) => client.connect(t) });
+        else await client.connect(makeTransport());
+      } else {
+        const headers = Object.fromEntries(Object.entries(spec.headers ?? {}).map(([k, v]) => [k, interpolateEnv(v)]));
+        await client.connect(new StreamableHTTPClientTransport(new URL(interpolateEnv(spec.url)), { requestInit: { headers } }));
+      }
+      const { tools } = await client.listTools();
+      const set: ToolSet = {};
+      for (const t of tools) {
+        set[t.name] = mcpToolToAiTool(
+          async (n, args) => (await client.callTool({ name: n, arguments: args })) as unknown as McpCallResult,
+          { name: t.name, description: t.description, inputSchema: t.inputSchema },
+        );
+      }
+      return { spec, kind, client, status: "connected", toolCount: tools.length, set };
+    } catch (e) {
+      await client.close().catch(() => {});
+      const needsAuth = e instanceof McpAuthRequiredError || e instanceof UnauthorizedError;
+      return { spec, kind, status: needsAuth ? "needs-auth" : "error", toolCount: 0, error: e instanceof Error ? e.message : String(e), set: {} };
+    }
+  }
+
+  async function set(name: string, spec: McpServerConfig, interactive: boolean): Promise<McpServerStatus> {
+    const prev = entries.get(name);
+    if (prev?.client) await prev.client.close().catch(() => {});
+    // Hold a transient (non-connected) slot during the async connect so a concurrent toolsForRef
+    // never hands an agent the just-closed client.
+    entries.set(name, { spec, kind: isStdioServer(spec) ? "stdio" : "http", status: "error", toolCount: 0, error: "connecting…", set: {} });
+    const e = await connectOne(name, spec, interactive);
+    entries.set(name, e);
+    return statusOf(name, e);
+  }
+
+  function statusOf(name: string, e: Entry): McpServerStatus {
+    return { name, kind: e.kind, status: e.status, toolCount: e.toolCount, error: e.error };
+  }
+
+  // Connect everything concurrently at boot (non-interactive).
+  await Promise.all(Object.entries(opts.servers).map(([name, spec]) =>
+    connectOne(name, spec, false).then((e) => { entries.set(name, e); })));
+
+  return {
+    toolsForRef(ref) {
+      const slash = ref.indexOf("/");
+      const server = slash === -1 ? ref : ref.slice(0, slash);
+      const toolName = slash === -1 ? undefined : ref.slice(slash + 1);
+      const e = entries.get(server);
+      if (!e || e.status !== "connected") return {};
+      if (toolName) return e.set[toolName] ? { [toolKey(server, toolName)]: e.set[toolName] } : {};
+      const out: ToolSet = {};
+      for (const [n, t] of Object.entries(e.set)) out[toolKey(server, n)] = t;
+      return out;
+    },
+    list() {
+      return [...entries.entries()].map(([name, e]) => statusOf(name, e));
+    },
+    addServer(name, spec) { return set(name, spec, /*interactive*/ true); },
+    login(name) {
+      const e = entries.get(name);
+      if (!e) return Promise.reject(new Error(`no MCP server "${name}"`));
+      return set(name, e.spec, /*interactive*/ true);
+    },
+    reconnect(name) {
+      const e = entries.get(name);
+      if (!e) return Promise.reject(new Error(`no MCP server "${name}"`));
+      return set(name, e.spec, /*interactive*/ false);
+    },
+    async removeServer(name) {
+      const e = entries.get(name);
+      if (!e) return false;
+      if (e.client) await e.client.close().catch(() => {});
+      entries.delete(name);
+      return true;
+    },
+    async closeAll() {
+      await Promise.all([...entries.values()].map((e) => e.client?.close().catch(() => {})));
+    },
+  };
+}

package/src/core/mcp/oauth.ts

@@ -0,0 +1,119 @@
+/** OAuth for remote MCP servers. A file-backed OAuthClientProvider (the SDK drives discovery, PKCE,
+ *  and dynamic client registration) + a loopback-callback connect helper that mirrors taicho's
+ *  ChatGPT OAuth (core/auth/login.ts): a Bun.serve on localhost catches the redirect code. Tokens
+ *  persist per server under agents/.mcp/ (gitignored) at mode 0600 and are never logged. */
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { UnauthorizedError, type OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { OAuthTokens, OAuthClientMetadata, OAuthClientInformationMixed } from "@modelcontextprotocol/sdk/shared/auth.js";
+
+export const MCP_OAUTH_PORT = 1456; // distinct from the ChatGPT login port (1455)
+export const MCP_OAUTH_PATH = "/oauth/callback";
+export const mcpRedirectUrl = (port = MCP_OAUTH_PORT): string => `http://localhost:${port}${MCP_OAUTH_PATH}`;
+
+/** Thrown (instead of opening a browser) when a connect needs interactive auth in a non-interactive
+ *  context (boot). The user then runs `/mcp login <server>`. */
+export class McpAuthRequiredError extends Error {
+  constructor(public server: string) { super(`MCP server "${server}" needs sign-in — run /mcp login ${server}`); }
+}
+
+interface OAuthState { tokens?: OAuthTokens; clientInformation?: OAuthClientInformationMixed; codeVerifier?: string }
+
+const stateDir = (ws: string): string => join(ws, "agents", ".mcp");
+const statePath = (ws: string, server: string): string => join(stateDir(ws), `${server}-oauth.json`);
+
+function readState(ws: string, server: string): OAuthState {
+  const f = statePath(ws, server);
+  if (!existsSync(f)) return {};
+  try { return JSON.parse(readFileSync(f, "utf8")) as OAuthState; } catch { return {}; }
+}
+function writeState(ws: string, server: string, patch: Partial<OAuthState>): void {
+  mkdirSync(stateDir(ws), { recursive: true });
+  writeFileSync(statePath(ws, server), JSON.stringify({ ...readState(ws, server), ...patch }, null, 2), { mode: 0o600 });
+}
+
+/** Build the provider. `redirectToAuthorization` is injected so boot can refuse (throw
+ *  McpAuthRequiredError) while `/mcp login` opens the browser. Storage is shared via files, so
+ *  provider instances are interchangeable across attempts. */
+export function createMcpOAuthProvider(opts: {
+  ws: string;
+  serverName: string;
+  redirectToAuthorization: (url: URL) => void;
+  redirectPort?: number;
+}): OAuthClientProvider {
+  const { ws, serverName } = opts;
+  return {
+    get redirectUrl() { return mcpRedirectUrl(opts.redirectPort); },
+    get clientMetadata(): OAuthClientMetadata {
+      return {
+        client_name: "taicho",
+        redirect_uris: [mcpRedirectUrl(opts.redirectPort)],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+      };
+    },
+    clientInformation() { return readState(ws, serverName).clientInformation; },
+    saveClientInformation(info) { writeState(ws, serverName, { clientInformation: info }); },
+    tokens() { return readState(ws, serverName).tokens; },
+    saveTokens(t) { writeState(ws, serverName, { tokens: t }); },
+    redirectToAuthorization(url) { opts.redirectToAuthorization(url); },
+    saveCodeVerifier(v) { writeState(ws, serverName, { codeVerifier: v }); },
+    codeVerifier() {
+      const v = readState(ws, serverName).codeVerifier;
+      if (!v) throw new Error("no PKCE code_verifier saved for MCP OAuth");
+      return v;
+    },
+  };
+}
+
+/** Interactive flow: start the loopback server, connect (the SDK opens the browser via
+ *  redirectToAuthorization), capture the code, finishAuth, then RECONNECT WITH A FRESH TRANSPORT.
+ *  The reconnect must use a new transport: the first connect started the original one, and the
+ *  StreamableHTTP transport's close() aborts but never clears its started flag, so reusing it
+ *  throws "already started". `makeTransport` produces a fresh transport each call; `connect`
+ *  reconnects the same Client (its transport was cleared by the failed connect's close()). */
+export async function runMcpOAuth(opts: {
+  makeTransport: () => StreamableHTTPClientTransport;
+  connect: (transport: StreamableHTTPClientTransport) => Promise<void>;
+  redirectPort?: number;
+  timeoutMs?: number;
+}): Promise<void> {
+  const port = opts.redirectPort ?? MCP_OAUTH_PORT;
+  let resolveCode!: (c: string) => void;
+  let rejectFlow!: (e: Error) => void;
+  const codeP = new Promise<string>((res, rej) => { resolveCode = res; rejectFlow = rej; });
+  const server = Bun.serve({
+    port,
+    fetch(req) {
+      const u = new URL(req.url);
+      if (u.pathname === MCP_OAUTH_PATH) {
+        const err = u.searchParams.get("error");
+        if (err) { rejectFlow(new Error(u.searchParams.get("error_description") ?? err)); return new Response("authorization failed", { status: 400 }); }
+        const code = u.searchParams.get("code");
+        if (code) { resolveCode(code); return new Response("taicho: MCP server authorized — you can close this tab."); }
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  const timer = setTimeout(() => rejectFlow(new Error("MCP OAuth timed out")), opts.timeoutMs ?? 120_000);
+  try {
+    const first = opts.makeTransport();
+    try { await opts.connect(first); return; } catch (e) { if (!(e instanceof UnauthorizedError)) throw e; }
+    const code = await codeP;
+    await first.finishAuth(code); // exchanges code -> tokens (persisted via the provider); HTTP only
+    await opts.connect(opts.makeTransport()); // fresh transport; tokens now on disk
+  } finally {
+    clearTimeout(timer);
+    server.stop(true);
+  }
+}
+
+export function defaultOpenBrowser(url: string): void {
+  // `start` is a cmd.exe builtin, so on Windows it must be invoked via `cmd /c start "" <url>`.
+  const argv = process.platform === "darwin" ? ["open", url]
+    : process.platform === "win32" ? ["cmd", "/c", "start", "", url]
+    : ["xdg-open", url];
+  try { Bun.spawn(argv, { stdout: "ignore", stderr: "ignore" }); } catch { /* fall back to the printed URL */ }
+}

package/src/core/memory.ts

@@ -0,0 +1,13 @@
+/** A read-only digest of an agent's recent runs, injected into its prompt context so workers
+ *  retain continuity across runs (no per-worker conversation thread needed for v1). */
+import { listTraces } from "../store/trace";
+
+export function recentRunsDigest(ws: string, agentId: string, k = 5): string | undefined {
+  const traces = listTraces(ws, agentId);
+  if (!traces.length) return undefined;
+  const recent = traces.slice(-k).reverse(); // newest first
+  const lines = recent.map(
+    (t) => `- ${t.task} → ${t.outcome}${t.artifacts.length ? ` (artifacts: ${t.artifacts.join(", ")})` : ""}`,
+  );
+  return `## Your recent runs\n${lines.join("\n")}`;
+}

package/src/core/mock-model.ts

@@ -0,0 +1,70 @@
+/** Test-only helper. Plan 07 unified the loop on `streamText`, so the AI SDK now drives every model
+ *  via `doStream` (not `doGenerate`). Tests still script models as text / tool-call GENERATE results,
+ *  so this `MockLanguageModelV3` subclass auto-derives a streaming `doStream` from a `doGenerate`
+ *  script — converting each result into the equivalent LanguageModelV3 stream parts, which streamText
+ *  drains back to the same aggregated fields (text, usage, toolCalls, providerMetadata). It still runs
+ *  the script through the recording `doGenerate` wrapper, so `.doGenerateCalls[i].prompt` / `.length`
+ *  assertions keep working unchanged. A test that passes `doStream` directly (the subscription/Codex
+ *  shape) is left exactly as the real mock handles it.
+ *
+ *  Usage: swap `from "ai/test"` for `from "./mock-model"` in a test's imports — nothing else changes.
+ *  `mockValues` and `simulateReadableStream` are re-exported so that single path move is enough. */
+import { MockLanguageModelV3 as RealMockLanguageModelV3, mockValues, simulateReadableStream } from "ai/test";
+import type { LanguageModelV3GenerateResult } from "@ai-sdk/provider";
+
+export { mockValues, simulateReadableStream };
+
+const DEFAULT_USAGE = { inputTokens: { total: 1 }, outputTokens: { total: 1 } };
+
+/** One generate result (content + finishReason + usage [+ providerMetadata]) → the stream parts a
+ *  doStream emits. Text becomes start/delta/end; a tool call becomes a single `tool-call` part; the
+ *  finish part carries usage + finishReason + any providerMetadata (e.g. OpenRouter's real cost). */
+export function streamParts(r: LanguageModelV3GenerateResult): unknown[] {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const res = r as any;
+  const parts: unknown[] = [{ type: "stream-start", warnings: [] }];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const content: any[] = Array.isArray(res.content) ? res.content : [];
+  content.forEach((part, i) => {
+    if (part.type === "text") {
+      const id = `t${i}`;
+      parts.push({ type: "text-start", id }, { type: "text-delta", id, delta: part.text }, { type: "text-end", id });
+    } else if (part.type === "tool-call") {
+      parts.push({ type: "tool-call", toolCallId: part.toolCallId, toolName: part.toolName, input: part.input });
+    } else if (part.type === "reasoning") {
+      const id = `g${i}`;
+      parts.push({ type: "reasoning-start", id }, { type: "reasoning-delta", id, delta: part.text ?? "" }, { type: "reasoning-end", id });
+    }
+  });
+  parts.push({
+    type: "finish",
+    finishReason: res.finishReason ?? { unified: "stop", raw: "stop" },
+    usage: res.usage ?? DEFAULT_USAGE,
+    providerMetadata: res.providerMetadata,
+  });
+  return parts;
+}
+
+type MockOpts = ConstructorParameters<typeof RealMockLanguageModelV3>[0];
+
+export class MockLanguageModelV3 extends RealMockLanguageModelV3 {
+  constructor(opts: MockOpts = {}) {
+    const o = opts ?? {};
+    if (o.doGenerate && !o.doStream) {
+      super({ provider: o.provider, modelId: o.modelId, supportedUrls: o.supportedUrls, doGenerate: o.doGenerate });
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      const self = this;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      this.doStream = (async (options: any) => {
+        // Run the SAME script through the recording doGenerate wrapper (records doGenerateCalls +
+        // advances mockValues), then stream the result it returns.
+        const r = (await self.doGenerate(options)) as LanguageModelV3GenerateResult;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return { stream: simulateReadableStream({ initialDelayInMs: 0, chunkDelayInMs: 0, chunks: streamParts(r) as any }) };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      }) as any;
+    } else {
+      super(o);
+    }
+  }
+}

package/src/core/model.ts

@@ -0,0 +1,91 @@
+/** provider+model -> AI-SDK model instance. Keys are read from env by the providers. */
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { generateText } from "ai";
+import type { Provider, ResolvedConfig, TaichoConfig } from "../store/config";
+import { log } from "./logger";
+import { withRequestTimeout, DEFAULT_MODEL_REQUEST_TIMEOUT_MS } from "@taicho-ai/agent/request-timeout";
+
+// Reuse the exact model param type generateText expects (robust across SDK versions).
+export type Model = Parameters<typeof generateText>[0]["model"];
+
+const warnedMismatch = new Set<string>();
+
+/** OpenRouter has no default model; fail loudly (not at an opaque call-time 400) when none is set.
+ *  The slug must be namespaced (vendor/model) — this also catches a first-party fallback model
+ *  (e.g. "claude-sonnet-4-6") bleeding into a per-agent `provider: openrouter` override.
+ *  Plan 12: `timeoutFetch` is the transport-deadline-wrapped fetch (a hung request errors + retries
+ *  via the AI SDK's maxRetries) — applied to EVERY env-key provider, not just codex. */
+function instantiate(provider: Provider, model: string, timeoutFetch: typeof fetch): Model {
+  if (provider === "openrouter") {
+    if (!model.includes("/")) {
+      throw new Error(
+        "OpenRouter requires an explicit namespaced model (vendor/model). Set TAICHO_MODEL or " +
+          "defaults.model in taicho.yaml, e.g. 'anthropic/claude-sonnet-4.5'. Browse slugs at " +
+          "https://openrouter.ai/models",
+      );
+    }
+    // apiKey defaults to OPENROUTER_API_KEY; the HTTP-Referer/X-Title headers are OpenRouter's
+    // recommended app attribution. usage:{include:true} (per model) returns the real per-call cost.
+    const openrouter = createOpenRouter({
+      apiKey: process.env.OPENROUTER_API_KEY,
+      headers: { "HTTP-Referer": "https://taicho.ai", "X-Title": "taicho" },
+      fetch: timeoutFetch,
+    });
+    return openrouter(model, { usage: { include: true } });
+  }
+  return provider === "anthropic"
+    ? createAnthropic({ fetch: timeoutFetch })(model)
+    : createOpenAI({ fetch: timeoutFetch })(model);
+}
+
+export function buildModel(cfg: ResolvedConfig, timeoutMs?: number): Model {
+  return instantiate(cfg.provider, cfg.model, withRequestTimeout(fetch, timeoutMs ?? DEFAULT_MODEL_REQUEST_TIMEOUT_MS));
+}
+
+export interface ResolvedModel { model: Model; modelId: string; provider: Provider; captureCost?: boolean; }
+
+/** @param teamsOf the running agent's teams (Plan 22: many-to-many), or undefined. Injected rather than
+ *  looked up so the resolver stays free of a DB import; the REPL passes a prepared registry query. */
+export function createModelResolver(opts: {
+  config: TaichoConfig;
+  fallback: ResolvedConfig;
+  timeoutMs?: number;
+  teamsOf?: (agentId: string) => string[];
+}): {
+  resolveModel: (agentId: string) => ResolvedModel;
+} {
+  const cache = new Map<string, Model>();
+  // Plan 12: one transport-deadline fetch shared across every model this resolver builds. The deadline
+  // is config-disposed (defaults.modelRequestTimeoutMs) — model-supplied values never reach it.
+  const timeoutFetch = withRequestTimeout(fetch, opts.timeoutMs ?? DEFAULT_MODEL_REQUEST_TIMEOUT_MS);
+  const resolveModel = (agentId: string): ResolvedModel => {
+    // Plan 19/22: agent → team → defaults. The agent still wins, so a single specialist can out-run its
+    // team's model without the team having to know about it. An agent on SEVERAL teams resolves against
+    // the first (in declaration order) that actually carries a model/provider override — deterministic,
+    // and the implicit `default` team (which never has one) is skipped for free.
+    const a = opts.config.agents?.[agentId];
+    const teamId = opts.teamsOf?.(agentId)?.find((id) => opts.config.teams?.[id]);
+    const t = teamId ? opts.config.teams?.[teamId] : undefined;
+    const provider: Provider = a?.provider ?? t?.provider ?? opts.config.defaults?.provider ?? opts.fallback.provider;
+    const model = a?.model ?? t?.model ?? opts.config.defaults?.model ?? opts.fallback.model;
+    const key = `${provider}:${model}`;
+    // Heuristic diagnostic: a partial per-agent override can pair a model id with a mismatched
+    // provider (e.g. an OpenAI model under the Anthropic provider). Warn once per provider:model
+    // so a misconfiguration surfaces here instead of as a cryptic call-time API error.
+    const looksMismatched =
+      (provider === "anthropic" && !model.startsWith("claude-")) ||
+      (provider === "openai" && model.startsWith("claude-"));
+    if (looksMismatched && !warnedMismatch.has(key)) {
+      warnedMismatch.add(key);
+      log.warn(`model "${model}" looks mismatched with provider "${provider}" for agent "${agentId}" — check taicho.yaml (set both provider and model)`);
+    }
+    let inst = cache.get(key);
+    if (!inst) { inst = instantiate(provider, model, timeoutFetch); cache.set(key, inst); }
+    // OpenRouter returns the real per-call cost (usage:{include:true}); the loop reads it from
+    // providerMetadata instead of the static price table.
+    return { model: inst, modelId: model, provider, captureCost: provider === "openrouter" || undefined };
+  };
+  return { resolveModel };
+}

package/src/core/pricing.ts

@@ -0,0 +1,27 @@
+/** Per-model USD pricing for advisory cost accounting. Tokens are the hard budget; cost is
+ *  secondary. Values are USD per 1,000,000 tokens. Unknown models price to 0 (never throw). */
+import { log } from "./logger";
+
+export interface ModelPrice { inUsdPerMTok: number; outUsdPerMTok: number; }
+
+const TABLE: Record<string, ModelPrice> = {
+  "claude-sonnet-4-6": { inUsdPerMTok: 3, outUsdPerMTok: 15 },
+  "claude-opus-4-8": { inUsdPerMTok: 15, outUsdPerMTok: 75 },
+  "gpt-5.5": { inUsdPerMTok: 5, outUsdPerMTok: 15 },
+};
+
+let warned = false;
+
+export function priceUsd(model: string, usage: { inputTokens: number; outputTokens: number }): number {
+  const p = TABLE[model];
+  if (!p) {
+    if (!warned) { warned = true; log.warn(`no price for model "${model}" — cost reported as 0`); }
+    return 0;
+  }
+  return (usage.inputTokens / 1_000_000) * p.inUsdPerMTok + (usage.outputTokens / 1_000_000) * p.outUsdPerMTok;
+}
+
+/** Build a pricer bound to a resolved model id (the agent loop is provider-agnostic). */
+export function pricerFor(model: string): (u: { inputTokens: number; outputTokens: number }) => number {
+  return (u) => priceUsd(model, u);
+}

package/src/core/providers/openai-codex.ts

@@ -0,0 +1,67 @@
+/** Codex-backed (ChatGPT subscription) provider. Built on the AI-SDK OpenAI provider with the
+ *  Codex baseURL + a custom fetch that injects the OAuth Bearer token and refreshes on 401.
+ *  Tokens are NEVER logged; use redactAuthHeader for any debug output. */
+import { createOpenAI } from "@ai-sdk/openai";
+import type { AuthProfile } from "../auth/profile";
+import { AuthExpiredError } from "../auth/refresh";
+import { OPENAI_CODEX_AUTH, codexHeaders } from "../auth/constants";
+import { log } from "../logger";
+import { withRequestTimeout, DEFAULT_MODEL_REQUEST_TIMEOUT_MS } from "@taicho-ai/agent/request-timeout";
+
+export function redactAuthHeader(value: string | null): string {
+  if (!value) return "";
+  return value.replace(/Bearer\s+\S+/i, "Bearer ***");
+}
+
+interface AuthFetchDeps {
+  load: () => AuthProfile | null;
+  refresh: () => Promise<AuthProfile>;
+  baseFetch?: typeof fetch;
+  /** Plan 12: per-request transport deadline (ms) for the model fetch. A genuinely hung request
+   *  (open socket, zero tokens) becomes a retryable error routed through the AI SDK's maxRetries,
+   *  instead of the deleted loop-level idle watchdog. Config-disposed; defaults to 120s. */
+  timeoutMs?: number;
+}
+
+/** Wrap fetch to inject Codex auth headers; on 401, refresh once (single-flight upstream) + retry. */
+export function makeAuthFetch(deps: AuthFetchDeps): typeof fetch {
+  const base = deps.baseFetch ?? fetch;
+  const send = (input: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1], profile: AuthProfile) => {
+    const headers = new Headers(init?.headers);
+    for (const [k, v] of Object.entries(codexHeaders(profile.access_token, profile.account_id))) headers.set(k, v);
+    return base(input, { ...init, headers });
+  };
+  return (async (input, init) => {
+    const profile = deps.load();
+    if (!profile) throw new AuthExpiredError();
+    let res = await send(input, init, profile);
+    if (res.status === 401) {
+      const refreshed = await deps.refresh(); // throws AuthExpiredError if refresh fails
+      res = await send(input, init, refreshed);
+    }
+    // Diagnostic: on a non-2xx, record the request URL + status + body snippet so endpoint/model
+    // mismatches are debuggable. Routed through the debug-level logger (raised by --verbose or the
+    // historical TAICHO_DEBUG env; see core/logger.ts envLevel) — the logger redacts, so the
+    // Authorization header can never leak even if it reappears in a body echo.
+    if (!res.ok) {
+      const url = input instanceof Request ? input.url : String(input);
+      const body = await res.clone().text().catch(() => "");
+      log.debug(`codex ${res.status} ${url} :: ${body.slice(0, 500)}`);
+    }
+    return res;
+  }) as typeof fetch;
+}
+
+/** An AI-SDK provider whose model calls hit the Codex backend with the subscription token.
+ *  apiKey is a placeholder — real auth is the Authorization header set by makeAuthFetch. */
+export function createCodexProvider(deps: AuthFetchDeps) {
+  return createOpenAI({
+    // The ChatGPT-subscription backend serves the Responses API at <codexBaseUrl>/responses
+    // (NO /v1 — that's the api.openai.com convention). The provider appends "/responses".
+    baseURL: OPENAI_CODEX_AUTH.codexBaseUrl,
+    apiKey: "codex-oauth",
+    // Plan 12: wrap the auth-injecting fetch with the transport deadline (outside makeAuthFetch, so it
+    // bounds the whole request including a 401 refresh+retry). A hang aborts the real connection.
+    fetch: withRequestTimeout(makeAuthFetch(deps), deps.timeoutMs ?? DEFAULT_MODEL_REQUEST_TIMEOUT_MS),
+  });
+}

package/src/core/registry.ts

@@ -0,0 +1,67 @@
+import type { Database } from "bun:sqlite";
+import { effectiveTeams, type AgentDef } from "@taicho-ai/contracts/agent";
+import { parseTeamAcl } from "@taicho-ai/contracts/team";
+
+/** Roster is human-controlled: creation flows through the root agent's proposal card,
+ *  never autonomous. Discovery is filtered by the CALLER's visibility ACL.
+ *
+ *  Plan 22: membership is many-to-many. The `registry` row keeps a denormalized PRIMARY team (the
+ *  agent's first explicit team, for cheap display/model resolution), while `agent_teams` is the real
+ *  membership index — one row per (agent, team), including the implicit `default` via effectiveTeams,
+ *  so "who is on team X" and "which teams is agent Y on" are both one indexed query. Per-agent rows are
+ *  replaced wholesale (delete-then-insert) so an edit that drops a team leaves no ghost membership. */
+export function syncRegistry(db: Database, agents: AgentDef[]) {
+  const insR = db.query("INSERT OR REPLACE INTO registry (id, role, is_root, team) VALUES (?, ?, ?, ?)");
+  const delAT = db.query("DELETE FROM agent_teams WHERE agent_id = ?");
+  const insAT = db.query("INSERT OR IGNORE INTO agent_teams (agent_id, team_id, ord) VALUES (?, ?, ?)");
+  for (const a of agents) {
+    insR.run(a.id, a.role, a.isRoot ? 1 : 0, a.teams[0] ?? null);
+    delAT.run(a.id);
+    effectiveTeams(a).forEach((t, i) => insAT.run(a.id, t, i));
+  }
+}
+
+/** The ACL grammar (Plan 19). An entry is `"*"` (everyone), an exact agent id, or `team:<id>` — which
+ *  matches every member of that team. Purely additive: no agent id may contain a colon, so an entry
+ *  written before Plan 19 keeps exactly the meaning it had. Plan 22: a target now carries its full
+ *  membership list (`teams`, which includes the implicit `default`), so a `team:<id>` entry matches when
+ *  that id is anywhere in the list — an agent on several teams is reachable through any of them.
+ *
+ *  Note this is the grammar for BOTH canSee and canDelegateTo, and that `team:<id>` in canDelegateTo
+ *  grants both "address the team" and "address any of its members". A team is a legibility boundary,
+ *  not a security one — encapsulation comes from what root's roster SHOWS it (teams, not members),
+ *  not from what it is forbidden. Narrow the ACL by hand if you want the hard version. */
+function aclMatches(entry: string, target: { id: string; teams?: string[] }): boolean {
+  if (entry === "*") return true;
+  if (entry === target.id) return true;
+  const team = parseTeamAcl(entry);
+  return team !== null && !!target.teams?.includes(team);
+}
+
+export function acl(entries: string[], target: { id: string; teams?: string[] }): boolean {
+  return entries.some((e) => aclMatches(e, target));
+}
+
+export function visibleTo(caller: AgentDef, all: AgentDef[]): { id: string; role: string }[] {
+  return all
+    .filter((a) => a.id !== caller.id)
+    .filter((a) => acl(caller.canSee, { id: a.id, teams: effectiveTeams(a) }))
+    .map((a) => ({ id: a.id, role: a.role }));
+}
+
+/** Visibility from the registry INDEX (id/role/teams only) — never loads agent identities, so the
+ *  per-run cost stays O(1) file reads regardless of roster size. The caller is already loaded. */
+export function visibleToRows(
+  caller: AgentDef,
+  rows: { id: string; role: string; teams?: string[] }[],
+): { id: string; role: string; teams?: string[] }[] {
+  return rows.filter((r) => r.id !== caller.id).filter((r) => acl(caller.canSee, r));
+}
+
+/** May `from` delegate to this target? The target may be an agent (pass its registry row so a
+ *  `team:<id>` grant can match against its membership) or a team (pass `{ id: teamId, isTeam: true }`,
+ *  matched by a `team:<id>` entry or `*`). */
+export function canDelegate(from: AgentDef, to: { id: string; teams?: string[]; isTeam?: boolean }): boolean {
+  if (to.isTeam) return from.canDelegateTo.some((e) => e === "*" || parseTeamAcl(e) === to.id);
+  return acl(from.canDelegateTo, to);
+}