@scp-dev/mcp 0.1.9 → 0.2.0

package/dist/index.d.ts

@@ -25,6 +25,8 @@ interface RelayMcpOptions {
     channels?: boolean;
     /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
     launchedWithChannels?: boolean;
+    /** Claude Code's per-session inbox socket (CLAUDE_CODE_MESSAGING_SOCKET): with channels enabled but not loaded, as in a background session, deliveries are queued there as the next turn */
+    sessionInbox?: SessionInbox;
     /** the wake the endpoint advertises while this shim pushes by channel, over `pi` for a pi client and `channels` for any other */
     wake?: Wake;
     version?: string;
@@ -306,6 +308,19 @@ declare const TOOLS: readonly [{
         };
         readonly additionalProperties: false;
     };
+}, {
+    readonly name: "relay_link_accept";
+    readonly description: "Accept a link request; you then sit under the requesting agent as its worker.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["id"];
+        readonly additionalProperties: false;
+    };
 }, {
     readonly name: "relay_leave";
     readonly description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.";
@@ -480,10 +495,19 @@ declare const TOOLS: readonly [{
         readonly additionalProperties: false;
     };
 }];
+type SessionInbox = {
+    socket: string;
+    token?: string;
+    sessionId?: string;
+};
+/** the inbox of the Claude Code session that started this process, from its environment */
+declare function sessionInboxOf(env: Record<string, string | undefined>): SessionInbox | undefined;
+/** queues one user turn on a Claude Code session's inbox socket; resolves once the lines are flushed and the socket closed */
+declare function sendToSessionInbox(inbox: SessionInbox, content: string, timeoutMs?: number): Promise<void>;
 /**
  * The relay's MCP server over stdio: newline-delimited JSON-RPC 2.0, nothing else on the output.
  * It claims one agent endpoint, keeps one broker connection (heartbeat, reconnect on the next call), and resolves when the input ends.
  */
 declare function runRelayMcp(options: RelayMcpOptions): Promise<void>;
 
-export { INSTRUCTIONS, MCP_PROTOCOLS, type RelayMcpOptions, type SpawnRequest, TOOLS, runRelayMcp };
+export { INSTRUCTIONS, MCP_PROTOCOLS, type RelayMcpOptions, type SessionInbox, type SpawnRequest, TOOLS, runRelayMcp, sendToSessionInbox, sessionInboxOf };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/server.ts
 import { statSync } from "fs";
+import { connect as connectSocket } from "net";
 import { isAbsolute } from "path";
 import {
   CLI_NAME,
@@ -168,6 +169,11 @@ var TOOLS = [
       additionalProperties: false
     }
   },
