@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 package provides the core contract layer: every message is a typed envelope so v2 modules can be built independently and still interoperate with full type safety.

In the Miadi stack, it belongs with the packages that steer agents at work. It defines the messages that pass between the parts of a multi-agent workflow (intake, planning, monitoring, memory, agent registration, resource access), so each part can be written separately and still agree with the others. It holds types only.

Why

Miadi-A2A v2 separates Workflow, Operator, Agent, and Resource layers (per HAWK §3.1). This architecture requires a shared contract surface that every component can compile against, moving away from untyped message patterns to a structured coordination plane.

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

Design Principles

• Pure Contracts. Types only, zero runtime dependencies.
• Implementation Agnostic. Framing the message shape without enforcing a specific transport logic in this package.
• Zero 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.
• Companion package: @miadi/episodic-memory-schema, the durable record a session produces.

License

MIT.