@bill10/agent-007 0.6.2

package/server/mcp.js

@@ -0,0 +1,596 @@
+// The board's MCP server — how an agent you are talking to can put a card on
+// the job board when you ask it to.
+//
+// Why MCP and not a command on PATH: an agent does not enumerate its PATH, so a
+// binary sitting there is invisible. An MCP tool arrives in the agent's tool
+// list with a name and a description, which is real discovery — and it is a
+// capability, not an instruction. Nothing tells an agent to post jobs; the tool
+// is simply there when the user asks for one.
+//
+// Transport is JSON HTTP served by the app's own Express server. Claude Code
+// connects directly; Codex uses agent-mcp-bridge.js to forward stdio requests
+// while keeping the board credential in its per-session file.
+//
+// Kept free of Express and of the job store so the protocol is testable on its
+// own: handleMcpMessage takes a parsed message and a context, and returns the
+// reply object (or null for a notification, which gets no reply by JSON-RPC).
+// Every tool is a thin wrapper over one injected board function: this module
+// owns the wire text an agent reads, and nothing about how cards are stored.
+
+// lib/jobs.js is the pure half of the board — no store, no Express — so the
+// column names come from there rather than being spelled out a second time.
+import { JOB_STATES, STATE_LABELS, JOB_AGENTS } from '../lib/jobs.js';
+import { APPROVAL_WAIT_MS } from './agent-mcp.js';
+
+// Echoed back from the client's own initialize when it sends one. MCP clients
+// negotiate this, and answering with whatever the client asked for is the
+// behaviour this server wants — there is nothing here that varies by protocol
+// revision.
+export const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+
+export const SERVER_INFO = { name: 'agent-007-board', version: '1' };
+
+// The description is the whole discovery mechanism, so it says what the tool is
+// for and — deliberately — when to reach for it. "When the user asks" is the
+// operative clause: a job board full of work an agent queued for itself is not
+// what this is for.
+export const POST_JOB_TOOL = {
+  name: 'post_job',
+  description:
+    'Post a job card to the Agent 007 job board, in the To do column. Use this when '
+    + 'the user asks you to add something to the board, queue work for later, or hand '
+    + 'a task to another agent — not for work you are already doing. The board '
+    + 'dispatches each card to a fresh agent in its own git worktree and branch, so '
+    + 'the detail must be everything that agent needs to do the work unattended: it '
+    + 'will not have this conversation. Pass `schedule` to make it a recurring job '
+    + 'instead: the card becomes a schedule, and each time it comes due it posts a '
+    + 'run card of its own that goes through the board like any job.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: {
+        type: 'string',
+        description: 'One line naming the work, as it should read on the card.',
+      },
+      detail: {
+        type: 'string',
+        description:
+          'Everything the agent picking this up needs: context, constraints, files, '
+          + 'how to tell it is done. Written for someone who was not in this conversation.',
+      },
+      repo: {
+        type: 'string',
+        description:
+          'Which repository to run the job in — a full path or just the folder name. '
+          + 'Defaults to the repository this terminal is working in.',
+      },
+      schedule: {
+        type: 'string',
+        description:
+          'Optional. Supplying this makes the card a SCHEDULED job that runs again '
+          + 'on every match instead of once: a five-field cron expression in the '
+          + "server's local time (\"0 9 * * 1-5\" = 09:00 on weekdays), or one of "
+          + '@hourly, @daily, @weekly, @monthly, @yearly. Its runs report a summary '
+          + 'unless requires_pr is true. A schedule holds off while its last run is '
+          + 'still going or its PR is open, and a newer no-PR run replaces the last '
+          + 'one in Review. Omit this for ordinary work that should happen once.',
+      },
+      agent: {
+        type: 'string',
+        enum: JOB_AGENTS,
+        description:
+          'Optional. Which CLI the board spawns for this card: claude (Claude Code) '
+          + 'or codex. Defaults to the one you are running as.',
+      },
+      requires_pr: {
+        type: 'boolean',
+        description:
+          'Optional. Whether the work ends in a pull request (on a schedule: whether '
+          + 'each run does). Defaults to true for a one-time job and false for a '
+          + 'schedule; pass false for work that is not a code change — '
+          + 'research, an investigation, an ops chore — so the agent reports a '
+          + 'summary instead of opening a PR.',
+      },
+    },
+    required: ['title'],
+    additionalProperties: false,
+  },
+};
+
+// Reading the board is a separate tool from writing to it so an agent can be
+// asked "what is on the board?" without the answer costing a card. The board is
+// one shared wall — every connected client sees every card — so these show the
+// whole board rather than only what this agent posted.
+export const LIST_JOBS_TOOL = {
+  name: 'list_jobs',
+  description:
+    'List the cards on the Agent 007 job board — To do, In progress and Review, '
+    + 'with the id of each. Use this when the user asks what is on the board, what '
+    + 'is queued or running, or before editing a card, since editing needs the id. '
+    + 'Finished cards are archived off the board: pass state "done" to see those.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      state: {
+        type: 'string',
+        enum: JOB_STATES,
+        description:
+          'Optional. Show only this column: todo, in-progress, review, or done '
+          + '(the finished archive). Omit for the whole board, archive excluded.',
+      },
+      repo: {
+        type: 'string',
+        description:
+          'Optional. Show only cards for this repository — a full path or just the '
+          + 'folder name. Omit for every repository the board knows.',
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+export const READ_JOB_TOOL = {
+  name: 'read_job',
+  description:
+    'Read one card on the Agent 007 job board in full, including the detail the '
+    + 'job agent is given, its branch and pull request, and any error the board hit. '
+    + 'Use this when the user asks what a card says or how it is going. Ids come '
+    + 'from list_jobs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The card id, as list_jobs reports it.' },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+};
+
+export const EDIT_JOB_TOOL = {
+  name: 'edit_job',
+  description:
+    'Change a card that is still in To do: its title, detail, repository, '
+    + 'schedule or whether it requires a pull request. Only To do cards can be edited — once the board has dispatched a '
+    + 'card its agent has already been handed the text, so a later edit would leave '
+    + 'the card describing work nobody was asked to do. Pass only the fields that '
+    + 'change; the rest are left alone. Ids come from list_jobs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The card id, as list_jobs reports it.' },
+      title: { type: 'string', description: 'Replaces the line naming the work.' },
+      detail: {
+        type: 'string',
+        description:
+          'Replaces the whole detail body — this is not appended to what is there, '
+          + 'so read the card first if you mean to add to it.',
+      },
+      repo: {
+        type: 'string',
+        description: 'Move the card to another repository — a full path or folder name.',
+      },
+      schedule: {
+        type: 'string',
+        description:
+          'Replaces the cron schedule (five fields, or an @shorthand). Pass an empty '
+          + 'string to turn a scheduled card back into one that runs once.',
+      },
+      requires_pr: {
+        type: 'boolean',
+        description:
+          'Whether the work ends in a pull request. '
+          + 'Pass false for work that is not a code change — '
+          + 'research, an investigation, an ops chore — so the agent reports a '
+          + 'summary instead of opening a PR.',
+      },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+};
+
+// How a board-dispatched agent reports that its job is done. The card moves to
+// Review; the agent keeps running there until the card reaches Done.
+export const FINISH_JOB_TOOL = {
+  name: 'finish_job',
+  description:
+    'Report that the job-board job you were dispatched to do is finished, which '
+    + 'moves its card to Review. Only for an agent the board dispatched, and only '
+    + 'once the work is done. If the job requires a pull request, run your ship skill (/ship, or $ship in Codex) first, '
+    + 'wait for it to open the PR, and pass its URL as pr_url. If it does not, pass '
+    + 'a summary of what you did or found — that is what the reviewer reads.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      pr_url: {
+        type: 'string',
+        description: 'The pull request URL. Required when the job requires a pull request.',
+      },
+      summary: {
+        type: 'string',
+        description:
+          'What you did or found, written for someone who was not watching. Required '
+          + 'when the job needs no pull request; optional otherwise.',
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+// Messaging lives on this same server because it is the one both CLIs already
+// load: Claude Code's own SendMessage reaches only other Claude Code sessions.
+export const LIST_AGENTS_TOOL = {
+  name: 'list_agents',
+  description:
+    'List the other agents running in Agent 007 that you can message with '
+    + 'send_message — Claude Code and Codex alike — with the repo and branch each '
+    + 'is on, what it is doing, and its job card if it has one. Use this when the '
+    + 'user asks you to ask, tell or coordinate with another agent.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+};
+
+export const SEND_MESSAGE_TOOL = {
+  name: 'send_message',
+  description:
+    'Send a message to another agent running in Agent 007, whether it runs on '
+    + 'Claude Code or Codex. It arrives in that agent\'s terminal as a new turn '
+    + 'once the agent is idle at its prompt, marked as coming from you, and any '
+    + 'reply comes back to you the same way — this call does not wait for one. '
+    + 'Use it when the user asks you to ask, tell or coordinate with another '
+    + 'agent; do not start conversations of your own accord. Names come from '
+    + 'list_agents.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      to: { type: 'string', description: 'The agent\'s name, as list_agents prints it.' },
+      message: {
+        type: 'string',
+        description: 'What to say. The recipient was not in this conversation, so '
+          + 'include the context it needs to answer.',
+      },
+    },
+    required: ['to', 'message'],
+    additionalProperties: false,
+  },
+};
+
+// Billion's alone (server/billion.js): listed only for its session.
+export const BILLION_READY_TOOL = {
+  name: 'billion_ready',
+  description:
+    'Open your inbox: until you call this, messages from agents and job board '
+    + 'notices wait instead of being typed into your terminal. Call it when your '
+    + 'introduction is done and at the start of every operating cycle; calling it '
+    + 'again does nothing.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+};
+
+export const ADD_REPO_TOOL = {
+  name: 'add_repo',
+  description:
+    'Add a git repository to the Agent 007 board, so job cards can be posted in it '
+    + 'and it shows in the owner\'s left panel. Use it after creating a new '
+    + 'project\'s repo (with its remote and a pushed main). Adding one already '
+    + 'on the board does nothing.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Absolute path to the repository on this machine (~/ is allowed).' },
+    },
+    required: ['path'],
+    additionalProperties: false,
+  },
+};
+
+export const CLOSE_JOB_TOOL = {
+  name: 'close_job',
+  description:
+    'Close one of your own cards that is in Review. accept: true files a card with '
+    + 'no pull request as Done (a card with a PR is filed away when you merge the '
+    + 'PR, or close it to drop the work). accept: false sends it back to To do '
+    + 'with your note added to its detail, for a fresh worker to redo; if it had a '
+    + 'pull request, close that one afterwards. Either way its worker is closed.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The card id, as list_jobs reports it.' },
+      accept: { type: 'boolean', description: 'true: Done. false: back to To do.' },
+      note: { type: 'string', description: 'Required when sending it back: what the next worker must do differently.' },
+    },
+    required: ['id', 'accept'],
+    additionalProperties: false,
+  },
+};
+
+export const ANSWER_PERMISSION_TOOL = {
+  name: 'answer_permission',
+  description:
+    'Answer a worker\'s permission request, which arrives in your terminal as '
+    + '"[Approval <id>] …". allow lets the worker go ahead; deny refuses, and your '
+    + 'reason is what the worker reads; owner leaves it to the owner, who then sees '
+    + `the worker's dialog. Unanswered requests go to the owner after ${APPROVAL_WAIT_MS / 60000} minutes.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The id from the [Approval <id>] line.' },
+      decision: { type: 'string', enum: ['allow', 'deny', 'owner'] },
+      reason: { type: 'string', description: 'For deny: what the worker should do instead.' },
+    },
+    required: ['id', 'decision'],
+    additionalProperties: false,
+  },
+};
+
+export const TOOLS = [POST_JOB_TOOL, LIST_JOBS_TOOL, READ_JOB_TOOL, EDIT_JOB_TOOL, FINISH_JOB_TOOL, LIST_AGENTS_TOOL, SEND_MESSAGE_TOOL];
+const BILLION_TOOLS = [BILLION_READY_TOOL, ADD_REPO_TOOL, CLOSE_JOB_TOOL, ANSWER_PERMISSION_TOOL];
+
+export function toolsFor(session) {
+  return session?.isBillion ? [...TOOLS, ...BILLION_TOOLS] : TOOLS;
+}
+
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+// A tool that failed is not a protocol error: MCP reports it as a normal result
+// with isError, so the model reads the reason and can correct itself. A JSON-RPC
+// error would surface to the agent as "the tool is broken" instead.
+const toolText = (text, isError = false) => ({ content: [{ type: 'text', text }], isError });
+
+// A stored time as the server's clock reads it (agents talk to this board over
+// loopback, so that is the reader's clock too). The stored value is ISO; an
+// agent reporting "next 2026-09-04T09:00:00.000Z" to a person is making them do
+// the conversion.
+const when = (iso) => (iso ? new Date(iso).toLocaleString() : null);
+
+// The cron and its next firing, built once: four builders used to spell this
+// out with three different separators, so the same fact read three ways.
+const scheduleText = (job, sep = ', next ') =>
+  `${job.schedule}${job.nextRunAt ? `${sep}${when(job.nextRunAt)}` : ''}`;
+
+// One line per card: what it is, and the id needed to read or edit it. Kept
+// lean deliberately — who posted it and the whole detail body are what read_job
+// is for, and a board of twenty cards is answering "what is queued?", not
+// twenty questions.
+function summaryLine(job) {
+  const bits = [job.repo];
+  if (job.agent === 'codex') bits.push('codex');
+  if (job.type === 'scheduled') {
+    bits.push(`schedule ${scheduleText(job)}`);
+  }
+  if (job.scheduleId) bits.push('a scheduled run');
+  // The live state of the agent working it, when there is one, is the part a
+  // person actually asks about ("is it stuck?").
+  if (job.agentName) bits.push(`${job.agentName}${job.status ? ` ${job.status}` : ''}`);
+  // So an agent can tell its own cards apart without a read_job per card.
+  if (job.postedByAgent) bits.push(`posted by ${job.postedByAgent}`);
+  if (job.prUrl) bits.push(job.prUrl);
+  return `  ${job.id}  ${job.title}\n    ${bits.filter(Boolean).join(' · ')}`;
+}
+
+const CALLS = {
+  [POST_JOB_TOOL.name]: (args, ctx) => {
+    const result = ctx.postJob({
+      title: args.title,
+      detail: args.detail,
+      repo: args.repo,
+      schedule: args.schedule,
+      agent: args.agent,
+      requiresPr: args.requires_pr,
+      session: ctx.session || null,
+    });
+    if (result.error) return toolText(result.error, true);
+
+    const where = result.repoName ? ` in ${result.repoName}` : '';
+    // Read back the schedule the board actually stored, and when it next fires.
+    // A cron expression is easy to get subtly wrong ("0 0 * * 0" is not weekly
+    // to everyone), and a concrete next-run time is what makes the mistake
+    // visible while the user is still in the conversation to correct it.
+    const fires = result.job.schedule ? ` on a schedule (${scheduleText(result.job)})` : '';
+    const column = result.job.schedule ? '' : result.job.requiresPr === false ? ' (To do, no pull request)' : ' (To do)';
+    const line = `Posted "${result.job.title}"${where}${fires} to the Agent 007 job board${column}.`;
+    // The dispatcher note matters: with the board stopped the card sits there
+    // doing nothing, and an agent reporting "queued it" without saying so would
+    // leave the user believing work had started.
+    const note = result.dispatcherRunning
+      ? ''
+      : ' The board dispatcher is stopped, so it waits there until the board is started.';
+    // The id, because editing a card needs it and the agent has it right here.
+    return toolText(`${line}${note}\nid: ${result.job.id}`);
+  },
+
+  [LIST_JOBS_TOOL.name]: (args, ctx) => {
+    const result = ctx.listJobs({ state: args.state, repo: args.repo });
+    if (result.error) return toolText(result.error, true);
+
+    const scope = [result.state ? STATE_LABELS[result.state] : null, result.repoName]
+      .filter(Boolean).join(' · ');
+    if (!result.jobs.length) {
+      // An empty board and a filtered-out board read the same otherwise, and
+      // the archive is invisible by default — say which this is.
+      const archive = result.archived ? ` ${result.archived} finished card(s) are archived (state: "done").` : '';
+      return toolText(`Nothing on the Agent 007 job board${scope ? ` for ${scope}` : ''}.${archive}`);
+    }
+    // Grouped by column in board order, so the shape of the answer is the shape
+    // of the board the user is looking at.
+    const groups = JOB_STATES
+      .map(state => [state, result.jobs.filter(job => job.state === state)])
+      .filter(([, jobs]) => jobs.length)
+      .map(([state, jobs]) => `${STATE_LABELS[state]} (${jobs.length})\n${jobs.map(summaryLine).join('\n')}`);
+    const head = `${result.jobs.length} card(s) on the Agent 007 job board${scope ? ` — ${scope}` : ''}:`;
+    const archive = result.archived
+      ? `\n\n${result.archived} finished card(s) are archived off the board (state: "done").`
+      : '';
+    return toolText(`${head}\n\n${groups.join('\n\n')}${archive}`);
+  },
+
+  [READ_JOB_TOOL.name]: (args, ctx) => {
+    const result = ctx.readJob(args.id);
+    if (result.error) return toolText(result.error, true);
+    const job = result.job;
+    const lines = [
+      `${job.title}`,
+      `id: ${job.id}`,
+      `column: ${STATE_LABELS[job.state] || job.state}${job.status ? ` (${job.status})` : ''}`,
+      `repo: ${job.repo}`,
+      // Only when it is not the default, the way the card's chip works.
+      job.agent === 'codex' ? 'runs on: codex' : null,
+      job.type === 'scheduled'
+        ? `schedule: ${scheduleText(job, ' — next ')}`
+          + `${job.runCount ? ` — posted ${job.runCount} run(s), last ${when(job.lastRunAt)}` : ''}`
+          + `${job.requiresPr ? ', each run opens a pull request' : ''}`
+          + `${job.lastSkipReason ? ` — last held off: ${job.lastSkipReason}` : ''}`
+        : `schedule: runs once${job.requiresPr ? '' : ', no pull request'}`
+          + `${job.scheduleId ? ` (a run of schedule ${job.scheduleId})` : ''}`,
+      `posted: ${when(job.postedAt)}`
+        + `${job.postedByName ? ` by ${job.postedByName}` : ''}`
+        + `${job.postedByAgent ? ` (typed by ${job.postedByAgent})` : ''}`,
+      job.agentName ? `agent: ${job.agentName}, started ${when(job.startedAt)}` : null,
+      job.branchName ? `branch: ${job.branchName}` : null,
+      job.prUrl ? `pull request: ${job.prUrl}${job.prMergedAt ? ` (merged ${when(job.prMergedAt)})` : job.prClosedAt ? ` (closed without merging ${when(job.prClosedAt)})` : ''}` : null,
+      job.resultSummary ? `result: ${job.resultSummary}` : null,
+      job.attachments.length ? `attachments: ${job.attachments.join(', ')}` : null,
+      // Whoever last changed the text, so a card an agent rewrote never reads
+      // as if the person who queued it wrote what is there now.
+      job.editedByAgent ? `edited by ${job.editedByAgent}${job.editedAt ? ` on ${when(job.editedAt)}` : ''}` : null,
+      // Surfaced, not swallowed: a card that failed to dispatch looks identical
+      // to one waiting its turn unless the reason is said out loud.
+      job.lastError ? `last error: ${job.lastError}` : null,
+      job.prCheckError ? `pull request check: ${job.prCheckError}` : null,
+      // Kept in step by hand with editableInPlace in server/jobs.js and with
+      // EDIT_JOB_TOOL's description above: three statements of one rule.
+      job.state === 'todo' ? null : 'This card has left To do, so edit_job can no longer change it.',
+      '',
+      job.detail || '(no detail on this card)',
+    ];
+    return toolText(lines.filter(line => line !== null).join('\n'));
+  },
+
+  [EDIT_JOB_TOOL.name]: (args, ctx) => {
+    const result = ctx.editJob({
+      id: args.id,
+      title: args.title,
+      detail: args.detail,
+      repo: args.repo,
+      schedule: args.schedule,
+      requiresPr: args.requires_pr,
+    });
+    if (result.error) return toolText(result.error, true);
+    const job = result.job;
+    const fires = job.type === 'scheduled' ? ` It runs ${scheduleText(job)}.` : '';
+    return toolText(
+      `Updated ${result.changed.join(', ')} on "${job.title}" (${job.repo}), still in To do.${fires}`,
+    );
+  },
+
+  // Async: checking the PR is a network call. handleMcpMessage passes the
+  // promise through, and the route awaits it.
+  [FINISH_JOB_TOOL.name]: async (args, ctx) => {
+    const result = await ctx.finishJob({ prUrl: args.pr_url, summary: args.summary });
+    if (result.error) return toolText(result.error, true);
+    return toolText(`"${result.job.title}" is in Review. You are done — end your turn here.`);
+  },
+
+  [BILLION_READY_TOOL.name]: (args, ctx) => {
+    const result = ctx.billionReady ? ctx.billionReady() : { error: 'Only Billion has an inbox to open.' };
+    if (result.error) return toolText(result.error, true);
+    return toolText(result.waiting
+      ? `Inbox open. ${result.waiting} message(s) will arrive one at a time as you come to rest at your prompt.`
+      : 'Inbox open. Nothing is waiting.');
+  },
+
+  [ADD_REPO_TOOL.name]: async (args, ctx) => {
+    const result = await ctx.addRepo(args.path);
+    if (result.error) return toolText(result.error, true);
+    return toolText(`${result.path} is on the board as "${result.slug}". post_job can use it now.`);
+  },
+
+  [CLOSE_JOB_TOOL.name]: async (args, ctx) => {
+    const result = await ctx.closeJob({ id: args.id, accept: args.accept === true, note: args.note });
+    if (result.error) return toolText(result.error, true);
+    return toolText(result.accepted
+      ? `"${result.job.title}" is Done and its worker is closed.`
+      : `"${result.job.title}" is back in To do with your note; a fresh worker picks it up on the next dispatch.`
+        + (result.oldPrUrl ? ` Its old pull request is still open: close ${result.oldPrUrl}.` : ''));
+  },
+
+  [ANSWER_PERMISSION_TOOL.name]: (args, ctx) => {
+    const result = ctx.answerPermission({ id: args.id, decision: args.decision, reason: args.reason });
+    if (result.error) return toolText(result.error, true);
+    if (result.cut) return toolText(`That request was cut short, so your allow went to the owner instead: ${result.worker}'s dialog is showing for them now.`);
+    return toolText(result.choice === 'owner'
+      ? `Left to the owner: ${result.worker}'s dialog is showing for them now.`
+      : `${result.worker} has your answer: ${result.choice}.`);
+  },
+
+  [LIST_AGENTS_TOOL.name]: (args, ctx) => {
+    const agents = ctx.listAgents();
+    if (!agents.length) return toolText('No other agents are running that you can message.');
+    const lines = agents.map(a => {
+      const bits = [a.agent, a.repoSlug, a.branchName, a.state?.toLowerCase(),
+        a.jobTitle ? `job: ${a.jobTitle}` : null,
+        a.pending ? `${a.pending} message(s) waiting for it` : null];
+      return `  ${a.name}\n    ${bits.filter(Boolean).join(' · ')}`;
+    });
+    return toolText(`${agents.length} agent(s) you can message:\n${lines.join('\n')}`);
+  },
+
+  [SEND_MESSAGE_TOOL.name]: (args, ctx) => {
+    const result = ctx.sendMessage({ to: args.to, text: args.message });
+    if (result.error) return toolText(result.error, true);
+    // Say which, so an agent does not report "asked it" and then wait on an
+    // answer that cannot come until the other one stops working.
+    return toolText(result.delivered
+      ? `Delivered to ${result.to.name}. Its reply, if any, will arrive as a message in this terminal.`
+      : `Queued for ${result.to.name} (position ${result.queued}); it gets the message once it is next free at its prompt. Its reply, if any, will arrive as a message in this terminal.`);
+  },
+};
+
+/**
+ * Handle one JSON-RPC message.
+ *
+ * @param msg      parsed JSON-RPC request or notification
+ * @param ctx      { session, postJob, listJobs, readJob, editJob, finishJob, listAgents,
+ *                 sendMessage } — the agent
+ *                 this token belongs to, and the injected board functions
+ *                 (server/jobs.js, the write ones bound to a broadcast), kept
+ *                 as parameters so this module never imports the job store.
+ * @returns the reply object, or null when the message is a notification — or
+ *          a promise of the reply, for a tool that has to wait (finish_job).
+ */
+export function handleMcpMessage(msg, ctx = {}) {
+  const { id, method, params } = msg || {};
+  // JSON-RPC notifications carry no id and MUST NOT be answered. The client
+  // sends notifications/initialized right after the handshake.
+  const isNotification = id === undefined || id === null;
+
+  if (method === 'initialize') {
+    return ok(id, {
+      protocolVersion: params?.protocolVersion || DEFAULT_PROTOCOL_VERSION,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: SERVER_INFO,
+    });
+  }
+
+  if (isNotification) return null;
+
+  if (method === 'ping') return ok(id, {});
+  if (method === 'tools/list') return ok(id, { tools: toolsFor(ctx.session) });
+
+  if (method === 'tools/call') {
+    // hasOwn, not truthiness: a plain object inherits Object.prototype, so a
+    // call naming "valueOf" or "toString" would otherwise find a function on
+    // the chain and run it — a 500 for the first, and a result of
+    // "[object Undefined]" for the second, neither of them a tool.
+    const name = params?.name;
+    if (typeof name !== 'string' || !Object.hasOwn(CALLS, name)
+      || !toolsFor(ctx.session).some(tool => tool.name === name)) {
+      return fail(id, -32602, `Unknown tool: ${name}`);
+    }
+    const result = CALLS[name](params?.arguments || {}, ctx);
+    return result instanceof Promise ? result.then(r => ok(id, r)) : ok(id, result);
+  }
+
+  // Everything else, including the client's own discovery probes. JSON-RPC says
+  // method-not-found; Claude Code handles it and carries on.
+  return fail(id, -32601, `Method not found: ${method}`);
+}