+  {
+    name: "relay_link_accept",
+    description: "Accept a link request; you then sit under the requesting agent as its worker.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false }
+  },
   {
     name: "relay_leave",
     description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.",
@@ -393,6 +399,37 @@ function delivered(messages) {
 ` : "";
   return [PREAMBLE, ...messages.map((message) => `${shown(message)}${wrapMessage(message)}`)].join("\n\n");
 }
+function sessionInboxOf(env) {
+  const socket = env.CLAUDE_CODE_MESSAGING_SOCKET;
+  if (!socket || !isAbsolute(socket)) return void 0;
+  return {
+    socket,
+    ...env.CLAUDE_CODE_MESSAGING_TOKEN ? { token: env.CLAUDE_CODE_MESSAGING_TOKEN } : {},
+    ...env.CLAUDE_CODE_SESSION_ID ? { sessionId: env.CLAUDE_CODE_SESSION_ID } : {}
+  };
+}
+function sendToSessionInbox(inbox, content, timeoutMs = 5e3) {
+  return new Promise((resolve, reject) => {
+    const socket = connectSocket(inbox.socket);
+    const timer = setTimeout(() => socket.destroy(new Error("session inbox timed out")), timeoutMs);
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    socket.once("close", (failed) => {
+      clearTimeout(timer);
+      if (!failed) resolve();
+    });
+    socket.once("connect", () => {
+      const lines = [
+        ...inbox.token ? [{ type: "auth", token: inbox.token }] : [],
+        { type: "user", ...inbox.sessionId ? { session_id: inbox.sessionId } : {}, priority: "next", message: { role: "user", content } }
+      ];
+      socket.end(lines.map((line) => `${JSON.stringify(line)}
+`).join(""));
+    });
+  });
+}
 async function runRelayMcp(options) {
   const log = options.log ?? (() => {
   });
@@ -406,6 +443,7 @@ async function runRelayMcp(options) {
   let announced = false;
   let initialized = false;
   let channelClient = false;
+  let inbox;
   let stopped = false;
   const channelPushed = /* @__PURE__ */ new Set();
   let channelLoop;
@@ -669,6 +707,11 @@ async function runRelayMcp(options) {
           `joined the relay as ${me?.address}${me?.parent ? ` under ${me.parent}` : ""}: peers can message you, and new messages reach you after your tool calls`
         );
       }
+      case "relay_link_accept": {
+        const result = await call("link_accept", { id: str(args, "id", true) });
+        me = result.endpoint;
+        return text(`${result.endpoint.address} now sits under ${result.parent} as its worker`);
+      }
       case "relay_leave": {
         const view = await call("leave");
         client?.close();
@@ -778,7 +821,7 @@ ${wrapPeek(result)}`);
     }
   }
   async function pushChannel() {
-    while (!stopped && channelClient) {
+    while (!stopped && (channelClient || inbox)) {
       try {
         const { messages, hold } = await call("inbox", { wait_s: LIMITS.injectHoldS, offer: true });
         for (const message of messages) {
@@ -786,16 +829,22 @@ ${wrapPeek(result)}`);
           channelPushed.add(message.seq);
           if (channelPushed.size > DELIVERED_KEEP) channelPushed.delete(channelPushed.values().next().value);
           remember(message);
-          write({
-            jsonrpc: "2.0",
-            method: "notifications/claude/channel",
-            params: {
-              content: `${PREAMBLE}
+          const content = `${PREAMBLE}
 
-${wrapMessage(message)}`,
-              meta: { from: message.from.address, id: message.id, seq: String(message.seq), thread: message.thread }
+${wrapMessage(message)}`;
+          if (inbox) {
+            try {
+              await sendToSessionInbox(inbox, content);
+            } catch (error) {
+              channelPushed.delete(message.seq);
+              throw error;
             }
-          });
+          } else
+            write({
+              jsonrpc: "2.0",
+              method: "notifications/claude/channel",
+              params: { content, meta: { from: message.from.address, id: message.id, seq: String(message.seq), thread: message.thread } }
+            });
         }
         const pushed = messages.flatMap((message) => message.seq !== void 0 && channelPushed.has(message.seq) ? [message.seq] : []);
         if (pushed.length) await call("injected", { seqs: pushed, hold });
@@ -819,7 +868,8 @@ ${wrapMessage(message)}`,
     }
     const params = typeof message.params === "object" && message.params !== null ? message.params : {};
     if (!isRequest) {
-      if (method === "notifications/initialized" && options.channels && channelClient) channelLoop ??= pushChannel().finally(() => channelLoop = void 0);
+      if (method === "notifications/initialized" && options.channels && (channelClient || inbox))
+        channelLoop ??= pushChannel().finally(() => channelLoop = void 0);
       return;
     }
     const respond = (result) => write({ jsonrpc: "2.0", id, result });
@@ -832,7 +882,8 @@ ${wrapMessage(message)}`,
         const channel = capabilities?.experimental?.["claude/channel"];
         channelClient = typeof channel === "object" && channel !== null || options.launchedWithChannels === true;
         const clientInfo = params.clientInfo;
-        wake = options.channels && channelClient ? options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels") : null;
+        inbox = options.channels && !channelClient && clientInfo?.name === "claude-code" ? options.sessionInbox : void 0;
+        wake = options.channels && channelClient ? options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels") : inbox ? "claude-inbox" : null;
         advertise();
         return respond({
           protocolVersion,
@@ -922,5 +973,7 @@ export {
   INSTRUCTIONS,
   MCP_PROTOCOLS,
   TOOLS,
-  runRelayMcp
+  runRelayMcp,
+  sendToSessionInbox,
+  sessionInboxOf
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/mcp",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "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.3.0",
-    "@scp-dev/core": "0.2.0"
+    "@scp-dev/broker": "0.4.0",
+    "@scp-dev/core": "0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/index.ts

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

package/src/server.ts

@@ -1,4 +1,5 @@
 import { statSync } from "node:fs"
+import { connect as connectSocket } from "node:net"
 import { isAbsolute } from "node:path"
 import {
   type AskResult,
@@ -67,6 +68,8 @@ export interface RelayMcpOptions {
   channels?: boolean
   /** the client was started with channels loaded (Claude Code does not declare the capability itself) */
   launchedWithChannels?: boolean
+  /** Claude Code's per-session inbox socket (CLAUDE_CODE_MESSAGING_SOCKET): with channels enabled but not loaded, as in a background session, deliveries are queued there as the next turn */
+  sessionInbox?: SessionInbox
   /** the wake the endpoint advertises while this shim pushes by channel, over `pi` for a pi client and `channels` for any other */
   wake?: Wake
   version?: string
@@ -243,6 +246,11 @@ export const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_link_accept",
+    description: "Accept a link request; you then sit under the requesting agent as its worker.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
+  },
   {
     name: "relay_leave",
     description: "Take this session off the relay: it goes offline and gets no new messages pushed; its mail is kept until relay_join.",
@@ -517,6 +525,42 @@ function delivered(messages: Envelope[]): string {
   return [PREAMBLE, ...messages.map((message) => `${shown(message)}${wrapMessage(message)}`)].join("\n\n")
 }
 
+export type SessionInbox = { socket: string; token?: string; sessionId?: string }
+
+/** the inbox of the Claude Code session that started this process, from its environment */
+export function sessionInboxOf(env: Record<string, string | undefined>): SessionInbox | undefined {
+  const socket = env.CLAUDE_CODE_MESSAGING_SOCKET
+  if (!socket || !isAbsolute(socket)) return undefined
+  return {
+    socket,
+    ...(env.CLAUDE_CODE_MESSAGING_TOKEN ? { token: env.CLAUDE_CODE_MESSAGING_TOKEN } : {}),
+    ...(env.CLAUDE_CODE_SESSION_ID ? { sessionId: env.CLAUDE_CODE_SESSION_ID } : {}),
+  }
+}
+
+/** queues one user turn on a Claude Code session's inbox socket; resolves once the lines are flushed and the socket closed */
+export function sendToSessionInbox(inbox: SessionInbox, content: string, timeoutMs = 5000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const socket = connectSocket(inbox.socket)
+    const timer = setTimeout(() => socket.destroy(new Error("session inbox timed out")), timeoutMs)
+    socket.once("error", (error) => {
+      clearTimeout(timer)
+      reject(error)
+    })
+    socket.once("close", (failed) => {
+      clearTimeout(timer)
+      if (!failed) resolve()
+    })
+    socket.once("connect", () => {
+      const lines = [
+        ...(inbox.token ? [{ type: "auth", token: inbox.token }] : []),
+        { type: "user", ...(inbox.sessionId ? { session_id: inbox.sessionId } : {}), priority: "next", message: { role: "user", content } },
+      ]
+      socket.end(lines.map((line) => `${JSON.stringify(line)}\n`).join(""))
+    })
+  })
+}
+
 /**
  * The relay's MCP server over stdio: newline-delimited JSON-RPC 2.0, nothing else on the output.
  * It claims one agent endpoint, keeps one broker connection (heartbeat, reconnect on the next call), and resolves when the input ends.
@@ -534,6 +578,8 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   let initialized = false
   /** 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
+  /** the session inbox deliveries go to instead, for a Claude Code client without channels loaded */
+  let inbox: SessionInbox | undefined
   let stopped = false
   /** seqs this shim pushed, so a push whose confirm was lost is not pushed again */
   const channelPushed = new Set<number>()
@@ -817,6 +863,11 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
           `joined the relay as ${me?.address}${me?.parent ? ` under ${me.parent}` : ""}: peers can message you, and new messages reach you after your tool calls`,
         )
       }
+      case "relay_link_accept": {
+        const result = await call<{ endpoint: EndpointView; parent: string }>("link_accept", { id: str(args, "id", true) })
+        me = result.endpoint
+        return text(`${result.endpoint.address} now sits under ${result.parent} as its worker`)
+      }
       case "relay_leave": {
         const view = await call<EndpointView>("leave")
         client?.close()
@@ -929,7 +980,7 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
   }
 
   async function pushChannel(): Promise<void> {
-    while (!stopped && channelClient) {
+    while (!stopped && (channelClient || inbox)) {
       try {
         const { messages, hold } = await call<{ messages: Envelope[]; hold?: string | null }>("inbox", { wait_s: LIMITS.injectHoldS, offer: true })
         for (const message of messages) {
@@ -937,14 +988,20 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
           channelPushed.add(message.seq)
           if (channelPushed.size > DELIVERED_KEEP) channelPushed.delete(channelPushed.values().next().value!)
           remember(message)
-          write({
-            jsonrpc: "2.0",
-            method: "notifications/claude/channel",
-            params: {
-              content: `${PREAMBLE}\n\n${wrapMessage(message)}`,
-              meta: { from: message.from.address, id: message.id, seq: String(message.seq), thread: message.thread },
-            },
-          })
+          const content = `${PREAMBLE}\n\n${wrapMessage(message)}`
+          if (inbox) {
+            try {
+              await sendToSessionInbox(inbox, content)
+            } catch (error) {
+              channelPushed.delete(message.seq)
+              throw error
+            }
+          } else
+            write({
+              jsonrpc: "2.0",
+              method: "notifications/claude/channel",
+              params: { content, meta: { from: message.from.address, id: message.id, seq: String(message.seq), thread: message.thread } },
+            })
         }
         const pushed = messages.flatMap((message) => (message.seq !== undefined && channelPushed.has(message.seq) ? [message.seq] : []))
         if (pushed.length) await call("injected", { seqs: pushed, hold })
@@ -969,7 +1026,8 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
     }
     const params = (typeof message.params === "object" && message.params !== null ? message.params : {}) as Json
     if (!isRequest) {
-      if (method === "notifications/initialized" && options.channels && channelClient) channelLoop ??= pushChannel().finally(() => (channelLoop = undefined))
+      if (method === "notifications/initialized" && options.channels && (channelClient || inbox))
+        channelLoop ??= pushChannel().finally(() => (channelLoop = undefined))
       return
     }
     const respond = (result: unknown) => write({ jsonrpc: "2.0", id, result })
@@ -982,7 +1040,8 @@ export async function runRelayMcp(options: RelayMcpOptions): Promise<void> {
         const channel = capabilities?.experimental?.["claude/channel"]
         channelClient = (typeof channel === "object" && channel !== null) || options.launchedWithChannels === true
         const clientInfo = params.clientInfo as { name?: unknown } | undefined
-        wake = options.channels && channelClient ? (options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels")) : null
+        inbox = options.channels && !channelClient && clientInfo?.name === "claude-code" ? options.sessionInbox : undefined
+        wake = options.channels && channelClient ? (options.wake ?? (clientInfo?.name === "pi" ? "pi" : "channels")) : inbox ? "claude-inbox" : null
         advertise()
         return respond({
           protocolVersion,