a2acalling 0.6.48 → 0.6.50

package/docs/prompts/e2e-test-agent.md

@@ -0,0 +1,368 @@
+# E2E Test Agent Prompt Sequence
+
+Run a full end-to-end validation of `a2acalling` in an isolated environment. Execute each step sequentially. If a step fails, log the failure and continue to the next step unless the failure is blocking (steps 1-3 block all subsequent steps).
+
+## Prerequisites
+
+Before starting, verify:
+
+- **Node.js** >= 18.0.0 (`node --version`)
+- **npm** available (`npm --version`)
+- **Ports** 3100-3199 range available (used by test servers)
+- **Disk** at least 200MB free in system temp directory
+- **Network** localhost connections allowed (no firewall blocking loopback)
+
+If any prerequisite is missing, report it as a step-0 failure and abort.
+
+## Output Format
+
+Report each step as a JSON object:
+
+```json
+{
+  "step": 1,
+  "name": "install",
+  "status": "pass",
+  "duration_ms": 4230,
+  "error": null
+}
+```
+
+On completion, return a JSON array of all step results:
+
+```json
+{
+  "run_id": "e2e_<timestamp>",
+  "started_at": "<ISO-8601>",
+  "finished_at": "<ISO-8601>",
+  "total_steps": 9,
+  "passed": 8,
+  "failed": 1,
+  "results": [ ... ]
+}
+```
+
+---
+
+## Step 1: Install from npm
+
+**What to do:**
+
+```bash
+WORKDIR=$(mktemp -d -t a2a-e2e-XXXXXX)
+cd "$WORKDIR"
+npm init -y --silent
+npm install a2acalling
+```
+
+**Expected outcome:**
+- Exit code 0 from `npm install`
+- `node_modules/a2acalling/bin/cli.js` exists
+- `node_modules/a2acalling/src/server.js` exists
+
+**Failure:**
+- If npm install fails, record the stderr and abort all remaining steps (blocking).
+
+**Variables to carry forward:**
+- `WORKDIR` -- root temp directory
+- `CLI` = `$WORKDIR/node_modules/.bin/a2a`
+- `A2A_CONFIG_DIR` = `$WORKDIR/config` (create this directory)
+
+---
+
+## Step 2: Run Quickstart Onboarding
+
+**What to do:**
+
+```bash
+export A2A_CONFIG_DIR="$WORKDIR/config"
+export CI=true
+mkdir -p "$A2A_CONFIG_DIR"
+```
+
+First, write a minimal config to simulate port detection completing:
+
+```bash
+cat > "$A2A_CONFIG_DIR/a2a-config.json" << 'CONF'
+{
+  "onboarding": { "version": 2, "step": "awaiting_disclosure", "server_port": 3100 },
+  "agent": { "hostname": "localhost:3100", "name": "e2e-test-agent" },
+  "tiers": {}
+}
+CONF
+```
+
+Then submit the disclosure manifest:
+
+```bash
+node "$CLI" onboard --submit '{
+  "tiers": {
+    "public": {
+      "topics": [{"topic": "General", "description": "Open discussion"}],
+      "objectives": [],
+      "do_not_discuss": []
+    },
+    "friends": {
+      "topics": [{"topic": "Projects", "description": "Current work"}],
+      "objectives": [],
+      "do_not_discuss": []
+    },
+    "family": {
+      "topics": [{"topic": "Everything", "description": "Full access"}],
+      "objectives": [],
+      "do_not_discuss": []
+    }
+  },
+  "never_disclose": ["passwords", "api-keys"],
+  "personality_notes": "E2E test agent. Direct and minimal responses."
+}'
+```
+
+**Expected outcome:**
+- Exit code 0
+- stdout contains "Onboarding complete"
+- `$A2A_CONFIG_DIR/a2a-config.json` has `onboarding.step` set to `"complete"`
+
+**Failure:**
+- If onboarding fails, record stdout/stderr and abort (blocking).
+
+---
+
+## Step 3: Verify Server Health
+
+**What to do:**
+
+Start the server, then check health endpoints:
+
+```bash
+node "$WORKDIR/node_modules/a2acalling/src/server.js" &
+SERVER_PID=$!
+sleep 2
+```
+
+Check ping:
+
+```bash
+curl -s http://localhost:3100/api/a2a/ping
+```
+
+Check status:
+
+```bash
+curl -s http://localhost:3100/api/a2a/status
+```
+
+**Expected outcome:**
+- Ping returns `{"pong": true, "timestamp": "..."}` with HTTP 200
+- Status returns JSON with `"a2a": true` and a `"version"` field
+- Server process is running (PID exists)
+
+**Failure:**
+- If server does not start or endpoints do not respond within 10 seconds, abort (blocking).
+
+**Variables to carry forward:**
+- `SERVER_PID`
+- `BASE_URL` = `http://localhost:3100`
+
+---
+
+## Step 4: Create Invite Token
+
+**What to do:**
+
+```bash
+node "$CLI" create --name "E2E-Caller" --tier public --expires 1h
+```
+
+Parse the output to extract the token and invite URL.
+
+**Expected outcome:**
+- Exit code 0
+- Output contains an invite URL matching `a2a://localhost:3100/fed_...`
+- Output contains a token matching `fed_[A-Za-z0-9_-]+`
+
+**Variables to carry forward:**
+- `TOKEN` -- the `fed_...` string
+- `INVITE_URL` -- the full `a2a://...` URL
+
+---
+
+## Step 5: Test Inbound Call
+
+**What to do:**
+
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Hello from E2E test",
+    "caller": {
+      "name": "E2E Test Runner",
+      "instance": "localhost",
+      "context": "Automated E2E validation"
+    }
+  }'
+```
+
+**Expected outcome:**
+- HTTP 200
+- Response JSON has `"success": true`
+- Response JSON has a `"conversation_id"` starting with `conv_`
+- Response JSON has a non-empty `"response"` field
+- Response JSON has `"can_continue": true`
+
+---
+
+## Step 6: Test Multi-turn Conversation
+
+**What to do:**
+
+Use the `conversation_id` from step 5. Make two follow-up calls:
+
+Call 1:
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"message\": \"Follow-up question 1\",
+    \"conversation_id\": \"$CONVERSATION_ID\"
+  }"
+```
+
+Call 2:
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"message\": \"Follow-up question 2\",
+    \"conversation_id\": \"$CONVERSATION_ID\"
+  }"
+```
+
+**Expected outcome:**
+- Both calls return HTTP 200 with `"success": true`
+- Both return the same `conversation_id` as the original
+- Both have non-empty `"response"` fields
+
+---
+
+## Step 7: Test Error Cases
+
+Run three negative tests:
+
+### 7a: No auth header
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "no auth"}'
+```
+
+**Expected:** HTTP 401, response body has `"error": "missing_token"`
+
+### 7b: Bad token
+
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer fed_invalid_token_value" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "bad token"}'
+```
+
+**Expected:** HTTP 401 or 403, response body has `"success": false`
+
+### 7c: Missing message body
+
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+**Expected:** HTTP 400, response body has `"error": "missing_message"`
+
+**Step passes only if all three sub-tests pass.** Report sub-test details in the error field if any fail.
+
+---
+
+## Step 8: Test Token Revocation
+
+**What to do:**
+
+First, find the token ID:
+
+```bash
+node "$CLI" list
+```
+
+Parse the token ID (`tok_...`) from the output, then revoke it:
+
+```bash
+node "$CLI" revoke "$TOKEN_ID"
+```
+
+Then attempt a call with the revoked token:
+
+```bash
+curl -s -X POST "$BASE_URL/api/a2a/invoke" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "should fail"}'
+```
+
+**Expected outcome:**
+- Revoke command exits 0
+- Post-revocation call returns `"success": false`
+- Error field is `"token_revoked"` or similar auth error
+
+---
+
+## Step 9: Cleanup
+
+**What to do:**
+
+```bash
+kill $SERVER_PID 2>/dev/null
+wait $SERVER_PID 2>/dev/null
+
+rm -rf "$WORKDIR"
+```
+
+Verify:
+```bash
+! kill -0 $SERVER_PID 2>/dev/null  # process is gone
+[ ! -d "$WORKDIR" ]               # directory is gone
+```
+
+**Expected outcome:**
+- Server process is terminated
+- Temp directory is removed
+- No orphaned processes on port 3100
+
+**This step always passes unless cleanup throws an unexpected error.**
+
+---
+
+## Failure Reporting
+
+When a step fails, generate a Linear bug report payload:
+
+```json
+{
+  "title": "E2E: Step <N> (<name>) failed",
+  "description": "## Failure\n\n<error message>\n\n## Reproduction\n\nRun `node test/e2e/orchestrate.js --verbose`\n\n## Environment\n\n- Node: <version>\n- npm: <version>\n- OS: <platform>\n- a2acalling: <version>",
+  "priority": 2,
+  "labels": ["bug", "e2e"],
+  "team": "ENG"
+}
+```
+
+Priority mapping:
+- Steps 1-3 (blocking): priority 1 (Urgent)
+- Steps 4-6 (core flow): priority 2 (High)
+- Steps 7-8 (error handling): priority 3 (Normal)
+- Step 9 (cleanup): priority 4 (Low)

package/docs/protocol.md

@@ -309,6 +309,127 @@ a2a_call({
 }
 ```
 
