@miadi/a2a-contracts

TypeScript contract types for the 16 standardized interfaces of Miadi-A2A v2, modeled on the HAWK hierarchical agent workflow framework (Cheng et al. 2025, arXiv:2507.04067).

This is a functional stub at v0.1.0: types only, zero runtime dependencies. The actual transport remains A2A v1's Redis broker; this package gives every message a typed contract so v2 modules can be built independently and still interoperate.

Why

Miadi-A2A v1 is a working Redis-backed transport, but it carries untyped JSON. v2's structural ambition — separating Workflow, Operator, Agent, and Resource layers (per HAWK §3.1) — needs a contract surface that every layer can compile against.

See rispecs/a2a/06-hawk-inspired-next-gen.spec.md for the architectural direction this package implements.

The 16 interfaces

| Interface | From → To | Purpose | | --------- | ---------------------------------- | ---------------------------------------- | | I₁ | TaskParser → WorkflowEngine | Hand off parsed user intent | | I₂ | WorkflowOptimizer ⇌ WorkflowEngine | Real-time strategy adjustment | | I₃ | WorkflowEngine → WorkflowPlanner | Delegate decomposition | | I₄ | WorkflowEngine → WorkflowMonitor | Stream execution telemetry | | I₅ | WorkflowEngine → Environment | Load / snapshot / diff world state | | I₆ | WorkflowEngine → Memory | Read / write / append session memory | | I₇ | WorkflowEngine → TaskManagement | Dispatch / cancel / status | | I₈ | WorkflowEngine → TaskOptimizer | Select among candidate executions | | I₉ | WorkflowEngine → Reasoning | LLM/CoT inference | | I₁₀ | WorkflowEngine → Security | Authorize subject ⨯ resource ⨯ action | | I₁₁ | TaskMgmt → Agent Specification | Declare an agent | | I₁₂ | TaskMgmt → Agent Publication | Publish agent endpoint | | I₁₃ | TaskMgmt → Agent Registration | Register capabilities in a registry | | I₁₄ | TaskMgmt → Agent Discovery | Find agents by capability | | I₁₅ | Operator → Resource | Structured resource access with audit | | I₁₆ | Agent → Resource | Direct resource invocation by agent |

Install

pnpm add @miadi/a2a-contracts

Usage

import {
  makeRequest,
  type RequestOf,
} from "@miadi/a2a-contracts"

// Build a typed I1 message — TypeScript enforces the payload shape.
const msg = makeRequest("I1", {
  taskId: "task-001",
  rawBrief: "Tell a story about Inwe-village…",
  intent: "literary fable",
  constraints: { setting: "forest village", season: "early autumn" },
  unknowns: ["target length", "audience age"],
  metaInstructions: [],
}, {
  messageId: "01HXXX…",
  traceId:   "trace-001",
  createdAt: "2026-05-28T10:00:00Z",
  from:      "task.parser",
  to:        "workflow.engine",
  sourceLayer: "user",
  targetLayer: "workflow",
})

// The envelope carries `interfaceId: "I1"`, so the consumer can narrow.

Type-level helpers:

type I9Req = RequestOf<"I9">  // = I9_ReasoningRequest

What this package does NOT do

• No runtime validation. Validators (Zod / Valibot) will land in a separate package or in a future minor version. For v0.1.0 the goal is structural type correctness at compile time.
• No transport. Transport stays in A2A v1 (lib/a2a-message-broker.ts) and any future replacement.
• No business logic. Every interface is a pure data contract.

Lineage

• Cheng, Y. et al. (2025). "HAWK: A Hierarchical Agent Workflow Framework for Multi-Agent Collaboration." arXiv:2507.04067. Registered in foundations/source-ledger.yaml as mas.cheng-2025-hawk.
• Companion package: @miadi/episodic-memory-schema (the durable per-session output).
• Spec: rispecs/a2a/06-hawk-inspired-next-gen.spec.md.

License

MIT.