Skip to content

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.

feat(cli): harness machines engines <machine> asks that machine which engines it has, now (#1788) (#1888)

daniel-auto30a386662115
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 033a833b0..27c84c39e 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -46,6 +46,7 @@ import { LocalModels } from './lib/localModels.js'
import { STRICT_DOWN_TYPES, encryptDownFrame, encryptDownFrameFor, encryptRpcResult } from './lib/e2ee/applicationFrames.js'
import { CloseAgentService } from './lib/closeAgentService.js'
import { env } from './config/env.js'
+import { supportsFirstPrompt } from './lib/engineLaunch.js'
describe('safe session close RPC', () => {
it('seals cleanup previews and passes the open-tab condition to Close', async () => {
@@ -1883,6 +1884,29 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('answers engines_probe with whether this machine can start each engine with a first prompt (#1788)', async () => {
+ const socket = relaySocket('token')
+ const frames: Array<Record<string, unknown>> = []
+ socket.registerLocalClient('local:probe', {
+ sendFrame: (frame) => { frames.push(frame); return true },
+ sendBinary: () => true,
+ })
+ socket.engineProbeProvider = async () => [
+ { engine: 'claude', installed: true, command: 'claude', installable: true, signedIn: true },
+ { engine: 'cursor', installed: false, command: 'cursor-agent', installable: true },
+ ] as never
+ socket.handleLocalFrame('local:probe', { type: 'engines_probe', payload: { requestId: 'probe-fp' } })
+ await vi.waitFor(() => expect(frames.some((frame) => frame.type === 'engines_probe_result')).toBe(true))
+ const reply = frames.find((frame) => frame.type === 'engines_probe_result')!.payload as {
+ engines: Array<{ engine: string; firstPrompt: boolean }>
+ }
+ const firstPrompt = Object.fromEntries(reply.engines.map((entry) => [entry.engine, entry.firstPrompt]))
+ expect(firstPrompt).toEqual({ claude: supportsFirstPrompt('claude'), cursor: supportsFirstPrompt('cursor') })
+ expect(firstPrompt.claude).toBe(true)
+ await socket.unregisterLocalClient('local:probe')
+ await socket.stop()
+ })
+
it('opens a harness on a conversation Harness did not start, and refuses what a resume cannot take', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index e63404cfb..5c9477c59 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -35,6 +35,7 @@ import type { ScmLaunchRecord } from './scm/types.js'
import type { StartedBy } from './lib/agentAttribution.js'
import { probeEngines } from './lib/engineProbe.js'
import { engineInstallRecipe } from './lib/engineInstall.js'
+import { supportsFirstPrompt } from './lib/engineLaunch.js'
import { agentFrame, type AgentDshContext, type AgentFrame } from './lib/agentFrame.js'
import type { AgentTokenUsage } from './lib/agentUsageWire.js'
import { terminalHandoffRequest } from './lib/terminalHandoff.js'
@@ -1126,6 +1127,10 @@ export class BackendSocket {
// lets an older CLI (which never sends the field) keep reading as "unknown" rather
// than "no", per the desktop app's `EngineAvailability.fromJson`.
...(entry.engine === 'codex' ? { supportsCodexHome: true } : {}),
+ // Static too, and this machine's own: whether `harness new` here can hand the engine a
+ // first prompt (engineLaunch.ts FIRST_PROMPT_ARGS), so a caller on another version reads
+ // it from the machine that will start the agent (#1788).
+ firstPrompt: supportsFirstPrompt(entry.engine),
// Static too: a pane whose engine is still downloading beside Desktop Harness's setup
// waits for that download (engineLaunch.ts `harness_wait_download`) rather than
// installing it again, so the desktop may open the pane before the download ends.
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 277d588f0..a6d155f79 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -180,6 +180,8 @@ Machine:
harness settings [<name> on|off] what agents may do (agents-start-agents, agents-tell-agents, pull-request-line, agent-messages): your account's experiments in Settings ▸ Experimental, each off by default
harness mcp-servers [add|remove] local MCP servers (a paired lamp's lamp-mcp) for the agents Harness starts here: yours alone to change
harness machines delete <id> remove ANOTHER machine (refuses this one; use \`harness logout\`)
+ harness machines engines <machine> [--engine E]… [--json]
+ ask another of your machines now which engines it has: installed, signed in, first prompt
harness e2e plan which coding tools have a new version out (the grid-switch e2e trigger)
harness e2e grid-switch move a fresh agent subscription -> grid -> back home with its tool + MCP; leaves a review bundle
harness remote from a Harness terminal tile: open a terminal on another of your machines and move this tile to it
@@ -2931,6 +2933,12 @@ switch (cmd) {
else if (args[0] === 'list') machinesListCommand(flags.includes('--json')).catch(onError)
else if (args[0] === 'delete' || args[0] === 'rm') {
machinesDeleteCommand(args[1], flags.includes('--yes')).catch(onError)
+ } else if (args[0] === 'engines') {
+ // The raw words after `engines`: `--engine <name>` takes a value the args/flags split would separate.
+ import('./lib/machineEngines.js')
+ .then(({ runMachinesEngines }) => runMachinesEngines(rest.slice(rest.indexOf('engines') + 1), env.ADAPTER_DATA_DIR, daemonPort()))
+ .then((code) => { process.exitCode = code })
+ .catch(onError)
} else { console.error(`Unknown command: machines ${args[0]}`); usage(1) }
break
case 'link':
diff --git a/cli/src/devices/client.ts b/cli/src/devices/client.ts
index 06e8b1a1f..6cfc31a26 100644
--- a/cli/src/devices/client.ts
+++ b/cli/src/devices/client.ts
@@ -15,6 +15,8 @@ export interface DevicesClientDeps {
fetch?: typeof fetch
request?: (machineId: string, type: string, payload?: Record<string, unknown>) => Promise<Record<string, unknown>>
delay?: (ms: number) => Promise<void>
+ /** How long the other computer has to answer: 12 s unless a request needs longer (an engine probe's login shells). */
+ timeoutMs?: number
}
export function deviceRequest(deps: DevicesClientDeps, machineId: string, type: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
@@ -29,7 +31,7 @@ export function deviceRequest(deps: DevicesClientDeps, machineId: string, type:
try { socket.close() } catch { /* already closed */ }
if (error) reject(error); else resolve(reply!)
}
- const timer = setTimeout(() => finish(new Error('This computer did not answer in time.')), 12_000)
+ const timer = setTimeout(() => finish(new Error('This computer did not answer in time.')), deps.timeoutMs ?? 12_000)
socket.on('open', () => socket.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1, tool: true } })))
socket.on('error', error => finish(error))
socket.on('close', code => finish(new Error(code === 4404 ? 'Link this computer in Machines first.' : 'The computer disconnected.')))
diff --git a/cli/src/lib/autonomous-device/addonCommand.ts b/cli/src/lib/autonomous-device/addonCommand.ts
index 4dd3a36e5..4c5e1c18d 100644
--- a/cli/src/lib/autonomous-device/addonCommand.ts
+++ b/cli/src/lib/autonomous-device/addonCommand.ts
@@ -16,7 +16,7 @@ const VALUE_FLAGS = new Set(['--device', '--machine', '--act', '--holds-ms', '--
export type MachineAsk = (machine: string, op: string, input: Record<string, unknown>) => Promise<Record<string, unknown>>
/** The owner's machine `--machine` names, by id or name (case-blind), as this daemon lists the account's machines. */
-async function machineIdOf(word: string, dataDir: string, port: number): Promise<string> {
+export async function machineIdOf(word: string, dataDir: string, port: number): Promise<string> {
const response = await fetch(`http://127.0.0.1:${port}/api/machines`, {
headers: { 'x-adapter-local': '1', ...localCredentialHeaders(dataDir) }, signal: AbortSignal.timeout(8000) })
if (!response.ok) throw Object.assign(new Error('Could not read the account\'s machines. Sign in and try again.'), { code: 'MACHINES_UNAVAILABLE' })
diff --git a/cli/src/lib/machineEngines.spec.ts b/cli/src/lib/machineEngines.spec.ts
new file mode 100644
index 000000000..ab42b56e2
--- /dev/null
+++ b/cli/src/lib/machineEngines.spec.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { readinessRows, runMachinesEngines, type MachineProbe } from './machineEngines.js'
+
+const OFFICE = 'm-office-1'
+
+describe('readinessRows (#1788)', () => {
+ it('reads a probe that said false as unknown, never as not there', () => {
+ const rows = readinessRows(OFFICE, {
+ engines: [
+ { engine: 'claude', installed: true, installable: true, signedIn: false, firstPrompt: true },
+ { engine: 'hermes', installed: false, installable: true, firstPrompt: true },
+ ],
+ })
+ expect(rows).toEqual([
+ { machineId: OFFICE, engine: 'claude', installed: true, signedIn: false, installable: true, firstPrompt: true },
+ { machineId: OFFICE, engine: 'hermes', installed: null, signedIn: null, installable: true, firstPrompt: true },
+ ])
+ })
+
+ it('says signedIn only once installed, and firstPrompt is unknown from an older Harness', () => {
+ const rows = readinessRows(OFFICE, {
+ engines: [
+ { engine: 'codex', installed: false, signedIn: false },
+ { engine: 'cursor', installed: true },
+ 'not an entry',
+ { installed: true },
+ ],
+ })
+ expect(rows).toEqual([
+ { machineId: OFFICE, engine: 'codex', installed: null, signedIn: null, installable: null, firstPrompt: null },
+ { machineId: OFFICE, engine: 'cursor', installed: true, signedIn: null, installable: null, firstPrompt: null },
+ ])
+ })
+})
+
+describe('harness machines engines (#1788)', () => {
+ const probing = (reply: Record<string, unknown>) => {
+ const asked: Array<{ machine: string; payload: Record<string, unknown> }> = []
+ const probe: MachineProbe = async (machine, payload) => {
+ asked.push({ machine, payload })
+ return { machineId: OFFICE, reply }
+ }
+ return { asked, probe }
+ }
+
+ it('asks the named machine for the engines named, and prints one JSON line each', async () => {
+ const { asked, probe } = probing({ engines: [{ engine: 'hermes', installed: true, installable: true, firstPrompt: true }] })
+ const lines: string[] = []
+ const code = await runMachinesEngines(['office', '--engine', 'hermes', '--engine', 'hermes', '--json'], '/tmp', 1, probe, (line) => lines.push(line))
+ expect(code).toBe(0)
+ expect(asked).toEqual([{ machine: 'office', payload: { engines: ['hermes'] } }])
+ expect(lines.map((line) => JSON.parse(line))).toEqual([
+ { machineId: OFFICE, engine: 'hermes', installed: true, signedIn: null, installable: true, firstPrompt: true },
+ ])
+ })
+
+ it('asks for every engine when none is named', async () => {
+ const { asked, probe } = probing({ engines: [] })
+ expect(await runMachinesEngines(['office', '--json'], '/tmp', 1, probe, () => {})).toBe(0)
+ expect(asked[0].payload).toEqual({})
+ })
+
+ it('refuses an engine it does not know, a missing machine and an unknown flag, asking nothing', async () => {
+ const { asked, probe } = probing({ engines: [] })
+ for (const argv of [['office', '--engine', 'nope'], [], ['office', '--engine'], ['office', '--fast'], ['a', 'b']]) {
+ expect(await runMachinesEngines(argv, '/tmp', 1, probe, () => {})).toBe(2)
+ }
+ expect(asked).toEqual([])
+ })
+
+ it('fails plainly when the machine cannot be reached or its probe fails', async () => {
+ const unreachable: MachineProbe = async () => { throw new Error('Link this computer in Machines first.') }
+ expect(await runMachinesEngines(['office', '--json'], '/tmp', 1, unreachable, () => {})).toBe(1)
+ const { probe } = probing({ error: 'ENGINE_PROBE_FAILED' })
+ const lines: string[] = []
+ expect(await runMachinesEngines(['office', '--json'], '/tmp', 1, probe, (line) => lines.push(line))).toBe(1)
+ expect(lines).toEqual([])
+ })
+})
diff --git a/cli/src/lib/machineEngines.ts b/cli/src/lib/machineEngines.ts
new file mode 100644
index 000000000..0192bf140
--- /dev/null
+++ b/cli/src/lib/machineEngines.ts
@@ -0,0 +1,102 @@
+import { WebSocket } from 'ws'
+import { ENGINES } from '../engines/types.js'
+import { deviceRequest } from '../devices/client.js'
+import { machineIdOf } from './autonomous-device/addonCommand.js'
+
+const USAGE = 'Usage: harness machines engines <machine> [--engine <engine>]… [--json]'
+ + ' — which engines another of your machines has, asked of it now (#1788).'
+
+/** An engine probe answers within each engine's login shell (5 s each, engineProbe.ts), so more than the link's usual 12 s. */
+const PROBE_WITHIN_MS = 30_000
+
+/** One engine's readiness on a machine, as printed: `null` is unknown, never "not there". */
+export interface EngineReadiness {
+ machineId: string
+ engine: string
+ /** `true`, or `null`: the probe reads a missing command, a login shell that timed out and a failed spawn
+ * all as not installed (engineProbe.ts), so only a failed start says an engine is missing. */
+ installed: true | null
+ /** Read for claude and codex only, and only once installed; `null` for every other engine. */
+ signedIn: boolean | null
+ installable: boolean | null
+ /** Whether that machine's Harness can start the engine with a first prompt; `null` from an older Harness. */
+ firstPrompt: boolean | null
+}
+
+/** Asks another of the owner's machines one request over the machine link: its answer, or a throw. */
+export type MachineProbe = (machine: string, payload: Record<string, unknown>) => Promise<{ machineId: string; reply: Record<string, unknown> }>
+
+const probeMachine = (dataDir: string, port: number): MachineProbe => async (machine, payload) => {
+ const machineId = await machineIdOf(machine, dataDir, port)
+ const reply = await deviceRequest({
+ port, dataDir, machineId: async () => null, timeoutMs: PROBE_WITHIN_MS,
+ connect: (url, headers) => new WebSocket(url, { headers }),
+ }, machineId, 'engines_probe', payload)
+ return { machineId, reply }
+}
+
+/** The probe's answer as one row per engine, read as #1743's consumer reads it (superTabs/machines.ts). */
+export function readinessRows(machineId: string, reply: Record<string, unknown>): EngineReadiness[] {
+ const engines = Array.isArray(reply.engines) ? reply.engines : []
+ return engines.flatMap((entry): EngineReadiness[] => {
+ if (!entry || typeof entry !== 'object') return []
+ const row = entry as Record<string, unknown>
+ if (typeof row.engine !== 'string') return []
+ const installed = row.installed === true ? true : null
+ return [{
+ machineId,
+ engine: row.engine,
+ installed,
+ signedIn: installed && typeof row.signedIn === 'boolean' ? row.signedIn : null,
+ installable: typeof row.installable === 'boolean' ? row.installable : null,
+ firstPrompt: typeof row.firstPrompt === 'boolean' ? row.firstPrompt : null,
+ }]
+ })
+}
+
+const yesNo = (value: boolean | null): string => value === null ? 'unknown' : value ? 'yes' : 'no'
+
+/** `harness machines engines <machine> [--engine E]… [--json]`: each engine's readiness on that machine, on request. */
+export async function runMachinesEngines(argv: string[], dataDir: string, port: number,
+ probe: MachineProbe = probeMachine(dataDir, port), out: (line: string) => void = console.log): Promise<number> {
+ const json = argv.includes('--json'), words: string[] = [], engines: string[] = []
+ let invalid = false
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ if (a === '--json') continue
+ if (a === '--engine') {
+ const engine = argv[++i]
+ if (!engine || !(ENGINES as readonly string[]).includes(engine)) invalid = true
+ else if (!engines.includes(engine)) engines.push(engine)
+ } else if (a.startsWith('--')) invalid = true
+ else words.push(a)
+ }
+ if (invalid || words.length !== 1) {
+ console.error(`${USAGE}\nEngines: ${ENGINES.join(', ')}.`)
+ return 2
+ }
+ let answer: { machineId: string; reply: Record<string, unknown> }
+ try {
+ answer = await probe(words[0], engines.length ? { engines } : {})
+ } catch (error) {
+ console.error((error as Error).message)
+ return 1
+ }
+ if (typeof answer.reply.error === 'string') {
+ console.error(`That machine could not check its engines (${answer.reply.error}).`)
+ return 1
+ }
+ const rows = readinessRows(answer.machineId, answer.reply)
+ if (json) {
+ for (const row of rows) out(JSON.stringify(row))
+ return 0
+ }
+ const width = Math.max(6, ...rows.map(row => row.engine.length))
+ out('')
+ out(` ${'ENGINE'.padEnd(width)} INSTALLED SIGNED IN FIRST PROMPT`)
+ for (const row of rows) {
+ out(` ${row.engine.padEnd(width)} ${yesNo(row.installed).padEnd(9)} ${yesNo(row.signedIn).padEnd(9)} ${yesNo(row.firstPrompt)}`)
+ }
+ out('')
+ return 0
+}
diff --git a/docs/cli.md b/docs/cli.md
index 8350386a0..64d505c0b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -18,6 +18,7 @@ works the same on a headless Linux server; the app is not required on a machine,
| `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. |
| `harness dsh list` · `harness dsh update <owner/name>` | Installed harness package versions and available updates · update one package while preserving its workspaces. |
| `harness machines [list] [--json]` · `harness machines delete <id>` | This account's machines · remove another machine (never this one). |
+| `harness machines engines <machine> [--engine E]… [--json]` | Asks that machine now, over the machine link, which engines it has (`engines_probe`, answered there): one JSON line per engine with `machineId`, `engine`, `installed` (`true` or `null`), `signedIn` (claude and codex only, else `null`), `installable` and `firstPrompt` (whether its Harness can start that engine with a first prompt; `null` from an older Harness). `null` means unknown, never "not there": the probe reads a missing command, a timed-out login shell and a failed spawn alike, so only a failed start says an engine is missing. `--engine` narrows the probe to the engines named, so the answer comes sooner. For a device that hands work to its person's machines (#1788). |
| `harness pair <code>` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. |
| `harness pair <verb> [--json]` · `harness pair talk <words…>` · `harness pair mcp` | Your paired daemon's control interface (below): read every harness on every machine; talk to the daemon. |
| `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. |