+## E2E Testing
+
+### Architecture
+
+E2E tests run in fully isolated environments. Each test gets its own temp directory, config directory (`A2A_CONFIG_DIR`), and ephemeral port. No shared state between tests; no pollution of the host system.
+
+Core components:
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| Environment | `test/e2e/env.js` | Creates isolated temp dir, config dir, port finder, cleanup |
+| Two-server harness | `test/e2e/two-server.js` | Spins up two independent A2A servers for cross-agent tests |
+| CLI runner | `test/e2e/cli-runner.js` | Wraps `bin/cli.js` as child process with structured output |
+| Agent prompt | `docs/prompts/e2e-test-agent.md` | 9-step prompt sequence for Claude subagent validation |
+
+### Test Categories
+
+- **Infrastructure** (`env.test.js`) -- Isolated environments, port allocation, cleanup
+- **CLI integration** (`cli-runner.test.js`) -- Command execution, onboarding, exit codes, timeouts
+- **Cross-agent flow** (`two-server.test.js`) -- Two servers, token isolation, ping/invoke across instances
+- **Error handling** -- Bad tokens, missing auth, revoked tokens, malformed requests
+- **Summary validation** -- Prompt correctness across `server.js`, `openclaw-integration.js`, `claude-subagent.js` paths
+
+### Entry Points
+
+```bash
+# Run all tests (unit + integration + E2E)
+node test/run.js
+
+# Run E2E tests only
+node test/run.js --e2e
+
+# Standalone orchestrator with verbose or JSON output
+node test/e2e/orchestrate.js [--verbose] [--json]
+
+# Default: excludes E2E for faster feedback
+node test/run.js
+```
+
+The `--e2e` flag filters to files under `test/e2e/`. The standalone orchestrator runs the full 9-step sequence from `docs/prompts/e2e-test-agent.md` and outputs structured JSON results.
+
+### File Structure
+
+```
+test/e2e/
+  env.js                  # createE2EEnv() — isolated temp + config + port
+  env.test.js             # Tests for env isolation and port allocation
+  cli-runner.js           # CLIRunner class — child-process CLI wrapper
+  cli-runner.test.js      # Tests for CLI execution, onboarding, timeouts
+  two-server.js           # TwoServerHarness — two independent A2A instances
+  two-server.test.js      # Tests for cross-agent token isolation and ping
+  orchestrate.js           # Standalone E2E orchestrator (planned)
+```
+
+### Adding New E2E Tests
+
+1. Create `test/e2e/<name>.test.js` exporting `function(test, assert, helpers)`.
+2. Use `createE2EEnv()` for isolation. Always call `env.cleanup()` in a finally block.
+3. Use `TwoServerHarness` if you need two agents. Call `harness.teardown()` after.
+4. Use `CLIRunner` for CLI interactions. It handles `A2A_CONFIG_DIR` automatically.
+5. The test runner discovers all `*.test.js` files recursively -- no registration needed.
+
+Example skeleton:
+
+```js
+module.exports = function (test, assert, helpers) {
+  const { createE2EEnv } = require('./env');
+
+  test('my new E2E scenario', async () => {
+    const env = createE2EEnv('my-test');
+    try {
+      // ... test logic using env.configDir, env.findAvailablePort()
+    } finally {
+      env.cleanup();
+    }
+  });
+};
+```
+
+## CLI Skills (Claude Code & Codex)
+
+A2A ships with slash commands for Claude Code and agent instructions for Codex CLI.
+
+### Installation
+
+```bash
+a2a skills              # Install into current project
+a2a skills --check      # See what would be installed
+a2a skills --force      # Overwrite existing files
+```
+
+Skills are also installed automatically on `npm install -g a2acalling`.
+
+### Claude Code Commands
+
+| Command | Description |
+|---------|-------------|
+| `/a2a-call <contact> <msg>` | Call another agent (multi-turn) |
+| `/a2a-invite [name] [--tier]` | Create invite token |
+| `/a2a-contacts [add\|show\|ping\|rm]` | Manage contacts |
+| `/a2a-status` | Server and agent health dashboard |
+| `/a2a-setup` | First-time setup and onboarding |
+
+Files installed to: `.claude/commands/a2a-*.md`
+
+### Codex CLI
+
+A2A agent instructions are installed to `.codex/AGENTS.md`. Codex reads this file automatically to understand available A2A commands, permission tiers, and workflows.
+
+### Manual Installation
+
+If the automatic install didn't work, copy the files manually:
+
+```bash
+# Claude Code commands
+cp node_modules/a2acalling/.claude/commands/a2a-*.md .claude/commands/
+
+# Codex instructions
+cp node_modules/a2acalling/.codex/AGENTS.md .codex/AGENTS.md
+```
+
 ## Future Protocol Extensions (v1+)
 
 - **Capability advertisement**: Agents declare what they can help with

