@taicho-ai/framework 0.1.0

package/src/store/artifacts.ts

@@ -0,0 +1,338 @@
+/** Addressable, versioned, IMMUTABLE-PER-VERSION artifact store over artifacts/. Files are canon;
+ *  artifacts/_index.json is a rebuildable manifest for enumeration. A revision is a NEW version,
+ *  never an overwrite — v<N>.json is written exclusively (flag "wx"), like reserveRunId. The store
+ *  is PAYLOAD-AGNOSTIC: the body is opaque bytes (or an external ref) and it never interprets it.
+ *  Mirrors store/skills.ts (files canon + a rebuildable index).
+ *
+ *  Layout:  artifacts/<id>/v<N>.json   — the envelope (metadata + summary + location)
+ *           artifacts/<id>/v<N>.<ext>  — the body bytes (local-file artifacts only)
+ *           artifacts/_index.json      — manifest: the latest version of every id (rebuildable) */
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, renameSync } from "node:fs";
+import { join, basename } from "node:path";
+import { Artifact, type ArtifactLocation, parseHandle } from "@taicho-ai/contracts/artifact";
+import { paths } from "./files";
+
+// underscore prefix ⇒ can never collide with a valid artifact id dir (ids start with [a-z0-9]).
+const MANIFEST = "_index.json";
+
+function idDir(ws: string, id: string): string { return join(paths.artifactDir(ws), id); }
+function envelopeFile(ws: string, id: string, version: number): string { return join(idDir(ws, id), `v${version}.json`); }
+function bodyFile(ws: string, id: string, version: number, ext: string): string { return join(idDir(ws, id), `v${version}.${ext}`); }
+function manifestPath(ws: string): string { return join(paths.artifactDir(ws), MANIFEST); }
+
+function slugify(s: string): string {
+  const slug = s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return slug || "artifact";
+}
+
+/** A caller-supplied id, normalized to the store's id shape; null if it reduces to nothing. */
+function normalizeId(raw?: string): string | null {
+  if (!raw) return null;
+  const id = raw.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return id || null;
+}
+
+/** Versions present for an id, ascending. */
+export function artifactVersions(ws: string, id: string): number[] {
+  const dir = idDir(ws, id);
+  if (!existsSync(dir)) return [];
+  const vs: number[] = [];
+  for (const f of readdirSync(dir)) {
+    const m = f.match(/^v(\d+)\.json$/);
+    if (m) vs.push(Number(m[1]));
+  }
+  return vs.sort((a, b) => a - b);
+}
+
+export interface SaveArtifactInput {
+  id?: string;                 // stable logical id/slug; omit to derive from the title
+  title: string;
+  type?: string;               // free-form tag
+  role?: "output" | "input" | "resource";
+  producer: string;            // agentId (provenance — from ctx in the tool)
+  runId: string;               // run id (provenance — from ctx in the tool)
+  parents?: string[];          // parent artifact handles (lineage)
+  summary?: string;
+  body?: string | Uint8Array;  // local bytes to store; omit when using `external`
+  external?: string;           // external ref URI (instead of local body)
+  ext?: string;                // body file extension (default md)
+}
+
+/** Save a NEW immutable version. Reusing an existing id bumps to the next version (never overwrites);
+ *  a fresh id starts at v1. Provenance/lineage come from the caller. */
+export function saveArtifact(ws: string, input: SaveArtifactInput): Artifact {
+  if (input.body === undefined && !input.external) throw new Error("save_artifact needs a body or an external location");
+  const id = normalizeId(input.id) ?? slugify(input.title);
+  mkdirSync(idDir(ws, id), { recursive: true });
+  const ext = (input.ext ?? "md").replace(/[^a-z0-9]/gi, "").slice(0, 12) || "md";
+
+  // exclusive-create the envelope so a concurrent save can never clobber a version — retry the next.
+  for (let version = (artifactVersions(ws, id).at(-1) ?? 0) + 1; ; version++) {
+    const location: ArtifactLocation = input.external
+      ? { kind: "external", uri: input.external }
+      : { kind: "file", path: bodyFile(ws, id, version, ext) };
+    const artifact = Artifact.parse({
+      id, version, title: input.title, type: input.type ?? "document",
+      role: input.role ?? "output", producer: input.producer, runId: input.runId,
+      parents: input.parents ?? [], summary: input.summary, location,
+      created: new Date().toISOString(),
+    });
+    try {
+      writeFileSync(envelopeFile(ws, id, version), JSON.stringify(artifact, null, 2), { flag: "wx" });
+      if (location.kind === "file") writeFileSync(location.path, input.body ?? "");
+      upsertManifest(ws, artifact);
+      return artifact;
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException)?.code === "EEXIST") continue; // lost a race for this version
+      throw e;
+    }
+  }
+}
+
+/** The envelope for a handle ("id" ⇒ latest, "id@vN" ⇒ that version); null if absent. */
+export function readArtifact(ws: string, handle: string): Artifact | null {
+  const { id, version } = parseHandle(handle);
+  const v = version ?? artifactVersions(ws, id).at(-1);
+  if (!v) return null;
+  const file = envelopeFile(ws, id, v);
+  if (!existsSync(file)) return null;
+  try { return Artifact.parse(JSON.parse(readFileSync(file, "utf8"))); } catch { return null; }
+}
+
+/** Raw body bytes for a local-file artifact; null if external or missing. Payload-agnostic (Buffer).
+ *  RELOCATABLE addressing: the body path is recomputed from the CURRENT ws + the artifact's id + the
+ *  stored filename (v<N>.<ext>), exactly as envelopeFile recomputes the envelope path. The absolute
+ *  path baked into the envelope goes stale the moment the workspace dir is renamed/moved, but the
+ *  bytes still live at ws/artifacts/<id>/v<N>.<ext> — so we address them by ws, not by the baked path. */
+export function readArtifactBody(ws: string, handle: string): Buffer | null {
+  const file = artifactBodyPath(ws, handle);
+  if (!file || !existsSync(file)) return null;
+  return readFileSync(file);
+}
+
+/** Plan 21: the body file's CURRENT path (recomputed from ws, per the relocatable-addressing note
+ *  above — never read `location.path` directly); null for external artifacts or a missing handle.
+ *  The browser's `o` verb hands this to $EDITOR. */
+export function artifactBodyPath(ws: string, handle: string): string | null {
+  const a = readArtifact(ws, handle);
+  if (!a || a.location.kind !== "file") return null;
+  return join(idDir(ws, a.id), basename(a.location.path));
+}
+
+export interface ArtifactFilter {
+  producer?: string;
+  type?: string;
+  role?: "output" | "input" | "resource";
+  q?: string;   // substring over id/title/summary
+}
+
+/** The latest version of each artifact, filtered, newest first. Reads the manifest (rebuilds it from
+ *  the canonical envelopes if it's missing). */
+export function listArtifacts(ws: string, filter: ArtifactFilter = {}): Artifact[] {
+  const ql = filter.q?.toLowerCase();
+  return readManifest(ws).filter((a) =>
+    (!filter.producer || a.producer === filter.producer) &&
+    (!filter.type || a.type === filter.type) &&
+    (!filter.role || a.role === filter.role) &&
+    (!ql || `${a.id} ${a.title} ${a.summary ?? ""}`.toLowerCase().includes(ql)),
+  ).sort((x, y) => y.created.localeCompare(x.created));
+}
+
+// ── manifest (rebuildable index) ─────────────────────────────────────────────
+
+function readManifestRaw(ws: string): Artifact[] {
+  const f = manifestPath(ws);
+  if (!existsSync(f)) return [];
+  try {
+    const arr = JSON.parse(readFileSync(f, "utf8"));
+    return Array.isArray(arr) ? arr.map((x) => Artifact.parse(x)) : [];
+  } catch { return []; }
+}
+
+/** The manifest (latest version per id). _index.json is a REBUILDABLE cache, never authoritative:
+ *  rebuilt from the canonical envelopes when it's missing/empty, and RECONCILED against a cheap dir
+ *  scan so a valid-but-stale manifest (an id dropped by a cross-process last-writer-wins upsert)
+ *  self-heals — we union in any on-disk id the manifest is missing. The common case is a single
+ *  readdir + set-membership check (no file reads); recovery only touches ids the manifest lacks. */
+export function readManifest(ws: string): Artifact[] {
+  const raw = readManifestRaw(ws);
+  if (!raw.length) return rebuildArtifactIndex(ws);
+  const dir = paths.artifactDir(ws);
+  if (!existsSync(dir)) return raw;
+  const known = new Set(raw.map((a) => a.id));
+  const recovered: Artifact[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || known.has(entry.name)) continue;
+    const top = artifactVersions(ws, entry.name).at(-1);
+    if (!top) continue;
+    const a = readArtifact(ws, `${entry.name}@v${top}`);
+    if (a) recovered.push(a);
+  }
+  if (!recovered.length) return raw;
+  const healed = [...raw, ...recovered];
+  writeManifest(ws, healed);   // make the heal durable
+  return healed;
+}
+
+function writeManifest(ws: string, arr: Artifact[]): void {
+  mkdirSync(paths.artifactDir(ws), { recursive: true });
+  // atomic publish (temp + rename) so a concurrent reader never observes a half-written manifest.
+  const dest = manifestPath(ws);
+  const tmp = `${dest}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(arr, null, 2));
+  renameSync(tmp, dest);
+}
+
+/** `a` is always the newest version of its id (saveArtifact only ever appends), so it replaces any
+ *  prior manifest entry for that id. Seeds from the canonical scan so a deleted manifest self-heals. */
+function upsertManifest(ws: string, a: Artifact): void {
+  const cur = readManifest(ws).filter((x) => x.id !== a.id);
+  cur.push(a);
+  writeManifest(ws, cur);
+}
+
+/** Rebuild the manifest by scanning every id dir's latest envelope (files are canon). */
+export function rebuildArtifactIndex(ws: string): Artifact[] {
+  const dir = paths.artifactDir(ws);
+  if (!existsSync(dir)) return [];
+  const latest: Artifact[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const top = artifactVersions(ws, entry.name).at(-1);
+    if (!top) continue;
+    const a = readArtifact(ws, `${entry.name}@v${top}`);
+    if (a) latest.push(a);
+  }
+  writeManifest(ws, latest);
+  return latest;
+}
+
+// ── retention & GC (Plan 01 Phase 4b) ────────────────────────────────────────
+// Immutable-per-version + heavy media = unbounded disk. Policy (Phase 0): keep-latest-N per id +
+// archive UNREFERENCED old versions; NEVER break an id CONSUMED by a hand-off/policy/task. "Archive"
+// relocates a version's files into artifacts/<id>/_archive/ — out of the live scan (artifactVersions
+// only reads the id dir's top level), so the addressable store shrinks WITHOUT losing history and no
+// referenced version ever disappears from under a live reference.
+//
+// A version is "referenced" iff something CONSUMES or PINS it — a hand-off edge (inputArtifacts /
+// outputArtifacts), a task's resultRef, an approved-output exemplar (policy.artifact), an annotation,
+// or the parent-closure of a kept version. It is NOT referenced merely because its own producing run
+// recorded emitting it: EVERY version an agent saves lands in that run's `trace.artifacts`, so
+// treating the producing record as a reference would pin every version ever produced and shadow
+// keep-latest-N entirely (the retention feature would archive nothing — the PR #17 GC no-op bug).
+// `collectReferencedArtifacts` below deliberately draws ONLY from the consumption/hand-off graph.
+
+// underscore prefix ⇒ can never collide with a valid artifact id dir; also where a version's files go.
+const ARCHIVE = "_archive";
+
+/** The live-reference sources GC honors: everything that CONSUMES or PINS an artifact handle, as
+ *  opposed to a producing run's own record of what it emitted (`trace.artifacts`, deliberately absent
+ *  here — see the GC-section note above). Annotation targets + parent-closure are protected INSIDE
+ *  gcArtifacts (off the on-disk annotations log + lineage fixpoint), not gathered here. */
+export interface GcReferenceSources {
+  // Hand-off graph only — the handles that flowed ACROSS delegation edges (down to children /
+  // up from them). NEVER a trace's own `artifacts` (its production record).
+  traces?: { inputArtifacts?: string[]; outputArtifacts?: string[] }[];
+  taskResultRefs?: (string | null | undefined)[];   // task-state hand-off refs (an id@vN, or a run id → harmlessly ignored)
+  exemplarArtifacts?: (string | null | undefined)[]; // approved-output exemplars (policy.artifact handles)
+  extra?: (string | null | undefined)[];            // any other live handles the caller knows about
+}
+
+/** PURE: collect the deduped set of artifact handles GC must protect because something CONSUMES,
+ *  HANDS OFF, or PINS them — the union of every source in `src`. Deliberately draws from the
+ *  consumption/hand-off graph, NOT a producing run's own `trace.artifacts` (which lists every version
+ *  it ever saved and would shadow keep-latest-N). A superseded intermediate that nothing here points
+ *  at, and that falls outside keep-latest-N, is therefore archivable. */
+export function collectReferencedArtifacts(src: GcReferenceSources): string[] {
+  const out = new Set<string>();
+  const add = (h?: string | null) => { const t = h?.trim(); if (t) out.add(t); };
+  for (const t of src.traces ?? []) {
+    for (const h of t.inputArtifacts ?? []) add(h);
+    for (const h of t.outputArtifacts ?? []) add(h);
+  }
+  for (const h of src.taskResultRefs ?? []) add(h);
+  for (const h of src.exemplarArtifacts ?? []) add(h);
+  for (const h of src.extra ?? []) add(h);
+  return [...out];
+}
+
+export interface GcOptions {
+  keepLatest?: number;    // per id: always keep the N newest versions (default 3)
+  referenced?: string[];  // protected handles the CALLER knows are live (hand-off/policy/task refs — see collectReferencedArtifacts)
+  /** Plan 21: compute the protected set and the would-archive list on the SAME code path, but touch
+   *  nothing — the browser's `g` verb previews with this, then runs for real; preview and action
+   *  cannot disagree because they are one function. */
+  dryRun?: boolean;
+}
+export interface GcReport {
+  archived: string[];     // version handles ("id@vN") relocated into _archive
+  kept: number;           // count of live versions remaining after GC
+  protectedRefs: number;  // size of the protected set honored (keep-latest + referenced + annotated + lineage)
+}
+
+/** Normalize a handle to a concrete "id@vN" (bare id ⇒ its latest present version); null if absent. */
+function pin(ws: string, handle: string): string | null {
+  const { id, version } = parseHandle(handle);
+  const v = version ?? artifactVersions(ws, id).at(-1);
+  return v ? `${id}@v${v}` : null;
+}
+
+/** Collect the handles GC must protect for one id: keep-latest-N + every version that carries an
+ *  annotation (its target/resolvedBy). Read straight off the annotations log to avoid an import cycle
+ *  with store/annotations.ts (which reads THIS module). */
+function protectForId(ws: string, id: string, keepLatest: number, into: Set<string>): void {
+  const vs = artifactVersions(ws, id);
+  for (const v of vs.slice(-keepLatest)) into.add(`${id}@v${v}`);
+  const af = join(idDir(ws, id), "annotations.jsonl");
+  if (!existsSync(af)) return;
+  for (const line of readFileSync(af, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const a = JSON.parse(line) as { target?: string; resolvedBy?: string };
+      for (const h of [a.target, a.resolvedBy]) { if (h) { const n = pin(ws, h); if (n) into.add(n); } }
+    } catch { /* skip corrupt annotation line */ }
+  }
+}
+
+export function gcArtifacts(ws: string, opts: GcOptions = {}): GcReport {
+  const keepLatest = Math.max(1, opts.keepLatest ?? 3);
+  const dir = paths.artifactDir(ws);
+  if (!existsSync(dir)) return { archived: [], kept: 0, protectedRefs: 0 };
+
+  const ids = readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== ARCHIVE)
+    .map((e) => e.name);
+
+  const protectedSet = new Set<string>();
+  for (const h of opts.referenced ?? []) { const n = pin(ws, h); if (n) protectedSet.add(n); }
+  for (const id of ids) protectForId(ws, id, keepLatest, protectedSet);
+
+  // Lineage integrity: a protected version's ancestors must survive too. Iterate to a fixed point.
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const h of [...protectedSet]) {
+      const a = readArtifact(ws, h);
+      for (const p of a?.parents ?? []) { const n = pin(ws, p); if (n && !protectedSet.has(n)) { protectedSet.add(n); grew = true; } }
+    }
+  }
+
+  const archived: string[] = [];
+  let kept = 0;
+  for (const id of ids) {
+    for (const v of artifactVersions(ws, id)) {
+      const handle = `${id}@v${v}`;
+      if (protectedSet.has(handle)) { kept++; continue; }
+      if (!opts.dryRun) {
+        const archiveDir = join(idDir(ws, id), ARCHIVE);
+        mkdirSync(archiveDir, { recursive: true });
+        // relocate the envelope (v<N>.json) + any body (v<N>.<ext>) — anchored so v1 never matches v11.
+        const re = new RegExp(`^v${v}\\.`);
+        for (const f of readdirSync(idDir(ws, id))) if (re.test(f)) renameSync(join(idDir(ws, id), f), join(archiveDir, f));
+      }
+      archived.push(handle); // dryRun: the WOULD-archive list, same computation
+    }
+  }
+  if (!opts.dryRun) rebuildArtifactIndex(ws); // latest-per-id is unchanged (only OLDER versions archived) — refresh anyway
+  return { archived, kept, protectedRefs: protectedSet.size };
+}

package/src/store/config.ts

@@ -0,0 +1,187 @@
+/** Resolve which provider/model to use and whether a key is present.
+ *  Env-first; config.yaml is deferred. Keys are read by the AI SDK from env directly. */
+import { z } from "zod";
+import { YAML } from "bun";
+import { join } from "node:path";
+import { log } from "../core/logger";
+
+export type Provider = "anthropic" | "openai" | "openrouter";
+export interface ResolvedConfig { provider: Provider; model: string; }
+export interface MissingConfig { missing: true; }
+
+// OpenRouter has no sensible default slug (its catalog drifts), so it maps to "" — an empty
+// sentinel meaning "model is required". buildModel/createModelResolver enforce non-empty there.
+const DEFAULT_MODEL: Record<Provider, string> = {
+  anthropic: "claude-sonnet-4-6",
+  openai: "gpt-5.5",
+  openrouter: "",
+};
+
+const keyFor = (env: Record<string, string | undefined>, p: Provider): string | undefined =>
+  p === "anthropic" ? env.ANTHROPIC_API_KEY : p === "openai" ? env.OPENAI_API_KEY : env.OPENROUTER_API_KEY;
+
+export function resolveConfig(env: Record<string, string | undefined> = process.env): ResolvedConfig | MissingConfig {
+  const tp = env.TAICHO_PROVIDER;
+  const wanted: Provider | null = tp === "openai" ? "openai" : tp === "anthropic" ? "anthropic" : tp === "openrouter" ? "openrouter" : null;
+  const pick = (p: Provider): ResolvedConfig => ({ provider: p, model: env.TAICHO_MODEL ?? DEFAULT_MODEL[p] });
+
+  if (wanted) return keyFor(env, wanted) ? pick(wanted) : { missing: true };
+  // Auto-detect: prefer a first-party key; OpenRouter is last so a stray key can't hijack a setup.
+  if (env.ANTHROPIC_API_KEY) return pick("anthropic");
+  if (env.OPENAI_API_KEY) return pick("openai");
+  if (env.OPENROUTER_API_KEY) return pick("openrouter");
+  return { missing: true };
+}
+
+export function isMissing(c: ResolvedConfig | MissingConfig): c is MissingConfig {
+  return "missing" in c;
+}
+
+const PartialBudgets = z.object({
+  maxIterationsPerRun: z.number().int().positive().optional(),
+  maxWorkItemsPerRequest: z.number().int().positive().optional(),
+  maxTokensPerRun: z.number().int().positive().optional(),
+  maxCostPerRunUsd: z.number().positive().optional(),
+  maxConcurrentRuns: z.number().int().positive().optional(), // Plan 04: per-agent background concurrency cap
+}).optional();
+
+const AgentOverride = z.object({
+  provider: z.enum(["anthropic", "openai", "openrouter"]).optional(),
+  model: z.string().optional(),
+  budgets: PartialBudgets,
+});
+
+/** An MCP server: a local stdio subprocess, or a remote HTTP endpoint. Distinguished by
+ *  `command` vs `url` (no explicit type tag). Secrets in env/headers use ${VAR} (see interpolateEnv). */
+const McpStdioServer = z.object({
+  command: z.string(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+});
+const McpHttpServer = z.object({
+  url: z.string().url(),
+  headers: z.record(z.string(), z.string()).optional(),
+  auth: z.literal("oauth").optional(), // omitted ⇒ no-auth or static-header auth
+  // Secrets stored WITH the server. `applyMcpEnv` loads them into process.env on add + every boot, so a
+  // ${VAR} ref in `url`/`headers` resolves (via interpolateEnv) both immediately and after a restart.
+  env: z.record(z.string(), z.string()).optional(),
+});
+export const McpServerConfig = z.union([McpStdioServer, McpHttpServer]);
+export type McpServerConfig = z.infer<typeof McpServerConfig>;
+export const isStdioServer = (s: McpServerConfig): s is z.infer<typeof McpStdioServer> => "command" in s;
+
+const McpConfig = z.object({
+  enabled: z.boolean().optional(), // default: on when servers are present
+  servers: z.record(z.string(), McpServerConfig).optional(),
+}).optional();
+export type McpConfig = z.infer<typeof McpConfig>;
+
+/** Expand ${VAR} references against the environment so secrets stay in env, not the config file. */
+export function interpolateEnv(value: string, env: Record<string, string | undefined> = process.env): string {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => env[name] ?? "");
+}
+
+/** Plan 09: squad-WIDE spend ceilings (all agents, all runs) enforced in the loop and persisted across
+ *  sessions. Distinct from per-run/per-agent `budgets` above — these bound the whole squad's rolling
+ *  daily/weekly spend. Any subset may be set; USD ceilings only constrain priced runs (a subscription
+ *  squad is bounded by tokens, never a fabricated dollar figure). Plan 19 adds per-team ceilings under
+ *  `teams.<id>.ceilings`, metered against the same SpendLedger with a different scope. */
+const Ceilings = z.object({
+  dailyTokens: z.number().int().positive().optional(),
+  weeklyTokens: z.number().int().positive().optional(),
+  dailyCostUsd: z.number().positive().optional(),
+  weeklyCostUsd: z.number().positive().optional(),
+});
+const SquadCeilings = Ceilings.optional();
+
+/** Plan 19: per-team configuration. `team.md` is canon for CAPABILITY (lead, charter, tool policy);
+ *  taicho.yaml overrides MODEL and BUDGETS — exactly the division of authority agents already use
+ *  between agent.md and `agents.<id>`. One rule, learned once.
+ *
+ *  Resolution walks agent → team → defaults, so "the trading team runs opus with a tight daily ceiling"
+ *  is one block instead of a line repeated on every member. `ceilings` bound the team's rolling spend
+ *  across sessions, metered against the same SpendLedger as the squad ceiling, under its own scope. */
+const TeamOverride = z.object({
+  provider: z.enum(["anthropic", "openai", "openrouter"]).optional(),
+  model: z.string().optional(),
+  budgets: PartialBudgets,
+  ceilings: Ceilings.optional(),
+});
+export type TeamOverride = z.infer<typeof TeamOverride>;
+
+export const TaichoConfig = z.object({
+  defaults: z.object({
+    provider: z.enum(["anthropic", "openai", "openrouter"]).optional(),
+    model: z.string().optional(),
+    budgets: PartialBudgets,
+    // Plan 05: fraction (0..1) of a model's context window at which the loop folds the oldest tool
+    // round-trips into one compact summary. Default ~0.7 (see compaction.ts DEFAULT_COMPACT_AT).
+    compactAt: z.number().positive().max(1).optional(),
+    // Plan 05 Ph3: how many recent conversation turns boot-replay keeps VERBATIM; older turns fold
+    // into a rolling summary. Default 6 (conversation-replay.ts DEFAULT_REPLAY_KEEP_TURNS).
+    replayKeepTurns: z.number().int().nonnegative().optional(),
+    // Plan 12: per-request transport deadline (ms) for a model fetch. A genuinely hung request (open
+    // socket, zero tokens) aborts the connection and errors, routed through the AI SDK's maxRetries —
+    // replaces the deleted loop-level idle watchdog. Default 120s (request-timeout.ts).
+    modelRequestTimeoutMs: z.number().int().positive().optional(),
+  }).optional(),
+  // Squad-level ceilings (Plan 09) — top-level because they bound the whole squad, not one agent.
+  budgets: SquadCeilings,
+  // Plan 19: per-team model/budget overrides + the team's own spend ceiling.
+  teams: z.record(z.string(), TeamOverride).optional(),
+  agents: z.record(z.string(), AgentOverride).optional(),
+  auth: z.object({ chatgpt_signin: z.boolean().optional() }).optional(),
+  // Plan 04: a global ceiling on total in-flight + queued BACKGROUND runs (dispatch_task). Bounds
+  // system-wide fan-out independent of per-agent maxConcurrentRuns; default applied in the REPL (32).
+  tasks: z.object({ maxBackgroundRuns: z.number().int().positive().optional() }).optional(),
+  mcp: McpConfig,
+  embeddings: z.object({ provider: z.enum(["off", "local", "openai"]).optional() }).optional(), // semantic KB backend
+}).default({});
+export type TaichoConfig = z.infer<typeof TaichoConfig>;
+
+export type AuthSource =
+  | { kind: "env"; provider: Provider; model: string }
+  | { kind: "oauth-openai-codex"; accountId: string; expiresAt: number }
+  | { kind: "none" };
+
+/** Precedence: an explicit `TAICHO_PROVIDER` always wins (`openai-codex` → subscription;
+ *  `openai`/`anthropic`/`openrouter` → that env API key). Otherwise a signed-in ChatGPT
+ *  subscription is PREFERRED over env API keys (if you logged in, you meant it), then env keys,
+ *  then none. `auth.chatgpt_signin: false` disables the subscription path entirely. */
+export function resolveAuth(opts: {
+  env?: Record<string, string | undefined>;
+  config: TaichoConfig;
+  loadProfile: () => { account_id: string; expires_at: number } | null;
+}): AuthSource {
+  const env = opts.env ?? process.env;
+  const flagOn = opts.config.auth?.chatgpt_signin !== false;
+  const profile = flagOn ? opts.loadProfile() : null;
+  const oauth = (): AuthSource =>
+    profile ? { kind: "oauth-openai-codex", accountId: profile.account_id, expiresAt: profile.expires_at } : { kind: "none" };
+  const envAuth = (): AuthSource => {
+    const envCfg = resolveConfig(env);
+    return isMissing(envCfg) ? { kind: "none" } : { kind: "env", provider: envCfg.provider, model: envCfg.model };
+  };
+
+  if (env.TAICHO_PROVIDER === "openai-codex") return oauth();
+  if (env.TAICHO_PROVIDER === "openai" || env.TAICHO_PROVIDER === "anthropic" || env.TAICHO_PROVIDER === "openrouter") return envAuth();
+  return profile ? oauth() : envAuth(); // signed-in subscription preferred over env keys
+}
+
+export async function loadConfig(ws: string): Promise<TaichoConfig> {
+  const file = join(ws, "taicho.yaml");
+  if (!(await Bun.file(file).exists())) return TaichoConfig.parse({});
+  let raw: unknown;
+  try {
+    raw = YAML.parse(await Bun.file(file).text());
+  } catch (e) {
+    log.warn(`failed to parse taicho.yaml — using defaults`, e);
+    return TaichoConfig.parse({});
+  }
+  const result = TaichoConfig.safeParse(raw);
+  if (!result.success) {
+    log.warn("invalid taicho.yaml — using defaults");
+    return TaichoConfig.parse({});
+  }
+  return result.data;
+}

package/src/store/conversation.ts

@@ -0,0 +1,107 @@
+/** Durable conversation evidence lives separately from prompt context.
+ *  ledger.jsonl is append-only audit history; context.json says which turns are safe to replay. */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./files";
+import { clearThread } from "./thread";
+
+export type LedgerStatus = "submitted" | "completed" | "failed" | "blocked" | "interrupted";
+
+export interface ConversationLedgerTurn {
+  turnId: string;
+  runId: string;
+  timestamp: string;
+  agent: string;
+  role: "user" | "assistant" | "system";
+  content: unknown;
+  status: LedgerStatus;
+  parentRunId?: string;
+  /** Plan 01 Ph5: artifact HANDLES (id@vN) this turn produced. Carried by REFERENCE into replay —
+   *  the replay cache resolves each to its summary (never the body); the ledger just records the ids. */
+  artifacts?: string[];
+}
+
+export interface ContextDecision {
+  turnId: string;
+  runId: string;
+  reason?: string;
+}
+
+export interface ConversationContext {
+  agent: string;
+  includedTurns: ContextDecision[];
+  excludedTurns: ContextDecision[];
+}
+
+export function newTurnId(agent: string, runId: string, role: string): string {
+  return `${agent}_${runId.slice(runId.indexOf("/") + 1)}_${role}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function ledgerFile(ws: string, agent: string): string {
+  return join(paths.conversationDir(ws, agent), "ledger.jsonl");
+}
+
+function contextFile(ws: string, agent: string): string {
+  return join(paths.conversationDir(ws, agent), "context.json");
+}
+
+export function appendLedgerTurn(ws: string, agent: string, turn: ConversationLedgerTurn): void {
+  mkdirSync(paths.conversationDir(ws, agent), { recursive: true });
+  appendFileSync(ledgerFile(ws, agent), JSON.stringify(turn) + "\n");
+}
+
+export function loadLedger(ws: string, agent: string): ConversationLedgerTurn[] {
+  const f = ledgerFile(ws, agent);
+  if (!existsSync(f)) return [];
+  const out: ConversationLedgerTurn[] = [];
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line) as ConversationLedgerTurn); } catch { /* ignore corrupt audit line */ }
+  }
+  return out;
+}
+
+export function loadContext(ws: string, agent: string): ConversationContext {
+  const f = contextFile(ws, agent);
+  if (!existsSync(f)) return { agent, includedTurns: [], excludedTurns: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(f, "utf8")) as ConversationContext;
+    return { agent, includedTurns: parsed.includedTurns ?? [], excludedTurns: parsed.excludedTurns ?? [] };
+  } catch {
+    return { agent, includedTurns: [], excludedTurns: [] };
+  }
+}
+
+export function recordContextDecision(
+  ws: string,
+  agent: string,
+  decision: { include: boolean; turnId: string; runId: string; reason?: string },
+): void {
+  mkdirSync(paths.conversationDir(ws, agent), { recursive: true });
+  const ctx = loadContext(ws, agent);
+  const entry = { turnId: decision.turnId, runId: decision.runId, reason: decision.reason };
+  const same = (x: ContextDecision) => x.turnId === decision.turnId;
+  ctx.includedTurns = ctx.includedTurns.filter((x) => !same(x));
+  ctx.excludedTurns = ctx.excludedTurns.filter((x) => !same(x));
+  if (decision.include) ctx.includedTurns.push(entry);
+  else ctx.excludedTurns.push(entry);
+  writeFileSync(contextFile(ws, agent), JSON.stringify(ctx, null, 2));
+}
+
+/** Durably reset an agent's conversation (a user-invoked `/clear`). The append-only ledger + context are
+ *  TRUTH, so they are ARCHIVED — moved to conversations/.archive/<agent>-<ts>/ — never deleted. The
+ *  derived replay cache (agents/<id>/thread.jsonl) is wiped too. A subsequent turn recreates a fresh
+ *  ledger and a subsequent boot loads an empty thread, so the old conversation never rehydrates. Returns
+ *  the archive path (or null if there was nothing to archive). */
+export function clearConversation(ws: string, agent: string, now: number = Date.now()): string | null {
+  const dir = paths.conversationDir(ws, agent);
+  let archived: string | null = null;
+  if (existsSync(dir)) {
+    const archiveRoot = join(ws, "conversations", ".archive");
+    mkdirSync(archiveRoot, { recursive: true });
+    archived = join(archiveRoot, `${agent}-${now}`);
+    renameSync(dir, archived);
+  }
+  clearThread(ws, agent); // the derived replay cache lives under agents/<id>/, outside the conversation dir
+  return archived;
+}

