@coreplane/switchboard 0.0.0 → 1.18.1

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "{{script}}",
+  "main": "worker.ts",
+  "compatibility_date": "2026-08-01",
+  // The installation's Cloudflare account (deploy/profile.json `account`) — every Worker deploys to it.
+  "account_id": "{{account}}",
+  // Reachable only with the MEMORY_TOKEN bearer secret (plus an unauthenticated
+  // GET /healthz wake ping). Custom domain on the installation's zone so the
+  // bot config (memory.worker.baseUrl) has a stable URL.
+  "workers_dev": false,
+  "routes": [{ "pattern": "{{hostname}}", "custom_domain": true }],
+  "observability": { "enabled": true },
+  "durable_objects": {
+    // One MemoryDO per scopeKey (the DO name IS the scope key, e.g.
+    // "org:<organization>") — the scope partition is the object boundary, so a
+    // scope's rows live in one SQLite database and cross-scope reads are
+    // impossible by construction.
+    "bindings": [
+      { "name": "MEMORY", "class_name": "MemoryDO" },
+      // ONE ScheduleDO (named "schedules"): every cron firing the bot's Worker
+      // shim makes, for the /runs Scheduled panel (docs/reference/specs/live-view.md).
+      { "name": "SCHEDULES", "class_name": "ScheduleDO" },
+      // One RunHistoryDO per store key (`runs:default`): persistent run history
+      // (docs/reference/specs/run-history.md) — runs + run_events + the retention policy.
+      { "name": "RUNS", "class_name": "RunHistoryDO" },
+      // ONE ConfigDO (named "config"): the bot's runtime config documents — the
+      // chat-set `overrides` (docs/reference/specs/routing-and-config.md item 12) — versioned.
+      { "name": "CONFIG", "class_name": "ConfigDO" },
+      // One RunTranscriptDO per LIVE run (the DO name is the run id): the raw
+      // transcript a resumed run continues from (docs/reference/specs/run-history.md item
+      // 32). Kept apart from the history object so transcript bytes never queue
+      // behind an admission decision; cleared at finish.
+      { "name": "RUN_TRANSCRIPTS", "class_name": "RunTranscriptDO" }
+    ]
+  },
+  // SQLite-backed DOs (durable across restarts — AGENTS.md invariant 6).
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["MemoryDO"] },
+    { "tag": "v2", "new_sqlite_classes": ["FrictionDO"] },
+    { "tag": "v3", "new_sqlite_classes": ["ScheduleDO"] },
+    { "tag": "v4", "new_sqlite_classes": ["RunHistoryDO"] },
+    { "tag": "v5", "new_sqlite_classes": ["ConfigDO"] },
+    { "tag": "v6", "new_sqlite_classes": ["RunTranscriptDO"] },
+    // The friction ledger is read from run history (RunHistoryDO carries every
+    // run's diagnosis); the FrictionDO that once mirrored those diagnoses is
+    // retired with its rows — docs/reference/specs/self-improvement.md item 1.
+    { "tag": "v7", "deleted_classes": ["FrictionDO"] }
+  ]
+}

package/dist/assets/deploy/cloudflare-resident/Dockerfile

