@coreplane/switchboard 1.247.0 → 1.249.0

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

@@ -9,37 +9,63 @@ organization: acme
 
 providers:
   anthropic:
-    type: anthropic
+    wire: anthropic-messages
     apiKeyEnv: ANTHROPIC_API_KEY
-  # OpenAI itself runs on the same compatible adapter: any preset's model may
-  # be openai/<model-id> anywhere a model is accepted. The adapter speaks Chat
-  # Completions, not the Responses API, sends no reasoning control (our effort
-  # tiers do not reach these models), and meters tokens without pricing them.
-  # A first-class OpenAI block is a plan's business, not this file's.
+  # OpenAI itself runs on its Responses API (record 0052): every first-party
+  # OpenAI card in pi's registry is `openai-responses`, OpenAI recommends the
+  # wire for new projects, and its chat route loses tool calling with any
+  # effort above `none` from GPT-5.4. The wire is a declaration here; the proxy
+  # serves the Responses route in a later unit, and until then a run on this
+  # block meets the provider's own answer. `type: openai-compatible` keeps
+  # loading as `wire: openai-chat` for one release.
   openai:
-    type: openai-compatible
+    wire: openai-responses
     baseUrl: https://api.openai.com/v1
     apiKeyEnv: OPENAI_API_KEY
   # groq:
-  #   type: openai-compatible
+  #   wire: openai-chat
   #   baseUrl: https://api.groq.com/openai/v1
   #   apiKeyEnv: GROQ_API_KEY
-  # OpenRouter: one key, many vendors' models, on the same compatible adapter.
-  # Its model ids already carry the vendor, so any preset's model may be
-  # openrouter/<vendor>/<model> — e.g. openrouter/anthropic/claude-sonnet-4:
+  # OpenRouter: one key, many vendors' models, an aggregator (`vendor: model`
+  # reads the vendor off the model id's first segment, so the card is per block
+  # AND vendor: a tier the OpenRouter file refuses may be native direct).
+  # `catalog: openrouter` names the pi registry file its cards come from; a
+  # block named unlike its catalog still reads that file. Any preset's model
+  # may be openrouter/<vendor>/<model> — e.g. openrouter/anthropic/claude-sonnet-4:
   # the first slash names this block, the rest is the model id passed through.
   # OPENROUTER_API_KEY is read at the first model call, never at load, so
   # without it every other block runs as today and only a run on this one
-  # fails, by that name. Effort tiers, documents and prompt caching ride the
-  # compatible adapter as far as it carries them: pi applies its OpenRouter
-  # rules (prompt-cache markers included); a document becomes a text note.
-  # `switchboard init` keeps this block only with --openrouter-key.
+  # fails, by that name. `switchboard init` keeps this block only with
+  # --openrouter-key.
   openrouter:
-    type: openai-compatible
+    wire: openai-chat
+    vendor: model
+    catalog: openrouter
     baseUrl: https://openrouter.ai/api/v1
     apiKeyEnv: OPENROUTER_API_KEY
+    # The operator's layer over the registry card: what a run needs that no
+    # layer names goes out unvouched (and a note says so on the record) until
+    # an override like this pins it. `providers check` (a later unit) reads the
+    # provider's own endpoint to fill these in.
+    # models:
+    #   deepseek/deepseek-v4.1-flash:
+    #     window: 1048576
+    #     capField: max_tokens
+    #     levels:
+    #       high: high
+    #       xhigh: xhigh
+    #     inputs:
+    #       image: true
+    #     cache: automatic
+    # A passthrough is merged into the request body on the wires whose adapter
+    # takes one — a vendor-only feature such as OpenRouter's routing, never a
+    # control: it is not decided, not noted and not in the matrix, and a wrong
+    # one surfaces as the provider's own error on the first turn.
+    # passthrough:
+    #   provider:
+    #     sort: throughput
   # local:
-  #   type: openai-compatible
+  #   wire: openai-chat
   #   baseUrl: http://localhost:11434/v1   # Ollama
 
 defaults:

