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): 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.ts
index 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.ts
index 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> [--char
A 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 null
let before: string | undefined
let events: HistoryEvent[] = []
@@ -646,7 +656,8 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pro
try {
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 ?? listed
const 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 = {}): Pro
const 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 = {}): Pro
s.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 = {}): Pro
if (!frame) return ended(t, (await list(t.daemon, true)).some((f) => f.id === t.frame.id) ? 'stopped' : 'gone')
t.frame = frame
if (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 = {}): Pr
return 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.ts
index 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_000
export 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?.state
return 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.ts
index 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 answered
harness wait <name>[,<name>] wait until they stop working (--any, --timeout 30m); exit 3 = needs the person
harness 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 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
@@ -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)
+ break
case 'wait':
waitCommand(rest, { machines: usableMachines }).then(code => { process.exitCode = code }).catch(onError)
break
diff --git a/cli/src/cloud/service.spec.ts b/cli/src/cloud/service.spec.ts
index 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.ts
index 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 : undefined
const model = typeof request.model === 'string' && request.model ? request.model.slice(0, 120) : undefined
let started: Awaited<ReturnType<CloudAdapter['start']>>
diff --git a/cli/src/lib/cloudAgents.ts b/cli/src/lib/cloudAgents.ts
index 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.ts
index 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.ts
index 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: boolean
prompt: string | null
name: 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 | null
json: 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 = false
let prompt: string | null = null
let name: string | null = null
+ let repo: string | null = null
+ let acuLimit: number | null = null
let json = false
const 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.cwd
else 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.md
index 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 i
harness 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: