@ssheleg/agent-stack 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,94 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.1] - 2026-08-14
+
+A red `validate` could not stop a publish anywhere in this family, and one member
+proved it: on 2026-08-12 `sheleg-dev` tagged v0.4.1 while its own validate run for that
+exact tag **failed**, and npm served 0.4.1 four minutes later.
+
+### Fixed
+
+- **The release now runs the whole validate suite before anything is published.**
+  `validate.yml` gained a `workflow_call` trigger and `release.yml` calls it with
+  `needs: validate` — the release runs *after* the real suite rather than beside a copy
+  of it. **Not one plant is duplicated:** each still has exactly one home.
+- **A guard keeps the connection there.** It fails when the trigger, the call, or the
+  `needs` goes missing — calling the suite without depending on it lets the jobs run in
+  parallel, which looks gated and is not. Watched failing against the planted removal.
+
+Proven end to end on `sheleg-dev` v0.4.3 before it reached here: the release run shows
+`validate / validate` completing first, then `release`, then `publish`.
+
+## [0.7.0] — 2026-08-14
+
+### Added
+
+- **`agent-interop`, a third skill — the protocol layer between processes.** The pack
+  could build an agent (`agent-orchestrator`) and prove it behaved (`agent-evals`), and
+  said nothing about how either talks to anything outside its own process. Six references:
+  MCP's wire surface, running many servers at once, shipping a server so a client can
+  actually reach it, the registry, A2A, and the gateway layer. It is its own skill rather
+  than a reference under `agent-orchestrator` because both existing descriptions sit at
+  ~91% of the 1024-character budget — measured, not estimated — and "write me an MCP
+  server" matches neither of their triggers.
+
+- **`references/mcp.md`** — MCP pinned at revision `2026-07-28`, written around the part
+  that breaks code written from memory: the protocol is now **stateless**, the `initialize`
+  handshake is gone in favour of `server/discover`, and version plus capabilities ride in
+  `_meta` on every request. The full deprecation register with migration paths —
+  **sampling, roots, logging and dynamic client registration are all on the way out**,
+  which is precisely the set an older model reaches for first. Plus notifications as opt-in
+  `subscriptions/listen` streams, `ttlMs` / `cacheScope` caching, and the fact that a
+  failed tool arrives as `isError: true` inside a 200.
+
+- **`references/mcp-scale.md`** — the two distinct costs of many servers and the pattern
+  for each: progressive discovery for *when* definitions enter context (with the published
+  1–5% threshold), programmatic tool calling for *how* tools are invoked. Includes the
+  interaction that turns a clever discovery scheme into a regression — most providers cache
+  the prompt prefix **including the `tools` array**, so mutating it mid-conversation can
+  cost more than the definitions it removed.
+
+- **`references/mcp-ship.md`** — mounting a server inside an existing app, transport-level
+  auth, client config in both forms, and the 404 that is really FastMCP's double path.
+  Relocated from `make-skill`, where it had been describing a protocol rather than a skill.
+
+- **`references/a2a.md`** — A2A 1.0 under the Linux Foundation: agent cards and the
+  `/.well-known/agent-card.json` path, the full `TASK_STATE_*` enum with terminal states
+  marked, three protocol bindings with their REST method mapping, and the v0.x→1.0 rename
+  spelled out so inherited code is recognisable on sight.
+
+- **`references/registry.md`** — `server.json`, reverse-DNS namespaces and the Ed25519
+  DNS/HTTP challenge that proves one, the publish flow with its three named failure modes,
+  and the registry's three refusals: no private servers, not for direct host consumption,
+  not designed for self-hosting.
+
+- **`references/gateway.md`** — what a gateway must do that an API gateway does not, stated
+  vendor-neutrally, with agentgateway as the named reference implementation. Includes the
+  federation trap that bites later: `prefixMode: conditional` renames every tool the day a
+  second target is added.
+
+### Changed
+
+- **The validator now enforces a revision stamp on protocol references** (`PROTOCOL_PINNED`
+  in `test/validate.py`). Prose about somebody else's specification ages silently — a
+  reader cannot tell last year's handshake from this year's, and a model writing code from
+  it is confidently wrong with no signal anywhere on the page. Every file under
+  `agent-interop/references/` must open with `**Spec pinned:** … · read YYYY-MM-DD`, and
+  the date must be a real one. Two negative self-tests, both anchored on the stamp's shape
+  and both asserting they planted something.
+
+- **`test/validate.py` no longer reads `other-skill/references/x.md` as a link of its own.**
+  A bare `references/x.md` means this skill's file; a path-qualified one is prose about a
+  sibling. Without the lookbehind, stating a boundary against another skill — which
+  `agent-interop` must do — failed the build over a file it never claimed. The existing
+  dangling-link plant proves the narrowed pattern still catches the real case, and a second
+  plant proves it inside the new skill.
+
+- **The installer functional test asserts every shipped skill installs**, by enumerating the
+  skills directory rather than naming files. `bin/agent-stack.js` already enumerated;
+  nothing proved it kept doing so.
+
 ## v0.6.1 — 2026-08-13
 
 Two CI fixes that had been sitting on `main` unreleased ship here, and the half of