package/dist/assets/deploy/cloudflare/preflight.mjs

@@ -1,22 +1,23 @@
 #!/usr/bin/env node
 // Deploy preflight for the bot Worker (docs/reference/specs/slack-channel.md item 8).
 //
-// `wrangler deploy` rolls the bot container. Cloudflare's rollout sends SIGTERM;
-// since the run ledger's handoff (docs/reference/specs/run-history.md item 39) the bot
-// hands every resumable run to the next generation and exits within seconds,
-// and the next generation continues the runs under their own cards — so a
-// deploy no longer waits on runs, and this preflight no longer refuses for
-// them. `npm run deploy` runs it first and refuses only while
+// `wrangler deploy` rolls the bot container. Cloudflare's rollout sends SIGTERM
+// and the container is gone at the drain's end, whatever it was still driving:
+// the run ledger's handoff (docs/reference/specs/run-history.md item 39) lets the
+// next generation resume a run, but a resume is a recovery, not a guarantee —
+// one that fails costs the run — so a deploy never rolls over a live run.
+// `npm run deploy` runs this first and refuses while
+//   - the bot reports runs in flight (`GET /healthz` `inFlight > 0`): the
+//     runner retries every minute up to its budget, then fails by name;
 //   - the container application is not in a settled state (a rollout is still
 //     provisioning/updating — `wrangler containers list --json`): a second
 //     rollout on top of one in progress replaces the instance the first put
 //     into its graceful drain and kills whatever it was running (two deploys
 //     90 s apart once killed a review at 153 s).
-// It WARNS (never refuses) when the bot reports runs in flight (`inFlight > 0`
-// — they hand off) or is already draining (`draining: true` — its resumable
-// runs were handed off; a ship pipeline still in flight would be killed), and
-// when /healthz says the reconnect catch-up is failing or the bot token lacks
-// required scopes (`catchUp.error`, `catchUp.missingScopes`).
+// It WARNS (never refuses) when the bot is already draining with nothing in
+// flight (`draining: true` — the instance exits on its own), and when /healthz
+// says the reconnect catch-up is failing or the bot token lacks required
+// scopes (`catchUp.error`, `catchUp.missingScopes`).
 //
 // Fail closed: unreachable bot, a body without the JSON shape (a bot whose
 // /healthz answers a bare `ok` is not one this preflight can read), a wrangler failure, or an app
@@ -40,7 +41,7 @@ export const APP_NAME = "switchboard-switchboardserver";
 const SETTLED_APP_STATES = new Set(["active", "ready"]);
 
 const HOW_TO_FORCE =
