agentalk

name	agentalk
description	Develop, test, and contribute to the agentalk CLI — the A2A protocol client. Use when working on this project's source code, adding commands, fixing bugs, running tests, or releasing. Triggers: 'agentalk dev', 'add command', 'run tests', 'build', 'release', 'A2A client code'.

agentalk — Project Development Guide

A TypeScript CLI (curl for AI agents) implementing the A2A (Agent-to-Agent) protocol v1.0.

Quick Reference

pnpm install        # Install deps
pnpm build          # Compile TypeScript → dist/
pnpm dev            # Watch mode
pnpm test           # Run all tests (node:test)

Architecture

src/
├── cli.ts              # Entry — Commander.js program setup
├── client.ts           # A2AClient — HTTP client for all A2A ops
├── format.ts           # Pretty-print formatters (chalk)
├── types.ts            # Full A2A Protocol v1.0 TypeScript types
├── commands/
│   ├── agent.ts        # `agentalk agent` — fetch agent card
│   ├── send.ts         # `agentalk send` — one-shot message
│   ├── stream.ts       # `agentalk stream` — SSE streaming
│   └── task.ts         # `agentalk task {get,list,cancel}`
└── test/
    ├── client.test.ts  # A2AClient unit tests (mock fetch)
    ├── format.test.ts  # Formatter unit tests
    └── cli.test.ts     # CLI integration tests

Conventions

• Runtime: Node.js ≥ 22, TypeScript ≥ 5.7
• Package manager: pnpm (lockfile committed)
• Module system: ESM ("type": "module")
• Testing: node:test + node:assert — zero external test deps
• HTTP: Native fetch — no polyfills
• Streaming: eventsource-parser for SSE
• Output: chalk for colored terminal output; --json flag for machine-readable
• CLI framework: commander
• Commits: Follow Conventional Commits

Adding a New Command

1. Create src/commands/<name>.ts, export a function that receives (program: Command) and registers the subcommand
2. Wire it in src/cli.ts by importing and calling the registration function
3. Add formatting helpers in src/format.ts if needed
4. Add types in src/types.ts if new A2A types are involved
5. Add tests in src/test/<name>.test.ts
6. Run pnpm build && pnpm test to verify

Adding Tests

• Tests live in src/test/ and use node:test (describe, it, mock)
• Mock fetch via mock.method(globalThis, 'fetch', ...) — see client.test.ts for patterns
• Build before testing: tests run against compiled JS in dist/test/

Release Workflow

Publishing is automated via GitHub Actions (.github/workflows/publish.yml):

1. Bump version in package.json
2. Commit & push
3. Create a GitHub Release → triggers: pnpm install → pnpm build → pnpm test → pnpm publish --provenance --access public

A2A Protocol Reference

The CLI implements the A2A Protocol v1.0:

Endpoint	Method	CLI Command
/.well-known/agent.json	GET	agentalk agent <url>
/	POST	agentalk send <url>
/stream	POST (SSE)	agentalk stream <url>
/tasks/<id>	GET	agentalk task get <url> <id>
/tasks	GET	agentalk task list <url>
/tasks/<id>/cancel	POST	agentalk task cancel <url> <id>

Global CLI Options

• --json — Raw JSON output for scripting/piping
• -H, --header <K:V> — HTTP headers (repeatable, for auth)
• --tenant <id> — Multi-tenant isolation