a2acalling 0.6.75 → 0.6.76

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-conversations.md

@@ -0,0 +1,47 @@
+---
+description: Browse and manage A2A conversations
+allowed-tools: [Bash]
+argument-hint: [show <id>|end <id>|--contact <name>|--status active]
+---
+
+List, view, and manage A2A agent conversations.
+
+## Usage
+
+```
+/a2a-conversations                        # list recent conversations
+/a2a-conversations --contact Alice        # filter by contact
+/a2a-conversations --status active        # filter by status
+/a2a-conversations show <id>              # show conversation details with messages
+/a2a-conversations end <id>              # end an active conversation
+```
+
+## Instructions
+
+Parse the user's arguments to determine the action:
+
+### List conversations (default)
+
+```bash
+a2a conversations $ARGUMENTS
+```
+
+Format as a table: ID, contact, status (active/concluded/timeout), message count, last activity.
+
+### Show conversation detail
+
+```bash
+a2a conversations show $ID
+```
+
+Display the full conversation: each message with timestamp, direction (inbound/outbound), and content. Show the summary if the conversation has concluded.
+
+### End a conversation
+
+```bash
+a2a conversations end $ID
+```
+
+This generates a summary and marks the conversation as concluded. Show the summary to the user.
+
+If no conversations exist, suggest: "No conversations yet. Start one with `/a2a-call`."

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-gui.md

@@ -0,0 +1,30 @@
+---
+description: Open the A2A dashboard in browser or native app
+allowed-tools: [Bash]
+argument-hint: [--tab contacts|calls|logs|settings|invites]
+---
+
+Open the A2A Calling dashboard. Uses the native Callbook app if installed, otherwise opens in the default browser.
+
+## Usage
+
+```
+/a2a-gui                   # open dashboard
+/a2a-gui --tab contacts    # open specific tab
+/a2a-gui --tab calls       # open calls tab
+/a2a-gui --tab logs        # open logs tab
+/a2a-gui --tab settings    # open settings tab
+/a2a-gui --tab invites     # open invites tab
+```
+
+## Instructions
+
+Run the dashboard command with any arguments:
+
+```bash
+a2a gui $ARGUMENTS
+```
+
+If it fails because the server is not running, suggest `/a2a-setup` to start it.
+
+Tell the user the dashboard URL (typically `http://127.0.0.1:<port>/dashboard/`) so they can also bookmark it.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-invite.md

@@ -0,0 +1,63 @@
+---
+description: Create or revoke A2A invite tokens for sharing with other agents
+allowed-tools: [Bash]
+argument-hint: [name] [--tier public|friends|family] [--expires 7d] | revoke <id>
+---
+
+Create an A2A federation token and display the invite URL, or revoke an existing token.
+
+## Usage
+
+### Create invite
+
+```
+/a2a-invite Alice --tier friends --expires 7d
+/a2a-invite "Bob's Agent" --tier public
+/a2a-invite                              # interactive — uses defaults
+```
+
+### Revoke invite
+
+```
+/a2a-invite revoke <token_id>            # revoke a specific token
+/a2a-invite list                         # list active tokens to find IDs
+```
+
+## Instructions
+
+### Create flow
+
+Parse the user's arguments and run:
+
+```bash
+a2a create $ARGUMENTS
+```
+
+If no arguments provided, run `a2a create` with no flags (interactive mode).
+
+After success, display the invite URL prominently and explain:
+1. The URL format: `a2a://<hostname>/<token>`
+2. Share this URL with the other agent's owner
+3. The token tier controls what the caller can access (public = read-only, friends = calendar/email/search read, family = full access)
+4. The token expires per the `--expires` flag (default: never)
+
+Also suggest: "Run `/a2a-contacts` to see who already has access."
+
+### Revoke flow
+
+If the first argument is `revoke`:
+
+1. If a token ID is provided: `a2a revoke <id>`
+2. If no ID provided: first run `a2a list` to show active tokens, then ask the user which to revoke.
+
+**Always confirm before revoking:** "This will permanently invalidate token <id>. The holder will no longer be able to call you. Proceed?"
+
+### List flow
+
+If the first argument is `list`:
+
+```bash
+a2a list
+```
+
+Show active tokens with their IDs, names, tiers, and expiry dates.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-setup.md

@@ -0,0 +1,30 @@
+---
+description: Set up A2A Calling — onboard, start server, configure agent
+allowed-tools: [Bash, Read, Write]
+argument-hint: [--force]
+---
+
+Set up or reset your A2A Calling installation. Runs onboarding, starts the server, and configures your agent.
+
+## Usage
+
+```
+/a2a-setup              # first-time setup or resume incomplete onboarding
+/a2a-setup --force      # reset and re-run from scratch
+```
+
+## Instructions
+
+1. Check if already onboarded: `a2a config --show`
+2. If not onboarded (or `--force`): run `a2a quickstart $ARGUMENTS`
+3. If already onboarded but server not running: run `a2a server` in background
+4. After setup, show the status with `a2a config --show` and `a2a list`
+
+The quickstart flow will:
+- Detect an available port
+- Start the A2A server
+- Detect the hostname
+- Prompt for disclosure topics (what your agent discusses)
+- Save the configuration
+
+If running non-interactively, quickstart auto-accepts defaults.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-skills.md

@@ -0,0 +1,27 @@
+---
+description: Reinstall A2A skill files into current project
+allowed-tools: [Bash]
+argument-hint: [--check|--force]
+---
+
+Reinstall or check A2A slash-command skill files in the current project.
+
+## Usage
+
+```
+/a2a-skills              # reinstall skill files (skips unchanged)
+/a2a-skills --check      # check which files are installed vs missing
+/a2a-skills --force      # force reinstall all files
+```
+
+## Instructions
+
+Run the skills command with the user's arguments:
+
+```bash
+a2a skills $ARGUMENTS
+```
+
+Show the result: which files were installed, skipped (already up to date), or had errors.
+
+If files were reinstalled, suggest reloading Claude Code to pick up the new slash commands.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-status.md

@@ -0,0 +1,46 @@
+---
+description: Check A2A server status, active conversations, version, and agent health
+allowed-tools: [Bash, Read]
+argument-hint: [--version]
+---
+
+Check the health of your A2A installation — server running, conversations active, contacts online, version info.
+
+## Usage
+
+```
+/a2a-status              # full status dashboard
+/a2a-status --version    # show version only
+```
+
+## Instructions
+
+### Version only
+
+If `--version` is specified:
+
+```bash
+a2a version
+```
+
+Show the version and exit.
+
+### Full status (default)
+
+Run these commands and compile a status report:
+
+1. **Version:** `a2a version`
+2. **Config:** `a2a config --show`
+3. **Active tokens:** `a2a list`
+4. **Contacts:** `a2a contacts`
+5. **Recent conversations:** `a2a conversations --limit 5`
+
+Present a clear status dashboard:
+- Version: current version number
+- Server: running/stopped (with port and hostname)
+- Tokens: N active, N expired/revoked
+- Contacts: N total
+- Recent calls: last 5 conversations with status
+
+If the server is not running, suggest `/a2a-setup` to start it.
+If not onboarded, suggest `/a2a-setup` for first-time setup.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-uninstall.md

@@ -0,0 +1,36 @@
+---
+description: Uninstall A2A Calling — stop server and remove config
+allowed-tools: [Bash, Read]
+argument-hint: [--keep-config]
+---
+
+Uninstall A2A Calling. Stops the server, removes skill files, and optionally removes configuration.
+
+## Usage
+
+```
+/a2a-uninstall                # uninstall with confirmation
+/a2a-uninstall --keep-config  # uninstall but preserve config files
+```
+
+## Instructions
+
+**This is a destructive operation. Always confirm with the user before proceeding.**
+
+1. Show the user what will be removed:
+   - Running A2A server (will be stopped)
+   - Skill files in `.claude/commands/a2a-*.md`
+   - CLAUDE.md A2A section
+   - `.codex/AGENTS.md`
+   - Config at `~/.config/openclaw/a2a-config.json` (unless `--keep-config`)
+   - Disclosure at `~/.config/openclaw/a2a-disclosure.json` (unless `--keep-config`)
+
+2. Ask the user to confirm: "This will stop the A2A server and remove installed files. Proceed?"
+
+3. If confirmed, run:
+
+```bash
+a2a uninstall --force
+```
+
+If `--keep-config` was specified, tell the user their config files were preserved and can be reused on reinstall.

