Raven-1/tests/test_ui_agent_marks.py
Dizhan Xue 547c1aba5e
feat(*): reach Mirasim's agents as ACP sub-agent presets (#971)
## Summary

Connect the coding agents Mirasim runs as Raven ACP sub-agents, with one
bundled preset per agent and no separate adapter download.

- Serve Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok
  Build, DSH, Pi and ZCode CLI through `mirasim ui-cli`. The adapter
  runs on Raven's interpreter, so a Mirasim preset is not offered on a
  registered machine, and a stored row whose interpreter is gone is
  pointed at the running one when the config is next read. It withholds
  session MCP because ui-cli does not accept per-session servers. The
  boot capability backfill asks Mirasim once which agents it has
  installed and handshakes only those.
- Read model and effort choices from Mirasim. Offer the own models of
  Claude Code, Codex, Kimi Code and ZCode CLI on both their own-account
  and Mirasim platform routes. Persist conversation bindings and switch
  routes before continued turns. A menu read that fails is tried again
  after a short pause rather than kept for the cached copy's lifetime,
  an effort the menus in hand do not offer is read again before it is
  refused, and a failed menu read still reports the agents installed
  since the last one. A connect or test whose handshake could not read
  the menus keeps the ones already measured, and connecting an agent
  with a model refuses one its measured menu does not offer, as editing
  one already did.
- Retain the last model catalog when a refresh fails. Deleting a session
  prevents later writes, prompts, loads and route switches, waits for an
  already-running store write, and does not wait for unrelated catalog
  work. A turn, and its cancel, uses the catalog in hand instead of
  queueing behind another session's read.
- Relay questions and tool approvals through ACP. Content returned by
  another agent retains that agent's redaction policy, including values
  matching Raven's configured credentials. The rule covers Mirasim,
  shared sub-agent records and announcements, delegated tool results,
  A2A replies, logs, main-agent context, live ACP updates and session
  replay. Provenance is decided per result: a tool's declaration admits
  it to carrying another agent's content, and each result that does
  claims it, so a delegating tool's own errors, receipts and status
  lines stay Raven's text under the local scrub, and no result can claim
  provenance its tool never declared. Forwarding through `tool_call`
  carries a result whole for every tool, so a refusal reached that way
  ends the turn as a direct call does. The contract surface version is
  incremented for the added provenance fields. Local tool-result
  protections, outbound credential handling, permission checks and
  untrusted-content fencing retain their existing roles.
- Group unconfigured Mirasim presets into one card. Connect each member
  with its selected model in one write. Missing members open the
  existing installation and recheck flow, and a member whose handshake
  was refused for want of a sign-in is named in the drawer as it is on
  its card. A family whose members sit in two sections of the agents
  page draws one card in each. Narrow drawers keep the agent name and
  place the model and action on a second row.
- Guard command processes and clean up their descendants on
  cancellation, including ones a tool starts in a session of its own
  while the agent ignores SIGTERM: on Linux the guard adopts them as a
  child subreaper, and the process tree is read again before SIGKILL. A
  guard that outlasts its drain no longer replaces the command's own
  error with a shutdown traceback. Stage oversized prompts within the
  full Windows command-line budget, counting the venv launcher's second
  launch, refuse a `mirasim` that resolves to a `.bat` or `.cmd` shim,
  and preserve percent escapes and UNC authorities in file attachments.
  The guard starts without the ACP package, polls its command's exit
  quickly at first and then slowly, and the adapter's stderr log carries
  no local variables.
- Share the existing ACP stdin reader with the adapter, and update the
  integration docs, domain vocabulary, translations and agent-mark
  attribution.

## Type

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

## Verification

Rebased onto current main and reran validation on Linux with Python
3.12.13 and Node 22.23.2. The isolated interpreter resolves this
checkout even when a subprocess clears PYTHONPATH. Existing dependencies
were reused without changing their declarations or lockfile. In the
commands below, `$CHECKS` denotes the temporary result directory used
for the run. Both Python selections use the same
`COVERAGE_FILE=$CHECKS/post-rebase.coverage`.

```sh
uv run --frozen --no-sync pytest tests/test_agent_loop_*.py tests/test_acp_mirasim_*.py tests/test_tool_registry_*.py tests/test_subagent_acp*.py tests/test_subagent_activity.py tests/test_subagent_history.py tests/test_subagent_manager.py tests/test_subagent_probe_state.py tests/test_security_untrusted_context.py tests/test_tool_admission.py tests/test_tool_search.py tests/test_cli_log_file.py tests/test_acp_journal.py tests/test_a2a_client_tool.py tests/test_subagent_mirasim.py tests/test_subagent_probe.py tests/test_subagent_third_party.py tests/test_ui_agent_marks.py tests/test_acp_replay.py tests/test_acp_updates.py tests/test_rpc_console.py tests/test_rpc_system.py -n 0 -x -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml --junitxml=$CHECKS/post-rebase-python.xml
# 2871 passed
uv run --frozen --no-sync pytest tests/test_contracts_*.py tests/test_tool_admission.py tests/test_tool_registry_execute.py tests/test_security_untrusted_context.py tests/test_config_loader.py tests/test_raven_config_tool.py tests/test_rpc_subagents.py tests/test_subagent_name_vocabulary.py tests/test_tool_refusal_continuation.py -n 0 -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-append --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml
# 487 passed, 1 skipped (POSIX directory permissions are not enforced for root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $CHECKS/post-rebase-coverage.json diff --base-ref origin/main --head HEAD --threshold 90
# 93.33%, 1594/1708 executable changed lines; passed
```

The full Python suite, `uv run --frozen --python 3.12 --all-extras
pytest -q`: 9 failed, 32315 passed, 176 skipped, 2 xfailed. Each failing
id is then run by id against a clean archive of the merge base, through
the same interpreter and extras and with the imported `raven` checked to
resolve inside the archive; every id that fails here also fails there.

The catalog-only failure and resumed-session deletion regressions failed
before their fixes. Additional tests exercise deletion during catalog
reads, store writes and route lookups. The content-policy tests failed
against the former redaction behavior and now check exact content
through direct calls, tool_call, the main provider, recorded frames,
persisted transcripts and ACP replay. Local file reads and outgoing
credential records remain covered by controls.

In ui-web:

```sh
npm test -- --no-file-parallelism
# 250 files, 3977 tests passed
npm run gen:check
npm run type-check
npm run lint
npm run build
# passed; lint has four warnings in unchanged files
```

Chromium checks used the actual page and styles with synthetic agent
rows. Model selection travels in the connect request; Escape closes only
the picker; missing members reach the download link and Check again. At
390px and 320px the name columns measure 252px and 182px, respectively,
with no horizontal overflow in the drawer. No page errors were reported.

```sh
make check-commits check-large-files check-source-language
# passed
npm run lint:i18n --prefix ui-tui
npm run lint:rpc --prefix ui-tui
# passed
uv run --frozen --no-sync python -m pre_commit run --from-ref origin/main --to-ref HEAD
```

The full-PR pre-commit run passes except prettier (ui-tui), which flags
`src/components/newInstancePicker.tsx` and
`src/components/subagentsHub.tsx`. Both files are byte-identical to
main; running the formatter against their main contents fails too. The
fixes do not touch either file. Commit-scoped hooks for the new changes
pass. Ruff check and format, ty on changed production files, all ten
import contracts, and whitespace checks pass. Every replayed commit
retains its patch, and the PR title and body pass the repository's ASCII
and commit-message grammar checks.

The earlier native Windows verification covers prompt launch limits and
file-URI conversions. This follow-up has no new native Windows, real SMB
or live vendor/provider run.

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

## Risk

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

Credential authorization and scope belong at the point where access is
granted. Redacting a later reply cannot revoke access the receiving
agent already has. Under this product policy, Raven preserves returned
content unchanged and leaves redaction decisions to the sending agent.
Credentials an agent includes in its reply can therefore remain in
Raven's retained logs and transcripts.

Agent-returned content is preserved according to the sender's policy
across all supported delegation paths. The adapter returns each reply
when the turn settles rather than streaming it. Short prompts use
command-line arguments; oversized prompts use temporary attachments.
Connecting an agent probes it: with a model chosen, on that model's own
route, so the pick a connect carries is proved before the row is stored;
with none, on the agent's default. Compatibility was originally measured
against Mirasim 0.0.465; older CLI versions have not been verified.

