catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/entry/mcp/server.ts

@@ -4,24 +4,70 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { sessionKey, type HostContext } from "../../domain/host.ts";
-import { errorMessage } from "../../domain/errors.ts";
+import { type CatherdError, errorMessage } from "../../domain/errors.ts";
+import {
+  isCoordinatorTool,
+  refusedForRole,
+  type RoleScope,
+  roleScopeError,
+} from "../../domain/role-scope.ts";
+import { takeBootLock } from "../../infra/boot-lock.ts";
 import { resolveHost } from "../../infra/host-context.ts";
 import { log } from "../../infra/log.ts";
 import { currentSession } from "../../services/sessions.ts";
 import { startNotifier } from "../../services/notifier.ts";
 import type { Deps } from "../../services/ports.ts";
-import { reconcileAll } from "../../services/reconcile.ts";
-import { backgroundSync } from "../../services/source-sync.ts";
+import { adoptOwned, reconcileAll } from "../../services/reconcile.ts";
+import { refreshIndex } from "../../services/catalog-service.ts";
 import { defaultDeps } from "../deps.ts";
-import { registerDispatchTools } from "./dispatch-tools.ts";
-import { registerLaneTools } from "./lane-tools.ts";
-import { registerProtocolTools } from "./protocol-tools.ts";
-import { sdkToolError, toolOf } from "./result.ts";
-import { registerRunTools } from "./run-tools.ts";
-import { registerSetupTools } from "./setup-tools.ts";
+import { handle, sdkToolError, toolOf } from "./result.ts";
+import { registerSessionTools } from "./session-tools.ts";
 
 type ObserveSession = (context: Deps) => (() => void) | undefined;
 
+/** Spec 1.5 plan 21: a coordinator tool's description says, first, that only the orchestrator calls it. */
+function orchestratorOnly(name: string, config: unknown): unknown {
+  const c = config as { description?: string };
+  return isCoordinatorTool(name) && c.description
+    ? { ...c, description: `Orchestrator only (a role process gets E_ROLE_SCOPE). ${c.description}` }
+    : config;
+}
+
+type RequestHandler = (
+  request: { params?: { name?: unknown; arguments?: unknown } },
+  extra: unknown,
+) => unknown;
+
+/** How often a session looks for the new reports of the 2.0 runs it owns. */
+const REPORT_POLL_MS = 3_000;
+
+/** Why a role process may not make this call on the full server (plan 21 review, finding 3), else null: a coordinator tool. */
+const roleRefusal = (name: string, args: unknown, role: RoleScope): CatherdError | null =>
+  refusedForRole(name, args, role) ? roleScopeError(name, role) : null;
+
+/**
+ * Spec 1.5 plan 21: in a role's process (`deps.role`) a coordinator tool call is refused with E_ROLE_SCOPE
+ * before anything else, its input check included, so a role learns at once that the tool is not its own. The
+ * SDK keeps its request handlers in a private map; test/entry/role-scope-mcp.test.ts fails if it moves.
+ */
+function refuseCoordinatorTools(server: McpServer, deps: Deps): void {
+  const handlers = (server.server as unknown as { _requestHandlers: Map<string, RequestHandler> })
+    ._requestHandlers;
+  const callTool = handlers.get("tools/call");
+  if (!callTool) return;
+  handlers.set("tools/call", async (request, extra) => {
+    const role = deps.role;
+    const name = String(request.params?.name ?? "");
+    const refusal = role ? roleRefusal(name, request.params?.arguments, role) : null;
+    if (!refusal) return callTool(request, extra);
+    const r = await handle(() => {
+      throw refusal;
+    });
+    log("warn", "tool", { tool: name, ok: false, code: "E_ROLE_SCOPE" });
+    return r;
+  });
+}
+
 type Handler = (...args: unknown[]) => CallToolResult | Promise<CallToolResult>;
 
 /** Spec §10.2: every tool call is logged with its duration and outcome (the error code), never its input. */
@@ -38,7 +84,7 @@ function logToolCalls(
     h: Handler,
   ) => unknown;
   (server as unknown as { registerTool: typeof register }).registerTool = (name, config, handler) =>
