Agentic RPC framework
Build a persistent, query-driven Rust daemon exposing a DaemonService trait, a line-based JSON transport, and bindings that all speak the trait over that transport — CLI, API, MCP, ACP — then verify with a green build/fmt/clippy/test gate before claiming anything done.
When to use
- Designing or extending the agentic RPC framework (daemon, transport, bindings, protocol).
- Adding a new binding (HTTP, MCP, ACP) on top of the existing line-based JSON protocol.
Always-on rules
- X: drive enforced. All paths, env vars, builds, toolchains on X:.
CARGO_TARGET_DIR=X:/cargo-targetandRUSTUP_HOME=X:/Dev/rustup. C: stays at 90% full / unused. - Never stub. Full implementation, working artifacts. A crate not exercised end-to-end is not done; a command not reachable is not done.
- Verification-first.
cargo fmt --all -- --check-> FMT_OK;cargo clippy --workspace --all-targets -- -D warnings-> 0 errors;cargo test --workspace-> green, before any claim of completion. - One JSON per line, one response per line. The line-based JSON protocol is the wire that CLI, API, MCP, and ACP all build on.
- No credentials. Secrets are never preserved; replace them with
[REDACTED]. - Rust module resolution.
pub mod foo;resolvesfoo.rsBEFOREfoo/mod.rs(the/lib.rspath is crate-root-only, never a submodule). Afoo.rsstub silently shadowsfoo/mod.rs; before believing any "verified" claim, verify withfind crates/<crate>/src/<module>/that the real module compiles — a stub plus one skeleton test is not verification. This caught a fake S1 spike where the real engine implementation was permanently shadowed. write_filestale-view guard.write_filerefuses to overwrite a file it last read via offset/limit (a "partial view"). Bypass byrmthenwrite_file— the delete satisfies the guard.- Feature-pin typo loop. The salsa feature pin is
salsa, NOTsalpa. Always verify with--listthat the realsalsa_enginetests appear; use variable-based invocationF=salsa; cargo test -p rpc-core --features "$F". cargo rustc --print=cfgis unsupported. This cargo version rejectscargo rustc --print=cfg(invalid value / unexpected argument). To confirm feature activation, usecargo metadata --no-deps.
Procedure
- Scaffold the workspace. Workspace manifest with explicit
memberslist;[workspace.package]for shared metadata; serde pinneddefault-features = false, features = ["derive", "std"]. All 12 crates inmembers. - Core domain + engine trait.
rpc-core:IncrementalEnginetrait (apply_changes,query,cancel) plus theQuery/QueryResultwire domain (DaemonHealth,CapabilitySet,Revision). UseMockEngineas the reference implementation; gate the real engine adapter behind an opt-in feature (e.g.salsa). - Production engine backend (external IDE-analysis library). The real-time engine wraps a third-party IDE-analysis library (e.g.
ra_ap_ide/parser +ra_ap_ide_diagnostics) behind theIncrementalEnginetrait, so CLI/API/MCP/ACP bindings are unchanged. The wrapper owns anAnalysisHost(interior-mutated viaMutex) plus a tracked file set.apply_changesupdates the tracked set and bumps a revision;query(Diagnose(path))rebuilds the ra_ap world for that path and maps the ra_ap diagnostics into the wirerpc_diagnostics::Diagnosticdomain. Keep the wrapper behind an opt-in feature (e.g.salsa) so the default build stays light. Version-sensitive gotchas (from the S1 spike): read the INSTALLED crate source before writing —AbsPathBufis inra_ap_paths,AnalysisHostis inra_ap_ide,full_diagnosticsis a method onAnalysis(3 args),Diagnostichas acode: DiagnosticCode(callas_str()),Severity/AssistResolveStrategyare inra_ap_ide_db,DiagnosticsConfig::test_sample()builds a valid config, andproc_macro_cwdmust usetriomphe::Arc(notstd::sync::Arc) over an ABSOLUTE path — on WindowsAbsPathBuf::try_from("/")panics becausePath::is_absolute()rejects a bare/(current-drive root, not drive-anchored); pass a drive-anchored path like"X:/"or"C:/". Seereferences/ra-ap-lib.mdfor the wiring recipe and the corrected API surface. - Daemon as a library.
rpc-daemonis a LIBRARY exposingDaemonServicetrait (Daemon,ToolRegistry,EngineHandle,LocalDaemon).main.rsis only entry points:--one-shot CMDand--listen <addr>. - Transport. Line-based JSON (
one req per line, one JSON resp per line). Newlines are mandatory on both ends (see pitfall: newline requirement). - Bindings.
rpc-cli(TCP/stdio/self-test),rpc-api(in-process), thenrpc-mcp/rpc-acp(translate the same trait to MCP tools / ACP proposals). Every binding uses theDaemonServicetrait, never the concreteDaemon. - Run the F1 gate. Build, fmt, clippy, test. Green = done.
Query double-tag serde bug.
Query { kind: QueryKind }whereQueryKindis#[serde(tag="kind")]serializes the tag twice ({"kind":{"kind":"diagnose",...}}), so JSON{"kind":"diagnose","path":...}fails to deserialize withinvalid type: string "diagnose", expected internally tagged enum. Fix:#[serde(flatten)]thekindfield so the wire format is the clean"{\"kind\":\"diagnose\",\"path\":...}— round-trip it through a serde_json test in the self-test.Transport: newline requirement. The transport reads one JSON line at a time (
read_line). A client thatwrite_alls the request bytes without a trailing\nhangs forever inread_line— the daemon never responds and the client blocks up to the terminal timeout. Always send\nafter the request line.Daemon accept loop must not exit.
servethat accepts once and returns exits the process, killing the transport thread. Use aloop { accept() }so the daemon keeps serving; each connection runs in its own thread.Rebuild while the daemon is running -> Access is denied. Windows refuses to overwrite an executing binary. Kill the running daemon (
taskkill /F /IM rpc-daemon.exe) beforecargo build. Verify no daemon remains before rebuilding.Dispatch must cover every op. The transport's
dispatchis amatch op; an op not listed returns silently asunknown operation. Add the arm rather than assuming the CLI covers it.Bind-address discovery.
--listen 0picks a random port. The log must print the boundlocal_addr()(after binding), not the pre-bound address, so clients know the real port.Tool surface must be wired three ways.
tools/capabilitiescommands must be wired into theDaemonServicetrait, the transport dispatch, AND the CLIbuild_req/dispatch. One side missing and the command is invisible to that terminal.Tool path format. CLI apply flags are
--path=.../--content=...(equals, no spaces).build_reqparses viastarts_with("--path="); spacing-separated flags fail with exit 2.External engine rebuild-per-query perf. Wrapping a third-party IDE-analysis library behind
IncrementalEngineby rebuilding the wholeAnalysisHostworld on everyqueryis correct but slow (full parse + HIR each time, typically far above 100ms). It is the right prototype shape and the right fallback for a daemon with no incremental plan — but it must be replaced before the daemon is used for latency. Do not claim the sub-100ms promise on this shape; mark it explicitly as "correct, not yet fast".Subsecond ThinLink (S3). Not standalone; embedded in
dioxus-cli(dx serve --hotpatch). Seereferences/subsecond-thinlink.md.Salsa persistence (S2). Feature
persistence(v0.28.5, MSRV 1.88). Seereferences/salsa-persistence.md.Recursive
Deserialize(F2).ChangeembedsVec<Change>; derive fails. Always parse manually in transport.Library
ra_ap_*(S1).v0.0.358(MSRV 1.98.0) is linkable, but the crate API shifts between point releases — inspect the INSTALLED crate source rather than trusting stale docs. Keys you will trip on: (1)AbsPathBufis inra_ap_paths(NOTra_ap_cfg); (2)AnalysisHostis inra_ap_ide(NOTra_ap_ide_db); (3)full_diagnosticsis a METHOD onAnalysis(analysis.full_diagnostics(&config, resolve, file_id) -> Cancellable<Vec<Diagnostic>>, Cancellable =Result<T, Cancelled>), NOT a free fn — the free fn takes 4 args (db, &config, resolve, file_id); (4)Diagnosticfields arecode: DiagnosticCode, message: String, range: FileRange, severity: Severity, unused, experimental, fixes: Option<Vec<Assist>>, main_node—codeis aDiagnosticCode(call.as_str(), not.map()),rangeis ONEFileRange(with.range.range=TextRange); (5)Severity(Error/Warning/WeakWarning/Allow) is inra_ap_ide_dbandAssistResolveStrategyinra_ap_ide_db::assists; (6)DiagnosticsConfig::test_sample()builds a valid config. Version coordination is also required (triomphe0.1.17 matching ra_ap_ide's dependency). Use the salsa feature pinsalsa(neversalpa); verify withF=salsa; cargo test -p rpc-core --features "$F".
Verification gate (F1)
Run in order; stop on first failure:
cargo build --workspace --all-targets-> exit 0cargo fmt --all -- --check-> FMT_OKcargo clippy --workspace --all-targets -- -D warnings-> 0 errorscargo test --workspace-> all crates green (includingrpc-cliself-test,rpc-apidoctest)
Note: cargo rustc --print=cfg is NOT supported by this cargo version (rejected). To confirm feature activation, use cargo metadata --no-deps.
\n
- Subsecond ThinLink (S3 spike). Not a standalone crate; embedded in
dioxus-cli(dx serve --hotpatch). Seereferences/subsecond-thinlink.md. Daemon-side hot-patching must shell out todxCLI or replicate embedded ThinLink manually. - Salsa persistence (S2 spike). Feature
persistence(v0.28.5, MSRV 1.88). Seereferences/salsa-persistence.mdfortests/persistence.rsAPI (#[salsa::input(persist)],as_serialize,Database::deserialize). - Recursive
Deserializefailure (F2 fix).ChangeembedsVec<Change>; derivingDeserializefails. Always parse recursively-structured wire types manually intransport::run(manualChangePackconstruction), not via derive macros. - Library
ra_ap_*feasibility (S1 spike).v0.0.358(MSRV 1.98.0) linkable; version coordination required. Seereferences/ra-ap-lib.md. Note:docs/ENGINE.mdstill shows the pre-fixproc_macro_cwd = AbsPathBuf::try_from("/")— that example fails on Windows (rejected byPath::is_absolute()); the working source uses a drive-anchored path ("X:/"or"C:/"). - Public repo location. The public repo is
https://github.com/LoopyLuci/rust-rtpc(notnousresearch). Therepositoryfield inCargo.tomlmust match the actual remote. - Purpose-built ML model sizing. When designing AI/ML components for this framework, every model must: (1) run on bare CPU (no GPU dependency); (2) improve performance/effectiveness more than the resources it consumes (measure ROI: latency removed vs latency added); (3) be sized specifically for the task (tiny NNs ~1–3 M params, trees/linear ~sub-ms). GPU acceleration (CUDA/ROCm EP) is optional; CPU EP is the floor. See
docs/ML-DESIGN.mdfor the full catalog and sizing table.
Browzeit Workspace Pattern (multi-crate Rust + agentic RPC)
The Browzeit project builds a next-gen browser with integrated AI agents using a Rust workspace with 8 crates in crates/: traits, types, core, engine, renderer, network, driver, api. Verified cargo check --workspace exits 0.
Key patterns
- AgentOrchestrator (
engine/src/agent.rs): UsesArc<AgentState>withRefCellfor interior-mutability onstatus,logs,steps_taken,subagents.AgentStatemust beRefCell<...>for all mutable fields; struct literals useRefCell::new(). - DriverAgentOrchestrator (
driver/src/agent.rs): WrapsAgentOrchestrator. Usestypes::browser::BrowserWindow(NOTdriver::shell::BrowserWindow).DriverAgentOrchestrator::new()takes 0 args and createsBrowserWindow::new()internally. - API crate (
api/src/lib.rs+main.rs): UsesaxumRouterwithJsonresponses.GLOBAL_ORCHESTRATORispub static mut(must bepubto be accessible frommain.rs). Usebrowzeit_api::GLOBAL_ORCHESTRATORto access frommain.rs. - Python GUI shell (
gui_shell/browzeit_shell.py): Pythonhttp.serveron port 8765 serving GUI + proxying API calls. SSE endpoint at/api/agent/streamfor live thought streaming.webview.create_windowfor native shell. - Agent module stubs (
engine/src/agent/moe.rs,moa.rs,moi.rs,session.rs,subagent.rs,swarm.rs): These modules must be fully implemented withuse crate::agent::protocol::LLMClientfor LLM client trait access. TheMoERouterroutes tasks by capability matching;MoAAggregatorcoordinates multiple agents via iterative refinement. - API endpoint for
get_agent_results: FetchGLOBAL_ORCHESTRATORviabrowzeit_api::GLOBAL_ORCHESTRATOR(from lib.rs). Usetask_id.clone()fortask_idfields sinceStringdoesn't implementCopy. - Rust module resolution:
pub mod foo;resolvesfoo.rsBEFOREfoo/mod.rs. Verify module compiles:find crates/<crate>/src/<module>/to ensure the real module is being compiled, not a stale stub.
Verification gate (F1)
Run in order; stop on first failure:
cargo build --workspace --all-targets-> exit 0cargo fmt --all -- --check-> FMT_OKcargo clippy --workspace --all-targets -- -D warnings-> 0 errorscargo test --workspace-> all crates green (includingrpc-cliself-test,rpc-apidoctest)
Note: cargo rustc --print=cfg is NOT supported by this cargo version (rejected). To confirm feature activation, use cargo metadata --no-deps.
References
references/f1-gate.md— verification gate procedure.references/subsecond-thinlink.md— S3 spike: subsecond runtime + ThinLink embedded indx.references/salsa-persistence.md— S2 spike: salsa v0.28.5 persistence feature (tests/persistence.rs).references/ra-ap-lib.md— S1 spike:ra_ap_*library consumption (v0.0.360/v0.0.358, MSRV 1.98.0).references/ml-design.md— CPU-first ML model sizing table + ROI rules (docs/ML-DESIGN.mdfull catalog: 11 models, each with concrete param count, CPU latency, RAM, and gain:cst).
References
references/f1-gate.md— verification gate procedure.references/subsecond-thinlink.md— S3 spike: subsecond runtime + ThinLink embedded indx.references/salsa-persistence.md— S2 spike: salsa v0.28.5 persistence feature (tests/persistence.rs).references/ra-ap-lib.md— S1 spike:ra_ap_*library consumption (v0.0.360/v0.0.358, MSRV 1.98.0).references/ml-design.md— CPU-first ML model sizing table + ROI rules (docs/ML-DESIGN.mdfull catalog: 11 models, each with concrete param count, CPU latency, RAM, and gain:cst).