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
fix(swarm): name what is wrong with a command's id or JSON, and take the JSON on stdin
bitcoinbuilderccc6be1ffe21
diff --git a/cli/src/superTabs/command.spec.ts b/cli/src/superTabs/command.spec.tsindex 9a190b5dc..b8e8b1fa5 100644--- a/cli/src/superTabs/command.spec.ts+++ b/cli/src/superTabs/command.spec.ts@@ -15,10 +15,30 @@ it('keeps an explicit stable receipt for agent messages and arbitrary work commaexpect(parseSuperTabArgs(['--tab', 'tab', 'status'], where).payload.agentId).toBe('')for (const argv of [[], ['status'], [...prefix, 'post', 'lead', 'Ready'], [...prefix, 'messages', '../other'],[...prefix, 'message', 'lead'], [...prefix, 'message', 'lead', '../other'], [...prefix, 'message', 'lead', 'id', 'extra'],- ['--port', 'no', 'help'], ['--machine', '', 'help'], [...prefix, 'status', 'extra'], [...prefix, 'route', 'g1'], [...prefix, 'route', '../x', '{}']]) {+ ['--port', 'no', 'help'], ['--machine', '', 'help'], [...prefix, 'status', 'extra']]) {expect(() => parseSuperTabArgs(argv, where)).toThrow('harness super-tab')}})+// Swarm groups #13 and #16 (2026-10-29/30): a Builder's done update got only the usage line back, once without its operation+// id and once with its JSON split by a quote inside it, and it could not tell what to fix.+it('says what is wrong with a command\'s id or JSON instead of the usage line', () => {+ const json = '{"type":"work.status","conversationId":"g1","assignmentId":"current","status":"done","result":"ok"}'+ expect(() => parseSuperTabArgs([...prefix, 'command', json], where)).toThrow('command needs OPERATION_ID before the JSON')+ expect(() => parseSuperTabArgs([...prefix, 'command', 'op-1'], where)).toThrow('command needs its JSON after OPERATION_ID')+ expect(() => parseSuperTabArgs([...prefix, 'command'], where)).toThrow('command needs OPERATION_ID and the JSON on the same command line')+ // `'...--format='%h %s' returned...'` reaches the CLI as three arguments.+ expect(() => parseSuperTabArgs([...prefix, 'command', 'op-1', '{"result":"git log --format=%h', '%s', 'returned"}'], where))+ .toThrow("got 3 arguments after OPERATION_ID: a quote inside the JSON ended the shell's quoting")+ expect(() => parseSuperTabArgs([...prefix, 'command', 'op-1', '{"type":'], where)).toThrow(/The command JSON is not valid .*send the JSON on stdin with -/)+ expect(() => parseSuperTabArgs([...prefix, 'route', '../x', '{}'], where)).toThrow('route needs GROUP first')+ expect(() => parseSuperTabArgs([...prefix, 'route', 'g1'], where)).toThrow("route needs its JSON after GROUP: route g1 JSON, or send the JSON on stdin with - in its place: route GROUP - <<'JSON'")+ expect(() => parseSuperTabArgs([...prefix, 'messages'], where)).toThrow('harness super-tab')+})+it('reads a command\'s JSON from stdin for -', () => {+ const stdin = vi.fn(() => '{"type":"work.status","result":"it\'s \'%h %s\'"}')+ expect(parseSuperTabArgs([...prefix, 'command', 'op-1', '-'], where, stdin).payload).toMatchObject({ operationId: 'op-1', command: { type: 'work.status', result: "it's '%h %s'" } })+ expect(stdin).toHaveBeenCalledOnce()+})it('reacts to a message as people do, and --off takes the reaction back', () => {expect(parseSuperTabArgs([...prefix, 'react', 'lead', 'msg-1', 'eyes', 'op-1'], where).payload).toEqual({ action: 'command', tabId: 'tab', agentId: 'agent',operationId: 'op-1', command: { type: 'message.react', conversationId: 'lead', messageId: 'msg-1', emoji: 'eyes', on: true } })@@ -450,7 +470,7 @@ it('parses a Buddy\'s propose OPERATION_ID JSON as its proposal command, whateveconst proposal = { conversationId: 'chat', ownerMessageId: 'asked', goal: 'Offline sync', scope: 'Desktop only', priority: 'normal' }expect(parseSuperTabArgs([...prefix, 'propose', 'op-1', JSON.stringify({ ...proposal, type: 'work.assign' })], where).payload).toMatchObject({ action: 'command', operationId: 'op-1', command: { ...proposal, type: 'buddy.propose' } })- expect(() => parseSuperTabArgs([...prefix, 'propose', 'op-1'], where)).toThrow('harness super-tab')+ expect(() => parseSuperTabArgs([...prefix, 'propose', 'op-1'], where)).toThrow('propose needs its JSON after OPERATION_ID')})// Security review of #2087: --agent naming a Builder let a Buddy on the same machine speak as it. The harness the command// runs in goes with every request, and the daemon holds the agent named to that harness's own (service.spec.ts).diff --git a/cli/src/superTabs/command.ts b/cli/src/superTabs/command.tsindex 8e4fbe365..f9c240c03 100644--- a/cli/src/superTabs/command.ts+++ b/cli/src/superTabs/command.ts@@ -9,6 +9,7 @@ import { resolve } from 'node:path'import { readInsideFolder, uploadAttachments, type UploadTarget } from './attach.js'import { keyName } from './terminal.js'import { randomUUID } from 'node:crypto'+import { readFileSync } from 'node:fs'import { inDaemonPane, NOT_IN_PANE, runningPane, type PaneProbe } from './callerPane.js'// cli.ts's way to it: this file is its door to the Swarm's code (architecture.spec.ts SWARM_DOORS).export { buddyRefusal } from './buddyPane.js'@@ -27,9 +28,43 @@ function harnessIn(frames: PaneFrame[], pane: string, machineId: string): booleaconst ELSEWHERE = 'From a harness, Swarm commands go to this computer\'s own Harness only: leave out --machine and --port, or give this computer\'s own.'const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status [--archived [PAGE]] | messages GROUP [--before SEQUENCE MESSAGE_ID] | message GROUP MESSAGE_ID | decisions [--answered] | costs [--days N] | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | react GROUP MESSAGE_ID EMOJI OPERATION_ID [--off] | command OPERATION_ID JSON | propose OPERATION_ID JSON [--attach PATH]... | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | plan [JSON] | remove-machine MACHINE_ID [--yes] | set-agents MACHINE_ID COUNT | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'+/** The actions that take an id and then one JSON argument, and what that id names. */+const JSON_ACTIONS: Readonly<Record<string, string>> = { command: 'OPERATION_ID', propose: 'OPERATION_ID', start: 'OPERATION_ID', capacity: 'MACHINE_ID', route: 'GROUP' }+const stdinHint = (action: string) => `or send the JSON on stdin with - in its place: ${action} ${JSON_ACTIONS[action]} - <<'JSON' (the JSON on the next lines, then JSON alone on a line)`++/** The JSON argument, or why it is not one.+ *+ * Codex Builders on Mac Auto (Swarm groups #13 and #16, 2026-10-29/30) got only the usage line back for a work.status+ * done: one left out the operation id, one quoted its JSON in single quotes around a result that held `'%h %s'`, so+ * the shell split it into several arguments. Neither could tell what to fix, and the finished task stayed open. */+function jsonArgument(action: string, text: string): unknown {+ try { return JSON.parse(text) } catch (error) {+ throw new Error(`The ${action} JSON is not valid (${(error as Error).message}). Pass it as one argument, ${stdinHint(action)}.`)+ }+}+/** Why [positional] is not `ACTION ID JSON`, in words an agent can act on; null to leave it to the usage line. */+function jsonShapeError(positional: readonly string[]): string | null {+ const [action, first = ''] = positional+ const id = JSON_ACTIONS[action]+ if (!id) return null+ const hint = stdinHint(action)+ // Nothing after the action: the id and JSON went on the next lines, which the shell ran as commands of their own.+ if (positional.length === 1) return `${action} needs ${id} and the JSON on the same command line: ${action} ${id} JSON. A line break without \\ before it ends the command; ${hint}.`+ if (!identifier(first)) {+ return (first as string).trim().startsWith('{')+ ? `${action} needs ${id} before the JSON: ${action} ${id} JSON. ${id === 'OPERATION_ID' ? 'Use a new unique id of letters, digits, - or _ (reuse it only to repeat an interrupted request).' : ''}`.trim()+ : `${action} needs ${id} first, as letters, digits, - or _ only: ${action} ${id} JSON.`+ }+ if (positional.length < 3 || !positional[2]) return `${action} needs its JSON after ${id}: ${action} ${first} JSON, ${hint}.`+ if (action !== 'propose' && positional.length > 3) {+ return `${action} takes ${id} and the JSON as one argument, but got ${positional.length - 2} arguments after ${id}: a quote inside the JSON ended the shell's quoting. Quote it so it stays one argument, ${hint}.`+ }+ return null+}+/** The files one proposal may carry (backend buddies.ts MAX_PROPOSAL_ATTACHMENTS). */const MAX_PROPOSAL_FILES = 5-export function parseSuperTabArgs(argv: readonly string[], where: Where) {+export function parseSuperTabArgs(argv: readonly string[], where: Where, stdin: () => string = () => readFileSync(0, 'utf8')) {const positional: string[] = []let tabId = '', agentId = ''const target = { ...where }@@ -42,6 +77,8 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {else { positional.push(...argv.slice(i)); break }}if (!Number.isInteger(target.port) || target.port < 1 || target.port > 65535 || !identifier(target.machineId)) throw new Error(USAGE)+ // `-` in the JSON's place reads it from stdin, where no shell quoting can split it.+ if (JSON_ACTIONS[positional[0]] && positional[2] === '-') positional[2] = stdin()const [action, first, second, third] = positionalif (action !== 'help' && (!identifier(tabId) || (agentId && !identifier(agentId)))) throw new Error(USAGE)const payload: Record<string, unknown> = { action, tabId, agentId }@@ -84,7 +121,7 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {Object.assign(payload, { action: 'command', operationId: positional[4],command: { type: 'message.react', conversationId: first, messageId: second, emoji: third, on: positional.length === 5 } })} else if (action === 'command' && identifier(first) && second && positional.length === 3) {- Object.assign(payload, { operationId: first, command: JSON.parse(second) })+ Object.assign(payload, { operationId: first, command: jsonArgument(action, second) })} else if (action === 'propose' && identifier(first) && second) {const attach: string[] = []for (let i = 3; i < positional.length; i += 2) {@@ -95,12 +132,12 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {if (attach.length > MAX_PROPOSAL_FILES) throw new Error(`Attach at most ${MAX_PROPOSAL_FILES} files to a proposal.`)// A Buddy's proposal for its owner (backend buddies.ts): only ever that command, whatever the JSON says it is.Object.assign(payload, { action: 'command', operationId: first, ...(attach.length ? { attach } : {}),- command: { ...JSON.parse(second), type: 'buddy.propose' } })+ command: { ...object(jsonArgument(action, second)), type: 'buddy.propose' } })} else if (action === 'start' && identifier(first) && second && positional.length === 3) {- Object.assign(payload, { operationId: first, request: JSON.parse(second) })+ Object.assign(payload, { operationId: first, request: jsonArgument(action, second) })} else if (action === 'resume' && identifier(first) && positional.length === 2) payload.startId = firstelse if (action === 'capacity' && identifier(first) && second && positional.length === 3) {- Object.assign(payload, { targetMachineId: first, request: JSON.parse(second) })+ Object.assign(payload, { targetMachineId: first, request: jsonArgument(action, second) })} else if (action === 'remove-machine' && identifier(first) && (positional.length === 2 || positional.length === 3 && second === '--yes')) {// The machine's owner, as the person: without --yes, what removal would do (the agents it stops, a refusal); with it,// the removal. The daemon's owner-only backend request carries both.@@ -112,7 +149,7 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {// The machine's owner, as the person: how many Swarm agents may run on it at once (contribution.ts setMachineAgents).Object.assign(payload, { action: 'setMachineAgents', machineId: first, maxAgents: Number(second) })} else if (action === 'route' && identifier(first) && second && positional.length === 3) {- Object.assign(payload, { conversationId: first, assessment: JSON.parse(second) })+ Object.assign(payload, { conversationId: first, assessment: jsonArgument(action, second) })} else if (action === 'plan' && positional.length <= 2) {if (first !== undefined) payload.request = JSON.parse(first)} else if (action === 'screen' && identifier(first) && (positional.length === 2@@ -134,7 +171,7 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {if (!text && !keys.length) throw new Error(USAGE)Object.assign(payload, { operationId: `terminal-${randomUUID()}`,command: { type: 'agent.input', agentId: first, ...(text ? { text } : {}), ...(keys.length ? { keys } : {}) } })- } else if (!['status', 'help'].includes(action) || positional.length !== 1) throw new Error(USAGE)+ } else if (!['status', 'help'].includes(action) || positional.length !== 1) throw new Error(jsonShapeError(positional) ?? USAGE)return { where: target, payload }}diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 89716d596..e30bbe549 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -73,7 +73,7 @@ const HELP = {capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',startRequest: { conversationId: 'GROUP', machineId: 'MACHINE', engine: 'codex', name: 'Builder', cwd: '/absolute/repo/on/that/machine', worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH', requirements: START_REQUIREMENTS,model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },- command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. On Custom skills, work.assign takes "roleId" too, a role of the agent\'s kind. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change one project\'s routing rules: only the project owner does (naming projectId), or that project\'s Lead passing on the project owner\'s request, with askedIn naming the project owner\'s message in that project\'s chat. project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it. tab.tidy turns off, or back on, the Swarm\'s tidying: workers idle for 15 minutes stop and finished groups archive once their pull requests are merged or closed. Only the Swarm owner does, or a Lead passing on the owner\'s own chat message, with askedIn naming it. Two failed starts in a row suspend an engine on a machine for up to 6 hours (the route says so); machine.engineResume offers it there again: only the machine\'s owner does, or the Lead passing on the owner\'s chat message, with askedIn naming it. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine, preferIdle and noGridFirst only rank. Low-risk work that is not a review ranks models on the Swarm\'s grid first unless the owner set noGridFirst: low-difficulty work, and medium work of kind docs, copy, tests, fixtures, fix or refactor (a grid model rated 2, such as Kimi K3 or DeepSeek v4.1). A review never runs on a grid model, below quality 2 or on the reviewed Builder\'s engine. When a grid attempt\'s first review says Ready no, or its grid host never starts the agent, the Swarm closes it and steps the task up (no grid and quality 2, then quality 3, at most twice) and tells you: route it again, and the route and the server keep to the new floor.',+ command: 'command OPERATION_ID JSON: send one of the commands below. The JSON is one argument: when it holds quotes, put - in its place and send it on stdin (command OPERATION_ID - <<\'JSON\' … JSON). Reuse exactly the same ID and JSON after an interrupted request. On Custom skills, work.assign takes "roleId" too, a role of the agent\'s kind. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change one project\'s routing rules: only the project owner does (naming projectId), or that project\'s Lead passing on the project owner\'s request, with askedIn naming the project owner\'s message in that project\'s chat. project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it. tab.tidy turns off, or back on, the Swarm\'s tidying: workers idle for 15 minutes stop and finished groups archive once their pull requests are merged or closed. Only the Swarm owner does, or a Lead passing on the owner\'s own chat message, with askedIn naming it. Two failed starts in a row suspend an engine on a machine for up to 6 hours (the route says so); machine.engineResume offers it there again: only the machine\'s owner does, or the Lead passing on the owner\'s chat message, with askedIn naming it. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine, preferIdle and noGridFirst only rank. Low-risk work that is not a review ranks models on the Swarm\'s grid first unless the owner set noGridFirst: low-difficulty work, and medium work of kind docs, copy, tests, fixtures, fix or refactor (a grid model rated 2, such as Kimi K3 or DeepSeek v4.1). A review never runs on a grid model, below quality 2 or on the reviewed Builder\'s engine. When a grid attempt\'s first review says Ready no, or its grid host never starts the agent, the Swarm closes it and steps the task up (no grid and quality 2, then quality 3, at most twice) and tells you: route it again, and the route and the server keep to the new floor.',commands: [{ type: 'project.report', projectId: 'PROJECT', through: { GROUP: 214031 }, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },