@taicho-ai/framework 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @taicho-ai/framework
+
+Taicho's multi-agent composition framework: delegation, teams, persistence, knowledge, coaching,
+scheduling, providers, MCP, and the adapter from workflow graph nodes to individual agent runs.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@taicho-ai/framework",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "3.0.82",
+    "@ai-sdk/openai": "3.0.69",
+    "@huggingface/transformers": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openrouter/ai-sdk-provider": "2.10.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@taicho-ai/agent": "0.1.0",
+    "@taicho-ai/contracts": "0.1.0",
+    "@taicho-ai/graph": "0.1.0",
+    "@taicho-ai/telemetry": "0.1.0",
+    "ai": "6.0.199",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "3.0.10",
+    "@opentelemetry/sdk-metrics": "^2.9.0",
+    "@opentelemetry/sdk-trace-node": "^2.9.0"
+  },
+  "description": "Multi-agent framework for taicho: delegation, storage, teams, knowledge, coaching, providers, MCP, scheduling.",
+  "license": "MIT",
+  "homepage": "https://taicho.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taicho-ai/taicho.git",
+    "directory": "packages/framework"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/coaching/patterns.ts

@@ -0,0 +1,103 @@
+/** Plan 06 Phase 3 — repeated verification failures feed coaching.
+ *
+ *  A single failed acceptance check is noise; the SAME agent failing the SAME criteria across
+ *  MULTIPLE delegations is a standing gap the captain may want to codify. When that repeat crosses a
+ *  threshold we PROPOSE a coaching note — status "proposed", exactly like a /teach proposal before the
+ *  captain approves it. A proposed note is INERT (run.ts only applies status:"approved" notes), so this
+ *  is a suggestion awaiting the captain, never an auto-applied policy. This mirrors coaching's
+ *  correction→policy proposal path (teach.ts), minus the LLM distiller: the failure reasons are already
+ *  structured, so the draft is deterministic (and the pattern detection stays testable, no network). */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { toPolicy } from "./proposal";
+import { writePolicy } from "../store/policy";
+import type { PolicyNote } from "@taicho-ai/contracts/policy";
+
+/** How many delegations of the SAME (agent, criteria) must FAIL before coaching is proposed. The
+ *  2nd failure is the first REPEAT — a one-off never proposes. Kept intentionally low + defensible. */
+export const REPEAT_FAILURE_THRESHOLD = 2;
+
+/** One terminal verification failure — the child run is the dedupe key (one record per delegation). */
+const FailureRecord = z.object({
+  targetAgent: z.string(),                 // the child agent whose output failed the check
+  criteria: z.string(),                    // the acceptance criteria it failed (raw, for display + normalized match)
+  runId: z.string(),                       // the failing child run — dedupe key
+  reasons: z.array(z.string()).default([]),// the unmet-criteria reasons from the verdict
+  at: z.string(),
+});
+type FailureRecord = z.infer<typeof FailureRecord>;
+
+/** Squad-level append-only ledger of verification failures (one JSON object per line). */
+function ledgerFile(ws: string): string {
+  return join(ws, "verification-failures.jsonl");
+}
+
+/** Collapse trivial variation so "must mention Y" and "  Must  mention  Y " count as one pattern. */
+function normalize(criteria: string): string {
+  return criteria.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function readLedger(ws: string): FailureRecord[] {
+  const f = ledgerFile(ws);
+  if (!existsSync(f)) return [];
+  const out: FailureRecord[] = [];
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(FailureRecord.parse(JSON.parse(line))); } catch { /* skip a corrupt audit line */ }
+  }
+  return out;
+}
+
+export interface RecordFailureInput {
+  targetAgent: string;
+  criteria: string;
+  runId: string;
+  reasons?: string[];
+}
+
+/** Record one delegation's terminal verification FAILURE. If this failure makes the (agent, criteria)
+ *  repeat count reach REPEAT_FAILURE_THRESHOLD for the FIRST time, PROPOSE a coaching note (status
+ *  "proposed") scoped to the target agent and return it. Fires at most once per pattern (exactly when a
+ *  NEW distinct child run brings the count to the threshold); further failures do not re-nag, and a
+ *  duplicate runId can neither double-count nor re-propose. Never throws on a bad ws. */
+export function recordVerificationFailure(ws: string, input: RecordFailureInput): { proposed?: PolicyNote } {
+  const key = normalize(input.criteria);
+  // Read BEFORE appending so we can tell a genuinely-new failing run from a duplicate re-record.
+  const prior = readLedger(ws).filter((r) => r.targetAgent === input.targetAgent && normalize(r.criteria) === key);
+  const priorRunIds = new Set(prior.map((r) => r.runId));
+  const isNew = !priorRunIds.has(input.runId);
+
+  const rec: FailureRecord = {
+    targetAgent: input.targetAgent,
+    criteria: input.criteria,
+    runId: input.runId,
+    reasons: input.reasons ?? [],
+    at: new Date().toISOString(),
+  };
+  const f = ledgerFile(ws);
+  mkdirSync(dirname(f), { recursive: true });
+  appendFileSync(f, JSON.stringify(rec) + "\n");
+
+  // Fire ONLY when a new distinct failing run first pushes the pattern to the threshold. A duplicate
+  // re-record (isNew=false) or a later failure (count already past the threshold) proposes nothing.
+  const distinctAfter = priorRunIds.size + (isNew ? 1 : 0);
+  if (!isNew || distinctAfter !== REPEAT_FAILURE_THRESHOLD) return {};
+
+  // Deterministic proposal from the accumulated reasons — coaching's correction→policy shape, but the
+  // reasons are already structured so no distiller (LLM) call is needed.
+  const reasons = [...new Set([...prior, rec].flatMap((r) => r.reasons).filter(Boolean))];
+  const draft = {
+    when: `producing output as "${input.targetAgent}" for a delegated task that carries acceptance criteria`,
+    do:
+      `Your output has repeatedly failed acceptance verification (${distinctAfter} delegations for a similar contract). ` +
+      `Before returning, make sure it satisfies the stated criteria` +
+      (reasons.length ? ` — recurring gaps: ${reasons.join("; ")}.` : "."),
+    scope: "agent" as const,
+  };
+  // toPolicy defaults status to "proposed" — leave it (coaching is approval-gated; run.ts applies only
+  // APPROVED notes), so this is a captain-gated suggestion, never an active policy.
+  const note: PolicyNote = toPolicy(draft, { agent: input.targetAgent, taughtBy: "verification", fromRun: input.runId });
+  writePolicy(ws, note);
+  return { proposed: note };
+}