package/src/store/db.ts

@@ -0,0 +1,34 @@
+import { Database } from "bun:sqlite";
+import { join } from "node:path";
+import { migrate } from "./migrate";
+
+/** Embedded store: derived state only (registry cache, embeddings, indexes).
+ *  Files are canon — deleting the DB and re-indexing must always work. */
+export function openDb(workspace: string): Database {
+  const db = new Database(join(workspace, "taicho.db"), { create: true });
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    -- team (Plan 19) is declared here for a FRESH workspace only. CREATE TABLE IF NOT EXISTS cannot add
+    -- a column to a table that already exists, so every pre-Plan-19 database gets it from migration v8's
+    -- guarded ALTER instead. Both must be present and both idempotent: baseline alone would silently
+    -- skip existing workspaces, ALTER alone would throw "duplicate column" on new ones.
+    CREATE TABLE IF NOT EXISTS registry (
+      id TEXT PRIMARY KEY, role TEXT NOT NULL, is_root INTEGER DEFAULT 0, team TEXT
+    );
+    CREATE TABLE IF NOT EXISTS embeddings (
+      ref TEXT PRIMARY KEY,            -- policy/exemplar id or expansion key
+      kind TEXT NOT NULL,              -- 'policy' | 'exemplar'
+      vec BLOB NOT NULL                -- float32 array (brute-force cosine in v0; sqlite-vec later)
+    );
+    CREATE TABLE IF NOT EXISTS task_ledger (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      goal_hash TEXT NOT NULL,         -- dedup key for equivalent in-flight tasks
+      agent TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'claimed',  -- claimed | done | blocked
+      run_id TEXT,
+      created INTEGER DEFAULT (unixepoch())
+    );
+  `);
+  migrate(db); // versioned tables on top of the baseline (kb_nodes/kb_edges, meta)
+  return db;
+}