Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(mcp): an agent works the loop through MCP; init wires it [A9,P6]
Corey Olson280ccacb8241
diff --git a/src/init.js b/src/init.jsindex 628da881..6bdfb9ba 100644--- a/src/init.js+++ b/src/init.js@@ -417,6 +417,55 @@ function writeAgentDocs(root, onWrite) {export const RESUME_HOOK ='m=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/..; for p in node_modules/.bin/pullboard "$m/node_modules/.bin/pullboard"; do [ -x "$p" ] && exec "$p" resume; done; command -v pullboard >/dev/null && exec pullboard resume; true';+/**+ * The MCP server command: pullboard from this checkout's install, else the main checkout's, else the PATH (#961).+ * It runs through sh -c, as the session hook does, so one entry works however pullboard was installed.+ */+export const MCP_COMMAND =+ 'm=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/..; for p in node_modules/.bin/pullboard "$m/node_modules/.bin/pullboard"; do [ -x "$p" ] && exec "$p" mcp; done; command -v pullboard >/dev/null && exec pullboard mcp; echo "pullboard is not installed; npm i -D pullboard" >&2; exit 1';++/**+ * Register pullboard mcp for Claude Code (.mcp.json) and Codex (.codex/config.toml), merging with any servers already+ * there and never replacing a pullboard entry or a file it cannot read, so an agent can work the loop through MCP (#961).+ *+ * @param {string} root+ * @param {(path: string) => void} onWrite+ * @returns {string[]} What happened, one note per client.+ */+function writeMcpConfig(root, onWrite) {+ const notes = [];+ const claude = join(root, '.mcp.json');+ let config = {};+ if (existsSync(claude)) {+ try { config = JSON.parse(readFileSync(claude, 'utf8')); } catch { config = null; }+ }+ const servers = config?.mcpServers;+ if (!config || typeof config !== 'object' || Array.isArray(config) || (servers !== undefined && (!servers || typeof servers !== 'object' || Array.isArray(servers)))) {+ notes.push('kept .mcp.json, which is not a JSON object with an mcpServers object; add a pullboard server that runs pullboard mcp');+ } else if (servers && Object.hasOwn(servers, 'pullboard')) {+ notes.push('kept the Claude Code MCP server in .mcp.json');+ } else {+ config.mcpServers = { ...servers, pullboard: { command: 'sh', args: ['-c', MCP_COMMAND] } };+ writeFileSync(claude, `${JSON.stringify(config, null, 2)}\n`);+ onWrite('.mcp.json');+ notes.push('added pullboard mcp to .mcp.json for Claude Code');+ }+ const codex = join(root, '.codex', 'config.toml');+ const contents = existsSync(codex) ? readFileSync(codex, 'utf8') : '';+ if (/^\s*\[mcp_servers\.(?:pullboard|"pullboard")\]\s*$/mu.test(contents) || /^\s*\[mcp_servers\]\s*$(?:(?!^\s*\[)[\s\S])*?^\s*pullboard\s*=/mu.test(contents)) {+ notes.push('kept the Codex MCP server in .codex/config.toml');+ } else {+ // A new table at the end is valid TOML after any existing content, so nothing already there is rewritten.+ const prefix = contents && !contents.endsWith('\n') ? `${contents}\n` : contents;+ const table = `${prefix ? `${prefix}\n` : ''}[mcp_servers.pullboard]\ncommand = "sh"\nargs = ["-c", ${JSON.stringify(MCP_COMMAND)}]\n`;+ mkdirSync(join(root, '.codex'), { recursive: true });+ writeFileSync(codex, table);+ onWrite('.codex/config.toml');+ notes.push('added pullboard mcp to .codex/config.toml for Codex; trust this project so Codex loads it');+ }+ return notes;+}+/*** Have Claude Code run `pullboard resume` whenever a session starts, resumes or is compacted (I6), so* an agent picks its work up from the board rather than from a summary of it. The hook is merged@@ -585,6 +634,7 @@ export function initRepo({ info, openBoardHere, register, closeBoard, model, per...installHooks(root, onWrite),...installSkills(root, onWrite),writeSessionHook(root, onWrite),+ ...writeMcpConfig(root, onWrite),];if (gate && (!configured || configured === gate)) {const gateNote = missingGateNote(root, gate);diff --git a/src/mcp.js b/src/mcp.jsindex b0c073ee..96de1960 100644--- a/src/mcp.js+++ b/src/mcp.js@@ -1,5 +1,5 @@/**- * pullboard mcp: a local MCP server over stdio that lets an agent's own MCP client read the board and+ * pullboard mcp: a local MCP server over stdio that lets an agent's own MCP client read the board, work the loop and* coordinate on it as that agent (A9), and never make a person's move (P6). It is newline-delimited* JSON-RPC 2.0 on stdin and stdout, hand-written because Pullboard has no dependencies, and it opens* no network connection (P5). Every tool runs the CLI command it mirrors through the same `main` the@@ -65,6 +65,59 @@ export const MCP_TOOLS = Object.freeze([additionalProperties: false,},},+ {+ name: 'next',+ description: 'Take the next item this seat can work, claiming it, or with verify the next review, reserving it. Mirrors pullboard next [--verify].',+ inputSchema: {+ type: 'object',+ properties: { verify: { type: 'boolean', description: 'Take the next review instead of the next item to build.' } },+ additionalProperties: false,+ },+ },+ {+ name: 'claim',+ description: 'Claim an item, or renew this seat\'s claim on it; its criterion freezes at claim. Mirrors pullboard claim <id>.',+ inputSchema: {+ type: 'object',+ properties: { id: { type: 'integer', description: 'The item id, as on the board.' } },+ required: ['id'],+ additionalProperties: false,+ },+ },+ {+ name: 'submit',+ description: 'Submit this seat\'s committed work on an item: a clean tree, the gate green at HEAD. Mirrors pullboard submit <id> [--infra "<why>"].',+ inputSchema: {+ type: 'object',+ properties: {+ id: { type: 'integer', description: 'The item id, as on the board.' },+ infra: { type: 'string', description: 'Why an existing test or gate file was edited, when submit asks for it.' },+ },+ required: ['id'],+ additionalProperties: false,+ },+ },+ {+ name: 'verify',+ description: 'Give a verdict on another agent\'s submitted item from its checked-out commit. Mirrors pullboard verify <id> accept --note "<how>" or reject --reason <CODE> --note "<what failed>".',+ inputSchema: {+ type: 'object',+ properties: {+ id: { type: 'integer', description: 'The item id, as on the board.' },+ decision: { type: 'string', enum: ['accept', 'reject'], description: 'accept or reject.' },+ note: { type: 'string', description: 'How it was proved, or what failed.' },+ reason: { type: 'string', description: 'For a reject: the reason code, such as TEST_FAILURE.' },+ cause: { type: 'string', description: 'For a reject: the cause key, when one is known.' },+ },+ required: ['id', 'decision', 'note'],+ additionalProperties: false,+ },+ },+ {+ name: 'resume',+ description: 'Pick this seat\'s work back up from the board: what it holds, what came back, and the one next step. Mirrors pullboard resume.',+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },+ },]);/** The prefix that marks a captured idea in its shout, until ideas become their own kind of item. */@@ -94,6 +147,12 @@ function validateArguments(tool, args) {if (rule.type === 'string' && typeof value !== 'string') {throw new Refused('BAD_REQUEST', `${tool.name} needs ${key} as text; use the tool's input schema`);}+ if (rule.type === 'boolean' && typeof value !== 'boolean') {+ throw new Refused('BAD_REQUEST', `${tool.name} needs ${key} as true or false; use the tool's input schema`);+ }+ if (rule.enum && !rule.enum.includes(value)) {+ throw new Refused('BAD_REQUEST', `${tool.name} needs ${key} as one of ${rule.enum.join(', ')}; use the tool's input schema`);+ }}return args;}@@ -132,6 +191,19 @@ async function runCli(runCommand, cwd, argv) {return { status, document };}+/** The CLI argv for one loop move (next, claim, submit, verify, resume), or null for any other tool. */+function loopArgv(name, input) {+ if (name === 'next') return ['next', '--json', ...(input.verify ? ['--verify'] : [])];+ if (name === 'claim') return ['claim', '--json', '--', String(input.id)];+ if (name === 'submit') return ['submit', '--json', ...(input.infra === undefined ? [] : [`--infra=${input.infra}`]), '--', String(input.id)];+ if (name === 'verify') {+ return ['verify', '--json', `--note=${input.note}`, ...(input.reason === undefined ? [] : [`--reason=${input.reason}`]),+ ...(input.cause === undefined ? [] : [`--cause=${input.cause}`]), '--', String(input.id), input.decision];+ }+ if (name === 'resume') return ['resume', '--json'];+ return null;+}+/** A tool result carrying one versioned document, flagged as an error when it is a refusal. */function toolResult(document, isError) {return { content: [{ type: 'text', text: JSON.stringify(document, null, 2) }], structuredContent: document, isError };@@ -165,6 +237,13 @@ async function callTool(runCommand, cwd, name, args) {const shown = await runCli(runCommand, cwd, ['show', '--json', '--', String(input.id)]);return toolResult(shown.document, Boolean(shown.status));}+ // The loop's moves are the CLI's own argv: flags as --name=value, so no value can be read as another flag,+ // and positionals after --, so an id or decision cannot either (#961).+ const loop = loopArgv(name, input);+ if (loop) {+ const moved = await runCli(runCommand, cwd, loop);+ return toolResult(moved.document, Boolean(moved.status));+ }// The CLI's own shout argv, positionals after --, as moveArgs builds it. moveArgs refuses blank text// before the engine runs, so the text goes straight to the CLI, whose shout refuses it as EMPTY_SHOUT.const argv = name === 'shout'@@ -197,7 +276,7 @@ async function handleMessage(message, { runCommand, cwd, seat }) {protocolVersion: MCP_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSIONS[0],capabilities: { tools: {} },serverInfo: { name: 'pullboard', version: VERSION },- instructions: `Pullboard tools for ${seat}: read the board, show an item, shout, capture an idea. They run the CLI's own moves and refusals. A person's move (approving or declining rows, answering decisions, signing off) is refused HUMAN_REQUIRED here.`,+ instructions: `Pullboard tools for ${seat}: read the board, show an item, shout, capture an idea, and work the loop: next, claim, submit, verify, resume. They run the CLI's own moves and refusals. A person's move (approving or declining rows, answering decisions, signing off) is refused HUMAN_REQUIRED here.`,} };}if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };diff --git a/test/init-permissions.test.js b/test/init-permissions.test.jsindex 52dfc788..6f2a7a19 100644--- a/test/init-permissions.test.js+++ b/test/init-permissions.test.js@@ -160,7 +160,10 @@ test('init grants the agent the permissions the Pullboard loop needs [I1,I2]', tassert.ok(initialized.document.notes.some(note => note.includes(expectedLegacyCodex)), 'Codex setup prints exact legacy workspace-write values scoped to the machine home');assert.ok(initialized.document.notes.some(note => /sandbox_mode at the TOML top level before any table, append these exact paths to any existing writable_roots array while keeping its entries, and do not duplicate the table or replace unrelated settings/u.test(note)), 'Codex setup explains the top-level key and exact append without replacing settings or duplicating the TOML table');assert.ok(initialized.document.notes.some(note => /https:\/\/learn\.chatgpt\.com\/docs\/config-file\/config-reference.*https:\/\/learn\.chatgpt\.com\/docs\/permissions/u.test(note)), 'Codex setup cites the official sandbox and permission-profile references');- assert.equal(readFileSync(codexConfigPath, 'utf8'), existingCodexConfig, 'init prints Codex configuration guidance without rewriting a project config');+ const codexAfter = readFileSync(codexConfigPath, 'utf8');+ assert.ok(codexAfter.startsWith(existingCodexConfig), 'init prints Codex configuration guidance without rewriting a project config');+ // The only addition is the pullboard MCP server table (#961); the sandbox settings stay exactly as written.+ assert.match(codexAfter.slice(existingCodexConfig.length), /^\n\[mcp_servers\.pullboard\]\ncommand = "sh"\nargs = \["-c", "[^\n]+"\]\n$/u);assert.ok(initialized.document.notes.some(note => /permission-profile users.*existing \[permissions\.<active-profile>\.filesystem\].*do not mix/iu.test(note)), 'Codex setup explains the permission-profile alternative without mixing config systems');const profileBoard = `${JSON.stringify(machineHomePath)} = "write" and ${JSON.stringify(join(box.root, '.git', 'pullboard'))} = "write" under their existing [permissions.<active-profile>.filesystem] table instead, since a named profile ignores writable_roots`;assert.ok(initialized.document.notes.some(note => note.includes(profileBoard)), 'the permission-profile step grants the board folder too (#913)');diff --git a/test/mcp.test.js b/test/mcp.test.jsindex 0edbef84..611a2dcc 100644--- a/test/mcp.test.js+++ b/test/mcp.test.js@@ -223,7 +223,7 @@ test('[A9,P5] an MCP client reads the board and shouts as its agent', async (t)assert.match(hello.result.instructions, new RegExp(`agent ${box.agent} in the web lane`));const listed = await client.request('tools/list');- assert.deepEqual(listed.result.tools.map((tool) => tool.name), ['board_status', 'show_item', 'shout', 'capture_idea']);+ assert.deepEqual(listed.result.tools.map((tool) => tool.name), ['board_status', 'show_item', 'shout', 'capture_idea', 'next', 'claim', 'submit', 'verify', 'resume']);for (const tool of listed.result.tools) {assert.equal(tool.inputSchema.type, 'object', tool.name);assert.equal(tool.inputSchema.additionalProperties, false, `${tool.name} refuses unknown arguments`);@@ -378,3 +378,78 @@ test('[P6,A9] a person\'s move through MCP is refused', async (t) => {const approved = cli(box, box.repo, ['spec', 'approve', 'G2']);assert.equal(approved.status, 0, JSON.stringify(approved.document));});++test('an agent claims, submits, verifies and resumes through MCP with the CLI\'s refusals [A9,P6]', async (t) => {+ const box = project(t);+ const added = cli(box, box.repo, ['add', 'web', 'An item worked through MCP', '--specs', 'G1', '--criterion', 'web/mcp.txt exists.']);+ assert.equal(added.status, 0, JSON.stringify(added.document));+ const id = added.document.item.item_id;+ const builder = mcpClient(t, box, box.web, box.sessionA);+ await initialize(builder);+ const names = (await builder.request('tools/list')).result.tools.map((tool) => tool.name);+ for (const name of ['next', 'claim', 'submit', 'verify', 'resume']) assert.ok(names.includes(name), `MCP offers ${name}`);++ // The same refusal, code and next step, whether the CLI or MCP makes the move.+ const missing = await builder.call('claim', { id: 9999 });+ const cliMissing = cli(box, box.web, ['claim', '9999'], box.sessionA);+ assert.equal(missing.isError, true);+ assert.equal(cliMissing.status, 1);+ assert.deepEqual(missing.structuredContent.error, cliMissing.document.error, 'a refused claim reads the same through MCP');++ const claimed = await builder.call('claim', { id });+ assert.equal(claimed.isError, false, JSON.stringify(claimed.structuredContent));+ mkdirSync(join(box.web, 'web'), { recursive: true });+ writeFileSync(join(box.web, 'web', 'mcp.txt'), 'made through MCP\n');+ box.git(box.web, 'add', 'web/mcp.txt');+ box.git(box.web, 'commit', '-q', '-m', 'feat(web): write the MCP fixture file [G1]');+ const submitted = await builder.call('submit', { id });+ assert.equal(submitted.isError, false, JSON.stringify(submitted.structuredContent));+ const commit = box.git(box.web, 'rev-parse', 'HEAD').trim();++ // A builder never verifies its own work, through MCP as through the CLI.+ const own = await builder.call('verify', { id, decision: 'accept', note: 'I built it.' });+ const cliOwn = cli(box, box.web, ['verify', String(id), 'accept', '--note', 'I built it.'], box.sessionA);+ assert.equal(own.isError, true);+ assert.equal(own.structuredContent.error.code, cliOwn.document.error.code, 'self-verification is refused alike');+ const resumed = await builder.call('resume', {});+ assert.equal(resumed.isError, false, JSON.stringify(resumed.structuredContent));+ assert.equal(resumed.structuredContent.version, 1);+ assertProtocolOnly((await builder.close()).lines);++ // Another agent, in its own session, takes the review and accepts through MCP.+ const review = join(box.dir, 'review');+ box.git(box.repo, 'worktree', 'add', '-q', '--detach', review, commit);+ const sessionB = { CODEX_SESSION_ID: 'mcp-session-b' };+ const reviewerJoined = cli(box, review, ['join', 'web', '--model', 'reviewer-model'], sessionB);+ assert.equal(reviewerJoined.status, 0, JSON.stringify(reviewerJoined.document));+ const reviewer = mcpClient(t, box, review, sessionB);+ await initialize(reviewer);+ const reserved = await reviewer.call('next', { verify: true });+ assert.equal(reserved.isError, false, JSON.stringify(reserved.structuredContent));+ const accepted = await reviewer.call('verify', { id, decision: 'accept', note: 'web/mcp.txt exists at the submitted commit.' });+ assert.equal(accepted.isError, false, JSON.stringify(accepted.structuredContent));+ assertProtocolOnly((await reviewer.close()).lines);+ const shown = cli(box, box.repo, ['show', String(id)]);+ assert.equal(shown.document.item_status, 'verified', 'the item was claimed, submitted and verified through MCP alone');+ assert.equal(readFileSync(box.env.MCP_NETWORK_LOG, 'utf8').includes('attempt'), false, 'no tool opened a network connection');++ // init registered the server for both clients, keeping what was already there.+ const servers = JSON.parse(readFileSync(join(box.repo, '.mcp.json'), 'utf8')).mcpServers;+ assert.deepEqual(servers.pullboard.args.slice(0, 1), ['-c']);+ assert.match(servers.pullboard.args[1], /exec "\$p" mcp/u);+ assert.match(readFileSync(join(box.repo, '.codex', 'config.toml'), 'utf8'), /^\[mcp_servers\.pullboard\]$/mu);+ const other = join(box.dir, 'other');+ mkdirSync(join(other, '.codex'), { recursive: true });+ box.git(box.dir, 'init', '-q', '-b', 'main', other);+ writeFileSync(join(other, '.mcp.json'), `${JSON.stringify({ mcpServers: { mine: { command: 'mine' } } })}\n`);+ writeFileSync(join(other, '.codex', 'config.toml'), 'model = "mine"\n\n[mcp_servers.mine]\ncommand = "mine"\n');+ const merged = box.run(other, ['init', '--model', 'coordinator-model']);+ assert.equal(merged.status, 0, fixtureChildMessage(merged));+ assert.deepEqual(Object.keys(JSON.parse(readFileSync(join(other, '.mcp.json'), 'utf8')).mcpServers).sort(), ['mine', 'pullboard'], 'an existing server is kept');+ const toml = readFileSync(join(other, '.codex', 'config.toml'), 'utf8');+ assert.ok(toml.startsWith('model = "mine"\n\n[mcp_servers.mine]\ncommand = "mine"\n'), 'existing Codex settings are kept as written');+ assert.match(toml, /^\[mcp_servers\.pullboard\]$/mu);+ const again = box.run(other, ['init', '--model', 'coordinator-model']);+ assert.equal(readFileSync(join(other, '.codex', 'config.toml'), 'utf8'), toml, 'a second init adds nothing');+ assert.ok(again.status === 0 || again.status === 1, 'a second init leaves the registration alone');+});