a2acalling 0.6.48 → 0.6.49

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,85 @@ 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();
+    }
+  });
+};
+```
+
 ## 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.49",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/src/dashboard/public/app.js

@@ -1,6 +1,7 @@
 const state = {
   settings: null,
   dashboardStatus: null,
+  autoUpdate: null,
   callbookDevices: [],
   contacts: [],
   selectedContactId: null,
@@ -63,6 +64,20 @@ function esc(text) {
     .replaceAll("'", ''');
 }
 
+function formatUpdaterState(stateValue) {
+  const state = String(stateValue || '').trim() || 'unknown';
+  return state.replaceAll('_', ' ');
+}
+
+function updaterPillClass(stateValue) {
+  const state = String(stateValue || '').trim();
+  if (state === 'failed') return 'err';
+  if (state === 'waiting_for_safe_restart' || state === 'checking' || state === 'downloading' || state === 'applying' || state === 'restarting') {
+    return 'warn';
+  }
+  return 'ok';
+}
+
 async function copyText(value) {
   const text = String(value || '');
   if (!text) return false;
@@ -284,7 +299,7 @@ function bindContactsActions() {
     if (!urlEl || !serverNameEl) return;
     if (mineEl && !mineEl.checked) return;
     if (serverNameEl.value.trim()) return;
-    const match = String(urlEl.value || '').trim().match(/^(?:a2a|oclaw):\\/\\/([^/]+)\\//);
+    const match = String(urlEl.value || '').trim().match(/^(?:a2a|oclaw):\/\/([^/]+)\//);
     if (match && match[1]) {
       serverNameEl.value = match[1];
     }
@@ -1035,14 +1050,59 @@ function renderCallbookStatus() {
   `;
 }
 
+function renderAutoUpdateStatus() {
+  const el = document.getElementById('auto-update-status');
+  const toggleBtn = document.getElementById('auto-update-toggle');
+  if (!el) return;
+
+  const au = state.autoUpdate;
+  if (!au) {
+    el.textContent = 'Loading…';
+    if (toggleBtn) toggleBtn.disabled = true;
+    return;
+  }
+
+  const stateText = formatUpdaterState(au.state);
+  const pillClass = updaterPillClass(au.state);
+  const enabled = Boolean(au.enabled);
+  const intervalSec = Number.isFinite(au.interval_ms) ? Math.floor(au.interval_ms / 1000) : null;
+
+  el.innerHTML = `
+    <div><strong>Status:</strong> <span class="status-pill ${pillClass}">${esc(stateText)}</span></div>
+    <div><strong>Enabled:</strong> ${enabled ? 'yes' : 'no'}</div>
+    <div><strong>Current version:</strong> <span class="mono">${esc(au.current_version || '-')}</span></div>
+    <div><strong>Latest version:</strong> <span class="mono">${esc(au.latest_version || '-')}</span></div>
+    <div><strong>Target version:</strong> <span class="mono">${esc(au.target_version || '-')}</span></div>
+    <div><strong>Active calls:</strong> ${esc(String(au.active_calls || 0))}</div>
+    <div><strong>Interval:</strong> ${intervalSec === null ? '-' : `${intervalSec}s`}</div>
+    <div><strong>Last checked:</strong> ${esc(fmtDate(au.last_checked_at))}</div>
+    <div><strong>Last success:</strong> ${esc(fmtDate(au.last_success_at))}</div>
+    ${au.defer_reason ? `<div><strong>Deferred:</strong> ${esc(au.defer_reason)}</div>` : ''}
+    ${au.last_error ? `<div><strong>Error:</strong> <span class="mono">${esc(au.last_error)}</span></div>` : ''}
+  `;
+
+  if (toggleBtn) {
+    toggleBtn.disabled = false;
+    toggleBtn.textContent = enabled ? 'Disable auto-update' : 'Enable auto-update';
+  }
+}
+
 async function loadDashboardStatus(refreshIp = false) {
   const payload = await request(`/status${refreshIp ? '?refresh_ip=true' : ''}`);
   state.dashboardStatus = payload;
+  state.autoUpdate = payload.auto_update || state.autoUpdate;
   renderCallbookStatus();
+  renderAutoUpdateStatus();
   renderContacts();
   renderContactDetail();
 }
 
