@scp-dev/mcp 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,36 @@
+# @scp-dev/mcp
+
+The SCP MCP server: a dependency-free stdio server that gives one agent session the relay's tools over its local broker.
+
+```sh
+npm install @scp-dev/mcp
+```
+
+Most people mount it through the CLI: `swarm setup --write`, or `swarm mcp install --harness claude`, which registers `swarm mcp` under the name `scp`.
+
+## Usage
+
+```ts
+import { connectBroker, relayDir } from "@scp-dev/broker"
+import { runRelayMcp } from "@scp-dev/mcp"
+
+const dir = relayDir()
+await runRelayMcp({
+  connect: () => connectBroker(dir),
+  claim: { handle: "parser", harness: "codex" },
+  input: process.stdin,
+  output: (line) => void process.stdout.write(line),
+})
+```
+
+## Provides
+
+- `runRelayMcp`: JSON-RPC 2.0 over stdio. It binds as an agent endpoint, resumes with its token after a reconnect, sets status `working`, and with `channels` pushes messages as `notifications/claude/channel`.
+- `TOOLS`: `relay_whoami`, `relay_list`, `relay_peers`, `relay_send`, `relay_reply`, `relay_inbox`, `relay_ask`, `relay_ask_wait`, `relay_spawn`, `relay_status`, `relay_set_status`, `relay_set_now`, `relay_set_title`, `relay_rules`, `relay_group`, `relay_peek`, `relay_set_peek`.
+- `INSTRUCTIONS` and `MCP_PROTOCOLS`: the server's instructions (the untrusted-content preamble) and the protocol versions it speaks.
+
+Implements [Appendix F, MCP tools](https://scp.dev/spec#appendix-f-reference-binding-mcp-tools). See the [root README](https://github.com/scphq/scp#readme).
+
+## License
+
+[Apache-2.0](LICENSE).

package/dist/index.d.ts

@@ -15,13 +15,35 @@ interface RelayMcpOptions {
     output: (line: string) => void;
     /** HOME shortens cwds in relay_list */
     env?: Record<string, string | undefined>;
-    /** push deliveries as `notifications/claude/channel` */
+    /** push deliveries as `notifications/claude/channel` to a client that declares `claude/channel` or was launched with channels */
     channels?: boolean;
+    /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
+    launchedWithChannels?: boolean;
     version?: string;
+    /** starts a worker for relay_spawn, resolving with its name and its runner's pid once its harness started; without it there is no relay_spawn */
+    spawn?: (request: SpawnRequest) => Promise<{
+        name: string;
+        pid: number;
+    }>;
     /** diagnostics, never stdout */
     log?: (line: string) => void;
     heartbeatMs?: number;
 }
+/**
+ * what relay_spawn asks for: `swarm spawn --bg` of `command` with these flags, acting as `as`, the shim's own address, of `harness`,
+ * in `cwd`: the one asked for, else the caller's working directory when it exists, else (none) the shim's
+ */
+interface SpawnRequest {
+    command: string[];
+    as: string;
+    harness?: string;
+    name?: string;
+    title?: string;
+    no_push?: boolean;
+    handback_bytes?: number;
+    /** the directory the worker runs in, absolute and existing */
+    cwd?: string;
+}
 declare const TOOLS: readonly [{
     readonly name: "relay_whoami";
     readonly description: "Your own address on the relay, with your harness, title and labels.";
@@ -80,6 +102,72 @@ declare const TOOLS: readonly [{
         readonly required: readonly ["to", "body"];
         readonly additionalProperties: false;
     };
+}, {
+    readonly name: "relay_spawn";
+    readonly description: "Start a worker agent under you, as swarm spawn does: command is its harness command as argv, its task in it (e.g. [\"claude\", \"-p\", \"<task>\", \"--model\", \"<model>\"] or [\"codex\", \"exec\", \"<task>\"]), or give harness and task instead. It returns at once with the worker's name; its messages and its handback (exit code and final output) reach you by themselves, and relay_send to that name steers it: the worker gets your message after its next tool call or before it finishes, so its task need not tell it to check an inbox.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly command: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly minItems: 1;
+                readonly description: "the harness command as argv";
+            };
+            readonly harness: {
+                readonly type: "string";
+                readonly enum: readonly ["claude", "codex"];
+                readonly description: "instead of command: claude -p <task> or codex exec <task>";
+            };
+            readonly task: {
+                readonly type: "string";
+                readonly description: "with harness: the worker's task";
+            };
+            readonly model: {
+                readonly type: "string";
+                readonly description: "with harness: its --model";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: "its address (default <harness>-<5 random characters>)";
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly maxLength: 64;
+                readonly description: "its title until it sets its own (default the task's first line)";
+            };
+            readonly no_push: {
+                readonly type: "boolean";
+                readonly description: "your stop does not wait on it; its messages and handback still reach you after your tool calls";
+            };
+            readonly handback_bytes: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 16384;
+                readonly description: "hand back only the last N bytes of its final output";
+            };
+            readonly cwd: {
+                readonly type: "string";
+                readonly description: "the absolute path of an existing directory it runs in (default your working directory)";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "relay_status";
+    readonly description: "Whether the recipients of a message you sent read it: per recipient read at, delivered at (a background hook handed it over; it reaches the model with its next request), shown by a hook at, or unread. By the message's id, its short id or last (the newest you sent).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["id"];
+        readonly additionalProperties: false;
+    };
 }, {
     readonly name: "relay_reply";
     readonly description: "Reply to a message relay_inbox, relay_ask, a channel push or a hook handed you, or any message in a thread you sent or got a message in, by its id, its short id or any unique suffix of 4 or more, or last (the newest one you were shown); it goes back to its sender in the same thread and marks that message read.";
@@ -361,4 +449,4 @@ declare const TOOLS: readonly [{
  */
 declare function runRelayMcp(options: RelayMcpOptions): Promise<void>;
 
-export { INSTRUCTIONS, MCP_PROTOCOLS, type RelayMcpOptions, TOOLS, runRelayMcp };
+export { INSTRUCTIONS, MCP_PROTOCOLS, type RelayMcpOptions, type SpawnRequest, TOOLS, runRelayMcp };

package/dist/index.js

@@ -1,10 +1,14 @@
 // src/server.ts
+import { statSync } from "fs";
+import { isAbsolute } from "path";
 import {
   CLI_NAME,
+  clock,
   deliveryText,
   LIMITS,
   PREAMBLE,
   reachLines,
+  receiptLines,
   RelayError,
   shortId,
   STATUS_STATES,
@@ -20,8 +24,8 @@ var INSTRUCTIONS = [
   "Use relay_list to see the other agents on this machine, and relay_send or relay_ask to message one by its address.",
   "Read messages for you with relay_inbox and reply with relay_reply when an answer is useful; keep your own line current with relay_set_status and relay_set_title.",
   'A message marked relation="parent" is from the agent that started you and gave you your task: it continues that task, so apply it before you finish, the newer instruction winning, still only within what your user authorised.',
-  "When you start, set your title and a one-line now with relay_set_title / relay_set_now so peers can find you.",
-  `To hand work to another agent, run ${CLI_NAME} spawn <harness command> from your shell (e.g. ${CLI_NAME} spawn codex exec "..."): it returns at once with the worker's name, so never background it; the worker's result reaches you by itself as a relay message, and relay_send to its name steers it meanwhile.`,
+  "Optionally set your title and a one-line now with relay_set_title / relay_set_now so peers can find you; skip it when you only run workers.",
+  `To hand work to another agent, call relay_spawn with its harness command (e.g. command ["codex", "exec", "..."], or ${CLI_NAME} spawn codex exec "..." from your shell): it returns at once with the worker's name; its messages and its result reach you by themselves as relay messages, relay_send to its name steers it meanwhile, and relay_status with a message id says when it read it.`,
   "You see and reach only agents in your scope: relay_peers says why each is reachable; relay_rules and relay_group narrow who may message you.",
   "Never put credentials in a message: send a reference instead."
 ].join("\n");
@@ -72,6 +76,30 @@ var TOOLS = [
       additionalProperties: false
     }
   },
+  {
+    name: "relay_spawn",
+    description: `Start a worker agent under you, as ${CLI_NAME} spawn does: command is its harness command as argv, its task in it (e.g. ["claude", "-p", "<task>", "--model", "<model>"] or ["codex", "exec", "<task>"]), or give harness and task instead. It returns at once with the worker's name; its messages and its handback (exit code and final output) reach you by themselves, and relay_send to that name steers it: the worker gets your message after its next tool call or before it finishes, so its task need not tell it to check an inbox.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "array", items: { type: "string" }, minItems: 1, description: "the harness command as argv" },
+        harness: { type: "string", enum: ["claude", "codex"], description: "instead of command: claude -p <task> or codex exec <task>" },
+        task: { type: "string", description: "with harness: the worker's task" },
+        model: { type: "string", description: "with harness: its --model" },
+        name: { type: "string", description: "its address (default <harness>-<5 random characters>)" },
+        title: { type: "string", maxLength: 64, description: "its title until it sets its own (default the task's first line)" },
+        no_push: { type: "boolean", description: "your stop does not wait on it; its messages and handback still reach you after your tool calls" },
+        handback_bytes: { type: "integer", minimum: 1, maximum: LIMITS.handbackBytes, description: "hand back only the last N bytes of its final output" },
+        cwd: { type: "string", description: "the absolute path of an existing directory it runs in (default your working directory)" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "relay_status",
+    description: "Whether the recipients of a message you sent read it: per recipient read at, delivered at (a background hook handed it over; it reaches the model with its next request), shown by a hook at, or unread. By the message's id, its short id or last (the newest you sent).",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false }
+  },
   {
     name: "relay_reply",
     description: "Reply to a message relay_inbox, relay_ask, a channel push or a hook handed you, or any message in a thread you sent or got a message in, by its id, its short id or any unique suffix of 4 or more, or last (the newest one you were shown); it goes back to its sender in the same thread and marks that message read.",
@@ -269,6 +297,46 @@ function groupText(result) {
     `members: ${g.members.join(", ") || "none"}`
   ].join("\n");
 }
+function spawnRequest(args) {
+  if (args.command === void 0 === (args.harness === void 0)) throw new ToolInputError("give command (the harness command as argv) or harness and task");
+  let command;
+  if (args.command !== void 0) {
+    const words = args.command;
+    if (!Array.isArray(words) || !words.length || !words.every((w) => typeof w === "string") || !String(words[0]).trim())
+      throw new ToolInputError('command must be the harness command as a list of words, e.g. ["codex", "exec", "<task>"]');
+    if (args.task !== void 0 || args.model !== void 0) throw new ToolInputError("task and model go with harness; with command, put them in it");
+    command = words;
+  } else {
+    const harness = oneOf(args, "harness", ["claude", "codex"]);
+    const model = str(args, "model");
+    command = [...harness === "claude" ? ["claude", "-p"] : ["codex", "exec"], str(args, "task", true), ...model ? ["--model", model] : []];
+  }
+  const bytes = args.handback_bytes;
+  if (bytes !== void 0 && (typeof bytes !== "number" || !Number.isInteger(bytes) || bytes < 1 || bytes > LIMITS.handbackBytes))
+    throw new ToolInputError(`handback_bytes must be whole bytes, 1 to ${LIMITS.handbackBytes}`);
+  const name = args.name === void 0 ? void 0 : str(args, "name", true);
+  const title = str(args, "title");
+  const noPush = bool(args, "no_push");
+  const cwd = str(args, "cwd");
+  if (cwd !== void 0 && !isAbsolute(cwd)) throw new ToolInputError("cwd must be an absolute path");
+  if (cwd !== void 0 && !isDirectory(cwd)) throw new ToolInputError(`cwd ${cwd} is not an existing directory`);
+  return {
+    command,
+    ...name ? { name } : {},
+    ...title !== void 0 ? { title } : {},
+    ...noPush ? { no_push: true } : {},
+    ...bytes !== void 0 ? { handback_bytes: bytes } : {},
+    ...cwd !== void 0 ? { cwd } : {}
+  };
+}
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+var capped = (wait) => typeof wait === "number" && wait > LIMITS.waitMaxS;
 function seconds(args, fallback) {
   const value = args.wait_s;
   if (value === void 0) return fallback;
@@ -301,11 +369,14 @@ async function* chunks(input) {
   for (let read = await reader.read(); !read.done; read = await reader.read()) yield read.value;
 }
 function delivered(messages) {
-  return [PREAMBLE, ...messages.map(wrapMessage)].join("\n\n");
+  const shown = (message) => message.shown_at ? `(a hook already showed you this at ${clock(message.shown_at)}; that copy may reach you after this call)
+` : "";
+  return [PREAMBLE, ...messages.map((message) => `${shown(message)}${wrapMessage(message)}`)].join("\n\n");
 }
 async function runRelayMcp(options) {
   const log = options.log ?? (() => {
   });
+  const tools = options.spawn ? TOOLS : TOOLS.filter((t) => t.name !== "relay_spawn");
   const home = options.env?.HOME;
   const sent = /* @__PURE__ */ new Map();
   let client;
@@ -450,11 +521,39 @@ async function runRelayMcp(options) {
         if (result.held) return text(heldText(result.held));
         const lines = reachLines(result.deliveries);
         const to = result.deliveries.map((d) => lines.length ? d.address : deliveryText(d)).join(", ");
+        const receipt = result.deliveries.some((d) => d.state === "running" || d.state === "starting") ? [`relay_status with id ${shortId(result.id)} shows when it is read`] : [];
         return {
-          ...text([`sent ${result.id} (thread ${result.thread}) to ${to}${redactedText(result.redacted)}`, ...lines].join("\n")),
+          ...text([`sent ${result.id} (thread ${result.thread}) to ${to}${redactedText(result.redacted)}`, ...lines, ...receipt].join("\n")),
           structuredContent: sentContent(result)
         };
       }
+      case "relay_spawn": {
+        const request = spawnRequest(args);
+        const spawn = options.spawn;
+        if (!spawn) throw new RelayError("method_not_found", "no tool relay_spawn");
+        const view = await call("whoami");
+        let started;
+        try {
+          const cwd = request.cwd ?? (view.cwd && isAbsolute(view.cwd) && isDirectory(view.cwd) ? view.cwd : void 0);
+          started = await spawn({ ...request, as: view.address, ...view.harness ? { harness: view.harness } : {}, ...cwd ? { cwd } : {} });
+        } catch (error) {
+          return text(error instanceof Error ? error.message : String(error), true);
+        }
+        return {
+          ...text(
+            `${started.name} started (pid ${started.pid}) and runs in the background: its messages and its handback reach you by themselves, after your tool calls or when you stop; steer it with relay_send to ${started.name} (it gets the message after its next tool call or before it finishes)`
+          ),
+          structuredContent: { name: started.name, pid: started.pid }
+        };
+      }
+      case "relay_status": {
+        const receipts = await call("receipts", { id: str(args, "id", true) });
+        const lines = receiptLines(receipts);
+        return {
+          ...text([`${receipts.id}:`, ...lines.length ? lines : ["no deliveries of it are kept any more"]].join("\n")),
+          structuredContent: { ...receipts }
+        };
+      }
       case "relay_reply": {
         let id = str(args, "id", true);
         const body = str(args, "body", true);
@@ -483,7 +582,7 @@ async function runRelayMcp(options) {
       case "relay_inbox": {
         const ack = bool(args, "ack") ?? true;
         const { messages } = await call("inbox", { wait_s: seconds(args, 0) });
-        if (!messages.length) return text("no unread messages");
+        if (!messages.length) return text(`no unread messages${capped(args.wait_s) ? `; waited ${LIMITS.waitMaxS} s (cap)` : ""}`);
         for (const message of messages) remember(message);
         if (ack) await call("ack", { seqs: messages.map((m) => m.seq) });
         return text(delivered(messages));
@@ -668,9 +767,8 @@ ${wrapMessage(message)}`,
         const protocolVersion = typeof asked === "string" && MCP_PROTOCOLS.includes(asked) ? asked : MCP_PROTOCOLS[0];
         initialized = true;
         const capabilities = params.capabilities;
-        const client2 = params.clientInfo;
         const channel = capabilities?.experimental?.["claude/channel"];
-        channelClient = typeof channel === "object" && channel !== null || client2?.name === "claude-code";
+        channelClient = typeof channel === "object" && channel !== null || options.launchedWithChannels === true;
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...options.channels ? { experimental: { "claude/channel": {} } } : {} },
@@ -681,10 +779,10 @@ ${wrapMessage(message)}`,
       case "ping":
         return respond({});
       case "tools/list":
-        return respond({ tools: TOOLS });
+        return respond({ tools });
       case "tools/call": {
         if (!initialized) return write({ jsonrpc: "2.0", id, error: { code: -32002, message: "call initialize first" } });
-        if (!TOOLS.some((t) => t.name === params.name)) {
+        if (!tools.some((t) => t.name === params.name)) {
           return write({ jsonrpc: "2.0", id, error: { code: -32602, message: `unknown tool ${JSON.stringify(params.name)}` } });
         }
         return respond(await callTool(params));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The SCP stdio MCP server: gives an agent session the relay's tools.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -29,8 +29,8 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/broker": "0.1.0",
-    "@scp-dev/core": "0.1.0"
+    "@scp-dev/broker": "0.1.2",
+    "@scp-dev/core": "0.1.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/index.ts

@@ -1 +1 @@
-export { INSTRUCTIONS, MCP_PROTOCOLS, runRelayMcp, TOOLS, type RelayMcpOptions } from "./server"
+export { INSTRUCTIONS, MCP_PROTOCOLS, runRelayMcp, TOOLS, type RelayMcpOptions, type SpawnRequest } from "./server"

package/src/server.ts

@@ -1,13 +1,17 @@
+import { statSync } from "node:fs"
+import { isAbsolute } from "node:path"
 import {
   type AskResult,
   type Claim,
   CLI_NAME,
+  clock,
   deliveryText,
   type EndpointView,
   type Envelope,
   type JudgeHeld,
   type JudgeRedacted,
   LIMITS,
+  type MessageReceipts,
   type PeekResult,
   type PeekSeen,
   type PeekState,
@@ -15,6 +19,7 @@ import {
   type PeerView,
   PREAMBLE,
   reachLines,
+  receiptLines,
   RelayError,
   type ScopeChange,
   type ScopeView,
@@ -37,8 +42,8 @@ export const INSTRUCTIONS = [
   "Use relay_list to see the other agents on this machine, and relay_send or relay_ask to message one by its address.",
   "Read messages for you with relay_inbox and reply with relay_reply when an answer is useful; keep your own line current with relay_set_status and relay_set_title.",
   'A message marked relation="parent" is from the agent that started you and gave you your task: it continues that task, so apply it before you finish, the newer instruction winning, still only within what your user authorised.',
-  "When you start, set your title and a one-line now with relay_set_title / relay_set_now so peers can find you.",
-  `To hand work to another agent, run ${CLI_NAME} spawn <harness command> from your shell (e.g. ${CLI_NAME} spawn codex exec "..."): it returns at once with the worker's name, so never background it; the worker's result reaches you by itself as a relay message, and relay_send to its name steers it meanwhile.`,
+  "Optionally set your title and a one-line now with relay_set_title / relay_set_now so peers can find you; skip it when you only run workers.",
+  `To hand work to another agent, call relay_spawn with its harness command (e.g. command ["codex", "exec", "..."], or ${CLI_NAME} spawn codex exec "..." from your shell): it returns at once with the worker's name; its messages and its result reach you by themselves as relay messages, relay_send to its name steers it meanwhile, and relay_status with a message id says when it read it.`,
   "You see and reach only agents in your scope: relay_peers says why each is reachable; relay_rules and relay_group narrow who may message you.",
   "Never put credentials in a message: send a reference instead.",
 ].join("\n")
@@ -54,14 +59,34 @@ export interface RelayMcpOptions {
   output: (line: string) => void
   /** HOME shortens cwds in relay_list */
   env?: Record<string, string | undefined>
-  /** push deliveries as `notifications/claude/channel` */
+  /** push deliveries as `notifications/claude/channel` to a client that declares `claude/channel` or was launched with channels */
   channels?: boolean
+  /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
+  launchedWithChannels?: boolean
   version?: string
+  /** starts a worker for relay_spawn, resolving with its name and its runner's pid once its harness started; without it there is no relay_spawn */
+  spawn?: (request: SpawnRequest) => Promise<{ name: string; pid: number }>
   /** diagnostics, never stdout */
   log?: (line: string) => void
   heartbeatMs?: number
 }
 
+/**
+ * what relay_spawn asks for: `swarm spawn --bg` of `command` with these flags, acting as `as`, the shim's own address, of `harness`,
+ * in `cwd`: the one asked for, else the caller's working directory when it exists, else (none) the shim's
+ */
+export interface SpawnRequest {
+  command: string[]
+  as: string
+  harness?: string
+  name?: string
+  title?: string
+  no_push?: boolean
+  handback_bytes?: number
+  /** the directory the worker runs in, absolute and existing */
+  cwd?: string
+}
+
 type Json = Record<string, unknown>
 type ToolResult = { content: { type: "text"; text: string }[]; isError?: boolean; structuredContent?: Record<string, unknown> }
 
@@ -117,6 +142,31 @@ export const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_spawn",
+    description: `Start a worker agent under you, as ${CLI_NAME} spawn does: command is its harness command as argv, its task in it (e.g. ["claude", "-p", "<task>", "--model", "<model>"] or ["codex", "exec", "<task>"]), or give harness and task instead. It returns at once with the worker's name; its messages and its handback (exit code and final output) reach you by themselves, and relay_send to that name steers it: the worker gets your message after its next tool call or before it finishes, so its task need not tell it to check an inbox.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "array", items: { type: "string" }, minItems: 1, description: "the harness command as argv" },
+        harness: { type: "string", enum: ["claude", "codex"], description: "instead of command: claude -p <task> or codex exec <task>" },
+        task: { type: "string", description: "with harness: the worker's task" },
+        model: { type: "string", description: "with harness: its --model" },
+        name: { type: "string", description: "its address (default <harness>-<5 random characters>)" },
+        title: { type: "string", maxLength: 64, description: "its title until it sets its own (default the task's first line)" },
+        no_push: { type: "boolean", description: "your stop does not wait on it; its messages and handback still reach you after your tool calls" },
+        handback_bytes: { type: "integer", minimum: 1, maximum: LIMITS.handbackBytes, description: "hand back only the last N bytes of its final output" },
+        cwd: { type: "string", description: "the absolute path of an existing directory it runs in (default your working directory)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_status",
+    description:
+      "Whether the recipients of a message you sent read it: per recipient read at, delivered at (a background hook handed it over; it reaches the model with its next request), shown by a hook at, or unread. By the message's id, its short id or last (the newest you sent).",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
+  },
   {
     name: "relay_reply",
     description:
@@ -353,6 +403,50 @@ function groupText(result: unknown): string {
   ].join("\n")
 }
 
+/** relay_spawn's arguments as a spawn request, all but who spawns; a `cwd` must be an existing directory's absolute path */
+function spawnRequest(args: Json): Omit<SpawnRequest, "as" | "harness"> {
+  if ((args.command === undefined) === (args.harness === undefined)) throw new ToolInputError("give command (the harness command as argv) or harness and task")
+  let command: string[]
+  if (args.command !== undefined) {
+    const words = args.command
+    if (!Array.isArray(words) || !words.length || !words.every((w) => typeof w === "string") || !String(words[0]).trim())
+      throw new ToolInputError('command must be the harness command as a list of words, e.g. ["codex", "exec", "<task>"]')
+    if (args.task !== undefined || args.model !== undefined) throw new ToolInputError("task and model go with harness; with command, put them in it")
+    command = words as string[]
+  } else {
+    const harness = oneOf(args, "harness", ["claude", "codex"] as const)
+    const model = str(args, "model")
+    command = [...(harness === "claude" ? ["claude", "-p"] : ["codex", "exec"]), str(args, "task", true), ...(model ? ["--model", model] : [])]
+  }
+  const bytes = args.handback_bytes
+  if (bytes !== undefined && (typeof bytes !== "number" || !Number.isInteger(bytes) || bytes < 1 || bytes > LIMITS.handbackBytes))
+    throw new ToolInputError(`handback_bytes must be whole bytes, 1 to ${LIMITS.handbackBytes}`)
+  const name = args.name === undefined ? undefined : str(args, "name", true)
+  const title = str(args, "title")
+  const noPush = bool(args, "no_push")
+  const cwd = str(args, "cwd")
+  if (cwd !== undefined && !isAbsolute(cwd)) throw new ToolInputError("cwd must be an absolute path")
+  if (cwd !== undefined && !isDirectory(cwd)) throw new ToolInputError(`cwd ${cwd} is not an existing directory`)
+  return {
+    command,
+    ...(name ? { name } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(noPush ? { no_push: true } : {}),
+    ...(bytes !== undefined ? { handback_bytes: bytes } : {}),
+    ...(cwd !== undefined ? { cwd } : {}),
+  }
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+const capped = (wait: unknown): boolean => typeof wait === "number" && wait > LIMITS.waitMaxS
+
 function seconds(args: Json, fallback: number): number {
   const value = args.wait_s
   if (value === undefined) return fallback
@@ -392,7 +486,9 @@ async function* chunks(input: RelayMcpOptions["input"]): AsyncIterable<Uint8Arra
 }
 
 function delivered(messages: Envelope[]): string {
-  return [PREAMBLE, ...messages.map(wrapMessage)].join("\n\n")
+  const shown = (message: Envelope) =>
+    message.shown_at ? `(a hook already showed you this at ${clock(message.shown_at)}; that copy may reach you after this call)\n` : ""
+  return [PREAMBLE, ...messages.map((message) => `${shown(message)}${wrapMessage(message)}`)].join("\n\n")
 }
 
 /**
@@ -401,6 +497,7 @@ function delivered(messages: Envelope[]): string {
  */
 export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   const log = options.log ?? (() => {})
+  const tools = options.spawn ? TOOLS : TOOLS.filter((t) => t.name !== "relay_spawn")
   const home = options.env?.HOME
   const sent = new Map<string, { from: string; thread: string }>()
   let client: RelayClient | undefined
@@ -409,7 +506,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   let me: EndpointView | null = null
   let announced = false
   let initialized = false
-  /** whether the client takes channel notifications: it says so, or it is Claude Code, which takes them without saying so when started with channels */
+  /** whether the client takes channel notifications: it says so, or it was launched with channels (Claude Code does not say so itself) */
   let channelClient = false
   let stopped = false
   /** seqs this shim pushed, so a push whose confirm was lost is not pushed again */
@@ -561,11 +658,41 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         if (result.held) return text(heldText(result.held))
         const lines = reachLines(result.deliveries)
         const to = result.deliveries.map((d) => (lines.length ? d.address : deliveryText(d))).join(", ")
+        const receipt = result.deliveries.some((d) => d.state === "running" || d.state === "starting")
+          ? [`relay_status with id ${shortId(result.id)} shows when it is read`]
+          : []
         return {
-          ...text([`sent ${result.id} (thread ${result.thread}) to ${to}${redactedText(result.redacted)}`, ...lines].join("\n")),
+          ...text([`sent ${result.id} (thread ${result.thread}) to ${to}${redactedText(result.redacted)}`, ...lines, ...receipt].join("\n")),
           structuredContent: sentContent(result),
         }
       }
+      case "relay_spawn": {
+        const request = spawnRequest(args)
+        const spawn = options.spawn
+        if (!spawn) throw new RelayError("method_not_found", "no tool relay_spawn")
+        const view = await call<EndpointView>("whoami")
+        let started: { name: string; pid: number }
+        try {
+          const cwd = request.cwd ?? (view.cwd && isAbsolute(view.cwd) && isDirectory(view.cwd) ? view.cwd : undefined)
+          started = await spawn({ ...request, as: view.address, ...(view.harness ? { harness: view.harness } : {}), ...(cwd ? { cwd } : {}) })
+        } catch (error) {
+          return text(error instanceof Error ? error.message : String(error), true)
+        }
+        return {
+          ...text(
+            `${started.name} started (pid ${started.pid}) and runs in the background: its messages and its handback reach you by themselves, after your tool calls or when you stop; steer it with relay_send to ${started.name} (it gets the message after its next tool call or before it finishes)`,
+          ),
+          structuredContent: { name: started.name, pid: started.pid },
+        }
+      }
+      case "relay_status": {
+        const receipts = await call<MessageReceipts>("receipts", { id: str(args, "id", true) })
+        const lines = receiptLines(receipts)
+        return {
+          ...text([`${receipts.id}:`, ...(lines.length ? lines : ["no deliveries of it are kept any more"])].join("\n")),
+          structuredContent: { ...receipts },
+        }
+      }
       case "relay_reply": {
         let id = str(args, "id", true)
         const body = str(args, "body", true)
@@ -594,7 +721,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
       case "relay_inbox": {
         const ack = bool(args, "ack") ?? true
         const { messages } = await call<{ messages: Envelope[] }>("inbox", { wait_s: seconds(args, 0) })
-        if (!messages.length) return text("no unread messages")
+        if (!messages.length) return text(`no unread messages${capped(args.wait_s) ? `; waited ${LIMITS.waitMaxS} s (cap)` : ""}`)
         for (const message of messages) remember(message)
         if (ack) await call("ack", { seqs: messages.map((m) => m.seq) })
         return text(delivered(messages))
@@ -780,9 +907,8 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         const protocolVersion = typeof asked === "string" && (MCP_PROTOCOLS as readonly string[]).includes(asked) ? asked : MCP_PROTOCOLS[0]
         initialized = true
         const capabilities = params.capabilities as { experimental?: Record<string, unknown> } | undefined
-        const client = params.clientInfo as { name?: unknown } | undefined
         const channel = capabilities?.experimental?.["claude/channel"]
-        channelClient = (typeof channel === "object" && channel !== null) || client?.name === "claude-code"
+        channelClient = (typeof channel === "object" && channel !== null) || options.launchedWithChannels === true
         return respond({
           protocolVersion,
           capabilities: { tools: {}, ...(options.channels ? { experimental: { "claude/channel": {} } } : {}) },
@@ -793,10 +919,10 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
       case "ping":
         return respond({})
       case "tools/list":
-        return respond({ tools: TOOLS })
+        return respond({ tools })
       case "tools/call": {
         if (!initialized) return write({ jsonrpc: "2.0", id, error: { code: -32002, message: "call initialize first" } })
-        if (!TOOLS.some((t) => t.name === params.name)) {
+        if (!tools.some((t) => t.name === params.name)) {
           return write({ jsonrpc: "2.0", id, error: { code: -32602, message: `unknown tool ${JSON.stringify(params.name)}` } })
         }
         return respond(await callTool(params))