From f82b11ce3864037c5c6f3fc3457e4ec4b625d4bc Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:39:12 -0600 Subject: [PATCH] desktop: its own crate, incord-desktop, with the incu binary src/desktop/ moves whole to crates/desktop (package incord-desktop, lib incord_desktop, binary incu), the way the sandbox became incord-sandbox. It no longer depends on incode; incode depends on it. The three couplings are cut inside the crate: - permissions -> permission::Tier (observe / act / deny), reading incode's mode words so `-p read-only` keeps its meaning; `--tier observe|act` is the crate's own flag. - hooks -> hooks::Hooks, a trait, with ShellHooks for incu. incode's `--desktop-mcp` hands the server its own HookRunner through an adapter, so the operator's commands run exactly as before. - folders::create_dir_all -> std::fs::create_dir_all. incode creates the journal's folder, and wraps request_stop, so a fresh .incode/ still gets its .gitignore. - config::Config reads limits, display and hooks, with serde aliases for desktop_limits / desktop_display / desktop_hooks, so incode's admin.json is a valid incu config as it stands. incode keeps src/desktop.rs: a re-export so every crate::desktop::* path is unchanged, the client registration that names incode's flags (client_config*, codex_config_overrides), request_stop, and `serve`, the wrapper `incode --desktop-mcp` calls. The 16 tools and their tiers are unchanged; the "twelve tools" drift is fixed in permissions and the docs. CI: the crate's clippy and tests run (cargo test --lib is incode's alone), the Linux release-build job builds and ldd-checks incu, the X11 live test points at the crate, and the release tag check covers the third crate. wiring::MAX_UNWIRED falls 41 -> 38: that scan reads incode's src/ only. --- .github/workflows/ci.yml | 35 +- .github/workflows/release.yml | 6 +- Cargo.lock | 23 +- Cargo.toml | 109 +-- crates/desktop/Cargo.toml | 101 +++ .../desktop => crates/desktop/src}/capture.rs | 4 +- .../desktop/src}/capture/x11.rs | 30 +- crates/desktop/src/cli.rs | 460 +++++++++++++ crates/desktop/src/config.rs | 180 +++++ {src/desktop => crates/desktop/src}/coords.rs | 0 {src/desktop => crates/desktop/src}/dpi.rs | 0 crates/desktop/src/hooks.rs | 619 ++++++++++++++++++ .../desktop => crates/desktop/src}/journal.rs | 10 +- .../mod.rs => crates/desktop/src/lib.rs | 25 +- {src/desktop => crates/desktop/src}/limits.rs | 0 {src/desktop => crates/desktop/src}/linux.rs | 0 {src/desktop => crates/desktop/src}/macos.rs | 0 crates/desktop/src/main.rs | 25 + {src/desktop => crates/desktop/src}/mcp.rs | 185 ++---- .../desktop/src}/mcp/definitions.rs | 5 +- .../desktop/src}/mcp/gate.rs | 43 +- .../desktop/src}/mcp/guard.rs | 20 +- .../desktop/src}/mcp/tests.rs | 112 +--- .../desktop/src}/mcp/tools.rs | 24 +- .../desktop/src}/mcp/transport.rs | 0 crates/desktop/src/permission.rs | 235 +++++++ {src/desktop => crates/desktop/src}/safety.rs | 6 +- {src/desktop => crates/desktop/src}/thread.rs | 0 {src/desktop => crates/desktop/src}/uia.rs | 2 +- .../desktop/src}/uia_windows.rs | 2 +- {src/desktop => crates/desktop/src}/win32.rs | 2 +- {src/desktop => crates/desktop/src}/x11.rs | 2 +- docs/ARCHITECTURE.md | 4 +- docs/COMPUTER_USE.md | 20 +- docs/incord-memory-integration.md | 2 +- scripts/test-all.sh | 3 + src/desktop.rs | 383 +++++++++++ src/main.rs | 57 +- src/permissions/mod.rs | 17 +- src/wiring.rs | 7 +- 40 files changed, 2278 insertions(+), 480 deletions(-) create mode 100644 crates/desktop/Cargo.toml rename {src/desktop => crates/desktop/src}/capture.rs (99%) rename {src/desktop => crates/desktop/src}/capture/x11.rs (96%) create mode 100644 crates/desktop/src/cli.rs create mode 100644 crates/desktop/src/config.rs rename {src/desktop => crates/desktop/src}/coords.rs (100%) rename {src/desktop => crates/desktop/src}/dpi.rs (100%) create mode 100644 crates/desktop/src/hooks.rs rename {src/desktop => crates/desktop/src}/journal.rs (97%) rename src/desktop/mod.rs => crates/desktop/src/lib.rs (95%) rename {src/desktop => crates/desktop/src}/limits.rs (100%) rename {src/desktop => crates/desktop/src}/linux.rs (100%) rename {src/desktop => crates/desktop/src}/macos.rs (100%) create mode 100644 crates/desktop/src/main.rs rename {src/desktop => crates/desktop/src}/mcp.rs (56%) rename {src/desktop => crates/desktop/src}/mcp/definitions.rs (99%) rename {src/desktop => crates/desktop/src}/mcp/gate.rs (86%) rename {src/desktop => crates/desktop/src}/mcp/guard.rs (92%) rename {src/desktop => crates/desktop/src}/mcp/tests.rs (87%) rename {src/desktop => crates/desktop/src}/mcp/tools.rs (96%) rename {src/desktop => crates/desktop/src}/mcp/transport.rs (100%) create mode 100644 crates/desktop/src/permission.rs rename {src/desktop => crates/desktop/src}/safety.rs (98%) rename {src/desktop => crates/desktop/src}/thread.rs (100%) rename {src/desktop => crates/desktop/src}/uia.rs (99%) rename {src/desktop => crates/desktop/src}/uia_windows.rs (99%) rename {src/desktop => crates/desktop/src}/win32.rs (99%) rename {src/desktop => crates/desktop/src}/x11.rs (99%) create mode 100644 src/desktop.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cc815eb..14522c0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -89,22 +89,25 @@ jobs: with: key: ${{ matrix.target }} - name: Build - run: cargo build --release --locked --target ${{ matrix.target }} -p incord-code -p incord-sandbox - # The released binary must run on a machine with no desktop libraries: + run: cargo build --release --locked --target ${{ matrix.target }} -p incord-code -p incord-sandbox -p incord-desktop + # The released binaries must run on a machine with no desktop libraries: # screen capture talks to the X server over its socket, so nothing of - # Wayland, GBM, EGL, PipeWire or libxcb may be linked. - - name: incode links no desktop library + # Wayland, GBM, EGL, PipeWire or libxcb may be linked. `incu` is the + # desktop crate's own binary; incode links the same crate. + - name: incode and incu link no desktop library shell: bash run: | set -euo pipefail - bin="target/${{ matrix.target }}/release/incode" - ldd "$bin" - if ldd "$bin" | grep -E 'libxcb|libwayland|libgbm|libEGL|libpipewire|libdbus'; then - echo "incode links a desktop library it must not need" >&2 - exit 1 - fi + for program in incode incu; do + bin="target/${{ matrix.target }}/release/$program" + ldd "$bin" + if ldd "$bin" | grep -E 'libxcb|libwayland|libgbm|libEGL|libpipewire|libdbus'; then + echo "$program links a desktop library it must not need" >&2 + exit 1 + fi + done - # Linux screen capture (src/desktop/capture/x11.rs) against a real X + # Linux screen capture (crates/desktop/src/capture/x11.rs) against a real X # server: the display list from RandR, GetImage of the root, the pixel # conversion, at depth 24 (32 bits per pixel) and depth 16 (5-6-5). The # live test is #[ignore]d everywhere else because it needs a display; @@ -127,11 +130,11 @@ jobs: shell: bash run: | set -euo pipefail - live=desktop::capture::x11::tests::a_real_x_screen_is_captured_at_its_size_and_in_its_colours + live=capture::x11::tests::a_real_x_screen_is_captured_at_its_size_and_in_its_colours for screen in 1280x800x24 1024x768x16; do echo "::group::Xvfb -screen 0 $screen" xvfb-run -a -s "-screen 0 $screen" \ - cargo test --lib "$live" -- --ignored --exact --nocapture --test-threads=1 \ + cargo test -p incord-desktop --lib "$live" -- --ignored --exact --nocapture --test-threads=1 \ | tee "$RUNNER_TEMP/live.txt" grep -q "test result: ok. 1 passed" "$RUNNER_TEMP/live.txt" echo "::endgroup::" @@ -189,6 +192,12 @@ jobs: # incode's commands under `sandbox_engine = "insbx"`, for real (Linux; # it says it skipped elsewhere). - run: cargo test --test insbx_engine + # The standalone computer-use crate (`incu`): Windows UI Automation, + # macOS accessibility and Linux X11 each build here, and its tests (the + # desktop server's protocol, gates, journal and kill switch) run on all + # three. `cargo test --lib` above is incode's alone. + - run: cargo clippy -p incord-desktop --all-targets -- -D warnings + - run: cargo test -p incord-desktop # The standalone sandbox (`insbx`). Its escape tests run on Linux and # macOS, and skip, saying so, where the OS cannot enforce what they check. - run: cargo clippy -p incord-sandbox --all-targets -- -D warnings diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bb9f509..54c7df3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,17 +23,17 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Tag matches both crates' versions + - name: Tag matches all three crates' versions env: TAG: ${{ github.ref_name }} run: | set -euo pipefail want="${TAG#v}" cargo metadata --no-deps --format-version 1 \ - | jq -r '.packages[] | select(.name == "incord-code" or .name == "incord-sandbox") | "\(.name) \(.version)"' \ + | jq -r '.packages[] | select(.name == "incord-code" or .name == "incord-sandbox" or .name == "incord-desktop") | "\(.name) \(.version)"' \ > versions.txt cat versions.txt - test "$(wc -l < versions.txt)" -eq 2 + test "$(wc -l < versions.txt)" -eq 3 while read -r name version; do if [ "$version" != "$want" ]; then echo "::error::tag $TAG names version $want, but $name is $version in its Cargo.toml" diff --git a/Cargo.lock b/Cargo.lock index 8280456..8ffb0c2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1999,11 +1999,9 @@ dependencies = [ "base64 0.22.1", "calamine", "chrono", - "clipboard-win", "crossterm", "dom_query", "dom_smoothie", - "enigo", "flate2", "globset", "grep-regex", @@ -2014,6 +2012,7 @@ dependencies = [ "hyper-util", "ignore", "image", + "incord-desktop", "incord-sandbox", "jsonschema", "landlock", @@ -2043,13 +2042,29 @@ dependencies = [ "tree-sitter-rust", "tree-sitter-typescript", "tungstenite", - "uiautomation", "uuid", "windows-sys 0.61.2", + "zip", +] + +[[package]] +name = "incord-desktop" +version = "0.1.0" +dependencies = [ + "base64 0.22.1", + "chrono", + "clipboard-win", + "enigo", + "image", + "libc", + "regex", + "serde", + "serde_json", + "uiautomation", + "windows-sys 0.61.2", "x11rb", "xcap", "zbus", - "zip", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index 9003b07..bd854e3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = [".", "crates/sandbox"] +members = [".", "crates/sandbox", "crates/desktop"] # Standalone workspace root. The crate previously inherited version/edition from # a parent workspace that does not exist, so cargo failed while parsing the # manifest, before it could even look at the source. @@ -90,6 +90,18 @@ agent-client-protocol-schema = { version = "=1.9.1", default-features = false } # no new package; it adds the seccomp filter, the host-allowlist proxy and the # `.git` protection the built-in engine lacks. incord-sandbox = { path = "crates/sandbox" } +# Computer use (`crates/desktop`, binary `incu`): the 16-tool MCP server that +# `incode --desktop-mcp` wraps, and the journal/stop-file/capture code the run +# server and the toolbox call. A path dependency, so no new package: it carries +# the screen-capture, accessibility and input dependencies that used to be +# declared here. `default-features = false` so the `desktop-capture` feature +# below decides whether capture is built, as it always did. +incord-desktop = { path = "crates/desktop", default-features = false } +# PNG and JPEG for the toolbox's own picture handling (`toolbox::image`); the +# same pin and the same two codecs as `incord-desktop`, so it is one package. +# `default-features = false` because the default is FIFTEEN codecs (avif, exr, +# webp, tiff, dds, ...) and pictures need png + jpeg only. +image = { version = "0.25.10", default-features = false, features = ["png", "jpeg"] } # CLI-specific rustyline = { version = "15", features = ["derive"] } @@ -178,68 +190,16 @@ toml = "1" flate2 = "=1.1.10" tar = { version = "=0.4.46", default-features = false } -# Computer use — see docs/COMPUTER_USE.md. THESE ARE NEW PACKAGES, unlike every -# other entry in this file, and the vetting is recorded in .incord/RULE_ACK: -# latest stable as resolved from the live index on 2026-09-16, pinned, MSRV -# re-measured (unchanged at 1.88, now pinned by `image` itself), builds clean. -# -# Both carry `default-features = false`, which is the point: -# - image defaults to FIFTEEN codecs (avif, exr, webp, tiff, dds, ...). We -# encode screenshots, so png + jpeg is the whole requirement. -# - xcap's optional `image` and `wgc` features are both left OFF. `wgc` is -# Windows Graphics Capture, a more modern capture path than the default — -# worth revisiting when there is a reason, not before, since it pulls -# further windows crates. -# -# `screenshots` is NOT used: it is deprecated in favour of xcap by the same -# author, and the 0.8.x version in the original sketch is two minor lines stale. -# -# xcap is the capture library on Windows and macOS ONLY — see the target table -# below — and optional there, behind the `desktop-capture` feature. -image = { version = "0.25.10", default-features = false, features = ["png", "jpeg"] } -enigo = { version = "0.6.1", default-features = false } +# Computer use is its own crate now: `crates/desktop` (`incord-desktop`, binary +# `incu`), declared above. The dependencies only it uses (image, enigo, xcap, +# clipboard-win, uiautomation, x11rb, zbus and the Win32 display bindings) moved +# with it, with the notes on why each is pinned as it is. `image` is declared in +# both: incode decodes and re-encodes pictures too (`toolbox::image`). -# Screen capture on Windows and macOS (`src/desktop/capture.rs`), optional -# behind the `desktop-capture` feature (on by default). -# -# NOT on Linux, where the screen is read from the X server with x11rb instead -# (`src/desktop/capture/x11.rs`). xcap 0.9.8 has no feature to leave out its -# Linux Wayland backend: it always builds libwayshot-xcap (wayland-client, GBM, -# EGL) and PipeWire (pipewire 0.10.1 -> libspa 0.10.1, through bindgen, so -# libclang too), none of which this crate uses — Linux computer use is X11 only -# (docs/COMPUTER_USE.md decision 5). That backend is what broke the release -# build: libspa 0.10 expects newer PipeWire headers than Ubuntu 22.04 (the -# release runner, chosen for its older glibc) ships, and fails to compile -# there (`spa_meta_first` missing, `spa_video_info_raw` has no `flags`). No -# 0.9.x release offers a way out, so on Linux the dependency is gone. -[target.'cfg(any(windows, target_os = "macos"))'.dependencies] -xcap = { version = "0.9.8", default-features = false, optional = true } - -# --------------------------------------------------------------------------- -# Computer use — see docs/COMPUTER_USE.md. -# -# Windows only, because decision 8 ships Windows first. macOS and Linux get -# their own target tables when they land; note that the rest of this crate -# splits windows / not(windows), which is NOT good enough here — three -# platforms need three arms, and `not(windows)` must never be read as Linux. -# -# NO NEW PACKAGE. windows-sys 0.61.2 is ALREADY resolved in Cargo.lock with 13 -# reverse dependencies of its own, so declaring it turns on Win32 bindings the -# binary already links rather than pulling anything new — the same reasoning -# the hyper and base64 entries above record. -# -# The four features are the smallest set that answers "where are the displays -# and how is this one scaled": HiDpi for the process-awareness call and the -# per-monitor DPI query, Gdi for the enumeration, Foundation for RECT, and -# WindowsAndMessaging for the primary-display flag. Each was confirmed present -# in the cached 0.61.2 manifest before being written here, rather than assumed. [target.'cfg(windows)'.dependencies] -clipboard-win = "5.4.1" -uiautomation = "0.25.1" windows-sys = { version = "0.61", features = [ "Win32_Foundation", - "Win32_Graphics_Gdi", - "Win32_UI_HiDpi", + # WindowsAndMessaging: mcp_oauth::open_browser's SW_SHOWNORMAL. "Win32_UI_WindowsAndMessaging", # agent::process_tree — a job object, so stopping an agent stops everything # it started, and the tree dies with incode. SECURITY_ATTRIBUTES and @@ -291,27 +251,6 @@ libc = "0.2" # Pinned exactly, like every other toolbox dependency. [target.'cfg(target_os = "linux")'.dependencies] landlock = "=0.4.7" -# Computer use on Linux (`src/desktop/linux.rs`), on an X11 display — -# `docs/COMPUTER_USE.md` decision 5. -# - enigo's `x11rb` backend: without it enigo on Linux has no backend at all -# and every action fails. Vetted in a scratch copy of this manifest: it -# adds THREE packages — x11rb 0.13.2, x11rb-protocol 0.13.2 and -# gethostname 1.1.0 (MIT OR Apache-2.0, pure Rust, no C library) — and -# nothing on Windows or macOS, since this table is Linux-only. enigo -# 0.6.1 (the latest) pins x11rb 0.13, so 0.14 is not a choice here. -# - zbus for the AT-SPI2 accessibility tree: NO NEW PACKAGE. zbus 5.19.0 -# (the latest) was resolved by xcap when it was vetted; since xcap left -# Linux this line is what resolves it, with the same default features, -# which include the blocking API used here. -# - x11rb, named directly to ask the X server which window keystrokes -# reach (`linux::keyboard_pid`) and to capture the screen -# (`desktop::capture::x11`): NO NEW PACKAGE — the same 0.13.2 the enigo -# backend above already resolves. `randr` is for the display list -# (RandR 1.5 GetMonitors); enigo already turns it on for the same crate, -# so naming it here builds nothing new. -enigo = { version = "0.6.1", default-features = false, features = ["x11rb"] } -x11rb = { version = "0.13.2", default-features = false, features = ["randr"] } -zbus = "5.19" # --------------------------------------------------------------------------- # Features @@ -325,11 +264,11 @@ zbus = "5.19" # Every Outline grammar is on by default; each can be dropped to shrink the # binary, and Outline then says that language was not built in. default = ["desktop-capture", "lang-rust", "lang-ts", "lang-python", "lang-go", "lang-js"] -# Screenshots and the display list for computer use (`src/desktop/capture.rs`), -# on every OS. Without it every capture is refused by name. On Windows and -# macOS it builds xcap; on Linux it needs no extra crate (the X server is read -# with x11rb, which input already links), so `dep:xcap` names nothing there. -desktop-capture = ["dep:xcap"] +# Screenshots and the display list for computer use, on every OS: forwarded to +# `incord-desktop` (`crates/desktop/src/capture.rs`). Without it every capture +# is refused by name. On Windows and macOS it builds xcap; on Linux it needs no +# extra crate (the X server is read with x11rb). +desktop-capture = ["incord-desktop/desktop-capture"] lang-rust = ["dep:tree-sitter-rust"] lang-ts = ["dep:tree-sitter-typescript"] lang-python = ["dep:tree-sitter-python"] diff --git a/crates/desktop/Cargo.toml b/crates/desktop/Cargo.toml new file mode 100644 index 0000000..7bbb019 --- /dev/null +++ b/crates/desktop/Cargo.toml @@ -0,0 +1,101 @@ +[package] +name = "incord-desktop" +# Released beside incode, under the same tag: kept equal to its version. +version = "0.1.0" +edition = "2021" +rust-version = "1.88" +license = "Apache-2.0" +description = "Computer use for an agent: screenshots, accessibility trees, mouse and keyboard, as a 16-tool MCP server with a kill switch and a watch journal" +repository = "https://github.com/incordai/Incode" +keywords = ["computer-use", "mcp", "accessibility", "agents", "automation"] +categories = ["command-line-utilities", "accessibility"] + +[lib] +name = "incord_desktop" +path = "src/lib.rs" + +[[bin]] +name = "incu" +path = "src/main.rs" + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +chrono = "0.4" +# Screenshots travel to the client as base64 image blocks. +base64 = "0.22" +# The operator's hook `matcher` (`src/hooks.rs`). +regex = "1" + +# Moved here from incode with the code that uses them, at the same pins; the +# reasoning for each choice is recorded in incode's Cargo.toml history and in +# docs/COMPUTER_USE.md. +# +# `default-features = false` is the point: image defaults to FIFTEEN codecs +# (avif, exr, webp, tiff, dds, ...) and screenshots need png + jpeg only. +image = { version = "0.25.10", default-features = false, features = ["png", "jpeg"] } +enigo = { version = "0.6.1", default-features = false } + +# Screen capture on Windows and macOS (`src/capture.rs`), optional behind the +# `desktop-capture` feature (on by default). +# +# NOT on Linux, where the screen is read from the X server with x11rb instead +# (`src/capture/x11.rs`). xcap 0.9.8 has no feature to leave out its Linux +# Wayland backend: it always builds libwayshot-xcap (wayland-client, GBM, EGL) +# and PipeWire (pipewire 0.10.1 -> libspa 0.10.1, through bindgen, so libclang +# too), none of which this crate uses -- Linux computer use is X11 only +# (docs/COMPUTER_USE.md decision 5). That backend is what broke the release +# build: libspa 0.10 expects newer PipeWire headers than Ubuntu 22.04 (the +# release runner, chosen for its older glibc) ships, and fails to compile +# there. No 0.9.x release offers a way out, so on Linux the dependency is gone. +[target.'cfg(any(windows, target_os = "macos"))'.dependencies] +xcap = { version = "0.9.8", default-features = false, optional = true } + +# Windows: UI Automation, the clipboard and the Win32 display calls. +# +# The rest of incode splits windows / not(windows), which is NOT good enough +# here: three platforms need three arms, and `not(windows)` must never be read +# as Linux. +# +# windows-sys is the same 0.61.2 incode itself resolves; the features are the +# smallest set that answers "where are the displays and how is this one +# scaled" (HiDpi for the process awareness call and the per-monitor DPI query, +# Gdi for the enumeration, Foundation for RECT and HWND, WindowsAndMessaging +# for the primary-display flag and the window calls) plus Threading for the +# owning program's name of a window (`uia_windows`). +[target.'cfg(windows)'.dependencies] +clipboard-win = "5.4.1" +uiautomation = "0.25.1" +windows-sys = { version = "0.61", features = [ + "Win32_Foundation", + "Win32_Graphics_Gdi", + "Win32_System_Threading", + "Win32_UI_HiDpi", + "Win32_UI_WindowsAndMessaging", +] } + +# `prctl` for the private Xvfb (`src/linux.rs`), and the process group a hook +# command is killed through (`src/hooks.rs`). +[target.'cfg(unix)'.dependencies] +libc = "0.2" + +# Computer use on Linux, on an X11 display (docs/COMPUTER_USE.md decision 5). +# - enigo's `x11rb` backend: without it enigo on Linux has no backend at all +# and every action fails. +# - zbus for the AT-SPI2 accessibility tree, with its default features, +# which include the blocking API used here. +# - x11rb, named directly to ask the X server which window keystrokes reach +# (`linux::keyboard_pid`) and to capture the screen (`capture::x11`); +# `randr` is for the display list (RandR 1.5 GetMonitors). +[target.'cfg(target_os = "linux")'.dependencies] +enigo = { version = "0.6.1", default-features = false, features = ["x11rb"] } +x11rb = { version = "0.13.2", default-features = false, features = ["randr"] } +zbus = "5.19" + +[features] +default = ["desktop-capture"] +# Screenshots and the display list, on every OS. Without it every capture is +# refused by name. On Windows and macOS it builds xcap; on Linux it needs no +# extra crate (the X server is read with x11rb, which input already links), so +# `dep:xcap` names nothing there. +desktop-capture = ["dep:xcap"] diff --git a/src/desktop/capture.rs b/crates/desktop/src/capture.rs similarity index 99% rename from src/desktop/capture.rs rename to crates/desktop/src/capture.rs index 80220de..5b944d2 100644 --- a/src/desktop/capture.rs +++ b/crates/desktop/src/capture.rs @@ -490,7 +490,7 @@ pub(crate) fn desktop_view( } /// Encode an image. Pure, so it is testable with no screen attached. -pub(crate) fn encode( +pub fn encode( image: &RgbaImage, format: ShotFormat, jpeg_quality: u8, @@ -698,7 +698,7 @@ mod tests { #[cfg(all(windows, feature = "desktop-capture"))] mod live { use super::*; - use crate::desktop::screen_info; + use crate::screen_info; #[test] fn a_real_capture_matches_the_display_it_came_from() { diff --git a/src/desktop/capture/x11.rs b/crates/desktop/src/capture/x11.rs similarity index 96% rename from src/desktop/capture/x11.rs rename to crates/desktop/src/capture/x11.rs index 26bc18d..950d709 100644 --- a/src/desktop/capture/x11.rs +++ b/crates/desktop/src/capture/x11.rs @@ -243,7 +243,7 @@ mod live { use x11rb::rust_connection::RustConnection; use super::{displays, scale_from_resources, to_rgba, Monitor, PixelLayout}; - use crate::desktop::Rect; + use crate::Rect; /// The X server `$DISPLAY` names, and which of its screens that is. fn connect() -> Result<(RustConnection, usize), String> { @@ -339,7 +339,7 @@ mod live { impl Monitor { /// Called by `capture::all_monitors`, the one place every capture and /// the display list start from. - pub(in crate::desktop::capture) fn all() -> Result, String> { + pub(in crate::capture) fn all() -> Result, String> { let (conn, screen) = connect()?; let setup = conn.setup(); let screen = setup @@ -358,49 +358,49 @@ mod live { } /// Called by `capture::capture` and `capture::capture_region`. - pub(in crate::desktop::capture) fn name(&self) -> Result { + pub(in crate::capture) fn name(&self) -> Result { Ok(self.name.clone()) } /// The same as [`Monitor::name`]: X11 has no other. Called by /// `capture::monitor_infos`. - pub(in crate::desktop::capture) fn friendly_name(&self) -> Result { + pub(in crate::capture) fn friendly_name(&self) -> Result { Ok(self.name.clone()) } /// Called by `capture::capture`, `capture_region` and `monitor_infos`. - pub(in crate::desktop::capture) fn x(&self) -> Result { + pub(in crate::capture) fn x(&self) -> Result { Ok(self.rect.x) } /// Called by `capture::capture`, `capture_region` and `monitor_infos`. - pub(in crate::desktop::capture) fn y(&self) -> Result { + pub(in crate::capture) fn y(&self) -> Result { Ok(self.rect.y) } /// Called by `capture::capture`, `capture_region` and `monitor_infos`. - pub(in crate::desktop::capture) fn width(&self) -> Result { + pub(in crate::capture) fn width(&self) -> Result { Ok(self.rect.width.max(0) as u32) } /// Called by `capture::capture`, `capture_region` and `monitor_infos`. - pub(in crate::desktop::capture) fn height(&self) -> Result { + pub(in crate::capture) fn height(&self) -> Result { Ok(self.rect.height.max(0) as u32) } /// Called by `capture::monitor_infos`. - pub(in crate::desktop::capture) fn scale_factor(&self) -> Result { + pub(in crate::capture) fn scale_factor(&self) -> Result { Ok(self.scale) } /// Called by `capture::capture_primary` and `capture::monitor_infos`. - pub(in crate::desktop::capture) fn is_primary(&self) -> Result { + pub(in crate::capture) fn is_primary(&self) -> Result { Ok(self.primary) } /// The display's pixels, from the root window. Called by /// `capture::capture` and `capture::capture_region`. - pub(in crate::desktop::capture) fn capture_image(&self) -> Result { + pub(in crate::capture) fn capture_image(&self) -> Result { let (conn, screen) = connect()?; let setup = conn.setup(); let screen = setup @@ -673,7 +673,7 @@ mod tests { .iter() .enumerate() .map(|(i, m)| { - crate::desktop::capture::describe( + crate::capture::describe( i, list.len(), m.name.clone(), @@ -711,7 +711,7 @@ mod tests { ("screen", rect(0, 0, 1280, 800)) ); assert_eq!(only.scale, 2.0); - let info = crate::desktop::capture::describe( + let info = crate::capture::describe( 0, list.len(), only.name.clone(), @@ -764,8 +764,8 @@ mod tests { use x11rb::protocol::xproto::{ConnectionExt as _, CreateWindowAux, WindowClass}; use x11rb::wrapper::ConnectionExt as _; - use crate::desktop::capture::{capture_primary, capture_region, CaptureOptions}; - use crate::desktop::screen_info; + use crate::capture::{capture_primary, capture_region, CaptureOptions}; + use crate::screen_info; let (conn, screen) = x11rb::connect(None).expect("an X server on $DISPLAY"); let setup = conn.setup(); diff --git a/crates/desktop/src/cli.rs b/crates/desktop/src/cli.rs new file mode 100644 index 0000000..8f91d56 --- /dev/null +++ b/crates/desktop/src/cli.rs @@ -0,0 +1,460 @@ +//! What `incu` does, as functions both binaries call: serve the MCP server over +//! stdio, and stop a running one. +//! +//! # Where this sits +//! +//! The server is a separate PROCESS on purpose. Windows per-monitor DPI +//! awareness is set once, before anything reads the screen, and cannot be +//! changed afterwards, so it needs a startup it owns; and a crash in desktop +//! control must not take down a live harness session. Two entry points start +//! that process: +//! +//! - `incu` (`src/main.rs`), which parses its own argv with [`parse`]. +//! - incode's `--desktop-mcp` (`src/main.rs` in incode), a thin wrapper that +//! keeps every existing agent config and installer working: it reads its own +//! `admin.json`, then calls [`serve`] with what it found. +//! +//! # `-p` is an alias of `--tier` +//! +//! incode has always passed `-p ` on the argv of the child it launches, +//! always and never omitted when it is the default, because the child cannot see +//! the flag the session was started with. `-p read-only` therefore keeps +//! working here, through [`Tier::from_mode_word`]; `--tier observe|act` is the +//! crate's own spelling of the same two rungs ([`crate::permission`]). +//! +//! # Nothing on stdout +//! +//! Stdout is the protocol channel, and a banner there is a parse error at the +//! client. Everything [`serve`] says goes to stderr. + +use std::path::{Path, PathBuf}; + +use crate::config::Config; +use crate::hooks::{HookConfig, Hooks, ShellHooks}; +use crate::limits::DesktopLimits; +use crate::mcp::Server; +use crate::permission::Tier; + +/// The usage text of `incu`. +pub const USAGE: &str = "\ +incu - computer use for an agent, as an MCP server over stdio + +USAGE: + incu serve [OPTIONS] speak MCP on stdin/stdout (the default command) + incu stop [OPTIONS] halt the desktop a running server drives + incu --help | --version + +OPTIONS for serve: + --tier what the agent may do (default: act). + observe = look at the screen, never touch it + -p, --permission-mode an alias of --tier that takes incode's mode words: + read-only = observe; workspace-write, + danger-full-access, allow = act; prompt = nothing + --journal append what the desktop did to this file, and + watch for the stop file beside it + --config limits, display and hooks (JSON; incode's + admin.json is read as it stands). Default: + $INCU_CONFIG, else the platform config folder + --display Linux: \":N\" or \"xvfb[:WxH]\" (overrides the config) + +OPTIONS for stop: + --journal stop the server journalling to PATH + --workspace stop the server for DIR's .incode/ journal + (default: the current directory) + +Nothing but the protocol is written to stdout."; + +/// A command line, parsed. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Command { + /// Print this and exit successfully. + Print(String), + /// Run the server. + Serve(ServeArgs), + /// Ask a running server to stop. + Stop(StopArgs), +} + +/// The flags of `incu serve`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ServeArgs { + /// What the agent may do. [`Tier::Act`] when no flag named one. + pub tier: Tier, + /// Where to append what the desktop did; `None` means nobody is watching. + pub journal: Option, + /// The config file named on the command line, if any. + pub config: Option, + /// The Linux display named on the command line, if any. + pub display: Option, +} + +/// The flags of `incu stop`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct StopArgs { + /// The journal whose stop file to write, if one was named. + pub journal: Option, + /// The workspace whose journal it is, when no journal was named. + pub workspace: Option, +} + +/// Parse `incu`'s arguments (without the program name). +/// +/// No subcommand and a leading flag means `serve`, so a client configured with +/// bare flags starts the server. +/// +/// # Errors +/// +/// An unknown flag or subcommand, a flag missing its value, or a mode that +/// names nothing: a typo in a security flag is reported, never resolved to +/// something. +pub fn parse>(args: I) -> Result { + let mut args: Vec = args.into_iter().collect(); + match args.first().map(String::as_str) { + None | Some("serve") => { + if !args.is_empty() { + args.remove(0); + } + parse_serve(args) + } + Some("stop") => { + args.remove(0); + parse_stop(args) + } + Some("-h" | "--help" | "help") => Ok(Command::Print(USAGE.to_string())), + Some("--version" | "-V") => Ok(Command::Print(format!( + "incu {}", + env!("CARGO_PKG_VERSION") + ))), + Some(flag) if flag.starts_with('-') => parse_serve(args), + Some(other) => Err(format!("unknown command `{other}`\n\n{USAGE}")), + } +} + +fn value(flag: &str, it: &mut std::vec::IntoIter) -> Result { + it.next().ok_or_else(|| format!("{flag} needs a value")) +} + +fn parse_serve(args: Vec) -> Result { + let mut tier: Option = None; + let mut journal = None; + let mut config = None; + let mut display = None; + let mut it = args.into_iter(); + while let Some(flag) = it.next() { + match flag.as_str() { + "-h" | "--help" => return Ok(Command::Print(USAGE.to_string())), + "--tier" | "-p" | "--permission-mode" => { + let word = value(&flag, &mut it)?; + let named = if flag == "--tier" { + Tier::parse(&word) + .ok_or_else(|| format!("--tier takes `observe` or `act`, not `{word}`"))? + } else { + Tier::from_mode_word(&word).ok_or_else(|| { + format!( + "{flag} does not know the mode `{word}` \ + (read-only, workspace-write, danger-full-access, allow or prompt)" + ) + })? + }; + if tier.is_some_and(|already| already != named) { + return Err("--tier and -p name different tiers".to_string()); + } + tier = Some(named); + } + "--journal" => journal = Some(PathBuf::from(value(&flag, &mut it)?)), + "--config" => config = Some(PathBuf::from(value(&flag, &mut it)?)), + "--display" => display = Some(value(&flag, &mut it)?), + other => return Err(format!("unknown option `{other}` for serve\n\n{USAGE}")), + } + } + Ok(Command::Serve(ServeArgs { + tier: tier.unwrap_or(Tier::Act), + journal, + config, + display, + })) +} + +fn parse_stop(args: Vec) -> Result { + let mut journal = None; + let mut workspace = None; + let mut it = args.into_iter(); + while let Some(flag) = it.next() { + match flag.as_str() { + "-h" | "--help" => return Ok(Command::Print(USAGE.to_string())), + "--journal" => journal = Some(PathBuf::from(value(&flag, &mut it)?)), + "--workspace" => workspace = Some(PathBuf::from(value(&flag, &mut it)?)), + other => return Err(format!("unknown option `{other}` for stop\n\n{USAGE}")), + } + } + if journal.is_some() && workspace.is_some() { + return Err("stop takes --journal or --workspace, not both".to_string()); + } + Ok(Command::Stop(StopArgs { journal, workspace })) +} + +/// Everything [`serve`] needs, already resolved. +pub struct ServeOptions { + /// What the agent may do. + pub tier: Tier, + /// Where to append what the desktop did, and the stop file beside it. + pub journal: Option, + /// The limits in force once resolved; refused if a safety limit is loosened. + pub limits: DesktopLimits, + /// Linux: the display to drive (see [`crate::linux::attach`]). Unused + /// elsewhere. + pub display: Option, + /// The operator's commands around every call, if any. + pub hooks: Option>, + /// What the startup lines on stderr call this server (`incu`, or + /// `incode-desktop` for incode's wrapper). + pub name: &'static str, +} + +impl ServeOptions { + /// What `incu serve` runs with: the flags, over the config file they name + /// (or the default one). + /// + /// # Errors + /// + /// The config file cannot be read or is malformed; the desktop will not + /// start without the guard the operator wrote. + pub fn from_args(args: ServeArgs) -> Result { + let config = match &args.config { + Some(path) => Config::load(path)?, + None => Config::load_default()?, + }; + let Config { + limits, + display, + hooks, + } = config; + Ok(Self { + tier: args.tier, + journal: args.journal, + limits, + display: args.display.or(display), + hooks: shell_hooks(hooks), + name: "incu", + }) + } +} + +/// [`ShellHooks`] for `config`, or none when it has nothing to run. +fn shell_hooks(config: HookConfig) -> Option> { + (!config.is_empty()).then(|| Box::new(ShellHooks::new(config)) as Box) +} + +/// Run the MCP server on stdio until the client goes away. +/// +/// Synchronous on this thread, deliberately: the protocol is a line-oriented +/// pipe and the input thread is its own OS thread, so an async runtime would add +/// a scheduler to a program that has nothing to schedule. +/// +/// The steps, in the order they have always run: install the limits (refusing +/// one that loosens a safety limit), on Linux attach the display FIRST while +/// this process is still one thread (attaching sets `DISPLAY`, which the input +/// thread reads when it connects, and the display is held until the server +/// returns so a private Xvfb lives exactly as long as the desktop it backs), +/// start the input thread, build the [`Server`], then [`crate::mcp::run_stdio`]. +/// +/// # Errors +/// +/// The limits are refused, the display cannot be attached, the input thread +/// cannot start, or reading stdin fails. The text is what the operator is shown. +pub fn serve(options: ServeOptions) -> Result<(), String> { + let ServeOptions { + tier, + journal, + limits, + display, + hooks, + name, + } = options; + crate::limits::set( + limits + .resolve() + .map_err(|e| format!("the desktop will not start: {e}"))?, + ); + #[cfg(target_os = "linux")] + let _display = { + let attached = crate::linux::attach(display.as_deref()).map_err(|e| format!("{e}"))?; + eprintln!( + "{name} on display {}{}", + attached.name(), + if attached.is_private() { + " (a private Xvfb, stopped when this server ends)" + } else { + "" + } + ); + attached + }; + // Only Linux has a display to name; the others drive the one they are in. + #[cfg(not(target_os = "linux"))] + let _ = display; + let input = crate::thread::InputThread::start() + .map_err(|e| format!("could not start desktop input: {e}"))?; + let mut server = Server::new(input).with_tier(tier); + if let Some(hooks) = hooks { + let before = hooks.pre_tool_count(); + if before > 0 { + eprintln!("{name}: {before} pre-tool hook(s) will run before every action"); + } + server = server.with_hook_runner(hooks); + } + if let Some(path) = journal { + eprintln!("{name} journalling to {}", path.display()); + server = server.with_journal(path); + } + // Named on stderr so an operator who asked for `read-only` can see that it + // arrived. A capability restriction nobody can observe is one nobody trusts. + eprintln!("{name} MCP server ready on stdio ({})", tier.label()); + crate::mcp::run_stdio(server).map_err(|e| e.to_string()) +} + +/// Ask the server whose stop file is `path` to stop, and say so on stdout. +/// +/// REPORTED, never swallowed: a stop request that silently failed is worse than +/// no stop button at all, because the operator walks away believing the desktop +/// is halted. +/// +/// # Errors +/// +/// The stop file could not be written. +pub fn stop(path: &Path) -> Result<(), String> { + crate::safety::request_stop(path) + .map_err(|e| format!("could not request a stop at {}: {e}", path.display()))?; + println!("desktop stop requested: {}", path.display()); + println!( + "It takes effect before the desktop's next action, and is permanent \ + for that session. Delete the file to allow a NEW session to act." + ); + Ok(()) +} + +/// Run a parsed `incu` command. The `incu` binary's whole body. +/// +/// # Errors +/// +/// Whatever [`serve`] or [`stop`] refuses with. +pub fn run(command: Command) -> Result<(), String> { + match command { + Command::Print(text) => { + println!("{text}"); + Ok(()) + } + Command::Serve(args) => serve(ServeOptions::from_args(args)?), + Command::Stop(args) => { + let path = match (args.journal, args.workspace) { + (Some(journal), _) => crate::safety::stop_file_beside(&journal), + (None, Some(workspace)) => crate::safety::stop_path_in(&workspace), + (None, None) => crate::safety::stop_path_in( + &std::env::current_dir().map_err(|e| format!("no current directory: {e}"))?, + ), + }; + stop(&path) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn argv(words: &[&str]) -> Vec { + words.iter().map(|w| (*w).to_string()).collect() + } + + fn serve_args(words: &[&str]) -> ServeArgs { + match parse(argv(words)).expect("parses") { + Command::Serve(args) => args, + other => panic!("expected serve, got {other:?}"), + } + } + + #[test] + fn serve_is_the_default_command_and_act_the_default_tier() { + assert_eq!(serve_args(&[]).tier, Tier::Act); + assert_eq!(serve_args(&["serve"]).tier, Tier::Act); + // Bare flags start the server too. + assert_eq!(serve_args(&["--tier", "observe"]).tier, Tier::Observe); + } + + /// `-p` is the argv incode has always passed to the child it launches. + #[test] + fn dash_p_is_an_alias_of_tier_and_takes_incodes_mode_words() { + assert_eq!(serve_args(&["-p", "read-only"]).tier, Tier::Observe); + assert_eq!(serve_args(&["-p", "workspace-write"]).tier, Tier::Act); + assert_eq!(serve_args(&["serve", "-p", "prompt"]).tier, Tier::Deny); + assert_eq!( + serve_args(&["--permission-mode", "danger-full-access"]).tier, + Tier::Act + ); + // The exact argv incode's client config emits, minus the flag that + // selects incode's own server mode. + let args = serve_args(&["--journal", "/w/.incode/desktop.jsonl", "-p", "read-only"]); + assert_eq!(args.tier, Tier::Observe); + assert_eq!( + args.journal.as_deref(), + Some(Path::new("/w/.incode/desktop.jsonl")) + ); + } + + #[test] + fn a_typo_in_a_security_flag_is_refused_not_guessed() { + assert!(parse(argv(&["-p", "wrokspace-write"])).is_err()); + assert!(parse(argv(&["--tier", "read-only"])).is_err()); + assert!(parse(argv(&["--tier"])).is_err()); + } + + #[test] + fn two_tiers_that_disagree_are_refused() { + assert!(parse(argv(&["--tier", "observe", "-p", "workspace-write"])).is_err()); + assert!(parse(argv(&["--tier", "act", "-p", "workspace-write"])).is_ok()); + } + + #[test] + fn stop_takes_a_journal_or_a_workspace() { + assert!(matches!( + parse(argv(&["stop", "--journal", "j.jsonl"])), + Ok(Command::Stop(_)) + )); + assert!(parse(argv(&["stop", "--journal", "a", "--workspace", "b"])).is_err()); + } + + #[test] + fn unknown_commands_and_options_are_refused() { + assert!(parse(argv(&["frobnicate"])).is_err()); + assert!(parse(argv(&["serve", "--frobnicate"])).is_err()); + } + + #[test] + fn help_and_version_print_instead_of_serving() { + assert_eq!( + parse(argv(&["--help"])), + Ok(Command::Print(USAGE.to_string())) + ); + assert!(matches!( + parse(argv(&["--version"])), + Ok(Command::Print(v)) if v.starts_with("incu ") + )); + } + + /// The usage must name every flag the parser takes, or an operator cannot + /// find the one that matters. + #[test] + fn the_usage_names_every_flag() { + for flag in [ + "--tier", + "-p", + "--permission-mode", + "--journal", + "--config", + "--display", + "--workspace", + ] { + assert!(USAGE.contains(flag), "{flag} is not in the usage"); + } + } +} diff --git a/crates/desktop/src/config.rs b/crates/desktop/src/config.rs new file mode 100644 index 0000000..0371b55 --- /dev/null +++ b/crates/desktop/src/config.rs @@ -0,0 +1,180 @@ +//! The settings the crate owns: limits, the Linux display and the operator's +//! hooks. +//! +//! # One file for either binary +//! +//! incode keeps these three under `desktop_limits`, `desktop_display` and +//! `desktop_hooks` (also `hooks`) in `~/.incode/admin.json`. [`Config`] reads +//! those names as aliases of its own, and ignores every other key, so +//! `incu serve --config ~/.incode/admin.json` reads incode's file unchanged and +//! an operator's guard cannot end up written in one place and missing in the +//! other. There is deliberately no `deny_unknown_fields` here for that reason. +//! (`desktop_limits` itself keeps it, as ever: a misspelt limit is refused, not +//! ignored.) +//! +//! # Wired to +//! +//! - **Called by** [`crate::cli`] (`incu serve --config`), which hands the +//! limits to [`crate::limits::set`], the display to +//! [`crate::linux::attach`] and the hooks to [`crate::hooks::ShellHooks`]. +//! - incode's `--desktop-mcp` does not read this: it already holds the same +//! three values in its `AdminConfig` and passes them to +//! [`crate::cli::serve`] itself. + +use std::path::{Path, PathBuf}; + +use serde::{Deserialize, Serialize}; + +use crate::hooks::HookConfig; +use crate::limits::DesktopLimits; + +/// The environment variable that names the config file when `--config` is not +/// given. +pub const CONFIG_ENV: &str = "INCU_CONFIG"; + +/// What `incu` is configured with. Every field is optional: an absent one is +/// the default, and a file of nothing behaves as no file. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct Config { + /// Every bound: rate cap, heartbeat, tree size, journal size, timeouts. The + /// two safety limits may only be made stricter. See [`crate::limits`]. + #[serde(default, alias = "desktop_limits")] + pub limits: DesktopLimits, + /// Linux: the X display to drive. `":N"` attaches to one already running; + /// `"xvfb"` (or `"xvfb:WIDTHxHEIGHT"`) starts a private one for the server's + /// life. Unset is a refusal, never `$DISPLAY`. See [`crate::linux::attach`]. + #[serde(default, alias = "desktop_display")] + pub display: Option, + /// The operator's commands around every call. See [`crate::hooks`]. + #[serde(default, alias = "desktop_hooks", alias = "hooks")] + pub hooks: HookConfig, +} + +impl Config { + /// Where the file lives when `--config` is not given: `$INCU_CONFIG`, else + /// `incord-desktop/config.json` under the platform's config folder + /// (`%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` elsewhere). + /// `None` when none of those can be found. + #[must_use] + pub fn default_path() -> Option { + if let Some(path) = std::env::var_os(CONFIG_ENV).filter(|p| !p.is_empty()) { + return Some(PathBuf::from(path)); + } + let base = if cfg!(windows) { + std::env::var_os("APPDATA").map(PathBuf::from) + } else { + std::env::var_os("XDG_CONFIG_HOME") + .filter(|p| !p.is_empty()) + .map(PathBuf::from) + .or_else(|| { + std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".config")) + }) + }; + base.map(|dir| dir.join("incord-desktop").join("config.json")) + } + + /// Read the file at `path`. + /// + /// # Errors + /// + /// The file cannot be read or is not valid. A malformed file is REFUSED, not + /// read as empty: empty would start the desktop with no hooks and default + /// limits, a guard the operator wrote silently gone. + pub fn load(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|e| format!("cannot read {}: {e}", path.display()))?; + // A byte-order mark is what some Windows editors put in front of a file + // a person wrote by hand. + serde_json::from_str(text.trim_start_matches('\u{feff}')) + .map_err(|e| format!("{} is not a valid config: {e}", path.display())) + } + + /// The config in force when no `--config` was given: the file at + /// [`Config::default_path`] if there is one, else the defaults. A file that + /// exists but is malformed is still refused. + /// + /// # Errors + /// + /// The file exists and cannot be read or is not valid. + pub fn load_default() -> Result { + match Self::default_path() { + Some(path) if path.is_file() => Self::load(&path), + _ => Ok(Self::default()), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// **The point of the aliases**: incode's own file, with all its other keys, + /// is a valid config here and means the same. + #[test] + fn an_incode_admin_file_is_read_as_it_stands() { + let admin = r#"{ + "model": "whatever", + "notify": "bell", + "desktop_limits": {"max_actions_per_minute": 30, "blocked_apps": ["vault"]}, + "desktop_display": "xvfb:1280x800", + "desktop_hooks": { + "pre_tool_use": ["check.sh", {"command": "ask.sh", "matcher": "type_text"}], + "post_tool_use": ["log.sh"], + "stop": ["not-a-desktop-event.sh"] + } + }"#; + let config: Config = serde_json::from_str(admin).expect("incode's file"); + assert_eq!(config.limits.max_actions_per_minute, Some(30)); + assert_eq!(config.limits.blocked_apps, ["vault"]); + assert_eq!(config.display.as_deref(), Some("xvfb:1280x800")); + assert_eq!(config.hooks.pre_tool_use.len(), 2); + assert_eq!(config.hooks.post_tool_use.len(), 1); + } + + /// `hooks` is the same key as `desktop_hooks`, as incode's `admin.json` + /// accepts it. + #[test] + fn hooks_is_accepted_for_desktop_hooks() { + let config: Config = + serde_json::from_str(r#"{"hooks": {"pre_tool_use": ["a"]}}"#).expect("config"); + assert_eq!(config.hooks.pre_tool_use.len(), 1); + } + + #[test] + fn the_crates_own_names_work_too() { + let config: Config = + serde_json::from_str(r#"{"limits": {"tree_depth": 4}, "display": ":99", "hooks": {}}"#) + .expect("config"); + assert_eq!(config.limits.tree_depth, Some(4)); + assert_eq!(config.display.as_deref(), Some(":99")); + } + + #[test] + fn nothing_set_is_the_default() { + let config: Config = serde_json::from_str("{}").expect("config"); + assert_eq!(config, Config::default()); + assert!(config.hooks.is_empty()); + assert!(config.limits.is_empty()); + } + + /// A misspelt limit is refused, not ignored: a stricter cap the operator + /// wrote must not silently stay at its default. + #[test] + fn a_misspelt_limit_is_refused() { + let bad = serde_json::from_str::(r#"{"limits": {"max_action_per_minute": 1}}"#); + assert!(bad.is_err()); + } + + #[test] + fn a_malformed_file_is_refused_not_read_as_empty() { + let dir = std::env::temp_dir().join(format!("incu-config-{}", std::process::id())); + std::fs::create_dir_all(&dir).expect("temp dir"); + let path = dir.join("config.json"); + std::fs::write(&path, "{not json").expect("write"); + let why = Config::load(&path).expect_err("malformed"); + assert!(why.contains("not a valid config"), "{why}"); + let missing = Config::load(&dir.join("absent.json")).expect_err("missing"); + assert!(missing.contains("cannot read"), "{missing}"); + let _ = std::fs::remove_dir_all(&dir); + } +} diff --git a/src/desktop/coords.rs b/crates/desktop/src/coords.rs similarity index 100% rename from src/desktop/coords.rs rename to crates/desktop/src/coords.rs diff --git a/src/desktop/dpi.rs b/crates/desktop/src/dpi.rs similarity index 100% rename from src/desktop/dpi.rs rename to crates/desktop/src/dpi.rs diff --git a/crates/desktop/src/hooks.rs b/crates/desktop/src/hooks.rs new file mode 100644 index 0000000..f89ad64 --- /dev/null +++ b/crates/desktop/src/hooks.rs @@ -0,0 +1,619 @@ +//! The operator's own commands, run around every desktop tool call. +//! +//! # Where this sits +//! +//! The desktop server is the one place a click or a keystroke passes through, +//! so it is where an operator's veto is worth the most: a click reaches a +//! machine they are signed into and no checkpoint undoes it. +//! [`crate::mcp::Server`] asks a [`Hooks`] before the tool runs +//! ([`Hooks::run_pre_tool_use`]) and tells it after +//! ([`Hooks::run_post_tool_use`]). +//! +//! Two things implement [`Hooks`]: +//! +//! - [`ShellHooks`], here, for the `incu` binary and any embedder with no hook +//! engine of its own. Built from a [`HookConfig`] read out of the +//! configuration file ([`crate::config::Config`]). +//! - incode's own `hooks::HookRunner`, through an adapter in `main.rs`, so +//! `incode --desktop-mcp` keeps running the operator's commands exactly as +//! it did before the desktop became its own crate (its process-tree +//! containment, its POSIX-shell choice on Windows). This module does not +//! replace that engine; it is what the desktop needs of one. +//! +//! # The contract with the operator's command +//! +//! It is the contract incode's hooks documented, kept identical so an +//! operator's existing scripts work under either binary: +//! +//! - **stdin** carries the event as one JSON object, then is closed: +//! `hook_event_name` (`PreToolUse` / `PostToolUse`), `tool_name`, +//! `tool_input`, `session_id` and `cwd`, and after the tool `tool_response` +//! and `is_error`. It is a pipe, never an inherited stdin: the server's own +//! stdin is the MCP protocol. +//! - `HOOK_TOOL_NAME` and `HOOK_TOOL_INPUT` are also set in its environment +//! (the input cut at [`MAX_ENV_INPUT_BYTES`]; the whole of it is on stdin). +//! - **Exit code 2 denies the call**, before it runs; stderr is the reason the +//! agent is given (stdout when stderr is empty). Any other code allows it. A +//! post-tool command cannot deny anything. +//! - Anything on stdout is passed back as a message. +//! - It is killed with everything it started at [`HOOK_TIMEOUT`]; a command +//! that could not run or ran past it allows the call, with a message saying +//! so. +//! - A command with a `matcher` runs only for the tools it names: a regular +//! expression matched against the WHOLE tool name; none, `""` or `*` is every +//! tool. A matcher that is not a regular expression runs the command for no +//! tool, and says so. +//! +//! # A hook is shown the REAL input +//! +//! [`crate::mcp::Server`] describes a typed password to the journal as "8 +//! characters". A hook is deliberately outside that boundary: it is a command +//! the operator wrote, running on the operator's machine, and inspecting what +//! is about to be typed is the entire reason a pre-tool hook exists. A hook that +//! cannot see the input cannot refuse on it. + +use std::io::{Read, Write}; +use std::process::{Child, Command, Stdio}; +use std::sync::mpsc; +use std::time::{Duration, Instant}; + +use serde::{Deserialize, Serialize}; +use serde_json::{json, Value}; + +/// The most of a call's input put in `HOOK_TOOL_INPUT`, in bytes. An +/// environment block is bounded (32 767 characters on Windows) and `type_text` +/// can carry a great deal; the full input is always on stdin. +pub const MAX_ENV_INPUT_BYTES: usize = 8 * 1024; + +/// How long a hook may take before it is killed and treated as allowing. +/// +/// A hook runs between the agent asking and the desktop moving, so the whole +/// session waits on it. Without a bound, one command that waits on input hangs +/// the desktop with no way to tell from the outside whether the agent or the +/// hook is stuck. +/// +/// Ten seconds is long for a guard command and short enough that a hung one is +/// noticed rather than lived with. +pub const HOOK_TIMEOUT: Duration = Duration::from_secs(10); + +/// How long to wait for a finished hook's output pipes to close. A command that +/// started a background process which kept them open must not hold the call. +const PIPE_GRACE: Duration = Duration::from_secs(2); + +/// What a hook run comes to. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct HookOutcome { + denied: bool, + messages: Vec, +} + +impl HookOutcome { + /// An outcome that lets the call go ahead, with whatever the commands said. + #[must_use] + pub fn allow(messages: Vec) -> Self { + Self { + denied: false, + messages, + } + } + + /// An outcome that refuses the call, with the reason(s) to give the agent. + #[must_use] + pub fn deny(messages: Vec) -> Self { + Self { + denied: true, + messages, + } + } + + /// Whether a pre-tool command refused the call (exit code 2). + #[must_use] + pub fn is_denied(&self) -> bool { + self.denied + } + + /// What the commands said: the refusal's reason, or their stdout. + #[must_use] + pub fn messages(&self) -> &[String] { + &self.messages + } +} + +/// What the desktop server needs of an operator's hook engine. +/// +/// Held by [`crate::mcp::Server`] (`with_hook_runner`, or `with_hooks` for the +/// built-in [`ShellHooks`]) and called from its gates in `mcp/gate.rs` +/// (`Server::hook_veto`, `Server::tell_post_hooks`). `Send` because the server +/// is built on one thread and may be handed to another. +pub trait Hooks: Send { + /// How many pre-tool commands there are, for the startup line that tells the + /// operator their guard is armed ([`crate::cli::serve`]). The default, + /// nothing, only means the line is not printed. + fn pre_tool_count(&self) -> usize { + 0 + } + + /// The pre-tool commands, for a caller holding the input as text. A denied + /// outcome refuses the call before it reaches the desktop. + fn run_pre_tool_use(&self, tool_name: &str, tool_input: &str) -> HookOutcome; + + /// The post-tool commands, for a call that ran and returned `tool_output`. + /// They cannot deny: the action already happened. + fn run_post_tool_use( + &self, + tool_name: &str, + tool_input: &str, + tool_output: &str, + is_error: bool, + ) -> HookOutcome; +} + +/// One hook command: a command line, or `{"command", "matcher"}`. +/// +/// Written the way incode's `admin.json` writes it, so one file serves both +/// binaries ([`crate::config::Config`]). +#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(from = "RawHookCommand", into = "RawHookCommand")] +pub struct HookCommand { + /// The command line, run through the platform shell (`cmd /C` on Windows, + /// `sh -lc` elsewhere). + pub command: String, + /// The tool names the command runs for; see the module header. + pub matcher: Option, +} + +/// How a [`HookCommand`] is written. +#[derive(Serialize, Deserialize)] +#[serde(untagged)] +enum RawHookCommand { + Plain(String), + Matched { + command: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + matcher: Option, + }, +} + +impl From for HookCommand { + fn from(raw: RawHookCommand) -> Self { + match raw { + RawHookCommand::Plain(command) => command.into(), + RawHookCommand::Matched { command, matcher } => Self { command, matcher }, + } + } +} + +impl From for RawHookCommand { + fn from(hook: HookCommand) -> Self { + match hook.matcher { + None => Self::Plain(hook.command), + matcher => Self::Matched { + command: hook.command, + matcher, + }, + } + } +} + +impl From for HookCommand { + fn from(command: String) -> Self { + Self { + command, + matcher: None, + } + } +} + +impl From<&str> for HookCommand { + fn from(command: &str) -> Self { + command.to_string().into() + } +} + +impl std::fmt::Display for HookCommand { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.command) + } +} + +impl HookCommand { + /// Whether this command runs for the tool `tool_name`, and why not when its + /// matcher cannot be read. + /// + /// # Errors + /// + /// The matcher is not a regular expression. + pub fn matches(&self, tool_name: &str) -> Result { + match self.matcher.as_deref().map(str::trim) { + None | Some("" | "*") => Ok(true), + Some(pattern) => regex::Regex::new(&format!("^(?:{pattern})$")) + .map(|re| re.is_match(tool_name)) + .map_err(|e| format!("its matcher `{pattern}` is not a regular expression: {e}")), + } + } +} + +/// The operator's pre- and post-tool commands. +/// +/// Only the two events the desktop has. `admin.json` carries seven more for +/// incode's own sessions; they are ignored here (no `deny_unknown_fields`), so +/// the same file can be read by either binary. +#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] +pub struct HookConfig { + /// Commands run BEFORE the tool. Exit code 2 refuses the call. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub pre_tool_use: Vec, + /// Commands run AFTER the tool, whatever it returned. These cannot refuse + /// anything: a deny here would report a refusal for something that was + /// done. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub post_tool_use: Vec, +} + +impl HookConfig { + /// Whether there is anything to run at all. + /// + /// Checked once at startup ([`crate::mcp::Server::with_hooks`]) so the + /// ordinary case, no hooks configured, costs nothing per call. + #[must_use] + pub fn is_empty(&self) -> bool { + self.pre_tool_use.is_empty() && self.post_tool_use.is_empty() + } +} + +/// [`Hooks`] that runs the operator's commands itself, from a [`HookConfig`]. +/// +/// What `incu` uses. It spawns each command with a piped stdin that is written +/// and closed, bounds the wait at [`HOOK_TIMEOUT`] and kills the command's +/// whole process tree when the bound passes. +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ShellHooks { + config: HookConfig, +} + +impl ShellHooks { + /// Run `config`'s commands. + #[must_use] + pub fn new(config: HookConfig) -> Self { + Self { config } + } + + /// The commands of one event that take this tool, then each one run in + /// turn. A pre-tool command exiting 2 stops the rest. + fn run_commands( + &self, + commands: &[HookCommand], + tool_name: &str, + tool_input: &str, + after: Option<(&str, bool)>, + ) -> HookOutcome { + let mut messages = Vec::new(); + // Only the commands whose matcher takes this tool; one whose matcher + // cannot be read runs for none, and says so. + let commands: Vec<&HookCommand> = commands + .iter() + .filter(|hook| match hook.matches(tool_name) { + Ok(runs) => runs, + Err(why) => { + messages.push(format!("Hook `{hook}` was not run: {why}")); + false + } + }) + .collect(); + if commands.is_empty() { + return HookOutcome::allow(messages); + } + let input = parsed(tool_input); + let mut event = json!({ + "hook_event_name": if after.is_some() { "PostToolUse" } else { "PreToolUse" }, + "tool_name": tool_name, + "tool_input": input, + "session_id": "", + "cwd": Value::Null, + }); + if let Some((output, is_error)) = after { + event["tool_response"] = json!(output); + event["is_error"] = json!(is_error); + } + let mut payload = event.to_string().into_bytes(); + payload.push(b'\n'); + + let env_input = match &input { + Value::String(text) => text.clone(), + other => other.to_string(), + }; + let env = [ + ("HOOK_TOOL_NAME", tool_name.to_string()), + ( + "HOOK_TOOL_INPUT", + head_bytes(&env_input, MAX_ENV_INPUT_BYTES).to_string(), + ), + ]; + for command in commands { + match run_shell_command(command, &env, &payload) { + Ok((code, stdout, stderr)) => { + if code == 2 && after.is_none() { + // Exit 2 denies; stderr is the reason. + let reason = if stderr.is_empty() { stdout } else { stderr }; + messages.push(if reason.is_empty() { + format!("the operator's hook `{command}` refused this call") + } else { + reason + }); + return HookOutcome::deny(messages); + } + if !stdout.is_empty() { + messages.push(stdout); + } + } + Err(e) => messages.push(format!("Hook `{command}` failed: {e}")), + } + } + HookOutcome::allow(messages) + } +} + +impl Hooks for ShellHooks { + fn pre_tool_count(&self) -> usize { + self.config.pre_tool_use.len() + } + + fn run_pre_tool_use(&self, tool_name: &str, tool_input: &str) -> HookOutcome { + self.run_commands(&self.config.pre_tool_use, tool_name, tool_input, None) + } + + fn run_post_tool_use( + &self, + tool_name: &str, + tool_input: &str, + tool_output: &str, + is_error: bool, + ) -> HookOutcome { + // A post-tool command cannot deny: the action already happened. + let ran = self.run_commands( + &self.config.post_tool_use, + tool_name, + tool_input, + Some((tool_output, is_error)), + ); + HookOutcome::allow(ran.messages) + } +} + +/// A call's input from its text: the JSON it holds, or the text itself. +fn parsed(tool_input: &str) -> Value { + serde_json::from_str(tool_input).unwrap_or_else(|_| json!(tool_input)) +} + +/// The longest prefix of `s` within `max_bytes`, not splitting a character. +fn head_bytes(s: &str, max_bytes: usize) -> &str { + if s.len() <= max_bytes { + return s; + } + let mut end = max_bytes; + while end > 0 && !s.is_char_boundary(end) { + end -= 1; + } + &s[..end] +} + +/// One operator command, run through the shell with `env` set and the event on +/// its stdin: its exit code, stdout and stderr, each trimmed. +/// +/// # Errors +/// +/// The command could not be started, or ran past [`HOOK_TIMEOUT`] (and was +/// killed with everything it had started). +fn run_shell_command( + hook: &HookCommand, + env: &[(&str, String)], + payload: &[u8], +) -> std::io::Result<(i32, String, String)> { + // Verbatim on Windows, as a shell would be given it: `Command::arg` would + // escape a `"` the operator wrote as `\"`, which `cmd /C` does not read + // that way. + #[cfg(windows)] + let mut child = { + use std::os::windows::process::CommandExt; + let mut c = Command::new("cmd"); + c.arg("/C").raw_arg(&hook.command); + c + }; + #[cfg(not(windows))] + let mut child = { + use std::os::unix::process::CommandExt; + let mut c = Command::new("sh"); + // Its own process group, so a timeout can take the whole tree. + c.arg("-lc").arg(&hook.command).process_group(0); + c + }; + for (name, value) in env { + child.env(name, value); + } + child + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + let mut child = child.spawn()?; + + // Written on a thread of its own and CLOSED when that thread ends, so the + // command sees end-of-input. Not written inline: a large event and a + // command that prints before it reads would each wait on the other. + if let Some(mut stdin) = child.stdin.take() { + let payload = payload.to_vec(); + std::thread::spawn(move || { + let _ = stdin.write_all(&payload); + }); + } + let stdout = collect(child.stdout.take()); + let stderr = collect(child.stderr.take()); + + let deadline = Instant::now() + HOOK_TIMEOUT; + let status = loop { + if let Some(status) = child.try_wait()? { + break status; + } + if Instant::now() >= deadline { + kill_tree(&mut child); + return Err(std::io::Error::other(format!( + "it ran past {} seconds and was stopped", + HOOK_TIMEOUT.as_secs() + ))); + } + std::thread::sleep(Duration::from_millis(10)); + }; + + let said = |rx: mpsc::Receiver>| { + let bytes = rx.recv_timeout(PIPE_GRACE).unwrap_or_default(); + String::from_utf8_lossy(&bytes).trim().to_string() + }; + Ok((status.code().unwrap_or(-1), said(stdout), said(stderr))) +} + +/// Read `pipe` to its end on a thread of its own, delivering what it held. +fn collect(pipe: Option) -> mpsc::Receiver> { + let (tx, rx) = mpsc::channel(); + std::thread::spawn(move || { + let mut bytes = Vec::new(); + if let Some(mut pipe) = pipe { + let _ = pipe.read_to_end(&mut bytes); + } + let _ = tx.send(bytes); + }); + rx +} + +/// Stop `child` and everything it started. +/// +/// Unix: the child leads its own process group, so `killpg` reaches every +/// descendant. Windows: `taskkill /T` walks the tree from the child's pid. +/// Either way the child itself is killed and reaped last, so a failure to reach +/// the tree still stops the command. +fn kill_tree(child: &mut Child) { + #[cfg(unix)] + { + if let Ok(group) = i32::try_from(child.id()) { + // SAFETY: `killpg` takes plain integers and has no memory effects. + unsafe { + libc::killpg(group, libc::SIGKILL); + } + } + } + #[cfg(windows)] + { + let _ = Command::new("taskkill") + .args(["/T", "/F", "/PID", &child.id().to_string()]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status(); + } + let _ = child.kill(); + let _ = child.wait(); +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A command that prints `said` and exits with `code`. + fn says(said: &str, code: i32) -> HookCommand { + if cfg!(windows) { + format!("cmd /C echo {said}& exit {code}").into() + } else { + format!("echo {said}; exit {code}").into() + } + } + + fn shell(pre: Vec) -> ShellHooks { + ShellHooks::new(HookConfig { + pre_tool_use: pre, + post_tool_use: Vec::new(), + }) + } + + #[test] + fn a_pre_hook_exiting_two_denies_and_its_output_is_the_reason() { + let ran = shell(vec![says("no", 2)]).run_pre_tool_use("click", "{}"); + assert!(ran.is_denied(), "{ran:?}"); + assert_eq!(ran.messages(), ["no"]); + } + + #[test] + fn any_other_exit_allows_and_its_stdout_is_a_message() { + let ran = shell(vec![says("fyi", 1)]).run_pre_tool_use("click", "{}"); + assert!(!ran.is_denied(), "{ran:?}"); + assert_eq!(ran.messages(), ["fyi"]); + } + + #[test] + fn a_post_hook_cannot_deny() { + let hooks = ShellHooks::new(HookConfig { + pre_tool_use: Vec::new(), + post_tool_use: vec![says("done", 2)], + }); + let ran = hooks.run_post_tool_use("click", "{}", "ok", false); + assert!(!ran.is_denied(), "{ran:?}"); + } + + #[test] + fn a_hook_is_told_the_tool_in_its_environment() { + let echo = if cfg!(windows) { + "cmd /C echo %HOOK_TOOL_NAME%" + } else { + "echo $HOOK_TOOL_NAME" + }; + let ran = shell(vec![echo.into()]).run_pre_tool_use("move_mouse", "{}"); + assert_eq!(ran.messages(), ["move_mouse"]); + } + + #[test] + fn a_matcher_runs_the_command_only_for_the_tools_it_names() { + let only_type = HookCommand { + command: says("blocked", 2).command, + matcher: Some("type_text|paste_text".to_string()), + }; + let hooks = shell(vec![only_type]); + assert!(!hooks.run_pre_tool_use("click", "{}").is_denied()); + assert!(hooks.run_pre_tool_use("paste_text", "{}").is_denied()); + // Matched against the whole name, not a part of it. + assert!(!hooks.run_pre_tool_use("type_text_x", "{}").is_denied()); + } + + #[test] + fn a_matcher_that_is_not_a_regex_runs_nothing_and_says_so() { + let broken = HookCommand { + command: says("blocked", 2).command, + matcher: Some("(".to_string()), + }; + let ran = shell(vec![broken]).run_pre_tool_use("click", "{}"); + assert!(!ran.is_denied(), "{ran:?}"); + assert!(ran.messages()[0].contains("not a regular expression")); + } + + #[test] + fn a_command_that_cannot_run_allows_with_a_message() { + let ran = shell(vec!["exit 0".into()]).run_pre_tool_use("click", "{}"); + assert!(!ran.is_denied(), "{ran:?}"); + } + + #[test] + fn a_hook_is_written_as_a_line_or_with_its_matcher() { + let config: HookConfig = serde_json::from_str( + r#"{"pre_tool_use": ["one", {"command": "two", "matcher": "key"}], + "user_prompt_submit": ["ignored here"]}"#, + ) + .expect("a config with an event the desktop does not have"); + assert_eq!(config.pre_tool_use[0], "one".into()); + assert_eq!(config.pre_tool_use[1].matcher.as_deref(), Some("key")); + assert!(config.post_tool_use.is_empty()); + } + + #[test] + fn the_environment_copy_of_the_input_is_cut_on_a_character_boundary() { + // "中" is three bytes: a two-byte budget keeps none of it. + assert_eq!(head_bytes("中文", 2), ""); + assert_eq!(head_bytes("中文", 3), "中"); + assert_eq!(head_bytes("short", 100), "short"); + } +} diff --git a/src/desktop/journal.rs b/crates/desktop/src/journal.rs similarity index 97% rename from src/desktop/journal.rs rename to crates/desktop/src/journal.rs index 9c868d2..13a5e8e 100644 --- a/src/desktop/journal.rs +++ b/crates/desktop/src/journal.rs @@ -40,7 +40,7 @@ use serde::{Deserialize, Serialize}; /// How much journal to keep before the oldest records are dropped. /// /// The input thread caps the agent at 120 actions per minute by default -/// ([`crate::desktop::limits`]), so an agent driving flat out writes on the +/// ([`crate::limits`]), so an agent driving flat out writes on the /// order of 30 KB a minute. A quarter of a megabyte is therefore several /// minutes of the most recent activity, which is what an operator asking /// "what is it doing right now" actually wants, and it bounds the cost of the @@ -50,7 +50,7 @@ pub const MAX_BYTES: u64 = super::limits::DEFAULT_JOURNAL_MAX_BYTES; /// Where the journal lives inside a workspace. /// -/// In `.incode/`, with the transcripts (`crate::transcript::DIR`), rather than +/// In `.incode/`, with incode's transcripts, rather than /// in a new top-level directory: it is the same kind of artefact — a record of /// what an agent did — and `.incode/` is already the harness's own space. pub const FILE: &str = ".incode/desktop.jsonl"; @@ -157,7 +157,11 @@ impl Journal { self.trim()?; if let Some(parent) = self.path.parent() { - crate::folders::create_dir_all(parent)?; + // Plain `create_dir_all`: the project's `.incode/.gitignore` that + // incode writes beside a fresh `.incode/` is incode's concern, and + // its `--desktop-mcp` wrapper creates the folder that way before + // this server starts. See `crate::cli`. + std::fs::create_dir_all(parent)?; } let mut file = std::fs::OpenOptions::new() .create(true) diff --git a/src/desktop/mod.rs b/crates/desktop/src/lib.rs similarity index 95% rename from src/desktop/mod.rs rename to crates/desktop/src/lib.rs index 1f62ef8..50eaff1 100644 --- a/src/desktop/mod.rs +++ b/crates/desktop/src/lib.rs @@ -1,15 +1,22 @@ -//! Computer use — what the agent can see of a screen, and later what it can do -//! to one. +//! Computer use — what the agent can see of a screen, and what it can do to +//! one — as the `incord-desktop` crate and its `incu` binary. //! -//! The design and the decisions behind it are in `docs/COMPUTER_USE.md`. Three -//! of those decisions shape this module and are repeated here because a reader +//! The design and the decisions behind it are in `docs/COMPUTER_USE.md`. Four +//! of those decisions shape this crate and are repeated here because a reader //! who redraws them by accident will produce something that compiles and is //! wrong: //! //! - **This is offered to a DELEGATED agent over MCP.** It is not dispatched by -//! a loop in this crate, because there is no such loop — see -//! [`crate::tools`], which records that it was deliberately removed. Nothing -//! here may depend on [`crate::agent`]. +//! a loop, because there is no such loop: the agent runs in its own process +//! and reaches the screen only through the 16 tools of [`mcp`]. +//! +//! - **This crate does not depend on incode.** It began as a module of incode +//! (`src/desktop/`) and moved out whole. What it used to take from the rest +//! of incode is restated here: the permission tier ([`permission`]), the +//! operator's hooks ([`hooks`]), the settings ([`config`]) and a plain +//! `std::fs::create_dir_all`. incode depends on this crate, as it does on +//! `incord-sandbox`, and its `--desktop-mcp` flag is a thin wrapper over +//! [`cli::serve`]. //! //! - **One coordinate space leaves this module: physical pixels, top-left //! origin, in virtual-desktop coordinates.** Platform quirks — Windows DPI @@ -34,11 +41,15 @@ use std::fmt; use serde::{Deserialize, Serialize}; pub mod capture; +pub mod cli; +pub mod config; pub mod coords; pub mod dpi; +pub mod hooks; pub mod journal; pub mod limits; pub mod mcp; +pub mod permission; pub mod safety; pub mod thread; pub mod uia; diff --git a/src/desktop/limits.rs b/crates/desktop/src/limits.rs similarity index 100% rename from src/desktop/limits.rs rename to crates/desktop/src/limits.rs diff --git a/src/desktop/linux.rs b/crates/desktop/src/linux.rs similarity index 100% rename from src/desktop/linux.rs rename to crates/desktop/src/linux.rs diff --git a/src/desktop/macos.rs b/crates/desktop/src/macos.rs similarity index 100% rename from src/desktop/macos.rs rename to crates/desktop/src/macos.rs diff --git a/crates/desktop/src/main.rs b/crates/desktop/src/main.rs new file mode 100644 index 0000000..4d95ede --- /dev/null +++ b/crates/desktop/src/main.rs @@ -0,0 +1,25 @@ +//! `incu`: computer use for an agent, as an MCP server over stdio. +//! +//! The binary is only argument parsing and an exit code; everything it does is +//! in [`incord_desktop::cli`], which incode's `--desktop-mcp` wrapper shares. +//! Nothing is written to stdout except the protocol (and the text of `--help`, +//! `--version` and `stop`, none of which run beside a client). + +use std::process::ExitCode; + +fn main() -> ExitCode { + let command = match incord_desktop::cli::parse(std::env::args().skip(1)) { + Ok(command) => command, + Err(why) => { + eprintln!("incu: {why}"); + return ExitCode::from(2); + } + }; + match incord_desktop::cli::run(command) { + Ok(()) => ExitCode::SUCCESS, + Err(why) => { + eprintln!("incu: {why}"); + ExitCode::FAILURE + } + } +} diff --git a/src/desktop/mcp.rs b/crates/desktop/src/mcp.rs similarity index 56% rename from src/desktop/mcp.rs rename to crates/desktop/src/mcp.rs index dc45479..4ee3bdc 100644 --- a/src/desktop/mcp.rs +++ b/crates/desktop/src/mcp.rs @@ -4,8 +4,9 @@ //! //! `docs/COMPUTER_USE.md` section 1: the harness owns no model loop, so the only //! way a delegated agent gains a capability is over MCP. Decision 4 makes this a -//! SEPARATE PROCESS — `incode desktop-mcp --stdio` — so the Windows DPI call -//! owns its own startup and a crash here cannot take down a live session. +//! SEPARATE PROCESS — `incu serve`, or incode's `--desktop-mcp` wrapper of it — +//! so the Windows DPI call owns its own startup and a crash here cannot take +//! down a live session. //! //! # The protocol was measured, not remembered //! @@ -37,34 +38,37 @@ //! 1,000), `run_tool` at 315 lines and `call_tool` at 131 (threshold 100), //! because one file held the JSON-RPC transport, the tool definitions, the //! per-call gates, sixteen tools in one `match`, the screen guards and the -//! tests. This file keeps the server itself, the one function every tool -//! call passes ([`Server::call_tool`], now its gates as named steps) and the -//! client registration; the rest moved unchanged, each part to its own file: +//! tests. This file keeps the server itself and the one function every tool +//! call passes ([`Server::call_tool`], now its gates as named steps); the +//! rest moved unchanged, each part to its own file. (The client registration, +//! `client_config` and `codex_config_overrides`, names incode's flags and so +//! stayed in incode, in `desktop.rs`.) //! //! - [`transport`]: `handle_line`, the method table, the error envelope and //! [`run_stdio`]. //! - [`definitions`]: [`tool_definitions`], what a client is told. -//! - [`gate`]: the stop file, the permission mode, the hooks and the journal +//! - [`gate`]: the stop file, the permission tier, the hooks and the journal //! — the steps `call_tool` runs, in its order. //! - [`tools`]: `run_tool` and one step per tool. //! - [`guard`]: the blocked-application, focus, point and region refusals a //! tool asks before it acts. -//! - `tests`: the tests, at their old path `desktop::mcp::tests`. +//! - `tests`: the tests, at their old path `mcp::tests`. //! //! # Wired to //! -//! - **Called by** `main.rs` (`Parsed::DesktopMcp`), which builds a -//! [`Server`] and hands it to [`run_stdio`]; `toolbox::desktop`, through -//! [`tool_definitions`]; and `cli` / `agent::codex`, through -//! [`client_config_json`] and [`codex_config_overrides`]. -//! - **Calls** the desktop layer in [`super`] (`thread`, `uia`, `capture`, -//! `safety`, `journal`, `limits`), [`crate::permissions`] and -//! [`crate::hooks`], through the modules above. +//! - **Called by** [`crate::cli::serve`], which builds a [`Server`] and hands +//! it to [`run_stdio`] (for `incu serve` and for incode's `--desktop-mcp`); +//! and, in incode, `toolbox::desktop`, through [`tool_definitions`]. +//! - **Calls** the desktop layer (`thread`, `uia`, `capture`, `safety`, +//! `journal`, `limits`), [`crate::permission`] and [`crate::hooks`], through +//! the modules above. use serde_json::{json, Value}; use super::safety::Safety; use super::thread::InputThread; +use crate::hooks::{HookConfig, Hooks, ShellHooks}; +use crate::permission::Tier; mod definitions; mod gate; @@ -75,26 +79,15 @@ mod transport; #[cfg(test)] mod tests; -pub(crate) use definitions::tool_definitions; +pub use definitions::tool_definitions; pub use transport::run_stdio; use transport::{code, Failure}; -/// The tools that change the machine and so may end with a screenshot -/// (`screenshot_after`). -const ACTING: &[&str] = &[ - "click_element", - "set_value", - "element_action", - "focus_window", - "type_text", - "paste_text", - "key", - "scroll", - "drag", - "move_mouse", - "click", -]; +// The tools that change the machine and so may end with a screenshot +// (`screenshot_after`): the table the tier is checked against, so the two +// cannot disagree. +use crate::permission::ACTING; /// What every tool description carries, and why. /// @@ -119,16 +112,16 @@ pub struct Server { /// /// Not optional, because "no policy" would mean an ungoverned desktop and /// the whole point is that there is always an answer. The default is the - /// mode a session runs in unless told otherwise, so registering this + /// tier a session runs in unless told otherwise, so registering this /// server by hand does not silently produce something more capable than /// the harness would have launched. - permissions: crate::permissions::PermissionPolicy, + tier: Tier, /// The operator's own commands, run around every call. /// /// `None` is the ordinary case and costs nothing. See [`crate::hooks`] for /// the contract, and for why a hook sees the real input rather than the /// redacted description the journal gets. - hooks: Option, + hooks: Option>, } impl Server { @@ -141,9 +134,7 @@ impl Server { initialised: false, journal: None, stop_file: None, - permissions: crate::permissions::PermissionPolicy::for_desktop( - crate::permissions::PermissionMode::WorkspaceWrite, - ), + tier: Tier::Act, hooks: None, } } @@ -153,21 +144,36 @@ impl Server { /// An empty config is dropped rather than stored, so the ordinary case /// costs one `is_empty` at startup instead of two process spawns per /// click. + /// + /// Runs them with [`ShellHooks`]; a caller with a hook engine of its own + /// (incode's `--desktop-mcp`) hands it over with + /// [`Server::with_hook_runner`]. + #[must_use] + pub fn with_hooks(mut self, config: HookConfig) -> Self { + self.hooks = + (!config.is_empty()).then(|| Box::new(ShellHooks::new(config)) as Box); + self + } + + /// Run the operator's commands with `hooks`, an engine the caller owns. + /// + /// Called by [`crate::cli::serve`], with either [`ShellHooks`] or whatever + /// the embedding program supplied. #[must_use] - pub fn with_hooks(mut self, config: crate::hooks::HookConfig) -> Self { - self.hooks = (!config.is_empty()).then(|| crate::hooks::HookRunner::new(config)); + pub fn with_hook_runner(mut self, hooks: Box) -> Self { + self.hooks = Some(hooks); self } - /// Run this desktop under a session's permission mode. + /// Run this desktop under a permission tier. /// /// The launcher passes what the operator asked for; see - /// [`crate::permissions::PermissionPolicy::for_desktop`] for which tools - /// each mode reaches. A server built without this keeps the default mode, - /// which is what a session gets when no flag is given. + /// [`crate::permission::Tier`] for which tools each tier reaches. A server + /// built without this keeps [`Tier::Act`], which is what a session gets + /// when no flag is given. #[must_use] - pub fn with_permission_mode(mut self, mode: crate::permissions::PermissionMode) -> Self { - self.permissions = crate::permissions::PermissionPolicy::for_desktop(mode); + pub fn with_tier(mut self, tier: Tier) -> Self { + self.tier = tier; self } @@ -216,7 +222,7 @@ impl Server { // click look like a broken server, and the agent would retry the // transport rather than read the reason. self.catch_stop_file(); - let permitted = self.authorise(name, &args); + let permitted = self.authorise(name); let raw_args = args.to_string(); let vetoed = self.hook_veto(&permitted, name, &raw_args); let outcome = self.outcome(&permitted, vetoed, name, &args); @@ -232,92 +238,3 @@ impl Server { }) } } - -/// The name a client will see this server under. -pub const CLIENT_KEY: &str = "desktop"; - -/// The MCP configuration a client needs in order to launch this server. -/// -/// Verified against the installed Claude CLI 2.1.273: `--mcp-config ` -/// takes JSON, and `--strict-mcp-config` confines the agent to only what is -/// passed there. Codex takes the same information as -/// `-c mcp_servers..…` instead (`src/agent/codex/argv.rs`), which is why -/// this returns the SHAPE rather than a command line — each backend spells it -/// differently, and the thing they agree on is what to launch. -/// -/// `exe` is the path to this binary. Taken as an argument rather than read from -/// [`std::env::current_exe`] inside, so it is testable and so a caller can -/// register a server it is not itself running. -/// `journal` is where the launched server should record what it did, so -/// `--serve` can stream it (`COMPUTER_USE.md` 14c). `None` means nobody is -/// watching and the server writes nowhere. -pub fn client_config( - exe: &std::path::Path, - journal: Option<&std::path::Path>, - mode: crate::permissions::PermissionMode, -) -> Value { - let mut args = vec!["--desktop-mcp".to_string()]; - if let Some(path) = journal { - args.push("--desktop-journal".to_string()); - args.push(path.to_string_lossy().to_string()); - } - // ALWAYS PASSED, never omitted when it happens to be the default. This - // server is a separate process and cannot see the flag the session was - // started with; leaving it off would mean the operator's `-p read-only` - // stopped at the process boundary, which is exactly the bug that made a - // read-only session able to type. - args.push("-p".to_string()); - args.push(mode.as_str().to_string()); - json!({ - "mcpServers": { - CLIENT_KEY: { - "command": exe.to_string_lossy(), - "args": args, - } - } - }) -} - -/// [`client_config`] as the compact JSON string a `--mcp-config` flag takes. -pub fn client_config_json( - exe: &std::path::Path, - journal: Option<&std::path::Path>, - mode: crate::permissions::PermissionMode, -) -> String { - client_config(exe, journal, mode).to_string() -} - -/// The same registration as `-c key=value` overrides, which is how Codex takes -/// it. -/// -/// Verified against the installed CLI: `codex mcp add --help` documents `-c` -/// as "Override a configuration value… The `value` portion is parsed as TOML", -/// and its own example passes an array — -/// `-c 'sandbox_permissions=["disk-full-read-access"]'` — so the `args` list -/// below is TOML, not JSON, and not a guess. -/// -/// Returned as pairs rather than a command line because the caller knows how -/// its own `Command` wants them. -pub fn codex_config_overrides( - exe: &std::path::Path, - journal: Option<&std::path::Path>, - mode: crate::permissions::PermissionMode, -) -> Vec { - // TOML basic strings take backslash escapes, so a Windows path must have - // its separators doubled or `C:\Users\…` becomes an invalid escape. This - // applies to the JOURNAL path too, which is also a Windows path — the - // exe is not a special case, the string syntax is. - let toml = |p: &std::path::Path| p.to_string_lossy().replace('\\', "\\\\"); - let args = match journal { - Some(path) => format!( - "[\"--desktop-mcp\",\"--desktop-journal\",\"{}\",\"-p\",\"{}\"]", - toml(path), - mode.as_str() - ), - None => format!("[\"--desktop-mcp\",\"-p\",\"{}\"]", mode.as_str()), - }; - vec![ - format!("mcp_servers.{CLIENT_KEY}.command=\"{}\"", toml(exe)), - format!("mcp_servers.{CLIENT_KEY}.args={args}"), - ] -} diff --git a/src/desktop/mcp/definitions.rs b/crates/desktop/src/mcp/definitions.rs similarity index 99% rename from src/desktop/mcp/definitions.rs rename to crates/desktop/src/mcp/definitions.rs index 77793e5..15c6c41 100644 --- a/src/desktop/mcp/definitions.rs +++ b/crates/desktop/src/mcp/definitions.rs @@ -15,7 +15,8 @@ //! //! - **Called by** `tools/list` in [`super::transport`], and by the toolbox //! (`toolbox::desktop`) through [`tool_definitions`], which [`super`] -//! re-exports as `desktop::mcp::tool_definitions`. +//! re-exports as `mcp::tool_definitions` (public, since incode is a +//! separate crate now). //! - **Calls** nothing; reads [`super::ACTING`] and [`super::UNTRUSTED`]. use serde_json::{json, Value}; @@ -24,7 +25,7 @@ use super::{ACTING, UNTRUSTED}; /// Every desktop tool, in MCP's shape. The toolbox offers these same /// definitions to a model (`toolbox::desktop`), so they are written once. -pub(crate) fn tool_definitions() -> Vec { +pub fn tool_definitions() -> Vec { /// The tools that take a `window` from list_windows. const WINDOWED: &[&str] = &[ "screenshot", diff --git a/src/desktop/mcp/gate.rs b/crates/desktop/src/mcp/gate.rs similarity index 86% rename from src/desktop/mcp/gate.rs rename to crates/desktop/src/mcp/gate.rs index f13577a..530eeb3 100644 --- a/src/desktop/mcp/gate.rs +++ b/crates/desktop/src/mcp/gate.rs @@ -1,6 +1,6 @@ //! The gates every `tools/call` passes, as the named steps //! `Server::call_tool` runs in order: the operator's stop file, the session's -//! permission mode, the operator's pre-tool hook, the decision whether the +//! permission tier, the operator's pre-tool hook, the decision whether the //! tool runs at all, the post-tool hook, and the journal line — with //! [`Server::describe`], the redaction boundary for that line. //! @@ -21,11 +21,11 @@ //! # Wired to //! //! - **Called by** `Server::call_tool` in [`super`], once per `tools/call`. -//! - **Calls** [`crate::desktop::safety`] for the stop file and the stop, -//! [`crate::permissions::PermissionPolicy::authorize`] for the mode, -//! [`crate::hooks::HookRunner`] for the operator's commands, +//! - **Calls** [`crate::safety`] for the stop file and the stop, +//! [`crate::permission::Tier::authorise`] for the tier, +//! [`crate::hooks::Hooks`] for the operator's commands, //! [`Server::run_and_look`] in [`super::tools`] for the tool, and -//! [`crate::desktop::journal::Journal::record`] for the journal. +//! [`crate::journal::Journal::record`] for the journal. use serde_json::Value; @@ -46,33 +46,30 @@ impl Server { // The cost is one `exists()` per tool call, beside work that takes a // screenshot or walks an accessibility tree. if let Some(path) = self.stop_file.as_deref() { - if crate::desktop::safety::stop_requested(path) { + if crate::safety::stop_requested(path) { self.safety.stop(); } } } - /// Whether this session's permission mode allows `name`, with the - /// mode's reason when it does not. + /// Whether this session's permission tier allows `name`, with the tier's + /// reason when it does not. /// /// Called by `Server::call_tool` after [`Server::catch_stop_file`]. - pub(super) fn authorise(&self, name: &str, args: &Value) -> Result<(), String> { + pub(super) fn authorise(&self, name: &str) -> Result<(), String> { // WHAT THIS SESSION IS ALLOWED TO DO, asked before the stop check is // asked about anything and before a single pixel is read. // - // The mode reached the agent (`PermissionMode::agent_mode`) and - // governed its file writing, but the desktop was outside it entirely: - // a session started `-p read-only` could not edit a file and could - // type into a login form. The policy that was written for this and - // never called now runs here, at the one point every tool passes. + // The mode reached the agent and governed its file writing, but the + // desktop was outside it entirely: a session started `-p read-only` + // could not edit a file and could type into a login form. The tier + // that was written for this and never called now runs here, at the one + // point every tool passes. // - // No prompter is passed, and there is none to pass: stdin and stdout - // are the protocol. `Prompt` therefore denies, which is the right - // answer for an unattended server rather than a gap. - match self.permissions.authorize(name, &args.to_string(), None) { - crate::permissions::PermissionOutcome::Allow => Ok(()), - crate::permissions::PermissionOutcome::Deny { reason } => Err(reason), - } + // Nobody can be asked: stdin and stdout are the protocol. The `prompt` + // mode therefore denies, which is the right answer for an unattended + // server rather than a gap. + self.tier.authorise(name) } /// The operator's pre-tool hook's refusal, if it refused. @@ -139,7 +136,7 @@ impl Server { // the one tool for finding out why. match (permitted, self.safety.is_stopped(), vetoed) { (Err(reason), _, _) => Err(reason.clone()), - (Ok(()), true, _) => Err(crate::desktop::safety::Refusal::Stopped.message()), + (Ok(()), true, _) => Err(crate::safety::Refusal::Stopped.message()), (Ok(()), false, Some(why)) => Err(why), (Ok(()), false, None) => self.run_and_look(name, args), } @@ -180,7 +177,7 @@ impl Server { ) { // Journalled HERE rather than inside `run_tool`, because this is the // one place every tool passes through with its outcome known. Putting - // it in the arms would mean twelve call sites and a thirteenth tool + // it in the arms would mean sixteen call sites and a seventeenth tool // added later that nobody remembers to instrument. if let Some(journal) = self.journal.as_mut() { let (t, detail, ok) = match outcome { diff --git a/src/desktop/mcp/guard.rs b/crates/desktop/src/mcp/guard.rs similarity index 92% rename from src/desktop/mcp/guard.rs rename to crates/desktop/src/mcp/guard.rs index 5fc2980..9c7f988 100644 --- a/src/desktop/mcp/guard.rs +++ b/crates/desktop/src/mcp/guard.rs @@ -19,13 +19,13 @@ //! `set_value`, `element_action`, `move_mouse`, `click`, `ui_tree`, //! `click_element`, `type_text`, `paste_text`, `key`, `scroll`, `drag`, //! and the screenshot path `shoot`). -//! - **Calls** [`crate::desktop::limits::get`] for the blocked applications, -//! [`crate::desktop::uia`] for the focused window and the window list, and -//! [`crate::desktop::screen_info`] for the displays. +//! - **Calls** [`crate::limits::get`] for the blocked applications, +//! [`crate::uia`] for the focused window and the window list, and +//! [`crate::screen_info`] for the displays. -use crate::desktop::coords::PhysicalPoint; -use crate::desktop::uia::{self, WindowInfo}; -use crate::desktop::Rect; +use crate::coords::PhysicalPoint; +use crate::uia::{self, WindowInfo}; +use crate::Rect; /// Refuse a window that belongs to a blocked application (a password /// manager, or one admin.json names). Checked BEFORE anything is read from @@ -37,8 +37,8 @@ pub(super) fn refuse_blocked(info: &WindowInfo) -> Result<(), String> { /// Refuse an application by name; [`refuse_blocked`] for a window, and /// called directly by `ui_tree` for the application a walked tree names. pub(super) fn refuse_app(app: &str) -> Result<(), String> { - match crate::desktop::limits::get().blocked(app) { - Some(entry) if entry == crate::desktop::limits::UNNAMED_APP => Err( + match crate::limits::get().blocked(app) { + Some(entry) if entry == crate::limits::UNNAMED_APP => Err( "refused: the application that owns that window could not be named, so it cannot be \ told apart from a password manager; incode does not read or act on it." .to_string(), @@ -104,7 +104,7 @@ pub(super) fn off_every_screen(at: PhysicalPoint, screens: &[Rect]) -> Option Result, String> { - let info = crate::desktop::screen_info().map_err(|e| { + let info = crate::screen_info().map_err(|e| { format!( "refused: the displays could not be read ({e}), so this cannot be checked to be on \ one" @@ -125,7 +125,7 @@ pub(super) fn blocked_windows() -> Result, String> { })?; Ok(windows .into_iter() - .filter(|w| crate::desktop::limits::get().blocked(&w.app).is_some()) + .filter(|w| crate::limits::get().blocked(&w.app).is_some()) .collect()) } diff --git a/src/desktop/mcp/tests.rs b/crates/desktop/src/mcp/tests.rs similarity index 87% rename from src/desktop/mcp/tests.rs rename to crates/desktop/src/mcp/tests.rs index 0227913..4acb1da 100644 --- a/src/desktop/mcp/tests.rs +++ b/crates/desktop/src/mcp/tests.rs @@ -8,8 +8,8 @@ use super::*; use super::guard::off_every_screen; use super::tools::{image, point}; use super::transport::code; -use crate::desktop::capture::ShotFormat; -use crate::desktop::coords::PhysicalPoint; +use crate::capture::ShotFormat; +use crate::coords::PhysicalPoint; /// Protocol tests that need no desktop: they exercise the pure shapes. mod protocol { @@ -96,79 +96,15 @@ mod protocol { ); } - /// The config has to name the flag that actually starts the server. - /// - /// If these two ever drift, the client launches the binary in its - /// NORMAL mode — which starts the interactive harness on a pipe, prints - /// human text to stdout, and looks to the client like a server speaking - /// gibberish. That is a long debugging session for a one-word mistake. - #[test] - fn the_client_config_launches_this_binary_in_server_mode() { - let config = client_config( - std::path::Path::new("C:/bin/incode.exe"), - None, - crate::permissions::PermissionMode::WorkspaceWrite, - ); - let server = &config["mcpServers"][CLIENT_KEY]; - - assert_eq!(server["command"], "C:/bin/incode.exe"); - assert_eq!( - server["args"], - json!(["--desktop-mcp", "-p", "workspace-write"]), - "the config must pass the flag that selects the server mode" - ); - - // With a journal, the path is passed as its own argument — one the - // server can only receive this way, since it holds no workspace. - let watched = client_config( - std::path::Path::new("C:/bin/incode.exe"), - Some(std::path::Path::new("C:/work/.incode/desktop.jsonl")), - crate::permissions::PermissionMode::ReadOnly, - ); - assert_eq!( - watched["mcpServers"][CLIENT_KEY]["args"], - json!([ - "--desktop-mcp", - "--desktop-journal", - "C:/work/.incode/desktop.jsonl", - "-p", - "read-only" - ]), - "the session's mode must reach the child process on its argv" - ); - - // The same string main.rs matches on, so a rename breaks here - // rather than at a client six months later. - assert!( - USAGE_FLAG_IN_MAIN.contains("--desktop-mcp"), - "the flag in the config no longer matches the one main.rs parses" - ); - } - - /// The flag `src/main.rs` parses. Kept beside the config that emits it. - const USAGE_FLAG_IN_MAIN: &str = "--desktop-mcp"; - - #[test] - fn the_config_is_valid_json_for_a_command_line() { - let text = client_config_json( - std::path::Path::new("/usr/local/bin/incode"), - None, - crate::permissions::PermissionMode::WorkspaceWrite, - ); - let parsed: Value = serde_json::from_str(&text).expect("must be valid JSON"); - assert_eq!( - parsed["mcpServers"]["desktop"]["command"], - "/usr/local/bin/incode" - ); - // Compact, because it is passed as one shell argument. - assert!(!text.contains('\n'), "a multi-line config breaks the flag"); - } + // `the_client_config_launches_this_binary_in_server_mode` and + // `the_config_is_valid_json_for_a_command_line` moved to incode's + // `desktop.rs`, with the `client_config` they test: it names incode's flags. #[test] fn a_point_on_no_display_is_refused_and_one_on_any_display_is_not() { let screens = [ - crate::desktop::Rect::from_edges(-1920, 0, 0, 1080), - crate::desktop::Rect::from_edges(0, 0, 2560, 1440), + crate::Rect::from_edges(-1920, 0, 0, 1080), + crate::Rect::from_edges(0, 0, 2560, 1440), ]; let at = |x, y| PhysicalPoint { x, y }; for (x, y) in [(0, 0), (-1920, 500), (2559, 1439), (-1, 1079)] { @@ -237,7 +173,7 @@ mod live { #[test] fn a_read_only_desktop_may_look_and_may_not_touch() { let mut s = Server::new(InputThread::start().expect("input thread")) - .with_permission_mode(crate::permissions::PermissionMode::ReadOnly); + .with_tier(crate::permission::Tier::Observe); s.safety().stop(); let typed = call( @@ -268,7 +204,7 @@ mod live { // since a stop halts reads too and would prove nothing about the // permission mode. let mut looking = Server::new(InputThread::start().expect("input thread")) - .with_permission_mode(crate::permissions::PermissionMode::ReadOnly); + .with_tier(crate::permission::Tier::Observe); let looked = call( &mut looking, r#"{"jsonrpc":"2.0","id":2,"method":"tools/call", @@ -318,13 +254,6 @@ mod live { crate::hooks::HookConfig { pre_tool_use: vec![deny.into()], post_tool_use: Vec::new(), - user_prompt_submit: Vec::new(), - pre_compact: Vec::new(), - stop: Vec::new(), - notification: Vec::new(), - session_start: Vec::new(), - session_end: Vec::new(), - subagent_stop: Vec::new(), }, ); @@ -361,13 +290,6 @@ mod live { crate::hooks::HookConfig { pre_tool_use: vec![allow.into()], post_tool_use: Vec::new(), - user_prompt_submit: Vec::new(), - pre_compact: Vec::new(), - stop: Vec::new(), - notification: Vec::new(), - session_start: Vec::new(), - session_end: Vec::new(), - subagent_stop: Vec::new(), }, ); @@ -673,7 +595,7 @@ mod live { r#"{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"click","arguments":{"x":10,"y":10}}}"#, ); - let entries = crate::desktop::journal::since(&path, None); + let entries = crate::journal::since(&path, None); assert_eq!(entries.len(), 1, "the refusal was not journalled"); assert_eq!(entries[0].t, "refused"); assert!(!entries[0].ok); @@ -790,7 +712,7 @@ mod live { std::process::id(), std::thread::current().id() )); - let stop = crate::desktop::safety::stop_file_beside(&journal); + let stop = crate::safety::stop_file_beside(&journal); let _ = std::fs::remove_file(&journal); let _ = std::fs::remove_file(&stop); @@ -806,7 +728,7 @@ mod live { "the server must work before the stop, or this proves nothing" ); - crate::desktop::safety::request_stop(&stop).expect("request the stop"); + crate::safety::request_stop(&stop).expect("request the stop"); let after = call(&mut s, probe); assert_eq!( @@ -831,7 +753,7 @@ mod live { // The operator sees their own stop land in the channel they were // watching — that is what makes it confirmable. - let entries = crate::desktop::journal::since(&journal, None); + let entries = crate::journal::since(&journal, None); assert!( entries.iter().any(|e| e.t == "refused" && !e.ok), "the stop was not journalled: {entries:?}" @@ -847,14 +769,14 @@ mod live { #[test] fn watching_and_stopping_name_the_same_place() { let workspace = std::path::Path::new("C:/work"); - let journal = crate::desktop::journal::path_in(workspace); + let journal = crate::journal::path_in(workspace); assert_eq!( - crate::desktop::safety::stop_path_in(workspace), - crate::desktop::safety::stop_file_beside(&journal), + crate::safety::stop_path_in(workspace), + crate::safety::stop_file_beside(&journal), "the workspace path and the beside-the-journal path disagree" ); assert_eq!( - crate::desktop::safety::stop_path_in(workspace).parent(), + crate::safety::stop_path_in(workspace).parent(), journal.parent(), "the stop file must live beside the journal" ); diff --git a/src/desktop/mcp/tools.rs b/crates/desktop/src/mcp/tools.rs similarity index 96% rename from src/desktop/mcp/tools.rs rename to crates/desktop/src/mcp/tools.rs index 90d6682..aa8de6f 100644 --- a/src/desktop/mcp/tools.rs +++ b/crates/desktop/src/mcp/tools.rs @@ -20,18 +20,18 @@ //! - **Called by** `Server::call_tool` in [`super`], through //! [`Server::run_and_look`], once the gates in [`super::gate`] have let //! the call through; [`window_arg`] also by `Server::describe`. -//! - **Calls** [`crate::desktop::thread::InputThread`] for the mouse and the -//! keyboard, [`crate::desktop::uia`] for windows and elements, -//! [`crate::desktop::capture`] for pictures, and [`super::guard`] before +//! - **Calls** [`crate::thread::InputThread`] for the mouse and the +//! keyboard, [`crate::uia`] for windows and elements, +//! [`crate::capture`] for pictures, and [`super::guard`] before //! each of them. use base64::Engine as _; use serde_json::{json, Value}; -use crate::desktop::capture::{self, CaptureOptions, ShotFormat}; -use crate::desktop::coords::PhysicalPoint; -use crate::desktop::thread::{InputThread, MouseButton}; -use crate::desktop::uia::{self, WindowInfo}; +use crate::capture::{self, CaptureOptions, ShotFormat}; +use crate::coords::PhysicalPoint; +use crate::thread::{InputThread, MouseButton}; +use crate::uia::{self, WindowInfo}; use super::guard::{ blocked_windows, guard_focus, refuse_app, refuse_blocked, refuse_point, refuse_region, @@ -83,7 +83,7 @@ impl Server { /// `screen_info`: every display. Called by [`Server::run_tool`]. fn screen_info() -> Result, String> { - let info = crate::desktop::screen_info().map_err(|e| e.to_string())?; + let info = crate::screen_info().map_err(|e| e.to_string())?; Ok(vec![text( serde_json::to_string_pretty(&info).unwrap_or_default(), )]) @@ -119,7 +119,7 @@ fn list_windows() -> Result, String> { let windows = uia::list_windows().map_err(|e| e.to_string())?; let listed: Vec = windows .iter() - .map(|w| match crate::desktop::limits::get().blocked(&w.app) { + .map(|w| match crate::limits::get().blocked(&w.app) { // Listed so the agent knows it is there and not to // try, with the area every click and capture keeps // off; its title (often an entry's name) is not. @@ -214,7 +214,7 @@ fn ui_tree(args: &Value) -> Result, String> { let depth = args .get("depth") .and_then(Value::as_u64) - .unwrap_or(u64::from(crate::desktop::limits::get().tree_depth)) as u32; + .unwrap_or(u64::from(crate::limits::get().tree_depth)) as u32; let tree = uia::window_tree(window_arg(args).as_deref(), depth).map_err(|e| e.to_string())?; // Walked in this process, and discarded unread when blocked. refuse_app(&tree.app)?; @@ -437,7 +437,7 @@ fn scroll_steps(args: &Value, key: &str) -> Result { let Some(raw) = args.get(key) else { return Ok(0); }; - let max = i64::from(crate::desktop::limits::get().max_scroll_steps); + let max = i64::from(crate::limits::get().max_scroll_steps); match raw.as_i64() { Some(n) if n.abs() <= max => Ok(n as i32), Some(n) => Err(format!( @@ -551,7 +551,7 @@ fn shoot(window: Option<&str>, options: CaptureOptions) -> Result, St /// to change. A failure is reported beside the action's result rather than /// replacing it — the action itself already happened. fn after_shot(args: &Value) -> Vec { - std::thread::sleep(crate::desktop::limits::get().settle); + std::thread::sleep(crate::limits::get().settle); let window = window_arg(args).or_else(|| uia::foreground().ok().flatten().map(|w| w.id)); match shoot(window.as_deref(), CaptureOptions::default()) { Ok(content) => content, diff --git a/src/desktop/mcp/transport.rs b/crates/desktop/src/mcp/transport.rs similarity index 100% rename from src/desktop/mcp/transport.rs rename to crates/desktop/src/mcp/transport.rs diff --git a/crates/desktop/src/permission.rs b/crates/desktop/src/permission.rs new file mode 100644 index 0000000..482b2d1 --- /dev/null +++ b/crates/desktop/src/permission.rs @@ -0,0 +1,235 @@ +//! What a session may do to the machine: the crate's own permission tier. +//! +//! # Where this sits +//! +//! The server asks [`Tier::authorise`] first of its three per-call gates +//! (`mcp/gate.rs`, `Server::authorise`), before the stop is consulted about +//! anything and before a single pixel is read. The tier arrives on the command +//! line ([`crate::cli`]: `--tier`, or `-p ` as an alias) or from +//! [`crate::mcp::Server::with_tier`]. +//! +//! # Why the crate owns this, and how it matches incode's +//! +//! Until the desktop became a crate of its own this was incode's +//! `PermissionPolicy::for_desktop(PermissionMode)`. The crate cannot depend on +//! incode, so the tier is restated here as the two rungs the 16 tools actually +//! use, and [`Tier::from_mode_word`] reads incode's own mode words so the argv +//! incode has always passed (`-p read-only`) keeps meaning the same thing: +//! +//! | mode word | tier | reaches | +//! |---|---|---| +//! | `read-only` | [`Tier::Observe`] | the 5 observing tools | +//! | `workspace-write` (the default), `danger-full-access`, `allow` | [`Tier::Act`] | all 16 | +//! | `prompt` | [`Tier::Deny`] | nothing | +//! +//! `prompt` denies everything, and that is correct rather than unfortunate: +//! stdin and stdout are the MCP protocol, so there is no channel to ask a human +//! on. A word nobody recognises is not guessed at; the caller refuses to start. +//! +//! # Only two rungs, on purpose +//! +//! The observing tools need `read-only`; the acting ones `workspace-write`. Not +//! `danger-full-access`, even though a click reaches far outside any workspace: +//! `workspace-write` is the default mode, and putting the desktop above it would +//! mean the feature ships switched off and the flag becomes the thing people +//! turn off. What the split buys is that `read-only` means the agent may LOOK at +//! the screen and may not touch it. Before it, read-only sessions could type. + +/// The tools that only look. A screenshot photographs a machine signed into real +/// accounts, which is why it is gated at all rather than left ungoverned, but it +/// takes nothing and changes nothing. +pub const OBSERVING: &[&str] = &[ + "screen_info", + "cursor_position", + "screenshot", + "ui_tree", + "list_windows", +]; + +/// The tools that change the state of a machine the operator is signed into, and +/// so may end with a screenshot (`screenshot_after`, `mcp.rs`). +pub const ACTING: &[&str] = &[ + "click_element", + "set_value", + "element_action", + "focus_window", + "type_text", + "paste_text", + "key", + "scroll", + "drag", + "move_mouse", + "click", +]; + +/// How much of the desktop a server will hand over. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Tier { + /// Nothing at all: there is nobody to ask for approval. + Deny, + /// Look, never touch: [`OBSERVING`]. + Observe, + /// Look and touch: [`OBSERVING`] and [`ACTING`]. The default. + Act, +} + +impl Tier { + /// The tier a `--tier` value names: `observe` or `act`. + #[must_use] + pub fn parse(word: &str) -> Option { + match word { + "observe" => Some(Self::Observe), + "act" => Some(Self::Act), + _ => None, + } + } + + /// The tier an incode permission-mode word names, or `None` if it names no + /// mode. The spellings are the ones incode's `PermissionMode::parse` takes. + /// + /// Called by [`crate::cli`] for `-p`, and by incode's `--desktop-mcp` + /// wrapper with `PermissionMode::as_str()`. + #[must_use] + pub fn from_mode_word(word: &str) -> Option { + match word { + "read-only" | "readonly" => Some(Self::Observe), + "workspace-write" | "write" | "danger-full-access" | "full" | "danger" | "allow" => { + Some(Self::Act) + } + "prompt" | "ask" => Some(Self::Deny), + _ => None, + } + } + + /// The name this tier is shown under: the mode word a refusal quotes and the + /// startup line prints, so an operator who asked for `read-only` sees that it + /// arrived. + #[must_use] + pub fn label(self) -> &'static str { + match self { + Self::Deny => "prompt", + Self::Observe => "read-only", + Self::Act => "workspace-write", + } + } + + /// Whether this tier lets `tool` run, with the reason when it does not. + /// + /// The words of a refusal are the ones the agent has always been given + /// ("requires workspace-write permission; current mode is read-only"), so a + /// client that matches on them keeps working. + /// + /// A tool the tables do not name is refused at every tier: the tables are the + /// only way in. (Under incode's `danger-full-access` and `allow` such a name + /// used to reach the dispatcher and be refused there as unknown; the + /// refusal now comes from here, with the same effect and different words.) + /// + /// # Errors + /// + /// The tier does not reach `tool`. + pub fn authorise(self, tool: &str) -> Result<(), String> { + let acting = ACTING.contains(&tool); + let observing = OBSERVING.contains(&tool); + match self { + Self::Act if acting || observing => Ok(()), + Self::Observe if observing => Ok(()), + Self::Observe => Err(format!( + "tool '{tool}' requires {} permission; current mode is {}", + if acting { + "workspace-write" + } else { + "danger-full-access" + }, + self.label() + )), + // `Deny`, and an unknown tool under `Act`: someone would have to + // approve it, and nobody can be asked. + _ => Err(format!( + "tool '{tool}' requires approval (no prompter available)" + )), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The tier table must be the server's tool list, or a tool is either + /// ungoverned or unreachable. Checked against what `tools/list` offers, so a + /// seventeenth tool cannot be added without deciding its tier. + #[test] + fn every_listed_tool_has_a_tier_and_there_are_sixteen() { + let listed: Vec = crate::mcp::tool_definitions() + .iter() + .map(|t| t["name"].as_str().unwrap_or_default().to_string()) + .collect(); + assert_eq!(listed.len(), 16, "{listed:?}"); + for name in &listed { + assert!( + OBSERVING.contains(&name.as_str()) ^ ACTING.contains(&name.as_str()), + "`{name}` must be in exactly one of OBSERVING and ACTING" + ); + } + assert_eq!(OBSERVING.len() + ACTING.len(), listed.len()); + } + + #[test] + fn read_only_looks_and_never_touches() { + for tool in OBSERVING { + assert!(Tier::Observe.authorise(tool).is_ok(), "{tool}"); + } + for tool in ACTING { + let why = Tier::Observe.authorise(tool).expect_err(tool); + assert!(why.contains("workspace-write"), "{why}"); + assert!( + why.contains("read-only"), + "the refusal names the mode: {why}" + ); + } + } + + #[test] + fn the_default_tier_reaches_every_tool() { + for tool in OBSERVING.iter().chain(ACTING) { + assert!(Tier::Act.authorise(tool).is_ok(), "{tool}"); + } + } + + /// `prompt` denies everything: stdin and stdout are the protocol, so there is + /// nobody to ask. + #[test] + fn prompt_reaches_nothing() { + for tool in OBSERVING.iter().chain(ACTING) { + let why = Tier::Deny.authorise(tool).expect_err(tool); + assert!(why.contains("requires approval"), "{why}"); + } + } + + #[test] + fn a_tool_nobody_serves_is_refused_at_every_tier() { + for tier in [Tier::Deny, Tier::Observe, Tier::Act] { + assert!(tier.authorise("format_disk").is_err(), "{tier:?}"); + } + } + + /// The words incode has always passed on `-p` keep their meaning, and a typo + /// in a security flag is reported rather than resolved to something. + #[test] + fn incodes_mode_words_map_to_the_same_rungs() { + assert_eq!(Tier::from_mode_word("read-only"), Some(Tier::Observe)); + assert_eq!(Tier::from_mode_word("workspace-write"), Some(Tier::Act)); + assert_eq!(Tier::from_mode_word("danger-full-access"), Some(Tier::Act)); + assert_eq!(Tier::from_mode_word("allow"), Some(Tier::Act)); + assert_eq!(Tier::from_mode_word("prompt"), Some(Tier::Deny)); + assert_eq!(Tier::from_mode_word("wrokspace-write"), None); + } + + #[test] + fn the_tier_flag_takes_observe_and_act_only() { + assert_eq!(Tier::parse("observe"), Some(Tier::Observe)); + assert_eq!(Tier::parse("act"), Some(Tier::Act)); + assert_eq!(Tier::parse("read-only"), None); + assert_eq!(Tier::parse("deny"), None); + } +} diff --git a/src/desktop/safety.rs b/crates/desktop/src/safety.rs similarity index 98% rename from src/desktop/safety.rs rename to crates/desktop/src/safety.rs index 1f4cfd2..7cb9ab0 100644 --- a/src/desktop/safety.rs +++ b/crates/desktop/src/safety.rs @@ -214,7 +214,11 @@ pub fn stop_path_in(workspace: &std::path::Path) -> std::path::PathBuf { /// it is worse than no stop button at all. pub fn request_stop(path: &std::path::Path) -> std::io::Result<()> { if let Some(parent) = path.parent() { - crate::folders::create_dir_all(parent)?; + // Plain `create_dir_all`. incode's `desktop::safety::request_stop` + // (`src/desktop.rs`) is this function behind incode's own + // `folders::create_dir_all`, which also writes the `.gitignore` of a + // fresh `.incode/`, so every incode caller keeps that. + std::fs::create_dir_all(parent)?; } // The timestamp is for a human reading the directory later. Nothing parses // it — see the note above. diff --git a/src/desktop/thread.rs b/crates/desktop/src/thread.rs similarity index 100% rename from src/desktop/thread.rs rename to crates/desktop/src/thread.rs diff --git a/src/desktop/uia.rs b/crates/desktop/src/uia.rs similarity index 99% rename from src/desktop/uia.rs rename to crates/desktop/src/uia.rs index 35fd4ca..88f7846 100644 --- a/src/desktop/uia.rs +++ b/crates/desktop/src/uia.rs @@ -1248,7 +1248,7 @@ mod tests { tree.elements.len() ); - let screen = crate::desktop::screen_info().expect("screen"); + let screen = crate::screen_info().expect("screen"); let bounds = screen.virtual_bounds().expect("a desktop"); let on_desktop = |r: Rect| { diff --git a/src/desktop/uia_windows.rs b/crates/desktop/src/uia_windows.rs similarity index 99% rename from src/desktop/uia_windows.rs rename to crates/desktop/src/uia_windows.rs index 2f170b0..0cf7ff3 100644 --- a/src/desktop/uia_windows.rs +++ b/crates/desktop/src/uia_windows.rs @@ -24,7 +24,7 @@ use windows_sys::Win32::UI::WindowsAndMessaging::{ }; use super::{find, walk, Done, Element, Role, Tree, Want, WindowInfo}; -use crate::desktop::{DesktopError, Rect}; +use crate::{DesktopError, Rect}; /// The actions [`act`] knows, in the shared vocabulary. const ACTIONS: &[&str] = &[ diff --git a/src/desktop/win32.rs b/crates/desktop/src/win32.rs similarity index 99% rename from src/desktop/win32.rs rename to crates/desktop/src/win32.rs index adfe9cc..f485aff 100644 --- a/src/desktop/win32.rs +++ b/crates/desktop/src/win32.rs @@ -172,7 +172,7 @@ unsafe extern "system" fn collect_one( #[cfg(test)] mod tests { - use crate::desktop::{screen_info, ScreenInfo}; + use crate::{screen_info, ScreenInfo}; fn live() -> ScreenInfo { screen_info().expect("a Windows session must be able to describe its own displays") diff --git a/src/desktop/x11.rs b/crates/desktop/src/x11.rs similarity index 99% rename from src/desktop/x11.rs rename to crates/desktop/src/x11.rs index 2c63612..8d761d2 100644 --- a/src/desktop/x11.rs +++ b/crates/desktop/src/x11.rs @@ -240,7 +240,7 @@ pub(crate) fn focused_index(listed: &[Listed], chain: &[u32]) -> Option Rect { Rect { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7453e26..9186f4f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1059,7 +1059,7 @@ was not probed. `team_read` are toolbox tools (`toolbox::team`, over `team_mcp::Server`), and the separate server is no longer handed to a bridged model. It is kept for codex, which still reaches the channel through `mcp_overrides_for`. -- The desktop: **fixed (phase 6b)** — its twelve tools are toolbox tools, reached +- The desktop: **fixed (phase 6b)** — its sixteen tools are toolbox tools, reached through the bridge; `incode --desktop-mcp` is now only their executor, started by the toolbox. No desktop server is handed to the CLI. See §5b, "The desktop". - The engine's session-capture hooks: **fixed (phase 4)** — incode fires them itself on @@ -1290,7 +1290,7 @@ code names it. ### The desktop (phase 6b) -The twelve desktop tools are toolbox tools when the desktop is switched on +The sixteen desktop tools are toolbox tools when the desktop is switched on (`INCODE_DESKTOP`; `cli::desktop_setup_for` → `Toolbox::enable_desktop`, on the bridged claude route and the API route). They are offered, schema-checked, held to the mode and the engine, and drawn as incode's own calls like every other tool, and no desktop server diff --git a/docs/COMPUTER_USE.md b/docs/COMPUTER_USE.md index 6867b18..d315c08 100644 --- a/docs/COMPUTER_USE.md +++ b/docs/COMPUTER_USE.md @@ -1,8 +1,10 @@ # incode — Computer Use > **Status note, 2026-09-26.** The first line below is out of date. The Windows desktop -> (`src/desktop/`) is built, and its twelve tools are Toolbox tools behind incode's -> gate, executed by `incode --desktop-mcp` (`ARCHITECTURE.md` §5b, "The desktop"). +> (now the `incord-desktop` crate, `crates/desktop`, binary `incu`; it was `src/desktop/`) +> is built, and its sixteen tools (five that observe, eleven that act) are Toolbox tools +> behind incode's gate, executed by `incode --desktop-mcp`, which is a thin wrapper over +> `incu serve` (`ARCHITECTURE.md` §5b, "The desktop"). > macOS (Phase C) is built (2026-10-01, `src/desktop/macos.rs`): monitors and capture > through xcap in POINTS, the accessibility tree through AXUIElement, the clipboard > through `pbcopy`, and the two TCC grants probed before every action and reported by @@ -477,15 +479,17 @@ state of the code. What it correctly identified is that a policy is worth nothin where nobody calls it; what it could not say is where it *should* be called. That place is point 1 below — the desktop MCP server, which this section already -names as "the only one this crate fully controls". `desktop::mcp::call_tool` now -asks `PermissionPolicy::for_desktop(mode)` before every tool, and the session's -`-p` reaches that separate process on its argv. +names as "the only one this crate fully controls". `desktop::mcp::Server::call_tool` now +asks the server's permission tier before every tool (`incord_desktop::permission::Tier`; +`PermissionPolicy::for_desktop(mode)` is incode's statement of the same table, and a +test keeps the two equal), and the session's `-p` reaches that separate process on its +argv (`incu` also takes `--tier observe|act`). | Mode | The desktop it gets | |---|---| -| `read-only` | `screen_info`, `cursor_position`, `screenshot`, `ui_tree`. Nothing that moves. | -| `workspace-write` (default) | all twelve — unchanged from before | -| `danger-full-access`, `allow` | all twelve | +| `read-only` | `screen_info`, `cursor_position`, `screenshot`, `ui_tree`, `list_windows`. Nothing that moves. | +| `workspace-write` (default) | all sixteen — unchanged from before | +| `danger-full-access`, `allow` | all sixteen | | `prompt` | nothing. stdin and stdout are the protocol, so there is no channel to ask a human on, and `authorize` with no prompter denies. | The acting tools require `WorkspaceWrite` rather than `DangerFullAccess`, even diff --git a/docs/incord-memory-integration.md b/docs/incord-memory-integration.md index b13b334..ffd811d 100644 --- a/docs/incord-memory-integration.md +++ b/docs/incord-memory-integration.md @@ -90,7 +90,7 @@ may hear a session twice — once from incode, once from the CLI under the CLI's (Closed for codex in phase 8: it runs with `--disable hooks`. Still true for agy.) **Phase 6b (2026-09-25).** Three more kinds of call now pass the engine's pre-tool hook, -because they are Toolbox tools: the desktop's twelve tools (previously run in +because they are Toolbox tools: the desktop's sixteen tools (previously run in `incode --desktop-mcp` with only the desktop's own hooks, which still run there as a second line), `Screenshot` (observe, fail open) and `RenderPdf` (change, fail closed; its OUTPUT path is in `tool_input.paths` and is reported to `code-edit` once written). A diff --git a/scripts/test-all.sh b/scripts/test-all.sh index e693a02..eeafb91 100755 --- a/scripts/test-all.sh +++ b/scripts/test-all.sh @@ -44,6 +44,9 @@ if wants rust; then # Runs real commands under the insbx engine (Linux; it says it skipped # elsewhere). step rust cargo test --test insbx_engine + # The computer-use crate (`incu`); `--lib` above is incode's alone. + [ -n "${QUICK:-}" ] || step rust cargo clippy -p incord-desktop --all-targets -- -D warnings + step rust cargo test -p incord-desktop else skipped="$skipped rust(cargo)" fi diff --git a/src/desktop.rs b/src/desktop.rs new file mode 100644 index 0000000..1c9bd2a --- /dev/null +++ b/src/desktop.rs @@ -0,0 +1,383 @@ +//! Computer use, as incode sees it: the `incord-desktop` crate (`crates/desktop`, +//! binary `incu`) under its old path, and the few things that name incode. +//! +//! # Where this sits +//! +//! The desktop began as this module and moved out whole, for the reasons in the +//! `incord-desktop` crate header: it does not depend on incode, and incode +//! depends on it as it does on `incord-sandbox`. `pub use incord_desktop::*` +//! keeps every `crate::desktop::…` path in incode (`serve::http`, `runtime:: +//! cancel`, `migrate`, `admin`, `cli`, the toolbox) as it was; rewriting them to +//! name the crate is a later step. +//! +//! Three things are not re-exported as they are, because they are incode's: +//! +//! - [`mcp::client_config`], [`mcp::client_config_json`] and +//! [`mcp::codex_config_overrides`] build the registration an agent CLI needs +//! to launch `incode --desktop-mcp`. They name incode's flags and take +//! incode's `PermissionMode`, so they stayed. +//! - [`safety::request_stop`] is the crate's, behind incode's own +//! `folders::create_dir_all`, which also writes the `.gitignore` of a fresh +//! `.incode/`. The crate uses plain `std::fs::create_dir_all`. +//! - [`serve`] is `incode --desktop-mcp`: a thin wrapper that hands the crate's +//! [`cli::serve`] the settings from `admin.json` and the operator's hook +//! engine ([`crate::hooks::HookRunner`], so the commands run exactly as they +//! always have, in the shell and with the process-tree containment incode's +//! hooks use). +//! +//! # Wired to +//! +//! - **Called by** `main.rs` (`Parsed::DesktopMcp`) for [`serve`]; +//! `cli::agent_session` and `agent::codex` for [`mcp::codex_config_overrides`]. +//! - **Calls** `incord_desktop` for everything else. + +use std::path::PathBuf; + +pub use incord_desktop::*; + +use incord_desktop::hooks::{HookOutcome, Hooks}; +use incord_desktop::permission::Tier; + +use crate::admin::AdminConfig; +use crate::permissions::PermissionMode; + +pub mod mcp { + //! The server (the crate's), and the registration of it that names incode. + + pub use incord_desktop::mcp::*; + + use serde_json::{json, Value}; + + use crate::permissions::PermissionMode; + + /// The name a client will see this server under. + pub const CLIENT_KEY: &str = "desktop"; + + /// The MCP configuration a client needs in order to launch this server. + /// + /// Verified against the installed Claude CLI 2.1.273: `--mcp-config ` + /// takes JSON, and `--strict-mcp-config` confines the agent to only what is + /// passed there. Codex takes the same information as + /// `-c mcp_servers..…` instead (`src/agent/codex/argv.rs`), which is why + /// this returns the SHAPE rather than a command line — each backend spells it + /// differently, and the thing they agree on is what to launch. + /// + /// `exe` is the path to this binary. Taken as an argument rather than read from + /// [`std::env::current_exe`] inside, so it is testable and so a caller can + /// register a server it is not itself running. + /// `journal` is where the launched server should record what it did, so + /// `--serve` can stream it (`COMPUTER_USE.md` 14c). `None` means nobody is + /// watching and the server writes nowhere. + pub fn client_config( + exe: &std::path::Path, + journal: Option<&std::path::Path>, + mode: PermissionMode, + ) -> Value { + let mut args = vec!["--desktop-mcp".to_string()]; + if let Some(path) = journal { + args.push("--desktop-journal".to_string()); + args.push(path.to_string_lossy().to_string()); + } + // ALWAYS PASSED, never omitted when it happens to be the default. This + // server is a separate process and cannot see the flag the session was + // started with; leaving it off would mean the operator's `-p read-only` + // stopped at the process boundary, which is exactly the bug that made a + // read-only session able to type. + args.push("-p".to_string()); + args.push(mode.as_str().to_string()); + json!({ + "mcpServers": { + CLIENT_KEY: { + "command": exe.to_string_lossy(), + "args": args, + } + } + }) + } + + /// [`client_config`] as the compact JSON string a `--mcp-config` flag takes. + pub fn client_config_json( + exe: &std::path::Path, + journal: Option<&std::path::Path>, + mode: PermissionMode, + ) -> String { + client_config(exe, journal, mode).to_string() + } + + /// The same registration as `-c key=value` overrides, which is how Codex takes + /// it. + /// + /// Verified against the installed CLI: `codex mcp add --help` documents `-c` + /// as "Override a configuration value… The `value` portion is parsed as TOML", + /// and its own example passes an array — + /// `-c 'sandbox_permissions=["disk-full-read-access"]'` — so the `args` list + /// below is TOML, not JSON, and not a guess. + /// + /// Returned as pairs rather than a command line because the caller knows how + /// its own `Command` wants them. + pub fn codex_config_overrides( + exe: &std::path::Path, + journal: Option<&std::path::Path>, + mode: PermissionMode, + ) -> Vec { + // TOML basic strings take backslash escapes, so a Windows path must have + // its separators doubled or `C:\Users\…` becomes an invalid escape. This + // applies to the JOURNAL path too, which is also a Windows path — the + // exe is not a special case, the string syntax is. + let toml = |p: &std::path::Path| p.to_string_lossy().replace('\\', "\\\\"); + let args = match journal { + Some(path) => format!( + "[\"--desktop-mcp\",\"--desktop-journal\",\"{}\",\"-p\",\"{}\"]", + toml(path), + mode.as_str() + ), + None => format!("[\"--desktop-mcp\",\"-p\",\"{}\"]", mode.as_str()), + }; + vec![ + format!("mcp_servers.{CLIENT_KEY}.command=\"{}\"", toml(exe)), + format!("mcp_servers.{CLIENT_KEY}.args={args}"), + ] + } +} + +pub mod safety { + //! The kill switch (the crate's), with incode's `.incode/` folder handling on + //! the one function that creates a file. + + pub use incord_desktop::safety::*; + + /// Ask the desktop at this path to stop. + /// + /// [`incord_desktop::safety::request_stop`] behind incode's + /// `folders::create_dir_all`, so a stop file written into a fresh `.incode/` + /// brings that folder's `.gitignore` with it, as it did when this code was + /// in incode. Called by `serve::http`, `runtime::cancel` and `main.rs` + /// (`--desktop-stop`). + /// + /// # Errors + /// + /// Returns the I/O error. A caller must REPORT it rather than swallow it: a + /// stop request that silently failed is worse than no stop button at all. + pub fn request_stop(path: &std::path::Path) -> std::io::Result<()> { + if let Some(parent) = path.parent() { + crate::folders::create_dir_all(parent)?; + } + incord_desktop::safety::request_stop(path) + } +} + +/// incode's hook engine, as the desktop server's [`Hooks`]. +/// +/// The commands, their matchers, the shell they run in and the way they are +/// stopped at the time limit are all `crate::hooks::HookRunner`'s, unchanged. +struct OperatorHooks { + runner: crate::hooks::HookRunner, + pre_tool: usize, +} + +impl OperatorHooks { + fn outcome(ran: crate::hooks::HookRunResult) -> HookOutcome { + let messages = ran.messages().to_vec(); + if ran.is_denied() { + HookOutcome::deny(messages) + } else { + HookOutcome::allow(messages) + } + } +} + +impl Hooks for OperatorHooks { + fn pre_tool_count(&self) -> usize { + self.pre_tool + } + + fn run_pre_tool_use(&self, tool_name: &str, tool_input: &str) -> HookOutcome { + Self::outcome(self.runner.run_pre_tool_use(tool_name, tool_input)) + } + + fn run_post_tool_use( + &self, + tool_name: &str, + tool_input: &str, + tool_output: &str, + is_error: bool, + ) -> HookOutcome { + Self::outcome( + self.runner + .run_post_tool_use(tool_name, tool_input, tool_output, is_error), + ) + } +} + +/// `incode --desktop-mcp`: serve the desktop on stdio under `mode`, with the +/// limits, display and hooks `admin` holds, until the client goes away. +/// +/// Called by `main.rs` (`Parsed::DesktopMcp`) once it has loaded `admin.json`. +/// The whole of the work is [`cli::serve`]; what this adds is incode's: +/// +/// - the session's [`PermissionMode`] becomes the crate's [`Tier`] through the +/// word `-p` has always carried ([`Tier::from_mode_word`]); +/// - the operator's hooks are run by incode's own engine ([`OperatorHooks`]); +/// - the journal's folder is made with `folders::create_dir_all` first, so a +/// fresh `.incode/` gets its `.gitignore` before the server writes into it. +/// +/// # Errors +/// +/// What [`cli::serve`] refuses with, as text. +pub fn serve( + journal: Option, + mode: PermissionMode, + admin: AdminConfig, +) -> Result<(), String> { + if let Some(parent) = journal.as_deref().and_then(std::path::Path::parent) { + // Not fatal: a journal that cannot be written is a lost view of the + // work, not a reason to refuse it (`Journal::record`'s own contract). + let _ = crate::folders::create_dir_all(parent); + } + let hooks = admin.desktop_hooks; + let hooks: Option> = (!hooks.is_empty()).then(|| { + Box::new(OperatorHooks { + pre_tool: hooks.pre_tool_use.len(), + runner: crate::hooks::HookRunner::new(hooks), + }) as Box + }); + cli::serve(cli::ServeOptions { + // Every mode word incode emits is one the crate knows; failing closed + // costs nothing if that ever stops being true. + tier: Tier::from_mode_word(mode.as_str()).unwrap_or(Tier::Deny), + journal, + limits: admin.desktop_limits, + display: admin.desktop_display, + hooks, + name: "incode-desktop", + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::{json, Value}; + + /// The config has to name the flag that actually starts the server. + /// + /// If these two ever drift, the client launches the binary in its + /// NORMAL mode — which starts the interactive harness on a pipe, prints + /// human text to stdout, and looks to the client like a server speaking + /// gibberish. That is a long debugging session for a one-word mistake. + #[test] + fn the_client_config_launches_this_binary_in_server_mode() { + let config = mcp::client_config( + std::path::Path::new("C:/bin/incode.exe"), + None, + PermissionMode::WorkspaceWrite, + ); + let server = &config["mcpServers"][mcp::CLIENT_KEY]; + + assert_eq!(server["command"], "C:/bin/incode.exe"); + assert_eq!( + server["args"], + json!(["--desktop-mcp", "-p", "workspace-write"]), + "the config must pass the flag that selects the server mode" + ); + + // With a journal, the path is passed as its own argument — one the + // server can only receive this way, since it holds no workspace. + let watched = mcp::client_config( + std::path::Path::new("C:/bin/incode.exe"), + Some(std::path::Path::new("C:/work/.incode/desktop.jsonl")), + PermissionMode::ReadOnly, + ); + assert_eq!( + watched["mcpServers"][mcp::CLIENT_KEY]["args"], + json!([ + "--desktop-mcp", + "--desktop-journal", + "C:/work/.incode/desktop.jsonl", + "-p", + "read-only" + ]), + "the session's mode must reach the child process on its argv" + ); + + // The same string main.rs matches on, so a rename breaks here + // rather than at a client six months later. + assert!( + USAGE_FLAG_IN_MAIN.contains("--desktop-mcp"), + "the flag in the config no longer matches the one main.rs parses" + ); + } + + /// The flag `src/main.rs` parses. Kept beside the config that emits it. + const USAGE_FLAG_IN_MAIN: &str = "--desktop-mcp"; + + #[test] + fn the_config_is_valid_json_for_a_command_line() { + let text = mcp::client_config_json( + std::path::Path::new("/usr/local/bin/incode"), + None, + PermissionMode::WorkspaceWrite, + ); + let parsed: Value = serde_json::from_str(&text).expect("must be valid JSON"); + assert_eq!( + parsed["mcpServers"]["desktop"]["command"], + "/usr/local/bin/incode" + ); + // Compact, because it is passed as one shell argument. + assert!(!text.contains('\n'), "a multi-line config breaks the flag"); + } + + /// **The crate's tier and incode's policy must say the same thing.** The + /// server now runs the tier; `PermissionPolicy::for_desktop` stays as incode's + /// statement of the same table, and this is what keeps the two from + /// drifting: every mode, every one of the 16 tools, the same verdict and the + /// same words in a refusal. + #[test] + fn the_crates_tier_agrees_with_the_desktop_permission_policy() { + use crate::permissions::{PermissionOutcome, PermissionPolicy}; + let modes = [ + PermissionMode::ReadOnly, + PermissionMode::WorkspaceWrite, + PermissionMode::DangerFullAccess, + PermissionMode::Prompt, + PermissionMode::Allow, + ]; + for mode in modes { + let tier = Tier::from_mode_word(mode.as_str()).expect("a mode word"); + let policy = PermissionPolicy::for_desktop(mode); + for tool in permission::OBSERVING.iter().chain(permission::ACTING) { + let from_policy = match policy.authorize(tool, "{}", None) { + PermissionOutcome::Allow => Ok(()), + PermissionOutcome::Deny { reason } => Err(reason), + }; + assert_eq!( + tier.authorise(tool), + from_policy, + "{} on {tool}", + mode.as_str() + ); + } + } + } + + /// incode's hook engine reaches the server through the adapter with its + /// verdict intact: exit 2 refuses, and what the command printed is the reason. + #[test] + fn the_operators_hook_engine_refuses_through_the_adapter() { + let deny = if cfg!(windows) { + "cmd /C echo blocked: %HOOK_TOOL_NAME% & exit 2" + } else { + "echo \"blocked: $HOOK_TOOL_NAME\"; exit 2" + }; + let hooks = OperatorHooks { + pre_tool: 1, + runner: crate::hooks::HookRunner::new(crate::hooks::HookConfig { + pre_tool_use: vec![deny.into()], + ..Default::default() + }), + }; + let ran = hooks.run_pre_tool_use("click", "{}"); + assert!(ran.is_denied(), "{ran:?}"); + assert_eq!(ran.messages(), ["blocked: click"]); + assert_eq!(hooks.pre_tool_count(), 1); + } +} diff --git a/src/main.rs b/src/main.rs index 0e0e428..ed0e745 100644 --- a/src/main.rs +++ b/src/main.rs @@ -491,56 +491,13 @@ fn main() -> anyhow::Result<()> { &incord_code::admin::AdminConfig::default_dir(), ) .map_err(|e| anyhow::anyhow!("the desktop will not start: {e}"))?; - incord_code::desktop::limits::set( - admin - .desktop_limits - .resolve() - .map_err(|e| anyhow::anyhow!("the desktop will not start: {e}"))?, - ); - // Linux: the display comes FIRST, while this process is still one - // thread — attaching sets `DISPLAY`, which the input thread reads - // when it connects. Held until the server returns, so a private - // Xvfb lives exactly as long as the desktop it backs. - #[cfg(target_os = "linux")] - let _display = { - let display = incord_code::desktop::linux::attach(admin.desktop_display.as_deref()) - .map_err(|e| anyhow::anyhow!("{e}"))?; - eprintln!( - "incode-desktop on display {}{}", - display.name(), - if display.is_private() { - " (a private Xvfb, stopped when this server ends)" - } else { - "" - } - ); - display - }; - let input = incord_code::desktop::thread::InputThread::start() - .map_err(|e| anyhow::anyhow!("could not start desktop input: {e}"))?; - let hooks = admin.desktop_hooks; - if !hooks.pre_tool_use.is_empty() { - eprintln!( - "incode-desktop: {} pre-tool hook(s) will run before every action", - hooks.pre_tool_use.len() - ); - } - let mut server = incord_code::desktop::mcp::Server::new(input) - .with_permission_mode(permission_mode) - .with_hooks(hooks); - if let Some(path) = journal { - eprintln!("incode-desktop journalling to {}", path.display()); - server = server.with_journal(path); - } - - // Named on stderr so an operator who asked for `read-only` can see - // that it arrived. A capability restriction nobody can observe is - // one nobody trusts. - eprintln!( - "incode-desktop MCP server ready on stdio ({})", - permission_mode.as_str() - ); - incord_code::desktop::mcp::run_stdio(server)?; + // The server itself is the `incord-desktop` crate's (`incu serve` + // is the same code); this flag is its wrapper, so every agent + // config and installer that launches `incode --desktop-mcp` is + // unchanged. The limits, the Linux display and the hooks are + // `admin`'s; see `incord_code::desktop::serve`. + incord_code::desktop::serve(journal, permission_mode, admin) + .map_err(|e| anyhow::anyhow!(e))?; return Ok(()); } Parsed::Acp(config) => { diff --git a/src/permissions/mod.rs b/src/permissions/mod.rs index 0b9b347..8160ebb 100644 --- a/src/permissions/mod.rs +++ b/src/permissions/mod.rs @@ -196,8 +196,14 @@ impl PermissionPolicy { self } - /// The requirements for the tools this harness actually dispatches: the - /// twelve on the desktop MCP server. + /// The requirements for the sixteen tools of the desktop MCP server: five + /// that observe and eleven that move something. + /// + /// The server is the `incord-desktop` crate now, and it runs its own + /// `Tier` (`crates/desktop/src/permission.rs`), which it cannot take from + /// here. This stays as incode's statement of the same table, and + /// `desktop::tests::the_crates_tier_agrees_with_the_desktop_permission_policy` + /// fails if the two ever disagree. /// /// # Why the desktop is where this policy finally applies /// @@ -208,12 +214,13 @@ impl PermissionPolicy { /// ask on their behalf. /// /// The desktop server is different: it IS the dispatcher. - /// `desktop::mcp::call_tool` is a choke point in this crate's own process, - /// and every click, keystroke and screenshot passes through it. + /// `desktop::mcp::Server::call_tool` is a choke point in the desktop + /// server's own process, and every click, keystroke and screenshot passes + /// through it. /// /// # The split, and why it is only two rungs /// - /// The four observing tools need `ReadOnly`; the eight that move something + /// The five observing tools need `ReadOnly`; the eleven that move something /// need `WorkspaceWrite`. Not `DangerFullAccess`, even though a click /// reaches far outside any workspace — because `workspace-write` is the /// default mode, and putting the desktop above it would mean the feature diff --git a/src/wiring.rs b/src/wiring.rs index c300fa3..9bfaf33 100644 --- a/src/wiring.rs +++ b/src/wiring.rs @@ -62,7 +62,12 @@ use std::path::{Component, Path, PathBuf}; /// guarded one `use`, and it read split-out test files as production callers. /// Seeing again found `toolbox::Toolbox::set_permission_rules` and /// `ClaudeCodeBackend::{with_session, with_models}`, each reached only by tests. -pub const MAX_UNWIRED: usize = 41; +/// +/// It fell from 41 to 38 when the desktop moved to `crates/desktop`: this scan +/// reads incode's `src/` only, so the three uncalled items that were in +/// `src/desktop/` are no longer in what it counts. They were not wired by the +/// move. (The `Supervisor` entry below names one of them.) +pub const MAX_UNWIRED: usize = 38; /// A `pub` item nothing outside its own file calls. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]