Dizhan Xue b602de6bbf
feat(*): stream Mirasim turns over the running host's WebSocket (#996)
## Summary

The Mirasim adapter keeps one WebSocket connection to the Mirasim host
already running on the machine. It replaces the per-request `mirasim
ui-cli` processes and streams the host's session snapshots through ACP.

- Find the host through `RAVEN_MIRASIM_HOST` (`unix:<path>`, or a
  loopback port as `<port>`, `127.0.0.1:<port>`, `localhost:<port>` or
  `[::1]:<port>`, connected to as named), else the remote host's Unix
  socket (Linux and macOS), else the desktop app's loopback port and its
  token file. Tokens travel in headers. The adapter never requests
  `ready` or `getConfig`, whose answers contain settings and
  credentials. The WebSocket upgrade is bounded by the connect timeout.
- Stream text, thoughts, tools, sub-agents, plans, delivered files,
  usage and accepted steers. Reconnect with backoff, resubscribe
  sessions, and take a fresh snapshot when patches have a sequence gap.
- Live patches carry no segments; only settled history turns do. Within
  one patch a call already shown settles before the text after it, and
  a new call follows the text before it. A snapshot taken whole, on
  subscribing, after a gap or when a queued turn is dispatched, puts its
  calls before its text, so the answer after a call stays one message.
  History replays in its segments' order, using the host's UTF-16
  offsets.
- Support new, load with complete history replay, resume without
  replay, list, close and delete. A turn running in the app while a
  session loads is forwarded after the replay. Lists cover this agent's
  conversations in the given directory, ones begun in Mirasim included.
  Delete also removes the Mirasim conversation. A conversation the host
  refuses to continue, deleted or not one of its own, is started again
  once, with a note saying why. A list or history request the host
  fails is refused at once with its reason, and history paging stops if
  the host hands back a page it already gave.
- Cancel running tasks with `stop` and queued prompts with `recall`.
  Prompts accepted after timeout remain tracked for cleanup and session
  persistence. Failed or unconfirmed steers are recalled; if they
  started their own task, that task is stopped by id. A prompt still in
  the host's queue when the connection comes back is recognised from
  the queue the host lists on resubscribe.
- Relay approvals and questions of turns Raven started through ACP
  permission and elicitation requests; questions in turns Mirasim starts
  are left to the app. Claude receives inline images; other agents get
  an image linked as a local file as its path, and refuse inline ones.
  Claude, Codex, DSH, Pi and ZCode support steering. Turns started in
  Mirasim are forwarded while the adapter holds their session.
- Refuse queued prompts after session close or adapter shutdown. Every
  local ACP agent whose tree a Windows Job or POSIX process group owns
  gets an EOF grace that ends as soon as the agent exits. An agent may
  ask for a longer one under `agentCapabilities._meta` as
  `raven.shutdownGraceS`, granted up to five seconds; the Mirasim
  adapter asks for five, so a first prompt the host accepts late is
  still stopped. A close cancelled during the grace still releases the
  connection. PID-only cleanup keeps the launcher alive for the
  process-tree walk.
- The question of which agents Mirasim has runs in the environment the
  presets' adapters get: the login shell's on Linux and macOS, Raven's
  own on Windows. With no host reachable it lists none, and the boot
  handshakes no Mirasim preset except a row that sets
  `RAVEN_MIRASIM_HOST` or `MIRASIM_HOME` in its own `env`.
  `readyTimeoutMs` is 150000, above the adapter's own connect and menu
  limits.

The old `uicli.py` and `guard.py` transport is removed. Existing binding
files remain readable. The agent-integration documentation is updated
in English and Chinese. The Windows ACP job exercises the loopback
transport, real preset subprocesses and teardown. The live suite claims
a slot directory of its own by a lock, sweeps only that slot, and checks
the model each turn ran on.

`scripts/check_mirasim_frames.py` checks a host bundle for the frames
and fields the adapter uses. Run against the bundle that last worked, it
also reports each of those names that now occurs fewer times, which is
how a frame renamed in one of several places shows.

Protocol details verified against the host bundles 0.0.537, 0.0.547 and
0.0.558: `listSessions` filters by workdir, `getHistory` pages
backward, any prompt can set the session's route, there is no
unsubscribe frame, a request whose handler throws is answered with an
error carrying its `reqId` as `clientRef`, and live patches never carry
`segments`. Deleting a Mirasim conversation leaves the underlying
agent's transcript files intact.

## Type

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

## Verification

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

Final local verification ran on Linux with Python 3.12.13 at the head
of this branch. Temporary report paths are abbreviated as `$CHECKS`.

```sh
PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
  tests/test_acp_mirasim_catalog.py tests/test_acp_mirasim_host.py \
  tests/test_acp_mirasim_input.py tests/test_acp_mirasim_interactions.py \
  tests/test_acp_mirasim_server.py tests/test_acp_mirasim_store.py \
  tests/test_acp_mirasim_stream.py tests/test_check_mirasim_frames.py \
  tests/test_subagent_mirasim.py tests/test_acp_client_teardown.py \
  tests/test_acp_windows.py tests/test_acp_client_launch.py \
  tests/test_acp_client_resume.py tests/test_subagent_probe.py \
  tests/test_subagent_third_party.py tests/test_subagent_acp.py \
  tests/test_acp_protocol.py \
  -n 0 -q --tb=short --idle-ceiling-strict -p no:cacheprovider \
  --cov=raven --cov-branch \
  --cov-report=json:$CHECKS/coverage.json \
  --junitxml=$CHECKS/regression.xml
# 1060 passed; no failures, errors, skips, or strict-idle violations

uv run --frozen --no-sync python scripts/coverage_gate.py \
  --coverage-json $CHECKS/coverage.json \
  diff --base-ref origin/main --threshold 90
# 99.20%: 1362 of 1373 executable changed lines

UV_NO_SYNC=1 make lint-python lint-types
# Ruff check/format: 2384 files; ty passes
uv run --frozen --no-sync lint-imports
# 10 contracts kept
uv run --frozen --no-sync deptry raven
# No dependency issues
uv run --frozen --no-sync pre-commit run --files <changed files>
# All applicable hooks pass
UV_NO_SYNC=1 make check-commits check-large-files check-source-language
# commitlint, commit messages, assets and source language pass
git diff --check origin/main...HEAD
# Exit 0
UV_PROJECT_ENVIRONMENT=$CHECKS/docsenv uv run --frozen --group docs \
  --no-dev mkdocs build -f docs-site/mkdocs.yml --strict -d $CHECKS/site
# Built

for v in 0.0.537 0.0.547 0.0.558; do
  uv run --frozen --no-sync python scripts/check_mirasim_frames.py \
    ~/.mirasim-remote/servers/$v/server.cjs \
    --against ~/.mirasim-remote/servers/0.0.537/server.cjs
done
# Each: 13 sent frames, 11 read frames and 64 fields present,
# none fewer than in 0.0.537

PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
  tests/integration/test_acp_mirasim_real_llm.py \
  -m integration -n 0 -q -p no:cacheprovider -rA --tb=short
# 10 passed in 346 s against the Mirasim host 0.0.537 running
# on this machine; every turn ran on glm-5.3-flash
```

Each new regression test was observed failing before its repair: the
refused unknown conversation, the reconnect with a prompt still queued,
the tool that ran while the connection was down, the turn running in
the app during a load, the repeated history page, the failed list and
history, the upgrade that never answers, the descendant holding the
agent's stdout, the close cancelled during the grace, the first prompt
the host accepts after the grace has passed, the empty agent list with
no host, the ready budget, and the frame check's count drop. The
stand-in host now hands frames to its dispatcher concurrently, as the
host does; removing the adapter's late recall makes three tests fail.
The frame check reports, against 0.0.537, copies with the dispatcher's
`stop` case renamed (6 occurrences, then 5), the six patch frames
renamed, and `coalesceMs` renamed; presence alone passed all three.

The local pass used the loopback stand-in host and real subprocess
tests; the live-model suite then ran against the Mirasim host already
running on the machine, across claude, codex, pi and zcode. Native
Windows and macOS were not run for this revision; the Windows ACP CI
job runs the four adapter test files natively.

## Risk

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

- Mirasim presets need a reachable host. Preset discovery still checks
  for `mirasim` on the login PATH; a desktop-only install without that
  executable does not offer the rows. The adapter's old `--executable`
  argument is removed.
- The adapter is one more client of the user's own host: Raven's turns
  show live in the Mirasim app and on paired phones, queue behind the
  user's own turns on the same conversation, and end if the desktop app
  closes or the host restarts. Turns the user starts in Mirasim on a
  conversation Raven holds are forwarded to Raven as turns nobody
  prompted.
- Removing an ACP instance now deletes its Mirasim conversation as well.
  Loading a session replays its complete history. The host has no
  unsubscribe operation.
- The desktop token is sent to the configured loopback endpoint, as
  with `ui-cli --port`; discovery relies on the local token file and
  port.
- Every local ACP agent's EOF grace now ends when the agent exits
  rather than when its pipes close; an agent can ask for up to five
  seconds. An unreachable host, abrupt parent death, or an adapter that
  cannot finish within its grace can still prevent cancellation of work
  owned by the shared host.
- Known limit: a queued prompt the host dispatches while the connection
  is down is not recognised as this adapter's after it reconnects; it
  is given up after 60 seconds and its turn runs on, forwarded as one
  nobody prompted.
- Rollback: revert the squash commit to restore the per-request
  transport. No binding migration is required. Conversations already
  deleted from Mirasim are not restored by reverting code.

## Related Issues

N/A
2026-10-19 14:28:09 +08:00
..

Raven operational scripts

Standalone CLIs and admin utilities. Not part of the Raven wheel — these scripts are invoked directly from a checkout and don't ship to end users.

Layout

scripts/
├── README.md                     This file.
├── boxlite_cli.py                Direct CLI for the boxlite microVM library.
└── check_mirasim_frames.py       Check a Mirasim host bundle for the frames the Mirasim adapter uses.

When to use

Script Purpose See
boxlite_cli.py Manage boxlite OCI images + VMs (pull / ls / create / start / stop / rm / shell). Independent of Raven — works even when no agent is running, can inspect VMs owned by another boxlite home. docs/sandbox/boxlite_cli.md
check_mirasim_frames.py After Mirasim updates, check that its host still names every frame and field raven/acp/mirasim/ speaks. Run it --against the bundle that last worked: a name renamed in one of the places that say it then shows as occurring fewer times, which presence alone cannot see. Reads the bundles as text and never runs them; exits 1 naming what is missing or fewer, 2 when a bundle cannot be read. the module docstring

scripts/boxlite_cli.py is complementary to the raven sandbox sub-command group (in raven/cli/sandbox_commands.py):

  • raven sandbox … — agent-runtime debug interface (Unix-socket connection to a SandboxDebugServer inside a running Raven process; only sees VMs owned by that process).
  • scripts/boxlite_cli.py … — direct boxlite library CLI (manages images, creates / cleans up VMs, can target any boxlite home dir).

Use raven sandbox when you want to inspect / shell into the VMs your live agent is currently using. Use scripts/boxlite_cli.py for everything else (image management, post-mortem cleanup, cross-process inspection, Raven-not-running scenarios).

Where fixture generators live

Test / benchmark data generators are NOT in scripts/ — they live alongside the benchmark or test that consumes them. Examples:

  • benchmarks/skill_evals/fixtures/build_mock_library.py — synthetic SQLite mass-library DB for test_skill_forge_e2e.py and skill_evals/run_eval.py.