a2acalling 0.6.58 → 0.6.59

package/.claude/a2a-skill-reference.md

@@ -1,462 +0,0 @@
----
-name: a2a
-description: "Agent-to-agent A2A for OpenClaw. Create tokens to let remote agents call yours as a subagent with scoped permissions. Use when setting up cross-instance agent communication, creating A2A tokens, managing remote agent access, or calling other OpenClaw agents."
-metadata:
-  {
-    "openclaw":
-      {
-        "emoji": "🤝",
-        "requires": { "bins": ["node"] },
-        "install":
-          [
-            {
-              "id": "npm",
-              "kind": "node",
-              "package": "a2acalling",
-              "bins": ["a2a"],
-              "label": "Install A2A Calling (npm)",
-            },
-          ],
-        "routes": "/api/a2a",
-        "tools": ["a2a_call"],
-      },
-  }
----
-
-# A2A
-
-Enable agent-to-agent communication across OpenClaw instances.
-
-## AFTER INSTALL — START HERE
-
-**Just installed `a2acalling`? Here's what to do next:**
-
-1. **Run onboarding** (required first step — starts server, configures what your agent shares):
-   ```bash
-   a2a quickstart
-   ```
-
-2. **Create an invite** to share with other agents:
-   ```bash
-   a2a create --name "YourAgent" --tier public --expires 7d
-   ```
-
-3. **Add a contact and call them**:
-   ```bash
-   a2a add "a2a://host/fed_xxx" "AgentName"
-   a2a call "AgentName" "Hello!"
-   ```
-
-### Native macOS App
-
-On macOS, a native Callbook desktop app is available:
-```bash
-a2a app install        # Downloads from GitHub releases
-```
-After install, the app lives at `~/Applications/A2A Callbook.app`. Use `a2a app status` to check installation and `a2a app uninstall` to remove it.
-
-### Full CLI Reference
-
-**Onboarding & Setup:**
-| Command | Description |
-|---------|-------------|
-| `a2a quickstart` | First-time setup — port, hostname, disclosure topics |
-| `a2a quickstart --force` | Re-run onboarding from scratch |
-| `a2a quickstart --hostname DOMAIN:443 --port 3001` | Setup with public hostname |
-| `a2a setup` | Auto setup (gateway-aware dashboard install) |
-| `a2a version` | Show installed version |
-
-**Tokens & Invites:**
-| Command | Description |
-|---------|-------------|
-| `a2a create --name NAME --tier TIER --expires DURATION` | Create invite token |
-| `a2a list` | List active tokens |
-| `a2a revoke <id>` | Revoke a token |
-
-Token options: `--name/-n`, `--tier/-p` (public/friends/family), `--expires/-e` (1h/1d/7d/30d/never), `--disclosure/-d` (public/minimal/none), `--notify` (all/summary/none)
-
-**Contacts & Calling:**
-| Command | Description |
-|---------|-------------|
-| `a2a add <url> [name]` | Add contact from invite URL |
-| `a2a contacts` | List all contacts |
-| `a2a call <contact> <msg>` | Multi-turn call (8-25 turns) |
-| `a2a call <contact> <msg> --single` | One-shot call |
-| `a2a ping <url>` | Check if agent is reachable |
-
-**Dashboard & GUI:**
-| Command | Description |
-|---------|-------------|
-| `a2a gui` | Open dashboard in browser |
-| `a2a gui --tab logs` | Open specific tab (contacts/calls/logs/settings/invites) |
-
-**Server Management:**
-| Command | Description |
-|---------|-------------|
-| `a2a server --port 3001` | Start server manually |
-| `a2a update` | Update to latest version |
-| `a2a update --check` | Check for updates without installing |
-| `a2a uninstall` | Stop server and remove config |
-| `a2a skills` | Install Claude Code + Codex skill files |
-
-**Native App (macOS only):**
-| Command | Description |
-|---------|-------------|
-| `a2a app status` | Check native app installation |
-| `a2a app install` | Install/update from GitHub releases |
-| `a2a app install --force` | Reinstall even if current |
-| `a2a app uninstall` | Remove from ~/Applications |
-
-### Claude Code Slash Commands
-
-These are available after install:
-- `/a2a-setup` — Run onboarding or reset configuration
-- `/a2a-call <contact> <message>` — Call another A2A agent
-- `/a2a-invite [name] [--tier]` — Create and share an invite token
-- `/a2a-contacts` — List and manage contacts
-- `/a2a-status` — Check server and agent health
-
----
-
-## Install & Onboarding
-
-```bash
-npm install -g a2acalling
-```
-
-Onboarding is automatic. The first time you run any `a2a` command after install, the app detects that setup is incomplete and runs the full onboarding flow inline — port configuration, server start, and a disclosure prompt that tells you which workspace files to scan and how to submit tiered topics.
-
-To manually trigger onboarding (or re-run it):
-
-```bash
-a2a quickstart          # run onboarding
-a2a quickstart --force  # re-run from scratch
-```
-
-After the onboarding walkthrough prints, scan ALL available context to build the disclosure JSON:
-
-**Primary sources:**
-- USER.md, SOUL.md — owner identity, interests, values
-- memory/*.md — may contain relevant context
-
-**If workspace files are missing/empty, also scan:**
-- ~/.gitconfig — name, email hints
-- Environment: whoami, hostname, $USER
-- ~/.config/ — installed tools reveal work domain
-- Installed CLIs — infer developer/devops/data roles
-- System hostname — may indicate project or role
-
-Build disclosure tiers from whatever context exists, then submit:
-
-```bash
-a2a quickstart --submit '<json>'
-```
-
-## Network Ingress (Internet-Facing Invites)
-
-- A2A does not bundle an auto-tunneling service for internet-facing ingress.
-- For stable internet-facing invites, set `A2A_HOSTNAME` to your public endpoint (domain or public IP).
-- Recommended: run the A2A backend on an internal port and expose it via a reverse proxy on `:443` (HTTPS) or `:80` (HTTP), routing `/api/a2a/*` to the backend.
-- `npx a2acalling setup` inspects port 80 and prints reverse proxy guidance + an external reachability check.
-
-## Publishing (Maintainers)
-
-This repo ships as:
-- GitHub repo: `onthegonow/a2a_calling`
-- npm package: `a2acalling`
-
-Maintainer credentials are local-only and must never be committed:
-- `.env` (gitignored) must contain `GH_TOKEN` and `NPM_TOKEN`
-- GitHub Actions repo secrets should also include `GH_TOKEN` and `NPM_TOKEN` for automated releases
-
-## Commands
-
-### Quickstart
-
-User says: `/a2a quickstart`, `/a2a start`, "set up A2A", "get started with A2A", "configure what my agent shares"
-
-Deterministic onboarding flow (sequential, flags-based):
-
-1. Background bootstrap (config + disclosure)
-2. Owner dashboard access (local URL + optional Callbook Remote install link)
-3. Set permission tiers: populate tier `topics` + `goals` (schema-validated and saved)
-4. Port scan + reverse proxy guidance (if needed for public hostname)
-5. External IP confirmation and public reachability check (public hostname only)
-
-Run it like:
-
-```bash
-# Local machine (local-only invites)
-a2a quickstart --port 3001
-
-# Server / public hostname
-a2a quickstart --hostname YOUR_DOMAIN:443 --port 3001
-```
-
-Quickstart prints and saves a tier configuration immediately (validated by the config layer). If you want to override the Friends tier topics/interests, rerun with:
-
-```bash
-# Provide topics directly
-a2a quickstart --port 3001 --friends-topics "chat,search,openclaw,a2a"
-
-# Or prompt interactively for Friends tier topics
-a2a quickstart --port 3001 --interactive
-```
-
-If reverse proxy/ingress is required, Quickstart will stop and ask for explicit confirmation (`--confirm-ingress`).
-
-Full disclosure onboarding (manifest editing) remains available below: it generates a disclosure manifest that controls what topics your agent discusses or redirects during A2A calls — scoped by access tier (public, friends, family).
-
-This onboarding is required before the first `/a2a call`. The owner must approve permissions first.
-
-Flow:
-
-1. Scan ALL available context to generate a default manifest:
-   - Primary: USER.md, SOUL.md, memory/*.md
-   - Fallback: ~/.gitconfig, env vars, hostname, installed tools
-   - Infer owner's domain from system state if workspace is empty
-2. Present the manifest as a numbered text list grouped by tier:
-
-```
-PUBLIC TIER (anyone can see):
-Lead with:
-  1. [topic] — [detail]
-  2. [topic] — [detail]
-Discuss freely:
-  3. [topic] — [detail]
-Deflect:
-  4. [topic] — [detail]
-
-FRIENDS TIER (trusted contacts):
-Lead with:
-  5. [topic] — [detail]
-...
-
-FAMILY TIER (inner circle):
-...
-
-NEVER DISCLOSE:
-  N. [item]
-```
-
-3. User edits via text commands:
-
-```
-move 3 to friends.lead       — Move topic #3 to friends tier lead_with
-remove 5                     — Remove topic #5
-add public.discuss "Topic" "Detail about it"  — Add new topic
-edit 2 detail "Updated desc" — Edit topic #2's detail
-done                         — Save manifest and finish
-```
-
-4. Manifest saved to `~/.config/openclaw/a2a-disclosure.json`
-
-### Open GUI (Dashboard)
-
-User says: `/a2a gui`, `/a2a dashboard`, "open the GUI", "open the dashboard", "show me A2A logs"
-
-This opens the local dashboard UI in the default browser (or prints the URL if auto-open is not possible).
-
-Notes:
-- This command is safe and **does not require onboarding**.
-- Optional: open a specific tab via `--tab`.
-
-Remote dashboard access (Callbook Remote):
-- If the owner wants to use the dashboard from a different machine (ex: MacBook), have them open the dashboard locally on the server at `http://127.0.0.1:<port>/dashboard/`.
-- In `Settings` -> `Remote Callbook`, click `Create Install Link (24h)` and copy the URL to the remote machine.
-- The install link is one-time use and exchanges for a long-lived session cookie in the remote browser.
-- To revoke access, use `Settings` -> `Remote Callbook` -> `Paired Devices` -> `Revoke`.
-
-Examples:
-
-```bash
-a2a gui
-a2a gui --tab logs
-a2a dashboard --tab calls
-```
-
-### Invite (Create & Share Token)
-
-User says: `/a2a invite`, `/a2a invite public`, `/a2a invite friends`, `/a2a invite family`, "create an invite", "generate an A2A invite"
-
-**IMPORTANT: You MUST output the full formatted invite below. Do NOT shorten it, summarize it, or skip sections. The entire block is the deliverable.**
-
-1. Determine the tier from the user's command (default: `public`).
-2. Run: `a2a create --name "AGENT_NAME" --owner "OWNER_NAME" --expires never --permissions TIER`
-   Use the agent's real name and owner name from workspace context.
-3. Extract the `a2a://` invite URL from the CLI output.
-4. Read topics from the config: `cat ~/.config/openclaw/a2a-config.json` — get the tier's `topics` and `goals` arrays.
-5. Output the invite to the user as EXACTLY this format (fill in real values):
-
----
-
-📞🗣️ **Agent-to-Agent Call Invite**
-
-👤 **OWNER_NAME** would like your agent to call **AGENT_NAME** and explore where our owners might collaborate.
-
-💬 topic1 · topic2 · topic3 · topic4
-🎯 goal1 · goal2 · goal3
-
-a2a://hostname/fed_xxxxx
-
-── setup ──
-npm i -g a2acalling && a2a add "a2a://hostname/fed_xxxxx" "AGENT_NAME" && a2a call "AGENT_NAME" "Hello from my owner!"
-https://github.com/onthegonow/a2a_calling
-
----
-
-Here is a COMPLETE EXAMPLE of what the output must look like for bappybot:
-
----
-
-📞🗣️ **Agent-to-Agent Call Invite**
-
-👤 **Ben Pollack** would like your agent to call **bappybot** and explore where our owners might collaborate.
-
-💬 chat · openclaw · a2a-protocol · decentralization · community-living · snow-adventures · interactive-art · music-education
-🎯 grow-network · spread-a2a-awareness · find-collaborators · build-in-public
-
-a2a://149.28.213.47:3001/fed_AbCdEfGhIjKlMnOpQrStUvWx
-
-── setup ──
-npm i -g a2acalling && a2a add "a2a://149.28.213.47:3001/fed_AbCdEfGhIjKlMnOpQrStUvWx" "bappybot" && a2a call "bappybot" "Hello from my owner!"
-https://github.com/onthegonow/a2a_calling
-
----
-
-Formatting rules:
-- Join topics with ` · ` (middle dot). Show ALL topics from the tier config, not just "chat".
-- Join goals with ` · `. Omit the 🎯 line only if there are zero goals.
-- The setup line is ONE single copy-pasteable command.
-- GitHub link is always the last line.
-- If the token expires, add `⏰ EXPIRY_DATE` below the invite URL.
-- Never truncate, abbreviate, or skip any part of this template.
-
-### Create Token (Advanced)
-
-User says: `/a2a create`, "create an A2A token", "let another agent call me"
-
-For users who want fine-grained control over token options:
-
-```bash
-a2a create --name "NAME" --expires DURATION --permissions LEVEL
-```
-
-Options:
-- `--name, -n` — Token label
-- `--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`)
-
-After creating, format the output as the invite block described above.
-
-### List Tokens
-
-```bash
-a2a list
-```
-
-### Revoke Token
-
-```bash
-a2a revoke TOKEN_ID
-```
-
-### Add Remote Agent
-
-When user shares an invite URL:
-
-```bash
-a2a add "a2a://host/token" "Agent Name"
-```
-
-### Uninstall
-
-User says: `/a2a uninstall`, "uninstall A2A", "remove A2A calling"
-
-This stops the pm2-managed server (process name: `a2a`) and optionally deletes local config/DB files under `~/.config/openclaw/`.
-
-Ask for confirmation in chat, then run one of:
-
-```bash
-# Full uninstall (deletes local config + database)
-a2a uninstall --force
-
-# Keep config/DB (for reinstall)
-a2a uninstall --keep-config --force
-```
-
-Then tell the user to complete removal with:
-
-```bash
-npm uninstall -g a2acalling
-```
-
-## Calling Remote Agents
-
-When task delegation to a known remote agent would help, or user asks to contact an A2A agent:
-
-```javascript
-// Use a2a_call tool
-a2a_call({
-  endpoint: "a2a://host/token",
-  message: "Your question here",
-  conversation_id: "optional-for-continuity"
-})
-```
-
-## Handling Incoming Calls
-
-When receiving an A2A call, the agent operates within the token's permission scope.
-
-Each tier carries a `capabilities[]` array. `context-read` is always available — the agent can read its own knowledge base to formulate answers. Higher tiers unlock caller-facing capabilities:
-
-| Tier | Default Capabilities |
-|------|---------------------|
-| `public` | `context-read` |
-| `friends` | `context-read`, `calendar.read`, `email.read`, `search` |
-| `family` | `context-read`, `calendar`, `email`, `search`, `tools`, `memory` |
-
-Topics and goals act as information filters — they control what the agent proactively shares, discusses, or deflects.
-
-Apply disclosure level:
-- `public` — Share any non-private info
-- `minimal` — Direct answers only, no owner context
-- `none` — Confirm capability only
-
-## Owner Notifications
-
-When `notify: all`, send to owner:
-
-```
-🤝 A2A call received
-
-From: [Caller] ([host])
-Token: "[name]" (expires [date])
-
----
-[Transcript]
----
-
-📊 [N] calls | Expires in [time]
-```
-
-Owner can reply to inject into the conversation.
-
-## Update
-
-Check for and install the latest version. Handles both npm global installs and git clones. Re-syncs SKILL.md and config after update.
-
-```bash
-a2a update --check    # Check for updates without installing
-a2a update            # Update to latest version
-```
-
-## Rate Limits
-
-Per token: 10/min, 100/hr, 1000/day
-
-## Protocol Reference
-
-See [docs/protocol.md](docs/protocol.md) for full specification.

package/.claude/commands/a2a-call.md

@@ -1,26 +0,0 @@
----
-description: Call another A2A agent — starts a multi-turn conversation
-allowed-tools: [Bash, Read]
-argument-hint: <contact-or-url> <message>
----
-
-Call an A2A agent. This starts a multi-turn agent-to-agent conversation.
-
-## Usage
-
-```
-/a2a-call Alice "Hello! My owner wants to discuss the project."
-/a2a-call a2a://host.com/fed_abc123 "Reaching out about collaboration"
-```
-
-## Instructions
-
-Run the following command with the user's arguments:
-
-```bash
-a2a call $ARGUMENTS
-```
-
-If the call succeeds, summarize the conversation outcome for the user.
-If it fails with "not onboarded", tell the user to run `/a2a-setup` first.
-If it fails with "contact not found", suggest `/a2a-contacts` to see available contacts.

package/.claude/commands/a2a-contacts.md

@@ -1,31 +0,0 @@
----
-description: List A2A contacts — agents you can call or who can call you
-allowed-tools: [Bash]
-argument-hint: [add|show|ping|rm] [args...]
----
-
-Manage your A2A contact list — see who you can call and who has access to you.
-
-## Usage
-
-```
-/a2a-contacts                          # list all contacts
-/a2a-contacts add a2a://host/fed_xxx Alice  # add contact from invite URL
-/a2a-contacts show Alice               # show contact details
-/a2a-contacts ping Alice               # check if contact is online
-/a2a-contacts rm Alice                 # remove a contact
-```
-
-## Instructions
-
-Run the appropriate command based on user input:
-
-- No arguments: `a2a contacts`
-- `add`: `a2a contacts add $ARGUMENTS`
-- `show`: `a2a contacts show $ARGUMENTS`
-- `ping`: `a2a contacts ping $ARGUMENTS`
-- `rm`: `a2a contacts rm $ARGUMENTS`
-
-If the user just wants to see their contacts, also run `a2a list` to show active tokens (outbound invites).
-
-Format the output clearly: contact name, owner, status (online/offline), permission tier, last seen.

package/.claude/commands/a2a-invite.md

@@ -1,33 +0,0 @@
----
-description: Create an A2A invite token to share with another agent
-allowed-tools: [Bash]
-argument-hint: [name] [--tier public|friends|family] [--expires 7d]
----
-
-Create an A2A federation token and display the invite URL for sharing.
-
-## Usage
-
-```
-/a2a-invite Alice --tier friends --expires 7d
-/a2a-invite "Bob's Agent" --tier public
-/a2a-invite                              # interactive — uses defaults
-```
-
-## Instructions
-
-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."

package/.claude/commands/a2a-setup.md

@@ -1,30 +0,0 @@
----
-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-status.md

@@ -1,24 +0,0 @@
----
-description: Check A2A server status, active conversations, and agent health
-allowed-tools: [Bash, Read]
----
-
-Check the health of your A2A installation — server running, conversations active, contacts online.
-
-## Instructions
-
-Run these commands and compile a status report:
-
-1. **Config:** `a2a config --show`
-2. **Active tokens:** `a2a list`
-3. **Contacts:** `a2a contacts`
-4. **Recent conversations:** `a2a conversations --limit 5`
-
-Present a clear status dashboard:
-- 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.