Skip to main content

Architecture

jhf-reed Architecture

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

Reed carries two lanes with different postures, different upstreams and different blocking status. Every section on this page describes the Action Lane (reed.action.capability_plane) unless it says otherwise; the Context Lane (reed.context.delivery.readonly) has its own flow below. LANES.md (docs/LANES.md) is the canonical disambiguation.

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.
  • reed.fabric_catalog_query.read is the first admitted read-only gateway path and is bound to Fabric catalog revision mcp-production-mvp-catalog-v1. It is read-only but belongs to the Action Lane and reaches Fabric, not Bobbin; "read-only Reed path" therefore does not identify the Context Lane.
  • Reed action-lane capabilities remain fail-closed by contract unless current owner truth and runtime followthrough are readbackable; the historical Jadda blocker chain tracked through JaddaHelpifyr/jhf-reed#97 is resolved and must not be reintroduced without fresh owner evidence.
  • 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 — Action Lane​

  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.

Live Flow — Context Lane​

The Context Lane does not route to a module adapter and never writes. It is served by the dedicated jhf-reed-context-gateway container and terminates at the Bobbin semantic API.

  1. OpenClaw agent calls one of the five reed_context_* tools over /mcp.
  2. Reed authorizes the request against the presented admission envelope — principal, tenant, runtime scope, capability admission, policy admission, projection status and projection freshness are all mandatory per request.
  3. Reed checks lane readiness from the runtime readiness projection.
  4. Reed calls the Bobbin semantic API with an operator credential.
  5. Reed filters the response to the contracted safe fields and returns it.
  6. Reed writes context-lane execution evidence through the Fabric Event Spine for routed executions and for the denials raised before routing — unauthenticated, insufficient_permission, stale_projection, runtime_not_ready and admission_contract_incoherent — the last raised when the manifest declares an admission field the ACL does not require, so the lane denies rather than running with a hole. Coverage is deliberately stated rather than rounded up: unknown-method 404 and malformed-params 400 emit nothing, and context-read-requested is declared and registered but never emitted (jhf-reed#132). Silence on the lane is an open question, not proof that nothing happened.

Contract: contracts/runtime/reed_context_runtime_manifest_v1.json. Implementation: scripts/reed_context_runtime.py.

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.