The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(cli): start, read and answer cloud agents from the CLI (#1444) (#1445)
0xdiego252f12016ff4c6
diff --git a/cli/src/agentClient/commands.spec.ts b/cli/src/agentClient/commands.spec.tsindex d7338f2d6..a0e82fee7 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, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, waitCommand, whoamiCommand, type ClientDeps } from './commands.js'+import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, DEPTH_REFUSAL, EXIT, parseDuration, psCommand, refusalNext, replyCommand, showCommand, spawnCheck, spawnCount, spawnRefusal, SPAWN_LIMITS, step, waitCommand, whoamiCommand, type ClientDeps } from './commands.js'import { AgentClientError, type Daemon, type Where } from './daemon.js'import { Ledger, ledgerPath } from './ledger.js'import { agentSettingsPath } from '../lib/agentSettings.js'@@ -1659,3 +1659,96 @@ describe('harness whoami', () => {expect(h.err[0]).toBe('harness whoami takes no names and no --machine: it is about you, here.')})})++describe('a cloud harness (#1444)', () => {+ const cloud = (id: string, state: string, over: Partial<Frame> = {}) => frame(id, {+ engine: 'devin-cloud', location: 'cloud', tmuxPane: null, project: null, sessionId: id,+ activity: { state: state === 'working' || state === 'starting' ? 'working' : 'idle' },+ cloud: { state, links: [{ label: 'Session', url: 'https://app.devin.ai/sessions/1' }] }, ...over,+ })+ const transcript = (d: FakeDaemon, messages: Array<{ from: string; text: string }>) => {+ d.extra.cloud_transcript = () => ({ messages: messages.map((m, i) => ({ id: String(i), at: '', ...m })), total: messages.length })+ }++ it('shows its state from the cloud, its last words and its links, reading no screen', async () => {+ const d = new FakeDaemon()+ d.frames = [cloud('devin', 'idle')]+ transcript(d, [{ from: 'person', text: 'old' }, { from: 'agent', text: 'old answer' }, { from: 'person', text: 'reply to the thread' }, { from: 'agent', text: 'On it.' }, { from: 'agent', text: 'Replied.' }])+ const h = harness(d)+ expect(await showCommand(['devin', '--json'], h.deps)).toBe(EXIT.ok)+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ state: 'idle', ask: 'reply to the thread', answer: 'On it.\n\nReplied.',+ links: [{ label: 'Session', url: 'https://app.devin.ai/sessions/1' }] })+ expect(d.requests.some((r) => r.type === 'agent_close' || r.type === 'session_get')).toBe(false)+ const text = harness(d)+ expect(await showCommand(['devin'], text.deps)).toBe(EXIT.ok)+ expect(text.out).toContain('Session: https://app.devin.ai/sessions/1')+ })++ it('says it needs the person while it asks, though its frame says idle, and how the answer goes to it', async () => {+ const d = new FakeDaemon()+ d.frames = [cloud('devin', 'needs_input')]+ transcript(d, [{ from: 'person', text: 'go' }, { from: 'agent', text: 'Which branch?' }])+ const h = harness(d)+ expect(await showCommand(['devin', '--json'], h.deps)).toBe(EXIT.ok)+ expect(JSON.parse(h.out.join('\n'))).toMatchObject({ state: 'needs-input', needsPerson: true, answer: 'Which branch?',+ next: [{ run: "harness reply devin -- <the person's answer>" }] })+ const w = harness(d)+ expect(await waitCommand(['devin'], w.deps)).toBe(EXIT.needsInput)+ })++ it('waits while it starts and works, and returns when it is done or failed', async () => {+ const d = new FakeDaemon()+ const states = ['starting', 'working', 'working', 'idle']+ d.extra.agents_list = () => ({ agents: [cloud('devin', states.length > 1 ? states.shift()! : states[0])] })+ const h = harness(d)+ expect(await waitCommand(['devin'], h.deps)).toBe(EXIT.ok)+ expect(h.out).toEqual(['devin: idle · read it: harness show devin'])+ expect(d.requests.some((r) => r.type === 'agent_close')).toBe(false)+ d.extra.agents_list = () => ({ agents: [cloud('devin', 'failed')] })+ const f = harness(d)+ expect(await waitCommand(['devin', '--json'], f.deps)).toBe(EXIT.stopped)+ expect(JSON.parse(f.out.join('\n')).harnesses[0].state).toBe('failed')+ })++ it('replies with the person\'s words, and refuses an agent, a terminal harness and no words', async () => {+ const d = new FakeDaemon()+ d.frames = [cloud('devin', 'needs_input'), frame('kid')]+ const sent: Record<string, unknown>[] = []+ d.extra.cloud_send = (payload) => { sent.push(payload); return { ok: true } }+ const h = harness(d)+ 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)+ 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)+ expect(await replyCommand(['devin', '--', 'x'], busy.deps)).not.toBe(EXIT.ok)+ expect(busy.err.join('\n')).toMatch(/still working/)+ d.frames.push(frame('lead'))+ const before = d.requests.length+ const agent = harness(d)+ expect(await replyCommand(['devin', '--', 'x'], agent.deps)).toBe(EXIT.refused)+ expect(d.requests.slice(before).some((r) => r.type === 'cloud_send')).toBe(false)+ // The agent is told to tell the person, never to run the reply it would be refused.+ const shown = harness(d)+ expect(await showCommand(['devin', '--json'], shown.deps)).toBe(EXIT.ok)+ expect(JSON.parse(shown.out.join('\n')).next).toEqual([{ tell: expect.stringMatching(/tell the person/) }])+ })++ it('says a failed one failed in the cloud, shows nothing read when its conversation cannot be read, and will not close one', async () => {+ const d = new FakeDaemon()+ d.frames = [cloud('devin', 'failed')]+ const w = harness(d)+ expect(await waitCommand(['devin'], w.deps)).toBe(EXIT.stopped)+ expect(w.out).toEqual(['devin: failed · it failed in the cloud; what it said and its links: harness show devin'])+ d.extra.cloud_transcript = () => ({ error: 'SERVICE_UNAVAILABLE' })+ const s = harness(d)+ expect(await showCommand(['devin'], s.deps)).toBe(EXIT.ok)+ expect(s.out).toContain('No turn yet.')+ const c = harness(d)+ expect(await closeCommand(['devin'], c.deps)).toBe(EXIT.usage)+ expect(c.err.join('\n')).toMatch(/stop it in Harness/)+ expect(d.requests.some((r) => r.type === 'agent_close' && r.payload.mode !== 'inspect')).toBe(false)+ })+})diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.tsindex 3b5c8bb2d..41fcb3298 100644--- a/cli/src/agentClient/commands.ts+++ b/cli/src/agentClient/commands.ts@@ -29,7 +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 } from './ledger.js'import { messagesRpc, type Rpc } from '../messages/rpc.js'-import { asSaid, callerOf, clip, forAgent, isAgent, lastTurn, matching, outsideCaller, rowsOf, stateOf, STOPPED_WITHIN_MS, type Caller, type Frame, type HistoryEvent, type Row, type State } from './model.js'+import { asSaid, callerOf, clip, cloudTurn, forAgent, isAgent, lastTurn, matching, outsideCaller, rowsOf, stateOf, STOPPED_WITHIN_MS, type Caller, type Frame, type HistoryEvent, type Row, type State } from './model.js'export interface ClientDeps {pane?: string | undefined@@ -61,6 +61,11 @@ export const SHOW_USAGE = `Usage: harness show [--machine <name>] <name> [--charA harness's state and its last turn: what it was asked and what it answered (the first N characters, 4000 by default).${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.+The person's, or a program's acting for them; an agent does not answer for the person.+${ON_MACHINE}`export const WAIT_USAGE = `Usage: harness wait [--machine <name>] <name>[,<name>…] [--any] [--timeout 30m] [--json]Waits until each harness has stopped working, then prints its state. --any returns when the first one does.@@ -411,6 +416,11 @@ async function inspect(t: { daemon: Daemon; frame: Frame }): Promise<Screen | nu/** The last turn, from the end of the transcript, a page at a time: never the whole file (the attach OOM). */async function readLastTurn(t: { daemon: Daemon; frame: Frame }, pages = 4) {+ if (t.frame.location === 'cloud') {+ const reply = await t.daemon.request('cloud_transcript', { agentId: t.frame.id })+ if (typeof reply.error === 'string') return null+ return cloudTurn(Array.isArray(reply.messages) ? reply.messages as Array<Record<string, unknown>> : [])+ }if (!t.frame.sessionId) return nulllet before: string | undefinedlet events: HistoryEvent[] = []@@ -646,7 +656,8 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Protry {t = await target(s, o, names[0], away)const listed = stateOf(t.frame)- const screen = listed === 'stopped' || listed === 'offline' ? null : await inspect(t)+ // A cloud harness has no screen: its state is the cloud service's.+ const screen = listed === 'stopped' || listed === 'offline' || t.frame.location === 'cloud' ? null : await inspect(t)const state: State = screen === 'draft' ? 'idle' : screen ?? listedconst turn = await readLastTurn(t)const parent = o.ledger.parentOf({ machineId: t.machineId, agentId: t.frame.id })@@ -654,12 +665,17 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Proconst answer = turn?.answer ?? ''// A name the verbs take: an unnamed harness is called by its session title, a sentence, so by its id's start.const at = onAway(addressOf({ machineId: '', agentId: t.frame.id, name: t.frame.name ?? '', engine: '' }), away)- const next = showNext(s.env, state, t.yours, at)+ const next = t.frame.location === 'cloud' && state === 'needs-input' && !o.caller && !o.orphan+ // Answered by the person, or a program speaking for them (the lamp): no agent tool says it.+ ? [{ run: `harness reply ${at} -- <the person's answer>`, when: 'it waits for the person: tell them what it asks' }]+ // `close` takes no cloud harness.+ : showNext(s.env, state, t.yours && t.frame.location !== 'cloud', at)const result = {name: t.frame.name, id: t.frame.id, agent: engineName(t.frame.engine ?? ''), machine: t.machine, state, startedBy,folder: t.frame.project?.cwd ?? null, branch: t.frame.project?.branch ?? null,ask: turn?.ask ?? null, answer: clip(answer, chars), truncated: answer.length > chars, tools: turn?.tools ?? 0, next,...(state === 'needs-input' ? { needsPerson: true } : {}),+ ...(t.frame.cloud?.links?.length ? { links: t.frame.cloud.links } : {}),}if (flags.has('--json')) s.out(JSON.stringify(result, null, 1))else {@@ -672,6 +688,7 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pros.out(result.answer || '(no text)')if (result.truncated) s.out(`… ${answer.length - chars} more characters: ${step(s.env, 'show', onAway(result.name ?? t.frame.id, away), { flag: `--chars ${answer.length}`, arg: `chars: ${answer.length}` })}`)}+ for (const link of result.links ?? []) s.out(`${link.label}: ${link.url}`)const said = formatNext(next)if (said) s.out(said)}@@ -680,6 +697,34 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pro})}+// ── reply ──────────────────────────────────────────────────────────────────────────────────────────++export function replyCommand(argv: readonly string[], deps: ClientDeps = {}): Promise<number> {+ return run(REPLY_USAGE, deps, wantsJson, argv, async (s) => {+ const dash = argv.indexOf('--')+ const { names, flags, machine } = words(dash < 0 ? argv : argv.slice(0, dash), { '--json': 'flag' })+ const text = dash < 0 ? '' : argv.slice(dash + 1).join(' ').trim()+ if (names.length !== 1) throw new UsageError(names.length ? 'Name one harness.' : 'Name the harness to reply to.')+ if (!text) throw new UsageError('Give the words after --: harness reply <name> -- <words>')+ const away = await machineOf(s, s.where(), machine)+ 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.')+ 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' }]+ 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() }+ })+}+// ── wait ───────────────────────────────────────────────────────────────────────────────────────────/** How far another machine's clock may be off from this one's, for what happened before or after a close. */@@ -769,6 +814,11 @@ export function waitCommand(argv: readonly string[], deps: ClientDeps = {}): Proif (!frame) return ended(t, (await list(t.daemon, true)).some((f) => f.id === t.frame.id) ? 'stopped' : 'gone')t.frame = frameif (frame.status === 'stopped') return ended(t, 'stopped')+ // A cloud harness says where it is itself, with no screen to read: done once it is no longer starting or working.+ if (frame.location === 'cloud') {+ const state = stateOf(frame)+ return state === 'idle' || state === 'needs-input' || state === 'failed' ? state : null+ }// The daemon says it is working: no need to read its screen.const screen = frame.activity?.state === 'working' ? 'working' : await inspect(t)if (screen === 'working') { sawWorking.add(t); idle.delete(t); return null }@@ -845,6 +895,7 @@ export function waitCommand(argv: readonly string[], deps: ClientDeps = {}): Pro: r.state === 'needs-input' ? 'it waits for the person (a question or a permission); only the person answers it': r.state === 'timeout' ? `still working; wait again or read it: ${read}`: r.state === 'installing' || r.state === 'starting' ? `${askedLine(s.env, following.find((a) => a.row.creation.creationId === r.id)!, away)}`+ : r.state === 'failed' && targets.some((t) => t.frame.id === r.id) ? `it failed in the cloud; what it said and its links: ${read}`: r.state === 'failed' ? `it never started: ${r.detail || 'its machine refused it'}`// Harness closes one another agent started once it has sat idle half an hour (services/agentCleanup.ts): its// answer is still there to read.@@ -895,6 +946,8 @@ export function closeCommand(argv: readonly string[], deps: ClientDeps = {}): Prreturn EXIT.ok}const name = t.frame.name ?? t.frame.id.slice(0, 8)+ // `agent_close` has no cloud harness to close (lib/closeAgentService.ts): it answered "changed, try again" for good.+ if (t.frame.location === 'cloud') throw new UsageError(`${name} runs in its maker's cloud: stop it in Harness. Its conversation is kept either way.`)if (o.orphan) throw new AgentClientError('NOT_YOURS', ORPHAN, 'ORPHAN')if (o.caller && o.caller.agentId === t.frame.id && t.machineId === o.where.machineId) {throw new AgentClientError('NOT_YOURS', 'That is your own harness. The person closes it.')diff --git a/cli/src/agentClient/model.ts b/cli/src/agentClient/model.tsindex 59f61d6c6..2c5955416 100644--- a/cli/src/agentClient/model.ts+++ b/cli/src/agentClient/model.ts@@ -22,6 +22,10 @@ export interface Frame {parentAgentId?: string | null/** `agent` when another agent started it, here or from another machine or outside Harness. */startedBy?: string | null+ /** `cloud`: a harness in its maker's cloud (lib/cloudAgents.ts), with no pane and no session. Its state and words are+ * the cloud service's: `cloud.state` and `cloud_transcript`. */+ location?: string+ cloud?: { state?: string; links?: Array<{ label: string; url: string }> } | null}/** The agent running the verb: a harness in its own pane, or an agent outside Harness. Null for a person at a terminal. */@@ -63,9 +67,16 @@ export const STOPPED_WITHIN_MS = 7 * 24 * 60 * 60_000export const isAgent = (frame: Frame): boolean => !!frame.id && frame.engine !== 'terminal'+/** A cloud harness's `cloud.state` (lib/cloudAgents.ts `CloudState`). Its frame's activity says idle while it asks the+ * person, so a wait read it as done (lampOS, #1444). */+const CLOUD_STATES: Record<string, State> = {+ starting: 'starting', working: 'working', needs_input: 'needs-input', idle: 'idle', failed: 'failed', stopped: 'stopped',+}+export function stateOf(frame: Frame): State {if (frame.status === 'stopped') return 'stopped'if (frame.status === 'offline') return 'offline'+ if (frame.location === 'cloud') return CLOUD_STATES[frame.cloud?.state ?? ''] ?? 'unknown'const state = frame.activity?.statereturn state === 'working' ? 'working' : state === 'idle' ? 'idle' : 'unknown'}@@ -218,4 +229,14 @@ export function lastTurn(events: HistoryEvent[]): LastTurn | null {return { ask: asSaid(text(events[start].payload?.content)) || null, answer: final || said(0), tools, answered: !!final }}+/** A cloud harness's last turn from its conversation (`cloud_transcript`): the person's last words and everything the+ * agent said after them. */+export function cloudTurn(messages: ReadonlyArray<{ from?: unknown; text?: unknown }>): LastTurn | null {+ let start = -1+ for (let i = messages.length - 1; i >= 0; i--) if (messages[i].from === 'person') { start = i; break }+ if (start < 0) return null+ const answer = messages.slice(start + 1).filter((m) => m.from === 'agent').map((m) => text(m.text).trim()).filter(Boolean).join('\n\n')+ return { ask: text(messages[start].text) || null, answer, tools: 0, answered: !!answer }+}+export const clip = (value: string, max: number): string => (value.length > max ? `${value.slice(0, max - 1)}…` : value)diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 78979da13..ea7a92359 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -155,7 +155,8 @@ Machine:harness show <name> a harness's state and last turn: what it was asked and what it answeredharness wait <name>[,<name>] wait until they stop working (--any, --timeout 30m); exit 3 = needs the personharness close <name> [--now] save a harness's screen and stop it; an agent closes only what it started- new, ps, show, wait and close take --machine <name> for another of your+ harness reply <name> -- <w> say words to a cloud harness (Devin Cloud, Cursor Cloud, Fo): its answer or what next+ new, ps, show, wait, reply and close take --machine <name> for another of yourmachines: \`harness show --machine office x\`harness mcp the agent verbs as an MCP server on stdin/stdout, for agents that use MCPharness help agents the agent commands, states, exit codes and rules on one screen@@ -2536,7 +2537,7 @@ async function logsExportCommand(json: boolean): Promise<void> {import { orchestratorCommand } from './orchestrator/command.js'import { superTabCommand } from './superTabs/command.js'import { paneOwner, sendCommand } from './messages/command.js'-import { agentOrigin, closeCommand, psCommand, showCommand, waitCommand, whoamiCommand } from './agentClient/commands.js'+import { agentOrigin, closeCommand, psCommand, replyCommand, showCommand, waitCommand, 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'@@ -2597,6 +2598,9 @@ switch (cmd) {case 'show':showCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)break+ case 'reply':+ replyCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)+ breakcase 'wait':waitCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)breakdiff --git a/cli/src/cloud/service.spec.ts b/cli/src/cloud/service.spec.tsindex 1dc4c30c1..84b4e33bf 100644--- a/cli/src/cloud/service.spec.ts+++ b/cli/src/cloud/service.spec.ts@@ -104,12 +104,21 @@ describe('a cloud harness', () => {expect(saved.harnesses[0]).toMatchObject({ remote: { id: 'devin-1' }, harness: { agentId: harness.agentId } })})+ it('starts Devin Cloud with no repository, as Devin\'s API allows (#1444)', async () => {+ const devin = maker()+ const service = start({ 'devin-cloud': devin })+ expect(await service.port.create({ engine: 'devin-cloud', prompt: 'reply to the release thread' })).toMatchObject({ ok: true })+ expect(devin.start).toHaveBeenCalledWith({ task: 'reply to the release thread', repository: null, options: { acuLimit: undefined, model: undefined } })+ })+it('refuses what it cannot start, in words a person reads', async () => {const devin = maker({ start: vi.fn(async () => { throw new CloudError('NOT_CONNECTED', 'Add your Devin API key') }) })const service = start({ 'devin-cloud': devin, fo: maker({ id: 'fo', start: vi.fn(async () => { throw new Error('boom') }) }) })expect(await service.port.create({ engine: 'claude', prompt: 'x' })).toMatchObject({ ok: false, error: 'INVALID_ENGINE' })expect(await service.port.create({ engine: 'devin-cloud', prompt: ' ' })).toMatchObject({ ok: false, error: 'INVALID_REQUEST' })- expect(await service.port.create({ engine: 'devin-cloud', prompt: 'x' })).toMatchObject({ ok: false, detail: expect.stringContaining('GitHub repository') })+ expect(await service.port.create({ engine: 'cursor-cloud', prompt: 'x' })).toMatchObject({ ok: false, detail: expect.stringContaining('GitHub repository') })+ expect(await service.port.create({ engine: 'devin-cloud', prompt: 'x', repositoryUrl: 'https://gitlab.com/acme/api' })).toMatchObject({ ok: false, error: 'INVALID_REQUEST', detail: expect.stringContaining('not a GitHub repository') })+ expect(devin.start).not.toHaveBeenCalled()expect(await service.port.create({ engine: 'devin-cloud', prompt: 'x', repository: 'acme/api' })).toEqual({ ok: false, error: 'NOT_CONNECTED', detail: 'Add your Devin API key' })expect(await service.port.create({ engine: 'fo', prompt: 'x' })).toEqual({ ok: false, error: 'CLOUD_FAILED', detail: 'Fo could not be reached. Try again.' })expect(doors.publish).not.toHaveBeenCalled()diff --git a/cli/src/cloud/service.ts b/cli/src/cloud/service.tsindex 1ede7eca1..e9bd4cc86 100644--- a/cli/src/cloud/service.ts+++ b/cli/src/cloud/service.ts@@ -14,7 +14,7 @@ import { randomBytes } from 'node:crypto'import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'import { join } from 'node:path'import type { CloudCore, CloudPort, CloudResult, ServiceRequests } from '../core/api.js'-import { CLOUD_AGENT_IDS, CLOUD_AGENTS, SAID_MAX, cloudAgentFrame, isCloudAgent, type CloudAgentId, type CloudHarness } from '../lib/cloudAgents.js'+import { CLOUD_AGENT_IDS, CLOUD_AGENTS, SAID_MAX, cloudAgentFrame, isCloudAgent, type CloudAgentId, type CloudAgentInfo, type CloudHarness } from '../lib/cloudAgents.js'import { connectionFor, connectionsBridge, type Bridge } from './bridge.js'import { cursorAdapter } from './cursor.js'import { devinAdapter } from './devin.js'@@ -244,7 +244,10 @@ export function startCloudService(options: CloudServiceOptions) {const task = typeof request.prompt === 'string' ? request.prompt.trim() : ''if (!task) return { ok: false, error: 'INVALID_REQUEST', detail: `Tell ${CLOUD_AGENTS[agent].name} what to do.` }const repository = repositoryOf(request.repositoryUrl) ?? repositoryOf(request.repository)- if (CLOUD_AGENTS[agent].kind === 'coding' && !repository) return { ok: false, error: 'INVALID_REQUEST', detail: `Choose a GitHub repository for ${CLOUD_AGENTS[agent].name}.` }+ // A repository given but not read (a GitLab address, a typo) is refused: started without it, the agent would work blind.+ if (!repository && (request.repositoryUrl || request.repository)) return { ok: false, error: 'INVALID_REQUEST', detail: 'That is not a GitHub repository: give owner/name or https://github.com/owner/name.' }+ const info: CloudAgentInfo = CLOUD_AGENTS[agent]+ if (info.kind === 'coding' && !info.repositoryOptional && !repository) return { ok: false, error: 'INVALID_REQUEST', detail: `Choose a GitHub repository for ${CLOUD_AGENTS[agent].name}.` }const acuLimit = typeof request.acuLimit === 'number' && Number.isInteger(request.acuLimit) && request.acuLimit > 0 && request.acuLimit <= 1000 ? request.acuLimit : undefinedconst model = typeof request.model === 'string' && request.model ? request.model.slice(0, 120) : undefinedlet started: Awaited<ReturnType<CloudAdapter['start']>>diff --git a/cli/src/lib/cloudAgents.ts b/cli/src/lib/cloudAgents.tsindex 1ff131f52..abe2af58e 100644--- a/cli/src/lib/cloudAgents.ts+++ b/cli/src/lib/cloudAgents.ts@@ -17,6 +17,8 @@ export interface CloudAgentInfo {place: string/** A coding agent works on a GitHub repository; a personal agent runs errands and takes no repository. */kind: 'coding' | 'personal'+ /** A coding agent that can start with no repository: Devin's API takes `repos` as optional (lampOS asked, #1444). */+ repositoryOptional?: true/** How its connection is found among the person's Connections: by the host its MCP server or API is at. */connection: { mcp: string } | { api: string }/** What to connect, said when it is not connected. */@@ -29,7 +31,7 @@ export const CLOUD_AGENTS = {connect: 'Connect Fo in Connections (Add custom, https://mcp.api.wajo.ai/fo).',},'devin-cloud': {- name: 'Devin Cloud', place: "Devin's cloud", kind: 'coding', connection: { api: 'https://api.devin.ai' },+ name: 'Devin Cloud', place: "Devin's cloud", kind: 'coding', repositoryOptional: true, connection: { api: 'https://api.devin.ai' },connect: 'Add your Devin API key: harness connections add-key Devin https://api.devin.ai',},'cursor-cloud': {diff --git a/cli/src/lib/newCommand.spec.ts b/cli/src/lib/newCommand.spec.tsindex 2f1291e8b..7b2823755 100644--- a/cli/src/lib/newCommand.spec.ts+++ b/cli/src/lib/newCommand.spec.ts@@ -12,7 +12,7 @@ const env = { cwd: '/work/repo', home: '/home/me' }describe('harness new: the words', () => {it('asks nothing: claude, here, on this machine', () => {expect(parseNewArgs([], env)).toEqual({- agent: 'claude', machine: null, cwd: '/work/repo', projectName: null, mode: 'auto', modeGiven: false, prompt: null, name: null, json: false,+ agent: 'claude', machine: null, cwd: '/work/repo', projectName: null, mode: 'auto', modeGiven: false, prompt: null, name: null, repo: null, acuLimit: null, json: false,})})@@ -91,6 +91,17 @@ describe('harness new: the words', () => {expect(newAgentPayload(parseNewArgs(['acme/blender', '.'], env), '/work/repo', 'codex')).toMatchObject({ engine: 'codex', dsh: 'acme/blender' })})+ it('sends a cloud coding agent its repository and ACU limit, and refuses them for any other agent (#1444)', () => {+ const args = parseNewArgs(['devin-cloud', '--machine', 'office', '--repo', 'acme/api', '--acu-limit', '10', '--json', '--', 'reply', 'to', 'the', 'thread'], env)+ expect(args).toMatchObject({ agent: 'devin-cloud', repo: 'acme/api', acuLimit: 10, prompt: 'reply to the thread' })+ expect(newAgentPayload(args, null)).toMatchObject({ engine: 'devin-cloud', repositoryUrl: 'acme/api', acuLimit: 10, prompt: 'reply to the thread' })+ expect(newAgentPayload(parseNewArgs(['devin-cloud', '--', 'x'], env), null)).not.toHaveProperty('repositoryUrl')+ expect(() => parseNewArgs(['codex', '--repo', 'acme/api'], env)).toThrow(/--repo is for a cloud agent/)+ expect(() => parseNewArgs(['devin-cloud', '--repo', ' ', '--', 'x'], env)).toThrow(/--repo needs a value/)+ expect(() => parseNewArgs(['devin-cloud', '--acu-limit', '0'], env)).toThrow(/1 to 1000/)+ expect(() => parseNewArgs(['devin-cloud', '--acu-limit', '2.5'], env)).toThrow(/1 to 1000/)+ })+it('only sends a permission mode to the engines that take one', () => {// The engines with no PERMISSION_MODES row cannot be handed the default `auto`: the daemon refuses// a mode the engine has no contract for (INVALID_PERMISSION_MODE), which made `harness new hermes`diff --git a/cli/src/lib/newCommand.ts b/cli/src/lib/newCommand.tsindex 4beb8ffc2..1bab67297 100644--- a/cli/src/lib/newCommand.ts+++ b/cli/src/lib/newCommand.ts@@ -7,6 +7,7 @@ import { formatNext, type NextStep } from '../agentClient/next.js'import { folderTrust } from '../engines/launchPrep.js'import { ENGINES, type AgentEngine } from '../engines/types.js'import { engineName } from '../messages/model.js'+import { isCloudAgent } from './cloudAgents.js'import { projectFolderSlug } from './agentNames.js'import { permissionModeFlags } from './engineLaunch.js'import { projectsRoot } from './projectFolder.js'@@ -44,6 +45,10 @@ export interface NewArgs {modeGiven: booleanprompt: string | nullname: string | null+ /** A cloud coding agent's GitHub repository, `owner/name` or its address, as typed: the machine reads it. */+ repo: string | null+ /** Devin Cloud's ACU limit. */+ acuLimit: number | nulljson: boolean}@@ -70,6 +75,9 @@ export const NEW_USAGE = [' -- <words…> everything after -- is the first message, unquoted:',' harness new codex -- fix the flaky login test',' --name <n> the harness\'s name until the agent titles its session',+ ' --repo <r> a cloud coding agent\'s GitHub repository: owner/name or https://github.com/owner/name',+ ' (Cursor Cloud needs one; Devin Cloud works without)',+ ' --acu-limit <n> the most ACUs Devin Cloud may spend (1-1000; 5 when left out)',' --json print the result as one JSON line','','An agent refused (its limits, or the person has not let agents start agents) exits 5: do not retry.',@@ -88,6 +96,8 @@ export function parseNewArgs(argv: string[], env: { cwd: string; home: string })let modeGiven = falselet prompt: string | null = nulllet name: string | null = null+ let repo: string | null = null+ let acuLimit: number | null = nulllet json = falseconst value = (flag: string, index: number): string => {const next = argv[index + 1]@@ -108,6 +118,16 @@ export function parseNewArgs(argv: string[], env: { cwd: string; home: string })else if (word === '--mode') { mode = value(word, i); modeGiven = true; i++ }else if (word === '--prompt' || word === '--task') { prompt = value(word, i); i++ }else if (word === '--name') { name = value(word, i); i++ }+ else if (word === '--repo') {+ repo = value(word, i).trim()+ if (!repo) throw new NewUsageError('--repo needs a value.')+ i+++ }+ else if (word === '--acu-limit') {+ acuLimit = Number(value(word, i))+ if (!Number.isInteger(acuLimit) || acuLimit < 1 || acuLimit > 1000) throw new NewUsageError('--acu-limit takes a whole number from 1 to 1000.')+ i+++ }else if (word === '--machine') {if (machine !== null) throw new NewUsageError('Name one machine.')machine = value(word, i).trim()@@ -131,6 +151,9 @@ export function parseNewArgs(argv: string[], env: { cwd: string; home: string })}else words.push(word)}+ if ((repo !== null || acuLimit !== null) && !isCloudAgent(words[0])) {+ throw new NewUsageError(`${repo !== null ? '--repo' : '--acu-limit'} is for a cloud agent: harness new devin-cloud ${repo !== null ? '--repo owner/name' : '--acu-limit 10'} -- <task>`)+ }if (!MODES.has(mode)) throw new NewUsageError(`--mode is one of ${[...MODES].join(', ')}.`)if (words.length > 2) throw new NewUsageError(`Too many words: ${words.slice(2).join(' ')}.`)if (words[1] !== undefined) {@@ -164,7 +187,7 @@ export function parseNewArgs(argv: string[], env: { cwd: string; home: string })if (machine === null) cwd = env.cwdelse projectName = ''}- return { agent: words[0] ?? 'claude', machine, cwd, projectName, mode, modeGiven, prompt, name, json }+ return { agent: words[0] ?? 'claude', machine, cwd, projectName, mode, modeGiven, prompt, name, repo, acuLimit, json }}/** The `agent_create` payload for [args]: the same fields the app's box sends. [baseEngine] is the@@ -198,6 +221,8 @@ export function newAgentPayload(args: NewArgs, cwd: string | null, baseEngine =...(terminal || mode === null ? {} : { permissionMode: mode }),...(args.prompt ? { prompt: args.prompt } : {}),...(args.name ? { name: args.name } : {}),+ ...(args.repo ? { repositoryUrl: args.repo } : {}),+ ...(args.acuLimit !== null ? { acuLimit: args.acuLimit } : {}),creationId: randomUUID(),}}diff --git a/docs/cli.md b/docs/cli.mdindex c9b9b4088..455cb9ecd 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -109,6 +109,12 @@ auto|ask|plan|full`, `--name`, `--new [name]` and `--json` are the rest. There iharness on another of your machines: `harness new claude --machine office --name check -- …`, then`harness wait --machine office check` and `harness show --machine office check`.+A cloud agent starts the same way: `harness new devin-cloud --machine office --repo acme/api -- <task>`.+`--repo` takes `owner/name` or a GitHub address; Cursor Cloud needs one, Devin Cloud works without.+`--acu-limit <n>` caps Devin Cloud's spend (5 when left out). `show` and `wait` read it from the cloud: its+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 whoami` says, for an agent, where it is and what it may do before it acts (`--json` gives the same as`context`); the top of an agent's `harness ps` begins with it, and `harness mcp` puts it in its instructions: