## 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
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 fortest_skill_forge_e2e.pyandskill_evals/run_eval.py.