Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(spaces): start a run and reply to it from the app (agents.start, agents.message) (CUA-2347) (#6005)
cua-agents[bot]06afb7cda6cb
diff --git a/apps/cua-spaces-desktop/src/bridge/agents.ts b/apps/cua-spaces-desktop/src/bridge/agents.tsindex af2a85af34..96b8824402 100644--- a/apps/cua-spaces-desktop/src/bridge/agents.ts+++ b/apps/cua-spaces-desktop/src/bridge/agents.ts@@ -67,6 +67,30 @@ export function agentsMethods({ model }: BridgeContext): Handlers {const runId = string(args, "runId");return persistent.runEvents(space, runId, count(args, "cursor") ?? 0, count(args, "max"));},+ // Start a run in a Space and reply to it: the daemon's agent_start and+ // agent_message, answered as is (snake_case, like agents.events).+ "agents.start": async (args) => {+ const space = string(args, "spaceId");+ const agent = string(args, "agent");+ const prompt = string(args, "prompt");+ const persistent = model.agents.persistent;+ if (!persistent.canCallTools) throw Failure.unsupported("Starting a run needs the cua daemon");+ const env = Array.isArray(args.envFromHost) ? args.envFromHost.filter((v): v is string => typeof v === "string") : [];+ return persistent.startRun(space, agent, prompt, {+ repo: optionalString(args, "repo"),+ branch: optionalString(args, "branch"),+ model: optionalString(args, "model"),+ envFromHost: env,+ });+ },+ "agents.message": async (args) => {+ const space = string(args, "spaceId");+ const runId = string(args, "runId");+ const text = string(args, "text");+ const persistent = model.agents.persistent;+ if (!persistent.canCallTools) throw Failure.unsupported("Replying to a run needs the cua daemon");+ return persistent.sendMessage(space, runId, text, args.force === true);+ },"agents.pause": pauseOrResume(true),"agents.resume": pauseOrResume(false),"agents.setup": async () => {diff --git a/apps/cua-spaces-desktop/src/bridge/methods.ts b/apps/cua-spaces-desktop/src/bridge/methods.tsindex 114b87dea0..d893d4c30a 100644--- a/apps/cua-spaces-desktop/src/bridge/methods.ts+++ b/apps/cua-spaces-desktop/src/bridge/methods.ts@@ -17,6 +17,7 @@ export const METHODS = ["machines.list", "host.status","agents.list", "agents.runs", "agents.events", "agents.pause", "agents.resume","agents.setup", "agents.configure", "agents.signIn",+ "agents.start", "agents.message","agents.detail", "agents.readFile", "agents.restoreFile", "agents.addRoutine", "agents.setRoutine","agents.removeRoutine", "agents.allowComputer", "agents.revokeComputer","agentKeys.list", "agentKeys.set", "agentKeys.remove",diff --git a/apps/cua-spaces-desktop/src/model/agents.ts b/apps/cua-spaces-desktop/src/model/agents.tsindex d09d2f64a7..bde9e62dd2 100644--- a/apps/cua-spaces-desktop/src/model/agents.ts+++ b/apps/cua-spaces-desktop/src/model/agents.ts@@ -124,6 +124,29 @@ export class PersistentAgents {return this.call("agent_events", args);}+ /** Starts a coding agent in a Space (`agent_start`): its answer as is. Saved+ * provider keys the harness reads are forwarded by the daemon unnamed. */+ async startRun(+ space: string,+ agent: string,+ prompt: string,+ o: { repo: string | null; branch: string | null; model: string | null; envFromHost: string[] },+ ): Promise<Json> {+ const args: Record<string, unknown> = { space, agent, prompt };+ if (o.repo) args.repo = o.repo;+ if (o.branch) args.branch = o.branch;+ if (o.model) args.model = o.model;+ if (o.envFromHost.length) args.env_from_host = o.envFromHost;+ return this.call("agent_start", args);+ }++ /** Sends a reply to a run (`agent_message`): queued while a turn runs, or the turn is interrupted first with `force`. */+ async sendMessage(space: string, runId: string, text: string, force: boolean): Promise<Json> {+ const args: Record<string, unknown> = { space, run_id: runId, text };+ if (force) args.force = true;+ return this.call("agent_message", args);+ }+/** The selected agent's home (files only, recursively), its routines, every* computer grant and the recent audit: the core's input records. The web* UI's `agents.detail` answers it. */diff --git a/apps/cua-spaces-desktop/test/agents-fixtures.ts b/apps/cua-spaces-desktop/test/agents-fixtures.tsindex 2204ff8924..697feeb6fe 100644--- a/apps/cua-spaces-desktop/test/agents-fixtures.ts+++ b/apps/cua-spaces-desktop/test/agents-fixtures.ts@@ -69,6 +69,10 @@ export class FakeAgentsTools {case "routine_set_enabled":case "routine_remove":return {};+ case "agent_start":+ return { run_id: "run-2", agent: args.agent, space: args.space, process_tag: "cua-agent-run-2", cwd: "/home/cua/run-2", notes: [], hint: "" };+ case "agent_message":+ return { delivered: true, run_id: args.run_id, status: "running", phase: "working", reason: "" };case "agent_events":return { run_id: args.run_id, status: "idle", phase: "idle", events: [], cursor: args.cursor, caught_up: true };default:@@ -175,7 +179,7 @@ export class FixtureAgentSetup implements AgentSetupRunning {/** The methods test/agents.test.ts checks (their answers need a daemon's tools, which the shared bridge test has none of). */export const AGENT_METHODS = [- "agents.list", "agents.runs", "agents.events", "agents.pause", "agents.resume", "agents.setup", "agents.configure", "agents.signIn", "agents.setupDriver",+ "agents.list", "agents.runs", "agents.events", "agents.start", "agents.message", "agents.pause", "agents.resume", "agents.setup", "agents.configure", "agents.signIn", "agents.setupDriver","agents.detail", "agents.readFile", "agents.restoreFile", "agents.addRoutine", "agents.setRoutine", "agents.removeRoutine","agents.allowComputer", "agents.revokeComputer","agentKeys.list", "agentKeys.set", "agentKeys.remove",diff --git a/apps/cua-spaces-desktop/test/agents.test.ts b/apps/cua-spaces-desktop/test/agents.test.tsindex e0c0073a11..5f4e88f9eb 100644--- a/apps/cua-spaces-desktop/test/agents.test.ts+++ b/apps/cua-spaces-desktop/test/agents.test.ts@@ -233,10 +233,26 @@ describe.skipIf(!built)("agents", () => {expect(await code(bridge, "agents.events", { runId: "r" })).toBe("bad_args");});+ it("starts a run in a Space and sends it a reply", async () => {+ const { bridge } = makeBridge();+ const run = (await call(bridge, "agents.start", { spaceId: "local:dev", agent: "claude-code", prompt: "Run the tests", repo: "https://github.com/trycua/cua" })) as Record<string, unknown>;+ expect(run).toMatchObject({ run_id: "run-2", agent: "claude-code" });+ expect(daemon.calls.at(-1)).toBe("agent_start");+ expect(daemon.args.at(-1)).toEqual({ space: "local:dev", agent: "claude-code", prompt: "Run the tests", repo: "https://github.com/trycua/cua" });+ expect(shapeProblems("agents.start", run)).toEqual([]);+ const sent = await call(bridge, "agents.message", { spaceId: "local:dev", runId: "run-2", text: "Use Python 3.13", force: true });+ expect(daemon.args.at(-1)).toEqual({ space: "local:dev", run_id: "run-2", text: "Use Python 3.13", force: true });+ expect(shapeProblems("agents.message", sent)).toEqual([]);+ expect(await code(bridge, "agents.start", { spaceId: "local:dev" })).toBe("bad_args");+ expect(await code(bridge, "agents.message", { spaceId: "local:dev", runId: "run-2" })).toBe("bad_args");+ });+it("is unsupported without the daemon or the coding-agent setup", async () => {const { bridge } = makeBridge({ tools: null, setup: null });expect(await code(bridge, "agents.list")).toBe("unsupported");expect(await code(bridge, "agents.events", { spaceId: "s", runId: "r", cursor: 0 })).toBe("unsupported");+ expect(await code(bridge, "agents.start", { spaceId: "s", agent: "claude-code", prompt: "hi" })).toBe("unsupported");+ expect(await code(bridge, "agents.message", { spaceId: "s", runId: "r", text: "hi" })).toBe("unsupported");expect(await code(bridge, "agents.setup")).toBe("unsupported");expect(await code(bridge, "agents.configure", {})).toBe("unsupported");expect(await code(bridge, "agents.setupDriver", { agents: ["codex"] })).toBe("unsupported");diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PersistentModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PersistentModel.swiftindex d31a60e9a8..dbb45bda21 100644--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PersistentModel.swift+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PersistentModel.swift@@ -149,6 +149,27 @@ public final class PersistentModel {return try await call("agent_events", args)}+ /// Starts a coding agent in a Space (`agent_start`): its answer as is+ /// (`run_id`, `agent`, `space`, ...). Saved provider keys the harness+ /// reads are forwarded by the daemon without being named here.+ func startRun(space: String, agent: String, prompt: String, repo: String?, branch: String?, model: String?,+ envFromHost: [String]) async throws -> [String: Any] {+ var args: [String: Any] = ["space": space, "agent": agent, "prompt": prompt]+ if let repo { args["repo"] = repo }+ if let branch { args["branch"] = branch }+ if let model { args["model"] = model }+ if !envFromHost.isEmpty { args["env_from_host"] = envFromHost }+ return try await call("agent_start", args)+ }++ /// Sends a reply to a run (`agent_message`): queued while a turn runs,+ /// or the turn is interrupted first with `force`.+ func sendMessage(space: String, runId: String, text: String, force: Bool) async throws -> [String: Any] {+ var args: [String: Any] = ["space": space, "run_id": runId, "text": text]+ if force { args["force"] = true }+ return try await call("agent_message", args)+ }+/// The selected agent's home (`agents/<name>/`, recursively, files only),/// its routines, every computer grant and the recent audit: the core's/// input records (`AgentsInput`). The web UI's `agents.detail` answers it.diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swiftindex 88e1084ba0..198ed42588 100644--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift@@ -75,6 +75,8 @@ final class WebUIBridge: NSObject, WKScriptMessageHandlerWithReply {"machines.list", "host.status","agents.list", "agents.runs", "agents.events", "agents.pause", "agents.resume","agents.setup", "agents.configure", "agents.signIn",+ // Start a run in a Space and reply to it (the daemon's agent_start, agent_message).+ "agents.start", "agents.message",// A persistent agent's Memory, Routines and Access (`PersistentModel`)."agents.detail", "agents.readFile", "agents.restoreFile", "agents.addRoutine", "agents.setRoutine","agents.removeRoutine", "agents.allowComputer", "agents.revokeComputer",@@ -310,7 +312,7 @@ final class WebUIBridge: NSObject, WKScriptMessageHandlerWithReply {return hostStatus()case "agents.list", "agents.runs", "agents.events", "agents.pause", "agents.resume",- "agents.setup", "agents.configure", "agents.signIn":+ "agents.setup", "agents.configure", "agents.signIn", "agents.start", "agents.message":return try await agents(method, args)case "checklist.get": return ["state": model.checklist.stored]@@ -718,6 +720,18 @@ final class WebUIBridge: NSObject, WKScriptMessageHandlerWithReply {let max = (args["max"] as? NSNumber)?.uint32Valuereturn try await persistent.runEvents(space: try string(args, "spaceId"), runId: try string(args, "runId"),cursor: cursor, max: max)+ case "agents.start":+ let spaceId = try string(args, "spaceId"), agent = try string(args, "agent"), prompt = try string(args, "prompt")+ guard persistent.canCallTools else { throw Failure.unsupported("Starting a run needs the cua daemon") }+ let text = { (key: String) in (args[key] as? String).flatMap { $0.isEmpty ? nil : $0 } }+ return try await persistent.startRun(space: spaceId, agent: agent, prompt: prompt, repo: text("repo"),+ branch: text("branch"), model: text("model"),+ envFromHost: (args["envFromHost"] as? [String]) ?? [])+ case "agents.message":+ let spaceId = try string(args, "spaceId"), runId = try string(args, "runId"), text = try string(args, "text")+ guard persistent.canCallTools else { throw Failure.unsupported("Replying to a run needs the cua daemon") }+ return try await persistent.sendMessage(space: spaceId, runId: runId, text: text,+ force: (args["force"] as? Bool) ?? false)case "agents.pause", "agents.resume":let name = try string(args, "name")guard !persistent.agentsState.busy else { throw Failure(code: "failed", message: "Another change is still running") }diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swiftindex f5e6ad359d..5838219bcc 100644--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift@@ -285,6 +285,8 @@ struct BridgeContractTests {"host.openSettings": "opens System Settings","host.joinWithCode": "runs the bundled cua; JoinWithCodeTests covers the arguments and bad args","agents.events": "needs the daemon's agent_events; WebUIHostTests checks it is unsupported without it",+ "agents.start": "starts a coding agent through the daemon; WebUIHostTests checks it is unsupported without it",+ "agents.message": "as agents.start (the daemon's agent_message)","agents.pause": "changes the fake's state for agents.list", "agents.resume": "as agents.pause","agents.setupDriver": "writes the coding agents' configs on the fixture setup",// Teleport needs the SDK's handle and a reachable Space; its answersdiff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swiftindex ce1cfb81bf..3e326e33b3 100644--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift@@ -176,7 +176,7 @@ struct WebUIHostTests {@Test func theContractsOperationsAreRouted() {for m in ["spaces.cancelCreate", "host.status", "keyvault.approve", "keyvault.deny", "keyvault.revokeGrant","agents.list", "agents.runs", "agents.events", "agents.pause", "agents.resume",- "agents.setup", "agents.configure", "agents.signIn"] {+ "agents.setup", "agents.configure", "agents.signIn", "agents.start", "agents.message"] {#expect(WebUIBridge.methods.contains(m), "\(m)")}}@@ -294,6 +294,10 @@ struct WebUIHostTests {#expect(await failure(bridge, "agents.setup", [:]) == "unsupported")#expect(await failure(bridge, "agents.runs", [:]) == "bad_args")#expect(await failure(bridge, "agents.pause", [:]) == "bad_args")+ #expect(await failure(bridge, "agents.start", ["spaceId": "s", "agent": "claude-code", "prompt": "hi"]) == "unsupported")+ #expect(await failure(bridge, "agents.start", ["spaceId": "s"]) == "bad_args")+ #expect(await failure(bridge, "agents.message", ["spaceId": "s", "runId": "r", "text": "hi"]) == "unsupported")+ #expect(await failure(bridge, "agents.message", ["spaceId": "s", "runId": "r"]) == "bad_args")}@Test func agentRunsAndSetupRowsAreTheCoresRecords() async throws {diff --git a/apps/cua-spaces-web/src/bridge/README.md b/apps/cua-spaces-web/src/bridge/README.mdindex e77c8224d4..d3e634483a 100644--- a/apps/cua-spaces-web/src/bridge/README.md+++ b/apps/cua-spaces-web/src/bridge/README.md@@ -104,6 +104,7 @@ Each is an existing Tauri command under a host-neutral name:| `agents.list` | `agents_tool` `persistent_agent_list` (snake_case mapped to `PersistentAgent`) || `agents.runs` `{spaceId}` | `list_space_agents` || `agents.events` `{spaceId, runId, cursor, max?}` | none yet: unsupported (`TAURI_UNSUPPORTED`) |+| `agents.start` `{spaceId, agent, prompt, repo?, branch?, model?, envFromHost?}`, `agents.message` `{spaceId, runId, text, force?}` | none yet: unsupported (`TAURI_UNSUPPORTED`) || `agents.pause` / `.resume` `{name}` | `agents_tool` `agent_pause` / `agent_resume` || `agents.setup` / `.configure` `{agents}` | `agent_setup_detect` / `agent_setup_configure` || `agents.detail`, `.readFile`, `.restoreFile`, `.addRoutine`, `.setRoutine`, `.removeRoutine`, `.allowComputer`, `.revokeComputer` | `agents_tool` (the tools `PersistentModel` runs; see `ops/agent-detail.ts`) |@@ -281,6 +282,8 @@ under a host-neutral name; nothing here is a new mechanism. Types are in| `agents.list` | `{}` | `PersistentAgent[]` | `persistent_agent_list` || `agents.runs` | `{ spaceId }` | `SpaceAgentRun[]` | `agent_list` (`list_space_agents`) || `agents.events` | `{ spaceId, runId, cursor, max? }` | `AgentEventsPage` (`{ run_id, status, phase, events, cursor, caught_up }`) | `agent_events` |+| `agents.start` | `{ spaceId, agent, prompt, repo?, branch?, model?, envFromHost? }` | `AgentStarted` (`{ run_id, agent, ... }`) | unsupported (no Tauri command starts a run) |+| `agents.message` | `{ spaceId, runId, text, force? }` | `AgentMessageSent` (`{ delivered, run_id, status, phase }`) | unsupported (no Tauri command sends to a run) || `agents.pause` / `agents.resume` | `{ name }` | `null` | `agent_pause` / `agent_resume` || `agents.setup` | `{}` | `AgentSetupRow[]` | `agent_setup_detect` (`cua agents status`) || `agents.configure` | `{ agents: string[] \| null }` | `AgentSetupRow[]` | `agent_setup_configure` (`cua agents setup`) |@@ -297,7 +300,7 @@ run whose conversation can't be read.| Host | Answers ||---|---|| demo | everything: four persistent agents (Claude Code, Codex, Hermes, OpenClaw) and five runs; `run-ada-7` writes its third turn live for about 25 s after start |-| tauri | everything except `agents.events` (the Tauri shell has no `agent_events` command, and `agents_tool` doesn't allow it) |+| tauri | everything except `agents.events`, `agents.start` and `agents.message` (the Tauri shell has no `agent_events`, `agent_start` or `agent_message` command, and `agents_tool` doesn't allow them) || electron | the Swift host's methods (below), as they are ported (`apps/cua-spaces-desktop/test/not-yet.ts`) || webkit | everything, from the SwiftUI app's own models (below); without the daemon the host answers `unsupported` |@@ -312,6 +315,8 @@ which is the `agent_events` result as is):| `agents.list` | `{}` | `PersistentAgentInput[]` | `PersistentModel.loadAgents` (`persistent_agent_list`) || `agents.runs` | `{ spaceId }` | `SpaceAgentRun[]` | `AgentRunsModel.refresh` || `agents.events` | `{ spaceId, runId, cursor, max? }` | `agent_events` result | the `agent_events` tool (`AgentRun.events(cursor:)` in the SDK) |+| `agents.start` | `{ spaceId, agent, prompt, repo?, branch?, model?, envFromHost? }` | `agent_start` result | the `agent_start` tool (`PersistentModel.startRun`); saved provider keys the harness reads go without being named |+| `agents.message` | `{ spaceId, runId, text, force? }` | `agent_message` result | the `agent_message` tool (`PersistentModel.sendMessage`) || `agents.pause` / `agents.resume` | `{ name }` | `null` | `PersistentModel.send(.pause/.resume)` || `agents.setup` / `agents.configure` | `{}` / `{ agents }` | `AgentSettingsRow[]` | the Settings "AI agents" rows || `agents.signIn` | `{ agent }` | `AgentSettingsRow[]` | the agent's own sign-in on this computer (`codex login`; `AgentSetupRunning.signIn`), returning once it runs |diff --git a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.tsindex 94fa105378..2557d1c7db 100644--- a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts+++ b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts@@ -43,6 +43,8 @@ export const DEMO_ARGS: { [K in OpName]: OpArgs<K> } = {"agents.list": {},"agents.runs": { spaceId: SPACE },"agents.events": { spaceId: SPACE, runId: "run-ada-7", cursor: 0 },+ "agents.start": { spaceId: SPACE, agent: "claude-code", prompt: "Run the tests" },+ "agents.message": { spaceId: SPACE, runId: "run-ada-7", text: "Use Python 3.13" },"agents.pause": { name: "ada" },"agents.resume": { name: "ada" },"agents.setup": {},diff --git a/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts b/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.tsindex e64b3ce83b..e3464be12c 100644--- a/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts+++ b/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts@@ -56,6 +56,8 @@ const ARGS: { [K in OpName]: OpArgs<K> } = {"agents.list": {},"agents.runs": { spaceId: "s1" },"agents.events": { spaceId: "s1", runId: "r1", cursor: 0 },+ "agents.start": { spaceId: "s1", agent: "claude-code", prompt: "Run the tests" },+ "agents.message": { spaceId: "s1", runId: "r1", text: "Use Python 3.13" },"agents.pause": { name: "ada" },"agents.resume": { name: "ada" },"agents.setup": {},diff --git a/apps/cua-spaces-web/src/bridge/adapters/demo-agents.ts b/apps/cua-spaces-web/src/bridge/adapters/demo-agents.tsindex 0d7deabef3..7ec08289f5 100644--- a/apps/cua-spaces-web/src/bridge/adapters/demo-agents.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/demo-agents.ts@@ -89,6 +89,16 @@ class Script {private tools = 0;constructor(private t: number) {}+ /** Writes after `events` (a reply to a run that already has turns). */+ static after(events: AgentEvent[], t: number): Script {+ const s = new Script(t);+ const last = events[events.length - 1];+ s.seq = last?.seq ?? 0;+ s.turn = events.reduce((n, e) => Math.max(n, e.turn), 0);+ s.tools = events.filter((e) => e.kind === "tool_call").length;+ return s;+ }+private push(e: Omit<AgentEvent, "seq" | "ts_ms" | "turn">, gapMs: number): this {this.t += gapMs;this.events.push({ seq: ++this.seq, ts_ms: this.t, turn: this.turn, ...e });@@ -161,6 +171,8 @@ export interface DemoRunRecord {live: boolean;/** Set when a pause cut the run short. */stoppedAt?: number;+ /** Shown as `needsYou` once every event is written, until a reply. */+ asks?: { title: string; detail: string };}const ONBOARDING_DIFF = `## Onboarding copy@@ -312,6 +324,59 @@ export function demoRunRecords(t0: number): DemoRunRecord[] {];}+/** A run started from the app (`agents.start`): it reads the task, gets the+ * code, runs the tests and answers, then asks to sign in to GitHub before it+ * posts anything, so the conversation shows every step. Written over about+ * twenty seconds from `t0`. */+export function demoStartedRun(space: string, runId: string, agent: string, prompt: string, t0: number, repo?: string): DemoRunRecord {+ const where = repo ?? "the project";+ const s = new Script(t0)+ .prompt(prompt)+ .thought("Get the code first, then find out how its tests run.", 1400)+ .tool("execute", `git clone ${where}`, "completed", "Cloned into ./project", 2600)+ .tool("read", "Read pyproject.toml", "completed", undefined, 900)+ .tool("execute", "python -m pip install -e '.[dev]'", "completed", "Installed 31 packages", 3400)+ .tool("execute", "python -m pytest -q", "completed", "70 passed in 41.2s", 4200)+ .say(+ "All **70 tests pass** on this clean computer (Python 3.12, 41 seconds). Nothing was skipped.\n\nTo post the result on your pull request I need to be signed in to GitHub here. Can you sign in, or should I skip posting?",+ 90,+ )+ .end();+ return {+ space,+ live: true,+ events: s.events,+ asks: { title: "Sign in to GitHub", detail: "The agent needs a GitHub sign-in on this computer to post the result." },+ run: {+ runId,+ agent,+ status: "running",+ reason: "a turn is running",+ summary: prompt.split("\n")[0]!.slice(0, 120),+ createdAt: Math.floor(t0 / 1000),+ phase: "thinking",+ turn: 1,+ },+ };+}++/** `agents.message` on a demo run: the reply is a new turn, answered in a few seconds. */+export function demoReply(rec: DemoRunRecord, text: string, t: number): void {+ const written = writtenEvents(rec, t);+ const s = Script.after(written, t).prompt(text);+ if (/sign|signed|logged|done|go ahead|yes/i.test(text)) {+ s.tool("execute", "gh pr comment --body-file result.md", "completed", "Posted a comment", 2200)+ .say("Posted the result on your pull request. You can keep this computer for the next check, or throw it away.", 80);+ } else {+ s.thought("Read the reply and carry on.", 800).say("Got it. I'll go on with that.", 80);+ }+ s.end();+ rec.events = [...written, ...s.events];+ rec.live = true;+ rec.stoppedAt = undefined;+ rec.asks = undefined;+}+/** The events written by `now`. */export function writtenEvents(rec: DemoRunRecord, now: number): AgentEvent[] {const until = rec.stoppedAt ?? now;@@ -327,6 +392,8 @@ export function runAt(rec: DemoRunRecord, now: number): SpaceAgentRun {const status: AgentRunStatus = done ? "idle" : "running";return {...rec.run,+ turn: last?.turn ?? rec.run.turn,+ needsYou: done && rec.asks ? rec.asks : null,status,reason: done ? "waiting for a follow-up" : "a turn is running",phase: done ? "waiting" : last?.kind === "message" ? "responding" : "tool",diff --git a/apps/cua-spaces-web/src/bridge/adapters/demo.ts b/apps/cua-spaces-web/src/bridge/adapters/demo.tsindex 5a8ac6da7a..97a5b77cd0 100644--- a/apps/cua-spaces-web/src/bridge/adapters/demo.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/demo.ts@@ -47,7 +47,7 @@ import type { CliInstallPlan } from "../contracts/first-run";import { unsupportedChecklistOps } from "../ops/checklist";import { demoTeleportHandlers } from "./demo/teleport";import { createDemoSettings } from "./demo/settings";-import { demoAgentSetup, demoPersistentAgents, demoRunRecords, runAt, writtenEvents, type DemoRunRecord } from "./demo-agents";+import { demoAgentSetup, demoPersistentAgents, demoReply, demoRunRecords, demoStartedRun, runAt, writtenEvents, type DemoRunRecord } from "./demo-agents";import { demoVolumeHandlers, demoVolumeState, type DemoVolumeState } from "./demo/volume";import { demoHostSetupHandlers, demoHostSetupState, type DemoHostSetupState } from "./demo/host-setup";import { demoSpaceDetailHandlers, demoSpaceDetailState, type DemoSpaceDetailState } from "./demo/space-detail";@@ -555,6 +555,24 @@ export function createDemoAdapter(options: DemoOptions = {}): DataAdapter & { recaught_up: page.length === after.length,};},+ "agents.start": async ({ spaceId, agent, prompt, repo }) => {+ const row = findRow(spaceId);+ if (row.powerState !== "running" || !row.reachable) throw new HostError(`${row.name} is not running`, "space_off");+ await wait(step);+ const runId = `run-${Math.random().toString(16).slice(2, 8)}`;+ state.runs.push(demoStartedRun(spaceId, runId, agent, prompt, now(), repo));+ emit({ type: "agents.changed" });+ return { run_id: runId, agent, space: spaceId };+ },+ "agents.message": async ({ spaceId, runId, text }) => {+ const rec = state.runs.find((r) => r.space === spaceId && r.run.runId === runId);+ if (!rec) throw new HostError(`no run ${runId} in ${spaceId}`, "not_found");+ const busy = runAt(rec, now()).status === "running";+ demoReply(rec, text, now());+ emit({ type: "agents.changed" });+ const run = runAt(rec, now());+ return { delivered: true, run_id: runId, status: run.status, phase: run.phase, reason: busy ? "queued after the current turn" : "" };+ },"agents.pause": async ({ name }) => {const agent = findAgent(name);await wait(step);diff --git a/apps/cua-spaces-web/src/bridge/adapters/tauri.ts b/apps/cua-spaces-web/src/bridge/adapters/tauri.tsindex 1db1da96c5..90776377ca 100644--- a/apps/cua-spaces-web/src/bridge/adapters/tauri.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/tauri.ts@@ -89,6 +89,8 @@ export const TAURI_EVENTS = {export const TAURI_UNSUPPORTED: readonly OpName[] = ["settings.choose","agents.events",+ "agents.start",+ "agents.message","agents.setupDriver","agents.signIn","host.joinWithCode",diff --git a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts b/apps/cua-spaces-web/src/bridge/adapters/webkit.tsindex c68c8b7ea1..97f8adec7b 100644--- a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/webkit.ts@@ -30,7 +30,7 @@import { Emitter, HostError, type DataAdapter } from "../adapter";import { hostOs, THIS_MACHINE, type HostOs } from "../host-os";import { electronTransport, webkitTransport, type HostTransport } from "../transport";-import type { AgentEventsPage, AgentSetupRow, PersistentAgent, SpaceAgentRun } from "../contracts/agents";+import type { AgentEventsPage, AgentMessageSent, AgentSetupRow, AgentStarted, PersistentAgent, SpaceAgentRun } from "../contracts/agents";import type { CancelOutcome, HostActionId, HostStatus, MachinePageRow, MachineRow, MachinesView, SpacePowerReport } from "../contracts/host";import type { HostWindow } from "../detect";import {@@ -649,6 +649,8 @@ export function createWebkitAdapter("agents.runs": async ({ spaceId }) => list(await request("agents.runs", { spaceId })) as SpaceAgentRun[],"agents.events": ({ spaceId, runId, cursor, max }) =>request<AgentEventsPage>("agents.events", max == null ? { spaceId, runId, cursor } : { spaceId, runId, cursor, max }),+ "agents.start": (a) => request<AgentStarted>("agents.start", { ...a }),+ "agents.message": (a) => request<AgentMessageSent>("agents.message", { ...a }),"agents.pause": async ({ name }) => {await request("agents.pause", { name });return null;diff --git a/apps/cua-spaces-web/src/bridge/contracts/agents.ts b/apps/cua-spaces-web/src/bridge/contracts/agents.tsindex 7c023c06cb..1d40274631 100644--- a/apps/cua-spaces-web/src/bridge/contracts/agents.ts+++ b/apps/cua-spaces-web/src/bridge/contracts/agents.ts@@ -91,6 +91,39 @@ export interface AgentEventsPage {caught_up: boolean;}+/** `agents.start`: a coding agent's run in a Space (`agent_start`). */+export interface AgentStartRequest {+ spaceId: string;+ /** Harness id (`claude-code`, `openai-codex`, ...). */+ agent: string;+ /** The task. */+ prompt: string;+ /** A Git URL cloned into the run's folder first, and its branch or tag. */+ repo?: string;+ branch?: string;+ model?: string;+ /** Provider key names to forward (values never cross the bridge). Saved keys the harness reads go without being named. */+ envFromHost?: string[];+}++/** `agent_start`'s answer (snake_case, as the tool answers). */+export interface AgentStarted {+ run_id: string;+ agent: string;+ space?: string;+ cwd?: string;+ hint?: string;+}++/** `agent_message`'s answer: queued while a turn runs, or a new turn. */+export interface AgentMessageSent {+ delivered: boolean;+ run_id: string;+ status: AgentRunStatus;+ phase: string;+ reason?: string;+}+/** A coding agent on this machine, as the SDK's agent setup sees it. */export interface AgentSetupRow {/** Setup id (`claude-code`, `codex`, `hermes`, `openclaw`, ...). */diff --git a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.jsonindex 28a7c82a09..b2d437305d 100644--- a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json+++ b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json@@ -5179,6 +5179,35 @@]}},+ "agents.message": {+ "type": "object",+ "properties": {+ "delivered": {+ "type": "boolean"+ },+ "run_id": {+ "type": "string"+ },+ "status": {+ "enum": [+ "running",+ "idle",+ "failed",+ "crashed",+ "unknown"+ ]+ },+ "phase": {+ "type": "string"+ }+ },+ "required": [+ "delivered",+ "run_id",+ "status",+ "phase"+ ]+ },"agents.pause": {"type": "null"},@@ -5314,6 +5343,21 @@"$ref": "#/$defs/AgentSetupRow"}},+ "agents.start": {+ "type": "object",+ "properties": {+ "run_id": {+ "type": "string"+ },+ "agent": {+ "type": "string"+ }+ },+ "required": [+ "run_id",+ "agent"+ ]+ },"checklist.get": {"type": "object","properties": {@@ -6953,6 +6997,35 @@]}},+ "agents.message": {+ "type": "object",+ "properties": {+ "delivered": {+ "type": "boolean"+ },+ "run_id": {+ "type": "string"+ },+ "status": {+ "enum": [+ "running",+ "idle",+ "failed",+ "crashed",+ "unknown"+ ]+ },+ "phase": {+ "type": "string"+ }+ },+ "required": [+ "delivered",+ "run_id",+ "status",+ "phase"+ ]+ },"agents.pause": {},"agents.readFile": {"$ref": "#/$defs/AgentOpenFile"@@ -7084,6 +7157,21 @@"$ref": "#/$defs/AgentSetupRow"}},+ "agents.start": {+ "type": "object",+ "properties": {+ "run_id": {+ "type": "string"+ },+ "agent": {+ "type": "string"+ }+ },+ "required": [+ "run_id",+ "agent"+ ]+ },"app.info": {"type": "object","properties": {diff --git a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts b/apps/cua-spaces-web/src/bridge/contracts/shapes.tsindex a5d14c5ff6..6a3df05e02 100644--- a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts+++ b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts@@ -911,6 +911,8 @@ export const OP_SHAPES: Record<OpName, Schema> = {cursor: num,caught_up: bool,}),+ "agents.start": object({ run_id: str, agent: str }),+ "agents.message": object({ delivered: bool, run_id: str, status: oneOf("running", "idle", "failed", "crashed", "unknown"), phase: str }),"agents.pause": nul,"agents.resume": nul,"agents.setup": agentSetupRows,@@ -1361,6 +1363,8 @@ export const WEBKIT_SHAPES: Partial<Record<WebkitMethod, Schema>> = {"agents.list": OP_SHAPES["agents.list"],"agents.runs": OP_SHAPES["agents.runs"],"agents.events": OP_SHAPES["agents.events"],+ "agents.start": OP_SHAPES["agents.start"],+ "agents.message": OP_SHAPES["agents.message"],"agents.pause": any,"agents.resume": any,"agents.setup": agentSetupRows,diff --git a/apps/cua-spaces-web/src/bridge/coverage.ts b/apps/cua-spaces-web/src/bridge/coverage.tsindex 9f8a658e6c..dd2ca1a0cd 100644--- a/apps/cua-spaces-web/src/bridge/coverage.ts+++ b/apps/cua-spaces-web/src/bridge/coverage.ts@@ -122,6 +122,16 @@ export const HOST_COVERAGE = {tauri: [],unsupported: { tauri: "no Tauri command reads agent_events, and agents_tool doesn't allow it" },},+ "agents.start": {+ webkit: { methods: ["agents.start"] },+ tauri: [],+ unsupported: { tauri: "no Tauri command starts a run, and agents_tool doesn't allow agent_start" },+ },+ "agents.message": {+ webkit: { methods: ["agents.message"] },+ tauri: [],+ unsupported: { tauri: "no Tauri command sends to a run, and agents_tool doesn't allow agent_message" },+ },"agents.pause": { webkit: { methods: ["agents.pause"] }, tauri: ["agents_tool"] },"agents.resume": { webkit: { methods: ["agents.resume"] }, tauri: ["agents_tool"] },"agents.setup": { webkit: { methods: ["agents.setup"] }, tauri: ["agent_setup_detect"] },diff --git a/apps/cua-spaces-web/src/bridge/protocol.ts b/apps/cua-spaces-web/src/bridge/protocol.tsindex 10e0a18757..b929a7de83 100644--- a/apps/cua-spaces-web/src/bridge/protocol.ts+++ b/apps/cua-spaces-web/src/bridge/protocol.ts@@ -28,7 +28,7 @@ import type {CreateProgress,TelemetryView,} from "./contracts/host";-import type { AgentEventsPage, AgentSetupRow, PersistentAgent, SpaceAgentRun } from "./contracts/agents";+import type { AgentEventsPage, AgentMessageSent, AgentSetupRow, AgentStarted, AgentStartRequest, PersistentAgent, SpaceAgentRun } from "./contracts/agents";import type { KeyvaultOverview, KvGrant, KvItem } from "./contracts/keyvault";import type { SpaceOs, SpaceRow } from "./contracts/spaces";import { NEW_SPACE_OPERATIONS, type NewSpaceOperations } from "./ops/new-space";@@ -271,6 +271,10 @@ export interface HostOperations"agents.runs": { args: { spaceId: string }; result: SpaceAgentRun[] };/** A run's events after `cursor` (`agent_events`; at most `max`, default 100). */"agents.events": { args: { spaceId: string; runId: string; cursor: number; max?: number }; result: AgentEventsPage };+ /** Starts a coding agent in a Space (`agent_start`). */+ "agents.start": { args: AgentStartRequest; result: AgentStarted };+ /** Sends a reply to a run (`agent_message`; `force` interrupts the turn first). */+ "agents.message": { args: { spaceId: string; runId: string; text: string; force?: boolean }; result: AgentMessageSent };/** Stops the run, saves the home, holds routines, suspends a local Space (`agent_pause`). */"agents.pause": { args: { name: string }; result: null };"agents.resume": { args: { name: string }; result: null };@@ -314,6 +318,8 @@ export const OPERATIONS = ["agents.list","agents.runs","agents.events",+ "agents.start",+ "agents.message","agents.pause","agents.resume","agents.setup",diff --git a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts b/apps/cua-spaces-web/src/bridge/webkit-protocol.tsindex 2b1ac758ba..9640a13924 100644--- a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts+++ b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts@@ -64,6 +64,8 @@ export const WEBKIT_METHODS = ["agents.list","agents.runs","agents.events",+ "agents.start",+ "agents.message","agents.pause","agents.resume","agents.setup",