Skip to content

Platform Messaging Update System

The platform messaging update system gives first-tier untool.ai platform-building teams fast feedback loops without making GitHub, docs, or chat the polling interface.

The rule: NATS JetStream is the high-speed semantic bus. Webhooks are delivery projections from that bus for systems that cannot subscribe to NATS directly. GitHub Issues and PRs remain the durable evidence lane.

MECE Subject Families

Subject families must be mutually exclusive and collectively exhaustive for platform coordination messages. Do not overload one subject with mixed meanings.

Family Meaning Example subjects
platform.capability.* Capability lifecycle, availability, degradation, retirement, and source-of-truth changes. platform.capability.changed.v1
platform.adoption.* Repo/team adoption progress, validation evidence pointers, blockers, and closure. platform.adoption.status.v1
platform.hvfs.* Source-control substrate workspace, branch, commit, merge, diff, and file events. platform.hvfs.commit.v1
fleet.agent.* Agent handoff, heartbeat, claim, control, and coordination messages. fleet.agent.handoff.v1
platform.security.* Security evidence, waiver, incident, control-state, and remediation updates. platform.security.evidence.v1

The families are intentionally semantic, not implementation-owned. A backend service, MCP tool, webhook bridge, or Fleet Console panel may publish or consume a family, but the family name describes the message's platform meaning.

First-Tier Subscribers

First-tier access means these teams should be able to subscribe through NATS-native consumers, MCP discovery tools, or webhook projections as soon as a subject family exists:

Team/repo First subjects Why
backend-core platform.capability.*, platform.adoption.*, platform.hvfs.*, platform.security.* Owns UDA, data connectors, HVFS provider, security-sensitive backend state.
commons-core platform.hvfs.*, platform.capability.*, platform.adoption.* Owns shared agent-facing contracts such as the HVFS client.
agentarmy-forge platform.capability.*, platform.adoption.* Generates typed object and fixture outputs that must react to capability changes.
frontend-core platform.capability.*, platform.adoption.*, platform.security.* Surfaces readiness, adoption, evidence, and Fleet Console state.
middle-core fleet.agent.*, platform.capability.*, platform.adoption.* Bridges coordination, API/BFF flows, and agent-facing operations.
Fleet Console all families, read-only first Provides live operator visibility and HITL control.
Platform operators all families Own release, security, incident, and adoption feedback loops.

Delivery Lanes

Lane Use when Source of truth
NATS-native The consumer can hold a durable JetStream consumer and needs low-latency replayable updates. Fuseki/system ontology facts projected to NATS.
Webhook projection The consumer needs HTTPS push, service-token auth, or external integration delivery. NATS message plus subscription contract.
MCP discovery Coding agents need to list subjects, capability entries, adoption state, or subscription metadata. Local-fleet/untool MCP tools backed by feed, Fuseki, and audit state.
GitHub durable record A work item needs ownership, acceptance criteria, validation evidence, or closure. GitHub issue/PR state.

Webhook delivery must not become a second source of truth. A webhook subscription is a delivery intent. The canonical message is the NATS CloudEvent, and the canonical platform fact comes from the system ontology/Fuseki graph.

Webhook Subscription Contract

Webhook subscriptions are described by contracts/platform-update-subscription.schema.json.

Minimum semantics:

  • subscriptionId is stable and owned by the subscribing team.
  • deliveryMode is nats, webhook, or mcp.
  • subjectFilters name one or more MECE subject families or concrete subjects.
  • sink.url is required for webhook delivery.
  • auth declares the expected delivery authentication class.
  • replayPolicy declares whether the bridge should replay the latest message per key, replay from a sequence, or deliver new messages only.

The webhook bridge consumes NATS subjects using durable consumers, applies the subscription filter, POSTs CloudEvents to each sink, and records delivery result events under the appropriate family, such as platform.adoption.* or future platform.delivery.* if delivery state becomes large enough to deserve its own family.

HVFS Relationship

HVFS is the source-control substrate for the future untool.ai GitHub replacement. Its events belong under platform.hvfs.*, not under generic capability or fleet subjects.

GitHub stays in the loop during transition because Issues and PRs are still the durable human/audit surface. HVFS becomes the repository-state foundation: branches, commits, merges, diffs, virtual checkouts, file reads/writes, and content-addressed blobs.

Agent Behavior

Coding agents should:

  1. Discover available subject families through MCP.
  2. Subscribe natively to NATS when running inside the trusted platform network.
  3. Register or follow webhook subscription definitions when HTTP push is the right integration.
  4. Keep acceptance criteria and validation evidence in GitHub until the HVFS-native durable evidence surface exists.
  5. Preserve MECE boundaries when proposing new subjects.

Tracking

  • Messaging update system issue: #417
  • Capability log issue: #407
  • HVFS foundation issue: #416