pi-a2a-adaptor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ww2521
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# pi-a2a-adaptor
+
+> A2A protocol client for [pi coding agent](https://pi.dev) — fully compatible with [fasta2a](https://github.com/datalayer/fasta2a) and the [A2A Protocol](https://a2a-protocol.org).
+
+## Overview
+
+**pi-a2a-adaptor** enables [pi coding agent](https://pi.dev) to discover, communicate with, and orchestrate other A2A-compliant agents. It provides a full A2A client implementation that strictly follows the A2A protocol wire format (tested against fasta2a v0.6.1).
+
+Inspired by [pi-a2a-communication](https://github.com/DrOlu/pi-a2a-communication), this project is a ground-up rewrite that strictly implements the latest A2A protocol specification, making it fully compatible with [fasta2a](https://github.com/datalayer/fasta2a) and other A2A-compliant servers.
+
+## Features
+
+- **Agent Discovery** — Auto-discover remote agents via `/.well-known/agent-card.json`
+- **Task Management** — Send tasks, poll status, cancel, and list remote tasks
+- **Streaming** — SSE-based real-time task progress via `message/stream`
+- **Task Orchestration** — Chain and parallel task execution with artifact passing
+- **Long-running Tasks** — Configurable polling with timeout for tasks that take minutes
+- **Push Notifications** — Register callback URLs for async task completion
+- **11 Commands** — Full CLI interface via `/a2a-*` commands
+- **2 Tools** — LLM-callable tools for single and parallel agent calls
+
+## Quick Start
+
+### Install as pi Extension
+
+```bash
+# Clone into pi's global extensions directory
+git clone https://github.com/ww2521/pi-a2a-adaptor.git ~/.pi/agent/extensions/pi-a2a-adaptor
+```
+
+> **No build step required.** pi uses [jiti](https://github.com/unjs/jiti) to load TypeScript directly.
+
+### Reload pi
+
+```
+/reload
+```
+
+### Discover an Agent
+
+```
+/a2a-discover https://your-agent.example.com
+```
+
+### Send a Task
+
+```
+/a2a-send https://your-agent.example.com "Analyze this code for bugs"
+```
+
+### Broadcast to Multiple Agents
+
+```
+/a2a-broadcast "Review this code for security issues" --agents https://agent1.com,https://agent2.com
+```
+
+### Chain Tasks (Pipeline)
+
+```
+/a2a-chain scout "Find bugs in main.py" | worker "Fix {previous}"
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/a2a-discover <url>` | Discover an A2A agent at a URL |
+| `/a2a-agents` | List all discovered agents |
+| `/a2a-send <agent> <message>` | Send a task to an agent (auto-polls for completion) |
+| `/a2a-broadcast <msg> --agents <urls>` | Broadcast to multiple agents in parallel |
+| `/a2a-chain <agent1> <task1> \| <agent2> <task2>` | Chain tasks sequentially (`{previous}` placeholder) |
+| `/a2a-status <task-id> <agent-url>` | Get task status |
+| `/a2a-cancel <task-id> <agent-url>` | Cancel a task |
+| `/a2a-list <agent-url> [context-id]` | List tasks on a remote agent |
+| `/a2a-resubscribe <task-id> <agent-url>` | Resubscribe to a task's event stream |
+| `/a2a-config <key> <value>` | Configure timeout, retries, cache TTL, etc. |
+| `/a2a-help` | Show help |
+
+## LLM Tools
+
+- **`a2a_call`** — Call a single A2A agent with a task message
+- **`a2a_parallel`** — Call multiple A2A agents in parallel with the same message
+
+## Protocol Compliance
+
+This client implements the A2A protocol wire format as used by [fasta2a v0.6.1](https://github.com/datalayer/fasta2a):
+
+| Feature | Implementation |
+|---|---|
+| JSON-RPC methods | `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/list`, `tasks/resubscribe`, `tasks/pushNotification/*` |
+| Dispatch endpoint | `POST /` (unified JSON-RPC) |
+| Agent Card | `GET /.well-known/agent-card.json` |
+| Part types | discriminated union via `kind` (`"text"`, `"file"`, `"data"`) |
+| SSE events | JSON-RPC envelope with `result.kind` (`"task"`, `"status-update"`, `"artifact-update"`) |
+| Task states | `submitted`, `working`, `inputRequired`, `completed`, `failed`, `canceled`, `rejected` |
+
+## Project Structure
+
+```
+pi-a2a-adaptor/
+├── src/
+│   ├── client.ts          # A2AClient core (HTTP, SSE, polling)
+│   ├── registry.ts        # AgentRegistry with TTL caching
+│   ├── task-manager.ts    # TaskManager (chain / parallel)
+│   ├── types.ts           # Full A2A type definitions
+│   └── errors.ts          # Semantic error types
+├── pi-extension/
+│   └── index.ts           # pi extension entry (commands + tools)
+└── tests/
+    └── a2a-client.test.ts # 60 integration tests
+```
+
+## Testing
+
+```bash
+npm install
+npx vitest run
+```
+
+The test suite runs 60 integration tests against a mock A2A server that implements the fasta2a wire format, covering:
+
+- Agent Card discovery
+- `message/send` (sync and async with polling)
+- `message/stream` (SSE event parsing)
+- `tasks/get`, `tasks/cancel`, `tasks/list`
+- `tasks/resubscribe`
+- Push notification lifecycle (set / get / list / delete)
+- Part types (text, file-bytes, file-uri, data)
+- Long-running task polling with timeout
+- Error code handling
+
+## Configuration
+
+Edit `~/.pi/agent/settings.json` or use `/a2a-config` at runtime:
+
+```
+/a2a-config timeout 60000
+/a2a-config retryAttempts 3
+/a2a-config cacheTtl 300000
+/a2a-config verifySsl true
+```
+
+## Development
+
+```bash
+# Type check
+npx tsc --noEmit
+
+# Run tests
+npx vitest run
+
+# Run tests in watch mode
+npx vitest
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-a2a-adaptor",
+  "version": "1.0.0",
+  "description": "A2A protocol extension for Pi — discover, call, chain, and broadcast tasks to remote AI agents",
+  "type": "module",
+  "main": "src/index.js",
+  "keywords": [
+    "pi-package",
+    "a2a",
+    "agent2agent",
+    "agent-protocol",
+    "pi-extension"
+  ],
+  "files": [
+    "src",
+    "pi-extension",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./pi-extension/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}