Agents That Message Each Other, in Turn

// Lines 1 to 41 elided: the module header and the imports. Full file: server/src/agent-mail.js at tag module-32.

/**
* The MCP server name every agent's mail server is registered under.
*
* The same name for every agent, because the name is part of the wire tool name
* the model sees, `mcp__workbench__send_to_agent`, and a name carrying the
* caller's agentId would make one agent's transcript unreadable beside another's
* for no gain. The instances differ; the name does not.
*
* `mcp__server__tool_name` is the SDK's own naming, given at
* @anthropic-ai/claude-agent-sdk 0.3.251 sdk.d.ts line 3964: "Fully-qualified
* MCP tool name, e.g. mcp__server__tool_name", with the note that server names
* are normalized so non-`[a-zA-Z0-9_-]` becomes `_`. "workbench" needs no
* normalising.
*/
export const MAIL_SERVER_NAME = "workbench";

/**
* The version reported on the MCP server.
*
* `CreateSdkMcpServerOptions.version` is optional (sdk.d.ts line 514). It is set
* anyway, because a server that reports no version is a server nobody can talk
* about later. The number is the module that introduced it, not the package's:
* this server's surface is two tools, and it changes when a module changes it.
*/
export const MAIL_SERVER_VERSION = "32.0.0";

/** The two tool names, unqualified. */
export const LIST_AGENTS_TOOL = "list_agents";
export const SEND_TO_AGENT_TOOL = "send_to_agent";

/**
* The fully-qualified names the model calls and `allowedTools` names.
*
* Both are listed in `allowedTools` because every session runs under
* `permissionMode: 'dontAsk'`, documented at sdk.d.ts line 1826 as "Don't prompt
* for permissions, deny if not pre-approved". A tool nothing pre-approves is a
* tool that is denied, and this application has no approval frames to answer a
* prompt with. Record 0011 is what makes that the mode; record 0073 is why these
* two names are the only additions to the allow list.
*/
export const LIST_AGENTS_WIRE_NAME = `mcp__${MAIL_SERVER_NAME}__${LIST_AGENTS_TOOL}`;
export const SEND_TO_AGENT_WIRE_NAME = `mcp__${MAIL_SERVER_NAME}__${SEND_TO_AGENT_TOOL}`;

export const MAIL_TOOL_NAMES = Object.freeze([
LIST_AGENTS_WIRE_NAME,
SEND_TO_AGENT_WIRE_NAME,
]);

/**
* The prefix stamped onto every delivered message, before the sender's name.
*
* The name and not the agentId. A model reads prose, and `[message from Ledger]`
* is prose; `[message from agent-2]` is a database row. The id is what
* `send_to_agent` takes and what `list_agents` prints beside each name, so a
* model that wants to reply has the mapping in front of it either way. Record
* 0074, which also says what it costs: two agents named the same are
* indistinguishable in a prefix, and the roster does not forbid that.
*
* @param {string} name The sender's name, as the roster holds it now.
* @returns {string}
*/
export function mailPrefix(name) {
return `[message from ${name}] `;
}

/**
* The text `send_to_agent` returns after a delivery.
*
* This is the sentence the module turns on, and record 0072 is the argument for
* every clause of it. Short version: a tool description is read once, before the
* model has done anything; a tool result is read immediately after the model has
* acted, at the exact moment it is deciding what to do next. The second position
* is worth more, so the asynchrony is stated there rather than left to the
* description.
*
* The recipient is named because the model addressed an id and thinks in names,
* and both are given so a follow-up needs no second `list_agents` call.
*
* @param {AgentRecord} to
* @returns {string}
*/
export function deliveredText(to) {
return [
  `Delivered to ${to.name} (${to.agentId}).`,
  "Delivery is asynchronous. It has not been read yet and will not be read until",
  `${to.name} reaches its own next turn boundary, which may be a while.`,
  "Do not wait for a reply, and do not send again to prompt one:",
  "carry on with your own work; the reply, if any, arrives as a later message.",
].join(" ");
}

// The CallToolResult helpers and rosterText elided.

