feat(channels): implement A2A v1.0.0 channel adapter (channels/a2a/)

[raykao]

Summary

Build a new src/channels/a2a/ channel adapter implementing the A2A (Agent2Agent) Protocol v1.0.0, the unified open standard under the Linux Foundation (formed by the merger of IBM ACP and Google A2A, 2025).

This replaces the now-closed #214 (which targeted ACP v0.2.0, a defunct spec).

Spec: https://a2aproject.github.io/A2A/latest/specification/
Protocol binding: JSON-RPC 2.0 over HTTP + SSE (the standard JSON-RPC binding)

---

Problem

copilot-bridge currently has no standard-compliant external channel. The existing channels/acp/ (soon channels/copilot-bridge-ws-rpc/ per #231) is a custom internal WebSocket JSON-RPC protocol - well-suited for internal clients (kanban) but not interoperable with the broader A2A ecosystem.

An A2A channel would let any A2A-compliant client (other agents, external UIs, third-party tooling) interact with copilot-bridge agents without custom client code.

---

Proposed Solution

A new, clean implementation in src/channels/a2a/ that conforms to A2A v1.0.0. No shared code with channels/copilot-bridge-ws-rpc/.

Endpoints

Method	Endpoint	Purpose
GET	/.well-known/agent.json	Agent Card discovery
POST	/	JSON-RPC endpoint (all A2A operations)

All A2A operations are multiplexed over a single JSON-RPC endpoint. SSE streaming is handled via Content-Type: text/event-stream on the same HTTP POST.

A2A Operations to implement

Operation	JSON-RPC Method	Priority
Send message	message/send	P0
Send streaming message	message/stream	P0
Get task	tasks/get	P0
Cancel task	tasks/cancel	P1
Subscribe to task	tasks/resubscribe	P1
Set push notification config	tasks/pushNotificationConfig/set	P2
Get push notification config	tasks/pushNotificationConfig/get	P2
List tasks	tasks/list	P2

Agent Card (.well-known/agent.json)

Per A2A spec, served at /.well-known/agent.json per agent. Fields:

{
  "name": "...",
  "description": "...",
  "url": "https://host/agents/{name}",
  "version": "...",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [...]
}

Task Lifecycle

Maps SDK session events to A2A task states:

SDK event	A2A task state
Session created	submitted
session.in_progress	working
session.idle	completed
session.error	failed
Permission requested	input-required
Permission resolved	back to working

Streaming (SSE)

message/stream returns Content-Type: text/event-stream. Events emitted:

• TaskStatusUpdateEvent - task state transitions
• TaskArtifactUpdateEvent - streaming text chunks (as Part with mediaType: text/plain)
• Tool call tracking via Part.metadata (trajectory data: tool name, input, output)

Permission Approval (HITL)

When the SDK requests a permission:

1. Task transitions to input-required
2. await_request in the Task object carries the permission details
3. Client sends message/send with the approval/denial to resume
4. Task transitions back to working

Push Notifications

When tasks/pushNotificationConfig/set is called, bridge registers the webhook URL. On task state transitions, bridge POSTs StreamResponse to the webhook.

The client (kanban) can register a webhook and disconnect - bridge will POST when the task needs attention (input-required, completed, failed).

Multi-turn Sessions

Each A2A task has a contextId. Subsequent messages with the same contextId are routed to the same underlying copilot session. Maps directly to the bridge's existing session-per-channel model.

---

What This Enables for Kanban

• Kanban sends a prompt via message/stream, SSE stream stays open
• Agent streams thoughts/tool calls via TaskArtifactUpdateEvent with trajectory metadata
• When agent needs approval: task goes input-required, kanban renders approval UI
• Kanban resumes via message/send with approval
• On disconnect: kanban calls tasks/resubscribe to reattach to stream
• If kanban was offline: push notification fires, kanban calls tasks/get to hydrate
• Agent can also use a write_card_update skill to push richer semantic updates directly to the card

---

Implementation Notes

• Clean implementation - no shared code with channels/copilot-bridge-ws-rpc/
• channels/copilot-bridge-ws-rpc/ remains for internal clients; A2A channel is for external/ecosystem clients
• Auth: HTTP Authorization: Bearer <token> per agent, same pattern as WS channel
• One HTTP server per A2A platform config entry (like the WS channel)
• channels/copilot-bridge-ws-rpc/ is the eventual deprecation candidate once this covers all use cases

Spec References

• A2A v1.0.0 spec: https://a2aproject.github.io/A2A/latest/specification/
• Streaming & async: https://a2aproject.github.io/A2A/latest/topics/streaming-and-async/
• Agent card: https://a2aproject.github.io/A2A/latest/topics/key-concepts/
• Python SDK (reference impl): https://github.com/a2aproject/a2a-python
• JS SDK: https://github.com/a2aproject/a2a-js

Supersedes

Closes #214 (targeted ACP v0.2.0 - now defunct, merged into A2A)

Reported By

Agent (automated) - ACP/A2A conformance review + protocol research, 2026-05-22

[raykao]

Design spec doc is now written and merged:

docs/a2a-channel.md - https://github.com/raykao/copilot-bridge/blob/main/docs/a2a-channel.md

Covers:

• Full operation set (message/send, message/stream, tasks/get, tasks/cancel, tasks/resubscribe, tasks/list, push notification config CRUD)
• Task lifecycle and SDK event mapping
• HITL / permission approval via input-required state - spec-native, no extensions
• Push notification webhook flow (disconnected clients)
• Multi-turn sessions via contextId
• Reconnect flow via tasks/resubscribe (first event = current state, no gap)
• Multi-agent routing via /agents/{name} URL paths
• GET /agents list endpoint (only bridge addition beyond pure A2A)

Implementation of src/channels/a2a/ against this spec is the next step.

[ChrisRomp]

Good research on the ACP -> A2A merger. The task lifecycle mapping and contextId -> session model look like clean fits for the bridge architecture.

A few things to consider:

• The channels/acp/ code this builds on hasn't landed on main yet (feat: add HTTP channel adapter with ACP v0.2.0 support #216 was closed without merge). What's the path to getting the prerequisite channel code in? Does refactor(channels): rename channels/acp to copilot-bridge-ws-rpc - not ACP v0.2.0 compliant #231 need to land first, or can A2A be built independently?
• With Mattermost/Slack, ws-rpc, and A2A, that's three channel families to maintain. Is the intent to deprecate ws-rpc once A2A covers all use cases (push notifications, permission callbacks, subscriptions)? The issue mentions this but it would be good to have clear criteria for deprecation.
• P0/P1/P2 prioritization makes sense. I'd suggest shipping P0 first as a minimal PR, then P1/P2 as follow-ups -- large PRs are hard to review.