catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/entry/mcp/run-tools.ts

@@ -1,164 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { ID_PATTERN } from "../../domain/ids.ts";
-import { ROLES } from "../../domain/roles.ts";
-import { knownQueueCapability } from "../../infra/codex-queue.ts";
-import { redact } from "../../infra/log.ts";
-import { registerSavedSecrets } from "../../services/jev-service.ts";
-import type { Deps } from "../../services/ports.ts";
-import {
-  readKnowledge,
-  readRunFile,
-  recordAgentRun,
-  result,
-  setNext,
-  startRun,
-  writeRunFile,
-} from "../../services/run-service.ts";
-import { repin } from "../../services/run-pin.ts";
-import { runsSummary, status } from "../../services/summary.ts";
-import { handle } from "./result.ts";
-
-export function registerRunTools(server: McpServer, deps: Deps): void {
-  server.registerTool(
-    "run_start",
-    {
-      description:
-        "Start a catherd run for a git repository: creates its run folder (outside the repo) and state.md. Returns the run id, the folder, protocol (the next step of the milestone loop and its six-line checklist), and hints when state.md could not be written yet. from: the run this one takes over (a planning run handed to the execution run in a worktree): it is closed with a pointer here, and status hides it.",
-      inputSchema: {
-        repo: z.string().min(1),
-        title: z.string().min(1),
-        a_lines: z.array(z.string().min(1)).min(1),
-        from: z.string().regex(ID_PATTERN).optional(),
-      },
-    },
-    (a) => handle(() => startRun(deps, { repo: a.repo, title: a.title, aLines: a.a_lines, from: a.from })),
-  );
-
-  server.registerTool(
-    "run_pin",
-    {
-      description:
-        "Re-pin a run to what its repo runs on now: the profile, each role's access and each backend's isolation. run_start pins them; while they differ, dispatch keeps the pinned values and status and state.md say what changed. Only on the owner's word. Returns the new pin and what it changed. Orchestrator only.",
-      inputSchema: { run: z.string().regex(ID_PATTERN) },
-    },
-    (a) => handle(() => repin(deps, a)),
-  );
-
-  server.registerTool(
-    "write_run_file",
-    {
-      description:
-        "Write a file in the run folder: plan.md, lanes/Mx.Ly.md, a dossier or notes. The path is relative to the run folder; catherd's own files are refused.",
-      inputSchema: { run: z.string(), path: z.string().min(1), content: z.string() },
-    },
-    (a) => handle(() => writeRunFile(a)),
-  );
-
-  server.registerTool(
-    "read_run_file",
-    {
-      description: "Read a file in the run folder, by a path relative to it.",
-      inputSchema: { run: z.string(), path: z.string().min(1) },
-    },
-    (a) => handle(() => readRunFile(a)),
-  );
-
-  server.registerTool(
-    "status",
-    {
-      description:
-        "catherd's version, and one screen per run: the state.md tail, live roles, unread results waiting for the orchestrator, totals, reported Claude subagents, Jev fallbacks, per backend how many dispatches ran native and isolated, budget and landed milestones. Without a run: every run with live roles or unread completions waiting for its orchestrator, else the newest. Reads only.",
-      inputSchema: { run: z.string().optional() },
-    },
-    (a) =>
-      handle(async () => {
-        registerSavedSecrets();
-        const queue =
-          deps.host.host === "codex" && !deps.host.conflict ? knownQueueCapability(process.env) : null;
-        return redact(status(deps, a.run, queue));
-      }),
-  );
-
-  server.registerTool(
-    "result",
-    {
-      description:
-        "A role's latest dispatch: its state, its record once finished, its capped reply, and hints (climb, violation, failed, limit and failover lines). Reading a finished record marks it read: catherd's messages announce records, and this is how you read one.",
-      inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
-    },
-    (a) => handle(() => result(deps, a)),
-  );
-
-  server.registerTool(
-    "set_next",
-    {
-      description:
-        "Record the run's next step, the last line of state.md: when pausing, or when the plan changes. dispatch, climb and land write state.md themselves. Returns { state } (state.md's text), and hints ['state.md not refreshed: …'] with state null when git fails (the step is still recorded).",
-      inputSchema: { run: z.string(), next: z.string().min(1) },
-    },
-    (a) => handle(() => setNext(a)),
-  );
-
-  server.registerTool(
-    "record_agent_run",
-    {
-      description:
-        'After every native Claude subagent (Agent tool) of a run, record what the Agent result reported: total_tokens and duration_ms. The budget counts it. Pass lane (e.g. M1.L1) when the subagent worked a lane, so its time counts toward that lane\'s kind in the catalog timings. status says how the subagent\'s work ended: for a verifier it is the verdict, so pass status: "failed" when its verdict is FAIL; only a PASS is recorded ok. For a verifier, pass verdict: the first line of its reply; a VERDICT: BLOCKED: environment — <probe> (status "failed") is then a blocker to surface to the owner, not a fix round. Pass reply_status, the STATUS word its reply ends with: a reviewer that stopped partial is not the milestone review.',
-      inputSchema: {
-        run: z.string(),
-        name: z.string().regex(ID_PATTERN),
-        role: z.enum(ROLES),
-        rung: z.string().min(3),
-        total_tokens: z.number().int().nonnegative(),
-        duration_ms: z.number().nonnegative().optional(),
-        cost_usd: z.number().nonnegative().optional(),
-        status: z.enum(["ok", "failed", "cancelled"]).default("ok"),
-        lane: z.string().regex(ID_PATTERN).optional(),
-        verdict: z.string().min(1).optional(),
-        reply_status: z.enum(["complete", "partial", "blocked", "refused", "flaky"]).optional(),
-      },
-    },
-    (a) =>
-      handle(() =>
-        recordAgentRun(deps, {
-          lane: a.lane,
-          run: a.run,
-          name: a.name,
-          role: a.role,
-          rung: a.rung,
-          totalTokens: a.total_tokens,
-          durationMs: a.duration_ms,
-          costUsd: a.cost_usd,
-          status: a.status,
-          verdict: a.verdict,
-          replyStatus: a.reply_status,
-        }),
-      ),
-  );
-
-  server.registerTool(
-    "read_knowledge",
-    {
-      description:
-        "What past runs of this repo learned, one line per landed milestone that said something. Read it before an architect plans a new run.",
-      inputSchema: { repo: z.string().min(1) },
-    },
-    (a) => handle(() => readKnowledge(a.repo)),
-  );
-
-  server.registerTool(
-    "runs_summary",
-    {
-      description:
-        "Per role and rung over past runs: runs, ok, refusals, climbs from that rung, seconds and tokens; reported Claude subagent runs; and what the user's harness customizations cost per run (median first-turn input, native against isolated; with a run, over that run's repo; null below 3 runs a side or when native is not dearer; none for Codex, which reports no per-request input). Reads only.",
-      inputSchema: {
-        run: z.string().optional(),
-        repo: z.string().optional(),
-        role: z.enum(ROLES).optional(),
-        since_days: z.number().positive().optional(),
-      },
-    },
-    (a) => handle(() => runsSummary({ run: a.run, repo: a.repo, role: a.role, sinceDays: a.since_days })),
-  );
-}

