From 37e3c9b015587fd3ba2516591d8899ace2e847a4 Mon Sep 17 00:00:00 2001 From: Wing Date: Sun, 15 Nov 2026 04:58:06 +0000 Subject: [PATCH 1/7] Agents reach any online device's terminal; Cloud chats message every device MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Terminals: Zeron MCP's open_terminal, write_terminal, read_terminal and close_terminal open a shell on this device or any other online one (the engine's OpenTerminal … CloseTerminal, forwarded by targetDeviceId as the terminal panel does). The server follows each terminal's stream into an emulator, returning what it printed since last read (escapes removed), busy/exited, and the screen for full-screen programs. The engine opens them only to an agent whose chat runs with full access and no sandbox. list_devices says which devices are online. Cloud: a runner sees every device, chat, project and session row, reaches any chat's room and blobs, and dials or nudges any device as a client, so a Cloud chat's agent lists, messages and starts chats on the person's other devices and opens terminals there. It still never hosts another device's room, claims or re-homes another device's rows, or touches the user's own kinds; it may rename or archive any chat. An agent naming another device for a Cloud chat's child starts it there instead of on the Cloud machine. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + crates/engine/src/rpc.rs | 15 +- crates/engine/src/rpc/agent_gate.rs | 57 +- crates/engine/tests/cloud_rpc.rs | 21 + crates/mcp/Cargo.toml | 1 + crates/mcp/src/jsonrpc.rs | 8 +- crates/mcp/src/tools.rs | 17 +- crates/mcp/src/tools/terminals.rs | 855 ++++++++++++++++++ crates/rpc/src/lib.rs | 22 +- docs/design/cloud-attachments.md | 5 +- docs/design/cloud-device.md | 59 +- edge/src/attachment-blobs.ts | 6 +- edge/src/index.ts | 21 +- edge/src/registry-room.ts | 62 +- edge/src/registry-runner.test.ts | 61 +- edge/src/registry-runner.ts | 97 +- edge/src/runner-access.ts | 104 --- edge/src/runner-policy.test.ts | 17 +- edge/src/runner-policy.ts | 28 +- .../workerd/attachment-blobs.workerd.test.ts | 36 +- .../workerd/cloud-delegates.workerd.test.ts | 31 +- edge/test/workerd/cloud.workerd.test.ts | 6 +- edge/test/workerd/fixture.ts | 15 +- .../workerd/runner-boundary.workerd.test.ts | 99 +- 24 files changed, 1191 insertions(+), 453 deletions(-) create mode 100644 crates/mcp/src/tools/terminals.rs delete mode 100644 edge/src/runner-access.ts diff --git a/Cargo.lock b/Cargo.lock index 3e914104a..cebcaddc5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -13823,6 +13823,7 @@ dependencies = [ "zeron-doc", "zeron-proto", "zeron-rpc", + "zeron-term", "zeron-theme", "zeron-visual", ] diff --git a/crates/engine/src/rpc.rs b/crates/engine/src/rpc.rs index 4914e63ba..8eb582620 100644 --- a/crates/engine/src/rpc.rs +++ b/crates/engine/src/rpc.rs @@ -1266,12 +1266,14 @@ impl EngineRpc { /// Where a chat runs when it runs on Cloud: its own new session machine /// (minted by the edge, idempotent per chat) cloning the project's GitHub /// repository — or, for a side chat whose parent runs on a session - /// machine, that same machine (they share files). `None` = not Cloud; - /// create normally. + /// machine, that same machine (they share files), unless an agent names + /// another device for it (a Cloud chat's agent starting a chat on the + /// person's computer). `None` = not Cloud; create normally. async fn cloud_chat_host( &self, chat_id: &str, space_id: Option<&str>, + device_id: Option<&str>, parent_chat_id: Option<&str>, branch: Option<&str>, cloud: bool, @@ -1279,12 +1281,18 @@ impl EngineRpc { ) -> Result, RpcError> { let failed = |e: crate::EngineError| RpcError::Failed(e.to_string()); let on_cloud = |device_id: &str| device_id.starts_with(zeron_proto::CLOUD_DEVICE_PREFIX); + // An agent's chat on another of the person's devices runs there. + let elsewhere = |parent: &str| { + matches!(zeron_rpc::caller(), zeron_rpc::Caller::Agent { .. }) + && device_id.is_some_and(|device| !device.is_empty() && device != parent) + }; // A side chat of a Cloud chat shares its machine (and files), unless - // it asks for a Cloud session of its own. + // it asks for a Cloud session of its own or an agent puts it elsewhere. if !cloud && let Some(parent) = parent_chat_id && let Some(parent) = self.workspace.chat(parent).map_err(failed)? && on_cloud(&parent.device_id) + && !elsewhere(&parent.device_id) { return Ok(Some(CloudHost { device_id: parent.device_id, @@ -4268,6 +4276,7 @@ impl RpcService for EngineRpc { && let Some(host) = Box::pin(self.cloud_chat_host( chat_id, space_id.as_deref(), + device_id.as_deref(), parent_chat_id.as_deref(), branch.as_deref().filter(|b| !b.is_empty()), *cloud, diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index 018fded07..f4048ada1 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -14,6 +14,11 @@ //! a chat it made, what it would itself have to ask the person for. //! - What it writes into a chat carries Zeron's header naming the sending //! chat, built here; a header in the text can't claim another chat. +//! - A terminal (on this device or any other of the person's) is a shell +//! as the person, with no sandbox: only an agent whose own chat runs with +//! full access and no sandbox opens, types into or reads one. Anything +//! less would let a supervised or sandboxed agent do through a shell what +//! it would itself have to ask for. //! //! The calling chat is the one its MCP server names (`x-zeron-chat`): the //! engine sets that server's environment, so a sandboxed agent can't change @@ -82,7 +87,16 @@ impl EngineRpc { params["chatId"] = json!(chat); return Ok(params); } - if !matches!(method, methods::MUTATE | methods::QUEUE_MESSAGE | methods::QUEUE_COMMAND) { + let terminal = matches!( + method, + methods::OPEN_TERMINAL + | methods::SUBSCRIBE_TERMINAL + | methods::WRITE_TERMINAL + | methods::RESIZE_TERMINAL + | methods::CLOSE_TERMINAL + | methods::TERMINAL_STATUS + ); + if !terminal && !matches!(method, methods::MUTATE | methods::QUEUE_MESSAGE | methods::QUEUE_COMMAND) { return Ok(params); } let chats = self.workspace.read_chats().unwrap_or_default(); @@ -94,6 +108,20 @@ impl EngineRpc { text, ) }; + if terminal { + let unconfined = calling.as_ref().is_none_or(|c| { + c.ceiling.is_none_or(|(sandbox, access)| { + sandbox == SandboxLevel::DangerFullAccess && access == AccessMode::FullAccess + }) + }); + return if unconfined { + Ok(params) + } else { + Err(refused( + "A terminal is a shell with no sandbox: only a chat with full access and no sandbox uses one. Ask the person to give this chat full access, or to run it themselves", + )) + }; + } match method { methods::MUTATE => match params["op"].as_str().unwrap_or_default() { "createChat" => { @@ -290,6 +318,33 @@ mod tests { core.sessions.shutdown().await; } + /// A terminal, here or on another device, only for an agent whose chat + /// runs with full access and no sandbox; the person's own calls pass. + #[tokio::test] + async fn only_an_unconfined_agent_uses_a_terminal() { + let (_temp, core) = core().await; + chat(&core, "careful", "Careful", "read-only", "supervised").await; + chat(&core, "sandboxed", "Sandboxed", "workspace-write", "full-access").await; + chat(&core, "free", "Free", "danger-full-access", "full-access").await; + let rpc = core.rpc_service(); + let open = json!({"chatId":"x", "cols":80, "rows":24, "targetDeviceId":"laptop"}); + for method in [methods::OPEN_TERMINAL, methods::WRITE_TERMINAL, methods::SUBSCRIBE_TERMINAL, methods::TERMINAL_STATUS] { + for who in ["careful", "sandboxed", "nowhere"] { + let refused = with_caller(agent(who), async { rpc.agent_gate(method, open.clone()) }).await; + assert!( + matches!(&refused, Err(zeron_rpc::RpcError::Failed(m)) if m.contains("full access and no sandbox")), + "{who} {method}: {refused:?}" + ); + } + let allowed = with_caller(agent("free"), async { rpc.agent_gate(method, open.clone()) }).await.unwrap(); + assert_eq!(allowed, open, "{method}"); + // A server with no chat (set up by hand) is capped by nothing. + with_caller(Caller::Agent { chat: None }, async { rpc.agent_gate(method, open.clone()) }).await.unwrap(); + assert_eq!(rpc.agent_gate(method, open.clone()).unwrap(), open); + } + core.sessions.shutdown().await; + } + /// An agent can't raise a chat's access after the fact, nor delete. #[tokio::test] async fn an_agent_cannot_change_a_chats_config() { diff --git a/crates/engine/tests/cloud_rpc.rs b/crates/engine/tests/cloud_rpc.rs index 2c90e7c81..79af21da4 100644 --- a/crates/engine/tests/cloud_rpc.rs +++ b/crates/engine/tests/cloud_rpc.rs @@ -544,6 +544,27 @@ async fn chats_run_on_cloud_get_their_own_session_machines() { assert_eq!(side.device_id, "cloud-s-chat-1"); assert_eq!(side.cwd.as_deref(), Some("/home/user/app")); + // An agent naming another of the person's devices starts its chat + // there; naming the parent's machine, or none, it shares that machine. + use zeron_rpc::RpcService as _; + let rpc = core.rpc_service(); + let agent_creates = |chat_id: &str, device: Option| { + let mut op = serde_json::json!({ + "op": "createChat", "chatId": chat_id, "spaceId": "sp-app", "parentChatId": "chat-1", + "config": { "harness": "mock", "sandbox": "workspace-write", "access": "full-access" }, + }); + if let Some(device) = device { + op["deviceId"] = serde_json::json!(device); + } + zeron_rpc::with_caller(zeron_rpc::Caller::Agent { chat: None }, rpc.handle(methods::MUTATE, op)) + }; + agent_creates("side-here", Some(core.workspace.device_id().to_owned())).await.unwrap(); + assert_eq!(core.workspace.chat("side-here").unwrap().unwrap().device_id, core.workspace.device_id()); + agent_creates("side-there", Some("cloud-s-chat-1".into())).await.unwrap(); + assert_eq!(core.workspace.chat("side-there").unwrap().unwrap().device_id, "cloud-s-chat-1"); + agent_creates("side-unnamed", None).await.unwrap(); + assert_eq!(core.workspace.chat("side-unnamed").unwrap().unwrap().device_id, "cloud-s-chat-1"); + // Without Cloud picked, the same project runs here. create( &client, diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.toml index c723676b5..d804a765f 100644 --- a/crates/mcp/Cargo.toml +++ b/crates/mcp/Cargo.toml @@ -9,6 +9,7 @@ publish.workspace = true zeron-proto.workspace = true zeron-doc.workspace = true zeron-rpc.workspace = true +zeron-term.workspace = true tokio.workspace = true serde.workspace = true serde_json.workspace = true diff --git a/crates/mcp/src/jsonrpc.rs b/crates/mcp/src/jsonrpc.rs index f381d325f..1f8177b6c 100644 --- a/crates/mcp/src/jsonrpc.rs +++ b/crates/mcp/src/jsonrpc.rs @@ -60,7 +60,13 @@ on (a claude-code agent may hand a task to codex, and the reverse). Pass \ `harness` (and a model from `list_models`) to `create_chat` to choose one. \ Delegation is one level deep: a chat that has a parent cannot create chats. \ Pass `cloud: true` to run a child on a Cloud machine of its own (Codex or Claude Code); \ -from a Cloud chat it clones the same repository, and without `cloud` it shares your machine.\n\ +from a Cloud chat it clones the same repository, and without `cloud` it shares your machine \ +unless you name another device or project. From any chat, Cloud or not, you can list and \ +message chats on every one of the person's devices.\n\ +\n\ +`open_terminal` opens a shell on any online device (see `list_devices`); type into it with \ +`write_terminal`, read it with `read_terminal`, and close it with `close_terminal`. Only a chat \ +with full access and no sandbox may use one.\n\ \n\ When a chart, table, diagram, dashboard, or 3D view would say more than prose and \ `show_visual` is available, write a Luau visual script and show it with `show_visual` before \ diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index d7d8165ab..6a857df60 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -23,6 +23,7 @@ use crate::transcript::{RenderOptions, RenderedMessage, render_entries}; use crate::zeron::{HarnessInfo, TranscriptFollow, TurnOutcome, Zeron, session_for, short}; mod plugins; +mod terminals; mod themes; pub use plugins::ListedTool; pub(crate) use plugins::is_plugin_tool_name; @@ -32,6 +33,8 @@ const MAX_BATCH: usize = 32; /// Cloud runs these agents (Codex and Claude Code): a Cloud chat's harness. const CLOUD_HARNESSES: &[HarnessId] = &[HarnessId::ClaudeCode, HarnessId::Codex]; const DEFAULT_WAIT: Duration = Duration::from_secs(600); +/// A device seen this recently is online (the app's sidebar says the same). +const ONLINE_SECS: i64 = 70; const MAX_WAIT: Duration = Duration::from_secs(3600); #[derive(Debug, Clone, Serialize)] @@ -50,6 +53,8 @@ pub struct Tools { /// Which plugin tools the client was last shown ([`Self::list_all`], /// [`Self::watch_plugin_tools`]). plugins: plugins::PluginState, + /// The terminals this connection follows ([`terminals`]). + terminal_state: terminals::TerminalState, } fn chat_key_schema(extra: Value) -> Value { @@ -82,7 +87,7 @@ fn catalog() -> Vec { }, ToolDef { name: "list_devices", - description: "Devices in this workspace (the local engine's device is flagged). Chats and projects are hosted on a device.", + description: "Devices in this workspace (the local engine's device is flagged). Chats and projects are hosted on a device. `online`: seen in the last 70 s (always true for this one); open_terminal reaches any online device.", input_schema: json!({ "type": "object", "properties": {} }), }, ToolDef { @@ -150,7 +155,7 @@ fn catalog() -> Vec { "title": { "type": "string", "description": "Sidebar title. Otherwise the engine titles it from the first exchange." }, "branch": { "type": "string", "description": "Branch label to record on the chat." }, "cwd": { "type": "string", "description": "Working directory override (an existing worktree path). Defaults to the project folder." }, - "cloud": { "type": "boolean", "default": false, "description": "Run on a Cloud machine of its own (cloning the project's GitHub repository) instead of the project's device. From a Cloud chat, the child clones the same repository; without cloud it shares this machine." }, + "cloud": { "type": "boolean", "default": false, "description": "Run on a Cloud machine of its own (cloning the project's GitHub repository) instead of the project's device. From a Cloud chat, the child clones the same repository; without cloud it shares this machine, unless device or project names another of the person's devices." }, "prompt": { "type": "string", "description": "First message to send right away." }, "wait": { "type": "boolean", "default": false, "description": "With prompt: block until the first turn finishes and return the reply." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 600 } @@ -299,6 +304,7 @@ fn catalog() -> Vec { }); tools.extend(plugins::catalog()); tools.extend(themes::catalog()); + tools.extend(terminals::catalog()); tools } @@ -817,6 +823,7 @@ impl Tools { zeron, pending_turns: Default::default(), plugins: Default::default(), + terminal_state: Default::default(), } } @@ -892,6 +899,9 @@ impl Tools { plugins::EXPORT_TEMPLATE | plugins::IMPORT_TEMPLATE => { return self.template_packages(name, args).await; } + terminal if terminals::NAMES.contains(&terminal) => { + return self.terminals(terminal, args).await; + } theme if themes::NAMES.contains(&theme) => { return self.themes(theme, args).await; } @@ -966,12 +976,15 @@ impl Tools { async fn list_devices(&self) -> anyhow::Result { let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; + let now = chrono::Utc::now(); Ok(json!({ "devices": devices.iter().map(|d| json!({ "id": d.id, "name": d.name, "platform": d.platform, "local": d.id == local, + "online": d.id == local + || d.last_seen_at.is_some_and(|at| now - at <= chrono::Duration::seconds(ONLINE_SECS)), "lastSeenAt": d.last_seen_at, "version": d.version, })).collect::>() diff --git a/crates/mcp/src/tools/terminals.rs b/crates/mcp/src/tools/terminals.rs new file mode 100644 index 000000000..2991ec986 --- /dev/null +++ b/crates/mcp/src/tools/terminals.rs @@ -0,0 +1,855 @@ +//! Terminal tools: a shell on this device or any other of the person's +//! online devices (the engine's `OpenTerminal` … `CloseTerminal`, sent to +//! another device by `targetDeviceId` as the app's terminal panel does). +//! +//! This server follows each terminal it opens (or is pointed at) with a +//! `SubscribeTerminal` stream, folding its output into an emulator so a tool +//! can return both what was printed since it last looked (escape sequences +//! taken out) and the screen as a person would see it (what a full-screen +//! program like `top` or `vim` shows). The engine lets an agent do this only +//! from a chat with full access and no sandbox (rpc/agent_gate.rs): a shell +//! is neither. + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use base64::Engine as _; +use serde::Deserialize; +use serde_json::{Value, json}; +use zeron_proto::TerminalEvent; +use zeron_rpc::methods; +use zeron_term::emulator::Emulator; + +use super::{ToolDef, Tools}; +use crate::zeron::Zeron; + +pub(super) const OPEN_TERMINAL: &str = "open_terminal"; +pub(super) const WRITE_TERMINAL: &str = "write_terminal"; +pub(super) const READ_TERMINAL: &str = "read_terminal"; +pub(super) const CLOSE_TERMINAL: &str = "close_terminal"; + +pub(super) const NAMES: [&str; 4] = [OPEN_TERMINAL, WRITE_TERMINAL, READ_TERMINAL, CLOSE_TERMINAL]; + +const DEFAULT_COLS: u16 = 120; +const DEFAULT_ROWS: u16 = 40; +/// How long a write waits for output by default, and the most any wait may. +const DEFAULT_WRITE_WAIT: Duration = Duration::from_secs(2); +const MAX_WAIT: Duration = Duration::from_secs(300); +/// Output quiet this long after it last changed reads as settled. +const QUIET: Duration = Duration::from_millis(500); +const POLL: Duration = Duration::from_millis(50); +/// The most unread output kept (the newest); older is counted, not kept. +const MAX_UNREAD: usize = 64 * 1024; +/// The most output one reply carries (the newest). +const MAX_REPLY_OUTPUT: usize = 16 * 1024; +/// Resubscribe attempts in a row before a terminal reads as lost. +const MAX_RESUBSCRIBES: u32 = 5; + +fn terminal_schema() -> Value { + json!({ "type": "string", "description": "Terminal id, from open_terminal." }) +} + +fn device_schema() -> Value { + json!({ "type": "string", "description": "The terminal's device (id or exact name). Only needed for a terminal this server didn't open (one the person opened, or one from before a restart): one it opened, it remembers." }) +} + +fn wait_schema(default_ms: u64) -> Value { + json!({ + "type": "integer", "minimum": 0, "maximum": MAX_WAIT.as_millis() as u64, "default": default_ms, + "description": "Wait up to this many milliseconds for output: the reply comes once output has been quiet for half a second, `until` appears, or the shell exits." + }) +} + +pub(super) fn catalog() -> Vec { + vec![ + ToolDef { + name: OPEN_TERMINAL, + description: "Open a shell on any of the person's online devices: this one when `device` is omitted, or another (see list_devices; a Cloud machine must be awake). Returns the terminal's id, its device, folder and shell. Type into it with write_terminal, read it with read_terminal, and close it with close_terminal when you're done. It runs as the person, with no sandbox, so only a chat with full access may open one.", + input_schema: json!({ + "type": "object", + "properties": { + "device": { "type": "string", "description": "Device id or exact name. Omit for this device." }, + "cwd": { "type": "string", "description": "Folder to start in, on that device (default: your chat's folder on its own device, else home)." }, + "cols": { "type": "integer", "minimum": 20, "maximum": 500, "default": DEFAULT_COLS }, + "rows": { "type": "integer", "minimum": 5, "maximum": 200, "default": DEFAULT_ROWS } + } + }), + }, + ToolDef { + name: WRITE_TERMINAL, + description: "Type into a terminal, then wait for what it prints. `input` is sent as typed, then Enter unless `enter` is false: send a command as `input`, or keys with `enter: false` (\\u0003 is Ctrl-C, \\u0004 Ctrl-D, \\u001b Esc, \\u001b[A the Up arrow). Returns `output` (what it printed since you last read it, escape sequences removed), `busy` (a program other than the shell is running), `exited` once the shell has ended, and `screen` (the visible screen, as text) when asked for or while a full-screen program shows. For a long command, pass `until` (text its end prints, such as a prompt) and a longer `wait_ms`, or read_terminal again later.", + input_schema: json!({ + "type": "object", + "properties": { + "terminal": terminal_schema(), + "input": { "type": "string", "description": "What to type." }, + "enter": { "type": "boolean", "default": true, "description": "Press Enter after the input." }, + "wait_ms": wait_schema(DEFAULT_WRITE_WAIT.as_millis() as u64), + "until": { "type": "string", "description": "Return as soon as the output since this call contains this text." }, + "screen": { "type": "boolean", "default": false, "description": "Include the visible screen." }, + "device": device_schema() + }, + "required": ["terminal", "input"] + }), + }, + ToolDef { + name: READ_TERMINAL, + description: "What a terminal printed since you last read it (escape sequences removed), whether a program is still running in it (`busy`) or the shell has exited, and optionally the visible screen. Pass `wait_ms` to wait for more output first. Works on a terminal the person opened too, given its id and device.", + input_schema: json!({ + "type": "object", + "properties": { + "terminal": terminal_schema(), + "wait_ms": wait_schema(0), + "until": { "type": "string", "description": "With wait_ms: return as soon as the unread output contains this text." }, + "screen": { "type": "boolean", "default": false, "description": "Include the visible screen." }, + "device": device_schema() + }, + "required": ["terminal"] + }), + }, + ToolDef { + name: CLOSE_TERMINAL, + description: "Close a terminal, ending its shell and anything running in it.", + input_schema: json!({ + "type": "object", + "properties": { "terminal": terminal_schema(), "device": device_schema() }, + "required": ["terminal"] + }), + }, + ] +} + +/// The terminals this server follows, by id. +#[derive(Default)] +pub(super) struct TerminalState { + followed: tokio::sync::Mutex>>, +} + +/// One terminal, as this server follows it. +struct Followed { + id: String, + /// `None`: this engine's own device. + target: Option, + device: Value, + screen: Mutex, + task: Mutex>>, +} + +impl Drop for Followed { + fn drop(&mut self) { + if let Some(task) = self.task.lock().ok().and_then(|mut t| t.take()) { + task.abort(); + } + } +} + +struct Screen { + emulator: Emulator, + /// Output not yet returned, escape sequences removed. + unread: String, + /// Characters dropped from the front of `unread` past [`MAX_UNREAD`]. + dropped: usize, + /// Bumped by every output chunk (a wait's "since this call" mark). + total: u64, + last_seq: u64, + last_output: Option, + exit: Option, + /// Why the stream was lost, when it was. + lost: Option, + /// The host leaves terminal queries to its viewers (an older engine). + answer_queries: bool, + /// Stripping state carried between chunks. + strip: Strip, +} + +#[derive(Deserialize)] +struct OpenArgs { + device: Option, + cwd: Option, + cols: Option, + rows: Option, +} + +#[derive(Deserialize)] +struct WriteArgs { + terminal: String, + input: String, + #[serde(default = "yes")] + enter: bool, + wait_ms: Option, + until: Option, + #[serde(default)] + screen: bool, + device: Option, +} + +#[derive(Deserialize)] +struct ReadArgs { + terminal: String, + wait_ms: Option, + until: Option, + #[serde(default)] + screen: bool, + device: Option, +} + +#[derive(Deserialize)] +struct CloseArgs { + terminal: String, + device: Option, +} + +fn yes() -> bool { + true +} + +fn parse(args: Value) -> Result { + let args = if args.is_null() { json!({}) } else { args }; + serde_json::from_value(args).map_err(|e| format!("invalid arguments: {e}")) +} + +fn wait_of(ms: Option, default: Duration) -> Duration { + ms.map(Duration::from_millis).unwrap_or(default).min(MAX_WAIT) +} + +impl Tools { + pub(super) async fn terminals(&self, tool: &str, args: Value) -> Result { + let result = match tool { + OPEN_TERMINAL => self.open_terminal(parse(args)?).await, + WRITE_TERMINAL => self.write_terminal(parse(args)?).await, + READ_TERMINAL => self.read_terminal(parse(args)?).await, + _ => self.close_terminal(parse(args)?).await, + }; + result.map_err(|e| format!("{e:#}")) + } + + /// The device to send a call to (`None`: this engine's), and how a reply + /// names it. + async fn terminal_device(&self, key: Option<&str>) -> anyhow::Result<(Option, Value)> { + let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; + let id = self.zeron.resolve_device_id(key).await?; + let name = devices.iter().find(|d| d.id == id).map(|d| d.name.clone()); + let named = json!({ "id": id, "name": name, "local": id == local }); + Ok(((id != local).then_some(id), named)) + } + + async fn open_terminal(&self, args: OpenArgs) -> anyhow::Result { + let (target, device) = self.terminal_device(args.device.as_deref()).await?; + let cols = args.cols.unwrap_or(DEFAULT_COLS).clamp(20, 500); + let rows = args.rows.unwrap_or(DEFAULT_ROWS).clamp(5, 200); + // On its own chat's device, the terminal is the chat's (its folder + // by default, its activity); elsewhere that folder means nothing. + let origin = self.zeron.origin(); + let own_device = match (&origin.device_id, &target) { + (_, None) => true, + (Some(here), Some(there)) => here == there, + (None, Some(_)) => false, + }; + let chat_id = match origin.chat_id.as_deref() { + Some(chat) if own_device => chat.to_owned(), + Some(chat) => format!("agent-terminal:{chat}"), + None => "agent-terminal".to_owned(), + }; + let mut params = json!({ "chatId": chat_id, "cols": cols, "rows": rows }); + if let Some(cwd) = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()) { + params["cwd"] = json!(cwd); + } + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); + } + let session: zeron_proto::TerminalSession = + serde_json::from_value(self.zeron.call_rpc(methods::OPEN_TERMINAL, params).await.map_err(said)?)?; + let followed = self + .follow(&session.id, target, device.clone(), cols, rows, !session.host_replies) + .await; + // The prompt, usually. + let mut reply = self.settled(&followed, Duration::from_secs(1), None, false).await; + reply["cwd"] = json!(session.cwd); + reply["shell"] = json!(session.shell); + Ok(reply) + } + + async fn write_terminal(&self, args: WriteArgs) -> anyhow::Result { + let followed = self.followed(&args.terminal, args.device.as_deref()).await?; + let mut input = args.input; + if args.enter { + input.push('\r'); + } + anyhow::ensure!(!input.is_empty(), "nothing to type: input is empty and enter is false"); + let wait = wait_of(args.wait_ms, DEFAULT_WRITE_WAIT); + // Only output after the keys count toward `until`. + let mark = followed.screen.lock().map(|s| s.unread.len()).unwrap_or(0); + let mut params = json!({ + "terminalId": followed.id, + "data": base64::engine::general_purpose::STANDARD.encode(input.as_bytes()), + }); + if let Some(target) = &followed.target { + params["targetDeviceId"] = json!(target); + } + self.zeron.call_rpc(methods::WRITE_TERMINAL, params).await.map_err(said)?; + let until = args.until.as_deref().filter(|u| !u.is_empty()).map(|u| (u, mark)); + Ok(self.settled(&followed, wait, until, args.screen).await) + } + + async fn read_terminal(&self, args: ReadArgs) -> anyhow::Result { + let followed = self.followed(&args.terminal, args.device.as_deref()).await?; + let wait = wait_of(args.wait_ms, Duration::ZERO); + let until = args.until.as_deref().filter(|u| !u.is_empty()).map(|u| (u, 0)); + Ok(self.settled(&followed, wait, until, args.screen).await) + } + + async fn close_terminal(&self, args: CloseArgs) -> anyhow::Result { + let known = self.terminal_state.followed.lock().await.remove(&args.terminal); + let target = match &known { + Some(followed) => followed.target.clone(), + None => self.terminal_device(args.device.as_deref()).await?.0, + }; + let mut params = json!({ "terminalId": args.terminal }); + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); + } + self.zeron.call_rpc(methods::CLOSE_TERMINAL, params).await.map_err(said)?; + Ok(json!({ "terminal": args.terminal, "closed": true })) + } + + /// A terminal this server follows, or — named with its device — one it + /// starts following now (its output so far replays from the start). + async fn followed(&self, id: &str, device: Option<&str>) -> anyhow::Result> { + if let Some(followed) = self.terminal_state.followed.lock().await.get(id) { + return Ok(followed.clone()); + } + let (target, named) = self.terminal_device(device).await?; + // Make sure it's there before following it. + let mut params = json!({ "terminalId": id }); + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); + } + self.zeron.call_rpc(methods::TERMINAL_STATUS, params).await.map_err(|e| { + anyhow::anyhow!( + "no terminal {id} on {}: {} (open one with open_terminal; for one this server didn't open, pass its device)", + named["name"].as_str().unwrap_or("this device"), + said(e) + ) + })?; + Ok(self + .follow(id, target, named, DEFAULT_COLS, DEFAULT_ROWS, false) + .await) + } + + async fn follow( + &self, + id: &str, + target: Option, + device: Value, + cols: u16, + rows: u16, + answer_queries: bool, + ) -> Arc { + let followed = Arc::new(Followed { + id: id.to_owned(), + target, + device, + screen: Mutex::new(Screen { + emulator: Emulator::new(cols, rows), + unread: String::new(), + dropped: 0, + total: 0, + last_seq: 0, + last_output: None, + exit: None, + lost: None, + answer_queries, + strip: Strip::default(), + }), + task: Mutex::new(None), + }); + let task = tokio::spawn(stream_into(self.zeron.clone(), Arc::downgrade(&followed))); + if let Ok(mut slot) = followed.task.lock() { + *slot = Some(task); + } + self.terminal_state + .followed + .lock() + .await + .insert(id.to_owned(), followed.clone()); + followed + } + + /// Wait as asked, then take the unread output and say where the terminal + /// stands. + async fn settled(&self, followed: &Followed, wait: Duration, until: Option<(&str, usize)>, screen: bool) -> Value { + let start = Instant::now(); + let deadline = start + wait; + let first_total = followed.screen.lock().map(|s| s.total).unwrap_or(0); + while Instant::now() < deadline { + let done = match followed.screen.lock() { + Ok(s) => { + s.exit.is_some() + || s.lost.is_some() + || match until { + Some((text, mark)) => s.unread.get(mark.min(s.unread.len())..).is_some_and(|new| new.contains(text)), + None => s.total != first_total && s.last_output.is_some_and(|at| at.elapsed() >= QUIET), + } + } + Err(_) => true, + }; + if done { + break; + } + tokio::time::sleep(POLL).await; + } + let busy = self.busy(followed).await; + let Ok(mut s) = followed.screen.lock() else { + return json!({ "terminal": followed.id, "error": "this terminal's state was lost" }); + }; + let unread = std::mem::take(&mut s.unread); + let dropped = std::mem::take(&mut s.dropped); + let (output, cut) = newest(&unread, MAX_REPLY_OUTPUT); + let mut reply = json!({ + "terminal": followed.id, + "device": followed.device, + "output": output, + }); + if dropped + cut > 0 { + reply["outputDropped"] = json!(format!("{} earlier characters not shown", dropped + cut)); + } + if let Some(busy) = busy { + reply["busy"] = json!(busy); + } + if let Some(exit) = &s.exit { + reply["exited"] = exit.clone(); + } + if let Some(lost) = &s.lost { + reply["lost"] = json!(lost); + } + if let Some((text, _)) = until + && !output.contains(text) + && s.exit.is_none() + { + reply["untilSeen"] = json!(false); + } + if screen || s.emulator.alt_screen() { + reply["screen"] = json!(screen_text(&s.emulator)); + if let Some(cursor) = s.emulator.cursor() { + reply["cursor"] = json!({ "row": cursor.row, "col": cursor.col }); + } + } + reply + } + + /// Whether a program other than the shell runs in it; `None` if the + /// device doesn't say in time. + async fn busy(&self, followed: &Followed) -> Option { + let mut params = json!({ "terminalId": followed.id }); + if let Some(target) = &followed.target { + params["targetDeviceId"] = json!(target); + } + let status = tokio::time::timeout( + Duration::from_secs(3), + self.zeron.call_rpc(methods::TERMINAL_STATUS, params), + ) + .await + .ok()? + .ok()?; + status["busy"].as_bool() + } +} + +/// An engine error in its own words. +fn said(error: zeron_rpc::RpcError) -> anyhow::Error { + match error { + zeron_rpc::RpcError::Failed(message) => anyhow::anyhow!(message), + other => anyhow::anyhow!("{other}"), + } +} + +/// Follow `followed`'s output until it exits, it's dropped, or the stream +/// can't be had back. +async fn stream_into(zeron: Arc, followed: std::sync::Weak) { + let mut failures = 0u32; + loop { + let Some(this) = followed.upgrade() else { return }; + let after = this.screen.lock().map(|s| s.last_seq).unwrap_or(0); + let mut params = json!({ "terminalId": this.id, "afterSeq": after, "hostReplies": true }); + if let Some(target) = &this.target { + params["targetDeviceId"] = json!(target); + } + drop(this); + match zeron.subscribe(methods::SUBSCRIBE_TERMINAL, params).await { + Ok(mut subscription) => { + failures = 0; + while let Some(item) = subscription.recv().await { + let Some(this) = followed.upgrade() else { return }; + let Ok(event) = serde_json::from_value::(item) else { continue }; + let replies = this.screen.lock().map(|mut s| s.take(event)).unwrap_or_default(); + if !replies.is_empty() { + let mut params = json!({ + "terminalId": this.id, + "data": base64::engine::general_purpose::STANDARD.encode(&replies), + }); + if let Some(target) = &this.target { + params["targetDeviceId"] = json!(target); + } + let _ = zeron.call_rpc(methods::WRITE_TERMINAL, params).await; + } + if this.screen.lock().is_ok_and(|s| s.exit.is_some()) { + return; + } + } + } + Err(error) => { + failures += 1; + if failures >= MAX_RESUBSCRIBES { + if let Some(this) = followed.upgrade() + && let Ok(mut s) = this.screen.lock() + { + s.lost = Some(format!("can't follow this terminal any more: {error:#}")); + } + return; + } + } + } + tokio::time::sleep(Duration::from_millis(300) * (failures + 1)).await; + } +} + +impl Screen { + /// Fold one stream event in; returns what the emulator answers back + /// (only for a host that leaves queries to its viewers). + fn take(&mut self, event: TerminalEvent) -> Vec { + match event { + TerminalEvent::Data { seq, data } => { + if seq <= self.last_seq && self.last_seq != 0 { + return Vec::new(); + } + self.last_seq = seq; + let bytes = base64::engine::general_purpose::STANDARD + .decode(&data) + .unwrap_or_else(|_| data.into_bytes()); + let replies = self.emulator.feed(&bytes); + self.strip.push(&bytes, &mut self.unread); + if self.unread.len() > MAX_UNREAD { + let mut cut = self.unread.len() - MAX_UNREAD; + while !self.unread.is_char_boundary(cut) { + cut += 1; + } + self.dropped += self.unread[..cut].chars().count(); + self.unread.drain(..cut); + } + self.total += 1; + self.last_output = Some(Instant::now()); + if self.answer_queries { replies } else { Vec::new() } + } + TerminalEvent::Exit { seq, exit_code, signal } => { + self.last_seq = seq; + self.exit = Some(json!({ "code": exit_code, "signal": signal })); + Vec::new() + } + } + } +} + +/// The newest `max` bytes of `text` (on a character boundary), and how many +/// characters were left off. +fn newest(text: &str, max: usize) -> (String, usize) { + if text.len() <= max { + return (text.to_owned(), 0); + } + let mut cut = text.len() - max; + while !text.is_char_boundary(cut) { + cut += 1; + } + (text[cut..].to_owned(), text[..cut].chars().count()) +} + +/// The visible screen as text: trailing blanks off each row, blank rows off +/// the bottom. +fn screen_text(emulator: &Emulator) -> String { + let mut rows: Vec = emulator + .lines() + .into_iter() + .map(|row| { + let line: String = row.iter().filter(|cell| !cell.wide_spacer).map(|cell| cell.ch).collect(); + line.trim_end().to_owned() + }) + .collect(); + while rows.last().is_some_and(String::is_empty) { + rows.pop(); + } + rows.join("\n") +} + +/// Takes escape sequences and control characters out of a terminal's output +/// as it streams (a sequence may span chunks), keeping text, newlines and +/// tabs. A carriage return that doesn't start a newline drops what it would +/// overwrite on that line (progress bars keep their last state). +#[derive(Default)] +struct Strip { + state: StripState, + /// A UTF-8 character split across chunks. + partial: Vec, + /// A `\r` not yet known to be part of `\r\n`. + pending_cr: bool, +} + +#[derive(Default, Clone, Copy, PartialEq, Eq)] +enum StripState { + #[default] + Text, + Escape, + /// An escape that takes one more character (`ESC ( B`, a charset). + EscapeArgument, + /// CSI: parameters until a final byte. + Csi, + /// OSC, DCS, SOS, PM, APC: a string until BEL or ST. + String, + StringEscape, +} + +impl Strip { + fn push(&mut self, bytes: &[u8], out: &mut String) { + let mut bytes_in = std::mem::take(&mut self.partial); + bytes_in.extend_from_slice(bytes); + let text = match std::str::from_utf8(&bytes_in) { + Ok(text) => text.to_owned(), + Err(error) if error.error_len().is_none() => { + let valid = error.valid_up_to(); + self.partial = bytes_in[valid..].to_vec(); + String::from_utf8_lossy(&bytes_in[..valid]).into_owned() + } + Err(_) => String::from_utf8_lossy(&bytes_in).into_owned(), + }; + for ch in text.chars() { + self.state = match self.state { + StripState::Text => match ch { + '\u{1b}' => StripState::Escape, + _ => { + self.text(ch, out); + StripState::Text + } + }, + StripState::Escape => match ch { + '[' => StripState::Csi, + ']' | 'P' | 'X' | '^' | '_' => StripState::String, + '(' | ')' | '*' | '+' | '-' | '.' | '/' | '#' | '%' | ' ' => StripState::EscapeArgument, + _ => StripState::Text, + }, + StripState::EscapeArgument => StripState::Text, + StripState::Csi => match ch { + '\u{40}'..='\u{7e}' => StripState::Text, + _ => StripState::Csi, + }, + StripState::String => match ch { + '\u{7}' => StripState::Text, + '\u{1b}' => StripState::StringEscape, + _ => StripState::String, + }, + StripState::StringEscape => match ch { + '\\' => StripState::Text, + _ => StripState::String, + }, + }; + } + } + + fn text(&mut self, ch: char, out: &mut String) { + if self.pending_cr { + self.pending_cr = false; + if ch != '\n' { + // Back to the start of the line: what follows overwrites it. + let start = out.rfind('\n').map_or(0, |i| i + 1); + out.truncate(start); + } + } + match ch { + '\r' => self.pending_cr = true, + '\n' | '\t' => out.push(ch), + '\u{8}' => { + if !out.ends_with('\n') { + out.pop(); + } + } + c if c.is_control() => {} + c => out.push(c), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn strip(chunks: &[&[u8]]) -> String { + let mut strip = Strip::default(); + let mut out = String::new(); + for chunk in chunks { + strip.push(chunk, &mut out); + } + out + } + + #[test] + fn output_loses_its_escapes_and_keeps_its_text() { + assert_eq!(strip(&[b"\x1b[1;32mok\x1b[0m done\r\n"]), "ok done\n"); + // A title (OSC) and a bracketed-paste toggle, split across chunks. + assert_eq!(strip(&[b"\x1b]0;tit", b"le\x07$ ls\r\n\x1b[?20", b"04hfile\r\n"]), "$ ls\nfile\n"); + // A progress bar redrawn with \r keeps its last state. + assert_eq!(strip(&[b"10%\r50%\r", b"100%\r\n"]), "100%\n"); + // Backspace, and a UTF-8 character split across chunks. + assert_eq!(strip(&[b"ab\x08c \xe2\x9c", b"\x93\r\n"]), "ac \u{2713}\n"); + // A charset designation takes its argument with it. + assert_eq!(strip(&[b"\x1b(Bplain\x1b="]), "plain"); + } + + #[test] + fn the_newest_output_is_kept() { + assert_eq!(newest("abcdef", 10), ("abcdef".into(), 0)); + assert_eq!(newest("abcdef", 3), ("def".into(), 3)); + // Never mid-character. + assert_eq!(newest("a\u{2713}b", 2), ("b".into(), 2)); + } + + #[test] + fn the_screen_reads_as_a_person_sees_it() { + let mut screen = Screen { + emulator: Emulator::new(20, 5), + unread: String::new(), + dropped: 0, + total: 0, + last_seq: 0, + last_output: None, + exit: None, + lost: None, + answer_queries: false, + strip: Strip::default(), + }; + let data = |seq, text: &str| TerminalEvent::Data { + seq, + data: base64::engine::general_purpose::STANDARD.encode(text), + }; + screen.take(data(1, "$ echo hi\r\nhi\r\n$ ")); + // A replay of what was already seen changes nothing. + screen.take(data(1, "$ echo hi\r\nhi\r\n$ ")); + assert_eq!(screen.unread, "$ echo hi\nhi\n$ "); + assert_eq!(screen_text(&screen.emulator), "$ echo hi\nhi\n$"); + screen.take(TerminalEvent::Exit { seq: 2, exit_code: 0, signal: None }); + assert_eq!(screen.exit, Some(json!({ "code": 0, "signal": null }))); + } + + /// A shell on "Worker" (dev-remote) that echoes what's typed, then + /// prints `out` and a prompt; every call is recorded. + struct Shell { + calls: std::sync::Mutex>, + output: tokio::sync::broadcast::Sender, + seq: std::sync::atomic::AtomicU64, + } + + impl Shell { + fn new() -> Arc { + Arc::new(Self { + calls: Default::default(), + output: tokio::sync::broadcast::channel(64).0, + seq: Default::default(), + }) + } + + fn print(&self, text: &str) { + let seq = self.seq.fetch_add(1, std::sync::atomic::Ordering::SeqCst) + 1; + let _ = self.output.send(json!({ + "type": "data", "seq": seq, + "data": base64::engine::general_purpose::STANDARD.encode(text), + })); + } + } + + #[async_trait::async_trait] + impl zeron_rpc::RpcService for Shell { + async fn handle(&self, method: &str, params: Value) -> Result { + use futures::StreamExt; + use zeron_rpc::RpcReply; + self.calls.lock().unwrap().push((method.to_owned(), params.clone())); + Ok(match method { + methods::LOCAL_DEVICE => RpcReply::Value(json!({ "deviceId": "dev-local" })), + methods::WATCH_DEVICES => RpcReply::Stream( + futures::stream::iter(vec![json!([ + { "id": "dev-local", "name": "Laptop", "platform": "linux", "lastSeenAt": null }, + { "id": "dev-remote", "name": "Worker", "platform": "linux", "lastSeenAt": null } + ])]) + .boxed(), + ), + methods::OPEN_TERMINAL => { + self.print("$ "); + RpcReply::Value(json!({ "id": "t1", "cwd": "/home/me", "shell": "bash", "hostReplies": true })) + } + methods::SUBSCRIBE_TERMINAL => { + let rx = self.output.subscribe(); + RpcReply::Stream( + futures::stream::unfold(rx, |mut rx| async move { Some((rx.recv().await.ok()?, rx)) }).boxed(), + ) + } + methods::WRITE_TERMINAL => { + let typed = base64::engine::general_purpose::STANDARD + .decode(params["data"].as_str().unwrap_or_default()) + .unwrap(); + let typed = String::from_utf8(typed).unwrap(); + self.print(&format!("{}\r\n\x1b[32mout\x1b[0m\r\n$ ", typed.trim_end_matches('\r'))); + RpcReply::Value(json!({ "ok": true })) + } + methods::TERMINAL_STATUS => RpcReply::Value(json!({ "busy": false, "exited": false })), + methods::CLOSE_TERMINAL => RpcReply::Value(json!({ "ok": true })), + other => return Err(zeron_rpc::RpcError::UnknownMethod(other.into())), + }) + } + } + + #[tokio::test] + async fn a_terminal_on_another_device_is_opened_typed_into_read_and_closed() { + let shell = Shell::new(); + let origin = crate::zeron::Origin { + chat_id: Some("chat-1".into()), + device_id: Some("dev-local".into()), + ..Default::default() + }; + let tools = Tools::new(Arc::new(Zeron::with_client(zeron_rpc::memory_client(shell.clone()), origin))); + + let opened = tools.call(OPEN_TERMINAL, json!({ "device": "Worker" })).await.unwrap(); + assert_eq!(opened["terminal"], "t1"); + assert_eq!(opened["device"]["id"], "dev-remote"); + assert_eq!(opened["shell"], "bash"); + let calls = shell.calls.lock().unwrap().clone(); + let (_, open) = calls.iter().find(|(m, _)| m == methods::OPEN_TERMINAL).unwrap(); + assert_eq!(open["targetDeviceId"], "dev-remote"); + // Its chat's folder is on another device: not the chat's terminal there. + assert_eq!(open["chatId"], "agent-terminal:chat-1"); + + let wrote = tools + .call(WRITE_TERMINAL, json!({ "terminal": "t1", "input": "ls", "until": "$ ", "wait_ms": 5000 })) + .await + .unwrap(); + assert_eq!(wrote["output"], "ls\nout\n$ ", "{wrote}"); + assert_eq!(wrote["busy"], false); + assert!(wrote.get("screen").is_none()); + let calls = shell.calls.lock().unwrap().clone(); + let (_, write) = calls.iter().find(|(m, _)| m == methods::WRITE_TERMINAL).unwrap(); + assert_eq!(write["targetDeviceId"], "dev-remote"); + assert_eq!( + base64::engine::general_purpose::STANDARD.decode(write["data"].as_str().unwrap()).unwrap(), + b"ls\r" + ); + + // Read: nothing new, and the screen when asked. + let read = tools.call(READ_TERMINAL, json!({ "terminal": "t1", "screen": true })).await.unwrap(); + assert_eq!(read["output"], ""); + assert!(read["screen"].as_str().unwrap().ends_with("ls\nout\n$"), "{read}"); + + let closed = tools.call(CLOSE_TERMINAL, json!({ "terminal": "t1" })).await.unwrap(); + assert_eq!(closed["closed"], true); + let calls = shell.calls.lock().unwrap().clone(); + let (_, close) = calls.iter().find(|(m, _)| m == methods::CLOSE_TERMINAL).unwrap(); + assert_eq!(close["targetDeviceId"], "dev-remote"); + // Forgotten once closed: naming it again needs its device. + let again = tools.call(READ_TERMINAL, json!({ "terminal": "t1" })).await.unwrap(); + assert_eq!(again["device"]["id"], "dev-local"); + } +} diff --git a/crates/rpc/src/lib.rs b/crates/rpc/src/lib.rs index 132dd6e49..4d72eb4b8 100644 --- a/crates/rpc/src/lib.rs +++ b/crates/rpc/src/lib.rs @@ -780,8 +780,11 @@ pub fn app_forward_only(method: &str, params: &serde_json::Value) -> bool { /// `Review*`), signing (`SignPlugin`, `PluginSigningKey`), updating /// (`UpdatePlugin`, `UpdateTemplate`, the engine's and harnesses'), /// credentials (`AccessToken`, sign-in, `StepUp`, `DeleteAccount`), -/// terminals, files, vault and agent logins, and a command's whole output +/// files, vault and agent logins, and a command's whole output /// (`ReadToolOutput`: an agent reads a chat as its doc keeps it). +/// Terminals are here (on any of the person's devices), and the engine +/// opens them only to an agent whose chat runs with full access and no +/// sandbox (its agent gate). pub fn agent_allowed(method: &str) -> bool { matches!( method, @@ -806,6 +809,14 @@ pub fn agent_allowed(method: &str) -> bool { | methods::PUBLISH_IMAGE // Saying what the calling chat's agent waits on. | methods::AWAIT_BACKGROUND + // Terminals on any of the person's devices (Zeron MCP's + // open_terminal …): full access only (the engine's agent gate). + | methods::OPEN_TERMINAL + | methods::SUBSCRIBE_TERMINAL + | methods::WRITE_TERMINAL + | methods::RESIZE_TERMINAL + | methods::CLOSE_TERMINAL + | methods::TERMINAL_STATUS // Plugins: authoring, installing (lands waiting for the person), // checking for updates, exporting (to Zeron's plugin-exports // folder only: the engine refuses an agent's `to`), and their @@ -1435,8 +1446,6 @@ mod tests { methods::SET_PLUGIN_OFF, methods::REMOVE_PLUGIN, methods::SET_BUILTIN_PLUGINS, - methods::OPEN_TERMINAL, - methods::WRITE_TERMINAL, methods::WRITE_WORKSPACE_FILE, // The window's own watch of the theme files. methods::WATCH_THEMES, @@ -1454,6 +1463,13 @@ mod tests { // it to Zeron's plugin-exports folder (R29). let asked = agent.call(methods::EXPORT_PLUGIN, serde_json::json!({})).await.unwrap(); assert!(asked.as_str().unwrap().starts_with("Agent"), "{asked}"); + // Terminals reach the engine as the agent's, which opens them only + // to a chat with full access and no sandbox. + for method in [methods::OPEN_TERMINAL, methods::SUBSCRIBE_TERMINAL, methods::WRITE_TERMINAL, methods::CLOSE_TERMINAL, methods::TERMINAL_STATUS] { + assert!(agent_allowed(method), "{method}"); + let asked = agent.call(method, serde_json::json!({})).await.unwrap(); + assert!(asked.as_str().unwrap().starts_with("Agent"), "{method}: {asked}"); + } // The theme tools' methods, exactly: data only. for method in [methods::LIST_THEMES, methods::GET_THEME, methods::CREATE_THEME, methods::UPDATE_THEME, methods::DELETE_THEME, methods::USE_THEME] { assert!(agent_allowed(method), "{method}"); diff --git a/docs/design/cloud-attachments.md b/docs/design/cloud-attachments.md index 83275b449..e972b098a 100644 --- a/docs/design/cloud-attachments.md +++ b/docs/design/cloud-attachments.md @@ -81,9 +81,8 @@ and never looks in the store. ## Access Objects live at `attachments/{userId}/{chatId}/{uploadId}`, where the user id comes from the -caller's verified token, so only that user's bearers can name them. A Cloud machine's token -is admitted only for a chat it hosts, or a delegate it started -(`edge/src/runner-access.ts`). Every read and write needs a bearer. The size limit is the +caller's verified token, so only that user's bearers (their devices and Cloud machines) can +name them. Every read and write needs a bearer. The size limit is the engine's existing upload cap, 32 MiB, refused from the `content-length` before anything is stored. Each object carries a SHA-256 that R2 checks on the way in and the machine checks on the way out. diff --git a/docs/design/cloud-device.md b/docs/design/cloud-device.md index 994867f73..d0a67d1d4 100644 --- a/docs/design/cloud-device.md +++ b/docs/design/cloud-device.md @@ -130,38 +130,42 @@ next token refresh fails and that engine goes dark within one token lifetime. The sandbox runs full-access agents on arbitrary repository code, so anything that can read `runner-key` can mint runner tokens. A runner token therefore acts as **its session's device** -(the JWT's verified `dev` claim), never as the whole user — and never as a neighbouring -session. Enforced at the edge: +(the JWT's verified `dev` claim), never as the whole user. Like any of the person's devices, +though, it reaches their other devices and every one of their chats: a Cloud chat's agent +lists and messages chats on the laptop, starts chats there, and opens terminals on any online +device, as an agent on the laptop can. Enforced at the edge: - **Paths** (`edge/src/runner-policy.ts`, 403): no `/auth/*` org routes, no `/cloud/*`, no - `/vault/*` except `POST /vault/{org}/grant` for its own device. `/device/{id}/*` only for its - own id; for any other device only `GET /device/{id}/status` (read-only liveness) — no - client/host sockets, nudges or sidecars. No legacy loro rooms (`/session`, `/tail`, + `/vault/*` except `POST /vault/{org}/grant` for its own device. `/device/{id}/*` fully for + its own id; for any other device a client socket (`ws`, role client — that device's RPC + surface: chats, terminals, files), the command nudge, and `GET /device/{id}/status` — never + the host role or that device's sidecars. No legacy loro rooms (`/session`, `/tail`, `/stats`, `/diff`, `/snapshot`, `/append`, `/workspace`). On `/registry/{org}` only row sync (`ws`, `GET rows`, `POST push`) — no `stats`, `push-target` (APNs titles) or `reset`. -- **Chat-scoped data** (`edge/src/runner-access.ts`): `/chat2/{chatId}/*` and - `/blob/{chatId}/*` only while registry row `chats/{chatId}` is live and its - `fields.deviceId` equals the runner's device; otherwise 403 `not_host`. Positive answers are - cached per isolate for ≤5 min; refusals are never cached. +- **Chat-scoped data**: `/chat2/{chatId}/*` and `/blob/{chatId}/*` for any of the user's + chats, as for their other devices (the rooms are the user's, by bearer). - **Registry** (`edge/src/registry-runner.ts`; the Worker stamps `x-zeron-runner-device` on runner forwards and strips any inbound value). Writes: `devices` only its own row; - `chats`, `spaces`, `sessions` only when the existing live row is hosted by the runner AND - the row after the op still is (no claiming, handing away or ownerless rows); deletes need a - live owned row; tombstones are never revived; every other kind (`preferences`, + `chats`, `spaces`, `sessions` when the existing live row is hosted by the runner AND the + row after the op still is (no claiming, handing away or ownerless rows) — except that a + chat hosted elsewhere may be renamed or archived (`title`, `archived`), and a new chat row + may be hosted by any device (a chat it starts there); deletes need a live owned row (or a + delegate's, below); tombstones are never revived; every other kind (`preferences`, `sidebarPins`, anything new) is refused. Refused ops are skipped individually (an `{t:"error", code:"not_owner"}` frame each, plus `rejected` in the ack); the rest of the - batch applies. Reads (hello/backfill, live `rows` broadcasts, `GET /rows`): every `devices` - row, the hosted rows the runner owns, the projects (spaces) of the chats it hosts, and - tombstones of hosted kinds (they carry no fields); laptop chats, other projects and other - sessions' chats and session rows — titles, previews, status — never reach it. + batch applies. Reads (hello/backfill, live `rows` broadcasts, `GET /rows`): every + `devices`, `chats`, `spaces` and `sessions` row; none of the user's own kinds. Presence is unfiltered, but a runner socket's presence/attribution device is pinned to its verified id. +- **Engine** (`crates/engine/src/rpc/agent_gate.rs`): what an agent may do is the same on + Cloud as on a computer. Its terminals (`OpenTerminal` … `TerminalStatus`, here or on another + device) only from a chat with full access and no sandbox. User bearers are unaffected by all of the above. #### Delegation -The one widening: a session's machine may start and manage **delegates** of the chat it runs +A session's machine may start and manage **delegates** of the chat it runs (Zeron MCP `create_chat { cloud: true }`), one level deep. A delegate is a Cloud session of its own, on its own machine, recorded with `parentChatId` = the parent's chat. @@ -173,21 +177,20 @@ its own, on its own machine, recorded with `parentChatId` = the parent's chat. hold: credits, and `CLOUD_MAX_AWAKE` machines at once. A runner request without `parentChatId` is refused (a machine never acts as the user). - **Its chat row** is written by the edge, as the user (`chats/{chatId}`: the new machine as - host, `parentChatId`, the parent's `spaceId`, `roomGen: 2`, the asked-for `config`): a - runner may write only rows it hosts, and only the edge knows which machine it just made. + host, `parentChatId`, the parent's `spaceId`, `roomGen: 2`, the asked-for `config`): only + the edge knows which machine it just made. - **Manage** (`DELETE /cloud/{org}/sessions/{chatId}`, `POST …/{wake|sleep}`): only sessions whose `parentChatId` is its chat. Retry, the session list, projects, billing and Cloud on/off stay the user's. -- **See and reach**: the registry shows the runner its delegates' chat and session rows - (`RunnerScope.children`), and lets it rename, archive or delete them — never re-home them. - `/chat2/{chatId}/*` and `/blob/{chatId}/*` admit it when it hosts the chat's parent - (`/chat-host` answers `parentHost`). `/device/{id}/*` admits a client socket (never the host - role) and the command nudge for a device hosting one of its delegates - (`runnerDeviceGate`, via the registry's `/device-parents`). No other main chat — on the - laptop or another session — becomes visible. +- **Delete**: the registry lets it delete its delegates' chat and session rows + (`runnerChildren`) — never re-home them. -A stolen runner key therefore reaches at most: starting machines on the repository its -session already has (bounded by credits and the awake limit), and its own delegates. +A stolen runner key therefore reaches what an agent on any of the person's devices reaches: +their chats (reading them, messaging them, starting chats on their devices) and, through a +client link, those devices' RPC surface (terminals, files) — plus starting machines on the +repository its session already has (bounded by credits and the awake limit). It still can't +manage the account, read the vault, host another device, or change the person's +preferences. ### Workflows (Cloudflare Workflows) diff --git a/edge/src/attachment-blobs.ts b/edge/src/attachment-blobs.ts index f493d1208..8864d7820 100644 --- a/edge/src/attachment-blobs.ts +++ b/edge/src/attachment-blobs.ts @@ -7,8 +7,7 @@ * deletes the object once its own copy is on disk. * * Who may touch an object: the key is under the caller's own user id, so only - * that user's bearers can name it, and a Cloud machine is admitted only for a - * chat it hosts (or a delegate it started; runner-access.ts). + * that user's bearers (their devices and Cloud machines) can name it. * * Retention: the machine's DELETE is the normal end. The bucket's lifecycle * rule on `attachments/` (30 days, see docs/design/cloud-attachments.md) catches @@ -25,7 +24,6 @@ import type { Verified } from "./auth"; import type { Env } from "./env"; import { json } from "./http"; -import { runnerChatGate } from "./runner-access"; /** The engine's own cap on an assembled upload (uploads.rs `MAX_BYTES`). */ export const MAX_ATTACHMENT_BYTES = 32 * 1024 * 1024; @@ -85,8 +83,6 @@ export const handleAttachmentBlob = async ( chatId: string, uploadId: string ): Promise => { - const notHost = await runnerChatGate(env, auth, chatId); - if (notHost) return notHost; const key = attachmentKey(auth.userId, chatId, uploadId); switch (request.method) { diff --git a/edge/src/index.ts b/edge/src/index.ts index b84e33e41..65a4d768f 100644 --- a/edge/src/index.ts +++ b/edge/src/index.ts @@ -100,7 +100,6 @@ import { handleAdminRoute, runCloudCron } from "./cloud/billing"; import { sandboxProvider } from "./cloud/providers"; import { FakeProvider } from "./cloud/providers/fake"; import { handleAttachmentBlob } from "./attachment-blobs"; -import { runnerChatGate, runnerDeviceGate } from "./runner-access"; import { runnerRefusal } from "./runner-policy"; import { handleOnboardingRoute } from "./onboarding-routes"; import { handlePluginKeyRoute } from "./plugin-keys"; @@ -179,10 +178,9 @@ export default { if (!auth) return json({ error: "unauthenticated" }, 401); // Runner bearers (the Cloud device) act as their DEVICE, not the user: - // no account management, no vault beyond their own grants, no other - // device's room but its liveness, no legacy rooms (runner-policy.ts); - // chat2/blobs only for chats they host (runner-access.ts); registry rows - // filtered and ownership-checked in RegistryRoom (registry-runner.ts). + // no account management, no vault beyond their own grants, another + // device's room only as a client, no legacy rooms (runner-policy.ts); + // registry writes ownership-checked in RegistryRoom (registry-runner.ts). const refused = runnerRefusal(auth, request.method, url); if (refused) return json({ error: "forbidden", message: refused }, 403); @@ -249,11 +247,6 @@ export default { // client-minted). The DO handles /ws, /checkpoint (GET Range-resumable // + POST floor-guarded), host-published /tail + /diff sidecars, // /stats, /reset. ────────────────────────────────────────────────────── - if (parts[0] === "chat2" && parts[1] && ID_RE.test(parts[1])) { - // A Cloud runner reaches only the chats its device hosts. - const notHost = await runnerChatGate(env, auth, parts[1]); - if (notHost) return notHost; - } const chatResponse = chatRoute(request, env, auth.userId, auth.orgId); if (chatResponse) return chatResponse; @@ -371,12 +364,6 @@ export default { // ── device rooms ──────────────────────────────────────────────────────── if (parts[0] === "device" && parts[1] && ID_RE.test(parts[1])) { const deviceId = parts[1]; - // Another device's link or nudge: only a delegate's machine (the - // policy already admitted nothing else but liveness). - if (parts[2] === "ws" || parts[2] === "nudge") { - const refusedDevice = await runnerDeviceGate(env, auth, deviceId); - if (refusedDevice) return refusedDevice; - } if (parts[2] === "ws") { if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") { return json({ error: "expected websocket" }, 426); @@ -422,8 +409,6 @@ export default { if (partId === undefined || !PART_RE.test(partId)) { return json({ error: "bad part id" }, 400); } - const notHost = await runnerChatGate(env, auth, parts[1]); - if (notHost) return notHost; const key = `blob/${auth.userId}/${parts[1]}/${partId}`; if (request.method === "PUT") { const body = await request.arrayBuffer(); diff --git a/edge/src/registry-room.ts b/edge/src/registry-room.ts index 06ed3afee..bc9b9abe4 100644 --- a/edge/src/registry-room.ts +++ b/edge/src/registry-room.ts @@ -27,7 +27,7 @@ * tombstone GC + the R2 backup. */ import { applyOp, validateOp, type Op, type Row } from "./registry-core"; -import { chatHost, parentOf, runnerCanSee, runnerOpRefusal, type RunnerScope } from "./registry-runner"; +import { chatHost, runnerCanSee, runnerOpRefusal } from "./registry-runner"; import { AUTH_USER_HEADER, RUNNER_ACCOUNT_HEADER, RUNNER_DEVICE_HEADER, apnsConfig, type Env } from "./env"; import { isDeadToken, sendApns, type ApnsEnvironment } from "./apns"; import { WriteMeter } from "./write-meter"; @@ -212,19 +212,16 @@ export class RegistryRoom implements DurableObject { ); } - /** What one reader may receive: everything for user callers, owned rows - * (plus all devices, and the projects of the chats it hosts) for a runner. */ + /** What one reader may receive: everything for user callers; for a + * runner, every device, chat, project and session row (registry-runner.ts). */ private visible(rows: Row[], runner: string | undefined, _account: string | undefined): Row[] { if (runner === undefined) return rows; - const scope = this.runnerScope(runner); - return rows.filter((row) => runnerCanSee(runner, row, scope)); + return rows.filter((row) => runnerCanSee(runner, row)); } - /** What `device` reaches beyond its own rows: the projects of the live - * chats it hosts, and the live chats whose parent it hosts (delegates it - * started on other machines). */ - private runnerScope(device: string): RunnerScope { - const spaces = new Set(); + /** The live chats whose parent `device` hosts: delegates it started on + * other machines, which it may delete. */ + private runnerChildren(device: string): Set { const hosted = new Set(); const parents: [string, string][] = []; for (const raw of this.sql.exec<{ id: string; fields: string }>( @@ -232,36 +229,13 @@ export class RegistryRoom implements DurableObject { )) { try { const fields = JSON.parse(raw.fields) as Record; - if (fields.deviceId === device) { - hosted.add(raw.id); - if (typeof fields.spaceId === "string") spaces.add(fields.spaceId); - } + if (fields.deviceId === device) hosted.add(raw.id); if (typeof fields.parentChatId === "string") parents.push([raw.id, fields.parentChatId]); } catch { - /* a malformed row names no project and no parent */ + /* a malformed row names no parent */ } } - const children = new Set(parents.filter(([, parent]) => hosted.has(parent)).map(([id]) => id)); - return { spaces, children }; - } - - /** The hosts of the parents of the live chats `device` hosts: the runners - * that delegated work to it (the Worker's device-room gate). */ - private parentHosts(device: string): string[] { - const hosts = new Set(); - for (const raw of this.sql.exec<{ fields: string }>( - "SELECT fields FROM rows WHERE kind = 'chats' AND deleted = 0" - )) { - try { - const fields = JSON.parse(raw.fields) as Record; - if (fields.deviceId !== device || typeof fields.parentChatId !== "string") continue; - const host = chatHost(this.loadRow("chats", fields.parentChatId)); - if (host) hosts.add(host); - } catch { - /* a malformed row delegates nothing */ - } - } - return [...hosts]; + return new Set(parents.filter(([, parent]) => hosted.has(parent)).map(([id]) => id)); } private rowsSince(cursor: number): Row[] { @@ -403,29 +377,19 @@ export class RegistryRoom implements DurableObject { }); } - // The Worker's chat2/blob gate for runners: who hosts this chat? Only + // Who hosts this chat? (The chat relay and Cloud's delegate rows.) Only // reachable through the Worker, which asks the caller's own room. if (url.pathname === "/chat-host" && request.method === "GET") { const chat = url.searchParams.get("chat") ?? ""; const row = this.loadRow("chats", chat); - const parent = parentOf(row); return json({ deviceId: chatHost(row) ?? null, - // A delegate's parent host may reach it too (its runner started it). - parentHost: (parent && chatHost(this.loadRow("chats", parent))) ?? null, // Whether the id was ever used, tombstones included: a new delegate // must take a fresh id, never an existing (or deleted) chat's. known: row !== undefined }); } - // The Worker's device-room gate for runners: which runners delegated - // work to this device (host the parents of the chats it hosts)? - if (url.pathname === "/device-parents" && request.method === "GET") { - const device = url.searchParams.get("device") ?? ""; - return json({ hosts: this.parentHosts(device) }); - } - if (url.pathname === "/push" && request.method === "POST") { // Push over plain HTTPS — the WS push's fallback twin for networks // where the upgrade never completes. Same validation, same atomic @@ -612,8 +576,8 @@ export class RegistryRoom implements DurableObject { const sessionsBefore = new Map(); let applied = 0; const rejected: RejectedOp[] = []; - // Children as the batch starts: a delegate the runner may manage. - const children = runner === undefined ? undefined : this.runnerScope(runner).children; + // Children as the batch starts: a delegate the runner may delete. + const children = runner === undefined ? undefined : this.runnerChildren(runner); for (const op of ops) { const key = `${op.kind} ${op.id}`; const before = touched.get(key) ?? this.loadRow(op.kind, op.id); diff --git a/edge/src/registry-runner.test.ts b/edge/src/registry-runner.test.ts index 5406cd2a8..e83600ad2 100644 --- a/edge/src/registry-runner.test.ts +++ b/edge/src/registry-runner.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from "vitest"; import type { Op, Row } from "./registry-core"; -import { chatHost, parentOf, runnerCanSee, runnerOpRefusal } from "./registry-runner"; +import { chatHost, runnerCanSee, runnerOpRefusal } from "./registry-runner"; const CLOUD = "cloud-1"; const LAPTOP = "laptop-1"; @@ -28,18 +28,28 @@ describe("runner registry writes", () => { expect(runnerOpRefusal(CLOUD, row("sessions", "c1", { deviceId: CLOUD }), upsert("sessions", "c1", { status: "idle" }))).toBeNull(); }); - it("refuses touching, claiming or deleting another device's rows", () => { - const laptopChat = row("chats", "c2", { deviceId: LAPTOP, title: "secret" }); - expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { title: "x" }))).toMatch(/another device/); - expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { deviceId: CLOUD }))).toMatch(/another device/); + it("renames or archives a chat on another device, and starts chats there", () => { + const laptopChat = row("chats", "c2", { deviceId: LAPTOP, title: "plans" }); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { title: "x" }))).toBeNull(); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { archived: true }))).toBeNull(); + expect(runnerOpRefusal(CLOUD, undefined, upsert("chats", "c9", { deviceId: LAPTOP, parentChatId: "c1" }))).toBeNull(); + }); + + it("refuses claiming, reconfiguring or deleting another device's rows", () => { + const laptopChat = row("chats", "c2", { deviceId: LAPTOP, title: "plans" }); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { deviceId: CLOUD }))).toMatch(/only be renamed or archived/); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { config: {} }))).toMatch(/only be renamed or archived/); expect(runnerOpRefusal(CLOUD, laptopChat, del("chats", "c2"))).toMatch(/another device/); expect(runnerOpRefusal(CLOUD, row("spaces", "s1", { deviceId: LAPTOP }), upsert("spaces", "s1", { name: "x" }))).toMatch(/another device/); + expect(runnerOpRefusal(CLOUD, row("sessions", "c2", { deviceId: LAPTOP }), upsert("sessions", "c2", { status: "idle" }))).toMatch(/another device/); // Handing its own row to another device, or leaving it ownerless. const own = row("chats", "c1", { deviceId: CLOUD }); expect(runnerOpRefusal(CLOUD, own, upsert("chats", "c1", { deviceId: LAPTOP }))).toMatch(/would not be hosted/); expect(runnerOpRefusal(CLOUD, own, upsert("chats", "c1", { deviceId: null }))).toMatch(/would not be hosted/); expect(runnerOpRefusal(CLOUD, undefined, upsert("chats", "c9", { title: "no host" }))).toMatch(/would not be hosted/); - expect(runnerOpRefusal(CLOUD, undefined, upsert("chats", "c9", { deviceId: LAPTOP }))).toMatch(/would not be hosted/); + // Only a chat starts elsewhere: no new project or session row there. + expect(runnerOpRefusal(CLOUD, undefined, upsert("spaces", "s9", { deviceId: LAPTOP }))).toMatch(/would not be hosted/); + expect(runnerOpRefusal(CLOUD, undefined, upsert("sessions", "c9", { deviceId: LAPTOP }))).toMatch(/would not be hosted/); }); it("never revives tombstones or deletes what it cannot prove it owns", () => { @@ -60,14 +70,15 @@ describe("runner registry writes", () => { }); describe("runner registry reads", () => { - it("sees every device, its own hosted rows, and tombstones only", () => { + it("sees every device, chat, project and session, and none of the user's own kinds", () => { expect(runnerCanSee(CLOUD, row("devices", LAPTOP, { name: "Mac" }))).toBe(true); expect(runnerCanSee(CLOUD, row("chats", "c1", { deviceId: CLOUD }))).toBe(true); - expect(runnerCanSee(CLOUD, row("chats", "c2", { deviceId: LAPTOP, title: "secret" }))).toBe(false); - expect(runnerCanSee(CLOUD, row("sessions", "c2", { deviceId: LAPTOP }))).toBe(false); - expect(runnerCanSee(CLOUD, row("spaces", "s1", { deviceId: LAPTOP }))).toBe(false); - expect(runnerCanSee(CLOUD, row("preferences", "p", { a: 1 }))).toBe(false); + expect(runnerCanSee(CLOUD, row("chats", "c2", { deviceId: LAPTOP, title: "plans" }))).toBe(true); + expect(runnerCanSee(CLOUD, row("sessions", "c2", { deviceId: LAPTOP }))).toBe(true); + expect(runnerCanSee(CLOUD, row("spaces", "s1", { deviceId: LAPTOP }))).toBe(true); expect(runnerCanSee(CLOUD, row("chats", "c3", {}, true))).toBe(true); + expect(runnerCanSee(CLOUD, row("preferences", "p", { a: 1 }))).toBe(false); + expect(runnerCanSee(CLOUD, row("sidebarPins", "c1", { pinned: true }))).toBe(false); }); it("names a chat's host only for live chat rows", () => { @@ -83,32 +94,14 @@ describe("delegates (child chats on other machines)", () => { const children = new Set(["child"]); const child = row("chats", "child", { deviceId: OTHER, parentChatId: "main", title: "t" }); - it("sees its children's chat and session rows, never another main chat", () => { - const scope = { spaces: new Set(), children }; - expect(runnerCanSee(CLOUD, child, scope)).toBe(true); - expect(runnerCanSee(CLOUD, row("sessions", "child", { deviceId: OTHER }), scope)).toBe(true); - expect(runnerCanSee(CLOUD, row("chats", "other-main", { deviceId: OTHER }), scope)).toBe(false); - expect(runnerCanSee(CLOUD, row("sessions", "other-main", { deviceId: OTHER }), scope)).toBe(false); - expect(runnerCanSee(CLOUD, row("spaces", "s9", { deviceId: LAPTOP }), scope)).toBe(false); - expect(runnerCanSee(CLOUD, child)).toBe(false); // no scope: hosted rows only - }); - - it("may rename, archive or delete a child, nothing else", () => { + it("may also delete a child, with its session row, but not re-home or reconfigure it", () => { expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { title: "x" }), children)).toBeNull(); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { archived: true }), children)).toBeNull(); expect(runnerOpRefusal(CLOUD, child, del("chats", "child"), children)).toBeNull(); expect(runnerOpRefusal(CLOUD, row("sessions", "child", { deviceId: OTHER }), del("sessions", "child"), children)).toBeNull(); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { deviceId: CLOUD }), children)).toMatch(/only rename/); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { parentChatId: null }), children)).toMatch(/only rename/); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { config: {} }), children)).toMatch(/only rename/); + expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { deviceId: CLOUD }), children)).toMatch(/only be renamed/); + expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { parentChatId: null }), children)).toMatch(/only be renamed/); expect(runnerOpRefusal(CLOUD, row("sessions", "child", { deviceId: OTHER }), upsert("sessions", "child", { status: "idle" }), children)).toMatch(/another device/); - // Not its child: refused as before. - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { title: "x" }))).toMatch(/another device/); - }); - - it("reads a chat's parent", () => { - expect(parentOf(child)).toBe("main"); - expect(parentOf(row("chats", "main", { deviceId: CLOUD }))).toBeUndefined(); - expect(parentOf(row("chats", "gone", {}, true))).toBeUndefined(); + // Not its child: no delete. + expect(runnerOpRefusal(CLOUD, child, del("chats", "child"))).toMatch(/another device/); }); }); diff --git a/edge/src/registry-runner.ts b/edge/src/registry-runner.ts index d08061bad..61d19a362 100644 --- a/edge/src/registry-runner.ts +++ b/edge/src/registry-runner.ts @@ -2,17 +2,17 @@ * What a Cloud runner may write to and read from its user's registry * (docs/design/cloud-device.md, "Trust boundary"). * - * The Cloud sandbox runs full-access agents on arbitrary repository code, so - * its runner key must be treated as potentially stolen. A runner therefore - * acts as ITS DEVICE, not as the whole user: it sees every `devices` row - * (names, presence), the chats/spaces/sessions it hosts, and the projects - * (spaces) those chats belong to — a Cloud chat's project lives on the - * user's computer; it can write only rows it hosts. Ownership is the row's `fields.deviceId` (the - * host). One exception, delegation: the chat a runner hosts may have child - * chats on other machines (Cloud sessions it started). The runner sees those - * children's chat and session rows, and may rename, archive or delete the - * children — never re-home them, and never see any other main chat. Pure (no storage), separate from registry-core.ts, which mirrors - * the Rust merge code 1:1 — this is server-only policy. + * A Cloud chat works with the person's other devices the way a chat on any + * of their computers does: its runner SEES every device, chat, project and + * session row (so its agent can list and message chats anywhere), but it + * still WRITES as its device. It may write the rows it hosts, start a chat + * on another device (a new row hosted there), and rename or archive any + * chat — never re-home a chat, delete another device's (its delegates + * aside), or touch the user's own kinds (preferences, sidebar pins). Its + * delegates (child chats it started on other machines) may also be deleted. + * Ownership is the row's `fields.deviceId` (the host). Pure (no storage), + * separate from registry-core.ts, which mirrors the Rust merge code 1:1 — + * this is server-only policy. */ import { applyOp, type Op, type Row } from "./registry-core"; @@ -20,20 +20,12 @@ import { applyOp, type Op, type Row } from "./registry-core"; * (crates/doc/src/registry.rs: spaces, chats, sessions). */ const HOSTED_KINDS = new Set(["chats", "spaces", "sessions"]); -/** The fields a runner may write on a child chat (hosted elsewhere): its - * label and whether it is archived. */ -const CHILD_FIELDS = new Set(["title", "archived"]); +/** The fields a runner may write on a chat hosted elsewhere: its label and + * whether it is archived (what an agent's tools do to any chat). */ +const ANY_CHAT_FIELDS = new Set(["title", "archived"]); -/** What a runner reaches beyond the rows it hosts. */ -export interface RunnerScope { - /** Projects of the chats it hosts. */ - readonly spaces: ReadonlySet; - /** Live chats whose `parentChatId` is a chat it hosts (its delegates). */ - readonly children: ReadonlySet; -} - -/** No reach beyond hosted rows. */ -export const NO_SCOPE: RunnerScope = { spaces: new Set(), children: new Set() }; +/** No delegates. */ +const NO_CHILDREN: ReadonlySet = new Set(); /** The host device of a live row, if it names one. */ const hostOf = (row: Row | undefined): string | undefined => { @@ -46,13 +38,15 @@ const hostOf = (row: Row | undefined): string | undefined => { * Why runner `device` may not apply `op` to the stored row `before`, or null * when it may. Rules: * - `devices`: only its own device row; - * - hosted kinds: a live row must already be hosted by the runner, and the - * row as it would be after the op must still be (no claiming another - * device's chat, no handing one away, no ownerless rows); + * - a chat hosted elsewhere may be renamed or archived; a delegate (in + * `children`) may also be deleted, with its session row — its host and + * parent stay as written; + * - a new chat may be hosted by any device (a chat it starts on another of + * the person's devices); every other new or existing hosted row must be + * hosted by the runner before and after the op (no claiming another + * device's row, no handing one away, no ownerless rows); * - deletes need a live row the runner hosts; a runner never revives a * tombstone (its fields — and so its former host — are gone); - * - a child chat (in `children`) may be renamed, archived or deleted, and - * nothing else — its host and parent stay as the edge wrote them; * - every other kind (preferences, sidebar pins, anything new) is the * user's, not a device's: refused. */ @@ -60,50 +54,37 @@ export const runnerOpRefusal = ( device: string, before: Row | undefined, op: Op, - children: ReadonlySet = NO_SCOPE.children + children: ReadonlySet = NO_CHILDREN ): string | null => { if (op.kind === "devices") return op.id === device ? null : "not this runner's device row"; if (!HOSTED_KINDS.has(op.kind)) return `kind ${op.kind} is not writable by a runner`; const live = before !== undefined && !before.deleted ? before : undefined; if (live && hostOf(live) !== device) { - if (children.has(op.id) && (op.kind === "chats" || (op.kind === "sessions" && op.op === "delete"))) { - // Deleting a chat cascades to its session row (same id). - if (op.op === "delete") return null; - const keys = [...Object.keys(op.set ?? {}), ...Object.keys(op.clocks ?? {})]; - return keys.every((key) => CHILD_FIELDS.has(key)) ? null : "a parent may only rename, archive or delete its child chats"; + // Deleting a chat cascades to its session row (same id). + if (op.op === "delete") { + return children.has(op.id) && (op.kind === "chats" || op.kind === "sessions") ? null : "hosted by another device"; } - return "hosted by another device"; + if (op.kind !== "chats") return "hosted by another device"; + const keys = [...Object.keys(op.set ?? {}), ...Object.keys(op.clocks ?? {})]; + return keys.every((key) => ANY_CHAT_FIELDS.has(key)) ? null : "a chat on another device may only be renamed or archived"; } if (op.op === "delete") return live ? null : "no row of this runner's to delete"; if (before?.deleted) return "a runner cannot revive a deleted row"; const { row } = applyOp(before, op); - if (row && !row.deleted && hostOf(row) !== device) return "the row would not be hosted by this runner"; + if (!row || row.deleted) return null; + const host = hostOf(row); + // A chat it starts on another device: any host, never none. + if (before === undefined && op.kind === "chats" && host !== undefined) return null; + if (host !== device) return "the row would not be hosted by this runner"; return null; }; /** - * Whether a runner may see `row`: all device rows, the hosted rows it owns, - * the projects of the chats it hosts (`scope.spaces`), its child chats and - * their session rows (`scope.children`; a session row's id is its chat's), - * and tombstones of hosted kinds (they carry no fields — only the id and - * delete clock — and the runner must learn when its own rows die). + * Whether a runner may see `row`: every device, chat, project and session + * row (live or tombstoned), and none of the user's own kinds. */ -export const runnerCanSee = (device: string, row: Row, scope: RunnerScope = NO_SCOPE): boolean => { - if (row.kind === "devices") return true; - if (!HOSTED_KINDS.has(row.kind)) return false; - if (row.deleted) return true; - if (hostOf(row) === device) return true; - if (row.kind === "spaces") return scope.spaces.has(row.id); - return scope.children.has(row.id); -}; +export const runnerCanSee = (_device: string, row: Row): boolean => row.kind === "devices" || HOSTED_KINDS.has(row.kind); -/** The chat's parent chat id, if it records one. */ -export const parentOf = (row: Row | undefined): string | undefined => { - if (!row || row.deleted || row.kind !== "chats") return undefined; - const parent = row.fields.parentChatId; - return typeof parent === "string" && parent !== "" ? parent : undefined; -}; - -/** The chat's host device, for the Worker's chat2/blob gate. */ +/** The chat's host device, for the registry's `/chat-host`. */ export const chatHost = (row: Row | undefined): string | undefined => row?.kind === "chats" ? hostOf(row) : undefined; diff --git a/edge/src/runner-access.ts b/edge/src/runner-access.ts deleted file mode 100644 index dc1b75b8a..000000000 --- a/edge/src/runner-access.ts +++ /dev/null @@ -1,104 +0,0 @@ -/** - * Per-chat gate for runner bearers on chat-scoped data — `/chat2/{chatId}/*` - * (transcripts, command rows a host executes) and `/blob/{chatId}/*` (tool - * outputs): a runner may touch a chat only while the registry says its device - * hosts it (`chats/{chatId}` live, `fields.deviceId === dev`; a subagent's - * doc goes by the chat that spawned it). Without this a - * stolen runner key could read every transcript or append commands that a - * LAPTOP host then executes. - * - * Positive answers are cached per isolate for ≤5 minutes (a chat's host - * rarely changes; the registry DO stays off the hot path). Negative answers - * are never cached: a chat the Cloud device created moments ago must work as - * soon as its row lands. - */ -import type { Verified } from "./auth"; -import { AUTH_USER_HEADER, type Env } from "./env"; -import { json } from "./http"; - -const POSITIVE_TTL_MS = 5 * 60_000; -const MAX_CACHE = 10_000; -const allowed = new Map(); - -/** A subagent's transcript doc is `{chatId}--sub--{toolUseId}` (nested ones - * are named after the root chat too) and has no registry row of its own: it - * belongs to whoever hosts the chat that spawned it. */ -export const gatedChat = (chatId: string): string => chatId.split("--sub--", 1)[0] || chatId; - -/** undefined = proceed; otherwise the refusal to return. */ -export const runnerChatGate = async ( - env: Pick, - auth: Verified, - chatId: string, - now = Date.now() -): Promise => { - if (auth.kind !== "runner") return undefined; - const notHost = () => json({ error: "not_host", message: "This chat is not hosted by this Cloud device." }, 403); - if (!auth.orgId || !auth.deviceId) return notHost(); - const chat = gatedChat(chatId); - const key = `${auth.orgId}/${auth.userId}/${auth.deviceId}/${chat}`; - const until = allowed.get(key); - if (until !== undefined && until > now) return undefined; - allowed.delete(key); - - const room = env.REGISTRY_ROOMS.get(env.REGISTRY_ROOMS.idFromName(`reg1/${auth.orgId}/${auth.userId}`)); - let host: unknown; - let parentHost: unknown; - try { - const reply = await room.fetch(`https://registry/chat-host?chat=${encodeURIComponent(chat)}`, { - headers: { [AUTH_USER_HEADER]: auth.userId } - }); - if (!reply.ok) throw new Error(`registry ${reply.status}`); - ({ deviceId: host, parentHost } = (await reply.json()) as { deviceId?: unknown; parentHost?: unknown }); - } catch (e) { - console.warn("runner chat gate: registry unavailable", String(e)); - return json({ error: "unavailable", message: "Couldn't check the chat's host; retry." }, 503); - } - // Its own chat, or a delegate it started on another machine (it hosts the - // delegate's parent). - if (host !== auth.deviceId && parentHost !== auth.deviceId) return notHost(); - if (allowed.size >= MAX_CACHE) allowed.clear(); - allowed.set(key, now + POSITIVE_TTL_MS); - return undefined; -}; - -const deviceAllowed = new Map(); - -/** - * Gate for a runner on ANOTHER device's room (`/device/{id}/*` — that - * device's RPC surface: queues, interrupts, files). Allowed only when the - * device hosts a chat whose parent the runner hosts: the runner started that - * delegate and manages it. Its own room and read-only liveness never reach - * here (runner-policy.ts). Cached like the chat gate: positive answers only. - */ -export const runnerDeviceGate = async ( - env: Pick, - auth: Verified, - deviceId: string, - now = Date.now() -): Promise => { - if (auth.kind !== "runner" || deviceId === auth.deviceId) return undefined; - const refused = () => json({ error: "forbidden", message: "A runner may only reach the machines of chats it started." }, 403); - if (!auth.orgId || !auth.deviceId) return refused(); - const key = `${auth.orgId}/${auth.userId}/${auth.deviceId}/${deviceId}`; - const until = deviceAllowed.get(key); - if (until !== undefined && until > now) return undefined; - deviceAllowed.delete(key); - - const room = env.REGISTRY_ROOMS.get(env.REGISTRY_ROOMS.idFromName(`reg1/${auth.orgId}/${auth.userId}`)); - let hosts: unknown; - try { - const reply = await room.fetch(`https://registry/device-parents?device=${encodeURIComponent(deviceId)}`, { - headers: { [AUTH_USER_HEADER]: auth.userId } - }); - if (!reply.ok) throw new Error(`registry ${reply.status}`); - hosts = ((await reply.json()) as { hosts?: unknown }).hosts; - } catch (e) { - console.warn("runner device gate: registry unavailable", String(e)); - return json({ error: "unavailable", message: "Couldn't check the device's chats; retry." }, 503); - } - if (!Array.isArray(hosts) || !hosts.includes(auth.deviceId)) return refused(); - if (deviceAllowed.size >= MAX_CACHE) deviceAllowed.clear(); - deviceAllowed.set(key, now + POSITIVE_TTL_MS); - return undefined; -}; diff --git a/edge/src/runner-policy.test.ts b/edge/src/runner-policy.test.ts index 5878960d7..8b8f438a7 100644 --- a/edge/src/runner-policy.test.ts +++ b/edge/src/runner-policy.test.ts @@ -39,11 +39,6 @@ const REFUSED: [string, string][] = [ ["GET", "/device/laptop-1/sidecar/repos"], ["POST", "/device/laptop-1/sidecar/repos"], ["POST", "/device/laptop-1/status"], - // A user's computer, even one hosting a delegate's chat: never a client - // link or a nudge (its RPC surface is terminals, files, the user's bearer). - ["GET", "/device/laptop-1/ws?role=client"], - ["GET", "/device/laptop-1/ws"], - ["POST", "/device/laptop-1/nudge"], // Routes the policy doesn't name are refused. ["GET", "/preview/o/other"], ["GET", "/something-new/o"], @@ -72,7 +67,7 @@ describe("runner policy", () => { } }); - it("allows grants, its own device room, other devices' liveness, and row sync", () => { + it("allows grants, its own device room, other devices as a client, chats, and row sync", () => { for (const [method, path] of [ ["POST", "/vault/o/grant"], ["GET", "/device/cloud-1/ws?role=host"], @@ -80,8 +75,12 @@ describe("runner policy", () => { ["POST", "/device/cloud-1/nudge"], ["POST", "/device/cloud-1/sidecar/repos"], ["GET", "/device/laptop-1/status"], - // A delegate's machine: a client link and the command nudge, gated per - // device by runner-access.ts (runnerDeviceGate). + // Any of the person's other devices — a computer or another Cloud + // machine: a client link (its chats, terminals, files) and the + // command nudge. + ["GET", "/device/laptop-1/ws?role=client"], + ["GET", "/device/laptop-1/ws"], + ["POST", "/device/laptop-1/nudge"], ["GET", "/device/cloud-2/ws?role=client"], ["GET", "/device/cloud-2/ws"], ["POST", "/device/cloud-2/nudge"], @@ -93,7 +92,7 @@ describe("runner policy", () => { ["GET", "/registry/o/ws"], ["GET", "/registry/o/rows"], ["POST", "/registry/o/push"], - // Gated per chat by runner-access.ts, not by path. + // Any of the person's chats. ["GET", "/chat2/c1/ws"], ["PUT", "/blob/c1/p1"], ["POST", "/runner/heartbeat"], diff --git a/edge/src/runner-policy.ts b/edge/src/runner-policy.ts index bea866b24..b7b2c4b2a 100644 --- a/edge/src/runner-policy.ts +++ b/edge/src/runner-policy.ts @@ -5,15 +5,15 @@ * The Cloud sandbox runs full-access agents on arbitrary repository code, so * a runner token must be treated as possibly stolen. It acts as ITS DEVICE, * not as the user: it never manages the account (`/auth/*` org routes, - * `/cloud/*`), touches the vault beyond a grant for itself, reaches another - * device's room (except read-only liveness), uses the legacy loro rooms, or - * sees registry internals. Chat-scoped data (chat2 rooms, blobs) is gated - * per chat on the registry's host field (runner-access.ts); registry rows are - * filtered and ownership-checked inside RegistryRoom (registry-runner.ts). + * `/cloud/*`), touches the vault beyond a grant for itself, hosts another + * device's room, uses the legacy loro rooms, or sees registry internals. Like + * any of the person's devices it reaches their other devices (a client link: + * their chats, terminals and files) and every chat's data (chat2 rooms, + * blobs); its registry writes are ownership-checked inside RegistryRoom + * (registry-runner.ts). * Pure, so the whole path table is unit-testable without a Worker. */ import type { Verified } from "./auth"; -import { CLOUD_DEVICE_PREFIX } from "./cloud/policy"; /** The pre-chat2 loro rooms (s2 sessions, workspace docs): whole-user * documents with no per-device scoping — never for a runner. */ @@ -44,18 +44,14 @@ export const runnerRefusal = (auth: Verified, method: string, url: URL): string return "runner tokens may only request vault grants"; case "device": if (parts[1] === auth.deviceId) return undefined; - // Another device's room is that device's RPC surface (terminals, - // files, sidecars): read-only liveness, and — for the machine of a - // delegate it started (checked by runnerDeviceGate) — a client link - // and the command nudge. Never the host role. + // Another device's room is that device's RPC surface (chats, + // terminals, files): read-only liveness, a client link and the command + // nudge (a message to a chat it hosts), as any of the person's devices + // has. Never the host role, never its sidecars. if (parts[2] === "status" && parts.length === 3 && method === "GET") return undefined; - // Only ever another Cloud machine: a delegate's chat can be written on - // a user's computer (its RPC surface: terminals, files, the user's - // bearer), and a chat's parent alone must never open that. - if (!(parts[1] ?? "").startsWith(CLOUD_DEVICE_PREFIX)) return "a runner may only use its own device room"; if (parts[2] === "ws" && parts.length === 3 && (url.searchParams.get("role") ?? "client") === "client") return undefined; if (parts[2] === "nudge" && parts.length === 3 && method === "POST") return undefined; - return "a runner may only use its own device room"; + return "a runner reaches another device's room only as a client"; case "registry": // Row sync only; stats (push targets/log), APNs targets (notification // titles of every chat) and the operator wipe are the user's. @@ -70,7 +66,7 @@ export const runnerRefusal = (auth: Verified, method: string, url: URL): string return "runner tokens cannot use this route"; case "chat2": case "blob": - // Gated per chat on the registry's host field (runner-access.ts). + // Any of the person's chats, as their devices reach them. return undefined; case "runner": // Its own heartbeat (the account DO checks the device). diff --git a/edge/test/workerd/attachment-blobs.workerd.test.ts b/edge/test/workerd/attachment-blobs.workerd.test.ts index e70af4ef9..bee39f6be 100644 --- a/edge/test/workerd/attachment-blobs.workerd.test.ts +++ b/edge/test/workerd/attachment-blobs.workerd.test.ts @@ -132,40 +132,12 @@ describe("attachment bytes", () => { expect(new Uint8Array(await mine!.arrayBuffer())).toEqual(PNG); }); - it("a machine that doesn't host the chat is refused, whatever it asks", async () => { + it("any of the person's machines may reach them, whichever hosts the chat", async () => { const { user, otherMachine, path } = await world(); await (await put(user, path, PNG)).body?.cancel(); - for (const [method, send] of [ - ["GET", () => call("GET", path, otherMachine)], - ["HEAD", () => call("HEAD", path, otherMachine)], - ["DELETE", () => call("DELETE", path, otherMachine)], - ["PUT", () => put(otherMachine, path, PNG)] - ] as const) { - const reply = await send(); - expect(reply.status, method).toBe(403); - if (method !== "HEAD") expect(await reply.json(), method).toMatchObject({ error: "not_host" }); - else await reply.body?.cancel(); - } - const still = await call("GET", path, user); - expect(new Uint8Array(await still.arrayBuffer())).toEqual(PNG); - }); - - it("the machine that started a delegate may reach the delegate's attachments", async () => { - const { user, host, cloud, other, otherMachine } = await world(); - const parent = `parent-${rand()}`; - const child = `child-${rand()}`; - await push( - user, - [ - upsert("chats", parent, { deviceId: cloud, title: "parent" }, "laptop"), - upsert("chats", child, { deviceId: other, parentChatId: parent, title: "child" }, "laptop") - ], - "laptop" - ); - const path = `/blob/${child}/attachments/up-${rand()}`; - const stored = await put(host, path, PNG); - expect(stored.status, await stored.clone().text()).toBe(200); - expect((await call("GET", path, otherMachine)).status).toBe(200); + const read = await call("GET", path, otherMachine); + expect(read.status).toBe(200); + expect(new Uint8Array(await read.arrayBuffer())).toEqual(PNG); }); it("refuses anything over the engine's upload cap before storing it", async () => { diff --git a/edge/test/workerd/cloud-delegates.workerd.test.ts b/edge/test/workerd/cloud-delegates.workerd.test.ts index 4f3ce4c02..e37680cd0 100644 --- a/edge/test/workerd/cloud-delegates.workerd.test.ts +++ b/edge/test/workerd/cloud-delegates.workerd.test.ts @@ -143,7 +143,7 @@ describe("Cloud delegates", () => { expect(((await again.json()) as { deviceId: string }).deviceId).toBe(deviceId); }); - it("sees and reaches its children, never another main chat", async () => { + it("sees and reaches its children and every other chat, but hosts only its own room", async () => { const { u, main, other, runner } = await world(); const child = `child-${rand()}`; const { deviceId } = (await (await startChild(u, runner, child, main.chatId)).json()) as { deviceId: string }; @@ -151,19 +151,20 @@ describe("Cloud delegates", () => { const seen = await rows(runner); expect(find(seen, "chats", child)).toBeDefined(); expect(find(seen, "chats", main.chatId)).toBeDefined(); - expect(find(seen, "chats", other.chatId)).toBeUndefined(); + expect(find(seen, "chats", other.chatId)).toBeDefined(); - // Chat rooms: its child's, not the other main chat's. + // Chat rooms: its child's, and any other chat's. expect((await call("GET", `/chat2/${child}/stats`, runner)).status).toBe(200); - expect((await call("GET", `/chat2/${other.chatId}/stats`, runner)).status).toBe(403); - // Device rooms: a client link and the nudge to its child's machine only. - const link = await call("GET", `/device/${deviceId}/ws?role=client`, runner, undefined, { upgrade: "websocket" }); - expect(link.status).toBe(101); - link.webSocket!.accept(); - link.webSocket!.close(); + expect((await call("GET", `/chat2/${other.chatId}/stats`, runner)).status).toBe(200); + // Device rooms: a client link to any machine, never the host role. + for (const device of [deviceId, other.deviceId]) { + const link = await call("GET", `/device/${device}/ws?role=client`, runner, undefined, { upgrade: "websocket" }); + expect(link.status, device).toBe(101); + link.webSocket!.accept(); + link.webSocket!.close(); + } expect((await call("GET", `/device/${deviceId}/ws?role=host`, runner, undefined, { upgrade: "websocket" })).status).toBe(403); - expect((await call("GET", `/device/${other.deviceId}/ws?role=client`, runner, undefined, { upgrade: "websocket" })).status).toBe(403); - expect((await call("POST", `/device/${other.deviceId}/nudge`, runner, { chatId: other.chatId })).status).toBe(403); + expect((await call("GET", `/device/${other.deviceId}/ws?role=host`, runner, undefined, { upgrade: "websocket" })).status).toBe(403); }); it("manages its children's machines, and only theirs", async () => { @@ -204,17 +205,13 @@ describe("Cloud delegates", () => { expect(await grandchild.json()).toMatchObject({ error: "too_deep" }); }); - it("wakes its sleeping child when it sends to it, and nobody else's", async () => { - const { u, main, other, runner } = await world(); + it("wakes a sleeping Cloud chat when it sends to it, as a person's send would", async () => { + const { u, main, runner } = await world(); const child = await readyChild(u, runner, main.chatId); expect((await call("POST", `/cloud/${u.orgId}/sessions/${child.chatId}/sleep`, runner, {})).status).toBe(200); await waitForSession(u, child.chatId, "sleeping"); - // Not a session it started: refused at the door, and nothing wakes. - expect((await call("POST", `/device/${other.deviceId}/nudge`, runner, { chatId: other.chatId })).status).toBe(403); - // Its own child: the send wakes it, as a user's send would. expect((await call("POST", `/device/${child.deviceId}/nudge`, runner, { chatId: child.chatId })).status).toBe(200); await waitForSession(u, child.chatId, "starting"); - expect((await session(u, other.chatId))?.state).toBe("sleeping"); }); it("wakes its sleeping parent once it stops working: finished, or waiting on an answer", async () => { diff --git a/edge/test/workerd/cloud.workerd.test.ts b/edge/test/workerd/cloud.workerd.test.ts index 054100d37..f56508fcd 100644 --- a/edge/test/workerd/cloud.workerd.test.ts +++ b/edge/test/workerd/cloud.workerd.test.ts @@ -511,7 +511,7 @@ describe("runner tokens", () => { expect((await call("POST", "/runner/token", undefined, { ...u, deviceId, ts: "now", sig: "x" })).status).toBe(400); }); - it("is refused on /cloud and vault admin, but grants for itself and reads its project's space", async () => { + it("is refused on /cloud and vault admin, but grants for itself and reads the person's projects", async () => { const u = newUser(); const { deviceId, spaceId, accountDeviceId, key } = await readySession(u); const bearer = `Bearer ${await runnerToken(u, deviceId, key)}`; @@ -536,7 +536,7 @@ describe("runner tokens", () => { expect((await call("POST", "/vault/org1/grant", bearer, github)).status).toBe(403); // The chat it hosts belongs to a laptop's project: the session reads - // that project's row, but not the laptop's other projects. + // that project's row, and the laptop's other projects too. const hlc = (n: number) => `${String(Date.now()).padStart(13, "0")}-${String(n).padStart(6, "0")}-laptop`; const pushed = await call("POST", "/registry/org1/push?device=laptop", userBearer(u), { batch: `b-${crypto.randomUUID()}`, @@ -549,7 +549,7 @@ describe("runner tokens", () => { expect(pushed.status).toBe(200); const seen = ((await (await call("GET", "/registry/org1/rows", bearer)).json()) as { rows: { kind: string; id: string }[] }).rows; expect(seen.some((r) => r.kind === "spaces" && r.id === spaceId)).toBe(true); - expect(seen.some((r) => r.kind === "spaces" && r.id === "laptop-space")).toBe(false); + expect(seen.some((r) => r.kind === "spaces" && r.id === "laptop-space")).toBe(true); expect(seen.some((r) => r.kind === "devices" && r.id === accountDeviceId)).toBe(false); const orgs = await handleAuthRoute( diff --git a/edge/test/workerd/fixture.ts b/edge/test/workerd/fixture.ts index ad9272ad5..f2d8722ef 100644 --- a/edge/test/workerd/fixture.ts +++ b/edge/test/workerd/fixture.ts @@ -14,7 +14,6 @@ import { import type { Env } from "../../src/env"; import { dialDeviceRoom } from "../../src/device-link"; import { deviceParam, forward } from "../../src/forward"; -import { runnerChatGate, runnerDeviceGate } from "../../src/runner-access"; import { previewRoute } from "../../src/preview-route"; import { releaseRoute } from "../../src/releases"; import { modelListRoute } from "../../src/model-list"; @@ -120,8 +119,8 @@ const json = (value: unknown, status = 200) => * The production routing seam, in src/index.ts's order, minus the routes * that need loro's WASM (which cannot load in this tier): releases, admin + runner * pre-bearer routes, the hosted model list, bearer gate, runner policy, /cloud, /vault, preview, - * /device (with Cloud auto-wake), /registry, /chat2 and /blob (with the - * runner chat gate) — all through the production `forward`. + * /device (with Cloud auto-wake), /registry, /chat2 and /blob — all through + * the production `forward`. */ export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { @@ -161,10 +160,6 @@ export default { if (parts[0] === "device" && parts[1] && id.test(parts[1])) { const deviceId = parts[1]; const room = `d2/${deviceId}`; - if (parts[2] === "ws" || parts[2] === "nudge") { - const refusedDevice = await runnerDeviceGate(env, auth, deviceId); - if (refusedDevice) return refusedDevice; - } if (parts[2] === "ws") { return dialDeviceRoom(env, auth, request, url, deviceId); } @@ -182,18 +177,12 @@ export default { return forward(env.REGISTRY_ROOMS, room, request, auth, `/${parts[2]}`, url.search); } } - if (parts[0] === "chat2" && parts[1] && id.test(parts[1])) { - const notHost = await runnerChatGate(env, auth, parts[1]); - if (notHost) return notHost; - } const chat = chatRoute(request, env, auth.userId); if (chat) return chat; if (parts[0] === "blob" && parts.length === 4 && parts[2] === "attachments" && id.test(parts[1]) && id.test(parts[3])) { return handleAttachmentBlob(request, env, auth, parts[1], parts[3]); } if (parts[0] === "blob" && parts[1] && parts[2] && parts.length === 3) { - const notHost = await runnerChatGate(env, auth, parts[1]); - if (notHost) return notHost; const key = `blob/${auth.userId}/${parts[1]}/${parts[2]}`; if (request.method === "PUT") { await env.BLOBS.put(key, await request.arrayBuffer()); diff --git a/edge/test/workerd/runner-boundary.workerd.test.ts b/edge/test/workerd/runner-boundary.workerd.test.ts index 032bdcff0..0d1cc4099 100644 --- a/edge/test/workerd/runner-boundary.workerd.test.ts +++ b/edge/test/workerd/runner-boundary.workerd.test.ts @@ -1,7 +1,9 @@ /** * The Cloud runner trust boundary (docs/design/cloud-device.md, "Trust * boundary"): a runner token — possibly stolen by code running in the - * sandbox — acts as its device, never as the whole user. + * sandbox — acts as its device, never as the whole user. Like any of the + * person's devices it reaches their other devices and chats; it never hosts + * another device's room or writes rows it doesn't own. */ import { describe, expect, it } from "vitest"; import { encodeHlc, type Op } from "../../src/registry-core"; @@ -44,25 +46,21 @@ const world = async () => { const ws = { upgrade: "websocket" }; describe("device rooms", () => { - it("a runner cannot dial, nudge or read sidecars of another device, but can see its liveness", async () => { + it("a runner dials and nudges another device as a client, never as its host or into its sidecars", async () => { const { user, runner, laptop } = await world(); const host = await call("GET", `/device/${laptop}/ws?role=host`, user, undefined, ws); expect(host.status).toBe(101); host.webSocket!.accept(); - expect((await call("GET", `/device/${laptop}/ws?role=client`, runner, undefined, ws)).status).toBe(403); + const client = await call("GET", `/device/${laptop}/ws?role=client`, runner, undefined, ws); + expect(client.status).toBe(101); + client.webSocket!.accept(); + expect((await call("POST", `/device/${laptop}/nudge`, runner, { chatId: "c1" })).status).toBe(200); expect((await call("GET", `/device/${laptop}/ws?role=host`, runner, undefined, ws)).status).toBe(403); - expect((await call("POST", `/device/${laptop}/nudge`, runner, { chatId: "c1" })).status).toBe(403); expect((await call("GET", `/device/${laptop}/sidecar/repos`, runner)).status).toBe(403); const status = await call("GET", `/device/${laptop}/status`, runner); expect(status.status).toBe(200); expect(await status.json()).toMatchObject({ hostConnected: true }); - - // The user's own devices are unaffected. - const client = await call("GET", `/device/${laptop}/ws?role=client`, user, undefined, ws); - expect(client.status).toBe(101); - client.webSocket!.accept(); - expect((await call("POST", `/device/${laptop}/nudge`, user, { chatId: "c1" })).status).toBe(200); client.webSocket!.close(); host.webSocket!.close(); }); @@ -84,46 +82,25 @@ describe("device rooms", () => { }); describe("chat-scoped data", () => { - it("opens chat2 and blobs only for chats the runner's device hosts", async () => { + it("opens chat2 and blobs for any of the person's chats, wherever they're hosted", async () => { const { user, runner, cloud, laptopChat } = await world(); const cloudChat = `cc-${rand()}`; - - const denied = await call("GET", `/chat2/${laptopChat}/stats`, runner); - expect(denied.status).toBe(403); - expect(await denied.json()).toMatchObject({ error: "not_host" }); - // Not in the registry yet: refused — and not remembered as refused. - expect((await call("GET", `/chat2/${cloudChat}/stats`, runner)).status).toBe(403); expect((await push(runner, [upsert("chats", cloudChat, { deviceId: cloud, title: "cloud work" }, cloud)], cloud)).applied).toBe(1); + + expect((await call("GET", `/chat2/${laptopChat}/stats`, runner)).status).toBe(200); + expect((await call("GET", `/chat2/${laptopChat}--sub--toolu_01/stats`, runner)).status).toBe(200); expect((await call("GET", `/chat2/${cloudChat}/stats`, runner)).status).toBe(200); - - expect((await call("PUT", `/blob/${laptopChat}/p1`, runner, "out")).status).toBe(403); + expect((await call("PUT", `/blob/${laptopChat}/p1`, runner, "out")).status).toBe(200); expect((await call("PUT", `/blob/${cloudChat}/p1`, runner, "out")).status).toBe(200); - - // User bearers are untouched. expect((await call("GET", `/chat2/${laptopChat}/stats`, user)).status).toBe(200); - expect((await call("PUT", `/blob/${laptopChat}/p1`, user, "out")).status).toBe(200); }); - it("opens a subagent's doc by the chat that spawned it", async () => { - const { runner, cloud, laptopChat } = await world(); - const cloudChat = `cc-${rand()}`; - expect((await push(runner, [upsert("chats", cloudChat, { deviceId: cloud, title: "cloud work" }, cloud)], cloud)).applied).toBe(1); - - // No registry row of its own: the spawning chat's host decides. - expect((await call("GET", `/chat2/${cloudChat}--sub--toolu_01/stats`, runner)).status).toBe(200); - expect((await call("GET", `/chat2/${cloudChat}--sub--toolu_01--sub--toolu_02/stats`, runner)).status).toBe(200); - const denied = await call("GET", `/chat2/${laptopChat}--sub--toolu_01/stats`, runner); - expect(denied.status).toBe(403); - expect(await denied.json()).toMatchObject({ error: "not_host" }); - }); - - it("refuses a runner's attempt to claim a laptop chat, so the chat stays closed to it", async () => { + it("refuses a runner's attempt to claim a laptop chat", async () => { const { user, runner, cloud, laptop, laptopChat } = await world(); const claim = await push(runner, [upsert("chats", laptopChat, { deviceId: cloud }, cloud)], cloud); expect(claim.applied).toBe(0); - expect(claim.rejected).toEqual([{ kind: "chats", id: laptopChat, error: "hosted by another device" }]); + expect(claim.rejected).toEqual([{ kind: "chats", id: laptopChat, error: "a chat on another device may only be renamed or archived" }]); expect(find(await rows(user), "chats", laptopChat)?.fields).toMatchObject({ deviceId: laptop, title: "secret plans" }); - expect((await call("GET", `/chat2/${laptopChat}/stats`, runner)).status).toBe(403); }); }); @@ -158,29 +135,43 @@ describe("registry writes", () => { expect(find(all, "chats", laptopChat)?.deleted).toBe(false); expect(find(all, "chats", cloudChat)?.fields.deviceId).toBe(cloud); + // It may rename or archive a laptop chat, and start a chat there. + const startedThere = `lc-${rand()}`; + const allowed = await push( + runner, + [ + upsert("chats", laptopChat, { title: "renamed from Cloud", archived: true }, cloud), + upsert("chats", startedThere, { deviceId: laptop, title: "started from Cloud" }, cloud) + ], + cloud + ); + expect(allowed).toMatchObject({ applied: 2 }); + const after = await rows(user); + expect(find(after, "chats", laptopChat)?.fields).toMatchObject({ deviceId: laptop, title: "renamed from Cloud", archived: true }); + expect(find(after, "chats", startedThere)?.fields.deviceId).toBe(laptop); + // The same writes from the user's own bearer are not restricted. expect((await push(user, [upsert("devices", laptop, { name: "Renamed" }, laptop)])).applied).toBe(1); }); }); describe("registry reads", () => { - it("delivers only devices and the runner's own rows — over HTTP, hello and live broadcasts", async () => { + it("delivers every device, chat, project and session, never the user's own kinds", async () => { const { user, runner, cloud, laptop, laptopChat, space } = await world(); const cloudChat = `cc-${rand()}`; + await push(user, [upsert("preferences", "sidebar", { collapsed: true }, laptop)]); await push(runner, [upsert("devices", cloud, { name: "Cloud" }, cloud), upsert("chats", cloudChat, { deviceId: cloud, title: "mine" }, cloud)], cloud); const seen = await rows(runner); expect(find(seen, "devices", laptop)).toBeDefined(); expect(find(seen, "devices", cloud)).toBeDefined(); expect(find(seen, "chats", cloudChat)).toBeDefined(); - expect(find(seen, "chats", laptopChat)).toBeUndefined(); - expect(find(seen, "sessions", laptopChat)).toBeUndefined(); - expect(find(seen, "spaces", space)).toBeUndefined(); - expect(JSON.stringify(seen)).not.toContain("secret"); - const everything = await rows(user); - expect(find(everything, "chats", laptopChat)).toBeDefined(); + expect(find(seen, "chats", laptopChat)?.fields.title).toBe("secret plans"); + expect(find(seen, "sessions", laptopChat)).toBeDefined(); + expect(find(seen, "spaces", space)).toBeDefined(); + expect(find(seen, "preferences", "sidebar")).toBeUndefined(); - // WebSocket: the hello state is filtered, and so is every broadcast. + // WebSocket: the hello state and every broadcast. const socket = (await call("GET", "/registry/org1/ws", runner, undefined, ws)).webSocket!; socket.accept(); const frames: Record[] = []; @@ -191,22 +182,22 @@ describe("registry reads", () => { await expect.poll(() => frames.some((f) => f.t === "state")).toBe(true); const state = frames.find((f) => f.t === "state") as { rows: WireRow[] }; expect(find(state.rows, "chats", cloudChat)).toBeDefined(); - expect(find(state.rows, "chats", laptopChat)).toBeUndefined(); + expect(find(state.rows, "chats", laptopChat)).toBeDefined(); + expect(find(state.rows, "preferences", "sidebar")).toBeUndefined(); - await push(user, [upsert("chats", laptopChat, { title: "more secret plans" }, laptop)]); - await push(user, [upsert("chats", cloudChat, { title: "renamed from the laptop" }, laptop)]); + await push(user, [upsert("chats", laptopChat, { title: "more plans" }, laptop)]); + await push(user, [upsert("preferences", "sidebar", { collapsed: false }, laptop)]); await expect.poll(() => frames.filter((f) => f.t === "rows").length).toBe(2); const broadcasts = frames.filter((f) => f.t === "rows") as { rows: WireRow[] }[]; - expect(broadcasts[0]!.rows).toEqual([]); // the cursor still advances - expect(broadcasts[1]!.rows.map((r) => r.id)).toEqual([cloudChat]); - expect(JSON.stringify(frames)).not.toContain("secret"); + expect(broadcasts[0]!.rows.map((r) => r.id)).toEqual([laptopChat]); + expect(broadcasts[1]!.rows).toEqual([]); // the cursor still advances // Its pushes over the socket get per-op errors plus a partial ack, and // its presence/attribution is its verified device, not the claimed one. - socket.send(JSON.stringify({ t: "push", batch: "ws-1", ops: [upsert("chats", laptopChat, { title: "x" }, cloud)] })); + socket.send(JSON.stringify({ t: "push", batch: "ws-1", ops: [upsert("chats", laptopChat, { deviceId: cloud }, cloud)] })); await expect.poll(() => frames.some((f) => f.t === "ack" && f.batch === "ws-1")).toBe(true); expect(frames.find((f) => f.t === "error" && f.code === "not_owner")).toMatchObject({ - message: `chats/${laptopChat}: hosted by another device` + message: `chats/${laptopChat}: a chat on another device may only be renamed or archived` }); expect(frames.find((f) => f.t === "ack" && f.batch === "ws-1")).toMatchObject({ applied: 0, rejected: [expect.objectContaining({ id: laptopChat })] }); socket.close(); From 98761f6aad16c6b572b5601aebd674c853b47224 Mon Sep 17 00:00:00 2001 From: Wing Date: Sun, 15 Nov 2026 20:48:55 +0000 Subject: [PATCH 2/7] Agents run commands on other devices like a shell tool, not a terminal session Replaces the open/write/read/close terminal tools with one run_command: the device runs the command in the user's login shell with no PTY and no input, and replies with its output and exit code. Nothing is kept between calls. The output is capped at 64 KiB (its start and end) and every run has a timeout (at most 10 minutes). The command gets its own process group, which is killed on a timeout or when the call is abandoned. At most 16 run at once per device. The engine allows it only from a chat with full access and no sandbox. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 - crates/engine/src/lib.rs | 1 + crates/engine/src/rpc.rs | 37 ++ crates/engine/src/rpc/agent_gate.rs | 46 +- crates/engine/src/run_command.rs | 342 +++++++++++ crates/engine/src/terminals.rs | 4 +- crates/mcp/Cargo.toml | 1 - crates/mcp/src/jsonrpc.rs | 6 +- crates/mcp/src/tools.rs | 13 +- crates/mcp/src/tools/commands.rs | 150 +++++ crates/mcp/src/tools/terminals.rs | 855 ---------------------------- crates/rpc/src/lib.rs | 37 +- docs/design/cloud-device.md | 8 +- 13 files changed, 586 insertions(+), 915 deletions(-) create mode 100644 crates/engine/src/run_command.rs create mode 100644 crates/mcp/src/tools/commands.rs delete mode 100644 crates/mcp/src/tools/terminals.rs diff --git a/Cargo.lock b/Cargo.lock index cebcaddc5..3e914104a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -13823,7 +13823,6 @@ dependencies = [ "zeron-doc", "zeron-proto", "zeron-rpc", - "zeron-term", "zeron-theme", "zeron-visual", ] diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index cf4ce525e..1f3e8cdd7 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -69,6 +69,7 @@ pub mod registry; pub mod remote_terminals; pub mod repos; pub mod rpc; +pub mod run_command; pub mod run_journal; pub mod runner; pub mod wake_trace; diff --git a/crates/engine/src/rpc.rs b/crates/engine/src/rpc.rs index 8eb582620..080ecc118 100644 --- a/crates/engine/src/rpc.rs +++ b/crates/engine/src/rpc.rs @@ -481,6 +481,19 @@ fn resolve_open_terminal_cwd( crate::repos::resolve_chat_cwd(&raw, scratch_root) } +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct RunCommandParams { + command: String, + #[serde(default)] + cwd: Option, + /// The calling chat: its folder is the default, when it runs here. + #[serde(default)] + chat_id: Option, + #[serde(default)] + timeout_ms: Option, +} + #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] struct TerminalIdParams { @@ -2461,6 +2474,8 @@ fn forward_deadline(method: &str) -> std::time::Duration { // update, verification, and the relayed response itself. methods::APPLY_HARNESS_UPDATE => crate::harness_updates::APPLY_REPLY_DEADLINE, methods::CREATE_WORKTREE => Duration::from_secs(120), + // The longest a command may run there, and the reply's way back. + methods::RUN_COMMAND => crate::run_command::MAX_TIMEOUT + Duration::from_secs(30), // Allow the adapter discovery budget plus relay and shutdown overhead. methods::LIST_MODELS | methods::LIST_COMMANDS => Duration::from_secs(100), _ => Duration::from_secs(30), @@ -2583,6 +2598,8 @@ fn forwardable(method: &str) -> bool { | methods::RESIZE_TERMINAL | methods::CLOSE_TERMINAL | methods::TERMINAL_STATUS + // A command runs on the device it names. + | methods::RUN_COMMAND // Agent accounts are per-device CLI logins (the device switcher // retargets which device's logins are shown). | methods::LIST_AGENT_ACCOUNTS @@ -5530,6 +5547,26 @@ impl RpcService for EngineRpc { .map_err(|e| RpcError::Failed(e.to_string()))?; RpcReply::value(&serde_json::json!({ "ok": true })) } + methods::RUN_COMMAND => { + let p: RunCommandParams = parse_params(params)?; + // Its chat's folder by default, when the chat runs here. + let chat_cwd = p + .chat_id + .as_deref() + .and_then(|chat| self.workspace.chat(chat).ok().flatten()) + .filter(|chat| chat.device_id == self.doc_host.device_id()) + .and_then(|chat| chat.cwd); + let cwd = resolve_open_terminal_cwd(p.cwd, chat_cwd, None, &self.repos.scratch_root()) + .map_err(RpcError::Failed)?; + let timeout = p + .timeout_ms + .map(Duration::from_millis) + .unwrap_or(crate::run_command::DEFAULT_TIMEOUT); + let outcome = crate::run_command::run(&cwd, &p.command, timeout) + .await + .map_err(RpcError::Failed)?; + RpcReply::value(&outcome) + } methods::TERMINAL_STATUS => { let p: TerminalIdParams = parse_params(params)?; let status = self diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index f4048ada1..447a8b7b2 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -14,11 +14,11 @@ //! a chat it made, what it would itself have to ask the person for. //! - What it writes into a chat carries Zeron's header naming the sending //! chat, built here; a header in the text can't claim another chat. -//! - A terminal (on this device or any other of the person's) is a shell -//! as the person, with no sandbox: only an agent whose own chat runs with -//! full access and no sandbox opens, types into or reads one. Anything -//! less would let a supervised or sandboxed agent do through a shell what -//! it would itself have to ask for. +//! - A command it runs (`RunCommand`, on this device or any other of the +//! person's) runs as the person, with no sandbox: only an agent whose own +//! chat runs with full access and no sandbox may. Anything less would let +//! a supervised or sandboxed agent do through it what it would itself +//! have to ask for. //! //! The calling chat is the one its MCP server names (`x-zeron-chat`): the //! engine sets that server's environment, so a sandboxed agent can't change @@ -87,16 +87,8 @@ impl EngineRpc { params["chatId"] = json!(chat); return Ok(params); } - let terminal = matches!( - method, - methods::OPEN_TERMINAL - | methods::SUBSCRIBE_TERMINAL - | methods::WRITE_TERMINAL - | methods::RESIZE_TERMINAL - | methods::CLOSE_TERMINAL - | methods::TERMINAL_STATUS - ); - if !terminal && !matches!(method, methods::MUTATE | methods::QUEUE_MESSAGE | methods::QUEUE_COMMAND) { + let command = method == methods::RUN_COMMAND; + if !command && !matches!(method, methods::MUTATE | methods::QUEUE_MESSAGE | methods::QUEUE_COMMAND) { return Ok(params); } let chats = self.workspace.read_chats().unwrap_or_default(); @@ -108,7 +100,7 @@ impl EngineRpc { text, ) }; - if terminal { + if command { let unconfined = calling.as_ref().is_none_or(|c| { c.ceiling.is_none_or(|(sandbox, access)| { sandbox == SandboxLevel::DangerFullAccess && access == AccessMode::FullAccess @@ -118,7 +110,7 @@ impl EngineRpc { Ok(params) } else { Err(refused( - "A terminal is a shell with no sandbox: only a chat with full access and no sandbox uses one. Ask the person to give this chat full access, or to run it themselves", + "A command runs as the person with no sandbox: only a chat with full access and no sandbox runs one. Ask the person to give this chat full access, or to run it themselves", )) }; } @@ -318,17 +310,17 @@ mod tests { core.sessions.shutdown().await; } - /// A terminal, here or on another device, only for an agent whose chat + /// A command, here or on another device, only for an agent whose chat /// runs with full access and no sandbox; the person's own calls pass. #[tokio::test] - async fn only_an_unconfined_agent_uses_a_terminal() { + async fn only_an_unconfined_agent_runs_a_command() { let (_temp, core) = core().await; chat(&core, "careful", "Careful", "read-only", "supervised").await; chat(&core, "sandboxed", "Sandboxed", "workspace-write", "full-access").await; chat(&core, "free", "Free", "danger-full-access", "full-access").await; let rpc = core.rpc_service(); - let open = json!({"chatId":"x", "cols":80, "rows":24, "targetDeviceId":"laptop"}); - for method in [methods::OPEN_TERMINAL, methods::WRITE_TERMINAL, methods::SUBSCRIBE_TERMINAL, methods::TERMINAL_STATUS] { + let open = json!({"command":"ls", "targetDeviceId":"laptop"}); + for method in [methods::RUN_COMMAND] { for who in ["careful", "sandboxed", "nowhere"] { let refused = with_caller(agent(who), async { rpc.agent_gate(method, open.clone()) }).await; assert!( @@ -342,6 +334,18 @@ mod tests { with_caller(Caller::Agent { chat: None }, async { rpc.agent_gate(method, open.clone()) }).await.unwrap(); assert_eq!(rpc.agent_gate(method, open.clone()).unwrap(), open); } + // Through the engine, it runs here and says how it went. + let dir = tempfile::tempdir().unwrap(); + let ran = with_caller( + agent("free"), + rpc.handle(methods::RUN_COMMAND, json!({"command":"echo hi; exit 2", "cwd": dir.path()})), + ) + .await + .unwrap(); + let zeron_rpc::RpcReply::Value(ran) = ran else { panic!("a stream") }; + assert_eq!((ran["exitCode"].clone(), ran["output"].as_str().unwrap().ends_with("hi\n")), (json!(2), true), "{ran}"); + let refused = with_caller(agent("careful"), rpc.handle(methods::RUN_COMMAND, json!({"command":"echo hi"}))).await; + assert!(refused.is_err()); core.sessions.shutdown().await; } diff --git a/crates/engine/src/run_command.rs b/crates/engine/src/run_command.rs new file mode 100644 index 000000000..f45eabfe3 --- /dev/null +++ b/crates/engine/src/run_command.rs @@ -0,0 +1,342 @@ +//! `RunCommand`: one shell command run to its end on this device, for an +//! agent on this device or another of the person's (Zeron MCP's +//! `run_command`, forwarded by `targetDeviceId`). +//! +//! It works like an agent's own shell tool, not a terminal: no PTY and no +//! session. The user's shell runs the command as a login shell (`-l -c`), so +//! it gets the same PATH as their terminal. Stdin is empty, so a prompt for +//! input ends instead of hanging. The reply carries the output and the exit +//! code. What it costs is bounded: +//! +//! - **Memory**: at most [`HEAD`] + [`TAIL`] bytes of output are kept per run +//! (the start and the end); what's between is counted, not kept. +//! - **Time**: every run has a timeout (at most [`MAX_TIMEOUT`]). When it +//! expires, or the call is dropped, the command's whole process group is +//! killed (Unix), so nothing it started lives on. +//! - **Concurrency**: at most [`MAX_RUNNING`] commands at once per device; +//! beyond that a run is refused, not queued. +//! +//! Something the command deliberately puts in the background (`nohup x &`) +//! outlives a run that ends normally, as it would in a terminal. The run +//! stops reading output [`DRAIN`] after the shell exits, so such a process +//! never holds the reply open. + +use std::process::Stdio; +use std::time::{Duration, Instant}; + +use serde::Serialize; +use tokio::io::{AsyncRead, AsyncReadExt}; +use tokio::sync::Semaphore; + +pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(120); +pub const MAX_TIMEOUT: Duration = Duration::from_secs(600); +/// Output kept from the start of a run, and from its end. +const HEAD: usize = 16 * 1024; +const TAIL: usize = 48 * 1024; +/// How long output is still read once the shell has exited. +const DRAIN: Duration = Duration::from_millis(250); +pub const MAX_RUNNING: usize = 16; + +static RUNNING: Semaphore = Semaphore::const_new(MAX_RUNNING); + +/// How one run ended. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct RunOutcome { + /// `None` when it was killed (timed out, or by a signal). + pub exit_code: Option, + /// Stdout and stderr together, in the order they arrived. When it was + /// too long, its start and end with a line saying how much was left out. + pub output: String, + /// Bytes of output left out of the middle. + #[serde(skip_serializing_if = "is_zero")] + pub omitted_bytes: u64, + pub timed_out: bool, + pub duration_ms: u64, +} + +fn is_zero(n: &u64) -> bool { + *n == 0 +} + +/// Run `command` in `cwd` with the user's shell, for at most `timeout`. +pub async fn run(cwd: &str, command: &str, timeout: Duration) -> Result { + run_with_shell(&crate::terminals::selected_shell(), cwd, command, timeout).await +} + +pub(crate) async fn run_with_shell( + shell: &str, + cwd: &str, + command: &str, + timeout: Duration, +) -> Result { + if command.trim().is_empty() { + return Err("The command is empty".into()); + } + if !std::fs::metadata(cwd).is_ok_and(|m| m.is_dir()) { + return Err(format!("No folder {cwd} on this device")); + } + let _slot = RUNNING.try_acquire().map_err(|_| { + format!("{MAX_RUNNING} commands are already running on this device: wait for one to finish") + })?; + let timeout = timeout.min(MAX_TIMEOUT); + let started = Instant::now(); + + let mut cmd = tokio::process::Command::new(shell); + if crate::terminals::is_powershell(shell) { + cmd.args(["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command]); + } else if cfg!(windows) { + cmd.args(["/C", command]); + } else { + cmd.args(["-l", "-c", command]); + } + cmd.current_dir(cwd) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + // Nothing waits on a pager or paints for a terminal that isn't there. + .env("TERM", "dumb") + .env("PAGER", "cat") + .env("GIT_PAGER", "cat") + .env("GIT_TERMINAL_PROMPT", "0") + .kill_on_drop(true); + // Its own process group, so a timeout ends everything it started. + #[cfg(unix)] + cmd.process_group(0); + #[cfg(windows)] + cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW + let mut child = cmd + .spawn() + .map_err(|e| format!("Couldn't start {shell}: {e}"))?; + let group = Group::new(child.id()); + + let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); + let readers = [ + child.stdout.take().map(|out| tokio::spawn(pump(out, sender.clone()))), + child.stderr.take().map(|err| tokio::spawn(pump(err, sender.clone()))), + ]; + drop(sender); + + let mut output = Capped::default(); + let deadline = tokio::time::Instant::now() + timeout; + let mut status = None; + let mut timed_out = false; + // Until the shell exits (or time is up), taking output as it comes. + while status.is_none() { + tokio::select! { + exited = child.wait() => status = Some(exited.map_err(|e| e.to_string())?), + Some(chunk) = chunks.recv() => output.push(&chunk), + () = tokio::time::sleep_until(deadline) => { + timed_out = true; + group.kill(); + let _ = child.kill().await; + status = child.wait().await.ok(); + break; + } + } + } + // What's still in the pipes, briefly: a process it left in the + // background may keep them open for good. + let drain = tokio::time::Instant::now() + DRAIN; + loop { + tokio::select! { + chunk = chunks.recv() => match chunk { + Some(chunk) => output.push(&chunk), + None => break, + }, + () = tokio::time::sleep_until(drain) => break, + } + } + for reader in readers.into_iter().flatten() { + reader.abort(); + } + group.finished(); + + let exit_code = if timed_out { None } else { status.and_then(|s| s.code()) }; + let (output, omitted_bytes) = output.finish(); + Ok(RunOutcome { + exit_code, + output, + omitted_bytes, + timed_out, + duration_ms: started.elapsed().as_millis() as u64, + }) +} + +/// Read `from` into `to` until it ends or nobody listens. +async fn pump(mut from: impl AsyncRead + Unpin, to: tokio::sync::mpsc::Sender>) { + let mut buf = vec![0u8; 8 * 1024]; + loop { + match from.read(&mut buf).await { + Ok(0) | Err(_) => return, + Ok(n) => { + if to.send(buf[..n].to_vec()).await.is_err() { + return; + } + } + } + } +} + +/// The command's process group. Dropped before [`Group::finished`] (the +/// call was abandoned) or on a timeout, everything in it is killed. +struct Group { + #[cfg_attr(not(unix), allow(dead_code))] + pid: Option, + done: std::sync::atomic::AtomicBool, +} + +impl Group { + fn new(pid: Option) -> Self { + Self { pid, done: false.into() } + } + + fn kill(&self) { + #[cfg(unix)] + if let Some(pid) = self.pid.and_then(|p| i32::try_from(p).ok()).filter(|p| *p > 0) { + // SAFETY: signals the group this run made (process_group(0)). + unsafe { + libc::kill(-pid, libc::SIGKILL); + } + } + } + + fn finished(&self) { + self.done.store(true, std::sync::atomic::Ordering::Release); + } +} + +impl Drop for Group { + fn drop(&mut self) { + if !self.done.load(std::sync::atomic::Ordering::Acquire) { + self.kill(); + } + } +} + +/// Output kept within [`HEAD`] + [`TAIL`] bytes: the first bytes, the last +/// bytes, and a count of the rest. +#[derive(Default)] +struct Capped { + head: Vec, + tail: std::collections::VecDeque, + omitted: u64, +} + +impl Capped { + fn push(&mut self, mut bytes: &[u8]) { + if self.head.len() < HEAD { + let take = bytes.len().min(HEAD - self.head.len()); + self.head.extend_from_slice(&bytes[..take]); + bytes = &bytes[take..]; + } + if bytes.len() >= TAIL { + self.omitted += (self.tail.len() + bytes.len() - TAIL) as u64; + self.tail.clear(); + bytes = &bytes[bytes.len() - TAIL..]; + } + let overflow = (self.tail.len() + bytes.len()).saturating_sub(TAIL); + self.tail.drain(..overflow); + self.omitted += overflow as u64; + self.tail.extend(bytes); + } + + fn finish(self) -> (String, u64) { + let head = String::from_utf8_lossy(&self.head).into_owned(); + let tail: Vec = self.tail.into(); + let tail = String::from_utf8_lossy(&tail).into_owned(); + if self.omitted == 0 { + return (head + &tail, 0); + } + ( + format!("{head}\n… {} bytes of output left out …\n{tail}", self.omitted), + self.omitted, + ) + } +} + +#[cfg(all(test, unix))] +mod tests { + use super::*; + + async fn sh(command: &str, timeout: Duration) -> RunOutcome { + let dir = std::env::temp_dir(); + run_with_shell("/bin/sh", dir.to_str().unwrap(), command, timeout).await.unwrap() + } + + #[tokio::test] + async fn a_command_gives_its_output_and_exit_code() { + let ran = sh("echo out; echo err >&2; exit 3", DEFAULT_TIMEOUT).await; + assert_eq!(ran.exit_code, Some(3)); + assert!(ran.output.contains("out\n") && ran.output.contains("err\n"), "{ran:?}"); + assert!(!ran.timed_out); + // No input to wait for: a prompt reads end of input. + let ran = sh("read line; echo \"got [$line]\"", DEFAULT_TIMEOUT).await; + assert_eq!(ran.output, "got []\n"); + } + + #[tokio::test] + async fn it_runs_where_it_is_asked() { + let dir = tempfile::tempdir().unwrap(); + let ran = run_with_shell("/bin/sh", dir.path().to_str().unwrap(), "pwd", DEFAULT_TIMEOUT).await.unwrap(); + let here = std::fs::canonicalize(dir.path()).unwrap(); + assert_eq!(std::fs::canonicalize(ran.output.trim()).unwrap(), here); + assert!(run_with_shell("/bin/sh", "/no/such/folder", "pwd", DEFAULT_TIMEOUT).await.is_err()); + assert!(run_with_shell("/bin/sh", "/tmp", " ", DEFAULT_TIMEOUT).await.is_err()); + } + + #[tokio::test] + async fn a_timeout_kills_everything_the_command_started() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("(sleep 1; touch {}) & sleep 30", marker.display()); + let started = Instant::now(); + let ran = sh(&command, Duration::from_millis(300)).await; + assert!(ran.timed_out); + assert_eq!(ran.exit_code, None); + assert!(started.elapsed() < Duration::from_secs(5), "{:?}", started.elapsed()); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "a child outlived the timeout"); + } + + #[tokio::test] + async fn an_abandoned_run_kills_everything_it_started() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("sleep 1; touch {}", marker.display()); + let run = sh(&command, DEFAULT_TIMEOUT); + assert!(tokio::time::timeout(Duration::from_millis(200), run).await.is_err()); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "the command outlived its caller"); + } + + #[tokio::test] + async fn something_left_in_the_background_never_holds_the_reply() { + let started = Instant::now(); + let ran = sh("sleep 30 & echo started", DEFAULT_TIMEOUT).await; + assert_eq!(ran.exit_code, Some(0)); + assert_eq!(ran.output, "started\n"); + assert!(started.elapsed() < Duration::from_secs(3), "{:?}", started.elapsed()); + } + + #[tokio::test] + async fn long_output_keeps_its_start_and_end_within_bounds() { + let ran = sh("echo FIRST; head -c 1000000 /dev/zero | tr '\\0' x; echo; echo LAST", DEFAULT_TIMEOUT).await; + assert!(ran.output.starts_with("FIRST\n")); + assert!(ran.output.ends_with("LAST\n")); + assert!(ran.omitted_bytes > 900_000); + assert!(ran.output.len() < HEAD + TAIL + 100); + } + + #[test] + fn capped_output_counts_what_it_leaves_out() { + let mut capped = Capped::default(); + capped.push(&vec![b'a'; HEAD]); + capped.push(&vec![b'b'; TAIL + 10]); + capped.push(b"end"); + let (output, omitted) = capped.finish(); + assert_eq!(omitted, 13); + assert!(output.starts_with(&"a".repeat(HEAD))); + assert!(output.ends_with("bend")); + } +} diff --git a/crates/engine/src/terminals.rs b/crates/engine/src/terminals.rs index 04cce9079..4ccc93567 100644 --- a/crates/engine/src/terminals.rs +++ b/crates/engine/src/terminals.rs @@ -227,7 +227,7 @@ fn clamp_size(cols: u16, rows: u16) -> PtySize { } /// The user's interactive shell: `$SHELL`, else the platform default. -fn selected_shell() -> String { +pub(crate) fn selected_shell() -> String { if cfg!(windows) { return windows_shell(|name| std::env::var_os(name), |path| path.is_file()); } @@ -275,7 +275,7 @@ fn windows_shell( /// prints a banner as it starts unless told `-NoLogo`. Its last part, split /// at either slash: a Windows path reads the same wherever it's asked /// (`std::path` splits at `\` only on Windows, and the tests run on all). -fn is_powershell(shell: &str) -> bool { +pub(crate) fn is_powershell(shell: &str) -> bool { let file = shell.rsplit(['/', '\\']).next().unwrap_or(shell); let stem = file.rsplit_once('.').map_or(file, |(stem, _)| stem); matches!(stem.to_ascii_lowercase().as_str(), "pwsh" | "powershell") diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.toml index d804a765f..c723676b5 100644 --- a/crates/mcp/Cargo.toml +++ b/crates/mcp/Cargo.toml @@ -9,7 +9,6 @@ publish.workspace = true zeron-proto.workspace = true zeron-doc.workspace = true zeron-rpc.workspace = true -zeron-term.workspace = true tokio.workspace = true serde.workspace = true serde_json.workspace = true diff --git a/crates/mcp/src/jsonrpc.rs b/crates/mcp/src/jsonrpc.rs index 1f8177b6c..0445d5e52 100644 --- a/crates/mcp/src/jsonrpc.rs +++ b/crates/mcp/src/jsonrpc.rs @@ -64,9 +64,9 @@ from a Cloud chat it clones the same repository, and without `cloud` it shares y unless you name another device or project. From any chat, Cloud or not, you can list and \ message chats on every one of the person's devices.\n\ \n\ -`open_terminal` opens a shell on any online device (see `list_devices`); type into it with \ -`write_terminal`, read it with `read_terminal`, and close it with `close_terminal`. Only a chat \ -with full access and no sandbox may use one.\n\ +`run_command` runs a shell command on any online device (see `list_devices`) and returns its \ +output and exit code, as your own shell tool does here. Only a chat with full access and no \ +sandbox may use it.\n\ \n\ When a chart, table, diagram, dashboard, or 3D view would say more than prose and \ `show_visual` is available, write a Luau visual script and show it with `show_visual` before \ diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index 6a857df60..86f8841aa 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -22,8 +22,8 @@ use zeron_proto::{ use crate::transcript::{RenderOptions, RenderedMessage, render_entries}; use crate::zeron::{HarnessInfo, TranscriptFollow, TurnOutcome, Zeron, session_for, short}; +mod commands; mod plugins; -mod terminals; mod themes; pub use plugins::ListedTool; pub(crate) use plugins::is_plugin_tool_name; @@ -53,8 +53,6 @@ pub struct Tools { /// Which plugin tools the client was last shown ([`Self::list_all`], /// [`Self::watch_plugin_tools`]). plugins: plugins::PluginState, - /// The terminals this connection follows ([`terminals`]). - terminal_state: terminals::TerminalState, } fn chat_key_schema(extra: Value) -> Value { @@ -87,7 +85,7 @@ fn catalog() -> Vec { }, ToolDef { name: "list_devices", - description: "Devices in this workspace (the local engine's device is flagged). Chats and projects are hosted on a device. `online`: seen in the last 70 s (always true for this one); open_terminal reaches any online device.", + description: "Devices in this workspace (the local engine's device is flagged). Chats and projects are hosted on a device. `online`: seen in the last 70 s (always true for this one); run_command reaches any online device.", input_schema: json!({ "type": "object", "properties": {} }), }, ToolDef { @@ -304,7 +302,7 @@ fn catalog() -> Vec { }); tools.extend(plugins::catalog()); tools.extend(themes::catalog()); - tools.extend(terminals::catalog()); + tools.push(commands::tool()); tools } @@ -823,7 +821,6 @@ impl Tools { zeron, pending_turns: Default::default(), plugins: Default::default(), - terminal_state: Default::default(), } } @@ -899,9 +896,7 @@ impl Tools { plugins::EXPORT_TEMPLATE | plugins::IMPORT_TEMPLATE => { return self.template_packages(name, args).await; } - terminal if terminals::NAMES.contains(&terminal) => { - return self.terminals(terminal, args).await; - } + commands::RUN_COMMAND => self.run_command(parse(args)?).await, theme if themes::NAMES.contains(&theme) => { return self.themes(theme, args).await; } diff --git a/crates/mcp/src/tools/commands.rs b/crates/mcp/src/tools/commands.rs new file mode 100644 index 000000000..12b8720a1 --- /dev/null +++ b/crates/mcp/src/tools/commands.rs @@ -0,0 +1,150 @@ +//! `run_command`: one shell command on this device or any other of the +//! person's online devices, run to its end like an agent's own shell tool +//! (the engine's `RunCommand`, sent to another device by `targetDeviceId`). +//! Nothing is kept here between calls: the device that runs it caps the +//! output and kills what the command started when it times out +//! (crates/engine/src/run_command.rs). The engine allows it only from a chat +//! with full access and no sandbox (rpc/agent_gate.rs). + +use serde::Deserialize; +use serde_json::{Value, json}; +use zeron_rpc::{RpcError, methods}; + +use super::{ToolDef, Tools}; + +pub(super) const RUN_COMMAND: &str = "run_command"; +const DEFAULT_TIMEOUT_SECS: u64 = 120; +const MAX_TIMEOUT_SECS: u64 = 600; + +pub(super) fn tool() -> ToolDef { + ToolDef { + name: RUN_COMMAND, + description: "Run a shell command on this device, or on any other of the person's online devices (see list_devices; a Cloud machine must be awake), and get its output and exit code, as your own shell tool does here. It runs in the user's login shell (PowerShell on Windows) with no input and no terminal, in `cwd` (default: your chat's folder when it runs on your chat's device, else home). Stdout and stderr come back together; long output keeps its start and end. A command still running at `timeout_secs` is killed with everything it started (timedOut). Each call is a fresh shell: `cd` and variables don't carry over, so chain steps with && or pass cwd. Something left in the background with `nohup … &` keeps running. Only a chat with full access may use this.", + input_schema: json!({ + "type": "object", + "properties": { + "command": { "type": "string", "description": "The command, as you'd type it in a terminal there." }, + "device": { "type": "string", "description": "Device id or exact name. Omit for this device." }, + "cwd": { "type": "string", "description": "Folder on that device to run it in." }, + "timeout_secs": { "type": "integer", "minimum": 1, "maximum": MAX_TIMEOUT_SECS, "default": DEFAULT_TIMEOUT_SECS } + }, + "required": ["command"] + }), + } +} + +#[derive(Deserialize)] +pub(super) struct RunArgs { + command: String, + device: Option, + cwd: Option, + timeout_secs: Option, +} + +impl Tools { + pub(super) async fn run_command(&self, args: RunArgs) -> anyhow::Result { + anyhow::ensure!(!args.command.trim().is_empty(), "command is empty"); + let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; + let device = self.zeron.resolve_device_id(args.device.as_deref()).await?; + let timeout = args.timeout_secs.unwrap_or(DEFAULT_TIMEOUT_SECS).clamp(1, MAX_TIMEOUT_SECS); + let mut params = json!({ "command": args.command, "timeoutMs": timeout * 1000 }); + if let Some(cwd) = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()) { + params["cwd"] = json!(cwd); + } + if let Some(chat) = &self.zeron.origin().chat_id { + params["chatId"] = json!(chat); + } + if device != local { + params["targetDeviceId"] = json!(device); + } + let mut outcome = match self.zeron.call_rpc(methods::RUN_COMMAND, params).await { + Ok(outcome) => outcome, + Err(RpcError::UnknownMethod(_)) => anyhow::bail!( + "That device's Zeron is too old to run commands: update Zeron there and restart it" + ), + Err(RpcError::Failed(message)) => anyhow::bail!(message), + Err(error) => anyhow::bail!("{error}"), + }; + let name = devices.iter().find(|d| d.id == device).map(|d| d.name.clone()); + outcome["device"] = json!({ "id": device, "name": name, "local": device == local }); + Ok(outcome) + } +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use super::*; + use crate::zeron::{Origin, Zeron}; + + /// Two devices; `RunCommand` answers with what it was asked. + struct Engine { + calls: std::sync::Mutex>, + old_remote: bool, + } + + #[async_trait::async_trait] + impl zeron_rpc::RpcService for Engine { + async fn handle(&self, method: &str, params: Value) -> Result { + use futures::StreamExt; + use zeron_rpc::RpcReply; + Ok(match method { + methods::LOCAL_DEVICE => RpcReply::Value(json!({ "deviceId": "dev-local" })), + methods::WATCH_DEVICES => RpcReply::Stream( + futures::stream::iter(vec![json!([ + { "id": "dev-local", "name": "Laptop", "platform": "linux", "lastSeenAt": null }, + { "id": "dev-remote", "name": "Worker", "platform": "linux", "lastSeenAt": null } + ])]) + .boxed(), + ), + methods::RUN_COMMAND => { + if self.old_remote && params["targetDeviceId"] == "dev-remote" { + return Err(RpcError::UnknownMethod(method.into())); + } + self.calls.lock().unwrap().push(params); + RpcReply::Value(json!({ "exitCode": 0, "output": "hi\n", "timedOut": false, "durationMs": 5 })) + } + other => return Err(RpcError::UnknownMethod(other.into())), + }) + } + } + + fn tools(engine: Arc) -> Tools { + let origin = Origin { chat_id: Some("chat-1".into()), ..Default::default() }; + Tools::new(Arc::new(Zeron::with_client(zeron_rpc::memory_client(engine), origin))) + } + + #[tokio::test] + async fn a_command_runs_on_the_device_it_names() { + let engine = Arc::new(Engine { calls: Default::default(), old_remote: false }); + let tools = tools(engine.clone()); + let ran = tools + .call(RUN_COMMAND, json!({ "command": "echo hi", "device": "Worker", "cwd": "/srv", "timeout_secs": 5 })) + .await + .unwrap(); + assert_eq!(ran["output"], "hi\n"); + assert_eq!(ran["exitCode"], 0); + assert_eq!(ran["device"], json!({ "id": "dev-remote", "name": "Worker", "local": false })); + let sent = engine.calls.lock().unwrap().last().cloned().unwrap(); + assert_eq!( + sent, + json!({ "command": "echo hi", "cwd": "/srv", "timeoutMs": 5000, "chatId": "chat-1", "targetDeviceId": "dev-remote" }) + ); + + // This device: no target; a timeout is bounded. + tools.call(RUN_COMMAND, json!({ "command": "ls", "timeout_secs": 100000 })).await.unwrap(); + let sent = engine.calls.lock().unwrap().last().cloned().unwrap(); + assert!(sent.get("targetDeviceId").is_none()); + assert_eq!(sent["timeoutMs"], MAX_TIMEOUT_SECS * 1000); + + assert!(tools.call(RUN_COMMAND, json!({ "command": " " })).await.unwrap_err().contains("empty")); + } + + #[tokio::test] + async fn an_older_device_says_so() { + let tools = tools(Arc::new(Engine { calls: Default::default(), old_remote: true })); + let error = tools.call(RUN_COMMAND, json!({ "command": "ls", "device": "dev-remote" })).await.unwrap_err(); + assert!(error.contains("too old"), "{error}"); + } +} diff --git a/crates/mcp/src/tools/terminals.rs b/crates/mcp/src/tools/terminals.rs deleted file mode 100644 index 2991ec986..000000000 --- a/crates/mcp/src/tools/terminals.rs +++ /dev/null @@ -1,855 +0,0 @@ -//! Terminal tools: a shell on this device or any other of the person's -//! online devices (the engine's `OpenTerminal` … `CloseTerminal`, sent to -//! another device by `targetDeviceId` as the app's terminal panel does). -//! -//! This server follows each terminal it opens (or is pointed at) with a -//! `SubscribeTerminal` stream, folding its output into an emulator so a tool -//! can return both what was printed since it last looked (escape sequences -//! taken out) and the screen as a person would see it (what a full-screen -//! program like `top` or `vim` shows). The engine lets an agent do this only -//! from a chat with full access and no sandbox (rpc/agent_gate.rs): a shell -//! is neither. - -use std::collections::HashMap; -use std::sync::{Arc, Mutex}; -use std::time::{Duration, Instant}; - -use base64::Engine as _; -use serde::Deserialize; -use serde_json::{Value, json}; -use zeron_proto::TerminalEvent; -use zeron_rpc::methods; -use zeron_term::emulator::Emulator; - -use super::{ToolDef, Tools}; -use crate::zeron::Zeron; - -pub(super) const OPEN_TERMINAL: &str = "open_terminal"; -pub(super) const WRITE_TERMINAL: &str = "write_terminal"; -pub(super) const READ_TERMINAL: &str = "read_terminal"; -pub(super) const CLOSE_TERMINAL: &str = "close_terminal"; - -pub(super) const NAMES: [&str; 4] = [OPEN_TERMINAL, WRITE_TERMINAL, READ_TERMINAL, CLOSE_TERMINAL]; - -const DEFAULT_COLS: u16 = 120; -const DEFAULT_ROWS: u16 = 40; -/// How long a write waits for output by default, and the most any wait may. -const DEFAULT_WRITE_WAIT: Duration = Duration::from_secs(2); -const MAX_WAIT: Duration = Duration::from_secs(300); -/// Output quiet this long after it last changed reads as settled. -const QUIET: Duration = Duration::from_millis(500); -const POLL: Duration = Duration::from_millis(50); -/// The most unread output kept (the newest); older is counted, not kept. -const MAX_UNREAD: usize = 64 * 1024; -/// The most output one reply carries (the newest). -const MAX_REPLY_OUTPUT: usize = 16 * 1024; -/// Resubscribe attempts in a row before a terminal reads as lost. -const MAX_RESUBSCRIBES: u32 = 5; - -fn terminal_schema() -> Value { - json!({ "type": "string", "description": "Terminal id, from open_terminal." }) -} - -fn device_schema() -> Value { - json!({ "type": "string", "description": "The terminal's device (id or exact name). Only needed for a terminal this server didn't open (one the person opened, or one from before a restart): one it opened, it remembers." }) -} - -fn wait_schema(default_ms: u64) -> Value { - json!({ - "type": "integer", "minimum": 0, "maximum": MAX_WAIT.as_millis() as u64, "default": default_ms, - "description": "Wait up to this many milliseconds for output: the reply comes once output has been quiet for half a second, `until` appears, or the shell exits." - }) -} - -pub(super) fn catalog() -> Vec { - vec![ - ToolDef { - name: OPEN_TERMINAL, - description: "Open a shell on any of the person's online devices: this one when `device` is omitted, or another (see list_devices; a Cloud machine must be awake). Returns the terminal's id, its device, folder and shell. Type into it with write_terminal, read it with read_terminal, and close it with close_terminal when you're done. It runs as the person, with no sandbox, so only a chat with full access may open one.", - input_schema: json!({ - "type": "object", - "properties": { - "device": { "type": "string", "description": "Device id or exact name. Omit for this device." }, - "cwd": { "type": "string", "description": "Folder to start in, on that device (default: your chat's folder on its own device, else home)." }, - "cols": { "type": "integer", "minimum": 20, "maximum": 500, "default": DEFAULT_COLS }, - "rows": { "type": "integer", "minimum": 5, "maximum": 200, "default": DEFAULT_ROWS } - } - }), - }, - ToolDef { - name: WRITE_TERMINAL, - description: "Type into a terminal, then wait for what it prints. `input` is sent as typed, then Enter unless `enter` is false: send a command as `input`, or keys with `enter: false` (\\u0003 is Ctrl-C, \\u0004 Ctrl-D, \\u001b Esc, \\u001b[A the Up arrow). Returns `output` (what it printed since you last read it, escape sequences removed), `busy` (a program other than the shell is running), `exited` once the shell has ended, and `screen` (the visible screen, as text) when asked for or while a full-screen program shows. For a long command, pass `until` (text its end prints, such as a prompt) and a longer `wait_ms`, or read_terminal again later.", - input_schema: json!({ - "type": "object", - "properties": { - "terminal": terminal_schema(), - "input": { "type": "string", "description": "What to type." }, - "enter": { "type": "boolean", "default": true, "description": "Press Enter after the input." }, - "wait_ms": wait_schema(DEFAULT_WRITE_WAIT.as_millis() as u64), - "until": { "type": "string", "description": "Return as soon as the output since this call contains this text." }, - "screen": { "type": "boolean", "default": false, "description": "Include the visible screen." }, - "device": device_schema() - }, - "required": ["terminal", "input"] - }), - }, - ToolDef { - name: READ_TERMINAL, - description: "What a terminal printed since you last read it (escape sequences removed), whether a program is still running in it (`busy`) or the shell has exited, and optionally the visible screen. Pass `wait_ms` to wait for more output first. Works on a terminal the person opened too, given its id and device.", - input_schema: json!({ - "type": "object", - "properties": { - "terminal": terminal_schema(), - "wait_ms": wait_schema(0), - "until": { "type": "string", "description": "With wait_ms: return as soon as the unread output contains this text." }, - "screen": { "type": "boolean", "default": false, "description": "Include the visible screen." }, - "device": device_schema() - }, - "required": ["terminal"] - }), - }, - ToolDef { - name: CLOSE_TERMINAL, - description: "Close a terminal, ending its shell and anything running in it.", - input_schema: json!({ - "type": "object", - "properties": { "terminal": terminal_schema(), "device": device_schema() }, - "required": ["terminal"] - }), - }, - ] -} - -/// The terminals this server follows, by id. -#[derive(Default)] -pub(super) struct TerminalState { - followed: tokio::sync::Mutex>>, -} - -/// One terminal, as this server follows it. -struct Followed { - id: String, - /// `None`: this engine's own device. - target: Option, - device: Value, - screen: Mutex, - task: Mutex>>, -} - -impl Drop for Followed { - fn drop(&mut self) { - if let Some(task) = self.task.lock().ok().and_then(|mut t| t.take()) { - task.abort(); - } - } -} - -struct Screen { - emulator: Emulator, - /// Output not yet returned, escape sequences removed. - unread: String, - /// Characters dropped from the front of `unread` past [`MAX_UNREAD`]. - dropped: usize, - /// Bumped by every output chunk (a wait's "since this call" mark). - total: u64, - last_seq: u64, - last_output: Option, - exit: Option, - /// Why the stream was lost, when it was. - lost: Option, - /// The host leaves terminal queries to its viewers (an older engine). - answer_queries: bool, - /// Stripping state carried between chunks. - strip: Strip, -} - -#[derive(Deserialize)] -struct OpenArgs { - device: Option, - cwd: Option, - cols: Option, - rows: Option, -} - -#[derive(Deserialize)] -struct WriteArgs { - terminal: String, - input: String, - #[serde(default = "yes")] - enter: bool, - wait_ms: Option, - until: Option, - #[serde(default)] - screen: bool, - device: Option, -} - -#[derive(Deserialize)] -struct ReadArgs { - terminal: String, - wait_ms: Option, - until: Option, - #[serde(default)] - screen: bool, - device: Option, -} - -#[derive(Deserialize)] -struct CloseArgs { - terminal: String, - device: Option, -} - -fn yes() -> bool { - true -} - -fn parse(args: Value) -> Result { - let args = if args.is_null() { json!({}) } else { args }; - serde_json::from_value(args).map_err(|e| format!("invalid arguments: {e}")) -} - -fn wait_of(ms: Option, default: Duration) -> Duration { - ms.map(Duration::from_millis).unwrap_or(default).min(MAX_WAIT) -} - -impl Tools { - pub(super) async fn terminals(&self, tool: &str, args: Value) -> Result { - let result = match tool { - OPEN_TERMINAL => self.open_terminal(parse(args)?).await, - WRITE_TERMINAL => self.write_terminal(parse(args)?).await, - READ_TERMINAL => self.read_terminal(parse(args)?).await, - _ => self.close_terminal(parse(args)?).await, - }; - result.map_err(|e| format!("{e:#}")) - } - - /// The device to send a call to (`None`: this engine's), and how a reply - /// names it. - async fn terminal_device(&self, key: Option<&str>) -> anyhow::Result<(Option, Value)> { - let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; - let id = self.zeron.resolve_device_id(key).await?; - let name = devices.iter().find(|d| d.id == id).map(|d| d.name.clone()); - let named = json!({ "id": id, "name": name, "local": id == local }); - Ok(((id != local).then_some(id), named)) - } - - async fn open_terminal(&self, args: OpenArgs) -> anyhow::Result { - let (target, device) = self.terminal_device(args.device.as_deref()).await?; - let cols = args.cols.unwrap_or(DEFAULT_COLS).clamp(20, 500); - let rows = args.rows.unwrap_or(DEFAULT_ROWS).clamp(5, 200); - // On its own chat's device, the terminal is the chat's (its folder - // by default, its activity); elsewhere that folder means nothing. - let origin = self.zeron.origin(); - let own_device = match (&origin.device_id, &target) { - (_, None) => true, - (Some(here), Some(there)) => here == there, - (None, Some(_)) => false, - }; - let chat_id = match origin.chat_id.as_deref() { - Some(chat) if own_device => chat.to_owned(), - Some(chat) => format!("agent-terminal:{chat}"), - None => "agent-terminal".to_owned(), - }; - let mut params = json!({ "chatId": chat_id, "cols": cols, "rows": rows }); - if let Some(cwd) = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()) { - params["cwd"] = json!(cwd); - } - if let Some(target) = &target { - params["targetDeviceId"] = json!(target); - } - let session: zeron_proto::TerminalSession = - serde_json::from_value(self.zeron.call_rpc(methods::OPEN_TERMINAL, params).await.map_err(said)?)?; - let followed = self - .follow(&session.id, target, device.clone(), cols, rows, !session.host_replies) - .await; - // The prompt, usually. - let mut reply = self.settled(&followed, Duration::from_secs(1), None, false).await; - reply["cwd"] = json!(session.cwd); - reply["shell"] = json!(session.shell); - Ok(reply) - } - - async fn write_terminal(&self, args: WriteArgs) -> anyhow::Result { - let followed = self.followed(&args.terminal, args.device.as_deref()).await?; - let mut input = args.input; - if args.enter { - input.push('\r'); - } - anyhow::ensure!(!input.is_empty(), "nothing to type: input is empty and enter is false"); - let wait = wait_of(args.wait_ms, DEFAULT_WRITE_WAIT); - // Only output after the keys count toward `until`. - let mark = followed.screen.lock().map(|s| s.unread.len()).unwrap_or(0); - let mut params = json!({ - "terminalId": followed.id, - "data": base64::engine::general_purpose::STANDARD.encode(input.as_bytes()), - }); - if let Some(target) = &followed.target { - params["targetDeviceId"] = json!(target); - } - self.zeron.call_rpc(methods::WRITE_TERMINAL, params).await.map_err(said)?; - let until = args.until.as_deref().filter(|u| !u.is_empty()).map(|u| (u, mark)); - Ok(self.settled(&followed, wait, until, args.screen).await) - } - - async fn read_terminal(&self, args: ReadArgs) -> anyhow::Result { - let followed = self.followed(&args.terminal, args.device.as_deref()).await?; - let wait = wait_of(args.wait_ms, Duration::ZERO); - let until = args.until.as_deref().filter(|u| !u.is_empty()).map(|u| (u, 0)); - Ok(self.settled(&followed, wait, until, args.screen).await) - } - - async fn close_terminal(&self, args: CloseArgs) -> anyhow::Result { - let known = self.terminal_state.followed.lock().await.remove(&args.terminal); - let target = match &known { - Some(followed) => followed.target.clone(), - None => self.terminal_device(args.device.as_deref()).await?.0, - }; - let mut params = json!({ "terminalId": args.terminal }); - if let Some(target) = &target { - params["targetDeviceId"] = json!(target); - } - self.zeron.call_rpc(methods::CLOSE_TERMINAL, params).await.map_err(said)?; - Ok(json!({ "terminal": args.terminal, "closed": true })) - } - - /// A terminal this server follows, or — named with its device — one it - /// starts following now (its output so far replays from the start). - async fn followed(&self, id: &str, device: Option<&str>) -> anyhow::Result> { - if let Some(followed) = self.terminal_state.followed.lock().await.get(id) { - return Ok(followed.clone()); - } - let (target, named) = self.terminal_device(device).await?; - // Make sure it's there before following it. - let mut params = json!({ "terminalId": id }); - if let Some(target) = &target { - params["targetDeviceId"] = json!(target); - } - self.zeron.call_rpc(methods::TERMINAL_STATUS, params).await.map_err(|e| { - anyhow::anyhow!( - "no terminal {id} on {}: {} (open one with open_terminal; for one this server didn't open, pass its device)", - named["name"].as_str().unwrap_or("this device"), - said(e) - ) - })?; - Ok(self - .follow(id, target, named, DEFAULT_COLS, DEFAULT_ROWS, false) - .await) - } - - async fn follow( - &self, - id: &str, - target: Option, - device: Value, - cols: u16, - rows: u16, - answer_queries: bool, - ) -> Arc { - let followed = Arc::new(Followed { - id: id.to_owned(), - target, - device, - screen: Mutex::new(Screen { - emulator: Emulator::new(cols, rows), - unread: String::new(), - dropped: 0, - total: 0, - last_seq: 0, - last_output: None, - exit: None, - lost: None, - answer_queries, - strip: Strip::default(), - }), - task: Mutex::new(None), - }); - let task = tokio::spawn(stream_into(self.zeron.clone(), Arc::downgrade(&followed))); - if let Ok(mut slot) = followed.task.lock() { - *slot = Some(task); - } - self.terminal_state - .followed - .lock() - .await - .insert(id.to_owned(), followed.clone()); - followed - } - - /// Wait as asked, then take the unread output and say where the terminal - /// stands. - async fn settled(&self, followed: &Followed, wait: Duration, until: Option<(&str, usize)>, screen: bool) -> Value { - let start = Instant::now(); - let deadline = start + wait; - let first_total = followed.screen.lock().map(|s| s.total).unwrap_or(0); - while Instant::now() < deadline { - let done = match followed.screen.lock() { - Ok(s) => { - s.exit.is_some() - || s.lost.is_some() - || match until { - Some((text, mark)) => s.unread.get(mark.min(s.unread.len())..).is_some_and(|new| new.contains(text)), - None => s.total != first_total && s.last_output.is_some_and(|at| at.elapsed() >= QUIET), - } - } - Err(_) => true, - }; - if done { - break; - } - tokio::time::sleep(POLL).await; - } - let busy = self.busy(followed).await; - let Ok(mut s) = followed.screen.lock() else { - return json!({ "terminal": followed.id, "error": "this terminal's state was lost" }); - }; - let unread = std::mem::take(&mut s.unread); - let dropped = std::mem::take(&mut s.dropped); - let (output, cut) = newest(&unread, MAX_REPLY_OUTPUT); - let mut reply = json!({ - "terminal": followed.id, - "device": followed.device, - "output": output, - }); - if dropped + cut > 0 { - reply["outputDropped"] = json!(format!("{} earlier characters not shown", dropped + cut)); - } - if let Some(busy) = busy { - reply["busy"] = json!(busy); - } - if let Some(exit) = &s.exit { - reply["exited"] = exit.clone(); - } - if let Some(lost) = &s.lost { - reply["lost"] = json!(lost); - } - if let Some((text, _)) = until - && !output.contains(text) - && s.exit.is_none() - { - reply["untilSeen"] = json!(false); - } - if screen || s.emulator.alt_screen() { - reply["screen"] = json!(screen_text(&s.emulator)); - if let Some(cursor) = s.emulator.cursor() { - reply["cursor"] = json!({ "row": cursor.row, "col": cursor.col }); - } - } - reply - } - - /// Whether a program other than the shell runs in it; `None` if the - /// device doesn't say in time. - async fn busy(&self, followed: &Followed) -> Option { - let mut params = json!({ "terminalId": followed.id }); - if let Some(target) = &followed.target { - params["targetDeviceId"] = json!(target); - } - let status = tokio::time::timeout( - Duration::from_secs(3), - self.zeron.call_rpc(methods::TERMINAL_STATUS, params), - ) - .await - .ok()? - .ok()?; - status["busy"].as_bool() - } -} - -/// An engine error in its own words. -fn said(error: zeron_rpc::RpcError) -> anyhow::Error { - match error { - zeron_rpc::RpcError::Failed(message) => anyhow::anyhow!(message), - other => anyhow::anyhow!("{other}"), - } -} - -/// Follow `followed`'s output until it exits, it's dropped, or the stream -/// can't be had back. -async fn stream_into(zeron: Arc, followed: std::sync::Weak) { - let mut failures = 0u32; - loop { - let Some(this) = followed.upgrade() else { return }; - let after = this.screen.lock().map(|s| s.last_seq).unwrap_or(0); - let mut params = json!({ "terminalId": this.id, "afterSeq": after, "hostReplies": true }); - if let Some(target) = &this.target { - params["targetDeviceId"] = json!(target); - } - drop(this); - match zeron.subscribe(methods::SUBSCRIBE_TERMINAL, params).await { - Ok(mut subscription) => { - failures = 0; - while let Some(item) = subscription.recv().await { - let Some(this) = followed.upgrade() else { return }; - let Ok(event) = serde_json::from_value::(item) else { continue }; - let replies = this.screen.lock().map(|mut s| s.take(event)).unwrap_or_default(); - if !replies.is_empty() { - let mut params = json!({ - "terminalId": this.id, - "data": base64::engine::general_purpose::STANDARD.encode(&replies), - }); - if let Some(target) = &this.target { - params["targetDeviceId"] = json!(target); - } - let _ = zeron.call_rpc(methods::WRITE_TERMINAL, params).await; - } - if this.screen.lock().is_ok_and(|s| s.exit.is_some()) { - return; - } - } - } - Err(error) => { - failures += 1; - if failures >= MAX_RESUBSCRIBES { - if let Some(this) = followed.upgrade() - && let Ok(mut s) = this.screen.lock() - { - s.lost = Some(format!("can't follow this terminal any more: {error:#}")); - } - return; - } - } - } - tokio::time::sleep(Duration::from_millis(300) * (failures + 1)).await; - } -} - -impl Screen { - /// Fold one stream event in; returns what the emulator answers back - /// (only for a host that leaves queries to its viewers). - fn take(&mut self, event: TerminalEvent) -> Vec { - match event { - TerminalEvent::Data { seq, data } => { - if seq <= self.last_seq && self.last_seq != 0 { - return Vec::new(); - } - self.last_seq = seq; - let bytes = base64::engine::general_purpose::STANDARD - .decode(&data) - .unwrap_or_else(|_| data.into_bytes()); - let replies = self.emulator.feed(&bytes); - self.strip.push(&bytes, &mut self.unread); - if self.unread.len() > MAX_UNREAD { - let mut cut = self.unread.len() - MAX_UNREAD; - while !self.unread.is_char_boundary(cut) { - cut += 1; - } - self.dropped += self.unread[..cut].chars().count(); - self.unread.drain(..cut); - } - self.total += 1; - self.last_output = Some(Instant::now()); - if self.answer_queries { replies } else { Vec::new() } - } - TerminalEvent::Exit { seq, exit_code, signal } => { - self.last_seq = seq; - self.exit = Some(json!({ "code": exit_code, "signal": signal })); - Vec::new() - } - } - } -} - -/// The newest `max` bytes of `text` (on a character boundary), and how many -/// characters were left off. -fn newest(text: &str, max: usize) -> (String, usize) { - if text.len() <= max { - return (text.to_owned(), 0); - } - let mut cut = text.len() - max; - while !text.is_char_boundary(cut) { - cut += 1; - } - (text[cut..].to_owned(), text[..cut].chars().count()) -} - -/// The visible screen as text: trailing blanks off each row, blank rows off -/// the bottom. -fn screen_text(emulator: &Emulator) -> String { - let mut rows: Vec = emulator - .lines() - .into_iter() - .map(|row| { - let line: String = row.iter().filter(|cell| !cell.wide_spacer).map(|cell| cell.ch).collect(); - line.trim_end().to_owned() - }) - .collect(); - while rows.last().is_some_and(String::is_empty) { - rows.pop(); - } - rows.join("\n") -} - -/// Takes escape sequences and control characters out of a terminal's output -/// as it streams (a sequence may span chunks), keeping text, newlines and -/// tabs. A carriage return that doesn't start a newline drops what it would -/// overwrite on that line (progress bars keep their last state). -#[derive(Default)] -struct Strip { - state: StripState, - /// A UTF-8 character split across chunks. - partial: Vec, - /// A `\r` not yet known to be part of `\r\n`. - pending_cr: bool, -} - -#[derive(Default, Clone, Copy, PartialEq, Eq)] -enum StripState { - #[default] - Text, - Escape, - /// An escape that takes one more character (`ESC ( B`, a charset). - EscapeArgument, - /// CSI: parameters until a final byte. - Csi, - /// OSC, DCS, SOS, PM, APC: a string until BEL or ST. - String, - StringEscape, -} - -impl Strip { - fn push(&mut self, bytes: &[u8], out: &mut String) { - let mut bytes_in = std::mem::take(&mut self.partial); - bytes_in.extend_from_slice(bytes); - let text = match std::str::from_utf8(&bytes_in) { - Ok(text) => text.to_owned(), - Err(error) if error.error_len().is_none() => { - let valid = error.valid_up_to(); - self.partial = bytes_in[valid..].to_vec(); - String::from_utf8_lossy(&bytes_in[..valid]).into_owned() - } - Err(_) => String::from_utf8_lossy(&bytes_in).into_owned(), - }; - for ch in text.chars() { - self.state = match self.state { - StripState::Text => match ch { - '\u{1b}' => StripState::Escape, - _ => { - self.text(ch, out); - StripState::Text - } - }, - StripState::Escape => match ch { - '[' => StripState::Csi, - ']' | 'P' | 'X' | '^' | '_' => StripState::String, - '(' | ')' | '*' | '+' | '-' | '.' | '/' | '#' | '%' | ' ' => StripState::EscapeArgument, - _ => StripState::Text, - }, - StripState::EscapeArgument => StripState::Text, - StripState::Csi => match ch { - '\u{40}'..='\u{7e}' => StripState::Text, - _ => StripState::Csi, - }, - StripState::String => match ch { - '\u{7}' => StripState::Text, - '\u{1b}' => StripState::StringEscape, - _ => StripState::String, - }, - StripState::StringEscape => match ch { - '\\' => StripState::Text, - _ => StripState::String, - }, - }; - } - } - - fn text(&mut self, ch: char, out: &mut String) { - if self.pending_cr { - self.pending_cr = false; - if ch != '\n' { - // Back to the start of the line: what follows overwrites it. - let start = out.rfind('\n').map_or(0, |i| i + 1); - out.truncate(start); - } - } - match ch { - '\r' => self.pending_cr = true, - '\n' | '\t' => out.push(ch), - '\u{8}' => { - if !out.ends_with('\n') { - out.pop(); - } - } - c if c.is_control() => {} - c => out.push(c), - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - - fn strip(chunks: &[&[u8]]) -> String { - let mut strip = Strip::default(); - let mut out = String::new(); - for chunk in chunks { - strip.push(chunk, &mut out); - } - out - } - - #[test] - fn output_loses_its_escapes_and_keeps_its_text() { - assert_eq!(strip(&[b"\x1b[1;32mok\x1b[0m done\r\n"]), "ok done\n"); - // A title (OSC) and a bracketed-paste toggle, split across chunks. - assert_eq!(strip(&[b"\x1b]0;tit", b"le\x07$ ls\r\n\x1b[?20", b"04hfile\r\n"]), "$ ls\nfile\n"); - // A progress bar redrawn with \r keeps its last state. - assert_eq!(strip(&[b"10%\r50%\r", b"100%\r\n"]), "100%\n"); - // Backspace, and a UTF-8 character split across chunks. - assert_eq!(strip(&[b"ab\x08c \xe2\x9c", b"\x93\r\n"]), "ac \u{2713}\n"); - // A charset designation takes its argument with it. - assert_eq!(strip(&[b"\x1b(Bplain\x1b="]), "plain"); - } - - #[test] - fn the_newest_output_is_kept() { - assert_eq!(newest("abcdef", 10), ("abcdef".into(), 0)); - assert_eq!(newest("abcdef", 3), ("def".into(), 3)); - // Never mid-character. - assert_eq!(newest("a\u{2713}b", 2), ("b".into(), 2)); - } - - #[test] - fn the_screen_reads_as_a_person_sees_it() { - let mut screen = Screen { - emulator: Emulator::new(20, 5), - unread: String::new(), - dropped: 0, - total: 0, - last_seq: 0, - last_output: None, - exit: None, - lost: None, - answer_queries: false, - strip: Strip::default(), - }; - let data = |seq, text: &str| TerminalEvent::Data { - seq, - data: base64::engine::general_purpose::STANDARD.encode(text), - }; - screen.take(data(1, "$ echo hi\r\nhi\r\n$ ")); - // A replay of what was already seen changes nothing. - screen.take(data(1, "$ echo hi\r\nhi\r\n$ ")); - assert_eq!(screen.unread, "$ echo hi\nhi\n$ "); - assert_eq!(screen_text(&screen.emulator), "$ echo hi\nhi\n$"); - screen.take(TerminalEvent::Exit { seq: 2, exit_code: 0, signal: None }); - assert_eq!(screen.exit, Some(json!({ "code": 0, "signal": null }))); - } - - /// A shell on "Worker" (dev-remote) that echoes what's typed, then - /// prints `out` and a prompt; every call is recorded. - struct Shell { - calls: std::sync::Mutex>, - output: tokio::sync::broadcast::Sender, - seq: std::sync::atomic::AtomicU64, - } - - impl Shell { - fn new() -> Arc { - Arc::new(Self { - calls: Default::default(), - output: tokio::sync::broadcast::channel(64).0, - seq: Default::default(), - }) - } - - fn print(&self, text: &str) { - let seq = self.seq.fetch_add(1, std::sync::atomic::Ordering::SeqCst) + 1; - let _ = self.output.send(json!({ - "type": "data", "seq": seq, - "data": base64::engine::general_purpose::STANDARD.encode(text), - })); - } - } - - #[async_trait::async_trait] - impl zeron_rpc::RpcService for Shell { - async fn handle(&self, method: &str, params: Value) -> Result { - use futures::StreamExt; - use zeron_rpc::RpcReply; - self.calls.lock().unwrap().push((method.to_owned(), params.clone())); - Ok(match method { - methods::LOCAL_DEVICE => RpcReply::Value(json!({ "deviceId": "dev-local" })), - methods::WATCH_DEVICES => RpcReply::Stream( - futures::stream::iter(vec![json!([ - { "id": "dev-local", "name": "Laptop", "platform": "linux", "lastSeenAt": null }, - { "id": "dev-remote", "name": "Worker", "platform": "linux", "lastSeenAt": null } - ])]) - .boxed(), - ), - methods::OPEN_TERMINAL => { - self.print("$ "); - RpcReply::Value(json!({ "id": "t1", "cwd": "/home/me", "shell": "bash", "hostReplies": true })) - } - methods::SUBSCRIBE_TERMINAL => { - let rx = self.output.subscribe(); - RpcReply::Stream( - futures::stream::unfold(rx, |mut rx| async move { Some((rx.recv().await.ok()?, rx)) }).boxed(), - ) - } - methods::WRITE_TERMINAL => { - let typed = base64::engine::general_purpose::STANDARD - .decode(params["data"].as_str().unwrap_or_default()) - .unwrap(); - let typed = String::from_utf8(typed).unwrap(); - self.print(&format!("{}\r\n\x1b[32mout\x1b[0m\r\n$ ", typed.trim_end_matches('\r'))); - RpcReply::Value(json!({ "ok": true })) - } - methods::TERMINAL_STATUS => RpcReply::Value(json!({ "busy": false, "exited": false })), - methods::CLOSE_TERMINAL => RpcReply::Value(json!({ "ok": true })), - other => return Err(zeron_rpc::RpcError::UnknownMethod(other.into())), - }) - } - } - - #[tokio::test] - async fn a_terminal_on_another_device_is_opened_typed_into_read_and_closed() { - let shell = Shell::new(); - let origin = crate::zeron::Origin { - chat_id: Some("chat-1".into()), - device_id: Some("dev-local".into()), - ..Default::default() - }; - let tools = Tools::new(Arc::new(Zeron::with_client(zeron_rpc::memory_client(shell.clone()), origin))); - - let opened = tools.call(OPEN_TERMINAL, json!({ "device": "Worker" })).await.unwrap(); - assert_eq!(opened["terminal"], "t1"); - assert_eq!(opened["device"]["id"], "dev-remote"); - assert_eq!(opened["shell"], "bash"); - let calls = shell.calls.lock().unwrap().clone(); - let (_, open) = calls.iter().find(|(m, _)| m == methods::OPEN_TERMINAL).unwrap(); - assert_eq!(open["targetDeviceId"], "dev-remote"); - // Its chat's folder is on another device: not the chat's terminal there. - assert_eq!(open["chatId"], "agent-terminal:chat-1"); - - let wrote = tools - .call(WRITE_TERMINAL, json!({ "terminal": "t1", "input": "ls", "until": "$ ", "wait_ms": 5000 })) - .await - .unwrap(); - assert_eq!(wrote["output"], "ls\nout\n$ ", "{wrote}"); - assert_eq!(wrote["busy"], false); - assert!(wrote.get("screen").is_none()); - let calls = shell.calls.lock().unwrap().clone(); - let (_, write) = calls.iter().find(|(m, _)| m == methods::WRITE_TERMINAL).unwrap(); - assert_eq!(write["targetDeviceId"], "dev-remote"); - assert_eq!( - base64::engine::general_purpose::STANDARD.decode(write["data"].as_str().unwrap()).unwrap(), - b"ls\r" - ); - - // Read: nothing new, and the screen when asked. - let read = tools.call(READ_TERMINAL, json!({ "terminal": "t1", "screen": true })).await.unwrap(); - assert_eq!(read["output"], ""); - assert!(read["screen"].as_str().unwrap().ends_with("ls\nout\n$"), "{read}"); - - let closed = tools.call(CLOSE_TERMINAL, json!({ "terminal": "t1" })).await.unwrap(); - assert_eq!(closed["closed"], true); - let calls = shell.calls.lock().unwrap().clone(); - let (_, close) = calls.iter().find(|(m, _)| m == methods::CLOSE_TERMINAL).unwrap(); - assert_eq!(close["targetDeviceId"], "dev-remote"); - // Forgotten once closed: naming it again needs its device. - let again = tools.call(READ_TERMINAL, json!({ "terminal": "t1" })).await.unwrap(); - assert_eq!(again["device"]["id"], "dev-local"); - } -} diff --git a/crates/rpc/src/lib.rs b/crates/rpc/src/lib.rs index 4d72eb4b8..b1e7f4d33 100644 --- a/crates/rpc/src/lib.rs +++ b/crates/rpc/src/lib.rs @@ -299,6 +299,11 @@ pub mod methods { pub const CLOSE_TERMINAL: &str = "CloseTerminal"; /// Whether closing a terminal would end a program running in it. pub const TERMINAL_STATUS: &str = "TerminalStatus"; + /// `{command, cwd?, chatId?, timeoutMs?}` → `RunOutcome`: one shell + /// command run to its end on the target device (no PTY, no session), + /// its output capped and its process group killed at the timeout. + /// Relay-forwardable (Zeron MCP's `run_command`). + pub const RUN_COMMAND: &str = "RunCommand"; /// Checkout-diff stream for the target device's chats (DataRpc, /// relay-forwardable — diffs are produced where the checkout lives). pub const WATCH_CHECKOUT_DIFFS: &str = "WatchCheckoutDiffs"; @@ -780,11 +785,11 @@ pub fn app_forward_only(method: &str, params: &serde_json::Value) -> bool { /// `Review*`), signing (`SignPlugin`, `PluginSigningKey`), updating /// (`UpdatePlugin`, `UpdateTemplate`, the engine's and harnesses'), /// credentials (`AccessToken`, sign-in, `StepUp`, `DeleteAccount`), -/// files, vault and agent logins, and a command's whole output +/// terminals, files, vault and agent logins, and a command's whole output /// (`ReadToolOutput`: an agent reads a chat as its doc keeps it). -/// Terminals are here (on any of the person's devices), and the engine -/// opens them only to an agent whose chat runs with full access and no -/// sandbox (its agent gate). +/// Running a command (`RunCommand`, on any of the person's devices) is +/// here, and the engine allows it only to an agent whose chat runs with +/// full access and no sandbox (its agent gate). pub fn agent_allowed(method: &str) -> bool { matches!( method, @@ -809,14 +814,9 @@ pub fn agent_allowed(method: &str) -> bool { | methods::PUBLISH_IMAGE // Saying what the calling chat's agent waits on. | methods::AWAIT_BACKGROUND - // Terminals on any of the person's devices (Zeron MCP's - // open_terminal …): full access only (the engine's agent gate). - | methods::OPEN_TERMINAL - | methods::SUBSCRIBE_TERMINAL - | methods::WRITE_TERMINAL - | methods::RESIZE_TERMINAL - | methods::CLOSE_TERMINAL - | methods::TERMINAL_STATUS + // A command on any of the person's devices (Zeron MCP's + // run_command): full access only (the engine's agent gate). + | methods::RUN_COMMAND // Plugins: authoring, installing (lands waiting for the person), // checking for updates, exporting (to Zeron's plugin-exports // folder only: the engine refuses an agent's `to`), and their @@ -1446,6 +1446,8 @@ mod tests { methods::SET_PLUGIN_OFF, methods::REMOVE_PLUGIN, methods::SET_BUILTIN_PLUGINS, + methods::OPEN_TERMINAL, + methods::WRITE_TERMINAL, methods::WRITE_WORKSPACE_FILE, // The window's own watch of the theme files. methods::WATCH_THEMES, @@ -1463,13 +1465,10 @@ mod tests { // it to Zeron's plugin-exports folder (R29). let asked = agent.call(methods::EXPORT_PLUGIN, serde_json::json!({})).await.unwrap(); assert!(asked.as_str().unwrap().starts_with("Agent"), "{asked}"); - // Terminals reach the engine as the agent's, which opens them only - // to a chat with full access and no sandbox. - for method in [methods::OPEN_TERMINAL, methods::SUBSCRIBE_TERMINAL, methods::WRITE_TERMINAL, methods::CLOSE_TERMINAL, methods::TERMINAL_STATUS] { - assert!(agent_allowed(method), "{method}"); - let asked = agent.call(method, serde_json::json!({})).await.unwrap(); - assert!(asked.as_str().unwrap().starts_with("Agent"), "{method}: {asked}"); - } + // A command reaches the engine as the agent's, which runs it only + // for a chat with full access and no sandbox. + let asked = agent.call(methods::RUN_COMMAND, serde_json::json!({})).await.unwrap(); + assert!(asked.as_str().unwrap().starts_with("Agent"), "{asked}"); // The theme tools' methods, exactly: data only. for method in [methods::LIST_THEMES, methods::GET_THEME, methods::CREATE_THEME, methods::UPDATE_THEME, methods::DELETE_THEME, methods::USE_THEME] { assert!(agent_allowed(method), "{method}"); diff --git a/docs/design/cloud-device.md b/docs/design/cloud-device.md index d0a67d1d4..d5ac118db 100644 --- a/docs/design/cloud-device.md +++ b/docs/design/cloud-device.md @@ -132,8 +132,8 @@ The sandbox runs full-access agents on arbitrary repository code, so anything th `runner-key` can mint runner tokens. A runner token therefore acts as **its session's device** (the JWT's verified `dev` claim), never as the whole user. Like any of the person's devices, though, it reaches their other devices and every one of their chats: a Cloud chat's agent -lists and messages chats on the laptop, starts chats there, and opens terminals on any online -device, as an agent on the laptop can. Enforced at the edge: +lists and messages chats on the laptop, starts chats there, and runs commands on any online +device (`run_command`), as an agent on the laptop can. Enforced at the edge: - **Paths** (`edge/src/runner-policy.ts`, 403): no `/auth/*` org routes, no `/cloud/*`, no `/vault/*` except `POST /vault/{org}/grant` for its own device. `/device/{id}/*` fully for @@ -158,8 +158,8 @@ device, as an agent on the laptop can. Enforced at the edge: Presence is unfiltered, but a runner socket's presence/attribution device is pinned to its verified id. - **Engine** (`crates/engine/src/rpc/agent_gate.rs`): what an agent may do is the same on - Cloud as on a computer. Its terminals (`OpenTerminal` … `TerminalStatus`, here or on another - device) only from a chat with full access and no sandbox. + Cloud as on a computer. It runs commands (`RunCommand`, here or on another device) only + from a chat with full access and no sandbox. User bearers are unaffected by all of the above. From 6cb6e01366cc680a88322db050819cde3639aff6 Mon Sep 17 00:00:00 2001 From: Wing Date: Sun, 15 Nov 2026 21:11:41 +0000 Subject: [PATCH 3/7] Agents' commands on other devices work as their own shell tool does run_command now matches an agent's local shell tool: cd carries over between commands on a device (a POSIX shell's final folder, from an exit trap), and background: true leaves a dev server, watcher or long build running, read with command_output, stopped with stop_command and listed with list_commands. Background commands are bounded: newest 128 KiB of output each, 48 KiB a read, 32 running per device, ended ones remembered for at most an hour. Their process groups die when stopped, when the chat that started them is archived or deleted, and at engine shutdown. Running commands keep a Cloud machine awake and hold off updates. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/lib.rs | 8 +- crates/engine/src/rpc.rs | 29 ++ crates/engine/src/rpc/agent_gate.rs | 7 +- crates/engine/src/run_command.rs | 614 +++++++++++++++++++++++--- crates/engine/src/sessions.rs | 4 +- crates/engine/tests/agent_commands.rs | 53 +++ crates/mcp/src/jsonrpc.rs | 7 +- crates/mcp/src/tools.rs | 9 +- crates/mcp/src/tools/commands.rs | 318 ++++++++++--- crates/rpc/src/lib.rs | 24 +- docs/design/cloud-device.md | 6 +- 11 files changed, 933 insertions(+), 146 deletions(-) create mode 100644 crates/engine/tests/agent_commands.rs diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index 1f3e8cdd7..2671bab45 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -380,6 +380,8 @@ impl EngineCore { ); let terminals = Terminals::new(); sessions.track_terminal_activity(terminals.clone(), workspace.clone()); + // An agent's background commands end with its chat. + run_command::follow_chats(workspace.watch_chats()); let project_actions = ProjectActionsStore::open(profile.store_root())?; doc_host.set_project_action_runtime(project_actions.clone(), terminals.clone()); let previews = zeron_preview::PreviewService::new( @@ -513,8 +515,8 @@ impl EngineCore { self.workspace_scope } - /// When an update may restart this engine: never under a live run or an open - /// terminal. On a Cloud machine, a message waiting counts too: nothing is + /// When an update may restart this engine: never under a live run, an open + /// terminal or a running command. On a Cloud machine, a message waiting counts too: nothing is /// running yet, and a restart would land just as its turn starts. pub fn update_quiescence(&self, cloud: bool) -> zeron_update::QuiescentCheck { let sessions = self.sessions.clone(); @@ -523,6 +525,7 @@ impl EngineCore { Arc::new(move || { !sessions.any_active() && !terminals.any_open() + && run_command::running_count() == 0 && !doc_host.as_ref().is_some_and(DocHost::has_waiting_commands) }) } @@ -747,6 +750,7 @@ impl EngineCore { } self.sessions.shutdown().await; self.terminals.shutdown(); + run_command::shutdown(); self.sessions.stop_activity_projection().await; self.agent_accounts.shutdown(); self.change_requests.shutdown(); diff --git a/crates/engine/src/rpc.rs b/crates/engine/src/rpc.rs index 080ecc118..66666736e 100644 --- a/crates/engine/src/rpc.rs +++ b/crates/engine/src/rpc.rs @@ -492,6 +492,15 @@ struct RunCommandParams { chat_id: Option, #[serde(default)] timeout_ms: Option, + /// Leave it running and reply at once (`CommandStatus`). + #[serde(default)] + background: bool, +} + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct CommandIdParams { + id: String, } #[derive(Debug, Deserialize)] @@ -2600,6 +2609,9 @@ fn forwardable(method: &str) -> bool { | methods::TERMINAL_STATUS // A command runs on the device it names. | methods::RUN_COMMAND + | methods::READ_COMMAND_OUTPUT + | methods::STOP_COMMAND + | methods::LIST_BACKGROUND_COMMANDS // Agent accounts are per-device CLI logins (the device switcher // retargets which device's logins are shown). | methods::LIST_AGENT_ACCOUNTS @@ -5558,6 +5570,11 @@ impl RpcService for EngineRpc { .and_then(|chat| chat.cwd); let cwd = resolve_open_terminal_cwd(p.cwd, chat_cwd, None, &self.repos.scratch_root()) .map_err(RpcError::Failed)?; + if p.background { + let started = crate::run_command::start(&cwd, &p.command, p.chat_id.as_deref()) + .map_err(RpcError::Failed)?; + return RpcReply::value(&started); + } let timeout = p .timeout_ms .map(Duration::from_millis) @@ -5567,6 +5584,18 @@ impl RpcService for EngineRpc { .map_err(RpcError::Failed)?; RpcReply::value(&outcome) } + methods::READ_COMMAND_OUTPUT => { + let p: CommandIdParams = parse_params(params)?; + RpcReply::value(&crate::run_command::read(&p.id).map_err(RpcError::Failed)?) + } + methods::STOP_COMMAND => { + let p: CommandIdParams = parse_params(params)?; + RpcReply::value(&crate::run_command::stop(&p.id).await.map_err(RpcError::Failed)?) + } + methods::LIST_BACKGROUND_COMMANDS => { + let chat = params.get("chatId").and_then(|c| c.as_str()); + RpcReply::value(&crate::run_command::list(chat)) + } methods::TERMINAL_STATUS => { let p: TerminalIdParams = parse_params(params)?; let status = self diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index 447a8b7b2..699b3b2fe 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -87,7 +87,10 @@ impl EngineRpc { params["chatId"] = json!(chat); return Ok(params); } - let command = method == methods::RUN_COMMAND; + let command = matches!( + method, + methods::RUN_COMMAND | methods::READ_COMMAND_OUTPUT | methods::STOP_COMMAND | methods::LIST_BACKGROUND_COMMANDS + ); if !command && !matches!(method, methods::MUTATE | methods::QUEUE_MESSAGE | methods::QUEUE_COMMAND) { return Ok(params); } @@ -320,7 +323,7 @@ mod tests { chat(&core, "free", "Free", "danger-full-access", "full-access").await; let rpc = core.rpc_service(); let open = json!({"command":"ls", "targetDeviceId":"laptop"}); - for method in [methods::RUN_COMMAND] { + for method in [methods::RUN_COMMAND, methods::READ_COMMAND_OUTPUT, methods::STOP_COMMAND, methods::LIST_BACKGROUND_COMMANDS] { for who in ["careful", "sandboxed", "nowhere"] { let refused = with_caller(agent(who), async { rpc.agent_gate(method, open.clone()) }).await; assert!( diff --git a/crates/engine/src/run_command.rs b/crates/engine/src/run_command.rs index f45eabfe3..7e2ee20ad 100644 --- a/crates/engine/src/run_command.rs +++ b/crates/engine/src/run_command.rs @@ -1,27 +1,39 @@ -//! `RunCommand`: one shell command run to its end on this device, for an -//! agent on this device or another of the person's (Zeron MCP's -//! `run_command`, forwarded by `targetDeviceId`). +//! Shell commands for agents, on this device or another of the person's +//! (Zeron MCP's `run_command` & co., forwarded by `targetDeviceId`): what an +//! agent's own shell tool does on its machine, on any of them. //! -//! It works like an agent's own shell tool, not a terminal: no PTY and no -//! session. The user's shell runs the command as a login shell (`-l -c`), so -//! it gets the same PATH as their terminal. Stdin is empty, so a prompt for -//! input ends instead of hanging. The reply carries the output and the exit -//! code. What it costs is bounded: +//! - [`run`] (`RunCommand`): one command run to its end. Its output and exit +//! code come back, and where it ended up (`cwd`, from a POSIX shell), so an +//! agent's `cd` carries over to its next command. +//! - [`start`] (`RunCommand {background}`): one left running (a dev server, +//! a watcher, a long build), read with [`read`] (`ReadCommandOutput`), +//! stopped with [`stop`] (`StopCommand`), listed with [`list`] +//! (`ListCommands`). //! -//! - **Memory**: at most [`HEAD`] + [`TAIL`] bytes of output are kept per run -//! (the start and the end); what's between is counted, not kept. -//! - **Time**: every run has a timeout (at most [`MAX_TIMEOUT`]). When it -//! expires, or the call is dropped, the command's whole process group is -//! killed (Unix), so nothing it started lives on. -//! - **Concurrency**: at most [`MAX_RUNNING`] commands at once per device; -//! beyond that a run is refused, not queued. +//! No PTY and no session: the user's shell runs the command as a login shell +//! (`-l -c`, so it has the PATH their terminal has; PowerShell or cmd on +//! Windows), with empty stdin so a prompt for input ends instead of hanging. +//! What it costs is bounded: //! -//! Something the command deliberately puts in the background (`nohup x &`) -//! outlives a run that ends normally, as it would in a terminal. The run -//! stops reading output [`DRAIN`] after the shell exits, so such a process -//! never holds the reply open. +//! - **Memory**: a run keeps at most [`HEAD`] + [`TAIL`] bytes of output (its +//! start and end); a background command its newest [`RING`] bytes. What's +//! left out is counted, not kept. At most [`MAX_ENDED`] ended background +//! commands are remembered, none for longer than [`KEEP_ENDED`]. +//! - **Time**: a run has a timeout (at most [`MAX_TIMEOUT`]). Each command +//! gets its own process group (Unix), which is killed at the timeout, when +//! the call is abandoned, when a background command is stopped, when the +//! chat that started it is archived or deleted ([`follow_chats`]), and when +//! the engine shuts down ([`shutdown`]). Nothing it started lives on. +//! - **Concurrency**: at most [`MAX_RUNNING`] runs and [`MAX_BACKGROUND`] +//! background commands at once per device; past that, refused, not queued. +//! +//! Running commands count as work ([`running_count`]): a Cloud machine stays +//! awake for them, and an update waits for them. +use std::collections::{HashMap, VecDeque}; use std::process::Stdio; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, LazyLock, Mutex}; use std::time::{Duration, Instant}; use serde::Serialize; @@ -30,14 +42,32 @@ use tokio::sync::Semaphore; pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(120); pub const MAX_TIMEOUT: Duration = Duration::from_secs(600); -/// Output kept from the start of a run, and from its end. +/// Output a run keeps from its start, and from its end. const HEAD: usize = 16 * 1024; const TAIL: usize = 48 * 1024; -/// How long output is still read once the shell has exited. +/// Output a background command keeps (its newest), and the most one read +/// returns. +const RING: usize = 128 * 1024; +const MAX_READ: usize = 48 * 1024; +/// How long output is still read once a run's shell has exited. const DRAIN: Duration = Duration::from_millis(250); pub const MAX_RUNNING: usize = 16; +pub const MAX_BACKGROUND: usize = 32; +const MAX_ENDED: usize = 32; +const KEEP_ENDED: Duration = Duration::from_secs(60 * 60); static RUNNING: Semaphore = Semaphore::const_new(MAX_RUNNING); +static BACKGROUND: LazyLock>>> = LazyLock::new(Default::default); + +fn lock(mutex: &Mutex) -> std::sync::MutexGuard<'_, T> { + mutex.lock().unwrap_or_else(std::sync::PoisonError::into_inner) +} + +/// Commands running now, run or background: work in progress. +pub fn running_count() -> usize { + let background = lock(&BACKGROUND).values().filter(|c| c.ended().is_none()).count(); + MAX_RUNNING - RUNNING.available_permits() + background +} /// How one run ended. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] @@ -53,6 +83,9 @@ pub struct RunOutcome { pub omitted_bytes: u64, pub timed_out: bool, pub duration_ms: u64, + /// The folder it ended in (a POSIX shell's `pwd`), when it finished. + #[serde(skip_serializing_if = "Option::is_none")] + pub cwd: Option, } fn is_zero(n: &u64) -> bool { @@ -73,49 +106,24 @@ pub(crate) async fn run_with_shell( if command.trim().is_empty() { return Err("The command is empty".into()); } - if !std::fs::metadata(cwd).is_ok_and(|m| m.is_dir()) { - return Err(format!("No folder {cwd} on this device")); - } let _slot = RUNNING.try_acquire().map_err(|_| { format!("{MAX_RUNNING} commands are already running on this device: wait for one to finish") })?; let timeout = timeout.min(MAX_TIMEOUT); let started = Instant::now(); - - let mut cmd = tokio::process::Command::new(shell); - if crate::terminals::is_powershell(shell) { - cmd.args(["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command]); - } else if cfg!(windows) { - cmd.args(["/C", command]); - } else { - cmd.args(["-l", "-c", command]); - } - cmd.current_dir(cwd) - .stdin(Stdio::null()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - // Nothing waits on a pager or paints for a terminal that isn't there. - .env("TERM", "dumb") - .env("PAGER", "cat") - .env("GIT_PAGER", "cat") - .env("GIT_TERMINAL_PROMPT", "0") - .kill_on_drop(true); - // Its own process group, so a timeout ends everything it started. - #[cfg(unix)] - cmd.process_group(0); - #[cfg(windows)] - cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW - let mut child = cmd - .spawn() - .map_err(|e| format!("Couldn't start {shell}: {e}"))?; - let group = Group::new(child.id()); - + // Where it ends up, written by the shell as it exits. + let ended_in = posix(shell).then(|| tempfile::NamedTempFile::new().ok()).flatten(); + let script = match &ended_in { + // On the way out, however it ends (an `exit` in the command too). + Some(file) => format!( + "trap '__zeron_status=$?; pwd -P >| {} 2>/dev/null; exit $__zeron_status' EXIT\n{command}\n", + quote(&file.path().to_string_lossy()).replace('\'', r"'\''") + ), + None => command.to_owned(), + }; + let (mut child, group) = spawn(shell, cwd, &script)?; let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); - let readers = [ - child.stdout.take().map(|out| tokio::spawn(pump(out, sender.clone()))), - child.stderr.take().map(|err| tokio::spawn(pump(err, sender.clone()))), - ]; - drop(sender); + let readers = pumps(&mut child, sender); let mut output = Capped::default(); let deadline = tokio::time::Instant::now() + timeout; @@ -147,12 +155,17 @@ pub(crate) async fn run_with_shell( () = tokio::time::sleep_until(drain) => break, } } - for reader in readers.into_iter().flatten() { + for reader in readers { reader.abort(); } group.finished(); let exit_code = if timed_out { None } else { status.and_then(|s| s.code()) }; + let cwd = ended_in + .filter(|_| !timed_out) + .and_then(|file| std::fs::read_to_string(file.path()).ok()) + .map(|pwd| pwd.trim_end_matches(['\n', '\r']).to_owned()) + .filter(|pwd| !pwd.is_empty()); let (output, omitted_bytes) = output.finish(); Ok(RunOutcome { exit_code, @@ -160,10 +173,302 @@ pub(crate) async fn run_with_shell( omitted_bytes, timed_out, duration_ms: started.elapsed().as_millis() as u64, + cwd, }) } -/// Read `from` into `to` until it ends or nobody listens. +/// A background command, as [`start`], [`read`], [`stop`] and [`list`] say it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct CommandStatus { + pub id: String, + pub command: String, + pub cwd: String, + /// `running`, `exited` (on its own) or `stopped` (stopped, or its chat + /// went away, or the engine shut down). + pub status: &'static str, + #[serde(skip_serializing_if = "Option::is_none")] + pub exit_code: Option, + pub duration_ms: u64, + /// [`read`]: output since the last read. + #[serde(skip_serializing_if = "Option::is_none")] + pub output: Option, + /// [`read`]: bytes of that output no longer kept. + #[serde(skip_serializing_if = "is_zero")] + pub omitted_bytes: u64, +} + +struct Background { + id: String, + command: String, + cwd: String, + /// The chat that started it: it stops when that chat is archived or + /// deleted ([`follow_chats`]). + chat: Option, + started: Instant, + group: Group, + output: Mutex, + end: Mutex>, + /// Asked to stop: it ends as `stopped`, whatever its code. + stopping: AtomicBool, +} + +#[derive(Clone, Copy)] +struct End { + at: Instant, + code: Option, + stopped: bool, +} + +impl Background { + fn ended(&self) -> Option { + *lock(&self.end) + } + + fn status(&self, read: bool) -> CommandStatus { + let end = self.ended(); + let (output, omitted_bytes) = if read { + let (output, omitted) = lock(&self.output).read(); + (Some(output), omitted) + } else { + (None, 0) + }; + CommandStatus { + id: self.id.clone(), + command: self.command.clone(), + cwd: self.cwd.clone(), + status: match end { + None => "running", + Some(end) if end.stopped => "stopped", + Some(_) => "exited", + }, + exit_code: end.and_then(|e| e.code), + duration_ms: end.map_or(self.started.elapsed(), |e| e.at - self.started).as_millis() as u64, + output, + omitted_bytes, + } + } + + fn stop(&self) { + self.stopping.store(true, Ordering::Release); + self.group.kill(); + } +} + +/// Start `command` in `cwd` and leave it running, for `chat`. +pub fn start(cwd: &str, command: &str, chat: Option<&str>) -> Result { + start_with_shell(&crate::terminals::selected_shell(), cwd, command, chat) +} + +pub(crate) fn start_with_shell( + shell: &str, + cwd: &str, + command: &str, + chat: Option<&str>, +) -> Result { + let mut commands = lock(&BACKGROUND); + forget_ended(&mut commands); + if commands.values().filter(|c| c.ended().is_none()).count() >= MAX_BACKGROUND { + return Err(format!( + "{MAX_BACKGROUND} background commands are already running on this device: stop one first" + )); + } + let (mut child, group) = spawn(shell, cwd, command)?; + let id = format!("cmd-{}", &uuid::Uuid::new_v4().simple().to_string()[..12]); + let background = Arc::new(Background { + id: id.clone(), + command: command.to_owned(), + cwd: cwd.to_owned(), + chat: chat.map(str::to_owned), + started: Instant::now(), + group, + output: Mutex::new(Ring::default()), + end: Mutex::new(None), + stopping: AtomicBool::new(false), + }); + let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); + let readers = pumps(&mut child, sender); + let weak = Arc::downgrade(&background); + tokio::spawn(async move { + let collect = { + let weak = weak.clone(); + async move { + while let Some(chunk) = chunks.recv().await { + let Some(this) = weak.upgrade() else { return }; + lock(&this.output).push(&chunk); + } + } + }; + let mut collecting = tokio::spawn(collect); + let status = child.wait().await.ok(); + // Its last words, briefly (as a run's). + if tokio::time::timeout(DRAIN, &mut collecting).await.is_err() { + collecting.abort(); + } + let Some(this) = weak.upgrade() else { return }; + for reader in readers { + reader.abort(); + } + this.group.finished(); + *lock(&this.end) = Some(End { + at: Instant::now(), + code: status.and_then(|s| s.code()), + stopped: this.stopping.load(Ordering::Acquire), + }); + }); + let status = background.status(false); + commands.insert(id, background); + Ok(status) +} + +/// A background command's output since it was last read, and how it stands. +pub fn read(id: &str) -> Result { + let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; + Ok(command.status(true)) +} + +/// Stop a background command and everything it started; its output since +/// the last read comes back. +pub async fn stop(id: &str) -> Result { + let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; + if command.ended().is_none() { + command.stop(); + let wait = Instant::now() + Duration::from_secs(5); + while command.ended().is_none() && Instant::now() < wait { + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + Ok(command.status(true)) +} + +/// The background commands `chat` started here (every one, without a chat). +pub fn list(chat: Option<&str>) -> Vec { + let mut commands = lock(&BACKGROUND); + forget_ended(&mut commands); + let mut listed: Vec<_> = commands + .values() + .filter(|c| chat.is_none_or(|chat| c.chat.as_deref() == Some(chat))) + .map(|c| (c.started, c.status(false))) + .collect(); + listed.sort_by_key(|(started, _)| *started); + listed.into_iter().map(|(_, status)| status).collect() +} + +fn unknown(id: &str) -> String { + format!("No command {id} on this device (it may have ended over an hour ago, or the engine restarted)") +} + +/// Ended commands past [`KEEP_ENDED`], and the oldest past [`MAX_ENDED`]. +fn forget_ended(commands: &mut HashMap>) { + commands.retain(|_, c| c.ended().is_none_or(|end| end.at.elapsed() < KEEP_ENDED)); + let mut ended: Vec<(Instant, String)> = commands + .values() + .filter_map(|c| c.ended().map(|end| (end.at, c.id.clone()))) + .collect(); + if ended.len() > MAX_ENDED { + ended.sort(); + for (_, id) in &ended[..ended.len() - MAX_ENDED] { + commands.remove(id); + } + } +} + +/// Stop background commands whose chat is archived or deleted, as `chats` +/// (one engine's) change. A chat counts as deleted only once these chats +/// have shown it, so one not synced here yet isn't taken as gone. Runs while +/// `chats` does. +pub fn follow_chats(mut chats: tokio::sync::watch::Receiver>) { + tokio::spawn(async move { + // Commands whose chat these chats have shown. + let mut seen = std::collections::HashSet::::new(); + loop { + { + let commands: Vec> = lock(&BACKGROUND) + .values() + .filter(|c| c.chat.is_some() && c.ended().is_none()) + .cloned() + .collect(); + seen.retain(|id| commands.iter().any(|c| &c.id == id)); + if !commands.is_empty() { + let chats = chats.borrow_and_update(); + for command in commands { + let chat = command.chat.as_deref().and_then(|id| chats.iter().find(|c| c.id == id)); + let gone = match chat { + Some(chat) => { + seen.insert(command.id.clone()); + chat.archived + } + None => seen.contains(&command.id), + }; + if gone { + tracing::info!(command = %command.id, "its chat went away: stopping it"); + command.stop(); + } + } + } + } + if chats.changed().await.is_err() { + return; + } + } + }); +} + +/// Stop every background command (the engine is going). +pub fn shutdown() { + for command in lock(&BACKGROUND).values() { + if command.ended().is_none() { + command.stop(); + } + } +} + +/// Start the shell on `script` in `cwd`, in a process group of its own. +fn spawn(shell: &str, cwd: &str, script: &str) -> Result<(tokio::process::Child, Group), String> { + if script.trim().is_empty() { + return Err("The command is empty".into()); + } + if !std::fs::metadata(cwd).is_ok_and(|m| m.is_dir()) { + return Err(format!("No folder {cwd} on this device")); + } + let mut cmd = tokio::process::Command::new(shell); + if crate::terminals::is_powershell(shell) { + cmd.args(["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script]); + } else if cfg!(windows) { + cmd.args(["/C", script]); + } else { + cmd.args(["-l", "-c", script]); + } + cmd.current_dir(cwd) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + // Nothing waits on a pager or a password prompt. + .env("PAGER", "cat") + .env("GIT_PAGER", "cat") + .env("GIT_TERMINAL_PROMPT", "0") + .kill_on_drop(true); + #[cfg(unix)] + cmd.process_group(0); + #[cfg(windows)] + cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW + let child = cmd.spawn().map_err(|e| format!("Couldn't start {shell}: {e}"))?; + let group = Group::new(child.id()); + Ok((child, group)) +} + +/// Stdout and stderr, read into `to` as they come. +fn pumps(child: &mut tokio::process::Child, to: tokio::sync::mpsc::Sender>) -> Vec> { + let mut readers = Vec::with_capacity(2); + if let Some(out) = child.stdout.take() { + readers.push(tokio::spawn(pump(out, to.clone()))); + } + if let Some(err) = child.stderr.take() { + readers.push(tokio::spawn(pump(err, to))); + } + readers +} + async fn pump(mut from: impl AsyncRead + Unpin, to: tokio::sync::mpsc::Sender>) { let mut buf = vec![0u8; 8 * 1024]; loop { @@ -178,12 +483,22 @@ async fn pump(mut from: impl AsyncRead + Unpin, to: tokio::sync::mpsc::Sender|` this module's cwd line uses. +fn posix(shell: &str) -> bool { + let name = shell.rsplit(['/', '\\']).next().unwrap_or(shell); + matches!(name, "sh" | "bash" | "zsh" | "dash" | "ksh" | "mksh" | "ash") +} + +fn quote(path: &str) -> String { + format!("'{}'", path.replace('\'', r"'\''")) +} + +/// A command's process group. Dropped before [`Group::finished`] (the call +/// was abandoned), on a timeout, or when stopped, everything in it is killed. struct Group { #[cfg_attr(not(unix), allow(dead_code))] pid: Option, - done: std::sync::atomic::AtomicBool, + done: AtomicBool, } impl Group { @@ -194,32 +509,44 @@ impl Group { fn kill(&self) { #[cfg(unix)] if let Some(pid) = self.pid.and_then(|p| i32::try_from(p).ok()).filter(|p| *p > 0) { - // SAFETY: signals the group this run made (process_group(0)). + // SAFETY: signals the group this module made (process_group(0)). unsafe { libc::kill(-pid, libc::SIGKILL); } } + // Windows has no process groups to signal: end the tree. + #[cfg(windows)] + if let Some(pid) = self.pid { + use std::os::windows::process::CommandExt as _; + let _ = std::process::Command::new("taskkill") + .args(["/T", "/F", "/PID", &pid.to_string()]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .creation_flags(0x0800_0000) + .spawn(); + } } fn finished(&self) { - self.done.store(true, std::sync::atomic::Ordering::Release); + self.done.store(true, Ordering::Release); } } impl Drop for Group { fn drop(&mut self) { - if !self.done.load(std::sync::atomic::Ordering::Acquire) { + if !self.done.load(Ordering::Acquire) { self.kill(); } } } -/// Output kept within [`HEAD`] + [`TAIL`] bytes: the first bytes, the last -/// bytes, and a count of the rest. +/// A run's output within [`HEAD`] + [`TAIL`] bytes: the first bytes, the +/// last bytes, and a count of the rest. #[derive(Default)] struct Capped { head: Vec, - tail: std::collections::VecDeque, + tail: VecDeque, omitted: u64, } @@ -255,6 +582,37 @@ impl Capped { } } +/// A background command's newest [`RING`] bytes, and how far a reader got. +#[derive(Default)] +struct Ring { + bytes: VecDeque, + /// Bytes ever written, and ever read (or passed over). + written: u64, + read: u64, +} + +impl Ring { + fn push(&mut self, bytes: &[u8]) { + self.written += bytes.len() as u64; + let bytes = &bytes[bytes.len().saturating_sub(RING)..]; + let overflow = (self.bytes.len() + bytes.len()).saturating_sub(RING); + self.bytes.drain(..overflow); + self.bytes.extend(bytes); + } + + /// What's unread (its newest [`MAX_READ`] bytes), and how much unread + /// output was lost or left out. + fn read(&mut self) -> (String, u64) { + let kept_from = self.written - self.bytes.len() as u64; + let from = self.read.max(kept_from).max(self.written.saturating_sub(MAX_READ as u64)); + let omitted = from - self.read; + let start = (from - kept_from) as usize; + let unread: Vec = self.bytes.range(start..).copied().collect(); + self.read = self.written; + (String::from_utf8_lossy(&unread).into_owned(), omitted) + } +} + #[cfg(all(test, unix))] mod tests { use super::*; @@ -270,17 +628,31 @@ mod tests { assert_eq!(ran.exit_code, Some(3)); assert!(ran.output.contains("out\n") && ran.output.contains("err\n"), "{ran:?}"); assert!(!ran.timed_out); + let ran = sh("false", DEFAULT_TIMEOUT).await; + assert_eq!(ran.exit_code, Some(1)); // No input to wait for: a prompt reads end of input. let ran = sh("read line; echo \"got [$line]\"", DEFAULT_TIMEOUT).await; assert_eq!(ran.output, "got []\n"); } #[tokio::test] - async fn it_runs_where_it_is_asked() { + async fn it_runs_where_it_is_asked_and_says_where_it_ended() { let dir = tempfile::tempdir().unwrap(); - let ran = run_with_shell("/bin/sh", dir.path().to_str().unwrap(), "pwd", DEFAULT_TIMEOUT).await.unwrap(); + std::fs::create_dir(dir.path().join("sub")).unwrap(); let here = std::fs::canonicalize(dir.path()).unwrap(); - assert_eq!(std::fs::canonicalize(ran.output.trim()).unwrap(), here); + for shell in ["/bin/sh", "/bin/bash", "/bin/zsh"].into_iter().filter(|s| std::path::Path::new(s).exists()) { + let ran = run_with_shell(shell, dir.path().to_str().unwrap(), "pwd; cd sub", DEFAULT_TIMEOUT) + .await + .unwrap(); + assert_eq!(std::fs::canonicalize(ran.output.trim()).unwrap(), here, "{shell}"); + assert_eq!(ran.cwd.as_deref().map(std::path::PathBuf::from), Some(here.join("sub")), "{shell}"); + assert_eq!(ran.exit_code, Some(0), "{shell}"); + // An `exit` keeps its code and still says where it ended. + let ran = run_with_shell(shell, dir.path().to_str().unwrap(), "cd sub && exit 3", DEFAULT_TIMEOUT) + .await + .unwrap(); + assert_eq!((ran.exit_code, ran.cwd.map(std::path::PathBuf::from)), (Some(3), Some(here.join("sub"))), "{shell}"); + } assert!(run_with_shell("/bin/sh", "/no/such/folder", "pwd", DEFAULT_TIMEOUT).await.is_err()); assert!(run_with_shell("/bin/sh", "/tmp", " ", DEFAULT_TIMEOUT).await.is_err()); } @@ -328,6 +700,83 @@ mod tests { assert!(ran.output.len() < HEAD + TAIL + 100); } + async fn until(what: &str, mut done: impl FnMut() -> bool) { + let give_up = Instant::now() + Duration::from_secs(5); + while !done() { + assert!(Instant::now() < give_up, "{what}"); + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + + #[tokio::test] + async fn a_background_command_is_read_as_it_goes_and_stopped_with_all_it_started() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("echo ready; (sleep 1; touch {}) & while true; do sleep 0.05; done", marker.display()); + let started = start_with_shell("/bin/sh", dir.path().to_str().unwrap(), &command, Some("chat-a")).unwrap(); + assert_eq!(started.status, "running"); + let id = started.id; + let mut seen = String::new(); + until("its first output", || { + seen.push_str(&read(&id).unwrap().output.unwrap()); + seen.contains("ready") + }) + .await; + // Read once: not again. + assert_eq!(read(&id).unwrap().output.as_deref(), Some("")); + assert!(list(Some("chat-a")).iter().any(|c| c.id == id && c.status == "running")); + assert!(list(Some("chat-b")).iter().all(|c| c.id != id)); + assert!(running_count() >= 1); + + let stopped = stop(&id).await.unwrap(); + assert_eq!(stopped.status, "stopped"); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "a child outlived its stop"); + assert!(stop("cmd-nope").await.is_err()); + } + + #[tokio::test] + async fn a_background_command_that_ends_says_how() { + let started = start_with_shell("/bin/sh", "/tmp", "echo done; exit 4", None).unwrap(); + until("it ends", || read(&started.id).is_ok_and(|c| c.status == "exited")).await; + let ended = read(&started.id).unwrap(); + assert_eq!(ended.exit_code, Some(4)); + } + + #[tokio::test] + async fn a_background_command_stops_when_its_chat_goes() { + let chat = |id: &str, archived: bool| -> zeron_proto::Chat { + serde_json::from_value(serde_json::json!({ + "id": id, "deviceId": "d", "title": null, "archived": archived, "cwd": null, "branch": null, + "checkoutId": null, "config": null, "lastMessagePreview": null, "lastMessageAt": null, + "createdAt": "2026-11-15T00:00:00Z", + })) + .unwrap() + }; + let (chats, watched) = tokio::sync::watch::channel(Vec::new()); + follow_chats(watched); + // Another engine's chats, which never had these: it stops none. + let (others, other) = tokio::sync::watch::channel(Vec::new()); + follow_chats(other); + others.send_replace(vec![chat("unrelated", false)]); + let kept = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("kept")).unwrap().id; + let archived = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("archived")).unwrap().id; + let deleted = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("deleted")).unwrap().id; + let unsynced = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("not-here-yet")).unwrap().id; + chats.send_replace(vec![chat("kept", false), chat("archived", false), chat("deleted", false)]); + // Let the first list land before the second replaces it. + tokio::time::sleep(Duration::from_millis(200)).await; + chats.send_replace(vec![chat("kept", false), chat("archived", true)]); + for id in [&archived, &deleted] { + until("stopped", || read(id).is_ok_and(|c| c.status == "stopped")).await; + } + tokio::time::sleep(Duration::from_millis(100)).await; + for id in [&kept, &unsynced] { + assert_eq!(read(id).unwrap().status, "running", "{id}"); + stop(id).await.unwrap(); + } + } + #[test] fn capped_output_counts_what_it_leaves_out() { let mut capped = Capped::default(); @@ -339,4 +788,25 @@ mod tests { assert!(output.starts_with(&"a".repeat(HEAD))); assert!(output.ends_with("bend")); } + + #[test] + fn a_ring_keeps_the_newest_and_reads_each_byte_once() { + let mut ring = Ring::default(); + ring.push(b"hello "); + assert_eq!(ring.read(), ("hello ".into(), 0)); + ring.push(&vec![b'x'; RING + 100]); + ring.push(b"end"); + let (output, omitted) = ring.read(); + assert!(output.ends_with("xend") && output.len() == MAX_READ, "{}", output.len()); + assert_eq!(omitted, (RING + 100 + 3 - MAX_READ) as u64); + assert_eq!(ring.read(), (String::new(), 0)); + assert!(ring.bytes.len() <= RING); + } + + #[test] + fn only_posix_shells_report_their_folder() { + assert!(posix("/bin/zsh") && posix("/usr/bin/bash") && posix("sh")); + assert!(!posix("/usr/bin/fish") && !posix(r"C:\pwsh.exe")); + assert_eq!(quote("/tmp/a'b"), r"'/tmp/a'\''b'"); + } } diff --git a/crates/engine/src/sessions.rs b/crates/engine/src/sessions.rs index 6f5f098d1..d36957478 100644 --- a/crates/engine/src/sessions.rs +++ b/crates/engine/src/sessions.rs @@ -697,7 +697,9 @@ impl SessionsEngine { crate::runner::RunCounts { active, waiting, - background: self.background_count(), + // An agent's commands (a dev server left running) keep the + // machine awake as background work does. + background: self.background_count() + crate::run_command::running_count(), } } diff --git a/crates/engine/tests/agent_commands.rs b/crates/engine/tests/agent_commands.rs new file mode 100644 index 000000000..35749364d --- /dev/null +++ b/crates/engine/tests/agent_commands.rs @@ -0,0 +1,53 @@ +//! Zeron MCP's command tools against a real engine: what an agent runs, +//! leaves in the background, reads and stops, with real processes. +#![cfg(unix)] + +use std::sync::Arc; +use std::time::{Duration, Instant}; + +use serde_json::{Value, json}; +use zeron_engine::{EngineCore, HarnessId, default_registry}; +use zeron_mcp::{Origin, Tools, Zeron}; +use zeron_rpc::memory_client; + +#[tokio::test] +async fn an_agent_runs_commands_as_its_own_shell_tool_would() { + let dir = tempfile::tempdir().unwrap(); + let core = EngineCore::assemble(dir.path(), Arc::new(default_registry()), HarnessId::Mock, None).unwrap(); + let tools = Tools::new(Arc::new(Zeron::with_client(memory_client(core.rpc_service()), Origin::default()))); + let work = tempfile::tempdir().unwrap(); + std::fs::create_dir(work.path().join("app")).unwrap(); + let app = std::fs::canonicalize(work.path().join("app")).unwrap(); + + // Output and exit code; cd carries over to the next command. + let ran = tools + .call("run_command", json!({ "command": "cd app && echo hi && exit 3", "cwd": work.path() })) + .await + .unwrap(); + assert_eq!((ran["output"].as_str(), ran["exitCode"].as_i64()), (Some("hi\n"), Some(3)), "{ran}"); + let ran = tools.call("run_command", json!({ "command": "pwd -P" })).await.unwrap(); + assert_eq!(ran["output"].as_str().map(str::trim), app.to_str(), "{ran}"); + + // A server left running: read as it goes, then stopped. + let started = tools + .call( + "run_command", + json!({ "command": "echo listening; while true; do sleep 0.05; done", "background": true }), + ) + .await + .unwrap(); + let id = started["id"].as_str().unwrap().to_owned(); + let mut printed = String::new(); + let give_up = Instant::now() + Duration::from_secs(10); + while !printed.contains("listening") { + assert!(Instant::now() < give_up, "{printed:?}"); + let read: Value = tools.call("command_output", json!({ "id": id })).await.unwrap(); + printed.push_str(read["output"].as_str().unwrap_or_default()); + tokio::time::sleep(Duration::from_millis(50)).await; + } + let listed = tools.call("list_commands", json!({})).await.unwrap(); + assert!(listed["commands"].as_array().unwrap().iter().any(|c| c["id"] == id.as_str() && c["status"] == "running")); + let stopped = tools.call("stop_command", json!({ "id": id })).await.unwrap(); + assert_eq!(stopped["status"], "stopped", "{stopped}"); + core.sessions.shutdown().await; +} diff --git a/crates/mcp/src/jsonrpc.rs b/crates/mcp/src/jsonrpc.rs index 0445d5e52..c449c4b36 100644 --- a/crates/mcp/src/jsonrpc.rs +++ b/crates/mcp/src/jsonrpc.rs @@ -64,9 +64,10 @@ from a Cloud chat it clones the same repository, and without `cloud` it shares y unless you name another device or project. From any chat, Cloud or not, you can list and \ message chats on every one of the person's devices.\n\ \n\ -`run_command` runs a shell command on any online device (see `list_devices`) and returns its \ -output and exit code, as your own shell tool does here. Only a chat with full access and no \ -sandbox may use it.\n\ +`run_command` runs shell commands on any online device (see `list_devices`) as your own shell \ +tool does here: output and exit code, `cd` carrying over, and `background: true` for servers and \ +watchers (read them with `command_output`, stop them with `stop_command`). Only a chat with full \ +access and no sandbox may use it.\n\ \n\ When a chart, table, diagram, dashboard, or 3D view would say more than prose and \ `show_visual` is available, write a Luau visual script and show it with `show_visual` before \ diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index 86f8841aa..8b7ecf5b6 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -53,6 +53,8 @@ pub struct Tools { /// Which plugin tools the client was last shown ([`Self::list_all`], /// [`Self::watch_plugin_tools`]). plugins: plugins::PluginState, + /// Each device's folder after this chat's last command there. + command_state: commands::CommandState, } fn chat_key_schema(extra: Value) -> Value { @@ -302,7 +304,7 @@ fn catalog() -> Vec { }); tools.extend(plugins::catalog()); tools.extend(themes::catalog()); - tools.push(commands::tool()); + tools.extend(commands::catalog()); tools } @@ -821,6 +823,7 @@ impl Tools { zeron, pending_turns: Default::default(), plugins: Default::default(), + command_state: Default::default(), } } @@ -896,7 +899,9 @@ impl Tools { plugins::EXPORT_TEMPLATE | plugins::IMPORT_TEMPLATE => { return self.template_packages(name, args).await; } - commands::RUN_COMMAND => self.run_command(parse(args)?).await, + command if commands::NAMES.contains(&command) => { + return self.commands(command, args).await; + } theme if themes::NAMES.contains(&theme) => { return self.themes(theme, args).await; } diff --git a/crates/mcp/src/tools/commands.rs b/crates/mcp/src/tools/commands.rs index 12b8720a1..f30e10f3e 100644 --- a/crates/mcp/src/tools/commands.rs +++ b/crates/mcp/src/tools/commands.rs @@ -1,10 +1,20 @@ -//! `run_command`: one shell command on this device or any other of the -//! person's online devices, run to its end like an agent's own shell tool -//! (the engine's `RunCommand`, sent to another device by `targetDeviceId`). -//! Nothing is kept here between calls: the device that runs it caps the -//! output and kills what the command started when it times out -//! (crates/engine/src/run_command.rs). The engine allows it only from a chat -//! with full access and no sandbox (rpc/agent_gate.rs). +//! Shell commands on this device or any other of the person's online +//! devices, as an agent's own shell tool runs them on its machine: run one to +//! its end (`run_command`), or leave one running in the background and read +//! (`command_output`), stop (`stop_command`) or list (`list_commands`) it. +//! The engine's `RunCommand` & co., sent to another device by +//! `targetDeviceId`. The device that runs a command bounds it: its output, +//! its time, and everything it started, which ends at a timeout, a stop, or +//! when this chat is archived or deleted (crates/engine/src/run_command.rs). +//! The engine allows it only from a chat with full access and no sandbox +//! (rpc/agent_gate.rs). +//! +//! Kept here: each device's folder after the last command, so `cd` carries +//! over to the next command there, as in a shell (one short path per device). +//! A background command's id names its device (`cmd-…@device`), so nothing +//! else is kept. + +use std::collections::HashMap; use serde::Deserialize; use serde_json::{Value, json}; @@ -13,24 +23,61 @@ use zeron_rpc::{RpcError, methods}; use super::{ToolDef, Tools}; pub(super) const RUN_COMMAND: &str = "run_command"; +pub(super) const COMMAND_OUTPUT: &str = "command_output"; +pub(super) const STOP_COMMAND: &str = "stop_command"; +pub(super) const LIST_COMMANDS: &str = "list_commands"; +pub(super) const NAMES: [&str; 4] = [RUN_COMMAND, COMMAND_OUTPUT, STOP_COMMAND, LIST_COMMANDS]; + const DEFAULT_TIMEOUT_SECS: u64 = 120; const MAX_TIMEOUT_SECS: u64 = 600; -pub(super) fn tool() -> ToolDef { - ToolDef { - name: RUN_COMMAND, - description: "Run a shell command on this device, or on any other of the person's online devices (see list_devices; a Cloud machine must be awake), and get its output and exit code, as your own shell tool does here. It runs in the user's login shell (PowerShell on Windows) with no input and no terminal, in `cwd` (default: your chat's folder when it runs on your chat's device, else home). Stdout and stderr come back together; long output keeps its start and end. A command still running at `timeout_secs` is killed with everything it started (timedOut). Each call is a fresh shell: `cd` and variables don't carry over, so chain steps with && or pass cwd. Something left in the background with `nohup … &` keeps running. Only a chat with full access may use this.", - input_schema: json!({ - "type": "object", - "properties": { - "command": { "type": "string", "description": "The command, as you'd type it in a terminal there." }, - "device": { "type": "string", "description": "Device id or exact name. Omit for this device." }, - "cwd": { "type": "string", "description": "Folder on that device to run it in." }, - "timeout_secs": { "type": "integer", "minimum": 1, "maximum": MAX_TIMEOUT_SECS, "default": DEFAULT_TIMEOUT_SECS } - }, - "required": ["command"] - }), - } +/// Each device's folder after this chat's last command there. +#[derive(Default)] +pub(super) struct CommandState { + cwd: tokio::sync::Mutex>, +} + +fn device_schema() -> Value { + json!({ "type": "string", "description": "Device id or exact name (see list_devices). Omit for this device." }) +} + +fn id_schema() -> Value { + json!({ "type": "string", "description": "The command's id, from run_command with background (it names its device)." }) +} + +pub(super) fn catalog() -> Vec { + vec![ + ToolDef { + name: RUN_COMMAND, + description: "Run a shell command on this device or on any other of the person's online devices (see list_devices; a Cloud machine must be awake), exactly as you would with your own shell tool: builds, tests, git, package managers, scripts, servers. It runs in the user's login shell there (PowerShell on Windows), with their PATH, and no input or terminal. The working directory carries over between commands on the same device (`cd` sticks; environment variables don't); the first command on a device starts in `cwd`, or your chat's folder on its own device, or home. Returns `output` (stdout and stderr together; long output keeps its start and end), `exitCode`, and `timedOut`: a command still running at `timeout_secs` (default 120, at most 600) is killed with everything it started. For something that keeps running — a dev server, a watcher, a long build — pass `background: true`: it returns an `id` at once; read what it prints with command_output and stop it with stop_command. Background commands stop on their own when this chat is archived or deleted. Only a chat with full access may use this.", + input_schema: json!({ + "type": "object", + "properties": { + "command": { "type": "string", "description": "The command, as you'd type it in a terminal there." }, + "device": device_schema(), + "cwd": { "type": "string", "description": "Folder on that device to run it in (sets where later commands there start, too)." }, + "timeout_secs": { "type": "integer", "minimum": 1, "maximum": MAX_TIMEOUT_SECS, "default": DEFAULT_TIMEOUT_SECS }, + "background": { "type": "boolean", "default": false, "description": "Leave it running and return its id at once." } + }, + "required": ["command"] + }), + }, + ToolDef { + name: COMMAND_OUTPUT, + description: "What a background command printed since you last asked (its newest 48 KiB; `omittedBytes` counts what's gone), and whether it's `running`, `exited` (with `exitCode`) or `stopped`. To wait for something (a server to be ready), run_command `sleep 2` and ask again.", + input_schema: json!({ "type": "object", "properties": { "id": id_schema() }, "required": ["id"] }), + }, + ToolDef { + name: STOP_COMMAND, + description: "Stop a background command and everything it started; returns what it printed since you last asked.", + input_schema: json!({ "type": "object", "properties": { "id": id_schema() }, "required": ["id"] }), + }, + ToolDef { + name: LIST_COMMANDS, + description: "The background commands this chat started on a device (this one when omitted): each one's id, command, folder, status and how long it ran. Ended ones are listed for an hour.", + input_schema: json!({ "type": "object", "properties": { "device": device_schema() } }), + }, + ] } #[derive(Deserialize)] @@ -39,36 +86,144 @@ pub(super) struct RunArgs { device: Option, cwd: Option, timeout_secs: Option, + #[serde(default)] + background: bool, +} + +#[derive(Deserialize)] +struct IdArgs { + id: String, +} + +#[derive(Deserialize)] +struct ListArgs { + device: Option, +} + +fn parse(args: Value) -> Result { + let args = if args.is_null() { json!({}) } else { args }; + serde_json::from_value(args).map_err(|e| format!("invalid arguments: {e}")) +} + +/// An engine error in words to act on. +fn said(error: RpcError) -> anyhow::Error { + match error { + RpcError::UnknownMethod(_) => anyhow::anyhow!( + "That device's Zeron is too old to run commands: update Zeron there and restart it" + ), + RpcError::Failed(message) => anyhow::anyhow!(message), + other => anyhow::anyhow!("{other}"), + } } impl Tools { - pub(super) async fn run_command(&self, args: RunArgs) -> anyhow::Result { - anyhow::ensure!(!args.command.trim().is_empty(), "command is empty"); + pub(super) async fn commands(&self, tool: &str, args: Value) -> Result { + let result = match tool { + RUN_COMMAND => self.run_command(parse(args)?).await, + COMMAND_OUTPUT => self.command_call(methods::READ_COMMAND_OUTPUT, parse(args)?).await, + STOP_COMMAND => self.command_call(methods::STOP_COMMAND, parse(args)?).await, + _ => self.list_commands(parse(args)?).await, + }; + result.map_err(|e| format!("{e:#}")) + } + + /// The device to send to (`None`: this engine's), and how a reply names it. + async fn command_device(&self, key: Option<&str>) -> anyhow::Result<(Option, Value)> { let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; - let device = self.zeron.resolve_device_id(args.device.as_deref()).await?; + let id = self.zeron.resolve_device_id(key).await?; + let name = devices.iter().find(|d| d.id == id).map(|d| d.name.clone()); + let named = json!({ "id": id, "name": name, "local": id == local }); + Ok(((id != local).then_some(id), named)) + } + + async fn run_command(&self, args: RunArgs) -> anyhow::Result { + anyhow::ensure!(!args.command.trim().is_empty(), "command is empty"); + let (target, device) = self.command_device(args.device.as_deref()).await?; + let device_id = device["id"].as_str().unwrap_or_default().to_owned(); + let asked = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()).map(str::to_owned); + let remembered = match &asked { + Some(_) => None, + None => self.command_state.cwd.lock().await.get(&device_id).cloned(), + }; let timeout = args.timeout_secs.unwrap_or(DEFAULT_TIMEOUT_SECS).clamp(1, MAX_TIMEOUT_SECS); let mut params = json!({ "command": args.command, "timeoutMs": timeout * 1000 }); - if let Some(cwd) = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()) { - params["cwd"] = json!(cwd); + if args.background { + params["background"] = json!(true); } if let Some(chat) = &self.zeron.origin().chat_id { params["chatId"] = json!(chat); } - if device != local { - params["targetDeviceId"] = json!(device); + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); } - let mut outcome = match self.zeron.call_rpc(methods::RUN_COMMAND, params).await { - Ok(outcome) => outcome, - Err(RpcError::UnknownMethod(_)) => anyhow::bail!( - "That device's Zeron is too old to run commands: update Zeron there and restart it" - ), - Err(RpcError::Failed(message)) => anyhow::bail!(message), - Err(error) => anyhow::bail!("{error}"), + let send = |cwd: Option<&String>| { + let mut params = params.clone(); + if let Some(cwd) = cwd { + params["cwd"] = json!(cwd); + } + self.zeron.call_rpc(methods::RUN_COMMAND, params) }; - let name = devices.iter().find(|d| d.id == device).map(|d| d.name.clone()); - outcome["device"] = json!({ "id": device, "name": name, "local": device == local }); + let reply = match send(asked.as_ref().or(remembered.as_ref())).await { + // The folder it was left in is gone: start where a first one would. + Err(RpcError::Failed(message)) if remembered.is_some() && message.starts_with("No folder") => { + self.command_state.cwd.lock().await.remove(&device_id); + send(None).await + } + other => other, + }; + let mut outcome = reply.map_err(said)?; + if args.background { + if let Some(id) = outcome["id"].as_str() { + outcome["id"] = json!(format!("{id}@{device_id}")); + } + } else if let Some(cwd) = outcome["cwd"].as_str() { + self.command_state.cwd.lock().await.insert(device_id, cwd.to_owned()); + } else if let Some(asked) = asked { + // A shell that doesn't say where it ended: where it was asked. + self.command_state.cwd.lock().await.insert(device_id, asked); + } + outcome["device"] = device; Ok(outcome) } + + async fn command_call(&self, method: &str, args: IdArgs) -> anyhow::Result { + let (id, device) = match args.id.rsplit_once('@') { + Some((id, device)) => (id.to_owned(), Some(device.to_owned())), + None => (args.id.clone(), None), + }; + let (target, named) = self.command_device(device.as_deref()).await?; + let mut params = json!({ "id": id }); + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); + } + let mut status = self.zeron.call_rpc(method, params).await.map_err(said)?; + status["id"] = json!(args.id); + status["device"] = named; + Ok(status) + } + + async fn list_commands(&self, args: ListArgs) -> anyhow::Result { + let (target, named) = self.command_device(args.device.as_deref()).await?; + let device_id = named["id"].as_str().unwrap_or_default().to_owned(); + let mut params = json!({}); + if let Some(chat) = &self.zeron.origin().chat_id { + params["chatId"] = json!(chat); + } + if let Some(target) = &target { + params["targetDeviceId"] = json!(target); + } + let mut listed = self + .zeron + .call_rpc(methods::LIST_BACKGROUND_COMMANDS, params) + .await + .map_err(said)?; + for command in listed.as_array_mut().into_iter().flatten() { + if let Some(id) = command["id"].as_str() { + command["id"] = json!(format!("{id}@{device_id}")); + } + } + Ok(json!({ "device": named, "commands": listed })) + } } #[cfg(test)] @@ -78,9 +233,10 @@ mod tests { use super::*; use crate::zeron::{Origin, Zeron}; - /// Two devices; `RunCommand` answers with what it was asked. + /// Two devices. `RunCommand` ends wherever `cd` took it; the rest answer + /// with what they were asked. struct Engine { - calls: std::sync::Mutex>, + calls: std::sync::Mutex>, old_remote: bool, } @@ -89,6 +245,12 @@ mod tests { async fn handle(&self, method: &str, params: Value) -> Result { use futures::StreamExt; use zeron_rpc::RpcReply; + if method.contains("Command") { + if self.old_remote && params["targetDeviceId"] == "dev-remote" { + return Err(RpcError::UnknownMethod(method.into())); + } + self.calls.lock().unwrap().push((method.to_owned(), params.clone())); + } Ok(match method { methods::LOCAL_DEVICE => RpcReply::Value(json!({ "deviceId": "dev-local" })), methods::WATCH_DEVICES => RpcReply::Stream( @@ -98,13 +260,25 @@ mod tests { ])]) .boxed(), ), - methods::RUN_COMMAND => { - if self.old_remote && params["targetDeviceId"] == "dev-remote" { - return Err(RpcError::UnknownMethod(method.into())); - } - self.calls.lock().unwrap().push(params); - RpcReply::Value(json!({ "exitCode": 0, "output": "hi\n", "timedOut": false, "durationMs": 5 })) + methods::RUN_COMMAND if params["background"] == true => { + RpcReply::Value(json!({ "id": "cmd-1", "status": "running", "command": params["command"] })) } + methods::RUN_COMMAND => { + if params["cwd"] == "/gone" { + return Err(RpcError::Failed("No folder /gone on this device".into())); + } + let cwd = params["command"] + .as_str() + .and_then(|c| c.strip_prefix("cd ")) + .map(str::to_owned) + .or_else(|| params["cwd"].as_str().map(str::to_owned)) + .unwrap_or_else(|| "/home/me".into()); + RpcReply::Value(json!({ "exitCode": 0, "output": "hi\n", "timedOut": false, "durationMs": 5, "cwd": cwd })) + } + methods::READ_COMMAND_OUTPUT | methods::STOP_COMMAND => { + RpcReply::Value(json!({ "id": params["id"], "status": "running", "output": "listening\n" })) + } + methods::LIST_BACKGROUND_COMMANDS => RpcReply::Value(json!([{ "id": "cmd-1", "status": "running" }])), other => return Err(RpcError::UnknownMethod(other.into())), }) } @@ -115,32 +289,64 @@ mod tests { Tools::new(Arc::new(Zeron::with_client(zeron_rpc::memory_client(engine), origin))) } + fn last(engine: &Engine) -> (String, Value) { + engine.calls.lock().unwrap().last().cloned().unwrap() + } + #[tokio::test] - async fn a_command_runs_on_the_device_it_names() { + async fn a_command_runs_on_the_device_it_names_and_cd_carries_over_there() { let engine = Arc::new(Engine { calls: Default::default(), old_remote: false }); let tools = tools(engine.clone()); let ran = tools .call(RUN_COMMAND, json!({ "command": "echo hi", "device": "Worker", "cwd": "/srv", "timeout_secs": 5 })) .await .unwrap(); - assert_eq!(ran["output"], "hi\n"); - assert_eq!(ran["exitCode"], 0); + assert_eq!((ran["output"].as_str(), ran["exitCode"].as_i64()), (Some("hi\n"), Some(0))); assert_eq!(ran["device"], json!({ "id": "dev-remote", "name": "Worker", "local": false })); - let sent = engine.calls.lock().unwrap().last().cloned().unwrap(); assert_eq!( - sent, + last(&engine).1, json!({ "command": "echo hi", "cwd": "/srv", "timeoutMs": 5000, "chatId": "chat-1", "targetDeviceId": "dev-remote" }) ); - - // This device: no target; a timeout is bounded. + // cd there sticks there, and only there. + tools.call(RUN_COMMAND, json!({ "command": "cd /srv/app", "device": "Worker" })).await.unwrap(); + tools.call(RUN_COMMAND, json!({ "command": "ls", "device": "Worker" })).await.unwrap(); + assert_eq!(last(&engine).1["cwd"], "/srv/app"); tools.call(RUN_COMMAND, json!({ "command": "ls", "timeout_secs": 100000 })).await.unwrap(); - let sent = engine.calls.lock().unwrap().last().cloned().unwrap(); - assert!(sent.get("targetDeviceId").is_none()); - assert_eq!(sent["timeoutMs"], MAX_TIMEOUT_SECS * 1000); + let (_, here) = last(&engine); + assert!(here.get("cwd").is_none() && here.get("targetDeviceId").is_none(), "{here}"); + assert_eq!(here["timeoutMs"], MAX_TIMEOUT_SECS * 1000); + // A folder that's gone: back to where a first command starts. + tools.call(RUN_COMMAND, json!({ "command": "cd /gone" })).await.unwrap(); + tools.call(RUN_COMMAND, json!({ "command": "ls" })).await.unwrap(); + assert!(last(&engine).1.get("cwd").is_none()); assert!(tools.call(RUN_COMMAND, json!({ "command": " " })).await.unwrap_err().contains("empty")); } + #[tokio::test] + async fn a_background_command_is_found_again_by_its_id_wherever_it_runs() { + let engine = Arc::new(Engine { calls: Default::default(), old_remote: false }); + let tools = tools(engine.clone()); + let started = tools + .call(RUN_COMMAND, json!({ "command": "npm run dev", "device": "Worker", "background": true })) + .await + .unwrap(); + assert_eq!(started["id"], "cmd-1@dev-remote"); + assert_eq!(last(&engine).1["background"], true); + + let read = tools.call(COMMAND_OUTPUT, json!({ "id": "cmd-1@dev-remote" })).await.unwrap(); + assert_eq!(read["output"], "listening\n"); + assert_eq!(read["id"], "cmd-1@dev-remote"); + assert_eq!(last(&engine), (methods::READ_COMMAND_OUTPUT.to_owned(), json!({ "id": "cmd-1", "targetDeviceId": "dev-remote" }))); + + tools.call(STOP_COMMAND, json!({ "id": "cmd-1@dev-remote" })).await.unwrap(); + assert_eq!(last(&engine).0, methods::STOP_COMMAND); + + let listed = tools.call(LIST_COMMANDS, json!({ "device": "Worker" })).await.unwrap(); + assert_eq!(listed["commands"][0]["id"], "cmd-1@dev-remote"); + assert_eq!(last(&engine).1, json!({ "chatId": "chat-1", "targetDeviceId": "dev-remote" })); + } + #[tokio::test] async fn an_older_device_says_so() { let tools = tools(Arc::new(Engine { calls: Default::default(), old_remote: true })); diff --git a/crates/rpc/src/lib.rs b/crates/rpc/src/lib.rs index b1e7f4d33..92c5697e1 100644 --- a/crates/rpc/src/lib.rs +++ b/crates/rpc/src/lib.rs @@ -299,11 +299,20 @@ pub mod methods { pub const CLOSE_TERMINAL: &str = "CloseTerminal"; /// Whether closing a terminal would end a program running in it. pub const TERMINAL_STATUS: &str = "TerminalStatus"; - /// `{command, cwd?, chatId?, timeoutMs?}` → `RunOutcome`: one shell - /// command run to its end on the target device (no PTY, no session), - /// its output capped and its process group killed at the timeout. - /// Relay-forwardable (Zeron MCP's `run_command`). + /// `{command, cwd?, chatId?, timeoutMs?, background?}` → `RunOutcome`: + /// one shell command run to its end on the target device (no PTY, no + /// session), its output capped and its process group killed at the + /// timeout; with `background`, → `CommandStatus` of one left running. + /// Relay-forwardable, as are the three below (Zeron MCP's `run_command`, + /// `command_output`, `stop_command`, `list_commands`). pub const RUN_COMMAND: &str = "RunCommand"; + /// `{id}` → `CommandStatus`: a background command's output since it was + /// last read, and whether it still runs. + pub const READ_COMMAND_OUTPUT: &str = "ReadCommandOutput"; + /// `{id}` → `CommandStatus`: stop a background command and all it started. + pub const STOP_COMMAND: &str = "StopCommand"; + /// `{chatId?}` → `[CommandStatus]`: the background commands a chat started. + pub const LIST_BACKGROUND_COMMANDS: &str = "ListBackgroundCommands"; /// Checkout-diff stream for the target device's chats (DataRpc, /// relay-forwardable — diffs are produced where the checkout lives). pub const WATCH_CHECKOUT_DIFFS: &str = "WatchCheckoutDiffs"; @@ -814,9 +823,12 @@ pub fn agent_allowed(method: &str) -> bool { | methods::PUBLISH_IMAGE // Saying what the calling chat's agent waits on. | methods::AWAIT_BACKGROUND - // A command on any of the person's devices (Zeron MCP's - // run_command): full access only (the engine's agent gate). + // Commands on any of the person's devices (Zeron MCP's + // run_command & co.): full access only (the engine's agent gate). | methods::RUN_COMMAND + | methods::READ_COMMAND_OUTPUT + | methods::STOP_COMMAND + | methods::LIST_BACKGROUND_COMMANDS // Plugins: authoring, installing (lands waiting for the person), // checking for updates, exporting (to Zeron's plugin-exports // folder only: the engine refuses an agent's `to`), and their diff --git a/docs/design/cloud-device.md b/docs/design/cloud-device.md index d5ac118db..001a67a56 100644 --- a/docs/design/cloud-device.md +++ b/docs/design/cloud-device.md @@ -158,8 +158,10 @@ device (`run_command`), as an agent on the laptop can. Enforced at the edge: Presence is unfiltered, but a runner socket's presence/attribution device is pinned to its verified id. - **Engine** (`crates/engine/src/rpc/agent_gate.rs`): what an agent may do is the same on - Cloud as on a computer. It runs commands (`RunCommand`, here or on another device) only - from a chat with full access and no sandbox. + Cloud as on a computer. It runs commands (`RunCommand`, `ReadCommandOutput`, `StopCommand`, + `ListBackgroundCommands`, here or on another device) only from a chat with full access and no + sandbox. A command running on a Cloud machine counts as background work in its heartbeat, + so the machine stays awake for it. User bearers are unaffected by all of the above. From c57fdcf84192dd69a9d3fcca3e42f18049b68453 Mon Sep 17 00:00:00 2001 From: Wing Date: Sun, 15 Nov 2026 21:35:25 +0000 Subject: [PATCH 4/7] Commands an agent leaves running show in its chat's background band MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chat's host tracks each background command its agent starts with run_command, on that device or another, and lists it on the chat's session row with the runtime's own background processes ("on "). Every 5 s, while any are tracked, it asks each device which are still running, keeping the row fresh and dropping ended ones (and those on a device unreachable for 2 minutes). The band's Stop and output view route cmd-… ids to the device running the command; the output view reads the newest output without moving what the agent reads next. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/rpc.rs | 149 ++++++++++++++++++++++++++++ crates/engine/src/rpc/agent_gate.rs | 76 ++++++++++++++ crates/engine/src/run_command.rs | 41 ++++++++ crates/engine/src/sessions.rs | 96 ++++++++++++++++++ 4 files changed, 362 insertions(+) diff --git a/crates/engine/src/rpc.rs b/crates/engine/src/rpc.rs index 66666736e..56d8f9f82 100644 --- a/crates/engine/src/rpc.rs +++ b/crates/engine/src/rpc.rs @@ -501,6 +501,10 @@ struct RunCommandParams { #[serde(rename_all = "camelCase")] struct CommandIdParams { id: String, + /// The newest output, for a person looking: what its agent reads next + /// stays as it was. + #[serde(default)] + tail: bool, } #[derive(Debug, Deserialize)] @@ -1918,6 +1922,110 @@ impl EngineRpc { } } + /// A background command the calling agent just started (`device`: where, + /// `None` here): its chat shows it with its runtime's background + /// processes until it ends. Only an agent's own call: a peer forwarding + /// one here is running it for a chat hosted there. + fn track_command(&self, device: Option<&str>, started: &serde_json::Value) { + let zeron_rpc::Caller::Agent { chat: Some(chat) } = zeron_rpc::caller() else { + return; + }; + let Some(id) = started["id"].as_str() else { + return; + }; + let name = device.and_then(|device| { + self.workspace + .read_devices() + .ok()? + .into_iter() + .find(|d| d.id == device) + .map(|d| d.name) + }); + let task = zeron_proto::BackgroundTask { + id: match device { + Some(device) => format!("{id}@{device}"), + None => id.to_owned(), + }, + command: started["command"].as_str().unwrap_or_default().to_owned(), + description: name.map(|name| format!("on {name}")), + started_at: chrono::Utc::now(), + }; + let command = crate::run_command::CommandTask { + device: device.map(str::to_owned), + id: id.to_owned(), + task, + }; + if self.sessions.track_command(&chat, command) { + let rpc = self.clone(); + tokio::spawn(async move { rpc.follow_commands().await }); + } + } + + /// While any are tracked: every few seconds, ask each device which of a + /// chat's commands still run, and show those. A device out of reach + /// keeps its commands shown for [`COMMAND_UNREACHABLE`], then they go. + async fn follow_commands(self) { + const EVERY: Duration = Duration::from_secs(5); + const COMMAND_UNREACHABLE: Duration = Duration::from_secs(120); + let mut unreachable: std::collections::HashMap = Default::default(); + loop { + tokio::time::sleep(EVERY).await; + if !self.sessions.commands_followed() { + return; + } + for (chat, commands) in self.sessions.tracked_commands() { + let mut devices: Vec> = commands.iter().map(|c| c.device.clone()).collect(); + devices.sort(); + devices.dedup(); + // Per device: the ids still running, or `None` if it couldn't say. + let mut running: std::collections::HashMap, Option>> = Default::default(); + for device in devices { + let listed = match &device { + None => Some(serde_json::to_value(crate::run_command::list(Some(&chat))).unwrap_or_default()), + Some(target) => match tokio::time::timeout( + Duration::from_secs(10), + self.forward(target, methods::LIST_BACKGROUND_COMMANDS, serde_json::json!({ "chatId": chat })), + ) + .await + { + Ok(Ok(RpcReply::Value(value))) => Some(value), + _ => None, + }, + }; + let ids = listed.map(|listed| { + listed + .as_array() + .into_iter() + .flatten() + .filter(|c| c["status"] == "running") + .filter_map(|c| c["id"].as_str().map(str::to_owned)) + .collect() + }); + if let Some(target) = &device { + if ids.is_some() { + unreachable.remove(target); + } else { + unreachable.entry(target.clone()).or_insert_with(std::time::Instant::now); + } + } + running.insert(device, ids); + } + let still: Vec<_> = commands + .into_iter() + .filter(|c| match running.get(&c.device) { + Some(Some(ids)) => ids.contains(&c.id), + _ => c + .device + .as_ref() + .and_then(|d| unreachable.get(d)) + .is_none_or(|since| since.elapsed() < COMMAND_UNREACHABLE), + }) + .collect(); + self.sessions.set_tracked_commands(&chat, still); + } + } + } + /// Terminal I/O for a terminal on `target`: a direct link when the two /// devices can reach each other, the relay otherwise /// ([`crate::remote_terminals`]). Writes never wait on the network. @@ -3286,6 +3394,13 @@ impl RpcService for EngineRpc { if method == methods::APPLY_UPDATE { return self.forward_apply_update(&target, params).await; } + if method == methods::RUN_COMMAND && params["background"] == true { + let started = self.forward(&target, method, params).await?; + if let RpcReply::Value(started) = &started { + self.track_command(Some(&target), started); + } + return Ok(started); + } return self.forward(&target, method, params).await; } if matches!( @@ -3899,6 +4014,20 @@ impl RpcService for EngineRpc { } methods::STOP_BACKGROUND_TASK => { let p: BackgroundTaskParams = parse_params(params)?; + // A command its agent left running with run_command, wherever. + if let Some((id, device)) = crate::run_command::CommandTask::parse(&p.task_id) { + match device.filter(|d| d != self.doc_host.device_id()) { + Some(device) => { + self.forward(&device, methods::STOP_COMMAND, serde_json::json!({ "id": id })) + .await?; + } + None => { + crate::run_command::stop(&id).await.map_err(RpcError::Failed)?; + } + } + self.sessions.untrack_command(&p.chat_id, &p.task_id); + return RpcReply::value(&serde_json::json!({ "stopping": true })); + } let stopping = self.sessions.stop_background_task(&p.chat_id, &p.task_id); RpcReply::value(&serde_json::json!({ "stopping": stopping })) } @@ -3933,6 +4062,20 @@ impl RpcService for EngineRpc { } methods::READ_BACKGROUND_TASK_OUTPUT => { let p: BackgroundTaskParams = parse_params(params)?; + if let Some((id, device)) = crate::run_command::CommandTask::parse(&p.task_id) { + let output = match device.filter(|d| d != self.doc_host.device_id()) { + Some(device) => match self + .forward(&device, methods::READ_COMMAND_OUTPUT, serde_json::json!({ "id": id, "tail": true })) + .await + { + Ok(RpcReply::Value(value)) => serde_json::from_value(value).ok(), + _ => None, + }, + None => crate::run_command::tail(&id).ok(), + }; + let output: Option = output; + return RpcReply::value(&output); + } let output = self .sessions .background_task_output(&p.chat_id, &p.task_id) @@ -5573,6 +5716,9 @@ impl RpcService for EngineRpc { if p.background { let started = crate::run_command::start(&cwd, &p.command, p.chat_id.as_deref()) .map_err(RpcError::Failed)?; + if let Ok(value) = serde_json::to_value(&started) { + self.track_command(None, &value); + } return RpcReply::value(&started); } let timeout = p @@ -5586,6 +5732,9 @@ impl RpcService for EngineRpc { } methods::READ_COMMAND_OUTPUT => { let p: CommandIdParams = parse_params(params)?; + if p.tail { + return RpcReply::value(&crate::run_command::tail(&p.id).map_err(RpcError::Failed)?); + } RpcReply::value(&crate::run_command::read(&p.id).map_err(RpcError::Failed)?) } methods::STOP_COMMAND => { diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index 699b3b2fe..8960943e8 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -352,6 +352,82 @@ mod tests { core.sessions.shutdown().await; } + /// A command an agent leaves running shows on its chat's row with its + /// runtime's background processes: the person reads it (without taking + /// what the agent reads next) and stops it there; one that ends goes. + #[tokio::test] + async fn a_chat_shows_the_commands_its_agent_left_running() { + let (_temp, core) = core().await; + chat(&core, "free", "Free", "danger-full-access", "full-access").await; + core.sessions.seed_status("free", zeron_proto::SessionStatus::Working); + let rpc = core.rpc_service(); + let dir = tempfile::tempdir().unwrap(); + let value = |reply: zeron_rpc::RpcReply| match reply { + zeron_rpc::RpcReply::Value(value) => value, + zeron_rpc::RpcReply::Stream(_) => panic!("a stream"), + }; + let start = |command: &str| { + with_caller( + agent("free"), + rpc.handle( + methods::RUN_COMMAND, + json!({"command": command, "cwd": dir.path(), "chatId": "free", "background": true}), + ), + ) + }; + let server = value(start("echo listening; while true; do sleep 0.05; done").await.unwrap()); + let quick = value(start("echo done").await.unwrap()); + let shown = |core: &crate::EngineCore| -> Vec { + core.sessions + .session_status("free") + .map(|s| s.background_tasks.into_iter().map(|t| t.id).collect()) + .unwrap_or_default() + }; + let server_id = server["id"].as_str().unwrap().to_owned(); + let quick_id = quick["id"].as_str().unwrap().to_owned(); + assert_eq!(shown(&core), vec![server_id.clone(), quick_id.clone()]); + + // The person reads it; the agent still reads it all after. + let give_up = std::time::Instant::now() + std::time::Duration::from_secs(5); + loop { + let tail = value( + rpc.handle(methods::READ_BACKGROUND_TASK_OUTPUT, json!({"chatId": "free", "taskId": server_id})) + .await + .unwrap(), + ); + if tail["text"].as_str().is_some_and(|t| t.contains("listening")) { + break; + } + assert!(std::time::Instant::now() < give_up, "{tail}"); + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + } + let read = value( + with_caller(agent("free"), rpc.handle(methods::READ_COMMAND_OUTPUT, json!({"id": server_id}))) + .await + .unwrap(), + ); + assert_eq!(read["output"], "listening\n"); + + // One that ended goes from the row on the next look. + let give_up = std::time::Instant::now() + std::time::Duration::from_secs(12); + while shown(&core).contains(&quick_id) { + assert!(std::time::Instant::now() < give_up, "{:?}", shown(&core)); + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + } + assert_eq!(shown(&core), vec![server_id.clone()]); + + // Stopped from the row, the person's call: gone, and it ended. + let stopped = value( + rpc.handle(methods::STOP_BACKGROUND_TASK, json!({"chatId": "free", "taskId": server_id})) + .await + .unwrap(), + ); + assert_eq!(stopped["stopping"], true); + assert!(shown(&core).is_empty()); + assert_eq!(crate::run_command::read(&server_id).unwrap().status, "stopped"); + core.sessions.shutdown().await; + } + /// An agent can't raise a chat's access after the fact, nor delete. #[tokio::test] async fn an_agent_cannot_change_a_chats_config() { diff --git a/crates/engine/src/run_command.rs b/crates/engine/src/run_command.rs index 7e2ee20ad..91cb62f70 100644 --- a/crates/engine/src/run_command.rs +++ b/crates/engine/src/run_command.rs @@ -321,6 +321,47 @@ pub(crate) fn start_with_shell( Ok(status) } +/// A background command its agent's chat shows with its runtime's own +/// background processes (`Session::background_tasks`), tracked by the chat's +/// host wherever the command runs. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CommandTask { + /// Where it runs; `None`: the chat's host itself. + pub device: Option, + /// Its id there (`cmd-…`). + pub id: String, + /// As shown: its id is `cmd-…@device` for one elsewhere, the `id` its + /// agent was given. + pub task: zeron_proto::BackgroundTask, +} + +impl CommandTask { + /// A task id that names a command (`cmd-…`, `cmd-…@device`): its id and + /// device. `None` for a runtime's own task. + pub fn parse(task_id: &str) -> Option<(String, Option)> { + if !task_id.starts_with("cmd-") { + return None; + } + Some(match task_id.rsplit_once('@') { + Some((id, device)) => (id.to_owned(), Some(device.to_owned())), + None => (task_id.to_owned(), None), + }) + } +} + +/// The newest [`MAX_READ`] bytes a background command printed, for a person +/// looking (it doesn't move what its agent reads next). +pub fn tail(id: &str) -> Result { + let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; + let ring = lock(&command.output); + let start = ring.bytes.len().saturating_sub(MAX_READ); + let newest: Vec = ring.bytes.range(start..).copied().collect(); + Ok(zeron_proto::BackgroundTaskOutput { + text: String::from_utf8_lossy(&newest).into_owned(), + truncated: ring.written > newest.len() as u64, + }) +} + /// A background command's output since it was last read, and how it stands. pub fn read(id: &str) -> Result { let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; diff --git a/crates/engine/src/sessions.rs b/crates/engine/src/sessions.rs index d36957478..61fdb076e 100644 --- a/crates/engine/src/sessions.rs +++ b/crates/engine/src/sessions.rs @@ -258,6 +258,13 @@ struct Revival { struct Inner { voice: crate::voice::VoiceManager, device_id: String, + /// Per chat: the background processes its runtime runs (as it last + /// said), and the background commands its agent started with Zeron's + /// `run_command`, here or on another device. Its session row shows both. + runtime_tasks: Mutex>>, + command_tasks: Mutex>>, + /// A task follows the tracked commands (see [`SessionsEngine::track_command`]). + command_tracker: std::sync::atomic::AtomicBool, /// The engine is shutting down: dying runs re-dispatch nothing. shutting_down: std::sync::atomic::AtomicBool, /// A shutdown marks the turns it cuts off for pick-up on the next boot @@ -358,6 +365,9 @@ impl SessionsEngine { inner: Arc::new(Inner { voice: crate::voice::VoiceManager::default(), device_id, + runtime_tasks: Mutex::new(HashMap::new()), + command_tasks: Mutex::new(HashMap::new()), + command_tracker: std::sync::atomic::AtomicBool::new(false), shutting_down: std::sync::atomic::AtomicBool::new(false), revive_after_shutdown: std::sync::atomic::AtomicBool::new(true), revivals: Mutex::new(HashMap::new()), @@ -562,6 +572,12 @@ impl SessionsEngine { .subscribe() } + /// A status row for `chat_id`, as a run would leave (tests). + #[cfg(test)] + pub(crate) fn seed_status(&self, chat_id: &str, status: SessionStatus) { + self.inner.set_status(chat_id, status, true); + } + pub fn session_status(&self, chat_id: &str) -> Option { lock(&self.inner.statuses).get(chat_id).cloned() } @@ -636,6 +652,68 @@ impl SessionsEngine { /// Ask the chat's runtime to stop one of its background processes. False /// when no live runtime lists it (it ended meanwhile). + /// A background command `chat_id`'s agent started with `run_command` + /// (here or on another device): shown on its session row with its + /// runtime's processes until it ends. True when nothing follows the + /// tracked commands yet: the caller starts [`Self::follow_commands`]'s + /// loop. + pub fn track_command(&self, chat_id: &str, command: crate::run_command::CommandTask) -> bool { + lock(&self.inner.command_tasks) + .entry(chat_id.to_owned()) + .or_default() + .push(command); + self.inner.publish_background_tasks(chat_id); + !self + .inner + .command_tracker + .swap(true, std::sync::atomic::Ordering::AcqRel) + } + + /// Every chat's tracked commands. + pub fn tracked_commands(&self) -> HashMap> { + lock(&self.inner.command_tasks).clone() + } + + /// The tracked commands of `chat_id` still running, as just checked: + /// shown, and the row kept fresh while there are any. + pub fn set_tracked_commands(&self, chat_id: &str, commands: Vec) { + let changed = { + let mut tracked = lock(&self.inner.command_tasks); + let before = tracked.get(chat_id).map_or(0, Vec::len); + let after = commands.len(); + if commands.is_empty() { + tracked.remove(chat_id); + } else { + tracked.insert(chat_id.to_owned(), commands); + } + before != after + }; + if changed { + self.inner.publish_background_tasks(chat_id); + } + self.inner.touch_session(chat_id); + } + + /// One tracked command no longer shown (it was stopped). + pub fn untrack_command(&self, chat_id: &str, task_id: &str) { + let mut commands = lock(&self.inner.command_tasks).get(chat_id).cloned().unwrap_or_default(); + commands.retain(|c| c.task.id != task_id); + self.set_tracked_commands(chat_id, commands); + } + + /// Nothing is tracked any more: the loop following them ends (false), or + /// something was tracked meanwhile and it goes on (true). + pub fn commands_followed(&self) -> bool { + let tracked = lock(&self.inner.command_tasks); + if tracked.is_empty() { + self.inner + .command_tracker + .store(false, std::sync::atomic::Ordering::Release); + return false; + } + true + } + pub fn stop_background_task(&self, chat_id: &str, task_id: &str) -> bool { lock(&self.inner.runs) .get(chat_id) @@ -2640,6 +2718,24 @@ impl Inner { /// like [`Self::set_running_subagents`]. The live heartbeat keeps the row /// fresh while they run; an engine that stops beating took them with it. fn set_background_tasks(&self, chat_id: &str, tasks: Vec) { + { + let mut runtime = lock(&self.runtime_tasks); + if tasks.is_empty() { + runtime.remove(chat_id); + } else { + runtime.insert(chat_id.to_owned(), tasks); + } + } + self.publish_background_tasks(chat_id); + } + + /// The session row's background processes: its runtime's, then the + /// commands its agent left running with `run_command`. + fn publish_background_tasks(&self, chat_id: &str) { + let mut tasks = lock(&self.runtime_tasks).get(chat_id).cloned().unwrap_or_default(); + if let Some(commands) = lock(&self.command_tasks).get(chat_id) { + tasks.extend(commands.iter().map(|c| c.task.clone())); + } let session = { let mut statuses = lock(&self.statuses); let Some(entry) = statuses.get_mut(chat_id) else { From a64d0d398a381e2a786dfd19da974a839beac3d3 Mon Sep 17 00:00:00 2001 From: Wing Date: Mon, 16 Nov 2026 00:58:01 +0000 Subject: [PATCH 5/7] Commands on the engine's own foundations; Cloud widening's regressions fixed Commands (redone with no shortcuts): - commands::Commands is an engine-owned service like Terminals, shut down with EngineCore, wired into update quiescence and the Cloud heartbeat; no process-wide state (one engine could stop another's commands before). - Each command runs as zeron_harness::process::owned::Child (now public): its own process group / Job Object, TERM then KILL after a grace with escaped descendants, killed on drop, no nested-Claude markers. Anything a command leaves running ends with it; background: true is for that. - The login shell's PATH and variables come from the harness's snapshot (new compose_user_path), captured once: plain `-c`, no profile per run. - PowerShell gets -EncodedCommand (no quoting), passes a native command's exit code on and says where it ended; Windows-only tests for CI. - The background band follows each device's WatchBackgroundCommands stream instead of polling: an ended command leaves as it ends; the row keeps the live heartbeat's cadence. - stop waits on the command's end (watch), not a sleep loop. Cloud regressions found in review: - A Cloud machine that synced before it saw every row gets one full state (RegistryRoom.runnerBehind), again until its cursor passes it. - A Cloud machine's send wakes any of the person's sleeping sessions. - A runner may set any field of a chat hosted elsewhere but its host, so a branch or model set on a laptop chat lands instead of being dropped. - Only the session chat's project resolves to a Cloud machine's checkout. - OpenTerminal takes a chat's folder, and attaches to it, only for a chat this device runs (as project actions already require). Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/commands.rs | 1262 +++++++++++++++++ crates/engine/src/lib.rs | 32 +- crates/engine/src/rpc.rs | 241 ++-- crates/engine/src/rpc/agent_gate.rs | 102 +- crates/engine/src/run_command.rs | 853 ----------- crates/engine/src/sessions.rs | 101 +- crates/engine/src/workspace_files.rs | 83 +- crates/engine/tests/agent_commands.rs | 47 +- crates/engine/tests/cloud_rpc.rs | 36 +- .../engine/tests/m5_repos_diffs_terminals.rs | 42 + crates/harness/src/lib.rs | 10 + crates/harness/src/process.rs | 2 +- crates/harness/src/process/owned.rs | 10 +- crates/mcp/src/tools/commands.rs | 163 ++- crates/rpc/src/lib.rs | 9 +- docs/design/cloud-device.md | 14 +- edge/src/cloud/cloud-account.ts | 4 +- edge/src/cloud/routes.ts | 7 +- edge/src/registry-room.ts | 39 +- edge/src/registry-runner.test.ts | 14 +- edge/src/registry-runner.ts | 24 +- .../workerd/cloud-delegates.workerd.test.ts | 7 + .../workerd/runner-boundary.workerd.test.ts | 30 +- 23 files changed, 1979 insertions(+), 1153 deletions(-) create mode 100644 crates/engine/src/commands.rs delete mode 100644 crates/engine/src/run_command.rs diff --git a/crates/engine/src/commands.rs b/crates/engine/src/commands.rs new file mode 100644 index 000000000..6bd47931d --- /dev/null +++ b/crates/engine/src/commands.rs @@ -0,0 +1,1262 @@ +//! Shell commands for agents, on this device or another of the person's +//! (Zeron MCP's `run_command` & co., forwarded by `targetDeviceId`): what an +//! agent's own shell tool does on its machine, on any of them. Owned by the +//! engine ([`crate::EngineCore`]) like its terminals, and shut down with it. +//! +//! - [`Commands::run`] (`RunCommand`): one command run to its end. Its +//! output and exit code come back, and the folder it ended in (`cwd`, from +//! a POSIX shell), so an agent's `cd` carries over to its next command. +//! - [`Commands::start`] (`RunCommand {background}`): one left running (a dev +//! server, a watcher, a long build), read with [`Commands::read`], stopped +//! with [`Commands::stop`], listed with [`Commands::list`] and watched with +//! [`Commands::watch`] (`WatchBackgroundCommands`: how the chat's host +//! keeps its background band current, wherever the command runs). +//! +//! No PTY and no session. The user's shell runs the command (`-c`; +//! PowerShell or cmd on Windows) with the PATH and variables their login +//! shell sets, captured once per process ([`zeron_harness::compose_user_path`]), +//! and empty stdin, so a prompt for input ends instead of hanging. Each runs +//! as an owned process ([`zeron_harness::process::owned`]): a process group +//! (Job Object on Windows) of its own, without the markers of a Claude +//! session Zeron may itself run in. What it costs is bounded: +//! +//! - **Memory**: a run keeps at most [`HEAD`] + [`TAIL`] bytes of output (its +//! start and end); a background command its newest [`RING`] bytes. What's +//! left out is counted, not kept. At most [`MAX_ENDED`] ended background +//! commands are remembered, none for longer than [`KEEP_ENDED`]. +//! - **Processes**: when a command ends, so does everything it started. At +//! its timeout, on a stop, when the chat that started it is archived or +//! deleted ([`Commands::follow_chats`]), and at engine shutdown, its group +//! is asked to stop and killed after [`GRACE`]; a call abandoned mid-run +//! kills it at once. +//! - **Concurrency**: at most [`MAX_RUNNING`] runs and [`MAX_BACKGROUND`] +//! background commands at once per device; past that, refused, not queued. +//! +//! Running commands count as work ([`Commands::running`]): a Cloud machine +//! stays awake for them, and an update waits for them. + +use std::collections::{HashMap, VecDeque}; +use std::sync::{Arc, Mutex, Weak}; +use std::time::{Duration, Instant}; + +use futures::StreamExt as _; +use futures::stream::BoxStream; +use serde::Serialize; +use tokio::io::{AsyncRead, AsyncReadExt}; +use tokio::sync::{Notify, Semaphore, watch}; +use zeron_harness::process::{Command, Stdio, owned}; + +pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(120); +pub const MAX_TIMEOUT: Duration = Duration::from_secs(600); +/// Output a run keeps from its start, and from its end. +const HEAD: usize = 16 * 1024; +const TAIL: usize = 48 * 1024; +/// Output a background command keeps (its newest), and the most one read +/// returns. +const RING: usize = 128 * 1024; +const MAX_READ: usize = 48 * 1024; +/// How long output is still read once a shell has exited: a process that +/// left the group (`setsid`) may hold the pipes open for good. +const DRAIN: Duration = Duration::from_millis(250); +/// Between asking a command's processes to stop and killing them. +pub const GRACE: Duration = Duration::from_secs(2); +pub const MAX_RUNNING: usize = 16; +pub const MAX_BACKGROUND: usize = 32; +const MAX_ENDED: usize = 32; +const KEEP_ENDED: Duration = Duration::from_secs(60 * 60); + +fn lock(mutex: &Mutex) -> std::sync::MutexGuard<'_, T> { + mutex + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) +} + +/// This engine's agents' commands. Cheap to clone (shared state). +#[derive(Clone)] +pub struct Commands { + inner: Arc, +} + +struct Inner { + shell: String, + kind: ShellKind, + running: Semaphore, + background: Mutex>>, + /// Bumped when a background command starts, ends or is forgotten. + changes: watch::Sender, + /// Commands shown on chats hosted here, followed wherever they run: one + /// task per (chat, device), `None` being this one ([`Commands::show`]). + followers: Mutex), tokio::task::AbortHandle>>, +} + +impl Default for Commands { + fn default() -> Self { + Self::with_shell(crate::terminals::selected_shell()) + } +} + +/// How one run ended. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct RunOutcome { + /// `None` when it was killed (timed out, or by a signal). + pub exit_code: Option, + /// Stdout and stderr together, in the order they arrived. When it was + /// too long, its start and end with a line saying how much was left out. + pub output: String, + /// Bytes of output left out of the middle. + #[serde(skip_serializing_if = "is_zero")] + pub omitted_bytes: u64, + pub timed_out: bool, + pub duration_ms: u64, + /// The folder it ended in (a POSIX shell's `pwd`), when it finished. + #[serde(skip_serializing_if = "Option::is_none")] + pub cwd: Option, +} + +fn is_zero(n: &u64) -> bool { + *n == 0 +} + +/// A background command, as [`Commands::start`], [`Commands::read`], +/// [`Commands::stop`] and [`Commands::list`] say it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct CommandStatus { + pub id: String, + pub command: String, + pub cwd: String, + /// `running`, `exited` (on its own) or `stopped` (stopped, or its chat + /// went away, or the engine shut down). + pub status: &'static str, + #[serde(skip_serializing_if = "Option::is_none")] + pub exit_code: Option, + pub duration_ms: u64, + /// [`Commands::read`]: output since the last read. + #[serde(skip_serializing_if = "Option::is_none")] + pub output: Option, + /// [`Commands::read`]: bytes of that output no longer kept. + #[serde(skip_serializing_if = "is_zero")] + pub omitted_bytes: u64, +} + +/// A background command its agent's chat shows with its runtime's own +/// background processes (`Session::background_tasks`), followed by the +/// chat's host wherever the command runs. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CommandTask { + /// Where it runs; `None`: the chat's host itself. + pub device: Option, + /// Its id there (`cmd-…`). + pub id: String, + /// As shown: `cmd-…@device` for one elsewhere, the id its agent was given. + pub task: zeron_proto::BackgroundTask, +} + +impl CommandTask { + /// A task id that names a command (`cmd-…`, `cmd-…@device`): its id and + /// device. `None` for a runtime's own task. + pub fn parse(task_id: &str) -> Option<(String, Option)> { + if !task_id.starts_with("cmd-") { + return None; + } + Some(match task_id.rsplit_once('@') { + Some((id, device)) => (id.to_owned(), Some(device.to_owned())), + None => (task_id.to_owned(), None), + }) + } +} + +struct Background { + id: String, + command: String, + cwd: String, + /// The chat that started it: it stops when that chat is archived or + /// deleted ([`Commands::follow_chats`]). + chat: Option, + started: Instant, + output: Mutex, + end: watch::Sender>, + stop: Notify, +} + +#[derive(Clone, Copy)] +struct End { + at: Instant, + code: Option, + stopped: bool, +} + +impl Background { + fn ended(&self) -> Option { + *self.end.borrow() + } + + fn status(&self, read: bool) -> CommandStatus { + let end = self.ended(); + let (output, omitted_bytes) = if read { + let (output, omitted) = lock(&self.output).read(); + (Some(output), omitted) + } else { + (None, 0) + }; + CommandStatus { + id: self.id.clone(), + command: self.command.clone(), + cwd: self.cwd.clone(), + status: match end { + None => "running", + Some(end) if end.stopped => "stopped", + Some(_) => "exited", + }, + exit_code: end.and_then(|e| e.code), + duration_ms: end + .map_or(self.started.elapsed(), |e| e.at - self.started) + .as_millis() as u64, + output, + omitted_bytes, + } + } + + /// Ask it to stop, and wait (a bounded while) until it has. + async fn stop(&self) { + self.stop.notify_one(); + let mut end = self.end.subscribe(); + let _ = tokio::time::timeout(GRACE * 3, end.wait_for(Option::is_some)).await; + } +} + +impl Commands { + pub(crate) fn with_shell(shell: String) -> Self { + Self { + inner: Arc::new(Inner { + kind: ShellKind::of(&shell), + shell, + running: Semaphore::new(MAX_RUNNING), + background: Mutex::new(HashMap::new()), + changes: watch::Sender::new(0), + followers: Mutex::new(HashMap::new()), + }), + } + } + + /// Commands running now, run or background: work in progress. + pub fn running(&self) -> usize { + let background = lock(&self.inner.background) + .values() + .filter(|c| c.ended().is_none()) + .count(); + MAX_RUNNING - self.inner.running.available_permits() + background + } + + /// Run `command` in `cwd` to its end, for at most `timeout`. + pub async fn run( + &self, + cwd: &str, + command: &str, + timeout: Duration, + ) -> Result { + if command.trim().is_empty() { + return Err("The command is empty".into()); + } + let _slot = self.inner.running.try_acquire().map_err(|_| { + format!( + "{MAX_RUNNING} commands are already running on this device: wait for one to finish" + ) + })?; + let timeout = timeout.min(MAX_TIMEOUT); + let started = Instant::now(); + // Where it ends up, written by the shell as it exits. + let ended_in = self + .inner + .kind + .says_folder() + .then(|| tempfile::NamedTempFile::new().ok()) + .flatten(); + let script = self + .inner + .kind + .script(command, ended_in.as_ref().map(|file| file.path())); + let mut child = spawn(&self.inner.shell, self.inner.kind, cwd, &script)?; + let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); + let readers = pumps(&mut child, sender); + + let mut output = Capped::default(); + let deadline = tokio::time::Instant::now() + timeout; + let mut status = None; + // Until the shell exits (or time is up), taking output as it comes. + let timed_out = loop { + tokio::select! { + exited = child.wait() => { + status = exited.ok(); + break false; + } + Some(chunk) = chunks.recv() => output.push(&chunk), + () = tokio::time::sleep_until(deadline) => break true, + } + }; + if timed_out { + child.shutdown(GRACE).await; + } + drain(&mut chunks, |chunk| output.push(chunk)).await; + for reader in readers { + reader.abort(); + } + // Everything it started goes with it. + drop(child); + + let cwd = ended_in + .filter(|_| !timed_out) + .and_then(|file| std::fs::read_to_string(file.path()).ok()) + .map(|pwd| pwd.trim_end_matches(['\n', '\r']).to_owned()) + .filter(|pwd| !pwd.is_empty()); + let (output, omitted_bytes) = output.finish(); + Ok(RunOutcome { + exit_code: if timed_out { + None + } else { + status.and_then(|s| s.code()) + }, + output, + omitted_bytes, + timed_out, + duration_ms: started.elapsed().as_millis() as u64, + cwd, + }) + } + + /// Start `command` in `cwd` and leave it running, for `chat`. + pub fn start( + &self, + cwd: &str, + command: &str, + chat: Option<&str>, + ) -> Result { + if command.trim().is_empty() { + return Err("The command is empty".into()); + } + let mut commands = lock(&self.inner.background); + forget_ended(&mut commands); + if commands.values().filter(|c| c.ended().is_none()).count() >= MAX_BACKGROUND { + return Err(format!( + "{MAX_BACKGROUND} background commands are already running on this device: stop one first" + )); + } + let script = self.inner.kind.script(command, None); + let mut child = spawn(&self.inner.shell, self.inner.kind, cwd, &script)?; + let id = format!("cmd-{}", &uuid::Uuid::new_v4().simple().to_string()[..12]); + let background = Arc::new(Background { + id: id.clone(), + command: command.to_owned(), + cwd: cwd.to_owned(), + chat: chat.map(str::to_owned), + started: Instant::now(), + output: Mutex::new(Ring::default()), + end: watch::Sender::new(None), + stop: Notify::new(), + }); + let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); + let readers = pumps(&mut child, sender); + let this = background.clone(); + let inner = Arc::downgrade(&self.inner); + tokio::spawn(async move { + let mut stopped = false; + let status = loop { + tokio::select! { + exited = child.wait() => break exited.ok(), + Some(chunk) = chunks.recv() => lock(&this.output).push(&chunk), + () = this.stop.notified() => { + stopped = true; + child.shutdown(GRACE).await; + break child.wait().await.ok(); + } + } + }; + drain(&mut chunks, |chunk| lock(&this.output).push(chunk)).await; + for reader in readers { + reader.abort(); + } + drop(child); + this.end.send_replace(Some(End { + at: Instant::now(), + code: status.and_then(|s| s.code()), + stopped, + })); + if let Some(inner) = inner.upgrade() { + inner.changes.send_modify(|n| *n += 1); + } + }); + let status = background.status(false); + commands.insert(id, background); + drop(commands); + self.inner.changes.send_modify(|n| *n += 1); + Ok(status) + } + + fn get(&self, id: &str) -> Result, String> { + lock(&self.inner.background).get(id).cloned().ok_or_else(|| { + format!("No command {id} on this device (it may have ended over an hour ago, or Zeron restarted there)") + }) + } + + /// A background command's output since it was last read, and how it stands. + pub fn read(&self, id: &str) -> Result { + Ok(self.get(id)?.status(true)) + } + + /// The newest output a background command printed, for a person + /// looking: what its agent reads next stays as it was. + pub fn tail(&self, id: &str) -> Result { + let command = self.get(id)?; + let ring = lock(&command.output); + let start = ring.bytes.len().saturating_sub(MAX_READ); + let newest: Vec = ring.bytes.range(start..).copied().collect(); + Ok(zeron_proto::BackgroundTaskOutput { + text: String::from_utf8_lossy(&newest).into_owned(), + truncated: ring.written > newest.len() as u64, + }) + } + + /// Stop a background command and everything it started; its output since + /// the last read comes back. + pub async fn stop(&self, id: &str) -> Result { + let command = self.get(id)?; + if command.ended().is_none() { + command.stop().await; + } + Ok(command.status(true)) + } + + /// The background commands `chat` started here (every one, without a chat). + pub fn list(&self, chat: Option<&str>) -> Vec { + let mut commands = lock(&self.inner.background); + if forget_ended(&mut commands) { + self.inner.changes.send_modify(|n| *n += 1); + } + let mut listed: Vec<_> = commands + .values() + .filter(|c| chat.is_none_or(|chat| c.chat.as_deref() == Some(chat))) + .map(|c| (c.started, c.status(false))) + .collect(); + listed.sort_by_key(|(started, _)| *started); + listed.into_iter().map(|(_, status)| status).collect() + } + + /// [`Self::list`] for `chat` now, and again each time a background + /// command starts or ends (`WatchBackgroundCommands`). + pub fn watch(&self, chat: String) -> BoxStream<'static, serde_json::Value> { + let changes = self.inner.changes.subscribe(); + let commands = Arc::downgrade(&self.inner); + futures::stream::unfold( + (changes, commands, true), + move |(mut changes, commands, first)| { + let chat = chat.clone(); + async move { + if !first { + changes.changed().await.ok()?; + } + changes.borrow_and_update(); + let listed = Commands { + inner: commands.upgrade()?, + } + .list(Some(&chat)); + let value = serde_json::to_value(listed).ok()?; + Some((value, (changes, commands, false))) + } + }, + ) + .boxed() + } + + /// Show `task` on `chat`'s session row, and make sure something follows + /// the commands of `chat` on `task.device`: `follow` starts that task + /// when nothing does yet. The follower ends through [`Self::followed`]. + pub fn show( + &self, + sessions: &crate::sessions::SessionsEngine, + chat: &str, + task: CommandTask, + follow: impl FnOnce() -> tokio::task::JoinHandle<()>, + ) { + let mut followers = lock(&self.inner.followers); + let key = (chat.to_owned(), task.device.clone()); + sessions.show_command(chat, task); + followers + .entry(key) + .or_insert_with(|| follow().abort_handle()); + } + + /// A follower's check before it ends: true while `chat` still shows + /// commands on `device` (it goes on); otherwise it's forgotten (false). + pub fn followed( + &self, + sessions: &crate::sessions::SessionsEngine, + chat: &str, + device: &Option, + ) -> bool { + let mut followers = lock(&self.inner.followers); + if sessions.shown_commands_on(chat, device) > 0 { + return true; + } + followers.remove(&(chat.to_owned(), device.clone())); + false + } + + /// Stop background commands whose chat is archived or deleted, as + /// `chats` (this engine's) change. A chat counts as deleted only once + /// these chats have shown it, so one not synced here yet isn't taken as + /// gone. Ends with the engine. + pub fn follow_chats(&self, mut chats: watch::Receiver>) { + let inner: Weak = Arc::downgrade(&self.inner); + tokio::spawn(async move { + // Commands whose chat these chats have shown. + let mut seen = std::collections::HashSet::::new(); + loop { + let Some(live) = inner.upgrade() else { return }; + let commands: Vec> = lock(&live.background) + .values() + .filter(|c| c.chat.is_some() && c.ended().is_none()) + .cloned() + .collect(); + drop(live); + seen.retain(|id| commands.iter().any(|c| &c.id == id)); + let gone: Vec> = { + let chats = chats.borrow_and_update(); + commands + .into_iter() + .filter(|command| { + match command + .chat + .as_deref() + .and_then(|id| chats.iter().find(|c| c.id == id)) + { + Some(chat) => { + seen.insert(command.id.clone()); + chat.archived + } + None => seen.contains(&command.id), + } + }) + .collect() + }; + for command in gone { + tracing::info!(command = %command.id, "its chat went away: stopping it"); + command.stop.notify_one(); + } + if chats.changed().await.is_err() { + return; + } + } + }); + } + + /// Stop every background command (and what it started) and every + /// follower: the engine is going. + pub async fn shutdown(&self) { + for (_, follower) in lock(&self.inner.followers).drain() { + follower.abort(); + } + let running: Vec> = lock(&self.inner.background) + .values() + .filter(|c| c.ended().is_none()) + .cloned() + .collect(); + futures::future::join_all(running.iter().map(|c| c.stop())).await; + } +} + +/// What the user's shell is, for how a command is handed to it. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum ShellKind { + /// sh, bash, zsh, …: `-c`, and it says where it ended (`trap … EXIT`). + Posix, + /// PowerShell 7 or Windows PowerShell: `-EncodedCommand` (no quoting to + /// get wrong), a native command's exit code passed on, and where it + /// ended. + PowerShell, + /// cmd.exe, on a Windows without PowerShell: `/D /S /C`. + Cmd, + /// Any other Unix shell (fish, …): `-c`. + Other, +} + +/// The longest PowerShell command line Windows takes (32 767 characters), +/// with room for the shell's path and flags. +const MAX_ENCODED_COMMAND: usize = 32_000; + +impl ShellKind { + fn of(shell: &str) -> Self { + let name = shell.rsplit(['/', '\\']).next().unwrap_or(shell); + let stem = name + .rsplit_once('.') + .map_or(name, |(stem, _)| stem) + .to_ascii_lowercase(); + if crate::terminals::is_powershell(shell) { + Self::PowerShell + } else if matches!( + stem.as_str(), + "sh" | "bash" | "zsh" | "dash" | "ksh" | "mksh" | "ash" + ) { + Self::Posix + } else if cfg!(windows) || stem == "cmd" { + Self::Cmd + } else { + Self::Other + } + } + + fn says_folder(self) -> bool { + matches!(self, Self::Posix | Self::PowerShell) + } + + /// `command` as this shell runs it; with `ended_in`, it also writes the + /// folder it ended in there (in PowerShell, not after an `exit`). + fn script(self, command: &str, ended_in: Option<&std::path::Path>) -> String { + match (self, ended_in) { + (Self::Posix, Some(path)) => format!( + "trap '__zeron_status=$?; pwd -P >| {} 2>/dev/null; exit $__zeron_status' EXIT\n{command}\n", + quote(&path.to_string_lossy()).replace('\'', r"'\''") + ), + (Self::PowerShell, ended_in) => { + let say_folder = ended_in.map_or_else(String::new, |path| { + format!( + "try {{ [System.IO.File]::WriteAllText('{}', (Get-Location).ProviderPath) }} catch {{}}\n", + path.to_string_lossy().replace('\'', "''") + ) + }); + // Out in UTF-8 (as it's read back), without progress bars; + // a failure exits with a native command's own code, else 1. + format!( + "$ProgressPreference = 'SilentlyContinue'\n\ + try {{ [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 }} catch {{}}\n\ + $OutputEncoding = [System.Text.Encoding]::UTF8\n\ + {command}\n\ + $__zeronOk = $?\n\ + $__zeronCode = $global:LASTEXITCODE\n\ + {say_folder}\ + if (-not $__zeronOk) {{ if ($__zeronCode) {{ exit $__zeronCode }}; exit 1 }}\n\ + exit 0\n" + ) + } + _ => command.to_owned(), + } + } + + fn args(self, script: &str) -> Result, String> { + Ok(match self { + Self::PowerShell => { + use base64::Engine as _; + let utf16: Vec = script.encode_utf16().flat_map(u16::to_le_bytes).collect(); + let encoded = base64::engine::general_purpose::STANDARD.encode(utf16); + if encoded.len() > MAX_ENCODED_COMMAND { + return Err(format!( + "This command is too long for PowerShell's command line ({} characters): put it in a script file and run that", + script.len() + )); + } + [ + "-NoLogo", + "-NoProfile", + "-NonInteractive", + "-EncodedCommand", + ] + .into_iter() + .map(str::to_owned) + .chain([encoded]) + .collect() + } + // `/S`: cmd strips the quotes around the command itself. + Self::Cmd => vec!["/D".into(), "/S".into(), "/C".into(), script.into()], + Self::Posix | Self::Other => vec!["-c".into(), script.into()], + }) + } +} + +/// Start the shell on `script` in `cwd` as an owned process. +fn spawn(shell: &str, kind: ShellKind, cwd: &str, script: &str) -> Result { + if !std::fs::metadata(cwd).is_ok_and(|m| m.is_dir()) { + return Err(format!("No folder {cwd} on this device")); + } + let mut cmd = Command::new(shell); + cmd.args(kind.args(script)?); + cmd.current_dir(cwd) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + // Nothing waits on a pager or a password prompt. + .env("PAGER", "cat") + .env("GIT_PAGER", "cat") + .env("GIT_TERMINAL_PROMPT", "0"); + zeron_harness::compose_user_path(&mut cmd); + owned::configure(&mut cmd); + let child = cmd + .spawn() + .map_err(|e| format!("Couldn't start {shell}: {e}"))?; + Ok(owned::Child::new(child)) +} + +/// Stdout and stderr, read into `to` as they come. +fn pumps( + child: &mut owned::Child, + to: tokio::sync::mpsc::Sender>, +) -> Vec> { + let mut readers = Vec::with_capacity(2); + if let Some(out) = child.stdout.take() { + readers.push(tokio::spawn(pump(out, to.clone()))); + } + if let Some(err) = child.stderr.take() { + readers.push(tokio::spawn(pump(err, to))); + } + readers +} + +async fn pump(mut from: impl AsyncRead + Unpin, to: tokio::sync::mpsc::Sender>) { + let mut buf = vec![0u8; 8 * 1024]; + loop { + match from.read(&mut buf).await { + Ok(0) | Err(_) => return, + Ok(n) => { + if to.send(buf[..n].to_vec()).await.is_err() { + return; + } + } + } + } +} + +/// What's still in the pipes once the shell has exited, for at most [`DRAIN`]. +async fn drain(chunks: &mut tokio::sync::mpsc::Receiver>, mut take: impl FnMut(&[u8])) { + let until = tokio::time::Instant::now() + DRAIN; + loop { + tokio::select! { + chunk = chunks.recv() => match chunk { + Some(chunk) => take(&chunk), + None => return, + }, + () = tokio::time::sleep_until(until) => return, + } + } +} + +/// Ended commands past [`KEEP_ENDED`], and the oldest past [`MAX_ENDED`]; +/// whether any went. +fn forget_ended(commands: &mut HashMap>) -> bool { + let before = commands.len(); + commands.retain(|_, c| c.ended().is_none_or(|end| end.at.elapsed() < KEEP_ENDED)); + let mut ended: Vec<(Instant, String)> = commands + .values() + .filter_map(|c| c.ended().map(|end| (end.at, c.id.clone()))) + .collect(); + if ended.len() > MAX_ENDED { + ended.sort(); + for (_, id) in &ended[..ended.len() - MAX_ENDED] { + commands.remove(id); + } + } + commands.len() != before +} + +fn quote(path: &str) -> String { + format!("'{}'", path.replace('\'', r"'\''")) +} + +/// A run's output within [`HEAD`] + [`TAIL`] bytes: the first bytes, the +/// last bytes, and a count of the rest. +#[derive(Default)] +struct Capped { + head: Vec, + tail: VecDeque, + omitted: u64, +} + +impl Capped { + fn push(&mut self, mut bytes: &[u8]) { + if self.head.len() < HEAD { + let take = bytes.len().min(HEAD - self.head.len()); + self.head.extend_from_slice(&bytes[..take]); + bytes = &bytes[take..]; + } + if bytes.len() >= TAIL { + self.omitted += (self.tail.len() + bytes.len() - TAIL) as u64; + self.tail.clear(); + bytes = &bytes[bytes.len() - TAIL..]; + } + let overflow = (self.tail.len() + bytes.len()).saturating_sub(TAIL); + self.tail.drain(..overflow); + self.omitted += overflow as u64; + self.tail.extend(bytes); + } + + fn finish(self) -> (String, u64) { + let head = String::from_utf8_lossy(&self.head).into_owned(); + let tail: Vec = self.tail.into(); + let tail = String::from_utf8_lossy(&tail).into_owned(); + if self.omitted == 0 { + return (head + &tail, 0); + } + ( + format!( + "{head}\n… {} bytes of output left out …\n{tail}", + self.omitted + ), + self.omitted, + ) + } +} + +/// A background command's newest [`RING`] bytes, and how far a reader got. +#[derive(Default)] +struct Ring { + bytes: VecDeque, + /// Bytes ever written, and ever read (or passed over). + written: u64, + read: u64, +} + +impl Ring { + fn push(&mut self, bytes: &[u8]) { + self.written += bytes.len() as u64; + let bytes = &bytes[bytes.len().saturating_sub(RING)..]; + let overflow = (self.bytes.len() + bytes.len()).saturating_sub(RING); + self.bytes.drain(..overflow); + self.bytes.extend(bytes); + } + + /// What's unread (its newest [`MAX_READ`] bytes), and how much unread + /// output was lost or left out. + fn read(&mut self) -> (String, u64) { + let kept_from = self.written - self.bytes.len() as u64; + let from = self + .read + .max(kept_from) + .max(self.written.saturating_sub(MAX_READ as u64)); + let omitted = from - self.read; + let start = (from - kept_from) as usize; + let unread: Vec = self.bytes.range(start..).copied().collect(); + self.read = self.written; + (String::from_utf8_lossy(&unread).into_owned(), omitted) + } +} + +#[cfg(all(test, unix))] +mod tests { + use super::*; + + fn sh() -> Commands { + Commands::with_shell("/bin/sh".into()) + } + + async fn run(command: &str, timeout: Duration) -> RunOutcome { + let dir = std::env::temp_dir(); + sh().run(dir.to_str().unwrap(), command, timeout) + .await + .unwrap() + } + + async fn until(what: &str, mut done: impl FnMut() -> bool) { + let give_up = Instant::now() + Duration::from_secs(10); + while !done() { + assert!(Instant::now() < give_up, "{what}"); + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + + #[tokio::test] + async fn a_command_gives_its_output_and_exit_code() { + let ran = run("echo out; echo err >&2; exit 3", DEFAULT_TIMEOUT).await; + assert_eq!(ran.exit_code, Some(3)); + assert!( + ran.output.contains("out\n") && ran.output.contains("err\n"), + "{ran:?}" + ); + assert!(!ran.timed_out); + assert_eq!(run("false", DEFAULT_TIMEOUT).await.exit_code, Some(1)); + // No input to wait for: a prompt reads end of input. + assert_eq!( + run("read line; echo \"got [$line]\"", DEFAULT_TIMEOUT) + .await + .output, + "got []\n" + ); + // Not a nested Claude session's child. + let ran = run("echo \"[${CLAUDECODE:-}]\"", DEFAULT_TIMEOUT).await; + assert_eq!(ran.output, "[]\n"); + } + + #[tokio::test] + async fn it_runs_where_it_is_asked_and_says_where_it_ended() { + let dir = tempfile::tempdir().unwrap(); + std::fs::create_dir(dir.path().join("sub")).unwrap(); + let here = std::fs::canonicalize(dir.path()).unwrap(); + for shell in ["/bin/sh", "/bin/bash", "/bin/zsh"] + .into_iter() + .filter(|s| std::path::Path::new(s).exists()) + { + let commands = Commands::with_shell(shell.into()); + let ran = commands + .run(dir.path().to_str().unwrap(), "pwd; cd sub", DEFAULT_TIMEOUT) + .await + .unwrap(); + assert_eq!( + std::fs::canonicalize(ran.output.trim()).unwrap(), + here, + "{shell}" + ); + assert_eq!( + ran.cwd.map(std::path::PathBuf::from), + Some(here.join("sub")), + "{shell}" + ); + // An `exit` keeps its code and still says where it ended. + let ran = commands + .run( + dir.path().to_str().unwrap(), + "cd sub && exit 3", + DEFAULT_TIMEOUT, + ) + .await + .unwrap(); + assert_eq!( + (ran.exit_code, ran.cwd.map(std::path::PathBuf::from)), + (Some(3), Some(here.join("sub"))), + "{shell}" + ); + } + assert!( + sh().run("/no/such/folder", "pwd", DEFAULT_TIMEOUT) + .await + .is_err() + ); + assert!(sh().run("/tmp", " ", DEFAULT_TIMEOUT).await.is_err()); + } + + #[tokio::test] + async fn a_timeout_ends_everything_the_command_started() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("(sleep 1; touch {}) & sleep 30", marker.display()); + let started = Instant::now(); + let ran = run(&command, Duration::from_millis(300)).await; + assert!(ran.timed_out); + assert_eq!(ran.exit_code, None); + assert!( + started.elapsed() < GRACE + Duration::from_secs(2), + "{:?}", + started.elapsed() + ); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "a child outlived the timeout"); + } + + #[tokio::test] + async fn an_abandoned_run_ends_everything_it_started() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("sleep 1; touch {}", marker.display()); + assert!( + tokio::time::timeout(Duration::from_millis(200), run(&command, DEFAULT_TIMEOUT)) + .await + .is_err() + ); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "the command outlived its caller"); + } + + #[tokio::test] + async fn what_a_run_leaves_behind_ends_with_it_and_never_holds_the_reply() { + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!("(sleep 1; touch {}) & echo started", marker.display()); + let started = Instant::now(); + let ran = run(&command, DEFAULT_TIMEOUT).await; + assert_eq!((ran.exit_code, ran.output.as_str()), (Some(0), "started\n")); + assert!( + started.elapsed() < Duration::from_secs(1), + "{:?}", + started.elapsed() + ); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!( + !marker.exists(), + "left running: background: true is for that" + ); + } + + #[tokio::test] + async fn long_output_keeps_its_start_and_end_within_bounds() { + let ran = run( + "echo FIRST; head -c 1000000 /dev/zero | tr '\\0' x; echo; echo LAST", + DEFAULT_TIMEOUT, + ) + .await; + assert!(ran.output.starts_with("FIRST\n") && ran.output.ends_with("LAST\n")); + assert!(ran.omitted_bytes > 900_000); + assert!(ran.output.len() < HEAD + TAIL + 100); + } + + #[tokio::test] + async fn a_background_command_is_read_as_it_goes_and_stopped_with_all_it_started() { + let commands = sh(); + let dir = tempfile::tempdir().unwrap(); + let marker = dir.path().join("survived"); + let command = format!( + "echo ready; (sleep 1; touch {}) & while true; do sleep 0.05; done", + marker.display() + ); + let id = commands + .start(dir.path().to_str().unwrap(), &command, Some("chat-a")) + .unwrap() + .id; + assert_eq!(commands.running(), 1); + let mut seen = String::new(); + until("its first output", || { + seen.push_str(&commands.read(&id).unwrap().output.unwrap()); + seen.contains("ready") + }) + .await; + // A person looking doesn't take what the agent reads next. + assert!(commands.tail(&id).unwrap().text.contains("ready")); + assert_eq!(commands.read(&id).unwrap().output.as_deref(), Some("")); + assert_eq!(commands.list(Some("chat-a")).len(), 1); + assert!(commands.list(Some("chat-b")).is_empty()); + + let stopped = commands.stop(&id).await.unwrap(); + assert_eq!(stopped.status, "stopped"); + assert_eq!(commands.running(), 0); + tokio::time::sleep(Duration::from_millis(1500)).await; + assert!(!marker.exists(), "a child outlived its stop"); + assert!(commands.stop("cmd-nope").await.is_err()); + } + + #[tokio::test] + async fn a_background_command_that_ends_says_how_and_is_watched_ending() { + let commands = sh(); + let mut watched = commands.watch("chat-w".into()); + assert_eq!(watched.next().await.unwrap(), serde_json::json!([])); + let id = commands + .start("/tmp", "echo done; exit 4", Some("chat-w")) + .unwrap() + .id; + let mut ended = false; + while !ended { + let listed = tokio::time::timeout(Duration::from_secs(5), watched.next()) + .await + .unwrap() + .unwrap(); + ended = listed[0]["status"] == "exited"; + } + let read = commands.read(&id).unwrap(); + assert_eq!( + (read.exit_code, read.output.as_deref()), + (Some(4), Some("done\n")) + ); + } + + #[tokio::test] + async fn a_background_command_stops_when_its_chat_goes() { + let chat = |id: &str, archived: bool| -> zeron_proto::Chat { + serde_json::from_value(serde_json::json!({ + "id": id, "deviceId": "d", "title": null, "archived": archived, "cwd": null, "branch": null, + "checkoutId": null, "config": null, "lastMessagePreview": null, "lastMessageAt": null, + "createdAt": "2026-11-15T00:00:00Z", + })) + .unwrap() + }; + let commands = sh(); + let (chats, watched) = watch::channel(Vec::new()); + commands.follow_chats(watched); + let start = |chat: &str| commands.start("/tmp", "sleep 30", Some(chat)).unwrap().id; + let (kept, archived, deleted, unsynced) = ( + start("kept"), + start("archived"), + start("deleted"), + start("not-here-yet"), + ); + chats.send_replace(vec![ + chat("kept", false), + chat("archived", false), + chat("deleted", false), + ]); + // Let the first list land before the second replaces it. + tokio::time::sleep(Duration::from_millis(200)).await; + chats.send_replace(vec![chat("kept", false), chat("archived", true)]); + for id in [&archived, &deleted] { + until("stopped", || { + commands.read(id).is_ok_and(|c| c.status == "stopped") + }) + .await; + } + for id in [&kept, &unsynced] { + assert_eq!(commands.read(id).unwrap().status, "running", "{id}"); + } + commands.shutdown().await; + for id in [&kept, &unsynced] { + assert_eq!(commands.read(id).unwrap().status, "stopped", "{id}"); + } + } + + #[tokio::test] + async fn commands_are_each_engines_own() { + let (one, two) = (sh(), sh()); + let id = one.start("/tmp", "sleep 30", None).unwrap().id; + assert!(two.read(&id).is_err()); + two.shutdown().await; + assert_eq!(one.read(&id).unwrap().status, "running"); + one.shutdown().await; + } + + #[test] + fn capped_output_counts_what_it_leaves_out() { + let mut capped = Capped::default(); + capped.push(&vec![b'a'; HEAD]); + capped.push(&vec![b'b'; TAIL + 10]); + capped.push(b"end"); + let (output, omitted) = capped.finish(); + assert_eq!(omitted, 13); + assert!(output.starts_with(&"a".repeat(HEAD)) && output.ends_with("bend")); + } + + #[test] + fn a_ring_keeps_the_newest_and_reads_each_byte_once() { + let mut ring = Ring::default(); + ring.push(b"hello "); + assert_eq!(ring.read(), ("hello ".into(), 0)); + ring.push(&vec![b'x'; RING + 100]); + ring.push(b"end"); + let (output, omitted) = ring.read(); + assert!( + output.ends_with("xend") && output.len() == MAX_READ, + "{}", + output.len() + ); + assert_eq!(omitted, (RING + 100 + 3 - MAX_READ) as u64); + assert_eq!(ring.read(), (String::new(), 0)); + assert!(ring.bytes.len() <= RING); + } + + #[test] + fn task_ids_name_their_command_and_device() { + assert_eq!( + CommandTask::parse("cmd-1@dev-2"), + Some(("cmd-1".into(), Some("dev-2".into()))) + ); + assert_eq!(CommandTask::parse("cmd-1"), Some(("cmd-1".into(), None))); + assert_eq!(CommandTask::parse("bash_1"), None); + } + + #[test] + fn each_shell_is_handed_its_command_its_own_way() { + assert_eq!(ShellKind::of("/bin/zsh"), ShellKind::Posix); + assert_eq!(ShellKind::of("/usr/bin/bash"), ShellKind::Posix); + assert_eq!(ShellKind::of("/usr/bin/fish"), ShellKind::Other); + assert_eq!( + ShellKind::of(r"C:\Program Files\PowerShell\7\pwsh.exe"), + ShellKind::PowerShell + ); + assert_eq!( + ShellKind::of(r"C:\Windows\system32\cmd.exe"), + ShellKind::Cmd + ); + assert_eq!(quote("/tmp/a'b"), r"'/tmp/a'\''b'"); + // PowerShell takes it encoded (UTF-16LE base64): no quoting to break. + let args = ShellKind::PowerShell.args("echo \"it's\"").unwrap(); + assert_eq!( + args[..4], + [ + "-NoLogo", + "-NoProfile", + "-NonInteractive", + "-EncodedCommand" + ] + ); + use base64::Engine as _; + let decoded = base64::engine::general_purpose::STANDARD + .decode(&args[4]) + .unwrap(); + let utf16: Vec = decoded + .chunks(2) + .map(|b| u16::from_le_bytes([b[0], b[1]])) + .collect(); + assert_eq!(String::from_utf16(&utf16).unwrap(), "echo \"it's\""); + assert!( + ShellKind::PowerShell + .args(&"x".repeat(MAX_ENCODED_COMMAND)) + .is_err() + ); + // Its script passes a failure's code on, and says where it ended. + let script = + ShellKind::PowerShell.script("git status", Some(std::path::Path::new(r"C:\t\it's"))); + assert!(script.contains("\ngit status\n$__zeronOk = $?"), "{script}"); + assert!(script.contains(r"WriteAllText('C:\t\it''s'"), "{script}"); + assert!(script.contains("exit $__zeronCode"), "{script}"); + } +} + +/// The same guarantees through Windows' own shell (PowerShell, as +/// [`crate::terminals::selected_shell`] picks it), run by Windows CI. +#[cfg(all(test, windows))] +mod windows_tests { + use super::*; + + fn here() -> String { + std::env::temp_dir().to_string_lossy().into_owned() + } + + #[tokio::test] + async fn powershell_gives_output_exit_codes_and_where_it_ended() { + let commands = Commands::default(); + assert_eq!(commands.inner.kind, ShellKind::PowerShell); + let ran = commands + .run( + &here(), + "Write-Output \"it's \"\"quoted\"\"\"; exit 3", + DEFAULT_TIMEOUT, + ) + .await + .unwrap(); + assert_eq!(ran.exit_code, Some(3), "{ran:?}"); + assert!(ran.output.contains("it's \"quoted\""), "{ran:?}"); + // A native command's own code, not PowerShell's 1. + let ran = commands + .run(&here(), "cmd /c exit 5", DEFAULT_TIMEOUT) + .await + .unwrap(); + assert_eq!(ran.exit_code, Some(5), "{ran:?}"); + let dir = tempfile::tempdir().unwrap(); + std::fs::create_dir(dir.path().join("sub")).unwrap(); + let ran = commands + .run( + dir.path().to_str().unwrap(), + "Set-Location sub", + DEFAULT_TIMEOUT, + ) + .await + .unwrap(); + assert_eq!(ran.exit_code, Some(0), "{ran:?}"); + let ended = std::fs::canonicalize(ran.cwd.expect("where it ended")).unwrap(); + assert_eq!( + ended, + std::fs::canonicalize(dir.path().join("sub")).unwrap() + ); + } + + #[tokio::test] + async fn powershell_commands_time_out_and_stop_with_all_they_started() { + let commands = Commands::default(); + let started = Instant::now(); + let ran = commands + .run(&here(), "ping -n 30 127.0.0.1", Duration::from_millis(500)) + .await + .unwrap(); + assert!(ran.timed_out, "{ran:?}"); + assert!(started.elapsed() < GRACE + Duration::from_secs(5)); + + let id = commands + .start(&here(), "ping -n 60 127.0.0.1", None) + .unwrap() + .id; + let stopped = commands.stop(&id).await.unwrap(); + assert_eq!(stopped.status, "stopped"); + assert_eq!(commands.running(), 0); + } +} diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index 2671bab45..5e2868bc0 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -44,6 +44,7 @@ mod chat_persistence; mod cloud_accounts; pub mod cloud_client; pub mod cloud_disk; +pub mod commands; pub mod commit_credit; pub mod credentials; pub mod deferred; @@ -69,7 +70,6 @@ pub mod registry; pub mod remote_terminals; pub mod repos; pub mod rpc; -pub mod run_command; pub mod run_journal; pub mod runner; pub mod wake_trace; @@ -183,6 +183,8 @@ pub struct EngineCore { pub repos: Repos, pub workspace_files: WorkspaceFiles, pub terminals: Terminals, + /// Agents' shell commands on this device ([`commands`]). + pub commands: commands::Commands, /// I/O routing for terminals on other devices (direct link or relay). pub remote_terminals: remote_terminals::RemoteTerminals, pub project_actions: ProjectActionsStore, @@ -374,14 +376,18 @@ impl EngineCore { repos.clone(), workspace.clone(), device_id.clone(), - runner::session() - .and_then(|session| session.path.clone()) - .map(std::path::PathBuf::from), + runner::session().and_then(|session| { + Some(workspace_files::CloudCheckout { + path: std::path::PathBuf::from(session.path.clone()?), + chat_id: session.chat_id.clone(), + }) + }), ); let terminals = Terminals::new(); sessions.track_terminal_activity(terminals.clone(), workspace.clone()); + let commands = commands::Commands::default(); // An agent's background commands end with its chat. - run_command::follow_chats(workspace.watch_chats()); + commands.follow_chats(workspace.watch_chats()); let project_actions = ProjectActionsStore::open(profile.store_root())?; doc_host.set_project_action_runtime(project_actions.clone(), terminals.clone()); let previews = zeron_preview::PreviewService::new( @@ -488,6 +494,7 @@ impl EngineCore { repos, workspace_files, terminals, + commands, remote_terminals: Default::default(), project_actions, previews, @@ -521,11 +528,12 @@ impl EngineCore { pub fn update_quiescence(&self, cloud: bool) -> zeron_update::QuiescentCheck { let sessions = self.sessions.clone(); let terminals = self.terminals.clone(); + let commands = self.commands.clone(); let doc_host = cloud.then(|| self.doc_host.clone()); Arc::new(move || { !sessions.any_active() && !terminals.any_open() - && run_command::running_count() == 0 + && commands.running() == 0 && !doc_host.as_ref().is_some_and(DocHost::has_waiting_commands) }) } @@ -665,6 +673,7 @@ impl EngineCore { .with_auth(self.auth()) .with_previews(self.previews.clone()) .with_remote_terminals(self.remote_terminals.clone()) + .with_commands(self.commands.clone()) .with_harness_updates(self.harness_updates.clone()) .with_viewport_focus(self.viewport_focus.clone()) .with_plugins(self.plugins.clone()); @@ -750,7 +759,7 @@ impl EngineCore { } self.sessions.shutdown().await; self.terminals.shutdown(); - run_command::shutdown(); + self.commands.shutdown().await; self.sessions.stop_activity_projection().await; self.agent_accounts.shutdown(); self.change_requests.shutdown(); @@ -1141,11 +1150,18 @@ impl Engine { core.registry.set_run_environment(Arc::new(broker.clone())); broker.start(); let sessions = core.sessions.clone(); + let commands = core.commands.clone(); let activity = runner::RelayActivity::default(); let heartbeat = runner::spawn_heartbeat( identity.edge_url(), tokens, - Arc::new(move || sessions.run_counts()), + // An agent's running commands (a dev server left running) + // keep the machine awake as background work does. + Arc::new(move || { + let mut counts = sessions.run_counts(); + counts.background += commands.running(); + counts + }), Arc::new(cloud_disk::machine_usage), activity.clone(), runner::HEARTBEAT_INTERVAL, diff --git a/crates/engine/src/rpc.rs b/crates/engine/src/rpc.rs index 56d8f9f82..f8be382d2 100644 --- a/crates/engine/src/rpc.rs +++ b/crates/engine/src/rpc.rs @@ -915,6 +915,8 @@ pub struct EngineRpc { workspace_files: crate::WorkspaceFiles, terminals: Terminals, remote_terminals: crate::remote_terminals::RemoteTerminals, + /// Agents' shell commands here ([`crate::commands`]). + commands: crate::commands::Commands, project_actions: ProjectActionsStore, previews: Option, change_requests: CheckoutChangeRequests, @@ -979,6 +981,7 @@ impl EngineRpc { workspace_files, terminals, remote_terminals: Default::default(), + commands: Default::default(), project_actions, previews: None, change_requests, @@ -1010,6 +1013,12 @@ impl EngineRpc { } /// Share the engine-wide routing state for terminals on other devices. + /// The engine's agents' commands (one service per engine). + pub fn with_commands(mut self, commands: crate::commands::Commands) -> Self { + self.commands = commands; + self + } + pub fn with_remote_terminals( mut self, remote_terminals: crate::remote_terminals::RemoteTerminals, @@ -1924,9 +1933,9 @@ impl EngineRpc { /// A background command the calling agent just started (`device`: where, /// `None` here): its chat shows it with its runtime's background - /// processes until it ends. Only an agent's own call: a peer forwarding - /// one here is running it for a chat hosted there. - fn track_command(&self, device: Option<&str>, started: &serde_json::Value) { + /// processes until it ends ([`Self::follow_commands`]). Only an agent's + /// own call: a peer forwarding one here runs it for a chat hosted there. + fn show_command(&self, device: Option<&str>, started: &serde_json::Value) { let zeron_rpc::Caller::Agent { chat: Some(chat) } = zeron_rpc::caller() else { return; }; @@ -1941,88 +1950,92 @@ impl EngineRpc { .find(|d| d.id == device) .map(|d| d.name) }); - let task = zeron_proto::BackgroundTask { - id: match device { - Some(device) => format!("{id}@{device}"), - None => id.to_owned(), - }, - command: started["command"].as_str().unwrap_or_default().to_owned(), - description: name.map(|name| format!("on {name}")), - started_at: chrono::Utc::now(), - }; - let command = crate::run_command::CommandTask { + let task = crate::commands::CommandTask { device: device.map(str::to_owned), id: id.to_owned(), - task, + task: zeron_proto::BackgroundTask { + id: match device { + Some(device) => format!("{id}@{device}"), + None => id.to_owned(), + }, + command: started["command"].as_str().unwrap_or_default().to_owned(), + description: name.map(|name| format!("on {name}")), + started_at: chrono::Utc::now(), + }, }; - if self.sessions.track_command(&chat, command) { - let rpc = self.clone(); - tokio::spawn(async move { rpc.follow_commands().await }); - } + let follower = self.clone(); + let (chat_id, device) = (chat.clone(), task.device.clone()); + self.commands.show(&self.sessions, &chat, task, move || { + tokio::spawn(follower.follow_commands(chat_id, device)) + }); } - /// While any are tracked: every few seconds, ask each device which of a - /// chat's commands still run, and show those. A device out of reach - /// keeps its commands shown for [`COMMAND_UNREACHABLE`], then they go. - async fn follow_commands(self) { - const EVERY: Duration = Duration::from_secs(5); - const COMMAND_UNREACHABLE: Duration = Duration::from_secs(120); - let mut unreachable: std::collections::HashMap = Default::default(); + /// Follow the commands `chat` shows on `device` (`None`: here) through + /// that device's `WatchBackgroundCommands`: each one that ends leaves the + /// row as it ends, and the row stays fresh (the live heartbeat's + /// cadence) while any run. A device out of reach keeps its commands + /// shown for [`COMMANDS_UNREACHABLE`] while it's dialled again, then they + /// go. Ends when the chat shows none there. + async fn follow_commands(self, chat: String, device: Option) { + const COMMANDS_UNREACHABLE: Duration = Duration::from_secs(120); + const REDIAL: Duration = Duration::from_secs(3); + let heartbeat_every = + Duration::from_millis(zeron_proto::view::SESSION_HEARTBEAT_MS as u64 / 2); + let mut heartbeat = tokio::time::interval(heartbeat_every); + heartbeat.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + let mut lost_since: Option = None; loop { - tokio::time::sleep(EVERY).await; - if !self.sessions.commands_followed() { + let watched = match &device { + None => Ok(self.commands.watch(chat.clone())), + Some(target) => match self + .forward( + target, + methods::WATCH_BACKGROUND_COMMANDS, + serde_json::json!({ "chatId": chat }), + ) + .await + { + Ok(RpcReply::Stream(stream)) => Ok(stream), + Ok(RpcReply::Value(_)) => Err(()), + Err(error) => { + tracing::debug!(%chat, %target, %error, "commands' device not followed yet"); + Err(()) + } + }, + }; + if let Ok(mut listed) = watched { + lost_since = None; + loop { + tokio::select! { + item = listed.next() => { + let Some(item) = item else { break }; + let running: HashSet = item + .as_array() + .into_iter() + .flatten() + .filter(|c| c["status"] == "running") + .filter_map(|c| c["id"].as_str().map(str::to_owned)) + .collect(); + self.sessions.retain_commands(&chat, &device, |id| running.contains(id)); + if !self.commands.followed(&self.sessions, &chat, &device) { + return; + } + } + _ = heartbeat.tick() => self.sessions.heartbeat(&chat), + } + } + } + // Its stream ended or never opened: dial again, a while. + let since = *lost_since.get_or_insert_with(tokio::time::Instant::now); + if since.elapsed() >= COMMANDS_UNREACHABLE { + tracing::info!(%chat, ?device, "commands' device out of reach: no longer shown"); + self.sessions.retain_commands(&chat, &device, |_| false); + } + if !self.commands.followed(&self.sessions, &chat, &device) { return; } - for (chat, commands) in self.sessions.tracked_commands() { - let mut devices: Vec> = commands.iter().map(|c| c.device.clone()).collect(); - devices.sort(); - devices.dedup(); - // Per device: the ids still running, or `None` if it couldn't say. - let mut running: std::collections::HashMap, Option>> = Default::default(); - for device in devices { - let listed = match &device { - None => Some(serde_json::to_value(crate::run_command::list(Some(&chat))).unwrap_or_default()), - Some(target) => match tokio::time::timeout( - Duration::from_secs(10), - self.forward(target, methods::LIST_BACKGROUND_COMMANDS, serde_json::json!({ "chatId": chat })), - ) - .await - { - Ok(Ok(RpcReply::Value(value))) => Some(value), - _ => None, - }, - }; - let ids = listed.map(|listed| { - listed - .as_array() - .into_iter() - .flatten() - .filter(|c| c["status"] == "running") - .filter_map(|c| c["id"].as_str().map(str::to_owned)) - .collect() - }); - if let Some(target) = &device { - if ids.is_some() { - unreachable.remove(target); - } else { - unreachable.entry(target.clone()).or_insert_with(std::time::Instant::now); - } - } - running.insert(device, ids); - } - let still: Vec<_> = commands - .into_iter() - .filter(|c| match running.get(&c.device) { - Some(Some(ids)) => ids.contains(&c.id), - _ => c - .device - .as_ref() - .and_then(|d| unreachable.get(d)) - .is_none_or(|since| since.elapsed() < COMMAND_UNREACHABLE), - }) - .collect(); - self.sessions.set_tracked_commands(&chat, still); - } + self.sessions.heartbeat(&chat); + tokio::time::sleep(REDIAL).await; } } @@ -2592,7 +2605,7 @@ fn forward_deadline(method: &str) -> std::time::Duration { methods::APPLY_HARNESS_UPDATE => crate::harness_updates::APPLY_REPLY_DEADLINE, methods::CREATE_WORKTREE => Duration::from_secs(120), // The longest a command may run there, and the reply's way back. - methods::RUN_COMMAND => crate::run_command::MAX_TIMEOUT + Duration::from_secs(30), + methods::RUN_COMMAND => crate::commands::MAX_TIMEOUT + Duration::from_secs(30), // Allow the adapter discovery budget plus relay and shutdown overhead. methods::LIST_MODELS | methods::LIST_COMMANDS => Duration::from_secs(100), _ => Duration::from_secs(30), @@ -2720,6 +2733,7 @@ fn forwardable(method: &str) -> bool { | methods::READ_COMMAND_OUTPUT | methods::STOP_COMMAND | methods::LIST_BACKGROUND_COMMANDS + | methods::WATCH_BACKGROUND_COMMANDS // Agent accounts are per-device CLI logins (the device switcher // retargets which device's logins are shown). | methods::LIST_AGENT_ACCOUNTS @@ -2780,6 +2794,7 @@ fn is_stream_method(method: &str) -> bool { methods::WATCH_DOC_MESSAGES | methods::WATCH_QUEUE | methods::SUBSCRIBE_TERMINAL + | methods::WATCH_BACKGROUND_COMMANDS | methods::WATCH_CHECKOUT_DIFFS | methods::WATCH_WORKSPACE_GIT_STATUS | methods::WATCH_CHECKOUT_CHANGE_REQUEST @@ -3397,7 +3412,7 @@ impl RpcService for EngineRpc { if method == methods::RUN_COMMAND && params["background"] == true { let started = self.forward(&target, method, params).await?; if let RpcReply::Value(started) = &started { - self.track_command(Some(&target), started); + self.show_command(Some(&target), started); } return Ok(started); } @@ -4015,17 +4030,21 @@ impl RpcService for EngineRpc { methods::STOP_BACKGROUND_TASK => { let p: BackgroundTaskParams = parse_params(params)?; // A command its agent left running with run_command, wherever. - if let Some((id, device)) = crate::run_command::CommandTask::parse(&p.task_id) { + if let Some((id, device)) = crate::commands::CommandTask::parse(&p.task_id) { match device.filter(|d| d != self.doc_host.device_id()) { Some(device) => { - self.forward(&device, methods::STOP_COMMAND, serde_json::json!({ "id": id })) - .await?; + self.forward( + &device, + methods::STOP_COMMAND, + serde_json::json!({ "id": id }), + ) + .await?; } None => { - crate::run_command::stop(&id).await.map_err(RpcError::Failed)?; + self.commands.stop(&id).await.map_err(RpcError::Failed)?; } } - self.sessions.untrack_command(&p.chat_id, &p.task_id); + self.sessions.hide_command(&p.chat_id, &p.task_id); return RpcReply::value(&serde_json::json!({ "stopping": true })); } let stopping = self.sessions.stop_background_task(&p.chat_id, &p.task_id); @@ -4062,16 +4081,20 @@ impl RpcService for EngineRpc { } methods::READ_BACKGROUND_TASK_OUTPUT => { let p: BackgroundTaskParams = parse_params(params)?; - if let Some((id, device)) = crate::run_command::CommandTask::parse(&p.task_id) { + if let Some((id, device)) = crate::commands::CommandTask::parse(&p.task_id) { let output = match device.filter(|d| d != self.doc_host.device_id()) { Some(device) => match self - .forward(&device, methods::READ_COMMAND_OUTPUT, serde_json::json!({ "id": id, "tail": true })) + .forward( + &device, + methods::READ_COMMAND_OUTPUT, + serde_json::json!({ "id": id, "tail": true }), + ) .await { Ok(RpcReply::Value(value)) => serde_json::from_value(value).ok(), _ => None, }, - None => crate::run_command::tail(&id).ok(), + None => self.commands.tail(&id).ok(), }; let output: Option = output; return RpcReply::value(&output); @@ -5627,13 +5650,17 @@ impl RpcService for EngineRpc { let p: OpenTerminalParams = parse_params(params)?; // Prefer an explicit real path (new-chat canvas has no row // yet). `space-canvas:{spaceId}` names the selected project - // so a missing/tilde cwd still lands in that folder. - let chat_cwd = self + // so a missing/tilde cwd still lands in that folder. Only a + // chat this device runs lends its folder and takes the + // terminal (its activity rides that chat's session row, + // which only its host writes), as for a project action. + let hosted = self .workspace .chat(&p.chat_id) .ok() .flatten() - .and_then(|chat| chat.cwd); + .filter(|chat| chat.device_id == self.doc_host.device_id()); + let chat_cwd = hosted.as_ref().and_then(|chat| chat.cwd.clone()); let space_cwd = canvas_space_id(&p.chat_id).and_then(|space_id| { self.workspace .space(space_id) @@ -5652,7 +5679,7 @@ impl RpcService for EngineRpc { .terminals .open(&cwd, p.cols, p.rows) .map_err(|e| RpcError::Failed(e.to_string()))?; - if self.workspace.chat(&p.chat_id).ok().flatten().is_some() { + if hosted.is_some() { self.terminals .associate_chat(&session.id, &p.chat_id) .map_err(|e| RpcError::Failed(e.to_string()))?; @@ -5711,21 +5738,26 @@ impl RpcService for EngineRpc { .and_then(|chat| self.workspace.chat(chat).ok().flatten()) .filter(|chat| chat.device_id == self.doc_host.device_id()) .and_then(|chat| chat.cwd); - let cwd = resolve_open_terminal_cwd(p.cwd, chat_cwd, None, &self.repos.scratch_root()) - .map_err(RpcError::Failed)?; + let cwd = + resolve_open_terminal_cwd(p.cwd, chat_cwd, None, &self.repos.scratch_root()) + .map_err(RpcError::Failed)?; if p.background { - let started = crate::run_command::start(&cwd, &p.command, p.chat_id.as_deref()) + let started = self + .commands + .start(&cwd, &p.command, p.chat_id.as_deref()) .map_err(RpcError::Failed)?; if let Ok(value) = serde_json::to_value(&started) { - self.track_command(None, &value); + self.show_command(None, &value); } return RpcReply::value(&started); } let timeout = p .timeout_ms .map(Duration::from_millis) - .unwrap_or(crate::run_command::DEFAULT_TIMEOUT); - let outcome = crate::run_command::run(&cwd, &p.command, timeout) + .unwrap_or(crate::commands::DEFAULT_TIMEOUT); + let outcome = self + .commands + .run(&cwd, &p.command, timeout) .await .map_err(RpcError::Failed)?; RpcReply::value(&outcome) @@ -5733,17 +5765,24 @@ impl RpcService for EngineRpc { methods::READ_COMMAND_OUTPUT => { let p: CommandIdParams = parse_params(params)?; if p.tail { - return RpcReply::value(&crate::run_command::tail(&p.id).map_err(RpcError::Failed)?); + return RpcReply::value(&self.commands.tail(&p.id).map_err(RpcError::Failed)?); } - RpcReply::value(&crate::run_command::read(&p.id).map_err(RpcError::Failed)?) + RpcReply::value(&self.commands.read(&p.id).map_err(RpcError::Failed)?) } methods::STOP_COMMAND => { let p: CommandIdParams = parse_params(params)?; - RpcReply::value(&crate::run_command::stop(&p.id).await.map_err(RpcError::Failed)?) + RpcReply::value(&self.commands.stop(&p.id).await.map_err(RpcError::Failed)?) } methods::LIST_BACKGROUND_COMMANDS => { let chat = params.get("chatId").and_then(|c| c.as_str()); - RpcReply::value(&crate::run_command::list(chat)) + RpcReply::value(&self.commands.list(chat)) + } + methods::WATCH_BACKGROUND_COMMANDS => { + let chat = params + .get("chatId") + .and_then(|c| c.as_str()) + .unwrap_or_default(); + Ok(RpcReply::Stream(self.commands.watch(chat.to_owned()))) } methods::TERMINAL_STATUS => { let p: TerminalIdParams = parse_params(params)?; diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index 8960943e8..45361f5fb 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -319,35 +319,72 @@ mod tests { async fn only_an_unconfined_agent_runs_a_command() { let (_temp, core) = core().await; chat(&core, "careful", "Careful", "read-only", "supervised").await; - chat(&core, "sandboxed", "Sandboxed", "workspace-write", "full-access").await; + chat( + &core, + "sandboxed", + "Sandboxed", + "workspace-write", + "full-access", + ) + .await; chat(&core, "free", "Free", "danger-full-access", "full-access").await; let rpc = core.rpc_service(); let open = json!({"command":"ls", "targetDeviceId":"laptop"}); - for method in [methods::RUN_COMMAND, methods::READ_COMMAND_OUTPUT, methods::STOP_COMMAND, methods::LIST_BACKGROUND_COMMANDS] { + for method in [ + methods::RUN_COMMAND, + methods::READ_COMMAND_OUTPUT, + methods::STOP_COMMAND, + methods::LIST_BACKGROUND_COMMANDS, + ] { for who in ["careful", "sandboxed", "nowhere"] { - let refused = with_caller(agent(who), async { rpc.agent_gate(method, open.clone()) }).await; + let refused = + with_caller(agent(who), async { rpc.agent_gate(method, open.clone()) }).await; assert!( matches!(&refused, Err(zeron_rpc::RpcError::Failed(m)) if m.contains("full access and no sandbox")), "{who} {method}: {refused:?}" ); } - let allowed = with_caller(agent("free"), async { rpc.agent_gate(method, open.clone()) }).await.unwrap(); + let allowed = with_caller(agent("free"), async { + rpc.agent_gate(method, open.clone()) + }) + .await + .unwrap(); assert_eq!(allowed, open, "{method}"); // A server with no chat (set up by hand) is capped by nothing. - with_caller(Caller::Agent { chat: None }, async { rpc.agent_gate(method, open.clone()) }).await.unwrap(); + with_caller(Caller::Agent { chat: None }, async { + rpc.agent_gate(method, open.clone()) + }) + .await + .unwrap(); assert_eq!(rpc.agent_gate(method, open.clone()).unwrap(), open); } // Through the engine, it runs here and says how it went. let dir = tempfile::tempdir().unwrap(); let ran = with_caller( agent("free"), - rpc.handle(methods::RUN_COMMAND, json!({"command":"echo hi; exit 2", "cwd": dir.path()})), + rpc.handle( + methods::RUN_COMMAND, + json!({"command":"echo hi; exit 2", "cwd": dir.path()}), + ), ) .await .unwrap(); - let zeron_rpc::RpcReply::Value(ran) = ran else { panic!("a stream") }; - assert_eq!((ran["exitCode"].clone(), ran["output"].as_str().unwrap().ends_with("hi\n")), (json!(2), true), "{ran}"); - let refused = with_caller(agent("careful"), rpc.handle(methods::RUN_COMMAND, json!({"command":"echo hi"}))).await; + let zeron_rpc::RpcReply::Value(ran) = ran else { + panic!("a stream") + }; + assert_eq!( + ( + ran["exitCode"].clone(), + ran["output"].as_str().unwrap().ends_with("hi\n") + ), + (json!(2), true), + "{ran}" + ); + let refused = with_caller( + agent("careful"), + rpc.handle(methods::RUN_COMMAND, json!({"command":"echo hi"})), + ) + .await; assert!(refused.is_err()); core.sessions.shutdown().await; } @@ -359,7 +396,8 @@ mod tests { async fn a_chat_shows_the_commands_its_agent_left_running() { let (_temp, core) = core().await; chat(&core, "free", "Free", "danger-full-access", "full-access").await; - core.sessions.seed_status("free", zeron_proto::SessionStatus::Working); + core.sessions + .seed_status("free", zeron_proto::SessionStatus::Working); let rpc = core.rpc_service(); let dir = tempfile::tempdir().unwrap(); let value = |reply: zeron_rpc::RpcReply| match reply { @@ -375,7 +413,11 @@ mod tests { ), ) }; - let server = value(start("echo listening; while true; do sleep 0.05; done").await.unwrap()); + let server = value( + start("echo listening; while true; do sleep 0.05; done") + .await + .unwrap(), + ); let quick = value(start("echo done").await.unwrap()); let shown = |core: &crate::EngineCore| -> Vec { core.sessions @@ -391,25 +433,34 @@ mod tests { let give_up = std::time::Instant::now() + std::time::Duration::from_secs(5); loop { let tail = value( - rpc.handle(methods::READ_BACKGROUND_TASK_OUTPUT, json!({"chatId": "free", "taskId": server_id})) - .await - .unwrap(), + rpc.handle( + methods::READ_BACKGROUND_TASK_OUTPUT, + json!({"chatId": "free", "taskId": server_id}), + ) + .await + .unwrap(), ); - if tail["text"].as_str().is_some_and(|t| t.contains("listening")) { + if tail["text"] + .as_str() + .is_some_and(|t| t.contains("listening")) + { break; } assert!(std::time::Instant::now() < give_up, "{tail}"); tokio::time::sleep(std::time::Duration::from_millis(50)).await; } let read = value( - with_caller(agent("free"), rpc.handle(methods::READ_COMMAND_OUTPUT, json!({"id": server_id}))) - .await - .unwrap(), + with_caller( + agent("free"), + rpc.handle(methods::READ_COMMAND_OUTPUT, json!({"id": server_id})), + ) + .await + .unwrap(), ); assert_eq!(read["output"], "listening\n"); - // One that ended goes from the row on the next look. - let give_up = std::time::Instant::now() + std::time::Duration::from_secs(12); + // One that ended goes from the row as it ends (followed, not polled). + let give_up = std::time::Instant::now() + std::time::Duration::from_secs(2); while shown(&core).contains(&quick_id) { assert!(std::time::Instant::now() < give_up, "{:?}", shown(&core)); tokio::time::sleep(std::time::Duration::from_millis(100)).await; @@ -418,13 +469,16 @@ mod tests { // Stopped from the row, the person's call: gone, and it ended. let stopped = value( - rpc.handle(methods::STOP_BACKGROUND_TASK, json!({"chatId": "free", "taskId": server_id})) - .await - .unwrap(), + rpc.handle( + methods::STOP_BACKGROUND_TASK, + json!({"chatId": "free", "taskId": server_id}), + ) + .await + .unwrap(), ); assert_eq!(stopped["stopping"], true); assert!(shown(&core).is_empty()); - assert_eq!(crate::run_command::read(&server_id).unwrap().status, "stopped"); + assert_eq!(core.commands.read(&server_id).unwrap().status, "stopped"); core.sessions.shutdown().await; } diff --git a/crates/engine/src/run_command.rs b/crates/engine/src/run_command.rs deleted file mode 100644 index 91cb62f70..000000000 --- a/crates/engine/src/run_command.rs +++ /dev/null @@ -1,853 +0,0 @@ -//! Shell commands for agents, on this device or another of the person's -//! (Zeron MCP's `run_command` & co., forwarded by `targetDeviceId`): what an -//! agent's own shell tool does on its machine, on any of them. -//! -//! - [`run`] (`RunCommand`): one command run to its end. Its output and exit -//! code come back, and where it ended up (`cwd`, from a POSIX shell), so an -//! agent's `cd` carries over to its next command. -//! - [`start`] (`RunCommand {background}`): one left running (a dev server, -//! a watcher, a long build), read with [`read`] (`ReadCommandOutput`), -//! stopped with [`stop`] (`StopCommand`), listed with [`list`] -//! (`ListCommands`). -//! -//! No PTY and no session: the user's shell runs the command as a login shell -//! (`-l -c`, so it has the PATH their terminal has; PowerShell or cmd on -//! Windows), with empty stdin so a prompt for input ends instead of hanging. -//! What it costs is bounded: -//! -//! - **Memory**: a run keeps at most [`HEAD`] + [`TAIL`] bytes of output (its -//! start and end); a background command its newest [`RING`] bytes. What's -//! left out is counted, not kept. At most [`MAX_ENDED`] ended background -//! commands are remembered, none for longer than [`KEEP_ENDED`]. -//! - **Time**: a run has a timeout (at most [`MAX_TIMEOUT`]). Each command -//! gets its own process group (Unix), which is killed at the timeout, when -//! the call is abandoned, when a background command is stopped, when the -//! chat that started it is archived or deleted ([`follow_chats`]), and when -//! the engine shuts down ([`shutdown`]). Nothing it started lives on. -//! - **Concurrency**: at most [`MAX_RUNNING`] runs and [`MAX_BACKGROUND`] -//! background commands at once per device; past that, refused, not queued. -//! -//! Running commands count as work ([`running_count`]): a Cloud machine stays -//! awake for them, and an update waits for them. - -use std::collections::{HashMap, VecDeque}; -use std::process::Stdio; -use std::sync::atomic::{AtomicBool, Ordering}; -use std::sync::{Arc, LazyLock, Mutex}; -use std::time::{Duration, Instant}; - -use serde::Serialize; -use tokio::io::{AsyncRead, AsyncReadExt}; -use tokio::sync::Semaphore; - -pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(120); -pub const MAX_TIMEOUT: Duration = Duration::from_secs(600); -/// Output a run keeps from its start, and from its end. -const HEAD: usize = 16 * 1024; -const TAIL: usize = 48 * 1024; -/// Output a background command keeps (its newest), and the most one read -/// returns. -const RING: usize = 128 * 1024; -const MAX_READ: usize = 48 * 1024; -/// How long output is still read once a run's shell has exited. -const DRAIN: Duration = Duration::from_millis(250); -pub const MAX_RUNNING: usize = 16; -pub const MAX_BACKGROUND: usize = 32; -const MAX_ENDED: usize = 32; -const KEEP_ENDED: Duration = Duration::from_secs(60 * 60); - -static RUNNING: Semaphore = Semaphore::const_new(MAX_RUNNING); -static BACKGROUND: LazyLock>>> = LazyLock::new(Default::default); - -fn lock(mutex: &Mutex) -> std::sync::MutexGuard<'_, T> { - mutex.lock().unwrap_or_else(std::sync::PoisonError::into_inner) -} - -/// Commands running now, run or background: work in progress. -pub fn running_count() -> usize { - let background = lock(&BACKGROUND).values().filter(|c| c.ended().is_none()).count(); - MAX_RUNNING - RUNNING.available_permits() + background -} - -/// How one run ended. -#[derive(Debug, Clone, PartialEq, Eq, Serialize)] -#[serde(rename_all = "camelCase")] -pub struct RunOutcome { - /// `None` when it was killed (timed out, or by a signal). - pub exit_code: Option, - /// Stdout and stderr together, in the order they arrived. When it was - /// too long, its start and end with a line saying how much was left out. - pub output: String, - /// Bytes of output left out of the middle. - #[serde(skip_serializing_if = "is_zero")] - pub omitted_bytes: u64, - pub timed_out: bool, - pub duration_ms: u64, - /// The folder it ended in (a POSIX shell's `pwd`), when it finished. - #[serde(skip_serializing_if = "Option::is_none")] - pub cwd: Option, -} - -fn is_zero(n: &u64) -> bool { - *n == 0 -} - -/// Run `command` in `cwd` with the user's shell, for at most `timeout`. -pub async fn run(cwd: &str, command: &str, timeout: Duration) -> Result { - run_with_shell(&crate::terminals::selected_shell(), cwd, command, timeout).await -} - -pub(crate) async fn run_with_shell( - shell: &str, - cwd: &str, - command: &str, - timeout: Duration, -) -> Result { - if command.trim().is_empty() { - return Err("The command is empty".into()); - } - let _slot = RUNNING.try_acquire().map_err(|_| { - format!("{MAX_RUNNING} commands are already running on this device: wait for one to finish") - })?; - let timeout = timeout.min(MAX_TIMEOUT); - let started = Instant::now(); - // Where it ends up, written by the shell as it exits. - let ended_in = posix(shell).then(|| tempfile::NamedTempFile::new().ok()).flatten(); - let script = match &ended_in { - // On the way out, however it ends (an `exit` in the command too). - Some(file) => format!( - "trap '__zeron_status=$?; pwd -P >| {} 2>/dev/null; exit $__zeron_status' EXIT\n{command}\n", - quote(&file.path().to_string_lossy()).replace('\'', r"'\''") - ), - None => command.to_owned(), - }; - let (mut child, group) = spawn(shell, cwd, &script)?; - let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); - let readers = pumps(&mut child, sender); - - let mut output = Capped::default(); - let deadline = tokio::time::Instant::now() + timeout; - let mut status = None; - let mut timed_out = false; - // Until the shell exits (or time is up), taking output as it comes. - while status.is_none() { - tokio::select! { - exited = child.wait() => status = Some(exited.map_err(|e| e.to_string())?), - Some(chunk) = chunks.recv() => output.push(&chunk), - () = tokio::time::sleep_until(deadline) => { - timed_out = true; - group.kill(); - let _ = child.kill().await; - status = child.wait().await.ok(); - break; - } - } - } - // What's still in the pipes, briefly: a process it left in the - // background may keep them open for good. - let drain = tokio::time::Instant::now() + DRAIN; - loop { - tokio::select! { - chunk = chunks.recv() => match chunk { - Some(chunk) => output.push(&chunk), - None => break, - }, - () = tokio::time::sleep_until(drain) => break, - } - } - for reader in readers { - reader.abort(); - } - group.finished(); - - let exit_code = if timed_out { None } else { status.and_then(|s| s.code()) }; - let cwd = ended_in - .filter(|_| !timed_out) - .and_then(|file| std::fs::read_to_string(file.path()).ok()) - .map(|pwd| pwd.trim_end_matches(['\n', '\r']).to_owned()) - .filter(|pwd| !pwd.is_empty()); - let (output, omitted_bytes) = output.finish(); - Ok(RunOutcome { - exit_code, - output, - omitted_bytes, - timed_out, - duration_ms: started.elapsed().as_millis() as u64, - cwd, - }) -} - -/// A background command, as [`start`], [`read`], [`stop`] and [`list`] say it. -#[derive(Debug, Clone, PartialEq, Eq, Serialize)] -#[serde(rename_all = "camelCase")] -pub struct CommandStatus { - pub id: String, - pub command: String, - pub cwd: String, - /// `running`, `exited` (on its own) or `stopped` (stopped, or its chat - /// went away, or the engine shut down). - pub status: &'static str, - #[serde(skip_serializing_if = "Option::is_none")] - pub exit_code: Option, - pub duration_ms: u64, - /// [`read`]: output since the last read. - #[serde(skip_serializing_if = "Option::is_none")] - pub output: Option, - /// [`read`]: bytes of that output no longer kept. - #[serde(skip_serializing_if = "is_zero")] - pub omitted_bytes: u64, -} - -struct Background { - id: String, - command: String, - cwd: String, - /// The chat that started it: it stops when that chat is archived or - /// deleted ([`follow_chats`]). - chat: Option, - started: Instant, - group: Group, - output: Mutex, - end: Mutex>, - /// Asked to stop: it ends as `stopped`, whatever its code. - stopping: AtomicBool, -} - -#[derive(Clone, Copy)] -struct End { - at: Instant, - code: Option, - stopped: bool, -} - -impl Background { - fn ended(&self) -> Option { - *lock(&self.end) - } - - fn status(&self, read: bool) -> CommandStatus { - let end = self.ended(); - let (output, omitted_bytes) = if read { - let (output, omitted) = lock(&self.output).read(); - (Some(output), omitted) - } else { - (None, 0) - }; - CommandStatus { - id: self.id.clone(), - command: self.command.clone(), - cwd: self.cwd.clone(), - status: match end { - None => "running", - Some(end) if end.stopped => "stopped", - Some(_) => "exited", - }, - exit_code: end.and_then(|e| e.code), - duration_ms: end.map_or(self.started.elapsed(), |e| e.at - self.started).as_millis() as u64, - output, - omitted_bytes, - } - } - - fn stop(&self) { - self.stopping.store(true, Ordering::Release); - self.group.kill(); - } -} - -/// Start `command` in `cwd` and leave it running, for `chat`. -pub fn start(cwd: &str, command: &str, chat: Option<&str>) -> Result { - start_with_shell(&crate::terminals::selected_shell(), cwd, command, chat) -} - -pub(crate) fn start_with_shell( - shell: &str, - cwd: &str, - command: &str, - chat: Option<&str>, -) -> Result { - let mut commands = lock(&BACKGROUND); - forget_ended(&mut commands); - if commands.values().filter(|c| c.ended().is_none()).count() >= MAX_BACKGROUND { - return Err(format!( - "{MAX_BACKGROUND} background commands are already running on this device: stop one first" - )); - } - let (mut child, group) = spawn(shell, cwd, command)?; - let id = format!("cmd-{}", &uuid::Uuid::new_v4().simple().to_string()[..12]); - let background = Arc::new(Background { - id: id.clone(), - command: command.to_owned(), - cwd: cwd.to_owned(), - chat: chat.map(str::to_owned), - started: Instant::now(), - group, - output: Mutex::new(Ring::default()), - end: Mutex::new(None), - stopping: AtomicBool::new(false), - }); - let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); - let readers = pumps(&mut child, sender); - let weak = Arc::downgrade(&background); - tokio::spawn(async move { - let collect = { - let weak = weak.clone(); - async move { - while let Some(chunk) = chunks.recv().await { - let Some(this) = weak.upgrade() else { return }; - lock(&this.output).push(&chunk); - } - } - }; - let mut collecting = tokio::spawn(collect); - let status = child.wait().await.ok(); - // Its last words, briefly (as a run's). - if tokio::time::timeout(DRAIN, &mut collecting).await.is_err() { - collecting.abort(); - } - let Some(this) = weak.upgrade() else { return }; - for reader in readers { - reader.abort(); - } - this.group.finished(); - *lock(&this.end) = Some(End { - at: Instant::now(), - code: status.and_then(|s| s.code()), - stopped: this.stopping.load(Ordering::Acquire), - }); - }); - let status = background.status(false); - commands.insert(id, background); - Ok(status) -} - -/// A background command its agent's chat shows with its runtime's own -/// background processes (`Session::background_tasks`), tracked by the chat's -/// host wherever the command runs. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct CommandTask { - /// Where it runs; `None`: the chat's host itself. - pub device: Option, - /// Its id there (`cmd-…`). - pub id: String, - /// As shown: its id is `cmd-…@device` for one elsewhere, the `id` its - /// agent was given. - pub task: zeron_proto::BackgroundTask, -} - -impl CommandTask { - /// A task id that names a command (`cmd-…`, `cmd-…@device`): its id and - /// device. `None` for a runtime's own task. - pub fn parse(task_id: &str) -> Option<(String, Option)> { - if !task_id.starts_with("cmd-") { - return None; - } - Some(match task_id.rsplit_once('@') { - Some((id, device)) => (id.to_owned(), Some(device.to_owned())), - None => (task_id.to_owned(), None), - }) - } -} - -/// The newest [`MAX_READ`] bytes a background command printed, for a person -/// looking (it doesn't move what its agent reads next). -pub fn tail(id: &str) -> Result { - let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; - let ring = lock(&command.output); - let start = ring.bytes.len().saturating_sub(MAX_READ); - let newest: Vec = ring.bytes.range(start..).copied().collect(); - Ok(zeron_proto::BackgroundTaskOutput { - text: String::from_utf8_lossy(&newest).into_owned(), - truncated: ring.written > newest.len() as u64, - }) -} - -/// A background command's output since it was last read, and how it stands. -pub fn read(id: &str) -> Result { - let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; - Ok(command.status(true)) -} - -/// Stop a background command and everything it started; its output since -/// the last read comes back. -pub async fn stop(id: &str) -> Result { - let command = lock(&BACKGROUND).get(id).cloned().ok_or_else(|| unknown(id))?; - if command.ended().is_none() { - command.stop(); - let wait = Instant::now() + Duration::from_secs(5); - while command.ended().is_none() && Instant::now() < wait { - tokio::time::sleep(Duration::from_millis(20)).await; - } - } - Ok(command.status(true)) -} - -/// The background commands `chat` started here (every one, without a chat). -pub fn list(chat: Option<&str>) -> Vec { - let mut commands = lock(&BACKGROUND); - forget_ended(&mut commands); - let mut listed: Vec<_> = commands - .values() - .filter(|c| chat.is_none_or(|chat| c.chat.as_deref() == Some(chat))) - .map(|c| (c.started, c.status(false))) - .collect(); - listed.sort_by_key(|(started, _)| *started); - listed.into_iter().map(|(_, status)| status).collect() -} - -fn unknown(id: &str) -> String { - format!("No command {id} on this device (it may have ended over an hour ago, or the engine restarted)") -} - -/// Ended commands past [`KEEP_ENDED`], and the oldest past [`MAX_ENDED`]. -fn forget_ended(commands: &mut HashMap>) { - commands.retain(|_, c| c.ended().is_none_or(|end| end.at.elapsed() < KEEP_ENDED)); - let mut ended: Vec<(Instant, String)> = commands - .values() - .filter_map(|c| c.ended().map(|end| (end.at, c.id.clone()))) - .collect(); - if ended.len() > MAX_ENDED { - ended.sort(); - for (_, id) in &ended[..ended.len() - MAX_ENDED] { - commands.remove(id); - } - } -} - -/// Stop background commands whose chat is archived or deleted, as `chats` -/// (one engine's) change. A chat counts as deleted only once these chats -/// have shown it, so one not synced here yet isn't taken as gone. Runs while -/// `chats` does. -pub fn follow_chats(mut chats: tokio::sync::watch::Receiver>) { - tokio::spawn(async move { - // Commands whose chat these chats have shown. - let mut seen = std::collections::HashSet::::new(); - loop { - { - let commands: Vec> = lock(&BACKGROUND) - .values() - .filter(|c| c.chat.is_some() && c.ended().is_none()) - .cloned() - .collect(); - seen.retain(|id| commands.iter().any(|c| &c.id == id)); - if !commands.is_empty() { - let chats = chats.borrow_and_update(); - for command in commands { - let chat = command.chat.as_deref().and_then(|id| chats.iter().find(|c| c.id == id)); - let gone = match chat { - Some(chat) => { - seen.insert(command.id.clone()); - chat.archived - } - None => seen.contains(&command.id), - }; - if gone { - tracing::info!(command = %command.id, "its chat went away: stopping it"); - command.stop(); - } - } - } - } - if chats.changed().await.is_err() { - return; - } - } - }); -} - -/// Stop every background command (the engine is going). -pub fn shutdown() { - for command in lock(&BACKGROUND).values() { - if command.ended().is_none() { - command.stop(); - } - } -} - -/// Start the shell on `script` in `cwd`, in a process group of its own. -fn spawn(shell: &str, cwd: &str, script: &str) -> Result<(tokio::process::Child, Group), String> { - if script.trim().is_empty() { - return Err("The command is empty".into()); - } - if !std::fs::metadata(cwd).is_ok_and(|m| m.is_dir()) { - return Err(format!("No folder {cwd} on this device")); - } - let mut cmd = tokio::process::Command::new(shell); - if crate::terminals::is_powershell(shell) { - cmd.args(["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script]); - } else if cfg!(windows) { - cmd.args(["/C", script]); - } else { - cmd.args(["-l", "-c", script]); - } - cmd.current_dir(cwd) - .stdin(Stdio::null()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - // Nothing waits on a pager or a password prompt. - .env("PAGER", "cat") - .env("GIT_PAGER", "cat") - .env("GIT_TERMINAL_PROMPT", "0") - .kill_on_drop(true); - #[cfg(unix)] - cmd.process_group(0); - #[cfg(windows)] - cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW - let child = cmd.spawn().map_err(|e| format!("Couldn't start {shell}: {e}"))?; - let group = Group::new(child.id()); - Ok((child, group)) -} - -/// Stdout and stderr, read into `to` as they come. -fn pumps(child: &mut tokio::process::Child, to: tokio::sync::mpsc::Sender>) -> Vec> { - let mut readers = Vec::with_capacity(2); - if let Some(out) = child.stdout.take() { - readers.push(tokio::spawn(pump(out, to.clone()))); - } - if let Some(err) = child.stderr.take() { - readers.push(tokio::spawn(pump(err, to))); - } - readers -} - -async fn pump(mut from: impl AsyncRead + Unpin, to: tokio::sync::mpsc::Sender>) { - let mut buf = vec![0u8; 8 * 1024]; - loop { - match from.read(&mut buf).await { - Ok(0) | Err(_) => return, - Ok(n) => { - if to.send(buf[..n].to_vec()).await.is_err() { - return; - } - } - } - } -} - -/// A shell whose `$?`, `pwd -P` and `>|` this module's cwd line uses. -fn posix(shell: &str) -> bool { - let name = shell.rsplit(['/', '\\']).next().unwrap_or(shell); - matches!(name, "sh" | "bash" | "zsh" | "dash" | "ksh" | "mksh" | "ash") -} - -fn quote(path: &str) -> String { - format!("'{}'", path.replace('\'', r"'\''")) -} - -/// A command's process group. Dropped before [`Group::finished`] (the call -/// was abandoned), on a timeout, or when stopped, everything in it is killed. -struct Group { - #[cfg_attr(not(unix), allow(dead_code))] - pid: Option, - done: AtomicBool, -} - -impl Group { - fn new(pid: Option) -> Self { - Self { pid, done: false.into() } - } - - fn kill(&self) { - #[cfg(unix)] - if let Some(pid) = self.pid.and_then(|p| i32::try_from(p).ok()).filter(|p| *p > 0) { - // SAFETY: signals the group this module made (process_group(0)). - unsafe { - libc::kill(-pid, libc::SIGKILL); - } - } - // Windows has no process groups to signal: end the tree. - #[cfg(windows)] - if let Some(pid) = self.pid { - use std::os::windows::process::CommandExt as _; - let _ = std::process::Command::new("taskkill") - .args(["/T", "/F", "/PID", &pid.to_string()]) - .stdin(Stdio::null()) - .stdout(Stdio::null()) - .stderr(Stdio::null()) - .creation_flags(0x0800_0000) - .spawn(); - } - } - - fn finished(&self) { - self.done.store(true, Ordering::Release); - } -} - -impl Drop for Group { - fn drop(&mut self) { - if !self.done.load(Ordering::Acquire) { - self.kill(); - } - } -} - -/// A run's output within [`HEAD`] + [`TAIL`] bytes: the first bytes, the -/// last bytes, and a count of the rest. -#[derive(Default)] -struct Capped { - head: Vec, - tail: VecDeque, - omitted: u64, -} - -impl Capped { - fn push(&mut self, mut bytes: &[u8]) { - if self.head.len() < HEAD { - let take = bytes.len().min(HEAD - self.head.len()); - self.head.extend_from_slice(&bytes[..take]); - bytes = &bytes[take..]; - } - if bytes.len() >= TAIL { - self.omitted += (self.tail.len() + bytes.len() - TAIL) as u64; - self.tail.clear(); - bytes = &bytes[bytes.len() - TAIL..]; - } - let overflow = (self.tail.len() + bytes.len()).saturating_sub(TAIL); - self.tail.drain(..overflow); - self.omitted += overflow as u64; - self.tail.extend(bytes); - } - - fn finish(self) -> (String, u64) { - let head = String::from_utf8_lossy(&self.head).into_owned(); - let tail: Vec = self.tail.into(); - let tail = String::from_utf8_lossy(&tail).into_owned(); - if self.omitted == 0 { - return (head + &tail, 0); - } - ( - format!("{head}\n… {} bytes of output left out …\n{tail}", self.omitted), - self.omitted, - ) - } -} - -/// A background command's newest [`RING`] bytes, and how far a reader got. -#[derive(Default)] -struct Ring { - bytes: VecDeque, - /// Bytes ever written, and ever read (or passed over). - written: u64, - read: u64, -} - -impl Ring { - fn push(&mut self, bytes: &[u8]) { - self.written += bytes.len() as u64; - let bytes = &bytes[bytes.len().saturating_sub(RING)..]; - let overflow = (self.bytes.len() + bytes.len()).saturating_sub(RING); - self.bytes.drain(..overflow); - self.bytes.extend(bytes); - } - - /// What's unread (its newest [`MAX_READ`] bytes), and how much unread - /// output was lost or left out. - fn read(&mut self) -> (String, u64) { - let kept_from = self.written - self.bytes.len() as u64; - let from = self.read.max(kept_from).max(self.written.saturating_sub(MAX_READ as u64)); - let omitted = from - self.read; - let start = (from - kept_from) as usize; - let unread: Vec = self.bytes.range(start..).copied().collect(); - self.read = self.written; - (String::from_utf8_lossy(&unread).into_owned(), omitted) - } -} - -#[cfg(all(test, unix))] -mod tests { - use super::*; - - async fn sh(command: &str, timeout: Duration) -> RunOutcome { - let dir = std::env::temp_dir(); - run_with_shell("/bin/sh", dir.to_str().unwrap(), command, timeout).await.unwrap() - } - - #[tokio::test] - async fn a_command_gives_its_output_and_exit_code() { - let ran = sh("echo out; echo err >&2; exit 3", DEFAULT_TIMEOUT).await; - assert_eq!(ran.exit_code, Some(3)); - assert!(ran.output.contains("out\n") && ran.output.contains("err\n"), "{ran:?}"); - assert!(!ran.timed_out); - let ran = sh("false", DEFAULT_TIMEOUT).await; - assert_eq!(ran.exit_code, Some(1)); - // No input to wait for: a prompt reads end of input. - let ran = sh("read line; echo \"got [$line]\"", DEFAULT_TIMEOUT).await; - assert_eq!(ran.output, "got []\n"); - } - - #[tokio::test] - async fn it_runs_where_it_is_asked_and_says_where_it_ended() { - let dir = tempfile::tempdir().unwrap(); - std::fs::create_dir(dir.path().join("sub")).unwrap(); - let here = std::fs::canonicalize(dir.path()).unwrap(); - for shell in ["/bin/sh", "/bin/bash", "/bin/zsh"].into_iter().filter(|s| std::path::Path::new(s).exists()) { - let ran = run_with_shell(shell, dir.path().to_str().unwrap(), "pwd; cd sub", DEFAULT_TIMEOUT) - .await - .unwrap(); - assert_eq!(std::fs::canonicalize(ran.output.trim()).unwrap(), here, "{shell}"); - assert_eq!(ran.cwd.as_deref().map(std::path::PathBuf::from), Some(here.join("sub")), "{shell}"); - assert_eq!(ran.exit_code, Some(0), "{shell}"); - // An `exit` keeps its code and still says where it ended. - let ran = run_with_shell(shell, dir.path().to_str().unwrap(), "cd sub && exit 3", DEFAULT_TIMEOUT) - .await - .unwrap(); - assert_eq!((ran.exit_code, ran.cwd.map(std::path::PathBuf::from)), (Some(3), Some(here.join("sub"))), "{shell}"); - } - assert!(run_with_shell("/bin/sh", "/no/such/folder", "pwd", DEFAULT_TIMEOUT).await.is_err()); - assert!(run_with_shell("/bin/sh", "/tmp", " ", DEFAULT_TIMEOUT).await.is_err()); - } - - #[tokio::test] - async fn a_timeout_kills_everything_the_command_started() { - let dir = tempfile::tempdir().unwrap(); - let marker = dir.path().join("survived"); - let command = format!("(sleep 1; touch {}) & sleep 30", marker.display()); - let started = Instant::now(); - let ran = sh(&command, Duration::from_millis(300)).await; - assert!(ran.timed_out); - assert_eq!(ran.exit_code, None); - assert!(started.elapsed() < Duration::from_secs(5), "{:?}", started.elapsed()); - tokio::time::sleep(Duration::from_millis(1500)).await; - assert!(!marker.exists(), "a child outlived the timeout"); - } - - #[tokio::test] - async fn an_abandoned_run_kills_everything_it_started() { - let dir = tempfile::tempdir().unwrap(); - let marker = dir.path().join("survived"); - let command = format!("sleep 1; touch {}", marker.display()); - let run = sh(&command, DEFAULT_TIMEOUT); - assert!(tokio::time::timeout(Duration::from_millis(200), run).await.is_err()); - tokio::time::sleep(Duration::from_millis(1500)).await; - assert!(!marker.exists(), "the command outlived its caller"); - } - - #[tokio::test] - async fn something_left_in_the_background_never_holds_the_reply() { - let started = Instant::now(); - let ran = sh("sleep 30 & echo started", DEFAULT_TIMEOUT).await; - assert_eq!(ran.exit_code, Some(0)); - assert_eq!(ran.output, "started\n"); - assert!(started.elapsed() < Duration::from_secs(3), "{:?}", started.elapsed()); - } - - #[tokio::test] - async fn long_output_keeps_its_start_and_end_within_bounds() { - let ran = sh("echo FIRST; head -c 1000000 /dev/zero | tr '\\0' x; echo; echo LAST", DEFAULT_TIMEOUT).await; - assert!(ran.output.starts_with("FIRST\n")); - assert!(ran.output.ends_with("LAST\n")); - assert!(ran.omitted_bytes > 900_000); - assert!(ran.output.len() < HEAD + TAIL + 100); - } - - async fn until(what: &str, mut done: impl FnMut() -> bool) { - let give_up = Instant::now() + Duration::from_secs(5); - while !done() { - assert!(Instant::now() < give_up, "{what}"); - tokio::time::sleep(Duration::from_millis(20)).await; - } - } - - #[tokio::test] - async fn a_background_command_is_read_as_it_goes_and_stopped_with_all_it_started() { - let dir = tempfile::tempdir().unwrap(); - let marker = dir.path().join("survived"); - let command = format!("echo ready; (sleep 1; touch {}) & while true; do sleep 0.05; done", marker.display()); - let started = start_with_shell("/bin/sh", dir.path().to_str().unwrap(), &command, Some("chat-a")).unwrap(); - assert_eq!(started.status, "running"); - let id = started.id; - let mut seen = String::new(); - until("its first output", || { - seen.push_str(&read(&id).unwrap().output.unwrap()); - seen.contains("ready") - }) - .await; - // Read once: not again. - assert_eq!(read(&id).unwrap().output.as_deref(), Some("")); - assert!(list(Some("chat-a")).iter().any(|c| c.id == id && c.status == "running")); - assert!(list(Some("chat-b")).iter().all(|c| c.id != id)); - assert!(running_count() >= 1); - - let stopped = stop(&id).await.unwrap(); - assert_eq!(stopped.status, "stopped"); - tokio::time::sleep(Duration::from_millis(1500)).await; - assert!(!marker.exists(), "a child outlived its stop"); - assert!(stop("cmd-nope").await.is_err()); - } - - #[tokio::test] - async fn a_background_command_that_ends_says_how() { - let started = start_with_shell("/bin/sh", "/tmp", "echo done; exit 4", None).unwrap(); - until("it ends", || read(&started.id).is_ok_and(|c| c.status == "exited")).await; - let ended = read(&started.id).unwrap(); - assert_eq!(ended.exit_code, Some(4)); - } - - #[tokio::test] - async fn a_background_command_stops_when_its_chat_goes() { - let chat = |id: &str, archived: bool| -> zeron_proto::Chat { - serde_json::from_value(serde_json::json!({ - "id": id, "deviceId": "d", "title": null, "archived": archived, "cwd": null, "branch": null, - "checkoutId": null, "config": null, "lastMessagePreview": null, "lastMessageAt": null, - "createdAt": "2026-11-15T00:00:00Z", - })) - .unwrap() - }; - let (chats, watched) = tokio::sync::watch::channel(Vec::new()); - follow_chats(watched); - // Another engine's chats, which never had these: it stops none. - let (others, other) = tokio::sync::watch::channel(Vec::new()); - follow_chats(other); - others.send_replace(vec![chat("unrelated", false)]); - let kept = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("kept")).unwrap().id; - let archived = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("archived")).unwrap().id; - let deleted = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("deleted")).unwrap().id; - let unsynced = start_with_shell("/bin/sh", "/tmp", "sleep 30", Some("not-here-yet")).unwrap().id; - chats.send_replace(vec![chat("kept", false), chat("archived", false), chat("deleted", false)]); - // Let the first list land before the second replaces it. - tokio::time::sleep(Duration::from_millis(200)).await; - chats.send_replace(vec![chat("kept", false), chat("archived", true)]); - for id in [&archived, &deleted] { - until("stopped", || read(id).is_ok_and(|c| c.status == "stopped")).await; - } - tokio::time::sleep(Duration::from_millis(100)).await; - for id in [&kept, &unsynced] { - assert_eq!(read(id).unwrap().status, "running", "{id}"); - stop(id).await.unwrap(); - } - } - - #[test] - fn capped_output_counts_what_it_leaves_out() { - let mut capped = Capped::default(); - capped.push(&vec![b'a'; HEAD]); - capped.push(&vec![b'b'; TAIL + 10]); - capped.push(b"end"); - let (output, omitted) = capped.finish(); - assert_eq!(omitted, 13); - assert!(output.starts_with(&"a".repeat(HEAD))); - assert!(output.ends_with("bend")); - } - - #[test] - fn a_ring_keeps_the_newest_and_reads_each_byte_once() { - let mut ring = Ring::default(); - ring.push(b"hello "); - assert_eq!(ring.read(), ("hello ".into(), 0)); - ring.push(&vec![b'x'; RING + 100]); - ring.push(b"end"); - let (output, omitted) = ring.read(); - assert!(output.ends_with("xend") && output.len() == MAX_READ, "{}", output.len()); - assert_eq!(omitted, (RING + 100 + 3 - MAX_READ) as u64); - assert_eq!(ring.read(), (String::new(), 0)); - assert!(ring.bytes.len() <= RING); - } - - #[test] - fn only_posix_shells_report_their_folder() { - assert!(posix("/bin/zsh") && posix("/usr/bin/bash") && posix("sh")); - assert!(!posix("/usr/bin/fish") && !posix(r"C:\pwsh.exe")); - assert_eq!(quote("/tmp/a'b"), r"'/tmp/a'\''b'"); - } -} diff --git a/crates/engine/src/sessions.rs b/crates/engine/src/sessions.rs index 61fdb076e..f895b3929 100644 --- a/crates/engine/src/sessions.rs +++ b/crates/engine/src/sessions.rs @@ -262,9 +262,7 @@ struct Inner { /// said), and the background commands its agent started with Zeron's /// `run_command`, here or on another device. Its session row shows both. runtime_tasks: Mutex>>, - command_tasks: Mutex>>, - /// A task follows the tracked commands (see [`SessionsEngine::track_command`]). - command_tracker: std::sync::atomic::AtomicBool, + command_tasks: Mutex>>, /// The engine is shutting down: dying runs re-dispatch nothing. shutting_down: std::sync::atomic::AtomicBool, /// A shutdown marks the turns it cuts off for pick-up on the next boot @@ -367,7 +365,6 @@ impl SessionsEngine { device_id, runtime_tasks: Mutex::new(HashMap::new()), command_tasks: Mutex::new(HashMap::new()), - command_tracker: std::sync::atomic::AtomicBool::new(false), shutting_down: std::sync::atomic::AtomicBool::new(false), revive_after_shutdown: std::sync::atomic::AtomicBool::new(true), revivals: Mutex::new(HashMap::new()), @@ -652,66 +649,67 @@ impl SessionsEngine { /// Ask the chat's runtime to stop one of its background processes. False /// when no live runtime lists it (it ended meanwhile). - /// A background command `chat_id`'s agent started with `run_command` - /// (here or on another device): shown on its session row with its - /// runtime's processes until it ends. True when nothing follows the - /// tracked commands yet: the caller starts [`Self::follow_commands`]'s - /// loop. - pub fn track_command(&self, chat_id: &str, command: crate::run_command::CommandTask) -> bool { + /// Show a background command `chat_id`'s agent started with + /// `run_command` (here or on another device) on its session row, with + /// its runtime's own background processes ([`crate::commands::Commands::show`]). + pub fn show_command(&self, chat_id: &str, command: crate::commands::CommandTask) { lock(&self.inner.command_tasks) .entry(chat_id.to_owned()) .or_default() .push(command); self.inner.publish_background_tasks(chat_id); - !self - .inner - .command_tracker - .swap(true, std::sync::atomic::Ordering::AcqRel) } - /// Every chat's tracked commands. - pub fn tracked_commands(&self) -> HashMap> { - lock(&self.inner.command_tasks).clone() - } - - /// The tracked commands of `chat_id` still running, as just checked: - /// shown, and the row kept fresh while there are any. - pub fn set_tracked_commands(&self, chat_id: &str, commands: Vec) { + /// Keep showing those of `chat_id`'s commands on `device` that `keep` + /// says still run (and every command elsewhere). + pub fn retain_commands( + &self, + chat_id: &str, + device: &Option, + keep: impl Fn(&str) -> bool, + ) { let changed = { - let mut tracked = lock(&self.inner.command_tasks); - let before = tracked.get(chat_id).map_or(0, Vec::len); - let after = commands.len(); + let mut shown = lock(&self.inner.command_tasks); + let Some(commands) = shown.get_mut(chat_id) else { + return; + }; + let before = commands.len(); + commands.retain(|c| &c.device != device || keep(&c.id)); + let changed = commands.len() != before; if commands.is_empty() { - tracked.remove(chat_id); - } else { - tracked.insert(chat_id.to_owned(), commands); + shown.remove(chat_id); } - before != after + changed }; if changed { self.inner.publish_background_tasks(chat_id); } - self.inner.touch_session(chat_id); } - /// One tracked command no longer shown (it was stopped). - pub fn untrack_command(&self, chat_id: &str, task_id: &str) { - let mut commands = lock(&self.inner.command_tasks).get(chat_id).cloned().unwrap_or_default(); - commands.retain(|c| c.task.id != task_id); - self.set_tracked_commands(chat_id, commands); - } - - /// Nothing is tracked any more: the loop following them ends (false), or - /// something was tracked meanwhile and it goes on (true). - pub fn commands_followed(&self) -> bool { - let tracked = lock(&self.inner.command_tasks); - if tracked.is_empty() { - self.inner - .command_tracker - .store(false, std::sync::atomic::Ordering::Release); - return false; + /// No longer show one of `chat_id`'s commands (the person stopped it). + pub fn hide_command(&self, chat_id: &str, task_id: &str) { + let device = lock(&self.inner.command_tasks) + .get(chat_id) + .and_then(|commands| commands.iter().find(|c| c.task.id == task_id)) + .map(|c| (c.device.clone(), c.id.clone())); + if let Some((device, id)) = device { + self.retain_commands(chat_id, &device, |shown| shown != id); } - true + } + + /// How many of `chat_id`'s commands on `device` are shown. + pub fn shown_commands_on(&self, chat_id: &str, device: &Option) -> usize { + lock(&self.inner.command_tasks) + .get(chat_id) + .map_or(0, |commands| { + commands.iter().filter(|c| &c.device == device).count() + }) + } + + /// Keep `chat_id`'s row fresh while it shows running commands, as a live + /// run's heartbeat does. + pub fn heartbeat(&self, chat_id: &str) { + self.inner.touch_session(chat_id); } pub fn stop_background_task(&self, chat_id: &str, task_id: &str) -> bool { @@ -775,9 +773,7 @@ impl SessionsEngine { crate::runner::RunCounts { active, waiting, - // An agent's commands (a dev server left running) keep the - // machine awake as background work does. - background: self.background_count() + crate::run_command::running_count(), + background: self.background_count(), } } @@ -2732,7 +2728,10 @@ impl Inner { /// The session row's background processes: its runtime's, then the /// commands its agent left running with `run_command`. fn publish_background_tasks(&self, chat_id: &str) { - let mut tasks = lock(&self.runtime_tasks).get(chat_id).cloned().unwrap_or_default(); + let mut tasks = lock(&self.runtime_tasks) + .get(chat_id) + .cloned() + .unwrap_or_default(); if let Some(commands) = lock(&self.command_tasks).get(chat_id) { tasks.extend(commands.iter().map(|c| c.task.clone())); } diff --git a/crates/engine/src/workspace_files.rs b/crates/engine/src/workspace_files.rs index 8179b95be..45b5612d5 100644 --- a/crates/engine/src/workspace_files.rs +++ b/crates/engine/src/workspace_files.rs @@ -56,13 +56,23 @@ pub struct WorkspaceFiles { inner: Arc, } +/// A Cloud session machine's checkout: the folder its session chat's +/// project (made on another device) is cloned into +/// ([`crate::runner::session`]). +#[derive(Debug, Clone)] +pub struct CloudCheckout { + pub path: PathBuf, + /// The chat the machine was started for; its side chats share it. + pub chat_id: String, +} + struct WorkspaceFilesInner { repos: Repos, workspace: WorkspaceHost, device_id: String, /// On a Cloud session machine, its checkout of the session's repository: /// where a chat whose project was made on another device works. - cloud_checkout: Option, + cloud_checkout: Option, mutation_gates: Mutex>>>, write_locks: Mutex>>>, watches: Mutex>>, @@ -258,7 +268,7 @@ impl WorkspaceFiles { repos: Repos, workspace: WorkspaceHost, device_id: impl Into, - cloud_checkout: Option, + cloud_checkout: Option, ) -> Self { Self { inner: Arc::new(WorkspaceFilesInner { @@ -274,6 +284,25 @@ impl WorkspaceFiles { } } + /// Where `space`'s files are on this device: its folder, when this + /// device made it. A Cloud session machine answers from its own checkout + /// for its session chat's project — only that one: it sees every + /// project, and any other is a folder on another device. + fn space_root(&self, space: &zeron_proto::Space) -> Option { + if space.device_id == self.inner.device_id { + return Some(PathBuf::from(&space.path)); + } + let checkout = self.inner.cloud_checkout.as_ref()?; + let session_project = self + .inner + .workspace + .chat(&checkout.chat_id) + .ok() + .flatten() + .and_then(|chat| chat.space_id); + (session_project.as_deref() == Some(space.id.as_str())).then(|| checkout.path.clone()) + } + pub(crate) async fn resolve_target( &self, target: &WorkspaceTarget, @@ -340,18 +369,11 @@ impl WorkspaceFiles { .ok_or_else(|| { WorkspaceFilesError::NotFound("chat workspace space not found".into()) })?; - // A project made on another device is that device's folder — - // except on a Cloud session machine, which works in its own - // checkout of the project's repository. - let space_path = if space.device_id == self.inner.device_id { - PathBuf::from(&space.path) - } else if let Some(checkout) = &self.inner.cloud_checkout { - checkout.clone() - } else { - return Err(WorkspaceFilesError::Authorization( + let space_path = self.space_root(&space).ok_or_else(|| { + WorkspaceFilesError::Authorization( "chat space belongs to another device".into(), - )); - }; + ) + })?; let (checkout, identity) = tokio::join!( self.inner.repos.workspace_checkout(&space_path, &cwd), self.inner.repos.checkout_identity(&cwd), @@ -370,17 +392,9 @@ impl WorkspaceFiles { .space(space_id) .map_err(|error| WorkspaceFilesError::Io(error.to_string()))? .ok_or_else(|| WorkspaceFilesError::NotFound("space not found".into()))?; - // As for a chat target: a Cloud session machine answers for a - // project made elsewhere from its own checkout of it. - let space_path = if space.device_id == self.inner.device_id { - PathBuf::from(&space.path) - } else if let Some(checkout) = &self.inner.cloud_checkout { - checkout.clone() - } else { - return Err(WorkspaceFilesError::Authorization( - "space belongs to another device".into(), - )); - }; + let space_path = self.space_root(&space).ok_or_else(|| { + WorkspaceFilesError::Authorization("space belongs to another device".into()) + })?; let requested = target .checkout_path .as_deref() @@ -3670,6 +3684,8 @@ mod image_tests { .unwrap(); host.create_space("space", "laptop", "/Users/me/app", None, true) .unwrap(); + host.create_space("laptop-space", "laptop", "/Users/me/other", None, true) + .unwrap(); // Hosted on the session machine, like a chat sent to Cloud. host.create_chat_hosted( "chat", @@ -3702,7 +3718,10 @@ mod image_tests { repos, host, "cloud-session", - Some(checkout.clone()), + Some(CloudCheckout { + path: checkout.clone(), + chat_id: "chat".into(), + }), ); let resolved = files.resolve_target(&target).await.unwrap(); assert_eq!(resolved.root, std::fs::canonicalize(&checkout).unwrap()); @@ -3722,6 +3741,20 @@ mod image_tests { ..by_space }; assert!(files.resolve_target(&outside).await.is_err()); + // It sees the person's other projects, but they're folders on + // their own devices, never its checkout. + let elsewhere = WorkspaceTarget { + chat_id: None, + space_id: Some("laptop-space".into()), + checkout_path: None, + }; + let refused = files.resolve_target(&elsewhere).await.unwrap_err(); + assert!( + refused + .to_string() + .contains("space belongs to another device"), + "{refused}" + ); } fn request() -> ReadWorkspaceImageRequest { ReadWorkspaceImageRequest { diff --git a/crates/engine/tests/agent_commands.rs b/crates/engine/tests/agent_commands.rs index 35749364d..defdae51b 100644 --- a/crates/engine/tests/agent_commands.rs +++ b/crates/engine/tests/agent_commands.rs @@ -13,19 +13,38 @@ use zeron_rpc::memory_client; #[tokio::test] async fn an_agent_runs_commands_as_its_own_shell_tool_would() { let dir = tempfile::tempdir().unwrap(); - let core = EngineCore::assemble(dir.path(), Arc::new(default_registry()), HarnessId::Mock, None).unwrap(); - let tools = Tools::new(Arc::new(Zeron::with_client(memory_client(core.rpc_service()), Origin::default()))); + let core = EngineCore::assemble( + dir.path(), + Arc::new(default_registry()), + HarnessId::Mock, + None, + ) + .unwrap(); + let tools = Tools::new(Arc::new(Zeron::with_client( + memory_client(core.rpc_service()), + Origin::default(), + ))); let work = tempfile::tempdir().unwrap(); std::fs::create_dir(work.path().join("app")).unwrap(); let app = std::fs::canonicalize(work.path().join("app")).unwrap(); // Output and exit code; cd carries over to the next command. let ran = tools - .call("run_command", json!({ "command": "cd app && echo hi && exit 3", "cwd": work.path() })) + .call( + "run_command", + json!({ "command": "cd app && echo hi && exit 3", "cwd": work.path() }), + ) + .await + .unwrap(); + assert_eq!( + (ran["output"].as_str(), ran["exitCode"].as_i64()), + (Some("hi\n"), Some(3)), + "{ran}" + ); + let ran = tools + .call("run_command", json!({ "command": "pwd -P" })) .await .unwrap(); - assert_eq!((ran["output"].as_str(), ran["exitCode"].as_i64()), (Some("hi\n"), Some(3)), "{ran}"); - let ran = tools.call("run_command", json!({ "command": "pwd -P" })).await.unwrap(); assert_eq!(ran["output"].as_str().map(str::trim), app.to_str(), "{ran}"); // A server left running: read as it goes, then stopped. @@ -41,13 +60,25 @@ async fn an_agent_runs_commands_as_its_own_shell_tool_would() { let give_up = Instant::now() + Duration::from_secs(10); while !printed.contains("listening") { assert!(Instant::now() < give_up, "{printed:?}"); - let read: Value = tools.call("command_output", json!({ "id": id })).await.unwrap(); + let read: Value = tools + .call("command_output", json!({ "id": id })) + .await + .unwrap(); printed.push_str(read["output"].as_str().unwrap_or_default()); tokio::time::sleep(Duration::from_millis(50)).await; } let listed = tools.call("list_commands", json!({})).await.unwrap(); - assert!(listed["commands"].as_array().unwrap().iter().any(|c| c["id"] == id.as_str() && c["status"] == "running")); - let stopped = tools.call("stop_command", json!({ "id": id })).await.unwrap(); + assert!( + listed["commands"] + .as_array() + .unwrap() + .iter() + .any(|c| c["id"] == id.as_str() && c["status"] == "running") + ); + let stopped = tools + .call("stop_command", json!({ "id": id })) + .await + .unwrap(); assert_eq!(stopped["status"], "stopped", "{stopped}"); core.sessions.shutdown().await; } diff --git a/crates/engine/tests/cloud_rpc.rs b/crates/engine/tests/cloud_rpc.rs index 79af21da4..229b739a2 100644 --- a/crates/engine/tests/cloud_rpc.rs +++ b/crates/engine/tests/cloud_rpc.rs @@ -556,14 +556,38 @@ async fn chats_run_on_cloud_get_their_own_session_machines() { if let Some(device) = device { op["deviceId"] = serde_json::json!(device); } - zeron_rpc::with_caller(zeron_rpc::Caller::Agent { chat: None }, rpc.handle(methods::MUTATE, op)) + zeron_rpc::with_caller( + zeron_rpc::Caller::Agent { chat: None }, + rpc.handle(methods::MUTATE, op), + ) }; - agent_creates("side-here", Some(core.workspace.device_id().to_owned())).await.unwrap(); - assert_eq!(core.workspace.chat("side-here").unwrap().unwrap().device_id, core.workspace.device_id()); - agent_creates("side-there", Some("cloud-s-chat-1".into())).await.unwrap(); - assert_eq!(core.workspace.chat("side-there").unwrap().unwrap().device_id, "cloud-s-chat-1"); + agent_creates("side-here", Some(core.workspace.device_id().to_owned())) + .await + .unwrap(); + assert_eq!( + core.workspace.chat("side-here").unwrap().unwrap().device_id, + core.workspace.device_id() + ); + agent_creates("side-there", Some("cloud-s-chat-1".into())) + .await + .unwrap(); + assert_eq!( + core.workspace + .chat("side-there") + .unwrap() + .unwrap() + .device_id, + "cloud-s-chat-1" + ); agent_creates("side-unnamed", None).await.unwrap(); - assert_eq!(core.workspace.chat("side-unnamed").unwrap().unwrap().device_id, "cloud-s-chat-1"); + assert_eq!( + core.workspace + .chat("side-unnamed") + .unwrap() + .unwrap() + .device_id, + "cloud-s-chat-1" + ); // Without Cloud picked, the same project runs here. create( diff --git a/crates/engine/tests/m5_repos_diffs_terminals.rs b/crates/engine/tests/m5_repos_diffs_terminals.rs index 32c072fbf..53e47f977 100644 --- a/crates/engine/tests/m5_repos_diffs_terminals.rs +++ b/crates/engine/tests/m5_repos_diffs_terminals.rs @@ -2572,6 +2572,48 @@ async fn rpc_dispatch_for_m5_methods() { .expect("OpenTerminal"); let terminal_id = session["id"].as_str().expect("terminal id").to_string(); assert_eq!(session["cwd"], repo_path); + assert_eq!( + core.terminals.chats().get(&terminal_id).map(String::as_str), + Some("chat-term") + ); + + // A chat another device runs (seen here, as a Cloud machine sees every + // chat): its folder is a path there, and its session row is its host's, + // so the terminal neither starts in it nor joins it. (No project: a + // project's chats run on the project's device.) + client + .call( + methods::MUTATE, + serde_json::json!({ + "op": "createChat", + "chatId": "chat-elsewhere", + "deviceId": "another-device", + "cwd": repo_path, + }), + ) + .await + .expect("createChat elsewhere"); + assert_eq!( + core.workspace.chat("chat-elsewhere").unwrap().unwrap().device_id, + "another-device" + ); + let elsewhere = client + .call( + methods::OPEN_TERMINAL, + serde_json::json!({ "chatId": "chat-elsewhere", "cols": 80, "rows": 24 }), + ) + .await + .expect("OpenTerminal for a chat run elsewhere"); + assert_ne!(elsewhere["cwd"], repo_path); + let elsewhere_id = elsewhere["id"].as_str().expect("terminal id"); + assert!(!core.terminals.chats().contains_key(elsewhere_id)); + client + .call( + methods::CLOSE_TERMINAL, + serde_json::json!({ "terminalId": elsewhere_id }), + ) + .await + .expect("CloseTerminal elsewhere"); // New-chat canvas: no chat row. The space id in chatId is enough even // when the UI still sends `~` (spaces watch not landed) or omits cwd. diff --git a/crates/harness/src/lib.rs b/crates/harness/src/lib.rs index 287d3aa29..74bcd9f39 100644 --- a/crates/harness/src/lib.rs +++ b/crates/harness/src/lib.rs @@ -453,6 +453,16 @@ pub fn compose_login_shell_path(cmd: &mut tokio::process::Command) { apply_login_shell_env(cmd.as_std_mut()); } +/// The user's own PATH (the login shell's, with this process's) and the +/// login shell's TLS, SSH-agent and locale variables, for a child that runs +/// whatever the user would type: a shell running an agent's command. Unlike +/// [`compose_child_path`], no executable's directory goes first (the +/// shell's own `/bin` must not shadow the user's toolchain). +pub fn compose_user_path(cmd: &mut process::Command) { + compose_path(cmd.as_std_mut(), std::iter::empty()); + apply_login_shell_env(cmd.as_std_mut()); +} + /// Compose the child's PATH: the resolved executable's directory first, then /// the user's own PATH (the login shell's), then this process's — deduped. /// npm-shim CLIs are `#!/usr/bin/env node` scripts whose `node` lives beside diff --git a/crates/harness/src/process.rs b/crates/harness/src/process.rs index 05aad6b08..8636f4353 100644 --- a/crates/harness/src/process.rs +++ b/crates/harness/src/process.rs @@ -571,4 +571,4 @@ mod tests { } } -pub(crate) mod owned; +pub mod owned; diff --git a/crates/harness/src/process/owned.rs b/crates/harness/src/process/owned.rs index 28d6cea7b..4c09b9900 100644 --- a/crates/harness/src/process/owned.rs +++ b/crates/harness/src/process/owned.rs @@ -11,7 +11,7 @@ use crate::process::{Child as ProcessChild, Command}; /// own configuration (`CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_USE_BEDROCK`/`VERTEX`, /// `CLAUDE_CODE_GIT_BASH_PATH`, `ANTHROPIC_*`) is kept. Every Claude Zeron /// starts, directly or through an adapter, reports Zeron as its entrypoint. -pub(crate) fn configure(command: &mut Command) { +pub fn configure(command: &mut Command) { #[cfg(unix)] command.process_group(0); for key in INHERITED_SESSION_MARKERS { @@ -34,14 +34,14 @@ const INHERITED_SESSION_MARKERS: [&str; 11] = [ "CLAUDE_AGENT_SDK_VERSION", ]; -pub(crate) struct Child { +pub struct Child { inner: ProcessChild, #[cfg(unix)] group: Option, } impl Child { - pub(crate) fn new(inner: ProcessChild) -> Self { + pub fn new(inner: ProcessChild) -> Self { Self { #[cfg(unix)] group: Some(-(inner.id().expect("newly spawned child") as i32)), @@ -49,7 +49,9 @@ impl Child { } } - pub(crate) async fn shutdown(&mut self, grace: std::time::Duration) { + /// End it and everything it started: its group (and, on Unix, the + /// descendants that left it) asked to stop, then killed after `grace`. + pub async fn shutdown(&mut self, grace: std::time::Duration) { self.shutdown_with(Vec::new(), grace).await; } diff --git a/crates/mcp/src/tools/commands.rs b/crates/mcp/src/tools/commands.rs index f30e10f3e..e5f5f64cc 100644 --- a/crates/mcp/src/tools/commands.rs +++ b/crates/mcp/src/tools/commands.rs @@ -49,7 +49,7 @@ pub(super) fn catalog() -> Vec { vec![ ToolDef { name: RUN_COMMAND, - description: "Run a shell command on this device or on any other of the person's online devices (see list_devices; a Cloud machine must be awake), exactly as you would with your own shell tool: builds, tests, git, package managers, scripts, servers. It runs in the user's login shell there (PowerShell on Windows), with their PATH, and no input or terminal. The working directory carries over between commands on the same device (`cd` sticks; environment variables don't); the first command on a device starts in `cwd`, or your chat's folder on its own device, or home. Returns `output` (stdout and stderr together; long output keeps its start and end), `exitCode`, and `timedOut`: a command still running at `timeout_secs` (default 120, at most 600) is killed with everything it started. For something that keeps running — a dev server, a watcher, a long build — pass `background: true`: it returns an `id` at once; read what it prints with command_output and stop it with stop_command. Background commands stop on their own when this chat is archived or deleted. Only a chat with full access may use this.", + description: "Run a shell command on this device or on any other of the person's online devices (see list_devices; a Cloud machine must be awake), exactly as you would with your own shell tool: builds, tests, git, package managers, scripts, servers. It runs in the user's shell there (PowerShell on Windows) with the PATH and variables their login shell sets, and no input or terminal. The working directory carries over between commands on the same device (`cd` sticks; environment variables don't); the first command on a device starts in `cwd`, or your chat's folder on its own device, or home. Returns `output` (stdout and stderr together; long output keeps its start and end), `exitCode`, and `timedOut`: a command still running at `timeout_secs` (default 120, at most 600) is killed with everything it started, and anything a command leaves running (`server &`) ends with it. For something that keeps running — a dev server, a watcher, a long build — pass `background: true`: it returns an `id` at once; read what it prints with command_output and stop it with stop_command. Background commands stop on their own when this chat is archived or deleted. Only a chat with full access may use this.", input_schema: json!({ "type": "object", "properties": { @@ -120,7 +120,10 @@ impl Tools { pub(super) async fn commands(&self, tool: &str, args: Value) -> Result { let result = match tool { RUN_COMMAND => self.run_command(parse(args)?).await, - COMMAND_OUTPUT => self.command_call(methods::READ_COMMAND_OUTPUT, parse(args)?).await, + COMMAND_OUTPUT => { + self.command_call(methods::READ_COMMAND_OUTPUT, parse(args)?) + .await + } STOP_COMMAND => self.command_call(methods::STOP_COMMAND, parse(args)?).await, _ => self.list_commands(parse(args)?).await, }; @@ -129,7 +132,8 @@ impl Tools { /// The device to send to (`None`: this engine's), and how a reply names it. async fn command_device(&self, key: Option<&str>) -> anyhow::Result<(Option, Value)> { - let (devices, local) = tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; + let (devices, local) = + tokio::try_join!(self.zeron.devices(), self.zeron.local_device_id())?; let id = self.zeron.resolve_device_id(key).await?; let name = devices.iter().find(|d| d.id == id).map(|d| d.name.clone()); let named = json!({ "id": id, "name": name, "local": id == local }); @@ -140,12 +144,20 @@ impl Tools { anyhow::ensure!(!args.command.trim().is_empty(), "command is empty"); let (target, device) = self.command_device(args.device.as_deref()).await?; let device_id = device["id"].as_str().unwrap_or_default().to_owned(); - let asked = args.cwd.as_deref().map(str::trim).filter(|c| !c.is_empty()).map(str::to_owned); + let asked = args + .cwd + .as_deref() + .map(str::trim) + .filter(|c| !c.is_empty()) + .map(str::to_owned); let remembered = match &asked { Some(_) => None, None => self.command_state.cwd.lock().await.get(&device_id).cloned(), }; - let timeout = args.timeout_secs.unwrap_or(DEFAULT_TIMEOUT_SECS).clamp(1, MAX_TIMEOUT_SECS); + let timeout = args + .timeout_secs + .unwrap_or(DEFAULT_TIMEOUT_SECS) + .clamp(1, MAX_TIMEOUT_SECS); let mut params = json!({ "command": args.command, "timeoutMs": timeout * 1000 }); if args.background { params["background"] = json!(true); @@ -165,7 +177,9 @@ impl Tools { }; let reply = match send(asked.as_ref().or(remembered.as_ref())).await { // The folder it was left in is gone: start where a first one would. - Err(RpcError::Failed(message)) if remembered.is_some() && message.starts_with("No folder") => { + Err(RpcError::Failed(message)) + if remembered.is_some() && message.starts_with("No folder") => + { self.command_state.cwd.lock().await.remove(&device_id); send(None).await } @@ -177,7 +191,11 @@ impl Tools { outcome["id"] = json!(format!("{id}@{device_id}")); } } else if let Some(cwd) = outcome["cwd"].as_str() { - self.command_state.cwd.lock().await.insert(device_id, cwd.to_owned()); + self.command_state + .cwd + .lock() + .await + .insert(device_id, cwd.to_owned()); } else if let Some(asked) = asked { // A shell that doesn't say where it ended: where it was asked. self.command_state.cwd.lock().await.insert(device_id, asked); @@ -242,14 +260,21 @@ mod tests { #[async_trait::async_trait] impl zeron_rpc::RpcService for Engine { - async fn handle(&self, method: &str, params: Value) -> Result { + async fn handle( + &self, + method: &str, + params: Value, + ) -> Result { use futures::StreamExt; use zeron_rpc::RpcReply; if method.contains("Command") { if self.old_remote && params["targetDeviceId"] == "dev-remote" { return Err(RpcError::UnknownMethod(method.into())); } - self.calls.lock().unwrap().push((method.to_owned(), params.clone())); + self.calls + .lock() + .unwrap() + .push((method.to_owned(), params.clone())); } Ok(match method { methods::LOCAL_DEVICE => RpcReply::Value(json!({ "deviceId": "dev-local" })), @@ -285,8 +310,14 @@ mod tests { } fn tools(engine: Arc) -> Tools { - let origin = Origin { chat_id: Some("chat-1".into()), ..Default::default() }; - Tools::new(Arc::new(Zeron::with_client(zeron_rpc::memory_client(engine), origin))) + let origin = Origin { + chat_id: Some("chat-1".into()), + ..Default::default() + }; + Tools::new(Arc::new(Zeron::with_client( + zeron_rpc::memory_client(engine), + origin, + ))) } fn last(engine: &Engine) -> (String, Value) { @@ -295,62 +326,134 @@ mod tests { #[tokio::test] async fn a_command_runs_on_the_device_it_names_and_cd_carries_over_there() { - let engine = Arc::new(Engine { calls: Default::default(), old_remote: false }); + let engine = Arc::new(Engine { + calls: Default::default(), + old_remote: false, + }); let tools = tools(engine.clone()); let ran = tools .call(RUN_COMMAND, json!({ "command": "echo hi", "device": "Worker", "cwd": "/srv", "timeout_secs": 5 })) .await .unwrap(); - assert_eq!((ran["output"].as_str(), ran["exitCode"].as_i64()), (Some("hi\n"), Some(0))); - assert_eq!(ran["device"], json!({ "id": "dev-remote", "name": "Worker", "local": false })); + assert_eq!( + (ran["output"].as_str(), ran["exitCode"].as_i64()), + (Some("hi\n"), Some(0)) + ); + assert_eq!( + ran["device"], + json!({ "id": "dev-remote", "name": "Worker", "local": false }) + ); assert_eq!( last(&engine).1, json!({ "command": "echo hi", "cwd": "/srv", "timeoutMs": 5000, "chatId": "chat-1", "targetDeviceId": "dev-remote" }) ); // cd there sticks there, and only there. - tools.call(RUN_COMMAND, json!({ "command": "cd /srv/app", "device": "Worker" })).await.unwrap(); - tools.call(RUN_COMMAND, json!({ "command": "ls", "device": "Worker" })).await.unwrap(); + tools + .call( + RUN_COMMAND, + json!({ "command": "cd /srv/app", "device": "Worker" }), + ) + .await + .unwrap(); + tools + .call(RUN_COMMAND, json!({ "command": "ls", "device": "Worker" })) + .await + .unwrap(); assert_eq!(last(&engine).1["cwd"], "/srv/app"); - tools.call(RUN_COMMAND, json!({ "command": "ls", "timeout_secs": 100000 })).await.unwrap(); + tools + .call( + RUN_COMMAND, + json!({ "command": "ls", "timeout_secs": 100000 }), + ) + .await + .unwrap(); let (_, here) = last(&engine); - assert!(here.get("cwd").is_none() && here.get("targetDeviceId").is_none(), "{here}"); + assert!( + here.get("cwd").is_none() && here.get("targetDeviceId").is_none(), + "{here}" + ); assert_eq!(here["timeoutMs"], MAX_TIMEOUT_SECS * 1000); // A folder that's gone: back to where a first command starts. - tools.call(RUN_COMMAND, json!({ "command": "cd /gone" })).await.unwrap(); - tools.call(RUN_COMMAND, json!({ "command": "ls" })).await.unwrap(); + tools + .call(RUN_COMMAND, json!({ "command": "cd /gone" })) + .await + .unwrap(); + tools + .call(RUN_COMMAND, json!({ "command": "ls" })) + .await + .unwrap(); assert!(last(&engine).1.get("cwd").is_none()); - assert!(tools.call(RUN_COMMAND, json!({ "command": " " })).await.unwrap_err().contains("empty")); + assert!( + tools + .call(RUN_COMMAND, json!({ "command": " " })) + .await + .unwrap_err() + .contains("empty") + ); } #[tokio::test] async fn a_background_command_is_found_again_by_its_id_wherever_it_runs() { - let engine = Arc::new(Engine { calls: Default::default(), old_remote: false }); + let engine = Arc::new(Engine { + calls: Default::default(), + old_remote: false, + }); let tools = tools(engine.clone()); let started = tools - .call(RUN_COMMAND, json!({ "command": "npm run dev", "device": "Worker", "background": true })) + .call( + RUN_COMMAND, + json!({ "command": "npm run dev", "device": "Worker", "background": true }), + ) .await .unwrap(); assert_eq!(started["id"], "cmd-1@dev-remote"); assert_eq!(last(&engine).1["background"], true); - let read = tools.call(COMMAND_OUTPUT, json!({ "id": "cmd-1@dev-remote" })).await.unwrap(); + let read = tools + .call(COMMAND_OUTPUT, json!({ "id": "cmd-1@dev-remote" })) + .await + .unwrap(); assert_eq!(read["output"], "listening\n"); assert_eq!(read["id"], "cmd-1@dev-remote"); - assert_eq!(last(&engine), (methods::READ_COMMAND_OUTPUT.to_owned(), json!({ "id": "cmd-1", "targetDeviceId": "dev-remote" }))); + assert_eq!( + last(&engine), + ( + methods::READ_COMMAND_OUTPUT.to_owned(), + json!({ "id": "cmd-1", "targetDeviceId": "dev-remote" }) + ) + ); - tools.call(STOP_COMMAND, json!({ "id": "cmd-1@dev-remote" })).await.unwrap(); + tools + .call(STOP_COMMAND, json!({ "id": "cmd-1@dev-remote" })) + .await + .unwrap(); assert_eq!(last(&engine).0, methods::STOP_COMMAND); - let listed = tools.call(LIST_COMMANDS, json!({ "device": "Worker" })).await.unwrap(); + let listed = tools + .call(LIST_COMMANDS, json!({ "device": "Worker" })) + .await + .unwrap(); assert_eq!(listed["commands"][0]["id"], "cmd-1@dev-remote"); - assert_eq!(last(&engine).1, json!({ "chatId": "chat-1", "targetDeviceId": "dev-remote" })); + assert_eq!( + last(&engine).1, + json!({ "chatId": "chat-1", "targetDeviceId": "dev-remote" }) + ); } #[tokio::test] async fn an_older_device_says_so() { - let tools = tools(Arc::new(Engine { calls: Default::default(), old_remote: true })); - let error = tools.call(RUN_COMMAND, json!({ "command": "ls", "device": "dev-remote" })).await.unwrap_err(); + let tools = tools(Arc::new(Engine { + calls: Default::default(), + old_remote: true, + })); + let error = tools + .call( + RUN_COMMAND, + json!({ "command": "ls", "device": "dev-remote" }), + ) + .await + .unwrap_err(); assert!(error.contains("too old"), "{error}"); } } diff --git a/crates/rpc/src/lib.rs b/crates/rpc/src/lib.rs index 92c5697e1..05b1d1ab0 100644 --- a/crates/rpc/src/lib.rs +++ b/crates/rpc/src/lib.rs @@ -313,6 +313,10 @@ pub mod methods { pub const STOP_COMMAND: &str = "StopCommand"; /// `{chatId?}` → `[CommandStatus]`: the background commands a chat started. pub const LIST_BACKGROUND_COMMANDS: &str = "ListBackgroundCommands"; + /// `{chatId}` → stream of `[CommandStatus]`: [`LIST_BACKGROUND_COMMANDS`] + /// now and each time one starts or ends. The chat's host follows its + /// agent's commands on other devices with it (its background band). + pub const WATCH_BACKGROUND_COMMANDS: &str = "WatchBackgroundCommands"; /// Checkout-diff stream for the target device's chats (DataRpc, /// relay-forwardable — diffs are produced where the checkout lives). pub const WATCH_CHECKOUT_DIFFS: &str = "WatchCheckoutDiffs"; @@ -1479,7 +1483,10 @@ mod tests { assert!(asked.as_str().unwrap().starts_with("Agent"), "{asked}"); // A command reaches the engine as the agent's, which runs it only // for a chat with full access and no sandbox. - let asked = agent.call(methods::RUN_COMMAND, serde_json::json!({})).await.unwrap(); + let asked = agent + .call(methods::RUN_COMMAND, serde_json::json!({})) + .await + .unwrap(); assert!(asked.as_str().unwrap().starts_with("Agent"), "{asked}"); // The theme tools' methods, exactly: data only. for method in [methods::LIST_THEMES, methods::GET_THEME, methods::CREATE_THEME, methods::UPDATE_THEME, methods::DELETE_THEME, methods::USE_THEME] { diff --git a/docs/design/cloud-device.md b/docs/design/cloud-device.md index 001a67a56..a6abb990f 100644 --- a/docs/design/cloud-device.md +++ b/docs/design/cloud-device.md @@ -148,15 +148,21 @@ device (`run_command`), as an agent on the laptop can. Enforced at the edge: on runner forwards and strips any inbound value). Writes: `devices` only its own row; `chats`, `spaces`, `sessions` when the existing live row is hosted by the runner AND the row after the op still is (no claiming, handing away or ownerless rows) — except that a - chat hosted elsewhere may be renamed or archived (`title`, `archived`), and a new chat row - may be hosted by any device (a chat it starts there); deletes need a live owned row (or a - delegate's, below); tombstones are never revived; every other kind (`preferences`, + chat hosted elsewhere may have any field set but its host (`deviceId`: a chat is never + re-homed), and a new chat row may be hosted by any device (a chat it starts there); + another device's `spaces` and `sessions` rows stay its own; deletes need a live owned row + (or a delegate's, below); tombstones are never revived; every other kind (`preferences`, `sidebarPins`, anything new) is refused. Refused ops are skipped individually (an `{t:"error", code:"not_owner"}` frame each, plus `rejected` in the ack); the rest of the batch applies. Reads (hello/backfill, live `rows` broadcasts, `GET /rows`): every - `devices`, `chats`, `spaces` and `sessions` row; none of the user's own kinds. + `devices`, `chats`, `spaces` and `sessions` row; none of the user's own kinds. A machine + that synced while it saw only its own rows holds a cursor past rows it never got, so its + first state since is `full` (`RegistryRoom.runnerBehind`, recorded per device as the seq + it was sent at; sent again until the machine's cursor passes that seq). Presence is unfiltered, but a runner socket's presence/attribution device is pinned to its verified id. +- **Waking**: a Cloud machine's send (`POST /device/{id}/nudge`) wakes any of the person's + sleeping sessions, as their other devices' sends do (`CloudAccount.autoWake`). - **Engine** (`crates/engine/src/rpc/agent_gate.rs`): what an agent may do is the same on Cloud as on a computer. It runs commands (`RunCommand`, `ReadCommandOutput`, `StopCommand`, `ListBackgroundCommands`, here or on another device) only from a chat with full access and no diff --git a/edge/src/cloud/cloud-account.ts b/edge/src/cloud/cloud-account.ts index 5bf7d419a..876547927 100644 --- a/edge/src/cloud/cloud-account.ts +++ b/edge/src/cloud/cloud-account.ts @@ -1702,8 +1702,8 @@ export class CloudAccount extends DurableObject { const chatId = this.byDevice.get(deviceId); const s = chatId ? this.sessions.get(chatId) : undefined; if (!s || !this.matches(caller) || s.pendingDelete || s.state === "deleting") return false; - // A machine wakes only the sessions it started (its delegates). - if (caller.deviceId !== undefined && s.parentChatId !== this.byDevice.get(caller.deviceId)) return false; + // A Cloud machine's send wakes any of the person's sessions, as their + // other devices' do: its agent messages chats wherever they run. if (s.state === "ready") { // A send to a machine that's up. If it goes dark before its next // heartbeat, that heartbeat never reports the turn this started. diff --git a/edge/src/cloud/routes.ts b/edge/src/cloud/routes.ts index 01d246f0b..8d2e685f6 100644 --- a/edge/src/cloud/routes.ts +++ b/edge/src/cloud/routes.ts @@ -511,10 +511,9 @@ export const handleCloudRoute = async ( * sends wake a session; dials (viewing a chat) never do. The DO is the * caller's own, so another user's device id is simply not found there. * - * A Cloud machine's runner wakes a session too, but only one it started (its - * delegate): the agent there sent work to a side chat on a machine that went - * to sleep. The account DO checks the parentage, as it does for every other - * session action a runner takes. + * A Cloud machine's runner wakes a session too: its agent sent work to a + * chat (a delegate, or any other of the person's Cloud chats) on a machine + * that went to sleep. */ export const autoWakeCloudDevice = ( env: Pick, diff --git a/edge/src/registry-room.ts b/edge/src/registry-room.ts index bc9b9abe4..d4a06f6ca 100644 --- a/edge/src/registry-room.ts +++ b/edge/src/registry-room.ts @@ -19,8 +19,9 @@ * - presence — memory-only by construction (15s client beats, rebroadcast). * * Cloud runners (the Worker stamps RUNNER_DEVICE_HEADER for runner bearers) - * act as their device, not the user: every row delivery to them is filtered - * and every op they push must be on a row they host (registry-runner.ts). + * act as their device, not the user: row deliveries to them leave out the + * user's own kinds, and every op they push is ownership-checked + * (registry-runner.ts). * * Hibernation discipline: ZERO wall-clock timers; ping/pong rides the * auto-response pair; the one alarm does the bookkeeping flush and, daily, @@ -61,7 +62,7 @@ interface SocketState { /** Set once a valid hello established the session. */ ready?: boolean; /** Cloud runner socket: its verified device id. Rows are filtered and - * pushes ownership-checked for it. */ + * pushes ownership-checked for it (registry-runner.ts). */ runner?: string; /** The runner's account (logical Cloud device; JWT `cld`). */ runnerAccount?: string; @@ -219,6 +220,26 @@ export class RegistryRoom implements DurableObject { return rows.filter((row) => runnerCanSee(runner, row)); } + /** + * Whether runner `device`, at `cursor`, has yet to be sent every row it now + * sees (registry-runner.ts). Before, a runner was sent only its own rows, + * so a Cloud machine that synced then holds a cursor past laptop chats, + * projects and sessions it never received: its first state since is full. + * Recorded as the seq that full state was sent at. Only a cursor PAST it + * proves the runner applied it (and a row since): a cursor at it may be + * one that never got the reply, so that runner is sent everything again + * (a few extra full states at most — its own rows move the head on). + * Records the send when true. + */ + private runnerBehind(device: string | undefined, cursor: number | null, seq: number): boolean { + if (device === undefined) return false; + const key = `runnerSentAll:${device}`; + const sentAt = this.getMeta(key); + if (sentAt !== undefined && cursor !== null && cursor > Number(sentAt)) return false; + this.setMeta(key, String(seq)); + return true; + } + /** The live chats whose parent `device` hosts: delegates it started on * other machines, which it may delete. */ private runnerChildren(device: string): Set { @@ -367,7 +388,7 @@ export class RegistryRoom implements DurableObject { } const seq = this.seq(); const gcFloor = this.gcFloor(); - const full = cursor === null || cursor < gcFloor || cursor > seq; + const full = cursor === null || cursor < gcFloor || cursor > seq || this.runnerBehind(runner, cursor, seq); return json({ seq, full, @@ -497,8 +518,10 @@ export class RegistryRoom implements DurableObject { // A cursor from before the tombstone-GC horizon may have missed purged // deletes; a cursor AHEAD of the server means the server lost state (a // reset/wipe) — both force `full`, and the client reacts by replacing - // (former) or re-seeding the server (latter; see registry.rs). - const full = cursor === null || cursor < gcFloor || cursor > seq; + // (former) or re-seeding the server (latter; see registry.rs). So does a + // Cloud machine's cursor from before it saw every row (runnerBehind). + const full = + cursor === null || cursor < gcFloor || cursor > seq || this.runnerBehind(state.runner, cursor, seq); const rows = this.visible(full ? this.rowsSince(0) : this.rowsSince(cursor), state.runner, state.runnerAccount); send(ws, { t: "state", @@ -538,8 +561,8 @@ export class RegistryRoom implements DurableObject { /** Validate + atomically apply one op batch and broadcast merged rows to * every ready socket -- shared by the WS push and the HTTP `POST /push` * fallback. The caller delivers the ack/error on its own transport. - * `runner` (a Cloud device) may only touch rows it hosts: its other ops - * are skipped and reported in `rejected`, the rest of the batch applies. */ + * `runner` (a Cloud device) is ownership-checked (registry-runner.ts): its + * refused ops are skipped and reported in `rejected`, the rest applies. */ private applyPushBatch( device: string, frame: Record, diff --git a/edge/src/registry-runner.test.ts b/edge/src/registry-runner.test.ts index e83600ad2..80f413f51 100644 --- a/edge/src/registry-runner.test.ts +++ b/edge/src/registry-runner.test.ts @@ -28,17 +28,18 @@ describe("runner registry writes", () => { expect(runnerOpRefusal(CLOUD, row("sessions", "c1", { deviceId: CLOUD }), upsert("sessions", "c1", { status: "idle" }))).toBeNull(); }); - it("renames or archives a chat on another device, and starts chats there", () => { + it("sets any field of a chat on another device but its host, and starts chats there", () => { const laptopChat = row("chats", "c2", { deviceId: LAPTOP, title: "plans" }); expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { title: "x" }))).toBeNull(); expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { archived: true }))).toBeNull(); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { branch: "dev", config: { harness: "codex" } }))).toBeNull(); expect(runnerOpRefusal(CLOUD, undefined, upsert("chats", "c9", { deviceId: LAPTOP, parentChatId: "c1" }))).toBeNull(); }); - it("refuses claiming, reconfiguring or deleting another device's rows", () => { + it("refuses claiming or deleting another device's rows", () => { const laptopChat = row("chats", "c2", { deviceId: LAPTOP, title: "plans" }); - expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { deviceId: CLOUD }))).toMatch(/only be renamed or archived/); - expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { config: {} }))).toMatch(/only be renamed or archived/); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { deviceId: CLOUD }))).toMatch(/stays hosted there/); + expect(runnerOpRefusal(CLOUD, laptopChat, upsert("chats", "c2", { title: "x", deviceId: LAPTOP }))).toMatch(/stays hosted there/); expect(runnerOpRefusal(CLOUD, laptopChat, del("chats", "c2"))).toMatch(/another device/); expect(runnerOpRefusal(CLOUD, row("spaces", "s1", { deviceId: LAPTOP }), upsert("spaces", "s1", { name: "x" }))).toMatch(/another device/); expect(runnerOpRefusal(CLOUD, row("sessions", "c2", { deviceId: LAPTOP }), upsert("sessions", "c2", { status: "idle" }))).toMatch(/another device/); @@ -94,12 +95,11 @@ describe("delegates (child chats on other machines)", () => { const children = new Set(["child"]); const child = row("chats", "child", { deviceId: OTHER, parentChatId: "main", title: "t" }); - it("may also delete a child, with its session row, but not re-home or reconfigure it", () => { + it("may also delete a child, with its session row, but not re-home it", () => { expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { title: "x" }), children)).toBeNull(); expect(runnerOpRefusal(CLOUD, child, del("chats", "child"), children)).toBeNull(); expect(runnerOpRefusal(CLOUD, row("sessions", "child", { deviceId: OTHER }), del("sessions", "child"), children)).toBeNull(); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { deviceId: CLOUD }), children)).toMatch(/only be renamed/); - expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { parentChatId: null }), children)).toMatch(/only be renamed/); + expect(runnerOpRefusal(CLOUD, child, upsert("chats", "child", { deviceId: CLOUD }), children)).toMatch(/stays hosted there/); expect(runnerOpRefusal(CLOUD, row("sessions", "child", { deviceId: OTHER }), upsert("sessions", "child", { status: "idle" }), children)).toMatch(/another device/); // Not its child: no delete. expect(runnerOpRefusal(CLOUD, child, del("chats", "child"))).toMatch(/another device/); diff --git a/edge/src/registry-runner.ts b/edge/src/registry-runner.ts index 61d19a362..7b52ec1a8 100644 --- a/edge/src/registry-runner.ts +++ b/edge/src/registry-runner.ts @@ -4,12 +4,12 @@ * * A Cloud chat works with the person's other devices the way a chat on any * of their computers does: its runner SEES every device, chat, project and - * session row (so its agent can list and message chats anywhere), but it - * still WRITES as its device. It may write the rows it hosts, start a chat - * on another device (a new row hosted there), and rename or archive any - * chat — never re-home a chat, delete another device's (its delegates - * aside), or touch the user's own kinds (preferences, sidebar pins). Its - * delegates (child chats it started on other machines) may also be deleted. + * session row (so its agent can list and message chats anywhere), and + * writes chats as any of their devices may — start one on another device, + * set any field of one hosted elsewhere (its title, branch, config, …) — + * but it never re-homes a chat, deletes another device's (its delegates + * aside), writes another device's project or session rows (their host's to + * keep), or touches the user's own kinds (preferences, sidebar pins). * Ownership is the row's `fields.deviceId` (the host). Pure (no storage), * separate from registry-core.ts, which mirrors the Rust merge code 1:1 — * this is server-only policy. @@ -20,9 +20,8 @@ import { applyOp, type Op, type Row } from "./registry-core"; * (crates/doc/src/registry.rs: spaces, chats, sessions). */ const HOSTED_KINDS = new Set(["chats", "spaces", "sessions"]); -/** The fields a runner may write on a chat hosted elsewhere: its label and - * whether it is archived (what an agent's tools do to any chat). */ -const ANY_CHAT_FIELDS = new Set(["title", "archived"]); +/** What a runner may not write on a chat hosted elsewhere: its host. */ +const HOST_FIELD = "deviceId"; /** No delegates. */ const NO_CHILDREN: ReadonlySet = new Set(); @@ -38,9 +37,8 @@ const hostOf = (row: Row | undefined): string | undefined => { * Why runner `device` may not apply `op` to the stored row `before`, or null * when it may. Rules: * - `devices`: only its own device row; - * - a chat hosted elsewhere may be renamed or archived; a delegate (in - * `children`) may also be deleted, with its session row — its host and - * parent stay as written; + * - a chat hosted elsewhere may have any field set but its host; a delegate + * (in `children`) may also be deleted, with its session row; * - a new chat may be hosted by any device (a chat it starts on another of * the person's devices); every other new or existing hosted row must be * hosted by the runner before and after the op (no claiming another @@ -66,7 +64,7 @@ export const runnerOpRefusal = ( } if (op.kind !== "chats") return "hosted by another device"; const keys = [...Object.keys(op.set ?? {}), ...Object.keys(op.clocks ?? {})]; - return keys.every((key) => ANY_CHAT_FIELDS.has(key)) ? null : "a chat on another device may only be renamed or archived"; + return keys.includes(HOST_FIELD) ? "a chat on another device stays hosted there" : null; } if (op.op === "delete") return live ? null : "no row of this runner's to delete"; if (before?.deleted) return "a runner cannot revive a deleted row"; diff --git a/edge/test/workerd/cloud-delegates.workerd.test.ts b/edge/test/workerd/cloud-delegates.workerd.test.ts index e37680cd0..3d306c013 100644 --- a/edge/test/workerd/cloud-delegates.workerd.test.ts +++ b/edge/test/workerd/cloud-delegates.workerd.test.ts @@ -214,6 +214,13 @@ describe("Cloud delegates", () => { await waitForSession(u, child.chatId, "starting"); }); + it("wakes another of the person's sleeping Cloud chats it sends to, not only its children", async () => { + const { u, other, runner } = await world(); + expect((await session(u, other.chatId))?.state).toBe("sleeping"); + expect((await call("POST", `/device/${other.deviceId}/nudge`, runner, { chatId: other.chatId })).status).toBe(200); + await waitForSession(u, other.chatId, "starting"); + }); + it("wakes its sleeping parent once it stops working: finished, or waiting on an answer", async () => { const { u, user, main, runner } = await world(); const child = await readyChild(u, runner, main.chatId); diff --git a/edge/test/workerd/runner-boundary.workerd.test.ts b/edge/test/workerd/runner-boundary.workerd.test.ts index 0d1cc4099..b1ca68212 100644 --- a/edge/test/workerd/runner-boundary.workerd.test.ts +++ b/edge/test/workerd/runner-boundary.workerd.test.ts @@ -99,7 +99,7 @@ describe("chat-scoped data", () => { const { user, runner, cloud, laptop, laptopChat } = await world(); const claim = await push(runner, [upsert("chats", laptopChat, { deviceId: cloud }, cloud)], cloud); expect(claim.applied).toBe(0); - expect(claim.rejected).toEqual([{ kind: "chats", id: laptopChat, error: "a chat on another device may only be renamed or archived" }]); + expect(claim.rejected).toEqual([{ kind: "chats", id: laptopChat, error: "a chat on another device stays hosted there" }]); expect(find(await rows(user), "chats", laptopChat)?.fields).toMatchObject({ deviceId: laptop, title: "secret plans" }); }); }); @@ -135,7 +135,7 @@ describe("registry writes", () => { expect(find(all, "chats", laptopChat)?.deleted).toBe(false); expect(find(all, "chats", cloudChat)?.fields.deviceId).toBe(cloud); - // It may rename or archive a laptop chat, and start a chat there. + // It may set a laptop chat's fields (not its host), and start a chat there. const startedThere = `lc-${rand()}`; const allowed = await push( runner, @@ -156,6 +156,30 @@ describe("registry writes", () => { }); describe("registry reads", () => { + it("sends a Cloud machine that synced before every row it now sees, until it has them", async () => { + const { user, runner, laptopChat } = await world(); + type Pulled = { seq: number; full: boolean; rows: WireRow[] }; + const pull = async (bearer: string, since: number) => + (await (await call("GET", `/registry/org1/rows?since=${since}`, bearer)).json()) as Pulled; + // Caught up as of now, as a machine that synced before the change is + // (its cursor past the laptop's rows, which it was never sent). + const head = (await pull(user, 0)).seq; + const first = await pull(runner, head); + expect(first.full).toBe(true); + expect(find(first.rows, "chats", laptopChat)).toBeDefined(); + // At that cursor still: maybe it never got the reply, so again. + expect((await pull(runner, head)).full).toBe(true); + // Past it (applied, and a row since): incremental from then on. + await push(user, [upsert("chats", laptopChat, { title: "renamed" }, "laptop")]); + const after = (await pull(user, 0)).seq; + const caughtUp = await pull(runner, after); + expect(caughtUp.full).toBe(false); + await push(user, [upsert("chats", laptopChat, { title: "renamed again" }, "laptop")]); + const next = await pull(runner, after); + expect(next.full).toBe(false); + expect(next.rows.map((r) => r.id)).toEqual([laptopChat]); + }); + it("delivers every device, chat, project and session, never the user's own kinds", async () => { const { user, runner, cloud, laptop, laptopChat, space } = await world(); const cloudChat = `cc-${rand()}`; @@ -197,7 +221,7 @@ describe("registry reads", () => { socket.send(JSON.stringify({ t: "push", batch: "ws-1", ops: [upsert("chats", laptopChat, { deviceId: cloud }, cloud)] })); await expect.poll(() => frames.some((f) => f.t === "ack" && f.batch === "ws-1")).toBe(true); expect(frames.find((f) => f.t === "error" && f.code === "not_owner")).toMatchObject({ - message: `chats/${laptopChat}: a chat on another device may only be renamed or archived` + message: `chats/${laptopChat}: a chat on another device stays hosted there` }); expect(frames.find((f) => f.t === "ack" && f.batch === "ws-1")).toMatchObject({ applied: 0, rejected: [expect.objectContaining({ id: laptopChat })] }); socket.close(); From 77e5f9ff716b49bd5f98fa01ccb7063894467260 Mon Sep 17 00:00:00 2001 From: Wing Date: Mon, 16 Nov 2026 02:04:47 +0000 Subject: [PATCH 6/7] Commands on Windows: the folder file is closed while PowerShell writes it; gate tests use the platform's shell PowerShell's WriteAllText opens the file sharing only reads, which fails while Zeron holds it open for writing: keep just its path (TempPath, still removed after the run). Two gate tests ran POSIX syntax and compared LF output; they now run the platform's shell and compare trimmed lines. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/commands.rs | 10 ++++++---- crates/engine/src/rpc/agent_gate.rs | 17 ++++++++++------- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/crates/engine/src/commands.rs b/crates/engine/src/commands.rs index 6bd47931d..c8f6f979b 100644 --- a/crates/engine/src/commands.rs +++ b/crates/engine/src/commands.rs @@ -266,17 +266,19 @@ impl Commands { })?; let timeout = timeout.min(MAX_TIMEOUT); let started = Instant::now(); - // Where it ends up, written by the shell as it exits. + // Where it ends up, written by the shell as it exits: a closed file + // (Windows refuses a second writer while it's open here), removed + // when this run is done. let ended_in = self .inner .kind .says_folder() - .then(|| tempfile::NamedTempFile::new().ok()) + .then(|| tempfile::NamedTempFile::new().ok().map(|file| file.into_temp_path())) .flatten(); let script = self .inner .kind - .script(command, ended_in.as_ref().map(|file| file.path())); + .script(command, ended_in.as_deref()); let mut child = spawn(&self.inner.shell, self.inner.kind, cwd, &script)?; let (sender, mut chunks) = tokio::sync::mpsc::channel::>(16); let readers = pumps(&mut child, sender); @@ -307,7 +309,7 @@ impl Commands { let cwd = ended_in .filter(|_| !timed_out) - .and_then(|file| std::fs::read_to_string(file.path()).ok()) + .and_then(|path| std::fs::read_to_string(&path).ok()) .map(|pwd| pwd.trim_end_matches(['\n', '\r']).to_owned()) .filter(|pwd| !pwd.is_empty()); let (output, omitted_bytes) = output.finish(); diff --git a/crates/engine/src/rpc/agent_gate.rs b/crates/engine/src/rpc/agent_gate.rs index 45361f5fb..949d20a3c 100644 --- a/crates/engine/src/rpc/agent_gate.rs +++ b/crates/engine/src/rpc/agent_gate.rs @@ -372,10 +372,11 @@ mod tests { let zeron_rpc::RpcReply::Value(ran) = ran else { panic!("a stream") }; + // (`echo` and `exit` mean the same in sh and PowerShell.) assert_eq!( ( ran["exitCode"].clone(), - ran["output"].as_str().unwrap().ends_with("hi\n") + ran["output"].as_str().unwrap().trim_end() == "hi" ), (json!(2), true), "{ran}" @@ -413,11 +414,13 @@ mod tests { ), ) }; - let server = value( - start("echo listening; while true; do sleep 0.05; done") - .await - .unwrap(), - ); + // A server that runs until stopped, in this platform's shell. + let server_command = if cfg!(windows) { + "Write-Output listening; while ($true) { Start-Sleep -Milliseconds 50 }" + } else { + "echo listening; while true; do sleep 0.05; done" + }; + let server = value(start(server_command).await.unwrap()); let quick = value(start("echo done").await.unwrap()); let shown = |core: &crate::EngineCore| -> Vec { core.sessions @@ -457,7 +460,7 @@ mod tests { .await .unwrap(), ); - assert_eq!(read["output"], "listening\n"); + assert_eq!(read["output"].as_str().map(str::trim_end), Some("listening")); // One that ended goes from the row as it ends (followed, not polled). let give_up = std::time::Instant::now() + std::time::Duration::from_secs(2); From a4e90bbf0ffa842425831d151abdd6e2b1e92ad6 Mon Sep 17 00:00:00 2001 From: Wing Date: Mon, 16 Nov 2026 03:34:43 +0000 Subject: [PATCH 7/7] Plugin preview: block agents.cloud_key, as the action already refuses it Setting the API key every Cloud machine uses refuses a plugin preview (agents.rs), but the action was missing from BLOCKED, so the refusal never fired and every_action_the_code_refuses_is_blocked failed on main. Co-Authored-By: Claude Opus 5.5 --- apps/zgx/src/plugins/preview.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/apps/zgx/src/plugins/preview.rs b/apps/zgx/src/plugins/preview.rs index 4b3e7a029..778d9678c 100644 --- a/apps/zgx/src/plugins/preview.rs +++ b/apps/zgx/src/plugins/preview.rs @@ -81,6 +81,8 @@ pub const BLOCKED: &[&str] = &[ "agents.set_key", // (An API key, and what an agent's keys are called.) "agents.add_key", + // (The API key every Cloud machine uses.) + "agents.cloud_key", "agents.rename", "agents.sign_in", "agents.sign_out",