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
import { inspectCapacity, startAgent } from './start.js'
import { object } from './host.js'
import { routeAnswer, routeTask } from './routeCommand.js'
import { planWork } from './planCommand.js'
import { openDaemon, whereFor, type Daemon, type Where } from '../agentClient/daemon.js'
import { callerOf, outsideCaller, type Frame } from '../agentClient/model.js'
import { identifier } from './host.js'
import { resolve } from 'node:path'
import { readInsideFolder, uploadAttachments, type UploadTarget } from './attach.js'
import { buddyProjectFolder } from './buddyHome.js'
import { keyName } from './terminal.js'
import { randomUUID } from 'node:crypto'
import { readFileSync } from 'node:fs'
import { isatty } from 'node:tty'
import { inDaemonPane, NOT_IN_PANE, runningPane, windowsRunningPane, type PaneProbe, type RunningPane } from './callerPane.js'
import type { ProcessRow } from '../lib/processTable.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'
import { paneBuddy } from './buddyPane.js'
import { sendPane } from '../messages/command.js'
import { SWARM_TOOLS_SKILL } from '../lib/swarmTools.js'
type PaneFrame = Frame
/** Whether [pane] is a harness's here: a tmux pane as `callerOf` finds it, or a pty host's `<instance>:%N`. */
function harnessIn(frames: PaneFrame[], pane: string, machineId: string): boolean {
const pty = /^([^:]+):(%\d+)$/.exec(pane)
if (!pty) return !!callerOf(frames, pane, machineId)
return frames.some(frame => frame.terminal?.runtimes?.some(r => r.backend === 'ptyhost' && r.instance === pty[1] && r.paneId === pty[2]))
}
const 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 [--project NAME] [--archived [PAGE]] | messages GROUP [--thread ROOT] [--before SEQUENCE MESSAGE_ID] | message GROUP MESSAGE_ID | mine | task GROUP | decisions [--answered] | costs [--days N] | post GROUP TEXT|- OPERATION_ID [--to AGENT]... [--answers MESSAGE_ID | --reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | answer GROUP MESSAGE_ID TEXT|- OPERATION_ID [--to AGENT]... | 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 [--full-instructions] [--instructions-read REVISION] | plan [JSON] | remove-machine MACHINE_ID [--yes] | set-agents MACHINE_ID COUNT | instructions [PROJECT] | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help [tools]'
/** A Buddy's guard refuses a post or a proposal read from stdin (#2358): there its words would skip the secret check. A Buddy
* that followed the stdin form here was refused and tried again (#2360 took it out of a Buddy's help), so a Buddy's usage
* line and JSON hints never offer it. */
const BUDDY_USAGE = USAGE.replaceAll('TEXT|- OPERATION_ID', 'TEXT OPERATION_ID')
/** 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 JSON_STDIN = (action: string) => `${action} ${JSON_ACTIONS[action]} - <<'JSON' (the JSON on the next lines, then JSON alone on a line)`
const stdinHint = (action: string, buddy: boolean) => buddy
? `with the JSON in single quotes: ${action} ${JSON_ACTIONS[action]} '{...}' (an apostrophe inside it as \\u0027)`
: `or send the JSON on stdin with - in its place: ${JSON_STDIN(action)}`
/** A refusal worded for any caller, and for a Buddy (BUDDY_USAGE): which one it is is asked only once the command is refused. */
class UsageError extends Error {
constructor(readonly words: (buddy: boolean) => string) { super(words(false)) }
}
const usageError = () => new UsageError(buddy => buddy ? BUDDY_USAGE : USAGE)
/** 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 UsageError(buddy => `The ${action} JSON is not valid (${(error as Error).message}). Pass it as one argument, ${stdinHint(action, buddy)}.`)
}
}
/** 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[], buddy: boolean): string | null {
const [action, first = ''] = positional
const id = JSON_ACTIONS[action]
if (!id) return null
const hint = stdinHint(action, buddy)
// 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; ${buddy ? 'send it again ' : ''}${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
}
/** A message on stdin, for post's TEXT `-`.
*
* `post GROUP - OPERATION_ID` posted a literal dash: three Reviewer verdicts on 2026-10-30, #2345's findings among them,
* arrived as "-". So `-` reads the message from stdin, once, before anything is sent, and an empty or a terminal stdin is
* refused: nothing is posted, and nothing waits on a terminal for input that never comes. */
const POST_STDIN = "post GROUP - OPERATION_ID <<'MSG' (the message on the next lines, then MSG alone on a line)"
function postStdin(stdin: (what: string) => string, terminal: () => boolean): string {
if (terminal()) throw new Error(`post - reads the message from stdin, but stdin is a terminal, so nothing was posted. Send the message on stdin: ${POST_STDIN}, or pass it as TEXT.`)
// A heredoc ends the message with one line break, which is not part of it.
const text = stdin('post').replace(/\r?\n$/, '')
if (!text.trim()) throw new Error(`post - read no message from stdin, so nothing was posted. Send the message on stdin: ${POST_STDIN}. A message that is only - goes on stdin too.`)
return text
}
/** A JSON action's JSON on stdin, for its `-`; a terminal is refused as post's is, worded for a Buddy too (stdinHint). */
function jsonStdin(action: string, stdin: (what: string) => string, terminal: () => boolean): string {
if (terminal()) throw new UsageError(buddy => `${action} - reads the JSON from stdin, but stdin is a terminal, so nothing was sent. Pass it as one argument, ${stdinHint(action, buddy)}.`)
return stdin(action)
}
/** How long `-` waits on stdin while nothing arrives. #2355's review: `post GROUP - OPERATION_ID` from a pipe its writer left
* open (a tool that never closes it) read with no limit and waited for good. A heredoc or a pipe closes stdin at its end;
* every chunk starts the wait again, so a slow writer that keeps sending is never cut off. */
const STDIN_IDLE_MS = 30_000
export class StdinIdle extends Error {
constructor() { super(`Nothing more came on stdin for ${STDIN_IDLE_MS / 1000} s, and it was never closed.`) }
}
/** All of [stream], until it ends; StdinIdle once nothing has come for [idleMs], and the stream is let go, so the command can
* exit while its writer still holds the pipe open. */
export function readStdin(stream: NodeJS.ReadableStream & { destroy(): void }, idleMs = STDIN_IDLE_MS): Promise<string> {
return new Promise((resolve, reject) => {
let text = '', timer: ReturnType<typeof setTimeout> | undefined
const wait = () => {
clearTimeout(timer)
timer = setTimeout(() => { stream.destroy(); reject(new StdinIdle()) }, idleMs)
}
stream.setEncoding('utf8')
stream.on('data', (chunk: string) => { text += chunk; wait() })
stream.once('end', () => { clearTimeout(timer); resolve(text) })
stream.once('error', error => { clearTimeout(timer); reject(error) })
wait()
})
}
/** Why `-` read nothing usable from a stdin left open, and how to end it. */
function idleRefusal(what: string): string {
const waited = `${what} - read stdin until nothing more came for ${STDIN_IDLE_MS / 1000} s, but stdin was never closed`
return what === 'post'
? `${waited}, so nothing was posted. Close stdin after the message, as a heredoc does: ${POST_STDIN}, or pass it as TEXT.`
: `${waited}, so nothing was sent. Close stdin after the JSON, as a heredoc does: ${JSON_STDIN(what)}, or pass it as one argument.`
}
/** Stands in for stdin while the arguments are parsed the first time: stdin is read only for a command that wants it. */
class WantsStdin { constructor(readonly what: string) {} }
/** Whether the harness in this pane is a Buddy, by this computer's launch record (service.ts `buddyCheck`, what turns its
* guard on), for a refusal's wording alone. Asked of this computer's daemon, never one named with --machine. Anything it
* cannot tell is no Buddy: the guard still refuses what a Buddy may not send. */
async function buddyHere(open: typeof openDaemon, local: Where, pane: string | undefined): Promise<boolean> {
if (!pane) return false
try {
const daemon = await open(local)
try {
// The guard's own steps (buddyPane.ts paneBuddy), without its pane check: a wording, not a refusal.
return await paneBuddy(daemon, pane, local.machineId) === 'buddy'
} finally { daemon.close() }
} catch { return false }
}
/** The files one proposal may carry (backend buddies.ts MAX_PROPOSAL_ATTACHMENTS). */
const MAX_PROPOSAL_FILES = 5
/** route's flags after its JSON: `--full-instructions` and `--instructions-read N`, each at most once; null for anything else. */
function routeFlags(tail: string[]): { fullInstructions?: true; instructionsRead?: number } | null {
const flags: { fullInstructions?: true; instructionsRead?: number } = {}
for (let i = 0; i < tail.length; i++) {
if (tail[i] === '--full-instructions' && !flags.fullInstructions) flags.fullInstructions = true
else if (tail[i] === '--instructions-read' && flags.instructionsRead === undefined && /^\d{1,9}$/.test(tail[i + 1] ?? '')) flags.instructionsRead = Number(tail[++i])
else return null
}
return flags
}
/** [stdin] is asked for what `-` stands for: `post`'s message, or the JSON of the action it names. */
export function parseSuperTabArgs(argv: readonly string[], where: Where, stdin: (what: string) => string = () => readFileSync(0, 'utf8'),
terminal: () => boolean = () => isatty(0)) {
const positional: string[] = []
let tabId = '', agentId = ''
const target = { ...where }
for (let i = 0; i < argv.length; i++) {
const flag = argv[i]
if (flag === '--tab') tabId = argv[++i] ?? ''
else if (flag === '--agent') agentId = argv[++i] ?? ''
else if (flag === '--port') target.port = Number(argv[++i])
else if (flag === '--machine') target.machineId = argv[++i] ?? ''
else { positional.push(...argv.slice(i)); break }
}
if (!Number.isInteger(target.port) || target.port < 1 || target.port > 65535 || !identifier(target.machineId)) throw usageError()
// `-` in the JSON's place reads it from stdin, where no shell quoting can split it. A terminal is refused at once, as post's
// is: read, it waited 30 s for input that never comes and then said stdin was never closed (review of #2379).
if (JSON_ACTIONS[positional[0]] && positional[2] === '-') positional[2] = jsonStdin(positional[0], stdin, terminal)
// A person's one Buddy reads one of its projects by its name (status --project NAME, spec 2026-10-31-one-buddy-per-swarm):
// taken out first, so it goes with status alone or with --archived.
let statusProject: string | undefined
const projectAt = positional[0] === 'status' ? positional.indexOf('--project') : -1
if (projectAt > 0) {
statusProject = positional[projectAt + 1]
if (!statusProject || statusProject.length > 200 || /[\u0000-\u001f]/.test(statusProject)) throw usageError()
positional.splice(projectAt, 2)
}
const [action, first, second, third] = positional
if (action !== 'help' && (!identifier(tabId) || (agentId && !identifier(agentId)))) throw usageError()
const payload: Record<string, unknown> = { action, tabId, agentId, ...(statusProject ? { project: statusProject } : {}) }
if (action === 'messages' && identifier(first) && positional.length === 2) payload.conversationId = first
// Older messages, a page before the cursor the last page named: its sequence and message id together, as messages may
// share a sequence and a sequence alone skipped them (security review 2 of #2115). A Buddy reads a task's history this way.
else if (action === 'messages' && identifier(first) && positional.length === 5 && second === '--before' && /^(0|[1-9][0-9]{0,15})$/.test(third ?? '')
&& Number.isSafeInteger(Number(third)) && identifier(positional[4])) {
Object.assign(payload, { conversationId: first, before: Number(third), beforeId: positional[4] })
}
// One thread, its root and replies (a Buddy's thread session reads its own this way, with the main-chat messages it started
// from), paged as the conversation is.
else if (action === 'messages' && identifier(first) && second === '--thread' && identifier(third) && (positional.length === 4
|| (positional.length === 7 && positional[4] === '--before' && /^(0|[1-9][0-9]{0,15})$/.test(positional[5] ?? '')
&& Number.isSafeInteger(Number(positional[5])) && identifier(positional[6])))) {
Object.assign(payload, { conversationId: first, thread: third,
...(positional.length === 7 ? { before: Number(positional[5]), beforeId: positional[6] } : {}) })
}
// A Buddy's archived tasks, a page at a time from the page the last one named (cli/src/superTabs/buddyStatus.ts).
else if (action === 'status' && first === '--archived' && (positional.length === 2 || positional.length === 3 && /^[A-Za-z0-9_-]{1,512}$/.test(second ?? ''))) {
Object.assign(payload, { archived: true, ...(second ? { before: second } : {}) })
}
else if (action === 'mine' && positional.length === 1) { /* the agent's own work (agentContext.ts) */ }
else if (action === 'task' && identifier(first) && positional.length === 2) payload.conversationId = first
else if (action === 'decisions' && (positional.length === 1 || (positional.length === 2 && first === '--answered'))) payload.state = first ? 'answered' : 'open'
else if (action === 'instructions' && (positional.length === 1 || positional.length === 2 && identifier(first))) {
if (first) payload.projectId = first
}
else if (action === 'costs' && (positional.length === 1 || (positional.length === 3 && first === '--days' && /^[1-9][0-9]?$/.test(second ?? '') && Number(second) <= 90))) {
payload.days = positional.length === 3 ? Number(second) : 7
}
else if (action === 'message' && identifier(first) && identifier(second) && positional.length === 3) {
Object.assign(payload, { conversationId: first, messageId: second })
}
else if (action === 'post' && identifier(first) && typeof second === 'string' && identifier(third)) {
let replyTo: string | null = null, answers: string | null = null
const attach: string[] = [], mentions: string[] = [], to: string[] = []
for (let i = 4; i < positional.length; i += 2) {
const [flag, value] = [positional[i], positional[i + 1]]
if (flag === '--reply-to' && identifier(value) && replyTo === null && answers === null) replyTo = value
// The answer right below a message, in the main flow (task #2929); a reply to it goes in its thread.
else if (flag === '--answers' && identifier(value) && answers === null && replyTo === null) answers = value
// The agents it reaches, any agent of this project; the server adds @Name, a reply's author and a task's assignee (#2963).
else if (flag === '--to' && identifier(value) && (to.includes(value) || to.length < 16)) { if (!to.includes(value)) to.push(value) }
else if (flag === '--attach' && value && attach.length < 10) attach.push(resolve(value))
// A person's id, username or display name (an email from older callers), as written; the service maps it (task #2954).
else if (flag === '--mention' && value?.trim()) mentions.push(value.trim())
else throw usageError()
}
// TEXT `-` is the message on stdin; any other TEXT is the message itself, and stdin is never read.
const text = second === '-' ? postStdin(stdin, terminal) : second
// A screenshot or a log may go without words.
if (!text.trim() && !attach.length) throw usageError()
Object.assign(payload, { action: 'command', operationId: third, ...(attach.length ? { attach } : {}),
command: { type: 'message.send', conversationId: first, text, replyTo, ...(answers ? { answers } : {}), recipientIds: to, ...(mentions.length ? { mentions } : {}) } })
} else if (action === 'answer' && identifier(first) && identifier(second) && typeof third === 'string' && identifier(positional[4])) {
// The answer to the message [second] (task #3403): the server puts it in that message's thread, or right below it, and
// refuses a second answer saying where the first is.
const to: string[] = []
for (let i = 5; i < positional.length; i += 2) {
const [flag, value] = [positional[i], positional[i + 1]]
if (flag === '--to' && identifier(value) && (to.includes(value) || to.length < 16)) { if (!to.includes(value)) to.push(value) }
else throw usageError()
}
const text = third === '-' ? postStdin(stdin, terminal) : third
if (!text.trim()) throw usageError()
Object.assign(payload, { action: 'command', operationId: positional[4],
command: { type: 'message.send', conversationId: first, text, replyTo: null, answers: second, answer: true, recipientIds: to } })
} else if (action === 'react' && identifier(first) && identifier(second) && identifier(third) && identifier(positional[4])
&& (positional.length === 5 || positional.length === 6 && positional[5] === '--off')) {
// An acknowledgement without a post, as Slack bots do (swarm skills): the backend checks the emoji and who may react.
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: jsonArgument(action, second) })
} else if (action === 'propose' && identifier(first) && second) {
const attach: string[] = []
for (let i = 3; i < positional.length; i += 2) {
const [flag, value] = [positional[i], positional[i + 1]]
if (flag === '--attach' && value) attach.push(resolve(value))
else throw usageError()
}
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: { ...object(jsonArgument(action, second)), type: 'buddy.propose' } })
} else if (action === 'start' && identifier(first) && second && positional.length === 3) {
Object.assign(payload, { operationId: first, request: jsonArgument(action, second) })
} else if (action === 'resume' && identifier(first) && positional.length === 2) payload.startId = first
else if (action === 'capacity' && identifier(first) && second && positional.length === 3) {
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.
Object.assign(payload, second === '--yes'
? { action: 'backend', method: 'POST', path: `/api/super-tabs/${tabId}/commands`,
body: { operationId: `machine-remove-${randomUUID()}`, command: { type: 'machine.remove', machineId: first } } }
: { action: 'backend', method: 'GET', path: `/api/super-tabs/${tabId}/machines/${first}/removal/v2` })
} else if (action === 'set-agents' && identifier(first) && /^[1-9][0-9]{0,3}$/.test(second ?? '') && positional.length === 3) {
// 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[3]?.startsWith('--') && !routeFlags(positional.slice(3))) {
throw usageError()
} else if (action === 'route' && identifier(first) && second && routeFlags(positional.slice(3))) {
// The whole instructions only on request, and none of them for a revision the caller read (task #3294).
Object.assign(payload, { conversationId: first, assessment: jsonArgument(action, second), ...routeFlags(positional.slice(3)) })
} else if (action === 'plan' && positional.length <= 2) {
if (first !== undefined) payload.request = JSON.parse(first)
} else if (action === 'screen' && identifier(first) && (positional.length === 2
|| positional.length === 4 && second === '--scrollback' && /^[1-9]\d*$/.test(third ?? '') && Number(third) <= 200)) {
// The id names this one read; a read sent twice is only read twice.
Object.assign(payload, { operationId: `terminal-${randomUUID()}`,
command: { type: 'agent.screen', agentId: first, ...(positional.length === 4 ? { scrollback: Number(third) } : {}) } })
} else if (action === 'type' && identifier(first)) {
let text: string | undefined
const keys: string[] = []
for (let i = 2; i < positional.length; i++) {
if (positional[i] === '--key') {
const key = keyName(positional[++i] ?? '')
if (!key) throw usageError()
keys.push(key)
} else if (text === undefined && !keys.length) text = positional[i]
else throw usageError()
}
if (!text && !keys.length) throw usageError()
Object.assign(payload, { operationId: `terminal-${randomUUID()}`,
command: { type: 'agent.input', agentId: first, ...(text ? { text } : {}), ...(keys.length ? { keys } : {}) } })
} else if (action === 'help' && first === 'tools' && positional.length === 2) {
// The full tools manual, which every agent's launch line has it read (lib/swarmSkills.ts): printed by this CLI, no daemon asked.
payload.topic = 'tools'
} else if (!['status', 'help'].includes(action) || positional.length !== 1) {
throw new UsageError(buddy => jsonShapeError(positional, buddy) ?? (buddy ? BUDDY_USAGE : USAGE))
}
return { where: target, payload }
}
/** The arguments, with stdin read for `-` only when they want it, and then at most until it idles (readStdin). */
async function parse(argv: readonly string[], local: Where, stdin: () => string | Promise<string>, terminal?: () => boolean) {
try {
return parseSuperTabArgs(argv, local, what => { throw new WantsStdin(what) }, terminal)
} catch (error) {
if (!(error instanceof WantsStdin)) throw error
const text = await Promise.resolve().then(stdin).catch(failure => {
throw failure instanceof StdinIdle ? new Error(idleRefusal(error.what)) : failure
})
return parseSuperTabArgs(argv, local, () => text, terminal)
}
}
export async function superTabCommand(argv: readonly string[], deps: {
where?: () => Where; open?: typeof openDaemon; print?: (text: string) => void; pane?: string; probe?: PaneProbe; fetch?: typeof fetch; env?: NodeJS.ProcessEnv
platform?: NodeJS.Platform; stdin?: () => string | Promise<string>; terminal?: () => boolean
readProcesses?: () => Promise<ProcessRow[] | null>
} = {}): Promise<number> {
let daemon: Daemon | null = null
let operationId: unknown
const print = deps.print ?? console.log
try {
const platform = deps.platform ?? process.platform, env = deps.env ?? process.env, open = deps.open ?? openDaemon
// The pane this runs in, from its processes: TMUX_PANE is what the command says, and it may not name another harness's.
const running: RunningPane = 'pane' in deps ? { pane: deps.pane }
: platform === 'win32' ? await windowsRunningPane(sendPane(env), deps.readProcesses)
: runningPane(env, deps.probe, platform)
if (running.refused) throw new Error(running.refused)
const pane = running.pane
const local = (deps.where ?? (() => whereFor(pane)))()
const request = await parse(argv, local, deps.stdin ?? (() => readStdin(process.stdin)), deps.terminal)
.catch(async error => {
if (error instanceof UsageError && await buddyHere(open, local, pane)) throw new Error(error.words(true))
throw error
})
operationId = request.payload.operationId
if (request.payload.action === 'help' && request.payload.topic === 'tools') { print(SWARM_TOOLS_SKILL); return 0 }
// A harness reaches the Swarm through this computer's Harness alone (second review of #2087: a Buddy's --machine reached
// the owner's other Mac, which knew no pane there). The daemon refuses an agent's request from another computer as well.
const elsewhere = request.where.port !== local.port || request.where.machineId !== local.machineId
// Asked of this computer's daemon, never the other machine's (re-check of #2093: --machine asked the other one, which does
// not answer for this computer).
if (elsewhere && pane) {
const home = await open(local)
try {
const listed = await home.request('agents_list')
if (harnessIn(Array.isArray(listed.agents) ? listed.agents as PaneFrame[] : [], pane, local.machineId)) throw new Error(ELSEWHERE)
} finally { home.close() }
}
daemon = await open(request.where)
const owners = request.payload.action === 'backend' || request.payload.action === 'setMachineAgents'
if (owners) {
// The owner's own acts: removal deletes this machine's Swarm folders, and no agent raises its own machine's room
// (Lead, 2026-10-28). So neither a Swarm agent on it (its pane, or --agent) nor an outside agent's shell may run
// them with the owner's authority.
const listed = request.payload.agentId || outsideCaller(env, request.where.machineId) ? null : await daemon.request('agents_list')
if (!listed || callerOf(Array.isArray(listed.agents) ? listed.agents as Frame[] : [], pane, request.where.machineId)) {
throw new Error(request.payload.action === 'backend' ? 'Remove a machine from your own terminal or from Desktop, not from an agent.'
: 'Set a machine\'s agents from your own terminal or from Desktop, not from an agent.')
}
}
// Help names the caller when it can, as every request from a harness does; every agent reads the same help (project
// instructions, phase 4), and outside a harness it is that help too.
const help = request.payload.action === 'help'
// A harness's pane speaks as its own agent alone: with --agent too, its harness goes with the request, and the daemon
// refuses an agent that is not that harness's (security review of #2087: a Buddy named its Builder). A person's terminal
// is no harness, and its --agent is the person's as before.
if (!owners && (!request.payload.agentId || pane) && (!help || request.payload.tabId)) {
const listed = await daemon.request('agents_list')
const frames = Array.isArray(listed.agents) ? listed.agents as Frame[] : []
const caller = callerOf(frames, pane, request.where.machineId)
if (caller && !await inDaemonPane(daemon, caller.agentId, running.ancestors)) throw new Error(NOT_IN_PANE)
if (caller) request.payload.harnessId = caller.agentId
else if (!help && !request.payload.agentId) throw new Error('Run this command inside the participating harness, or supply its --agent ID.')
}
const source = daemon
const scoped = (payload: Record<string, unknown>) => source.request('super_tabs', {
tabId: request.payload.tabId, agentId: request.payload.agentId, harnessId: request.payload.harnessId, ...payload,
}, 30_000)
let result: Record<string, unknown>
if (['start', 'resume'].includes(String(request.payload.action))) {
result = await startAgent(request.payload, scoped, request.where, deps.open)
} else if (request.payload.action === 'capacity') {
// Establish current Super Tab participation before inspecting a machine;
// the native relay independently enforces that account's machine access.
const known = await scoped({ action: 'status' })
if (known.error) result = known
else {
const target = await open(request.where, String(request.payload.targetMachineId))
try { result = { ok: true, ...await inspectCapacity(target, object(request.payload.request)) } }
finally { target.close() }
}
} else if (request.payload.action === 'screen' || request.payload.action === 'type') {
const answer = await terminalRequest(request.payload, scoped)
const value = object(answer.value)
// The screen is printed as it is, for the Lead to read; anything else, and every failure, as JSON.
if (request.payload.action === 'screen' && value.ok === true && typeof value.text === 'string') print(value.text)
else print(JSON.stringify(answer.error ? answer : value))
return value.ok === true ? 0 : 1
} else if (request.payload.action === 'mine' || request.payload.action === 'task') {
// Printed as text for the agent to read (agent context design); every failure, as JSON.
const answer = await scoped({ ...request.payload })
const value = object(answer.value)
if (answer.ok === true && typeof value.text === 'string') { print(value.text); return 0 }
print(JSON.stringify(answer))
return 1
} else if (request.payload.action === 'instructions') {
// Printed as text for the agent to work by; every failure, as JSON.
const answer = await scoped({ ...request.payload })
const value = object(answer.value)
if (answer.ok === true && typeof value.text === 'string') {
// Each note with its id, which note.remove takes, and who asked by name where the status read has it (final review).
const notes = Array.isArray(value.notes) ? value.notes.map(object) : []
const coordinator = typeof value.coordinatorName === 'string' && value.coordinatorName ? value.coordinatorName : 'The coordinator'
const when = (at: unknown) => typeof at === 'number' && Number.isFinite(at) ? new Date(at).toISOString() : String(at)
print([`Instructions of project ${value.projectId}, revision ${value.revision}${value.template ? ' (the built-in template)' : ''}`, '', value.text,
...(notes.length ? ['', `${coordinator}'s notes:`, ...notes.map(n => `- ${n.text} (note ${n.id}, asked by ${n.askedByName ?? n.askedBy}, ${when(n.at)}`
+ `${n.expiresAt ? `, until ${when(n.expiresAt)}` : ''})`)] : [])].join('\n'))
return 0
}
print(JSON.stringify(answer))
return 1
} else if (request.payload.action === 'route') {
result = routeAnswer(await routeTask({ tabId: String(request.payload.tabId), conversationId: String(request.payload.conversationId),
assessment: request.payload.assessment }, scoped, request.where, deps.open),
{ fullInstructions: request.payload.fullInstructions === true, ...(typeof request.payload.instructionsRead === 'number' ? { instructionsRead: request.payload.instructionsRead } : {}) })
} else if (request.payload.action === 'plan') {
// Advisory: the plan records nothing, and the solver runs here, on the Lead's machine.
result = await planWork({ request: request.payload.request }, scoped, { dataDir: request.where.dataDir })
} else {
const { attach, ...payload } = request.payload
// Each file goes to the daemon's local upload route, which streams it to the backend with the account's token;
// this process holds no account credential.
if (Array.isArray(attach)) {
const command = object(payload.command)
const target = { tabId: String(payload.tabId), conversationId: String(command.conversationId), port: request.where.port, dataDir: request.where.dataDir }
command.attachmentIds = command.type === 'buddy.propose'
? await proposalFiles(attach as string[], String(payload.operationId), command, target, daemon, scoped, { ...deps, pane,
local: request.where.machineId === local.machineId && request.where.port === local.port })
: await uploadAttachments(attach as string[], String(payload.operationId), target, scoped, deps.fetch)
}
result = await daemon.request('super_tabs', payload, 30_000)
}
print(JSON.stringify({ ...result, ...(operationId ? { operationId } : {}) }))
return result.error ? 1 : 0
} catch (error) {
print(JSON.stringify({ error: error instanceof Error ? error.message : String(error), ...(operationId ? { operationId } : {}) }))
return 1
} finally { daemon?.close() }
}
/** A Buddy's proposal files (backend buddies.ts): those in its own folder, as its harness here records it, uploaded to its
* chat beside the files its owner sent there, which the proposal names by id. A repeat finds the proposal in the project
* chat and names the files it went with. */
async function proposalFiles(paths: string[], operationId: string, command: Record<string, unknown>, target: UploadTarget, daemon: Daemon,
scoped: (payload: Record<string, unknown>) => Promise<Record<string, unknown>>, deps: { pane?: string; fetch?: typeof fetch; local: boolean }): Promise<string[]> {
// Its folder is on this machine: through another machine's daemon (--machine, --port) its pane would name someone else's.
if (!deps.local) throw new Error('Attach files to a proposal from your Buddy\'s own terminal.')
const named = Array.isArray(command.attachmentIds) ? command.attachmentIds.map(String) : []
// Counted before any upload, so a refused proposal leaves no file behind.
if (new Set(named).size + paths.length > MAX_PROPOSAL_FILES) throw new Error(`Attach at most ${MAX_PROPOSAL_FILES} files to a proposal.`)
const listed = await daemon.request('agents_list')
const frames = Array.isArray(listed.agents) ? listed.agents as Frame[] : []
// The pane its parent processes prove (callerPane.ts), never TMUX_PANE as the command says it.
const caller = callerOf(frames, deps.pane, String(daemon.machineId))
const folder = frames.find(f => f.id === caller?.agentId)?.project?.cwd
if (!folder) throw new Error('Attach files to a proposal from your Buddy\'s own terminal.')
// Read for the upload (service.ts proposalTarget): a Buddy's status is a task summary with no chats, so reading it here refused
// every Buddy proposal with a file (Huy 11-06, #3872).
const read = object((await scoped({ action: 'proposalTarget', conversationId: target.conversationId })).value)
const projects = Array.isArray(read.projects) ? read.projects.map(object) : []
const chat = read.chat && object(read.chat).id === target.conversationId ? object(read.chat) : undefined
// A person's one Buddy chat has no project (Dee, 10-31): a project session proposes into its own project, and the Swarm-wide
// Buddy into the one its JSON names (Scholes, 11-02), with only that project's files: its folder holds every project's.
// The read answers for the asking agent alone: its record is the caller's, under its Swarm id, not the terminal's id the pane
// names (Linuxtest4 on #3402: matched by that id, a session's project was never read, and another project's PM got its file).
const self = read.self ? object(read.self) : undefined
const session = object(self?.buddySession).projectId
const wide = chat?.kind === 'swarm-buddy' && typeof session !== 'string'
const projectId = wide ? command.projectId : chat?.kind === 'swarm-buddy' ? session : chat?.projectId
const home = projects.find(p => p.id === projectId)?.leadConversationId
// Refused here too, before any upload: the backend would refuse it and leave the file behind.
if (!wide && command.projectId && command.projectId !== projectId) throw new Error('A session sends only to its own project\'s PM: leave the project out.')
if (typeof home !== 'string') throw new Error(wide ? 'Name the project to send this to, from your status.' : 'Name your own chat: a proposal comes from there.')
const inside = wide ? buddyProjectFolder(folder, String(projectId)) : folder
if (!inside) throw new Error('That project\'s code is not on this machine: name by its id a file your owner sent in your chat, or one you showed them there.')
const files = readInsideFolder(paths, inside)
const uploaded = await uploadAttachments(files, operationId, { ...target, sentIn: home }, scoped, deps.fetch)
return [...new Set([...named, ...uploaded])]
}
/** How often a terminal result is read: the backend holds each read about 20 s, and the worker's machine has 10 s to pick a
* request up and 30 s to answer it, after which the backend answers with the reason. */
const TERMINAL_READS = 3
async function terminalRequest(payload: Record<string, unknown>, scoped: (payload: Record<string, unknown>) => Promise<Record<string, unknown>>): Promise<Record<string, unknown>> {
const sent = await scoped({ action: 'command', operationId: payload.operationId, command: payload.command })
if (sent.error) return sent
const requestId = object(object(sent.value).result).requestId
if (!identifier(requestId)) return { error: 'TERMINAL_UNAVAILABLE', detail: 'This Swarm\'s server does not relay terminals yet.' }
for (let read = 0; read < TERMINAL_READS; read++) {
// Not `requestId`: the daemon's transport numbers each request under that name (agentClient/daemon.ts).
const answer = await scoped({ action: 'terminalResult', terminalRequestId: requestId })
// A read the backend held to its limit while the worker's machine was still answering is read again.
if (answer.error === 'BACKEND_TIMEOUT' || object(answer.value).pending === true) continue
return answer
}
return { error: 'TERMINAL_PENDING', detail: 'The worker\'s machine has not answered yet. Try again in a moment.' }
}