+async function loadAutoUpdateStatus() {
+  const payload = await request('/update/status');
+  state.autoUpdate = payload.auto_update || null;
+  renderAutoUpdateStatus();
+}
+
 function renderCallbookDevices() {
   const tbody = document.querySelector('#callbook-devices-table tbody');
   if (!tbody) return;
@@ -1154,6 +1214,47 @@ function bindCallbookActions() {
   });
 }
 
+function bindAutoUpdateActions() {
+  document.getElementById('auto-update-refresh')?.addEventListener('click', () => {
+    loadAutoUpdateStatus().catch(err => showNotice(err.message));
+  });
+
+  document.getElementById('auto-update-check')?.addEventListener('click', async () => {
+    try {
+      await request('/update/check', { method: 'POST', body: JSON.stringify({}) });
+      await loadAutoUpdateStatus();
+      showNotice('Update check complete');
+    } catch (err) {
+      showNotice(err.message);
+    }
+  });
+
+  document.getElementById('auto-update-now')?.addEventListener('click', async () => {
+    try {
+      await request('/update/now', { method: 'POST', body: JSON.stringify({}) });
+      await loadAutoUpdateStatus();
+      showNotice('Update triggered');
+    } catch (err) {
+      showNotice(err.message);
+    }
+  });
+
+  document.getElementById('auto-update-toggle')?.addEventListener('click', async () => {
+    const au = state.autoUpdate || {};
+    const nextEnabled = !Boolean(au.enabled);
+    try {
+      await request('/update/config', {
+        method: 'PUT',
+        body: JSON.stringify({ enabled: nextEnabled })
+      });
+      await loadAutoUpdateStatus();
+      showNotice(nextEnabled ? 'Auto-update enabled' : 'Auto-update disabled');
+    } catch (err) {
+      showNotice(err.message);
+    }
+  });
+}
+
 function renderInvites() {
   const tbody = document.querySelector('#invites-table tbody');
   tbody.innerHTML = '';
@@ -1247,6 +1348,7 @@ async function bootstrap() {
   bindContactsActions();
   bindSettingsActions();
   bindCallbookActions();
+  bindAutoUpdateActions();
   bindInviteActions();
   bindRefreshButtons();
 
@@ -1254,6 +1356,7 @@ async function bootstrap() {
     await Promise.all([
       loadSettings(),
       loadDashboardStatus(),
+      loadAutoUpdateStatus(),
       loadCallbookDevices(),
       loadContacts(),
       loadCalls(),
@@ -1262,6 +1365,10 @@ async function bootstrap() {
       loadLogs()
     ]);
     showNotice('Dashboard loaded');
+
+    setInterval(() => {
+      loadAutoUpdateStatus().catch(() => {});
+    }, 10000);
   } catch (err) {
     showNotice(err.message);
   }

package/src/dashboard/public/index.html

@@ -171,6 +171,15 @@
       <h3>Remote Callbook</h3>
       <div id="callbook-status" class="card"></div>
 
+      <h3>Auto Update</h3>
+      <div id="auto-update-status" class="card">Loading…</div>
+      <div class="row">
+        <button id="auto-update-refresh" type="button">Refresh</button>
+        <button id="auto-update-check" type="button">Check now</button>
+        <button id="auto-update-now" type="button">Update now</button>
+        <button id="auto-update-toggle" type="button">Disable auto-update</button>
+      </div>
+
       <form id="callbook-provision-form" class="card">
         <div class="row">
           <button type="submit">Create Install Link (24h)</button>

package/src/dashboard/public/style.css

@@ -202,6 +202,33 @@ tr[data-selected="1"] td {
   display: none;
 }
 
+.status-pill {
+  display: inline-block;
+  padding: 0.15rem 0.45rem;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  font-size: 0.78rem;
+  font-weight: 600;
+}
+
+.status-pill.ok {
+  background: #ecfdf3;
+  border-color: #9bd8b8;
+  color: #125934;
+}
+
+.status-pill.warn {
+  background: #fff7e8;
+  border-color: #f1d08e;
+  color: #8a5a00;
+}
+
+.status-pill.err {
+  background: #fff0f1;
+  border-color: #efb1b6;
+  color: #8c1d26;
+}
+
 @media (max-width: 720px) {
   nav {
     overflow-x: auto;