Skip to content

refactor(rpc): rename tui_rpc to rpc for any interactive client - #353

Open
ZuyiZhou wants to merge 1 commit into
mainfrom
refactor/rename_tui_rpc_module
Open

refactor(rpc): rename tui_rpc to rpc for any interactive client#353
ZuyiZhou wants to merge 1 commit into
mainfrom
refactor/rename_tui_rpc_module

Conversation

@ZuyiZhou

Copy link
Copy Markdown

Summary

raven/tui_rpc/ was named after the TUI because the TUI was its only client. It
is now the JSON-RPC surface that any interactive client speaks: the served page
already mounts the same dispatcher, transports and wire vocabulary, and an ACP
agent server will mount them too. The name described the first caller rather than
the module, so this renames it to raven/rpc/.

Behaviour is unchanged. The diff is a rename plus one token substitution:

  • raven/tui_rpc/ to raven/rpc/ (30 modules)
  • tests/test_tui_rpc_*.py to tests/test_rpc_*.py (22), plus 2 under
    tests/integration/
  • the tui_rpc token replaced across 72 files
  • .github/coverage-baseline.json: the 29 path keys renamed, every number left
    alone

Every changed line was checked mechanically rather than by eye. Grouping the diff
by file and comparing each removed line, with the substitution applied, against
the added lines gives: 10 files renamed with no content change, 72 files whose
content change is exactly the substitution (552 lines, reordering included, which
absorbs the import re-sorting ruff applied), 1 new test file, and 1 test file with
deliberate additions. Nothing else.

The wire protocol is untouched. None of the 48 method names in
ui-tui/rpc-schema/openrpc.json carried a tui_rpc prefix, and the three
tui_rpc.cli.dispatch occurrences were loguru log prefixes, not method names.
The only edit to that file is one module path inside info.description, which
ui-tui/scripts/gen-rpc-types.mjs never reads, so the generated TypeScript is
byte-identical.

Two decisions worth flagging for review:

  • The coverage baseline is not regenerated, only re-keyed. Both gates read
    totals alone (baseline-check compares monotonicity, ratchet compares live
    totals against the committed ones); neither reads per-file path keys, so those
    29 keys are inert data. Regenerating would have pulled in unrelated drift
    across 78 files and turned a mechanical rename into a line-by-line review.
  • raven/rpc/__init__.py's first docstring line is deliberately left as it
    was.
    Updating it is a content change, not a rename, and belongs with the
    follow-up work that touches this module's semantics.

Type

  • Fix
  • Feature
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

make coverage
  6705 passed, 33 skipped, 13 deselected, 19 failed (see the note below)

make coverage-diff
  diff coverage 94.20% (65/69 executable changed lines), threshold 90.00%
make coverage-ratchet
  line 76.61% (+1.04pp), branch 65.50% (+1.46pp), tolerance 0.05pp
make coverage-baseline-check
  monotonic, delta 0.000000pp on both line and branch

make lint-python
  ruff check + ruff format --check both clean

uv build --wheel
  all 30 modules under raven/rpc/ present in the wheel, no tui_rpc anywhere in it

The 19 failures do not come from this branch. They are 15 in
tests/test_provider_rates.py and 4 in tests/test_agent_loop_usage_sink.py,
all of them cases that assert a code path never reaches the network, and they
fail identically on an unmodified main: checked by running that file from
main's own copy with this branch's changes stashed. Neither file is touched
here. The three provider test files this branch does touch
(test_provider_auth_method.py, test_provider_resolution_invariants.py,
test_provider_wire_model.py, each only for the tui_rpc literal) all pass, as
does every test_rpc_* file.

Two test files carry real additions, because a pure rename cannot pass the 90%
diff coverage gate and the reason is worth recording. git detects the renames, so
lines that only moved never enter the diff, and the denominator collapses to the
lines that hold the tui_rpc literal -- nearly all of them log statements inside
except blocks, which are the least covered lines in the tree. The first gate run
measured 88.41% (61/69). Rather than leave tui_rpc behind in the log strings,
the uncovered error paths are now tested:

  • tests/test_rpc_dispatcher.py (new): a handler leaking SystemExit, and a
    handler returning a non-dict, each become a well-formed JSON-RPC error frame
    that carries the request id back
  • tests/test_rpc_server_socket.py: an auth token mismatch, and a token that is
    never sent, each close the connection

Four changed lines remain uncovered and are listed by the gate:
raven/cli/gateway_commands.py:500 (a function-local import on the gateway
question path) and raven/rpc/server.py:216, :256, :271 (an unreachable
frame-size branch that readuntil pre-empts, and two last-resort guards).

The npm gates were not run: node_modules is not installed in this working copy,
so lint:rpc, type-check and the bridge build are unverified here. The
info.description argument above is why that is not expected to matter, and CI
runs them.

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

Risk

No behaviour change and no wire change, so the risk is import breakage rather
than misbehaviour, and it is compile-time visible. raven.tui_rpc no longer
exists: importing it raises ModuleNotFoundError rather than resolving to a
stale module. Every one of the 29 submodules under raven.rpc was imported in
one pass to confirm the package resolves.

Packaging is unaffected because pyproject.toml selects packages = ["raven"]
and include = ["raven/**/*.py"] by glob rather than by module name; the built
wheel was checked rather than assumed.

Rollback is a straight revert. Any out-of-tree code importing raven.tui_rpc
must be updated, which is the one externally visible consequence.

  • Security impact considered
  • Backward compatibility considered
  • Rollback path is clear for risky changes

Related Issues

N/A

The module was named after the TUI because the TUI was its only client. It is
now the JSON-RPC surface that any interactive client speaks: the served page
already mounts the same dispatcher, transports and wire vocabulary, and an ACP
agent server will too. The old name described the first caller, not the module.

Mechanical rename, no production behaviour change:

- raven/tui_rpc/ -> raven/rpc/ (30 modules)
- tests/test_tui_rpc_*.py -> tests/test_rpc_*.py (22), plus 2 under
  tests/integration/
- the tui_rpc token replaced across 72 files; every changed line is exactly
  that substitution, checked line by line
- .github/coverage-baseline.json: the 29 path keys renamed, every number left
  alone, totals byte-identical to the previous baseline

The wire protocol is untouched. None of the 48 method names in
ui-tui/rpc-schema/openrpc.json carried a tui_rpc prefix, and the three
tui_rpc.cli.dispatch occurrences were loguru log prefixes rather than method
names. The only openrpc.json edit is one module path inside info.description,
which the TypeScript codegen never reads.

Two test files carry real additions, because a pure rename cannot pass the 90%
diff coverage gate. git records the renames, so lines that merely moved never
enter the diff, and the denominator collapses to the lines holding the tui_rpc
literal -- nearly all of them log statements inside except blocks, which are the
least covered lines in the tree. The first gate run measured 88.41% (61 of 69).
Rather than leave tui_rpc behind in the log strings, the uncovered error paths
are now tested:

- tests/test_rpc_dispatcher.py (new): a handler leaking SystemExit, and a
  handler returning a non-dict, both become well-formed JSON-RPC error frames
  that carry the request id back
- tests/test_rpc_server_socket.py: an auth token mismatch and a token that is
  never sent both close the connection

Diff coverage is now 94.20% (65 of 69). The ratchet moves line +1.05pp and
branch +1.48pp, and the baseline totals are unchanged so baseline-check stays
monotonic. Full suite: 6719 passed, 33 skipped.

Co-authored-by: Claude (claude-opus-5[1m]) <[email protected]>
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