-    register(name, config, async (...args: unknown[]) => {
+    register(name, orchestratorOnly(name, config), async (...args: unknown[]) => {
       const started = Date.now();
       const epoch = generation();
       const extra = args.at(-1) as { _meta?: Record<string, unknown> } | undefined;
@@ -101,17 +147,20 @@ export function buildServer(deps: Deps = defaultDeps(), observe?: ObserveSession
     log("warn", "tool", { tool: toolOf(message), ok: false, code });
     return r;
   };
-  registerRunTools(server, scoped);
-  registerLaneTools(server, scoped);
-  registerDispatchTools(server, scoped);
-  registerSetupTools(server, scoped);
-  registerProtocolTools(server, scoped);
+  registerSessionTools(server, scoped);
+  refuseCoordinatorTools(server, deps);
   return server;
 }
 
 /** Connect immediately; initialized triggers recovery without delaying the handshake. */
 export async function startMcpServer(
-  o: { transport?: Transport; sync?: () => Promise<unknown>; deps?: Deps } = {},
+  o: {
+    transport?: Transport;
+    sync?: () => Promise<unknown>;
+    deps?: Deps;
+    /** plan 22: the boot lock (tests replace it); null while another live server holds it */
+    bootLock?: () => (() => void) | null;
+  } = {},
 ): Promise<void> {
   const deps = o.deps ?? defaultDeps();
   const observed = new Map<string, ReturnType<typeof startNotifier>>();
@@ -121,7 +170,7 @@ export async function startMcpServer(
     const key = sessionKey(target);
     let active = observed.get(key);
     if (!active) {
-      active = startNotifier(context);
+      active = startNotifier(context, { reportPollMs: REPORT_POLL_MS });
       observed.set(key, active);
     }
     const n = active;
@@ -134,6 +183,8 @@ export async function startMcpServer(
   let generation = 0;
   let notifier: ReturnType<typeof startNotifier> | undefined;
   let recovery: Deps | undefined;
+  // plan 22: taken at the first initialize, held until this server closes; null: another server leads the boot
+  let boot: (() => void) | null | undefined;
   const invalidate = () => {
     generation++;
     if (recovery) recovery.host = { host: "unknown", session: null, conflict: null };
@@ -143,10 +194,17 @@ export async function startMcpServer(
     observed.clear();
     closed();
   };
-  server.server.onclose = invalidate;
+  server.server.onclose = () => {
+    invalidate();
+    boot?.();
+    boot = undefined;
+  };
   server.server.oninitialized = () => {
     invalidate();
     initialized();
+    boot ??= (o.bootLock ?? takeBootLock)();
+    const lead = boot !== null;
+    if (!lead) log("info", "boot", { skipped: "another catherd server runs the boot sync and reconcile" });
     log("info", "session", {
       host: deps.host.host,
       conflict: deps.host.conflict,
@@ -158,18 +216,24 @@ export async function startMcpServer(
     const epoch = generation;
     recovery = { ...deps };
     const context = recovery;
-    notifier = startNotifier(context);
+    notifier = startNotifier(context, { reportPollMs: REPORT_POLL_MS });
     const active = notifier;
     const target = currentSession(context);
     if (target) observed.set(sessionKey(target), active);
     void Promise.resolve()
       .then(() => {
-        if (epoch === generation) return (o.sync ?? (() => backgroundSync()))();
+        if (lead && epoch === generation) return (o.sync ?? (() => refreshIndex({ auto: true })))();
       })
-      .catch((e: unknown) => log("debug", "sources", { error: errorMessage(e) }));
+      .catch((e: unknown) => log("debug", "catalog", { error: errorMessage(e) }));
     void (async () => {
       try {
         if (epoch !== generation) return;
+        // the leading server reconciles every run; this one still watches the live roles of the runs its own
+        // session owns (a coordinator's server restarted mid-run) and tells its session what it owns
+        if (!lead) {
+          adoptOwned(context);
+          return void active.scan();
+        }
         const r = await reconcileAll(context);
         if (epoch !== generation) return;
         const shown = r.warnings.length;

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

@@ -0,0 +1,149 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CatherdError } from "../../domain/errors.ts";
+import { BaseBranchSchema } from "../../domain/branch.ts";
+import { ID_PATTERN } from "../../domain/ids.ts";
+import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
+import { knownQueueCapability } from "../../infra/codex-queue.ts";
+import { gitToplevel } from "../../infra/git.ts";
+import { redact } from "../../infra/log.ts";
+import { registerSavedSecrets } from "../../services/jev-service.ts";
+import { pausesOver } from "../../services/pause.ts";
+import type { Deps } from "../../services/ports.ts";
+import { inspectionHost } from "../../services/run-debug.ts";
+import { answerUnit, cancelRun, profileTool, runResult, runStart } from "../../services/run-client.ts";
+import { listRunViews, type RunView, runView } from "../../services/run-read.ts";
+import { findRun, listRuns } from "../../services/run-store.ts";
+import { handle } from "./result.ts";
+
+const RUN = z.string().min(1);
+const PROFILE = z.string().regex(PROFILE_NAME).optional();
+
+/**
+ * The git toplevel of `repo` (default: this server's directory, null outside a repository). A `repo` given
+ * outside a repository is refused: 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;
+};
+
+/** The runs `status` shows without a name: every unfinished one, else the newest. */
+const unfinished = (v: RunView): boolean => (v.phase === null ? v.live.length > 0 : v.phase !== "ended");
+
+/** The six tools of a session: a run is started, watched, answered, cancelled and read; the profile is its own. */
+export function registerSessionTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "run_start",
+    {
+      description:
+        "Start a run that drives itself: catherd plans, dispatches, reviews, verifies and lands each milestone in a background daemon. Returns the run id and the ntfy url its questions go to.",
+      inputSchema: {
+        repo: z.string().min(1),
+        title: z.string().min(1),
+        a_lines: z.array(z.string().min(1)).min(1),
+        plan: z
+          .array(z.string().min(1))
+          .max(20)
+          .optional()
+          .describe(
+            "The reviewed plan files the run implements as written (paths, relative to repo or absolute). Without one, the architect writes a plan and the run waits for your approval.",
+          ),
+        base: BaseBranchSchema.optional().describe(
+          "A branch on origin (main, staging): each milestone then gets its own branch and worktree from origin/<base>, and independent milestones run side by side; without it the run works in the repo.",
+        ),
+      },
+    },
+    (a) =>
+      handle(() =>
+        runStart(deps, { repo: a.repo, title: a.title, aLines: a.a_lines, plan: a.plan, base: a.base }),
+      ),
+  );
+
+  server.registerTool(
+    "status",
+    {
+      description:
+        "Each run's phase, milestones, live roles, parked questions and quota holds, and whether its daemon is alive (a dead one is restarted). Without a run: every unfinished run, else the newest.",
+      inputSchema: { run: RUN.optional() },
+    },
+    (a) =>
+      handle(() => {
+        registerSavedSecrets();
+        const listing = a.run ? null : listRuns();
+        const views = a.run ? [runView(deps, a.run)] : listRunViews(deps);
+        const open = views.filter(unfinished);
+        const shown = a.run ? views : open.length ? open : views.slice(0, 1);
+        const queue =
+          deps.host.host === "codex" && !deps.host.conflict ? knownQueueCapability(process.env) : null;
+        return redact({
+          // a pause (the machine's, a workspace's) covers the runs shown, and comes first
+          paused: pausesOver(
+            (listing?.runs ?? [findRun(a.run as string)]).filter((r) => shown.some((v) => v.id === r.id)),
+          ),
+          version: deps.version,
+          host: inspectionHost(deps.host),
+          queue,
+          runs: shown,
+          warnings: (listing?.corrupt ?? []).map((c) => `skipped run ${c.id}: ${c.reason}`),
+        });
+      }),
+  );
+
+  server.registerTool(
+    "answer",
+    {
+      description: "Answer a parked unit (the run, a milestone or a lane): it runs again with your answer.",
+      inputSchema: { run: RUN, unit: z.string().min(1), answer: z.string().min(1) },
+    },
+    (a) => handle(() => answerUnit(deps, a)),
+  );
+
+  server.registerTool(
+    "cancel",
+    {
+      description: "Stop the run: every live role is cancelled and the run ends.",
+      inputSchema: { run: RUN },
+    },
+    (a) => handle(() => cancelRun(deps, a)),
+  );
+
+  server.registerTool(
+    "result",
+    {
+      description:
+        "The run's report (the MR body: digests, known issues, the judge's decisions), or with name one role's record.",
+      inputSchema: { run: RUN, name: z.string().regex(ID_PATTERN).optional() },
+    },
+    (a) => handle(() => runResult(deps, a)),
+  );
+
+  server.registerTool(
+    "profile",
+    {
+      description:
+        "Read, validate or change a profile, or set notify_url, where parked questions are sent. Without a name: the profile this repo runs on (repo, default this server's directory).",
+      inputSchema: {
+        action: z.enum(["get", "validate", "set"]),
+        name: PROFILE,
+        repo: z.string().min(1).optional(),
+        patch: ProfilePatchSchema.optional(),
+        notify_url: z.string().min(1).optional(),
+      },
+    },
+    (a) =>
+      handle(async () =>
+        profileTool(deps, {
+          action: a.action,
+          name: a.name,
+          repo: (await toplevel(a.repo)) ?? undefined,
+          patch: a.patch,
+          notifyUrl: a.notify_url,
+        }),
+      ),
+  );
+}

package/src/entry/panel/openapi.ts

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import {
+  CheckSchema,
+  IndexedPairSchema,
+  IssueSchema,
+  ProfileSavedSchema,
+  SetupViewSchema,
+} from "../../services/panel-setup.ts";
+import { ParkedViewSchema, RunViewSchema, TimelineEntrySchema } from "../../services/run-read.ts";
+
+// The panel's HTTP API, in one table: it writes web/openapi.json (the web client is generated from it) and the
+// server parses every request with the same schemas, so the document and the server cannot drift.
+
+export const ErrorBodySchema = z.object({
+  error: z.object({ message: z.string(), type: z.string(), code: z.string(), fix: z.string().optional() }),
+});
+
+const Page = <T extends z.ZodType>(item: T) => z.object({ items: z.array(item), total: z.number().int() });
+
+export const LoginBodySchema = z.object({ token: z.string().min(1).max(200) });
+export const RungsBodySchema = z.object({ rungs: z.array(z.string().min(1)).max(50) });
+export const AnswerBodySchema = z.object({
+  unit: z.string().min(1).max(100),
+  answer: z.string().trim().min(1).max(10000),
+});
+export const AnswerResultSchema = z.object({ unit: z.string(), parked: z.array(z.string()) });
+export const CancelResultSchema = z.object({ cancelling: z.literal(true), live: z.array(z.string()) });
+export const SessionSchema = z.object({ authenticated: z.literal(true) });
+export const VersionSchema = z.object({ catherd: z.string() });
+export const RunListSchema = Page(RunViewSchema);
+export const TimelinePageSchema = Page(TimelineEntrySchema);
+export const QuestionListSchema = Page(ParkedViewSchema);
+
+const paging = {
+  limit: z.coerce.number().int().min(1).max(200).default(25),
+  offset: z.coerce.number().int().min(0).default(0),
+};
+export const ListRunsQuerySchema = z.object({
+  q: z.string().max(200).optional(),
+  phase: z.enum(["planning", "approval", "running", "ended"]).optional(),
+  ...paging,
+});
+export const TimelineQuerySchema = z.object(paging);
+export const QuestionsQuerySchema = z.object({
+  run: z.string().max(200).optional(),
+  q: z.string().max(200).optional(),
+  ...paging,
+});
+
+export type OperationId =
+  | "login"
+  | "logout"
+  | "getSession"
+  | "getVersion"
+  | "getSetup"
+  | "setRoleRungs"
+  | "listRuns"
+  | "getRun"
+  | "getRunTimeline"
+  | "cancelRun"
+  | "answerUnit"
+  | "listQuestions";
+
+export interface Operation {
+  id: OperationId;
+  method: "GET" | "POST" | "PUT";
+  path: string;
+  public?: true;
+  query?: z.ZodObject;
+  body?: z.ZodType;
+  /** null: 204 */
+  response: z.ZodType | null;
+}
+
+export const OPERATIONS: readonly Operation[] = [
+  {
+    id: "login",
+    method: "POST",
+    path: "/api/auth/login",
+    public: true,
+    body: LoginBodySchema,
+    response: null,
+  },
+  { id: "logout", method: "POST", path: "/api/auth/logout", response: null },
+  { id: "getSession", method: "GET", path: "/api/auth/session", response: SessionSchema },
+  { id: "getVersion", method: "GET", path: "/api/system/version", response: VersionSchema },
+  { id: "getSetup", method: "GET", path: "/api/setup", response: SetupViewSchema },
+  {
+    id: "setRoleRungs",
+    method: "PUT",
+    path: "/api/setup/roles/{role}",
+    body: RungsBodySchema,
+    response: ProfileSavedSchema,
+  },
+  { id: "listRuns", method: "GET", path: "/api/runs", query: ListRunsQuerySchema, response: RunListSchema },
+  { id: "getRun", method: "GET", path: "/api/runs/{id}", response: RunViewSchema },
+  {
+    id: "getRunTimeline",
+    method: "GET",
+    path: "/api/runs/{id}/timeline",
+    query: TimelineQuerySchema,
+    response: TimelinePageSchema,
+  },
+  { id: "cancelRun", method: "POST", path: "/api/runs/{id}/cancel", response: CancelResultSchema },
+  {
+    id: "answerUnit",
+    method: "POST",
+    path: "/api/runs/{id}/answers",
+    body: AnswerBodySchema,
+    response: AnswerResultSchema,
+  },
+  {
+    id: "listQuestions",
+    method: "GET",
+    path: "/api/questions",
+    query: QuestionsQuerySchema,
+    response: QuestionListSchema,
+  },
+];
+
+const SCHEMAS: Record<string, z.ZodType> = {
+  RunView: RunViewSchema,
+  ParkedView: ParkedViewSchema,
+  TimelineEntry: TimelineEntrySchema,
+  SetupView: SetupViewSchema,
+  Check: CheckSchema,
+  Issue: IssueSchema,
+  IndexedPair: IndexedPairSchema,
+  ProfileSaved: ProfileSavedSchema,
+  ErrorBody: ErrorBodySchema,
+  RunList: RunListSchema,
+  TimelinePage: TimelinePageSchema,
+  QuestionList: QuestionListSchema,
+  Session: SessionSchema,
+  Version: VersionSchema,
+  LoginBody: LoginBodySchema,
+  RungsBody: RungsBodySchema,
+  AnswerBody: AnswerBodySchema,
+  AnswerResult: AnswerResultSchema,
+  CancelResult: CancelResultSchema,
+};
+
+const REF = "#/components/schemas/";
+const nameOf = (s: z.ZodType): string => {
+  const hit = Object.entries(SCHEMAS).find(([, v]) => v === s);
+  if (!hit) throw new Error("an operation names a schema that panelOpenApi does not register");
+  return hit[0];
+};
+const refOf = (s: z.ZodType) => ({ $ref: REF + nameOf(s) });
+const json = (s: z.ZodType) => ({ content: { "application/json": { schema: refOf(s) } } });
+
+const without = ({ $schema: _s, $id: _i, ...rest }: Record<string, unknown>) => rest;
+
+/** The OpenAPI 3.1 document of OPERATIONS; `info.version` is the API's, never the package's. */
+export function panelOpenApi(): Record<string, unknown> {
+  const reg = z.registry<{ id: string }>();
+  for (const [id, s] of Object.entries(SCHEMAS)) reg.add(s, { id });
+  const out = z.toJSONSchema(reg, { uri: (id) => REF + id, io: "output" }) as {
+    schemas: Record<string, Record<string, unknown>>;
+  };
+  const schemas = Object.fromEntries(Object.entries(out.schemas).map(([k, v]) => [k, without(v)]));
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const op of OPERATIONS) {
+    const pathParams = [...op.path.matchAll(/\{(\w+)\}/g)].map((m) => ({
+      name: m[1],
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    }));
+    const queryParams = Object.entries(op.query?.shape ?? {}).map(([name, field]) => ({
+      name,
+      in: "query",
+      required: !(field as z.ZodType).safeParse(undefined).success,
+      schema: without(z.toJSONSchema(field as z.ZodType, { io: "input" }) as Record<string, unknown>),
+    }));
+    (paths[op.path] ??= {})[op.method.toLowerCase()] = {
+      operationId: op.id,
+      parameters: [...pathParams, ...queryParams],
+      ...(op.body ? { requestBody: { required: true, ...json(op.body) } } : {}),
+      responses: {
+        [op.response ? "200" : "204"]: op.response
+          ? { description: "ok", ...json(op.response) }
+          : { description: "no content" },
+        default: { description: "error", ...json(ErrorBodySchema) },
+      },
+    };
+  }
+  return { openapi: "3.1.0", info: { title: "catherd panel", version: "1" }, paths, components: { schemas } };
+}