package/package.json

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

package/scripts/install-skills.js

@@ -0,0 +1,80 @@
+/**
+ * A2A Skill Installer
+ *
+ * Copies Claude Code commands and Codex AGENTS.md into a target project directory.
+ * Idempotent: skips files that already exist with identical content.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+const SKILL_FILES = [
+  { src: '.claude/commands/a2a-call.md', dest: '.claude/commands/a2a-call.md' },
+  { src: '.claude/commands/a2a-invite.md', dest: '.claude/commands/a2a-invite.md' },
+  { src: '.claude/commands/a2a-contacts.md', dest: '.claude/commands/a2a-contacts.md' },
+  { src: '.claude/commands/a2a-status.md', dest: '.claude/commands/a2a-status.md' },
+  { src: '.claude/commands/a2a-setup.md', dest: '.claude/commands/a2a-setup.md' },
+  { src: '.codex/AGENTS.md', dest: '.codex/AGENTS.md' }
+];
+
+function installSkills(targetDir, options = {}) {
+  const result = { installed: [], skipped: [], errors: [] };
+
+  for (const file of SKILL_FILES) {
+    const srcPath = path.join(PACKAGE_ROOT, file.src);
+    const destPath = path.join(targetDir, file.dest);
+
+    try {
+      if (!fs.existsSync(srcPath)) {
+        result.errors.push({ file: file.src, error: 'Source file not found' });
+        continue;
+      }
+
+      const srcContent = fs.readFileSync(srcPath, 'utf8');
+
+      // Check if identical file already exists
+      if (!options.force && fs.existsSync(destPath)) {
+        const existing = fs.readFileSync(destPath, 'utf8');
+        if (existing === srcContent) {
+          result.skipped.push(file.dest);
+          continue;
+        }
+      }
+
+      // Create directory and write file
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.writeFileSync(destPath, srcContent);
+      result.installed.push(file.dest);
+    } catch (err) {
+      result.errors.push({ file: file.dest, error: err.message });
+    }
+  }
+
+  return result;
+}
+
+// CLI mode: node scripts/install-skills.js [targetDir] [--force]
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+  const targetDir = args.find(a => !a.startsWith('-')) || process.cwd();
+
+  const result = installSkills(targetDir, { force });
+
+  if (result.installed.length) {
+    console.log(`Installed ${result.installed.length} A2A skill file(s):`);
+    result.installed.forEach(f => console.log(`  + ${f}`));
+  }
+  if (result.skipped.length) {
+    console.log(`Skipped ${result.skipped.length} unchanged file(s)`);
+  }
+  if (result.errors.length) {
+    console.error(`Errors: ${result.errors.length}`);
+    result.errors.forEach(e => console.error(`  ! ${e.file}: ${e.error}`));
+    process.exit(1);
+  }
+}
+
+module.exports = { installSkills, SKILL_FILES };

package/scripts/postinstall.js

@@ -43,13 +43,25 @@ const result = spawnSync(process.execPath, [cliPath, 'quickstart'], {
 
 if (result.error) {
   // Don't fail the install — the agent will get onboarding when it runs `a2a`.
+  installSkillFiles();
   installMacOSApp();
   process.exit(0);
 }
 
+installSkillFiles();
 installMacOSApp();
 process.exit(result.status || 0);
 
+// Best-effort: install Claude Code + Codex skills into the workspace
+function installSkillFiles() {
+  try {
+    const { installSkills } = require('./install-skills');
+    installSkills(initCwd);
+  } catch (e) {
+    // Silent — skills can be installed later with `a2a skills`
+  }
+}
+
 // Download and install the native macOS app from GitHub Releases
 function installMacOSApp() {
   const os = require('os');