A stored Mirasim row whose interpreter no longer exists is rewritten in
the config file, once, by the first Raven to read the config after that
interpreter is gone. A row naming another interpreter that still exists
is left as written, so two installs reading one config do not rewrite it
back and forth.

Rollback is a revert. Configured Mirasim rows then need removal because
their bundled adapter is no longer present, and until they are removed
Raven refuses to load the config at all: an unknown preset name fails
validation, so the host does not start and the file has to be edited by
hand.

## Related Issues

N/A
2026-10-17 14:31:43 +08:00

179 lines
7.7 KiB
Python

"""Every third-party sub-agent preset has a brand mark, and every tone on it is true.
The roster draws a brand mark per agent, chosen by preset key. The preset list
lives in Python and the mark table lives in
``ui-web/src/components/AgentMark.tsx``, so nothing in either language can notice
when they disagree: adding a preset leaves its row wearing the generic glyph,
and renaming a file leaves a row addressing a 404. Both are invisible in
review and neither breaks a build.
This is also the only gate over that table that runs on a merge request.
GitLab's ``tests`` job runs the Python unit suite and nothing else -- the
stylesheet and DOM guards beside this one are vitest and node, which that
image does not have (see ``tests/test_ui_css_token_gate.py``).
The ``tone`` is derived from the file rather than trusted. It says how the SVG
answers the theme, and the dark theme filters each tone differently, so a wrong
one renders as a black mark on a black surface or as a recoloured brand:
- absent: every shape carries its own fill. Theme-independent, filtered not at
all.
- ``mono``: every shape draws in ``currentColor``, which an ``<img>`` resolves
against the SVG's own document and so renders black. Inverted wholesale.
- ``hybrid``: some shapes do and some do not. Inverted with the hue rotated
back, or the brand colour inverts along with the adaptive tone.
"""
from __future__ import annotations
import re
from pathlib import Path
from raven.agent.subagent.presets import THIRD_PARTY_SUBAGENT_PRESETS
_ROOT = Path(__file__).resolve().parents[1]
_TABLE = _ROOT / "ui-web" / "src" / "components" / "AgentMark.tsx"
_ASSETS = _ROOT / "ui-web" / "src" / "assets" / "agents"
_ENTRY = re.compile(
r"^\s{2}(\w+):\s*\{\s*file:\s*'([^']+)'(?:,\s*tone:\s*'(mono|hybrid)')?\s*\},?$",
re.MULTILINE,
)
_OWN = re.compile(r"^const OWN_MARK: \{ file: string \} = \{ file: '([^']+)' \}$", re.MULTILINE)
_GROUP = re.compile(r"^const GROUP_MARK: \{ file: string \} = \{ file: '([^']+)' \}$", re.MULTILINE)
_SHAPE = re.compile(r"<(?:path|rect|circle|ellipse|polygon)\b[^>]*>")
def _marks() -> dict[str, tuple[str, str | None]]:
"""The mark table as the stylesheet and the roster see it.
Read out of the source rather than executed: a Python suite cannot import
a tsx module, and the alternative -- restating the table here -- would be
the very duplication this file exists to catch.
"""
body = _TABLE.read_text(encoding="utf-8")
start = body.index("const MARKS")
end = body.index("\n}", start)
found = {key: (file, tone or None) for key, file, tone in _ENTRY.findall(body[start:end])}
assert found, "the mark table did not parse -- has its shape changed?"
return found
def _own_mark() -> str:
"""The mark for raven's own agents, which are keyed by a flag and not a preset.
Outside ``MARKS`` on purpose -- that table's contract is that it equals the
third-party presets exactly -- so it is parsed separately rather than by
widening the entry pattern above.
"""
found = _OWN.findall(_TABLE.read_text(encoding="utf-8"))
assert len(found) == 1, "raven's own mark did not parse -- has its shape changed?"
return found[0]
def _group_mark() -> str:
"""The mark for the card that stands in for the nine Mirasim agents at once.
Parsed separately for the same reason ``_own_mark`` is: it is one file for
nine presets, so it cannot live in a table whose contract is one entry per
preset. It is NOT exempt from the orphan check below -- the opposite: that
check is what stops this file becoming dead weight the bundle still ships.
"""
found = _GROUP.findall(_TABLE.read_text(encoding="utf-8"))
assert len(found) == 1, "the group mark did not parse -- has its shape changed?"
return found[0]
def _tone_of(file: str) -> str | None:
"""What the SVG itself says its tone is.
A shape draws in ``currentColor`` either by naming it or by carrying no
fill of its own while the root does -- qoder's second path is the latter,
which is why a plain substring test over the file is not enough to tell a
hybrid from a mono.
"""
svg = (_ASSETS / f"{file}.svg").read_text(encoding="utf-8")
root = svg[: svg.index(">") + 1]
root_adapts = "currentColor" in root
shapes = _SHAPE.findall(svg)
adaptive = sum(1 for el in shapes if "currentColor" in el or ("fill=" not in el and root_adapts))
if not adaptive:
return None
return "mono" if adaptive == len(shapes) else "hybrid"
def test_every_preset_has_a_mark() -> None:
assert set(_marks()) == set(THIRD_PARTY_SUBAGENT_PRESETS)
def test_every_mark_names_a_file_that_ships() -> None:
missing = {key: file for key, (file, _) in _marks().items() if not (_ASSETS / f"{file}.svg").is_file()}
assert not missing
def test_no_asset_is_orphaned() -> None:
"""An unreferenced file is dead weight the wheel still carries.
``ui-web/build.py`` copies the whole assets tree into the bundle, so a mark
left behind by a removed preset ships to every user forever.
"""
named = {f"{file}.svg" for file, _ in _marks().values()} | {f"{_own_mark()}.svg"} | {f"{_group_mark()}.svg"}
assert {path.name for path in _ASSETS.glob("*.svg")} == named
def test_the_group_mark_ships() -> None:
assert (_ASSETS / f"{_group_mark()}.svg").is_file()
def test_the_tone_agrees_with_the_file() -> None:
wrong = {
key: (declared, _tone_of(file)) for key, (file, declared) in _marks().items() if declared != _tone_of(file)
}
assert not wrong
def test_the_hybrid_tone_is_not_spent_on_a_file_that_does_not_need_it() -> None:
"""A hybrid is the only tone whose filter changes a colour on purpose.
Both directions matter and neither is visible in the rendered page: a
hybrid spelled ``mono`` recolours the brand, and a mono spelled ``hybrid``
rotates the hue of a shape that has none, so the assertion is that the set
is exactly the files that mix the two kinds of shape.
"""
declared = {key for key, (_, tone) in _marks().items() if tone == "hybrid"}
derived = {key for key, (file, _) in _marks().items() if _tone_of(file) == "hybrid"}
assert declared == derived
def test_the_own_mark_ships() -> None:
assert (_ASSETS / f"{_own_mark()}.svg").is_file()
def test_the_own_mark_answers_the_theme() -> None:
"""A raven is dark, and the dark theme's surface is ``#1e1c14``.
Two mechanisms answer that, and the file may carry either. A
``prefers-color-scheme`` rule inside the file flips the bird for the dark
surface -- what the mark the chrome draws does through ``currentColor``
(components/RavenMark.tsx), and what the stylesheet's ``color-scheme``
lines on ``.agent-mark img`` exist to make reachable from an ``<img>``, as
miromind.svg also relies on. An opaque plate behind every shape is the
other: it renders the same on either surface and makes the rule redundant.
A file with neither is the failure this guards -- measured at the roster's
render size, the bird against that surface is 1.07:1, gone.
The tone must stay absent either way, for the reason it always did: a
``mono`` or ``hybrid`` here would invert the whole mark, which lands
dark-on-dark in exactly one theme -- and no DOM assertion sees a colour.
"""
svg = (_ASSETS / f"{_own_mark()}.svg").read_text(encoding="utf-8")
root = svg[: svg.index(">") + 1]
shapes = _SHAPE.findall(svg)
plate = [el for el in shapes if el.startswith("<rect") and 'fill="#FFFFFF"' in el]
assert plate or "prefers-color-scheme" in svg, (
"the own mark carries neither a plate nor a prefers-color-scheme rule"
)
if plate:
assert 'fill="none"' in root, "a root fill would paint outside the plate"
assert _tone_of(_own_mark()) is None