a2acalling 0.6.75 → 0.6.76

package/.claude/worktrees/agent-af1f3b59/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 -->

package/.claude/worktrees/agent-af1f3b59/CONVENTIONS.md

@@ -0,0 +1,178 @@
+# Conventions — A2A Calling
+
+## Logging
+
+For runtime/server code under `src/`, use the structured logger from `src/lib/logger.js`. Keep bare `console.log`/`console.error` limited to CLI/setup/test entrypoints (for user-facing terminal output) and the logger sink implementation in `src/lib/logger.js`.
+
+```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
+
+Runtime/server 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. Tooling scripts in this repo currently use CommonJS as well; only introduce ESM if a host integration requires it, and keep module style consistent within a file.
+
+## 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 `/api/a2a/dashboard/*` endpoints
+- SSE for real-time updates via `src/lib/dashboard-events.js`
+- Dark theme is the default; uses CSS custom properties for theming
+- Sidebar navigation with panel switching (Contacts, Calls, Permissions, Invites, Logs, Health, Settings)
+- Permissions tab uses tier cards with tool toggles and auto-save
+- Drag-and-drop uses event delegation on stable parent containers (`.perm-sidebar` for sidebar items, zone containers for drop targets) — do NOT bind listeners directly to innerHTML-generated elements (A2A-61)
+
+## Network Resilience (A2A-54)
+
+Outbound client methods (`call()`, `end()`) automatically retry transient network errors with exponential backoff. Pattern:
+- Use `withRetry(fn, { delays })` for retryable operations
+- Only retry on transient errors (ECONNRESET, ECONNREFUSED, EPIPE, ENOTFOUND, EAI_AGAIN, timeout)
+- Never retry HTTP 4xx/5xx — those are explicit server rejections
+- All HTTP responses are size-capped at 2MB via `handleSizeCappedResponse()`
+- Configurable retry delays via `_retryDelays` constructor option (used in tests with `[0,0,0]` for fast execution)
+
+## Dashboard API Testing (A2A-56)
+
+Dashboard API integration tests follow the pattern in `test/integration/dashboard-logs.test.js`:
+- Mount `createDashboardApiRouter()` on an Express app
+- Use `helpers.request()` for HTTP assertions (binds to 127.0.0.1 — bypasses auth)
+- Bust module caches for `dashboard`, `logger`, `tokens`, `config`, `disclosure`, `conversations`, `callbook`, `dashboard-events`
+- Call `loggerModule.closeAllLoggerStores()` in teardown to prevent SQLite handle leaks
+- Pass `convStore` directly via `options.convStore` when testing calls endpoints
+
+## Store Lifecycle (A2A-57)
+
+All SQLite store classes (`ConversationStore`, `DashboardEventStore`, `CallbookStore`, `LoggerStore`) implement a `close()` method following this pattern:
+```js
+close() {
+  if (this.db) {
+    try { this.db.close(); } catch (_) {}
+    this.db = null;
+  }
+}
+```
+- `close()` must be idempotent (safe to call multiple times)
+- `close()` must be a no-op when DB was never initialized (`this.db === null`)
+- The `server.js` `shutdown()` function closes all stores on SIGTERM/SIGINT: `serverConvStore`, `eventStore`, `callbookStore` (A2A-59), and logger stores
+- All stores should be created at the `server.js` module level and passed to route factories — do NOT create stores inside route factories (A2A-59)
+- Test teardown should call `store.close()` to prevent SQLite handle leaks
+
+## Permission Tiers
+
+Tokens carry a permissions tier (`public`, `friends`, `family`, `custom`). Disclosure policy is manifest-driven via `src/lib/disclosure.js` and tier inheritance in prompt/runtime paths.
+
+Do not add new logic that depends on `tier.disclosure` or `token.disclosure` fields; those fields were removed from the core tier/token model.
+
+## Local Request Detection (A2A-73)
+
+Use `isDirectLocalRequest(req)` from `src/lib/local-request.js` for admin/dashboard local-only checks. This helper validates loopback socket origin, localhost Host header, and absence of proxy-forwarding headers. Do NOT use raw `req.ip` comparison behind reverse proxies. The module also exports `isLoopbackAddress(ip)` for IP-only checks.
+
+## Route Hardening (A2A-53)
+
+- Rate limit Map has eviction: entries are swept when Map exceeds 1000 entries (stale >24h first, then oldest by insertion order)
+- Admin token comparison uses `timingSafeTokenEqual()` from `src/routes/a2a.js` — do NOT use `!==` for secret comparison
+- Query parameter parsing follows the dashboard.js pattern: `Math.min(max, Math.max(min, Number.parseInt(String(value), 10) || defaultValue))`
+
+## Retention & Cleanup (A2A-55)
+
+All data stores implement retention cleanup following the `dashboard-events.js` auto-prune pattern:
+
+- **Cleanup component**: Use `createLogger({ component: 'a2a.cleanup' })` for all retention logging
+- **Best effort**: Prune failures are caught and logged as warnings — never crash the server
+- **VACUUM threshold**: Only run SQLite VACUUM after >100 rows deleted (costly I/O)
+- **Auto-prune**: Logger store prunes on every 1000th `write()` call (counter-based, like dashboard-events.js)
+- **Recursion safety**: Logger `pruneOld()` uses `_pruning` flag to prevent auto-prune during explicit prune
+- **Server startup**: `src/server.js` calls all three retention mechanisms after `writePidFile()`, before `updateManager.start()`
+- **Config defaults**: `A2AConfig.getRetention()` merges partial config with defaults — never writes defaults to disk
+- **Token grace period**: Expired tokens are kept for 1 hour after expiry (in-flight call protection)
+
+## Test Runtime (A2A-66)
+
+`A2A_RUNTIME=test` provides a minimal runtime for CI and headless environments:
+- `runTurn()`: if `A2A_AGENT_COMMAND` env var is set, spawns it with `shell: true` and JSON payload on stdin; otherwise echoes the message
+- `summarize()`: returns canned `{ summary, ownerSummary }` — no LLM required
+- `notify()`: no-op (same as claude mode)
+- Non-zero exit from `A2A_AGENT_COMMAND` throws an error with stderr context
+- The CI smoke lane (`a2atesting/a2acalling/scenarios/smoke-lane.js`) uses this mode
+
+## In-Memory Map Eviction (A2A-69)
+
+For in-memory Maps that accumulate entries over time (e.g., `claudeSessions` in `runtime-adapter.js`), use the prune-on-access pattern:
+- TTL eviction: delete entries older than a configurable threshold (checked via `updatedAt` timestamp)
+- Max-entry eviction: delete oldest entries first when Map exceeds a configurable max size
+- Prune runs at the start of the next operation (not on a timer) — zero overhead when idle
+- Both thresholds configurable via environment variables
+- Refresh `updatedAt` on every access to prevent evicting active entries
+
+## Native App Sidecar Lifecycle (A2A-93, A2A-96)
+
+For native macOS server process management in `native/macos/src-tauri/src/server.rs`:
+- Start with sidecar first (`a2a-server` bundled binary), then fall back to external `a2a` only if sidecar fails
+- Track child process state in shared `SidecarState` and clear dead children on exit
+- Use exponential backoff for restart attempts and enforce a hard crash cap to avoid restart loops
+- Emit status/log events to the frontend for observability; do not silently retry in background
+- During shutdown, set explicit shutdown state to prevent unintended auto-restart
+
+## DMG Installer Polish (A2A-101)
+
+The macOS DMG installer uses Tauri's built-in DMG bundler with custom configuration:
+- Background images: `dmg-background.png` (600x400) and `@2x` retina variant (1200x800) in `native/macos/src-tauri/`
+- DMG config in `tauri.conf.json` under `bundle.macOS.dmg`: window size, app/Applications positions
+- Icon set: all standard sizes (32, 128, 256, 512, 512@2x) in `native/macos/src-tauri/icons/`
+- Do NOT use third-party DMG tools — Tauri's bundler handles everything
+- Background design uses dashboard dark theme colors (#0B0E14, #151B28, #3B82F6)
+
+## Anti-Patterns
+
+- Do NOT use `console.log` outside the logger sink in `src/lib/logger.js`
+- 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)