package/src/entry/mcp/setup-tools.ts

@@ -1,109 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { CatherdError } from "../../domain/errors.ts";
-import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
-import { ROLES } from "../../domain/roles.ts";
-import { gitToplevel } from "../../infra/git.ts";
-import type { Deps } from "../../services/ports.ts";
-import { syncSources } from "../../services/source-sync.ts";
-import { handle } from "./result.ts";
-
-const PROFILE = z.string().regex(PROFILE_NAME).optional();
-const REPO = z.string().min(1).optional();
-
-/**
- * The git toplevel of `repo` (default: this server's directory, null outside a repository). A `repo`
- * given outside a repository is refused, as run_start does: never the global profile in its stead.
- */
-const toplevel = async (repo: string | undefined): Promise<string | null> => {
-  const top = await gitToplevel(repo ?? process.cwd());
-  if (top === null && repo !== undefined)
-    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
-      fix: "pass the path of the repository, or leave repo out for the active profile",
-    });
-  return top;
-};
-
-export function registerSetupTools(server: McpServer, deps: Deps): void {
-  server.registerTool(
-    "catalog_query",
-    {
-      description:
-        "Models catherd can place, with capabilities, the roles they can fill, their scored rungs (backend:model#effort), any 'treat like', their cost under the billing of `repo`'s profile, and whether this account's last listing offers them (`listed: false`: it does not); `enabled: false` rungs are unscored. Each score has its confidence, source and date (`from` names the rung a lent value belongs to); each model its price and speed facts, each rung catherd's own run evidence. Scored models first. opencode's models are as listed in `repo` (default: this server's directory), as route sees them there.",
-      inputSchema: {
-        repo: z.string().min(1).optional(),
-        role: z.enum(ROLES).optional(),
-        backend: z.string().optional(),
-        text: z.string().optional(),
-        scored_only: z.boolean().default(false),
-        limit: z.number().int().min(1).max(500).default(50),
-      },
-    },
-    (a) =>
-      handle(async () => {
-        // outside a git repository: the global listings and the active profile
-        const repo = (await gitToplevel(a.repo ?? process.cwd())) ?? undefined;
-        return deps.routing.catalog(
-          { role: a.role, backend: a.backend, text: a.text, scoredOnly: a.scored_only, limit: a.limit, repo },
-          deps.profiles.forRepo(repo ?? null).billing,
-        );
-      }),
-  );
-
-  server.registerTool(
-    "catalog_sync",
-    {
-      description:
-        "Fetch the public model facts and scores now (models.dev, OpenRouter, LiteLLM, Arena, Vectara, Epoch AI, and Artificial Analysis with the user's key): each source at most every 12 hours unless `force`. Returns the rungs newly scored, the user's treat-likes no longer needed (their rung now has values of its own), the sources that failed (each keeps its last good answer) and each source's state. route and catalog_query read the result at once.",
-      inputSchema: { force: z.boolean().default(false) },
-    },
-    (a) =>
-      handle(async () => {
-        // (1.2 minor) a sync already running (the boot sync) answers busy at once, never a 120 s wait
-        const r = await (deps.sync ?? ((o) => syncSources(o)))({ force: a.force, wait: false });
-        return {
-          newlyScored: r.newlyScored,
-          standInsNoLongerNeeded: r.noLongerNeeded,
-          failed: r.failed,
-          sources: r.sources,
-          warnings: r.warnings,
-          ...(r.busy ? { busy: "another sync was running; call catalog_sync again" } : {}),
-        };
-      }),
-  );
-
-  server.registerTool(
-    "profile_get",
-    {
-      description:
-        "A profile (without a name: the profile this repo runs on, i.e. the one bound to `repo`, default this server's directory, else the active one) as the run engine reads it, with every default filled in: per role its access mode, rungs and default rung, and whether its backend enforces the access (enforcement); billing, jev, harness isolation, failover, budget, timeouts, preflight, lock and notify. Also `active` (the global active profile), `here` (the profile this repo runs on) and every name.",
-      inputSchema: { name: PROFILE, repo: REPO, raw: z.boolean().optional() },
-    },
-    (a) =>
-      handle(async () =>
-        a.raw && deps.profiles.raw
-          ? deps.profiles.raw(a.name, await toplevel(a.repo))
-          : deps.profiles.get(a.name, await toplevel(a.repo)),
-      ),
-  );
-
-  server.registerTool(
-    "profile_validate",
-    {
-      description:
-        "Check a profile (without a name: the profile this repo runs on, as in profile_get). errors block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a 'treat like', a failover stand-in unscored or on the same quota, a backend catherd cannot run. warnings do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs, a quota none of whose rungs ever starts a lane, and every kind and difficulty no worker rung clears. Each has a path, a message and often a fix.",
-      inputSchema: { name: PROFILE, repo: REPO },
-    },
-    (a) => handle(async () => deps.profiles.validate(a.name, await toplevel(a.repo))),
-  );
-
-  server.registerTool(
-    "profile_set",
-    {
-      description:
-        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung, timeouts: a role's own idleMin and wallMin over the profile's), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid, unless the patch repairs an invalid profile: it fixes at least one of its errors and adds none, and then it saves with `errors` listing those still open. A save rewrites the agent files and relinks them. Returns saved, the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
-      inputSchema: { name: PROFILE, repo: REPO, patch: ProfilePatchSchema },
-    },
-    (a) => handle(async () => deps.profiles.set(a.name, a.patch, await toplevel(a.repo))),
-  );
-}

