{
  "id": "2026-05-07-redkey-coordination-api-platform-e0969214a3",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-07-redkey-coordination-api-platform.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.739Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "RedKey Coordination API Platform",
  "summary": "RedKey Coordination API Platform Purpose Build RedKey as the verified coordination API for parallel agent networks. The first visible wedge is OpenClaw, but the product is larger than an OpenClaw plugin. The core product is an API that gives any agent framework a shared HCS backed queue, role based claim eligibility, durable workflow events, missed claim awa...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Purpose",
      "level": 2,
      "body": "Build RedKey as the verified coordination API for parallel agent networks.\n\nThe first visible wedge is OpenClaw, but the product is larger than an OpenClaw plugin. The core product is an API that gives any agent framework a shared HCS-backed queue, role-based claim eligibility, durable workflow events, missed-claim awareness, and ledger receipts.\n\nThe public line:\n\n```text\nRedKey gives parallel agents a shared verified queue.\n```\n\nThe OpenClaw line:\n\n```text\nOpenClaw gives you agents. RedKey gives them a shared queue.\n```"
    },
    {
      "title": "Core Decision",
      "level": 2,
      "body": "Start with a hosted RedKey Coordination API, not only a GitHub plugin.\n\nThe GitHub repo should show how OpenClaw plugs into the API. It should provide the adapter, examples, and developer trust. The hosted RedKey product should own signup, OAuth, API keys, metering, HBAR funding, HCS-backed coordination, and receipts.\n\nThis creates a platform shape:\n\n```text\nRedKey Coordination API\n  |\n  |-- TypeScript SDK\n  |-- OpenClaw adapter\n  |-- Bezel recipe\n  |-- future LangGraph adapter\n  |-- future CrewAI adapter\n  |-- future custom agent clients\n```"
    },
    {
      "title": "HCS Boundary",
      "level": 2,
      "body": "Real coordination requires HCS.\n\nHCS is not an optional audit trail. It is the claim and queue mechanism. The abstraction is not about making HCS optional. The abstraction is about making HCS invisible to most developers.\n\nPublic primitives:\n\n- workspace\n- agent\n- A2A Agent Card\n- role\n- queue\n- task\n- claim\n- lease\n- workflow\n- event\n- receipt\n- ledger replay\n\nInternal primitives:\n\n- HCS topic\n- HCS sequence number\n- HCS consensus timestamp\n- Hedera transaction ID\n- operator account\n- topic routing\n- mirror-node verification\n- HBAR funding\n\nThe public API should not expose Hedera SDK usage, topic management, operator keys, or message construction."
    },
    {
      "title": "Product Layers",
      "level": 2,
      "body": "```text\nPublic clients\n  |\n  |-- OpenClaw adapter\n  |-- TypeScript SDK\n  |-- REST API\n  |\nRedKey public API\n  |\n  |-- auth and workspace control plane\n  |-- A2A Agent Card registry\n  |-- role and eligibility model\n  |-- coordination queue API\n  |-- ledger and receipt API\n  |-- usage and billing API\n  |\nRedKey internal execution\n  |\n  |-- HCS writer\n  |-- HCS reader/projector\n  |-- claim reducer\n  |-- workflow reducer\n  |-- metering service\n  |-- billing reconciliation\n```"
    },
    {
      "title": "Execution Modes",
      "level": 2,
      "body": "RedKey should support two execution modes."
    },
    {
      "title": "Simple Role Task",
      "level": 3,
      "body": "The simplest workflow is:\n\n```text\nput a task on a role\neligible agent claims it\nagent does it\nagent completes it\n```\n\nThis path should not require a workflow definition or `plan.json`.\n\nExample:\n\n```http\nPOST /queues/:queueId/tasks\n```\n\n```json\n{\n  \"title\": \"Research Piers Gorman\",\n  \"requiredRoles\": [\"role_researcher\"],\n  \"input\": {\n    \"guestName\": \"Piers Gorman\",\n    \"sourceHint\": \"TreviPay podcast planning doc\"\n  }\n}\n```\n\nThis creates one available task. Any active agent with `role_researcher` can claim it. The queue/HCS layer resolves the winning claim. The task completes or fails. No workflow engine needs to open follow-on tasks."
    },
    {
      "title": "Planned Workflow",
      "level": 3,
      "body": "Multi-step work should require a structured `plan.json`.\n\nThe plan is the contract between the user, the workflow reducer, and the agents. It prevents vague \"do this project\" prompts from turning into unmanaged agent activity.\n\nThe plan must break work into clear tasks with:\n\n- stable task IDs\n- required roles\n- required capabilities when needed\n- dependencies\n- expected inputs\n- expected outputs\n- completion criteria\n- retry policy\n- human approval gates when needed\n- artifact expectations\n\nThe workflow reducer reads ordered events and the plan, then opens the next eligible tasks.\n\n```text\nHCS ordered events + plan.json -> workflow reducer -> materialized workflow state -> available tasks\n```"
    },
    {
      "title": "Plan JSON",
      "level": 2,
      "body": "`plan.json` is required for multi-step workflows.\n\nMinimum shape:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"name\": \"podcast-production\",\n  \"description\": \"Prepare a podcast episode from guest intake through host-approved script.\",\n  \"roles\": {\n    \"producer\": {\n      \"description\": \"Owns intake, structure, and final packaging.\"\n    },\n    \"researcher\": {\n      \"description\": \"Finds and summarizes relevant background.\"\n    },\n    \"writer\": {\n      \"description\": \"Drafts host-ready copy.\"\n    },\n    \"reviewer\": {\n      \"description\": \"Checks quality, accuracy, and fit.\"\n    }\n  },\n  \"tasks\": [\n    {\n      \"id\": \"guest_intake\",\n      \"title\": \"Summarize guest and topic brief\",\n      \"role\": \"producer\",\n      \"dependsOn\": [],\n      \"input\": {\n        \"sources\": [\"planning_doc\"]\n      },\n      \"outputs\": [\"guest_brief\"],\n      \"completionCriteria\": [\n        \"Guest background summarized\",\n        \"Target episode angle identified\",\n        \"Known constraints captured\"\n      ]\n    },\n    {\n      \"id\": \"guest_research\",\n      \"title\": \"Research guest and market context\",\n      \"role\": \"researcher\",\n      \"dependsOn\": [\"guest_intake\"],\n      \"requiredCapabilities\": [\"web_search\", \"source_review\"],\n      \"outputs\": [\"research_packet\"],\n      \"completionCriteria\": [\n        \"At least five useful facts found\",\n        \"Sources included\",\n        \"Open questions listed\"\n      ]\n    },\n    {\n      \"id\": \"draft_script\",\n      \"title\": \"Draft podcast script\",\n      \"role\": \"writer\",\n      \"dependsOn\": [\"guest_intake\", \"guest_research\"],\n      \"outputs\": [\"script_draft\"],\n      \"completionCriteria\": [\n        \"Intro, segments, transitions, and closing included\",\n        \"Questions are specific to guest and topic\",\n        \"Host voice is preserved\"\n      ]\n    },\n    {\n      \"id\": \"review_script\",\n      \"title\": \"Review podcast script\",\n      \"role\": \"reviewer\",\n      \"dependsOn\": [\"draft_script\"],\n      \"approvalGate\": true,\n      \"outputs\": [\"review_notes\"],\n      \"completionCriteria\": [\n        \"Accuracy issues flagged\",\n        \"Weak questions improved\",\n        \"Ready for host review or returned with notes\"\n      ]\n    }\n  ],\n  \"policies\": {\n    \"maxParallelTasks\": 5,\n    \"defaultLeaseSeconds\": 900,\n    \"retry\": {\n      \"maxAttempts\": 2,\n      \"onFailure\": \"reopen\"\n    }\n  }\n}\n```"
    },
    {
      "title": "Plan Requirements",
      "level": 3,
      "body": "RedKey should validate plans before starting a workflow.\n\nRequired checks:\n\n- every task has a stable unique ID\n- every task has exactly one primary role\n- every referenced role exists\n- dependencies reference valid task IDs\n- dependency graph has no cycles\n- every task has completion criteria\n- outputs are named\n- approval gates are explicit\n- retry policy is explicit\n- max parallelism is explicit\n\nBest-practice warnings:\n\n- task is too broad\n- task has no concrete output\n- task depends on too many upstream tasks\n- task has unclear completion criteria\n- plan has too much serial work and not enough parallelizable work\n- role names are vague\n- task asks one agent to both produce and review the same artifact\n\nValidation endpoint:\n\n```http\nPOST /workflow-definitions/validate\n```\n\nStart workflow from plan:\n\n```http\nPOST /workflows\n```\n\n```json\n{\n  \"queueId\": \"queue_podcast\",\n  \"plan\": {\n    \"version\": \"1.0\",\n    \"name\": \"podcast-production\",\n    \"tasks\": []\n  }\n}\n```\n\nThe response should include validation results and the initial available tasks:\n\n```json\n{\n  \"workflowId\": \"wf_123\",\n  \"status\": \"running\",\n  \"availableTasks\": [\"guest_intake\"],\n  \"eventId\": \"evt_workflow_started_001\"\n}\n```"
    },
    {
      "title": "Public API Surfaces",
      "level": 2,
      "body": "Expose the smallest set of surfaces required to run both simple role tasks and planned workflows."
    },
    {
      "title": "1. Auth And Workspace API",
      "level": 3,
      "body": "Handles signup, OAuth, API keys, workspaces, and usage visibility.\n\nEndpoints:\n\n```http\nPOST /oauth/token\nGET  /workspaces\nPOST /workspaces\nGET  /usage\nGET  /billing/credits\n```\n\nHosted plans use RedKey-managed HBAR funding. Enterprise plans may use customer-owned Hedera accounts and topics behind a managed setup flow."
    },
    {
      "title": "2. Agent Registry API",
      "level": 3,
      "body": "Agents should register through A2A Agent Cards.\n\nPrimary endpoint:\n\n```http\nPOST /agents/register-card\n```\n\nSupported payloads:\n\n```json\n{\n  \"workspaceId\": \"wk_123\",\n  \"agentCardUrl\": \"https://agent.example.com/.well-known/agent.json\"\n}\n```\n\nor:\n\n```json\n{\n  \"workspaceId\": \"wk_123\",\n  \"agentCard\": {\n    \"name\": \"Research Agent\",\n    \"description\": \"Finds and summarizes source material\",\n    \"url\": \"https://agent.example.com/a2a\",\n    \"version\": \"1.0.0\",\n    \"skills\": [],\n    \"capabilities\": {}\n  }\n}\n```\n\nRedKey ingests the Agent Card and normalizes:\n\n- agent identity\n- endpoint\n- framework\n- capabilities\n- skills\n- auth requirements\n- verification status\n- eligible roles\n\nAdditional endpoints:\n\n```http\nGET  /agents\nGET  /agents/:agentId\nPOST /agents/:agentId/heartbeat\nPOST /agents/:agentId/deactivate\n```\n\nAgent registration should be a metered verified event when written to the coordination ledger:\n\n```text\nagent.registered\n```"
    },
    {
      "title": "3. Role And Eligibility API",
      "level": 3,
      "body": "Roles decide which agents are allowed to claim which tasks.\n\nKeep v1 roles simple. They are not full enterprise RBAC yet. In v1:\n\n```text\nRole = eligibility to claim certain tasks\n```\n\nEndpoints:\n\n```http\nPOST /roles\nGET  /roles\nGET  /roles/:roleId\nPOST /roles/:roleId/agents/:agentId\nDELETE /roles/:roleId/agents/:agentId\n```\n\nRole shape:\n\n```json\n{\n  \"id\": \"role_researcher\",\n  \"name\": \"Researcher\",\n  \"description\": \"Finds source material and summarizes relevant findings\",\n  \"capabilities\": [\"web_search\", \"source_review\"]\n}\n```\n\nClaim eligibility checks:\n\n- agent is active\n- agent has the required role\n- agent has required capabilities\n- task dependencies are satisfied\n- task is available\n- claim lease can be issued\n- HCS ordering confirms the claim outcome"
    },
    {
      "title": "4. Coordination API",
      "level": 3,
      "body": "This is the core queue and claim surface. It supports simple role tasks directly.\n\nEndpoints:\n\n```http\nPOST /queues\nGET  /queues\nPOST /queues/:queueId/tasks\nGET  /queues/:queueId/tasks/available\nPOST /tasks/:taskId/claim\nPOST /claims/:claimId/heartbeat\nPOST /claims/:claimId/complete\nPOST /claims/:claimId/fail\nGET  /workflows/:workflowId/state\nGET  /workflows/:workflowId/events\n```\n\nTask shape:\n\n```json\n{\n  \"queueId\": \"queue_podcast\",\n  \"workflowId\": \"wf_789\",\n  \"title\": \"Research Piers Gorman\",\n  \"requiredRoles\": [\"role_researcher\"],\n  \"requiredCapabilities\": [\"web_search\", \"source_review\"],\n  \"dependsOn\": [],\n  \"priority\": \"normal\",\n  \"input\": {\n    \"guestName\": \"Piers Gorman\"\n  }\n}\n```\n\nClaim request:\n\n```json\n{\n  \"agentId\": \"agt_123\",\n  \"leaseSeconds\": 600,\n  \"idempotencyKey\": \"claim-task_456-agt_123-001\"\n}\n```\n\nClaim success:\n\n```json\n{\n  \"status\": \"claimed\",\n  \"taskId\": \"task_456\",\n  \"claimId\": \"clm_789\",\n  \"agentId\": \"agt_123\",\n  \"leaseExpiresAt\": \"2026-05-07T20:15:00Z\",\n  \"eventId\": \"evt_claimed_001\"\n}\n```"
    },
    {
      "title": "5. Workflow Definition API",
      "level": 3,
      "body": "This is the planned multi-step workflow surface.\n\nEndpoints:\n\n```http\nPOST /workflow-definitions/validate\nPOST /workflow-definitions\nGET  /workflow-definitions\nGET  /workflow-definitions/:definitionId\nPATCH /workflow-definitions/:definitionId\nPOST /workflow-definitions/:definitionId/versions\nPOST /workflow-definitions/:definitionId/publish\n```\n\n`POST /workflow-definitions/validate` should be usable before a workflow is saved or started. It returns blocking validation errors and non-blocking best-practice warnings."
    },
    {
      "title": "6. Workflow Run API",
      "level": 3,
      "body": "This is the execution surface for a validated `plan.json`.\n\nEndpoints:\n\n```http\nPOST /workflows\nGET  /workflows\nGET  /workflows/:workflowId\nGET  /workflows/:workflowId/state\nGET  /workflows/:workflowId/events\nPOST /workflows/:workflowId/pause\nPOST /workflows/:workflowId/resume\nPOST /workflows/:workflowId/cancel\n```\n\nThe workflow reducer owns task opening. Agents do not decide what comes next. Agents claim available tasks, execute them, and complete or fail them."
    },
    {
      "title": "Missed Claim Awareness",
      "level": 2,
      "body": "Agents need to know when they attempted to claim work but did not win.\n\nThis should be first-class, not a generic error. A missed claim is useful coordination information. It tells an agent:\n\n- another agent already owns the task\n- the agent should stop preparing to work on it\n- the agent can ask for more available work\n- the system can measure contention\n\nClaim miss response:\n\n```json\n{\n  \"status\": \"missed\",\n  \"taskId\": \"task_456\",\n  \"agentId\": \"agt_999\",\n  \"reason\": \"claim_already_won\",\n  \"winningClaimId\": \"clm_789\",\n  \"winningAgentId\": \"agt_123\",\n  \"eventId\": \"evt_claim_missed_002\",\n  \"next\": {\n    \"action\": \"poll_available_tasks\",\n    \"queueId\": \"queue_podcast\"\n  }\n}\n```\n\nEvent types:\n\n```text\ntask.claim_attempted\ntask.claimed\ntask.claim_missed\ntask.claim_rejected\n```\n\nUse `claim_missed` when the agent was eligible and the task was claimable, but another valid claim won first.\n\nUse `claim_rejected` when the agent was not allowed to claim:\n\n- missing role\n- missing capability\n- inactive agent\n- failed policy\n- task dependency not satisfied\n- invalid lease request\n\nThis distinction matters. A missed claim is normal parallel coordination. A rejected claim is a policy or state problem.\n\nAgents should also be able to subscribe or poll for missed claims:\n\n```http\nGET /agents/:agentId/events?type=task.claim_missed\nGET /agents/:agentId/claim-history\n```\n\nAgent-facing guidance:\n\n```text\nIf claim returns \"missed\", do not retry the same task immediately.\nAsk for the next available task in the queue.\n```"
    },
    {
      "title": "Ledger And Receipt API",
      "level": 2,
      "body": "The ledger API should expose what happened, not raw HCS internals.\n\nEndpoints:\n\n```http\nGET /events/:eventId\nGET /events/:eventId/receipt\nGET /tasks/:taskId/events\nGET /claims/:claimId/events\nGET /agents/:agentId/events\nGET /workflows/:workflowId/events\nGET /ledger/query\n```\n\nReceipt shape:\n\n```json\n{\n  \"eventId\": \"evt_123\",\n  \"type\": \"task.claimed\",\n  \"sequence\": 55291,\n  \"timestamp\": \"2026-05-07T18:15:00Z\",\n  \"actor\": {\n    \"type\": \"agent\",\n    \"id\": \"agt_123\"\n  },\n  \"subject\": {\n    \"type\": \"task\",\n    \"id\": \"task_456\"\n  },\n  \"verification\": {\n    \"status\": \"verified\",\n    \"provider\": \"redkey\",\n    \"receiptUrl\": \"https://redkey.ai/receipts/evt_123\"\n  }\n}\n```\n\nInternal receipt metadata may include HCS topic IDs, sequence numbers, consensus timestamps, and transaction IDs. Do not require normal developers to handle those fields."
    }
  ],
  "html_path": "artifacts/2026-05-07-redkey-coordination-api-platform-e0969214a3.html",
  "json_path": "artifacts/2026-05-07-redkey-coordination-api-platform-e0969214a3.json"
}