openhuman/PLAN.md

Backend Overhaul — Controller Registry Consolidation

Branch: feat/backend-overhaul Base: main @ 515c4f4b

Why

Project rule (CLAUDE.md): domain functionality exposed to CLI + JSON-RPC only via the controller registry (schemas.rs per domain + src/core/all.rs). Current state is 90% there — 34 domains fully migrated — but six CLI adapters and one JSON-RPC fallback still live in the transport layer. Finishing this lets us delete ~95KB of adapter code and enforce the rule with a lint/grep check.

Goals

1. Zero domain-specific code in src/core/cli.rs, src/core/jsonrpc.rs, src/rpc/dispatch.rs.
2. Every CLI command and JSON-RPC method dispatched through the shared registry.
3. No behavior change — all existing CLI flags and RPC methods preserve names, params, outputs.
4. Unregistered infrastructure modules documented as intentionally transport-agnostic.

Non-goals

• No new domain functionality.
• No changes to skills QuickJS runtime exposure (stays runtime-only).
• No renames of existing CLI flags or RPC method names.
• No touching memory-tree domain (sanil-23 has in-flight PRs #732 #733).

Current leakage

File	LOC	What's there	Target
src/core/agent_cli.rs	21.4K	agent CLI adapter	openhuman/agent/schemas.rs
src/core/memory_cli.rs	15.3K	memory CLI adapter	openhuman/memory/schemas.rs
src/core/text_input_cli.rs	12.4K	text_input CLI adapter	openhuman/text_input/schemas.rs
src/core/screen_intelligence_cli.rs	26.5K	screen_intelligence CLI adapter	openhuman/screen_intelligence/schemas.rs
src/core/tree_summarizer_cli.rs	13.2K	tree_summarizer CLI adapter	openhuman/tree_summarizer/schemas.rs
src/core/cli.rs (voice block)	~2K	run_voice_server_command()	openhuman/voice/schemas.rs
src/rpc/dispatch.rs	76	openhuman.security_policy_info fallback	openhuman/security/schemas.rs (or about_app)

Total: ~95KB of adapter code to fold into registry.

Exposure rule (decision tree)

Two legitimate shapes for exposing a domain capability. Pick by command shape, not by convenience:

1. Controller registry (src/openhuman/<domain>/schemas.rs + src/core/all.rs). Use for request/response RPC-style capabilities — take params, do work, return JSON, done. The vast majority of domain methods. CLI access is free via the generic namespace dispatcher (openhuman <domain> <verb> --args).

2. Domain-owned CLI adapter (src/openhuman/<domain>/cli.rs). Use only for standalone long-running / blocking operational commands — e.g. openhuman voice runs a hotkey listener forever, holds the process, logs to stderr. These don't fit the registry's fire-and-return JSON contract. The adapter lives inside the domain (not in src/core/cli.rs) so transport layer stays generic.

Hard rule: no domain-specific imports or logic in src/core/cli.rs, src/core/jsonrpc.rs, or src/rpc/dispatch.rs. The only allowed reference is the dispatch line that routes args[0] to the domain's CLI function. Everything else lives in the domain.

Don't invent a third shape. If a capability feels like it needs one, it probably belongs in one of the two above with a thin adjustment.

Approach

Each migration is a self-contained diff:

1. Confirm domain already has schemas.rs with all_<domain>_registered_controllers().
2. For each CLI subcommand in <domain>_cli.rs:
   • Identify the underlying domain function it calls.
   • Add a handle_<verb> fn in schemas.rs that takes Map<String, Value> and returns ControllerFuture.
   • Register it in all_<domain>_registered_controllers().
3. Delete the <domain>_cli.rs file.
4. Remove its import from src/core/cli.rs / mod.rs.
5. Verify CLI flags still work via generic dispatcher — the registry already exposes them by method name.
6. cargo check + cargo test -p openhuman per step.

The generic CLI adapter in cli.rs already knows how to route <domain> <verb> --key value to registry method openhuman.<domain>_<verb>. Migration is mostly deletion once handlers exist.

Phases

Phase 1 — Smallest adapter first (shakedown)

voice (~2K inline in cli.rs). Lowest risk: one server command, confirms the approach end-to-end before touching bigger files.

• Commit: refactor(voice): move CLI adapter to controller registry

Phase 2 — Mechanical migrations (one PR each)

Order = smallest file first, so each PR is reviewable and CI catches issues early.

1. text_input (12.4K) — likely thin wrappers.
2. tree_summarizer (13.2K).
3. memory_cli (15.3K) — coordinate with sanil-23 memory-tree PRs; rebase after #732/#733 merge or pair-review.
4. agent_cli (21.4K).
5. screen_intelligence (26.5K) — largest, leave for last.

Each: one commit, one PR, self-contained. No bundling.

Phase 3 — JSON-RPC dispatch fallback

Move openhuman.security_policy_info from src/rpc/dispatch.rs into whichever domain owns security policy (likely about_app or a new security module). Delete rpc/dispatch.rs if it becomes empty, else leave as a thin generic dispatch shim.

Phase 4 — Enforce the rule

Add a build-time check or CI grep. The rule must forbid domain imports/types in the transport layer while still allowing the dispatcher to call the generic ::cli::run_* entrypoints that live inside each domain:

# Forbid `use crate::openhuman::<domain>::…` imports in transport files.
! grep -rE '^\s*use\s+crate::openhuman::[a-z_]+::' \
    src/core/cli.rs src/core/jsonrpc.rs src/rpc/dispatch.rs

# Forbid any other domain reference that is NOT a call into ::cli::run_*(…).
# (The dispatcher is allowed to invoke `crate::openhuman::<domain>::cli::run_<x>(...)`.)
! grep -rE 'crate::openhuman::[a-z_]+::' \
    src/core/cli.rs src/core/jsonrpc.rs src/rpc/dispatch.rs \
  | grep -vE 'crate::openhuman::[a-z_]+::cli::run_[a-z_]+\('

Fails if any domain-specific import or non-dispatcher reference creeps back in. Commit as chore(core): fence domain imports out of transport layer.

Phase 5 — Document unregistered modules

Add a short table to CLAUDE.md listing intentionally-unregistered infra modules (accessibility, approval, context, embeddings, integrations, node_runtime, overlay, providers, routing, tokenjuice, tool_timeout) with one-liner "why not in registry" for each. Also document skills as runtime-only.

Risks

• agent_cli / screen_intelligence size — large files may hide subtle flag-parsing logic not obvious from a first read. Mitigation: test-drive each CLI subcommand manually after migration; add CLI smoke tests to the registry dispatcher if missing.
• memory_cli collision with sanil-23 — memory-tree PRs touch adjacent paths. Mitigation: do phase 2.3 last, rebase on top of merged PRs.
• CLI flag drift — generic adapter parses flags by schema. If current _cli.rs does custom parsing (e.g. positional args, subcommand nesting), need to extend schema before deleting. Mitigation: read each CLI file top-to-bottom before writing handler.
• Behavior diff at registry boundary — registry handlers return ControllerFuture with JSON; _cli.rs may print formatted text. Mitigation: keep a thin formatter in the generic CLI path, not per-domain.

Verification per step

cargo check --manifest-path Cargo.toml
cargo test -p openhuman --test json_rpc_e2e
# Manual CLI smoke for migrated domain:
./target/debug/openhuman <domain> <verb> --args...

Plus yarn test:rust for the full mock-backed integration suite before each PR.

Milestones

• M1: Phase 1 done, shakedown merged.
• M2: Phases 2.1–2.5 done, all *_cli.rs deleted.
• M3: Phase 3 done, rpc/dispatch.rs cleaned.
• M4: Phase 4+5 done, rule enforced, docs updated.

Estimate: M1 = 0.5d, M2 = 3–4d (one domain/day), M3 = 0.5d, M4 = 0.5d. Total ~1 week of focused work.