@coreplane/switchboard 0.0.0 → 1.18.0

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

@@ -0,0 +1,410 @@
+// Sandbox proxy Worker: fronts per-thread Cloudflare Sandboxes with a minimal
+// authenticated HTTP API the bot's CloudflareSandboxExecutor calls.
+//
+//   POST /exec   { command, timeoutMs?, env? } -> { stdout, stderr, exitCode, durationMs }
+//   POST /read   { path, env? }             -> { content }
+//   POST /write  { path, content, env? }    -> { ok: true }
+//   GET  /healthz                           -> { ok: true, build: { commit, builtAt? } }
+//
+// Every request carries:
+//   Authorization: Bearer <SANDBOX_TOKEN>   (wrangler secret put SANDBOX_TOKEN)
+//   X-Thread-Key: <threadKey>               (one sandbox per conversation thread)
+// and the body's optional `env` ({ NAME: value }) is forwarded into the sandbox
+// for that one command — in the body, never in headers, because Workers Logs
+// record request headers (docs/reference/specs/execution.md item 5).
+//
+// The Sandbox SDK only runs inside Workers — that's why this proxy exists.
+// Verify method names against https://developers.cloudflare.com/sandbox/ on
+// first deploy; the SDK is young and its surface may shift.
+import { getSandbox, Sandbox, type ExecOptions, type ExecResult } from "@cloudflare/sandbox";
+import { BASH_TIMEOUT_MAX_MS, clampBashTimeout } from "../../src/execution/bashTimeout.js";
+import {
+  EXEC_KEEPALIVE_INTERVAL_MS,
+  SANDBOX_SLEEP_AFTER,
+  isRecycleError,
+  recycledMidCommandMessage,
+  withActivityKeepalive,
+} from "../../src/execution/sandboxKeepalive.js";
+import { envFromRequest } from "../../src/execution/sandboxEnv.js";
+import { shellQuote } from "../../src/execution/shellQuote.js";
+import {
+  fleetBusyAnswer,
+  fleetBusyExecAnswer,
+  isContainerStarting,
+  isFleetBusyError,
+  thrownShape,
+  thrownText,
+} from "../../src/execution/sandboxErrors.js";
+import { injectedBuildStamp } from "../../src/deploy/buildStamp.js";
+import { classifyError } from "../../src/core/trace/classify.js";
+import { systemClock } from "../../src/core/trace/clock.js";
+import { createTracer } from "../../src/core/trace/tracer.js";
+import { startAdoptedRoot, workerLogSink } from "../../src/core/trace/workerTrace.js";
+import sandboxPkg from "./package.json" with { type: "json" };
+
+/** The `@cloudflare/sandbox` version this Worker is built against — the pin
+ *  `check:sandbox-pair` holds equal to the Dockerfile's image tag, so it is
+ *  also the version a container on the CURRENT image reports. */
+const SDK_PIN: string = sandboxPkg.dependencies["@cloudflare/sandbox"];
+
+export class SwitchboardSandbox extends Sandbox {
+  // Idle lifetime of a thread's container (the SDK's own default is 10 min on
+  // 0.12.x, 20 on 0.3.x). On the 0.0.28 containers base the activity clock was
+  // renewed once per proxied fetch and the alarm loop SIGTERMed the container
+  // the moment it expired, in-flight request or not — so a review's first
+  // command (a 20-minute budget under a 20-minute default) was once
+  // killed at 20:00 exactly, surfaced as "Command execution failed", and
+  // the next command found a fresh container with an empty /workspace. `exec`
+  // below renews the clock every minute while a command runs, which makes
+  // this a true idle timeout (docs/reference/specs/execution.md item 2). The 0.3.x
+  // containers base tracks in-flight requests itself, so the keepalive is now
+  // belt-and-braces — kept until a live long-command receipt retires it. 5
+  // minutes of idle frees the slot sooner while a prompt follow-up still
+  // reuses the warm workspace.
+  sleepAfter = SANDBOX_SLEEP_AFTER;
+
+  // A Worker and its image deploy as two artifacts; until the rollout finishes
+  // this Worker can be handed a container still on the PREVIOUS image
+  // (docs/reference/specs/execution.md item 6; seen live: a 0.3.7 container under the
+  // 0.12.9 SDK, every command a message-less 400 for 90 s). The SDK's own
+  // check logs `container=unknown` at info and does nothing else; this one
+  // names the skew at warn so the rollout is visible in the logs.
+  //
+  // LOG ONLY — never `destroy()` here: onStart runs inside
+  // `blockConcurrencyWhile`, `destroy()` is unbounded and coalesced callers
+  // hang until eviction, a fresh placement during a gradual wave can land on
+  // the old image again (the incident's DO was brand new), and the
+  // healthy-but-not-running state after a destroy takes the SDK's stale-state
+  // path, which can `ctx.abort()` the DO. A command that fails on a skewed
+  // instance is named by `thrownText` with the rollout hint; the one-wave
+  // rollout (`rollout_step_percentage: 100`) keeps the window to seconds.
+  override async onStart(): Promise<void> {
+    await super.onStart();
+    const v = await this.client.utils.getVersion().catch(() => "unknown");
+    if (v !== SDK_PIN) {
+      console.warn(
+        `sandbox.version-skew container=${v} sdk=${SDK_PIN} — this instance may be on a previous image (Worker/image rollout in progress)`,
+      );
+    }
+  }
+
+  override async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+    return withActivityKeepalive(
+      () => this.renewActivityTimeout(),
+      () => super.exec(command, options),
+      EXEC_KEEPALIVE_INTERVAL_MS,
+    );
+  }
+
+  // A fence from the 0.3.x days, kept until a live container-restart receipt
+  // retires it: 0.3.x cached its default ExecutionSession in Durable
+  // Object memory while the session lived in the container, so a container
+  // restart under a live DO (image rollout, crash, sleep/wake) made every later
+  // call fail with "Session '<id>' not found" forever. 0.12.x persists the
+  // session id in DO storage, clears it itself in `onStop`, and its container
+  // recreates a missing session on the next exec — so this should never run;
+  // if it does, nulling the cached id only makes the SDK recreate the session,
+  // which is what it would have done anyway. The workspace disk is gone either
+  // way; repos re-clone — the same graceful degradation as an expired E2B
+  // sandbox.
+  resetDefaultSession(): void {
+    (this as unknown as { defaultSession: unknown }).defaultSession = null;
+  }
+}
+
+/** The 0.3.x stale-session text; see `resetDefaultSession`. */
+const STALE_SESSION = /session '[^']*' not found/i;
+
+/** Run a sandbox call and retry it ONCE when the failure says nothing ran: a
+ *  stale session (0.3.x; reset the cached id first) or a container still
+ *  booting (0.12.x's "Container is starting. Please retry in a moment.", after
+ *  a short pause). Both fail before the command or file op executes, so the
+ *  re-send is safe by construction. Anything else propagates: a failure whose
+ *  command MAY have run (a session shell that exited mid-command, a container
+ *  that stopped under the call) is never re-run here — /exec names it a
+ *  recycle instead (docs/reference/specs/execution.md item 9). */
+const CONTAINER_STARTING_RETRY_DELAY_MS = 3_000;
+
+async function withSessionRecovery<T>(
+  sandbox: { resetDefaultSession(): void | Promise<void> },
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    const { message } = thrownShape(err);
+    if (message && STALE_SESSION.test(message)) {
+      await sandbox.resetDefaultSession();
+      return await fn();
+    }
+    if (isContainerStarting(err)) {
+      await new Promise((r) => setTimeout(r, CONTAINER_STARTING_RETRY_DELAY_MS));
+      return await fn();
+    }
+    throw err;
+  }
+}
+
+interface Env {
+  Sandbox: DurableObjectNamespace<SwitchboardSandbox>;
+  SANDBOX_TOKEN: string;
+}
+
+const WORKDIR = "/workspace";
+
+// Default per-command time limit, enforced by coreutils `timeout` inside the
+// sandbox. The tuned 280s applies when the body carries no timeoutMs (an older
+// bot); a caller-supplied timeoutMs is clamped server-side to the shared
+// [1s, 20 min] bounds (clampBashTimeout — never trust the client's number).
+// Whatever the effective limit, it must stay BELOW the SDK backstop
+// (COMMAND_TIMEOUT_MS in the Dockerfile, sized above the 20-min ceiling) so
+// the real exit 124 wins. undici's 300s no-headers ceiling stopped mattering
+// once /exec streamed heartbeats — headers go out immediately.
+const EXEC_TIMEOUT_SECS = 280;
+
+/** The commit this bundle was built from, injected by the deploy
+ *  (`deploy/bin/build-stamp.mjs`) and answered on GET /healthz as `build`. */
+const BUILD = injectedBuildStamp();
+
+// The Worker's own spans (docs/reference/specs/tracing.md item 22): one `sandbox.exec`
+// root per command, started at the attempt that produced the answer, joining
+// the bot's trace (the bearer checked out before the header is read).
+const tracer = createTracer({ clock: systemClock });
+const traceSinks = [workerLogSink((line) => console.log(line))];
+
+/** One command's root, started at the attempt that answered, joining the bot's trace. */
+function execRoot(attemptStartedAt: number, traceparent: string | undefined) {
+  return startAdoptedRoot(tracer, "sandbox.exec", { sinks: traceSinks, startedAt: attemptStartedAt, traceparent });
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const auth = request.headers.get("authorization");
+    if (!env.SANDBOX_TOKEN || auth !== `Bearer ${env.SANDBOX_TOKEN}`) {
+      return json({ error: "unauthorized" }, 401);
+    }
+    // Build identity, behind the SAME bearer as everything else: this Worker
+    // authenticates every request and gains no unauthenticated surface for a
+    // stamp (docs/reference/specs/execution.md item 13). It needs no thread, so it answers
+    // before the X-Thread-Key check — and it is the one GET here.
+    if (request.method === "GET" && new URL(request.url).pathname === "/healthz") {
+      return json({ ok: true, build: BUILD });
+    }
+    if (request.method !== "POST") return json({ error: "POST only" }, 405);
+
+    const threadKey = request.headers.get("x-thread-key");
+    if (!threadKey) return json({ error: "missing X-Thread-Key" }, 400);
+
+    // One sandbox per thread; the DO name is the thread key. getSandbox is
+    // generic over the namespace's class since 0.12, so the subclass's
+    // resetDefaultSession is callable over RPC without a cast.
+    const sandbox = getSandbox(env.Sandbox, threadKey);
+
+    const url = new URL(request.url);
+    const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+
+    // Optional env passthrough (e.g. GH_TOKEN), read from the BODY's `env`
+    // (docs/reference/specs/execution.md item 5). It then rides in the SDK's per-exec
+    // `env` option, which the container applies to that one command and
+    // restores afterwards (0.12.x; 0.3.7 ignored it, so the value used to be
+    // an inline base64 `export` prefix — which put the live GH_TOKEN into every
+    // "Command executed" line the SDK logs). Nothing persists in the
+    // sandbox beyond the command's lifetime, and the command text the SDK
+    // logs never carries a credential.
+    //
+    // Body, never headers: Workers Logs record this invocation's request
+    // headers and redact them by a name heuristic only — a receipt probe's
+    // per-variable env header was once logged in clear. Bodies are not
+    // recorded. The one-release per-variable-header fallback that carried a
+    // body-only bot against a header-only Worker during that rollout is
+    // gone now that the body reader is live everywhere, so the
+    // credential rides only in the body and no request header is read as env.
+    const envVars = envFromRequest({ body });
+
+    try {
+      switch (url.pathname) {
+        case "/exec": {
+          // Streamed with a whitespace heartbeat. A long command otherwise
+          // holds a byteless HTTP request open for minutes, and some hop
+          // between the bot and this Worker silently drops idle connections —
+          // measured live: the container answered a 290s command at its 280s
+          // timeout, but the bot's fetch died without ever seeing the
+          // response (undici gives up 300s after sending a request that has
+          // received no headers). Headers go out immediately and a heartbeat
+          // byte flows every 15s, so no intermediary ever sees an idle
+          // connection. Heartbeats are pure whitespace, which is legal around
+          // a JSON document — the executor's res.json() on the full body
+          // parses unchanged.
+          //
+          // The time limit is enforced with coreutils `timeout` INSIDE the
+          // sandbox, not by the SDK: the SDK's COMMAND_TIMEOUT_MS rejection is
+          // useless to callers — its exec handler wraps every failure as a
+          // generic "Command execution failed" and buries the real message in
+          // a field its client discards (measured live). Shell-level timeout
+          // produces a real exit 124 through the normal result path, no error
+          // classification needed. SIGKILL follows 10s after TERM for
+          // stragglers. COMMAND_TIMEOUT_MS (Dockerfile) sits above this as a
+          // pure backstop.
+          //
+          // Per-call budget (docs/reference/specs/execution.md item 11): a numeric
+          // timeoutMs in the body is clamped server-side to the shared
+          // [1s, 20 min] bounds; absent (an older bot) → the tuned 280s
+          // default this Worker has always used.
+          const requested = body.timeoutMs;
+          const execTimeoutSecs =
+            typeof requested === "number" && Number.isFinite(requested)
+              ? Math.ceil(clampBashTimeout(requested) / 1000)
+              : EXEC_TIMEOUT_SECS;
+          const full = `mkdir -p ${WORKDIR} && cd ${WORKDIR} && ${String(body.command ?? "")}`;
+          return streamExec(
+            sandbox,
+            `timeout -k 10 ${execTimeoutSecs} bash -c ${shellQuote(full)}`,
+            { env: envVars },
+            execTimeoutSecs,
+            request.headers.get("traceparent") ?? undefined,
+          );
+        }
+        case "/read": {
+          const file = await withSessionRecovery(sandbox, () => sandbox.readFile(abs(String(body.path ?? ""))));
+          return json({ content: typeof file === "string" ? file : (file?.content ?? "") });
+        }
+        case "/write": {
+          await withSessionRecovery(sandbox, () =>
+            sandbox.writeFile(abs(String(body.path ?? "")), String(body.content ?? "")),
+          );
+          return json({ ok: true });
+        }
+        default:
+          return json({ error: "unknown route" }, 404);
+      }
+    } catch (err) {
+      // Never an empty text (item 3): a message-less SDK error is named as
+      // such, with the rollout hint.
+      const msg = thrownText(thrownShape(err));
+      // A full fleet (docs/reference/specs/execution.md item 14): the SDK could not get a
+      // container instance for this thread's Durable Object, so no session
+      // exists and the file op never started — re-sending is safe by
+      // construction. Named so the executor waits instead of reading it as a
+      // dead sandbox; 503 because that is what it is.
+      if (isFleetBusyError(err)) return json(fleetBusyAnswer(msg), 503);
+      return json({ error: msg }, 500);
+    }
+  },
+} satisfies ExportedHandler<Env>;
+
+/** Execute a command and stream the response: immediate headers, a whitespace
+ *  heartbeat every 15s while the command runs, then one JSON document. All
+ *  outcomes arrive in-body with HTTP 200 (headers are long gone by the time
+ *  the result is known): a completed command as {stdout, stderr, exitCode},
+ *  a sandbox-enforced timeout as exit 124, and any other failure as {error}. */
+function streamExec(
+  sandbox: {
+    resetDefaultSession(): void | Promise<void>;
+    exec(command: string, options?: ExecOptions): Promise<{ stdout?: string; stderr?: string; exitCode?: number }>;
+  },
+  command: string,
+  options: ExecOptions,
+  execTimeoutSecs: number,
+  traceparent: string | undefined,
+): Response {
+  const encoder = new TextEncoder();
+  // Per ATTEMPT, not per request: withSessionRecovery may run the command a
+  // second time after a stale-session reset, and a retry's own failure must be
+  // judged on its own clock, not the first attempt's.
+  let attemptStartedAt = systemClock();
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const beat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode("\n"));
+        } catch {
+          clearInterval(beat); // client went away; the exec promise still settles
+        }
+      }, 15_000);
+      const finish = (payload: object) => {
+        clearInterval(beat);
+        try {
+          controller.enqueue(encoder.encode(JSON.stringify(payload)));
+          controller.close();
+        } catch {
+          // stream already errored/cancelled — nothing left to deliver to
+        }
+      };
+      withSessionRecovery(sandbox, () => {
+        attemptStartedAt = systemClock();
+        return sandbox.exec(command, options);
+      })
+        .then((result) => {
+          const exitCode = result.exitCode ?? 0;
+          // coreutils `timeout` exits 124 when the deadline killed the
+          // command (137 when the follow-up SIGKILL had to) — annotate so the
+          // agent knows what happened and how to adapt.
+          const timedOut = exitCode === 124 || exitCode === 137;
+          const note = timedOut
+            ? `command timed out in the sandbox after ${execTimeoutSecs}s (pass the bash tool's timeoutMs for longer commands, max ${BASH_TIMEOUT_MAX_MS} ms); ` +
+              "re-run as smaller/faster steps or background it with nohup"
+            : "";
+          // The command as the Worker's own root (docs/reference/specs/tracing.md item 22).
+          execRoot(attemptStartedAt, traceparent).end(exitCode === 0 ? "ok" : "error", {
+            exitCode: timedOut ? 124 : exitCode,
+            ...(timedOut ? { timedOut: true } : {}),
+          });
+          finish({
+            stdout: result.stdout ?? "",
+            stderr: [result.stderr ?? "", note].filter(Boolean).join("\n"),
+            exitCode: timedOut ? 124 : exitCode,
+            // The command's wall time in the sandbox, for the bot's `exec.exec`
+            // span (docs/reference/specs/tracing.md item 19); an older client ignores it.
+            durationMs: systemClock() - attemptStartedAt,
+          });
+        })
+        .catch((err: unknown) => {
+          // A command the sandbox never answered for: an infra failure, classified, no message.
+          const root = execRoot(attemptStartedAt, traceparent);
+          root.fail(classifyError(new Error("sandbox exec failed"), { kind: "infra" }));
+          root.end("error");
+          const shape = thrownShape(err);
+          // The text that leaves the Worker is never empty (item 3): a
+          // message-less SDK error is named, with the rollout hint. The
+          // classifiers below still read the raw `shape`.
+          const raw = thrownText(shape);
+          // A full fleet (docs/reference/specs/execution.md item 14): session creation
+          // failed because no container instance was free, so the command
+          // never started — re-sending it is safe by construction. The named
+          // `reason` is what the executor waits on; the dual shape below is
+          // kept so an older executor still renders it as exit 127.
+          if (isFleetBusyError(err)) {
+            finish(fleetBusyExecAnswer(raw));
+            return;
+          }
+          // The container was replaced under the command (docs/reference/specs/execution.md
+          // item 2): certain when the SDK says so with a typed error, inferred
+          // when a recycle-shaped text arrives minutes into this attempt. Say
+          // so, and that /workspace is gone. Still exit 127: the workspace
+          // really is gone.
+          const certain = shape.name !== undefined && isRecycleError({ name: shape.name });
+          const msg = recycledMidCommandMessage(systemClock() - attemptStartedAt, raw, certain);
+          // Carry the failure in BOTH shapes so rollout order can't create
+          // a silent-success window: a new executor throws on `error`, and
+          // an executor that predates in-body errors (only checks exitCode)
+          // still renders "exit 127: <message>" instead of "(no output)".
+          finish({ error: msg, stdout: "", stderr: msg, exitCode: 127 });
+        });
+    },
+  });
+  return new Response(stream, { headers: { "content-type": "application/json" } });
+}
+
+function abs(p: string): string {
+  if (!p) throw new Error("missing path");
+  const path = p.startsWith("/") ? p : `${WORKDIR}/${p}`;
+  if (!path.startsWith(WORKDIR)) throw new Error(`Path escapes workspace: ${p}`);
+  return path;
+}
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

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

