@coreplane/switchboard 1.205.0 → 1.206.1

package/dist/assets/Dockerfile

@@ -1,7 +1,10 @@
 # Switchboard — single-process Slack bot (Socket Mode, no inbound port needed).
 # git + gh are installed because the coding/review agents shell out to them.
 
-FROM node:24-slim AS build
+# Node at the exact tag every image in this repository shares (the execution
+# images copy theirs from the same one); its major is .nvmrc's, and
+# src/deploy/imageNode.test.ts holds both.
+FROM node:24.21.0-slim AS build
 WORKDIR /app
 # One lockfile covers every workspace. npm needs each workspace's manifest on
 # disk to resolve the tree, so the manifests are copied before the install;
@@ -28,7 +31,7 @@ RUN npm run build
 # Runtime dependencies alone: the bot's production dependencies, no dev tools,
 # no web toolchain — a clean install rather than a prune, so nothing hoisted
 # for the build survives into the image.
-FROM node:24-slim AS deps
+FROM node:24.21.0-slim AS deps
 WORKDIR /app
 COPY package.json package-lock.json ./
 COPY web/package.json ./web/
@@ -53,7 +56,7 @@ RUN npm ci --omit=dev --workspaces=false --include-workspace-root
 FROM docker.io/library/golang:1.27.1-bookworm AS meat
 RUN CGO_ENABLED=0 go install meat.dev/cmd/meat@f39f41dfe7b5b37a12b35fdfbaecc7e779855bd3
 
-FROM node:24-slim
+FROM node:24.21.0-slim
 RUN apt-get update \
   && apt-get install -y --no-install-recommends git curl ca-certificates \
   && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \

package/dist/assets/config/config.example.yaml

@@ -109,7 +109,7 @@ defaults:
 # bypassed via directives or config scopes. Names must be registered agents /
 # owner/name slugs, or the load fails.
 # restrict:
-#   agents: [coding]
+#   agents: [coding, conductor]   # conductor: fan-out closed unless granted (docs/reference/specs/agent-conductor.md)
 #   repos: [acme/api]
 #
 # `grants`: what ANY actor holds, in one shape, keyed by its platform-namespaced
@@ -157,6 +157,16 @@ defaults:
 #   http:cron:                          # the identity the shim fires schedules as
 #     actions: [friction:read, friction:write, repo:write]
 #     channels: all                     # the weekly pass analyzes the whole fleet
+#   http:coordinator:                   # the ship coordinator's bearer (its own
+#     actions: [coordinator:step, plan:merge]  # SWITCHBOARD_INGRESS_TOKENS entry, subject
+#                                       # "coordinator", rotated apart from cron):
+#                                       # coordinator:step is the one grant the
+#                                       # coordinator's steps need — the child a spawn
+#                                       # starts is authorized as the requesting user,
+#                                       # never as this identity; plan:merge lets the
+#                                       # plan runner merge a plan branch's pull request
+#                                       # once the review approved at its head and CI is
+#                                       # green — leave it out and every merge is a person's
 #   schedule:self-improvement:          # the weekly cron's own actor (src/core/schedules.ts
 #     actions: [friction:write]         # declares its grants; an entry here REPLACES them)
 #     channels: all                     # analyzes the whole fleet, not one channel
@@ -278,6 +288,19 @@ workspaceDir: ./workspaces
 # ship:
 #   maxRounds: 3      # review rounds per pipeline
 #   maxMinutes: 120   # the ship preset's wall-clock budget in minutes (the registry's default)
+#   coordinator: false # true hands every agent:ship request to the plan runner — the ShipCoordinator
+#                      # Workflow in the bot Worker — instead of the in-process round loop; needs the
+#                      # `coordinator` ingress entry, its grant, run history on the state Worker and
+#                      # PUBLIC_BASE_URL (see docs/how-to/turn-features-on-and-off.md)
+
+# The fan-out cap a spawning run meets (docs/reference/specs/agent-conductor.md).
+# `agent:conductor` starts child runs as the person who asked — each an
+# ordinary run in a thread of its own, under that person's permissions — and
+# at most `maxChildren` of one run's children are live at once: a spawn past
+# the cap is refused by name until a child finishes. A child cannot spawn.
+# Default shown; an integer >= 1.
+# spawn:
+#   maxChildren: 3
 
 # Spend reporting: GET /costs (Access-gated). Optional. See docs/reference/specs/costs.md.
 # costs:

