agentalk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IchenDEV
+
+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,445 @@
+<div align="center">
+
+# ⚡ agentalk
+
+**curl for AI agents — the universal A2A protocol CLI**
+
+Discover, message, stream, and manage tasks with any A2A-compatible agent — right from your terminal.
+
+[![npm version](https://img.shields.io/npm/v/agentalk?style=flat-square&color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/agentalk)
+[![license](https://img.shields.io/npm/l/agentalk?style=flat-square&color=blue)](https://github.com/IchenDEV/agentalk/blob/main/LICENSE)
+[![node version](https://img.shields.io/node/v/agentalk?style=flat-square&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0-8B5CF6?style=flat-square&logo=google&logoColor=white)](https://google.github.io/A2A/)
+[![zero config](https://img.shields.io/badge/zero_config-ready-10B981?style=flat-square)](#quick-start)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-FF6F61?style=flat-square)](https://github.com/IchenDEV/agentalk/pulls)
+
+<br />
+
+[🇨🇳 中文文档](./README.zh-CN.md) · [Report Bug](https://github.com/IchenDEV/agentalk/issues) · [Request Feature](https://github.com/IchenDEV/agentalk/issues)
+
+<br />
+
+```
+  ╭──────────────────────────────────────────────────╮
+  │                                                  │
+  │   $ agentalk agent https://my-agent.example.com      │
+  │                                                  │
+  │   🤖 Recipe Agent                                │
+  │      v1.0.0                                      │
+  │      Helps with recipes and cooking              │
+  │                                                  │
+  │   Skills:                                        │
+  │     • Recipe Search (recipe-search)              │
+  │       Search by ingredients or cuisine           │
+  │                                                  │
+  │   $ agentalk send https://my-agent.example.com \     │
+  │       -m "Find me a pasta recipe"                │
+  │                                                  │
+  │   agent: Here's a classic carbonara recipe...    │
+  │                                                  │
+  ╰──────────────────────────────────────────────────╯
+```
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Why agentalk?](#why-agentalk)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Discover an Agent](#-discover-an-agent)
+  - [Send a Message](#-send-a-message)
+  - [Stream a Response](#-stream-a-response)
+  - [Manage Tasks](#-manage-tasks)
+- [Command Reference](#command-reference)
+- [Recipes](#recipes)
+- [Task States](#task-states)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why agentalk?
+
+The [A2A (Agent-to-Agent) protocol](https://google.github.io/A2A/) is an open standard by Google for agents to communicate. **agentalk** brings that protocol to your terminal.
+
+<table>
+<tr>
+<td width="50">🔍</td>
+<td><strong>Discover</strong></td>
+<td>Fetch and inspect agent cards to see what an agent can do</td>
+</tr>
+<tr>
+<td>💬</td>
+<td><strong>Message</strong></td>
+<td>Send messages and get structured responses</td>
+</tr>
+<tr>
+<td>🌊</td>
+<td><strong>Stream</strong></td>
+<td>Real-time SSE streaming for long-running tasks</td>
+</tr>
+<tr>
+<td>📋</td>
+<td><strong>Tasks</strong></td>
+<td>Full task lifecycle management — get, list, cancel</td>
+</tr>
+<tr>
+<td>🎨</td>
+<td><strong>Pretty Output</strong></td>
+<td>Colored, human-friendly display; <code>--json</code> for scripting</td>
+</tr>
+<tr>
+<td>🔒</td>
+<td><strong>Auth-ready</strong></td>
+<td>Pass any HTTP headers for Bearer tokens, API keys, etc.</td>
+</tr>
+<tr>
+<td>🏢</td>
+<td><strong>Multi-tenant</strong></td>
+<td>Built-in tenant isolation with <code>--tenant</code></td>
+</tr>
+</table>
+
+## Quick Start
+
+### Install globally
+
+```bash
+pnpm add -g agentalk
+```
+
+### Or run instantly with npx / pnpm dlx
+
+```bash
+pnpm dlx agentalk agent https://agent.example.com
+```
+
+> [!TIP]
+> No configuration needed. Just point it at any A2A-compatible agent URL and go.
+
+## Usage
+
+### 🔍 Discover an Agent
+
+```bash
+agentalk agent https://agent.example.com
+```
+
+<details>
+<summary>📸 <strong>Example output</strong></summary>
+
+```
+🤖 Recipe Agent
+   v1.0.0
+   Agent that helps users with recipes and cooking.
+
+Provider:
+  Google (https://ai.google.dev)
+
+Capabilities:
+  streaming, push-notifications
+
+Skills:
+  • Recipe Search (recipe-search)
+    Search for recipes by ingredients or cuisine
+    tags: cooking, recipes, food
+```
+
+</details>
+
+### 💬 Send a Message
+
+```bash
+# Simple message
+agentalk send https://agent.example.com -m "What can you do?"
+
+# Multi-turn conversation with context
+agentalk send https://agent.example.com -m "Tell me more" -c ctx_abc123
+
+# Continue an existing task
+agentalk send https://agent.example.com -m "Yes, proceed" -t task_xyz
+
+# Fire-and-forget (async)
+agentalk send https://agent.example.com -m "Process this report" --async
+```
+
+### 🌊 Stream a Response
+
+```bash
+agentalk stream https://agent.example.com -m "Generate a detailed analysis"
+```
+
+<details>
+<summary>📸 <strong>Example output</strong> (streamed in real-time)</summary>
+
+```
+[task-42] status → working
+agent: Analyzing the data...
+agent: Here are the key findings:
+[task-42] 📎 report.md: # Analysis Report ... (final)
+[task-42] status → completed
+```
+
+</details>
+
+### 📋 Manage Tasks
+
+```bash
+agentalk task get    https://agent.example.com task_abc123   # Get status
+agentalk task list   https://agent.example.com               # List all
+agentalk task list   https://agent.example.com -s TASK_STATE_COMPLETED  # Filter
+agentalk task cancel https://agent.example.com task_abc123   # Cancel
+```
+
+---
+
+## Command Reference
+
+```
+agentalk [options] [command]
+
+Commands:
+  agent <url>                 Fetch and display an agent card
+  send [options] <url>        Send a message to an agent
+  stream [options] <url>      Send a message and stream the response (SSE)
+  task get <url> <taskId>     Get a task by ID
+  task list [options] <url>   List tasks
+  task cancel <url> <taskId>  Cancel a task
+
+Global Options:
+  --json                      Output raw JSON (great for piping/scripting)
+  -H, --header <key:value>    Add HTTP header (repeatable)
+  --tenant <id>               Tenant ID for multi-tenant agents
+  -V, --version               Show version
+  -h, --help                  Show help
+```
+
+<details>
+<summary><code>send</code> options</summary>
+
+| Flag | Description |
+|------|-------------|
+| `-m, --message <text>` | Message text **(required)** |
+| `-c, --context <id>` | Context ID for multi-turn conversations |
+| `-t, --task <id>` | Task ID to continue an existing task |
+| `--output-modes <modes>` | Accepted output MIME types (comma-separated) |
+| `--history-length <n>` | Max history messages to return |
+| `--async` | Return immediately without waiting |
+
+</details>
+
+<details>
+<summary><code>stream</code> options</summary>
+
+| Flag | Description |
+|------|-------------|
+| `-m, --message <text>` | Message text **(required)** |
+| `-c, --context <id>` | Context ID for multi-turn conversations |
+| `-t, --task <id>` | Task ID to continue an existing task |
+| `--output-modes <modes>` | Accepted output MIME types (comma-separated) |
+
+</details>
+
+<details>
+<summary><code>task list</code> options</summary>
+
+| Flag | Description |
+|------|-------------|
+| `-c, --context <id>` | Filter by context ID |
+| `-s, --status <state>` | Filter by task state |
+| `--history-length <n>` | Max history messages per task |
+| `--artifacts` | Include artifacts in response |
+| `--page-size <n>` | Results per page |
+| `--page-token <token>` | Pagination token |
+
+</details>
+
+---
+
+## Recipes
+
+### Pipe JSON output to jq
+
+```bash
+# Extract just the task state
+agentalk --json task get https://agent.example.com task_123 | jq '.status.state'
+
+# Get all skill names from an agent
+agentalk --json agent https://agent.example.com | jq '.skills[].name'
+```
+
+### Use with authentication
+
+```bash
+# Bearer token
+agentalk agent https://agent.example.com -H "Authorization: Bearer sk-xxx"
+
+# API key in header
+agentalk send https://agent.example.com -m "Hello" -H "X-API-Key: key_xxx"
+```
+
+### Multi-turn conversation
+
+```bash
+# 1. Start conversation — grab the contextId
+CTX=$(agentalk --json send https://agent.example.com -m "Plan a trip to Tokyo" \
+  | jq -r '.task.contextId')
+
+# 2. Continue with context
+agentalk send https://agent.example.com -m "Make it a 5-day trip" -c "$CTX"
+
+# 3. Continue with task
+agentalk send https://agent.example.com -m "Add restaurants" -c "$CTX" -t task-xyz
+```
+
+### Multi-tenant agents
+
+```bash
+agentalk --tenant org_acme send https://agent.example.com -m "Hello"
+```
+
+---
+
+## Task States
+
+| State | Icon | Description |
+|-------|------|-------------|
+| `TASK_STATE_SUBMITTED` | 📥 | Task received by the agent |
+| `TASK_STATE_WORKING` | ⏳ | Agent is processing |
+| `TASK_STATE_COMPLETED` | ✅ | Finished successfully |
+| `TASK_STATE_FAILED` | ❌ | Encountered an error |
+| `TASK_STATE_CANCELED` | 🚫 | Canceled by user |
+| `TASK_STATE_INPUT_REQUIRED` | 💬 | Agent needs more input |
+| `TASK_STATE_REJECTED` | ⛔ | Agent rejected the task |
+| `TASK_STATE_AUTH_REQUIRED` | 🔐 | Authentication required |
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph CLI["🖥️ CLI Layer"]
+        A[cli.ts<br/>Commander.js] --> B[commands/agent.ts]
+        A --> C[commands/send.ts]
+        A --> D[commands/stream.ts]
+        A --> E[commands/task.ts]
+    end
+
+    subgraph Core["⚙️ Core"]
+        F[client.ts<br/>A2AClient]
+        G[format.ts<br/>chalk output]
+        H[types.ts<br/>A2A v1.0 types]
+    end
+
+    B & C & D & E --> F
+    B & C & D & E --> G
+    F --> H
+
+    subgraph Remote["☁️ Remote Agent"]
+        I["/.well-known/agent.json"]
+        J["POST /"]
+        K["POST /stream (SSE)"]
+        L["GET/POST /tasks/*"]
+    end
+
+    F -->|HTTP| I & J & K & L
+```
+
+<details>
+<summary>📁 <strong>Project structure</strong></summary>
+
+```
+src/
+├── cli.ts              # Entry point — Commander.js CLI setup
+├── client.ts           # A2AClient — HTTP client for all A2A operations
+├── format.ts           # Pretty-print formatters (chalk-powered)
+├── types.ts            # Full A2A Protocol v1.0 TypeScript types
+├── commands/
+│   ├── agent.ts        # `agentalk agent` command
+│   ├── send.ts         # `agentalk send` command
+│   ├── stream.ts       # `agentalk stream` command
+│   └── task.ts         # `agentalk task {get,list,cancel}` commands
+└── test/
+    ├── client.test.ts  # A2AClient unit tests (mock fetch)
+    ├── format.test.ts  # Formatter unit tests
+    └── cli.test.ts     # CLI integration tests
+```
+
+</details>
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Run tests (72 tests)
+pnpm test
+
+# Link globally for local dev
+pnpm link --global
+```
+
+### Requirements
+
+| Dependency | Version |
+|-----------|---------|
+| Node.js | ≥ 22 |
+| TypeScript | ≥ 5.7 |
+
+> [!NOTE]
+> Uses native `fetch` (no polyfill needed) and `node:test` for zero-dependency testing.
+
+---
+
+## Contributing
+
+Contributions are welcome! Here's how:
+
+1. Fork the repo
+2. Create your branch (`git checkout -b feat/amazing-feature`)
+3. Make your changes
+4. Run the tests (`pnpm test`)
+5. Commit (`git commit -m 'feat: add amazing feature'`)
+6. Push (`git push origin feat/amazing-feature`)
+7. Open a Pull Request
+
+> [!NOTE]
+> Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
+
+---
+
+## Related
+
+| Resource | Link |
+|----------|------|
+| A2A Protocol Spec | [google.github.io/A2A](https://google.github.io/A2A/) |
+| A2A GitHub | [github.com/google/A2A](https://github.com/google/A2A) |
+| npm Package | [npmjs.com/package/agentalk](https://www.npmjs.com/package/agentalk) |
+
+---
+
+<div align="center">
+
+**[MIT](./LICENSE) © 2026**
+
+Made with ❤️ for the A2A ecosystem
+
+[⬆ Back to top](#-agentalk)
+
+</div>