Dizhan Xue 6fbc573876
feat: enable MCP lending on Windows hosts (#972)
## Summary

Windows hosts can lend granted MCP servers to local and machine-based
ACP agents through authenticated loopback endpoints. Hosts with Unix
sockets retain that transport. Server definitions, upstream credentials,
sandbox policy and disabled-tool enforcement stay on the host.

- Share one connector between the local bridge and node client. Bind TCP
endpoints only to 127.0.0.1 and authenticate with a fresh per-endpoint
token before opening an upstream.
- Read inherited Windows stdin pipes through a daemon worker with
backpressure. Acknowledge each chunk on the event loop before reading
another, so neither the reader buffer nor queued callbacks can grow
without bound.
- Cancel both bridge pumps on exit, allow up to one second for the
endpoint connection to flush, then abort the transport if it still holds
unsent bytes. A peer that stops reading cannot hold failure or
cancellation cleanup indefinitely.
- Resolve this installation's raven.exe, preserve task and session
isolation, hide endpoint credentials from grant representations, and
redact them in bridge diagnostics and session-start journal frames.
Remote dispatches do not receive the host's loopback token.
- Update capability reporting, CLI help, the remote ACP entry's
`machine` docstring, CONTEXT.md and the English/Chinese collaboration
guide. Add Windows CI coverage and exercise both Unix and TCP endpoints
on Linux.

## Type

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

## Verification

Docker Linux, Debian Bookworm with procps and git, Python 3.12.12,
--init, a native Linux source copy, and a frozen environment: 783
related unit tests and all 3 real-server integration tests passed. The
source and test files were compared with the committed versions before
publication.

```sh
uv sync --frozen --extra dev
uv run --frozen --no-sync pytest tests/test_mcp_transport.py tests/test_mcp_bridge.py tests/test_mcp_endpoint.py tests/test_cli_mcp_commands.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_node_client.py tests/test_acp_journal.py tests/test_subagent_acp_remote.py tests/test_subagent_manager.py tests/test_subagent_mcp_grant.py tests/test_subagent_third_party.py -q -n 4 --dist loadfile --tb=short --cov=raven --cov-report=json:/out/coverage.json --junitxml=/out/units.xml
uv run --frozen --no-sync pytest tests/integration/test_mcp_bridge_e2e.py -m integration -q -n 0 --tb=short --junitxml=/out/integration.xml
```

PR diff coverage is 98.26% (169/172 changed executable lines), above the
unchanged 90% threshold. On the host checkout, `$coverageReport` points
to the JSON exported by that Linux run:

```powershell
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $coverageReport diff --base-ref origin/main --head HEAD --threshold 90
```

Native Windows, Python 3.13.12, a separate frozen environment and
PYTHONUTF8=1: all 21 bridge unit tests passed; all 8 integration cases
passed, comprising 3 MCP bridge cases and 5 native command-line cases
retained in the Windows CI job.

```powershell
uv run --frozen --python 3.13 --no-sync pytest tests/test_mcp_bridge.py -q -n 0 --tb=short
uv run --frozen --python 3.13 --no-sync pytest tests/integration/test_mcp_bridge_e2e.py tests/integration/test_acp_mirasim_real_process.py -m integration -q -n 0 --tb=short
```

Seven regression cases cover paused input, resuming consumption, closing
a paused worker, a busy event loop, and teardown with pending TCP
writes: while the endpoint stays stalled, while it drains those writes,
and when a second cancel arrives after that drain finished. Aborting the
endpoint after a close that finished was wrong: the selector transport
has already run connection_lost and dropped its loop, and its
_force_close returns early only on _conn_lost, which a drained close
does not raise, so the bridge exited 1 at teardown on Linux and macOS.
The abort now depends on whether the endpoint's write buffer still holds
bytes, since a closing transport empties it before calling
connection_lost. A flag set once the close returned would miss the
second cancel, and that case fails with one. The stalled-endpoint
teardown case pauses the endpoint's reading before the frames are fed:
it used to wait for the socket to stop reading through its own flow
control, which took 1.87 s of the case's 2 s budget on Linux, so a busy
runner timed out before the teardown ran. It is now 0.17 s per case, and
20 consecutive runs under 32 busy loops on 16 cores all passed. The
original teardown and buffering cases fail without the fixes. At this
head, making the stdin worker read again without waiting for its
previous chunk to be delivered fails 3 cases, removing the close
deadline fails 2, and never aborting fails 2; aborting unconditionally
fails both drained cases. These mutations ran on a disposable copy of
the source tree, not on the committed files.

The unreachable-upstream integration test still uses its original
1.5-second deadline. Its Windows fixture bypasses the venv redirector
while preserving the venv, so an inherited stdout handle cannot mask
EOF.

Full-PR pre-commit, commitlint, commit-message, source-language, asset
and whitespace checks passed. The bridge type check passed and all 10
import contracts were kept:

```powershell
uv run --frozen --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
npx --no-install commitlint --from origin/main --to HEAD --config commitlint.config.cjs
uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --frozen --no-sync python scripts/check_large_files.py origin/main...HEAD
uv run --frozen --no-sync python scripts/check_source_language.py origin/main...HEAD
uv run --frozen --no-sync ty check raven/mcp/bridge.py
uv run --frozen --no-sync lint-imports
git diff --check origin/main...HEAD
```

These are focused local results. Remote dispatch tests use the
repository's SSH stand-in and real node processes, not an external
machine. POSIX-dependent paths are covered on Linux; no full-suite
Windows pass, live LLM run or sandbox VM run is claimed. Existing
Windows path, shell and journal portability outside this MCP change
remains out of scope.

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

## Risk

Windows dispatches can now use granted MCP servers. Each fallback
endpoint opens an ephemeral loopback listener with a bounded
authentication handshake and its own random token. Upstream definitions
and credentials remain on the host, and remote dispatches receive no
loopback token.

Input now pauses when a bridge cannot forward requests. During shutdown,
a connection that cannot flush within one second is aborted and its
remaining queued bytes can be discarded. This bounds cleanup when a peer
has stopped reading.

Unix sockets remain the preferred transport, and the Raven node wire
protocol is unchanged. No dependencies, configuration fields or
migrations are added. Reverting the change restores the previous Windows
MCP limitation.

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

## Related Issues

Fixes #962

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-19 19:58:55 +08:00
..