package/dist/assets/deploy/cloudflare/coordinator.ts

@@ -0,0 +1,86 @@
+// The ship coordinator as a Workflow (docs/decisions/0029-durable-objects-store-workflows-schedule.md,
+// docs/decisions/0031-the-coordinator-runs-a-plan-not-a-pull-request.md;
+// docs/reference/specs/http-ingress.md item 9): the `ShipCoordinator`
+// entrypoint the Workflows binding names, declared here and re-exported by
+// worker.ts (the binding resolves `class_name` against the entry module, the
+// way the resident Worker's refresh cycle is split). `run()` is the plan
+// runner's driver (`src/core/coordinator/driver.ts`) over the platform's step
+// primitives and one bot client: every step is a `POST /admin/coordinator/<step>`
+// into the container, presented with the `coordinator` bearer from the token
+// map, and every fact and every child run is the bot's to produce. The instance
+// id is the plan's (`plan-<plan-id>`, or the ship record's for a task): the
+// bot wrote the instance and its unit rows before it created the instance, and
+// the driver's first step reads them back — nothing rides in the params.
+//
+// What a coordinator may hold is bounded here by type and in coordinator.test.ts
+// by a scan: the container binding (its loopback into the bot) and the token
+// map (the `coordinator` entry it presents to the bot's steps) — no model,
+// Slack or GitHub credential, and no fetch but the container binding's.
+import { getContainer } from "@cloudflare/containers";
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import { COORDINATOR_IDENTITY, COORDINATOR_STEP_PATH_PREFIX } from "../../src/core/coordinator/contract.ts";
+import {
+  readBotAnswer,
+  runPlan,
+  type CoordinatorBot,
+  type PlanRunSummary,
+  type StepRunner,
+} from "../../src/core/coordinator/driver.ts";
+import { parseIngressTokenMap, tokenForSubject } from "../../src/core/ingressTokens.ts";
+import { INSTANCE, INTERNAL } from "./shared";
+import type { Env } from "./worker";
+
+/** The env slice a coordinator instance may see. Everything else the shim
+ *  holds for the container is out of the coordinator's reach by type. */
+export type CoordinatorEnv = Pick<Env, "SWITCHBOARD" | "SWITCHBOARD_INGRESS_TOKENS">;
+
+/** What an instance is created with: nothing the driver reads — the instance
+ *  id names the plan, and the bot's rows are the input (the coordinator's
+ *  contract: ids only, never a task's text or a thread's contents). */
+export type ShipCoordinatorParams = Record<string, unknown>;
+
+/** The bot behind the container binding: the reply as the wire carried it.
+ *  The transport's failures throw for the step's retry; the door's own refusal
+ *  — a 401/403 the bot did not stamp, a bearer it does not admit — is final,
+ *  since no retry changes a token map. */
+function containerBot(env: CoordinatorEnv): CoordinatorBot {
+  return {
+    async step(route, body) {
+      const bearer = tokenForSubject(parseIngressTokenMap(env.SWITCHBOARD_INGRESS_TOKENS).tokens, COORDINATOR_IDENTITY);
+      if (bearer === undefined)
+        throw new NonRetryableError(
+          `the token map has no single \`${COORDINATOR_IDENTITY}\` entry — the coordinator cannot present itself to the bot`,
+        );
+      const res = await getContainer(env.SWITCHBOARD, INSTANCE).fetch(
+        new Request(`${INTERNAL}${COORDINATOR_STEP_PATH_PREFIX}${route}`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
+          body: JSON.stringify(body),
+        }),
+      );
+      const text = await res.text().catch(() => "");
+      if (res.status === 401 || res.status === 403) {
+        const read = readBotAnswer(res.status, text);
+        if (!read.ok) throw new NonRetryableError(`the bot refused the coordinator bearer on ${route}: ${read.reason}`);
+      }
+      return { status: res.status, text };
+    },
+  };
+}
+
+/** The platform's step as the driver types it. Every stored step output is a
+ *  bot answer — a JSON object — so the platform's serializable bound holds. */
+function workflowSteps(step: WorkflowStep): StepRunner {
+  return {
+    do: (name, config, callback) => step.do(name, config, callback),
+    sleep: (name, ms) => step.sleep(name, ms),
+    waitForEvent: (name, options) => step.waitForEvent(name, options),
+  };
+}
+
+export class ShipCoordinator extends WorkflowEntrypoint<CoordinatorEnv, ShipCoordinatorParams> {
+  async run(event: Readonly<WorkflowEvent<ShipCoordinatorParams>>, step: WorkflowStep): Promise<PlanRunSummary> {
+    return runPlan(workflowSteps(step), containerBot(this.env), event.instanceId);
+  }
+}

