Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.swift
index 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.swift
index 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)?.uint32Value
return 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.swift
index 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 answers
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 & { re
caught_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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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",