@taicho-ai/framework 0.1.0

package/src/core/firecrawl.ts

@@ -0,0 +1,25 @@
+/** Firecrawl scrape client: turn a URL into clean markdown. Used by the read_url agent tool so the
+ *  model can read MCP setup docs. fetch is injectable for tests; the API key comes from the env only. */
+const FIRECRAWL_SCRAPE_URL = "https://api.firecrawl.dev/v1/scrape";
+
+export async function scrapeUrl(
+  url: string,
+  opts: { apiKey?: string; fetchImpl?: typeof fetch } = {},
+): Promise<{ markdown: string } | { error: string }> {
+  const apiKey = opts.apiKey ?? process.env.FIRECRAWL_API_KEY;
+  if (!apiKey) return { error: "FIRECRAWL_API_KEY is not set — set it to let agents read web pages." };
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  try {
+    const res = await fetchImpl(FIRECRAWL_SCRAPE_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ url, formats: ["markdown"] }),
+    });
+    if (!res.ok) return { error: `firecrawl ${res.status}: ${(await res.text()).slice(0, 200)}` };
+    const json = (await res.json()) as { data?: { markdown?: string } };
+    const markdown = json.data?.markdown;
+    return markdown ? { markdown } : { error: "firecrawl returned no markdown for this page" };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/src/core/headless.ts

@@ -0,0 +1,260 @@
+/** Headless surface — drive `executeRun` WITHOUT Ink.
+ *
+ *  `RunDeps` is already the seam (model / approval / onStep are all injectable), so a headless run is
+ *  just `makeDeps` + `executeRun` with a non-interactive approval channel and stdout instead of a
+ *  React tree. This powers `taicho run "<goal>"` and `taicho tail`, and makes real-binary e2e cheap
+ *  (a scripted assertion, no VHS tape).
+ *
+ *  APPROVAL CHANNEL (the one real design point). A headless run is unattended by definition — there
+ *  is no captain watching an approval card. The DEFAULT is therefore **auto-reject**: the run
+ *  proceeds, but every privileged action (create_agent, run_command, add_mcp, propose_skill,
+ *  propose_coaching, ask_human) is declined and the model continues or reports it could not proceed.
+ *  Rejecting is the safe default — auto-approving would let a model spawn agents or run shell
+ *  commands with no human in the loop. Two opt-ins exist for trusted/interactive use:
+ *    --approve auto  → approve everything (scripted, trusted flows only)
+ *    --approve prompt → ask on stdin (y/N per request; free-text answer for ask_human)
+ *  All three are deterministic and never touch the network beyond the model call itself. */
+import type { Database } from "bun:sqlite";
+import { createInterface } from "node:readline";
+import { makeDeps, executeRun, type Model, type RunDeps, type ApprovalRequest, type ApprovalDecision } from "./run";
+import { loadAgent } from "../store/roster";
+import { tailRun } from "./events";
+import { log } from "./logger";
+import type { Schedule } from "@taicho-ai/contracts/schedule";
+
+export type ApprovalMode = "reject" | "approve" | "prompt";
+
+/** The `runHeadless` options for an UNATTENDED scheduled fire. The `triggeredBy: "schedule:<id>"` marker
+ *  is what EXCLUDES the fire from the target agent's conversation ledger + boot-replay cache (it still
+ *  gets full run evidence) — see runHeadless's `triggeredBy` note. Constructed in ONE place so every fire
+ *  site — the REPL (App.tsx), the boot CLI + `taicho schedule run` (index.tsx / schedule-cli), and the
+ *  audit test — share the SAME wiring and cannot drift. Callers spread the result and add `out`/`signal`. */
+export function scheduleFireOptions(s: Schedule): { goal: string; agent: string; approve: ApprovalMode; triggeredBy: string } {
+  return { goal: s.goal, agent: s.agent, approve: s.approve, triggeredBy: `schedule:${s.id}` };
+}
+
+export type CliCommand =
+  | { kind: "run"; goal: string; agent: string; approve: ApprovalMode }
+  | { kind: "tail"; runId?: string; follow: boolean }
+  // Plan 04 Phase 6: manage/fire durable schedules. `args` are the raw tokens after `schedule`
+  // (--verbose already stripped); parsed by parseScheduleCommand in scheduler.ts so the CLI and the
+  // REPL's /schedules command share one grammar.
+  | { kind: "schedule"; args: string[] }
+  // Plan 22: manage teams from the command line (`taicho team add|list|remove|member`). Raw tokens after
+  // `team`, parsed by runTeamCli — a captain-owned, model-free front door onto the same service layer.
+  | { kind: "team"; args: string[] };
+
+export interface ParsedCli {
+  /** `--verbose`/`-v` anywhere on the line → raise the log level to debug. */
+  verbose: boolean;
+  /** null ⇒ no subcommand ⇒ launch the interactive Ink REPL. */
+  command: CliCommand | null;
+}
+
+function normalizeApprove(v: string | undefined): ApprovalMode {
+  if (v === "approve" || v === "auto" || v === "yes" || v === "y") return "approve";
+  if (v === "prompt" || v === "ask" || v === "stdin") return "prompt";
+  return "reject";
+}
+
+/** Parse raw `process.argv` into a CLI command. Scans for the first bare `run`/`tail` token (position
+ *  > 0 so the executable path is never mistaken for a command); everything before it is the
+ *  interpreter/executable path, everything after is the command's args. No subcommand ⇒ REPL. */
+export function parseCli(argv: string[]): ParsedCli {
+  const verbose = argv.includes("--verbose") || argv.includes("-v");
+  const cmdIdx = argv.findIndex((a, i) => i > 0 && (a === "run" || a === "tail" || a === "schedule" || a === "team"));
+  if (cmdIdx < 0) return { verbose, command: null };
+
+  const cmd = argv[cmdIdx];
+  const rest = argv.slice(cmdIdx + 1).filter((a) => a !== "--verbose" && a !== "-v");
+
+  if (cmd === "schedule") return { verbose, command: { kind: "schedule", args: rest } };
+  if (cmd === "team") return { verbose, command: { kind: "team", args: rest } };
+
+  if (cmd === "run") {
+    let agent = "root";
+    let approve: ApprovalMode = "reject";
+    const positional: string[] = [];
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i]!;
+      if (a === "--agent" || a === "-a") agent = rest[++i] ?? agent;
+      else if (a.startsWith("--agent=")) agent = a.slice("--agent=".length);
+      else if (a === "--approve") approve = normalizeApprove(rest[++i]);
+      else if (a.startsWith("--approve=")) approve = normalizeApprove(a.slice("--approve=".length));
+      else if (a === "--yes" || a === "-y") approve = "approve";
+      else positional.push(a);
+    }
+    return { verbose, command: { kind: "run", goal: positional.join(" ").trim(), agent, approve } };
+  }
+
+  // tail
+  let follow = false;
+  const positional: string[] = [];
+  for (const a of rest) {
+    if (a === "--follow" || a === "-f") follow = true;
+    else positional.push(a);
+  }
+  return { verbose, command: { kind: "tail", runId: positional[0], follow } };
+}
+
+/** Build the non-interactive approval channel for a headless run. */
+export function makeApprovalChannel(
+  mode: ApprovalMode,
+  io?: { input?: NodeJS.ReadableStream; out?: (line: string) => void },
+): (req: ApprovalRequest) => Promise<ApprovalDecision> {
+  if (mode === "reject") return async () => ({ type: "reject" });
+
+  if (mode === "approve") {
+    return async (req) =>
+      req.kind === "ask_human"
+        ? { type: "answered", answer: req.options[0] ?? "yes" } // no human to ask; take the first offered option
+        : { type: "approve" };
+  }
+
+  // prompt: one line of stdin per request. On EOF / no TTY, degrade to reject (never hang unattended).
+  // `rl` is created once and reused across requests. A readline interface can't be reopened after its
+  // input hits EOF (which fires 'close'), so once closed every subsequent `ask` must short-circuit to
+  // "" (→ reject) rather than call `rl.question` on a closed interface — that throws ERR_USE_AFTER_CLOSE
+  // and would turn the documented "degrade to reject" into a headless crash on the 2nd+ request.
+  const out = io?.out ?? ((l: string) => process.stdout.write(l + "\n"));
+  const rl = createInterface({ input: io?.input ?? process.stdin });
+  let closed = false;
+  rl.once("close", () => { closed = true; });
+  const ask = (q: string) => new Promise<string>((resolve) => {
+    if (closed) { resolve(""); return; } // already EOF'd → degrade to reject; don't touch the closed rl
+    let settled = false;
+    const done = (v: string) => { if (!settled) { settled = true; resolve(v); } };
+    rl.question(q, done);
+    rl.once("close", () => done(""));
+  });
+  return async (req) => {
+    if (req.kind === "ask_human") {
+      out(`? ${req.question}${req.options.length ? ` [${req.options.join(" / ")}]` : ""}`);
+      const answer = (await ask("> ")).trim();
+      return answer ? { type: "answered", answer } : { type: "reject" };
+    }
+    out(`? approve ${req.kind}${describe(req)}`);
+    const yn = (await ask("[y/N] ")).trim().toLowerCase();
+    return yn === "y" || yn === "yes" ? { type: "approve" } : { type: "reject" };
+  };
+}
+
+function describe(req: ApprovalRequest): string {
+  switch (req.kind) {
+    case "create_agent": return `: ${req.draft.id ?? "(new agent)"}`;
+    case "run_command": return `: ${req.command}${req.cwd ? ` [cwd: ${req.cwd}]` : ""}`;
+    case "add_mcp": return `: ${req.name}`;
+    case "propose_skill": return `: ${req.draft.name}`;
+    default: return "";
+  }
+}
+
+export interface HeadlessDeps {
+  ws: string;
+  db: Database;
+  model: Model | null;
+  resolveModel?: RunDeps["resolveModel"];
+  priceUsd?: RunDeps["priceUsd"];
+  configDefaults?: RunDeps["configDefaults"];
+  mcp?: RunDeps["mcp"];
+  embed?: RunDeps["embed"];
+  spendLedger?: RunDeps["spendLedger"]; // Plan 09: squad-wide ceilings enforced in the loop
+  telemetry?: RunDeps["telemetry"]; // Plan 16: OpenTelemetry export (undefined ⇒ off)
+}
+
+export interface HeadlessResult {
+  ok: boolean;
+  runId?: string;
+  text: string;
+  outcome?: string;
+  tokens?: number;
+  costUsd?: number | null;
+}
+
+/** Drive one run to completion without Ink. Prints breadcrumbs + the final text to `out`, mirrors
+ *  everything to `taicho.log`, and returns a structured result the caller uses to pick an exit code. */
+export async function runHeadless(
+  hd: HeadlessDeps,
+  opts: {
+    goal: string;
+    agent?: string;
+    approve?: ApprovalMode;
+    // Defaults to "user": an EXPLICIT `taicho run "<goal>"` is a real user turn and is audited into the
+    // agent's conversation ledger + boot-replay cache identically to the REPL. Scheduler fires (cron /
+    // interval / watch, and `taicho schedule run`) pass a distinct `schedule:<id>` marker so the run
+    // still gets full run evidence (trace/transcript) but is EXCLUDED from the conversation audit —
+    // mirroring how a background dispatch cascade (triggeredBy = taskId) is excluded. Without this every
+    // autonomous fire polluted the ledger and replayed as prior "conversation" on the next launch.
+    triggeredBy?: string;
+    out?: (line: string) => void;
+    signal?: AbortSignal;
+    input?: NodeJS.ReadableStream;
+  },
+): Promise<HeadlessResult> {
+  const out = opts.out ?? ((l: string) => process.stdout.write(l + "\n"));
+  const agentId = opts.agent ?? "root";
+
+  if (!opts.goal.trim()) {
+    out('taicho: run needs a goal — taicho run "<goal>"');
+    return { ok: false, text: "" };
+  }
+  if (!hd.model) {
+    out("taicho: no credentials — set ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY, or run /login openai in the REPL.");
+    return { ok: false, text: "" };
+  }
+
+  const agent = await loadAgent(hd.ws, agentId).catch(() => null);
+  if (!agent) {
+    out(`taicho: no agent "${agentId}".`);
+    return { ok: false, text: "" };
+  }
+
+  const approve = opts.approve ?? "reject";
+  log.info(`headless run start`, { agent: agentId, approve, goal: opts.goal });
+  out(`taicho: ${agentId} · ${opts.goal}  (approvals: ${approve})`);
+
+  const deps = makeDeps({
+    ws: hd.ws,
+    db: hd.db,
+    model: hd.model,
+    requestApproval: makeApprovalChannel(approve, { input: opts.input, out }),
+    onStep: ({ tool, agent: a, note }) => {
+      // No Ink to fight: breadcrumbs go to stdout AND the log. Streamed token deltas are logged at
+      // debug only (they'd spam a headless stdout).
+      if (note) { out(`  ${note}`); log.info(`step note`, { agent: a, note }); return; }
+      if (tool) { out(`  ↳ ${a} → ${tool}()`); log.debug(`tool`, { agent: a, tool }); }
+    },
+    resolveModel: hd.resolveModel,
+    priceUsd: hd.priceUsd,
+    configDefaults: hd.configDefaults,
+    mcp: hd.mcp,
+    embed: hd.embed,
+    spendLedger: hd.spendLedger,
+    telemetry: hd.telemetry,
+    signal: opts.signal,
+  });
+
+  const res = await executeRun(deps, {
+    agent,
+    messages: [{ role: "user", content: opts.goal }],
+    triggeredBy: opts.triggeredBy ?? "user",
+  });
+
+  const { outcome, tokens, costUsd } = res.trace;
+  out("");
+  out(res.text);
+  out("");
+  out(`taicho: ${outcome} · run ${res.runId} · ${tokens} tok · ${costUsd == null ? "subscription" : "$" + costUsd.toFixed(4)}`);
+  log.info(`headless run done`, { runId: res.runId, outcome, tokens });
+
+  return { ok: outcome === "completed", runId: res.runId, text: res.text, outcome, tokens, costUsd };
+}
+
+/** `taicho tail [runId] [--follow]` — stream a run's events (latest run when no id). */
+export async function runTail(
+  ws: string,
+  cmd: { runId?: string; follow: boolean },
+  opts?: { out?: (line: string) => void; signal?: AbortSignal },
+): Promise<void> {
+  await tailRun({ ws, runId: cmd.runId, follow: cmd.follow, out: opts?.out, signal: opts?.signal });
+}

package/src/core/instrument.ts

@@ -0,0 +1,88 @@
+/** Pure helpers for the instrumentation seam: a one-line, redacted, length-capped render of tool
+ *  args ("read_url https://foo…", "run_command bun test") plus a capped JSON for the waterfall
+ *  drill-in. Transparency WITHOUT payload dumping, and NEVER logs auth material (mirrors the
+ *  redactAuthHeader discipline). Redaction is DEFENSE IN DEPTH: key-name masking (isSecretKey) for
+ *  secret-named fields PLUS value-level scrubbing (logger.redact) so a token embedded in the VALUE of
+ *  an ordinary field — `read_url {url:"…?api_key=sk-live-…"}`, `run_command {command:"curl -H
+ *  'Authorization: Bearer …'"}` — never surfaces in the status bar, breadcrumb, inspector, or the
+ *  persisted transcript. Value scrubbing runs BEFORE the length cap so a truncation can't expose a
+ *  partial secret. No I/O — unit-tested in isolation. */
+import { redact } from "./logger";
+
+const PREVIEW_CAP = 80;
+const JSON_CAP = 2000;
+/** Keys whose values are secrets/auth material and must never surface in a preview or a stored arg. */
+const SECRET_KEY = /(^|_|-)(token|secret|password|passwd|authorization|auth|bearer|api[_-]?key|apikey|key|credential|cookie|session)s?($|_|-)/i;
+const REDACTED = "‹redacted›";
+
+/** Cap a string to `n` chars, collapsing whitespace/newlines to single spaces first (one-liner).
+ *  Value-level secret scrubbing (logger.redact) runs BEFORE the cap so truncation can't leave a
+ *  partial secret visible. */
+export function oneLine(s: string, n = PREVIEW_CAP): string {
+  const flat = redact(s.replace(/\s+/g, " ").trim());
+  return flat.length > n ? flat.slice(0, n - 1) + "…" : flat;
+}
+
+/** True when a key names auth/secret material we must redact. */
+export function isSecretKey(key: string): boolean {
+  return SECRET_KEY.test(key);
+}
+
+/** Deep-redact secret-keyed values in a plain object/array (returns a new value). Non-plain values
+ *  (strings, numbers) pass through unchanged. */
+export function redactValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redactValue);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>))
+      out[k] = isSecretKey(k) ? REDACTED : redactValue(v);
+    return out;
+  }
+  return value;
+}
+
+/** A stable one-line preview of a tool's args. Known tools get a hand-picked field; everything else
+ *  falls back to a redacted `k=v` join. Always redacted, always ≤ PREVIEW_CAP chars. */
+export function argsPreview(tool: string, args: unknown): string {
+  const a = (args && typeof args === "object" ? (args as Record<string, unknown>) : {}) as Record<string, unknown>;
+  const str = (k: string): string | undefined => (typeof a[k] === "string" ? (a[k] as string) : undefined);
+  let picked: string | undefined;
+  switch (tool) {
+    case "read_url": picked = str("url"); break;
+    case "run_command": picked = str("command"); break;
+    case "delegate_task":
+    case "dispatch_task": picked = [str("to"), str("goal")].filter(Boolean).join(": "); break;
+    case "read_artifact": picked = str("id"); break;
+    case "save_artifact":
+    case "write_artifact": picked = str("title") ?? str("topicSlug"); break;
+    case "list_artifacts": picked = str("q") ?? str("type") ?? str("producer"); break;
+    case "create_agent": picked = str("id"); break;
+    case "find_agents":
+    case "find_skills":
+    case "recall": picked = str("query"); break;
+    case "use_skill": picked = str("name"); break;
+    case "ask_human": picked = str("question"); break;
+    case "remember": picked = str("title"); break;
+    case "add_mcp_server": picked = str("name"); break;
+  }
+  if (picked && picked.trim()) return oneLine(picked);
+  // Generic fallback: redacted scalar k=v pairs.
+  const parts: string[] = [];
+  for (const [k, v] of Object.entries(a)) {
+    if (isSecretKey(k)) { parts.push(`${k}=${REDACTED}`); continue; }
+    if (v == null || typeof v === "object") continue; // skip nested/empty in the one-liner
+    parts.push(`${k}=${String(v)}`);
+  }
+  return parts.length ? oneLine(parts.join(" ")) : "";
+}
+
+/** A capped, redacted JSON render of a value for the waterfall drill-in (args in / result out).
+ *  Two-layer redaction: key-name masking (redactValue) then value-level scrubbing (logger.redact)
+ *  for secrets embedded in ordinary-keyed values. Scrubbing runs BEFORE the cap. */
+export function capJson(value: unknown, cap = JSON_CAP): string {
+  let s: string | undefined;
+  try { s = JSON.stringify(redactValue(value)); } catch { s = String(value); }
+  if (s == null) return "";
+  s = redact(s);
+  return s.length > cap ? s.slice(0, cap) + `…[+${s.length - cap} chars]` : s;
+}

package/src/core/logger.ts

@@ -0,0 +1,143 @@
+/** Leveled, file-captured logging that does NOT fight Ink.
+ *
+ *  Under the full-screen TUI, a stray console.error/warn write corrupts or vanishes behind the Ink
+ *  render — so a run failure or a swallowed error left no trace the user could read. This logger
+ *  writes structured lines to a FILE (`taicho.log` in the workspace) instead, so diagnostics survive
+ *  a session and are greppable after the fact.
+ *
+ *  Auth material is NEVER written: every line passes through `redact()`, the same Bearer/token
+ *  scrub as `redactAuthHeader` (providers/openai-codex.ts) plus a few common API-key shapes. Kept
+ *  dependency-free so it can be imported from any layer (store/, core/, providers/) without pulling
+ *  a heavy provider into every module.
+ *
+ *  A single process-wide default logger (`log`) backs the scattered call sites. Boot calls
+ *  `configureLogger({ ws, level })` once it knows the workspace + verbosity (`--verbose` / env).
+ *  Tests use `createLogger({ file })` for isolation. */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { trace, context } from "@opentelemetry/api";
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+/** Numeric severity — a message is emitted only when its level >= the logger's threshold. */
+const ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };
+
+export interface Logger {
+  level: LogLevel;
+  debug(msg: string, data?: unknown): void;
+  info(msg: string, data?: unknown): void;
+  warn(msg: string, data?: unknown): void;
+  error(msg: string, data?: unknown): void;
+}
+
+/** Scrub anything that looks like a bearer token or API key BEFORE it reaches disk. Mirrors
+ *  `redactAuthHeader` (Bearer <token> → Bearer ***) and adds the common key/secret shapes an error
+ *  string, serialized profile, tool arg, or URL might carry. Targeted on purpose — it must not maul
+ *  ordinary prose. Beyond Bearer/`sk-`/named-JSON-field shapes it covers GitHub tokens (`ghp_`/`gho_`/
+ *  `ghu_`/`ghs_`/`ghr_` and fine-grained `github_pat_…`), Slack tokens (`xox[baprs]-…`), and bare
+ *  JWTs, so a gh-backed MCP or a new provider can't leak a credential shape the original rules miss.
+ *  It ALSO scrubs secret-carrying URL query params (`?api_key=…`, `&token=…`) so a secret leaks even
+ *  when it sits in the VALUE of an innocuously-named field. Each rule needs a distinctive prefix +
+ *  long opaque body (or a query-param delimiter), so it stays off ordinary text. Reused by the
+ *  instrumentation seam (instrument.ts) so waterfall/status-bar/transcript arg previews scrub too. */
+export function redact(s: string): string {
+  return s
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer ***")
+    .replace(/\bsk-[A-Za-z0-9._-]{8,}/g, "sk-***") // OpenAI/Anthropic/OpenRouter: sk-, sk-ant-, sk-proj-, sk-or-
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}/g, "github_pat_***") // GitHub fine-grained PAT
+    .replace(/\bgh[oprsu]_[A-Za-z0-9]{20,}/g, (m) => m.slice(0, 4) + "***") // GitHub gho_/ghp_/ghr_/ghs_/ghu_ tokens
+    .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, (m) => m.slice(0, 5) + "***") // Slack xoxb-/xoxa-/xoxp-/xoxr-/xoxs- tokens
+    .replace(/\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g, "eyJ***") // bare JWT: header.payload.signature
+    // URL/query-string secrets: the value leaks even under an innocuous key name (?api_key=…, &token=…).
+    .replace(/([?&](?:access_token|api[_-]?key|token|secret|sig|key)=)[^&\s#"'\\]+/gi, "$1***")
+    .replace(/"(access_token|refresh_token|id_token|api[_-]?key|apiKey|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"***"');
+}
+
+/** Serialize the optional structured payload for the line tail. Errors render as message + name;
+ *  circular structures degrade to "[unserializable]" rather than throwing (logging must not crash). */
+function serialize(data: unknown): string {
+  if (data === undefined) return "";
+  if (data instanceof Error) return `${data.name}: ${data.message}`;
+  if (typeof data === "string") return data;
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+function format(level: LogLevel, msg: string, data?: unknown): string {
+  const tail = serialize(data);
+  const line = tail ? `${msg} :: ${tail}` : msg;
+  // Plan 17: correlate the execution log with OpenTelemetry. When a span is active (a run/model/tool
+  // is in flight), stamp its trace_id/span_id so a taicho.log line lines up with the exact span in
+  // Jaeger/LangSmith/etc. No-op when telemetry is off (no active span) or outside a run.
+  const sc = trace.getSpanContext(context.active());
+  const corr = sc ? ` trace_id=${sc.traceId} span_id=${sc.spanId}` : "";
+  return `${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} ${redact(line)}${corr}\n`;
+}
+
+class FileLogger implements Logger {
+  level: LogLevel;
+  private file: string;
+  private sink?: (line: string) => void;
+  private ensured = false;
+
+  constructor(opts: { file?: string; level?: LogLevel; sink?: (line: string) => void }) {
+    this.level = opts.level ?? "info";
+    this.file = opts.file ?? defaultFile();
+    this.sink = opts.sink;
+  }
+
+  /** Re-point the file and/or level after boot resolves the workspace + verbosity. */
+  configure(opts: { ws?: string; file?: string; level?: LogLevel; sink?: (line: string) => void }): void {
+    if (opts.sink) this.sink = opts.sink;
+    if (opts.file) { this.file = opts.file; this.ensured = false; }
+    else if (opts.ws) { this.file = join(opts.ws, "taicho.log"); this.ensured = false; }
+    if (opts.level) this.level = opts.level;
+  }
+
+  private emit(level: LogLevel, msg: string, data?: unknown): void {
+    if (ORDER[level] < ORDER[this.level]) return;
+    const line = format(level, msg, data);
+    if (this.sink) { this.sink(line); return; }
+    try {
+      if (!this.ensured) { mkdirSync(dirname(this.file), { recursive: true }); this.ensured = true; }
+      appendFileSync(this.file, line);
+    } catch {
+      // Logging must never take down the app. A failed write is silently dropped.
+    }
+  }
+
+  debug(msg: string, data?: unknown): void { this.emit("debug", msg, data); }
+  info(msg: string, data?: unknown): void { this.emit("info", msg, data); }
+  warn(msg: string, data?: unknown): void { this.emit("warn", msg, data); }
+  error(msg: string, data?: unknown): void { this.emit("error", msg, data); }
+}
+
+/** Default file, resolved from env or the cwd (which IS the workspace for the running app). */
+function defaultFile(): string {
+  return process.env.TAICHO_LOG_FILE ?? join(process.cwd(), "taicho.log");
+}
+
+/** The starting level, from env. `TAICHO_LOG_LEVEL` wins; `TAICHO_VERBOSE`/`TAICHO_DEBUG` ⇒ debug.
+ *  (Historically only the codex path honored `TAICHO_DEBUG`; it now raises the general log level.) */
+export function envLevel(): LogLevel {
+  const raw = process.env.TAICHO_LOG_LEVEL?.toLowerCase();
+  if (raw && raw in ORDER) return raw as LogLevel;
+  if (process.env.TAICHO_VERBOSE || process.env.TAICHO_DEBUG) return "debug";
+  return "info";
+}
+
+/** Build an isolated logger — used by tests (explicit file) and anywhere a scoped sink is wanted. */
+export function createLogger(opts: { file?: string; level?: LogLevel; sink?: (line: string) => void }): Logger {
+  return new FileLogger(opts);
+}
+
+/** The process-wide default logger every scattered call site imports. Re-pointed at boot. */
+export const log = new FileLogger({ level: envLevel() });
+
+/** Re-point the default logger once boot knows the workspace + verbosity. */
+export function configureLogger(opts: { ws?: string; file?: string; level?: LogLevel; sink?: (line: string) => void }): void {
+  log.configure(opts);
+}

package/src/core/mcp/adapter.ts

@@ -0,0 +1,34 @@
+/** Adapt an MCP tool (JSON-Schema input + content-block output) into an AI-SDK `tool()` so the
+ *  agent loop treats it like any built-in tool. Decoupled from the MCP Client (takes a `call` fn)
+ *  to stay trivially testable. */
+import { tool, jsonSchema } from "ai";
+
+export interface McpToolInfo { name: string; description?: string; inputSchema?: unknown }
+
+type ContentBlock = { type: string; text?: string; resource?: unknown; [k: string]: unknown };
+export interface McpCallResult { content?: ContentBlock[]; isError?: boolean; structuredContent?: unknown }
+
+/** MCP returns an array of content blocks; the model wants plain text. Join text blocks, summarize
+ *  non-text ones, and fall back to structuredContent. isError is surfaced inline so the model sees it. */
+export function flattenMcpResult(res: McpCallResult): string {
+  const parts = (res.content ?? []).map((c) => {
+    if (c.type === "text") return c.text ?? "";
+    if (c.type === "resource") return typeof c.resource === "string" ? c.resource : JSON.stringify(c.resource ?? c);
+    if (c.type === "image" || c.type === "audio") return `[${c.type}]`;
+    return JSON.stringify(c);
+  });
+  let text = parts.join("\n").trim();
+  if (!text && res.structuredContent !== undefined) text = JSON.stringify(res.structuredContent);
+  return res.isError ? `Error: ${text || "tool call failed"}` : text;
+}
+
+export function mcpToolToAiTool(
+  call: (name: string, args: Record<string, unknown>) => Promise<McpCallResult>,
+  info: McpToolInfo,
+) {
+  return tool({
+    description: info.description ?? info.name,
+    inputSchema: jsonSchema((info.inputSchema as object | undefined) ?? { type: "object", properties: {} }),
+    execute: async (args) => flattenMcpResult(await call(info.name, (args ?? {}) as Record<string, unknown>)),
+  });
+}