catherd-cli 0.2.1 → 1.1.0

package/src/services/routing-service.ts

@@ -0,0 +1,190 @@
+import { BUDGET_CHEAP_AT } from "../domain/budget.ts";
+import { errorMessage } from "../domain/errors.ts";
+import {
+  type JevAnswers,
+  judgeRoute,
+  judgeVerdict,
+  VERDICT_OPTIONS,
+  laneState,
+  type SetName,
+  scrubFree,
+} from "../domain/jev.ts";
+import { type Difficulty, type Kind, parseLaneHeader } from "../domain/lane.ts";
+import type { Role } from "../domain/roles.ts";
+import type { RouteJev } from "../domain/route.ts";
+import {
+  candidates,
+  defaultDifficulty,
+  defaultLadder,
+  type Pick,
+  type RoutingProfile,
+  select,
+} from "../domain/select.ts";
+import { log } from "../infra/log.ts";
+import { catalogQuery, freshenDiscovery, loadCatalog } from "./catalog-service.ts";
+import { type Asked, askJev, type JevOpts, jevQuestions, logJev } from "./jev-service.ts";
+import type { ProfileView, RouteAnswer, RouteRequest, RoutingPort, Verdict } from "./ports.ts";
+
+function routingProfile(v: ProfileView, role: Role, spentFraction: number): RoutingProfile {
+  const rc = v.roles[role];
+  return {
+    // spec §4.6: from 80 % of the budget on, start at the cheapest rung that clears the bar
+    objective: spentFraction >= BUDGET_CHEAP_AT ? "cost" : v.objective,
+    billing: v.billing,
+    role: {
+      enabled: rc?.enabled ?? false,
+      rungs: rc?.rungs ?? [],
+      ...(rc?.defaultRung ? { defaultRung: rc.defaultRung } : {}),
+    },
+  };
+}
+
+const answer = (
+  pick: Pick,
+  source: RouteAnswer["source"],
+  kind: Kind | null,
+  difficulty: Difficulty | null,
+  asked: Asked | null,
+  jev: RouteJev | null,
+): RouteAnswer => ({
+  ...pick,
+  source,
+  kind,
+  difficulty,
+  questionSet: asked?.answers ? asked.meta.questionSet : null,
+  jev,
+});
+
+/** How long `route` waits on the daily discovery refresh before routing on the cached listing. */
+const DISCOVERY_BUDGET_MS = 5_000;
+
+export interface RoutingOpts extends JevOpts {
+  /** how long a route waits on the discovery refresh (DISCOVERY_BUDGET_MS) */
+  discoveryBudgetMs?: number;
+}
+
+/** A wedged listing never holds a route: past `ms` it routes on the cache while the refresh finishes. */
+async function freshenWithin(rungs: string[], repo: string, ms: number): Promise<void> {
+  const refresh = freshenDiscovery(rungs, Date.now(), repo).catch((e: unknown) =>
+    log("debug", "discovery", { error: errorMessage(e) }),
+  );
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const budget = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  await Promise.race([refresh, budget]);
+  clearTimeout(timer);
+}
+
+/**
+ * Spec §5.4: kind and difficulty from Jev (§5.5's rule), else the lane file's `Kind:`/`Difficulty:`,
+ * else the role's default rung. A kind Jev is sure of survives a difficulty in the dead band: the
+ * difficulty then comes from the lane, else the role's default difficulty (`jev-kind`). A role with one
+ * usable rung never asks Jev.
+ */
+async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
+  const p = routingProfile(req.profile, req.role, req.spentFraction);
+  await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
+  const c = loadCatalog({ repo: req.repo });
+  const fallback = () => defaultLadder(c, p, req.role);
+  if (req.laneText === null || candidates(c, p, req.role).length <= 1)
+    return answer(fallback(), "default", null, null, null, null);
+  const lane = parseLaneHeader(req.laneText);
+  let asked: Asked | null = null;
+  let judged: ReturnType<typeof judgeRoute> | null = null;
+  if (req.profile.jev.use !== "off") {
+    asked = await askJev(req.runDir, "route-v2", laneState(req.laneText), o);
+    if (asked.answers) judged = judgeRoute(jevQuestions().sets["route-v2"].rule, asked.answers);
+  }
+  const jev: RouteJev | null = judged
+    ? { pKind: judged.pKind, pA: judged.pA, pB: judged.pB, nouls: judged.nouls }
+    : null;
+  let out: RouteAnswer;
+  if (judged?.track && judged.difficulty) {
+    const kind = judged.kind ?? lane.kind ?? "repo_code";
+    out = answer(select(c, p, req.role, kind, judged.difficulty), "jev", kind, judged.difficulty, asked, jev);
+  } else if (judged?.kind) {
+    const difficulty = lane.difficulty ?? defaultDifficulty(c, p, req.role, judged.kind);
+    out = answer(
+      select(c, p, req.role, judged.kind, difficulty),
+      "jev-kind",
+      judged.kind,
+      difficulty,
+      asked,
+      jev,
+    );
+  } else {
+    const kind = lane.kind;
+    out =
+      kind && lane.difficulty
+        ? answer(select(c, p, req.role, kind, lane.difficulty), "lane", kind, lane.difficulty, asked, jev)
+        : answer(fallback(), "default", null, null, asked, jev);
+  }
+  if (asked) {
+    logJev(req.runDir, {
+      ...asked.meta,
+      call: "route-v2",
+      lane: req.lane,
+      answers: asked.answers,
+      derived: judged
+        ? { ...jev, kind: judged.kind, track: judged.track, difficulty: judged.difficulty }
+        : null,
+      used: `${req.role} ${out.rung}`,
+      source: out.source,
+      why: asked.why ?? (judged ? judged.rule : "no answers"),
+    });
+  }
+  return out;
+}
+
+async function verdict<T extends string>(
+  runDir: string,
+  set: Extract<SetName, "finding" | "same-defect">,
+  state: Record<string, unknown>,
+  options: readonly T[],
+  use: "auto" | "off",
+  o: JevOpts,
+): Promise<Verdict<T>> {
+  const rule = jevQuestions().sets[set].rule;
+  // spec §5.5: Jev off means no question and no jev.jsonl row; the rule's default answers
+  if (use === "off") return judgeVerdict(rule, set, options, null);
+  const asked = await askJev(runDir, set, state, o);
+  const v = judgeVerdict(rule, set, options, asked.answers as JevAnswers | null);
+  logJev(runDir, {
+    ...asked.meta,
+    call: set,
+    lane: null,
+    answers: asked.answers,
+    derived: null,
+    used: v.value,
+    source: v.source,
+    why: asked.why ?? `p ${v.probability} ${v.source === "jev" ? "≥" : "<"} ${rule.min}`,
+  });
+  return v;
+}
+
+/** The routing port over the 1.0 catalog and Jev (spec §5); `o` lets tests inject Jev's transport. */
+export function routingService(o: RoutingOpts = {}): RoutingPort {
+  return {
+    route: (req) => route(req, o),
+    finding: (runDir, laneText, finding, use) =>
+      verdict(
+        runDir,
+        "finding",
+        { lane: laneState(laneText), finding: scrubFree(finding) },
+        VERDICT_OPTIONS.finding,
+        use,
+        o,
+      ),
+    sameDefect: (runDir, before, after, use) =>
+      verdict(
+        runDir,
+        "same-defect",
+        { before: scrubFree(before), after: scrubFree(after) },
+        VERDICT_OPTIONS["same-defect"],
+        use,
+        o,
+      ),
+    catalog: (filter, billing) => catalogQuery(filter, billing),
+  };
+}

