Skip to main content

jhf-reed Architecture

Documentation Map​

jhf-reed Architecture

jhf-reed is planned as the Helpifyr Agent Capability Gateway. It separates agent execution from stack truth and module business logic.

Boundary​

Reed owns:

  • MCP/tool gateway runtime for agents.
  • Canonical action envelope handling.
  • Capability lookup from Fabric.
  • Policy/approval enforcement from Warp.
  • Identity/claims enforcement from Heddle.
  • Secret-broker access through Keystore.
  • Routing to module-owned adapters.
  • Evidence and event emission.

Reed does not own:

  • Business data truth.
  • Fabric contracts/projections.
  • Warp policy semantics.
  • Heddle identity semantics.
  • Keystore secrets.
  • Module-specific business actions.
  • Dobby learning/admission decisions.

Reed-Only MCP Chokepoint​

  • jhf-reed is the only admitted business MCP server for OpenClaw business agents.
  • Module adapters are not directly registered as agent-visible business MCP tools.
  • Direct business action paths via shell/exec/docker/ssh/browser/raw-http/direct-adapter/direct-secret are forbidden by contract.
  • Bypass attempts must produce machine-readable denial verdicts and security evidence.
  • Routing dimensions (tenant_id, environment, runtime_scope, adapter_instance_id) are mandatory and must match exactly; implicit defaults are forbidden.

Planned Flow​

  1. OpenClaw agent requests a tool/action through Reed.
  2. Reed resolves the capability from Fabric.
  3. Reed checks policy/risk/approval posture from Warp.
  4. Reed validates caller/principal claims from Heddle.
  5. Reed requests secret-broker access from Keystore when needed.
  6. Reed routes to the module-owned adapter.
  7. Reed records readback, evidence, events, and verdicts.
  8. Dobby may consume evidence for learning, but cannot mutate truth directly.

Fail-Closed Rules​

  • Missing capability truth: deny.
  • Stale projection: deny or degraded read-only according to Fabric/Warp contract.
  • Missing policy: deny.
  • Missing claims: deny.
  • Missing secret broker posture for secret-requiring actions: deny.
  • Missing module adapter: deny.
  • Failed evidence emission for write-capable actions: quarantine or fail according to the action contract.

License​

This document is part of an AGPLv3 repository. Helpifyr project information is available at https://helpifyr.com.