package/.claude/worktrees/agent-a0a8dd02/.claude/commands/a2a-update.md

@@ -0,0 +1,41 @@
+---
+description: Check for and install A2A updates
+allowed-tools: [Bash]
+argument-hint: [--check]
+---
+
+Check for available A2A updates and optionally install them.
+
+## Usage
+
+```
+/a2a-update              # check for updates and install if available
+/a2a-update --check      # check only, don't install
+```
+
+## Instructions
+
+1. First, check for updates:
+
+```bash
+a2a update --check
+```
+
+2. Show the user the current version vs available version.
+
+3. If an update is available and `--check` was NOT specified:
+   - Tell the user what version is available
+   - Ask for confirmation before updating
+   - If confirmed, run:
+
+```bash
+a2a update
+```
+
+4. After updating, show the new version:
+
+```bash
+a2a version
+```
+
+If the user is already on the latest version, tell them so.

package/.claude/worktrees/agent-a0a8dd02/.node-version

@@ -0,0 +1 @@
+20

package/.claude/worktrees/agent-a0a8dd02/ARCHITECTURE.md

@@ -0,0 +1,135 @@
+# Architecture — A2A Calling
+
+## System Overview
+
+A2A Calling enables agent-to-agent communication across OpenClaw instances. Agents create tokens with scoped permissions, share invite URLs, and remote agents call in via HTTP.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  CLI (bin/cli.js)                                                │
+│  Commands: create/list/revoke/call + ops commands (quickstart, gui, update, app, skills) │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Express Server (src/server.js)                                   │
+│  ├─ /api/a2a/* (invoke/end/message:send/agent-card/tokens/admin) → src/routes/a2a.js │
+│  ├─ /api/a2a/callbook/* + /callbook/* → src/routes/callbook.js         │
+│  ├─ /api/a2a/dashboard/* + /dashboard/* → src/routes/dashboard.js      │
+│  └─ /.well-known/a2a-agent-card → src/lib/agent-card.js               │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Core Libraries (src/lib/)                                        │
+│  ├─ tokens.js         Token CRUD, validation, tiers               │
+│  ├─ client.js         A2AClient for outbound calls (retry + size cap) │
+│  ├─ conversations.js  ConversationStore (SQLite)                  │
+│  ├─ conversation-driver.js  Multi-turn call orchestration         │
+│  ├─ summarizer.js     Call summary generation                     │
+│  ├─ summary-prompt.js Unified summary prompt builder              │
+│  ├─ summary-formatter.js  Format summaries for display            │
+│  ├─ disclosure.js     Disclosure manifest loading + tier merging  │
+│  ├─ config.js         Config file management                      │
+│  ├─ crypto.js         Ed25519 identity keypair + signing           │
+│  ├─ agent-card.js     Google A2A Agent Card generation            │
+│  ├─ logger.js         Structured logger (SQLite + stdout)         │
+│  ├─ call-monitor.js   Active call monitoring                      │
+│  ├─ callbook.js       Contact/callbook management                 │
+│  ├─ claude-subagent.js  Claude API integration for summaries      │
+│  ├─ openclaw-integration.js  OpenClaw runtime hooks               │
+│  ├─ prompt-template.js  Prompt template utilities                 │
+│  ├─ runtime-adapter.js  Runtime mode detection (openclaw/claude/test) │
+│  ├─ dashboard-events.js  SSE event broadcasting                   │
+│  ├─ external-ip.js    External IP/hostname detection              │
+│  ├─ invite-host.js    Invite URL construction                     │
+│  ├─ port-scanner.js   Available port detection                    │
+│  ├─ pid-file.js       PID file management                         │
+│  ├─ turn-timeout.js   Conversation turn timeout handling          │
+│  ├─ local-request.js  Proxy-aware local request detection (A2A-73) │
+│  ├─ update-checker.js Version update detection                    │
+│  └─ update-manager.js Self-update orchestration                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Data Storage
+
+- **Tokens**: JSON file at `~/.config/openclaw/a2a.json`
+- **Conversations**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-conversations.db` (WAL mode, A2A-71)
+- **Logs**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-logs.db` (WAL mode, A2A-71)
+- **Callbook**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-callbook.db`
+- **Dashboard Events**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-events.db`
+- **Config**: JSON at `~/.config/openclaw/a2a-config.json`
+- **Disclosure**: JSON at `~/.config/openclaw/a2a-disclosure.json`
+
+## Database Lifecycle Management (A2A-55)
+
+All three data stores have automatic retention cleanup that runs on server startup:
+
+- **Conversations**: `ConversationStore.pruneOld()` compresses messages 7+ days old, deletes concluded/timeout conversations 90+ days old. Active conversations are never deleted.
+- **Logs**: `LogStore.pruneOld()` deletes entries 30+ days old. Auto-prune triggers on every 1000th write (best effort). `pruneAllLoggerStores()` iterates all cached stores.
+- **Tokens**: `TokenStore.cleanupExpired()` removes tokens expired >1 hour (grace for in-flight calls) and revoked tokens >30 days old.
+
+All retention periods are configurable via `a2a-config.json` `retention` section. SQLite VACUUM runs only after >100 rows deleted. All cleanup is best-effort — failures are logged but never prevent server startup.
+
+## Permission System
+
+Three tiers with escalating capabilities:
+- **public**: `context-read` only
+- **friends**: `context-read`, `calendar.read`, `email.read`, `search`
+- **family**: `context-read`, `calendar`, `email`, `search`, `tools`, `memory`
+
+Disclosure policy is manifest-driven (`~/.config/openclaw/a2a-disclosure.json`), not a token/tier `disclosure` field:
+- Per-tier `topics`, `objectives`, and `do_not_discuss` are loaded from the disclosure manifest
+- Global `never_disclose` always applies
+- Tier inheritance is enforced in prompt construction (`friends` includes `public`; `family` includes `friends` + `public`)
+
+## Dependencies
+
+Only two runtime dependencies (intentionally minimal):
+- `express` — HTTP server and routing
+- `better-sqlite3` — SQLite for conversations, logs, callbook, and dashboard events
+
+## Dashboard
+
+Single-page app served from `src/dashboard/public/`. Uses Shoelace web components. Communicates with the API via `/api/a2a/dashboard/*` routes. UI is served at both `/api/a2a/dashboard/*` and legacy `/dashboard/*` mounts. Includes panels: Contacts, Calls, Permissions, Invites, Logs, Health (E2E test results), and Settings.
+
+## Native macOS App
+
+Tauri v2 app at `native/macos/` wrapping the dashboard SPA. Provides native menus, notifications, and server lifecycle management.
+
+Runtime behavior:
+- App startup uses a sidecar-first strategy (`app.shell().sidecar("a2a-server")`) from `native/macos/src-tauri/src/server.rs`
+- If sidecar spawn fails, it falls back to starting an external `a2a` CLI process
+- Sidecar exits are monitored with bounded auto-restart and exponential backoff (up to 5 consecutive crashes)
+- Sidecar logs are bridged to the UI via emitted events
+
+Packaging:
+- The standalone server binary is built from `src/server.js` via `scripts/build-standalone.sh` using `@yao-pkg/pkg`
+- Output binaries live at `native/macos/src-tauri/binaries/a2a-server-*`
+- Tauri release builds bundle the app artifacts (`.dmg`, `.app.tar.gz`) via `.github/workflows/tauri-build.yml`
+
+## Identity Verification
+
+Ed25519 cryptographic identity for agents. Each instance generates a keypair on first run (stored in config). Outbound calls sign messages; inbound calls verify signatures. Uses Node.js built-in `crypto.sign`/`crypto.verify` — no external dependencies. See `src/lib/crypto.js`.
+
+## Google A2A Compatibility
+
+Inbound compatibility endpoints are implemented in `src/routes/a2a.js`:
+- `POST /api/a2a/message:send` (Google A2A wire format ingress mapped into internal invoke flow)
+- `GET /api/a2a/agent-card` and `GET /.well-known/a2a-agent-card` (Agent Card discovery via `src/lib/agent-card.js`)
+
+Outbound calls auto-detect Google A2A remotes via Agent Card (`GET /.well-known/a2a-agent-card`, cached 5 min with prune-on-access eviction). When detected, `A2AClient.call()` sends via `message:send` format with response translation to the internal `{ response, conversation_id, can_continue }` shape; `end()` returns a synthetic `{ ended: true, summary: null }`. See `src/lib/client.js` (A2A-80).
+
+## Testing
+
+Zero-dependency test runner at `test/run.js` with custom assert API. Three test tiers:
+- `test/unit/` — Unit tests for individual modules
+- `test/integration/` — Integration tests for multi-module flows
+- `test/e2e/` — End-to-end tests for full system flows
+
+Test profiles at `test/profiles/` represent real personas with distinct permission tiers.
+
+E2E test results are persisted to `~/.config/openclaw/test-results/` via `test/e2e/persist.js` (timestamped `result-*.json` plus `latest.json`) and surfaced in the dashboard Health tab. The `scripts/run-e2e.sh` orchestrator runs E2E suites and stores results.
+
+## Network Resilience
+
+The outbound A2A client (`src/lib/client.js`) retries transient network failures (ECONNRESET, ECONNREFUSED, EPIPE, ENOTFOUND, EAI_AGAIN, timeouts) with exponential backoff (0s, 1s, 2s). HTTP 4xx/5xx errors are not retried. All response accumulation is capped at 2MB to prevent OOM from malicious remotes. These retry and size-cap mechanisms apply equally to Google A2A outbound calls via the same `withRetry()` and `handleSizeCappedResponse()` functions (A2A-80).

package/.claude/worktrees/agent-a0a8dd02/CLAUDE-INSTALL.md

@@ -0,0 +1,156 @@
+# A2A Calling — Installed Package Context
+
+This file is automatically installed by the `a2acalling` package to give Claude Code
+immediate context after `npm install`. It describes what A2A Calling is, how to get
+started, and the full CLI reference — so you never need to grep source code.
+
+## Getting Started
+
+After installing `a2acalling`, the FIRST thing to do is run onboarding:
+
+```bash
+a2a quickstart
+```
+
+This is the single entry point for all setup. It will:
+1. Detect an available port (prefers 80, falls back to 3001+)
+2. Start the A2A server
+3. Detect the hostname
+4. Prompt for disclosure topics (what your agent discusses with callers)
+5. On macOS, offer to install the native Callbook app
+6. Save configuration to `~/.config/openclaw/a2a-config.json`
+
+If onboarding was already completed, re-run with `--force`:
+
+```bash
+a2a quickstart --force
+```
+
+## Native macOS App (A2A Callbook)
+
+On macOS, a native desktop app is available. It provides a dashboard GUI for managing
+calls, contacts, tokens, and logs.
+
+```bash
+a2a app install          # Download and install from GitHub releases
+a2a app status           # Check if installed, show version and path
+a2a app uninstall        # Remove from ~/Applications
+```
+
+After install, the app lives at `~/Applications/A2A Callbook.app`. You can also
+open the dashboard in a browser:
+
+```bash
+a2a gui                  # Open dashboard in browser (or native app if installed)
+a2a gui --tab logs       # Open specific tab: contacts|calls|logs|settings|invites
+```
+
+## Full CLI Reference
+
+### Token Management
+
+```bash
+a2a create --name "AgentName" --owner "OwnerName" --expires 7d --permissions friends
+  # Options:
+  #   --name, -n        Token/agent name
+  #   --owner, -o       Owner name
+  #   --expires, -e     1h, 1d, 7d, 30d, never (default: 1d)
+  #   --permissions, -p public, friends, family (default: public)
+  #   --disclosure, -d  public, minimal, none (default: minimal)
+  #   --notify          all, summary, none (default: all)
+  #   --max-calls       Maximum invocations (default: 100)
+  #   --topics          Custom topics (comma-separated)
+  #   --tools           Custom tool allowlist (comma-separated)
+  #   --link, -l        Auto-link to contact name
+
+a2a list                 # List active tokens
+a2a revoke <token_id>    # Revoke a token
+```
+
+### Contacts
+
+```bash
+a2a contacts             # List all contacts (shows permission badges)
+a2a contacts add <url> --name "Alice" --owner "Alice Chen"
+a2a contacts show <name> # Show contact details + linked token
+a2a contacts edit <name> # Edit contact metadata
+a2a contacts link <name> <token_id>  # Link a token to a contact
+a2a contacts ping <name> # Ping contact, update status
+a2a contacts rm <name>   # Remove contact
+```
+
+### Calling
+
+```bash
+a2a call <contact|url> "<message>"   # Multi-turn call (default: 8-25 turns)
+a2a call Alice "Hello!"              # Call by contact name
+a2a call a2a://host/fed_xxx "Hi"     # Call by invite URL
+a2a call Alice "Quick q" --single    # One-shot (single turn)
+  # --min-turns N     Minimum turns before close (default: 8)
+  # --max-turns N     Maximum turns (default: 25)
+
+a2a ping <url>           # Check if agent is reachable
+a2a status <url>         # Get remote A2A status
+```
+
+### Conversations
+
+```bash
+a2a conversations                    # List all conversations
+  # --contact         Filter by contact
+  # --status          Filter: active, concluded, timeout
+  # --limit           Max results (default: 20)
+a2a conversations show <id>          # Show conversation with messages
+a2a conversations end <id>           # End and summarize conversation
+```
+
+### Server & Setup
+
+```bash
+a2a quickstart                       # First-time setup (port, hostname, disclosure)
+  # --port, -p        Preferred port (default: 80, fallback: 3001+)
+  # --force           Reset and re-run from scratch
+  # --submit '<json>' Submit disclosure JSON
+
+a2a server --port 3001               # Start server manually
+a2a config --show                    # Show current configuration
+a2a status                           # Show local server status
+a2a gui                              # Open dashboard GUI
+a2a app install                      # Install native macOS app
+a2a setup                            # Auto setup (gateway-aware)
+```
+
+### Maintenance
+
+```bash
+a2a update               # Update to latest version
+a2a update --check       # Check for updates without installing
+a2a skills               # Install Claude Code + Codex skill files
+a2a uninstall --force    # Stop server and remove config/DB
+a2a version              # Show installed version
+```
+
+## Permission Tiers
+
+| Tier | Default Capabilities |
+|------|---------------------|
+| `public` | `context-read` |
+| `friends` | `context-read`, `calendar.read`, `email.read`, `search` |
+| `family` | `context-read`, `calendar`, `email`, `search`, `tools`, `memory` |
+
+## Disclosure Levels
+
+| Level | Behavior |
+|-------|----------|
+| `public` | Agent shares freely within tier boundaries |
+| `minimal` | Direct answers only, no volunteered context |
+| `none` | Confirms capability, provides no information |
+
+## Key Paths
+
+- Config: `~/.config/openclaw/a2a-config.json`
+- Disclosure: `~/.config/openclaw/a2a-disclosure.json`
+- Native app: `~/Applications/A2A Callbook.app` (macOS only)
+- Dashboard: `http://127.0.0.1:<port>/dashboard/`
+
+<!-- END A2A CALLING SECTION -->