Version 0.2.0 - Hypermedia Swarm Protocol Reference Implementation

A minimal, hypermedia-driven agent swarm proof-of-concept implementing Hypergents v1.0 using:

• Deno runtime
• HAL + HAL-FORMS representations
• Lease-based tasks (ETag/If-Match)
• Idempotency-Key (retry-safe transitions)
• SSE events (hypergents:events) to avoid polling storms
• A simple HTMX dashboard (optional, for A2U)

This repo is intentionally small but “production-shaped”: the boring distributed-systems mechanics are part of the protocol.

deno task dev

Server listens on: http://localhost:8787

• GET / root (discover entry points)
• GET /policy/navigation navigation policy (agent “CSP”)
• GET /hive?capability=research directory offers
• POST /hive/register register an agent (TTL lease)
• GET /agents/:id agent resource
• POST /agents/:id/tasks delegate: create a task assigned to an agent

• GET /tasks list tasks
• GET /tasks/:id task (HAL-FORMS templates gated by state)
• POST /tasks/:id/claim claim lease (Idempotency-Key + If-Match required)
• POST /tasks/:id/heartbeat renew lease (owner only)
• POST /tasks/:id/checkpoint save progress (owner only)
• POST /tasks/:id/complete succeed (owner only, If-Match)
• POST /tasks/:id/fail fail (owner only, If-Match)
• POST /tasks/:id/cancel cancel task (owner only for leased/running)
• GET /tasks/:id/result fetch result

• POST /tasks/:id/subtasks create child task (owner only, parent must be running)
• GET /tasks/:id/subtasks list direct child tasks
• GET /tasks/:id/subtasks/events SSE stream of subtask state changes

Six predefined roles for orchestrated workflows: orchestrator, architect, developer, reviewer, tester, security. Each role has specific capabilities and the hive routes subtasks by capability match. See docs/user-guide.md for details.

• GET /events global SSE stream
• GET /tasks/:id/events task SSE stream
• GET /agents/:id/events agent SSE stream

• GET /ui HTMX dashboard (polls /ui/dashboard)

curl -s -X POST http://localhost:8787/hive/register \
  -H 'content-type: application/json' \
  -d '{"agentId":"research-01","capabilities":["research","summarize","web_search"]}' | jq

curl -i -s -X POST http://localhost:8787/agents/research-01/tasks \
  -H 'content-type: application/json' \
  -H 'idempotency-key: demo-create-1' \
  -d '{"description":"Summarize this text","input":{"text":"hello world"}}'

Copy Location: or read the self.href in JSON.

curl -i -s http://localhost:8787/tasks/<TASK_ID>

Copy the ETag: header value.

curl -i -s -X POST http://localhost:8787/tasks/<TASK_ID>/claim \
  -H 'content-type: application/json' \
  -H 'x-agent-id: research-01' \
  -H 'idempotency-key: demo-claim-1' \
  -H 'if-match: W/"rev-1"' \
  -d '{"leaseTtlSeconds":30}'

curl -i -s -X POST http://localhost:8787/tasks/<TASK_ID>/checkpoint \
  -H 'content-type: application/json' \
  -H 'x-agent-id: research-01' \
  -H 'idempotency-key: demo-cp-1' \
  -H 'if-match: W/"rev-2"' \
  -d '{"pct":50,"message":"halfway"}'

curl -i -s -X POST http://localhost:8787/tasks/<TASK_ID>/complete \
  -H 'content-type: application/json' \
  -H 'x-agent-id: research-01' \
  -H 'idempotency-key: demo-ok-1' \
  -H 'if-match: W/"rev-3"' \
  -d '{"result":{"text":"done"}}'

curl -s http://localhost:8787/tasks/<TASK_ID>/result | jq

Orchestrators can decompose work into subtasks. Subtasks inherit correlationId from their parent and maintain parent-child links via hypergents:parent-task and hypergents:subtasks rels.

