The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
harness mcp names the next steps as its tools (#1203)
Dee3feff3d78633
diff --git a/cli/e2e/agentClient.e2e.ts b/cli/e2e/agentClient.e2e.tsindex b70324c33..4c3452766 100644--- a/cli/e2e/agentClient.e2e.ts+++ b/cli/e2e/agentClient.e2e.ts@@ -243,10 +243,12 @@ describe('Harness for agents, end to end', () => {const started = await server.call('harness_start', { task: 'hello from mcp', folder: dir, name: 'mcpkid' })expect(started.isError, started.text).toBe(false)expect(started.text).toContain('Created mcpkid on this computer')+ // Its next steps are named as the tools: an MCP client may have no shell to run `harness show` in.+ expect(started.text).toContain('Read it: harness_read (name: "mcpkid") · wait for it: harness_wait (names: "mcpkid")')const ledger = readFileSync(join(d.dataDir, 'agent-client', 'started.jsonl'), 'utf8').trim().split('\n').map((line) => JSON.parse(line))expect(ledger).toEqual([expect.objectContaining({ by: expect.objectContaining({ agentId: expect.stringMatching(/^agent:cursor:mcp-\d+$/), name: 'Cursor' }) })])const waited = await server.call('harness_wait', { names: ['mcpkid'], timeout_seconds: 120 })- expect(waited).toEqual({ text: 'mcpkid: idle · read it: harness show mcpkid', isError: false })+ expect(waited).toEqual({ text: 'mcpkid: idle · read it: harness_read (name: "mcpkid")', isError: false })const read = await server.call('harness_read', { name: 'mcpkid' })expect(read.text).toContain('asked: [from Cursor outside Harness · ')expect(read.text).toContain('hello from mcp')diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.tsindex 8a9619dc9..f16fb1b59 100644--- a/cli/src/agentClient/commands.ts+++ b/cli/src/agentClient/commands.ts@@ -59,6 +59,21 @@ It is refused while the harness is working, unless --now. An agent may close onlexport const EXIT = { ok: 0, failed: 1, usage: 2, needsInput: 3, stopped: 4, timeout: 124 } as const+/** Set by `harness mcp` (mcp.ts) for the verbs it runs: their next steps are then named as its tools. */+export const VIA_MCP_ENV = 'HARNESS_VIA_MCP'+const TOOL_OF = { ps: 'harness_list', show: 'harness_read', wait: 'harness_wait', send: 'harness_send', close: 'harness_close' } as const++/**+ * A next step as the caller can take it: the shell's `harness show x`, or the tool `harness mcp` offers for it. An MCP+ * client may have no shell at all (Claude Desktop), and its agent was told to run `harness show x` (2026-10-11, in a+ * clean VM). [option] is a flag and its MCP argument: `--chars 9000` / `chars: 9000`.+ */+export function step(env: NodeJS.ProcessEnv, verb: keyof typeof TOOL_OF, name = '', option?: { flag: string; arg: string }): string {+ if (env[VIA_MCP_ENV] !== '1') return ['harness', verb, name, option?.flag, verb === 'send' ? '"…"' : ''].filter(Boolean).join(' ')+ const args = [name && `${verb === 'send' ? 'to' : verb === 'wait' ? 'names' : 'name'}: "${name}"`, option?.arg].filter(Boolean)+ return `${TOOL_OF[verb]}${args.length ? ` (${args.join(', ')})` : ''}`+}+const DEFAULT_CHARS = 4_000const DEFAULT_TIMEOUT_MS = 30 * 60_000const DEFAULT_INTERVAL_MS = 3_000@@ -178,7 +193,7 @@ async function target(s: Setup, o: Opened, name: string): Promise<Target> {if (!frame) { daemon.close(); throw new AgentClientError('GONE', `${elsewhere[0].name} is no longer on its machine.`) }return { daemon, frame, machineId: row.child.machineId, machine: row.child.machineId.slice(0, 8), yours: true, remote: true }}- throw new AgentClientError('UNKNOWN_HARNESS', `No harness named "${name}" on this machine. \`harness ps\` lists them.`)+ throw new AgentClientError('UNKNOWN_HARNESS', `No harness named "${name}" on this machine. \`${step(s.env, 'ps')}\` lists them.`)}type Screen = 'working' | 'needs-input' | 'idle' | 'draft'@@ -340,7 +355,7 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pros.out(`asked: ${clip(result.ask ?? '', 600)}`)s.out(`answer${result.tools ? ` (after ${result.tools} tool calls)` : ''}:`)s.out(result.answer || '(no text)')- if (result.truncated) s.out(`… ${answer.length - chars} more characters: harness show ${result.name} --chars ${answer.length}`)+ if (result.truncated) s.out(`… ${answer.length - chars} more characters: ${step(s.env, 'show', result.name, { flag: `--chars ${answer.length}`, arg: `chars: ${answer.length}` })}`)}if (state === 'needs-input') s.out(`It is waiting for the person (a question or a permission). Only the person answers it.`)}@@ -418,9 +433,9 @@ export function waitCommand(argv: readonly string[], deps: ClientDeps = {}): Proconst results = targets.filter((t) => settled.has(t)).map((t) => ({ name: t.frame.name ?? t.frame.id.slice(0, 8), id: t.frame.id, state: settled.get(t)! }))if (flags.has('--json')) s.out(JSON.stringify({ harnesses: results }, null, 1))else for (const r of results) {- const next = r.state === 'idle' ? `read it: harness show ${r.name}`+ const next = r.state === 'idle' ? `read it: ${step(s.env, 'show', r.name)}`: r.state === 'needs-input' ? 'it waits for the person (a question or a permission); only the person answers it'- : r.state === 'timeout' ? `still working; wait again or read it: harness show ${r.name}`+ : r.state === 'timeout' ? `still working; wait again or read it: ${step(s.env, 'show', r.name)}`: r.state === 'stopped' ? 'it was stopped' : 'it is gone's.out(`${r.name}: ${r.state} · ${next}`)}@@ -455,9 +470,9 @@ export function closeCommand(argv: readonly string[], deps: ClientDeps = {}): PragentId: t.frame.id, sessionId: t.frame.sessionId ?? '', createdAt: t.frame.createdAt ?? '', mode: flags.has('--now') ? 'now' : 'idle',}, 60_000)if (reply.error === 'SESSION_NOT_IDLE') {- throw new AgentClientError('WORKING', `${name} is ${reply.activity === 'needs_input' ? 'waiting for the person' : 'working'}. Wait for it (harness wait ${name}), or close it anyway with --now.`)+ throw new AgentClientError('WORKING', `${name} is ${reply.activity === 'needs_input' ? 'waiting for the person' : 'working'}. Wait for it (${step(s.env, 'wait', name)}), or close it anyway with ${s.env[VIA_MCP_ENV] === '1' ? 'now: true' : '--now'}.`)}- if (reply.error === 'AGENT_CHANGED') throw new AgentClientError('AGENT_CHANGED', `${name} changed while closing. Check it with harness show ${name}, then try again.`)+ if (reply.error === 'AGENT_CHANGED') throw new AgentClientError('AGENT_CHANGED', `${name} changed while closing. Check it with ${step(s.env, 'show', name)}, then try again.`)if (reply.error) throw new AgentClientError(String(reply.error), typeof reply.detail === 'string' && reply.detail ? reply.detail : `Could not close ${name}.`)s.out(flags.has('--json') ? JSON.stringify({ name, id: t.frame.id, closed: true }) : `Closed ${name}. Its conversation is kept.`)return EXIT.ok@@ -609,7 +624,7 @@ export async function agentOrigin(deps: ClientDeps = {}, record: Rpc = messagesR},next: (agent) => {const at = addressOf({ machineId: '', agentId: String(agent.id ?? ''), name: String(agent.name ?? ''), engine: '' })- return `Read it: harness show ${at} · wait for it: harness wait ${at}${caller.outside ? '' : ` · message it: harness send ${at} "…"`}`+ return `Read it: ${step(s.env, 'show', at)} · wait for it: ${step(s.env, 'wait', at)}${caller.outside ? '' : ` · message it: ${step(s.env, 'send', at)}`}`},}}diff --git a/cli/src/agentClient/mcp.spec.ts b/cli/src/agentClient/mcp.spec.tsindex a9288dead..ecd94cd79 100644--- a/cli/src/agentClient/mcp.spec.ts+++ b/cli/src/agentClient/mcp.spec.ts@@ -1,4 +1,5 @@import { PassThrough } from 'node:stream'+import { step } from './commands.js'import { describe, expect, it } from 'vitest'import { agentOfClient, answer, callerEnv, INSTRUCTIONS, mcpCommand, PROTOCOL_VERSIONS, result, type McpDeps, type Ran } from './mcp.js'@@ -60,13 +61,26 @@ describe('harness mcp', () => {})it('says whose session it is when the agent did not, and leaves a harness pane and a named session alone', () => {- expect(callerEnv(deps({ env: { PATH: '/bin' } }), 'cursor-vscode')).toEqual({ PATH: '/bin', AI_AGENT: 'cursor', HARNESS_AGENT_SESSION: 'mcp-1' })- expect(callerEnv(deps({ env: { AI_AGENT: 'amp_1_agent' } }))).toEqual({ AI_AGENT: 'amp_1_agent', HARNESS_AGENT_SESSION: 'mcp-1' })+ const via = { HARNESS_VIA_MCP: '1' }+ expect(callerEnv(deps({ env: { PATH: '/bin' } }), 'cursor-vscode')).toEqual({ PATH: '/bin', AI_AGENT: 'cursor', HARNESS_AGENT_SESSION: 'mcp-1', ...via })+ expect(callerEnv(deps({ env: { AI_AGENT: 'amp_1_agent' } }))).toEqual({ AI_AGENT: 'amp_1_agent', HARNESS_AGENT_SESSION: 'mcp-1', ...via })expect(callerEnv(deps({ env: {} }))).toMatchObject({ AI_AGENT: 'mcp-client' })expect(callerEnv(deps({ env: {}, session: undefined }))).toMatchObject({ HARNESS_AGENT_SESSION: `mcp-${process.ppid}` })- expect(callerEnv(deps({ env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' } }), 'claude-code')).toEqual({ CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' })- expect(callerEnv(deps({ env: { CODEX_THREAD_ID: 't' } }))).toEqual({ CODEX_THREAD_ID: 't' })- expect(callerEnv(deps({ env: { TMUX_PANE: '%1' }, inPane: true }))).toEqual({ TMUX_PANE: '%1' })+ expect(callerEnv(deps({ env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' } }), 'claude-code')).toEqual({ CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's', ...via })+ expect(callerEnv(deps({ env: { CODEX_THREAD_ID: 't' } }))).toEqual({ CODEX_THREAD_ID: 't', ...via })+ expect(callerEnv(deps({ env: { TMUX_PANE: '%1' }, inPane: true }))).toEqual({ TMUX_PANE: '%1', ...via })+ })++ it('has the verbs it runs name their next steps as its tools, and the shell keeps its own', () => {+ const mcp = { HARNESS_VIA_MCP: '1' }+ expect(step(mcp, 'show', 'reviewer')).toBe('harness_read (name: "reviewer")')+ expect(step(mcp, 'wait', 'reviewer')).toBe('harness_wait (names: "reviewer")')+ expect(step(mcp, 'send', 'reviewer')).toBe('harness_send (to: "reviewer")')+ expect(step(mcp, 'ps')).toBe('harness_list')+ expect(step(mcp, 'show', 'reviewer', { flag: '--chars 9000', arg: 'chars: 9000' })).toBe('harness_read (name: "reviewer", chars: 9000)')+ expect(step({}, 'show', 'reviewer', { flag: '--chars 9000', arg: 'chars: 9000' })).toBe('harness show reviewer --chars 9000')+ expect(step({}, 'send', 'reviewer')).toBe('harness send reviewer "…"')+ expect(step({}, 'ps')).toBe('harness ps')})it('knows the agents MCP clients are by the names they give', () => {diff --git a/cli/src/agentClient/mcp.ts b/cli/src/agentClient/mcp.tsindex 785a3ac77..eb280beb6 100644--- a/cli/src/agentClient/mcp.ts+++ b/cli/src/agentClient/mcp.ts@@ -15,7 +15,7 @@ import { isAbsolute, resolve } from 'node:path'import { createInterface } from 'node:readline'import { VERSION } from '../version.js'import { AGENT_SESSION_ENV } from './model.js'-import { EXIT } from './commands.js'+import { EXIT, VIA_MCP_ENV } from './commands.js'/** Newest first: the client's own when it is one of these, else the newest. */export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'] as const@@ -172,7 +172,8 @@ export async function answer(message: Message, deps: McpDeps, state: { client?:* and Codex's shells do; an MCP server's environment may not). `AI_AGENT` names the agent, as its client said.*/export function callerEnv(deps: McpDeps, client = ''): NodeJS.ProcessEnv {- const env = { ...(deps.env ?? process.env) }+ // The verbs then name their next steps as this server's tools.+ const env: NodeJS.ProcessEnv = { ...(deps.env ?? process.env), [VIA_MCP_ENV]: '1' }if (deps.inPane || (env.CLAUDECODE === '1' && env.CLAUDE_CODE_SESSION_ID) || env.CODEX_THREAD_ID) return envif (!env.AI_AGENT) env.AI_AGENT = agentOfClient(client)env[AGENT_SESSION_ENV] = deps.session ?? `mcp-${process.ppid}`