a2acalling 0.6.60 → 0.6.62

package/.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/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/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/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/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/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/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/ARCHITECTURE.md

@@ -0,0 +1,92 @@
+# 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, contacts, conversations   │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Express Server (src/server.js)                                   │
+│  ├─ /api/a2a/*      → src/routes/a2a.js (inbound calls, tokens)  │
+│  ├─ /api/callbook/* → src/routes/callbook.js (callbook sync)     │
+│  └─ /dashboard/*    → src/routes/dashboard.js (API + SPA)        │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Core Libraries (src/lib/)                                        │
+│  ├─ tokens.js         Token CRUD, validation, tiers               │
+│  ├─ client.js         A2AClient for outbound calls                │
+│  ├─ 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 level enforcement                │
+│  ├─ config.js         Config file management                      │
+│  ├─ 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 (standalone/OCW)   │
+│  ├─ 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          │
+│  ├─ 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`
+- **Logs**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-logs.db`
+- **Config**: JSON at `~/.config/openclaw/a2a-config.json`
+- **Disclosure**: JSON at `~/.config/openclaw/a2a-disclosure.json`
+
+## 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`
+
+Three disclosure levels controlling information sharing:
+- **public**: Shares freely within tier boundaries
+- **minimal**: Direct answers only, no volunteered context
+- **none**: Confirms capability, provides no information
+
+## Dependencies
+
+Only two runtime dependencies (intentionally minimal):
+- `express` — HTTP server and routing
+- `better-sqlite3` — SQLite for conversations and logs
+
+## Dashboard
+
+Single-page app served from `src/dashboard/public/`. Uses Shoelace web components. Communicates with the API via `/dashboard/api/*` routes. Includes tabs: Contacts, Calls, Logs, Settings, Invites, Permissions, and Health (E2E test results).
+
+## Native macOS App
+
+Tauri v2 app at `native/macos/` wrapping the dashboard SPA. Provides native menus, notifications, and server lifecycle management.
+
+## 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/a2a-e2e-results.json` via `test/e2e/persist.js` and surfaced in the dashboard Health tab. The `scripts/run-e2e.sh` orchestrator runs E2E suites and stores results.

package/CONVENTIONS.md

@@ -0,0 +1,78 @@
+# Conventions — A2A Calling
+
+## Logging
+
+Use the structured logger from `src/lib/logger.js`. Never use bare `console.log`.
+
+```js
+const { createLogger } = require('./logger');
+const logger = createLogger({ component: 'a2a.mymodule' });
+logger.info('Something happened', { event: 'my_event', data: { key: 'val' } });
+```
+
+Components follow dotted naming: `a2a.tokens`, `a2a.server`, `a2a.client`, etc.
+
+## Error Handling
+
+- Use the project's existing error patterns (e.g., `A2AError` from `src/lib/client.js`)
+- Log errors with `logger.error()`, including error codes and hints
+- HTTP responses use consistent JSON format: `{ success: false, error: { code, message } }`
+- Do NOT create new error classes without strong justification
+
+## Config Resolution
+
+Config directory resolves via:
+1. `process.env.A2A_CONFIG_DIR`
+2. `process.env.OPENCLAW_CONFIG_DIR`
+3. `~/.config/openclaw/`
+
+Always use `src/lib/config.js` for config access. Do not hardcode paths.
+
+## Testing
+
+- Test runner: `node test/run.js` (zero-dependency, custom assert API)
+- Test files: `*.test.js` in `test/unit/`, `test/integration/`, `test/e2e/`
+- Test helpers: `test/helpers.js`
+- Test profiles: `test/profiles/*.js` — real personas, not generic stubs
+- Prefer testing through the public API of each module
+
+## Dependencies
+
+This project is intentionally minimal-dependency. Only two runtime deps:
+- `express` — HTTP
+- `better-sqlite3` — SQLite
+
+Do NOT add new npm dependencies without explicit justification. Use Node.js built-ins.
+
+## Module Pattern
+
+All modules use CommonJS (`require`/`module.exports`). Each lib file exports a focused API. Large modules export a class (e.g., `TokenStore`, `ConversationStore`, `A2AClient`). Utility modules export functions.
+
+## Naming
+
+- Files: kebab-case (`call-monitor.js`, `dashboard-events.js`)
+- Classes: PascalCase (`TokenStore`, `A2AClient`)
+- Functions/variables: camelCase
+- Constants: UPPER_SNAKE_CASE for true constants
+- Token IDs: prefixed with `fed_` (federation tokens)
+- Trace IDs: prefixed with `trace_`
+
+## Dashboard
+
+- Single-page app in `src/dashboard/public/`
+- Uses Shoelace web components (`<sl-*>` elements)
+- Communicates via fetch to `/dashboard/api/*` endpoints
+- SSE for real-time updates via `src/lib/dashboard-events.js`
+
+## Permission Tiers
+
+Tokens have a tier (`public`, `friends`, `family`) and a disclosure level (`public`, `minimal`, `none`). These are enforced at the route level in `src/routes/a2a.js`.
+
+## Anti-Patterns
+
+- Do NOT use `console.log` — use the structured logger
+- Do NOT add npm dependencies for things Node.js builtins handle
+- Do NOT create new error classes — use existing patterns
+- Do NOT hardcode config paths — use config resolution
+- Do NOT use `var` — use `const` or `let`
+- Do NOT use sync file I/O in request handlers (sync is OK in CLI and setup)