package/src/coaching/proposal.ts

@@ -0,0 +1,29 @@
+/** Every correction forces a proposal — writes are never left to the agent's discretion.
+ *  A silently dropped instruction is the worst failure in a managerial trust model. */
+import { z } from "zod";
+import type { PolicyNote } from "@taicho-ai/contracts/policy";
+
+export const ProposalDraft = z.object({
+  when: z.string().describe("condition under which this instruction applies"),
+  do: z.string().describe("the instruction itself, imperative"),
+  scope: z.enum(["agent", "global"]).default("agent"),
+});
+export type ProposalDraft = z.infer<typeof ProposalDraft>;
+
+export function toPolicy(d: ProposalDraft, meta: {
+  agent: string; taughtBy: string; fromRun?: string; supersedes?: string;
+}): PolicyNote {
+  return {
+    id: `pol_${crypto.randomUUID().slice(0, 8)}`,
+    agent: meta.agent,
+    when: d.when,
+    do: d.do,
+    scope: d.scope,
+    status: "proposed",
+    supersedes: meta.supersedes,
+    taughtBy: meta.taughtBy,
+    fromRun: meta.fromRun,
+    created: new Date().toISOString(),
+    expanded: [],
+  };
+}

package/src/coaching/retrieval.ts

@@ -0,0 +1,27 @@
+/** Policy recall: embed task context -> vector candidates -> condition filter -> top-k.
+ *  Everything retrieved/applied/skipped is recorded in the run trace ledger. */
+import type { Database } from "bun:sqlite";
+import type { PolicyNote } from "@taicho-ai/contracts/policy";
+import { topK } from "../store/vectors";
+
+export interface RecallResult { applied: PolicyNote[]; skipped: { id: string; reason: string }[]; retrieved: string[]; }
+
+export async function recallPolicies(opts: {
+  db: Database;
+  taskContext: string;
+  candidates: Map<string, PolicyNote>;   // approved notes for this agent (+team/global)
+  embed: (text: string) => Promise<Float32Array>;
+  conditionCheck: (note: PolicyNote, taskContext: string) => Promise<boolean>;
+  k?: number;
+}): Promise<RecallResult> {
+  const q = await opts.embed(opts.taskContext);
+  const hits = topK(opts.db, "policy", q, opts.k ?? 8).filter((h) => opts.candidates.has(h.ref));
+  const applied: PolicyNote[] = [];
+  const skipped: { id: string; reason: string }[] = [];
+  for (const h of hits) {
+    const note = opts.candidates.get(h.ref)!;
+    if (await opts.conditionCheck(note, opts.taskContext)) applied.push(note);
+    else skipped.push({ id: note.id, reason: "condition no-match" });
+  }
+  return { applied, skipped, retrieved: hits.map((h) => h.ref) };
+}

