@coreplane/switchboard 0.0.0 → 1.18.0

package/dist/assets/src/execution/sandboxErrors.ts

@@ -0,0 +1,159 @@
+// Fleet-capacity classification for the per-thread sandbox path
+// (docs/reference/specs/execution.md item 14): ONE recognizer and one answer shape, shared
+// by the sandbox Worker (which names the condition) and the bot's executor
+// (which waits on it). Deliberately free of node: imports so wrangler can
+// bundle it into the Worker, like bashTimeout.ts and shellQuote.ts.
+//
+// Why this exists: enough concurrent cold runs exhaust the sandbox fleet's
+// `max_instances`. The @cloudflare/sandbox 0.3.x client could not parse the
+// platform's plain-text "no instance available" 503 and threw the bare
+// `Failed to create session: 503`; carried in-body as an ordinary failure, the
+// executor threw ExecInfraError on it, and the runner's fail-fast breaker read
+// two of them in a row as a WEDGED sandbox and aborted the run within seconds.
+// A full fleet is capacity: nothing ran, nothing is broken, and the right
+// move is to wait for an instance. On 0.12.x the SDK throws a typed
+// `ContainerUnavailableError` (code `CONTAINER_UNAVAILABLE`) for the same
+// condition; the recognizer below takes the type first and the text second.
+
+/** The named reason the Worker answers with, mirroring the resident's
+ *  `mirror-busy` (resident-repos.md) — a machine token the executor matches
+ *  on, never the SDK's message text. */
+export const FLEET_BUSY_REASON = "fleet-busy" as const;
+
+/** What a full fleet means, in the words the model and the operator see. */
+export const FLEET_BUSY_EXPLANATION =
+  "no free per-thread sandbox — every container instance the fleet may run (wrangler.jsonc max_instances) is awake serving another thread";
+
+/** The executor waits at most this long for an instance — the default bash
+ *  budget, so a default command never waits past its own limit. A longer
+ *  command's wait is still capped here: waiting five minutes for a slot is
+ *  patience; waiting twenty is a run that should have said so. */
+export const FLEET_BUSY_WAIT_MAX_MS = 5 * 60_000;
+
+/** Backoff between re-sends: 10 s, 20 s, then 30 s until the wait is spent.
+ *  Slots free up when other threads' runs end (minutes), so sub-10 s polling
+ *  would only burn Worker requests. */
+export const FLEET_BUSY_BACKOFF_MS: readonly number[] = [10_000, 20_000, 30_000];
+
+/** The messages a full fleet produces, across SDK generations:
+ *  - `Failed to create session: 503` — the 0.3.x client's unparsed answer to
+ *    the base Container's plain-text 503;
+ *  - "no container instance that can be provided to this durable object" /
+ *    "no Container instance available" — the platform's own wording, which the
+ *    0.12.x SDK keeps as the message of its `ContainerUnavailableError`;
+ *  - `CONTAINER_UNAVAILABLE` — that error's JSON code, when a client prints it.
+ *  A stale session, a wedged sandbox, a file-op failure, or a 503 from
+ *  something a command itself contacted is NOT this. */
+const FLEET_BUSY_PATTERNS: readonly RegExp[] = [
+  /^Failed to create session: 503\b/i,
+  /no container instance (?:that can be provided|available)/i,
+  /\bCONTAINER_UNAVAILABLE\b/,
+];
+
+export function isFleetBusy(message: string): boolean {
+  const text = message.trim();
+  return text.length > 0 && FLEET_BUSY_PATTERNS.some((re) => re.test(text));
+}
+
+/** The 0.12.x SDK's typed class for a full fleet. Matched by NAME and by its
+ *  `code`, not `instanceof`: the Worker sees the error after it crossed the
+ *  Durable Object RPC boundary, which keeps `name`/`message` and drops the
+ *  prototype. Text stays as the second layer for older SDKs and for causes
+ *  the SDK wraps in a plain Error. */
+export const FLEET_BUSY_ERROR_NAME = "ContainerUnavailableError";
+
+/** The shape of anything thrown at the Worker — a typed SDK error, a plain
+ *  Error, or a string — reduced to what classification can read. */
+export interface ThrownShape {
+  name?: string;
+  code?: unknown;
+  message?: string;
+}
+
+export function thrownShape(err: unknown): ThrownShape {
+  if (err instanceof Error) {
+    return { name: err.name, code: (err as { code?: unknown }).code, message: err.message };
+  }
+  if (typeof err === "object" && err !== null) {
+    const o = err as ThrownShape;
+    return { name: o.name, code: o.code, message: typeof o.message === "string" ? o.message : String(err) };
+  }
+  return { message: String(err) };
+}
+
+/** Type first, text second: a `ContainerUnavailableError` (by name or code) or
+ *  any message `isFleetBusy` recognizes. */
+export function isFleetBusyError(err: unknown): boolean {
+  const s = thrownShape(err);
+  return (
+    s.name === FLEET_BUSY_ERROR_NAME || s.code === "CONTAINER_UNAVAILABLE" || (!!s.message && isFleetBusy(s.message))
+  );
+}
+
+/** The 0.12.x Durable Object's answer while its container is still booting:
+ *  no session exists yet and nothing ran, so the SAME request can be re-sent
+ *  after a short pause — the one retry the Worker still does itself. */
+export const CONTAINER_STARTING_PATTERN = /^Container is starting\. Please retry in a moment\.?$/i;
+
+export function isContainerStarting(err: unknown): boolean {
+  const { message } = thrownShape(err);
+  return !!message && CONTAINER_STARTING_PATTERN.test(message.trim());
+}
+
+/** The Worker's answer on /read and /write (sent as HTTP 503): the named
+ *  reason plus an `error` that keeps the SDK's own message as the cause, so
+ *  the logs and the model can still see what the platform actually said. */
+export function fleetBusyAnswer(cause: string): { error: string; reason: typeof FLEET_BUSY_REASON } {
+  return { error: `${FLEET_BUSY_REASON}: ${FLEET_BUSY_EXPLANATION} (${cause})`, reason: FLEET_BUSY_REASON };
+}
+
+/** The Worker's answer on /exec, in-body under the streamed HTTP 200 like every
+ *  other exec failure: the dual `error` + exit-127/stderr shape (item 3) so an
+ *  executor that predates in-body errors still renders it, plus the reason. */
+export function fleetBusyExecAnswer(cause: string): {
+  error: string;
+  reason: typeof FLEET_BUSY_REASON;
+  stdout: "";
+  stderr: string;
+  exitCode: 127;
+} {
+  const { error, reason } = fleetBusyAnswer(cause);
+  return { error, reason, stdout: "", stderr: error, exitCode: 127 };
+}
+
+/** The message `ExecCapacityError` carries once the wait is spent: names the
+ *  wait and the knob, and tells the reader this is a retry-later condition. */
+export function fleetBusyExhaustedMessage(waitedMs: number): string {
+  return (
+    `sandbox fleet busy — no free per-thread sandbox after waiting ${Math.round(waitedMs / 1000)}s ` +
+    "(the fleet's max_instances is reached); try again in a few minutes"
+  );
+}
+
+/** The text the Worker carries in-body for a thrown value: the SDK's own
+ *  message when it has one, else a sentence that says the SDK gave none —
+ *  naming the error's name and code, and the one condition known to produce
+ *  it. Never the empty string (docs/reference/specs/execution.md items 3 and 6).
+ *
+ *  Why: during a Worker+image rollout a new thread's Durable Object can land
+ *  on a container still running the previous (0.3.x) image. The 0.12.x
+ *  client posts `{command, sessionId}`, the old server
+ *  answered 400 `{"error": "Session ID and command are required"}`, and the
+ *  client built a `SandboxError` from a body with no `message` — so
+ *  `err.message` was `""`. The Worker's `shape.message ?? String(err)` kept
+ *  the empty string (`??` only fires on null/undefined), every classifier
+ *  fell through, and seven commands reached the model as silent `exit 127`s
+ *  that read as a dead shell. Classifiers (`isFleetBusyError`,
+ *  `isRecycleError`, `recycledMidCommandMessage`) keep reading the raw shape;
+ *  this is only the text that leaves the Worker. */
+export function thrownText(shape: ThrownShape): string {
+  const text = shape.message?.trim() ?? "";
+  if (text) return text;
+  const who = shape.name
+    ? `${shape.name}${shape.code !== undefined ? `, code ${String(shape.code)}` : ""}`
+    : "no error name";
+  return (
+    `sandbox exec failed with no message from the SDK (${who}); the container may still be running a previous image ` +
+    "while a Worker/image rollout is in progress — retry in a minute"
+  );
+}