-  "to deploy anyway (over a rollout in progress, or blind when the bot cannot be consulted): `SWITCHBOARD_DEPLOY_FORCE=1 npm run deploy` (`node preflight.mjs --force` checks alone)";
+  "to deploy anyway (over the runs in flight — this kills them —, over a rollout in progress, or blind when the bot cannot be consulted): `SWITCHBOARD_DEPLOY_FORCE=1 npm run deploy` (`node preflight.mjs --force` checks alone)";
 
 /** GET /healthz. Never throws: `{ok:true,payload}` (parsed JSON, or the raw text when not JSON) or `{ok:false,error}`. */
 export async function fetchHealth(baseUrl, { timeoutMs = 20_000 } = {}) {
@@ -164,15 +165,16 @@ export function decide({ health, apps }, { force = false } = {}) {
       if (!Number.isInteger(p.inFlight) || p.inFlight < 0) {
         problems.push(`bot reports an impossible inFlight=${JSON.stringify(p.inFlight)} (counter bug or old Worker)`);
       } else if (p.inFlight > 0) {
-        // Not a refusal since the handoff (run-history item 39): SIGTERM hands
-        // every resumable run to the next generation, which continues it.
-        warnings.push(
-          `${p.inFlight} run(s) in flight — handed to the next generation on SIGTERM (run-history item 39); they continue there under their own cards`,
+        // A refusal: the rollout rolls the container under these runs. A
+        // handoff (run-history item 39) may resume them on the next generation,
+        // but a resume that fails costs the run — the deploy waits instead.
+        problems.push(
+          `${p.inFlight} run(s) in flight — the rollout would roll the bot container under them (a handoff is a recovery, not a guarantee)`,
         );
       }
       if (p.draining === true) {
         warnings.push(
-          "bot is already draining from a previous deploy — its resumable runs are handed off; a ship pipeline still in flight would be killed when this rollout replaces the draining instance",
+          "bot is already draining from a previous deploy — the draining instance exits on its own; this rollout replaces it at once",
         );
       }
     }
@@ -209,7 +211,7 @@ export function decide({ health, apps }, { force = false } = {}) {
       forced: true,
       problems,
       warnings,
-      message: `preflight WARNING: deploying by force despite —\n${detail}\n  a rollout landing on one in progress can disrupt it; in-flight runs hand off regardless (run-history item 39)${warningText}`,
+      message: `preflight WARNING: deploying by force despite —\n${detail}\n  this WILL kill the runs in flight that no resume recovers, and a rollout landing on one in progress can disrupt it${warningText}`,
     };
   }
   return {
@@ -217,7 +219,7 @@ export function decide({ health, apps }, { force = false } = {}) {
     forced: false,
     problems,
     warnings,
-    message: `preflight REFUSED: a Worker deploy rolls the bot container —\n${detail}\n  wait and retry; ${HOW_TO_FORCE}${warningText}`,
+    message: `preflight REFUSED: a Worker deploy rolls the bot container —\n${detail}\n  wait for them to finish and retry; ${HOW_TO_FORCE}${warningText}`,
   };
 }
 

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

@@ -749,6 +749,26 @@ export class ConfigDO extends DurableObject<Env> {
     });
   }
 
+  /** Delete the thread's pending row under the same requester check (record
+   *  0054: a typed answer supersedes the button, so a click cannot follow
+   *  it). At most one row per thread exists (`putConfirmation` replaces); a
+   *  thread with none is `used`. The body stays opaque here — a row stored
+   *  before the bot's union gained `kind` cancels the same way. */
+  async cancelConfirmationByThread(threadKey: string, actorIds: readonly string[]): Promise<ConfirmationCancelOutcome> {
+    return this.ctx.storage.transactionSync(() => {
+      const stored = this.sql
+        .exec<{ id: string; requester: string }>(
+          `SELECT id, requester FROM confirmations WHERE thread_key = ?`,
+          threadKey,
+        )
+        .toArray()[0];
+      if (!stored) return { refused: "used" };
+      if (!actorIds.includes(stored.requester)) return { refused: "foreign" };
+      this.sql.exec(`DELETE FROM confirmations WHERE id = ?`, stored.id);
+      return { ok: true };
+    });
+  }
+
   private readConfirmation(id: string): ConfirmationRow | undefined {
     const row = this.sql
       .exec<{ thread_key: string; requester: string; expires_at: number; body: string }>(
@@ -1168,6 +1188,7 @@ const CONFIG_ROUTES = new Set([
   "/config/confirmations/put",
   "/config/confirmations/consume",
   "/config/confirmations/cancel",
+  "/config/confirmations/cancel-by-thread",
 ]);
 const TICKET_STATES: ReadonlySet<string> = new Set<McpTicketState>(MCP_TICKET_STATES);
 /** A confirmation id as the bot mints it (a UUID) — one token, no whitespace, bounded. */
@@ -1253,6 +1274,16 @@ async function handleConfig(pathname: string, body: unknown, env: Env): Promise<
       console.log(`[config/confirmations/cancel] ${click.id} ${"ok" in outcome ? "cancelled" : outcome.refused}`);
       return json(outcome);
     }
+    case "/config/confirmations/cancel-by-thread": {
+      if (typeof b.threadKey !== "string" || !b.threadKey) return json({ error: "threadKey required" }, 400);
+      if (!Array.isArray(b.actorIds) || !b.actorIds.every((a): a is string => typeof a === "string"))
+        return json({ error: "actorIds must be a list of actor ids" }, 400);
+      const outcome = await dO.cancelConfirmationByThread(b.threadKey, b.actorIds);
+      console.log(
+        `[config/confirmations/cancel-by-thread] ${b.threadKey} ${"ok" in outcome ? "cancelled" : outcome.refused}`,
+      );
+      return json(outcome);
+    }
     default:
       break;
   }

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