package/src/coaching/supersede.ts

@@ -0,0 +1,14 @@
+/** Write-time contradiction check: new coaching that conflicts with an existing note
+ *  sets `supersedes` — an explicit replacement record, never a silent overwrite. */
+import type { PolicyNote } from "@taicho-ai/contracts/policy";
+
+export async function findContradiction(
+  draft: { when: string; do: string },
+  existing: PolicyNote[],
+  judge: (a: string, b: string) => Promise<boolean>,  // one LLM call: do these conflict?
+): Promise<PolicyNote | undefined> {
+  for (const note of existing.filter((n) => n.status === "approved")) {
+    if (await judge(`WHEN ${draft.when}: ${draft.do}`, `WHEN ${note.when}: ${note.do}`)) return note;
+  }
+  return undefined;
+}

package/src/coaching/teach.ts

@@ -0,0 +1,74 @@
+/** Turn a captain's free-text correction into a policy draft (one LLM call), and persist an
+ *  approved note. The draft→approve UI lives in the REPL; this is the testable core. */
+import { generateText, streamText } from "ai";
+import { ProposalDraft, toPolicy } from "./proposal";
+import { writePolicy } from "../store/policy";
+import type { PolicyNote } from "@taicho-ai/contracts/policy";
+import { SQUAD_SCOPE, type SpendLedger } from "../store/spend-ledger";
+
+type Model = Parameters<typeof generateText>[0]["model"];
+type Usage = Awaited<ReturnType<typeof generateText>>["usage"];
+
+/** Options for the coaching distiller's one model call.
+ *  - codexBackend (Plan 07): the ChatGPT/Codex subscription backend REJECTS non-streaming requests and
+ *    requires the system prompt in providerOptions.openai.instructions with store:false — a bare
+ *    generateText 400s ("Stream must be set to true" / "Instructions are required") for a signed-in
+ *    subscription user. So on that backend the call routes through streamText (drained to completion),
+ *    exactly like the agent loop (see loop.ts). The env path (api key) uses plain generateText.
+ *  - spendLedger/priceUsd (Plan 09): the distiller is a real model call the squad caused, so it's metered
+ *    against the squad ceiling. It runs OUTSIDE any run (no trace) ⇒ NOT surfaced in /costs (see costs.ts).
+ *    Subscription/unpriced ⇒ 0 USD (honest: tokens still count; the USD ceiling never fabricates spend). */
+export interface DraftOptions {
+  codexBackend?: boolean;
+  spendLedger?: SpendLedger;
+  priceUsd?: (u: { inputTokens: number; outputTokens: number }) => number;
+}
+
+export async function draftPolicy(model: Model, agentId: string, correction: string, opts?: DraftOptions): Promise<ProposalDraft> {
+  const system = `You convert a captain's correction for agent "${agentId}" into a standing instruction. Respond with ONLY a JSON object: {"when":"<condition it applies under>","do":"<imperative instruction>","scope":"agent" or "global"}. No prose, no code fence.`;
+  const messages = [{ role: "user" as const, content: correction }];
+
+  // Route the SAME way the agent loop does (Plan 07): Codex subscription ⇒ streamText with the system
+  // prompt in `instructions` + store:false (the backend rejects non-streaming / a top-level system);
+  // env (api key) ⇒ plain generateText. Either way we read back text + usage identically.
+  let text: string;
+  let usage: Usage | undefined;
+  if (opts?.codexBackend) {
+    let streamErr: unknown;
+    const s = streamText({
+      model, messages,
+      providerOptions: { openai: { instructions: system, store: false } },
+      onError: ({ error }) => { streamErr = error; },
+    });
+    await s.consumeStream();
+    if (streamErr) throw streamErr;
+    text = await s.text;
+    usage = await s.usage;
+  } else {
+    const res = await generateText({ model, system, messages });
+    text = res.text;
+    usage = res.usage;
+  }
+
+  // Commit the distiller's spend to the squad ceiling (Plan 09) BEFORE parsing — the tokens were spent
+  // regardless of whether the JSON parses. No priceUsd (subscription/unpriced) ⇒ 0 USD; tokens always count.
+  if (opts?.spendLedger) {
+    const inputTokens = usage?.inputTokens ?? 0;
+    const outputTokens = usage?.outputTokens ?? 0;
+    const tokens = usage?.totalTokens ?? inputTokens + outputTokens;
+    // Outside any run (no agent, no team) — the squad scope is the only honest one.
+    opts.spendLedger.add([SQUAD_SCOPE], { tokens, costUsd: opts.priceUsd?.({ inputTokens, outputTokens }) ?? 0 });
+  }
+
+  const trimmed = text.trim();
+  const json = trimmed.startsWith("{") ? trimmed : (trimmed.match(/\{[\s\S]*\}/)?.[0] ?? trimmed);
+  return ProposalDraft.parse(JSON.parse(json));
+}
+
+/** Persist an APPROVED policy note (coaching is approval-gated, so status is forced approved). */
+export function persistApprovedPolicy(ws: string, draft: ProposalDraft, agentId: string, fromRun?: string): PolicyNote {
+  const valid = ProposalDraft.parse(draft);
+  const note: PolicyNote = { ...toPolicy(valid, { agent: agentId, taughtBy: "user", fromRun }), status: "approved" };
+  writePolicy(ws, note);
+  return note;
+}

