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 reply gives more work to an idle harness in a pane, for a program acting for the person, behind programs-reply (#1628)

08e0bd214787d487ba151fefe6f7
diff --git a/cli/src/agentClient/commands.spec.ts b/cli/src/agentClient/commands.spec.ts
index 65bf250e4..1d4477e48 100644
--- a/cli/src/agentClient/commands.spec.ts
+++ b/cli/src/agentClient/commands.spec.ts
@@ -1732,7 +1732,8 @@ describe('a cloud harness (#1444)', () => {
expect(await replyCommand(['devin', '--', 'the', 'release', 'branch'], h.deps)).toBe(EXIT.ok)
expect(sent).toEqual([{ agentId: 'devin', text: 'the release branch' }])
expect(h.out.join('\n')).toMatch(/^Sent to devin\.\nNext: harness wait devin/)
- expect(await replyCommand(['kid', '--', 'x'], harness(d).deps)).toBe(EXIT.usage)
+ // A harness in a pane takes a program's words only while the person allows it (below, `harness reply` to a pane).
+ expect(await replyCommand(['kid', '--', 'x'], harness(d).deps)).toBe(EXIT.refused)
expect(await replyCommand(['devin'], harness(d).deps)).toBe(EXIT.usage)
d.extra.cloud_send = () => ({ error: 'CLOUD_FAILED', detail: 'Devin Cloud is still working.' })
const busy = harness(d)
@@ -2120,3 +2121,92 @@ describe('harness watch', () => {
}
})
})
+
+describe('harness reply to a harness in a pane (a program acting for the person)', () => {
+ const replied = (over: { state?: string; error?: [string, string] } = {}) => {
+ const calls: Array<[string, Record<string, unknown>]> = []
+ const record: Rpc = async (target, payload) => {
+ calls.push([target.machineId, payload])
+ if (over.error) throw new RefusedError(over.error[0], over.error[1])
+ return { id: 'm0000001', state: over.state ?? 'queued' }
+ }
+ return { calls, record }
+ }
+ const answeredWith = (d: FakeDaemon, id: string, ask: string, answer: string) =>
+ d.pages.set(`s-${id}`, [{ events: [ev('user_message', { content: ask }), ev('text_delta', { content: answer }), ev('done')], hasMore: false }])
+ // The lamp's lamp-tasks: no pane, no agent in its shell.
+ const program = (d: FakeDaemon, over: Partial<ClientDeps> & { others?: Record<string, FakeDaemon> } = {}) => harness(d, { pane: undefined, ...over })
+
+ beforeEach(() => { setAgentSettingsForTest(dir, { programsReply: true }) })
+
+ it('gives an idle harness the person\'s words through its machine, and records them for wait', async () => {
+ const d = new FakeDaemon(), office = new FakeDaemon('m2')
+ office.frames = [frame('lamp-skill', { engine: 'claude' })]
+ const r = replied()
+ const h = program(d, { record: r.record, others: { m2: office } })
+ h.deps.machines = async () => [{ machineId: 'm', label: 'studio', current: true }, { machineId: 'm2', label: 'office', current: false }] as never
+ expect(await replyCommand(['--machine', 'office', 'lamp-skill', '--json', '--', 'The lamp\'s check refused skill.toml: name is missing.'], h.deps)).toBe(EXIT.ok)
+ expect(r.calls).toEqual([['m2', { action: 'reply_local', machine: 'studio', agentId: 'lamp-skill', text: 'The lamp\'s check refused skill.toml: name is missing.' }]])
+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ ok: true, name: 'lamp-skill', state: 'queued', next: [{ run: 'harness wait --machine office lamp-skill' }] })
+ expect(h.ledger.toldBy({ machineId: 'm', agentId: 'person' }, { machineId: 'm2', agentId: 'lamp-skill' })).toMatchObject({ probe: 'The lamp\'s check refused skill.toml: name is missing.' })
+ })
+
+ it('is refused, never asked of a machine, while the switch is off, and for one that works, waits or is gone', async () => {
+ const d = new FakeDaemon()
+ d.frames = [frame('kid'), frame('busy', { activity: { state: 'working' } }), frame('asks', { activity: undefined }), frame('done', { status: 'stopped' })]
+ const r = replied()
+ setAgentSettingsForTest(dir, { programsReply: false })
+ let h = program(d, { record: r.record })
+ expect(await replyCommand(['kid', '--', 'x'], h.deps)).toBe(EXIT.refused)
+ expect(h.err.join('\n')).toContain('harness settings programs-reply on')
+ setAgentSettingsForTest(dir, { programsReply: true })
+ h = program(d, { record: r.record })
+ expect(await replyCommand(['busy', '--', 'x'], h.deps)).toBe(EXIT.failed)
+ expect(h.err.join('\n')).toMatch(/busy is working\. Wait for it to finish \(harness wait busy\)/)
+ h = program(d, { record: r.record })
+ expect(await replyCommand(['asks', '--', 'x'], h.deps)).toBe(EXIT.failed)
+ expect(h.err.join('\n')).toMatch(/waiting for the person.*Only they answer that/)
+ h = program(d, { record: r.record })
+ expect(await replyCommand(['done', '--', 'x'], h.deps)).not.toBe(EXIT.ok)
+ expect(r.calls).toEqual([])
+ })
+
+ it('refuses an agent: it tells the harnesses it started (harness tell), and only those', async () => {
+ const d = new FakeDaemon()
+ d.frames = [frame('lead', { engine: 'claude' }), frame('kid')]
+ const r = replied()
+ const inPane = harness(d, { record: r.record })
+ expect(await replyCommand(['kid', '--', 'x'], inPane.deps)).toBe(EXIT.refused)
+ expect(inPane.err.join('\n')).toMatch(/harness tell/)
+ const outside = program(d, { record: r.record, env: { CLAUDECODE: '1' } })
+ expect(await replyCommand(['kid', '--', 'x'], outside.deps)).toBe(EXIT.refused)
+ expect(r.calls).toEqual([])
+ })
+
+ it('says the machine\'s refusal as it said it, and records nothing', async () => {
+ const d = new FakeDaemon()
+ d.frames = [frame('kid')]
+ // Its machine reads the switch as off: the account's experiment had not reached it yet.
+ const r = replied({ error: ['REPLY_OFF', 'Programs may not give more work to your harnesses yet.'] })
+ const h = program(d, { record: r.record })
+ expect(await replyCommand(['kid', '--', 'x'], h.deps)).toBe(EXIT.refused)
+ expect(h.err.join('\n')).toContain('Programs may not give more work')
+ expect(h.ledger.toldBy({ machineId: 'm', agentId: 'person' }, { machineId: 'm', agentId: 'kid' })).toBeNull()
+ })
+
+ it('wait holds the answer to the work before until the harness takes the words', async () => {
+ const d = new FakeDaemon()
+ d.frames = [frame('kid', { engine: 'claude' })]
+ answeredWith(d, 'kid', 'Make a timer skill.', 'Done: skill.toml written.')
+ const r = replied()
+ const h = program(d, { record: r.record })
+ expect(await replyCommand(['kid', '--', 'The lamp\'s check refused it: name is missing.'], h.deps)).toBe(EXIT.ok)
+ expect(await waitCommand(['kid', '--timeout', '10s'], program(d).deps)).toBe(EXIT.timeout)
+ // Typed as the person's words, no header: a turn asked with them.
+ answeredWith(d, 'kid', 'The lamp\'s check refused it: name is missing.', 'Fixed: name added.')
+ expect(await waitCommand(['kid', '--timeout', '10s'], program(d).deps)).toBe(EXIT.ok)
+ const shown = program(d)
+ expect(await showCommand(['kid', '--json'], shown.deps)).toBe(EXIT.ok)
+ expect(JSON.parse(shown.out.join('\n'))).toMatchObject({ answer: 'Fixed: name added.' })
+ })
+})
diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.ts
index 732944002..5b8be34ba 100644
--- a/cli/src/agentClient/commands.ts
+++ b/cli/src/agentClient/commands.ts
@@ -29,6 +29,7 @@ import { formatNext, type NextStep } from './next.js'
import { AgentClientError, openDaemon, whereFor, type Daemon, type Where } from './daemon.js'
import { Ledger, ledgerPath, type Pending, type Started, type Told } from './ledger.js'
import { messagesRpc, type Rpc } from '../messages/rpc.js'
+import { PERSON_AGENT_ID, REPLY_OFF_TEXT } from '../messages/replyLocal.js'
import { TELL_OFF_TEXT } from '../messages/tell.js'
import { sendPane } from '../messages/command.js'
import { asSaid, callerOf, clip, cloudMeta, cloudTurn, forAgent, isAgent, lastTurn, matching, outsideCaller, rowsOf, stateOf, STOPPED_WITHIN_MS, type Caller, type CloudMeta, type Frame, type HistoryEvent, type Row, type State } from './model.js'
@@ -66,6 +67,8 @@ ${ON_MACHINE}`
export const REPLY_USAGE = `Usage: harness reply [--machine <name>] <name> [--json] -- <words…>
Says <words> to a cloud harness (Devin Cloud, Cursor Cloud, Fo): its answer to the question it asked, or what to do next.
+To a harness in a pane, only when it is idle and the person allows it (harness settings programs-reply): more work,
+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 TELL_USAGE = `Usage: harness tell [--machine <name>] <name> [--json] -- <work…>
@@ -105,8 +108,9 @@ and, if not, who can change that; how many of yours are open, and how many start
export const EXIT = { ok: 0, failed: 1, usage: 2, needsInput: 3, stopped: 4, refused: 5, timeout: 124 } as const
/** Not a failure: the caller may not do this. It should not retry; it tells the person or does the work itself.
- * `TELL_OFF` and `NOT_RUNNING` are `harness tell`'s: retried, they are refused the same. */
-export const REFUSED_CODES: ReadonlySet<string> = new Set(['SPAWN_LIMIT', 'TURNED_OFF', 'NOT_YOURS', 'TELL_OFF', 'NOT_RUNNING'])
+ * `TELL_OFF` and `NOT_RUNNING` are `harness tell`'s, `REPLY_OFF` is `harness reply`'s: retried, they are refused the
+ * same. `NOT_IDLE` is not among them: once the harness has finished, the reply is taken. */
+export const REFUSED_CODES: ReadonlySet<string> = new Set(['SPAWN_LIMIT', 'TURNED_OFF', 'NOT_YOURS', 'TELL_OFF', 'NOT_RUNNING', 'REPLY_OFF'])
/** What a refused caller may do instead: close one of its own when it is at its limit; otherwise the message says. */
export function refusalNext(env: NodeJS.ProcessEnv, error: AgentClientError): NextStep[] {
@@ -735,6 +739,11 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pro
})
}
+/** How much of the words a `Told` line keeps to know the turn they asked (ledger.ts `Told`). */
+const PROBE_CHARS = 80
+/** The words as a turn's ask holds them, to compare: spaces as one, since a pane may wrap or trim them. */
+const flat = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
// ── reply ──────────────────────────────────────────────────────────────────────────────────────────
export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {
@@ -748,15 +757,34 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr
const o = await opened(s)
let t: Target | null = null
try {
- if (o.caller || o.orphan) throw new AgentClientError('NOT_YOURS', 'Only the person replies to a cloud harness: tell them what it asked.')
+ if (o.caller || o.orphan) throw new AgentClientError('NOT_YOURS', 'Only the person replies to a harness: tell them what it asked. To give more work to one you started, use harness tell.')
t = await target(s, o, names[0], away)
const name = t.frame.name ?? t.frame.id.slice(0, 8)
- // A terminal agent is typed to in its pane; nothing here sends it words.
- if (t.frame.location !== 'cloud') throw new UsageError(`${name} is not a cloud harness: open it in Harness to talk to it.`)
- const reply = await t.daemon.request('cloud_send', { agentId: t.frame.id, text }, 3 * 60_000)
- if (typeof reply.error === 'string') throw new AgentClientError(reply.error, typeof reply.detail === 'string' && reply.detail ? reply.detail : `${name} did not take it (${reply.error}).`)
const at = onAway(addressOf({ machineId: '', agentId: t.frame.id, name: t.frame.name ?? '', engine: '' }), away)
const next: NextStep[] = [{ run: step(s.env, 'wait', at), when: 'for its answer' }]
+ if (t.frame.location !== 'cloud') {
+ // 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 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 })
+ : [`${name} on ${t.machine}: ${effect}`, failed ? null : formatNext(next)].filter(Boolean).join('\n'))
+ return failed ? EXIT.failed : EXIT.ok
+ }
+ const reply = await t.daemon.request('cloud_send', { agentId: t.frame.id, text }, 3 * 60_000)
+ if (typeof reply.error === 'string') throw new AgentClientError(reply.error, typeof reply.detail === 'string' && reply.detail ? reply.detail : `${name} did not take it (${reply.error}).`)
s.out(flags.has('--json') ? JSON.stringify({ ok: true, name, id: t.frame.id, next }) : `Sent to ${name}.\n${formatNext(next)}`)
return EXIT.ok
} finally { if (t?.remote) t.daemon.close(); o.daemon.close() }
@@ -765,11 +793,6 @@ export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Pr
// ── tell ───────────────────────────────────────────────────────────────────────────────────────────
-/** How much of the words a `Told` line keeps to know the turn they asked (ledger.ts `Told`). */
-const PROBE_CHARS = 80
-/** The words as a turn's ask holds them, to compare: spaces as one, since a pane may wrap or trim them. */
-const flat = (text: string): string => text.replace(/\s+/g, ' ').trim()
-
/**
* More work for a harness the caller started (messages/tell.ts): asked of the machine it runs on, which checks its own
* record of who started it and queues the words in its mailbox. Recorded here (`Told`), so `wait` does not take the
@@ -836,7 +859,9 @@ const TOLD_HOLD_MS = 10 * 60_000
* then its last answer is to the work before: the answer a `wait` returned at once, and wrongly, after a tell.
*/
function toldPending(o: Opened, t: Target, turn: { ask?: string | null } | null, now: number): Told | null {
- const told = o.caller ? o.ledger.toldBy(o.caller, { machineId: t.machineId, agentId: t.frame.id }) : null
+ // No caller is the person, or a program acting for them: their replies are recorded as the person's (`harness reply`).
+ const by = o.caller ?? (o.orphan ? null : { machineId: o.where.machineId, agentId: PERSON_AGENT_ID })
+ const told = by ? o.ledger.toldBy(by, { machineId: t.machineId, agentId: t.frame.id }) : null
if (!told || now - told.at > TOLD_HOLD_MS) return null
if (turn?.ask && flat(turn.ask).includes(told.probe)) return null
// Another machine's clock: a minute either way says nothing, and the turn's words still do.
diff --git a/cli/src/agentClient/settings.spec.ts b/cli/src/agentClient/settings.spec.ts
index bbca76759..707c55a29 100644
--- a/cli/src/agentClient/settings.spec.ts
+++ b/cli/src/agentClient/settings.spec.ts
@@ -32,6 +32,7 @@ describe('harness settings', () => {
'pull-request-line off a harness another agent starts says so in the pull requests it opens',
'agent-messages off agents in the same tab may message each other',
'agent-messages-hide-summary off the one-line summary of what a harness does is kept from a shared tab\'s other accounts',
+ 'programs-reply off a program acting for you may give more work to an idle harness of yours',
].join('\n')])
expect(d.asked).toEqual([{ url: 'http://127.0.0.1:4321/api/agent-settings', method: 'GET', headers: { 'x-adapter-local': '1' }, body: undefined }])
expect(SETTINGS_USAGE).toContain('experiments of your account, the same on each of its\ncomputers, and each off until you turn it on')
diff --git a/cli/src/agentClient/settings.ts b/cli/src/agentClient/settings.ts
index 81e4abc31..84f4e940b 100644
--- a/cli/src/agentClient/settings.ts
+++ b/cli/src/agentClient/settings.ts
@@ -38,6 +38,8 @@ computers, and each off until you turn it on:
agent-messages-hide-summary
keep the one-line summary of what a harness does from a shared tab's other accounts
(on hides it; it is shared while this is off)
+ programs-reply a program acting for you (not an agent) may give more work to an idle harness of yours in a
+ pane (harness reply), as you could by typing to it
An agent turns one on only for the person: it asks them first, with its tool for asking them (Claude Code:
AskUserQuestion; Codex: request_user_input) or in its reply, and adds ${PERSON_SAID_YES} once they said yes.
@@ -49,6 +51,7 @@ const ABOUT: Record<keyof AgentSettings, string> = {
pullRequestLine: 'a harness another agent starts says so in the pull requests it opens',
agentMessages: 'agents in the same tab may message each other',
agentMessagesHideSummary: 'the one-line summary of what a harness does is kept from a shared tab\'s other accounts',
+ programsReply: 'a program acting for you may give more work to an idle harness of yours',
}
export const SETTINGS_SIGNED_OUT = 'Signed out: these are experiments of your account. Sign in (harness login) to turn them on.'
diff --git a/cli/src/core/experiments.spec.ts b/cli/src/core/experiments.spec.ts
index 27bac55f9..b693ac607 100644
--- a/cli/src/core/experiments.spec.ts
+++ b/cli/src/core/experiments.spec.ts
@@ -124,7 +124,7 @@ describe('the account\'s agent experiments, kept for this computer', () => {
})
afterEach(() => { vi.useRealTimers(); rmSync(dataDir, { recursive: true, force: true }) })
- const OFF = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false }
+ const OFF = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false, programsReply: false }
/** The account's answer, as backend routes/experimentalSettings.ts gives it. */
const account = (features: Record<string, boolean>, accountId = 'acct') =>
({ status: 200, body: { success: true, data: { accountId, revision: 1, features: { share_button: false, ...features }, available: {} } } })
diff --git a/cli/src/core/experiments.ts b/cli/src/core/experiments.ts
index 9359c964a..a90e5ed87 100644
--- a/cli/src/core/experiments.ts
+++ b/cli/src/core/experiments.ts
@@ -168,7 +168,7 @@ export function createAgentSettingsSync(deps: {
const changes = body && typeof body === 'object'
? Object.entries(body as Record<string, unknown>).filter(([key, value]) => key in AGENT_SETTING_EXPERIMENTS && typeof value === 'boolean')
: []
- if (!changes.length) return { status: 400, body: { error: { code: 'BAD_REQUEST', message: 'Nothing to change: send {"agentsStartAgents": true|false}, {"pullRequestLine": true|false}, {"agentMessages": true|false}, {"agentMessagesHideSummary": true|false} or {"agentsTellAgents": true|false}.' } } }
+ if (!changes.length) return { status: 400, body: { error: { code: 'BAD_REQUEST', message: 'Nothing to change: send {"agentsStartAgents": true|false}, {"pullRequestLine": true|false}, {"agentMessages": true|false}, {"agentMessagesHideSummary": true|false}, {"agentsTellAgents": true|false} or {"programsReply": true|false}.' } } }
const asked = deps.session()
if (!asked?.machineId) return { status: 409, body: { error: { code: 'SIGNED_OUT', message: AGENT_SETTINGS_SIGNED_OUT } } }
const read = heard(await deps.backend('GET', EXPERIMENTAL_SETTINGS), asked)
diff --git a/cli/src/lib/agentSettings.spec.ts b/cli/src/lib/agentSettings.spec.ts
index 643c0bded..f82345f70 100644
--- a/cli/src/lib/agentSettings.spec.ts
+++ b/cli/src/lib/agentSettings.spec.ts
@@ -9,7 +9,7 @@ let dir: string
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'agent-settings-')) })
afterEach(() => { rmSync(dir, { recursive: true, force: true }); clearAuthSession() })
-const OFF = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false }
+const OFF = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false, programsReply: false }
const session = (over: Partial<AuthSession> = {}): AuthSession =>
({ version: 1, accessToken: 't', autonomousEnv: 'prod', computerId: 'c', machineId: 'm1', updatedAt: 0, ...over })
const owner = { accountId: 'acct', machineId: 'm1' }
@@ -19,8 +19,8 @@ describe('what the person lets agents do', () => {
// Off for all: none had been announced (owner, 2026-10-12).
expect(readAgentSettings(dir, session())).toEqual(OFF)
expect(readAgentSettings(dir, null)).toEqual(OFF)
- expect(AGENT_SETTING_NAMES).toEqual({ 'agents-start-agents': 'agentsStartAgents', 'agents-tell-agents': 'agentsTellAgents', 'pull-request-line': 'pullRequestLine', 'agent-messages': 'agentMessages', 'agent-messages-hide-summary': 'agentMessagesHideSummary' })
- expect(AGENT_SETTING_EXPERIMENTS).toEqual({ agentsStartAgents: 'agents_start_agents', pullRequestLine: 'agent_pull_request_line', agentMessages: 'agent_messages', agentMessagesHideSummary: 'agent_messages_hide_summary', agentsTellAgents: 'agents_tell_agents' })
+ expect(AGENT_SETTING_NAMES).toEqual({ 'agents-start-agents': 'agentsStartAgents', 'agents-tell-agents': 'agentsTellAgents', 'pull-request-line': 'pullRequestLine', 'agent-messages': 'agentMessages', 'agent-messages-hide-summary': 'agentMessagesHideSummary', 'programs-reply': 'programsReply' })
+ expect(AGENT_SETTING_EXPERIMENTS).toEqual({ agentsStartAgents: 'agents_start_agents', pullRequestLine: 'agent_pull_request_line', agentMessages: 'agent_messages', agentMessagesHideSummary: 'agent_messages_hide_summary', agentsTellAgents: 'agents_tell_agents', programsReply: 'programs_reply' })
})
it('reads the copy kept for the account signed in here, written whole and private', () => {
@@ -36,7 +36,7 @@ describe('what the person lets agents do', () => {
})
it('never turns one account\'s experiments on for another, or for no one', () => {
- saveAgentSettings(dir, owner, { agentsStartAgents: true, pullRequestLine: true, agentMessages: true, agentMessagesHideSummary: true, agentsTellAgents: true })
+ saveAgentSettings(dir, owner, { agentsStartAgents: true, pullRequestLine: true, agentMessages: true, agentMessagesHideSummary: true, agentsTellAgents: true, programsReply: true })
// Signed out, signed in with no machine yet, to another account's machine, or to another account.
expect(readAgentSettings(dir, null)).toEqual(OFF)
expect(readAgentSettings(dir, session({ machineId: undefined }))).toEqual(OFF)
diff --git a/cli/src/lib/agentSettings.ts b/cli/src/lib/agentSettings.ts
index 288593c63..4d118618c 100644
--- a/cli/src/lib/agentSettings.ts
+++ b/cli/src/lib/agentSettings.ts
@@ -35,15 +35,19 @@ export interface AgentSettings {
* gets no exception from Agent Messages (2026-10-11), so this one-way order from the starter is the person's to
* allow, not a side effect of starting. */
agentsTellAgents: boolean
+ /** A program acting for the person (the lamp's `lamp-tasks`, not an agent) may give more work to an idle harness of
+ * theirs in a pane (`harness reply`, messages/replyLocal.ts), as the person could by typing in Harness. Off by
+ * default, and not `agents-tell-agents`, which is about agents (#1628). */
+ programsReply: boolean
}
-export const AGENT_SETTINGS_DEFAULTS: AgentSettings = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false }
+export const AGENT_SETTINGS_DEFAULTS: AgentSettings = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, agentMessagesHideSummary: false, agentsTellAgents: false, programsReply: false }
/** Each setting's name in `harness settings`, and its key. */
-export const AGENT_SETTING_NAMES: Record<string, keyof AgentSettings> = { 'agents-start-agents': 'agentsStartAgents', 'agents-tell-agents': 'agentsTellAgents', 'pull-request-line': 'pullRequestLine', 'agent-messages': 'agentMessages', 'agent-messages-hide-summary': 'agentMessagesHideSummary' }
+export const AGENT_SETTING_NAMES: Record<string, keyof AgentSettings> = { 'agents-start-agents': 'agentsStartAgents', 'agents-tell-agents': 'agentsTellAgents', 'pull-request-line': 'pullRequestLine', 'agent-messages': 'agentMessages', 'agent-messages-hide-summary': 'agentMessagesHideSummary', 'programs-reply': 'programsReply' }
/** Each setting's account experiment, as the backend names it (lib/experimentalSettings.ts `experimentalFeatures`). */
-export const AGENT_SETTING_EXPERIMENTS: Record<keyof AgentSettings, string> = { agentsStartAgents: 'agents_start_agents', pullRequestLine: 'agent_pull_request_line', agentMessages: 'agent_messages', agentMessagesHideSummary: 'agent_messages_hide_summary', agentsTellAgents: 'agents_tell_agents' }
+export const AGENT_SETTING_EXPERIMENTS: Record<keyof AgentSettings, string> = { agentsStartAgents: 'agents_start_agents', pullRequestLine: 'agent_pull_request_line', agentMessages: 'agent_messages', agentMessagesHideSummary: 'agent_messages_hide_summary', agentsTellAgents: 'agents_tell_agents', programsReply: 'programs_reply' }
/** The flag an agent adds to `harness settings <name> on` once the person said yes to it (agentClient/settings.ts). */
export const PERSON_SAID_YES = '--person-said-yes'
@@ -55,6 +59,7 @@ export const AGENT_SETTING_QUESTIONS: Record<keyof AgentSettings, string> = {
pullRequestLine: 'May a harness another agent started say so in the pull requests it opens?',
agentMessages: 'May agents in the same tab message each other?',
agentMessagesHideSummary: 'May Harness share a one-line summary of what your harnesses do with the people in your shared tabs?',
+ programsReply: 'May programs that act for you, like your lamp, give more work to a harness of yours that is idle, as you could by typing to it?',
}
/**
diff --git a/cli/src/messages/replyLocal.ts b/cli/src/messages/replyLocal.ts
new file mode 100644
index 000000000..99f4e4b3c
--- /dev/null
+++ b/cli/src/messages/replyLocal.ts
@@ -0,0 +1,50 @@
+/**
+ * `harness reply` to a harness in a pane (#1628; shape A of its design, #1873): more work for
+ * an idle harness of the person's, from a program acting for them. The lamp hands a spoken request to Claude Code on
+ * the person's computer, checks its answer, and when the check fails says so to the same conversation, as a person
+ * would type it, instead of closing it and starting again with everything.
+ *
+ * A program is not an agent: `outsideCaller` (agentClient/model.ts) does not recognise it, and Harness reads it as the
+ * person, as `harness reply` to a cloud harness already does. So this is the person's own reach, with three bounds of
+ * its own: the person's switch (`programs-reply`, off by default; `agents-tell-agents` is about agents), only an idle
+ * harness (one that waits on a question or a permission is the person's alone to answer), and the mailbox (mailbox.ts),
+ * which types the words once the composer is free and never over a person's draft. The bounds are `tell`'s: its
+ * length, its rate and its queue.
+ *
+ * Its messages are kept under the pseudo-tab `replied`, as `tell`'s are under `told`: no tab carries them.
+ */
+import { askThePersonFirst } from '../lib/agentSettings.js'
+
+/** The tab id a replied message is kept under. No desk tab has it: ids there are the backend's. */
+export const REPLIED_TAB = 'replied'
+
+/** Who a replied message is from, in the ledger's `Told` lines and the message's sender: the person, not a harness. */
+export const PERSON_AGENT_ID = 'person'
+
+/** Said when the person has not allowed it: the program asks them, and starts a new harness if they say no. */
+export const REPLY_OFF_TEXT = `Programs may not give more work to your harnesses yet. ${askThePersonFirst('programs-reply', 'start a new harness with the whole task.')}`
+
+export interface ReplyRefusal { code: 'REPLY_OFF' | 'NOT_RUNNING' | 'NOT_IDLE'; message: string }
+
+export interface ReplyCheck {
+ /** The switch, as this machine keeps the account's experiments. */
+ on: boolean
+ /** Whether [agentId] is a live harness here. */
+ live: boolean
+ /** What it is doing, as this machine reads it (`core.agents.activity`). */
+ activity: 'working' | 'idle' | 'unknown'
+}
+
+/** Why a program may not reply to a harness on this machine, or null. */
+export function replyRefusal(check: ReplyCheck): ReplyRefusal | null {
+ if (!check.on) return { code: 'REPLY_OFF', message: REPLY_OFF_TEXT }
+ if (!check.live) return { code: 'NOT_RUNNING', message: 'That harness is no longer running: it was closed or stopped. Start a new harness with the whole task.' }
+ // Working, it would get the words at its next tool call, inside work the person did not ask to change; unknown, it may
+ // be waiting on a question or a permission, which only the person answers.
+ if (check.activity !== 'idle') {
+ return { code: 'NOT_IDLE', message: check.activity === 'working'
+ ? 'That harness is working. Wait for it to finish (harness wait), then reply.'
+ : 'That harness is not idle: it may be waiting for the person (a question or a permission). Only they answer that.' }
+ }
+ return null
+}
diff --git a/cli/src/messages/service.spec.ts b/cli/src/messages/service.spec.ts
index 5ac0d316c..75c337369 100644
--- a/cli/src/messages/service.spec.ts
+++ b/cli/src/messages/service.spec.ts
@@ -38,6 +38,8 @@ interface Setup {
rpc?: Rpc
backendStatus?: number
signedIn?: () => boolean
+ /** What each harness is doing, as `core.agents.activity` says: idle when not named. Not given, it knows none. */
+ activity?: Record<string, 'working' | 'idle' | 'unknown'>
}
function setup(over: Setup = {}) {
@@ -67,6 +69,7 @@ function setup(over: Setup = {}) {
live: () => agents,
displayName: (s) => (s as unknown as { title: string }).title,
terminalAvailable: () => true,
+ ...(over.activity ? { activity: async (ids: string[]) => Object.fromEntries(ids.map((id) => [id, over.activity?.[id] ?? 'idle'])) } : {}),
},
turns: {
deliver: (agentId, text, id) => { delivered.push([agentId, text, id]) },
@@ -631,6 +634,66 @@ describe('harness tell: more work from the harness that started it', () => {
})
})
+describe('harness reply to a harness here: a program acting for the person', () => {
+ // The person's words, behind `programs-reply` (replyLocal.ts), for an idle harness only: not agents' `tell`.
+ const allow = (t: ReturnType<typeof setup>, on = true) => { t.setting(false); setAgentSettingsForTest(root, { programsReply: on }) }
+
+ it('types the person\'s words into an idle harness, with no header, from here or another of the owner\'s machines', async () => {
+ const t = setup({ tabs: [], activity: {} })
+ allow(t)
+ const reply = await t.ask({ action: 'reply_local', machine: 'lamp-75c9', agentId: 'web', text: 'The lamp\'s check refused skill.toml: name is missing.' })
+ expect(reply).toMatchObject({ state: 'queued' })
+ expect(t.delivered).toHaveLength(1)
+ const [agentId, text, deliveryId] = t.delivered[0]
+ expect(agentId).toBe('web')
+ expect(text).toBe('The lamp\'s check refused skill.toml: name is missing.')
+ t.deliveryEvent({ deliveryId, sessionId: 'web', state: 'started' })
+ const history = await t.ask({ action: 'history', tabId: 'replied' })
+ expect(history.messages).toEqual([expect.objectContaining({ id: reply.id, from: expect.objectContaining({ agentId: 'person', machine: 'lamp-75c9' }),
+ statuses: [expect.objectContaining({ agentId: 'web', state: 'delivered' })] })])
+ expect(await t.ask({ action: 'reply_local', machine: 'lamp-75c9', agentId: 'api', text: 'Fix it.' }, OWNER_REMOTE)).toMatchObject({ state: 'queued' })
+ expect(t.delivered).toHaveLength(2)
+ })
+
+ it('is refused until the person turns it on, and for a harness that works, may wait for the person, or is gone', async () => {
+ const t = setup({ tabs: [], activity: { api: 'working', lead: 'unknown' } })
+ t.setting(false)
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x' })).toMatchObject({ error: 'REPLY_OFF', detail: expect.stringContaining('programs-reply') })
+ allow(t)
+ expect(await t.ask({ action: 'reply_local', agentId: 'api', text: 'x' })).toMatchObject({ error: 'NOT_IDLE', detail: expect.stringContaining('is working') })
+ expect(await t.ask({ action: 'reply_local', agentId: 'lead', text: 'x' })).toMatchObject({ error: 'NOT_IDLE', detail: expect.stringContaining('Only they answer that') })
+ expect(await t.ask({ action: 'reply_local', agentId: 'gone', text: 'x' })).toMatchObject({ error: 'NOT_RUNNING' })
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: ' ' })).toMatchObject({ error: 'USAGE' })
+ expect(await t.ask({ action: 'reply_local', text: 'x' })).toMatchObject({ error: 'USAGE' })
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x'.repeat(LIMITS.text + 1) })).toMatchObject({ error: 'TOO_LONG' })
+ // Not the owner: nothing at all.
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x' }, { local: true, owner: false })).toMatchObject({ error: 'OWNER_REQUIRED' })
+ expect(t.delivered).toEqual([])
+ })
+
+ it('keeps tell\'s rate: 30 in 10 minutes', async () => {
+ const t = setup({ tabs: [], activity: {} })
+ allow(t)
+ for (let i = 0; i < LIMITS.perSender; i++) {
+ const r = await t.ask({ action: 'reply_local', agentId: 'web', text: `x${i}` })
+ t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'web', state: 'started' })
+ expect(r).toMatchObject({ state: expect.any(String) })
+ }
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'one more' })).toMatchObject({ error: 'RATE_LIMITED' })
+ t.tick(LIMITS.window)
+ expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'later' })).not.toHaveProperty('error')
+ })
+
+ it('a hand-over under `replied` from another machine is no way around the idle check or the tabs', async () => {
+ const t = setup({ tabs: [], activity: {} })
+ allow(t)
+ const answer = await t.ask({ action: 'deliver', message: { id: 'm00000ee', tabId: 'replied', text: 'hi', at: 5,
+ from: { machineId: 'm2', agentId: 'person', name: 'the person', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'web', name: 'web' }] } }, OWNER_REMOTE)
+ expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'web', state: 'failed' })])
+ expect(t.delivered).toEqual([])
+ })
+})
+
describe('from the owner\'s other machines', () => {
const incoming =(to = 'api', from = { machineId: 'm2', agentId: 'phone' }) => ({
id: 'm00000aa', tabId: 'app', text: 'from the phone', at: 5,
diff --git a/cli/src/messages/service.ts b/cli/src/messages/service.ts
index 118db5c7e..9c6519524 100644
--- a/cli/src/messages/service.ts
+++ b/cli/src/messages/service.ts
@@ -43,6 +43,7 @@ import { PaneInbox } from './inbox.js'
import { Mailbox, type MailboxAgent } from './mailbox.js'
import { type DeliveryStatus, LIMITS, LONG_TEXT, longAdvice, type Message, MessageError, messageId, note, parseMessage, type Recipient, rendered, type TabNote, type Teammate } from './model.js'
import { TOLD_TAB, tellRefusal, toldText } from './tell.js'
+import { PERSON_AGENT_ID, REPLIED_TAB, replyRefusal } from './replyLocal.js'
import { messagesRpc, RefusedError, type Rpc } from './rpc.js'
import { RequestStore } from './requestStore.js'
import { cleanName, type Roster } from './roster.js'
@@ -229,6 +230,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
/** Whether a harness's starter may tell it more work (`agents-tell-agents`): read at each use, as few as they are, so
* a switch turned off stops what still waits at the mailbox's next look. */
const tellOn = (): boolean => readAgentSettings(options.dataDir ?? core.dataDir).agentsTellAgents
+ /** Whether a program acting for the person may reply to a harness here (`programs-reply`): read at each use, as `tellOn`. */
+ const replyOn = (): boolean => readAgentSettings(options.dataDir ?? core.dataDir).programsReply
let waking = false
const later = (): void => {
if (waking) return
@@ -280,6 +283,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
text: (delivery, message) => {
// More work from its starter: no tab, so no roster note, which would invite it to message its teammates.
if (message.tabId === TOLD_TAB) return toldText(message)
+ // The person's words, as they would type them: no header, as `harness reply` to a cloud harness sends them.
+ if (message.tabId === REPLIED_TAB) return message.text
const roster = rosterOf(delivery.agentId)
const text = rendered(message, account?.accountId)
return roster && store.state.noted[delivery.agentId] !== roster.signature ? `${roster.text}\n\n${text}` : text
@@ -321,6 +326,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
const refusal = tellRefusal({ on: tellOn(), lineage, self: self(), live: () => true }, entry.message.from, delivery.agentId)
return refusal ? { refused: refusal.message } : null
}
+ // A program's reply for the person: the switch is looked at again at each look, as a tell's is.
+ if (entry.message.tabId === REPLIED_TAB) return replyOn() ? null : { refused: 'programs-reply was turned off' }
if (!directory.current() && directory.on()) return null
const key = `${delivery.messageId} ${delivery.agentId}`
const recipient = { machineId: self(), agentId: delivery.agentId }
@@ -659,6 +666,45 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
return { id: message.id, state: status?.state ?? 'queued', ...(status?.reason ? { reason: status.reason } : {}) }
}
+ /** When programs replied to harnesses here, for the rate limit: the same 30 in 10 minutes a `tell` has. */
+ const repliedAt: number[] = []
+
+ /**
+ * `harness reply` to a harness in a pane here (replyLocal.ts), from a program acting for the person: a process of the
+ * owner's on this machine, or another of the owner's machines over the relay. Only an idle harness, only with the
+ * person's switch on; queued in the mailbox, which types it once the composer is free.
+ */
+ async function replyLocal(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ const text = typeof payload.text === 'string' ? payload.text : ''
+ if (!agentId) throw new MessageError('USAGE', 'Name the harness to reply to.')
+ if (!text.trim()) throw new MessageError('USAGE', 'Give the words: harness reply <name> -- <words>')
+ if (text.length > LIMITS.text) throw new MessageError('TOO_LONG', `A message holds at most ${LIMITS.text} characters.`)
+ const session = localAgent(agentId)
+ const activity = session ? (await core.agents.activity([agentId]))[agentId] ?? 'unknown' : 'unknown'
+ const refusal = replyRefusal({ on: replyOn(), live: !!session, activity })
+ if (refusal) throw new MessageError(refusal.code, refusal.message)
+ while (repliedAt.length && now() - repliedAt[0] >= LIMITS.window) repliedAt.shift()
+ if (repliedAt.length >= LIMITS.perSender) throw new MessageError('RATE_LIMITED', `Programs replied to your harnesses ${LIMITS.perSender} times in 10 minutes. Wait for their answers first.`)
+ if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
+ throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on that machine. Try again once some are delivered.')
+ }
+ const machine = typeof payload.machine === 'string' && payload.machine.trim() ? payload.machine.trim().slice(0, 200) : machineName(self())
+ const message: Message = {
+ id: messageId(), tabId: REPLIED_TAB, text, at: now(),
+ to: [{ machineId: self(), agentId, name: core.agents.displayName(session!) || agentId.slice(0, 8) }],
+ from: { machineId: self(), agentId: PERSON_AGENT_ID, name: 'the person', engine: '', machine },
+ }
+ repliedAt.push(now())
+ store.record(message)
+ store.status({ messageId: message.id, machineId: self(), agentId, state: 'queued', at: now() })
+ mailbox.accept(message, agentId)
+ mailbox.resume()
+ saveQuietly()
+ const status = store.entry(message.id)?.statuses.find((s) => s.machineId === self() && s.agentId === agentId)
+ return { id: message.id, state: status?.state ?? 'queued', ...(status?.reason ? { reason: status.reason } : {}) }
+ }
+
function withdrawNote(agentId: string): void {
const pending = store.state.notes[agentId]
if (!pending) return
@@ -1623,6 +1669,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
case 'started': return started(payload)
// From a pane here, or another of the owner's machines over the relay: `tell` tells them apart.
case 'tell': return tell(payload, asker.local)
+ // A program acting for the person, here or on another of the owner's machines (replyLocal.ts).
+ case 'reply_local': return replyLocal(payload)
case 'history': return history(payload)
// The windows' sidebar: every harness of a desk tab, shared or not, with its state and one line on what it does.
case 'tab_activity': return tabActivity(String(payload.tabId))
diff --git a/docs/cli.md b/docs/cli.md
index d2e6cd85b..9ccc7d3c3 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -120,6 +120,14 @@ A cloud agent starts the same way: `harness new devin-cloud --machine office --r
state, what it said after the last thing it was told, and its links (`links` in JSON). `harness reply <name> --
<words>` says the person's answer, or what to do next, to a cloud harness; an agent does not.
+`harness reply` also gives more work to a harness in a pane, for a program acting for the person (a lamp that checked
+the answer and found it wrong), when the person has turned on `programs-reply` (`harness settings`, off by default).
+Only an idle harness takes it: one that is working is refused until it finishes (exit 1), and one that may be waiting
+on a question or a permission is the person's to answer. The machine it runs on checks both again and types the words
+in once its composer is free, never over a draft, with `tell`'s limits. Then `harness wait` and `harness show`, as
+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 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