a2acalling 0.6.75 → 0.6.76

package/.claude/worktrees/agent-ad420869/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
+
+## Native App Onboarding Wizard (A2A-99)
+
+The Tauri app includes a first-run onboarding wizard at `/dashboard/onboarding.html`:
+- Routes: GET `/api/onboarding/status`, POST `/api/onboarding/complete`, GET `/api/onboarding/available-port`
+- Discovery module (`discovery.rs`) checks onboarding state and routes new users to wizard
+- Wizard collects: port preference, hostname, disclosure topics
+- On completion, saves config and redirects to main dashboard
+- Wizard files: `onboarding.html`, `onboarding.css`, `onboarding.js` in `src/dashboard/public/`
+
+## 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)

package/.claude/worktrees/agent-ad420869/README.md

@@ -0,0 +1,470 @@
+# 🤝 A2A Calling
+
+**Agent-to-Agent calling with OpenClaw support. "I'll have my people call your people!"**
+
+[![npm version](https://img.shields.io/npm/v/a2acalling.svg)](https://www.npmjs.com/package/a2acalling)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+Your AI agent can now call other AI agents — across instances, with scoped permissions, strategic summaries, and owner notifications. Think of it as a comms stream system for agents to communicate via text as effeciently as possible.
+
+## ✨ Features
+
+- 🔐 **Tiered permissions** — public / friends / family
+- 📇 **Contact management** — save agents, track trust, link permissions
+- 🧠 **Strategic summaries** — track what you got vs. gave, find mutual wins
+- 🔔 **Owner notifications** — know when your agent gets called
+- ⏱️ **Flexible tokens** — expiring or permanent, call limits optional
+- 🚦 **Rate limiting** — 10/min, 100/hr, 1000/day built-in
+- 🔄 **Multi-turn conversations** — continue threads across calls
+- 🧭 **Adaptive collaboration mode** — dynamic phase changes based on overlap and depth
+- 🗂️ **Minimal dashboard** — contacts, calls, tier settings, and invite generation
+- 💾 **Conversation history** — SQLite storage with context retrieval
+- 🧾 **Traceable logs** — DB-backed structured logs with `trace_id`, `error_code`, and hints
+
+## 🚀 Quick Start
+
+### Create an invite for others to call your agent
+
+```bash
+a2a create --name "My Agent" --owner "Your Name" --permissions friends
+
+# Output:
+# 🤝 Your Name is inviting you to connect agents!
+# Your agent can reach My Agent for: chat, web, files
+# a2a://your-host.com/fed_abc123xyz
+```
+
+### Call someone else's agent
+
+```bash
+# Add them as a contact
+a2a add "a2a://their-host.com/fed_xyz789" "Alice's Agent"
+
+# Make a call
+a2a call "Alice's Agent" "Hey! Want to collaborate on the a2a protocol?"
+
+# Or call directly
+a2a call "a2a://their-host.com/fed_xyz789" "Hello!"
+```
+
+## 🖥️ Native macOS App
+
+A2A Callbook is also available as a native macOS app that wraps the dashboard in a proper macOS window with native integrations.
+
+**Features:**
+- Native macOS notifications for incoming calls
+- Keyboard shortcuts: Cmd+1–5 for tab switching, Cmd+R to refresh
+- Menu bar tray icon with server status
+- Deep link support (`a2a://` URLs open in the app)
+- Cmd+W hides the window (stays in tray), Cmd+Q quits
+
+**Auto-installed** on macOS when you run `npm install -g a2acalling`. The app is placed in `~/Applications/`.
+
+**Manual install:** Download the `.dmg` from [GitHub Releases](https://github.com/onthegonow/a2a_calling/releases).
+
+**Build from source:**
+
+```bash
+# Requires Rust: https://rustup.rs
+cargo install tauri-cli --version "^2"
+cd native/macos/src-tauri
+cargo tauri build --target universal-apple-darwin
+```
+
+To open the app via CLI: `a2a gui` (prefers native app; use `--browser` to force browser).
+
+## 📦 Installation
+
+```bash
+# Global CLI
+npm install -g a2acalling
+
+# As a library
+npm install a2acalling
+```
+
+### Uninstall
+
+```bash
+# Stop pm2 server (name: a2a) and remove local config/DB (prompts unless --force)
+a2a uninstall
+
+# Keep config/DB for reinstall
+a2a uninstall --keep-config --force
+
+# Remove the global package
+npm uninstall -g a2acalling
+```
+
+### Setup (Auto-Detect Runtime)
+
+```bash
+# Auto setup (detects OpenClaw gateway/runtime or configures standalone mode)
+npx a2acalling setup
+
+# Or clone and install
+git clone https://github.com/onthegonow/a2a_calling.git
+cd a2a_calling
+npm install
+node scripts/install-openclaw.js setup
+```
+
+Setup behavior:
+- Runtime auto-detects OpenClaw when available and falls back to generic mode if unavailable.
+- If OpenClaw gateway is detected, dashboard is exposed on gateway at `/a2a` and A2A API at `/api/a2a/*` (proxied to A2A backend).
+- If OpenClaw is not detected, setup bootstraps standalone config + bridge templates and serves dashboard at `/dashboard`.
+- Setup inspects port 80 and prints reverse proxy guidance for stable internet-facing ingress.
+- Setup prints the exact dashboard URL at the end.
+
+Before the first `a2a call`, the owner must complete onboarding (install location, permission tiers, and server ingress verification). Run:
+
+```bash
+/a2a quickstart
+```
+
+CLI equivalents:
+
+```bash
+# Local machine (local-only invites)
+a2a quickstart --port 3001
+
+# Server / public hostname (recommended: terminate at 443 via reverse proxy)
+a2a quickstart --hostname YOUR_DOMAIN:443 --port 3001
+```
+
+## 🎯 Permission Tiers
+
+| Tier | What They Can Access |
+|------|---------------------|
+| `public` | Conversation only |
+| `friends` | Most read-only tools (calendar/email/search) |
+| `family` | Full tool access (careful!) |
+
+Customize tiers in `~/.config/openclaw/a2a-config.json`:
+
+```json
+{
+  "tiers": {
+    "friends": {
+      "topics": ["chat", "web", "files", "calendar"],
+      "allowed_tools": ["Bash(readonly)", "Read", "Grep", "Glob", "WebSearch", "WebFetch"],
+      "disclosure": "minimal"
+    }
+  }
+}
+```
+
+## 📇 Contact Management
+
+```bash
+# Add a contact
+a2a add "a2a://host/token" "Alice"
+
+# View contact details (shows trust level from YOUR token to them)
+a2a show "Alice"
+
+# Ping to check availability
+a2a ping "Alice"
+
+# Link a token you created FOR them
+a2a link "Alice" tok_abc123
+
+# List all contacts
+a2a contacts
+
+# Remove a contact
+a2a rm "Alice"
+```
+
+## 🧠 Strategic Summaries
+
+Every call generates an owner-context summary that tracks the exchange:
+
+```json
+{
+  "exchange": {
+    "weGot": ["learned about their developer tools project"],
+    "weGave": ["shared our A2A work"],
+    "balance": "even",
+    "fair": true
+  },
+  "mutualValue": {
+    "found": true,
+    "opportunities": ["potential integration partnership"],
+    "alignment": "connects to owner's interest in agent collaboration"
+  },
+  "trust": {
+    "assessment": "appropriate",
+    "recommendation": "maintain",
+    "pattern": "genuine partner, collaborative tone"
+  }
+}
+```
+
+Summaries are **private** — never shared with the caller.
+
+## 🔧 CLI Reference
+
+### Token Management
+
+```bash
+a2a create [options]          # Create an invite token
+  --name, -n <name>           # Token/contact name
+  --owner, -o <name>          # Your name (for invite)
+  --tier, -t <tier>           # public|friends|family
+  --topics <list>             # Custom topic list
+  --expires, -e <duration>    # 1h|1d|7d|30d|never (default: never)
+  --max-calls <n>             # Limit total calls (default: unlimited)
+  --notify <level>            # all|summary|none
+
+a2a list                      # List your tokens
+a2a revoke <id>               # Revoke a token
+a2a quickstart                # Deterministic onboarding
+```
+
+### Calling
+
+```bash
+a2a call <target> <message>   # Call an agent
+  --timeout <seconds>         # Response timeout (default: 60)
+  --context <text>            # Add context for the call
+
+a2a ping <target>             # Check if agent is available
+```
+
+### Server
+
+```bash
+a2a server [options]          # Start A2A server
+  --port, -p <port>           # Port (default: 3001)
+a2a setup                     # Auto setup via installer (gateway-aware dashboard)
+```
+
+Dashboard paths:
+- Standalone A2A server: `http://<host>:<port>/dashboard`
+- OpenClaw gateway mode: `http://<gateway>/a2a`
+
+### Remote Callbook (Mac / Remote Browser)
+
+If the owner wants to manage A2A from a different machine (ex: their MacBook), you can pair a browser session using a one-time install link:
+
+1. Open the dashboard on the server (local): `http://127.0.0.1:<port>/dashboard/`
+2. Go to `Settings` -> `Remote Callbook`
+3. Click `Create Install Link (24h)` and copy the URL
+4. Open that link on the Mac. It exchanges the code for a long-lived session cookie and then redirects to the dashboard.
+
+Notes:
+- The install link expires after 24 hours and is one-time use.
+- The session cookie is long-lived (effectively "never expires") until you revoke that device in `Settings` -> `Remote Callbook`.
+- Callbook session storage DB: `~/.config/openclaw/a2a-callbook.db` (or `$A2A_CONFIG_DIR/a2a-callbook.db`).
+
+### Traceability and Logs
+
+All runtime logs are persisted in SQLite and also emitted to stdout:
+
+- Log DB: `~/.config/openclaw/a2a-logs.db` (or `$A2A_CONFIG_DIR/a2a-logs.db`)
+- Trace fields: `trace_id`, `conversation_id`, `token_id`, `error_code`, `status_code`, `hint`
+
+Dashboard/API log routes:
+
+- `GET /api/a2a/dashboard/logs`
+- `GET /api/a2a/dashboard/logs/trace/:traceId`
+- `GET /api/a2a/dashboard/logs/stats`
+- `GET /api/a2a/dashboard/debug/call?trace_id=<id>` (or `conversation_id=<id>`)
+
+Useful filters for `/api/a2a/dashboard/logs`:
+
+- `trace_id`, `conversation_id`, `token_id`
+- `error_code`, `status_code`
+- `component`, `event`, `level`, `search`, `from`, `to`, `limit`
+
+Example:
+
+```bash
+curl "http://localhost:3001/api/a2a/dashboard/logs?trace_id=trace_abc123&error_code=TOKEN_INVALID_OR_EXPIRED"
+```
+
+### Incoming Call Debug
+
+Every `/api/a2a/invoke` and `/api/a2a/end` response now returns:
+- `trace_id` (generated when caller does not send one)
+- `request_id` (generated when caller does not send one)
+
+To inspect one call, use the dashboard debug endpoint:
+
+```bash
+curl -H "x-admin-token: $A2A_ADMIN_TOKEN" \
+  "http://localhost:3001/api/a2a/dashboard/debug/call?trace_id=<trace_id>"
+```
+
+For each call you get:
+- `summary` (event count, first/last seen, duration, and IDs involved)
+- `errors` and `error_codes` for fast triage
+- `logs` (ordered timeline events from that trace)
+
+## 📡 Protocol
+
+Tokens use the `a2a://` URI scheme:
+
+```
+a2a://<hostname>[:port]/<token>
+```
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/a2a/status` | Check A2A support |
+| `GET` | `/api/a2a/ping` | Health check with auth |
+| `POST` | `/api/a2a/invoke` | Call the agent |
+| `POST` | `/api/a2a/end` | End a conversation and return summary data |
+
+### Invoke Request
+
+```json
+{
+  "message": "Hello!",
+  "caller": { "name": "Agent Name", "owner": "Owner Name" },
+  "conversation_id": "optional-for-continuation",
+  "timeout_seconds": 60
+}
+```
+
+### Invoke Response
+
+```json
+{
+  "success": true,
+  "conversation_id": "conv_123",
+  "response": "Agent's response",
+  "can_continue": true,
+  "tokens_remaining": null
+}
+```
+
+### End Conversation Request
+
+```json
+{
+  "conversation_id": "conv_123"
+}
+```
+
+### End Conversation Response
+
+```json
+{
+  "success": true,
+  "conversation_id": "conv_123",
+  "status": "concluded",
+  "summary": "Optional call summary"
+}
+```
+
+## 🔌 Library Usage
+
+### Making Calls (Client)
+
+```javascript
+const { A2AClient } = require('a2acalling');
+
+const client = new A2AClient({
+  caller: { name: 'My Agent', owner: 'My Name' }
+});
+
+// Call via invite URL
+const response = await client.call(
+  'a2a://their-host.com/fed_token123',
+  'Can you help me with something?'
+);
+
+// Continue the conversation
+const followUp = await client.call(
+  'a2a://their-host.com/fed_token123',
+  'Thanks! One more question...',
+  { conversationId: response.conversation_id }
+);
+
+// Explicitly end the call when done
+const ended = await client.end(
+  'a2a://their-host.com/fed_token123',
+  response.conversation_id
+);
+```
+
+### Receiving Calls (Server)
+
+```javascript
+const { createRoutes, TokenStore } = require('a2acalling');
+const express = require('express');
+
+const app = express();
+app.use(express.json());
+
+app.use('/api/a2a', createRoutes({
+  tokenStore: new TokenStore(),
+  
+  async handleMessage(message, context) {
+    // context.permissions, context.caller, context.conversationId
+    return {
+      text: await yourAgent.respond(message, context),
+      canContinue: true
+    };
+  },
+  
+  async notifyOwner({ caller, message }) {
+    await notify(`🤝 ${caller.name} called your agent`);
+  }
+}));
+
+app.listen(3001);
+```
+
+## 🛡️ Security
+
+- **Rate limiting**: 10 calls/min, 100/hr, 1000/day per token
+- **Timeout bounds**: 5-300 seconds
+- **Token scoping**: Permissions baked in at creation
+- **Revocation**: Instant via `a2a revoke`
+
+## 🌍 Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `A2A_HOSTNAME` | Hostname for invite URLs (required for internet-facing invites) |
+| `A2A_PORT` | Server port (default: 3001) |
+| `A2A_CONFIG_DIR` | Config directory (default: `~/.config/openclaw`) |
+| `A2A_WORKSPACE` | Workspace root for context files like `USER.md` (default: current directory) |
+| `A2A_RUNTIME` | Runtime mode: `auto` (default), `openclaw`, or `claude` |
+| `A2A_AGENT_NAME` | Override local agent display name |
+| `A2A_OWNER_NAME` | Override owner display name |
+| `A2A_COLLAB_MODE` | Conversation style: `adaptive` (default) or `deep_dive` |
+| `A2A_ADMIN_TOKEN` | Protect dashboard/conversation admin routes for non-local access |
+| `A2A_LOG_LEVEL` | Minimum persisted/stdout log level: `trace`, `debug`, `info`, `warn`, `error` (default: `info`) |
+| `A2A_LOG_STACKS` | Include stack traces in log DB error payloads (`true` by default outside production) |
+
+## 🤝 Philosophy
+
+A2A is **cooperative AND adversarial**. Each agent maximizes value for their owner — but the best outcomes are mutual wins.
+
+Your agent should:
+1. **Protect your interests** — track what you're giving vs. getting
+2. **Find mutual value** — look for wins on both sides
+3. **Build relationships** — trust is earned over time
+4. **Stay strategic** — not every caller is a friend
+
+## 📚 Links
+
+- [OpenClaw](https://github.com/openclaw/openclaw) — The AI agent framework
+- [Protocol Spec](docs/protocol.md) — Full protocol documentation
+- [Discord](https://discord.gg/clawd) — Community chat
+
+## 📄 License
+
+MIT — go build something cool.
+
+---
+
+*I'll have my people call your people.* 🤝