{
  "id": "2026-05-06-agent-wire-v1-1-a2a-hardening-afd10dee21",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-06-agent-wire-v1-1-a2a-hardening.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.702Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Agent Wire v1.1 + A2A Hardening Spec",
  "summary": "Agent Wire v1.1 + A2A Hardening Spec Date: 2026 05 06 Status: Draft for implementation planning Supersedes / extends: docs/specs/2026 04 28 agent wire protocol.md, docs/specs/2026 05 01 hcs streaming wire protocol.md Related: docs/specs/2026 04 27 google agent sdk a2a.md, docs/plans/2026 04 27 a2a gateway.md Purpose Agent Wire is RedKey's internal coordinati...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Agent Wire v1.1 + A2A Hardening Spec",
      "level": 1,
      "body": "**Date:** 2026-05-06\n**Status:** Draft for implementation planning\n**Supersedes / extends:** `docs/specs/2026-04-28-agent-wire-protocol.md`, `docs/specs/2026-05-01-hcs-streaming-wire-protocol.md`\n**Related:** `docs/specs/2026-04-27-google-agent-sdk-a2a.md`, `docs/plans/2026-04-27-a2a-gateway.md`\n\n---"
    },
    {
      "title": "Purpose",
      "level": 2,
      "body": "Agent Wire is RedKey's internal coordination protocol. A2A is the external interoperability protocol for agent-to-agent collaboration. This spec uses A2A v1.0 as a hardening reference for Agent Wire without replacing RedKey's HCS-first architecture.\n\nThe intended outcome is:\n\n```text\nInternal RedKey agents\n  -> Agent Wire v1.1 events\n  -> HCS canonical stream\n  -> Supabase read model\n  -> Studio / runners / evaluators\n\nExternal A2A callers\n  -> A2A gateway\n  -> translation to/from Agent Wire v1.1\n  -> same HCS canonical stream\n```\n\nThis keeps one internal source of truth. A2A becomes a boundary binding, not a second execution model.\n\n---"
    },
    {
      "title": "Decision",
      "level": 2,
      "body": "Do both hardening tracks together at the schema/spec level:\n\n1. Upgrade Agent Wire from a typed message envelope into a typed streaming protocol.\n2. Borrow A2A's task, context, message, artifact, streaming, and capability concepts where they improve internal RedKey clarity.\n3. Make the protocol deterministic by requiring state-machine contracts, JSON Schemas, golden fixtures, conformance tests, and reducer tests before production implementation.\n\nDo not implement a separate A2A streaming subsystem. RedKey streaming remains HCS-backed Agent Wire. The A2A gateway later maps that stream to A2A `SendStreamingMessage`, `SubscribeToTask`, `TaskStatusUpdateEvent`, and `TaskArtifactUpdateEvent`.\n\n---"
    },
    {
      "title": "Deterministic Contract Standard",
      "level": 2,
      "body": "Agent Wire v1.1 must be implemented as contracts that code validates, not prose that agents interpret.\n\nRequired pipeline:\n\n```text\nspec\n  -> state-machine contract\n  -> JSON Schema\n  -> golden fixtures\n  -> conformance tests\n  -> implementation\n  -> reducer/state tests\n  -> HCS event record\n```\n\nRules:\n\n- Prose explains why. Structured contracts define what is valid.\n- Agents may draft specs, fixtures, and code, but validation decides authority.\n- Every event type must have a JSON Schema before producers emit it.\n- Every event type must have at least one valid golden fixture.\n- Every important invalid case must have a named invalid fixture.\n- Every state transition must be represented in a state-machine contract.\n- Reducer tests must prove ordered Wire events reduce to exact task/artifact/project state.\n- A2A mapping must be conformance-tested from Agent Wire events, not hand-waved in prose."
    },
    {
      "title": "Required Contract Paths",
      "level": 3,
      "body": "The first v1.1 implementation should create these directories:\n\n```text\nschemas/agent-wire/v1.1/\nfixtures/agent-wire/v1.1/\ncontracts/agent-wire/v1.1/\ntests/conformance/agent-wire/\ntests/reducers/agent-wire/\n```\n\nMinimum schema files:\n\n```text\nschemas/agent-wire/v1.1/envelope.schema.json\nschemas/agent-wire/v1.1/stream.schema.json\nschemas/agent-wire/v1.1/state.schema.json\nschemas/agent-wire/v1.1/task-created.schema.json\nschemas/agent-wire/v1.1/task-available.schema.json\nschemas/agent-wire/v1.1/task-claimed.schema.json\nschemas/agent-wire/v1.1/task-started.schema.json\nschemas/agent-wire/v1.1/task-blocked.schema.json\nschemas/agent-wire/v1.1/artifact-ready.schema.json\nschemas/agent-wire/v1.1/task-complete.schema.json\nschemas/agent-wire/v1.1/task-failed.schema.json\nschemas/agent-wire/v1.1/task-cancelled.schema.json\n```\n\nMinimum fixture files:\n\n```text\nfixtures/agent-wire/v1.1/task-created.valid.json\nfixtures/agent-wire/v1.1/task-available.valid.json\nfixtures/agent-wire/v1.1/task-claimed.valid.json\nfixtures/agent-wire/v1.1/task-started.valid.json\nfixtures/agent-wire/v1.1/artifact-ready.valid.json\nfixtures/agent-wire/v1.1/task-complete.valid.json\nfixtures/agent-wire/v1.1/task-complete.invalid-missing-artifact.json\nfixtures/agent-wire/v1.1/task-complete.invalid-verification-fail.json\nfixtures/agent-wire/v1.1/task-blocked.valid.json\nfixtures/agent-wire/v1.1/task-failed.valid.json\nfixtures/agent-wire/v1.1/task-cancelled.valid.json\n```\n\nMinimum contract files:\n\n```text\ncontracts/agent-wire/v1.1/task-state-machine.json\ncontracts/agent-wire/v1.1/event-state-map.json\ncontracts/agent-wire/v1.1/a2a-task-state-map.json\n```"
    },
    {
      "title": "Required Conformance Tests",
      "level": 3,
      "body": "The implementation is not conformant until tests prove:\n\n- Every valid fixture validates against the event schema and envelope schema.\n- Every invalid fixture fails for the expected reason.\n- Every event maps to exactly one normalized state category.\n- Every allowed transition is accepted by the state machine.\n- Every disallowed transition is rejected by the state machine.\n- The reducer can replay ordered Wire events into exact task state.\n- The reducer records artifact counts and artifact IDs from `artifact.ready`.\n- `task.complete.payload.artifact_ids` references all required final artifacts.\n- `task.complete.payload.verification.mechanical` must be `pass`.\n- Agent Wire task/artifact events map cleanly to A2A task/artifact events."
    },
    {
      "title": "Reducer Harness Contract",
      "level": 3,
      "body": "Reducer tests should use this shape:\n\n```json\n{\n  \"name\": \"happy path with one artifact\",\n  \"events\": [\n    \"task.created\",\n    \"task.available\",\n    \"task.claimed\",\n    \"task.started\",\n    \"artifact.ready\",\n    \"task.complete\"\n  ],\n  \"expected\": {\n    \"task_state\": \"completed\",\n    \"terminal\": true,\n    \"artifact_count\": 1,\n    \"blocked\": false,\n    \"verification\": {\n      \"mechanical\": \"pass\"\n    }\n  }\n}\n```\n\nNo LLM interpretation is allowed in reducer tests. Input is ordered Wire events. Output is exact state.\n\n---"
    },
    {
      "title": "Non-Goals",
      "level": 2,
      "body": "- Do not replace HCS as the canonical coordination stream.\n- Do not expose raw internal memory, model traces, runner logs, or tools through A2A.\n- Do not make internal Agent Wire conform exactly to A2A if doing so weakens RedKey's proof, attribution, or marketplace model.\n- Do not build the A2A gateway in this spec. This document defines the internal protocol hardening that makes that gateway straightforward later.\n\n---"
    },
    {
      "title": "What We Adopt From A2A",
      "level": 2,
      "body": "| A2A concept | Agent Wire v1.1 use |\n|---|---|\n| `Task` | RedKey `agent_tasks` row plus HCS task stream |\n| `Message` | Typed coordination message or human/agent input |\n| `Part` | Structured payload part inside a message or artifact reference |\n| `Artifact` | Durable output object with lineage, hash, and version |\n| `contextId` | RedKey `context_id`, grouping related tasks/messages |\n| `referenceTaskIds` | RedKey `reference_task_ids`, linking continuation or dependency tasks |\n| Task status events | RedKey lifecycle events with normalized state category |\n| Artifact update events | RedKey `artifact.*` events |\n| Agent Card | RedKey Agent Card discipline for identity, skills, modes, constraints, and auth |\n| Extensions | Namespaced RedKey metadata instead of ad hoc payload growth |\n\n---"
    },
    {
      "title": "Agent Wire v1.1 Envelope",
      "level": 2,
      "body": "Every meaningful internal coordination event should use the v1.1 envelope.\n\n```json\n{\n  \"wire\": \"1.1\",\n  \"wire_id\": \"wire_01HZY...\",\n  \"type\": \"task.started\",\n  \"sender\": \"agent:quinn-03\",\n  \"ts\": \"2026-05-06T16:00:00Z\",\n  \"stream\": {\n    \"stream_id\": \"task:0.0.8830671:attempt:1\",\n    \"stream_seq\": 12,\n    \"context_id\": \"project:knowledgevault-m01r\",\n    \"correlation_id\": \"project:knowledgevault-m01r\",\n    \"causation_id\": \"wire_01HZX...\",\n    \"reference_task_ids\": [\"0.0.8830669\"],\n    \"parent_task_id\": \"0.0.8830668\"\n  },\n  \"state\": {\n    \"category\": \"working\",\n    \"terminal\": false\n  },\n  \"payload\": {},\n  \"extensions\": {}\n}\n```\n\n| Field | Required | Purpose |\n|---|---:|---|\n| `wire` | yes | Protocol version. Current target: `1.1`. |\n| `wire_id` | yes | Globally unique event ID. |\n| `type` | yes | RedKey event name, e.g. `task.started`, `artifact.ready`. |\n| `sender` | yes | `agent:<slug>`, `runner:<id>`, `system`, or `human:<id>`. |\n| `ts` | yes | Producer timestamp. HCS consensus timestamp remains canonical after submission. |\n| `stream` | yes | Stream identity, ordering, context, and causality. |\n| `state` | yes for task events | Normalized lifecycle category. |\n| `payload` | yes | Type-specific structured data. |\n| `extensions` | no | Namespaced RedKey or future A2A-compatible metadata. |"
    },
    {
      "title": "HCS Metadata",
      "level": 3,
      "body": "The listener must persist HCS metadata separately from the signed/logged Wire body:\n\n```json\n{\n  \"hcs\": {\n    \"topic_id\": \"0.0.8830671\",\n    \"sequence_number\": 42,\n    \"consensus_timestamp\": \"2026-05-06T16:00:01.123456789Z\",\n    \"running_hash\": \"...\"\n  }\n}\n```\n\nHCS metadata is the proof layer. The Wire body is the coordination event."
    },
    {
      "title": "HCS Content Boundary",
      "level": 3,
      "body": "HCS should carry coordination facts, commitments, references, and proof metadata. It should not carry working content.\n\nGood HCS content:\n\n- task lifecycle events: `task.created`, `task.available`, `task.claimed`, `task.started`, `task.blocked`, `task.complete`\n- inbox and routing events that decide what work exists and who may act on it\n- artifact reference events: `artifact.ready` with URI, version, hash, and readiness metadata\n- review/gate events that affect scheduling or release\n- compact health/capacity events that affect orchestration\n\nBad HCS content:\n\n- raw model output, drafts, scratch notes, transcripts, verbose logs, or token streams\n- large artifacts or document bodies\n- private memory contents\n- secrets, credentials, API responses with sensitive content, or hidden prompts\n\nThe value of streaming through HCS is not content storage. The value is deterministic ordering, claim arbitration, auditability, replay, recovery, and cross-agent coordination. Supabase mirrors this stream for fast reads and product UI, but HCS remains the canonical event source.\n\n---"
    },
    {
      "title": "Stream Model",
      "level": 2,
      "body": "Agent Wire v1.1 treats streams as ordered chains of Wires.\n\n```text\nproject:<project_id>\nphase:<phase_id>\ntask:<task_id>:attempt:<n>\nagent:<agent_id>\nartifact:<artifact_id>\n```\n\nThe practical topology remains shared role/task topics with `stream_id` in each Wire. Dedicated topics can be used for high-value or long-running streams later."
    },
    {
      "title": "Stream Rules",
      "level": 3,
      "body": "- A stream is append-only.\n- `stream_seq` is monotonic within the logical stream.\n- HCS sequence number is canonical within the topic.\n- Supabase stores the reduced current state but is not the canonical event source.\n- A consumer can rebuild current state by replaying HCS events for the relevant stream.\n- Large data never goes into HCS; HCS carries references, hashes, and state transitions.\n\n---"
    },
    {
      "title": "Context And Lineage",
      "level": 2,
      "body": "A2A's `contextId` is valuable internally. RedKey should standardize it.\n\n| Field | Meaning |\n|---|---|\n| `context_id` | The broad work context: project, client, phase, or conversation. |\n| `correlation_id` | The operational grouping used for tracing and read-model grouping. Usually equal to `context_id`. |\n| `causation_id` | The Wire that directly caused this Wire. |\n| `reference_task_ids` | Prior tasks this task continues, refines, reviews, or depends on. |\n| `parent_task_id` | Direct parent when a task is spawned from another task. |"
    },
    {
      "title": "Rules",
      "level": 3,
      "body": "- New work in the same project should reuse the same `context_id`.\n- Retried work should keep `context_id` and use a new `stream_id` with incremented attempt.\n- Follow-up work should create a new task stream and list the prior task in `reference_task_ids`.\n- Parallel work should use separate task streams under the same `context_id`.\n- Terminal task streams are immutable. Corrections create a new stream referencing the old one.\n\n---"
    },
    {
      "title": "Message / Part / Artifact Model",
      "level": 2,
      "body": "Agent Wire should distinguish coordination messages from deliverable artifacts."
    },
    {
      "title": "Message",
      "level": 3,
      "body": "Messages carry input, requests, questions, feedback, or status. A message can contain multiple parts.\n\n```json\n{\n  \"message_id\": \"msg_01\",\n  \"role\": \"human | agent | system\",\n  \"parts\": [\n    {\n      \"kind\": \"text\",\n      \"text\": \"Please review the migration for auth regressions.\"\n    },\n    {\n      \"kind\": \"artifact_ref\",\n      \"artifact_id\": \"art_01\"\n    }\n  ],\n  \"metadata\": {\n    \"skill\": \"code-review\",\n    \"priority\": 2\n  }\n}\n```"
    }
  ],
  "html_path": "artifacts/2026-05-06-agent-wire-v1-1-a2a-hardening-afd10dee21.html",
  "json_path": "artifacts/2026-05-06-agent-wire-v1-1-a2a-hardening-afd10dee21.json"
}