Handbook

Channel agents monorepo and orchestrator on Fleet

Accepted for Forge Agents program (A02).

Updated

Status

Accepted for Forge Agents program (A02).

Context

Operator communication for Forge spans Matrix/Element (human UX), a Cursor bridge (headless agents on laptops), and a growing set of channel-facing bots. Implementation was split across forge-cursor-bridge, ad-hoc Granite scripts, and handbook notes in docs/guides/agent-communication.md.

Meanwhile, forge-workcells owns batch runners (local_llm_worker, …) under ADR-0002 and ADR-0008. Channel agents are long-lived services with different ingress, lifecycle, and deploy shape. Conflating them would blur the workcell WorkcellRequest → WorkcellResult contract.

Decision

  1. forge-agents is a private monorepo (autowww/forge-agents) for channel agents, packaging templates, and the agent orchestrator. Packages: communication, cursor_bridge, packaging, plus top-level orchestrator/.
  2. Channel agents ≠ workcells. Batch execution stays in forge-workcells. Channel agents are operator gateways and lifecycle tooling; they may emit forge.chat_intent.v1 / forge.agent_event.v1 projections but do not own ForgeRun final state.
  3. Orchestrator on Fleet (Granite). The orchestrator maintains forge.agent_registry.v1, wraps Matrix register/deregister, and maps start/stop to existing Fleet docker_argv / container-services. No parallel job plane.
  4. Platform owns contracts. Schemas (agent_registry.v1, communication_interaction.v1), handbook hub (docs/agents/), and this ADR live in forge-platform. Products must not submodule platform (handbook exception: forge-platform-website only).
  5. Communication agent defaults: A0_assisted, deterministic KB (FI + Platform + Blueprints), mandatory citations, 30-day interaction retention.
  6. Matrix rooms for bots remain unencrypted — bot readability is a deliberate ops trade-off; E2EE is not the default for agent rooms.
  7. forge-cursor-bridge migrates into packages/cursor_bridge/ with a deprecation redirect in the old repo.

Consequences

  • Clear split: channel agents (forge-agents) vs batch workcells (forge-workcells) vs control plane SoR (Lenses).
  • Operators gain a single Granite deploy path (install-granite.sh) and registry API for agent lifecycle.
  • Cloners need autowww org read access to private forge-agents.
  • Packaging stubs (Hermes, OpenClaw, Factory) ship manifests without full runtimes until separate programs land.
  • Handbook readers find governance in platform docs/agents/; runnable code in forge-agents.