@@ -0,0 +1,109 @@
+// The fleet drain (docs/reference/specs/resident-repos.md item 69): one record
+// in the registry Durable Object that closes `POST /attach` to NEW runs while a
+// deploy waits for the runs already in flight to end — a run registered from
+// its attach to its release re-attaches through it (a rolled container, an
+// evicted worktree, a resumed run), so the drain never refuses a run it waits for. Pure over its inputs so
+// it runs under plain Node (drain.test.ts); the Worker holds the storage and
+// the routes, and the deploy runner (src/deploy/residentDrain.ts) the other end.
+//
+// Why a record with an end and not a flag: Durable Object storage survives the
+// isolate swap the deploy performs, so a drain nobody lifted — a runner that
+// died mid-step — would close the fleet for good. Every drain carries `until`;
+// past it the record is nothing, whoever forgot it.
+
+import { DRAIN, minutesToMs } from "../../src/core/budgets.js";
+
+/** The drain as the registry stores it. */
+export interface DrainRecord {
+  /** ISO time the drain began. */
+  since: string;
+  /** ISO time it ends by itself, whether or not anyone lifts it. */
+  until: string;
+  /** Who asked (the deploy names its commit). */
+  by: string;
+  /** Why, in the words the attach refusal repeats. */
+  reason: string;
+}
+
+/** The longest a drain may run, and the default, from the one clock table
+ *  (src/core/budgets.ts `DRAIN`): past a coding child's whole lease with room
+ *  for the deploy itself, and short enough that a forgotten drain is an hour
+ *  and a half, not a day. */
+export const DRAIN_MAX_MINUTES: number = DRAIN.maxMinutes;
+export const DRAIN_DEFAULT_MINUTES: number = DRAIN.defaultMinutes;
+const REASON_MAX = 200;
+const BY_MAX = 80;
+
+export type DrainRequest = { ok: true; record: DrainRecord } | { ok: false; error: string };
+
+/** `POST /drain`'s body → the record, or the refusal by name. `minutes` is an
+ *  integer in [1, DRAIN_MAX_MINUTES] (default DRAIN_DEFAULT_MINUTES); `reason`
+ *  and `by` are short strings with defaults. A malformed value is refused,
+ *  never clamped silently: a drain is an operator's act and its words are read
+ *  back by every run it refuses. */
+export function parseDrainRequest(body: Record<string, unknown>, now: number): DrainRequest {
+  let minutes = DRAIN_DEFAULT_MINUTES;
+  if (body.minutes !== undefined) {
+    if (typeof body.minutes !== "number" || !Number.isInteger(body.minutes))
+      return { ok: false, error: "minutes must be an integer number of minutes" };
+    if (body.minutes < 1 || body.minutes > DRAIN_MAX_MINUTES)
+      return { ok: false, error: `minutes must be between 1 and ${DRAIN_MAX_MINUTES}` };
+    minutes = body.minutes;
+  }
+  const word = (v: unknown, name: string, max: number, fallback: string): string | { error: string } => {
+    if (v === undefined) return fallback;
+    if (typeof v !== "string" || v.trim() === "") return { error: `${name} must be a non-empty string` };
+    const trimmed = v.trim();
+    if (trimmed.length > max) return { error: `${name} must be at most ${max} characters` };
+    return trimmed;
+  };
+  const reason = word(body.reason, "reason", REASON_MAX, "a deploy");
+  if (typeof reason !== "string") return { ok: false, error: reason.error };
+  const by = word(body.by, "by", BY_MAX, "admin");
+  if (typeof by !== "string") return { ok: false, error: by.error };
+  return {
+    ok: true,
+    record: {
+      since: new Date(now).toISOString(),
+      until: new Date(now + minutesToMs(minutes)).toISOString(),
+      by,
+      reason,
+    },
+  };
+}
+
+/** The drain in force at `now`: the stored record when it is well-formed and
+ *  its `until` is still ahead; null for none, an expired one, or a record this
+ *  build cannot read (a shape from another build reads as no drain, never as a
+ *  closed fleet). */
+export function liveDrain(stored: unknown, now: number): DrainRecord | null {
+  if (typeof stored !== "object" || stored === null) return null;
+  const r = stored as Record<string, unknown>;
+  if (
+    typeof r.since !== "string" ||
+    typeof r.until !== "string" ||
+    typeof r.by !== "string" ||
+    typeof r.reason !== "string"
+  )
+    return null;
+  const until = Date.parse(r.until);
+  if (!Number.isFinite(until) || until <= now) return null;
+  return { since: r.since, until: r.until, by: r.by, reason: r.reason };
+}
+
+/** The `/attach` answer while the fleet is drained: a 503 whose body carries
+ *  the record, so the bot waits for `until` at most and the card says why the
+ *  run has not started. The `error` word `draining:` is the client's key. */
+export function drainRefusal(drain: DrainRecord): {
+  error: string;
+  status: 503;
+  draining: DrainRecord;
+} {
+  return {
+    error:
+      `draining: the resident fleet is closed to new runs for ${drain.reason} (asked by ${drain.by} at ${drain.since}, ` +
+      `ends by ${drain.until}) — the run waits at its attach and starts when the fleet reopens`,
+    status: 503,
+    draining: drain,
+  };
+}

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

