@pingagent/sdk 0.1.0 → 0.1.2

package/bin/pingagent.js

@@ -1,1125 +1,1418 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {
-  PingAgentClient,
-  generateIdentity,
-  saveIdentity,
-  loadIdentity,
-  identityExists,
-  updateStoredToken,
-  ensureTokenValid,
-  LocalStore,
-  ContactManager,
-  HistoryManager,
-  A2AAdapter,
-} from '../dist/index.js';
-import { ERROR_HINTS, SCHEMA_TEXT } from '@pingagent/schemas';
-
-const DEFAULT_SERVER = 'http://localhost:8787';
-const UPGRADE_URL = 'https://pingagent.chat';
-const DEFAULT_IDENTITY_PATH = path.join(os.homedir(), '.pingagent', 'identity.json');
-
-function resolvePath(p) {
-  if (!p) return p;
-  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
-  return p;
-}
-
-function getEffectiveIdentityPath() {
-  const dir = program.opts().identityDir;
-  if (dir) return path.join(resolvePath(dir), 'identity.json');
-  const envPath = process.env.PINGAGENT_IDENTITY_PATH;
-  return envPath ? resolvePath(envPath) : DEFAULT_IDENTITY_PATH;
-}
-
-function getStorePath() {
-  const envStore = process.env.PINGAGENT_STORE_PATH;
-  if (envStore) return resolvePath(envStore);
-  return path.join(path.dirname(getEffectiveIdentityPath()), 'store.db');
-}
-
-function printError(err) {
-  if (!err) return;
-  console.error(`Error: ${err.code ?? 'unknown'} - ${err.message ?? ''}`);
-  const hint = err.hint ?? (err.code && ERROR_HINTS[err.code]);
-  if (hint) console.error(`Hint: ${hint}`);
-  if (err.code && err.code.startsWith('E_PAYWALL_')) {
-    console.error(`Upgrade: ${UPGRADE_URL}`);
-  }
-}
-
-function openStore() {
-  return new LocalStore(getStorePath());
-}
-
-function makeClient(id, identityPath) {
-  const p = identityPath ?? getEffectiveIdentityPath();
-  return new PingAgentClient({
-    serverUrl: id.serverUrl ?? DEFAULT_SERVER,
-    identity: id,
-    accessToken: id.accessToken ?? '',
-    onTokenRefreshed: (token, expiresAt) => updateStoredToken(token, expiresAt, p),
-  });
-}
-
-/** Load identity, proactively refresh token if near/past expiry, then return client. */
-async function getClient() {
-  const identityPath = getEffectiveIdentityPath();
-  let id = loadIdentity(identityPath);
-  await ensureTokenValid(identityPath, id.serverUrl);
-  id = loadIdentity(identityPath);
-  return makeClient(id, identityPath);
-}
-
-const program = new Command();
-program
-  .name('pingagent')
-  .description('PingAgent Chat CLI')
-  .version('0.1.0')
-  .option('--identity-dir <dir>', 'Use identity and store from this directory (e.g. ~/.pingagent/agent1). Overrides PINGAGENT_IDENTITY_PATH for identity file; store is <dir>/store.db unless PINGAGENT_STORE_PATH is set.');
-
-program
-  .command('init')
-  .description('Initialize PingAgent Chat identity')
-  .option('--server <url>', 'Server URL', DEFAULT_SERVER)
-  .option('--token <token>', 'Developer token for production mode')
-  .option('--cursor', 'Auto-configure Cursor MCP')
-  .action(async (opts) => {
-    const identityPath = getEffectiveIdentityPath();
-    if (identityExists(identityPath)) {
-      const existing = loadIdentity(identityPath);
-      console.log(`Identity already exists: ${existing.did}`);
-      return;
-    }
-
-    console.log('PingAgent Chat Setup');
-    console.log('====================');
-    console.log('[1/3] Generating Ed25519 keypair... done');
-
-    const identity = generateIdentity();
-
-    console.log('[2/3] Registering with relay server...');
-    const client = new PingAgentClient({
-      serverUrl: opts.server,
-      identity,
-      accessToken: '',
-    });
-
-    const regRes = await client.register(opts.token);
-    if (!regRes.ok || !regRes.data) {
-      if (regRes.error) printError(regRes.error);
-      else console.error('Registration failed:', regRes.error?.message);
-      process.exit(1);
-    }
-
-    const { did, access_token, expires_ms, mode } = regRes.data;
-    console.log(`      Server: ${opts.server}`);
-    console.log(`      Mode: ${mode}`);
-    console.log(`      Your DID: ${did}`);
-
-    console.log('[3/3] Saving identity... done');
-    saveIdentity(identity, {
-      serverUrl: opts.server,
-      accessToken: access_token,
-      tokenExpiresAt: Date.now() + expires_ms,
-      mode,
-    }, identityPath);
-
-    console.log(`\nReady! Share your DID with agents you want to communicate with.`);
-    if (identityPath !== DEFAULT_IDENTITY_PATH) {
-      console.log(`Identity: ${identityPath}`);
-      console.log(`Store:   ${getStorePath()}`);
-    }
-    console.log(`\nRun 'pingagent doctor' to verify setup.`);
-  });
-
-program
-  .command('doctor')
-  .description('Check identity, token, permissions and server; use --fix to renew token if expired')
-  .option('--fix', 'Attempt to fix token if expired (runs renew-token)')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    const identityPath = getEffectiveIdentityPath();
-    const storePath = getStorePath();
-    const identityDir = path.dirname(identityPath);
-    const storeDir = path.dirname(storePath);
-    const issues = [];
-    const ok = [];
-
-    if (!identityExists(identityPath)) {
-      issues.push({ check: 'identity', message: 'No identity found. Run: pingagent init' });
-    } else {
-      ok.push('identity');
-      try {
-        const id = loadIdentity(identityPath);
-        const now = Date.now();
-        const expiresAt = id.tokenExpiresAt;
-        const graceMs = 5 * 60 * 1000;
-        if (expiresAt == null || expiresAt <= now + graceMs) {
-          issues.push({ check: 'token', message: 'Token expired or expiring soon. Run: pingagent renew-token', fixable: true });
-        } else {
-          ok.push('token');
-        }
-      } catch (e) {
-        issues.push({ check: 'identity', message: `Cannot load identity: ${e.message}` });
-      }
-    }
-
-    try {
-      if (!fs.existsSync(identityDir)) {
-        fs.mkdirSync(identityDir, { recursive: true, mode: 0o700 });
-      }
-      const testFile = path.join(identityDir, '.pingagent-write-test');
-      fs.writeFileSync(testFile, '');
-      fs.unlinkSync(testFile);
-      ok.push('identity_dir_writable');
-    } catch (e) {
-      issues.push({ check: 'identity_dir', message: `Identity directory not writable: ${identityDir} (${e.message})` });
-    }
-
-    try {
-      if (!fs.existsSync(storeDir)) {
-        fs.mkdirSync(storeDir, { recursive: true, mode: 0o700 });
-      }
-      const store = openStore();
-      store.close();
-      ok.push('store_writable');
-    } catch (e) {
-      issues.push({ check: 'store', message: `Store path not writable: ${storePath} (${e.message})` });
-    }
-
-    if (identityExists(identityPath)) {
-      const id = loadIdentity(identityPath);
-      const serverUrl = (id.serverUrl ?? DEFAULT_SERVER).replace(/\/$/, '');
-      try {
-        const res = await fetch(`${serverUrl}/.well-known/agent.json`, { method: 'GET' });
-        if (res.ok) ok.push('server_reachable');
-        else issues.push({ check: 'server', message: `Server returned ${res.status}: ${serverUrl}` });
-      } catch (e) {
-        issues.push({ check: 'server', message: `Server not reachable: ${serverUrl} (${e.message})` });
-      }
-    }
-
-    if (opts.fix && issues.some(i => i.fixable)) {
-      const tokenIssue = issues.find(i => i.check === 'token');
-      if (tokenIssue && identityExists(identityPath)) {
-        const existing = loadIdentity(identityPath);
-        const serverUrl = existing.serverUrl ?? DEFAULT_SERVER;
-
-        // Try refresh first, then fallback to re-register
-        const refreshed = await ensureTokenValid(identityPath, serverUrl);
-        if (refreshed) {
-          console.log('Fixed: token refreshed (via /v1/auth/refresh).');
-          issues.splice(issues.findIndex(i => i.check === 'token'), 1);
-          ok.push('token');
-        } else {
-          const client = new PingAgentClient({ serverUrl, identity: existing, accessToken: '' });
-          const regRes = await client.register();
-          if (regRes.ok && regRes.data) {
-            saveIdentity(existing, {
-              serverUrl,
-              accessToken: regRes.data.access_token,
-              tokenExpiresAt: Date.now() + regRes.data.expires_ms,
-              mode: regRes.data.mode,
-            }, identityPath);
-            console.log('Fixed: token renewed (via re-register).');
-            issues.splice(issues.findIndex(i => i.check === 'token'), 1);
-            ok.push('token');
-          }
-        }
-      }
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({ ok, issues }, null, 2));
-      process.exit(issues.length > 0 ? 1 : 0);
-    }
-
-    if (ok.length) console.log('OK:', ok.join(', '));
-    if (issues.length) {
-      for (const i of issues) console.error(`Issue [${i.check}]: ${i.message}`);
-      if (issues.some(i => i.fixable)) console.error('\nRun with --fix to attempt token renewal.');
-      process.exit(1);
-    }
-    console.log('All checks passed.');
-  });
-
-program
-  .command('renew-token')
-  .description('Renew access token using existing identity (keeps DID and keypair). Tries /v1/auth/refresh first, falls back to re-register.')
-  .option('--profile <name>', 'Use profile from ~/.pingagent/<name> (e.g. agent1, receiver)')
-  .option('--server <url>', 'Server URL (defaults to identity server or localhost:8787)')
-  .option('--token <token>', 'Developer token for production mode (optional)')
-  .action(async (opts) => {
-    const identityPath = program.opts().identityDir
-      ? path.join(resolvePath(program.opts().identityDir), 'identity.json')
-      : opts.profile
-        ? path.join(os.homedir(), '.pingagent', opts.profile, 'identity.json')
-        : getEffectiveIdentityPath();
-    if (!identityExists(identityPath)) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH) first.');
-      process.exit(1);
-    }
-
-    const existing = loadIdentity(identityPath);
-    const serverUrl = opts.server ?? existing.serverUrl ?? DEFAULT_SERVER;
-
-    // Step 1: try lightweight /v1/auth/refresh (works within grace period)
-    console.log('Attempting token refresh via /v1/auth/refresh...');
-    const refreshed = await ensureTokenValid(identityPath, serverUrl);
-    if (refreshed) {
-      const updated = loadIdentity(identityPath);
-      console.log('Token refreshed successfully (via /v1/auth/refresh).');
-      console.log(`DID: ${updated.did}`);
-      console.log(`Server: ${serverUrl}`);
-      return;
-    }
-
-    // Step 2: fallback to re-register with existing keypair
-    console.log('Refresh not possible (token beyond grace period). Falling back to re-register...');
-    const client = new PingAgentClient({
-      serverUrl,
-      identity: existing,
-      accessToken: '',
-    });
-
-    const regRes = await client.register(opts.token);
-    if (!regRes.ok || !regRes.data) {
-      if (regRes.error) printError(regRes.error);
-      else console.error('Token renewal failed:', regRes.error?.message);
-      process.exit(1);
-    }
-
-    const { access_token, expires_ms, mode } = regRes.data;
-    saveIdentity(existing, {
-      serverUrl,
-      accessToken: access_token,
-      tokenExpiresAt: Date.now() + expires_ms,
-      mode,
-    }, identityPath);
-
-    console.log('Token renewed successfully (via re-register).');
-    console.log(`DID: ${existing.did}`);
-    console.log(`Server: ${serverUrl}`);
-  });
-
-program
-  .command('status')
-  .description('Show current identity and subscription status')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.log('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      return;
-    }
-    const client = await getClient();
-    const id = loadIdentity(getEffectiveIdentityPath());
-
-    const tokenStatus = id.tokenExpiresAt && id.tokenExpiresAt > Date.now() ? 'valid' : 'expired';
-
-    if (opts.json) {
-      const out = { did: id.did, device_id: id.deviceId, server: id.serverUrl ?? null, mode: id.mode ?? null, token: tokenStatus };
-      const subRes = await client.getSubscription();
-      if (subRes.ok && subRes.data) {
-        out.tier = subRes.data.tier;
-        out.usage = subRes.data.usage;
-        out.limits = subRes.data.limits;
-      }
-      console.log(JSON.stringify(out, null, 2));
-      return;
-    }
-
-    console.log(`DID: ${id.did}`);
-    console.log(`Device: ${id.deviceId}`);
-    console.log(`Server: ${id.serverUrl ?? 'not set'}`);
-    console.log(`Mode: ${id.mode ?? 'unknown'}`);
-    console.log(`Token: ${tokenStatus}`);
-
-    const subRes = await client.getSubscription();
-    if (subRes.ok && subRes.data) {
-      const d = subRes.data;
-      console.log(`Tier: ${d.tier}`);
-      console.log(`Relay: ${d.usage.relay_today} / ${d.usage.relay_limit} today`);
-      console.log(`Artifact: ${(d.usage.artifact_bytes / 1024 / 1024).toFixed(2)} MB / ${d.limits.artifact_storage_mb} MB`);
-      console.log(`Alias: ${d.usage.alias_count} / ${d.usage.alias_limit}`);
-      if (d.billing_primary_did && d.billing_primary_did !== id.did) {
-        console.log(`Billing: linked device (primary: ${d.billing_primary_did})`);
-        console.log('  Subscription managed on primary. Use primary to create link codes or manage billing.');
-      } else if (d.linked_device_count > 0) {
-        console.log(`Billing: primary device (${d.linked_device_count} linked)`);
-      }
-      if (d.usage.relay_today >= d.usage.relay_limit) {
-        console.log(`\nQuota reached. Upgrade: ${UPGRADE_URL}`);
-      }
-    } else {
-      console.log('Subscription: (unable to fetch - check server and token)');
-    }
-  });
-
-program
-  .command('send')
-  .description('Send a task to a remote agent')
-  .requiredOption('--to <did>', 'Target DID or alias')
-  .requiredOption('--task <title>', 'Task title')
-  .option('--description <desc>', 'Task description')
-  .option('--wait', 'Wait for result')
-  .option('--timeout <seconds>', 'Timeout in seconds', '120')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-
-    let targetDid = opts.to;
-    if (targetDid.startsWith('@')) {
-      const resolved = await client.resolveAlias(targetDid);
-      if (!resolved.ok || !resolved.data) {
-        if (resolved.error) printError(resolved.error);
-        else console.error(`Could not resolve alias: ${targetDid}`);
-        process.exit(1);
-      }
-      targetDid = resolved.data.did;
-    }
-
-    let trusted = false;
-    if (opts.wait) {
-      const result = await client.sendTaskAndWait(
-        targetDid,
-        { title: opts.task, description: opts.description },
-        { timeoutMs: parseInt(opts.timeout) * 1000 },
-      );
-      trusted = result.status === 'ok';
-      if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(`Task ${result.task_id}: ${result.status}`);
-        if (result.result?.summary) console.log(`Summary: ${result.result.summary}`);
-        if (result.error) printError(result.error);
-        console.log(`Elapsed: ${result.elapsed_ms}ms`);
-      }
-    } else {
-      const openRes = await client.openConversation(targetDid);
-      if (!openRes.ok || !openRes.data) {
-        if (openRes.error) printError(openRes.error);
-        else console.error('Failed to open conversation');
-        process.exit(1);
-      }
-      trusted = openRes.data.trusted;
-
-      const { v7: uuidv7 } = await import('uuid');
-      const sendRes = await client.sendTask(openRes.data.conversation_id, {
-        task_id: `t_${uuidv7()}`,
-        title: opts.task,
-        description: opts.description,
-      });
-
-      if (!sendRes.ok) {
-        if (sendRes.error) printError(sendRes.error);
-        else console.error('Failed to send task');
-        process.exit(1);
-      }
-
-      if (opts.json) {
-        console.log(JSON.stringify(sendRes, null, 2));
-      } else {
-        console.log(`Sent: ${sendRes.data?.message_id} (seq: ${sendRes.data?.seq})`);
-      }
-    }
-
-    const store = openStore();
-    try {
-      const mgr = new ContactManager(store);
-      if (!mgr.get(targetDid)) {
-        mgr.add({ did: targetDid, trusted, notes: 'Added via pingagent send' });
-      }
-    } finally {
-      store.close();
-    }
-  });
-
-program
-  .command('chat')
-  .description('Send a text message (same as MCP pingagent_chat). Use "send" for tasks.')
-  .requiredOption('--to <did>', 'Target DID or alias')
-  .requiredOption('--message <text>', 'Message text')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-
-    let targetDid = opts.to;
-    if (targetDid.startsWith('@')) {
-      const resolved = await client.resolveAlias(targetDid);
-      if (!resolved.ok || !resolved.data) {
-        if (resolved.error) printError(resolved.error);
-        else console.error(`Could not resolve alias: ${targetDid}`);
-        process.exit(1);
-      }
-      targetDid = resolved.data.did;
-    }
-
-    const openRes = await client.openConversation(targetDid);
-    if (!openRes.ok || !openRes.data) {
-      if (openRes.error) printError(openRes.error);
-      else console.error('Failed to open conversation');
-      process.exit(1);
-    }
-
-    const store = openStore();
-    try {
-      const mgr = new ContactManager(store);
-      if (!mgr.get(targetDid)) {
-        mgr.add({
-          did: targetDid,
-          trusted: openRes.data.trusted,
-          conversation_id: openRes.data.conversation_id,
-          notes: openRes.data.trusted ? 'Added via pingagent chat' : 'Added via pingagent chat (pending)',
-        });
-      }
-    } finally {
-      store.close();
-    }
-
-    if (!openRes.data.trusted) {
-      await client.sendContactRequest(openRes.data.conversation_id, opts.message);
-      if (opts.json) {
-        console.log(JSON.stringify({ sent: 'contact_request', conversation_id: openRes.data.conversation_id }));
-      } else {
-        console.log('Contact request sent with your message. They need to approve before further messages are delivered.');
-      }
-      return;
-    }
-
-    const sendRes = await client.sendMessage(openRes.data.conversation_id, SCHEMA_TEXT, { text: opts.message });
-    if (!sendRes.ok) {
-      if (sendRes.error) printError(sendRes.error);
-      else console.error('Failed to send message');
-      process.exit(1);
-    }
-    if (opts.json) {
-      console.log(JSON.stringify({ message_id: sendRes.data?.message_id, seq: sendRes.data?.seq }));
-    } else {
-      console.log(`Sent: ${sendRes.data?.message_id} (seq: ${sendRes.data?.seq})`);
-    }
-  });
-
-program
-  .command('inbox')
-  .description('Fetch inbox messages')
-  .requiredOption('--conversation <id>', 'Conversation ID')
-  .option('--since-seq <n>', 'Since sequence number', '0')
-  .option('--limit <n>', 'Limit', '20')
-  .option('--box <box>', "Inbox box: ready, strangers, or all (merge both; use 'all' if Web messages don't show)", 'ready')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-    const sinceSeq = parseInt(opts.sinceSeq);
-    const limit = parseInt(opts.limit);
-
-    let messages = [];
-    let hasMore = false;
-    if (opts.box === 'all') {
-      const seen = new Set();
-      for (const box of ['ready', 'strangers']) {
-        const res = await client.fetchInbox(opts.conversation, { sinceSeq, limit, box });
-        if (res.ok && res.data) {
-          for (const m of res.data.messages) {
-            const id = m.message_id ?? `${opts.conversation}-${m.seq}`;
-            if (!seen.has(id)) { seen.add(id); messages.push(m); }
-          }
-          if (res.data.has_more) hasMore = true;
-        }
-      }
-      messages.sort((a, b) => (a.ts_ms ?? 0) - (b.ts_ms ?? 0));
-    } else {
-      const res = await client.fetchInbox(opts.conversation, { sinceSeq, limit, box: opts.box });
-      if (!res.ok) {
-        if (res.error) printError(res.error);
-        else console.error('Failed to fetch inbox');
-        process.exit(1);
-      }
-      messages = res.data?.messages ?? [];
-      hasMore = res.data?.has_more ?? false;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, data: { messages, has_more: hasMore } }, null, 2));
-    } else {
-      for (const msg of messages) {
-        console.log(`[${msg.seq}] ${msg.schema} from ${msg.sender_did?.slice(0, 20)}... (${msg.status})`);
-      }
-      console.log(`${messages.length} message(s), has_more: ${hasMore}`);
-    }
-  });
-
-program
-  .command('approve')
-  .description('Approve a contact request')
-  .argument('<conversation_id>', 'Pending DM conversation ID')
-  .action(async (conversationId) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-
-    const res = await client.approveContact(conversationId);
-    if (res.ok && res.data) {
-      console.log(`Approved. DM conversation: ${res.data.dm_conversation_id}`);
-    } else {
-      if (res.error) printError(res.error);
-      else console.error('Failed:', res.error?.message);
-      process.exit(1);
-    }
-  });
-
-program
-  .command('cancel')
-  .description('Cancel a running task')
-  .argument('<conversation_id>', 'Conversation ID')
-  .argument('<task_id>', 'Task ID')
-  .action(async (conversationId, taskId) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-
-    const res = await client.cancelTask(conversationId, taskId);
-    if (res.ok && res.data) {
-      console.log(`Task state: ${res.data.task_state}`);
-    } else {
-      if (res.error) printError(res.error);
-      else console.error('Cancel failed');
-      process.exit(1);
-    }
-  });
-
-program
-  .command('resolve')
-  .description('Resolve alias to DID')
-  .argument('<alias>', 'Alias (e.g. @my/bot)')
-  .action(async (alias) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-
-    const res = await client.resolveAlias(alias);
-    if (res.ok && res.data) {
-      console.log(`${res.data.alias} → ${res.data.did}`);
-    } else {
-      if (res.error) printError(res.error);
-      else console.error('Not found');
-      process.exit(1);
-    }
-  });
-
-// === Contacts ===
-const contacts = program.command('contacts').description('Manage local contacts');
-
-contacts
-  .command('list')
-  .description('List saved contacts')
-  .option('--tag <tag>', 'Filter by tag')
-  .option('--trusted', 'Show only trusted contacts')
-  .option('--json', 'Output as JSON')
-  .action((opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    const list = mgr.list({ tag: opts.tag, trusted: opts.trusted ? true : undefined });
-    if (opts.json) {
-      console.log(JSON.stringify(list, null, 2));
-    } else if (list.length === 0) {
-      console.log('No contacts found.');
-    } else {
-      for (const c of list) {
-        const name = c.display_name ?? c.alias ?? c.did.slice(0, 30) + '...';
-        const trust = c.trusted ? ' [trusted]' : '';
-        console.log(`  ${name}${trust}  ${c.did}`);
-      }
-      console.log(`\n${list.length} contact(s)`);
-    }
-    store.close();
-  });
-
-contacts
-  .command('add')
-  .description('Add a contact')
-  .argument('<did>', 'Agent DID')
-  .option('--alias <alias>', 'Alias (e.g. @my/bot)')
-  .option('--name <name>', 'Display name')
-  .option('--notes <notes>', 'Notes')
-  .option('--tag <tag>', 'Tag')
-  .action((did, opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    mgr.add({
-      did,
-      alias: opts.alias,
-      display_name: opts.name,
-      notes: opts.notes,
-      trusted: false,
-      tags: opts.tag ? [opts.tag] : undefined,
-    });
-    console.log(`Contact added: ${did}`);
-    store.close();
-  });
-
-contacts
-  .command('remove')
-  .description('Remove a contact')
-  .argument('<did>', 'Agent DID')
-  .action((did) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    if (mgr.remove(did)) {
-      console.log(`Contact removed: ${did}`);
-    } else {
-      console.log('Contact not found.');
-    }
-    store.close();
-  });
-
-contacts
-  .command('update')
-  .description('Update a contact')
-  .argument('<did>', 'Agent DID')
-  .option('--alias <alias>', 'Alias')
-  .option('--name <name>', 'Display name')
-  .option('--notes <notes>', 'Notes')
-  .option('--tag <tag>', 'Tag (replaces existing tags)')
-  .action((did, opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    const updates = {};
-    if (opts.alias) updates.alias = opts.alias;
-    if (opts.name) updates.display_name = opts.name;
-    if (opts.notes) updates.notes = opts.notes;
-    if (opts.tag) updates.tags = [opts.tag];
-    const result = mgr.update(did, updates);
-    if (result) {
-      console.log(`Contact updated: ${did}`);
-    } else {
-      console.log('Contact not found.');
-    }
-    store.close();
-  });
-
-contacts
-  .command('search')
-  .description('Search contacts')
-  .argument('<query>', 'Search query')
-  .option('--json', 'Output as JSON')
-  .action((query, opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    const results = mgr.search(query);
-    if (opts.json) {
-      console.log(JSON.stringify(results, null, 2));
-    } else if (results.length === 0) {
-      console.log('No contacts match.');
-    } else {
-      for (const c of results) {
-        console.log(`  ${c.display_name ?? c.alias ?? c.did.slice(0, 30)}  ${c.did}`);
-      }
-      console.log(`\n${results.length} match(es)`);
-    }
-    store.close();
-  });
-
-contacts
-  .command('export')
-  .description('Export contacts')
-  .option('--format <format>', 'json or csv', 'json')
-  .option('--output <file>', 'Output file path')
-  .action((opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    const data = mgr.export(opts.format);
-    if (opts.output) {
-      fs.writeFileSync(opts.output, data);
-      console.log(`Exported to ${opts.output}`);
-    } else {
-      console.log(data);
-    }
-    store.close();
-  });
-
-contacts
-  .command('import')
-  .description('Import contacts from file')
-  .argument('<file>', 'File to import')
-  .option('--format <format>', 'json or csv', 'json')
-  .action((file, opts) => {
-    const store = openStore();
-    const mgr = new ContactManager(store);
-    const data = fs.readFileSync(file, 'utf-8');
-    const result = mgr.import(data, opts.format);
-    console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`);
-    store.close();
-  });
-
-// === History ===
-const history = program.command('history').description('Manage local chat history');
-
-history
-  .command('conversations')
-  .description('List conversations with local history')
-  .option('--json', 'Output as JSON')
-  .action((opts) => {
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const convos = mgr.listConversations();
-    if (opts.json) {
-      console.log(JSON.stringify(convos, null, 2));
-    } else if (convos.length === 0) {
-      console.log('No local history.');
-    } else {
-      for (const c of convos) {
-        const date = new Date(c.last_message_at).toISOString();
-        console.log(`  ${c.conversation_id}  ${c.message_count} msg(s)  last: ${date}`);
-      }
-    }
-    store.close();
-  });
-
-history
-  .command('list')
-  .description('List messages in a conversation')
-  .argument('<conversation_id>', 'Conversation ID')
-  .option('--limit <n>', 'Limit', '50')
-  .option('--json', 'Output as JSON')
-  .action((conversationId, opts) => {
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const messages = mgr.list(conversationId, { limit: parseInt(opts.limit) });
-    if (opts.json) {
-      console.log(JSON.stringify(messages, null, 2));
-    } else if (messages.length === 0) {
-      console.log('No messages found.');
-    } else {
-      for (const m of messages) {
-        const dir = m.direction === 'sent' ? '→' : '←';
-        const text = m.payload?.text ?? m.payload?.title ?? m.schema;
-        console.log(`  ${dir} [${m.seq ?? '-'}] ${m.schema}  ${text}`);
-      }
-      console.log(`\n${messages.length} message(s)`);
-    }
-    store.close();
-  });
-
-history
-  .command('sync')
-  .description('Sync messages from server')
-  .argument('<conversation_id>', 'Conversation ID')
-  .option('--full', 'Full sync from beginning')
-  .action(async (conversationId, opts) => {
-    if (!identityExists(getEffectiveIdentityPath())) {
-      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
-      process.exit(1);
-    }
-    const client = await getClient();
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const result = await mgr.syncFromServer(client, conversationId, { full: opts.full });
-    console.log(`Synced ${result.synced} message(s)`);
-    store.close();
-  });
-
-history
-  .command('search')
-  .description('Search message history')
-  .argument('<query>', 'Search query')
-  .option('--conversation <id>', 'Limit to conversation')
-  .option('--json', 'Output as JSON')
-  .action((query, opts) => {
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const results = mgr.search(query, { conversationId: opts.conversation });
-    if (opts.json) {
-      console.log(JSON.stringify(results, null, 2));
-    } else if (results.length === 0) {
-      console.log('No messages match.');
-    } else {
-      for (const m of results) {
-        const dir = m.direction === 'sent' ? '→' : '←';
-        const text = m.payload?.text ?? m.payload?.title ?? m.schema;
-        console.log(`  ${dir} ${m.conversation_id.slice(0, 15)}  ${text}`);
-      }
-      console.log(`\n${results.length} match(es)`);
-    }
-    store.close();
-  });
-
-history
-  .command('export')
-  .description('Export chat history')
-  .option('--conversation <id>', 'Conversation ID (all if omitted)')
-  .option('--format <format>', 'json or csv', 'json')
-  .option('--output <file>', 'Output file path')
-  .action((opts) => {
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const data = mgr.export({ conversationId: opts.conversation, format: opts.format });
-    if (opts.output) {
-      fs.writeFileSync(opts.output, data);
-      console.log(`Exported to ${opts.output}`);
-    } else {
-      console.log(data);
-    }
-    store.close();
-  });
-
-history
-  .command('delete')
-  .description('Delete history for a conversation')
-  .argument('<conversation_id>', 'Conversation ID')
-  .action((conversationId) => {
-    const store = openStore();
-    const mgr = new HistoryManager(store);
-    const count = mgr.delete(conversationId);
-    console.log(`Deleted ${count} message(s)`);
-    store.close();
-  });
-
-// === A2A (Agent-to-Agent Protocol) ===
-const a2a = program.command('a2a').description('Interact with external A2A-compatible agents');
-
-a2a
-  .command('discover')
-  .description('Fetch and display an external agent\'s AgentCard')
-  .argument('<url>', 'Agent URL (e.g. https://agent.example.com)')
-  .option('--json', 'Output as JSON')
-  .action(async (url, opts) => {
-    const adapter = new A2AAdapter({ agentUrl: url });
-    const card = await adapter.getAgentCard();
-    if (opts.json) {
-      console.log(JSON.stringify(card, null, 2));
-    } else {
-      console.log(`Agent: ${card.name}`);
-      console.log(`Description: ${card.description}`);
-      console.log(`URL: ${card.url}`);
-      console.log(`Version: ${card.version} (protocol ${card.protocolVersion})`);
-      if (card.provider) console.log(`Provider: ${card.provider.organization}`);
-      console.log(`Capabilities: streaming=${card.capabilities.streaming ?? false}, push=${card.capabilities.pushNotifications ?? false}`);
-      console.log(`Skills:`);
-      for (const s of card.skills) {
-        console.log(`  [${s.id}] ${s.name}: ${s.description}`);
-        if (s.tags.length) console.log(`    tags: ${s.tags.join(', ')}`);
-      }
-    }
-  });
-
-a2a
-  .command('send')
-  .description('Send a task to an external A2A agent')
-  .argument('<url>', 'Agent URL')
-  .requiredOption('--task <title>', 'Task title/prompt')
-  .option('--description <desc>', 'Task description')
-  .option('--wait', 'Wait for task completion')
-  .option('--timeout <seconds>', 'Timeout in seconds', '120')
-  .option('--auth <token>', 'Bearer token for the remote agent')
-  .option('--json', 'Output as JSON')
-  .action(async (url, opts) => {
-    const adapter = new A2AAdapter({
-      agentUrl: url,
-      authToken: opts.auth,
-    });
-
-    const result = await adapter.sendTask({
-      title: opts.task,
-      description: opts.description,
-      wait: opts.wait,
-      timeoutMs: parseInt(opts.timeout) * 1000,
-    });
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Task ID: ${result.taskId}`);
-      console.log(`State: ${result.state}`);
-      if (result.summary) console.log(`Summary: ${result.summary}`);
-      if (result.output) console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
-    }
-  });
-
-a2a
-  .command('status')
-  .description('Get task status from an external A2A agent')
-  .argument('<url>', 'Agent URL')
-  .requiredOption('--task-id <id>', 'Task ID')
-  .option('--auth <token>', 'Bearer token')
-  .option('--json', 'Output as JSON')
-  .action(async (url, opts) => {
-    const adapter = new A2AAdapter({
-      agentUrl: url,
-      authToken: opts.auth,
-    });
-
-    const result = await adapter.getTaskStatus(opts.taskId);
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Task ID: ${result.taskId}`);
-      console.log(`State: ${result.state}`);
-      if (result.summary) console.log(`Summary: ${result.summary}`);
-    }
-  });
-
-a2a
-  .command('cancel')
-  .description('Cancel a task on an external A2A agent')
-  .argument('<url>', 'Agent URL')
-  .requiredOption('--task-id <id>', 'Task ID')
-  .option('--auth <token>', 'Bearer token')
-  .action(async (url, opts) => {
-    const adapter = new A2AAdapter({
-      agentUrl: url,
-      authToken: opts.auth,
-    });
-    const result = await adapter.cancelTask(opts.taskId);
-    console.log(`Task ${result.taskId}: ${result.state}`);
-  });
-
-// === Billing ===
-const billing = program.command('billing').description('Manage billing group (primary + linked devices)');
-
-billing
-  .command('link-code')
-  .description('Generate a link code for adding a device to your subscription (primary only)')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    const client = await getClient();
-    const res = await client.createBillingLinkCode();
-    if (!res.ok) {
-      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
-        console.error(`Error: ${res.error?.message ?? 'Failed to create link code'}`);
-        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
-      }
-      process.exit(1);
-    }
-    if (opts.json) {
-      console.log(JSON.stringify(res.data, null, 2));
-    } else {
-      console.log(`Link code: ${res.data.code}`);
-      console.log(`Expires in ${res.data.expires_in_seconds}s`);
-      console.log(`\nRun on the new device:\n  pingagent billing link --code ${res.data.code}`);
-    }
-  });
-
-billing
-  .command('link')
-  .description('Link this device to a primary subscription using a link code')
-  .requiredOption('--code <code>', 'Link code from primary device')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    const client = await getClient();
-    const res = await client.redeemBillingLink(opts.code);
-    if (!res.ok) {
-      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
-        console.error(`Error: ${res.error?.message ?? 'Failed to link device'}`);
-        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
-      }
-      process.exit(1);
-    }
-    if (opts.json) {
-      console.log(JSON.stringify(res.data, null, 2));
-    } else {
-      console.log(`Linked to primary: ${res.data.primary_did}`);
-      console.log('This device now shares the primary subscription tier and quotas.');
-    }
-  });
-
-billing
-  .command('linked-devices')
-  .description('List all devices in your billing group')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    const client = await getClient();
-    const res = await client.getLinkedDevices();
-    if (!res.ok) {
-      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
-        console.error(`Error: ${res.error?.message ?? 'Failed to get linked devices'}`);
-      }
-      process.exit(1);
-    }
-    if (opts.json) {
-      console.log(JSON.stringify(res.data, null, 2));
-    } else {
-      const d = res.data;
-      console.log(`Primary DID: ${d.primary_did}${d.is_primary ? ' (this device)' : ''}`);
-      if (d.linked_dids.length === 0) {
-        console.log('No linked devices.');
-      } else {
-        console.log(`Linked devices (${d.linked_dids.length}):`);
-        for (const did of d.linked_dids) {
-          const marker = did === client.getDid() ? ' (this device)' : '';
-          console.log(`  - ${did}${marker}`);
-        }
-      }
-    }
-  });
-
-billing
-  .command('unlink')
-  .description('Remove a linked device from your billing group (primary only)')
-  .requiredOption('--did <did>', 'DID of the device to unlink')
-  .option('--json', 'Output as JSON')
-  .action(async (opts) => {
-    const client = await getClient();
-    const res = await client.unlinkBillingDevice(opts.did);
-    if (!res.ok) {
-      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
-        console.error(`Error: ${res.error?.message ?? 'Failed to unlink device'}`);
-        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
-      }
-      process.exit(1);
-    }
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true }, null, 2));
-    } else {
-      console.log(`Unlinked: ${opts.did}`);
-      console.log('The device will revert to ghost tier.');
-    }
-  });
-
-program
-  .command('web')
-  .description('Start local web UI for debugging and audit. By default scans ~/.pingagent for profiles; use --identity-dir to lock to one profile.')
-  .option('--port <port>', 'Port for the web server', '3846')
-  .action(async (opts) => {
-    const serverUrl = process.env.PINGAGENT_SERVER_URL || DEFAULT_SERVER;
-    const port = parseInt(opts.port, 10) || 3846;
-    const identityDir = program.opts().identityDir;
-    const { startWebServer } = await import('../dist/web-server.js');
-    if (identityDir) {
-      const identityPath = path.join(resolvePath(identityDir), 'identity.json');
-      if (!identityExists(identityPath)) {
-        console.error('No identity found at', identityPath, '. Run: pingagent init');
-        process.exit(1);
-      }
-      const storePath = process.env.PINGAGENT_STORE_PATH
-        ? resolvePath(process.env.PINGAGENT_STORE_PATH)
-        : path.join(resolvePath(identityDir), 'store.db');
-      await startWebServer({ fixedIdentityPath: identityPath, fixedStorePath: storePath, serverUrl, port });
-    } else {
-      const rootDir = process.env.PINGAGENT_ROOT_DIR || path.join(os.homedir(), '.pingagent');
-      await startWebServer({ rootDir, serverUrl, port });
-    }
-  });
-
-program.parse();
+import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  PingAgentClient,
+  generateIdentity,
+  saveIdentity,
+  loadIdentity,
+  identityExists,
+  updateStoredToken,
+  ensureTokenValid,
+  LocalStore,
+  ContactManager,
+  HistoryManager,
+  A2AAdapter,
+} from '../dist/index.js';
+import { ERROR_HINTS, SCHEMA_TEXT } from '@pingagent/schemas';
+
+const DEFAULT_SERVER = 'http://localhost:8787';
+const UPGRADE_URL = 'https://pingagent.chat';
+const DEFAULT_IDENTITY_PATH = path.join(os.homedir(), '.pingagent', 'identity.json');
+
+function resolvePath(p) {
+  if (!p) return p;
+  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+function getEffectiveIdentityPath() {
+  const dir = program.opts().identityDir;
+  if (dir) return path.join(resolvePath(dir), 'identity.json');
+  const envPath = process.env.PINGAGENT_IDENTITY_PATH;
+  return envPath ? resolvePath(envPath) : DEFAULT_IDENTITY_PATH;
+}
+
+/** Resolve identity path from command opts (--profile) or global (--identity-dir) or default. */
+function getIdentityPathForCommand(opts) {
+  if (opts && opts.profile) return path.join(os.homedir(), '.pingagent', opts.profile, 'identity.json');
+  return getEffectiveIdentityPath();
+}
+
+function getStorePath(identityPath) {
+  if (process.env.PINGAGENT_STORE_PATH) return resolvePath(process.env.PINGAGENT_STORE_PATH);
+  const base = identityPath != null ? path.dirname(identityPath) : path.dirname(getEffectiveIdentityPath());
+  return path.join(base, 'store.db');
+}
+
+function printError(err) {
+  if (!err) return;
+  console.error(`Error: ${err.code ?? 'unknown'} - ${err.message ?? ''}`);
+  const hint = err.hint ?? (err.code && ERROR_HINTS[err.code]);
+  if (hint) console.error(`Hint: ${hint}`);
+  if (err.code && err.code.startsWith('E_PAYWALL_')) {
+    console.error(`Upgrade: ${UPGRADE_URL}`);
+  }
+}
+
+function openStore(identityPath) {
+  return new LocalStore(getStorePath(identityPath));
+}
+
+/** Format timestamp for display: human-readable by default, raw ms when --raw. */
+function formatTs(tsMs, raw) {
+  if (raw) return String(tsMs);
+  if (tsMs == null || Number.isNaN(tsMs)) return '-';
+  return new Date(tsMs).toLocaleString();
+}
+
+function makeClient(id, identityPath) {
+  const p = identityPath ?? getEffectiveIdentityPath();
+  return new PingAgentClient({
+    serverUrl: id.serverUrl ?? DEFAULT_SERVER,
+    identity: id,
+    accessToken: id.accessToken ?? '',
+    onTokenRefreshed: (token, expiresAt) => updateStoredToken(token, expiresAt, p),
+  });
+}
+
+/** Load identity, proactively refresh token if near/past expiry, then return client. */
+async function getClient(identityPath) {
+  const p = identityPath ?? getEffectiveIdentityPath();
+  let id = loadIdentity(p);
+  await ensureTokenValid(p, id.serverUrl);
+  id = loadIdentity(p);
+  return makeClient(id, p);
+}
+
+const program = new Command();
+program
+  .name('pingagent')
+  .description('PingAgent Chat CLI')
+  .version('0.1.0')
+  .option('--identity-dir <dir>', 'Use identity and store from this directory (e.g. ~/.pingagent/agent1). Overrides PINGAGENT_IDENTITY_PATH for identity file; store is <dir>/store.db unless PINGAGENT_STORE_PATH is set.')
+  .option('--raw', 'Show raw timestamps (milliseconds) instead of human-readable in non-JSON output.');
+
+program
+  .command('init')
+  .description('Initialize PingAgent Chat identity')
+  .option('--server <url>', 'Server URL', DEFAULT_SERVER)
+  .option('--token <token>', 'Developer token for production mode')
+  .option('--profile <name>', 'Profile name: use ~/.pingagent/<name>/ for identity and set server display_name to <name>')
+  .option('--bio <text>', 'Set profile bio on the server after registration')
+  .option('--cursor', 'Auto-configure Cursor MCP')
+  .action(async (opts) => {
+    const identityPath = opts.profile
+      ? path.join(os.homedir(), '.pingagent', opts.profile, 'identity.json')
+      : getEffectiveIdentityPath();
+    const withProfile = opts.profile != null || opts.bio != null;
+
+    if (identityExists(identityPath)) {
+      const existing = loadIdentity(identityPath);
+      console.log(`Identity already exists: ${existing.did}`);
+      if (withProfile) {
+        await ensureTokenValid(identityPath, existing.serverUrl ?? opts.server);
+        const id = loadIdentity(identityPath);
+        const client = makeClient(id, identityPath);
+        const profilePayload = {};
+        if (opts.profile != null) profilePayload.display_name = opts.profile;
+        if (opts.bio != null) profilePayload.bio = opts.bio;
+        console.log('Updating profile (display_name, bio)...');
+        const profileRes = await client.updateProfile(profilePayload);
+        if (!profileRes.ok) {
+          if (profileRes.error) printError(profileRes.error);
+          else console.error('Profile update failed.');
+          process.exit(1);
+        }
+        console.log('Profile updated.');
+      }
+      return;
+    }
+
+    const totalSteps = withProfile ? 4 : 3;
+
+    console.log('PingAgent Chat Setup');
+    console.log('====================');
+    console.log(`[1/${totalSteps}] Generating Ed25519 keypair... done`);
+
+    const identity = generateIdentity();
+
+    console.log(`[2/${totalSteps}] Registering with relay server...`);
+    const client = new PingAgentClient({
+      serverUrl: opts.server,
+      identity,
+      accessToken: '',
+    });
+
+    const regRes = await client.register(opts.token);
+    if (!regRes.ok || !regRes.data) {
+      if (regRes.error) printError(regRes.error);
+      else console.error('Registration failed:', regRes.error?.message);
+      process.exit(1);
+    }
+
+    const { did, access_token, expires_ms, mode } = regRes.data;
+    console.log(`      Server: ${opts.server}`);
+    console.log(`      Mode: ${mode}`);
+    console.log(`      Your DID: ${did}`);
+
+    console.log(`[3/${totalSteps}] Saving identity... done`);
+    saveIdentity(identity, {
+      serverUrl: opts.server,
+      accessToken: access_token,
+      tokenExpiresAt: Date.now() + expires_ms,
+      mode,
+    }, identityPath);
+
+    if (withProfile) {
+      const profilePayload = {};
+      if (opts.profile != null) profilePayload.display_name = opts.profile;
+      if (opts.bio != null) profilePayload.bio = opts.bio;
+      console.log(`[4/${totalSteps}] Setting profile (display_name, bio)...`);
+      const clientWithToken = new PingAgentClient({
+        serverUrl: opts.server,
+        identity,
+        accessToken: access_token,
+      });
+      const profileRes = await clientWithToken.updateProfile(profilePayload);
+      if (!profileRes.ok) {
+        if (profileRes.error) printError(profileRes.error);
+        else console.error('Profile update failed (identity was saved).');
+      } else {
+        console.log('      done');
+      }
+    }
+
+    console.log(`\nReady! Share your DID with agents you want to communicate with.`);
+    if (identityPath !== DEFAULT_IDENTITY_PATH) {
+      console.log(`Identity: ${identityPath}`);
+      console.log(`Store:   ${getStorePath()}`);
+    }
+    console.log(`\nRun 'pingagent doctor' to verify setup.`);
+  });
+
+program
+  .command('doctor')
+  .description('Check identity, token, permissions and server; use --fix to renew token if expired')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--fix', 'Attempt to fix token if expired (runs renew-token)')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    const storePath = getStorePath(identityPath);
+    const identityDir = path.dirname(identityPath);
+    const storeDir = path.dirname(storePath);
+    const issues = [];
+    const ok = [];
+
+    if (!identityExists(identityPath)) {
+      issues.push({ check: 'identity', message: 'No identity found. Run: pingagent init' });
+    } else {
+      ok.push('identity');
+      try {
+        const id = loadIdentity(identityPath);
+        const now = Date.now();
+        const expiresAt = id.tokenExpiresAt;
+        const graceMs = 5 * 60 * 1000;
+        if (expiresAt == null || expiresAt <= now + graceMs) {
+          issues.push({ check: 'token', message: 'Token expired or expiring soon. Run: pingagent renew-token', fixable: true });
+        } else {
+          ok.push('token');
+        }
+      } catch (e) {
+        issues.push({ check: 'identity', message: `Cannot load identity: ${e.message}` });
+      }
+    }
+
+    try {
+      if (!fs.existsSync(identityDir)) {
+        fs.mkdirSync(identityDir, { recursive: true, mode: 0o700 });
+      }
+      const testFile = path.join(identityDir, '.pingagent-write-test');
+      fs.writeFileSync(testFile, '');
+      fs.unlinkSync(testFile);
+      ok.push('identity_dir_writable');
+    } catch (e) {
+      issues.push({ check: 'identity_dir', message: `Identity directory not writable: ${identityDir} (${e.message})` });
+    }
+
+    try {
+      if (!fs.existsSync(storeDir)) {
+        fs.mkdirSync(storeDir, { recursive: true, mode: 0o700 });
+      }
+      const store = openStore(identityPath);
+      store.close();
+      ok.push('store_writable');
+    } catch (e) {
+      issues.push({ check: 'store', message: `Store path not writable: ${storePath} (${e.message})` });
+    }
+
+    if (identityExists(identityPath)) {
+      const id = loadIdentity(identityPath);
+      const serverUrl = (id.serverUrl ?? DEFAULT_SERVER).replace(/\/$/, '');
+      try {
+        const res = await fetch(`${serverUrl}/.well-known/agent.json`, { method: 'GET' });
+        if (res.ok) ok.push('server_reachable');
+        else issues.push({ check: 'server', message: `Server returned ${res.status}: ${serverUrl}` });
+      } catch (e) {
+        issues.push({ check: 'server', message: `Server not reachable: ${serverUrl} (${e.message})` });
+      }
+    }
+
+    if (opts.fix && issues.some(i => i.fixable)) {
+      const tokenIssue = issues.find(i => i.check === 'token');
+      if (tokenIssue && identityExists(identityPath)) {
+        const existing = loadIdentity(identityPath);
+        const serverUrl = existing.serverUrl ?? DEFAULT_SERVER;
+
+        // Try refresh first, then fallback to re-register
+        const refreshed = await ensureTokenValid(identityPath, serverUrl);
+        if (refreshed) {
+          console.log('Fixed: token refreshed (via /v1/auth/refresh).');
+          issues.splice(issues.findIndex(i => i.check === 'token'), 1);
+          ok.push('token');
+        } else {
+          const client = new PingAgentClient({ serverUrl, identity: existing, accessToken: '' });
+          const regRes = await client.register();
+          if (regRes.ok && regRes.data) {
+            saveIdentity(existing, {
+              serverUrl,
+              accessToken: regRes.data.access_token,
+              tokenExpiresAt: Date.now() + regRes.data.expires_ms,
+              mode: regRes.data.mode,
+            }, identityPath);
+            console.log('Fixed: token renewed (via re-register).');
+            issues.splice(issues.findIndex(i => i.check === 'token'), 1);
+            ok.push('token');
+          }
+        }
+      }
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({ ok, issues }, null, 2));
+      process.exit(issues.length > 0 ? 1 : 0);
+    }
+
+    if (ok.length) console.log('OK:', ok.join(', '));
+    if (issues.length) {
+      for (const i of issues) console.error(`Issue [${i.check}]: ${i.message}`);
+      if (issues.some(i => i.fixable)) console.error('\nRun with --fix to attempt token renewal.');
+      process.exit(1);
+    }
+    console.log('All checks passed.');
+  });
+
+program
+  .command('renew-token')
+  .description('Renew access token using existing identity (keeps DID and keypair). Tries /v1/auth/refresh first, falls back to re-register.')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name> (e.g. agent1, receiver)')
+  .option('--server <url>', 'Server URL (defaults to identity server or localhost:8787)')
+  .option('--token <token>', 'Developer token for production mode (optional)')
+  .action(async (opts) => {
+    const identityPath = program.opts().identityDir
+      ? path.join(resolvePath(program.opts().identityDir), 'identity.json')
+      : opts.profile
+        ? path.join(os.homedir(), '.pingagent', opts.profile, 'identity.json')
+        : getEffectiveIdentityPath();
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH) first.');
+      process.exit(1);
+    }
+
+    const existing = loadIdentity(identityPath);
+    const serverUrl = opts.server ?? existing.serverUrl ?? DEFAULT_SERVER;
+
+    // Step 1: try lightweight /v1/auth/refresh (works within grace period)
+    console.log('Attempting token refresh via /v1/auth/refresh...');
+        const refreshed = await ensureTokenValid(identityPath, serverUrl);
+      if (refreshed) {
+        const updated = loadIdentity(identityPath);
+      console.log('Token refreshed successfully (via /v1/auth/refresh).');
+      console.log(`DID: ${updated.did}`);
+      console.log(`Server: ${serverUrl}`);
+      return;
+    }
+
+    // Step 2: fallback to re-register with existing keypair
+    console.log('Refresh not possible (token beyond grace period). Falling back to re-register...');
+    const client = new PingAgentClient({
+      serverUrl,
+      identity: existing,
+      accessToken: '',
+    });
+
+    const regRes = await client.register(opts.token);
+    if (!regRes.ok || !regRes.data) {
+      if (regRes.error) printError(regRes.error);
+      else console.error('Token renewal failed:', regRes.error?.message);
+      process.exit(1);
+    }
+
+    const { access_token, expires_ms, mode } = regRes.data;
+    saveIdentity(existing, {
+      serverUrl,
+      accessToken: access_token,
+      tokenExpiresAt: Date.now() + expires_ms,
+      mode,
+    }, identityPath);
+
+    console.log('Token renewed successfully (via re-register).');
+    console.log(`DID: ${existing.did}`);
+    console.log(`Server: ${serverUrl}`);
+  });
+
+program
+  .command('status')
+  .description('Show current identity and subscription status')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.log('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      return;
+    }
+    const client = await getClient(identityPath);
+    const id = loadIdentity(identityPath);
+
+    const tokenStatus = id.tokenExpiresAt && id.tokenExpiresAt > Date.now() ? 'valid' : 'expired';
+
+    if (opts.json) {
+      const out = { did: id.did, device_id: id.deviceId, server: id.serverUrl ?? null, mode: id.mode ?? null, token: tokenStatus };
+      const subRes = await client.getSubscription();
+      if (subRes.ok && subRes.data) {
+        out.tier = subRes.data.tier;
+        out.usage = subRes.data.usage;
+        out.limits = subRes.data.limits;
+      }
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+
+    console.log(`DID: ${id.did}`);
+    console.log(`Device: ${id.deviceId}`);
+    console.log(`Server: ${id.serverUrl ?? 'not set'}`);
+    console.log(`Mode: ${id.mode ?? 'unknown'}`);
+    console.log(`Token: ${tokenStatus}`);
+
+    const subRes = await client.getSubscription();
+    if (subRes.ok && subRes.data) {
+      const d = subRes.data;
+      console.log(`Tier: ${d.tier}`);
+      console.log(`Relay: ${d.usage.relay_today} / ${d.usage.relay_limit} today`);
+      console.log(`Artifact: ${(d.usage.artifact_bytes / 1024 / 1024).toFixed(2)} MB / ${d.limits.artifact_storage_mb} MB`);
+      console.log(`Alias: ${d.usage.alias_count} / ${d.usage.alias_limit}`);
+      if (d.billing_primary_did && d.billing_primary_did !== id.did) {
+        console.log(`Billing: linked device (primary: ${d.billing_primary_did})`);
+        console.log('  Subscription managed on primary. Use primary to create link codes or manage billing.');
+      } else if (d.linked_device_count > 0) {
+        console.log(`Billing: primary device (${d.linked_device_count} linked)`);
+      }
+      if (d.usage.relay_today >= d.usage.relay_limit) {
+        console.log(`\nQuota reached. Upgrade: ${UPGRADE_URL}`);
+      }
+    } else {
+      console.log('Subscription: (unable to fetch - check server and token)');
+    }
+  });
+
+program
+  .command('send')
+  .description('Send a task to a remote agent')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--to <did>', 'Target DID or alias')
+  .option('--target <did>', 'Target DID or alias (alias of --to)')
+  .requiredOption('--task <title>', 'Task title')
+  .option('--description <desc>', 'Task description')
+  .option('--wait', 'Wait for result')
+  .option('--timeout <seconds>', 'Timeout in seconds', '120')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    let targetDid = opts.to ?? opts.target;
+    if (!targetDid) {
+      console.error('Provide --to or --target (e.g. --to did:agent:xxx or --to @alias)');
+      process.exit(1);
+    }
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+    if (targetDid.startsWith('@')) {
+      const resolved = await client.resolveAlias(targetDid);
+      if (!resolved.ok || !resolved.data) {
+        if (resolved.error) printError(resolved.error);
+        else console.error(`Could not resolve alias: ${targetDid}`);
+        process.exit(1);
+      }
+      targetDid = resolved.data.did;
+    }
+
+    let trusted = false;
+    if (opts.wait) {
+      const result = await client.sendTaskAndWait(
+        targetDid,
+        { title: opts.task, description: opts.description },
+        { timeoutMs: parseInt(opts.timeout) * 1000 },
+      );
+      trusted = result.status === 'ok';
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Task ${result.task_id}: ${result.status}`);
+        if (result.result?.summary) console.log(`Summary: ${result.result.summary}`);
+        if (result.error) printError(result.error);
+        console.log(`Elapsed: ${result.elapsed_ms}ms`);
+      }
+    } else {
+      const openRes = await client.openConversation(targetDid);
+      if (!openRes.ok || !openRes.data) {
+        if (openRes.error) printError(openRes.error);
+        else console.error('Failed to open conversation');
+        process.exit(1);
+      }
+      trusted = openRes.data.trusted;
+
+      const { v7: uuidv7 } = await import('uuid');
+      const sendRes = await client.sendTask(openRes.data.conversation_id, {
+        task_id: `t_${uuidv7()}`,
+        title: opts.task,
+        description: opts.description,
+      });
+
+      if (!sendRes.ok) {
+        if (sendRes.error) printError(sendRes.error);
+        else console.error('Failed to send task');
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(sendRes, null, 2));
+      } else {
+        console.log(`Sent: ${sendRes.data?.message_id} (seq: ${sendRes.data?.seq})`);
+      }
+    }
+
+    const store = openStore(identityPath);
+    try {
+      const mgr = new ContactManager(store);
+      if (!mgr.get(targetDid)) {
+        mgr.add({ did: targetDid, trusted, notes: 'Added via pingagent send' });
+      }
+    } finally {
+      store.close();
+    }
+  });
+
+program
+  .command('chat')
+  .description('Send a text message (same as MCP pingagent_chat). Use "send" for tasks.')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--to <did>', 'Target DID or alias')
+  .option('--target <did>', 'Target DID or alias (alias of --to)')
+  .requiredOption('--message <text>', 'Message text')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    let targetDid = opts.to ?? opts.target;
+    if (!targetDid) {
+      console.error('Provide --to or --target (e.g. --to did:agent:xxx or --to @alias)');
+      process.exit(1);
+    }
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+    if (targetDid.startsWith('@')) {
+      const resolved = await client.resolveAlias(targetDid);
+      if (!resolved.ok || !resolved.data) {
+        if (resolved.error) printError(resolved.error);
+        else console.error(`Could not resolve alias: ${targetDid}`);
+        process.exit(1);
+      }
+      targetDid = resolved.data.did;
+    }
+
+    const openRes = await client.openConversation(targetDid);
+    if (!openRes.ok || !openRes.data) {
+      if (openRes.error) printError(openRes.error);
+      else console.error('Failed to open conversation');
+      process.exit(1);
+    }
+
+    const store = openStore(identityPath);
+    try {
+      const mgr = new ContactManager(store);
+      if (!mgr.get(targetDid)) {
+        mgr.add({
+          did: targetDid,
+          trusted: openRes.data.trusted,
+          conversation_id: openRes.data.conversation_id,
+          notes: openRes.data.trusted ? 'Added via pingagent chat' : 'Added via pingagent chat (pending)',
+        });
+      }
+    } finally {
+      store.close();
+    }
+
+    if (!openRes.data.trusted) {
+      await client.sendContactRequest(openRes.data.conversation_id, opts.message);
+      if (opts.json) {
+        console.log(JSON.stringify({ sent: 'contact_request', conversation_id: openRes.data.conversation_id }));
+      } else {
+        console.log('Contact request sent with your message. They need to approve before further messages are delivered.');
+      }
+      return;
+    }
+
+    const sendRes = await client.sendMessage(openRes.data.conversation_id, SCHEMA_TEXT, { text: opts.message });
+    if (!sendRes.ok) {
+      if (sendRes.error) printError(sendRes.error);
+      else console.error('Failed to send message');
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({ message_id: sendRes.data?.message_id, seq: sendRes.data?.seq }));
+    } else {
+      console.log(`Sent: ${sendRes.data?.message_id} (seq: ${sendRes.data?.seq})`);
+    }
+  });
+
+program
+  .command('inbox')
+  .description('Fetch inbox messages. Without --conversation, lists conversations with recent activity.')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--conversation <id>', 'Conversation ID (omit to list all conversations with new messages)')
+  .option('--since-seq <n>', 'Since sequence number', '0')
+  .option('--limit <n>', 'Limit', '20')
+  .option('--box <box>', "Inbox box: ready, strangers, or all (merge both; use 'all' if Web messages don't show)", 'ready')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+    const sinceSeq = parseInt(opts.sinceSeq);
+    const limit = parseInt(opts.limit);
+
+    if (!opts.conversation) {
+      const listRes = await client.listConversations({ type: 'dm' });
+      if (!listRes.ok || !listRes.data?.conversations?.length) {
+        if (opts.json) {
+          console.log(JSON.stringify({ ok: true, data: { conversations: [] } }, null, 2));
+        } else {
+          console.log('No conversations. Send a message (pingagent chat --to <did>) or approve a contact request first.');
+        }
+        return;
+      }
+      const raw = program.opts().raw;
+      const convos = listRes.data.conversations;
+      if (opts.json) {
+        const withPreview = [];
+        for (const c of convos) {
+          const resReady = await client.fetchInbox(c.conversation_id, { sinceSeq: 0, limit: 1, box: 'ready' });
+          const resStrangers = await client.fetchInbox(c.conversation_id, { sinceSeq: 0, limit: 1, box: 'strangers' });
+          const lastReady = resReady.ok && resReady.data?.messages?.[0];
+          const lastStrangers = resStrangers.ok && resStrangers.data?.messages?.[0];
+          withPreview.push({
+            conversation_id: c.conversation_id,
+            type: c.type,
+            target_did: c.target_did,
+            trusted: c.trusted,
+            last_ready: lastReady ? { seq: lastReady.seq, schema: lastReady.schema, ts_ms: lastReady.ts_ms } : null,
+            last_strangers: lastStrangers ? { seq: lastStrangers.seq, schema: lastStrangers.schema, ts_ms: lastStrangers.ts_ms } : null,
+          });
+        }
+        console.log(JSON.stringify({ ok: true, data: { conversations: withPreview } }, null, 2));
+      } else {
+        for (const c of convos) {
+          const resReady = await client.fetchInbox(c.conversation_id, { sinceSeq: 0, limit: 1, box: 'ready' });
+          const resStrangers = await client.fetchInbox(c.conversation_id, { sinceSeq: 0, limit: 1, box: 'strangers' });
+          const lastReady = resReady.ok && resReady.data?.messages?.[0];
+          const lastStrangers = resStrangers.ok && resStrangers.data?.messages?.[0];
+          const preview = lastReady?.payload?.text ?? lastStrangers?.payload?.text ?? lastReady?.payload?.title ?? lastStrangers?.payload?.title ?? lastReady?.schema ?? lastStrangers?.schema ?? '-';
+          const ts = (lastReady ?? lastStrangers)?.ts_ms != null ? formatTs((lastReady ?? lastStrangers).ts_ms, raw) : '-';
+          const from = (lastReady ?? lastStrangers)?.sender_did?.slice(0, 16) ?? '?';
+          console.log(`  ${c.conversation_id}  ${c.trusted ? 'ready' : 'pending'}  last: ${ts}  from ${from}...  "${String(preview).slice(0, 40)}${String(preview).length > 40 ? '...' : ''}"`);
+        }
+        console.log('');
+        console.log('To view messages: pingagent inbox --conversation <conversation_id>');
+      }
+      return;
+    }
+
+    let messages = [];
+    let hasMore = false;
+    if (opts.box === 'all') {
+      const seen = new Set();
+      for (const box of ['ready', 'strangers']) {
+        const res = await client.fetchInbox(opts.conversation, { sinceSeq, limit, box });
+        if (res.ok && res.data) {
+          for (const m of res.data.messages) {
+            const id = m.message_id ?? `${opts.conversation}-${m.seq}`;
+            if (!seen.has(id)) { seen.add(id); messages.push(m); }
+          }
+          if (res.data.has_more) hasMore = true;
+        }
+      }
+      messages.sort((a, b) => (a.ts_ms ?? 0) - (b.ts_ms ?? 0));
+    } else {
+      const res = await client.fetchInbox(opts.conversation, { sinceSeq, limit, box: opts.box });
+      if (!res.ok) {
+        if (res.error) printError(res.error);
+        else console.error('Failed to fetch inbox');
+        process.exit(1);
+      }
+      messages = res.data?.messages ?? [];
+      hasMore = res.data?.has_more ?? false;
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, data: { messages, has_more: hasMore } }, null, 2));
+    } else {
+      const raw = program.opts().raw;
+      for (const msg of messages) {
+        const ts = formatTs(msg.ts_ms, raw);
+        console.log(`  ${ts}  [${msg.seq}] ${msg.schema} from ${msg.sender_did?.slice(0, 20)}... (${msg.status})`);
+      }
+      console.log(`${messages.length} message(s), has_more: ${hasMore}`);
+    }
+  });
+
+program
+  .command('approve')
+  .description('Approve a contact request')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .argument('<conversation_id>', 'Pending DM conversation ID')
+  .action(async (conversationId, opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+
+    const res = await client.approveContact(conversationId);
+    if (res.ok && res.data) {
+      console.log(`Approved. DM conversation: ${res.data.dm_conversation_id}`);
+    } else {
+      if (res.error) printError(res.error);
+      else console.error('Failed:', res.error?.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('cancel')
+  .description('Cancel a running task')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .argument('<conversation_id>', 'Conversation ID')
+  .argument('<task_id>', 'Task ID')
+  .action(async (conversationId, taskId, opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+
+    const res = await client.cancelTask(conversationId, taskId);
+    if (res.ok && res.data) {
+      console.log(`Task state: ${res.data.task_state}`);
+    } else {
+      if (res.error) printError(res.error);
+      else console.error('Cancel failed');
+      process.exit(1);
+    }
+  });
+
+program
+  .command('resolve')
+  .description('Resolve alias to DID')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .argument('<alias>', 'Alias (e.g. @my/bot)')
+  .action(async (alias, opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+
+    const res = await client.resolveAlias(alias);
+    if (res.ok && res.data) {
+      console.log(`${res.data.alias} → ${res.data.did}`);
+    } else {
+      if (res.error) printError(res.error);
+      else console.error('Not found');
+      process.exit(1);
+    }
+  });
+
+// === Conversations (local history management + server view) ===
+const conversations = program.command('conversations').description('Manage conversations (local history and server-side metadata)');
+
+conversations
+  .command('list')
+  .description('List server conversations for the current identity (optionally by profile). Use --type pending_dm to see only pending contact requests.')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--type <dm|pending_dm|all>', 'Filter: dm (established only), pending_dm (waiting for approval), or all (default)', 'all')
+  .option('--json', 'Output as JSON')
+  .action(async (opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+    const typeArg = opts.type === 'pending_dm' ? 'pending_dm' : opts.type === 'dm' ? 'dm' : undefined;
+    const res = await client.listConversations(typeArg ? { type: typeArg } : undefined);
+    const convos = res.ok && res.data?.conversations ? res.data.conversations : [];
+    const raw = program.opts().raw;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: res.ok, conversations: convos }, null, 2));
+    } else if (!res.ok) {
+      if (res.error) printError(res.error);
+      else console.error('Failed to list conversations');
+      process.exit(1);
+    } else if (convos.length === 0) {
+      const hint = typeArg === 'pending_dm'
+        ? 'No pending contact requests.'
+        : 'No conversations. Send a message (pingagent chat --to <did>) or approve a contact request first.';
+      console.log(hint);
+    } else {
+      for (const c of convos) {
+        const ts = c.last_message_ts_ms != null ? formatTs(c.last_message_ts_ms, raw) : '-';
+        const target = c.target_did?.slice(0, 30) ?? '?';
+        console.log(`  ${c.conversation_id}  ${c.trusted ? 'ready' : 'pending'}  last: ${ts}  target: ${target}`);
+      }
+      console.log(`\n${convos.length} conversation(s)`);
+    }
+  });
+
+conversations
+  .command('show')
+  .description('Show details and recent messages for a conversation')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .argument('<conversation_id>', 'Conversation ID')
+  .option('--limit <n>', 'Number of recent messages to fetch', '20')
+  .option('--json', 'Output as JSON')
+  .action(async (conversationId, opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / --profile / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient(identityPath);
+    const metaRes = await client.listConversations({ type: 'dm' });
+    const convo = metaRes.ok && metaRes.data?.conversations
+      ? metaRes.data.conversations.find(c => c.conversation_id === conversationId)
+      : null;
+    const limit = parseInt(opts.limit, 10) || 20;
+    const inboxRes = await client.fetchInbox(conversationId, { sinceSeq: 0, limit, box: 'all' });
+    const messages = inboxRes.ok && inboxRes.data?.messages ? inboxRes.data.messages : [];
+    const raw = program.opts().raw;
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: metaRes.ok && inboxRes.ok,
+        conversation: convo ?? null,
+        messages,
+      }, null, 2));
+      return;
+    }
+
+    if (!inboxRes.ok) {
+      if (inboxRes.error) printError(inboxRes.error);
+      else console.error('Failed to fetch messages for conversation');
+      process.exit(1);
+    }
+
+    if (convo) {
+      console.log(`Conversation: ${convo.conversation_id}`);
+      console.log(`Type: ${convo.type}`);
+      console.log(`Trusted: ${convo.trusted}`);
+      console.log(`Target DID: ${convo.target_did ?? '-'}`);
+      if (convo.last_message_ts_ms != null) {
+        console.log(`Last message: ${formatTs(convo.last_message_ts_ms, raw)}`);
+      }
+      console.log('');
+    }
+
+    if (messages.length === 0) {
+      console.log('No messages found for this conversation.');
+      return;
+    }
+
+    for (const msg of messages) {
+      const ts = formatTs(msg.ts_ms, raw);
+      const from = msg.sender_did?.slice(0, 20) ?? '?';
+      const text = msg.payload?.text ?? msg.payload?.title ?? msg.schema;
+      console.log(`  ${ts}  [${msg.seq}] ${msg.schema} from ${from}...  ${text}`);
+    }
+    console.log(`\n${messages.length} message(s)`);
+  });
+
+conversations
+  .command('delete')
+  .description('Delete local history for a conversation (server conversation unchanged)')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .argument('<conversation_id>', 'Conversation ID')
+  .action((conversationId, opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    const store = openStore(identityPath);
+    const mgr = new HistoryManager(store);
+    const count = mgr.delete(conversationId);
+    console.log(`Deleted ${count} message(s) for conversation ${conversationId}`);
+    store.close();
+  });
+
+conversations
+  .command('clear')
+  .description('Clear all local history (use --force to skip confirmation)')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .option('--force', 'Skip confirmation')
+  .action((opts = {}) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    const store = openStore(identityPath);
+    const mgr = new HistoryManager(store);
+    const convos = mgr.listConversations();
+    if (convos.length === 0) {
+      console.log('No local history to clear.');
+      store.close();
+      return;
+    }
+    if (!opts.force) {
+      console.log(`This will delete local history for ${convos.length} conversation(s). Run with --force to confirm.`);
+      store.close();
+      return;
+    }
+    let total = 0;
+    for (const c of convos) {
+      total += mgr.delete(c.conversation_id);
+    }
+    console.log(`Cleared ${total} message(s) from ${convos.length} conversation(s).`);
+    store.close();
+  });
+
+// === Contacts ===
+const contacts = program.command('contacts').description('Manage local contacts');
+
+contacts
+  .command('list')
+  .description('List saved contacts')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--trusted', 'Show only trusted contacts')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    const list = mgr.list({ tag: opts.tag, trusted: opts.trusted ? true : undefined });
+    if (opts.json) {
+      console.log(JSON.stringify(list, null, 2));
+    } else if (list.length === 0) {
+      console.log('No contacts found.');
+    } else {
+      for (const c of list) {
+        const name = c.display_name ?? c.alias ?? c.did.slice(0, 30) + '...';
+        const trust = c.trusted ? ' [trusted]' : '';
+        console.log(`  ${name}${trust}  ${c.did}`);
+      }
+      console.log(`\n${list.length} contact(s)`);
+    }
+    store.close();
+  });
+
+contacts
+  .command('add')
+  .description('Add a contact')
+  .argument('<did>', 'Agent DID')
+  .option('--alias <alias>', 'Alias (e.g. @my/bot)')
+  .option('--name <name>', 'Display name')
+  .option('--notes <notes>', 'Notes')
+  .option('--tag <tag>', 'Tag')
+  .action((did, opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    mgr.add({
+      did,
+      alias: opts.alias,
+      display_name: opts.name,
+      notes: opts.notes,
+      trusted: false,
+      tags: opts.tag ? [opts.tag] : undefined,
+    });
+    console.log(`Contact added: ${did}`);
+    store.close();
+  });
+
+contacts
+  .command('remove')
+  .description('Remove a contact')
+  .argument('<did>', 'Agent DID')
+  .action((did) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    if (mgr.remove(did)) {
+      console.log(`Contact removed: ${did}`);
+    } else {
+      console.log('Contact not found.');
+    }
+    store.close();
+  });
+
+contacts
+  .command('update')
+  .description('Update a contact')
+  .argument('<did>', 'Agent DID')
+  .option('--alias <alias>', 'Alias')
+  .option('--name <name>', 'Display name')
+  .option('--notes <notes>', 'Notes')
+  .option('--tag <tag>', 'Tag (replaces existing tags)')
+  .action((did, opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    const updates = {};
+    if (opts.alias) updates.alias = opts.alias;
+    if (opts.name) updates.display_name = opts.name;
+    if (opts.notes) updates.notes = opts.notes;
+    if (opts.tag) updates.tags = [opts.tag];
+    const result = mgr.update(did, updates);
+    if (result) {
+      console.log(`Contact updated: ${did}`);
+    } else {
+      console.log('Contact not found.');
+    }
+    store.close();
+  });
+
+contacts
+  .command('search')
+  .description('Search contacts')
+  .argument('<query>', 'Search query')
+  .option('--json', 'Output as JSON')
+  .action((query, opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    const results = mgr.search(query);
+    if (opts.json) {
+      console.log(JSON.stringify(results, null, 2));
+    } else if (results.length === 0) {
+      console.log('No contacts match.');
+    } else {
+      for (const c of results) {
+        console.log(`  ${c.display_name ?? c.alias ?? c.did.slice(0, 30)}  ${c.did}`);
+      }
+      console.log(`\n${results.length} match(es)`);
+    }
+    store.close();
+  });
+
+contacts
+  .command('export')
+  .description('Export contacts')
+  .option('--format <format>', 'json or csv', 'json')
+  .option('--output <file>', 'Output file path')
+  .action((opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    const data = mgr.export(opts.format);
+    if (opts.output) {
+      fs.writeFileSync(opts.output, data);
+      console.log(`Exported to ${opts.output}`);
+    } else {
+      console.log(data);
+    }
+    store.close();
+  });
+
+contacts
+  .command('import')
+  .description('Import contacts from file')
+  .argument('<file>', 'File to import')
+  .option('--format <format>', 'json or csv', 'json')
+  .action((file, opts) => {
+    const store = openStore();
+    const mgr = new ContactManager(store);
+    const data = fs.readFileSync(file, 'utf-8');
+    const result = mgr.import(data, opts.format);
+    console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`);
+    store.close();
+  });
+
+// === History ===
+const history = program.command('history').description('Manage local chat history');
+
+history
+  .command('conversations')
+  .description('List conversations with local history')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const raw = program.opts().raw;
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    const convos = mgr.listConversations();
+    if (opts.json) {
+      console.log(JSON.stringify(convos, null, 2));
+    } else if (convos.length === 0) {
+      console.log('No local history.');
+    } else {
+      for (const c of convos) {
+        const date = formatTs(c.last_message_at, raw);
+        console.log(`  ${c.conversation_id}  ${c.message_count} msg(s)  last: ${date}`);
+      }
+    }
+    store.close();
+  });
+
+history
+  .command('list')
+  .description('List messages in a conversation (default: most recent conversation)')
+  .argument('[conversation_id]', 'Conversation ID (omit to use most recent from local history)')
+  .option('--limit <n>', 'Limit', '50')
+  .option('--json', 'Output as JSON')
+  .action((conversationId, opts) => {
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    let cid = conversationId;
+    if (!cid) {
+      const convos = mgr.listConversations();
+      if (convos.length === 0) {
+        console.log('No local history. Run "pingagent inbox" then "pingagent history sync <conversation_id>" to sync, or pass a conversation_id.');
+        store.close();
+        return;
+      }
+      cid = convos[0].conversation_id;
+      if (!opts.json) {
+        console.log(`Using most recent conversation: ${cid}\n`);
+      }
+    }
+    const messages = mgr.list(cid, { limit: parseInt(opts.limit) });
+    if (opts.json) {
+      console.log(JSON.stringify(messages, null, 2));
+    } else if (messages.length === 0) {
+      console.log('No messages found.');
+    } else {
+      const raw = program.opts().raw;
+      for (const m of messages) {
+        const dir = m.direction === 'sent' ? '→' : '←';
+        const text = m.payload?.text ?? m.payload?.title ?? m.schema;
+        const ts = formatTs(m.ts_ms, raw);
+        console.log(`  ${ts}  ${dir} [${m.seq ?? '-'}] ${m.schema}  ${text}`);
+      }
+      console.log(`\n${messages.length} message(s)`);
+    }
+    store.close();
+  });
+
+history
+  .command('sync')
+  .description('Sync messages from server')
+  .argument('<conversation_id>', 'Conversation ID')
+  .option('--full', 'Full sync from beginning')
+  .action(async (conversationId, opts) => {
+    if (!identityExists(getEffectiveIdentityPath())) {
+      console.error('No identity found. Run: pingagent init (or use --identity-dir / PINGAGENT_IDENTITY_PATH)');
+      process.exit(1);
+    }
+    const client = await getClient();
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    const result = await mgr.syncFromServer(client, conversationId, { full: opts.full });
+    console.log(`Synced ${result.synced} message(s)`);
+    store.close();
+  });
+
+history
+  .command('search')
+  .description('Search message history')
+  .argument('<query>', 'Search query')
+  .option('--conversation <id>', 'Limit to conversation')
+  .option('--json', 'Output as JSON')
+  .action((query, opts) => {
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    const results = mgr.search(query, { conversationId: opts.conversation });
+    if (opts.json) {
+      console.log(JSON.stringify(results, null, 2));
+    } else if (results.length === 0) {
+      console.log('No messages match.');
+    } else {
+      for (const m of results) {
+        const dir = m.direction === 'sent' ? '→' : '←';
+        const text = m.payload?.text ?? m.payload?.title ?? m.schema;
+        console.log(`  ${dir} ${m.conversation_id.slice(0, 15)}  ${text}`);
+      }
+      console.log(`\n${results.length} match(es)`);
+    }
+    store.close();
+  });
+
+history
+  .command('export')
+  .description('Export chat history')
+  .option('--conversation <id>', 'Conversation ID (all if omitted)')
+  .option('--format <format>', 'json or csv', 'json')
+  .option('--output <file>', 'Output file path')
+  .action((opts) => {
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    const data = mgr.export({ conversationId: opts.conversation, format: opts.format });
+    if (opts.output) {
+      fs.writeFileSync(opts.output, data);
+      console.log(`Exported to ${opts.output}`);
+    } else {
+      console.log(data);
+    }
+    store.close();
+  });
+
+history
+  .command('delete')
+  .description('Delete history for a conversation')
+  .argument('<conversation_id>', 'Conversation ID')
+  .action((conversationId) => {
+    const store = openStore();
+    const mgr = new HistoryManager(store);
+    const count = mgr.delete(conversationId);
+    console.log(`Deleted ${count} message(s)`);
+    store.close();
+  });
+
+// === A2A (Agent-to-Agent Protocol) ===
+const a2a = program.command('a2a').description('Interact with external A2A-compatible agents');
+
+a2a
+  .command('discover')
+  .description('Fetch and display an external agent\'s AgentCard')
+  .argument('<url>', 'Agent URL (e.g. https://agent.example.com)')
+  .option('--json', 'Output as JSON')
+  .action(async (url, opts) => {
+    const adapter = new A2AAdapter({ agentUrl: url });
+    const card = await adapter.getAgentCard();
+    if (opts.json) {
+      console.log(JSON.stringify(card, null, 2));
+    } else {
+      console.log(`Agent: ${card.name}`);
+      console.log(`Description: ${card.description}`);
+      console.log(`URL: ${card.url}`);
+      console.log(`Version: ${card.version} (protocol ${card.protocolVersion})`);
+      if (card.provider) console.log(`Provider: ${card.provider.organization}`);
+      console.log(`Capabilities: streaming=${card.capabilities.streaming ?? false}, push=${card.capabilities.pushNotifications ?? false}`);
+      console.log(`Skills:`);
+      for (const s of card.skills) {
+        console.log(`  [${s.id}] ${s.name}: ${s.description}`);
+        if (s.tags.length) console.log(`    tags: ${s.tags.join(', ')}`);
+      }
+    }
+  });
+
+a2a
+  .command('send')
+  .description('Send a task to an external A2A agent')
+  .argument('<url>', 'Agent URL')
+  .requiredOption('--task <title>', 'Task title/prompt')
+  .option('--description <desc>', 'Task description')
+  .option('--wait', 'Wait for task completion')
+  .option('--timeout <seconds>', 'Timeout in seconds', '120')
+  .option('--auth <token>', 'Bearer token for the remote agent')
+  .option('--json', 'Output as JSON')
+  .action(async (url, opts) => {
+    const adapter = new A2AAdapter({
+      agentUrl: url,
+      authToken: opts.auth,
+    });
+
+    const result = await adapter.sendTask({
+      title: opts.task,
+      description: opts.description,
+      wait: opts.wait,
+      timeoutMs: parseInt(opts.timeout) * 1000,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Task ID: ${result.taskId}`);
+      console.log(`State: ${result.state}`);
+      if (result.summary) console.log(`Summary: ${result.summary}`);
+      if (result.output) console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
+    }
+  });
+
+a2a
+  .command('status')
+  .description('Get task status from an external A2A agent')
+  .argument('<url>', 'Agent URL')
+  .requiredOption('--task-id <id>', 'Task ID')
+  .option('--auth <token>', 'Bearer token')
+  .option('--json', 'Output as JSON')
+  .action(async (url, opts) => {
+    const adapter = new A2AAdapter({
+      agentUrl: url,
+      authToken: opts.auth,
+    });
+
+    const result = await adapter.getTaskStatus(opts.taskId);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Task ID: ${result.taskId}`);
+      console.log(`State: ${result.state}`);
+      if (result.summary) console.log(`Summary: ${result.summary}`);
+    }
+  });
+
+a2a
+  .command('cancel')
+  .description('Cancel a task on an external A2A agent')
+  .argument('<url>', 'Agent URL')
+  .requiredOption('--task-id <id>', 'Task ID')
+  .option('--auth <token>', 'Bearer token')
+  .action(async (url, opts) => {
+    const adapter = new A2AAdapter({
+      agentUrl: url,
+      authToken: opts.auth,
+    });
+    const result = await adapter.cancelTask(opts.taskId);
+    console.log(`Task ${result.taskId}: ${result.state}`);
+  });
+
+// === Billing ===
+const billing = program.command('billing').description('Manage billing group (primary + linked devices)');
+
+billing
+  .command('link-code')
+  .description('Generate a link code for adding a device to your subscription (primary only)')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.createBillingLinkCode();
+    if (!res.ok) {
+      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
+        console.error(`Error: ${res.error?.message ?? 'Failed to create link code'}`);
+        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(res.data, null, 2));
+    } else {
+      console.log(`Link code: ${res.data.code}`);
+      console.log(`Expires in ${res.data.expires_in_seconds}s`);
+      console.log(`\nRun on the new device:\n  pingagent billing link --code ${res.data.code}`);
+    }
+  });
+
+billing
+  .command('link')
+  .description('Link this device to a primary subscription using a link code')
+  .requiredOption('--code <code>', 'Link code from primary device')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.redeemBillingLink(opts.code);
+    if (!res.ok) {
+      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
+        console.error(`Error: ${res.error?.message ?? 'Failed to link device'}`);
+        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(res.data, null, 2));
+    } else {
+      console.log(`Linked to primary: ${res.data.primary_did}`);
+      console.log('This device now shares the primary subscription tier and quotas.');
+    }
+  });
+
+billing
+  .command('linked-devices')
+  .description('List all devices in your billing group')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.getLinkedDevices();
+    if (!res.ok) {
+      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
+        console.error(`Error: ${res.error?.message ?? 'Failed to get linked devices'}`);
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(res.data, null, 2));
+    } else {
+      const d = res.data;
+      console.log(`Primary DID: ${d.primary_did}${d.is_primary ? ' (this device)' : ''}`);
+      if (d.linked_dids.length === 0) {
+        console.log('No linked devices.');
+      } else {
+        console.log(`Linked devices (${d.linked_dids.length}):`);
+        for (const did of d.linked_dids) {
+          const marker = did === client.getDid() ? ' (this device)' : '';
+          console.log(`  - ${did}${marker}`);
+        }
+      }
+    }
+  });
+
+billing
+  .command('unlink')
+  .description('Remove a linked device from your billing group (primary only)')
+  .requiredOption('--did <did>', 'DID of the device to unlink')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.unlinkBillingDevice(opts.did);
+    if (!res.ok) {
+      if (opts.json) { console.log(JSON.stringify(res, null, 2)); } else {
+        console.error(`Error: ${res.error?.message ?? 'Failed to unlink device'}`);
+        if (res.error?.hint) console.error(`Hint: ${res.error.hint}`);
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true }, null, 2));
+    } else {
+      console.log(`Unlinked: ${opts.did}`);
+      console.log('The device will revert to ghost tier.');
+    }
+  });
+
+program
+  .command('web')
+  .description('Start local web UI for debugging and audit. By default scans ~/.pingagent for profiles; use --identity-dir to lock to one profile.')
+  .option('--port <port>', 'Port for the web server', '3846')
+  .action(async (opts) => {
+    const serverUrl = process.env.PINGAGENT_SERVER_URL || DEFAULT_SERVER;
+    const port = parseInt(opts.port, 10) || 3846;
+    const identityDir = program.opts().identityDir;
+    const defaultRoot = path.join(os.homedir(), '.pingagent');
+    const resolvedRoot = resolvePath(defaultRoot);
+    const { startWebServer } = await import('../dist/web-server.js');
+    const useSingleProfile = identityDir && path.resolve(resolvePath(identityDir)) !== resolvedRoot;
+    if (useSingleProfile) {
+      const identityPath = path.join(resolvePath(identityDir), 'identity.json');
+      if (!identityExists(identityPath)) {
+        console.error('No identity found at', identityPath, '. Run: pingagent init');
+        process.exit(1);
+      }
+      const storePath = process.env.PINGAGENT_STORE_PATH
+        ? resolvePath(process.env.PINGAGENT_STORE_PATH)
+        : path.join(resolvePath(identityDir), 'store.db');
+      await startWebServer({ fixedIdentityPath: identityPath, fixedStorePath: storePath, serverUrl, port });
+    } else {
+      const rootDir = process.env.PINGAGENT_ROOT_DIR || defaultRoot;
+      await startWebServer({ rootDir, serverUrl, port });
+    }
+  });
+
+program.parse();