package/dist/assets/deploy/cloudflare/shared.ts

@@ -0,0 +1,9 @@
+// What the shim's entry and its Workflow both address: the one container
+// instance the shim runs (a singleton Durable Object) and the internal origin
+// every request into it is written against — the container ignores the host,
+// the origin only has to be a URL. Declared apart from worker.ts so
+// coordinator.ts reaches them without importing the entry (the binding
+// resolves the Workflow's class against worker.ts, which re-exports it: a value
+// import the other way would be a cycle).
+export const INSTANCE = "singleton";
+export const INTERNAL = "https://switchboard-keepalive.internal";

package/dist/assets/deploy/cloudflare/worker.ts

@@ -12,6 +12,18 @@
 import { Container, getContainer } from "@cloudflare/containers";
 import { parseHealthz } from "../../src/deploy/liveGate.ts";
 import {
+  COORDINATOR_AUTHORIZE_PATH,
+  COORDINATOR_INSTANCES_PATH,
+  createInstanceResponse,
+  instanceStatusResponse,
+  isInstanceNotFound,
+  parseInstanceStatusPath,
+  parseCreateInstanceRequest,
+  parseSubjectAuthorization,
+  type CreateInstanceOutcome,
+} from "../../src/core/coordinator/instancesRoute.ts";
+import {
+  authenticateIngressBearer,
   authenticateRestart,
   decideRestart,
   parseRestartAuthorization,
@@ -34,6 +46,13 @@ import {
 import { systemClock } from "../../src/core/trace/clock.ts";
 import { createTracer } from "../../src/core/trace/tracer.ts";
 import { shimRoute, stripTraceContext, withTraceContext, workerLogSink } from "../../src/core/trace/workerTrace.ts";
+import type { ShipCoordinatorParams } from "./coordinator";
+import { INSTANCE, INTERNAL } from "./shared";
+
+/** The ship coordinator's Workflow entrypoint is declared in coordinator.ts;
+ *  the Workflows binding resolves its `class_name` against this module
+ *  (wrangler.template.jsonc), so the entry exports it under that name. */
+export { ShipCoordinator } from "./coordinator";
 
 // The Worker's own spans (docs/reference/specs/tracing.md item 22): one `bot-shim.fetch`
 // root per routed request and one `cron.<schedule>` root per fired schedule,
@@ -42,8 +61,11 @@ import { shimRoute, stripTraceContext, withTraceContext, workerLogSink } from ".
 const tracer = createTracer({ clock: systemClock });
 const traceSinks = [workerLogSink((line) => console.log(line))];
 
-interface Env {
+export interface Env {
   SWITCHBOARD: DurableObjectNamespace<SwitchboardServer>;
+  /** The ship coordinator (coordinator.ts): `POST /admin/coordinator/instances`
+   *  creates its instances; the state Worker's finish sends them `run-finished-<runId>`. */
+  SHIP_COORDINATOR: Workflow<ShipCoordinatorParams>;
   // secrets (wrangler secret put ...)
   SLACK_BOT_TOKEN: string;
   SLACK_APP_TOKEN: string;
@@ -117,9 +139,6 @@ function containerEnv(env: Env): Record<string, string> {
   return vars;
 }
 
-const INSTANCE = "singleton";
-const INTERNAL = "https://switchboard-keepalive.internal";
-
 export class SwitchboardServer extends Container<Env> {
   defaultPort = 8080; // the bot's health endpoint (PORT=8080 in the image)
   // Never let this scale to zero: the Slack websocket must stay connected and
@@ -260,6 +279,116 @@ async function handleAdminRestart(request: Request, env: Env): Promise<Response>
   return json(res.status, res.body);
 }
 
+/** `POST /admin/coordinator/instances` — the one route that creates a ship
+ *  coordinator instance (docs/reference/specs/http-ingress.md item 9), the
+ *  Workflow being this Worker's. WHO: the bearer must be an entry of
+ *  SWITCHBOARD_INGRESS_TOKENS (401/503 here, an unknown bearer never touches
+ *  the container). WHETHER: the bot's config — the shim relays the bearer to
+ *  `POST /admin/coordinator/authorize`, where the policy table decides
+ *  `coordinator:step`, and creates only on a 200. Body `{ id, params? }`. */
+async function handleCoordinatorInstances(request: Request, env: Env): Promise<Response> {
+  const json = (status: number, body: Record<string, unknown>) =>
+    new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+  if (request.method !== "POST")
+    return json(405, { ok: false, error: `method not allowed: POST ${COORDINATOR_INSTANCES_PATH}` });
+  const authorization = request.headers.get("authorization") ?? undefined;
+  const authn = authenticateIngressBearer(authorization, env.SWITCHBOARD_INGRESS_TOKENS, "coordinator");
+  if (!authn.ok) {
+    console.warn(`[coordinator] instances ${authn.status} — ${authn.reason}`);
+    return json(authn.status, { ok: false, error: authn.reason });
+  }
+  const parsed = parseCreateInstanceRequest(await request.text().catch(() => ""));
+  if (!parsed.ok) return json(400, { ok: false, error: parsed.reason });
+  let answer: Response;
+  try {
+    answer = await getContainer(env.SWITCHBOARD, INSTANCE).fetch(
+      new Request(`${INTERNAL}${COORDINATOR_AUTHORIZE_PATH}`, {
+        method: "POST",
+        headers: { authorization: authorization ?? "" },
+      }),
+    );
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.error(`[coordinator] instances ${parsed.id}: the bot could not be asked: ${reason}`);
+    return json(503, { ok: false, error: `coordinator disabled: the bot could not be asked (${reason})` });
+  }
+  const auth = parseSubjectAuthorization(answer.status, await answer.text().catch(() => ""));
+  if (!auth.ok) {
+    console.warn(`[coordinator] instances ${auth.status} — ${auth.reason}`);
+    return json(auth.status, { ok: false, error: auth.reason });
+  }
+  let outcome: CreateInstanceOutcome;
+  try {
+    await env.SHIP_COORDINATOR.create({ id: parsed.id, params: parsed.params });
+    outcome = { kind: "created", id: parsed.id };
+  } catch (err) {
+    // The engine refuses a taken id; read the existing instance back to say
+    // so. Anything else — the engine unreachable, a malformed param — is a
+    // failure by reason.
+    const reason = err instanceof Error ? err.message : String(err);
+    try {
+      const existing = await (await env.SHIP_COORDINATOR.get(parsed.id)).status();
+      outcome = { kind: "duplicate", id: parsed.id, status: existing.status };
+    } catch {
+      outcome = { kind: "failed", id: parsed.id, reason };
+    }
+  }
+  console.log(`[coordinator] ${auth.subject} → instance ${parsed.id}: ${outcome.kind}`);
+  const res = createInstanceResponse(outcome);
+  return json(res.status, res.body);
+}
+
+/** `GET /admin/coordinator/instances/<id>` — the platform's status of one
+ *  instance (docs/reference/specs/http-ingress.md item 9), read by the bot
+ *  before a plan is re-issued: still running, ended, or never created (the
+ *  leftover of a create that failed). The same door as the create: the bearer
+ *  in the map, the bot's `authorize` answer. The engine's own `instance.not_found`
+ *  is 404; any other failure is 502 by reason — never read as absence, because a
+ *  wrong absence would let a re-issue write over a live runner's records. */
+async function handleCoordinatorInstanceStatus(request: Request, env: Env, id: string): Promise<Response> {
+  const json = (status: number, body: Record<string, unknown>) =>
+    new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+  if (request.method !== "GET")
+    return json(405, {
+      ok: false,
+      error: `method not allowed: ${request.method} — ${COORDINATOR_INSTANCES_PATH}/<id> answers GET only`,
+    });
+  const authorization = request.headers.get("authorization") ?? undefined;
+  const authn = authenticateIngressBearer(authorization, env.SWITCHBOARD_INGRESS_TOKENS, "coordinator");
+  if (!authn.ok) {
+    console.warn(`[coordinator] instance status ${authn.status} — ${authn.reason}`);
+    return json(authn.status, { ok: false, error: authn.reason });
+  }
+  let answer: Response;
+  try {
+    answer = await getContainer(env.SWITCHBOARD, INSTANCE).fetch(
+      new Request(`${INTERNAL}${COORDINATOR_AUTHORIZE_PATH}`, {
+        method: "POST",
+        headers: { authorization: authorization ?? "" },
+      }),
+    );
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return json(503, { ok: false, error: `coordinator disabled: the bot could not be asked (${reason})` });
+  }
+  const auth = parseSubjectAuthorization(answer.status, await answer.text().catch(() => ""));
+  if (!auth.ok) return json(auth.status, { ok: false, error: auth.reason });
+  let outcome: Parameters<typeof instanceStatusResponse>[0];
+  try {
+    const status = await (await env.SHIP_COORDINATOR.get(id)).status();
+    outcome = { kind: "status", id, status: status.status };
+  } catch (err) {
+    // Absence is only the engine's own word for it — the `instance.not_found`
+    // code the Workflows binding throws for an id it has never seen. Any other
+    // failure, whatever its text says, is a failure by reason: a wrong absence
+    // would let a re-issue write over a live runner's records.
+    const reason = err instanceof Error ? err.message : String(err);
+    outcome = isInstanceNotFound(reason) ? { kind: "absent", id } : { kind: "failed", id, reason };
+  }
+  const res = instanceStatusResponse(outcome);
+  return json(res.status, res.body);
+}
+
 /** Record a firing on the state Worker's ScheduleDO (the /runs Scheduled panel
  *  reads it). Best-effort: a failure here is a log line — the run itself (if
  *  any) already happened and is its own record. */
@@ -283,11 +412,18 @@ export default {
     const root = tracer.start("bot-shim.fetch", { sinks: traceSinks, attrs: { route } });
     try {
       const forwarded = withTraceContext(inbound, root);
-      // The one route the Worker answers itself; everything else is the container's.
+      // The routes the Worker answers itself — the restart, the coordinator's
+      // instance creation and an instance's status, all over bindings only this
+      // Worker holds; everything else is the container's.
+      const statusId = parseInstanceStatusPath(pathname);
       const res =
         pathname === "/admin/restart"
           ? await handleAdminRestart(forwarded, env)
-          : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
+          : pathname === COORDINATOR_INSTANCES_PATH
+            ? await handleCoordinatorInstances(forwarded, env)
+            : statusId !== undefined
+              ? await handleCoordinatorInstanceStatus(forwarded, env, statusId)
+              : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
       root.end(res.status >= 500 ? "error" : "ok", { httpStatus: res.status });
       return res;
     } catch (err) {

package/dist/assets/deploy/cloudflare/wrangler.template.jsonc

@@ -55,6 +55,15 @@
     "bindings": [{ "name": "SWITCHBOARD", "class_name": "SwitchboardServer" }]
   },
   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SwitchboardServer"] }],
+  // The ship coordinator as a Workflow (coordinator.ts, re-exported by
+  // worker.ts; docs/reference/specs/http-ingress.md item 9): `POST
+  // /admin/coordinator/instances` creates its instances and the state Worker's
+  // finish sends them `run finished:<runId>` through its own cross-script
+  // binding to this class (deploy/cloudflare-memory/wrangler.template.jsonc).
+  // Same-script here, so this Worker deploys on its own.
+  "workflows": [
+    { "name": "{{script}}-ship-coordinator", "binding": "SHIP_COORDINATOR", "class_name": "ShipCoordinator" }
+  ],
   // Every cron here IS a schedule in src/core/schedules.ts (the registry; a unit
   // test fails when the two sets differ) and worker.ts looks each firing up there.
   // "* * * * *": keep-alive (/healthz) — also what RESTARTS the container after a