package/src/services/run-debug.ts

@@ -0,0 +1,79 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import type { ExitInfo, RunRecord } from "../domain/record.ts";
+import { dispatchPaths, readExit } from "../infra/dispatch-dir.ts";
+import { redact } from "../infra/log.ts";
+import { listDispatches } from "./dispatches.ts";
+import { registerSavedSecrets } from "./jev-service.ts";
+import { readRecords, type Run } from "./run-store.ts";
+
+/** How many trailing lines of stderr, events and the supervisor log `runs show --debug` prints. */
+export const TAIL_LINES = 20;
+
+export interface DispatchDebug {
+  name: string;
+  dispatchId: string;
+  rung: string;
+  admittedAt: string;
+  record: RunRecord | null;
+  exit: ExitInfo | null;
+  stderrTail: string[];
+  eventsTail: string[];
+  supervisorTail: string[];
+}
+
+/**
+ * The last `n` non-blank lines of `file`, read backwards `chunk` bytes at a time until they are in hand:
+ * a worker's stderr or event stream can be large, and only its end is shown. [] when there is no file.
+ */
+export function tail(file: string, n = TAIL_LINES, chunk = 64 * 1024): string[] {
+  let fd: number;
+  try {
+    fd = openSync(file, "r");
+  } catch {
+    return [];
+  }
+  try {
+    let pos = fstatSync(fd).size;
+    let buf = Buffer.alloc(0);
+    for (;;) {
+      const lines = buf.toString("utf8").split("\n");
+      // the first line may start mid-line, or mid-character: it counts only once the file's start is read
+      if (pos > 0) lines.shift();
+      const kept = lines.filter((l) => l.trim());
+      if (kept.length >= n || pos === 0) return kept.slice(-n);
+      const len = Math.min(chunk, pos);
+      pos -= len;
+      const part = Buffer.alloc(len);
+      readSync(fd, part, 0, len, pos);
+      buf = Buffer.concat([part, buf]);
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Spec §10.2 `runs show <id> --debug`: per dispatch, oldest first, its record, exit.json and the tails of
+ * stderr, events.jsonl and supervisor.log, with every known secret redacted. Reads only.
+ */
+export function runDebug(run: Run, name?: string): DispatchDebug[] {
+  registerSavedSecrets();
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  return listDispatches(run)
+    .filter((d) => name === undefined || d.admit.name === name)
+    .sort((a, b) => a.admit.dispatchId.localeCompare(b.admit.dispatchId))
+    .map((d) => {
+      const p = dispatchPaths(d.dir);
+      return redact({
+        name: d.admit.name,
+        dispatchId: d.admit.dispatchId,
+        rung: d.admit.rung,
+        admittedAt: d.admit.admittedAt,
+        record: records.get(d.admit.dispatchId) ?? null,
+        exit: readExit(d.dir),
+        stderrTail: tail(p.stderr),
+        eventsTail: tail(p.events),
+        supervisorTail: tail(p.supervisorLog),
+      });
+    });
+}

package/src/services/run-service.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import { assertId, parseRung } from "../domain/ids.ts";
+import type { RunRecord } from "../domain/record.ts";
+import type { Role } from "../domain/roles.ts";
+import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { writeTextAtomic } from "../infra/store.ts";
+import {
+  dispatchState,
+  type DispatchState,
+  latestDispatch,
+  listDispatches,
+  recordHints,
+} from "./dispatches.ts";
+import type { Deps } from "./ports.ts";
+import {
+  type AgentRun,
+  appendAgentRun,
+  createRun,
+  findRun,
+  knowledgeFile,
+  readRecords,
+  runFile,
+} from "./run-store.ts";
+import { protocolView } from "./protocol.ts";
+import { claimRun, currentSession } from "./sessions.ts";
+import { refreshState } from "./state.ts";
+
+export async function startRun(
+  deps: Deps,
+  i: { repo: string; title: string; aLines: string[] },
+): Promise<{
+  run: string;
+  dir: string;
+  protocol: { next: string; checklist: string[] };
+  hints?: string[];
+}> {
+  const top = await gitToplevel(i.repo);
+  if (!top)
+    throw new CatherdError("E_IO_PATH", `${i.repo} is not inside a git repository`, {
+      fix: "pass the path of the repository to work in",
+    });
+  const run = createRun({
+    repo: top,
+    title: i.title,
+    aLines: i.aLines,
+    version: deps.version,
+    now: new Date(deps.now()),
+    startedBy: currentSession(deps),
+  });
+  await claimRun(deps, run);
+  // a failed state.md refresh never fails the start: the run exists and is usable, so a retry would orphan it
+  const { hints } = await refreshState(run);
+  // spec 1.1 §10: the milestone loop, so the orchestrator starts on the protocol
+  return { run: run.id, dir: run.dir, protocol: protocolView(run, []), ...(hints.length ? { hints } : {}) };
+}
+
+export function writeRunFile(i: { run: string; path: string; content: string }): {
+  path: string;
+  bytes: number;
+} {
+  const file = runFile(findRun(i.run), i.path, "write");
+  writeTextAtomic(file, i.content);
+  return { path: file, bytes: Buffer.byteLength(i.content) };
+}
+
+export function readRunFile(i: { run: string; path: string }): string {
+  const file = runFile(findRun(i.run), i.path, "read");
+  if (!existsSync(file))
+    throw new CatherdError("E_IO_PATH", `no file ${i.path} in the run folder`, {
+      fix: "pass a path relative to the run folder",
+    });
+  return readFileSync(file, "utf8");
+}
+
+/**
+ * `set_next`: state.md's new text, and, as every tool gives them, `hints`: `state.md not refreshed: <message>`
+ * when git fails, with `state` null (the note is kept in state.json either way).
+ */
+export async function setNext(i: {
+  run: string;
+  next: string;
+}): Promise<{ state: string | null; hints?: string[] }> {
+  const { text, hints } = await refreshState(findRun(i.run), { next: i.next });
+  return { state: text ?? null, ...(hints.length ? { hints } : {}) };
+}
+
+const CAP_LINES = 250;
+const CAP_CHARS = 20_000;
+
+function capReply(reply: string, path: string): string {
+  const lines = reply.split("\n");
+  const head = lines.length > CAP_LINES ? lines.slice(0, CAP_LINES).join("\n") : reply;
+  if (head === reply && reply.length <= CAP_CHARS) return reply;
+  return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
+}
+
+/**
+ * A role's latest dispatch: its record once finished, its capped reply and its hints. Spec §3.7: reading a
+ * finished record marks it read, with the collect lease (each record is marked read once, whoever reads it);
+ * an earlier record of the same name still unread (a usage limit its stand-in replaced) is marked read with it,
+ * and its hints come first.
+ */
+export async function result(
+  deps: Deps,
+  i: { run: string; name: string },
+): Promise<{
+  name: string;
+  state: DispatchState | null;
+  record: RunRecord | null;
+  reply: string;
+  replyPath: string | null;
+  hints: string[];
+}> {
+  const run = findRun(i.run);
+  assertId("role name", i.name);
+  const d = latestDispatch(run, i.name);
+  if (!d)
+    throw new CatherdError("E_RUN_NOT_FOUND", `${i.name} was never dispatched in this run`, {
+      fix: "status(run) lists the roles",
+    });
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const record = records.get(d.admit.dispatchId) ?? null;
+  const hints: string[] = [];
+  for (const x of listDispatches(run).filter((x) => x.admit.name === i.name)) {
+    const r = records.get(x.admit.dispatchId);
+    if (!r || !awaitsCollect(x.dir) || !(await tryCollect(x.dir))) continue;
+    // read at once: the lease ends as the record goes out
+    endCollect(x.dir);
+    if (x.admit.dispatchId !== d.admit.dispatchId) hints.push(...recordHints(run, x, r));
+  }
+  if (record) for (const h of recordHints(run, d, record)) if (!hints.includes(h)) hints.push(h);
+  const reply = dispatchPaths(d.dir).reply;
+  const text = existsSync(reply) ? readFileSync(reply, "utf8") : "";
+  return {
+    name: i.name,
+    state: record ? "finished" : dispatchState(d, deps.now()),
+    record,
+    reply: capReply(text, relative(run.dir, reply)),
+    replyPath: relative(run.dir, reply),
+    hints,
+  };
+}
+
+/** Spec §4.6: what a native Claude subagent used, as the Agent tool reported it; counted in the budget. */
+export function recordAgentRun(
+  deps: Deps,
+  i: {
+    run: string;
+    name: string;
+    role: Role;
+    rung: string;
+    totalTokens: number;
+    costUsd?: number;
+    durationMs?: number;
+    status?: AgentRun["status"];
+    lane?: string;
+  },
+): AgentRun {
+  const run = findRun(i.run);
+  assertId("role name", i.name);
+  if (i.lane !== undefined) assertId("lane", i.lane);
+  if (parseRung(i.rung).backend !== "claude")
+    throw new CatherdError("E_ADMIT_RUNG", `${i.rung} is not a native Claude rung`, {
+      fix: "record_agent_run is for Agent subagents; dispatch records every other run itself",
+    });
+  const row: AgentRun = {
+    at: new Date(deps.now()).toISOString(),
+    name: i.name,
+    role: i.role,
+    rung: i.rung,
+    agent: deps.profiles.agentFor(run.meta.repo, i.role, i.rung),
+    totalTokens: i.totalTokens,
+    costUsd: i.costUsd ?? null,
+    secs: i.durationMs === undefined ? null : Math.round(i.durationMs / 1000),
+    status: i.status ?? "ok",
+    lane: i.lane ?? null,
+  };
+  appendAgentRun(run, row);
+  return row;
+}
+
+/** What past runs of the repo learned; `repo` may be any path inside it. */
+export async function readKnowledge(repo: string): Promise<string> {
+  const top = await gitToplevel(repo);
+  if (!top)
+    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
+      fix: "pass the path of the repository",
+    });
+  const file = knowledgeFile(top);
+  return existsSync(file) ? readFileSync(file, "utf8") : "catherd: no knowledge recorded yet for this repo";
+}