package/src/entry/mcp/workspace-tools.ts

@@ -1,142 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import {
-  BaseRefSchema,
-  RELEASES,
-  WORKSPACE_LIMIT,
-  WorkspaceBudgetSchema,
-  WorkspaceIdSchema,
-} from "../../domain/workspace.ts";
-import { pauseWorkspace, resumeWorkspace } from "../../services/pause.ts";
-import type { Deps } from "../../services/ports.ts";
-import { setWorkspaceBudget, workspaceContract } from "../../services/workspace-admission.ts";
-import {
-  inspectWorkspace,
-  startWorkspace,
-  startWorkspaceChild,
-  workspaceStatus,
-} from "../../services/workspace-service.ts";
-import { handle } from "./result.ts";
-
-const id = WorkspaceIdSchema;
-const repos = z
-  .record(id, z.string().min(1))
-  .refine((r) => Object.keys(r).length <= WORKSPACE_LIMIT)
-  .optional();
-const aLines = z.array(z.string().min(1)).min(1).max(100);
-
-export function registerWorkspaceTools(server: McpServer, deps: Deps): void {
-  server.registerTool(
-    "workspace_inspect",
-    {
-      description:
-        "Resolve explicit workspace members from catherd.workspace.json or a supplied repo map. The root may be a plain directory. Reads only; never scans unrelated repositories.",
-      inputSchema: { root: z.string().min(1), repos },
-    },
-    (a) => handle(() => inspectWorkspace(a.root, a.repos)),
-  );
-  server.registerTool(
-    "workspace_start",
-    {
-      description:
-        "Snapshot a workspace's selected repositories, step dependency graph and optional shared budget (no cap unless given; raise it later with workspace_budget). A step releases its dependents when its milestone lands, or with release: 'merge' and base (e.g. origin/main) once its landed commit is an ancestor of that ref, checked when a dependent asks. Returns workspace.id and dir. Child single-repo runs are created later with workspace_child_start; no commits or pushes are performed.",
-      inputSchema: {
-        root: z.string().min(1),
-        title: z.string().min(1),
-        a_lines: aLines,
-        repos,
-        steps: z
-          .array(
-            // #43 finding 6: an unknown key (dependsOn for depends_on) is refused, never dropped
-            z.strictObject({
-              id,
-              repo: id,
-              title: z.string().min(1),
-              a_lines: aLines,
-              depends_on: z.array(id).max(WORKSPACE_LIMIT).optional(),
-              milestone: id.optional(),
-              release: z.enum(RELEASES).optional(),
-              base: BaseRefSchema.optional(),
-            }),
-          )
-          .min(1)
-          .max(WORKSPACE_LIMIT),
-        budget: WorkspaceBudgetSchema.optional(),
-      },
-    },
-    (a) =>
-      handle(() =>
-        startWorkspace(deps, {
-          root: a.root,
-          title: a.title,
-          aLines: a.a_lines,
-          repos: a.repos,
-          budget: a.budget,
-          steps: a.steps.map((s) => ({
-            id: s.id,
-            repo: s.repo,
-            title: s.title,
-            aLines: s.a_lines,
-            dependsOn: s.depends_on,
-            milestone: s.milestone,
-            release: s.release,
-            base: s.base,
-          })),
-        }),
-      ),
-  );
-  server.registerTool(
-    "workspace_contract",
-    {
-      description:
-        "Read or write the workspace's shared contract before any child run exists. Once a child is created the contract is frozen and copied into each child as workspace-contract.md.",
-      inputSchema: { workspace: z.string().min(1), content: z.string().optional() },
-    },
-    (a) => handle(() => workspaceContract(a)),
-  );
-  server.registerTool(
-    "workspace_child_start",
-    {
-      description:
-        "Create or return a step's single-repo run once its dependencies have landed their declared milestone, every dispatch of theirs is collected, and each 'merge' release's commit is in its base ref (fetch first; nothing is polled). Returns run, dir and the frozen contract path. Use the existing route, dispatch, verification and land tools on this child run.",
-      inputSchema: { workspace: z.string().min(1), step: id },
-    },
-    (a) => handle(() => startWorkspaceChild(deps, a)),
-  );
-  server.registerTool(
-    "workspace_pause",
-    {
-      description:
-        "Pause every child of a workspace on one blocker (a VPN, Docker down): admission refuses each dispatch and child start with E_ADMIT_PAUSED and the reason until workspace_resume. Running roles finish. status shows the pause first. Push the reason to the owner once.",
-      inputSchema: { workspace: z.string().min(1), reason: z.string().min(1) },
-    },
-    (a) => handle(() => pauseWorkspace(deps.now(), a)),
-  );
-  server.registerTool(
-    "workspace_resume",
-    {
-      description: "Lift a workspace's pause. Returns the pause it lifted, or null when none was in force.",
-      inputSchema: { workspace: z.string().min(1) },
-    },
-    (a) => handle(() => resumeWorkspace(deps.now(), a)),
-  );
-  const cap = z.number().finite().nonnegative().nullable().optional();
-  server.registerTool(
-    "workspace_budget",
-    {
-      description:
-        "Set or raise a workspace's shared budget: each of minutes, tokens and usd given as a number replaces that cap, null removes it, and one left out stays. A workspace has no cap unless one is set; its minutes count from its first child. Returns the budget, the spend and its status.",
-      inputSchema: { workspace: z.string().min(1), minutes: cap, tokens: cap, usd: cap },
-    },
-    (a) => handle(() => setWorkspaceBudget(deps, a)),
-  );
-  server.registerTool(
-    "workspace_status",
-    {
-      description:
-        "Read a workspace's step readiness, child run ids, landed milestones, aggregate spending and shared budget. Reads only; never starts children automatically.",
-      inputSchema: { workspace: z.string().min(1) },
-    },
-    (a) => handle(() => workspaceStatus(deps, a.workspace)),
-  );
-}