@@ -0,0 +1,91 @@
+# Resident container image: the @cloudflare/sandbox base (Ubuntu 22.04; already
+# ships git, curl, jq, Node 24, npm, bun, cloudflared) plus GitHub tooling and
+# a pool of unprivileged users.
+# The tag MUST match the @cloudflare/sandbox version in package.json exactly
+# (no 'latest' tag exists on the @next line) — bump both together.
+FROM docker.io/cloudflare/sandbox:0.13.0-next.751.1
+
+# Git identity only. The engine never uses the gh CLI (ops run git directly,
+# tokens are minted via the GitHub REST API in the Worker/DO, and per-attach
+# credentials use a repo-local `store` helper), so gh is deliberately NOT
+# installed here — matching the resident system prompts and the tests that pin
+# that claim. No system credential.helper is configured; each worktree sets its
+# own per-attach helper.
+RUN git config --system user.name "switchboard-resident" \
+  && git config --system user.email "switchboard-resident@users.noreply.github.com"
+
+# The container is FOUR vCPUs shared by up to 16 threads (wrangler.jsonc).
+# Node test runners size their worker pools from the CPU count the kernel
+# reports — the HOST's, not the cgroup's — so an unconfigured `vitest`/`jest`
+# run forks a dozen workers and thrashes (seen live on the 1 vCPU resident: a
+# resident pinned at 100% CPU, 2.2 GiB). The runner pins stay at ONE worker per
+# thread: the cores are for concurrent threads, not for one thread's test
+# parallelism, and a repo's own config or CLI flags still win. The libuv pool
+# is one thread per vCPU (it is per Node process; more would oversubscribe the
+# cores once several threads run). These defaults inherit into every thread's
+# `su … -c` shell (su without `-` keeps the environment). CI=1 makes runners
+# non-interactive (no watch mode, no TTY progress spinners in captured
+# output). The heap cap keeps one runaway process to an eighth of the 12 GiB
+# so its neighbours keep theirs.
+ENV CI=1 \
+    VITEST_MAX_WORKERS=1 VITEST_MAX_THREADS=1 VITEST_MAX_FORKS=1 VITEST_MIN_THREADS=1 VITEST_MIN_FORKS=1 \
+    UV_THREADPOOL_SIZE=4 \
+    NODE_OPTIONS=--max-old-space-size=1536
+
+# pnpm + yarn: the base ships Node 24 + npm + bun but neither pnpm nor yarn, so a
+# repo whose onboard table is detected as pnpm or yarn (resident-repos item 52 —
+# every manager `detectCommands` can emit must exist here, or the table fails
+# deterministically at provision) couldn't be provisioned (install → build).
+# corepack is NOT on this base's PATH (unlike the older sandbox base), so both
+# come from npm at build time. yarn here is classic (1.x); a Yarn Berry repo
+# bootstraps through it via the `yarnPath` release it commits under
+# `.yarn/releases`.
+#
+# EXACT versions, enforced by src/deploy/imagePins.test.ts. This line once read
+# `pnpm@latest yarn@latest`, which made the pnpm major a property of the last
+# image build: one rebuild moved it 10 -> 11 unannounced, and pnpm 11 no
+# longer reads `package.json`'s `pnpm` field (overrides,
+# patchedDependencies, onlyBuiltDependencies), so a repo keeping its settings
+# there fails `--frozen-lockfile` with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH.
+# pnpm is pinned to the 10 line ON PURPOSE: 10.x reads that field, and pnpm
+# >=10 self-manages `packageManager`, so a repo pinning 11/12 still gets its
+# own version — the pin is a floor, not a ceiling. Which means the version
+# baked here is NOT necessarily the one that runs: a repo with a
+# `packageManager` field downloads that version on first install (a repo
+# pinning pnpm@10.10.0 gets exactly that), so provisioning needs the registry,
+# not just the image. The grep asserts the pin took, so a resolution surprise
+# fails the build instead of a provision.
+RUN npm install -g pnpm@10.34.5 yarn@1.22.22 \
+  && pnpm --version | grep -qx '10\.34\.5' \
+  && yarn --version | grep -qx '1\.22\.22'
+
+# squashfs-tools (`unsquashfs`): the SDK's presigned restore does not extract
+# an archive, it MOUNTS it (squashfuse + fuse-overlayfs at the handle's dir)
+# and leaves the `.sqsh` under /var/backups — resident-repos item 61. The
+# resident extracts the archive onto its ext4 disk instead (the SDK's own
+# local-dev method) so the mirror, the checkout and the deps store stay one
+# filesystem: `rm -rf` works, hardlink views work, `du -x` is right. The
+# Worker falls back to `cp -a` out of the mount while an older image lacks it.
+# The build asserts the binary with the probe the extract script uses at run
+# time (`command -v`): `unsquashfs -version` exits 1 on squashfs-tools 4.5 (this
+# base) when no filesystem is named, and failed the 1.2.0 image build that way.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends squashfs-tools \
+  && rm -rf /var/lib/apt/lists/* \
+  && command -v unsquashfs >/dev/null
+
+# Agent commands never run as root (repo code runs unprivileged, one user per
+# thread — docs/reference/specs/resident-repos.md). The SDK's exec has no user/uid option
+# (verified against 0.13.0-next.751.1), so the container server itself runs as
+# root and per-command demotion is done with `su -s /bin/bash workerN -c ...`
+# (verified live: exec via su lands at uid 200N). Provision a pool of
+# unprivileged users — one per resident cap slot — and shut the escalation
+# paths back up:
+#   - sudo: not installed in the base image; purge defensively in case a later
+#     base bump adds it.
+#   - su back to root: root's password is locked, so workerN -> root fails.
+# `su` itself must stay (it is the demotion mechanism, used only by root).
+RUN set -eux; \
+    for i in $(seq 1 17); do useradd -m -u "$((2000 + i))" -s /bin/bash "worker$i"; chmod 700 "/home/worker$i"; done; \
+    if dpkg -s sudo >/dev/null 2>&1; then apt-get remove -y --purge sudo; fi; \
+    passwd -l root

package/dist/assets/deploy/cloudflare-resident/gc.ts

@@ -0,0 +1,287 @@
+// Residency garbage collection — the PURE decision logic, kept free of
+// the Sandbox SDK and DO storage so it runs under plain-Node vitest
+// (gc.test.ts). worker.ts feeds it what it observed (mirror refs, the GitHub
+// pulls list, tree cleanliness, live views) and acts on the answers.
+//
+// Two mechanisms:
+//   1. Event-triggered reclamation: after every refresh-cycle `fetch --prune`,
+//      each live thread binding's ref is classified — branch gone from the
+//      mirror, or its PR merged/closed on GitHub — and a finished ref's
+//      worktree is evicted right away instead of waiting out the idle TTL.
+//      This is a POLL folded into the existing alarm, not a webhook: the
+//      GitHub App is configured with webhooks OFF (events: [], no hook
+//      config), and the fetch that already runs every cycle carries the
+//      "branch deleted" signal for free.
+//   2. Resident-level LRU eviction: an over-cap onboard with
+//      `evictColdest:true` (admin opt-in, default off) offboards the coldest
+//      eligible warm resident to make room instead of answering 429.
+
+// ---------------------------------------------------------------------------
+// 1. Reclamation
+// ---------------------------------------------------------------------------
+
+/** What GitHub says about a head branch's pull requests. */
+export interface PullSummary {
+  number: number;
+  state: "open" | "closed";
+  merged: boolean;
+}
+
+/** The fate of a thread's bound ref, as far as one refresh cycle can tell. */
+export type RefFate =
+  | "gone" // the branch no longer exists in the mirror after `fetch --prune`
+  | "merged" // no open PR; the latest PR for the head was merged
+  | "closed" // no open PR; PRs exist but none merged
+  | "open" // a PR is still open — work in progress
+  | "no-pr" // branch exists, no PR ever opened for it
+  | "unknown"; // GitHub could not be asked (unreachable / non-200 / unparsable)
+
+/** Defensive parse of `GET /repos/{o}/{r}/pulls?head=…&state=all`: a non-array
+ *  is null (an error object must never read as "no PRs"), malformed elements
+ *  are dropped rather than guessed at. */
+export function parsePullsBody(body: unknown): PullSummary[] | null {
+  if (!Array.isArray(body)) return null;
+  const out: PullSummary[] = [];
+  for (const el of body) {
+    if (!el || typeof el !== "object") continue;
+    const { number, state, merged_at } = el as Record<string, unknown>;
+    if (typeof number !== "number" || (state !== "open" && state !== "closed")) continue;
+    out.push({ number, state, merged: typeof merged_at === "string" && merged_at.length > 0 });
+  }
+  return out;
+}
+
+/** Parse `git for-each-ref --format='%(refname:short)' refs/heads/` output
+ *  into the set of branches the mirror holds — ONE spawn feeding every
+ *  binding's "branch gone?" membership test in the reclamation pass, instead
+ *  of a `rev-parse --verify` container round-trip per ref. */
+export function parseRefListing(stdout: string): Set<string> {
+  return new Set(
+    stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l !== ""),
+  );
+}
+
+/** Collapse a head's PR list into one fate. An open PR always wins (the
+ *  branch is still in play); otherwise merged beats closed. */
+export function pullsFate(pulls: readonly PullSummary[]): Extract<RefFate, "merged" | "closed" | "open" | "no-pr"> {
+  if (pulls.length === 0) return "no-pr";
+  if (pulls.some((p) => p.state === "open")) return "open";
+  if (pulls.some((p) => p.merged)) return "merged";
+  return "closed";
+}
+
+export interface ReclaimInput {
+  fate: RefFate;
+  /** The resident's default branch is never a finished ref. */
+  isDefaultRef: boolean;
+  /** Thread exec/read/write currently running on this binding. */
+  busy: number;
+  /** Tree cleanliness as the thread user; `null` = the runtime is down, so
+   *  the tree is already gone with the disk and there is nothing to preserve. */
+  clean: boolean | null;
+}
+
+/** The PR that decided the fate (for the audit trail): the open one, else the
+ *  merged one, else the newest closed one; null when there is none. */
+export function decisivePull(pulls: readonly PullSummary[]): PullSummary | null {
+  return pulls.find((p) => p.state === "open") ?? pulls.find((p) => p.merged) ?? pulls[0] ?? null;
+}
+
+export type ReclaimWhy =
+  | "default-ref"
+  | "pr-open"
+  | "no-pr"
+  | "fate-unknown"
+  | "busy"
+  | "re-attached"
+  | "dirty"
+  | Extract<RefFate, "gone" | "merged" | "closed">;
+
+/** Evict this binding now? A finished ref (gone/merged/closed) is reclaimed
+ *  only when nothing runs on it and its tree is provably clean — a merged PR
+ *  can still have unpushed local commits, and destroying work on a signal is
+ *  exactly what this must never do. Keeps are named so the pass is auditable. */
+export function reclaimDecision(input: ReclaimInput): { reclaim: boolean; why: ReclaimWhy } {
+  if (input.isDefaultRef) return { reclaim: false, why: "default-ref" };
+  switch (input.fate) {
+    case "open":
+      return { reclaim: false, why: "pr-open" };
+    case "no-pr":
+      return { reclaim: false, why: "no-pr" };
+    case "unknown":
+      return { reclaim: false, why: "fate-unknown" };
+  }
+  if (input.busy > 0) return { reclaim: false, why: "busy" };
+  if (input.clean === false) return { reclaim: false, why: "dirty" };
+  return { reclaim: true, why: input.fate };
+}
+
+// ---------------------------------------------------------------------------
+// 1b. Test overrides — lowering the effective cap / LRU floor for live checks
+// ---------------------------------------------------------------------------
+//
+// Why this exists: the over-cap behavior (429, `rejected[]`, the eviction and
+// its 1 h floor) is only reachable when the registry is FULL, and the
+// production cap (RESIDENT_CAP) is sized for the team's real fleet. Proving
+// item 46 the first time needed two deploys (cap 8→2, then →6) plus an hour of
+// clock time for the floor — and becomes impossible once six real residents
+// exist, because lowering the compiled cap below the fleet size would refuse
+// the team's own onboards. This is the resident's usual fault-injection
+// pattern (backdate-thread, force-down, force-onboarding …) applied to the
+// two limits: an admin-only debug op stores an override in the registry DO;
+// the registry enforces min(override, constant).
+//
+// Guard rails, by construction:
+//   - admin scope only (the /debug op is not in READ_DEBUG_OPS);
+//   - an override can only LOWER a limit — never above the compiled constant,
+//     so it can never become a back door past wrangler's max_instances;
+//   - deploy-scoped: the record carries the build marker it was set under and
+//     is ignored by any other build, so a forgotten test cap cannot outlive
+//     the session that set it;
+//   - visible: GET /residents reports the effective `cap` plus `capDefault`
+//     and the active `testOverrides`, so a dashboard never mistakes a test
+//     cap for the real one.
+
+/** The compiled limits the overrides may lower. */
+export interface LimitDefaults {
+  cap: number;
+  floorS: number;
+}
+
+/** What the registry DO stores. `build` is the identity of the deploy that
+ *  wrote it (`buildId`: the commit plus that build's timestamp); a different
+ *  build ignores the record. */
+export interface StoredTestOverrides {
+  cap?: number;
+  floorS?: number;
+  setAt: string;
+  build: string;
+}
+
+export type ParsedTestOverrides =
+  { overrides: { cap?: number; floorS?: number } } | { clear: true } | { error: string };
+
+/** Parse the `/debug {"op":"set-test-overrides", cap?, floorS?}` body.
+ *  Neither field → clear. Each present field must be an integer within
+ *  [1, cap] / [0, floorS] of the compiled defaults — overrides only lower. */
+export function parseTestOverrides(body: Record<string, unknown>, defaults: LimitDefaults): ParsedTestOverrides {
+  const out: { cap?: number; floorS?: number } = {};
+  if (body.cap !== undefined) {
+    if (typeof body.cap !== "number" || !Number.isInteger(body.cap) || body.cap < 1 || body.cap > defaults.cap) {
+      return {
+        error: `cap must be an integer between 1 and ${defaults.cap} (the compiled RESIDENT_CAP); overrides only lower it`,
+      };
+    }
+    out.cap = body.cap;
+  }
+  if (body.floorS !== undefined) {
+    if (
+      typeof body.floorS !== "number" ||
+      !Number.isInteger(body.floorS) ||
+      body.floorS < 0 ||
+      body.floorS > defaults.floorS
+    ) {
+      return {
+        error: `floorS must be an integer between 0 and ${defaults.floorS} (the compiled LRU_FLOOR_S); overrides only lower it`,
+      };
+    }
+    out.floorS = body.floorS;
+  }
+  if (out.cap === undefined && out.floorS === undefined) return { clear: true };
+  return { overrides: out };
+}
+
+export interface EffectiveLimits extends LimitDefaults {
+  /** The record in force, or null when none (or a stale one) applies. */
+  override: StoredTestOverrides | null;
+  /** Set when a stored record was ignored, naming why. */
+  ignored?: string;
+}
+
+/** The limits the registry enforces right now: the compiled defaults, lowered
+ *  by an override written under THIS build. Values are clamped to the
+ *  defaults even when stored (a later deploy may have lowered the constant). */
+export function effectiveLimits(
+  stored: StoredTestOverrides | undefined,
+  build: string,
+  defaults: LimitDefaults,
+): EffectiveLimits {
+  if (!stored) return { ...defaults, override: null };
+  if (stored.build !== build) return { ...defaults, override: null, ignored: `stale-build ${stored.build}` };
+  return {
+    cap: Math.min(defaults.cap, stored.cap ?? defaults.cap),
+    floorS: Math.min(defaults.floorS, stored.floorS ?? defaults.floorS),
+    override: stored,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 2. LRU eviction
+// ---------------------------------------------------------------------------
+
+/** One resident as the LRU picker sees it: registry record + live view.
+ *  `state: "unknown"` / `inFlight: null` model a live view that failed. */
+export interface ResidentView {
+  resource: string;
+  state: string;
+  inFlight: number | null;
+  onboardedAt: string;
+  provisionedAt: string | null;
+  threads: ReadonlyArray<{ lastAttachAt: string; evicted: boolean; user: string }>;
+}
+
+export interface EvictionPick {
+  candidate: { resource: string; lastActivityAt: string } | null;
+  rejected: Array<{ resource: string; why: string }>;
+}
+
+/** The newest thing that happened on the resident: an attach (evicted
+ *  bindings count — the run happened) or, never attached, provisioning. */
+export function lastActivityAt(view: ResidentView): string {
+  let latest = view.provisionedAt ?? view.onboardedAt;
+  for (const t of view.threads) if (t.lastAttachAt > latest) latest = t.lastAttachAt;
+  return latest;
+}
+
+/** Choose the coldest resident that is safe to offboard: `warm`, nothing in
+ *  flight, no LIVE worktree (a live tree may hold uncommitted work), and its
+ *  last activity older than `floorMs` (so a repo used minutes ago is never
+ *  evicted to make room). Coldest = oldest last activity; ties on name. */
+export function pickEvictionCandidate(views: readonly ResidentView[], nowMs: number, floorMs: number): EvictionPick {
+  const rejected: EvictionPick["rejected"] = [];
+  const eligible: Array<{ resource: string; lastActivityAt: string }> = [];
+  for (const v of views) {
+    if (v.state !== "warm") {
+      rejected.push({ resource: v.resource, why: `state ${v.state}` });
+      continue;
+    }
+    if (v.inFlight === null) {
+      rejected.push({ resource: v.resource, why: "in-flight count unknown" });
+      continue;
+    }
+    if (v.inFlight > 0) {
+      rejected.push({ resource: v.resource, why: `${v.inFlight} operation(s) in flight` });
+      continue;
+    }
+    const live = v.threads.filter((t) => !t.evicted && t.user).length;
+    if (live > 0) {
+      rejected.push({ resource: v.resource, why: `${live} live worktree(s)` });
+      continue;
+    }
+    const last = lastActivityAt(v);
+    const idleMs = nowMs - Date.parse(last);
+    if (!(idleMs >= floorMs)) {
+      rejected.push({
+        resource: v.resource,
+        why: `active ${Math.round(idleMs / 60_000)}m ago (floor ${Math.round(floorMs / 60_000)}m)`,
+      });
+      continue;
+    }
+    eligible.push({ resource: v.resource, lastActivityAt: last });
+  }
+  eligible.sort((a, b) => a.lastActivityAt.localeCompare(b.lastActivityAt) || a.resource.localeCompare(b.resource));
+  return { candidate: eligible[0] ?? null, rejected };
+}

package/dist/assets/deploy/cloudflare-resident/node-async-hooks.d.ts

@@ -0,0 +1,11 @@
+// The one Node API the resident Worker uses (docs/reference/specs/tracing.md item 19):
+// `AsyncLocalStorage` scopes a request's step trace to that request. Workers
+// provide it under `nodejs_compat`; the Worker's tsconfig types only
+// `@cloudflare/workers-types`, so the two members used are declared here
+// rather than pulling all of `@types/node` into the Worker's own check.
+declare module "node:async_hooks" {
+  export class AsyncLocalStorage<T> {
+    run<R>(store: T, callback: () => R): R;
+    getStore(): T | undefined;
+  }
+}

package/dist/assets/deploy/cloudflare-resident/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "switchboard-resident-worker",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check:image": "docker build --quiet .",
+    "deploy": "node preflight.mjs && node ../bin/build-stamp.mjs",
+    "preflight": "node preflight.mjs",
+    "dev": "wrangler dev",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "verify": "npm --prefix ../.. run --silent deploy:gen && npm run typecheck && npm test",
+    "typegen": "wrangler types",
+    "tail": "wrangler tail",
+    "secrets": "npm --prefix ../.. run --silent cli -- deploy secrets resident"
+  },
+  "dependencies": {
+    "@cloudflare/sandbox": "0.13.0-next.751.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260904.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.0",
+    "wrangler": "^4.129.0"
+  }
+}