@coreplane/switchboard 1.212.0 → 1.214.0

package/README.md

@@ -10,7 +10,7 @@
 Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.
 
 <p align="center">
-  <img alt="A review in a Slack thread: the mention, the status card ticking through the run's steps, then the verdict with its findings." src="https://raw.githubusercontent.com/coreplanelabs/switchboard/HEAD/docs/public/slack/run.gif" width="395">
+  <img alt="A review in a Slack thread: a plain request to look at a pull request, the card naming the agent it picked and why, then the verdict with its findings." src="https://raw.githubusercontent.com/coreplanelabs/switchboard/HEAD/docs/public/slack/run.gif" width="395">
 </p>
 
 <picture>
@@ -33,7 +33,7 @@ Next: [Get started](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/
 
 ## How it is put together
 
-Four seams: Channel, Provider, Executor, Agent. Each is an interface with more than one implementation. The dispatcher sits between them: directives, config layers, authorization, the agent loop ([How a request flows](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/explanation/how-a-request-flows.md)).
+Four seams: Channel, Provider, Executor, Agent. Each is an interface with more than one implementation. The dispatcher sits between them: it reads what you asked for and picks the agent, resolves the model through the config layers, checks authorization and runs the agent loop ([How a request flows](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/explanation/how-a-request-flows.md)).
 
 
 ## What you need
@@ -47,8 +47,10 @@ Four seams: Channel, Provider, Executor, Agent. Each is an interface with more t
 | Optional | An E2B account | Per-thread micro-VMs without Cloudflare |
 | Optional | A Brave Search key (`BRAVE_SEARCH_API_KEY`) | Web search for the research agent |
 
-Off means absent from `help`, the dashboard and the plan ([Turn features on and off](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/how-to/turn-features-on-and-off.md)). The bot is `npx @coreplane/switchboard start` on any machine with Node, or the published image `ghcr.io/coreplanelabs/switchboard`.
+Off means the bot never offers it and the dashboard and the plan never show it ([Turn features on and off](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/how-to/turn-features-on-and-off.md)). The bot is `npx @coreplane/switchboard start` on any machine with Node, or the published image `ghcr.io/coreplanelabs/switchboard`.
 
 ## Learn more
 
 Docs: <https://openswitchboard.dev> ([`docs/`](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/README.md)) · [CONTRIBUTING.md](https://github.com/coreplanelabs/switchboard/blob/HEAD/CONTRIBUTING.md) · [AGENTS.md](https://github.com/coreplanelabs/switchboard/blob/HEAD/AGENTS.md) · [SECURITY.md](https://github.com/coreplanelabs/switchboard/blob/HEAD/SECURITY.md) · [Apache-2.0](https://github.com/coreplanelabs/switchboard/blob/HEAD/LICENSE).
+
+Going deeper: commands and directives exist for whoever wants to type them ([Slack commands](https://github.com/coreplanelabs/switchboard/blob/HEAD/docs/reference/slack-commands.md)); a plain sentence needs none.

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

@@ -212,6 +212,27 @@ execution:
 # Under docker compose this directory is a named volume, so checkouts survive a restart.
 workspaceDir: ./workspaces
 
+# The artifact store (docs/reference/specs/execution.md item 20): one private R2
+# bucket a run's files move through by reference — a screenshot a coding run
+# attaches, a video a person drops on a thread. DEFAULT OFF: absent means no
+# store; attach_file keeps its inline path (10 MiB cap) and an inbound video is
+# skipped with its name, exactly as before. Configured, the bot signs presigned
+# URLs and the container moves the bytes; the bot never holds a file. Needs
+# three bot secrets — ARTIFACTS_R2_ACCESS_KEY_ID and ARTIFACTS_R2_SECRET_ACCESS_KEY
+# (an R2 API token scoped Object Read & Write to this bucket only) and
+# ARTIFACTS_COPY_TOKEN (self-minted, shared with the bot's own Worker) — and
+# PUBLIC_BASE_URL; a configured store with any of them unset fails startup by
+# name. `deploy` creates the bucket; `artifacts lifecycle` applies retention;
+# `artifacts check` reads whether the bucket is private.
+# artifacts:
+#   r2:
+#     accountId: <your Cloudflare account id>     # the S3 endpoint is <accountId>.r2.cloudflarestorage.com
+#     bucket: switchboard-artifacts                 # the bot's Worker binds the same name
+#   retentionDays: 30       # objects expire after this many days (default 30)
+#   inbound:
+#     maxBytesPerMessage: 2147483648   # the most staged bytes one message may carry (default 2 GiB)
+#     copyTimeoutMs: 1200000           # how long the bot waits on one inbound copy (default 20 min)
+
 # Cross-session self-learning memory (docs/reference/specs/memory.md). DEFAULT OFF: absent, or
 # enabled:false, means the dispatcher uses a NullMemoryStore and the model input
 # is byte-identical to memory-off — zero behavior change. When enabled, before
@@ -293,6 +314,18 @@ workspaceDir: ./workspaces
 #   maxRounds: 3      # review rounds per unit
 #   maxMinutes: 120   # the ship preset's wall-clock budget in minutes (the registry's default)
 
+# Which loop drives each preset's runs (docs/reference/specs/harness-pi.md):
+# `native`, the in-process turn loop, or `pi`, the pi coding agent started
+# inside the run's own execution container and driven over its RPC protocol —
+# with the run's model-proxy bearer as its only key, every event bridged onto
+# the run's own record, our tools and tool rules as its extension. Every
+# preset declares `native` until the pi series moves it; a deployment moves a
+# preset early here. Only a preset with a workspace (coding, review, explore)
+# can run on pi. A preset the registry does not know, or a value that is
+# neither harness, fails the load by name.
+# harness:
+#   coding: pi
+
 # The fan-out cap a spawning run meets (docs/reference/specs/agent-conductor.md).
 # `agent:conductor` starts child runs as the person who asked — each an
 # ordinary run in a thread of its own, under that person's permissions — and
@@ -302,6 +335,21 @@ workspaceDir: ./workspaces
 # spawn:
 #   maxChildren: 3
 
+# The request router (docs/reference/specs/routing-and-config.md item 21). ON BY
+# DEFAULT: a plain message — no `agent:` directive, no sticky preset, no channel
+# or user `agent` — asks the fast model which preset it means and runs as that
+# preset, the card saying why (`routed: <reason>`) and how to run it another way.
+# `ship` is never routed. The one way off, so every plain message runs
+# `defaults.agent` as before the router: `auto: false`. `model` is the router's
+# model; default `defaults.models.general`. `answer` is how that model answers:
+# `tool` (default) forces a call to the router's `route` tool, whose schema is
+# the answer, so prose cannot occur; `text` is the one-JSON-object text contract
+# alone — set it for a provider or model that cannot take a forced tool call.
+# routing:
+#   auto: false
+#   model: anthropic/claude-haiku-4-5
+#   answer: text
+
 # Spend reporting: GET /costs (Access-gated). Optional. See docs/reference/specs/costs.md.
 # costs:
 #   cloudflareAccountId: <32-hex account id>

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

@@ -0,0 +1,180 @@
+// The artifact copy route (docs/reference/specs/execution.md item 20, record
+// 0033): `POST /artifacts/copy { url, size, key }` streams a Slack file into
+// the artifacts bucket without the bot's container ever holding the bytes.
+// The bot asks (`R2ArtifactStore.copyFromUrl`, bearer ARTIFACTS_COPY_TOKEN);
+// this Worker holds the two things the copy needs — the R2 binding and the
+// Slack bot token that `url_private` requires — and answers `{ key, size }`
+// only once the bucket holds exactly `size` bytes under `key`.
+//
+// Pure over its deps so it is tested in plain Node (this directory's tests
+// run no workerd): the bucket, the upstream fetch, the length pipe (workerd's
+// `FixedLengthStream`, which refuses a body of another length) and the tokens
+// are handed in; `worker.ts` binds them from `env`.
+
+/** What the route needs from the bucket: R2's `put` with a stream and the object's type. */
+export interface CopyBucket {
+  put(
+    key: string,
+    value: ReadableStream<Uint8Array>,
+    options?: { httpMetadata?: { contentType?: string } },
+  ): Promise<unknown>;
+}
+
+export interface CopyDeps {
+  /** The `ARTIFACTS` R2 binding; absent when the deployment configures no bucket. */
+  bucket: CopyBucket | undefined;
+  /** The bucket's name as the Worker was deployed with (`ARTIFACTS_BUCKET_NAME`), for `GET`. */
+  bucketName: string | undefined;
+  /** The bearer the bot presents (`ARTIFACTS_COPY_TOKEN`). */
+  copyToken: string | undefined;
+  /** The Slack bot token `url_private` requires. Read from the Worker's env, never from the request. */
+  slackToken: string | undefined;
+  fetch: typeof fetch;
+  /** A pipe that carries exactly `size` bytes and fails on any other count:
+   *  `new FixedLengthStream(size)` in workerd, whose reader R2 accepts as a
+   *  stream of known length; a `TransformStream` in tests. */
+  lengthPipe: (size: number) => { readable: ReadableStream<Uint8Array>; writable: WritableStream<Uint8Array> };
+  /** The largest copy accepted; default `MAX_COPY_BYTES`. */
+  maxBytes?: number;
+}
+
+export const COPY_PATH = "/artifacts/copy";
+
+/** Slack's own per-file ceiling; a larger declared size is refused before any fetch. */
+export const MAX_COPY_BYTES = 1_073_741_824;
+
+/** The hosts a `url_private` may name: Slack's file host and the workspace's own. */
+export function slackFileHost(hostname: string): boolean {
+  return hostname === "files.slack.com" || hostname === "slack.com" || hostname.endsWith(".slack.com");
+}
+
+/** Inbound keys as `inboundKey` (src/artifacts/keys.ts) builds them and nothing
+ *  else: under `threads/`, one character class, no empty or dot segments. */
+const KEY_RE = /^threads\/[A-Za-z0-9._-]+\/in\/[A-Za-z0-9._-]+\/\d+-[A-Za-z0-9._-]+$/;
+export function validCopyKey(key: string): boolean {
+  return KEY_RE.test(key) && !key.split("/").some((s) => s === "" || /^\.+$/.test(s));
+}
+
+/** Constant-time equality over the two strings' UTF-8 bytes (a length difference is a mismatch). */
+export function sameToken(a: string, b: string): boolean {
+  const x = new TextEncoder().encode(a);
+  const y = new TextEncoder().encode(b);
+  let diff = x.length ^ y.length;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+  return diff === 0;
+}
+
+export type CopyRequest = { url: URL; size: number; key: string };
+
+/** Pure: the body parsed and checked, or the 4xx that refuses it — before any fetch. */
+export function parseCopyRequest(
+  raw: string,
+  maxBytes: number,
+): { ok: true; value: CopyRequest } | { ok: false; status: 400 | 413; reason: string } {
+  let body: unknown;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return { ok: false, status: 400, reason: "body is not JSON" };
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return { ok: false, status: 400, reason: "body is not an object" };
+  }
+  const { url, size, key } = body as Record<string, unknown>;
+  if (typeof url !== "string") return { ok: false, status: 400, reason: "url must be a string" };
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { ok: false, status: 400, reason: "url is not a URL" };
+  }
+  if (parsed.protocol !== "https:" || !slackFileHost(parsed.hostname)) {
+    return { ok: false, status: 400, reason: `url host ${parsed.hostname} is not a Slack file host` };
+  }
+  if (typeof size !== "number" || !Number.isInteger(size) || size < 1) {
+    return { ok: false, status: 400, reason: "size must be a positive integer" };
+  }
+  if (size > maxBytes) return { ok: false, status: 413, reason: `size ${size} is over the ${maxBytes}-byte ceiling` };
+  if (typeof key !== "string" || !validCopyKey(key)) {
+    return { ok: false, status: 400, reason: "key is not an inbound artifact key" };
+  }
+  return { ok: true, value: { url: parsed, size, key } };
+}
+
+const json = (status: number, body: Record<string, unknown>) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+/** The route. WHO: the copy bearer, checked in constant time before anything
+ *  else (401, and never the bucket's existence). WHAT: a Slack `url_private`,
+ *  a positive size within the ceiling and an inbound key (400/413, before any
+ *  fetch). THEN the upstream: Slack answers the login page (`text/html`) when
+ *  the token does not reach the file — refused as unauthorized, nothing put;
+ *  a status other than 200 is Slack's word (502); a `Content-Length` absent or
+ *  other than `size` is a 409 before any `put`. The body flows through the
+ *  length pipe into one `put` with Slack's content type; a stream that ends
+ *  short fails the pipe, the put rejects and the bucket keeps nothing (502). */
+export async function handleArtifactsCopy(request: Request, deps: CopyDeps): Promise<Response> {
+  const bearer = /^Bearer\s+(\S+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+  if (!deps.copyToken || !bearer || !sameToken(bearer, deps.copyToken)) {
+    return json(401, { ok: false, error: "artifacts copy: bearer refused" });
+  }
+  if (request.method === "GET") {
+    return deps.bucket && deps.bucketName
+      ? json(200, { ok: true, bucket: deps.bucketName })
+      : json(503, { ok: false, error: "artifacts copy: this Worker has no ARTIFACTS bucket binding" });
+  }
+  if (request.method !== "POST") return json(405, { ok: false, error: `method not allowed: POST ${COPY_PATH}` });
+  if (!deps.bucket)
+    return json(503, { ok: false, error: "artifacts copy: this Worker has no ARTIFACTS bucket binding" });
+  if (!deps.slackToken)
+    return json(503, { ok: false, error: "artifacts copy: SLACK_BOT_TOKEN is not set on this Worker" });
+  const parsed = parseCopyRequest(await request.text().catch(() => ""), deps.maxBytes ?? MAX_COPY_BYTES);
+  if (!parsed.ok) return json(parsed.status, { ok: false, error: `artifacts copy: ${parsed.reason}` });
+  const { url, size, key } = parsed.value;
+
+  let upstream: Response;
+  try {
+    upstream = await deps.fetch(url.toString(), {
+      headers: { authorization: `Bearer ${deps.slackToken}` },
+      redirect: "manual",
+    });
+  } catch (err) {
+    return json(502, { ok: false, error: `artifacts copy: slack did not answer: ${describe(err)}` });
+  }
+  const contentType = upstream.headers.get("content-type") ?? "application/octet-stream";
+  if (upstream.status === 200 && /^text\/html\b/i.test(contentType)) {
+    await upstream.body?.cancel().catch(() => {});
+    return json(502, {
+      ok: false,
+      error: "artifacts copy: slack answered its login page — the bot token is not authorized for this file",
+    });
+  }
+  if (upstream.status !== 200 || !upstream.body) {
+    await upstream.body?.cancel().catch(() => {});
+    return json(502, { ok: false, error: `artifacts copy: slack answered HTTP ${upstream.status}` });
+  }
+  const declared = Number(upstream.headers.get("content-length"));
+  if (!upstream.headers.has("content-length") || !Number.isInteger(declared)) {
+    await upstream.body.cancel().catch(() => {});
+    return json(409, { ok: false, error: "artifacts copy: slack stated no length for the file" });
+  }
+  if (declared !== size) {
+    await upstream.body.cancel().catch(() => {});
+    return json(409, { ok: false, error: `artifacts copy: slack states ${declared} bytes, not the ${size} declared` });
+  }
+
+  // The bytes: upstream → the fixed-length pipe → one put. Either side failing
+  // rejects the whole copy; R2 keeps nothing for a stream that did not complete.
+  const { readable, writable } = deps.lengthPipe(size);
+  try {
+    await Promise.all([
+      upstream.body.pipeTo(writable),
+      deps.bucket.put(key, readable, { httpMetadata: { contentType } }),
+    ]);
+  } catch (err) {
+    return json(502, { ok: false, error: `artifacts copy: the copy of ${key} failed mid-stream: ${describe(err)}` });
+  }
+  return json(200, { ok: true, key, size });
+}
+
+const describe = (err: unknown): string => (err instanceof Error ? err.message : String(err));

package/dist/assets/deploy/cloudflare/ensure-bucket.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Create the R2 buckets this Worker's wrangler.jsonc binds, before `wrangler
+// deploy` validates the bindings (docs/reference/specs/execution.md item 20,
+// record 0033). wrangler refuses a deploy whose `r2_buckets` names a bucket
+// that does not exist, and creating one by hand is the step an installation
+// forgets; `npm run deploy` runs this after the preflight. Idempotent: a bucket
+// that already exists is success (wrangler's own words for it are matched),
+// any other refusal is wrangler's, verbatim, and the deploy stops.
+//
+// Dependency-free Node. `bucketNamesOf()` and `decide()` are pure and
+// unit-tested (ensure-bucket.test.mjs); `main()` only does I/O around them.
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Every `bucket_name` the rendered config binds — the template renders the
+ *  block only when the deployment profile names a bucket, so an installation
+ *  without artifacts has none here and this script does nothing. */
+export function bucketNamesOf(wranglerJsonc) {
+  const names = [];
+  for (const m of wranglerJsonc.matchAll(/"bucket_name"\s*:\s*"([^"]+)"/g)) names.push(m[1]);
+  return [...new Set(names)];
+}
+
+/** Pure: what `wrangler r2 bucket create <name>` meant. Exit 0 → created; a
+ *  non-zero exit whose output says the bucket exists → already there (success);
+ *  anything else → wrangler's refusal, to print and stop on. */
+export function decide(name, code, output) {
+  if (code === 0) return { ok: true, kind: "created", name };
+  if (/already exists|10004/i.test(output)) return { ok: true, kind: "exists", name };
+  return { ok: false, name, reason: output.trim() || `wrangler exited ${code}` };
+}
+
+function wrangler(args, cwd) {
+  return new Promise((resolve) => {
+    execFile("npx", ["wrangler", ...args], { cwd, env: process.env, maxBuffer: 4 << 20 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+      resolve({ code, output: `${stdout ?? ""}\n${stderr ?? ""}` });
+    });
+  });
+}
+
+export async function main(dir = dirname(fileURLToPath(import.meta.url))) {
+  let rendered;
+  try {
+    rendered = readFileSync(join(dir, "wrangler.jsonc"), "utf8");
+  } catch {
+    console.error("[ensure-bucket] wrangler.jsonc is not rendered — run `npm run deploy:gen` first");
+    return 2;
+  }
+  const names = bucketNamesOf(rendered);
+  if (names.length === 0) {
+    console.log("[ensure-bucket] no R2 buckets bound — nothing to create");
+    return 0;
+  }
+  for (const name of names) {
+    const r = await wrangler(["r2", "bucket", "create", name], dir);
+    const d = decide(name, r.code, r.output);
+    if (!d.ok) {
+      console.error(`[ensure-bucket] could not create bucket ${name}:\n${d.reason}`);
+      return 1;
+    }
+    console.log(`[ensure-bucket] bucket ${name} ${d.kind === "created" ? "created" : "already exists"}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main();
+}

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

@@ -7,7 +7,7 @@
   },
   "scripts": {
     "check:image": "docker build ../..",
-    "deploy": "node preflight.mjs && node write-build.mjs && wrangler deploy",
+    "deploy": "node preflight.mjs && node ensure-bucket.mjs && node write-build.mjs && wrangler deploy",
     "preflight": "node preflight.mjs",
     "test": "vitest run",
     "verify": "npm --prefix ../.. run --silent deploy:gen && npm run typecheck && npm test",

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

@@ -46,6 +46,7 @@ import {
 import { systemClock } from "../../src/core/trace/clock.ts";
 import { createTracer } from "../../src/core/trace/tracer.ts";
 import { shimRoute, stripTraceContext, withTraceContext, workerLogSink } from "../../src/core/trace/workerTrace.ts";
+import { COPY_PATH, handleArtifactsCopy } from "./artifactsCopy.ts";
 import type { ShipCoordinatorParams } from "./coordinator";
 import { INSTANCE, INTERNAL } from "./shared";
 
@@ -90,6 +91,15 @@ export interface Env {
   MEMORY_TOKEN?: string; // durable memory + friction ledger + schedule firings + MCP registry: bearer for the state Worker
   MCP_CREDENTIAL_KEY?: string; // MCP registry: the bot-only key that seals server credentials before they reach the McpDO
   STATE_WORKER_URL?: string; // var: the state Worker's base URL — where this shim records each scheduled firing
+  ARTIFACTS_R2_ACCESS_KEY_ID?: string; // artifact store: the bucket-scoped S3 token the bot signs presigned URLs with
+  ARTIFACTS_R2_SECRET_ACCESS_KEY?: string; // artifact store: the secret half of that token
+  ARTIFACTS_COPY_TOKEN?: string; // artifact store: the bearer the bot presents to this Worker's /artifacts/copy route
+  /** The artifacts bucket (artifactsCopy.ts), bound only when the deployment profile names one
+   *  (`artifacts.bucket` → the template's `r2_buckets` block); `ARTIFACTS_BUCKET_NAME` is the same
+   *  name as a var, what `GET /artifacts/copy` reports so `artifacts check` can hold it against the
+   *  bot's config. Worker-side only: neither reaches the container. */
+  ARTIFACTS?: R2Bucket;
+  ARTIFACTS_BUCKET_NAME?: string;
 }
 
 /** Every secret/var the Worker forwards into the container. Optional entries
@@ -115,6 +125,9 @@ const FORWARDED_OPTIONAL = [
   "MEMORY_TOKEN",
   "MCP_CREDENTIAL_KEY",
   "STATE_WORKER_URL",
+  "ARTIFACTS_R2_ACCESS_KEY_ID",
+  "ARTIFACTS_R2_SECRET_ACCESS_KEY",
+  "ARTIFACTS_COPY_TOKEN",
 ] as const satisfies readonly (keyof Env)[];
 
 /** The container's environment, computed from the Worker env AT START TIME.
@@ -423,7 +436,18 @@ export default {
             ? await handleCoordinatorInstances(forwarded, env)
             : statusId !== undefined
               ? await handleCoordinatorInstanceStatus(forwarded, env, statusId)
-              : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
+              : pathname === COPY_PATH
+                ? // The artifact copy (artifactsCopy.ts): the R2 binding and the Slack
+                  // token are this Worker's; the bot only asks, with its copy bearer.
+                  await handleArtifactsCopy(inbound, {
+                    bucket: env.ARTIFACTS,
+                    bucketName: env.ARTIFACTS_BUCKET_NAME,
+                    copyToken: env.ARTIFACTS_COPY_TOKEN,
+                    slackToken: env.SLACK_BOT_TOKEN,
+                    fetch: (input, init) => fetch(input, init),
+                    lengthPipe: (size) => new FixedLengthStream(size),
+                  })
+                : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
       root.end(res.status >= 500 ? "error" : "ok", { httpStatus: res.status });
       return res;
     } catch (err) {

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

@@ -34,6 +34,10 @@
     // The state Worker (deploy/cloudflare-memory/): where worker.ts records each
     // scheduled firing for the /runs Scheduled panel, with MEMORY_TOKEN.
     // A profile without a memory Worker renders no var: firings go unrecorded.
+    // The artifacts bucket's name, beside its binding below (rendered together).
+    // {{#if artifacts}}
+    "ARTIFACTS_BUCKET_NAME": "{{artifacts.bucket}}",
+    // {{/if}}
     // {{#if urls.stateWorkerUrl}}
     "STATE_WORKER_URL": "{{urls.stateWorkerUrl}}"
     // {{/if}}
@@ -54,6 +58,17 @@
   "durable_objects": {
     "bindings": [{ "name": "SWITCHBOARD", "class_name": "SwitchboardServer" }]
   },
+  // The artifacts bucket (docs/reference/specs/execution.md item 20, record
+  // 0033): where a run's files live by reference. Rendered only when the
+  // deployment profile names a bucket (`artifacts.bucket`) — the bot's
+  // config `artifacts.r2.bucket` must say the same name, and `artifacts
+  // check` holds the two against each other through `GET /artifacts/copy`.
+  // `npm run deploy` creates the bucket first (ensure-bucket.mjs); wrangler
+  // validates the binding on deploy. `ARTIFACTS_BUCKET_NAME` above is the
+  // same name as a var, so the Worker can say which bucket it binds.
+  // {{#if artifacts}}
+  "r2_buckets": [{ "binding": "ARTIFACTS", "bucket_name": "{{artifacts.bucket}}" }],
+  // {{/if}}
   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SwitchboardServer"] }],
   // The ship coordinator as a Workflow (coordinator.ts, re-exported by
   // worker.ts; docs/reference/specs/http-ingress.md item 9): `POST

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

@@ -153,6 +153,24 @@ RUN apt-get update \
   && playwright screenshot --viewport-size=640,480 'data:text/html,<h1>ok</h1>' /tmp/ok.png && test -s /tmp/ok.png \
   && rm -f /tmp/proof.mp4 /tmp/proof_*.png /tmp/ok.png
 
+# pi — the coding harness the bot can start INSIDE this container in place of
+# its native turn loop (docs/reference/specs/harness-pi.md): `pi --mode rpc`,
+# one process per run in the thread's worktree, driven by the bot over its
+# JSONL protocol, with the run's model-proxy bearer as its only key (never a
+# model key: the bearer buys calls through the bot, docs/reference/specs/
+# model-proxy.md). Installed globally with this image's Node — pi needs
+# >= 22.19.0 and the image ships 24 — so every user finds it on PATH, at an
+# EXACT pin held by src/deploy/imagePiHarness.test.ts (the pnpm lesson: a
+# floating tag would move the harness's protocol with the build date, and a
+# pi minor changes RPC events and extension hooks). Proven by the layer, so
+# the BUILD fails, not a run: the pi on PATH answers the pin, and its own help
+# names the RPC mode the harness drives. Dark until a deployment sets
+# `harness: { coding: pi }`: nothing here starts pi on its own.
+RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
+  && npm cache clean --force \
+  && pi --version | grep -qx '0.85.1' \
+  && pi --help | grep -q -- '--mode <mode>'
+
 # 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
@@ -175,3 +193,9 @@ RUN set -eux; \
 # browser tree under /opt and launch it, so the BUILD fails if a chmod or the
 # path ever regresses, not a run.
 RUN su -s /bin/bash worker1 -c "playwright screenshot --viewport-size=640,480 'data:text/html,<h1>ok</h1>' /tmp/ok.png && test -s /tmp/ok.png && rm -f /tmp/ok.png"
+
+# pi once more, as worker1: a run's pi is started as the thread's user through
+# the same `su`, so the BUILD proves an unprivileged user finds the pin on PATH
+# and pi answers without a writable home (its config directory is the run's
+# own, named by PI_CODING_AGENT_DIR at start).
+RUN su -s /bin/bash worker1 -c "pi --version | grep -qx '0.85.1'"