package/dist/assets/src/execution/sandboxKeepalive.ts

@@ -0,0 +1,118 @@
+// Sandbox activity keepalive (docs/reference/specs/execution.md item 2): one in-flight
+// exec never outlives the container's activity timeout.
+//
+// On @cloudflare/containers 0.0.28 the base class kept an activity clock that
+// every proxied fetch renewed ONCE, before the fetch, and an alarm loop
+// stopped the container (SIGTERM) the moment the clock read expired — with no
+// notion of a request still in flight. So a single command running longer
+// than `sleepAfter` had its container killed under it, deterministically, at
+// exactly `sleepAfter`: the command ends in `Command execution failed` and
+// the next one lands in a fresh container with an empty /workspace. Renewing
+// the clock on a timer WHILE a command runs turns `sleepAfter` into what its
+// name says: idle time. The 0.3.x containers class that ships with sandbox
+// 0.12.x counts in-flight requests itself and refuses to expire while one is
+// open, so the keepalive is now belt-and-braces; it stays until a live
+// long-command run proves the SDK's own tracking on our path.
+//
+// Deliberately free of node: imports so wrangler can bundle it into the
+// sandbox Worker.
+
+/** How long an IDLE container stays warm before the Durable Object stops it,
+ *  in the Container class's own `<n>[smh]` grammar. With the keepalive below
+ *  (and the SDK's own in-flight tracking) this is pure idle time — a running
+ *  command can never reach it. 5 minutes frees a finished thread's slot
+ *  (`max_instances`) sooner than the SDK default (20 min on 0.3.x, 10 min on
+ *  0.12.x), while a follow-up inside 5 minutes still lands on the same warm
+ *  workspace; a later one re-clones, which is the documented per-thread
+ *  degradation (item 1). */
+export const SANDBOX_SLEEP_AFTER = "5m";
+
+/** How often a running command renews the activity clock. Well inside
+ *  SANDBOX_SLEEP_AFTER (the unit tests hold the ordering), so between two
+ *  renewals the clock always has minutes to spare. */
+export const EXEC_KEEPALIVE_INTERVAL_MS = 60_000;
+
+/** The Container class's `sleepAfter` grammar (`"5m"`, `"90s"`, `"1h"`), in
+ *  milliseconds — so a test can compare the interval against it. */
+export function parseSleepAfterMs(expr: string): number {
+  const m = /^(\d+)([smh])$/.exec(expr);
+  if (!m) throw new Error(`invalid sleepAfter expression: "${expr}" (expected <n>s, <n>m or <n>h)`);
+  const n = Number(m[1]);
+  return n * (m[2] === "s" ? 1_000 : m[2] === "m" ? 60_000 : 3_600_000);
+}
+
+/** Run `run()` while calling `renew()` every `intervalMs` until it settles —
+ *  resolve or reject alike. A renew that throws or rejects is swallowed: the
+ *  keepalive exists to protect the command's result, never to replace it. A
+ *  command that finishes inside one interval never triggers a renew. */
+export async function withActivityKeepalive<T>(
+  renew: () => void | Promise<void>,
+  run: () => Promise<T>,
+  intervalMs: number,
+): Promise<T> {
+  const timer = setInterval(() => {
+    try {
+      void Promise.resolve(renew()).catch(() => {});
+    } catch {
+      // a synchronous throw from renew — same policy as an async rejection
+    }
+  }, intervalMs);
+  try {
+    return await run();
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+/** The texts the SDK produces when the container is torn down under a
+ *  command, across generations. 0.3.x: the exec handler's generic wrapper (its
+ *  real cause, "Session terminated", sat in a field the client discarded), the
+ *  cause itself, and the stale-session answer the same attempt got once the
+ *  sessions were cleared. 0.12.x: the typed `SessionTerminatedError` text
+ *  (`Session '<id>' shell exited (exit code: <n>)`) and the
+ *  `OperationInterruptedError` text for a container that stopped under a
+ *  pending call, and the disconnect text for a sandbox `destroy()`ed under a
+ *  pending call. Anything else — a transport error, a file-op failure — is
+ *  never recycle-shaped, whenever it arrives. */
+const RECYCLE_SHAPED: readonly RegExp[] = [
+  /^Command execution failed$/,
+  /^Session terminated$/i,
+  /^Session '[^']*' not found$/i,
+  /^Session '[^']*' shell exited \(exit code: /i,
+  /^The sandbox container stopped while the operation was pending\.?$/i,
+  /^The sandbox was destroyed while the operation was pending\.?$/i,
+];
+
+/** The 0.12.x typed errors that MEAN the container went away under the call.
+ *  Matched by name, not `instanceof`: the Worker sees them after the Durable
+ *  Object RPC boundary, which keeps `name`/`message` and drops the prototype. */
+export const RECYCLE_ERROR_NAMES: readonly string[] = ["SessionTerminatedError", "OperationInterruptedError"];
+
+/** Type first, text second: a typed recycle error, or a recycle-shaped text. */
+export function isRecycleError(err: { name?: string; message?: string }): boolean {
+  if (err.name && RECYCLE_ERROR_NAMES.includes(err.name)) return true;
+  return !!err.message && RECYCLE_SHAPED.some((re) => re.test(err.message!.trim()));
+}
+
+/** Grace inside which a recycle-shaped TEXT is taken at face value: a session
+ *  that fails to start does so in seconds, not minutes. A typed recycle error
+ *  needs no grace — the SDK is stating the container stopped. */
+const RECYCLE_SUSPECT_AFTER_MS = 60_000;
+
+/** The message `/exec` puts in-body when a command's failure looks like the
+ *  container was recycled under it: a typed recycle error (`certain`), or a
+ *  recycle-shaped text that arrived more than a minute into THIS attempt (a
+ *  startup failure shows in seconds). Any other text, however late, is
+ *  returned unchanged — timing alone never rewords an unrelated error. The exit
+ *  code stays 127: it IS an infra failure — the workspace really is gone — and
+ *  a faked exit 124 would tell the model to shorten a command that was never
+ *  the problem. */
+export function recycledMidCommandMessage(elapsedMs: number, msg: string, certain = false): string {
+  const shaped = RECYCLE_SHAPED.some((re) => re.test(msg.trim()));
+  if (!certain && (!shaped || elapsedMs <= RECYCLE_SUSPECT_AFTER_MS)) return msg;
+  const secs = Math.round(elapsedMs / 1_000);
+  return (
+    `sandbox recycled mid-command after ${secs}s — the container was replaced and /workspace is empty; ` +
+    `re-clone before continuing (${msg})`
+  );
+}

