bot/docs/refactor/hanzonode-gateway-rfc.md

summary, read_when, title

summary	read_when	title
RFC to make Hanzo Node the runtime and gateway while keeping Bot UI and channels fully functional	Planning Hanzo Node as the single runtime for local and remote bot operation Integrating desktop and mobile clients with gateway and node capabilities	Hanzo Node Gateway RFC

Hanzo Node Gateway RFC

Decision

Adopt a node-first architecture where hanzod is the single runtime for:

• gateway RPC and events,
• channel routing and delivery,
• session and auth state,
• node capability invocation,
• approvals and policy enforcement.

The Bot desktop app becomes a first-class client and local capability host, not the primary runtime itself.

Feasibility

Feasible, and aligns with the current direction already present in this repo:

• Operator and node roles already exist in the gateway protocol.
• Local and remote operation models already exist.
• Node invocation and approval mechanisms already exist.

This is an implementation migration, not a product redefinition.

Target architecture

Runtime (hanzod)

hanzod owns the control plane and data plane:

• WebSocket RPC + event protocol compatibility.
• Session store, identity, and auth tokens.
• Channel adapters (core + plugin channels).
• Node registry and node.invoke dispatch.
• Approval engine (including privileged actions).

Desktop app

Desktop app is both:

• Operator UI (chat, dashboard, status, config), and
• Optional local node host for OS capabilities (automation, notifications, accessibility, camera, mic, screen, etc).

The app can run in two modes:

• Local mode: ensure hanzod service is up, attach as operator and optional node.
• Remote mode: attach to remote hanzod over SSH/tailnet.

Cloud and hybrid execution

Model inference can run in cloud while privileged actions stay local:

• Cloud side: orchestration, model calls, multi-agent scheduling.
• Local side (hanzod + desktop node): permissioned OS and device actions.

This preserves security boundaries while enabling cloud-scale reasoning.

Mobile path

Same protocol supports mobile clients later:

• Mobile as operator-only client,
• Mobile as node-capability client,
• Or dual-role client.

Feasible for automation support, with platform limits:

• Android automation is generally more permissive.
• iOS automation is constrained by platform policy and available APIs.

Compatibility requirements

hanzod must preserve:

• existing method and event names,
• role and scope enforcement,
• channel behavior and plugin method loading,
• config semantics for local and remote modes,
• operator flows used by desktop, web, and CLI clients.

Use /refactor/hanzonode-gateway-parity as the executable checklist.

Migration phases

Phase 0: Protocol freeze

• Freeze current RPC/event surface and auth semantics.
• Generate fixture suite from current gateway method/event contracts.

Exit criteria:

• Contract tests green against current runtime.

Phase 1: hanzod core skeleton

• Implement WS server, auth handshake, roles/scopes, and health/status methods.
• Add compatibility test harness against frozen fixtures.

Exit criteria:

• Basic client connect + auth + status parity.

Phase 2: Stateful control plane

• Port config, sessions, agents, cron, usage, wizard, and identity/team methods.
• Port event broadcaster semantics.

Exit criteria:

• Control UI and CLI can operate on hanzod for non-channel workflows.

Phase 3: Node and approvals

• Port node registry, pair/device token lifecycle, invoke workflow, and approvals.
• Wire desktop app as operator and node-capability host.

Exit criteria:

• End-to-end privileged action path works with approval policy.

Phase 4: Channel adapters

• Port built-in channels and plugin channel method plumbing.
• Keep routing and allowlist behavior unchanged.

Exit criteria:

• Channel E2E smoke tests pass.

Phase 5: Desktop default runtime

• Desktop app boots/attaches to hanzod by default.
• Local background service and remote attach both supported.

Exit criteria:

• Desktop app no longer depends on legacy gateway runtime.

Phase 6: Decommission legacy gateway runtime

• Keep compatibility bridge until release confidence is high.
• Remove legacy runtime only after parity gates pass.

Exit criteria:

• Full production cutover with rollback path removed.

Risks and mitigations

• Risk: protocol drift breaks existing clients.
  • Mitigation: fixture-based compatibility tests from current method/event surface.
• Risk: channel regressions.
  • Mitigation: per-channel parity matrix and smoke suite before cutover.
• Risk: permissions UX mismatch on desktop.
  • Mitigation: keep approvals and permission prompts in desktop UI while runtime moves to hanzod.
• Risk: mixed local/remote confusion.
  • Mitigation: strict mode model (local vs remote) and explicit runtime target in UI.

Immediate work package

1. Build and enforce the parity checklist (/refactor/hanzonode-gateway-parity).
2. Stand up hanzod protocol shell with role/scope/auth compatibility.
3. Integrate desktop app with hanzod local attach and remote attach.
4. Port node invoke + approval path first (highest product leverage).
5. Port channels next, starting with highest-volume production channels.

Definition of done

hanzod is the only runtime required for:

• Bot UI chat/dashboard,
• channel ingress/egress,
• node-capability invocation with approvals,
• local and remote operator access,
• cloud-hybrid execution where cloud handles reasoning and local node handles privileged execution.