@@ -0,0 +1,67 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "{{script}}",
+  "main": "worker.ts",
+  "compatibility_date": "2026-08-01",
+  // @cloudflare/sandbox 0.12.x imports Node built-ins (wrangler's dry run names
+  // sandbox-*.js and warns the Worker "may throw errors at runtime" without
+  // this); the resident Worker on the 0.13 line carries the same flag.
+  "compatibility_flags": ["nodejs_compat"],
+  // The installation's Cloudflare account (deploy/profile.json `account`) — every Worker deploys to it.
+  "account_id": "{{account}}",
+  // Reachable only with the SANDBOX_TOKEN bearer secret. Custom domain on the
+  // installation's zone so the bot config has a stable URL.
+  "workers_dev": false,
+  "routes": [{ "pattern": "{{hostname}}", "custom_domain": true }],
+  "observability": { "enabled": true },
+  "containers": [
+    {
+      "class_name": "SwitchboardSandbox",
+      // The profile's image mode decides (src/deploy/images.ts): `build` renders
+      // ./Dockerfile (on the @cloudflare/sandbox base image), built by wrangler
+      // at deploy time; `registry` renders the release's published image as
+      // copied into this account's registry by `deploy images`.
+      "image": "{{image}}",
+      // standard-4 = 4 vCPU / 12 GiB RAM / 20 GB disk — the largest predefined
+      // type; a custom type tops out at the same 4 vCPU / 12 GiB / 20 GB. The
+      // cold path clones + installs + checks a whole repo per thread with
+      // nothing warm, so the size is set by the largest single command a cold
+      // thread must be able to run, not by the typical one: a large monorepo's
+      // typecheck needs more than 8 GiB (its own CI notes put the root program
+      // near 8 GB and each sub-program near 4 GB), and the previous standard-3
+      // (2 vCPU / 8 GiB / 16 GB; a live probe read nproc 2, 8189 MiB, 15 GB on
+      // /) could not run it at all. "basic" (1 GiB) died running a repo's test
+      // suite during a cold review (vitest forks per vCPU). Cost is per AWAKE
+      // instance and a sandbox sleeps after 5 idle minutes (SANDBOX_SLEEP_AFTER),
+      // so the step is paid per active run-hour: 12 GiB against 8 of memory,
+      // and vCPU only while the cores are busy (docs/reference/specs/execution.md
+      // item 16).
+      "instance_type": "standard-4",
+      // The fleet's ceiling on AWAKE per-thread sandboxes; the next thread past
+      // it waits (docs/reference/specs/execution.md item 14). Billing is per awake
+      // instance, so a higher ceiling costs nothing while instances sleep, and
+      // the account has ~15x headroom on the containers limits (6 TiB memory /
+      // 1500 vCPU against 25 × 12 GiB = 300 GiB, ~20x, and 25 × 4 = 100 vCPU,
+      // 15x — the vCPU line is the tighter one). Seen live: thirteen cold
+      // runs in 45 min exhausted the previous ceiling of 10 and a review
+      // aborted in 33 s reading the wait as a dead sandbox.
+      "max_instances": 25,
+      // Replace the old-image instances in ONE wave on a deploy, not the
+      // platform's default [10, 100] with minutes between the waves. A Worker
+      // and its image deploy as two artifacts, and until the rollout finishes
+      // the NEW Worker code can be handed an instance still on the PREVIOUS
+      // image: seen live, a review's thread created 111 s after a Worker
+      // upload landed on a 0.3.7 container under the 0.12.9 SDK and every
+      // command failed for 90 s. In-flight commands on old
+      // instances die in any rollout mode (each old instance is SIGTERMed
+      // eventually; the grace period is already 0) — one wave only moves that
+      // moment earlier, and shrinks the window a new thread can fall into
+      // from minutes to seconds (docs/reference/specs/execution.md item 6).
+      "rollout_step_percentage": 100
+    }
+  ],
+  "durable_objects": {
+    "bindings": [{ "name": "Sandbox", "class_name": "SwitchboardSandbox" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SwitchboardSandbox"] }]
+}

package/dist/assets/deploy/profile.example.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
+  "account": "00000000000000000000000000000000",
+  "zone": "example.com",
+  "workers": {
+    "memory": { "script": "switchboard-memory", "hostname": "switchboard-memory.example.com" },
+    "bot": { "script": "switchboard", "hostname": "switchboard.example.com" },
+    "resident": { "script": "switchboard-resident", "hostname": "switchboard-resident.example.com" },
+    "sandbox": { "script": "switchboard-sandbox", "hostname": "switchboard-sandbox.example.com" }
+  },
+  "configSource": "config/config.yaml",
+  "images": "registry"
+}

package/dist/assets/deploy/secrets.manifest.json

@@ -0,0 +1,108 @@
+{
+  "$comment": "Every Cloudflare Worker secret Switchboard provisions: its name, which Worker(s) hold it, and whether a Worker may go without it (`optional: true` everywhere, or a list of the Workers it is optional on — a shared bearer is required on the Worker that serves the feature and optional on the bot until that feature is configured). This file is the contract — src/core/secretsManifest.test.ts keeps it equal to each worker.ts `Env` interface and to the bot container's forwarding list. WHERE the values live is the deployment profile's `secretsSource` (a directory of <NAME> files, `~/.secrets/switchboard` by default, or a 1Password item `op://Vault/Item` with one field per name); `deploy secrets <worker>` (`npm run secrets` in each deploy/cloudflare*/) puts them, refusing before any upload when a required value is absent. A shared bearer must carry ONE value on every Worker listed for it. Rotation: new value at the source, `deploy secrets` on EVERY listed Worker, then `deploy restart` for the bot (its running container keeps the env it started with). Public config (URLs, ids of no consequence) is a wrangler.jsonc var, not a secret.",
+  "secrets": [
+    {
+      "name": "SLACK_BOT_TOKEN",
+      "workers": ["bot"],
+      "note": "Slack app bot token (xoxb-). Third-party; rotate in the Slack app config."
+    },
+    {
+      "name": "SLACK_APP_TOKEN",
+      "workers": ["bot"],
+      "note": "Slack app-level token (xapp-) for Socket Mode. Third-party."
+    },
+    {
+      "name": "ANTHROPIC_API_KEY",
+      "workers": ["bot"],
+      "note": "Anthropic Console key the bot runs on. Third-party."
+    },
+    {
+      "name": "ANTHROPIC_ADMIN_KEY",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "Anthropic Admin API key (sk-ant-admin…) for the LLM-spend layer of GET /costs. Absent, /costs shows the Cloudflare side only."
+    },
+    {
+      "name": "BRAVE_SEARCH_API_KEY",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "Brave Search API key for the research agent's web search. Third-party. Optional: without it the research agent has no web search."
+    },
+    {
+      "name": "CF_ANALYTICS_TOKEN",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "Cloudflare API token for the installation's account, Account Analytics:Read — prices GET /costs from billing data. Optional: without it GET /costs has no infrastructure spend."
+    },
+    {
+      "name": "SWITCHBOARD_INGRESS_TOKENS",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "JSON bearer→identity map for POST /ingress and POST /mcp. Self-minted (openssl rand -hex 32 per entry). Optional: without it /ingress and /mcp are disabled and `deploy restart` has no bearer."
+    },
+    {
+      "name": "SANDBOX_TOKEN",
+      "workers": ["bot", "sandbox"],
+      "optional": ["bot"],
+      "note": "Shared bearer: bot → thread-sandbox Worker. Self-minted. Required on the sandbox Worker; optional on the bot, which needs it only when `execution.type: cloudflare`."
+    },
+    {
+      "name": "RESIDENT_OPERATOR_TOKEN",
+      "workers": ["bot", "resident"],
+      "optional": ["bot"],
+      "note": "Shared bearer: bot runtime → resident Worker attach/exec/read/write/status. Self-minted. Rotating it breaks in-flight resident runs — check /runs is empty first. Required on the resident Worker; optional on the bot, which needs it only when `execution.resident` is set."
+    },
+    {
+      "name": "RESIDENT_ADMIN_TOKEN",
+      "workers": ["bot", "resident"],
+      "optional": ["bot"],
+      "note": "Shared bearer: `repo onboard/offboard/reconfigure/rebuild` → resident admin routes; also the resident deploy preflight. Self-minted. Required on the resident Worker; optional on the bot, which needs it only when `execution.resident` is set."
+    },
+    {
+      "name": "RESIDENT_READ_TOKEN",
+      "workers": ["resident"],
+      "note": "Read-only /residents + debug routes; what the resident deploy preflight needs (CI holds this one). Self-minted."
+    },
+    {
+      "name": "R2_ACCESS_KEY_ID",
+      "workers": ["resident"],
+      "optional": true,
+      "note": "R2 API token (S3 access key id) scoped Object Read & Write to the resident cache bucket ONLY — with R2_SECRET_ACCESS_KEY and the CLOUDFLARE_ACCOUNT_ID / BACKUP_BUCKET_NAME vars, snapshot bytes travel container↔R2 over presigned URLs and the Durable Object leaves the data path (docs/reference/specs/resident-repos.md item 61). Absent → the SDK's local-bucket mode (the DO pumps the bytes; a 1.16 GB restore exceeds the isolate's memory). Created in the Cloudflare dashboard (R2 → Manage API tokens); rotate = new token, `deploy secrets resident`. /healthz `backupTransfer` says which mode is live."
+    },
+    {
+      "name": "R2_SECRET_ACCESS_KEY",
+      "workers": ["resident"],
+      "optional": true,
+      "note": "The secret half of R2_ACCESS_KEY_ID (same token). Both or neither."
+    },
+    {
+      "name": "MCP_CREDENTIAL_KEY",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "AES-256-GCM key (32 bytes, base64: `openssl rand -base64 32`) the bot seals MCP server credentials with before they go to the state Worker's McpDO (docs/reference/specs/mcp-tools.md). Bot-only by design: the Worker stores ciphertext. Rotation re-seals every credential — not built yet; rotate = users re-run `mcp connect`."
+    },
+    {
+      "name": "MEMORY_TOKEN",
+      "workers": ["bot", "resident", "memory"],
+      "note": "Shared bearer for the state Worker (memory, friction ledger, run history, schedule firings). ONE value on all three Workers — a resident with a different mint 401s on every watchdog firing record. Self-minted."
+    },
+    {
+      "name": "GITHUB_APP_ID",
+      "workers": ["bot", "resident"],
+      "optional": ["bot", "resident"],
+      "note": "The installation's GitHub App id. Not sensitive, but lives alongside the key so both Workers mint installation tokens the same way. Optional on both: without the triple the bot falls back to GH_TOKEN (or has no GitHub tools) and the resident clones anonymously."
+    },
+    {
+      "name": "GITHUB_APP_INSTALLATION_ID",
+      "workers": ["bot", "resident"],
+      "optional": ["bot", "resident"],
+      "note": "The App's installation id on the organization the bot works in. Not sensitive. Optional on both, with GITHUB_APP_ID."
+    },
+    {
+      "name": "GITHUB_APP_PRIVATE_KEY",
+      "workers": ["bot", "resident"],
+      "optional": ["bot", "resident"],
+      "note": "The App's PEM. Second credential domain: the resident holds its own copy; rotate both together (GitHub → generate new key → put on both → revoke old). Optional on both, with GITHUB_APP_ID."
+    }
+  ]
+}

package/dist/assets/docker-entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# The image's entrypoint (the Dockerfile installs it as `switchboard`).
+#   no arguments        → the bot, `node dist/index.js` (docker compose, the Cloudflare container)
+#   node|sh|bash …      → that command, as given (a shell into the image)
+#   anything else       → the CLI: `init`, `ask "…"`, `<group> <verb> …`
+# The CLI reads `.env` and `./config/config.yaml` from the working directory,
+# so `-w /work -v "$PWD":/work` installs into the host's directory.
+set -e
+if [ "$#" -eq 0 ]; then
+  exec node /app/dist/index.js
+fi
+case "$1" in
+  node | sh | bash) exec "$@" ;;
+esac
+exec node /app/dist/cli.js "$@"