package/src/core/agent-status.ts

@@ -0,0 +1,79 @@
+/** Plan 10 Phase 2 — the live status model (pure, testable). Folds the typed engine event stream
+ *  (events.ts) into one AgentStatus per ACTIVE run. The StatusBar (and later panes) render from this;
+ *  nothing is invented in the UI. Keyed by runId so a delegation cascade shows every live agent at
+ *  once (parent `delegating`, child `working`). Elapsed-in-state is `now - since`, computed at render. */
+import type { StepEvent } from "@taicho-ai/agent";
+
+export type AgentState = "idle" | "thinking" | "writing" | "working" | "waiting" | "delegating";
+
+export interface AgentStatus {
+  runId: string;
+  agent: string;
+  state: AgentState;
+  tool?: string;         // the current tool (working/delegating) or approval label (waiting)
+  argsPreview?: string;  // redacted one-liner for the current tool
+  since: number;         // ms timestamp when the current state began (for elapsed-in-state)
+  inflightTools: number; // tools whose execute() is currently running
+  waiting: boolean;      // blocked on the captain right now
+}
+
+export type StatusMap = ReadonlyMap<string, AgentStatus>;
+
+const isDelegation = (tool?: string) => tool === "delegate_task" || tool === "dispatch_task";
+
+/** Fold one event into the status map, returning a NEW map (so React state updates fire). Events
+ *  without a phase or runId (plain note breadcrumbs, etc.) pass through untouched. */
+export function statusReducer(map: StatusMap, ev: StepEvent, now: number): StatusMap {
+  if (!ev.phase || !ev.runId) return map;
+  const next = new Map(map);
+  const runId = ev.runId;
+  const prev: AgentStatus =
+    next.get(runId) ?? { runId, agent: ev.agent, state: "idle", since: now, inflightTools: 0, waiting: false };
+
+  const set = (s: Partial<AgentStatus> & { state: AgentState }): StatusMap => {
+    const since = s.state !== prev.state ? now : prev.since;
+    next.set(runId, { ...prev, agent: ev.agent, ...s, since });
+    return next;
+  };
+
+  switch (ev.phase) {
+    case "final":
+      next.delete(runId); // the run produced its final text → it is settling; drop it from the live view
+      return next;
+    case "model_start":
+      // A fresh model call: back to thinking (unless we're mid-approval, which owns the state).
+      return prev.waiting ? next : set({ state: "thinking", tool: undefined, argsPreview: undefined });
+    case "delta":
+      return prev.waiting ? next : set({ state: "writing" });
+    case "tool_start": {
+      const inflightTools = prev.inflightTools + 1;
+      return set({
+        state: isDelegation(ev.tool) ? "delegating" : "working",
+        tool: ev.tool,
+        argsPreview: ev.argsPreview,
+        inflightTools,
+      });
+    }
+    case "tool_end": {
+      const inflightTools = Math.max(0, prev.inflightTools - 1);
+      if (prev.waiting) { next.set(runId, { ...prev, inflightTools }); return next; } // approval owns state
+      // Back to thinking once no tool is in flight; otherwise stay busy.
+      const state: AgentState = inflightTools > 0 ? prev.state : "thinking";
+      return set({ state, tool: inflightTools > 0 ? prev.tool : undefined, argsPreview: inflightTools > 0 ? prev.argsPreview : undefined, inflightTools });
+    }
+    case "approval_start":
+      return set({ state: "waiting", waiting: true, tool: ev.tool, argsPreview: ev.argsPreview });
+    case "approval_end": {
+      const state: AgentState = prev.inflightTools > 0 ? "working" : "thinking";
+      return set({ state, waiting: false, tool: prev.inflightTools > 0 ? prev.tool : undefined });
+    }
+    default:
+      return next;
+  }
+}
+
+/** Ordered snapshot for rendering: waiting agents first (the "the squad is stalled on YOU" signal),
+ *  then oldest-in-state first for stability. */
+export function statusList(map: StatusMap): AgentStatus[] {
+  return [...map.values()].sort((a, b) => Number(b.waiting) - Number(a.waiting) || a.since - b.since);
+}