package/dist/assets/src/execution/shellQuote.ts

@@ -0,0 +1,8 @@
+/** POSIX single-quote escaping so an arbitrary command survives `bash -c`.
+ *  Pure and dependency-free — lives in src/ (inside the root tsconfig's
+ *  rootDir) and is imported across packages by the sandbox proxy Worker
+ *  (deploy/cloudflare-sandbox/worker.ts; wrangler's bundler follows the
+ *  relative import), so the tested code IS the shipped code. */
+export function shellQuote(s: string): string {
+  return `'${s.replaceAll("'", `'\\''`)}'`;
+}

package/dist/assets/src/mcp/registry.ts

@@ -0,0 +1,242 @@
+// The MCP server contract shared by the config layer, the bot's service, and
+// the state Worker (docs/reference/specs/mcp-tools.md items 11–17). Node-free and I/O-free:
+// `deploy/cloudflare-memory/worker.ts` imports the ticket and sealed-credential
+// validators by relative path so both ends check one shape. A server is a
+// `Scope` setting (`Scope.mcpServers[name]`, src/config.ts) — resolved through
+// the same `defaults → channel → user` layers as models and instructions —
+// never a record in a parallel store. Credentials are never part of an entry:
+// they are sealed blobs keyed by `<scopeKey>/<name>`, opened only by the bot.
+
+/** `none`: no Authorization header. `bearer`: a static token — `tokenEnv` on
+ *  the bot, or one pasted on the connect page and sealed. `oauth`: OAuth 2.1
+ *  (item 18) — the connect page sends the person to the server's authorization
+ *  server; the sealed credential is the token set the callback exchanged. */
+export type McpAuthKind = "none" | "bearer" | "oauth";
+
+/** One server as a scope carries it. `tokenEnv` is the static-config way to
+ *  supply a bearer (an env var on the bot); without it a bearer server's token
+ *  is the sealed credential the connect page stored. */
+export interface McpServerEntry {
+  url: string;
+  /** Agents whose runs may see it (default general + research). */
+  agents?: string[];
+  auth: McpAuthKind;
+  tokenEnv?: string;
+  /** Who added it at run time (`slack:U…`, `cli:local`); absent for static config. */
+  addedBy?: string;
+  addedAt?: number;
+}
+
+/** The three tiers a server can live in, in precedence order for a name clash. */
+export type McpScopeKind = "org" | "channel" | "user";
+
+/** `org` | `channel:<platform-namespaced id>` | `user:<platform-namespaced id>`
+ *  — the first half of a credential key. */
+export function mcpScopeKey(kind: McpScopeKind, id?: string): string {
+  if (kind === "org") return "org";
+  if (!id) throw new Error(`${kind} scope needs an id`);
+  return `${kind}:${id}`;
+}
+
+export function parseMcpScopeKey(key: string): { kind: McpScopeKind; id?: string } | undefined {
+  if (key === "org") return { kind: "org" };
+  for (const kind of ["channel", "user"] as const) {
+    const prefix = `${kind}:`;
+    if (key.startsWith(prefix) && key.length > prefix.length) return { kind, id: key.slice(prefix.length) };
+  }
+  return undefined;
+}
+
+/** `<scopeKey>/<name>` — the credential and ticket key; unique across tiers. */
+export function mcpCredentialKey(scopeKey: string, name: string): string {
+  return `${scopeKey}/${name}`;
+}
+
+export function splitCredentialKey(key: string): { scopeKey: string; name: string } | undefined {
+  const slash = key.lastIndexOf("/");
+  if (slash <= 0) return undefined;
+  const scopeKey = key.slice(0, slash);
+  const name = key.slice(slash + 1);
+  return parseMcpScopeKey(scopeKey) && MCP_SERVER_NAME_RE.test(name) ? { scopeKey, name } : undefined;
+}
+
+/** An encrypted credential as stored — opaque to the Worker. `keyId` names
+ *  the KEK generation; the credential key is the GCM additional data. */
+export interface SealedCredential {
+  /** `<scopeKey>/<name>` */
+  serverId: string;
+  keyId: string;
+  /** base64: 12-byte IV ‖ AES-256-GCM ciphertext+tag */
+  sealed: string;
+  updatedAt: number;
+}
+
+/** The connect flow's state machine (item 15). One ticket per `mcp add`/
+ *  `mcp connect`; single use; bound to the requester. */
+export type McpTicketState = "pending" | "opened" | "authorizing" | "completed" | "cancelled";
+/** Every state, for the Worker's route validation — one list, both ends. */
+export const MCP_TICKET_STATES: readonly McpTicketState[] = [
+  "pending",
+  "opened",
+  "authorizing",
+  "completed",
+  "cancelled",
+];
+
+export interface McpTicket {
+  nonce: string;
+  /** `<scopeKey>/<name>` */
+  serverId: string;
+  /** The chat/CLI identity that asked (`slack:U…`, `cli:local`). */
+  requesterId: string;
+  /** Resolved when the channel could (Slack `users:read.email`); the connect
+   *  page then requires the Access identity's email to match. */
+  requesterEmail?: string;
+  createdAt: number;
+  expiresAt: number;
+  state: McpTicketState;
+  /** Without `requesterEmail`, the FIRST Access identity to open the page is
+   *  bound and the completion must come from the same identity. */
+  openedBy?: { sub: string; email?: string; at: number };
+  completedBy?: { sub: string; email?: string; at: number };
+  /** OAuth (item 18): the pending authorization — PKCE verifier, client id,
+   *  `state`, endpoints — sealed under the bot's key (AAD `ticket:<nonce>`)
+   *  while the person is at the authorization server. Set when the ticket
+   *  enters `authorizing`; opaque to the Worker. */
+  oauth?: { keyId: string; sealed: string };
+  /** Set with `completed` (item 19): what the completion found, so the thread
+   *  that asked can be told without re-probing — the bridged tool count, or
+   *  the verify warning when the server could not be reached. */
+  outcome?: { toolCount?: number; warning?: string };
+}
+
+export const MCP_TICKET_TTL_MS = 10 * 60_000;
+export const MCP_SERVER_NAME_MAX = 32;
+export const MCP_SERVER_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+export const MCP_URL_MAX = 2_048;
+export const MCP_AGENTS_MAX = 8;
+/** Agents a CHANNEL- or USER-scoped server may reach — never the code-writing
+ *  or read-only-by-contract agents (item 14); only an org server (admins) may. */
+export const MCP_SELF_SERVE_AGENTS: readonly string[] = ["general", "research"];
+export const MCP_TOKEN_MAX_CHARS = 8_192;
+export const MCP_SERVERS_PER_SCOPE_MAX = 32;
+
+// ---- structural validators (both ends) --------------------------------------
+
+const isStr = (v: unknown, max = 4_096): v is string => typeof v === "string" && v.length > 0 && v.length <= max;
+const isNum = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+
+function isOutcome(v: unknown): v is NonNullable<McpTicket["outcome"]> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const o = v as Record<string, unknown>;
+  return (
+    (o.toolCount === undefined || (isNum(o.toolCount) && o.toolCount >= 0)) &&
+    (o.warning === undefined || isStr(o.warning, 1_024))
+  );
+}
+
+/** Shape only (the config layer adds the semantic checks: SSRF, known agents, tier rules). */
+export function isMcpServerEntry(v: unknown): v is McpServerEntry {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const e = v as Record<string, unknown>;
+  return (
+    isStr(e.url, MCP_URL_MAX) &&
+    (e.agents === undefined ||
+      (Array.isArray(e.agents) &&
+        e.agents.length > 0 &&
+        e.agents.length <= MCP_AGENTS_MAX &&
+        e.agents.every((a) => isStr(a, 32)))) &&
+    (e.auth === "none" || e.auth === "bearer" || e.auth === "oauth") &&
+    (e.tokenEnv === undefined || isStr(e.tokenEnv, 128)) &&
+    (e.addedBy === undefined || isStr(e.addedBy, 260)) &&
+    (e.addedAt === undefined || isNum(e.addedAt))
+  );
+}
+
+export function isSealedCredential(v: unknown): v is SealedCredential {
+  if (!v || typeof v !== "object") return false;
+  const c = v as Record<string, unknown>;
+  return isStr(c.serverId, 400) && isStr(c.keyId, 64) && isStr(c.sealed, 64 * 1024) && isNum(c.updatedAt);
+}
+
+export function isMcpTicket(v: unknown): v is McpTicket {
+  if (!v || typeof v !== "object") return false;
+  const t = v as Record<string, unknown>;
+  const actor = (a: unknown) =>
+    a === undefined ||
+    (!!a && typeof a === "object" && isStr((a as { sub?: unknown }).sub, 260) && isNum((a as { at?: unknown }).at));
+  return (
+    isStr(t.nonce, 128) &&
+    /^[A-Za-z0-9_-]{16,128}$/.test(t.nonce) &&
+    isStr(t.serverId, 400) &&
+    isStr(t.requesterId, 260) &&
+    (t.requesterEmail === undefined || isStr(t.requesterEmail, 320)) &&
+    isNum(t.createdAt) &&
+    isNum(t.expiresAt) &&
+    MCP_TICKET_STATES.includes(t.state as McpTicketState) &&
+    actor(t.openedBy) &&
+    actor(t.completedBy) &&
+    (t.oauth === undefined ||
+      (!!t.oauth &&
+        typeof t.oauth === "object" &&
+        isStr((t.oauth as { keyId?: unknown }).keyId, 64) &&
+        isStr((t.oauth as { sealed?: unknown }).sealed, 64 * 1024))) &&
+    (t.outcome === undefined || isOutcome(t.outcome))
+  );
+}
+
+/** A server as surfaces show it: never a credential, and the URL reduced to
+ *  its origin + path (a query string could carry a key). */
+export interface McpServerView {
+  name: string;
+  scope: McpScopeKind;
+  scopeKey: string;
+  url: string;
+  agents: string[];
+  auth: McpAuthKind;
+  /** `static` = bearer from `tokenEnv` on the bot; `connected` = a sealed
+   *  credential is stored (or no credential is needed); `awaiting_credential`
+   *  = bearer, nothing stored yet. */
+  state: "connected" | "awaiting_credential" | "static";
+  source: "config" | "runtime";
+  addedBy?: string;
+  addedAt?: number;
+}
+
+export function serverView(
+  scopeKey: string,
+  name: string,
+  entry: McpServerEntry,
+  opts: { hasCredential: boolean; source: "config" | "runtime" },
+): McpServerView {
+  const parsed = parseMcpScopeKey(scopeKey);
+  const state: McpServerView["state"] =
+    entry.auth === "none"
+      ? "connected"
+      : entry.tokenEnv
+        ? "static"
+        : opts.hasCredential
+          ? "connected"
+          : "awaiting_credential";
+  return {
+    name,
+    scope: parsed?.kind ?? "org",
+    scopeKey,
+    url: safeUrl(entry.url),
+    agents: [...(entry.agents ?? MCP_SELF_SERVE_AGENTS)],
+    auth: entry.auth,
+    state,
+    source: opts.source,
+    ...(entry.addedBy ? { addedBy: entry.addedBy } : {}),
+    ...(entry.addedAt !== undefined ? { addedAt: entry.addedAt } : {}),
+  };
+}
+
+export function safeUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return "(invalid url)";
+  }
+}