/**
* Build one agent's mail: two handlers, and the MCP server that wraps them.
*
* The caller is `self`, closed over here and never taken from a tool argument.
* A `from` field in the input schema would be a field the model fills in, and a
* model that can fill it in can fill it in wrongly, or usefully, from its point
* of view, by claiming to be somebody else. Closing over the record makes the
* question unaskable. Record 0071.
*
* @param {object} deps
* @param {AgentRecord} deps.self The agent whose session gets these tools. Held
*   by reference, so a rename that mutates the record in place is reflected in
*   the prefix on the next message this agent sends.
* @param {() => AgentRecord[]} deps.listAgents Every record on the roster,
*   including `self`; this module does the excluding.
* @param {(agentId: string) => boolean} deps.isLive Whether a conversation
*   exists for that agent on this connection.
* @param {(toId: string, text: string) => { ok: true, id: string, queued: boolean }
*   | { ok: false, message: string }} deps.deliver Put the text in an agent's
*   queue. `session.js` supplies it; see `deliverToAgent` there.
* @returns {{
*   serverName: string,
*   toolNames: readonly string[],
*   server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance,
*   handlers: {
*     listAgents: (args: {}) => Promise<any>,
*     sendToAgent: (args: { agentId: string, text: string }) => Promise<any>,
*   },
*   peers: () => AgentRecord[],
* }}
*/
export function createAgentMail({ self, listAgents, isLive, deliver }) {
/** Every agent but the caller, in roster order. */
const peers = () =>
  listAgents().filter((agent) => agent.agentId !== self.agentId);

// The two failure paths of send_to_agent elided: addressing yourself, and an id nobody holds.

  if (text.trim() === "") {
    return failed("send_to_agent needs some text to deliver.");
  }

  const outcome = deliver(to.agentId, text);
  if (!outcome.ok) return failed(outcome.message);

  return ok(deliveredText(to));
}

// `tool()` is declared at sdk.d.ts line 8349:
//   tool<Schema extends AnyZodRawShape>(_name, _description, _inputSchema,
//     _handler: (args: InferShape<Schema>, extra: unknown) =>
//       Promise<CallToolResult>, _extras?): SdkMcpToolDefinition<Schema>
// The third argument is a raw Zod shape, an object of Zod types, not a
// `z.object(...)`, which is what `AnyZodRawShape` means and why the two
// fields below are written bare. `SdkMcpToolDefinition` at lines 4461 to 4468
// is the object it returns: name, description, inputSchema, handler.
const tools = [
  tool(
    LIST_AGENTS_TOOL,
    "List the other agents on this workbench roster, with the id to address each one by. Call this before send_to_agent if you do not already know an id.",
    {},
    handleListAgents,
  ),
  tool(
    SEND_TO_AGENT_TOOL,
    "Send a message to another agent on this roster. Delivery is asynchronous: the text is put in that agent's queue and read at its next turn boundary, and any reply comes back to you later as a new message. This tool never returns a reply.",
    {
      // `.describe()` last, so the description is on the finished type rather
      // than on an intermediate one that a later `.min()` would replace.
      agentId: z
        .string()
        .describe(
          "The recipient's agentId, exactly as list_agents printed it. Not its name.",
        ),
      text: z
        .string()
        .describe(
          "What to say. The recipient sees it prefixed with your name, and knows it came from another agent.",
        ),
    },
    handleSendToAgent,
  ),
];

// `createSdkMcpServer` is declared at sdk.d.ts line 510 and documented at
// lines 502 to 509: "Creates an MCP server instance that can be used with the
// SDK transport. This allows SDK users to define custom tools that run in the
// same process." Its options type at lines 512 to 530 is
// `{ name, version?, instructions?, tools?, alwaysLoad?, ... }`, and it
// returns `McpSdkServerConfigWithInstance` (line 1102), the config object
// with a live `McpServer` on it, which is what `Options.mcpServers` (line
// 1797, `Record<string, McpServerConfig>`) accepts.
//
// In the same process is the whole reason this is an SDK server rather than a
// stdio one. The handlers above close over `self` and over `deliver`, which
// reaches this connection's conversations. A subprocess server would need the
// queue on the other side of a pipe.
const server = createSdkMcpServer({
  name: MAIL_SERVER_NAME,
  version: MAIL_SERVER_VERSION,
  tools,
});

return {
  serverName: MAIL_SERVER_NAME,
  toolNames: MAIL_TOOL_NAMES,
  server,
  handlers: {
    listAgents: handleListAgents,
    sendToAgent: handleSendToAgent,
  },
  peers,
};
}