package/README.md

@@ -9,8 +9,9 @@ Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
 
 ## What is in here
 
-Two skills — `agent-orchestrator` for building one, `agent-evals` for proving it
-behaves — and five references the first loads on demand.
+Three skills — `agent-orchestrator` for building one, `agent-evals` for proving it
+behaves, `agent-interop` for everything it talks to outside its own process — and
+eleven references they load on demand.
 
 **The orchestrator** (`SKILL.md`) — what the agent reads first:
 
@@ -39,6 +40,22 @@ code checks before model judges, judges calibrated against human labels before
 they are trusted, and a corpus grown from production failures rather than
 authored up front — where every fixed failure stays a fixture permanently.
 
+**The interop skill** (`agent-interop/SKILL.md`) — the protocols an agent speaks
+outside its own process, and the one rule that governs all of them: a protocol claim
+without a date is a guess. Every one of these specifications moved in the last twelve
+months in a way that silently breaks older code — MCP replaced the `initialize`
+handshake with `server/discover` and went **stateless**, deprecated **sampling, roots
+and logging**; A2A renamed its wire surface between v0.x and 1.0; agentgateway
+deprecated `binds` while its own overview page still teaches it. So every reference
+carries a `**Spec pinned:** … · read <date>` line, and the validator fails the build
+without one. Six references: `mcp.md` (the wire and the full deprecation register),
+`mcp-scale.md` (progressive discovery, code mode, and the prompt-cache interaction that
+undoes both), `mcp-ship.md` (mounting, and the 404 that is really a double path),
+`registry.md` (`server.json`, namespace proof, the registry's three refusals),
+`a2a.md` (cards, task states, three bindings), `gateway.md` (what a gateway must do that
+an API gateway does not). Plus a link map, and a verdict on each neighbouring standard —
+ACP, AGNTCY, AP2, Agent Skills — so an agent stops guessing.
+
 **`references/context-engineering.md`** — what the loop gives up when the window
 runs out: the five-rung compaction ladder and why to re-measure between rungs,
 the tool-pair boundary invariant, typed carryover blocks copied across the
@@ -122,8 +139,16 @@ audit row has to carry to prove a control was on.
 trajectory rather than a final answer, turning a production failure into a
 permanent fixture, calibrating a judge, gating a release on offline evals.
 
-Neither triggers for a single LLM call in a script or for prompt wording — that
-is not an orchestrator, and pulling this much doctrine for it is how a skill
+`agent-interop`: building or consuming an MCP server, exposing or calling another
+agent over A2A, publishing to the MCP Registry, or putting a gateway in front of
+agent traffic. Not for designing one server's tool set — that is a design problem,
+and Anthropic's `mcp-server-dev` plugin is built for it — and not for a skill's own
+construction, which is `make-skill`. That boundary runs both ways: `make-skill` keeps
+what changes *because you are writing a skill*, and the protocol itself is described
+here and nowhere else in the family.
+
+None of the three triggers for a single LLM call in a script or for prompt wording —
+that is not an orchestrator, and pulling this much doctrine for it is how a skill
 teaches you to route around it.
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.6.1",
-  "description": "Production patterns for AI agent orchestrators — tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access. This package is the installer CLI.",
+  "version": "0.7.1",
+  "description": "Production patterns for AI agent orchestrators \u2014 tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay \u2014 plus the wallet side of reselling LLM access. This package is the installer CLI.",
   "bin": {
     "agent-stack": "bin/agent-stack.js"
   },

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Two skills: agent-orchestrator \u2014 tool-calling loops, multi-stage pipelines with checkpoints, provider routing with fallback, four-layer memory, context engineering, plus the wallet side of reselling LLM access; and agent-evals \u2014 run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-interop/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: agent-interop
+description: >-
+  Use when an agent must talk to something outside its own process — building or consuming an
+  MCP server, exposing or calling another agent over A2A, publishing to the MCP Registry, or
+  putting a gateway in front of agent traffic. Carries the MCP 2026-07-28 wire surface and what
+  it deprecated (server/discover, stateless per-request _meta, elicitation in form and URL mode,
+  subscriptions/listen; sampling, roots, logging and dynamic client registration on the way out),
+  A2A 1.0 agent cards, task states and three bindings, registry namespaces and server.json, tool
+  federation, and what a gateway must do that an API gateway does not. Triggers - "MCP server",
+  "MCP client", "A2A", "agent card", "agent interoperability", "MCP registry", "server.json",
+  "agentgateway", "tool federation", "MCP-сервер", "карточка агента", "интероперабельность
+  агентов", "реестр MCP", "шлюз для агентов". Not for designing one server's tool set, and not
+  for a skill's own construction — that is make-skill.
+---
+
+# Agent interop — the protocols an agent speaks outside its own process
+
+`agent-orchestrator` builds the loop. `agent-evals` proves it behaves. This skill covers
+everything the loop reaches that is **not in its process**: a tool server, a peer agent, a
+registry, and the gateway between them.
+
+---
+
+## Rule zero — a protocol claim without a date is a guess
+
+Every one of these specifications moved in the last twelve months, and each moved in a way
+that silently breaks code written against the previous revision. Concretely, and each one
+measured against the live specification rather than recalled:
+
+- MCP replaced the `initialize` handshake with `server/discover` and made the protocol
+  **stateless**; a client that opens with `initialize` is speaking a revision that is on its
+  way out.
+- MCP **deprecated `sampling`, `roots` and `logging`** — three things an older model will
+  reach for first, because for a year they were the interesting part of the client side.
+- A2A renamed its wire surface between v0.x and v1.0, and SDKs and blog posts still document
+  v0.3.
+- agentgateway **deprecated `binds`** in favour of `gateways` — while its own overview page
+  still introduces `binds` as a core concept.
+
+So: **every reference in this skill opens with a `**Spec pinned:**` line**, and
+`test/validate.py` fails the build without one. That is a mechanical check, not an
+aspiration — the class of error it prevents is the one where prose reads as current
+because nothing on the page says otherwise.
+
+**Before you write wire-level code, fetch the spec.** These references tell you what to look
+for and what changed; they are not a substitute for the document. Read the pinned revision,
+then check whether a newer one exists. Every entry in the link map below is fetchable.
+
+---
+
+## Which protocol answers which question
+
+| The question you actually have | The answer | Where |
+|---|---|---|
+| I want to give a model a capability against a live system | **MCP server** | `references/mcp.md` |
+| My server is written and the client cannot connect to it | mounting and transports | `references/mcp-ship.md` |
+| I want my application to consume other people's tool servers | **MCP client** | `references/mcp.md`, then `references/mcp-scale.md` |
+| I have more servers than fit in a context window | client scaling patterns | `references/mcp-scale.md` |
+| I want another team's *autonomous agent* to accomplish an outcome for me | **A2A** | `references/a2a.md` |
+| I want my agent discoverable and callable by other agents | **A2A agent card** | `references/a2a.md` |
+| I want people to find and install my MCP server | **MCP Registry** | `references/registry.md` |
+| I have many servers, many clients, and a security team | **a gateway** | `references/gateway.md` |
+
+**The one-line rule between the two big ones.** MCP connects a model to a *capability* you
+control the shape of; A2A connects you to a *peer* whose insides you deliberately cannot
+see. The official framing is exact and worth keeping: *"A2A is about agents partnering on
+tasks, while MCP is more about agents using capabilities."* Real systems run both — an A2A
+server whose internals speak MCP — and that is the recommended architecture, not a
+compromise.
+
+**The tell that you picked wrong:** if you find yourself inventing a task lifecycle, a
+progress channel and a resumable handle on top of `tools/call`, you wanted A2A. If you find
+yourself publishing an agent card for something that is one HTTP call with a JSON schema,
+you wanted MCP.
+
+---
+
+## References
+
+Each file opens with its own **Load this when** line and its revision stamp. This table is
+an index; the trigger lives in the file, so the two cannot drift apart.
+
+| File | Read it when |
+|---|---|
+| [`references/mcp.md`](references/mcp.md) | you are **building or calling an MCP server** — the layers, per-request `_meta`, `server/discover`, the three server primitives and the one surviving client primitive, notifications, caching, transports, and the full deprecation register |
+| [`references/mcp-ship.md`](references/mcp-ship.md) | the server is written and **cannot be reached** — mounting inside an existing web app, transport-level auth, client config, and the 404 that is really a double path |
+| [`references/mcp-scale.md`](references/mcp-scale.md) | the host has **more servers and tools than context** — progressive discovery, programmatic tool calling, cache interaction, and the security surface each one opens |
+| [`references/a2a.md`](references/a2a.md) | the other side is **another agent, not a tool** — agent cards and discovery, the task lifecycle and its terminal states, three protocol bindings, streaming versus push |
+| [`references/registry.md`](references/registry.md) | you are **publishing a server** or building something that consumes the registry — `server.json`, reverse-DNS namespaces and how ownership is proved, the publish flow, and the registry's three refusals |
+| [`references/gateway.md`](references/gateway.md) | agent traffic needs **one controlled seam** — what a gateway must do that an API gateway does not, federation and name collisions, and where authorization actually belongs |
+
+---
+
+## Boundaries — what this skill is not
+
+**Against `make-skill`.** `make-skill` owns the *skill author's* view: whether a job wants a
+skill or a server at all, declaring a server dependency in `compatibility`, and the fact that
+tool names differ per host (`mcp__<server>__<tool>` in Claude Code, `mcp__plugin_<plugin>_<server>__<tool>`
+for a plugin's own server). **This skill owns the wire.** If the question is "what does the
+protocol say", it is here; if it is "how does my skill declare that it needs one", it is
+there. The protocol is described in exactly one of the two places, and this is it.
+
+**Against `agent-orchestrator`.** That skill routes between *model providers* and manages the
+loop's own context. This one routes between *processes*. They meet at exactly one point: an
+orchestrator that federates many MCP servers is subject to `references/mcp-scale.md`, and one
+that fronts them with a proxy is subject to `references/gateway.md`.
+
+**Against `agent-orchestrator/references/governance.md`.** That file decides *whether* a
+boundary may be crossed and what an audit row must carry to prove a control was applied. This
+skill describes *how* the crossing is spoken. Permission there, protocol here.
+
+**Not covered at all:** designing the tool set of one server (what tools, what schemas, what
+descriptions — that is a design problem, and Anthropic's `mcp-server-dev` plugin is built for
+it); prompt wording; a single LLM call in a script.
+
+---
+
+## The neighbourhood — one verdict each
+
+Named so an agent stops guessing, with the verdict stated rather than implied.
+
+| Thing | What it actually is | Verdict |
+|---|---|---|
+| **Agent Skills** (`agentskills.io`) | the open `SKILL.md` format this very file is written in — originally Anthropic's, now an open standard with wide client adoption | **Adopt, but not here.** The family owns it in `make-skill`. Relevant to interop in one way: MCP has a *Skills over MCP* extension, so a server can ship skills — see `references/mcp.md` |
+| **ACP** (IBM's Agent Communication Protocol) | a former A2A competitor | **Dead as a choice.** Merged into A2A under LF AI & Data on 2025-08-29; its team stopped developing it. If you meet ACP in a doc, the answer today is A2A |
+| **AGNTCY** (Cisco/Outshift → Linux Foundation, July 2025) | *not* an A2A rival — an infrastructure stack around multi-agent systems: OASF discovery, agent identity, SLIM messaging, observability. It archived its own competing protocol | **Orthogonal.** Evaluate it for identity and observability if you run many agents; it does not replace A2A or MCP |
+| **AP2** (Agent Payments Protocol) | Google's payments extension **for A2A**, standardising through FIDO Alliance working groups. Signs intent as Verifiable Digital Credentials — Checkout Mandates and Payment Mandates, each with an Open and a Closed stage | **Watch, do not build on it yet.** Explicitly in progress rather than production-ready. It is the right shape for the problem — proving *this user authorized this purchase* — so track it if an agent will ever spend money |
+| **"ChatGPT apps" / OpenAI's plugin surface** | checked, and it is **not a separate protocol**: an MCP server, plus Agent Skills for the workflows, plus optional UI | **Nothing new to learn.** Build the MCP server; the host packaging is the host's |
+| **MCP extensions** — Tasks, MCP Apps, Skills over MCP | opt-in additions to the core protocol, negotiated per connection | **Read before inventing.** Long-running work has a durable-handle answer already; see `references/mcp.md` |
+
+---
+
+## The link map — where to go and read
+
+Nothing here is summarised well enough to build against. These are the documents.
+
+| Read | For | URL |
+|---|---|---|
+| MCP specification (current) | the normative requirements; always check the revision it serves | `https://modelcontextprotocol.io/specification/latest` |
+| MCP architecture | the two layers, statelessness, the discovery exchange with real JSON | `https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture` |
+| MCP server concepts | tools, resources, resource templates, prompts — who controls each | `https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts` |
+| MCP client concepts | elicitation's two modes and the MRTR pattern; the deprecated client features | `https://modelcontextprotocol.io/docs/2026-07-28/learn/client-concepts` |
+| **MCP deprecation register** | the authoritative list of what is on the way out and its earliest removal | `https://modelcontextprotocol.io/specification/2026-07-28/deprecated` |
+| MCP client best practices | progressive discovery and code mode, with the numbers | `https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices` |
+| Build a server / build a client | the SDK-level walkthroughs | `https://modelcontextprotocol.io/docs/2026-07-28/develop/build-server`, `…/build-client` |
+| MCP + Agent Skills | how skills and servers compose, and the `mcp-server-dev` plugin | `https://modelcontextprotocol.io/docs/2026-07-28/develop/build-with-agent-skills` |
+| MCP registry — about, quickstart | what it is, and the exact publish flow | `https://modelcontextprotocol.io/registry/about`, `https://modelcontextprotocol.io/registry/quickstart` |
+| MCP docs index for machines | fetch this first if you are an agent exploring | `https://modelcontextprotocol.io/llms.txt` |
+| A2A home and specification | v1.0, the three bindings, the normative surface | `https://a2a-protocol.org/latest/`, `https://a2a-protocol.org/latest/specification/` |
+| A2A key concepts / life of a task / discovery | the object model, the lifecycle, the well-known URI | `https://a2a-protocol.org/latest/topics/key-concepts/`, `…/life-of-a-task/`, `…/agent-discovery/` |
+| A2A and MCP | the official statement of how they divide | `https://a2a-protocol.org/latest/topics/a2a-and-mcp/` |
+| agentgateway — standalone, Kubernetes | the config model, and the Gateway API story | `https://agentgateway.dev/docs/standalone/latest/`, `https://agentgateway.dev/docs/kubernetes/latest/` |
+| Source repositories | when the docs are behind the code | `https://github.com/a2aproject/A2A`, `https://github.com/modelcontextprotocol/modelcontextprotocol`, `https://github.com/modelcontextprotocol/registry`, `https://github.com/agentgateway/agentgateway` |
+
+**Fetch the `llms.txt` first when you are an agent.** Both `modelcontextprotocol.io` and
+`agentgateway.dev` publish one, and both are versioned per docs release — which is how you
+find the page that exists rather than the page you remember.
+
+---
+
+## Checklist — shipping anything that speaks these protocols
+
+- [ ] The revision you build against is **written down** — in `compatibility`, a constant, or a README line
+- [ ] You read the deprecation register before using a client feature
+- [ ] Version mismatch has a handled path, not a crash
+- [ ] Tool output is treated as **untrusted input**, including output from your own servers
+- [ ] Nothing secret is requested through an elicitation form — that is URL mode's job
+- [ ] Long-running work uses a durable handle rather than a held connection
+- [ ] If you federate: name collisions are resolved deliberately, not by load order
+- [ ] If you publish: the namespace is one you can prove you own
+- [ ] Authorization is enforced per hop, not only at the entrance

package/plugins/agent-stack/skills/agent-interop/references/a2a.md

@@ -0,0 +1,209 @@
+# A2A — when the other side is an agent, not a tool
+
+**Load this when:** you are delegating an outcome to somebody else's autonomous agent,
+publishing your own as callable, or choosing between A2A and MCP.
+
+**Spec pinned:** A2A **v1.0**, `https://a2a-protocol.org/latest/specification/` · read 2026-08-13
+
+Governance: created by Google, transferred to the **Linux Foundation**, Apache-2.0, run by a
+Technical Steering Committee with AWS, Cisco, Google, IBM Research, Microsoft, Salesforce,
+SAP and ServiceNow.
+
+**The v0.x → v1.0 rename is the trap here.** The wire surface changed names between them, and
+plenty of SDKs, tutorials and blog posts still document v0.3. A document that mixes the two
+is wrong against at least one of them. Check every field name against the version you target.
+
+## Contents
+
+- The five design principles, and what each one bought
+- The object model
+- Discovery — the agent card
+- The task lifecycle
+- Three protocol bindings
+- Getting results back
+- Security
+- Traps
+
+## The five design principles, and what each one bought
+
+Stated at announcement, and each is visible in the protocol:
+
+| Principle | What it produced |
+|---|---|
+| **Embrace agentic capabilities** | agents collaborate without shared memory, tools or context — the peer is opaque by design |
+| **Build on existing standards** | HTTP, SSE, JSON-RPC rather than a novel transport |
+| **Secure by default** | enterprise authentication and authorization, aligned with OpenAPI's auth schemes |
+| **Support for long-running tasks** | a task lifecycle that spans hours or days, with progress reported |
+| **Modality agnostic** | parts carry more than text — audio, video, binary, structured data |
+
+**The first one is the design decision that matters.** A2A's peer is deliberately a black
+box: you send an outcome, not a plan. If your design needs to see inside the other agent,
+A2A is the wrong protocol and you probably want an MCP server.
+
+## The object model
+
+| Object | What it is | Key fields |
+|---|---|---|
+| **AgentCard** | JSON metadata describing identity, capabilities, endpoint, skills and auth requirements | name, description, version, provider, capabilities, skills, security schemes |
+| **Task** | a **stateful unit of work** with a unique id and a lifecycle | `id`, `contextId`, `status`, `artifacts`, `history`, `metadata` |
+| **Message** | one turn of communication | `role` (`user` or `agent`), parts |
+| **Part** | the fundamental content container inside messages and artifacts | one of `text`, `raw` (bytes), `url`, `data` (JSON); plus optional `mediaType`, `filename`, `metadata` |
+| **Artifact** | a tangible output produced during a task | `artifactId`, human-readable name, one or more parts |
+
+**`contextId` is the piece people miss.** It is server-generated and groups multiple related
+tasks across interactions — the thing that makes a sequence of delegations one conversation
+rather than a pile of unrelated jobs.
+
+**`skills[]` on an agent card is not an Agent Skills `SKILL.md`.** A2A borrowed the word
+for *an advertised capability of a remote agent* — `id`, `name`, `description`, `tags`,
+`examples`, `inputModes`, `outputModes`. Agent Skills are instruction folders loaded into a
+model's context. Two unrelated things, one word. Keep them apart in anything you write, or
+every reader loses an hour.
+
+## Discovery — the agent card
+
+The standard location, following RFC 8615:
+
+```
+https://{agent-server-domain}/.well-known/agent-card.json
+```
+
+**Pre-0.3 deployments served `/.well-known/agent.json`** — expect both in the wild.
+
+Top-level card fields in 1.0 — confirm against the live schema before implementing:
+`name`, `description`, `version`, `provider`, `iconUrl`, `documentationUrl`,
+`supportedInterfaces`, `capabilities`, `securitySchemes`, `securityRequirements`,
+`defaultInputModes`, `defaultOutputModes`, `skills`, `extensions`, `signatures`.
+
+**`capabilities` gates what you may attempt** — `streaming`, `pushNotifications`,
+`extendedAgentCard`, `extensions`. Read it and branch; never assume streaming or push
+exists because the docs describe them.
+
+**Cards can be signed.** An unsigned card at a well-known URI is a claim, not proof —
+verify `signatures` whenever the peer is not first-party.
+
+A plain HTTP GET returns the card. Four discovery strategies exist, and they are not equal:
+
+1. **Well-known URI** — the standard, and what you should publish.
+2. **Authenticated extended cards** — fetched via `GetExtendedAgentCard`. This is the
+   recommended way to expose sensitive capability information: **selective disclosure by
+   client permission**, rather than a static public card carrying secrets.
+3. **Curated registries** — catalogues queryable by skill, tag or provider. Note the honest
+   gap: **the current specification does not prescribe a standard API for them**, so anything
+   you build against one is vendor-specific.
+4. **Direct configuration** — hardcoded URLs. Fine for a fixed pair of agents, and it does
+   not scale or standardize.
+
+**Never put a secret in the public card.** That is what the extended card exists for.
+
+## The task lifecycle
+
+The enum, spelled exactly as the specification defines it:
+
+```
+TASK_STATE_UNSPECIFIED
+TASK_STATE_SUBMITTED
+TASK_STATE_WORKING
+TASK_STATE_INPUT_REQUIRED     <- interrupted, awaiting the client
+TASK_STATE_AUTH_REQUIRED      <- interrupted, awaiting credentials
+TASK_STATE_COMPLETED          <- terminal
+TASK_STATE_CANCELED           <- terminal
+TASK_STATE_REJECTED           <- terminal
+TASK_STATE_FAILED             <- terminal
+```
+
+**Terminal means terminal: a task that reached completed, canceled, rejected or failed cannot
+restart.** Continuing work means a *new* task, linked by `contextId`. Client code that
+retries by re-sending to the same `taskId` after a failure is coding against a state machine
+that does not exist.
+
+**Interrupted is not failed.** `INPUT_REQUIRED` and `AUTH_REQUIRED` are the protocol asking
+you for something and holding the work open. A client that treats every non-`COMPLETED`
+status as an error abandons tasks that were waiting for one field.
+
+## Three protocol bindings
+
+The specification defines three, and an agent may implement any of them:
+
+| Binding | Section | Use when |
+|---|---|---|
+| **JSON-RPC** | §9 | the default; broadest tooling |
+| **gRPC** | §10 | you already run gRPC and want streaming and typed stubs |
+| **HTTP+JSON/REST** | §11 | plain REST clients, easiest to inspect and curl |
+
+**A server declares which bindings it supports on its card; the client picks one.**
+
+| Functionality | JSON-RPC / gRPC | REST |
+|---|---|---|
+| Send message | `SendMessage` | `POST /message:send` |
+| Send streaming message | `SendStreamingMessage` | `POST /message:stream` |
+| Get task | `GetTask` | `GET /tasks/{id}` |
+| List tasks | `ListTasks` | `GET /tasks` |
+| Cancel task | `CancelTask` | `POST /tasks/{id}:cancel` |
+| Subscribe to task | `SubscribeToTask` | `POST /tasks/{id}:subscribe` |
+| Create push config | `CreateTaskPushNotificationConfig` | `POST /tasks/{id}/pushNotificationConfigs` |
+| Get push config | `GetTaskPushNotificationConfig` | `GET /tasks/{id}/pushNotificationConfigs/{configId}` |
+| List push configs | `ListTaskPushNotificationConfigs` | `GET /tasks/{id}/pushNotificationConfigs` |
+| Delete push config | `DeleteTaskPushNotificationConfig` | `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` |
+| Extended card | `GetExtendedAgentCard` | `GET /extendedAgentCard` |
+
+**The v0.3.x names, so you recognize inherited code on sight:** slash-style JSON-RPC methods
+— `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`,
+`tasks/pushNotificationConfig/{set,get,list,delete}`,
+`agent/getAuthenticatedExtendedCard`. If you meet those, it is a **v0.x client**. Do not
+"fix" the names to 1.0 without moving the whole contract — half-migrated is worse than
+either version, and it works until it reaches the one field nobody updated.
+
+The same drift runs through the states: 1.0 uses proto-style constants
+(`TASK_STATE_COMPLETED`), v0.x used lowercase wire values (`submitted`, `working`,
+`input-required`). A document showing both has been half-migrated.
+
+## Getting results back
+
+Three mechanisms, matched to how long the work takes and whether you can hold a connection:
+
+| Mechanism | Shape | Right when |
+|---|---|---|
+| **Request/response with polling** | `SendMessage`, then `GetTask` on an interval | always available; work measured in seconds to minutes |
+| **Streaming (SSE)** | `SendStreamingMessage` / `SubscribeToTask`; needs `capabilities.streaming` | you want incremental output and can hold the connection |
+| **Push notifications** | server calls a webhook you registered; needs `capabilities.pushNotifications` | work spans hours or days, or the client is not always up |
+
+Stream events are typed: `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`.
+
+**Push is the one that makes long-running real.** Streaming dies with the connection;
+polling for six hours is a poor use of everyone's time. If your delegated work can outlive a
+request, register a push config and design for the callback.
+
+**Design for all three failing.** A long task whose stream drops must be recoverable **by
+id** — which is precisely why A2A gives tasks ids and states instead of making them
+fire-and-forget calls. Polling is the floor you fall back to.
+
+## Security
+
+- **Enterprise auth from the start** — the card declares its security schemes, aligned with
+  OpenAPI's authentication approaches: API key, HTTP auth, OAuth2, OpenID Connect, mutual
+  TLS. Read the card and satisfy what it declares; do not assume bearer tokens.
+- **Scope the token to the task.** Authorization is per skill and per task; handing a peer
+  a token broader than the work is how one delegation becomes an account compromise.
+- **Verify card signatures for any peer that is not first-party.** A well-known URI proves
+  where the file sits, not who wrote it.
+- **`AUTH_REQUIRED` is a protocol state**, not an error path bolted on. Handle it.
+- **The peer is opaque, and that cuts both ways.** You cannot verify how it reached its
+  result, so anything it returns is untrusted input to your system — the same rule as tool
+  output, with less recourse.
+- **Trace across hops.** A chain of agents compounds errors, and policy has to be enforced at
+  **each hop**, not only at the entrance. See `agent-orchestrator/references/governance.md`
+  for the control set; this file only says which wire it rides.
+
+## Traps
+
+- **Building against v0.3 field names** because that is what the tutorial showed. Check the
+  version.
+- **Retrying into a terminal task.** New task, same `contextId`.
+- **Treating `INPUT_REQUIRED` as a failure.** It is a question.
+- **Publishing capability detail in the public card** instead of the authenticated extended
+  card.
+- **Choosing A2A for something with a JSON schema and one call.** That is a tool. The cost of
+  A2A is a lifecycle, a card and a state machine; pay it when the other side is genuinely
+  autonomous.
+- **Assuming a registry API is standard.** It is not, yet.