a2acalling 0.6.59 → 0.6.61

package/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Architecture — A2A Calling
+
+## System Overview
+
+A2A Calling enables agent-to-agent communication across OpenClaw instances. Agents create tokens with scoped permissions, share invite URLs, and remote agents call in via HTTP.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  CLI (bin/cli.js)                                                │
+│  Commands: create, list, revoke, call, contacts, conversations   │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  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)        │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Core Libraries (src/lib/)                                        │
+│  ├─ tokens.js         Token CRUD, validation, tiers               │
+│  ├─ client.js         A2AClient for outbound calls                │
+│  ├─ conversations.js  ConversationStore (SQLite)                  │
+│  ├─ conversation-driver.js  Multi-turn call orchestration         │
+│  ├─ summarizer.js     Call summary generation                     │
+│  ├─ summary-prompt.js Unified summary prompt builder              │
+│  ├─ summary-formatter.js  Format summaries for display            │
+│  ├─ disclosure.js     Disclosure level enforcement                │
+│  ├─ config.js         Config file management                      │
+│  ├─ 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)   │
+│  ├─ 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          │
+│  ├─ update-checker.js Version update detection                    │
+│  └─ update-manager.js Self-update orchestration                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## 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`
+- **Config**: JSON at `~/.config/openclaw/a2a-config.json`
+- **Disclosure**: JSON at `~/.config/openclaw/a2a-disclosure.json`
+
+## Permission System
+
+Three tiers with escalating capabilities:
+- **public**: `context-read` only
+- **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
+
+## Dependencies
+
+Only two runtime dependencies (intentionally minimal):
+- `express` — HTTP server and routing
+- `better-sqlite3` — SQLite for conversations and logs
+
+## Dashboard
+
+Single-page app served from `src/dashboard/public/`. Uses Shoelace web components. Communicates with the API via `/dashboard/api/*` routes.
+
+## Native macOS App
+
+Tauri v2 app at `native/macos/` wrapping the dashboard SPA. Provides native menus, notifications, and server lifecycle management.
+
+## Testing
+
+Zero-dependency test runner at `test/run.js` with custom assert API. Three test tiers:
+- `test/unit/` — Unit tests for individual modules
+- `test/integration/` — Integration tests for multi-module flows
+- `test/e2e/` — End-to-end tests for full system flows
+
+Test profiles at `test/profiles/` represent real personas with distinct permission tiers.

package/CONVENTIONS.md