@@ -11,8 +11,10 @@ import {
   isRuntimeUnreachableSignal,
   selfAndCauses,
 } from "../../src/execution/residentRefresh.js";
+import { isRuntimeBusyError, RUNTIME_BUSY_REASON } from "../../src/execution/sandboxErrors.js";
 import type { ResidentLifecycleState } from "../../src/execution/residentState.js";
 import type { ResidentStep } from "../../src/execution/residentStepTrace.js";
+import type { RefusalCause } from "../../src/core/refusal.js";
 
 // The cause-chain walker has one home, beside the wording lists; the Worker
 // takes it from here with the rest of the thread data plane's shapes.
@@ -52,6 +54,12 @@ export interface ThreadErr {
   defaultRef?: string;
   state?: ResidentLifecycleState;
   reason?: string;
+  /** Why the route refused, in the seam's three classes (record 0054), so the
+   *  caller reads a field instead of the words: a bad ref or a missing binding
+   *  is `request`, a repository the App cannot see is `policy`, and the
+   *  machinery's own failure is `system`. The words stay for the person; the
+   *  cause is what the bot's command surfaces render by. */
+  cause?: RefusalCause;
 }
 
 /** Where a replacement or a reset was met: the command's spawn or its collect
@@ -143,7 +151,7 @@ export class ControlResetError extends Error {
  *  as an `/exec` script). Gating them would trade a spare re-attach for a read
  *  that fails outright while the container starts. */
 export function runtimeReplacedErr(err: RuntimeReplacedError): ThreadErr {
-  return { error: err.message, status: 409, reason: "runtime-replaced" };
+  return { error: err.message, status: 409, reason: "runtime-replaced", cause: "system" };
 }
 
 /** The named ThreadErr a DO code-update reset answers with — its own `reason`
@@ -152,7 +160,7 @@ export function runtimeReplacedErr(err: RuntimeReplacedError): ThreadErr {
  *  idempotent op or resolves a write by echo (harness-pi item 16), never the
  *  replaced verdict. */
 export function controlResetErr(err: ControlResetError): ThreadErr {
-  return { error: err.message, status: 409, reason: "control-reset" };
+  return { error: err.message, status: 409, reason: "control-reset", cause: "system" };
 }
 
 /** The platform's transient sentences the pinned SDK's own predicate does not
@@ -280,6 +288,9 @@ export function threadErrBuilders(p: ThrowPredicates): ThreadErrBuilders {
     // `isRuntimeUnreachableReason`) — and the remainder sentences.
     for (const link of selfAndCauses(err)) {
       if (isRuntimeUnreachableSignal(link)) return true;
+      // The DO's own word for a refused connect (`runtime-busy:`, item 68):
+      // the container accepts again in moments, so a re-probe clears it.
+      if (isRuntimeBusyError(link)) return true;
       const message = messageOf(link);
       if (isRuntimeUnreachableReason(message) || TRANSIENT_PLATFORM_WORDING.test(message)) return true;
     }
@@ -291,6 +302,8 @@ export function threadErrBuilders(p: ThrowPredicates): ThreadErrBuilders {
       error: prefix ? `${prefix}: ${words}` : words,
       status: 500,
       transient: isTransientPlatformThrow(err, known),
+      // A throw no route named is the machinery's own: system.
+      cause: "system",
     };
   };
   const threadRejectionErr = (err: unknown, route: ThreadDataRoute): ThreadErr => {
@@ -299,9 +312,13 @@ export function threadErrBuilders(p: ThrowPredicates): ThreadErrBuilders {
     const runtimeReplacement = p.isRuntimeReplacement(err);
     if (runtimeReplacement) {
       const vouched = p.sdkVouchesRuntimeMoved(err);
-      if (route === "/exec" && !vouched) return { error: messageOf(err), status: 409 };
+      if (route === "/exec" && !vouched) return { error: messageOf(err), status: 409, cause: "system" };
       return runtimeReplacedErr(new RuntimeReplacedError("call", err, vouched));
     }
+    // The DO's own word for a refused connect, thrown out of a method before
+    // the stub answered (item 68): the same 503 the method answers inside, so
+    // the client re-sends on the token wherever the throw was met.
+    if (isRuntimeBusyError(err)) return runtimeBusyErr(err instanceof Error ? err : new Error(messageOf(err)));
     // The two verdicts just settled ride into the typed 500, so its walk of the
     // cause chain is for the transient alone.
     return catchAllErr(err, undefined, { controlReset, runtimeReplacement });
@@ -309,6 +326,17 @@ export function threadErrBuilders(p: ThrowPredicates): ThreadErrBuilders {
   return { isTransientPlatformThrow, catchAllErr, threadRejectionErr };
 }
 
+/** A container that did not accept the connection
+ *  (docs/reference/specs/resident-repos.md item 68; execution.md item 28): the
+ *  platform's accept refusal met at the exec choke point's SPAWN — nothing
+ *  ran, the worktree is as it was — named with the wait token the client
+ *  re-sends on, as a 503 like the mirror held. `err` is the DO's typed error
+ *  (`SandboxRuntimeBusyError`, its message starting with the token), or the
+ *  same error after the stub boundary. */
+export function runtimeBusyErr(err: Error): ThreadErr {
+  return { error: err.message, status: 503, reason: RUNTIME_BUSY_REASON, cause: "system" };
+}
+
 /** /exec's failure document, in the item-3 dual shape (`error` beside
  *  `stdout: ""`, `stderr`, `exitCode: 127`) so old and new executors both
  *  render it. The ThreadErr's fields ride beside the words, as the JSON routes
@@ -328,6 +356,7 @@ export function execFailureDocument(failure: ThreadErr): object {
     ...(failure.state ? { state: failure.state } : {}),
     ...(typeof failure.stateReason === "string" ? { stateReason: failure.stateReason } : {}),
     ...(failure.reason ? { reason: failure.reason } : {}),
+    ...(failure.cause ? { cause: failure.cause } : {}),
     status: failure.status,
     ...(typeof failure.transient === "boolean" ? { transient: failure.transient } : {}),
     stdout: "",