Handsome-wzw 829eb28e1d
feat(*): build the ssh launch line and remote workdir for an agent on a registered machine (#893)
## Summary

First of a series of changes that let an ACP sub-agent run on a machine
in the
machine registry (`connections.json`), reached over ssh, so one turn can
dispatch work to agents on several machines at once.

The approach was measured first, on two registered Linux machines and
without changing code: raven's own `AcpClient`, started on an `ssh`
line,
already drives a remote `claude-agent-acp` and `qwen --acp` (handshake,
`session/new`, `session/cancel`, 10 connections at once), and a remote
agent exits once the local ssh is killed -- idle within 15 s, and mid
tool call within 2 s, its child command included. What breaks is
everything that assumes the agent shares this disk; the first of those
is that an agent refuses a `cwd` that does not exist where it runs
(`-32602 cwd does not exist on the machine running the agent`).

This change adds the pieces only a remote agent needs, with nothing
calling them yet:

- `raven/acp_client/remote.py`
  - `machine(id)`: the registered ssh machine. Refuses an unknown id, an
    unreadable registry, an entry with a blocking problem, and a local
    row, each in one sentence. Looked up in the caller, the way the
    machine channel looks one up, since main keeps the registry's
    readers to what its callers need.
  - `launch_command()`: the ssh line, as the one string the pool and
    `AcpClient` already take as a command (`shlex.join`, so their
    `shlex.split` gives back the argv). Built from the registry at
    launch and never stored, so no address, port or key path reaches a
    config file, log line or model. The agent starts in the machine
    user's login shell (`$SHELL -lic`): measured, agents installed
    through nvm or into `~/.local/bin` are on that PATH and no other.
    The remote command is one argv element after `--`, quoted once per
    shell that reads it -- the hand-written form
    `ssh host -- bash -lic 'qwen --acp'` loses `--acp` to the far
    shell's re-parse and hangs to the initialize timeout.
  - `ssh_log_path()` / `read_ssh_log()`: ssh's own messages name the
    address ("connect to host <ip> port <n>", and on a first connect
    "Permanently added '[<ip>]:<n>'"). The launch line sends them to an
    owner-only log per agent (`ssh -E`) instead of to stderr, which the
    connection journals and quotes in its errors; they are read back
    only to classify a failure. Measured: with `-E`, stderr carries the
    far side's output and nothing of ssh's.
  - `session_dir()`: `<root>/<handle>` made on the machine and resolved
    to an absolute path in one round trip (0.17 s measured). A directory
    the machine will not make is reported with the machine's own last
    word -- measured on a registered machine whose disk had filled, "No
    space left on device" -- skipping any line that carries the address.
  - `explain()`: one sentence for an ssh-level failure (timed out,
    unreachable, login refused, host key changed, agent not installed),
    naming the machine and never its address.
- `raven/ops/transport.py`: the ssh options move into `ssh_argv()` and
  the row's address into `ssh_target()`, so the one-shot runner and a
  remote agent share one spelling. The runner sends the same argv as
  before; a new test pins it.
- `docs/specs/2026-08-11-acp-local-agent-mesh-design.md`: its "remote
  agents" non-goal carries a dated amendment pointing at `remote.py`.
  ACP still runs over stdio only; the local process is ssh.

The next change (#897) wires this into the ACP backend behind a
`machine`
field on an agent's entry. Later changes add a small Raven process on
each registered machine that
reads and writes files there for this one, so the main agent can read a
remote file's lines without copying the file; scp-style remote paths for
the file tools; and `machine` on `subagents.add`.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `uv run pytest tests/test_acp_remote.py tests/test_ops_transport.py
tests/test_ops_connection_add.py tests/test_shell_machine_channel.py
tests/test_ops_connections.py`
  -- all passed. The quoting cases run the remote command through real
  shells here (`sh -c` standing in for sshd, `$SHELL -lic` for the login
  shell, `HOME` in a temp dir): the agent's own arguments arrive intact,
  a variable valued ``a b 'c' "d" $HOME `id` \e`` arrives unexpanded,
  a `~` root with a space in it is made and entered, a relative root
  comes back absolute from the login's home, and an agent on the PATH
  only a login shell's `.profile` sets is found.
- The same generated command run under dash on a registered Linux
  machine: same argv, cwd and value.
- Real machines, through `remote.py` and raven's `AcpClient`, against a
  scratch registry (not `~/.raven`): the session directory was made and
  resolved on the machine, `claude-agent-acp` answered `initialize` and
  accepted `session/new` in that directory; a machine that does not
  answer, an unregistered id, a wrong key and an agent that is not
  installed each came back as one sentence with no address in it. The
  remote test directory was removed afterwards and no process was left.
- `uv run pytest --ignore=tests/integration --idle-ceiling-strict` --
  27800 passed, 119 skipped, 3 failed:
  `test_rpc_files.py::test_a_host_without_libreoffice_says_so`,

`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
  and

`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`,
  which fail the same way on main on this machine.
- Diff coverage over the changed lines: 99% (the gate asks for 90).
- Twenty mutations, each reverting one part of the change, each
  turning a test red: the machine's reason dropped, the line carrying
  the address kept, the inner command not quoted for the outer shell,
  the variable assignments not quoted, `-T` dropped, `--` dropped, the
  extra options placed after the destination, the runner's host-key
  option dropped, ssh's own words passed on, the host-key failure not
  recognised, an unsafe handle kept without its digest, a slash allowed
  in a handle, a local row accepted as a remote machine, an entry with a
  blocking problem accepted, the session directory echoed instead of
  resolved on the machine, a failed `mkdir` taken as success, a `~` root
  quoted so the shell cannot expand it, the agent not started in the
  root, a bad variable name let through, and the agent started outside
  the login shell
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
  and `scripts/check_large_files.py` on the branch range, and the
  prospective squash header and the commit through `commitlint` -- all
  clean

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Nothing user-facing changes yet: no entry can name a machine until the
next change.

## Risk

No behaviour change. `remote.py` has no caller yet, and the one-shot
ssh runner sends the same command line as before, pinned by a test. The
launch line carries the machine's address, which is why it is built at
launch and held only in memory; variables travel on that line too, so
the design keeps secrets off it (no lent keys for a remote agent).
Rollback is a plain revert.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-12 16:09:09 +08:00
..