catherd-cli 0.2.1 → 1.0.0

package/src/adapters/codex/home.ts

@@ -0,0 +1,47 @@
+import { existsSync, lstatSync, readdirSync, readlinkSync, statSync, symlinkSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { dataDir } from "../../infra/paths.ts";
+import { ensurePrivateDir } from "../../infra/store.ts";
+
+export const userCodexHome = (): string => process.env.CODEX_HOME || join(homedir(), ".codex");
+
+/** Where isolated runs keep their Codex home; computing it creates nothing. */
+export const isolatedCodexHomePath = (): string => join(dataDir(), "codex-home");
+
+/** Isolated runs only: `--ignore-user-config` alone still loads the global AGENTS.md, so the home goes too. */
+export function isolatedCodexHome(): string {
+  const home = isolatedCodexHomePath();
+  ensurePrivateDir(home);
+  const auth = join(userCodexHome(), "auth.json");
+  const link = join(home, "auth.json");
+  if (!existsSync(auth)) return home;
+  // lstat, not existsSync: a broken link "does not exist" yet still blocks symlinkSync with EEXIST.
+  const current = lstatSync(link, { throwIfNoEntry: false });
+  if (current?.isSymbolicLink() && readlinkSync(link) !== auth) unlinkSync(link);
+  else if (current) return home;
+  symlinkSync(auth, link);
+  return home;
+}
+
+function mtimeMs(file: string): number | null {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return null; // vanished between readdir and stat
+  }
+}
+
+export function generatedImages(home: string, thread: string | null, sinceMs: number): string[] {
+  if (!thread) return [];
+  const dir = join(home, "generated_images", thread);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /\.(png|webp|jpe?g)$/i.test(f))
+    .map((f) => join(dir, f))
+    .filter((f) => {
+      const m = mtimeMs(f);
+      return m !== null && m >= sinceMs - 1000;
+    })
+    .sort();
+}

package/src/adapters/codex/index.ts

@@ -0,0 +1,227 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CatherdError } from "../../domain/errors.ts";
+import type { Access, RunStatus } from "../../domain/record.ts";
+import {
+  type BackendAdapter,
+  compareVersions,
+  type DiscoveredModel,
+  extractVersion,
+  type FinishedRun,
+  type Outcome,
+  type Probe,
+  type RunRequest,
+  type SpawnPlan,
+} from "../backend.ts";
+import { type CliResult, runCli } from "../cli.ts";
+import { CODEX_LIMIT, CODEX_TOO_OLD, foldCodexEvents, parseCodexLine } from "./events.ts";
+
+/** The item types that are a tool call running, as the idle watchdog counts them. */
+const CODEX_TOOL_ITEMS = new Set(["command_execution", "mcp_tool_call", "web_search", "file_change"]);
+import { generatedImages, isolatedCodexHome, isolatedCodexHomePath, userCodexHome } from "./home.ts";
+
+const CODEX_MIN_VERSION = "0.157.0";
+const THREAD = /^[A-Za-z0-9][A-Za-z0-9-]{3,127}$/;
+
+const SANDBOX: Record<Access, string> = {
+  "read-only": "read-only",
+  "workspace-write": "workspace-write",
+  full: "danger-full-access",
+};
+
+/** How long a `codex` query (version, login, models) may take before it counts as failed. */
+export const codexShell = { timeoutMs: 15_000 };
+
+/** Runs `codex <args>` without catherd's secrets; a run past the timeout is killed and counts as failed. */
+const sh = (args: string[], cwd?: string): Promise<CliResult | null> =>
+  runCli("codex", args, { timeoutMs: codexShell.timeoutMs, cwd });
+
+function plan(r: RunRequest): SpawnPlan {
+  if (r.thread !== null && !THREAD.test(r.thread))
+    throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a Codex thread id`, {
+      fix: "pass the thread from the earlier RunRecord",
+    });
+  const common = [
+    ...(r.isolated ? ["--ignore-user-config"] : []),
+    "-m",
+    r.rung.model,
+    // "default" leaves the effort to Codex's own config (spec §5.1)
+    ...(r.rung.effort === "default" ? [] : ["-c", `model_reasoning_effort=${r.rung.effort}`]),
+    "--json",
+    "-o",
+    r.replyPath,
+  ];
+  const sandbox = SANDBOX[r.access];
+  const args =
+    r.thread === null
+      ? ["exec", ...common, "-s", sandbox, "--", "-"]
+      : ["exec", "resume", ...common, "-c", `sandbox_mode=${sandbox}`, "--", r.thread, "-"];
+  return {
+    cmd: "codex",
+    args,
+    env: r.isolated ? { CODEX_HOME: isolatedCodexHome() } : {},
+    cwd: r.repo,
+    stdinPath: r.briefPath,
+  };
+}
+
+function finalize(run: FinishedRun): Outcome {
+  const f = foldCodexEvents(run.eventLines);
+  const tooOld = f.tooOld || CODEX_TOO_OLD.some((re) => re.test(run.stderr));
+  const stopped = run.exit.reason;
+  const status: RunStatus =
+    stopped === "cancelled"
+      ? "cancelled"
+      : stopped === "idle-timeout" || stopped === "wall-timeout"
+        ? "timeout"
+        : tooOld
+          ? "cli-too-old"
+          : f.limit
+            ? "limit"
+            : f.turnFailed
+              ? "failed"
+              : run.exit.code !== 0 && !run.reply.trim()
+                ? "failed"
+                : "ok";
+  const lastErr = run.stderr.trim().split("\n").at(-1) ?? "";
+  const home = run.request.isolated ? isolatedCodexHomePath() : userCodexHome();
+  return {
+    status,
+    thread: f.thread ?? run.request.thread,
+    tokens: f.tokens,
+    costUsd: null,
+    images: generatedImages(home, f.thread ?? run.request.thread, run.startedAtMs),
+    error:
+      status === "ok"
+        ? null
+        : {
+            code: status,
+            message: f.failure ?? (lastErr || `${stopped}, exit ${run.exit.code ?? run.exit.signal}`),
+          },
+  };
+}
+
+async function probe(): Promise<Probe> {
+  const v = await sh(["--version"]);
+  if (!v)
+    return {
+      installed: false,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [
+        { code: "E_BACKEND_MISSING", message: "codex is not on PATH", fix: "npm i -g @openai/codex" },
+      ],
+    };
+  const version = extractVersion(v.out);
+  const versionOk = version !== null && compareVersions(version, CODEX_MIN_VERSION) >= 0;
+  const status = await sh(["login", "status"]);
+  const loggedIn = status?.ok ?? false;
+  // how: `Logged in using ChatGPT`, or `… using an API key - <masked key>` (read, never kept); on stdout
+  // or stderr, depending on the version
+  const how = `${status?.out ?? ""}\n${status?.err ?? ""}`;
+  const login = !loggedIn
+    ? null
+    : /using ChatGPT/i.test(how)
+      ? "ChatGPT"
+      : /API key/i.test(how)
+        ? "API key"
+        : null;
+  const problems: Probe["problems"] = [];
+  if (!versionOk)
+    problems.push({
+      code: "E_BACKEND_TOO_OLD",
+      message: `codex ${version ?? "?"} is older than ${CODEX_MIN_VERSION}`,
+      fix: "npm i -g @openai/codex@latest",
+    });
+  if (!loggedIn)
+    problems.push({ code: "E_BACKEND_NOT_LOGGED_IN", message: "codex is not logged in", fix: "codex login" });
+  return {
+    installed: true,
+    version,
+    versionOk,
+    loggedIn,
+    ...(login ? { login, billing: login === "ChatGPT" ? "chatgpt-plan" : "metered" } : {}),
+    problems,
+  };
+}
+
+async function listModels(): Promise<DiscoveredModel[]> {
+  const r = await sh(["debug", "models"]);
+  const raw = r?.ok ? r.out : ((await sh(["debug", "models", "--bundled"]))?.out ?? "");
+  let data: { models?: Record<string, any>[] };
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  return (data.models ?? [])
+    .filter((m) => m.visibility === "list" && typeof m.slug === "string")
+    .map((m) => ({
+      id: m.slug as string,
+      efforts: ((m.supported_reasoning_levels ?? []) as { effort?: string }[])
+        .map((l) => l.effort)
+        .filter((e): e is string => typeof e === "string"),
+      context: typeof m.context_window === "number" ? m.context_window : null,
+      imageIn: Array.isArray(m.input_modalities) && m.input_modalities.includes("image"),
+    }));
+}
+
+/**
+ * Spec §10.3: runs a write into `dir` under `codex sandbox <os> --full-auto`, the workspace-write sandbox,
+ * from a scratch folder. null when this machine has no Codex sandbox to test with (the control fails).
+ */
+async function canWrite(dir: string): Promise<{ ok: boolean; fix?: string } | null> {
+  const os = process.platform === "darwin" ? "macos" : process.platform === "linux" ? "linux" : null;
+  if (!os) return null;
+  const cwd = mkdtempSync(join(tmpdir(), "catherd-sandbox-"));
+  try {
+    const run = (...script: string[]) => sh(["sandbox", os, "--full-auto", "--", "sh", "-c", ...script], cwd);
+    if (!(await run("true"))?.ok) return null;
+    const probe = join(dir, `.doctor-${process.pid}`);
+    // the path goes in as $1, never into the script text
+    const r = await run('touch "$1" && rm -f "$1"', "_", probe);
+    if (!r) return null;
+    return r.ok
+      ? { ok: true }
+      : {
+          ok: false,
+          fix: `add "${dir}" to writable_roots under [sandbox_workspace_write] in ~/.codex/config.toml`,
+        };
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+export const codexAdapter: BackendAdapter = {
+  id: "codex",
+  minVersion: CODEX_MIN_VERSION,
+  probe,
+  listModels,
+  plan,
+  parse(line) {
+    const e = parseCodexLine(line);
+    if (!e) return {};
+    const f = foldCodexEvents([line]);
+    // a tool call runs between item.started and item.completed, often printing nothing: the run is busy.
+    // Not a todo_list: update_plan opens one that only completes with the turn, and would mute the watchdog
+    const id = typeof e.item?.id === "string" && CODEX_TOOL_ITEMS.has(e.item.type) ? e.item.id : null;
+    const open = e.type === "item.started" ? true : e.type === "item.completed" ? false : null;
+    return {
+      ...(f.thread ? { thread: f.thread } : {}),
+      ...(id !== null && open !== null ? { item: { id, open } } : {}),
+      ...(e.type === "turn.completed" ? { tokens: f.tokens } : {}),
+      lastEvent: f.lastEvent ?? undefined,
+      ...(f.turnFailed ? { failure: f.failure ?? "turn failed" } : {}),
+      ...(f.limit ? { limit: true } : {}),
+      ...(f.tooOld ? { tooOld: true } : {}),
+    };
+  },
+  finalize,
+  enforcement: { "read-only": "enforced", "workspace-write": "enforced", full: "enforced" },
+  errors: { limit: CODEX_LIMIT, tooOld: CODEX_TOO_OLD },
+  resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
+  graceAfterFinalMs: null,
+  canWrite,
+};

package/src/adapters/discovery.ts

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { z } from "zod";
+import { discoveryDir } from "../infra/paths.ts";
+import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import type { DiscoveredModel } from "./backend.ts";
+
+const DiscoverySchema = z.looseObject({
+  schema: z.literal(1),
+  backend: z.string(),
+  fetchedAt: z.string(),
+  models: z.array(
+    z.object({
+      id: z.string(),
+      efforts: z.array(z.string()),
+      context: z.number().nullable(),
+      imageIn: z.boolean(),
+    }),
+  ),
+});
+export type DiscoveryFile = z.infer<typeof DiscoverySchema>;
+
+/**
+ * Spec §3.5: `<data>/discovery/<backend>.json`, the last listModels() with fetchedAt. A listing made for
+ * one repository (a backend whose models depend on where it runs) is kept apart, under `repos/`.
+ */
+export const discoveryPath = (backend: string, repo?: string): string =>
+  repo === undefined
+    ? join(discoveryDir(), `${backend}.json`)
+    : join(
+        discoveryDir(),
+        "repos",
+        `${backend}-${createHash("sha256").update(repo).digest("hex").slice(0, 16)}.json`,
+      );
+
+/** Backends whose listing depends on the repository they run in (opencode's project config enables models). */
+const PER_REPO: ReadonlySet<string> = new Set(["opencode"]);
+
+/** The repository `backend`'s listing is kept for: `repo` for a backend listed per repository, else none. */
+export const listingRepo = (backend: string, repo?: string): string | undefined =>
+  PER_REPO.has(backend) ? repo : undefined;
+
+/** The cached listing (for `repo` when given), or null when there is none or it cannot be read. */
+export function readDiscovery(backend: string, repo?: string): DiscoveryFile | null {
+  try {
+    return readVersioned(discoveryPath(backend, repo), DiscoverySchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+export function writeDiscovery(
+  backend: string,
+  models: DiscoveredModel[],
+  now = Date.now(),
+  repo?: string,
+): DiscoveryFile {
+  const file: DiscoveryFile = {
+    schema: 1,
+    backend,
+    ...(repo === undefined ? {} : { repo }),
+    fetchedAt: new Date(now).toISOString(),
+    models,
+  };
+  writeJsonAtomic(discoveryPath(backend, repo), file);
+  return file;
+}
+
+/**
+ * The cached models (for `repo` when given) while younger than `maxAgeMs` and listing `need` (when
+ * given); otherwise a fresh `list()`, cached when it is not empty. An empty fresh list falls back to the
+ * stale cache.
+ */
+export async function discovered(
+  backend: string,
+  list: () => Promise<DiscoveredModel[]>,
+  o: { maxAgeMs: number; need?: string; now?: number; repo?: string },
+): Promise<DiscoveredModel[]> {
+  const now = o.now ?? Date.now();
+  const cached = readDiscovery(backend, o.repo);
+  const fresh = cached !== null && now - Date.parse(cached.fetchedAt) < o.maxAgeMs;
+  if (cached && fresh && (o.need === undefined || cached.models.some((m) => m.id === o.need)))
+    return cached.models;
+  const models = await list();
+  if (models.length === 0) return cached?.models ?? [];
+  return writeDiscovery(backend, models, now, o.repo).models;
+}

package/src/adapters/opencode/agents.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Access } from "../../domain/record.ts";
+import { dataDir } from "../../infra/paths.ts";
+
+/** Spec §6.3: one catherd agent per access mode. */
+export const OPENCODE_AGENT: Record<Access, "catherd-ro" | "catherd-worker" | "catherd-full"> = {
+  "read-only": "catherd-ro",
+  "workspace-write": "catherd-worker",
+  full: "catherd-full",
+};
+
+const rule = (action: string, resource: string, effect: "allow" | "deny") =>
+  `  - { action: ${JSON.stringify(action)}, resource: ${JSON.stringify(resource)}, effect: ${effect} }`;
+
+/**
+ * Why catherd-ro has no shell (opencode v2 at 6585bb7, packages/core/src/…): the last matching rule wins
+ * (permission.ts:87-96) over a whole-resource wildcard (util/wildcard.ts:3-13), and the shell tool asks with
+ * one resource per parsed command (tool/plugin/shell.ts:126-140, shell/parse.ts:173-205). A redirect after a
+ * list or pipeline reaches no resource (`ls && cat a > b` asks for "ls" and "cat a"), so no allowlist of
+ * read commands is read-only. The role reads with read, glob and grep; its brief names the files.
+ */
+/**
+ * opencode v2 agent files (research 2026-09-25-opencode.md §4.5). Later rules win; every run passes
+ * `--auto`, so an "ask" left by opencode's defaults never aborts the run, and an explicit deny still holds.
+ * No body: the agent keeps opencode's own system prompt.
+ */
+export const OPENCODE_AGENT_FILES: Record<string, string> = {
+  "catherd-ro": [
+    "---",
+    "description: catherd read-only roles (architect, reviewer, researcher). Written by catherd.",
+    "mode: primary",
+    "permissions:",
+    rule("*", "*", "deny"),
+    ...["read", "glob", "grep", "webfetch", "websearch"].map((a) => rule(a, "*", "allow")),
+    // edit, write and patch all ask for `edit` (tool/plugin/edit.ts:181, write.ts:79, patch.ts:197)
+    rule("edit", "*", "deny"),
+    rule("shell", "*", "deny"),
+    "---",
+    "",
+  ].join("\n"),
+  "catherd-worker": [
+    "---",
+    "description: catherd workspace-write roles (worker, writer, artist). Written by catherd.",
+    "mode: primary",
+    "permissions:",
+    rule("*", "*", "allow"),
+    ...["git commit*", "git push*", "git reset --hard*"].map((c) => rule("shell", c, "deny")),
+    rule("question", "*", "deny"),
+    "---",
+    "",
+  ].join("\n"),
+  "catherd-full": [
+    "---",
+    "description: catherd full-access roles (verifier, ui-reviewer). Written by catherd.",
+    "mode: primary",
+    "permissions:",
+    rule("*", "*", "allow"),
+    rule("question", "*", "deny"),
+    "---",
+    "",
+  ].join("\n"),
+};
+
+/** The XDG config root opencode reads: the user's, or catherd's own for isolated runs. */
+export const userConfigRoot = (): string => process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+export const isolatedConfigRoot = (): string => join(dataDir(), "opencode-home", "config");
+
+export const agentsDir = (root: string): string => join(root, "opencode", "agents");
+
+/** Writes any catherd agent file that is missing or differs; true when one changed. Never touches other agents. */
+export function installAgents(root: string): boolean {
+  const dir = agentsDir(root);
+  mkdirSync(dir, { recursive: true });
+  let changed = false;
+  for (const [name, text] of Object.entries(OPENCODE_AGENT_FILES)) {
+    const file = join(dir, `${name}.md`);
+    if (existsSync(file) && readFileSync(file, "utf8") === text) continue;
+    writeFileSync(file, text);
+    changed = true;
+  }
+  return changed;
+}

package/src/adapters/opencode/events.ts

@@ -0,0 +1,109 @@
+import { type Tokens, ZERO_TOKENS } from "../../domain/record.ts";
+
+/** Spec §6.3: these error types are a usage limit, so the rung fails over. */
+export const OPENCODE_LIMIT_TYPES = ["provider.quota", "provider.rate-limit"];
+export const OPENCODE_LIMIT = [/provider\.quota/, /provider\.rate-limit/];
+/** opencode v1 errors: v2's `-m provider/model#variant` is a model v1 cannot find. */
+export const OPENCODE_TOO_OLD = [/ProviderModelNotFoundError/];
+
+export interface OpencodeFold {
+  thread: string | null;
+  tokens: Tokens;
+  costUsd: number;
+  lastEvent: string | null;
+  error: { type: string | null; message: string } | null;
+  limit: boolean;
+  tooOld: boolean;
+  /** the tool call a permission rule declined, e.g. `read <scratch>/outside.txt` */
+  declined: string | null;
+  /** the text of the last assistant message: earlier narration is not the reply */
+  reply: string;
+}
+
+type Event = Record<string, any>;
+
+export function parseOpencodeLine(line: string): Event | null {
+  if (!line.trim().startsWith("{")) return null;
+  try {
+    const e = JSON.parse(line) as unknown;
+    return e && typeof e === "object" && !Array.isArray(e) ? (e as Event) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** opencode counts cache reads and writes apart from input; catherd's input includes them (spec §4.3). */
+export function opencodeTokens(t: Event | undefined): Tokens {
+  if (!t) return { ...ZERO_TOKENS };
+  const n = (v: unknown) => (typeof v === "number" ? v : 0);
+  const cached = n(t.cache?.read);
+  return {
+    input: n(t.input) + cached + n(t.cache?.write),
+    cached,
+    output: n(t.output) + n(t.reasoning),
+  };
+}
+
+export const eventName = (e: Event): string =>
+  e.type === "tool_use" ? `tool_use/${e.part?.tool ?? "?"}` : String(e.type ?? "?");
+
+/** v1 errors are `{name, data}`; v2 errors are `{type, message}`. */
+export const isV1Error = (e: Event): boolean =>
+  e.type === "error" && typeof e.error?.name === "string" && e.error?.type === undefined;
+
+function firstString(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const v = Object.values(input as Record<string, unknown>).find((x) => typeof x === "string");
+  return typeof v === "string" ? v : "";
+}
+
+/**
+ * v2 often drops the last `step_finish`, so these stream tokens undercount; `settle` replaces them with
+ * the session's totals from the API.
+ */
+export function foldOpencodeEvents(lines: string[]): OpencodeFold {
+  const f: OpencodeFold = {
+    thread: null,
+    tokens: { ...ZERO_TOKENS },
+    costUsd: 0,
+    lastEvent: null,
+    error: null,
+    limit: false,
+    tooOld: false,
+    declined: null,
+    reply: "",
+  };
+  const texts = new Map<string, string[]>();
+  let lastMessage: string | null = null;
+  for (const line of lines) {
+    const e = parseOpencodeLine(line);
+    if (!e) continue;
+    f.lastEvent = eventName(e);
+    if (typeof e.sessionID === "string") f.thread ??= e.sessionID;
+    if (e.type === "text" && typeof e.part?.text === "string") {
+      const id = String(e.part.messageID ?? "");
+      texts.set(id, [...(texts.get(id) ?? []), e.part.text]);
+      lastMessage = id;
+    } else if (e.type === "step_finish") {
+      const t = opencodeTokens(e.part?.tokens);
+      f.tokens.input += t.input;
+      f.tokens.cached += t.cached;
+      f.tokens.output += t.output;
+      if (typeof e.part?.cost === "number") f.costUsd += e.part.cost;
+    } else if (e.type === "tool_use" && e.part?.state?.status === "error") {
+      if (/declined/i.test(String(e.part.state.error ?? "")))
+        f.declined = `${e.part.tool} ${firstString(e.part.state.input)}`.trim();
+    } else if (e.type === "error") {
+      if (isV1Error(e)) {
+        f.tooOld = true;
+        f.error = { type: null, message: String(e.error.data?.message ?? e.error.name) };
+      } else {
+        const type = typeof e.error?.type === "string" ? e.error.type : null;
+        f.error = { type, message: String(e.error?.message ?? type ?? "error") };
+        if (type && OPENCODE_LIMIT_TYPES.includes(type)) f.limit = true;
+      }
+    }
+  }
+  if (lastMessage !== null) f.reply = (texts.get(lastMessage) ?? []).join("\n");
+  return f;
+}