curl -s -X POST http://localhost:8787/hive/register \
  -H 'content-type: application/json' \
  -d '{"agentId":"orchestrator","capabilities":["orchestrate"]}'

curl -s -X POST http://localhost:8787/hive/register \
  -H 'content-type: application/json' \
  -d '{"agentId":"worker-1","capabilities":["research"]}'

# Create task
curl -i -X POST http://localhost:8787/agents/orchestrator/tasks \
  -H 'content-type: application/json' \
  -H 'idempotency-key: parent-create' \
  -d '{"description":"Coordinate research"}'

# Claim (use ETag from GET)
curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/claim \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: parent-claim' \
  -H 'if-match: W/"rev-1"' \
  -d '{"leaseTtlSeconds":60}'

# Start (use ETag from GET)
curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/start \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: parent-start' \
  -H 'if-match: W/"rev-2"' \
  -d '{}'

# Create a subtask routed via hive (by capability)
curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/subtasks \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: sub-1' \
  -H 'if-match: W/"rev-3"' \
  -d '{"description":"Research topic A","capability":"research"}'

# Or create a subtask directly assigned to an agent
curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/subtasks \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: sub-2' \
  -H 'if-match: W/"rev-3"' \
  -d '{"description":"Research topic B","agentId":"worker-1"}'

# List subtasks
curl -s http://localhost:8787/tasks/<PARENT_ID>/subtasks | jq

# Parent task now shows subtaskSummary
curl -s http://localhost:8787/tasks/<PARENT_ID> | jq '.subtaskSummary'
# { "total": 2, "pending": 2, "running": 0, "succeeded": 0, "failed": 0, "canceled": 0 }

Workers claim, start, and complete subtasks using the normal task workflow. Once all subtasks reach terminal states, the parent can complete:

# (After all children are succeeded/failed/canceled)
curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/complete \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: parent-complete' \
  -H 'if-match: W/"rev-N"' \
  -d '{"result":{"aggregated":"results"}}'

Canceling a parent automatically cancels all non-terminal children:

curl -i -X POST http://localhost:8787/tasks/<PARENT_ID>/cancel \
  -H 'x-agent-id: orchestrator' \
  -H 'idempotency-key: parent-cancel' \
  -H 'if-match: W/"rev-N"' \
  -d '{}'

• ETag + If-Match prevents double-claim and racey completion.
• Idempotency-Key makes retries safe under network churn.
• Lease + heartbeat enables crash recovery and re-claiming.
• Navigation policy prevents "follow hostile links" SSRF/confused-deputy attacks.
• SSE reduces load vs polling.
• Hierarchical orchestration enables task decomposition while preserving HATEOAS: orchestrators discover the hypergents:create-subtask affordance on running tasks they own; child tasks link back via hypergents:parent-task; the parent maintains an incremental subtaskSummary for monitoring; completion is gated until all children reach terminal states; cancel cascades automatically.

• docs/user-guide.md — comprehensive user guide
• docs/hypergents-v1.0.md — protocol spec (HAL + HAL-FORMS)
• docs/north-star.md — conceptual target
• docs/rel-registry.md — canonical rel vocabulary
• docs/rel-registry.v1.json — strict rel registry (machine-readable)
• docs/embedded-layout.v1.json — canonical _embedded keys (machine-readable)
• docs/schemas/ — JSON Schemas (draft 2020-12)

• tests/conformance/ — outline + minimal conformance tests + golden fixtures

MIT

Run conformance suite:

deno task conformance

Populate/update golden fixtures:

deno task goldens:update

Golden fixtures live in tests/conformance/golden/.

Note: Snapshot normalization is driven by docs/rel-registry.v1.json#canonicalization.

Conformance snapshots run in strict mode by default.

Disable strict mode (not recommended):

HSP_SNAPSHOT_STRICT=0 deno task conformance

Conformance validates response bodies against kind-specific schemas in docs/schemas/ to enforce no undeclared fields.

Disable schema gate (not recommended):

HSP_SCHEMA_STRICT=0 deno task conformance