a2acalling 0.6.54 → 0.6.56

package/CLAUDE-INSTALL.md

@@ -152,3 +152,5 @@ a2a version              # Show installed version
 - 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/SKILL.md

@@ -27,6 +27,97 @@ metadata:
 
 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

package/bin/cli.js

@@ -2711,6 +2711,75 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
       console.log('Removing database... ⏭️');
     }
 
+    // ── Remove installed skill files using the manifest ──────────────────
+    //
+    // The postinstall script writes .a2a-manifest.json listing every file
+    // it installed (CLAUDE.md section, slash commands, skill reference, etc.).
+    // We read the manifest to remove exactly the files we installed, avoiding
+    // accidental deletion of user files. For CLAUDE.md we only remove the
+    // A2A section (bounded by markers), not the entire file.
+    const manifestCwd = process.env.INIT_CWD || process.cwd();
+    const manifestPath = path.join(manifestCwd, '.a2a-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      process.stdout.write('Removing installed skill files... ');
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        let skillOk = true;
+        for (const entry of (manifest.files || [])) {
+          const filePath = path.join(manifestCwd, entry.path);
+          // Skip the manifest itself (we remove it last) and non-existent files
+          if (entry.path === '.a2a-manifest.json') continue;
+          if (!fs.existsSync(filePath)) continue;
+
+          // For CLAUDE.md: only remove the A2A section, not the whole file.
+          // The user may have their own project-specific content in CLAUDE.md.
+          if (entry.path === 'CLAUDE.md') {
+            try {
+              const content = fs.readFileSync(filePath, 'utf8');
+              const mergeKey = '# A2A Calling';
+              const endMarker = '<!-- END A2A CALLING SECTION -->';
+              if (content.includes(mergeKey)) {
+                const start = content.indexOf(mergeKey);
+                const endIdx = content.indexOf(endMarker, start);
+                let cleaned;
+                if (endIdx !== -1) {
+                  // Remove the bounded A2A section (header through end marker)
+                  const before = content.slice(0, start).trimEnd();
+                  const after = content.slice(endIdx + endMarker.length).trimStart();
+                  cleaned = before + (after ? '\n\n' + after : '');
+                } else {
+                  // Legacy: no end marker — remove from header to EOF
+                  cleaned = content.slice(0, start).trimEnd();
+                }
+                if (cleaned.trim()) {
+                  fs.writeFileSync(filePath, cleaned.trimEnd() + '\n');
+                } else {
+                  // CLAUDE.md was entirely A2A content — remove the file
+                  fs.rmSync(filePath, { force: true });
+                }
+              }
+            } catch (e) {
+              skillOk = false;
+            }
+            continue;
+          }
+
+          // For all other files: remove them entirely
+          try {
+            fs.rmSync(filePath, { force: true });
+          } catch (e) {
+            skillOk = false;
+          }
+        }
+        // Remove the manifest file itself last
+        fs.rmSync(manifestPath, { force: true });
+        console.log(skillOk ? '✅' : '⚠️');
+      } catch (err) {
+        console.log('⚠️');
+        console.error(`  Could not read manifest: ${err.message}`);
+      }
+    }
+
     // Remove native macOS app if present
     if (os.platform() === 'darwin') {
       const appCandidates = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2acalling",
-  "version": "0.6.54",
+  "version": "0.6.56",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/scripts/install-skills.js

@@ -1,13 +1,23 @@
 /**
  * A2A Skill Installer
  *
- * Copies Claude Code commands, CLAUDE.md context, and Codex AGENTS.md into a
- * target project directory. Idempotent: skips files that already exist with
- * identical content.
+ * Copies Claude Code commands, CLAUDE.md context, SKILL.md reference, and
+ * Codex AGENTS.md into a target project directory. Idempotent: skips files
+ * that already exist with identical content.
  *
  * CLAUDE.md is the key file — Claude Code reads it automatically, giving the
  * agent full context about the a2a CLI, native app, and onboarding flow
  * immediately after npm install.
+ *
+ * SKILL.md is the deep reference for A2A — invite formatting templates,
+ * incoming call handling, disclosure manifest flow, and protocol details.
+ * We copy it to .claude/ so Claude Code can discover it naturally without
+ * having to grep through node_modules. The .claude/ directory is already
+ * used for slash commands, so this is a natural home for reference docs.
+ *
+ * Unlike CLAUDE.md (which is auto-loaded), the skill reference file is only
+ * read when the agent explicitly looks in .claude/ — so it serves as opt-in
+ * deep reference rather than always-loaded context (avoiding token bloat).
  */
 
 const fs = require('fs');
@@ -15,9 +25,18 @@ const path = require('path');
 
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
+// Section delimiter used to bound the A2A block inside CLAUDE.md.
+// This allows safe replacement of ONLY the A2A content when updating,
+// preserving any user content before or after the A2A section.
+const A2A_SECTION_END_MARKER = '<!-- END A2A CALLING SECTION -->';
+
 const SKILL_FILES = [
   // CLAUDE.md — gives Claude Code instant context about the a2a CLI
   { src: 'CLAUDE-INSTALL.md', dest: 'CLAUDE.md', mergeKey: '# A2A Calling' },
+  // SKILL.md — deep reference for A2A (invite formatting, call handling, etc.)
+  // Copied to .claude/ so Claude Code discovers it naturally without grepping
+  // node_modules. This is opt-in context: only loaded when the agent looks.
+  { src: 'SKILL.md', dest: '.claude/a2a-skill-reference.md' },
   // Claude Code slash commands
   { src: '.claude/commands/a2a-call.md', dest: '.claude/commands/a2a-call.md' },
   { src: '.claude/commands/a2a-invite.md', dest: '.claude/commands/a2a-invite.md' },
@@ -31,6 +50,20 @@ const SKILL_FILES = [
 function installSkills(targetDir, options = {}) {
   const result = { installed: [], skipped: [], errors: [] };
 
+  // Install manifest: .a2a-manifest.json
+  //
+  // After installing skill files, we write a manifest recording every file
+  // we touched, what action was taken, and the package version. This serves
+  // three purposes:
+  //   1. Transparency — user can see exactly what the package added
+  //   2. Clean uninstall — `a2a uninstall` reads the manifest to remove files
+  //   3. Upgrade tracking — on re-install, we can compare versions and
+  //      only update files that actually changed
+  //
+  // The manifest is written to the project root (same level as CLAUDE.md)
+  // so it's easy to find.
+  const manifestEntries = [];
+
   for (const file of SKILL_FILES) {
     const srcPath = path.join(PACKAGE_ROOT, file.src);
     const destPath = path.join(targetDir, file.dest);
@@ -38,6 +71,7 @@ function installSkills(targetDir, options = {}) {
     try {
       if (!fs.existsSync(srcPath)) {
         result.errors.push({ file: file.src, error: 'Source file not found' });
+        manifestEntries.push({ path: file.dest, action: 'error', detail: 'Source file not found' });
         continue;
       }
 
@@ -46,47 +80,125 @@ function installSkills(targetDir, options = {}) {
       if (fs.existsSync(destPath)) {
         const existing = fs.readFileSync(destPath, 'utf8');
 
-        // Merge mode: if the file has a mergeKey, append/replace the A2A section
-        // in an existing file rather than overwriting it entirely.
+        // ── CLAUDE.md merge strategy ──────────────────────────────────────
+        //
+        // The a2acalling package installs context into the project's CLAUDE.md so
+        // Claude Code has immediate awareness of the CLI, commands, and native app.
+        // But projects often have their own CLAUDE.md with project-specific instructions.
+        //
+        // To avoid clobbering user content, we use a section-delimited merge:
+        //   1. If CLAUDE.md doesn't exist: write CLAUDE-INSTALL.md as-is
+        //   2. If CLAUDE.md exists WITHOUT an A2A section: append at the end
+        //   3. If CLAUDE.md exists WITH an A2A section: replace only between
+        //      "# A2A Calling" and "<!-- END A2A CALLING SECTION -->"
+        //
+        // The end marker ensures user content after the A2A block is preserved.
+        // Legacy installs without the marker fall back to replace-to-EOF (old behavior)
+        // but the marker is added during the update so future updates are safe.
         if (file.mergeKey) {
           if (existing.includes(file.mergeKey)) {
-            // A2A section already present — extract and compare
+            // A2A section already present — find its boundaries
             const sectionStart = existing.indexOf(file.mergeKey);
-            const existingSection = existing.slice(sectionStart);
+
+            // Check if the end marker exists to determine section boundaries.
+            // If found, we only replace the bounded section, preserving any
+            // user content after the marker. If not found (legacy installs
+            // that predate the marker), we replace from the header to EOF
+            // and add the marker so future updates are safe.
+            const endMarkerIndex = existing.indexOf(A2A_SECTION_END_MARKER, sectionStart);
+
+            let existingSection;
+            let after = '';
+
+            if (endMarkerIndex !== -1) {
+              // End marker found — extract only the bounded A2A section
+              const sectionEnd = endMarkerIndex + A2A_SECTION_END_MARKER.length;
+              existingSection = existing.slice(sectionStart, sectionEnd);
+              // Preserve everything after the end marker (user's trailing content)
+              after = existing.slice(sectionEnd);
+            } else {
+              // Legacy install without end marker — take everything from header to EOF
+              // The new content includes the marker, so future updates will be safe
+              existingSection = existing.slice(sectionStart);
+            }
+
+            // Compare the existing A2A section with the new source content.
+            // Skip the update if they're identical (idempotent behavior).
             if (!options.force && existingSection.trim() === srcContent.trim()) {
               result.skipped.push(file.dest);
+              manifestEntries.push({ path: file.dest, action: 'skipped' });
               continue;
             }
-            // Replace the A2A section with updated content
+
+            // Replace only the A2A section, preserving content before and after
             const before = existing.slice(0, sectionStart).trimEnd();
-            const merged = before ? before + '\n\n' + srcContent : srcContent;
+            let merged = before ? before + '\n\n' + srcContent : srcContent;
+            // Re-attach any trailing content that was after the end marker
+            if (after) {
+              merged = merged.trimEnd() + '\n' + after;
+            }
             fs.writeFileSync(destPath, merged);
             result.installed.push(file.dest + ' (updated A2A section)');
+            manifestEntries.push({ path: file.dest, action: 'updated A2A section' });
           } else {
-            // Existing CLAUDE.md without A2A section — append
+            // Existing CLAUDE.md without A2A section — append at the end
             const merged = existing.trimEnd() + '\n\n' + srcContent;
             fs.writeFileSync(destPath, merged);
             result.installed.push(file.dest + ' (appended A2A section)');
+            manifestEntries.push({ path: file.dest, action: 'appended A2A section' });
           }
           continue;
         }
 
-        // Standard mode: skip if identical
+        // Standard mode: skip if identical (non-merge files)
         if (!options.force && existing === srcContent) {
           result.skipped.push(file.dest);
+          manifestEntries.push({ path: file.dest, action: 'skipped' });
           continue;
         }
+      } else {
+        // File doesn't exist yet — will be created below
       }
 
       // Create directory and write file
       fs.mkdirSync(path.dirname(destPath), { recursive: true });
       fs.writeFileSync(destPath, srcContent);
       result.installed.push(file.dest);
+      manifestEntries.push({ path: file.dest, action: 'created' });
     } catch (err) {
       result.errors.push({ file: file.dest, error: err.message });
+      manifestEntries.push({ path: file.dest, action: 'error', detail: err.message });
     }
   }
 
+  // ── Write install manifest ────────────────────────────────────────────
+  //
+  // The manifest records every file we touched so the user (or `a2a uninstall`)
+  // knows exactly what was installed. We include the manifest itself in the list
+  // for completeness.
+  try {
+    const pkg = require('../package.json');
+    const manifestPath = path.join(targetDir, '.a2a-manifest.json');
+
+    // Add the manifest file itself to the entries list
+    manifestEntries.push({ path: '.a2a-manifest.json', action: 'created' });
+    // Add the install log file (written by postinstall.js)
+    manifestEntries.push({ path: '.a2a-install.log', action: 'created' });
+
+    const manifest = {
+      version: pkg.version,
+      installed_at: new Date().toISOString(),
+      files: manifestEntries,
+    };
+
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  } catch (err) {
+    // Non-fatal — the manifest is a convenience for cleanup, not required
+    // for the skill files to work. Failure here (e.g., read-only dir)
+    // should not break the install.
+    result.errors.push({ file: '.a2a-manifest.json', error: err.message });
+  }
+
   return result;
 }
 

package/scripts/postinstall.js

@@ -23,6 +23,7 @@
 if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) process.exit(0);
 if (process.env.DOCKER) process.exit(0);
 
+const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawnSync } = require('child_process');
@@ -70,6 +71,22 @@ function printGettingStarted() {
   const isMac = os.platform() === 'darwin';
   const pkg = require('../package.json');
 
+  // ── Short critical stderr output ──────────────────────────────────────
+  //
+  // npm v7+ suppresses stdout/stderr from postinstall scripts unless
+  // --foreground-scripts is used. We print a minimal critical line to stderr
+  // (which npm sometimes still shows) AND write the full banner to a log file
+  // so that Claude Code or a human can always find the getting-started info.
+  const shortLines = [
+    `a2acalling v${pkg.version} installed.`,
+    'Next step: a2a quickstart',
+    'Skills installed: /a2a-setup, /a2a-call, /a2a-contacts, /a2a-invite, /a2a-status',
+  ];
+  // Print the short critical summary to stderr — this is the most likely
+  // output to survive npm's output suppression in v7+
+  console.error(shortLines.join('\n'));
+
+  // ── Full verbose banner ───────────────────────────────────────────────
   const lines = [
     '',
     '╔══════════════════════════════════════════════════════════════╗',
@@ -176,9 +193,32 @@ function printGettingStarted() {
     '',
   );
 
-  // Print to stderr — npm v7+ captures stdout from lifecycle scripts,
-  // but stderr is still visible in many agent contexts
-  console.error(lines.join('\n'));
-  // Also print to stdout for contexts where stderr is filtered
-  console.log(lines.join('\n'));
+  const fullBanner = lines.join('\n');
+
+  // Print the full banner to stdout for contexts where it's visible
+  // (e.g., --foreground-scripts, direct script execution, agent contexts)
+  console.log(fullBanner);
+
+  // ── Write full banner to a log file ─────────────────────────────────
+  //
+  // Even when npm suppresses terminal output, the agent or human can read
+  // this file to get the full getting-started info. We write to the project
+  // root (initCwd) so it's next to CLAUDE.md and easy to discover.
+  try {
+    const logPath = path.join(initCwd, '.a2a-install.log');
+    const logContent = [
+      `a2acalling v${pkg.version} — install summary`,
+      `Installed at: ${new Date().toISOString()}`,
+      `Target directory: ${initCwd}`,
+      `Global install: ${isGlobal}`,
+      '',
+      ...shortLines,
+      '',
+      fullBanner,
+    ].join('\n');
+    fs.writeFileSync(logPath, logContent);
+  } catch (e) {
+    // Non-fatal — the log file is a convenience, not a requirement.
+    // This can fail if the target directory is read-only (e.g., system dirs).
+  }
 }