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 route picks the harness a program's words for the person belong to, or new work, and --send types them into an idle one

200d3301614b9e0dd112c9b04f96
diff --git a/cli/src/agentClient/commands.spec.ts b/cli/src/agentClient/commands.spec.ts
index 1d4477e48..f54caf57f 100644
--- a/cli/src/agentClient/commands.spec.ts
+++ b/cli/src/agentClient/commands.spec.ts
@@ -2,7 +2,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, DEPTH_REFUSAL, EXIT, parseDuration, psCommand, refusalNext, replyCommand, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, tellCommand, waitCommand, watchCommand, whoamiCommand, type ClientDeps } from './commands.js'
+import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, DEPTH_REFUSAL, EXIT, parseDuration, psCommand, refusalNext, replyCommand, routeCommand, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, tellCommand, waitCommand, watchCommand, whoamiCommand, type ClientDeps } from './commands.js'
import { RefusedError, type Rpc } from '../messages/rpc.js'
import { AgentClientError, type Daemon, type Where } from './daemon.js'
import { Ledger, ledgerPath } from './ledger.js'
@@ -2210,3 +2210,114 @@ describe('harness reply to a harness in a pane (a program acting for the person)
expect(JSON.parse(shown.out.join('\n'))).toMatchObject({ answer: 'Fixed: name added.' })
})
})
+
+describe('harness route (a program acting for the person picks the harness)', () => {
+ const replied = () => {
+ const calls: Array<[string, Record<string, unknown>]> = []
+ const record: Rpc = async (target, payload) => { calls.push([target.machineId, payload]); return { id: 'm0000001', state: 'queued' } }
+ return { calls, record }
+ }
+ // The lamp's lamp-tasks, asking about the office computer's harnesses.
+ const program = (d: FakeDaemon, office: FakeDaemon, over: Partial<ClientDeps> = {}) => {
+ const h = harness(d, { pane: undefined, others: { m2: office }, ...over })
+ h.deps.machines = async () => [{ machineId: 'm', label: 'studio', current: true }, { machineId: 'm2', label: 'office', current: false }] as never
+ return h
+ }
+ const decides = (d: FakeDaemon, answer: Record<string, unknown>) => {
+ const asked: Array<Record<string, unknown>> = []
+ d.extra.route_decide = (payload) => { asked.push(payload); return answer }
+ return asked
+ }
+
+ beforeEach(() => { setAgentSettingsForTest(dir, { programsReply: true }) })
+
+ it('shows this machine\'s router that machine\'s harnesses in a pane, and types the words into the one it picks', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week', { engine: 'devin' }), frame('skills', { engine: 'claude' }), frame('fo', { location: 'cloud' } as never), frame('old', { status: 'stopped' })]
+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9234, trace: '2 sessions · jev: "week" 92%' })
+ const r = replied()
+ const h = program(d, office, { record: r.record })
+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'how is the week log going?'], h.deps)).toBe(EXIT.ok)
+ expect(asked).toEqual([{ text: 'how is the week log going?', projects: [], agents: [], sessions: [
+ { id: 'week', name: 'week', asks: ['ask of week'], about: 'week recap' },
+ { id: 'skills', name: 'skills', asks: ['ask of skills'], about: 'skills recap' },
+ ] }])
+ // Decided by THIS machine's router, never the office's.
+ expect(office.requests.some((q) => q.type === 'route_decide')).toBe(false)
+ expect(r.calls).toEqual([['m2', { action: 'reply_local', machine: 'studio', agentId: 'week', text: 'how is the week log going?' }]])
+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ decided: 'session', id: 'week', name: 'week', machine: 'office', confidence: 0.923,
+ reason: '2 sessions · jev: "week" 92%', sent: { state: 'queued' }, next: [{ run: 'harness wait --machine office week' }] })
+ })
+
+ it('says new work and sends nothing, so the caller starts it', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week')]
+ decides(d, { decided: 'new', via: 'jev', reason: 'Jev: new work' })
+ const r = replied()
+ const h = program(d, office, { record: r.record })
+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'write a haiku'], h.deps)).toBe(EXIT.ok)
+ expect(JSON.parse(h.out.join('\n'))).toEqual({ decided: 'new', reason: 'Jev: new work' })
+ expect(r.calls).toEqual([])
+ })
+
+ it('tells the router where this computer\'s last words for that machine went, within ten minutes only', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week'), frame('skills')]
+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.95, trace: 't' })
+ const r = replied()
+ const h = program(d, office, { record: r.record })
+ expect(await routeCommand(['--machine', 'office', '--send', '--', 'read the week log'], h.deps)).toBe(EXIT.ok)
+ expect(asked[0].last).toBeUndefined()
+ h.advance(60_000)
+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)
+ expect(asked[1].last).toEqual({ id: 'week', agoMs: 60_000 })
+ // Another computer's words for the office (its line in this ledger cannot be: each computer keeps its own) and
+ // words for another machine never steer this one.
+ h.ledger.append({ at: NOW + 60_000, by: { machineId: 'm', agentId: 'person' }, told: { machineId: 'm3', agentId: 'skills' }, probe: 'x' })
+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)
+ expect(asked[2].last).toEqual({ id: 'week', agoMs: 60_000 })
+ h.advance(10 * 60_000)
+ expect(await routeCommand(['--machine', 'office', '--', 'and the other one?'], h.deps)).toBe(EXIT.ok)
+ expect(asked[3].last).toBeUndefined()
+ })
+
+ it('never sends to a harness still working: says NOT_IDLE, and to wait, not to start new work', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week', { activity: { state: 'working' } })]
+ decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9, trace: 't' })
+ const r = replied()
+ const h = program(d, office, { record: r.record })
+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'how is it going?'], h.deps)).toBe(EXIT.ok)
+ const said = JSON.parse(h.out.join('\n'))
+ expect(said).toMatchObject({ decided: 'session', id: 'week', sent: { error: 'NOT_IDLE' }, next: [{ run: 'harness wait --machine office week' }] })
+ expect(said.next[0].when).toMatch(/Never start new work/)
+ expect(r.calls).toEqual([])
+ expect(h.ledger.lastToldBy({ machineId: 'm', agentId: 'person' }, 'm2')).toBeNull()
+ })
+
+ it('is refused while the switch is off and for an agent, and asks the router nothing', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week')]
+ const asked = decides(d, { decided: 'session', id: 'week', via: 'jev', p: 0.9, trace: 't' })
+ setAgentSettingsForTest(dir, { programsReply: false })
+ let h = program(d, office)
+ expect(await routeCommand(['--machine', 'office', '--', 'x'], h.deps)).toBe(EXIT.refused)
+ expect(h.err.join('\n')).toContain('harness settings programs-reply on')
+ setAgentSettingsForTest(dir, { programsReply: true })
+ d.frames = [frame('lead', { engine: 'claude' })]
+ h = harness(d)
+ expect(await routeCommand(['--', 'x'], h.deps)).toBe(EXIT.refused)
+ expect(asked).toEqual([])
+ })
+
+ it('decides nothing when the router cannot: the caller acts on nothing', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('week')]
+ decides(d, { error: 'JEV_UNAVAILABLE', detail: "Harness's server did not answer in time" })
+ const r = replied()
+ const h = program(d, office, { record: r.record })
+ expect(await routeCommand(['--machine', 'office', '--send', '--json', '--', 'x'], h.deps)).toBe(EXIT.failed)
+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ error: 'ROUTER_UNAVAILABLE' })
+ expect(r.calls).toEqual([])
+ })
+})
diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.ts
index 5b8be34ba..46991a47d 100644
--- a/cli/src/agentClient/commands.ts
+++ b/cli/src/agentClient/commands.ts
@@ -71,6 +71,17 @@ To a harness in a pane, only when it is idle and the person allows it (harness s
typed into it once its composer is free. Then wait for it (harness wait <name>) and read its answer (harness show <name>).
The person's, or a program's acting for them; an agent does not answer for the person.
${ON_MACHINE}`
+export const ROUTE_USAGE = `Usage: harness route [--machine <name>] [--send] [--json] -- <words…>
+
+Says which of a machine's harnesses in a pane <words> belong to, as the person's ⌘B does: one of them, or new work.
+With --send, words for an idle one are typed into it, as harness reply does; nothing is ever started. For a program
+acting for the person, while they allow it (harness settings programs-reply).
+--json answers {"decided":"session","id","name","machine","confidence","reason"} or {"decided":"new","reason"},
+and with --send "sent": {"state":"queued"} or {"error":"NOT_IDLE"|"NOT_RUNNING",…}. NOT_IDLE: it is still working
+on the last words or waits for the person. Wait for it (harness wait <name>) and send them with harness reply, or
+say so: never start new work for them, or a follow-up ("how is it going?") becomes a second harness.
+Exit status: 0 once decided (sent or not: read "sent"), 5 refused (switch off), 1 nothing decided (ROUTER_UNAVAILABLE).
+${ON_MACHINE}`
export const TELL_USAGE = `Usage: harness tell [--machine <name>] <name> [--json] -- <work…>
Gives more work to a harness you started: typed into it once it is free, or given at its next tool call while it
@@ -540,6 +551,21 @@ export function formatRows(rows: Row[], now: number, on = 'this machine'): strin
return [head, ...lines].join('\n')
}
+/** What each live one of [rows] is about: the person's last asks and the summaries the daemon keeps (no transcript
+ * read), filled in place. `harness ps`'s, and what `harness route` shows the router. */
+async function describeRows(daemon: Daemon, rows: Row[]): Promise<void> {
+ await Promise.all(rows.filter((r) => r.state !== 'stopped').slice(0, ABOUT_MAX).map(async (row) => {
+ const recent = await daemon.request('agent_recent', { agentId: row.id, n: 3 }, 3_000).catch(() => null)
+ if (!recent || recent.error) return
+ const asks = (Array.isArray(recent.asks) ? recent.asks as unknown[] : []).filter((a): a is string => typeof a === 'string' && !!a.trim()).slice(0, 2)
+ const about = (Array.isArray(recent.events) ? recent.events as Array<Record<string, unknown>> : [])
+ .map((e) => (typeof e.recap === 'string' && e.recap ? e.recap : typeof e.text === 'string' ? e.text : '').replace(/\s+/g, ' ').trim())
+ .filter(Boolean).slice(0, 3).map((t) => clip(t, 140))
+ if (asks.length) row.asks = asks.map((a) => clip(asSaid(a).replace(/\s+/g, ' ').trim(), 200))
+ if (about.length) row.about = about.join(' / ')
+ }))
+}
+
export function psCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {
return run(PS_USAGE, deps, wantsJson, argv, async (s) => {
const { names, flags, machine } = words(argv, { '--all': 'flag', '--json': 'flag' })
@@ -555,17 +581,7 @@ export function psCommand(argv: readonly string[], deps: ClientDeps = {}): Promi
: { daemon: o.daemon, machineId: o.where.machineId, machine: o.machine }
const frames = line ? await list(line, all) : o.frames
const rows = rowsOf(frames, { machineId: on.machineId, machine: on.machine, caller: o.caller, ledger: o.ledger, now: s.now(), all })
- // What each is about: the summaries the daemon keeps (no transcript read), for the live ones.
- await Promise.all(rows.filter((r) => r.state !== 'stopped').slice(0, ABOUT_MAX).map(async (row) => {
- const recent = await on.daemon.request('agent_recent', { agentId: row.id, n: 3 }, 3_000).catch(() => null)
- if (!recent || recent.error) return
- const asks = (Array.isArray(recent.asks) ? recent.asks as unknown[] : []).filter((a): a is string => typeof a === 'string' && !!a.trim()).slice(0, 2)
- const about = (Array.isArray(recent.events) ? recent.events as Array<Record<string, unknown>> : [])
- .map((e) => (typeof e.recap === 'string' && e.recap ? e.recap : typeof e.text === 'string' ? e.text : '').replace(/\s+/g, ' ').trim())
- .filter(Boolean).slice(0, 3).map((t) => clip(t, 140))
- if (asks.length) row.asks = asks.map((a) => clip(asSaid(a).replace(/\s+/g, ' ').trim(), 200))
- if (about.length) row.about = about.join(' / ')
- }))
+ await describeRows(on.daemon, rows)
// Asked for and not started yet: listed by the name it was given, and what it waits for.
rows.unshift(...o.asked.filter((a) => !away || a.row.creation.machineId === away.machineId).map((a): Row => ({
name: askedName(a), id: a.row.creation.creationId, agent: engineName(a.row.creation.engine),
@@ -766,17 +782,7 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr
// A harness in a pane, for a program acting for the person (messages/replyLocal.ts): the machine it runs on
// checks the switch and that it is idle again, and queues the words in its mailbox.
if (!readAgentSettings(o.where.dataDir).programsReply) throw new AgentClientError('REPLY_OFF', REPLY_OFF_TEXT)
- const state = stateOf(t.frame)
- if (state === 'stopped' || state === 'offline') throw new AgentClientError('NOT_RUNNING', `${name} is no longer running: it was closed or stopped. Start a new harness with the whole task.`)
- if (state !== 'idle') throw new AgentClientError('NOT_IDLE', state === 'working' ? `${name} is working. Wait for it to finish (${step(s.env, 'wait', at)}), then reply.` : `${name} is not idle: it may be waiting for the person (a question or a permission). Only they answer that.`)
- let reply: Record<string, unknown>
- try { reply = await s.record({ port: o.where.port, dataDir: o.where.dataDir, machineId: t.machineId }, { action: 'reply_local', machine: o.machine, agentId: t.frame.id, text }, 20_000) } catch (error) {
- if (error instanceof MessageError) throw new AgentClientError(error.code, error.message)
- throw error
- }
- // As a tell's: `wait` and `show` then hold the answer to the work before until it has taken these words.
- try { o.ledger.append({ at: s.now(), by: { machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, told: { machineId: t.machineId, agentId: t.frame.id }, probe: flat(text).slice(0, PROBE_CHARS) }) }
- catch { /* `wait` then reads its last answer as it would without the line */ }
+ const reply = await replyInPane(s, o, t, text, at)
const failed = reply.state === 'failed'
const effect = failed ? `${name} did not take it: ${typeof reply.reason === 'string' ? reply.reason : 'its machine refused it'}.` : `${name} has it: typed once its composer is free.`
s.out(flags.has('--json') ? JSON.stringify({ ok: !failed, name, id: t.frame.id, message: reply.id ?? null, state: reply.state ?? 'queued', effect, next: failed ? [] : next })
@@ -791,6 +797,105 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr
})
}
+/** How long words sent from here still steer a follow-up that names nothing ("and the other one?") to where they went. */
+const ROUTE_LAST_MS = 10 * 60_000
+
+/**
+ * Where a program's words for the person go (docs/design/2026-10-09-auto-router.md): the machine's harnesses in a
+ * pane, as `ps` reads them, are shown to this machine's router (services/router.ts `route_decide`), which picks one or
+ * says new work. With `--send` the words go into the one picked, idle only, as `harness reply` types them; new work is
+ * the caller's to start (`harness new`). The same caller policy as `reply` (#1628): the person's switch, never an agent.
+ */
+export function routeCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {
+ return run(ROUTE_USAGE, deps, wantsJson, argv, async (s) => {
+ const dash = argv.indexOf('--')
+ const { names, flags, machine } = words(dash < 0 ? argv : argv.slice(0, dash), { '--json': 'flag', '--send': 'flag' })
+ const text = dash < 0 ? '' : argv.slice(dash + 1).join(' ').trim()
+ if (names.length) throw new UsageError('harness route takes no name: it picks one. Give the words after --.')
+ if (!text) throw new UsageError('Give the words after --: harness route -- <words>')
+ const away = await machineOf(s, s.where(), machine)
+ const o = await opened(s)
+ let line: Daemon | null = null
+ try {
+ if (o.caller || o.orphan) throw new AgentClientError('NOT_YOURS', 'Only the person, or a program acting for them, routes words to a harness. To give more work to one you started, use harness tell.')
+ if (!readAgentSettings(o.where.dataDir).programsReply) throw new AgentClientError('REPLY_OFF', REPLY_OFF_TEXT)
+ const on = away
+ ? { daemon: line = await s.open(o.where, away.machineId), machineId: away.machineId, machine: away.label }
+ : { daemon: o.daemon, machineId: o.where.machineId, machine: o.machine }
+ // Harnesses in a pane only: a cloud one is answered with `harness reply`, through its maker.
+ const frames = (line ? await list(line, false) : o.frames).filter((f) => isAgent(f) && f.location !== 'cloud')
+ const rows = rowsOf(frames, { machineId: on.machineId, machine: on.machine, caller: o.caller, ledger: o.ledger, now: s.now(), all: false })
+ .filter((r) => r.state !== 'stopped')
+ await describeRows(on.daemon, rows)
+ // Where this computer's last words for that machine went, within ROUTE_LAST_MS. This computer's ledger, so one
+ // lamp's follow-up is never steered by another's.
+ const told = o.ledger.lastToldBy({ machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, on.machineId)
+ const last = told && s.now() - told.at <= ROUTE_LAST_MS && rows.some((r) => r.id === told.told.agentId)
+ ? { id: told.told.agentId, agoMs: s.now() - told.at } : undefined
+ const sessions = rows.map((r) => ({ id: r.id, name: r.name, asks: r.asks ?? [], ...(r.about ? { about: r.about } : {}) }))
+ // Asked of THIS machine's router, as the owner over its own socket: the list is the caller's, so a harness on
+ // another computer is routed to as well as one here.
+ const verdict = await o.daemon.request('route_decide', { text, sessions, projects: [], agents: [], ...(last ? { last } : {}) }, 15_000)
+ if (typeof verdict.error === 'string') {
+ throw new AgentClientError('ROUTER_UNAVAILABLE', `Nothing was decided (${verdict.error}${typeof verdict.detail === 'string' ? `: ${verdict.detail}` : ''}). Act on nothing, or ask the person.`)
+ }
+ const row = verdict.decided === 'session' ? rows.find((r) => r.id === verdict.id) : undefined
+ if (!row) {
+ const reason = typeof verdict.reason === 'string' ? verdict.reason : 'new work'
+ s.out(flags.has('--json') ? JSON.stringify({ decided: 'new', reason }) : `New work: ${reason}. Start it with harness new.`)
+ return EXIT.ok
+ }
+ const decided = { decided: 'session', id: row.id, name: row.name, machine: on.machine,
+ confidence: typeof verdict.p === 'number' ? Math.round(verdict.p * 1000) / 1000 : null,
+ reason: typeof verdict.trace === 'string' ? verdict.trace : null }
+ if (!flags.has('--send')) {
+ s.out(flags.has('--json') ? JSON.stringify(decided) : `${row.name} on ${on.machine}${decided.confidence !== null ? ` (${Math.round(decided.confidence * 100)}%)` : ''}`)
+ return EXIT.ok
+ }
+ const frame = frames.find((f) => f.id === row.id)!
+ const at = onAway(addressOf({ machineId: '', agentId: row.id, name: row.name, engine: '' }), away)
+ let sent: Record<string, unknown>
+ try {
+ const reply = await replyInPane(s, o, { daemon: on.daemon, frame, machineId: on.machineId, machine: on.machine, yours: false, remote: !!line }, text, at)
+ sent = reply.state === 'failed'
+ ? { error: 'FAILED', detail: typeof reply.reason === 'string' ? reply.reason : 'its machine refused it' }
+ : { state: typeof reply.state === 'string' ? reply.state : 'queued', message: reply.id ?? null }
+ } catch (error) {
+ if (!(error instanceof AgentClientError) || !['NOT_IDLE', 'NOT_RUNNING'].includes(error.code)) throw error
+ sent = { error: error.code, detail: error.message }
+ }
+ const next: NextStep[] = sent.error === 'NOT_IDLE'
+ ? [{ run: step(s.env, 'wait', at), when: 'it is still on the last words: then send these with harness reply. Never start new work for them' }]
+ : sent.error ? [] : [{ run: step(s.env, 'wait', at), when: 'for its answer' }]
+ s.out(flags.has('--json') ? JSON.stringify({ ...decided, sent, next })
+ : [`${row.name} on ${on.machine}: ${sent.error ? `not sent (${sent.detail})` : 'has it: typed once its composer is free.'}`, formatNext(next)].filter(Boolean).join('\n'))
+ return EXIT.ok
+ } finally { line?.close(); o.daemon.close() }
+ })
+}
+
+/**
+ * [text] typed into [t], a harness in a pane, for the person (messages/replyLocal.ts): only while it is idle. The
+ * machine it runs on checks the switch and that it is idle again, and queues the words in its mailbox; its answer is
+ * returned. `harness reply`'s and `harness route --send`'s, which check the person's switch first.
+ */
+async function replyInPane(s: Setup, o: Opened, t: Target, text: string, at: string): Promise<Record<string, unknown>> {
+ const name = t.frame.name ?? t.frame.id.slice(0, 8)
+ const state = stateOf(t.frame)
+ if (state === 'stopped' || state === 'offline') throw new AgentClientError('NOT_RUNNING', `${name} is no longer running: it was closed or stopped. Start a new harness with the whole task.`)
+ if (state !== 'idle') throw new AgentClientError('NOT_IDLE', state === 'working' ? `${name} is working. Wait for it to finish (${step(s.env, 'wait', at)}), then reply.` : `${name} is not idle: it may be waiting for the person (a question or a permission). Only they answer that.`)
+ let reply: Record<string, unknown>
+ try { reply = await s.record({ port: o.where.port, dataDir: o.where.dataDir, machineId: t.machineId }, { action: 'reply_local', machine: o.machine, agentId: t.frame.id, text }, 20_000) } catch (error) {
+ if (error instanceof MessageError) throw new AgentClientError(error.code, error.message)
+ throw error
+ }
+ // As a tell's: `wait` and `show` then hold the answer to the work before until it has taken these words, and the
+ // next `harness route` from here takes it for where the last words went (`Ledger.lastToldBy`).
+ try { o.ledger.append({ at: s.now(), by: { machineId: o.where.machineId, agentId: PERSON_AGENT_ID }, told: { machineId: t.machineId, agentId: t.frame.id }, probe: flat(text).slice(0, PROBE_CHARS) }) }
+ catch { /* `wait` then reads its last answer as it would without the line */ }
+ return reply
+}
+
// ── tell ───────────────────────────────────────────────────────────────────────────────────────────
/**
diff --git a/cli/src/agentClient/ledger.ts b/cli/src/agentClient/ledger.ts
index 79ae2d538..972658061 100644
--- a/cli/src/agentClient/ledger.ts
+++ b/cli/src/agentClient/ledger.ts
@@ -190,6 +190,12 @@ export class Ledger {
return this.read().told.findLast((row) => same(row.by, by) && same(row.told, m)) ?? null
}
+ /** The last words [by] gave any harness on [machineId] (`harness reply`, `harness route --send`), or null. This
+ * machine's ledger holds only its own callers' lines, so another computer's follow-up never steers this one's. */
+ lastToldBy(by: LedgerMember, machineId: string): Told | null {
+ return this.read().told.findLast((row) => same(row.by, by) && row.told.machineId === machineId) ?? null
+ }
+
/** 0 for a harness the person started. */
depthOf(m: LedgerMember): number {
return this.parentOf(m)?.depth ?? 0
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 8bc2d1bee..b4da69c2f 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -175,7 +175,8 @@ Machine:
harness close <name> [--now] save a harness's screen and stop it; an agent closes only what it started
harness tell <name> -- <w> from an agent's pane: more work for a harness it started (agents-tell-agents)
harness reply <name> -- <w> say words to a cloud harness (Devin Cloud, Cursor Cloud, Fo): its answer or what next
- new, ps, show, wait, watch, tell, reply and close take --machine <name> for another of your
+ harness route [--send] -- <w> which harness words belong to, or new work; --send types them into an idle one (programs-reply)
+ new, ps, show, wait, watch, tell, reply, route and close take --machine <name> for another of your
machines: \`harness show --machine office x\`
harness mcp the agent verbs as an MCP server on stdin/stdout, for agents that use MCP
harness help agents the agent commands, states, exit codes and rules on one screen
@@ -2713,7 +2714,7 @@ async function logsExportCommand(json: boolean): Promise<void> {
import { orchestratorCommand } from './orchestrator/command.js'
import { paneOwner, sendCommand, sendPane } from './messages/command.js'
-import { agentOrigin, closeCommand, psCommand, replyCommand, showCommand, tellCommand, waitCommand, watchCommand, whoamiCommand } from './agentClient/commands.js'
+import { agentOrigin, closeCommand, psCommand, replyCommand, routeCommand, showCommand, tellCommand, waitCommand, watchCommand, whoamiCommand } from './agentClient/commands.js'
import { agentsHelp, helpFor } from './agentClient/help.js'
import { openUrlCommand } from './agentClient/openUrl.js'
import { harnessRunner, mcpCommand } from './agentClient/mcp.js'
@@ -2807,6 +2808,9 @@ switch (cmd) {
case 'reply':
replyCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)
break
+ case 'route':
+ routeCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)
+ break
case 'tell':
unlessBuddy(() => tellCommand(rest, { machines: usableMachines })).then(code => { process.exitCode = code }).catch(onError)
break
diff --git a/cli/src/services/router.spec.ts b/cli/src/services/router.spec.ts
index 07ea92924..700672bbc 100644
--- a/cli/src/services/router.spec.ts
+++ b/cli/src/services/router.spec.ts
@@ -154,7 +154,7 @@ describe('the router', () => {
const jev = vi.fn(async () => ({ target: said('s0', 0.8, ['s0', 's1', 'new']) }))
const { router: made, lines } = router({ jev })
expect(await startRouter(fakeCore(), made).route_decide!({ text: 'refund it', sessions: DESK }, OWNER))
- .toEqual({ decided: 'session', id: 'a1', via: 'jev' })
+ .toEqual({ decided: 'session', id: 'a1', via: 'jev', p: 0.8, trace: '2 sessions · jev: "billing retries" 0.80, then "Prometheus alerts" 0.10' })
expect(lines).toEqual(['session — 2 sessions · jev: "billing retries" 0.80, then "Prometheus alerts" 0.10'])
// Jev was asked the task as the client sent it, trimmed.
expect(jev).toHaveBeenCalledWith({ message: 'refund it' }, expect.objectContaining({ target: expect.any(Object) }), undefined)
diff --git a/cli/src/services/router.ts b/cli/src/services/router.ts
index eaa45bb04..136490829 100644
--- a/cli/src/services/router.ts
+++ b/cli/src/services/router.ts
@@ -98,7 +98,8 @@ export function startRouter(core: CoreApi, router: Router = defaultRouter(core))
router.log?.(`${verdict.kind === 'session' ? 'session' : verdict.kind === 'new' ? `new (${verdict.why})` : `nothing decided (${verdict.why})`} — ${verdict.trace}`)
if (verdict.kind === 'unavailable') return { error: 'JEV_UNAVAILABLE', detail: verdict.why }
return verdict.kind === 'session'
- ? { decided: 'session', id: verdict.id, via: 'jev' }
+ // `p` and `trace` for a caller that shows or logs why (`harness route`): names and odds only, never the words.
+ ? { decided: 'session', id: verdict.id, via: 'jev', p: verdict.p, trace: verdict.trace }
: { decided: 'new', via: verdict.via, reason: verdict.why, ...(verdict.project ? { project: verdict.project } : {}), ...(verdict.agent ? { agent: verdict.agent } : {}) }
} finally { pending.delete(request) }
},
diff --git a/docs/cli.md b/docs/cli.md
index 9ccc7d3c3..9dccf0942 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -128,6 +128,29 @@ in once its composer is free, never over a draft, with `tell`'s limits. Then `ha
after a start: `wait` does not return on the answer to the work before. An agent uses `harness tell` instead, for a
harness it started.
+`harness route [--machine <name>] [--send] [--json] -- <words>` is the person's ⌘B for such a program (a lamp that
+heard a request): which of a machine's harnesses in a pane the words belong to, or new work. It reads that machine's
+harnesses as `ps` does (name, the person's last asks, what each is about) and asks this machine's router
+(`services/router.ts`, Jev; the [design](design/2026-10-09-auto-router.md)), so no device need be paired and
+nothing is asked of the backend beyond Jev's own route. `--json` answers `{"decided":"session", "id", "name",
+"machine", "confidence", "reason"}` (Jev's odds and its trace: names and odds, never the words) or
+`{"decided":"new", "reason"}`; new work is the caller's to start with `harness new`. When the router cannot be asked
+it answers `ROUTER_UNAVAILABLE` (exit 1): nothing was decided, and the caller acts on nothing.
+
+- **`--send`** types the words into the harness picked exactly as `harness reply` does: idle only, through its
+ machine's mailbox. The answer adds `"sent": {"state": "queued"}`, or `{"error": "NOT_IDLE" | "NOT_RUNNING"}` with
+ nothing sent. Exit 0 once decided, sent or not: read `sent`.
+- **`NOT_IDLE`** means it is still on the last words, or waits for the person. Wait for it (`harness wait`, the
+ answer's `next`) and send them with `harness reply`, or say so. Never start new work for them: a follow-up ("how is
+ it going?") would become a second harness.
+- **A follow-up that names nothing** ("and the other one?") goes where this computer's last words for that machine
+ went within ten minutes: the `Told` line `reply` and `route --send` write in this computer's own ledger
+ (`Ledger.lastToldBy`). Each computer keeps its own, so one lamp's follow-up never steers another's.
+- **The caller policy is `reply`'s:** the person's `programs-reply` switch for the whole command, deciding included
+ (exit 5 while it is off), and never an agent in a pane (`NOT_YOURS`).
+- **Cost and time:** one decision is about $0.00017 and 0.4 to 0.7 s on Harness's key (bounded at 8 s), capped per
+ account at 30 a minute and 1,000 a day.
+
`harness watch <name>` follows one harness for a program that acts on it: a line each time it changes, one JSON
object a line with `--json`, until it stops or is gone (exit 4) or `--timeout` passes (exit 124; `0`, the default,
follows it as long as it lives). It decides as `wait` does: the maker's state for a cloud harness; the daemon's