@@ -0,0 +1,78 @@
+# Conventions — A2A Calling
+
+## Logging
+
+Use the structured logger from `src/lib/logger.js`. Never use bare `console.log`.
+
+```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
+
+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.
+
+## 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 `/dashboard/api/*` endpoints
+- SSE for real-time updates via `src/lib/dashboard-events.js`
+
+## 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`.
+
+## Anti-Patterns
+
+- Do NOT use `console.log` — use the structured logger
+- 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/docs/plans/2026-02-18-a2a-42-e2e-persistence.md

@@ -0,0 +1,879 @@
+# A2A-42: E2E Test Persistence & Dashboard Integration
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add local result persistence, regression detection, a cron-ready wrapper, and a dashboard Health tab so E2E test results are stored, compared, and visible without external dependencies.
+
+**Architecture:** A new `test/e2e/persist.js` module handles writing timestamped JSON results to `~/.config/openclaw/test-results/`, reading history, and detecting regressions. The existing orchestrator gets a `--persist` flag that calls persist after each run. A shell script wraps orchestrate for cron. The dashboard gets a new Health tab backed by a single `GET /dashboard/api/test-results` endpoint that reads from the persist layer.
+
+**Tech Stack:** Node.js builtins only (fs, path). No new npm dependencies. Shoelace web components for dashboard UI.
+
+**Linear Ticket:** A2A-42
+
+---
+
+## Conventions Reminder
+
+- Logger: `const { createLogger } = require('./logger'); const logger = createLogger({ component: 'a2a.test' });`
+- No `console.log` in production code (test orchestrator already uses stderr — that's fine)
+- CommonJS modules (`require`/`module.exports`)
+- Config dir: use the same resolution as `src/lib/config.js` — `process.env.A2A_CONFIG_DIR || process.env.OPENCLAW_CONFIG_DIR || ~/.config/openclaw/`
+- File naming: kebab-case
+- Test files: `*.test.js` in `test/unit/`
+
+---
+
+### Task 1: Create `test/e2e/persist.js` — Result Persistence Module
+
+**Files:**
+- Create: `test/e2e/persist.js`
+
+**Step 1: Write the persist module**
+
+This module provides four functions: `saveResult`, `getLatest`, `getHistory`, `detectRegression`. It stores results as timestamped JSON files in `<configDir>/test-results/` with a `latest.json` that is a regular file copy (not symlink — avoids cross-platform issues).
+
+```js
+/**
+ * E2E Test Result Persistence
+ *
+ * Stores test results as timestamped JSON in ~/.config/openclaw/test-results/.
+ * Provides history retrieval and regression detection.
+ *
+ * A2A-42: Local-first result storage — no external dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// A2A-42: Default config dir matches src/lib/config.js resolution.
+// Accept configDir parameter for testability (reviewer feedback: module-level
+// constants prevent testing the null-path without subprocess gymnastics).
+const DEFAULT_CONFIG_DIR = process.env.A2A_CONFIG_DIR ||
+  process.env.OPENCLAW_CONFIG_DIR ||
+  path.join(process.env.HOME || '/tmp', '.config', 'openclaw');
+
+const MAX_HISTORY = 20;
+
+function resolveDir(configDir) {
+  const base = configDir || DEFAULT_CONFIG_DIR;
+  return {
+    resultsDir: path.join(base, 'test-results'),
+    latestFile: path.join(base, 'test-results', 'latest.json')
+  };
+}
+
+// Module-level defaults for callers that don't pass configDir
+const RESULTS_DIR = resolveDir().resultsDir;
+const LATEST_FILE = resolveDir().latestFile;
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Save a test report result to disk.
+ * Writes a timestamped file and updates latest.json.
+ * Prunes history beyond MAX_HISTORY entries.
+ *
+ * @param {object} report - Output from TestReport.toJSON()
+ * @returns {{ file: string, latest: string, regression: object }}
+ */
+function saveResult(report, options = {}) {
+  const { resultsDir, latestFile } = resolveDir(options.configDir);
+  ensureDir(resultsDir);
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const filename = `result-${ts}.json`;
+  const filepath = path.join(resultsDir, filename);
+
+  // A2A-42: Detect regression before writing, so we can include it in the saved result
+  const previous = getLatest(options);
+  const regression = previous ? detectRegression(report, previous) : {
+    detected: false,
+    newFailures: [],
+    fixedTests: []
+  };
+
+  const enriched = { ...report, regression };
+  const json = JSON.stringify(enriched, null, 2);
+
+  // A2A-42: Atomic write via tmp+rename — matches pattern from src/lib/config.js:290
+  // Prevents truncated reads if the server reads latest.json mid-write.
+  const tmpTimestamped = filepath + '.tmp';
+  fs.writeFileSync(tmpTimestamped, json);
+  fs.renameSync(tmpTimestamped, filepath);
+
+  const tmpLatest = latestFile + '.tmp';
+  fs.writeFileSync(tmpLatest, json);
+  fs.renameSync(tmpLatest, latestFile);
+
+  pruneHistory(options);
+
+  return { file: filepath, latest: latestFile, regression };
+}
+
+/**
+ * Read the most recent test result.
+ * @returns {object|null}
+ */
+function getLatest(options = {}) {
+  const { latestFile } = resolveDir(options.configDir);
+  if (!fs.existsSync(latestFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(latestFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the last N results, newest first.
+ * @param {number} [limit=20]
+ * @returns {object[]}
+ */
+function getHistory(limit = MAX_HISTORY, options = {}) {
+  const { resultsDir } = resolveDir(options.configDir);
+  if (!fs.existsSync(resultsDir)) return [];
+
+  const files = fs.readdirSync(resultsDir)
+    .filter(f => f.startsWith('result-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, Math.max(1, limit));
+
+  return files.map(f => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(resultsDir, f), 'utf8'));
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+/**
+ * Compare current vs previous result for regressions.
+ * A regression is a step that passed before but fails now.
+ * A fix is a step that failed before but passes now.
+ *
+ * @param {object} current - Current report JSON
+ * @param {object} previous - Previous report JSON
+ * @returns {{ detected: boolean, newFailures: string[], fixedTests: string[] }}
+ */
+function detectRegression(current, previous) {
+  const prevSteps = new Map();
+  for (const step of (previous.steps || [])) {
+    prevSteps.set(step.name, step.status);
+  }
+
+  const newFailures = [];
+  const fixedTests = [];
+
+  for (const step of (current.steps || [])) {
+    const prevStatus = prevSteps.get(step.name);
+    if (!prevStatus) continue; // new step, not a regression
+    if (step.status === 'fail' && prevStatus === 'pass') {
+      newFailures.push(step.name);
+    }
+    if (step.status === 'pass' && prevStatus === 'fail') {
+      fixedTests.push(step.name);
+    }
+  }
+
+  return {
+    detected: newFailures.length > 0,
+    newFailures,
+    fixedTests
+  };
+}
+
+/**
+ * Remove old result files beyond MAX_HISTORY.
+ */
+function pruneHistory(options = {}) {
+  const { resultsDir } = resolveDir(options.configDir);
+  if (!fs.existsSync(resultsDir)) return;
+
+  const files = fs.readdirSync(resultsDir)
+    .filter(f => f.startsWith('result-') && f.endsWith('.json'))
+    .sort();
+
+  while (files.length > MAX_HISTORY) {
+    const oldest = files.shift();
+    try {
+      fs.unlinkSync(path.join(resultsDir, oldest));
+    } catch {
+      // best effort
+    }
+  }
+}
+
+module.exports = {
+  saveResult,
+  getLatest,
+  getHistory,
+  detectRegression,
+  RESULTS_DIR,
+  LATEST_FILE,
+  MAX_HISTORY,
+  resolveDir
+};
+```
+
+**Step 2: Commit**
+
+```bash
+git add test/e2e/persist.js
+git commit -m "feat(A2A-42): add E2E result persistence module"
+```
+
+---
+
+### Task 2: Unit Tests for `persist.js`
+
+**Files:**
+- Create: `test/unit/persist.test.js`
+
+**Step 1: Write the tests**
+
+```js
+/**
+ * Unit tests for test/e2e/persist.js
+ *
+ * Uses configDir parameter for isolation — no env var hacks.
+ * Each test gets a fresh temp directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { saveResult, getLatest, getHistory, detectRegression, resolveDir } = require('../e2e/persist');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'persist-test-'));
+}
+
+function makeReport(overrides = {}) {
+  return {
+    name: 'E2E Orchestrator',
+    status: overrides.status || 'passed',
+    startedAt: Date.now() - 500,
+    finishedAt: Date.now(),
+    duration: 500,
+    summary: { passed: 8, failed: 0, skipped: 0, total: 8 },
+    steps: overrides.steps || [
+      { name: 'Create harness', status: 'pass', timestamp: Date.now() },
+      { name: 'Start servers', status: 'pass', timestamp: Date.now() },
+      { name: 'Ping both agents', status: 'pass', timestamp: Date.now() },
+      { name: 'Create tokens', status: 'pass', timestamp: Date.now() },
+      { name: 'Exchange invites', status: 'pass', timestamp: Date.now() },
+      { name: 'B calls A', status: 'pass', timestamp: Date.now() },
+      { name: 'A calls B', status: 'pass', timestamp: Date.now() },
+      { name: 'Verify response integrity', status: 'pass', timestamp: Date.now() }
+    ],
+    ...overrides
+  };
+}
+
+module.exports = ({ test, assert }) => {
+  test('saveResult creates results directory and files', () => {
+    const configDir = makeTmpDir();
+    const report = makeReport();
+    const result = saveResult(report, { configDir });
+
+    assert.ok(fs.existsSync(result.file), 'Should create timestamped file');
+    assert.ok(fs.existsSync(result.latest), 'Should create latest.json');
+
+    const saved = JSON.parse(fs.readFileSync(result.file, 'utf8'));
+    assert.equal(saved.status, 'passed');
+    assert.equal(saved.summary.passed, 8);
+    assert.ok(saved.regression, 'Should include regression field');
+    assert.equal(saved.regression.detected, false);
+  });
+
+  test('getLatest returns the most recent result', () => {
+    const configDir = makeTmpDir();
+    const report = makeReport({ duration: 999 });
+    saveResult(report, { configDir });
+    const latest = getLatest({ configDir });
+    assert.ok(latest, 'Should return a result');
+    assert.equal(latest.duration, 999);
+  });
+
+  test('getLatest returns null when no results exist', () => {
+    const configDir = makeTmpDir();
+    const latest = getLatest({ configDir });
+    assert.equal(latest, null, 'Should return null for empty directory');
+  });
+
+  test('getHistory returns results newest first', () => {
+    const configDir = makeTmpDir();
+    for (let i = 0; i < 3; i++) {
+      saveResult(makeReport({ duration: 100 + i }), { configDir });
+    }
+    const history = getHistory(10, { configDir });
+    assert.ok(history.length >= 3, 'Should have at least 3 results');
+    assert.ok(history[0].duration >= history[history.length - 1].duration,
+      'Should be sorted newest first');
+  });
+
+  test('getHistory returns empty array for missing directory', () => {
+    const configDir = makeTmpDir();
+    const history = getHistory(10, { configDir });
+    assert.equal(history.length, 0, 'Should return empty array');
+  });
+
+  test('detectRegression identifies new failures', () => {
+    const previous = makeReport();
+    const current = makeReport({
+      status: 'failed',
+      steps: [
+        { name: 'Create harness', status: 'pass', timestamp: Date.now() },
+        { name: 'Start servers', status: 'fail', timestamp: Date.now() },
+        { name: 'Ping both agents', status: 'pass', timestamp: Date.now() }
+      ]
+    });
+
+    const result = detectRegression(current, previous);
+    assert.equal(result.detected, true);
+    assert.ok(result.newFailures.includes('Start servers'));
+    assert.equal(result.fixedTests.length, 0);
+  });
+
+  test('detectRegression identifies fixed tests', () => {
+    const previous = makeReport({
+      steps: [
+        { name: 'Create harness', status: 'pass', timestamp: Date.now() },
+        { name: 'Start servers', status: 'fail', timestamp: Date.now() }
+      ]
+    });
+    const current = makeReport({
+      steps: [
+        { name: 'Create harness', status: 'pass', timestamp: Date.now() },
+        { name: 'Start servers', status: 'pass', timestamp: Date.now() }
+      ]
+    });
+
+    const result = detectRegression(current, previous);
+    assert.equal(result.detected, false);
+    assert.ok(result.fixedTests.includes('Start servers'));
+  });
+
+  test('pruneHistory keeps only MAX_HISTORY files', () => {
+    const configDir = makeTmpDir();
+    for (let i = 0; i < 25; i++) {
+      saveResult(makeReport({ duration: i }), { configDir });
+    }
+
+    const { resultsDir } = resolveDir(configDir);
+    const files = fs.readdirSync(resultsDir)
+      .filter(f => f.startsWith('result-') && f.endsWith('.json'));
+
+    assert.ok(files.length <= 20, `Should have at most 20 files, got ${files.length}`);
+  });
+
+  test('saveResult uses atomic write (tmp+rename)', () => {
+    const configDir = makeTmpDir();
+    const report = makeReport();
+    const result = saveResult(report, { configDir });
+
+    // No .tmp files should remain after write
+    const { resultsDir } = resolveDir(configDir);
+    const tmpFiles = fs.readdirSync(resultsDir).filter(f => f.endsWith('.tmp'));
+    assert.equal(tmpFiles.length, 0, 'No .tmp files should remain after atomic write');
+  });
+};
+```
+
+**Step 2: Run tests**
+
+```bash
+node test/run.js --filter persist
+```
+
+Expected: All persist tests pass.
+
+**Step 3: Commit**
+
+```bash
+git add test/unit/persist.test.js
+git commit -m "test(A2A-42): add unit tests for E2E result persistence"
+```
+
+---
+
+### Task 3: Add `--persist` Flag to Orchestrator
+
+**Files:**
+- Modify: `test/e2e/orchestrate.js`
+
+**Step 1: Add persist flag handling**
+
+After line 18 (`const jsonOutput = args.includes('--json');`), add:
+
+```js
+const persistResults = args.includes('--persist');
+```
+
+Insert after `report.finish();` (line 238) and before the `// Output report` comment (line 240). The insertion point is inside `main()` after the `finally` block closes, at the same brace depth as `report.finish()`. The new code goes between line 238 (`report.finish();`) and line 240 (`// Output report`). Add:
+
+```js
+  // A2A-42: Persist results to local storage for regression tracking
+  if (persistResults) {
+    try {
+      const { saveResult } = require('./persist');
+      const persisted = saveResult(report.toJSON());
+      if (!jsonOutput) {
+        process.stderr.write(`Results saved to ${persisted.file}\n`);
+      }
+      if (persisted.regression.detected) {
+        process.stderr.write(`⚠ REGRESSION DETECTED: ${persisted.regression.newFailures.join(', ')}\n`);
+      }
+      if (persisted.regression.fixedTests.length > 0) {
+        process.stderr.write(`✓ Fixed: ${persisted.regression.fixedTests.join(', ')}\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`Warning: Failed to persist results: ${err.message}\n`);
+    }
+  }
+```
+
+Also update the usage comment at the top to document the new flag:
+
+```
+ * Usage:
+ *   node test/e2e/orchestrate.js                # markdown report to stderr
+ *   node test/e2e/orchestrate.js --json          # JSON report to stdout
+ *   node test/e2e/orchestrate.js --persist        # save results to disk
+ *   node test/e2e/orchestrate.js --json --persist  # both
+ *   node test/e2e/orchestrate.js --verbose        # verbose output
+```
+
+**Step 2: Verify it works manually**
+
+```bash
+node test/e2e/orchestrate.js --json --persist 2>/dev/null | head -5
+ls ~/.config/openclaw/test-results/
+```
+
+Expected: JSON output, and `test-results/` directory with `latest.json` and a timestamped file.
+
+**Step 3: Run the full test suite**
+
+```bash
+npm test
+```
+
+Expected: 328 passing, 2 failing (same pre-existing failures).
+
+**Step 4: Commit**
+
+```bash
+git add test/e2e/orchestrate.js
+git commit -m "feat(A2A-42): add --persist flag to E2E orchestrator"
+```
+
+---
+
+### Task 4: Create `scripts/run-e2e.sh` — Cron/CI Wrapper
+
+**Files:**
+- Create: `scripts/run-e2e.sh`
+
+**Step 1: Write the wrapper script**
+
+```bash
+#!/usr/bin/env bash
+# A2A-42: Cron/CI wrapper for E2E test orchestrator.
+# Runs orchestration, persists results, optionally alerts on failure.
+#
+# Usage:
+#   scripts/run-e2e.sh              # run + persist
+#   scripts/run-e2e.sh --alert      # run + persist + alert on failure
+#
+# Cron example (every 6 hours):
+#   0 */6 * * * /root/a2acalling/scripts/run-e2e.sh --alert >> /var/log/a2a-e2e.log 2>&1
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+ALERT_SCRIPT="/root/maestro/scripts/alert.sh"
+ALERT_ON_FAILURE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --alert) ALERT_ON_FAILURE=true ;;
+  esac
+done
+
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting E2E orchestration..."
+
+cd "$PROJECT_DIR"
+
+# A2A-42: Run orchestrator with JSON output and persistence.
+# stdout (JSON) goes to /dev/null; stderr (regression messages, logs) passes through
+# so cron log captures warnings like "REGRESSION DETECTED: ..."
+if node test/e2e/orchestrate.js --json --persist > /dev/null; then
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] E2E: PASSED"
+  exit 0
+else
+  EXIT_CODE=$?
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] E2E: FAILED (exit $EXIT_CODE)"
+
+  if [ "$ALERT_ON_FAILURE" = true ] && [ -x "$ALERT_SCRIPT" ]; then
+    "$ALERT_SCRIPT" error "E2E test failure detected — check ~/.config/openclaw/test-results/latest.json"
+  fi
+
+  exit "$EXIT_CODE"
+fi
+```
+
+**Step 2: Make it executable**
+
+```bash
+chmod +x scripts/run-e2e.sh
+```
+
+**Step 3: Test it runs**
+
+```bash
+scripts/run-e2e.sh
+echo $?
+```
+
+Expected: exit 0 with "PASSED" message.
+
+**Step 4: Commit**
+
+```bash
+git add scripts/run-e2e.sh
+git commit -m "feat(A2A-42): add cron/CI wrapper script for E2E tests"
+```
+
+---
+
+### Task 5: Dashboard API Endpoint — `GET /dashboard/api/test-results`
+
+**Files:**
+- Modify: `src/routes/dashboard.js` (add endpoint inside `createDashboardApiRouter`, after the `/logs/stats` route ~line 884)
+
+**Step 1: Add the endpoint**
+
+At the top of the `createDashboardApiRouter` function (after `const context = buildContext(options);` on line 449), add the persist require with a try/catch so it degrades gracefully in installed-package environments where test/e2e/ doesn't exist:
+
+```js
+  // A2A-42: Load E2E persist layer for Health tab. Gracefully null if not available
+  // (e.g., installed as npm package without test files).
+  let persistModule = null;
+  try {
+    persistModule = require(path.join(__dirname, '..', '..', 'test', 'e2e', 'persist'));
+  } catch {
+    // test/e2e/persist.js not available — Health tab will show "no results"
+  }
+```
+
+Then add this route after the `router.get('/logs/stats', ...)` block (around line 884):
+
+```js
+  // A2A-42: Serve E2E test results for the Health tab.
+  // Reads from local persist layer — no external dependencies.
+  router.get('/test-results', (req, res) => {
+    if (!persistModule) {
+      return res.json({
+        success: true,
+        latest: null,
+        history: [],
+        has_results: false,
+        message: 'Test results module not available'
+      });
+    }
+
+    const latest = persistModule.getLatest();
+    const limit = Math.min(20, Math.max(1, Number.parseInt(req.query.limit || '10', 10) || 10));
+    const history = persistModule.getHistory(limit);
+
+    return res.json({
+      success: true,
+      latest,
+      history: history.map(r => ({
+        status: r.status,
+        duration: r.duration,
+        startedAt: r.startedAt,
+        finishedAt: r.finishedAt,
+        summary: r.summary,
+        regression: r.regression || null
+      })),
+      has_results: latest !== null
+    });
+  });
+```
+
+**Step 2: Run full test suite**
+
+```bash
+npm test
+```
+
+Expected: 328 passing, 2 failing (same pre-existing).
+
+**Step 3: Commit**
+
+```bash
+git add src/routes/dashboard.js
+git commit -m "feat(A2A-42): add dashboard API endpoint for test results"
+```
+
+---
+
+### Task 6: Dashboard UI — Health Tab
+
+**Files:**
+- Modify: `src/dashboard/public/index.html` (add Health tab)
+- Modify: `src/dashboard/public/app.js` (add Health tab rendering and loader)
+
+**Step 1: Add tab to index.html**
+
+After the Logs tab (`<sl-tab slot="nav" panel="logs">Logs</sl-tab>`) on line 23, add:
+
+```html
+      <sl-tab slot="nav" panel="health">Health</sl-tab>
+```
+
+Before the closing `</sl-tab-group>` (line 257), add the Health panel:
+
+```html
+      <sl-tab-panel name="health">
+        <h2>E2E Health</h2>
+        <sl-card id="health-latest">
+          <p>No test results available. Run <code>node test/e2e/orchestrate.js --persist</code> to generate results.</p>
+        </sl-card>
+        <h3>History</h3>
+        <table id="health-history-table">
+          <thead>
+            <tr>
+              <th>Status</th>
+              <th>Duration</th>
+              <th>Passed</th>
+              <th>Failed</th>
+              <th>Regression</th>
+              <th>Time</th>
+            </tr>
+          </thead>
+          <tbody></tbody>
+        </table>
+      </sl-tab-panel>
+```
+
+**Step 2: Add Health tab JS to app.js**
+
+At the end of `app.js`, before the `bootstrap()` call (around line 2138), add:
+
+```js
+// === Health Tab (A2A-42) ===
+
+// A2A-42: Escape HTML entities for safe innerHTML rendering of step names/errors.
+function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+async function loadHealth() {
+  try {
+    const res = await fetch('./api/test-results');
+    const data = await res.json();
+    renderHealthLatest(data.latest);
+    renderHealthHistory(data.history || []);
+  } catch (err) {
+    renderHealthLatest(null);
+    renderHealthHistory([]);
+  }
+}
+
+function renderHealthLatest(latest) {
+  const card = document.getElementById('health-latest');
+  if (!card) return;
+
+  if (!latest) {
+    card.innerHTML = '<p>No test results available. Run <code>node test/e2e/orchestrate.js --persist</code> to generate.</p>';
+    return;
+  }
+
+  const statusBadge = latest.status === 'passed'
+    ? '<sl-badge variant="success">PASSED</sl-badge>'
+    : '<sl-badge variant="danger">FAILED</sl-badge>';
+
+  const regression = latest.regression;
+  let regressionHtml = '';
+  if (regression && regression.detected) {
+    regressionHtml = `<p><sl-badge variant="warning">REGRESSION</sl-badge> New failures: ${regression.newFailures.join(', ')}</p>`;
+  }
+  if (regression && regression.fixedTests && regression.fixedTests.length > 0) {
+    regressionHtml += `<p><sl-badge variant="success">FIXED</sl-badge> ${regression.fixedTests.join(', ')}</p>`;
+  }
+
+  const ts = latest.finishedAt ? new Date(latest.finishedAt).toLocaleString() : 'unknown';
+  const summary = latest.summary || {};
+
+  card.innerHTML = `
+    <div class="row">
+      <strong>Latest Run</strong> ${statusBadge}
+    </div>
+    <p><strong>Duration:</strong> ${latest.duration || 0}ms &middot;
+       <strong>Passed:</strong> ${summary.passed || 0} &middot;
+       <strong>Failed:</strong> ${summary.failed || 0} &middot;
+       <strong>Skipped:</strong> ${summary.skipped || 0} &middot;
+       <strong>Time:</strong> ${ts}</p>
+    ${regressionHtml}
+    <details>
+      <summary>Steps (${(latest.steps || []).length})</summary>
+      <ul>
+        ${(latest.steps || []).map(s => {
+          const icon = s.status === 'pass' ? '&#x2705;' : s.status === 'fail' ? '&#x274C;' : '&#x23ED;';
+          const err = s.error ? ` — <code>${escapeHtml(String(s.error).slice(0, 120))}</code>` : '';
+          return `<li>${icon} ${escapeHtml(s.name)}${err}</li>`;
+        }).join('')}
+      </ul>
+    </details>
+  `;
+}
+
+function renderHealthHistory(history) {
+  const tbody = document.querySelector('#health-history-table tbody');
+  if (!tbody) return;
+
+  if (!history || history.length === 0) {
+    tbody.innerHTML = '<tr><td colspan="6">No history</td></tr>';
+    return;
+  }
+
+  tbody.innerHTML = history.map(r => {
+    const badge = r.status === 'passed'
+      ? '<sl-badge variant="success" size="small">PASS</sl-badge>'
+      : '<sl-badge variant="danger" size="small">FAIL</sl-badge>';
+    const summary = r.summary || {};
+    const regression = r.regression;
+    const regText = regression && regression.detected
+      ? `<sl-badge variant="warning" size="small">${regression.newFailures.length} new</sl-badge>`
+      : '-';
+    const ts = r.finishedAt ? new Date(r.finishedAt).toLocaleString() : '-';
+    return `<tr>
+      <td>${badge}</td>
+      <td>${r.duration || 0}ms</td>
+      <td>${summary.passed || 0}</td>
+      <td>${summary.failed || 0}</td>
+      <td>${regText}</td>
+      <td>${ts}</td>
+    </tr>`;
+  }).join('');
+}
+```
+
+**Step 3: Register the Health tab in tabLoaders**
+
+In `app.js`, find the `tabLoaders` object (line ~2077) and add:
+
+```js
+  health: loadHealth,
+```
+
+So it becomes:
+
+```js
+const tabLoaders = {
+  contacts: loadContacts,
+  calls: loadCalls,
+  logs: () => { loadLogs(); loadLogStats(); },
+  permissions: () => {},
+  invites: loadInvites,
+  health: loadHealth,
+};
+```
+
+**Step 4: Run full test suite**
+
+```bash
+npm test
+```
+
+Expected: 328 passing, 2 failing (same pre-existing).
+
+**Step 5: Commit**
+
+```bash
+git add src/dashboard/public/index.html src/dashboard/public/app.js
+git commit -m "feat(A2A-42): add Health tab to dashboard with E2E results display"
+```
+
+---
+
+### Task 7: Final Verification & Squash
+
+**Step 1: Run E2E orchestrator with persist to seed data**
+
+```bash
+node test/e2e/orchestrate.js --json --persist > /dev/null 2>&1
+cat ~/.config/openclaw/test-results/latest.json | head -20
+```
+
+Expected: JSON with `status`, `summary`, `regression` fields.
+
+**Step 2: Run full test suite (all tiers)**
+
+```bash
+npm test
+```
+
+Expected: 328 passing, 2 failing (same pre-existing install-skills failures).
+
+**Step 3: Run E2E tier specifically**
+
+```bash
+node test/run.js --e2e
+```
+
+Expected: 51+ passing E2E tests.
+
+**Step 4: Verify diff size**
+
+```bash
+git diff --stat origin/main
+```
+
+Expected: Under 500 lines changed, under 15 files.
+
+**Step 5: Push and open PR**
+
+```bash
+git push origin feature/a2a-42
+```
+
+---
+
+## File Summary
+
+| Action | File | Description |
+|--------|------|-------------|
+| Create | `test/e2e/persist.js` | Result persistence: save, read, history, regression detect |
+| Create | `test/unit/persist.test.js` | Unit tests for persist module |
+| Create | `scripts/run-e2e.sh` | Cron/CI wrapper script |
+| Modify | `test/e2e/orchestrate.js` | Add `--persist` flag |
+| Modify | `src/routes/dashboard.js` | Add `GET /dashboard/api/test-results` endpoint |
+| Modify | `src/dashboard/public/index.html` | Add Health tab |
+| Modify | `src/dashboard/public/app.js` | Add Health tab rendering + register in tabLoaders |
+
+## Acceptance Criteria Traceability
+
+| Criterion | Task |
+|-----------|------|
+| `--json --persist` writes results | Task 1, 3 |
+| `latest.json` reflects most recent run | Task 1 |
+| History with timestamped results (last 20) | Task 1 |
+| Regression detection | Task 1 |
+| `scripts/run-e2e.sh` cron-ready | Task 4 |
+| Dashboard shows latest + trend | Task 5, 6 |
+| Existing 328 tests pass | Task 7 |
+| E2E 51 tests pass | Task 7 |
+| No new npm dependencies | All tasks |
+| Local reporting without Telegram/OpenClaw | Task 1, 4 |

package/package.json

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

package/scripts/install-skills.js

@@ -37,12 +37,19 @@ const SKILL_FILES = [
   // 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
+  // Claude Code slash commands — core (A2A-28)
   { 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' },
+  // Claude Code slash commands — extended (A2A-43)
+  { src: '.claude/commands/a2a-update.md', dest: '.claude/commands/a2a-update.md' },
+  { src: '.claude/commands/a2a-uninstall.md', dest: '.claude/commands/a2a-uninstall.md' },
+  { src: '.claude/commands/a2a-app.md', dest: '.claude/commands/a2a-app.md' },
+  { src: '.claude/commands/a2a-conversations.md', dest: '.claude/commands/a2a-conversations.md' },
+  { src: '.claude/commands/a2a-gui.md', dest: '.claude/commands/a2a-gui.md' },
+  { src: '.claude/commands/a2a-skills.md', dest: '.claude/commands/a2a-skills.md' },
   // Codex agent instructions
   { src: '.codex/AGENTS.md', dest: '.codex/AGENTS.md' }
 ];

package/scripts/run-e2e.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# A2A-42: Cron/CI wrapper for E2E test orchestrator.
+# Runs orchestration, persists results, optionally alerts on failure.
+#
+# Usage:
+#   scripts/run-e2e.sh              # run + persist
+#   scripts/run-e2e.sh --alert      # run + persist + alert on failure
+#
+# Cron example (every 6 hours):
+#   0 */6 * * * /root/a2acalling/scripts/run-e2e.sh --alert >> /var/log/a2a-e2e.log 2>&1
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+ALERT_SCRIPT="/root/maestro/scripts/alert.sh"
+ALERT_ON_FAILURE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --alert) ALERT_ON_FAILURE=true ;;
+  esac
+done
+
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting E2E orchestration..."
+
+cd "$PROJECT_DIR"
+
+# A2A-42: Run orchestrator with JSON output and persistence.
+# stdout (JSON) goes to /dev/null; stderr (regression messages, logs) passes through
+# so cron log captures warnings like "REGRESSION DETECTED: ..."
+if node test/e2e/orchestrate.js --json --persist > /dev/null; then
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] E2E: PASSED"
+  exit 0
+else
+  EXIT_CODE=$?
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] E2E: FAILED (exit $EXIT_CODE)"
+
+  if [ "$ALERT_ON_FAILURE" = true ] && [ -x "$ALERT_SCRIPT" ]; then
+    "$ALERT_SCRIPT" error "E2E test failure detected — check ~/.config/openclaw/test-results/latest.json"
+  fi
+
+  exit "$EXIT_CODE"
+fi

package/src/dashboard/public/app.js

@@ -2080,6 +2080,7 @@ const tabLoaders = {
   logs: () => { loadLogs(); loadLogStats(); },
   permissions: () => {},
   invites: loadInvites,
+  health: loadHealth,
 };
 
 function startPolling() {
@@ -2102,6 +2103,102 @@ function onTabSwitch(tabName) {
   startPolling(); // reset the 5s timer
 }
 
+// === Health Tab (A2A-42) ===
+
+// A2A-42: Escape HTML entities for safe innerHTML rendering of step names/errors.
+function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+async function loadHealth() {
+  try {
+    const data = await request('/test-results');
+    renderHealthLatest(data.latest);
+    renderHealthHistory(data.history || []);
+  } catch (err) {
+    renderHealthLatest(null);
+    renderHealthHistory([]);
+  }
+}
+
+function renderHealthLatest(latest) {
+  const card = document.getElementById('health-latest');
+  if (!card) return;
+
+  if (!latest) {
+    card.innerHTML = '<p>No test results available. Run <code>node test/e2e/orchestrate.js --persist</code> to generate.</p>';
+    return;
+  }
+
+  const statusBadge = latest.status === 'passed'
+    ? '<sl-badge variant="success">PASSED</sl-badge>'
+    : '<sl-badge variant="danger">FAILED</sl-badge>';
+
+  const regression = latest.regression;
+  let regressionHtml = '';
+  if (regression && regression.detected) {
+    regressionHtml = `<p><sl-badge variant="warning">REGRESSION</sl-badge> New failures: ${regression.newFailures.map(escapeHtml).join(', ')}</p>`;
+  }
+  if (regression && regression.fixedTests && regression.fixedTests.length > 0) {
+    regressionHtml += `<p><sl-badge variant="success">FIXED</sl-badge> ${regression.fixedTests.map(escapeHtml).join(', ')}</p>`;
+  }
+
+  const ts = latest.finishedAt ? new Date(latest.finishedAt).toLocaleString() : 'unknown';
+  const summary = latest.summary || {};
+
+  card.innerHTML = `
+    <div class="row">
+      <strong>Latest Run</strong> ${statusBadge}
+    </div>
+    <p><strong>Duration:</strong> ${latest.duration || 0}ms &middot;
+       <strong>Passed:</strong> ${summary.passed || 0} &middot;
+       <strong>Failed:</strong> ${summary.failed || 0} &middot;
+       <strong>Skipped:</strong> ${summary.skipped || 0} &middot;
+       <strong>Time:</strong> ${ts}</p>
+    ${regressionHtml}
+    <details>
+      <summary>Steps (${(latest.steps || []).length})</summary>
+      <ul>
+        ${(latest.steps || []).map(s => {
+          const icon = s.status === 'pass' ? '&#x2705;' : s.status === 'fail' ? '&#x274C;' : '&#x23ED;';
+          const err = s.error ? ` — <code>${escapeHtml(String(s.error).slice(0, 120))}</code>` : '';
+          return `<li>${icon} ${escapeHtml(s.name)}${err}</li>`;
+        }).join('')}
+      </ul>
+    </details>
+  `;
+}
+
+function renderHealthHistory(history) {
+  const tbody = document.querySelector('#health-history-table tbody');
+  if (!tbody) return;
+
+  if (!history || history.length === 0) {
+    tbody.innerHTML = '<tr><td colspan="6">No history</td></tr>';
+    return;
+  }
+
+  tbody.innerHTML = history.map(r => {
+    const badge = r.status === 'passed'
+      ? '<sl-badge variant="success" size="small">PASS</sl-badge>'
+      : '<sl-badge variant="danger" size="small">FAIL</sl-badge>';
+    const summary = r.summary || {};
+    const regression = r.regression;
+    const regText = regression && regression.detected
+      ? `<sl-badge variant="warning" size="small">${regression.newFailures.length} new</sl-badge>`
+      : '-';
+    const ts = r.finishedAt ? new Date(r.finishedAt).toLocaleString() : '-';
+    return `<tr>
+      <td>${badge}</td>
+      <td>${r.duration || 0}ms</td>
+      <td>${summary.passed || 0}</td>
+      <td>${summary.failed || 0}</td>
+      <td>${regText}</td>
+      <td>${ts}</td>
+    </tr>`;
+  }).join('');
+}
+
 async function bootstrap() {
   bindTabs();
   bindContactsActions();

package/src/dashboard/public/index.html

@@ -21,6 +21,7 @@
       <sl-tab slot="nav" panel="permissions">Permissions</sl-tab>
       <sl-tab slot="nav" panel="invites">Invites</sl-tab>
       <sl-tab slot="nav" panel="logs">Logs</sl-tab>
+      <sl-tab slot="nav" panel="health">Health</sl-tab>
 
       <sl-tab-panel name="contacts">
         <h2>Contacts</h2>
@@ -254,6 +255,27 @@
 
         <sl-card id="trace-detail"></sl-card>
       </sl-tab-panel>
+
+      <sl-tab-panel name="health">
+        <h2>E2E Health</h2>
+        <sl-card id="health-latest">
+          <p>No test results available. Run <code>node test/e2e/orchestrate.js --persist</code> to generate results.</p>
+        </sl-card>
+        <h3>History</h3>
+        <table id="health-history-table">
+          <thead>
+            <tr>
+              <th>Status</th>
+              <th>Duration</th>
+              <th>Passed</th>
+              <th>Failed</th>
+              <th>Regression</th>
+              <th>Time</th>
+            </tr>
+          </thead>
+          <tbody></tbody>
+        </table>
+      </sl-tab-panel>
     </sl-tab-group>
 
     <div id="notice"></div>

package/src/routes/dashboard.js

@@ -448,6 +448,16 @@ function createDashboardApiRouter(options = {}) {
   const router = express.Router();
   const context = buildContext(options);
   router.use(express.json());
+
+  // A2A-42: Load E2E persist layer for Health tab. Gracefully null if not available
+  // (e.g., installed as npm package without test files).
+  let persistModule = null;
+  try {
+    persistModule = require(path.join(__dirname, '..', '..', 'test', 'e2e', 'persist'));
+  } catch {
+    // test/e2e/persist.js not available — Health tab will show "no results"
+  }
+
   const ensureDashboardAccess = makeEnsureDashboardAccess(context);
   const writeSseEvent = (res, event) => {
     const eventName = sanitizeString(event?.type || 'message', 80) || 'message';
@@ -883,6 +893,38 @@ function createDashboardApiRouter(options = {}) {
     return res.json({ success: true, stats });
   });
 
+  // A2A-42: Serve E2E test results for the Health tab.
+  // Reads from local persist layer — no external dependencies.
+  router.get('/test-results', (req, res) => {
+    if (!persistModule) {
+      return res.json({
+        success: true,
+        latest: null,
+        history: [],
+        has_results: false,
+        message: 'Test results module not available'
+      });
+    }
+
+    const latest = persistModule.getLatest();
+    const limit = Math.min(20, Math.max(1, Number.parseInt(req.query.limit || '10', 10) || 10));
+    const history = persistModule.getHistory(limit);
+
+    return res.json({
+      success: true,
+      latest,
+      history: history.map(r => ({
+        status: r.status,
+        duration: r.duration,
+        startedAt: r.startedAt,
+        finishedAt: r.finishedAt,
+        summary: r.summary,
+        regression: r.regression || null
+      })),
+      has_results: latest !== null
+    });
+  });
+
   router.get('/debug/call', (req, res) => {
     const traceId = sanitizeString(req.query.trace_id || req.query.traceId || '', 120);
     const conversationId = sanitizeString(req.query.conversation_id || req.query.conversationId || '', 120);