package/src/core/auth/constants.ts

@@ -0,0 +1,53 @@
+/** OAuth + Codex-backend constants for ChatGPT subscription sign-in.
+ *
+ *  Cribbed from the open-source Codex CLI (github.com/openai/codex) and the OpenAI Codex auth
+ *  docs (developers.openai.com/codex/auth), per the spec's instruction NOT to hardcode auth
+ *  constants from the design doc itself. VERIFIED values are used directly; anything marked
+ *  UNVERIFIED keeps live auth behind the `auth.chatgpt_signin` flag until confirmed against the
+ *  Codex source. None of these matter for the unit/integration tests, which use a mock OAuth
+ *  server + mock fetch — they only govern real end-to-end sign-in.
+ */
+export const OPENAI_CODEX_AUTH = {
+  /** Codex's public OAuth client id (verified). */
+  clientId: "app_EMoamEEZ73f0CkXaXp7hrann",
+  /** OAuth endpoints (verified). */
+  authorizeUrl: "https://auth.openai.com/oauth/authorize",
+  tokenUrl: "https://auth.openai.com/oauth/token",
+  /** Localhost loopback redirect (verified: Codex default callback server). */
+  redirectUri: "http://localhost:1455/auth/callback",
+  callbackPort: 1455,
+  callbackPath: "/auth/callback",
+  /** Authorize params (verified). */
+  scopes: "openid profile email offline_access",
+  codeChallengeMethod: "S256" as const,
+  /** Originator string the Codex CLI sends (header `originator`). VERIFIED against codex-rs:
+   *  login/src/auth/default_client.rs → `DEFAULT_ORIGINATOR = "codex_cli_rs"`. The backend
+   *  allowlists first-party originators, so a wrong value can be rejected. */
+  originator: "codex_cli_rs",
+
+  /** Codex subscription backend (verified, codex-rs model-provider-info: CHATGPT_CODEX_BASE_URL).
+   *  The Responses API is served at baseURL + "/responses" (NO /v1 — that's the api.openai.com
+   *  convention; the @ai-sdk/openai provider appends "/responses" itself). */
+  codexBaseUrl: "https://chatgpt.com/backend-api/codex",
+  responsesPath: "/responses",
+  defaultModelId: "gpt-5.5", // VERIFIED: current Codex default slug (codex-rs models-manager/models.json)
+
+  /** account_id is extracted from the `id_token` JWT. UNVERIFIED: confirm the exact claim path
+   *  (Codex reads a ChatGPT account id from a namespaced auth claim in the id_token). */
+  accountIdClaim: { namespace: "https://api.openai.com/auth", field: "chatgpt_account_id" },
+
+  /** Refresh the access token when it is within this many ms of expiry (verified ~5 min). */
+  refreshSkewMs: 5 * 60_000, // currently informational only — refresh is 401-driven; proactive refresh is deferred
+} as const;
+
+/** Headers attached to every Codex-backend model request.
+ *  `Authorization: Bearer <access_token>` + `chatgpt-account-id: <account_id>` are well-attested.
+ *  UNVERIFIED: whether an additional `OpenAI-Beta` / `originator` / `session_id` header is
+ *  required by the Codex responses endpoint — confirm against the Codex source. */
+export function codexHeaders(accessToken: string, accountId: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${accessToken}`,
+    "chatgpt-account-id": accountId,
+    originator: OPENAI_CODEX_AUTH.originator,
+  };
+}

package/src/core/auth/login.ts

@@ -0,0 +1,110 @@
+/** OAuth (PKCE authorization-code) login flow for ChatGPT subscription sign-in.
+ *  Pure/exchange units are unit-tested; runLoginFlow (callback server + browser) is manual E2E. */
+import { OPENAI_CODEX_AUTH } from "./constants";
+import { generateCodeVerifier, codeChallenge } from "./pkce";
+import type { AuthProfile } from "./profile";
+
+interface TokenResponse { access_token: string; refresh_token: string; id_token?: string; expires_in: number; }
+
+export async function buildAuthorizeUrl(verifier: string, state: string): Promise<string> {
+  const u = new URL(OPENAI_CODEX_AUTH.authorizeUrl);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("client_id", OPENAI_CODEX_AUTH.clientId);
+  u.searchParams.set("redirect_uri", OPENAI_CODEX_AUTH.redirectUri);
+  u.searchParams.set("scope", OPENAI_CODEX_AUTH.scopes);
+  u.searchParams.set("code_challenge", await codeChallenge(verifier));
+  u.searchParams.set("code_challenge_method", OPENAI_CODEX_AUTH.codeChallengeMethod);
+  u.searchParams.set("state", state);
+  u.searchParams.set("originator", OPENAI_CODEX_AUTH.originator);
+  return u.toString();
+}
+
+export function decodeJwtPayload(jwt: string): Record<string, unknown> {
+  const part = jwt.split(".")[1];
+  if (!part) throw new Error("invalid jwt: no payload segment");
+  return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+}
+
+function accountIdFrom(idToken: string | undefined): string {
+  if (!idToken) return "";
+  try {
+    const payload = decodeJwtPayload(idToken);
+    const ns = payload[OPENAI_CODEX_AUTH.accountIdClaim.namespace] as Record<string, unknown> | undefined;
+    return (ns?.[OPENAI_CODEX_AUTH.accountIdClaim.field] as string)
+      ?? (payload[OPENAI_CODEX_AUTH.accountIdClaim.field] as string)
+      ?? "";
+  } catch { return ""; }
+}
+
+export async function exchangeCode(
+  opts: { code: string; verifier: string },
+  fetchImpl: typeof fetch = fetch,
+  now: () => number = Date.now,
+): Promise<AuthProfile> {
+  const res = await fetchImpl(OPENAI_CODEX_AUTH.tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: opts.code,
+      redirect_uri: OPENAI_CODEX_AUTH.redirectUri,
+      client_id: OPENAI_CODEX_AUTH.clientId,
+      code_verifier: opts.verifier,
+    }),
+  });
+  if (!res.ok) throw new Error(`token exchange failed: HTTP ${res.status}`);
+  const t = (await res.json()) as TokenResponse;
+  const account_id = accountIdFrom(t.id_token);
+  if (!account_id) throw new Error("taicho: could not read account_id from the ChatGPT id_token — the accountIdClaim path in constants.ts may need verification");
+  return { access_token: t.access_token, refresh_token: t.refresh_token, expires_at: now() + t.expires_in * 1000, account_id };
+}
+
+export interface LoginDeps {
+  openBrowser?: (url: string) => void;
+  onUrl?: (url: string) => void; // so the REPL can print the URL for the paste fallback
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** Interactive: open the browser, run a localhost callback server, exchange the code. Manual E2E. */
+export async function runLoginFlow(deps: LoginDeps = {}): Promise<AuthProfile> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const verifier = generateCodeVerifier();
+  const state = generateCodeVerifier();
+  const url = await buildAuthorizeUrl(verifier, state);
+
+  let resolveCode!: (code: string) => void;
+  let rejectFlow!: (e: Error) => void;
+  const codePromise = new Promise<string>((res, rej) => { resolveCode = res; rejectFlow = rej; });
+
+  const server = Bun.serve({
+    port: OPENAI_CODEX_AUTH.callbackPort,
+    fetch(req) {
+      const u = new URL(req.url);
+      if (u.pathname === OPENAI_CODEX_AUTH.callbackPath) {
+        if (u.searchParams.get("state") !== state) { rejectFlow(new Error("OAuth state mismatch")); return new Response("state mismatch", { status: 400 }); }
+        const err = u.searchParams.get("error");
+        if (err) { rejectFlow(new Error(u.searchParams.get("error_description") ?? err)); return new Response("sign-in failed", { status: 400 }); }
+        const code = u.searchParams.get("code");
+        if (code) { resolveCode(code); return new Response("taicho: signed in — you can close this tab."); }
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+
+  const timer = setTimeout(() => rejectFlow(new Error("login timed out — run /login openai again")), deps.timeoutMs ?? 120_000);
+  deps.onUrl?.(url);
+  (deps.openBrowser ?? defaultOpen)(url);
+  try {
+    const code = await codePromise;
+    return await exchangeCode({ code, verifier }, fetchImpl);
+  } finally {
+    clearTimeout(timer);
+    server.stop(true);
+  }
+}
+
+function defaultOpen(url: string): void {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try { Bun.spawn([cmd, url], { stdout: "ignore", stderr: "ignore" }); } catch { /* fall back to the printed URL */ }
+}

package/src/core/auth/pkce.ts

@@ -0,0 +1,18 @@
+/** PKCE (RFC 7636) helpers for the OAuth authorization-code flow. */
+
+function base64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** A cryptographically-random base64url verifier (32 bytes -> 43 chars, within RFC's 43–128). */
+export function generateCodeVerifier(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+/** S256 challenge: base64url(SHA-256(verifier)). */
+export async function codeChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}

package/src/core/auth/profile.ts

@@ -0,0 +1,38 @@
+/** OAuth profile store: a token bundle persisted per-user (NOT per-workspace) at
+ *  ~/.taicho/auth-profiles/openai-codex.json, mode 0600. Never logged. */
+import { z } from "zod";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, chmodSync } from "node:fs";
+
+export const AuthProfile = z.object({
+  access_token: z.string(),
+  refresh_token: z.string(),
+  expires_at: z.number(), // epoch ms
+  account_id: z.string(),
+  plan: z.string().optional(),
+});
+export type AuthProfile = z.infer<typeof AuthProfile>;
+
+export function authDir(home = homedir()): string { return join(home, ".taicho", "auth-profiles"); }
+export function profilePath(home = homedir()): string { return join(authDir(home), "openai-codex.json"); }
+
+export function writeProfile(p: AuthProfile, home = homedir()): void {
+  mkdirSync(authDir(home), { recursive: true, mode: 0o700 });
+  const f = profilePath(home);
+  writeFileSync(f, JSON.stringify(AuthProfile.parse(p), null, 2), { mode: 0o600 });
+  chmodSync(f, 0o600); // guarantee 0600 even if the file pre-existed with a looser mode
+}
+
+export function readProfile(home = homedir()): AuthProfile | null {
+  const f = profilePath(home);
+  if (!existsSync(f)) return null;
+  try { return AuthProfile.parse(JSON.parse(readFileSync(f, "utf8"))); } catch { return null; }
+}
+
+export function deleteProfile(home = homedir()): boolean {
+  const f = profilePath(home);
+  if (!existsSync(f)) return false;
+  rmSync(f);
+  return true;
+}