Skip to content

feat: act on another machine's services from the CLI and MCP - #97

Merged
teo-goulois merged 3 commits into
mainfrom
feat/remote-cli-and-mcp
Nov 9, 2026
Merged

teo-goulois merged 3 commits into
mainfrom
feat/remote-cli-and-mcp

Conversation

@teo-goulois

@teo-goulois teo-goulois commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

PR 5 of remote machines: the contract's "CLI" and "MCP" sections of docs/remote-machines.md. The daemon already did the work for the app (#72, #81, #83, #84); this adds the CLI layer and the agent tools on top.

CLI

  • --machine <name|id> on services status, logs, dev, stop and restart.
  • Resolving the machine: an exact id, then an exact name ignoring case, among active machines (pins of machines that left the account don't count). A name shared by two machines differing only in case lists both with their ids. An unknown name lists the roster. This machine's own id or name acts locally; dev then runs as --in-app, since the options --machine allows are exactly the ones --in-app takes.
  • Resolving the service: primary checkout unless --env; a name in two projects needs --project and lists the matches.
  • dev --machine refuses a command after --, --detach, --in-app, --env-file, --confirm-profile, --domain, --replace, --no-masking and the hidden launch flags, before asking the daemon (refused_argument, exit 2).
  • Controls: the daemon sends a control only over an open session, so the CLI holds a remote_watch open. Its first snapshot gives the expect. A control the snapshot already refuses (per controls, or a live legacy run, which the app relaunches after a confirmation) isn't sent. A legacy run that already stopped is only a record: the target's controls decide.
  • Output: human on a terminal, JSON otherwise. Progress comes first (on stderr in JSON mode), then the result.
    • A refusal prints the "Errors" message, mirrored from the app's remoteErrorMessage (no Rust copy existed to share), and exits 2.
    • unknown is a progress line ("Outcome unknown. Checking B…"). lost prints the fresh status and exits 3, as the contract says.
    • A conflict prints "B changed in the meantime." with the service's fresh state (status in JSON), exits 2, and is never resent.
    • A run that failed exits 1.
  • logs --machine: the last --lines, --cursor <runId>:<offset>, and -f. It prints the next cursor as local logs does. When the service restarts (gone), during -f or racing the first read, it reads the service's current run from the target's snapshot and goes on from offset 0.

Daemon and client

  • remote_inventory and remote_output_read errors now carry their code on the management socket.
  • New DaemonConnectionError::Remote { code, message }, so targets' codes reach the CLI and agents.

MCP

  • New read-only list_machines tool (machines --json).
  • machine on list_services, service_status, service_logs, service_start, service_stop and service_restart, and on no other tool. With it, cwd is ignored. Any other tool given machine fails before building or running anything, instead of acting on this machine. list_services and service_status both map to services status --machine.
  • service_start with machine fails on background, env_files, confirm_profile, command, domain and replace, saying the target decides how its services start. It needs service and never creates a project.
  • control_disabled and background_disabled add a hint to ask the user to allow controls. lost adds a hint to check service_status first.
  • The instructions' new "Other machines" paragraph went through unslop.

Docs

Pairing over SSH (docs/remote-cli-and-agent-pairing) is untouched. This branch starts from main, not from that branch.

Tests

  • Unit: machine resolution (id, name, case collision, unknown, self, signed-out pins), service resolution, refusal JSON vs human with exit 2, lost with fresh status and exit 3, failed exit 1, progress, snapshot pre-checks, cursors, and each MCP tool's machine argument and refusals, including cwd being ignored, every other tool refusing machine without running, a stopped legacy run allowing a start, and a conflict with its fresh state.
  • End to end (src/daemon/remote/tests/cli.rs): the CLI layer against a real management socket served by viewer A's link, with B on the fake relay. Covers resolving, status, logs tail, cursor and follow to the end of the run, a follow that goes on with the run replacing a restarted one, a restart between the snapshot and the first read, a stop with its progress, and a control_disabled refusal that sends nothing.
  • Binary (tests/remote_cli.rs): dev --machine refusals exit 2 with JSON.
  • Checks: cargo fmt, cargo clippy -- -D warnings and cargo test pass. tests/app_bridge.rs failed once on its known timing flake and passed on rerun.
  • Clippy: the larger Dev variant needed #[allow(clippy::large_enum_variant)] on the clap Commands enum.

PR 5 of remote machines (docs/remote-machines.md, "CLI" and "MCP"). The
daemon already viewed and controlled other machines for the app; a
terminal and an agent can now do the same.

- `--machine` on `services status`, `logs`, `dev`, `stop` and `restart`.
  It resolves an exact id, then an exact name ignoring case, among the
  active machines; this machine's own id or name acts locally. A service
  must be unique on the target or come with `--project`.
- `dev --machine` refuses every option but `--project`, `--env` and
  `--profile` before asking the daemon anything.
- A control holds a watch open, since the daemon sends one only over an
  open session, and its first snapshot gives what the control expects.
  What that snapshot already refuses is not sent.
- Human output on a terminal, JSON otherwise. A refusal says what the app
  says for its code and exits 2; an outcome that never came back prints
  the fresh state and exits 3; a run that failed exits 1.
- `remote_inventory` and `remote_output_read` errors now carry their code
  on the management socket, so the CLI and agents see it.
- MCP: `list_machines`, and `machine` on the six service tools; with it,
  `cwd` is ignored and `service_start` takes only service, project, env
  and profile. Refusals of controls and lost outcomes tell the agent what
  to do next.
A Codex review of the remote CLI and MCP found four ways a request could
act on the wrong run or the wrong machine, or say less than the contract
asks:

- MCP tools without a `machine` argument ignored one and ran here, in the
  server's folder. They now refuse it before building or running anything.
- A legacy run that had already stopped blocked a fresh start the target
  allowed. Only a live legacy run is refused before sending; otherwise the
  target's `controls` decide.
- `logs --machine --follow` stopped when the service restarted. On `gone`,
  it now reads the service's current run from the target's snapshot and
  follows it from offset 0, and a restart racing the first read is read
  the same way.
- A `conflict` printed only "B changed in the meantime." It now prints the
  service's fresh state with it, in text and JSON, still exits 2, and never
  resends the control.

docs/remote-machines.md says `dev` on this machine's own id behaves as
`dev --in-app`, and records the four behaviours above.
…and keep the watch through a conflict's report

After a restart between the snapshot and the first read, `logs --machine`
without a cursor tailed the new run, so a run longer than --lines lost its
first lines although the note said it was read from the start. And the
control's watch was dropped before the report fetched the fresh state, so
a conflict's state could need a new handshake or go missing.
@teo-goulois
teo-goulois merged commit 97cadcd into main Nov 9, 2026
4 checks passed
@teo-goulois
teo-goulois deleted the feat/remote-cli-and-mcp branch November 9, 2026 21:40
teo-goulois added a commit that referenced this pull request Nov 9, 2026
Brings in --machine for the CLI and MCP (#97).

- docs/remote-machines.md: keeps #97's CLI output and MCP snapshot text and
  #98's pairing over SSH exceptions.
- src/cli/machines.rs: machines() now takes the management client, so the
  SSH pairing passes ctx.mgmt_client.
- The CLI's --machine end-to-end test holds a session between A and B and
  checks that both agree on the latest protocol (3, pair.saved, or later)
  for the whole run. The CLI and MCP code from #97 never checks the
  session version, so nothing else needed to change.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant