a2acalling 0.6.73 → 0.6.74

package/.a2a-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.6.73",
-  "installed_at": "2026-02-27T06:20:51.170Z",
+  "version": "0.6.74",
+  "installed_at": "2026-03-01T18:24:44.875Z",
   "files": [
     {
       "path": "CLAUDE.md",

package/ARCHITECTURE.md

@@ -7,14 +7,15 @@ A2A Calling enables agent-to-agent communication across OpenClaw instances. Agen
 ```
 ┌──────────────────────────────────────────────────────────────────┐
 │  CLI (bin/cli.js)                                                │
-│  Commands: create, list, revoke, call, contacts, conversations   │
+│  Commands: create/list/revoke/call + ops commands (quickstart, gui, update, app, skills) │
 └───────────┬──────────────────────────────────────────────────────┘
             │
 ┌───────────▼──────────────────────────────────────────────────────┐
 │  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)        │
+│  ├─ /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               │
 └───────────┬──────────────────────────────────────────────────────┘
             │
 ┌───────────▼──────────────────────────────────────────────────────┐
@@ -26,22 +27,24 @@ A2A Calling enables agent-to-agent communication across OpenClaw instances. Agen
 │  ├─ summarizer.js     Call summary generation                     │
 │  ├─ summary-prompt.js Unified summary prompt builder              │
 │  ├─ summary-formatter.js  Format summaries for display            │
-│  ├─ disclosure.js     Disclosure level enforcement                │
+│  ├─ 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 (standalone/OCW)   │
+│  ├─ 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                   │
 └──────────────────────────────────────────────────────────────────┘
@@ -50,8 +53,10 @@ A2A Calling enables agent-to-agent communication across OpenClaw instances. Agen
 ## 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`
+- **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`
 
@@ -72,20 +77,20 @@ Three tiers with escalating capabilities:
 - **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
+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 and logs
+- `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 `/dashboard/api/*` routes. Includes tabs: Contacts, Calls, Logs, Settings, Invites, Permissions, and Health (E2E test results).
+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
 
@@ -95,6 +100,14 @@ Tauri v2 app at `native/macos/` wrapping the dashboard SPA. Provides native menu
 
 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:
@@ -104,8 +117,8 @@ Zero-dependency test runner at `test/run.js` with custom assert API. Three test
 
 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.
+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.
+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/CONVENTIONS.md

@@ -2,7 +2,7 @@
 
 ## Logging
 
-Use the structured logger from `src/lib/logger.js`. Never use bare `console.log`.
+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');
@@ -46,7 +46,7 @@ Do NOT add new npm dependencies without explicit justification. Use Node.js buil
 
 ## 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.
+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
 
@@ -61,10 +61,10 @@ All modules use CommonJS (`require`/`module.exports`). Each lib file exports a f
 
 - Single-page app in `src/dashboard/public/`
 - Uses Shoelace web components (`<sl-*>` elements)
-- Communicates via fetch to `/dashboard/api/*` endpoints
+- 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 tab switching (Contacts, Calls, Invites, Logs, Settings, Permissions, Health)
+- 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)
 
@@ -105,7 +105,13 @@ close() {
 
 ## 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`.
+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)
 
@@ -126,9 +132,27 @@ All data stores implement retention cleanup following the `dashboard-events.js`
 - **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
+
 ## Anti-Patterns
 
-- Do NOT use `console.log` — use the structured logger
+- 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

package/biome.json

@@ -0,0 +1,27 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": ["src/**/*.js"]
+	},
+	"formatter": {
+		"enabled": false
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"correctness": {
+				"noUnusedVariables": "warn"
+			}
+		}
+	},
+	"assist": {
+		"enabled": false
+	}
+}

package/docs/assessments/2026-02-27-google-a2a-protocol-assessment.md

@@ -0,0 +1,292 @@
+# Google A2A Protocol — Adoption & Adaptation Assessment
+
+**Ticket:** A2A-75
+**Date:** 2026-02-27
+**Status:** Assessment Complete
+
+---
+
+## 1. Executive Summary
+
+The Google A2A Protocol (a2a-protocol.org) is an open standard for agent-to-agent communication built on JSON-RPC 2.0 with HTTP, gRPC, and SSE bindings. It shares significant conceptual overlap with our A2A Calling protocol — both solve the same fundamental problem of enabling opaque agents to communicate. However, the two protocols diverge substantially in philosophy: Google's spec is enterprise-grade infrastructure (task-oriented, schema-heavy, multi-transport), while ours is relationship-oriented (token-scoped, disclosure-aware, conversation-first).
+
+**Recommendation:** Adopt Google A2A as the wire protocol and discovery layer while preserving our permission tiers, disclosure levels, conversation model, and "first meeting" workflow as an extension layer on top. This gives us interoperability with the emerging ecosystem without losing the social trust features that define our product.
+
+---
+
+## 2. Protocol Comparison
+
+### 2.1 Core Concepts Mapping
+
+| Our Concept | Google A2A Equivalent | Gap Analysis |
+|---|---|---|
+| Token (`fed_xxx`) | SecurityScheme (apiKey / OAuth2 / bearer) | Google is more flexible — supports OAuth2 flows. Our tokens are simpler (bearer only) but richer (tier, disclosure, topics, max_calls). |
+| `POST /invoke` | `a2a.SendMessage` | Direct mapping. Google returns Task or Message; we return response text + `can_continue`. |
+| `conversation_id` | `contextId` | Same concept — group related interactions. Google also has `taskId` for individual work units within a context. |
+| Multi-turn conversation | `input-required` task state | Google models this as task state machine; we model it as conversation continuation with `can_continue`. |
+| `POST /end` | Task reaches terminal state (`completed`/`canceled`) | Google has richer terminal states (failed, rejected, canceled). We have `concluded`/`timeout`. |
+| Permission tiers (public/friends/family) | Agent Card `skills` + OAuth scopes | **No equivalent.** Google has no concept of relationship-based capability gating. This is our key differentiator. |
+| Disclosure levels (public/minimal/none) | **No equivalent** | Google assumes agents share freely. No information-sharing policy model. |
+| `GET /status` | `GET /.well-known/a2a-agent-card` | Google's Agent Card is far richer — declares skills, auth requirements, capabilities, provider info. Our `/status` is minimal. |
+| Token `allowed_topics` | AgentSkill `inputSchema` | Loose mapping. Google uses JSON Schema for skill inputs; we use topic strings. |
+| Owner notifications | Push Notifications (webhooks) | Google's push notifications are for task updates to the *caller*, not owner awareness. Our notifications inform the *agent owner* about incoming calls. |
+| Ed25519 signatures | AgentCardSignature + TLS mutual auth | Google supports card signing. We have per-message Ed25519 signing. |
+| Rate limits (per-token) | API Management layer | Google delegates to infrastructure; we enforce per-token in-app. |
+| Caller context (`caller.name`, `caller.instance`) | Message `role` + metadata | Google messages don't carry caller identity — that's at the transport layer. |
+
+### 2.2 What Google A2A Has That We Don't
+
+1. **Agent Card / Discovery** — `/.well-known/a2a-agent-card` for automated agent discovery. Declares skills, capabilities, auth requirements. We have nothing comparable.
+2. **Task State Machine** — Seven states (`working`, `completed`, `failed`, `canceled`, `rejected`, `input-required`, `auth-required`) vs. our two (`active`, `concluded`/`timeout`).
+3. **Artifacts** — Structured output objects with MIME types, separate from conversational messages. We only have text responses.
+4. **Streaming** — SSE-based streaming for real-time task updates. We're request/response only.
+5. **gRPC Binding** — For high-performance inter-service communication.
+6. **Extension System** — Versioned, URI-identified extensions for capability expansion.
+7. **OpenTelemetry** — W3C Trace Context propagation for distributed tracing.
+
+### 2.3 What We Have That Google A2A Doesn't
+
+1. **Permission Tiers** — public/friends/family capability gating based on relationship trust level. This is our core value proposition.
+2. **Disclosure Levels** — public/minimal/none information-sharing policy. Controls *how much* the agent reveals, not just *what* it can do.
+3. **Owner Notifications** — Real-time alerts to the human owner when their agent is called. Google has no concept of human-in-the-loop awareness.
+4. **"First Meeting" Workflow** — Our conversation model is designed for agents meeting for the first time — exploratory, collaborative, with progressive trust building. Google's model is transactional.
+5. **Topic/Goal Scoping** — Per-token `allowed_topics` and `allowed_goals` constrain what a caller can discuss. Google has skill-level access but no per-session topic constraints.
+6. **Token Economics** — `max_calls`, `calls_made`, expiration, revocation — rate-limited trust delegation. Google delegates this to infrastructure.
+7. **Conversation Driver** — Multi-turn orchestration with min/max turns, idle timeout, auto-conclusion, and summary generation. Google leaves conversation management to the implementation.
+8. **Contact Book** — Persistent directory of known agents with metadata, linked tokens, and ping status.
+
+---
+
+## 3. Adoption Strategy
+
+### 3.1 Approach: "Google Wire, OpenClaw Soul"
+
+Adopt the Google A2A wire protocol (JSON-RPC 2.0, Agent Card, Task model) as the transport layer while preserving our permission, disclosure, and conversation semantics as an extension layer.
+
+```
+┌─────────────────────────────────────────────────┐
+│  OpenClaw Extension Layer                        │
+│  ├─ Permission tiers (public/friends/family)     │
+│  ├─ Disclosure levels (public/minimal/none)      │
+│  ├─ Owner notifications                          │
+│  ├─ Token economics (max_calls, expiry)          │
+│  ├─ "First meeting" conversation driver          │
+│  └─ Contact book + trust history                 │
+├─────────────────────────────────────────────────┤
+│  Google A2A Protocol (Wire Format)               │
+│  ├─ Agent Card (/.well-known/a2a-agent-card)     │
+│  ├─ JSON-RPC 2.0 (a2a.SendMessage, etc.)        │
+│  ├─ Task state machine                           │
+│  ├─ Artifacts + Parts                            │
+│  └─ Streaming (SSE)                              │
+├─────────────────────────────────────────────────┤
+│  Transport (HTTPS + optional gRPC)               │
+└─────────────────────────────────────────────────┘
+```
+
+### 3.2 Phase Plan
+
+#### Phase 1: Agent Card (Discovery Layer)
+
+Serve a Google A2A-compatible Agent Card at `/.well-known/a2a-agent-card`. This is the lowest-cost, highest-value adoption step — it makes our agents discoverable by any A2A-compatible system.
+
+**Agent Card contents:**
+- `name`, `description`, `provider` — from `a2a-config.json`
+- `skills` — derived from our disclosure manifest topics
+- `securitySchemes` — declare bearer token auth (our existing `fed_xxx` tokens)
+- `capabilities` — `streaming: false`, `pushNotifications: false` initially
+- `extensions` — declare our custom extension for permission tiers and disclosure
+
+**OpenClaw Extension in Agent Card:**
+```json
+{
+  "extensions": [
+    {
+      "uri": "https://openclaw.dev/a2a/extensions/trust-tiers",
+      "version": "1.0.0",
+      "required": false,
+      "data": {
+        "tiers": ["public", "friends", "family"],
+        "disclosure_levels": ["public", "minimal", "none"],
+        "owner_notifications": true,
+        "contact_book": true
+      }
+    }
+  ]
+}
+```
+
+#### Phase 2: Dual-Protocol Inbound
+
+Accept both our current `POST /api/a2a/invoke` format AND the Google A2A `a2a.SendMessage` JSON-RPC format on a new `POST /api/a2a/rpc` endpoint.
+
+**Mapping:**
+- Google `a2a.SendMessage` → our `invoke` handler
+- Google `contextId` → our `conversation_id`
+- Google `input-required` → our `can_continue: true`
+- Google `completed` → our conversation conclusion
+- Message `parts[].text` → our `message` string
+- Task `artifacts` → (new) structured response attachments
+
+**Token auth unchanged:** Google callers still need a valid `fed_xxx` bearer token. The token's tier and disclosure settings apply regardless of wire format.
+
+#### Phase 3: Dual-Protocol Outbound
+
+Update `A2AClient` to detect whether a remote agent serves a Google A2A Agent Card. If so, use `a2a.SendMessage` JSON-RPC format; otherwise, fall back to our current `POST /invoke`.
+
+**Detection:**
+1. `GET /.well-known/a2a-agent-card` — if 200 with valid card, use Google format
+2. `GET /api/a2a/status` — if 200 with `"a2a": true`, use our format
+3. Fall back to our format as default
+
+#### Phase 4: Task State Machine
+
+Adopt the Google task state machine internally, mapping to our conversation states:
+
+| Google Task State | Our Current State | Migration |
+|---|---|---|
+| `working` | `active` | Direct mapping |
+| `completed` | `concluded` | Direct mapping |
+| `failed` | (new) | Add `failed` status to conversations |
+| `canceled` | (new) | Add `canceled` status |
+| `rejected` | (implicit — 403 response) | Formalize as conversation state |
+| `input-required` | `active` + `can_continue: true` | Already modeled, just need state label |
+| `auth-required` | (new) | Add for re-auth scenarios |
+
+#### Phase 5: Streaming & Artifacts
+
+Add SSE streaming support for long-running responses and artifact support for structured outputs. This is the most complex phase and can be deferred until there's ecosystem demand.
+
+---
+
+## 4. Preserving Our Differentiators
+
+### 4.1 Permission Tiers as Extension
+
+Google A2A has no concept of relationship-based trust. Our tiers are modeled as an extension that enriches the standard auth flow:
+
+1. Standard Google A2A: client authenticates → agent processes request
+2. Our extension: client authenticates → **token tier determines capabilities** → **disclosure level constrains responses** → agent processes within scope
+
+This is transparent to Google-only callers — they authenticate normally and get `public` tier behavior by default. Callers that understand our extension can negotiate higher trust levels.
+
+### 4.2 "First Meeting" Conversation Model
+
+Google A2A's `a2a.SendMessage` is transactional — send a message, get a response. Our "first meeting" model is exploratory:
+
+1. Agents introduce themselves (caller context)
+2. Progressive topic exploration within allowed bounds
+3. Collaborative discovery of shared interests
+4. Trust building over multiple turns
+5. Summary generation at conclusion
+
+This maps cleanly onto Google's `contextId` + `input-required` pattern. The conversation driver orchestrates the multi-turn flow while the wire format is standard A2A.
+
+### 4.3 Owner Awareness
+
+Google A2A has push notifications for the *caller* to track task progress. We add owner notifications — the *callee's human* is informed about incoming calls. This is orthogonal to the protocol and requires no wire format changes. It remains a server-side feature.
+
+### 4.4 Contact Book & Trust History
+
+The contact book (persistent directory of known agents) is a local-only feature with no wire format implications. We can enhance it with Agent Card data — when we discover a remote agent's card, we can auto-populate contact metadata.
+
+---
+
+## 5. Migration Risks
+
+### 5.1 Low Risk
+- **Agent Card adoption** — additive, no breaking changes
+- **Dual-protocol inbound** — new endpoint, existing endpoint unchanged
+- **Contact book enrichment** — local-only enhancement
+
+### 5.2 Medium Risk
+- **Outbound protocol detection** — need robust fallback when remote agents serve partial or malformed Agent Cards
+- **Task state machine migration** — our conversation store schema needs new states; existing conversations need migration
+- **Response format change** — moving from flat `{ response: "..." }` to `{ parts: [...], artifacts: [...] }` requires dashboard and CLI updates
+
+### 5.3 High Risk
+- **Streaming** — fundamentally changes the response model from request/response to event stream. Requires significant changes to the conversation driver, dashboard, and CLI.
+- **gRPC binding** — would add a substantial dependency. Recommend deferring unless ecosystem demand materializes.
+
+---
+
+## 6. Specification: OpenClaw Trust Tiers Extension
+
+### 6.1 Extension URI
+
+`https://openclaw.dev/a2a/extensions/trust-tiers`
+
+### 6.2 Extension Data in Agent Card
+
+```json
+{
+  "uri": "https://openclaw.dev/a2a/extensions/trust-tiers",
+  "version": "1.0.0",
+  "required": false,
+  "data": {
+    "tiers": ["public", "friends", "family"],
+    "default_tier": "public",
+    "disclosure_levels": ["public", "minimal", "none"],
+    "default_disclosure": "minimal",
+    "supports_topics": true,
+    "supports_goals": true,
+    "owner_notifications": true,
+    "max_calls_enforced": true
+  }
+}
+```
+
+### 6.3 Extension Headers
+
+Callers that understand the extension can include:
+
+```
+X-OpenClaw-Tier-Request: friends
+X-OpenClaw-Disclosure-Preference: public
+X-OpenClaw-Caller-Context: {"name": "Alice", "instance": "alice.example.com", "reason": "Collaboration request"}
+```
+
+The server validates these against the token's actual tier — a `public` token cannot request `friends` tier access.
+
+### 6.4 Extension Response Metadata
+
+```json
+{
+  "metadata": {
+    "openclaw:tier": "friends",
+    "openclaw:disclosure": "minimal",
+    "openclaw:topics_allowed": ["chat", "search"],
+    "openclaw:calls_remaining": 95,
+    "openclaw:token_expires": "2026-03-06T17:54:00Z"
+  }
+}
+```
+
+---
+
+## 7. Implementation Priority
+
+| Priority | Item | Effort | Value |
+|---|---|---|---|
+| **P0** | Agent Card at `/.well-known/a2a-agent-card` | Small | High — instant ecosystem visibility |
+| **P1** | Dual-protocol inbound (`POST /api/a2a/rpc`) | Medium | High — accept calls from any A2A agent |
+| **P2** | Outbound protocol detection + Google format | Medium | Medium — call any A2A agent |
+| **P3** | Task state machine adoption | Medium | Medium — richer conversation lifecycle |
+| **P4** | Trust Tiers extension spec (formal) | Small | Medium — standardize our differentiator |
+| **P5** | Streaming support (SSE) | Large | Low — defer until ecosystem demand |
+| **P6** | Artifact support | Medium | Low — our use case is conversational |
+| **P7** | gRPC binding | Large | Low — defer indefinitely |
+
+---
+
+## 8. Conclusion
+
+The Google A2A Protocol and our A2A Calling protocol are complementary, not competing. Google provides the infrastructure layer (discovery, wire format, task management, enterprise features) while we provide the social layer (trust tiers, disclosure, owner awareness, relationship management).
+
+By adopting Google A2A as the wire protocol and extending it with our trust model, we get:
+- **Interoperability** with the broader A2A ecosystem (any Google A2A-compatible agent can call us)
+- **Preservation** of our unique features (permission tiers, disclosure, first-meeting workflow)
+- **Credibility** from aligning with an industry standard
+- **Future-proofing** as the ecosystem grows (streaming, artifacts, gRPC — all available when needed)
+
+The key architectural principle: **Google A2A is the envelope; OpenClaw is the letter inside.**