@pingagent/sdk 0.1.10 → 0.1.11

package/bin/pingagent.js

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import * as readline from 'node:readline';
+import { spawnSync } from 'node:child_process';
 import {
   PingAgentClient,
   generateIdentity,
@@ -17,10 +18,16 @@ import {
   HistoryManager,
   A2AAdapter,
   SessionManager,
+  SessionSummaryManager,
   TaskThreadManager,
+  TaskHandoffManager,
   TrustPolicyAuditManager,
+  TrustRecommendationManager,
+  getTrustRecommendationActionLabel,
+  formatCapabilityCardSummary,
   defaultTrustPolicyDoc,
   normalizeTrustPolicyDoc,
+  upsertTrustPolicyRecommendation,
   getActiveSessionFilePath,
   getSessionMapFilePath,
   getSessionBindingAlertsFilePath,
@@ -29,12 +36,16 @@ import {
   readSessionBindingAlerts,
   setSessionBinding,
   removeSessionBinding,
+  readIngressRuntimeStatus,
 } from '../dist/index.js';
 import { ERROR_HINTS, SCHEMA_TEXT } from '@pingagent/schemas';
 
 const DEFAULT_SERVER = 'https://pingagent.chat';
 const UPGRADE_URL = 'https://pingagent.chat';
 const DEFAULT_IDENTITY_PATH = path.join(os.homedir(), '.pingagent', 'identity.json');
+const OFFICIAL_HOSTED_ORIGIN = new URL(DEFAULT_SERVER).origin;
+const hostedPublicLinkAttempts = new Set();
+const SESSION_SUMMARY_FIELDS = ['objective', 'context', 'constraints', 'decisions', 'open_questions', 'next_action', 'handoff_ready_text'];
 
 function resolvePath(p) {
   if (!p) return p;
@@ -42,6 +53,18 @@ function resolvePath(p) {
   return p;
 }
 
+function normalizeOrigin(input) {
+  try {
+    return new URL(String(input ?? '')).origin;
+  } catch {
+    return null;
+  }
+}
+
+function isOfficialHostedServer(serverUrl) {
+  return normalizeOrigin(serverUrl) === OFFICIAL_HOSTED_ORIGIN;
+}
+
 function getEffectiveIdentityPath() {
   const dir = program.opts().identityDir;
   if (dir) return path.join(resolvePath(dir), 'identity.json');
@@ -108,6 +131,38 @@ function readTrustPolicyDoc(identityPath) {
   }
 }
 
+function writeTrustPolicyDoc(identityPath, doc) {
+  const policyPath = getTrustPolicyPath(identityPath);
+  fs.mkdirSync(path.dirname(policyPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(policyPath, JSON.stringify(normalizeTrustPolicyDoc(doc), null, 2), 'utf-8');
+  return policyPath;
+}
+
+function findOpenClawInstallScript() {
+  const explicit = process.env.PINGAGENT_OPENCLAW_INSTALL_BIN;
+  if (explicit) return { cmd: process.execPath, args: [resolvePath(explicit)] };
+  const repoScript = path.resolve(process.cwd(), 'packages', 'openclaw-install', 'install.mjs');
+  if (fs.existsSync(repoScript)) return { cmd: process.execPath, args: [repoScript] };
+  return null;
+}
+
+function runOpenClawInstall(args) {
+  const resolved = findOpenClawInstallScript();
+  if (!resolved) {
+    return { ok: false, stdout: '', stderr: 'OpenClaw installer script not found locally. Set PINGAGENT_OPENCLAW_INSTALL_BIN.' };
+  }
+  const result = spawnSync(resolved.cmd, [...resolved.args, ...args], {
+    encoding: 'utf-8',
+    env: process.env,
+  });
+  return {
+    ok: result.status === 0,
+    stdout: String(result.stdout ?? ''),
+    stderr: String(result.stderr ?? ''),
+    status: result.status ?? 1,
+  };
+}
+
 function clearScreen() {
   process.stdout.write('\x1Bc');
 }
@@ -173,6 +228,7 @@ function buildTaskExportBody(task, format = 'plain') {
           message: task.error_message,
         }
       : null,
+    handoff: task.handoff || null,
   };
   if (format === 'json') return JSON.stringify(payload, null, 2);
   return [
@@ -232,7 +288,9 @@ function buildHostState(identityPath, selectedSessionKey = null, historyPageInde
   const store = openStore(identityPath);
   try {
     const sessionManager = new SessionManager(store);
+    const sessionSummaryManager = new SessionSummaryManager(store);
     const taskManager = new TaskThreadManager(store);
+    const taskHandoffManager = new TaskHandoffManager(store);
     const historyManager = new HistoryManager(store);
     const auditManager = new TrustPolicyAuditManager(store);
     const sessions = sessionManager.listRecentSessions(50);
@@ -241,6 +299,7 @@ function buildHostState(identityPath, selectedSessionKey = null, historyPageInde
     const bindingByConversation = new Map(bindings.map((row) => [row.conversation_id, row]));
     const alertByConversation = new Map(alerts.map((row) => [row.conversation_id, row]));
     const activeChatSession = readCurrentActiveSessionKey();
+    const ingressRuntime = readIngressRuntimeStatus();
     const desiredSelectedSessionKey =
       (selectedSessionKey && sessions.some((session) => session.session_key === selectedSessionKey) ? selectedSessionKey : null) ??
       sessionManager.getActiveSession()?.session_key ??
@@ -255,8 +314,14 @@ function buildHostState(identityPath, selectedSessionKey = null, historyPageInde
       is_active_chat_session: session.session_key === activeChatSession,
     }));
     const selectedSession = sessionsWithMeta.find((session) => session.session_key === desiredSelectedSessionKey) ?? null;
+    const selectedSessionSummary = selectedSession
+      ? sessionSummaryManager.get(selectedSession.session_key)
+      : null;
     const selectedTasks = selectedSession
-      ? taskManager.listBySession(selectedSession.session_key, 12)
+      ? taskManager.listBySession(selectedSession.session_key, 12).map((task) => ({
+          ...task,
+          handoff: taskHandoffManager.get(task.task_id),
+        }))
       : [];
     const selectedAuditEvents = selectedSession
       ? auditManager.listBySession(selectedSession.session_key, 12)
@@ -270,27 +335,45 @@ function buildHostState(identityPath, selectedSessionKey = null, historyPageInde
     const selectedHistorySearchResults = selectedSession?.conversation_id && historySearchQuery.trim()
       ? historyManager.search(historySearchQuery.trim(), { conversationId: selectedSession.conversation_id, limit: 50 })
       : [];
+    const recommendationManager = new TrustRecommendationManager(store);
+    recommendationManager.sync({
+      policyDoc: policy.doc,
+      sessions,
+      tasks: taskManager.listRecent(100),
+      auditEvents: auditManager.listRecent(200),
+      runtimeMode,
+      limit: 50,
+    });
+    const selectedRecommendations = selectedSession?.remote_did
+      ? recommendationManager.list({ remoteDid: selectedSession.remote_did, limit: 10 })
+      : [];
     const unreadTotal = sessionsWithMeta.reduce((sum, session) => sum + (session.unread_count ?? 0), 0);
     const alertSessions = sessionsWithMeta.filter((session) => !!session.binding_alert).length;
     return {
       identity,
       runtimeMode,
       activeChatSession,
+      ingressRuntime,
       activeChatSessionFile: getActiveSessionFilePath(),
       sessionMapPath: getSessionMapFilePath(),
       sessionBindingAlertsPath: getSessionBindingAlertsFilePath(),
       policyPath: policy.path,
       policyDoc: policy.doc,
       sessions: sessionsWithMeta,
-      tasks: taskManager.listRecent(30),
+      tasks: taskManager.listRecent(30).map((task) => ({
+        ...task,
+        handoff: taskHandoffManager.get(task.task_id),
+      })),
       auditEvents: auditManager.listRecent(40),
       selectedSession,
+      selectedSessionSummary,
       selectedTasks,
       selectedAuditEvents,
       selectedMessages,
       selectedHistoryPage,
       selectedHistorySearchQuery: historySearchQuery.trim(),
       selectedHistorySearchResults,
+      selectedRecommendations,
       unreadTotal,
       alertSessions,
     };
@@ -302,9 +385,13 @@ function buildHostState(identityPath, selectedSessionKey = null, historyPageInde
 function renderHostTuiScreen(hostState, uiState) {
   const sessions = hostState.sessions || [];
   const selected = hostState.selectedSession || sessions[0] || null;
+  const selectedSummary = hostState.selectedSessionSummary || null;
   const tasks = hostState.selectedTasks || [];
   const auditEvents = hostState.selectedAuditEvents || [];
   const messages = hostState.selectedMessages || [];
+  const recommendations = hostState.selectedRecommendations || [];
+  const openRecommendation = recommendations.find((item) => item.status === 'open') || null;
+  const reopenRecommendation = recommendations.find((item) => item.status === 'dismissed' || item.status === 'superseded') || null;
   const historyPage = hostState.selectedHistoryPage || { messages: [], pageIndex: 0, hasOlder: false, hasNewer: false };
   const historySearchQuery = hostState.selectedHistorySearchQuery || '';
   const historySearchResults = hostState.selectedHistorySearchResults || [];
@@ -315,17 +402,24 @@ function renderHostTuiScreen(hostState, uiState) {
     ? ` (${Math.max(0, Math.ceil((uiState.statusExpiresAt - Date.now()) / 1000))}s)`
     : '';
   const statusTs = uiState?.statusAt ? ` @ ${formatStatusTimestamp(uiState.statusAt)}` : '';
+  const degraded = !hostState.ingressRuntime
+    || hostState.ingressRuntime.receive_mode === 'polling_degraded'
+    || !!hostState.ingressRuntime.hooks_last_error;
+  const ingressLabel = degraded ? 'Degraded' : 'Ready';
   const lines = [
     'PingAgent Host TUI',
     `DID: ${hostState.identity.did}`,
     `status=${formatStatusLine(uiState?.statusLevel || 'info', uiState?.statusMessage || '(ready)')}${statusTs}${statusCountdown}`,
-    `runtime_mode=${hostState.runtimeMode}  active_chat_session=${hostState.activeChatSession || '(none)'}`,
+    `runtime_mode=${hostState.runtimeMode}  receive_mode=${hostState.ingressRuntime?.receive_mode || 'webhook'}  active_chat_session=${hostState.activeChatSession || '(none)'}`,
+    `ingress=${ingressLabel}${degraded ? '  action=[f] fix-now' : ''}`,
+    uiState?.publicLinkUrl ? `public_link=${uiState.publicLinkUrl}` : null,
     `sessions=${sessions.length}  unread_total=${hostState.unreadTotal ?? 0}  alert_sessions=${hostState.alertSessions ?? 0}  view=${view}`,
     `policy=${hostState.policyPath}`,
     `session_map=${hostState.sessionMapPath}`,
     `binding_alerts=${hostState.sessionBindingAlertsPath}`,
+    hostState.ingressRuntime?.hooks_last_error ? `hooks_error=${truncateLine(hostState.ingressRuntime.hooks_last_error, 120)}` : null,
     '',
-  ];
+  ].filter(Boolean);
 
   if (view === 'help') {
     lines.push('Help');
@@ -339,10 +433,16 @@ function renderHostTuiScreen(hostState, uiState) {
     lines.push('- t: open task list view for selected session');
     lines.push('- x: cancel selected task (in task views)');
     lines.push('- p: multiline reply prompt (detail view)');
+    lines.push('- S: edit carry-forward summary (detail view)');
+    lines.push('- d: try demo agent preset');
     lines.push('- o: open local history paging (detail view)');
     lines.push('- n / p: older / newer history page (history view)');
     lines.push('- s or /: search local history (history view)');
     lines.push('- y: dump task detail to stdout (task-detail view, choose json/plain)');
+    lines.push('- f: repair OpenClaw hooks config');
+    lines.push('- A: apply first open trust recommendation for selected session');
+    lines.push('- D: dismiss current open recommendation');
+    lines.push('- R: reopen dismissed/superseded recommendation');
     lines.push('- b: bind selected conversation to current chat session');
     lines.push('- c: clear selected binding');
     lines.push('- q: quit');
@@ -382,8 +482,17 @@ function renderHostTuiScreen(hostState, uiState) {
       lines.push(`status=${selectedTask.status}`);
       lines.push(`updated_at=${formatTs(selectedTask.updated_at, false)}`);
       if (selectedTask.started_at) lines.push(`started_at=${formatTs(selectedTask.started_at, false)}`);
+      if (selectedTask.handoff?.objective) lines.push(`handoff_objective=${selectedTask.handoff.objective}`);
+      if (selectedTask.handoff?.priority) lines.push(`handoff_priority=${selectedTask.handoff.priority}`);
+      if (selectedTask.handoff?.success_criteria) lines.push(`handoff_success=${selectedTask.handoff.success_criteria}`);
+      if (selectedTask.handoff?.callback_session_key) lines.push(`handoff_callback=${selectedTask.handoff.callback_session_key}`);
       lines.push('actions=[x] cancel-task  [y] dump-stdout  [j/k] switch-task  [h/Esc] back-to-tasks');
       lines.push('');
+      if (selectedTask.handoff?.carry_forward_summary) {
+        lines.push('Handoff Summary');
+        lines.push(selectedTask.handoff.carry_forward_summary);
+        lines.push('');
+      }
       lines.push('Result');
       lines.push(selectedTask.result_summary || '(none)');
       lines.push('');
@@ -409,6 +518,8 @@ function renderHostTuiScreen(hostState, uiState) {
       lines.push(`status=${selectedTask.status}`);
       lines.push(`updated_at=${formatTs(selectedTask.updated_at, false)}`);
       if (selectedTask.started_at) lines.push(`started_at=${formatTs(selectedTask.started_at, false)}`);
+      if (selectedTask.handoff?.objective) lines.push(`handoff_objective=${selectedTask.handoff.objective}`);
+      if (selectedTask.handoff?.priority) lines.push(`handoff_priority=${selectedTask.handoff.priority}`);
       if (selectedTask.result_summary) lines.push(`result=${selectedTask.result_summary}`);
       if (selectedTask.error_code || selectedTask.error_message) {
         lines.push(`error=${selectedTask.error_code || 'E_TASK'} ${selectedTask.error_message || ''}`.trim());
@@ -440,10 +551,26 @@ function renderHostTuiScreen(hostState, uiState) {
       } else {
         lines.push('needs_rebind=false');
       }
+      if (openRecommendation) {
+        lines.push(`trust_action=${getTrustRecommendationActionLabel(openRecommendation)}`);
+      } else if (reopenRecommendation) {
+        lines.push(`trust_action=${getTrustRecommendationActionLabel(reopenRecommendation)}`);
+      }
+      if (selectedSummary) {
+        lines.push(`summary_objective=${selectedSummary.objective || '(none)'}`);
+        lines.push(`summary_next_action=${selectedSummary.next_action || '(none)'}`);
+      } else {
+        lines.push('summary_objective=(none)');
+      }
       const actionBar = [
         selected.trust_state === 'pending' ? '[a] approve' : null,
+        '[A] apply-rec',
+        '[D] dismiss-rec',
+        '[R] reopen-rec',
         '[m] mark-read',
+        '[d] demo',
         '[p] reply',
+        '[S] summary',
         '[o] history',
         '[t] tasks',
         '[b] bind-current',
@@ -451,9 +578,22 @@ function renderHostTuiScreen(hostState, uiState) {
       ].filter(Boolean).join('  ');
       lines.push(`actions=${actionBar}`);
       lines.push('');
+      lines.push('Carry-Forward Summary');
+      if (selectedSummary) {
+        lines.push(`- objective: ${selectedSummary.objective || '(none)'}`);
+        lines.push(`- context: ${truncateLine(selectedSummary.context || '(none)', 100)}`);
+        lines.push(`- constraints: ${truncateLine(selectedSummary.constraints || '(none)', 100)}`);
+        lines.push(`- decisions: ${truncateLine(selectedSummary.decisions || '(none)', 100)}`);
+        lines.push(`- open_questions: ${truncateLine(selectedSummary.open_questions || '(none)', 100)}`);
+        lines.push(`- next_action: ${truncateLine(selectedSummary.next_action || '(none)', 100)}`);
+        lines.push(`- handoff_ready: ${truncateLine(selectedSummary.handoff_ready_text || '(none)', 100)}`);
+      } else {
+        lines.push('- none');
+      }
+      lines.push('');
       lines.push('Tasks');
       lines.push(...(tasks.length
-        ? tasks.map((task) => `- ${task.title || task.task_id} [${task.status}] ${truncateLine(task.result_summary || task.error_message || '', 80)}`)
+        ? tasks.map((task) => `- ${task.title || task.task_id} [${task.status}]${task.handoff?.objective ? ` handoff=${truncateLine(task.handoff.objective, 30)}` : ''} ${truncateLine(task.result_summary || task.error_message || '', 80)}`)
         : ['- none']));
       if (view === 'detail') {
         lines.push('');
@@ -471,7 +611,7 @@ function renderHostTuiScreen(hostState, uiState) {
   }
 
   lines.push('');
-  lines.push('Keys: ↑/↓ or j/k select  Enter/l open  Esc/h back  g/G jump  r refresh  a approve  m read  p reply  o history  s search  t tasks  x cancel-task  y dump  b bind  c clear  ? help  q quit');
+  lines.push('Keys: ↑/↓ or j/k select  Enter/l open  Esc/h back  g/G jump  r refresh  a approve  A apply-rec  D dismiss-rec  R reopen-rec  d demo  m read  p reply  o history  s search  t tasks  x cancel-task  y dump  f fix-hooks  b bind  c clear  ? help  q quit');
   return lines.join('\n');
 }
 
@@ -489,6 +629,7 @@ async function runHostTui(identityPath, opts) {
     statusAt: 0,
     selectedHistoryPageIndex: 0,
     historySearchQuery: '',
+    publicLinkUrl: '',
   };
 
   const render = () => {
@@ -511,6 +652,9 @@ async function runHostTui(identityPath, opts) {
   };
 
   if (once) {
+    void maybeEnsureHostedPublicLink(identityPath).then((res) => {
+      if (res?.data?.public_url) uiState.publicLinkUrl = res.data.public_url;
+    });
     const { screen } = render();
     console.log(screen);
     return;
@@ -546,6 +690,132 @@ async function runHostTui(identityPath, opts) {
     uiState.statusAt = Date.now();
   };
 
+  const applySessionRecommendation = (selected) => {
+    if (!selected?.remote_did) return { ok: false, message: 'No remote DID for selected session.' };
+    const store = openStore(identityPath);
+    try {
+      const { path: policyPath, doc } = readTrustPolicyDoc(identityPath);
+      const auditManager = new TrustPolicyAuditManager(store);
+      const recommendationManager = new TrustRecommendationManager(store);
+      recommendationManager.sync({
+        policyDoc: doc,
+        sessions: new SessionManager(store).listRecentSessions(100),
+        tasks: new TaskThreadManager(store).listRecent(100),
+        auditEvents: auditManager.listRecent(200),
+        runtimeMode: process.env.PINGAGENT_RUNTIME_MODE || 'bridge',
+        limit: 50,
+      });
+      const recommendation = recommendationManager.list({
+        remoteDid: selected.remote_did,
+        status: 'open',
+        limit: 1,
+      })[0];
+      if (!recommendation) return { ok: false, message: 'No open recommendation for this session.' };
+      const nextDoc = upsertTrustPolicyRecommendation(doc, recommendation);
+      writeTrustPolicyDoc(identityPath, nextDoc);
+      recommendationManager.apply(recommendation.id);
+      auditManager.record({
+        event_type: 'recommendation_applied',
+        policy_scope: recommendation.policy,
+        remote_did: recommendation.remote_did,
+        action: String(recommendation.action),
+        outcome: 'recommendation_applied',
+        explanation: recommendation.reason,
+        matched_rule: recommendation.match,
+        detail: { recommendation_id: recommendation.id, session_key: selected.session_key },
+      });
+      return { ok: true, message: `${getTrustRecommendationActionLabel(recommendation)} (${recommendation.policy})`, path: policyPath };
+    } finally {
+      store.close();
+    }
+  };
+
+  const dismissSessionRecommendation = (selected) => {
+    if (!selected?.remote_did) return { ok: false, message: 'No remote DID for selected session.' };
+    const store = openStore(identityPath);
+    try {
+      const recommendationManager = new TrustRecommendationManager(store);
+      const recommendation = recommendationManager.list({
+        remoteDid: selected.remote_did,
+        status: 'open',
+        limit: 1,
+      })[0];
+      if (!recommendation) return { ok: false, message: 'No open recommendation for this session.' };
+      recommendationManager.dismiss(recommendation.id);
+      new TrustPolicyAuditManager(store).record({
+        event_type: 'recommendation_dismissed',
+        policy_scope: recommendation.policy,
+        remote_did: recommendation.remote_did,
+        action: String(recommendation.action),
+        outcome: 'recommendation_dismissed',
+        explanation: recommendation.reason,
+        matched_rule: recommendation.match,
+        detail: { recommendation_id: recommendation.id, session_key: selected.session_key },
+      });
+      return { ok: true, message: `Dismissed ${getTrustRecommendationActionLabel(recommendation)}` };
+    } finally {
+      store.close();
+    }
+  };
+
+  const reopenSessionRecommendation = (selected) => {
+    if (!selected?.remote_did) return { ok: false, message: 'No remote DID for selected session.' };
+    const store = openStore(identityPath);
+    try {
+      const recommendationManager = new TrustRecommendationManager(store);
+      const recommendation = recommendationManager.list({
+        remoteDid: selected.remote_did,
+        status: ['dismissed', 'superseded'],
+        limit: 1,
+      })[0];
+      if (!recommendation) return { ok: false, message: 'No dismissed or superseded recommendation for this session.' };
+      recommendationManager.reopen(recommendation.id);
+      new TrustPolicyAuditManager(store).record({
+        event_type: 'recommendation_reopened',
+        policy_scope: recommendation.policy,
+        remote_did: recommendation.remote_did,
+        action: String(recommendation.action),
+        outcome: 'recommendation_reopened',
+        explanation: recommendation.reason,
+        matched_rule: recommendation.match,
+        detail: { recommendation_id: recommendation.id, session_key: selected.session_key },
+      });
+      return { ok: true, message: 'Reopened recommendation' };
+    } finally {
+      store.close();
+    }
+  };
+
+  const sendDemoPreset = async () => {
+    const answer = await promptLine('Demo preset [hello/delegate/trust] (default hello): ');
+    const preset = (answer.trim().toLowerCase() || 'hello');
+    const presetMessages = {
+      hello: 'Hello',
+      delegate: 'Please show me how task delegation works in PingAgent.',
+      trust: 'Show me how trust decisions and recommendations work.',
+    };
+    const message = presetMessages[preset] || presetMessages.hello;
+    const { client, store } = await getClientWithStore(identityPath);
+    try {
+      const resolved = await client.resolveAlias('pingagent/demo');
+      if (!resolved.ok || !resolved.data?.did) {
+        setStatus(`Demo resolve failed: ${resolved.error?.message || 'unknown error'}`, 'err');
+        return;
+      }
+      const convo = await client.openConversation(resolved.data.did);
+      if (!convo.ok || !convo.data?.conversation_id) {
+        setStatus(`Demo open failed: ${convo.error?.message || 'unknown error'}`, 'err');
+        return;
+      }
+      const sendRes = await client.sendMessage(convo.data.conversation_id, SCHEMA_TEXT, { text: message });
+      setStatus(sendRes.ok
+        ? `Demo preset sent (${preset}) conversation=${convo.data.conversation_id}`
+        : `Demo send failed: ${sendRes.error?.message || 'unknown error'}`, sendRes.ok ? 'ok' : 'err', sendRes.ok ? 7000 : 9000);
+    } finally {
+      store.close();
+    }
+  };
+
   const promptLine = async (question) => {
     stopInterval();
     if (process.stdin.setRawMode) process.stdin.setRawMode(false);
@@ -655,6 +925,13 @@ async function runHostTui(identityPath, opts) {
   };
 
   startInterval();
+  void maybeEnsureHostedPublicLink(identityPath).then((result) => {
+    if (result?.data?.public_url) {
+      uiState.publicLinkUrl = result.data.public_url;
+      setStatus(result.created ? `Public link ready: ${result.data.public_url}` : `Public link available: ${result.data.public_url}`, 'ok', 7000);
+      latestState = redraw();
+    }
+  });
 
   process.stdin.on('keypress', async (_str, key) => {
     if (key?.name === 'q' || (key?.ctrl && key?.name === 'c')) {
@@ -762,6 +1039,35 @@ async function runHostTui(identityPath, opts) {
       latestState = redraw();
       return;
     }
+    if (_str === 'A') {
+      const selected = latestState.selectedSession;
+      if (!selected) return;
+      const result = applySessionRecommendation(selected);
+      setStatus(result.message, result.ok ? 'ok' : 'warn');
+      latestState = redraw();
+      return;
+    }
+    if (_str === 'D') {
+      const selected = latestState.selectedSession;
+      if (!selected) return;
+      const result = dismissSessionRecommendation(selected);
+      setStatus(result.message, result.ok ? 'ok' : 'warn');
+      latestState = redraw();
+      return;
+    }
+    if (_str === 'R') {
+      const selected = latestState.selectedSession;
+      if (!selected) return;
+      const result = reopenSessionRecommendation(selected);
+      setStatus(result.message, result.ok ? 'ok' : 'warn');
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'd') {
+      await sendDemoPreset();
+      latestState = redraw();
+      return;
+    }
     if (key?.name === 'p' && uiState.view === 'detail') {
       const selected = latestState.selectedSession;
       if (!selected?.conversation_id) return;
@@ -784,6 +1090,51 @@ async function runHostTui(identityPath, opts) {
       latestState = redraw();
       return;
     }
+    if (_str === 'S' && uiState.view === 'detail') {
+      const selected = latestState.selectedSession;
+      if (!selected) return;
+      const existing = latestState.selectedSessionSummary || {};
+      const input = await promptMultiline(
+        `Edit carry-forward summary as JSON for ${selected.remote_did || selected.session_key}\nCurrent:\n${JSON.stringify({
+          objective: existing.objective || '',
+          context: existing.context || '',
+          constraints: existing.constraints || '',
+          decisions: existing.decisions || '',
+          open_questions: existing.open_questions || '',
+          next_action: existing.next_action || '',
+          handoff_ready_text: existing.handoff_ready_text || '',
+        }, null, 2)}`
+      );
+      if (!input.trim()) {
+        setStatus('Summary update cancelled.', 'warn');
+        latestState = redraw();
+        return;
+      }
+      try {
+        const parsed = JSON.parse(input);
+        const store = openStore(identityPath);
+        try {
+          const manager = new SessionSummaryManager(store);
+          manager.upsert({
+            session_key: selected.session_key,
+            objective: parsed.objective,
+            context: parsed.context,
+            constraints: parsed.constraints,
+            decisions: parsed.decisions,
+            open_questions: parsed.open_questions,
+            next_action: parsed.next_action,
+            handoff_ready_text: parsed.handoff_ready_text,
+          });
+        } finally {
+          store.close();
+        }
+        setStatus(`Saved carry-forward summary for ${selected.session_key}`, 'ok');
+      } catch (error) {
+        setStatus(`Summary update failed: ${error?.message || 'invalid JSON'}`, 'err', 9000);
+      }
+      latestState = redraw();
+      return;
+    }
     if (key?.name === 'o' && uiState.view === 'detail') {
       uiState.view = 'history';
       uiState.selectedHistoryPageIndex = 0;
@@ -851,6 +1202,21 @@ async function runHostTui(identityPath, opts) {
       latestState = redraw();
       return;
     }
+    if (key?.name === 'f') {
+      const confirmed = await confirmAction('Repair OpenClaw hooks config now? A timestamped backup will be written first.');
+      if (!confirmed) {
+        setStatus('Hooks repair cancelled.', 'warn');
+        latestState = redraw();
+        return;
+      }
+      const result = runOpenClawInstall(['fix-hooks']);
+      setStatus(result.ok
+        ? `Hooks repaired.${result.stdout ? ` ${truncateLine(result.stdout.replace(/\s+/g, ' '), 100)}` : ''}`
+        : `Hooks repair failed: ${truncateLine(result.stderr || result.stdout || 'unknown error', 120)}`,
+      result.ok ? 'ok' : 'err', result.ok ? 7000 : 9000);
+      latestState = redraw();
+      return;
+    }
     if (key?.name === 'y' && uiState.view === 'task-detail') {
       const tasks = latestState.selectedTasks || [];
       const task = tasks[Math.max(0, Math.min(uiState.selectedTaskIndex, Math.max(0, tasks.length - 1)))] || null;
@@ -916,6 +1282,51 @@ async function getClientWithStore(identityPath) {
   return { client, store };
 }
 
+function resolveSessionFromStore(store, args = {}) {
+  const sessionManager = new SessionManager(store);
+  let session = args.sessionKey ? sessionManager.get(args.sessionKey) : null;
+  if (!session && args.conversationId) session = sessionManager.getByConversationId(args.conversationId);
+  if (!session && args.remoteDid) {
+    session = sessionManager.listRecentSessions(200).find((item) => item.remote_did === args.remoteDid) ?? null;
+  }
+  return session ?? sessionManager.getActiveSession() ?? sessionManager.listRecentSessions(1)[0] ?? null;
+}
+
+async function resolveTarget(client, target) {
+  const value = String(target ?? '').trim();
+  if (!value) throw new Error('Missing target');
+  if (value.startsWith('did:agent:')) return value;
+  if (value.startsWith('@')) {
+    const resolved = await client.resolveAlias(value.slice(1));
+    if (!resolved.ok || !resolved.data?.did) {
+      throw new Error(resolved.error?.message || `Cannot resolve alias ${value}`);
+    }
+    return resolved.data.did;
+  }
+  const publicAgent = await client.getPublicAgent(value).catch(() => ({ ok: false }));
+  if (publicAgent.ok && publicAgent.data?.did) return publicAgent.data.did;
+  return value;
+}
+
+async function maybeEnsureHostedPublicLink(identityPath) {
+  const p = identityPath ?? getEffectiveIdentityPath();
+  const id = loadIdentity(p);
+  if (!isOfficialHostedServer(id.serverUrl ?? DEFAULT_SERVER)) return null;
+  const key = `${p}:${normalizeOrigin(id.serverUrl ?? DEFAULT_SERVER)}`;
+  if (hostedPublicLinkAttempts.has(key)) return null;
+  hostedPublicLinkAttempts.add(key);
+  try {
+    const client = await getClient(p);
+    const current = await client.getPublicSelf().catch(() => ({ ok: false }));
+    if (current.ok && current.data?.public_url) return { created: false, data: current.data };
+    const created = await client.createPublicLink({ enabled: true }).catch(() => ({ ok: false }));
+    if (created.ok && created.data) return { created: true, data: created.data };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 const program = new Command();
 program
   .name('pingagent')
@@ -2249,6 +2660,467 @@ billing
     }
   });
 
+const publicCmd = program.command('public').description('Hosted public growth surface: shareable profile links, contact cards, and task shares');
+
+publicCmd
+  .command('link')
+  .description('Create or update your hosted public share link')
+  .option('--slug <slug>', 'Preferred public slug')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.createPublicLink({ slug: opts.slug });
+    if (!res.ok) {
+      if (opts.json) console.log(JSON.stringify(res, null, 2));
+      else printError(res.error);
+      process.exit(1);
+    }
+    if (opts.json) console.log(JSON.stringify(res.data, null, 2));
+    else {
+      console.log(`Public slug: ${res.data.public_slug || '(none)'}`);
+      console.log(`Canonical:   ${res.data.canonical_slug || '(none)'}`);
+      console.log(`URL:         ${res.data.public_url || '(none)'}`);
+    }
+  });
+
+publicCmd
+  .command('profile')
+  .description('Show your hosted public share state')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    await maybeEnsureHostedPublicLink();
+    const res = await client.getPublicSelf();
+    if (!res.ok) {
+      if (opts.json) console.log(JSON.stringify(res, null, 2));
+      else printError(res.error);
+      process.exit(1);
+    }
+    if (opts.json) console.log(JSON.stringify(res.data, null, 2));
+    else {
+      console.log(`DID:         ${res.data.did}`);
+      console.log(`Alias:       ${res.data.alias || '(none)'}`);
+      console.log(`Public slug: ${res.data.public_slug || '(none)'}`);
+      console.log(`Enabled:     ${res.data.public_share_enabled ? 'yes' : 'no'}`);
+      console.log(`Discoverable:${res.data.discoverable ? ' yes' : ' no'}`);
+      console.log(`URL:         ${res.data.public_url || '(none)'}`);
+    }
+  });
+
+publicCmd
+  .command('contact-card')
+  .description('Create a shareable contact card for this agent or another target DID')
+  .option('--target-did <did>', 'Target DID to place in the contact card')
+  .option('--intro-note <text>', 'Intro note shown on the card')
+  .option('--message-template <text>', 'Suggested first-message template')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.createContactCard({
+      target_did: opts.targetDid,
+      intro_note: opts.introNote,
+      message_template: opts.messageTemplate,
+    });
+    if (!res.ok) {
+      if (opts.json) console.log(JSON.stringify(res, null, 2));
+      else printError(res.error);
+      process.exit(1);
+    }
+    if (opts.json) console.log(JSON.stringify(res.data, null, 2));
+    else {
+      console.log(`Contact card: ${res.data.id}`);
+      console.log(`Target DID:   ${res.data.target_did}`);
+      console.log(`URL:          ${res.data.share_url || '(none)'}`);
+    }
+  });
+
+publicCmd
+  .command('task-share')
+  .description('Publish a shareable task result summary (explicit publish only)')
+  .requiredOption('--summary <text>', 'Generated summary to publish')
+  .option('--task-id <id>', 'Task ID')
+  .option('--title <title>', 'Task title')
+  .option('--status <status>', 'Task status', 'processed')
+  .option('--conversation <id>', 'Conversation ID')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const res = await client.createTaskShare({
+      task_id: opts.taskId,
+      title: opts.title,
+      status: opts.status,
+      summary: opts.summary,
+      conversation_id: opts.conversation,
+    });
+    if (!res.ok) {
+      if (opts.json) console.log(JSON.stringify(res, null, 2));
+      else printError(res.error);
+      process.exit(1);
+    }
+    if (opts.json) console.log(JSON.stringify(res.data, null, 2));
+    else {
+      console.log(`Task share: ${res.data.id}`);
+      console.log(`URL:        ${res.data.share_url || '(none)'}`);
+    }
+  });
+
+program
+  .command('capability-card')
+  .description('Show or update the structured machine-readable capability card for this agent')
+  .option('--summary <text>', 'Capability card summary')
+  .option('--accepts-new-work <value>', 'true or false')
+  .option('--preferred-contact-mode <mode>', 'dm, task, or either')
+  .option('--capability-item <json>', 'Capability item JSON; repeat to add/replace entries by id', (value, acc) => {
+    acc.push(value);
+    return acc;
+  }, [])
+  .option('--replace-items', 'Replace capability items with the provided --capability-item rows instead of merging by id')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const profileRes = await client.getProfile();
+    if (!profileRes.ok || !profileRes.data) {
+      if (opts.json) console.log(JSON.stringify(profileRes, null, 2));
+      else printError(profileRes.error);
+      process.exit(1);
+    }
+    const current = profileRes.data.capability_card || { version: '1', capabilities: [] };
+    const shouldUpdate =
+      opts.summary !== undefined
+      || opts.acceptsNewWork !== undefined
+      || opts.preferredContactMode !== undefined
+      || (opts.capabilityItem && opts.capabilityItem.length > 0)
+      || opts.replaceItems;
+    if (!shouldUpdate) {
+      if (opts.json) console.log(JSON.stringify(current, null, 2));
+      else {
+        console.log(`summary=${formatCapabilityCardSummary(current)}`);
+        console.log(JSON.stringify(current, null, 2));
+      }
+      return;
+    }
+    let capabilityItems = Array.isArray(current.capabilities) ? [...current.capabilities] : [];
+    if (opts.capabilityItem && opts.capabilityItem.length > 0) {
+      const parsedItems = opts.capabilityItem.map((item) => JSON.parse(item));
+      if (opts.replaceItems) {
+        capabilityItems = parsedItems;
+      } else {
+        const byId = new Map(capabilityItems.map((item) => [item.id, item]));
+        for (const item of parsedItems) {
+          byId.set(item.id, { ...(byId.get(item.id) || {}), ...item });
+        }
+        capabilityItems = Array.from(byId.values());
+      }
+    } else if (opts.replaceItems) {
+      capabilityItems = [];
+    }
+    const nextCard = {
+      version: current.version || '1',
+      summary: opts.summary !== undefined ? opts.summary : current.summary,
+      accepts_new_work: opts.acceptsNewWork !== undefined
+        ? String(opts.acceptsNewWork).trim().toLowerCase() === 'true'
+        : current.accepts_new_work,
+      preferred_contact_mode: opts.preferredContactMode !== undefined
+        ? opts.preferredContactMode
+        : current.preferred_contact_mode,
+      capabilities: capabilityItems,
+    };
+    const updateRes = await client.updateProfile({ capability_card: nextCard });
+    if (!updateRes.ok || !updateRes.data) {
+      if (opts.json) console.log(JSON.stringify(updateRes, null, 2));
+      else printError(updateRes.error);
+      process.exit(1);
+    }
+    if (opts.json) console.log(JSON.stringify(updateRes.data.capability_card || nextCard, null, 2));
+    else {
+      console.log(`summary=${formatCapabilityCardSummary(updateRes.data.capability_card || nextCard)}`);
+      console.log(JSON.stringify(updateRes.data.capability_card || nextCard, null, 2));
+    }
+  });
+
+program
+  .command('session-summary')
+  .description('Show or update the local carry-forward summary for a session')
+  .option('--session-key <key>', 'Exact session key')
+  .option('--conversation-id <id>', 'Conversation ID')
+  .option('--remote-did <did>', 'Remote DID')
+  .option('--objective <text>', 'Current objective')
+  .option('--context <text>', 'Current context')
+  .option('--constraints <text>', 'Constraints')
+  .option('--decisions <text>', 'Decisions already made')
+  .option('--open-questions <text>', 'Open questions')
+  .option('--next-action <text>', 'Next action')
+  .option('--handoff-ready-text <text>', 'Handoff-ready summary text')
+  .option('--clear-field <field>', 'Clear one summary field; repeatable', (value, acc) => {
+    acc.push(value);
+    return acc;
+  }, [])
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    const store = openStore(identityPath);
+    try {
+      const session = resolveSessionFromStore(store, {
+        sessionKey: opts.sessionKey,
+        conversationId: opts.conversationId,
+        remoteDid: opts.remoteDid,
+      });
+      if (!session) {
+        console.error('No session found. Use pingagent host tui or pingagent recent sessions first.');
+        process.exit(1);
+      }
+      const manager = new SessionSummaryManager(store);
+      const clearFields = Array.isArray(opts.clearField)
+        ? opts.clearField
+            .map((value) => String(value || '').trim())
+            .filter((value) => SESSION_SUMMARY_FIELDS.includes(value))
+        : [];
+      if (Array.isArray(opts.clearField) && opts.clearField.length !== clearFields.length) {
+        console.error(`clear-field must be one of: ${SESSION_SUMMARY_FIELDS.join(', ')}`);
+        process.exit(1);
+      }
+      const shouldUpdate = [
+        opts.objective,
+        opts.context,
+        opts.constraints,
+        opts.decisions,
+        opts.openQuestions,
+        opts.nextAction,
+        opts.handoffReadyText,
+      ].some((value) => value !== undefined) || clearFields.length > 0;
+      let summary = shouldUpdate
+        ? manager.upsert({
+            session_key: session.session_key,
+            objective: opts.objective,
+            context: opts.context,
+            constraints: opts.constraints,
+            decisions: opts.decisions,
+            open_questions: opts.openQuestions,
+            next_action: opts.nextAction,
+            handoff_ready_text: opts.handoffReadyText,
+          })
+        : manager.get(session.session_key);
+      if (clearFields.length > 0) {
+        summary = manager.clearFields(session.session_key, clearFields);
+      }
+      if (opts.json) {
+        console.log(JSON.stringify({ session, summary }, null, 2));
+      } else {
+        console.log(`session=${session.session_key}`);
+        console.log(`conversation=${session.conversation_id || '(none)'}`);
+        console.log(`remote=${session.remote_did || '(unknown)'}`);
+        console.log(JSON.stringify(summary, null, 2));
+      }
+    } finally {
+      store.close();
+    }
+  });
+
+program
+  .command('handoff')
+  .description('Send a first-class delegation / handoff task using the current task-thread transport')
+  .requiredOption('--to <target>', 'Target DID, alias, public slug, or connectable identity')
+  .requiredOption('--title <title>', 'Task title')
+  .option('--description <text>', 'Task description')
+  .option('--objective <text>', 'Delegation objective')
+  .option('--success-criteria <text>', 'Success criteria')
+  .option('--priority <text>', 'Priority label')
+  .option('--carry-forward-summary <text>', 'Explicit carry-forward summary; otherwise use the session summary')
+  .option('--callback-session-key <key>', 'Callback session key to reference in the handoff')
+  .option('--session-key <key>', 'Source session key whose summary should be used')
+  .option('--conversation-id <id>', 'Source conversation ID whose summary should be used')
+  .option('--remote-did <did>', 'Source remote DID whose summary should be used')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    const { client, store } = await getClientWithStore(identityPath);
+    try {
+      const targetDid = await resolveTarget(client, opts.to);
+      const sourceSession = resolveSessionFromStore(store, {
+        sessionKey: opts.sessionKey,
+        conversationId: opts.conversationId,
+        remoteDid: opts.remoteDid,
+      });
+      const result = await client.sendHandoff(targetDid, {
+        title: opts.title,
+        description: opts.description,
+        objective: opts.objective,
+        carry_forward_summary: opts.carryForwardSummary,
+        success_criteria: opts.successCriteria,
+        callback_session_key: opts.callbackSessionKey || sourceSession?.session_key,
+        priority: opts.priority,
+      }, {
+        sessionKey: sourceSession?.session_key,
+        conversationId: sourceSession?.conversation_id,
+      });
+      if (!result.ok || !result.data) {
+        if (opts.json) console.log(JSON.stringify(result, null, 2));
+        else printError(result.error);
+        process.exit(1);
+      }
+      if (opts.json) {
+        console.log(JSON.stringify({
+          target_did: targetDid,
+          source_session_key: sourceSession?.session_key ?? null,
+          ...result.data,
+        }, null, 2));
+      } else {
+        console.log(`task_id=${result.data.task_id}`);
+        console.log(`conversation_id=${result.data.conversation_id}`);
+        console.log(`target_did=${targetDid}`);
+        console.log(`source_session_key=${sourceSession?.session_key || '(none)'}`);
+        console.log(JSON.stringify(result.data.handoff, null, 2));
+      }
+    } finally {
+      store.close();
+    }
+  });
+
+program
+  .command('demo')
+  .description('Open or message the official PingAgent demo agent')
+  .option('--preset <name>', 'Preset first message: hello, delegate, or trust')
+  .option('--message <text>', 'Optional first message to send immediately')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    const client = await getClient();
+    const resolved = await client.resolveAlias('pingagent/demo');
+    if (!resolved.ok || !resolved.data?.did) {
+      if (opts.json) console.log(JSON.stringify(resolved, null, 2));
+      else printError(resolved.error);
+      process.exit(1);
+    }
+    const convo = await client.openConversation(resolved.data.did);
+    if (!convo.ok || !convo.data) {
+      if (opts.json) console.log(JSON.stringify(convo, null, 2));
+      else printError(convo.error);
+      process.exit(1);
+    }
+    const presetMessages = {
+      hello: 'Hello',
+      delegate: 'Please show me how task delegation works in PingAgent.',
+      trust: 'Show me how trust decisions and recommendations work.',
+    };
+    const effectiveMessage = typeof opts.message === 'string' && opts.message.trim()
+      ? opts.message
+      : (typeof opts.preset === 'string' && presetMessages[opts.preset.trim().toLowerCase()] ? presetMessages[opts.preset.trim().toLowerCase()] : '');
+    if (effectiveMessage) {
+      const sendRes = await client.sendMessage(convo.data.conversation_id, SCHEMA_TEXT, { text: effectiveMessage });
+      if (!sendRes.ok) {
+        if (opts.json) console.log(JSON.stringify(sendRes, null, 2));
+        else printError(sendRes.error);
+        process.exit(1);
+      }
+      if (opts.json) console.log(JSON.stringify({ did: resolved.data.did, conversation_id: convo.data.conversation_id, message_id: sendRes.data?.message_id, preset: opts.preset ?? null }, null, 2));
+      else console.log(`Demo agent messaged. conversation=${convo.data.conversation_id} message=${sendRes.data?.message_id}`);
+      return;
+    }
+    if (opts.json) console.log(JSON.stringify({ did: resolved.data.did, conversation_id: convo.data.conversation_id }, null, 2));
+    else console.log(`Demo agent ready. did=${resolved.data.did} conversation=${convo.data.conversation_id}`);
+  });
+
+program
+  .command('connect')
+  .description('Consume a PingAgent public link or contact card and open a conversation')
+  .argument('<target>', 'Share URL, contact card URL, public slug, alias, or DID')
+  .option('--message <text>', 'Optional first message to send immediately')
+  .option('--json', 'Output as JSON')
+  .action(async (target, opts) => {
+    const client = await getClient();
+    let targetDid = '';
+    let prefMessage = typeof opts.message === 'string' ? opts.message : '';
+    try {
+      if (/^https?:\/\//.test(target)) {
+        const url = new URL(target);
+        const parts = url.pathname.split('/').filter(Boolean);
+        if (parts[0] === 'c' && parts[1]) {
+          const card = await client.getContactCard(parts[1]);
+          if (!card.ok || !card.data) {
+            if (opts.json) console.log(JSON.stringify(card, null, 2));
+            else printError(card.error);
+            process.exit(1);
+          }
+          targetDid = card.data.target_did;
+          if (!prefMessage && card.data.message_template) prefMessage = card.data.message_template;
+        } else if (parts[0] === 'a' && parts[1]) {
+          const agent = await client.getPublicAgent(parts[1]);
+          if (!agent.ok || !agent.data?.did) {
+            if (opts.json) console.log(JSON.stringify(agent, null, 2));
+            else printError(agent.error);
+            process.exit(1);
+          }
+          targetDid = agent.data.did;
+        } else if (parts[0] === 'connect' && parts[1]) {
+          const requestedTarget = decodeURIComponent(parts[1]);
+          if (!prefMessage && url.searchParams.get('message')) {
+            prefMessage = url.searchParams.get('message') || '';
+          }
+          if (requestedTarget.startsWith('did:agent:')) {
+            targetDid = requestedTarget;
+          } else if (requestedTarget.startsWith('@')) {
+            const resolved = await client.resolveAlias(requestedTarget.slice(1));
+            if (!resolved.ok || !resolved.data?.did) {
+              if (opts.json) console.log(JSON.stringify(resolved, null, 2));
+              else printError(resolved.error);
+              process.exit(1);
+            }
+            targetDid = resolved.data.did;
+          } else {
+            const agent = await client.getPublicAgent(requestedTarget);
+            if (!agent.ok || !agent.data?.did) {
+              if (opts.json) console.log(JSON.stringify(agent, null, 2));
+              else printError(agent.error);
+              process.exit(1);
+            }
+            targetDid = agent.data.did;
+          }
+        }
+      }
+    } catch {
+      // fall through to text target handling
+    }
+    if (!targetDid) {
+      if (String(target).startsWith('did:agent:')) {
+        targetDid = String(target);
+      } else if (String(target).startsWith('@')) {
+        const resolved = await client.resolveAlias(String(target).slice(1));
+        if (!resolved.ok || !resolved.data?.did) {
+          if (opts.json) console.log(JSON.stringify(resolved, null, 2));
+          else printError(resolved.error);
+          process.exit(1);
+        }
+        targetDid = resolved.data.did;
+      } else {
+        const agent = await client.getPublicAgent(String(target));
+        if (!agent.ok || !agent.data?.did) {
+          if (opts.json) console.log(JSON.stringify(agent, null, 2));
+          else printError(agent.error);
+          process.exit(1);
+        }
+        targetDid = agent.data.did;
+      }
+    }
+    const convo = await client.openConversation(targetDid);
+    if (!convo.ok || !convo.data) {
+      if (opts.json) console.log(JSON.stringify(convo, null, 2));
+      else printError(convo.error);
+      process.exit(1);
+    }
+    if (prefMessage) {
+      const sendRes = await client.sendMessage(convo.data.conversation_id, SCHEMA_TEXT, { text: prefMessage });
+      if (!sendRes.ok) {
+        if (opts.json) console.log(JSON.stringify(sendRes, null, 2));
+        else printError(sendRes.error);
+        process.exit(1);
+      }
+      if (opts.json) console.log(JSON.stringify({ did: targetDid, conversation_id: convo.data.conversation_id, message_id: sendRes.data?.message_id }, null, 2));
+      else console.log(`Connected and sent first message. conversation=${convo.data.conversation_id} did=${targetDid}`);
+      return;
+    }
+    if (opts.json) console.log(JSON.stringify({ did: targetDid, conversation_id: convo.data.conversation_id }, null, 2));
+    else console.log(`Connected. conversation=${convo.data.conversation_id} did=${targetDid}`);
+  });
+
 const host = program
   .command('host')
   .description('Headless runtime inspection and control for PingAgent host state');