{
  "id": "2026-04-25-agent-inbox-design-71a08a5ad9",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-25-agent-inbox-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.672Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Agent Inbox Design — HCS-10/11 Compliant Messaging",
  "summary": "Agent Inbox Design — HCS 10/11 Compliant Messaging Date: 2026 04 25 Status: Approved for implementation Overview Every agent (and Justin) has a persistent, on chain inbox. Agent to agent messages are posted to HCS topic topics first — Supabase is the fast read mirror. The listener bridges HCS → Supabase. The runner polls Supabase inbox as the fast path each ...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Agent Inbox Design — HCS-10/11 Compliant Messaging",
      "level": 1,
      "body": "**Date:** 2026-04-25  \n**Status:** Approved for implementation\n\n---"
    },
    {
      "title": "Overview",
      "level": 2,
      "body": "Every agent (and Justin) has a persistent, on-chain inbox. Agent-to-agent messages are posted to HCS topic topics first — Supabase is the fast-read mirror. The listener bridges HCS → Supabase. The runner polls Supabase inbox as the fast path each cycle.\n\n---"
    },
    {
      "title": "Topic Structure Per Agent (HCS-10 Compliant)",
      "level": 2,
      "body": "Each agent gets **two HCS topics**, created once and stored in `agent_definitions`:\n\n| Topic | Memo Format | Purpose |\n|---|---|---|\n| **Inbound** | `hcs-10:0:3600:0:{accountId}` | Receives messages from other agents and system |\n| **Outbound** | `hcs-10:0:3600:1` | Agent's public activity log (future use) |\n\n`agent_definitions` gains two new columns: `inbound_topic_id`, `outbound_topic_id`.  \nExisting `hcs_topic_id` column is retired (was never populated).\n\nJustin (`slug: justin`) gets topics too — he is a first-class participant.\n\n---"
    },
    {
      "title": "Message Format (HCS-10 Compatible)",
      "level": 2,
      "body": "Messages posted to an agent's inbound topic:\n\n```json\n{\n  \"p\": \"hcs-10\",\n  \"op\": \"message\",\n  \"operator_id\": \"{sender_inbound_topic}@{sender_account}\",\n  \"data\": {\n    \"message_type\": \"task.blocked | task.complete | task.note | phase.note | project.note | feedback | fyi | review.request\",\n    \"subject\": \"Human-readable subject line\",\n    \"payload\": {},\n    \"ref_id\": \"0.0.XXXXX\",\n    \"ref_type\": \"task | phase | stage | project | agent\",\n    \"priority\": 1\n  },\n  \"ts\": \"ISO8601\"\n}\n```\n\n**Priority:** 1=urgent, 2=high, 3=normal, 4=low, 5=fyi\n\n**Internal shortcut:** Trusted internal agents can post directly without the full HCS-10 connection handshake. External agent interop (connection_request → connection_created → connection topic) is a future enhancement.\n\n---"
    },
    {
      "title": "Entity Notes",
      "level": 2,
      "body": "Agents can post notes directly to entity topics (tasks, phases, stages, projects):\n\n```json\n{\n  \"type\": \"task.note | phase.note | project.note\",\n  \"from_agent\": \"quinn\",\n  \"note\": \"markdown content\",\n  \"notify\": [\"mindy\", \"justin\"],\n  \"ts\": \"ISO8601\"\n}\n```\n\nThe listener routes `*.note` messages → inbox of agents in `notify` list.\n\n---"
    },
    {
      "title": "Supabase Inbox Table (`inbox`)",
      "level": 2,
      "body": "Fast-read mirror. Runner polls this each cycle.\n\n```sql\ninbox (\n  id                   uuid PK,\n  to_agent             text NOT NULL,       -- agent slug or 'ALL'\n  from_agent           text NOT NULL,       -- agent slug or 'system'\n  message_type         text NOT NULL,\n  subject              text NOT NULL,\n  payload              jsonb,\n  context              jsonb,               -- additional context for rich info sharing\n  ref_id               text,               -- entity topic_id or UUID\n  ref_type             text,               -- task | phase | stage | project | agent\n  priority             int DEFAULT 3,\n  processed            bool DEFAULT false,\n  processed_at         timestamptz,\n  processed_by_session uuid,\n  created_at           timestamptz DEFAULT now()\n)\n```\n\nIndexes: `(to_agent, processed, created_at)`, `(ref_id)`, `(from_agent, created_at desc)`\n\n---"
    },
    {
      "title": "New: `handle_agent_topics()`",
      "level": 3,
      "body": "- Queries `agent_definitions` for all `inbound_topic_id` values\n- Polls each, processes `op: \"message\"` → writes to Supabase `inbox`\n- Handles `*.note` on entity topics → routes to `notify` list inboxes"
    },
    {
      "title": "New: `send_inbox()` helper",
      "level": 3,
      "body": "Direct Supabase write for system-originated notifications (no round-trip through HCS):\n\n| Event observed | Who gets inbox message | Priority |\n|---|---|---|\n| `task.blocked` | mindy + justin | 1 (urgent) |\n| `task.complete` | engine | 3 (normal) |\n| `phase.complete` | engine + mindy | 2 (high) |\n| `*.note` | agents in `notify` field | per note |\n\n---"
    },
    {
      "title": "Runner Changes",
      "level": 2,
      "body": "`fetch_inbox()` in `base.py` already queries `inbox` table — no change needed once migration is applied and table exists.\n\n---"
    },
    {
      "title": "MCP Tool: `send_message`",
      "level": 2,
      "body": "Agents call this during sessions to send a message to another agent or Justin:\n\n```json\n{\n  \"name\": \"send_message\",\n  \"description\": \"Send a message to another agent or Justin. Posts to their HCS inbound topic (on-chain) and writes to Supabase inbox (fast-read). Use for: blocked issues, review requests, FYIs, feedback, questions.\",\n  \"inputSchema\": {\n    \"to_agent\": \"string — agent slug or 'ALL' or 'justin'\",\n    \"message_type\": \"string — 'feedback' | 'fyi' | 'review.request' | 'task.note' | ...\",\n    \"subject\": \"string\",\n    \"payload\": \"object — structured content\",\n    \"ref_id\": \"string — entity topic_id\",\n    \"ref_type\": \"string — task | phase | stage | project | agent\",\n    \"priority\": \"integer — 1-5\"\n  }\n}\n```\n\n**Flow:** `send_message` → post to recipient's `inbound_topic_id` on HCS → listener materializes to `inbox` on next cycle → recipient's runner sees it on next poll.\n\n**Fast-path alternative:** For urgent messages (priority ≤ 2), `send_message` also writes directly to Supabase `inbox` in addition to HCS, so recipient sees it within seconds not minutes.\n\n---"
    },
    {
      "title": "MCP Tool: `post_note`",
      "level": 2,
      "body": "Post a note to an entity topic. Creates on-chain commentary thread per entity.\n\n```json\n{\n  \"name\": \"post_note\",\n  \"description\": \"Post a note to a task, phase, stage, or project topic. Creates permanent on-chain record. Notified agents receive inbox message immediately.\",\n  \"inputSchema\": {\n    \"entity_id\": \"string — topic_id (0.0.XXXXX)\",\n    \"entity_type\": \"string — task | phase | stage | project\",\n    \"note\": \"string — markdown content\",\n    \"notify\": \"array of agent slugs to notify\"\n  }\n}\n```\n\n---"
    },
    {
      "title": "Implementation Steps",
      "level": 2,
      "body": "1. **Migration** `supabase/migrations/021_agent_topic_columns.sql` — add `inbound_topic_id`, `outbound_topic_id` to `agent_definitions`\n2. **Migration** `supabase/migrations/020_inbox.sql` — inbox table (already written)\n3. **Script** `scripts/create-agent-topics.js` — create HCS topics for all agents, update Supabase, republish HCS-11 profiles\n4. **Listener** — add `handle_agent_topics()`, `send_inbox()` helper, entity event routing\n5. **hedera-tools.js** — add `send_message` and `post_note` tools\n6. **Justin's inbox** — `node scripts/inbox.js` CLI reader\n\n---"
    },
    {
      "title": "HCS-11 Profile Shape Per Agent",
      "level": 2,
      "body": "Published to the shared definitions topic when agent topics are created:\n\n```json\n{\n  \"type\": \"agent_definition\",\n  \"agent\": {\n    \"slug\": \"quinn\",\n    \"name\": \"Quinn\",\n    \"hcs11_profile\": {\n      \"version\": \"1.0\",\n      \"type\": 1,\n      \"display_name\": \"Quinn\",\n      \"aiAgent\": {\n        \"type\": 1,\n        \"model\": \"claude-sonnet-4-6\",\n        \"capabilities\": [4, 16, 18]\n      },\n      \"inboundTopicId\": \"0.0.XXXXX\",\n      \"outboundTopicId\": \"0.0.XXXXX\"\n    }\n  }\n}\n```\n\nCapability codes used: 4=Code Generation, 16=Multi-Agent Coordination, 18=Workflow Automation. Per-agent capabilities differ by role."
    }
  ],
  "html_path": "artifacts/2026-04-25-agent-inbox-design-71a08a5ad9.html",
  "json_path": "artifacts/2026-04-25-agent-inbox-design-71a08a5ad9.json"
}