a2acalling 0.6.75 → 0.6.76

package/.claude/worktrees/agent-a5b87d75/docs/plans/2026-02-16-bugfixes-22-24.md

@@ -0,0 +1,246 @@
+# Bugfix Plan: A2A-22 + A2A-24
+
+> **For Claude:** Execute these fixes on branch `fix/bugs-22-23-24` in `/root/a2acalling`
+
+**Goal:** Fix quickstart onboarding gaps (identity, disclosure levels, goals) and surface network warnings during quickstart.
+
+**A2A-23 is already fixed** in commit d3fe14e. This plan covers A2A-22 and A2A-24 only.
+
+---
+
+## Bug A2A-22: Quickstart onboarding gaps
+
+### Fix 1: Disclosure levels inverted on friends/family tiers
+
+**File:** `bin/cli.js` ~line 546-553 (inside `handleDisclosureSubmit`)
+
+**Problem:** Friends and family tiers are set to `disclosure: 'minimal'` when they should be more open than public.
+
+**Fix:** Change disclosure levels to escalate: public→'minimal', friends→'standard', family→'full'.
+
+```javascript
+// BEFORE (broken):
+config.setTier('public', { topics: ..., disclosure: 'public' });
+config.setTier('friends', { topics: ..., disclosure: 'minimal' });
+config.setTier('family', { topics: ..., disclosure: 'minimal' });
+
+// AFTER (fixed):
+config.setTier('public', { topics: ..., disclosure: 'minimal' });
+config.setTier('friends', { topics: ..., disclosure: 'standard' });
+config.setTier('family', { topics: ..., disclosure: 'full' });
+```
+
+**Rationale:** Public tier should be most restrictive (minimal). Friends get more (standard). Family gets full disclosure. This matches the trust hierarchy.
+
+### Fix 2: Extract identity from disclosure submission
+
+**File:** `bin/cli.js` ~line 564-568 (inside `handleDisclosureSubmit`)
+
+**Problem:** Agent name defaults to 'my-agent', owner name is set to agent name. The disclosure manifest often contains the real owner name in `personality_notes` or the submission JSON, but it's never extracted.
+
+**Fix:** After parsing the disclosure JSON, extract identity fields:
+1. Check if the submission JSON has `agent_name` or `owner_name` fields (the extraction prompt should request these)
+2. Fall back to extracting from `personality_notes` (often contains "I'm [Name]" or similar)
+3. Fall back to the OS username
+4. Use extracted values for config and token creation
+
+In `handleDisclosureSubmit`, after line ~527 where `result` is validated, add:
+
+```javascript
+// Extract identity from disclosure submission
+const ownerName = result.owner_name
+  || result.manifest?.owner_name
+  || extractNameFromPersonality(result.manifest?.personality_notes)
+  || process.env.USER
+  || 'Agent Owner';
+
+const agentName = args.flags.name
+  || result.agent_name
+  || config.getAgent().name
+  || process.env.A2A_AGENT_NAME
+  || `${ownerName}'s Agent`;
+
+// Save identity to config
+config.setAgent({ name: agentName, owner_name: ownerName });
+```
+
+Add a helper function (before `handleDisclosureSubmit`):
+
+```javascript
+function extractNameFromPersonality(notes) {
+  if (!notes || typeof notes !== 'string') return null;
+  // Look for patterns like "I'm Ben", "My name is Ben", "Owner: Ben"
+  const patterns = [
+    /(?:I'm|I am|My name is|Name:|Owner:)\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)/,
+    /^([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)\s+(?:is|here|speaking)/
+  ];
+  for (const p of patterns) {
+    const m = notes.match(p);
+    if (m && m[1]) return m[1].trim();
+  }
+  return null;
+}
+```
+
+### Fix 3: Use extracted identity in token creation
+
+**File:** `bin/cli.js` ~line 572-582
+
+**Problem:** Token uses `agentName` as both name and owner, with hardcoded goals.
+
+**Fix:** Use the extracted `ownerName` for the token owner field:
+
+```javascript
+// BEFORE:
+const { token } = store.create({
+  name: agentName,
+  owner: agentName,  // wrong — should be owner name
+  ...
+});
+
+// AFTER:
+const { token } = store.create({
+  name: agentName,
+  owner: ownerName,
+  ...
+});
+```
+
+### Fix 4: Sync disclosure objectives to token goals
+
+**File:** `bin/cli.js` ~line 579
+
+**Problem:** Token goals are hardcoded `['grow-network', 'find-collaborators', 'build-in-public']` instead of derived from disclosure.
+
+**Fix:** Extract objectives from the disclosure manifest and use them as goals:
+
+```javascript
+// Extract goals from disclosure objectives
+const disclosureObjectives = (result.manifest?.objectives || [])
+  .map(o => typeof o === 'string' ? o : (o && o.objective || ''))
+  .map(s => s.trim().toLowerCase().replace(/\s+/g, '-').slice(0, 60))
+  .filter(Boolean);
+
+const tokenGoals = disclosureObjectives.length > 0
+  ? disclosureObjectives.slice(0, 5)
+  : ['grow-network', 'find-collaborators', 'build-in-public'];
+```
+
+Then use `tokenGoals` in the store.create call:
+```javascript
+allowedGoals: tokenGoals,
+```
+
+Also sync goals to tier config:
+```javascript
+config.setTier('public', {
+  topics: getTierTopics(tiersData.public),
+  goals: tokenGoals,
+  disclosure: 'minimal'
+});
+```
+
+### Fix 5: Update extraction prompt to request identity fields
+
+**File:** `src/lib/disclosure.js` — the `buildExtractionPrompt` function
+
+**Problem:** The extraction prompt tells the agent what to scan but doesn't ask for `owner_name` or `agent_name` fields in the JSON output.
+
+**Fix:** Add `owner_name` and `agent_name` to the required JSON schema in the prompt. Look for the JSON structure section and add:
+
+```
+"owner_name": "The human owner's real name (extracted from USER.md, git config, etc.)",
+"agent_name": "The agent's display name (extracted from USER.md or workspace context)",
+```
+
+---
+
+## Bug A2A-24: Surface network warnings during quickstart
+
+### Fix 6: Add connectivity check after server start
+
+**File:** `bin/cli.js` — quickstart command, after server start (~line 2017-2019)
+
+**Problem:** The verify URL is printed but never executed. No connectivity feedback.
+
+**Fix:** After the server starts and the verify URL is printed, actually run the connectivity check:
+
+```javascript
+// After line: console.log(`\n  Verify: curl -s ${verifyUrl}`);
+// Add actual verification:
+const http = require('http');
+const verifyOk = await new Promise(resolve => {
+  const req = http.request({
+    hostname: '127.0.0.1',
+    port: serverPort,
+    path: '/api/a2a/ping',
+    method: 'GET',
+    timeout: 2000
+  }, (res) => {
+    res.resume();
+    resolve(res.statusCode === 200);
+  });
+  req.on('error', () => resolve(false));
+  req.on('timeout', () => { req.destroy(); resolve(false); });
+  req.end();
+});
+
+if (verifyOk) {
+  console.log('  ✅ Local connectivity verified');
+} else {
+  console.log('  ⚠️  Local server check failed — server may still be starting');
+}
+```
+
+### Fix 7: Surface invite-host warnings during quickstart
+
+**File:** `bin/cli.js` — quickstart command, after server start
+
+**Problem:** `resolveInviteHost()` returns warnings about NAT/firewall, but they're only shown during `a2a create`, not during quickstart.
+
+**Fix:** After `publicHost` is set in quickstart, call `resolveInviteHost` and print its warnings:
+
+```javascript
+// After publicHost is determined, resolve and show warnings
+try {
+  const { resolveInviteHost } = require('../src/lib/invite-host');
+  const resolved = await resolveInviteHost({
+    hostname: publicHost,
+    port: serverPort
+  });
+  if (resolved.warnings && resolved.warnings.length) {
+    console.log('\n  ━━━ Network Warnings ━━━');
+    for (const w of resolved.warnings) {
+      console.warn(`  ⚠️  ${w}`);
+    }
+  }
+} catch (_) {}
+```
+
+### Fix 8: Add non-standard port warning with reverse proxy guidance
+
+**File:** `bin/cli.js` — quickstart, already partially handled
+
+**Assessment:** Looking at the code at lines 2008-2014, this is already partially implemented — when the user chooses 'continue' on a non-standard port, it prints a brief reminder about reverse proxy setup. But it could be more prominent.
+
+**Fix:** Enhance the existing warning. After the "Running on port X (non-standard)" message, add:
+
+```javascript
+console.log('');
+console.log('  ⚠️  Remote agents using your invite URL will try port 80 by default.');
+console.log('  Without a reverse proxy, inbound calls on port 80 will fail silently.');
+```
+
+---
+
+## Commit Strategy
+
+1. First commit: A2A-22 fixes (disclosure levels, identity extraction, goals sync)
+2. Second commit: A2A-24 fixes (connectivity check, network warnings)
+3. Run `npm test` after each commit to verify no regressions
+
+## Testing
+
+After all fixes:
+- `npm test` — all 269+ tests must pass
+- Manual verification of the logic changes (the reviewer should trace through the code paths)