@pingagent/sdk 0.1.9 → 0.1.10

package/bin/pingagent.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 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 {
   PingAgentClient,
   generateIdentity,
@@ -15,6 +16,19 @@ import {
   ContactManager,
   HistoryManager,
   A2AAdapter,
+  SessionManager,
+  TaskThreadManager,
+  TrustPolicyAuditManager,
+  defaultTrustPolicyDoc,
+  normalizeTrustPolicyDoc,
+  getActiveSessionFilePath,
+  getSessionMapFilePath,
+  getSessionBindingAlertsFilePath,
+  readCurrentActiveSessionKey,
+  readSessionBindings,
+  readSessionBindingAlerts,
+  setSessionBinding,
+  removeSessionBinding,
 } from '../dist/index.js';
 import { ERROR_HINTS, SCHEMA_TEXT } from '@pingagent/schemas';
 
@@ -77,6 +91,780 @@ function openStore(identityPath) {
   return new LocalStore(getStorePath(identityPath));
 }
 
+function getTrustPolicyPath(identityPath) {
+  return process.env.PINGAGENT_TRUST_POLICY_PATH
+    ? resolvePath(process.env.PINGAGENT_TRUST_POLICY_PATH)
+    : path.join(path.dirname(identityPath), 'trust-policy.json');
+}
+
+function readTrustPolicyDoc(identityPath) {
+  const policyPath = getTrustPolicyPath(identityPath);
+  try {
+    if (!fs.existsSync(policyPath)) return { path: policyPath, doc: defaultTrustPolicyDoc() };
+    const raw = JSON.parse(fs.readFileSync(policyPath, 'utf-8'));
+    return { path: policyPath, doc: normalizeTrustPolicyDoc(raw) };
+  } catch {
+    return { path: policyPath, doc: defaultTrustPolicyDoc() };
+  }
+}
+
+function clearScreen() {
+  process.stdout.write('\x1Bc');
+}
+
+function ansi(code, text) {
+  return process.stdout.isTTY ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+
+function formatStatusLine(level, message) {
+  const tag = level === 'ok'
+    ? ansi('32', '[OK]')
+    : level === 'warn'
+      ? ansi('33', '[WARN]')
+      : level === 'err'
+        ? ansi('31', '[ERR]')
+        : ansi('36', '[INFO]');
+  return `${tag} ${message || '(ready)'}`;
+}
+
+function formatStatusTimestamp(tsMs) {
+  if (!tsMs) return '';
+  return formatTs(tsMs, false);
+}
+
+function truncateLine(value, max = 100) {
+  const s = String(value ?? '');
+  return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+
+function formatSessionRow(session, selected) {
+  const marker = selected ? '>' : ' ';
+  const rebind = session.binding_alert ? ' !rebind' : '';
+  const trust = session.trust_state || 'unknown';
+  const unread = session.unread_count ?? 0;
+  const who = truncateLine(session.remote_did || session.conversation_id || 'unknown', 40);
+  return `${marker} ${who} [${trust}] unread=${unread}${rebind}`;
+}
+
+function formatMessageRow(message) {
+  const ts = formatTs(message.ts_ms ?? message.receivedAtMs ?? Date.now(), false);
+  const direction = message.direction || 'unknown';
+  const schema = message.schema || 'unknown';
+  const payload = message.payload || {};
+  const summary = schema === SCHEMA_TEXT && payload.text
+    ? payload.text
+    : JSON.stringify(payload);
+  return `- ${ts} ${direction} ${schema} ${truncateLine(summary, 90)}`;
+}
+
+function buildTaskExportBody(task, format = 'plain') {
+  const payload = {
+    task_id: task.task_id,
+    title: task.title || null,
+    status: task.status,
+    updated_at: task.updated_at ?? null,
+    updated_at_display: task.updated_at ? formatTs(task.updated_at, false) : null,
+    started_at: task.started_at ?? null,
+    started_at_display: task.started_at ? formatTs(task.started_at, false) : null,
+    result: task.result_summary || null,
+    error: task.error_message
+      ? {
+          code: task.error_code || 'E_TASK',
+          message: task.error_message,
+        }
+      : null,
+  };
+  if (format === 'json') return JSON.stringify(payload, null, 2);
+  return [
+    `task_id=${payload.task_id}`,
+    `title=${payload.title || '(none)'}`,
+    `status=${payload.status}`,
+    `updated_at=${payload.updated_at_display || '(none)'}`,
+    payload.started_at_display ? `started_at=${payload.started_at_display}` : null,
+    '',
+    '[result]',
+    payload.result || '(none)',
+    '',
+    '[error]',
+    payload.error ? `${payload.error.code} ${payload.error.message}` : '(none)',
+  ].filter(Boolean).join('\n');
+}
+
+function loadHistoryPage(historyManager, conversationId, pageIndex, pageSize) {
+  if (!conversationId) return { messages: [], pageIndex: 0, hasOlder: false, hasNewer: false };
+  let page = Math.max(0, pageIndex || 0);
+  let messages = historyManager.listRecent(conversationId, pageSize);
+  if (messages.length === 0) {
+    return { messages: [], pageIndex: 0, hasOlder: false, hasNewer: false };
+  }
+  for (let i = 0; i < page; i++) {
+    const first = messages[0];
+    if (!first) {
+      page = i;
+      messages = [];
+      break;
+    }
+    const older = first.seq != null
+      ? historyManager.listBeforeSeq(conversationId, first.seq, pageSize)
+      : historyManager.listBeforeTs(conversationId, first.ts_ms, pageSize);
+    if (!older.length) {
+      page = i;
+      break;
+    }
+    messages = older;
+  }
+  const first = messages[0];
+  const hasOlder = !!first && (
+    first.seq != null
+      ? historyManager.listBeforeSeq(conversationId, first.seq, 1).length > 0
+      : historyManager.listBeforeTs(conversationId, first.ts_ms, 1).length > 0
+  );
+  return {
+    messages,
+    pageIndex: page,
+    hasOlder,
+    hasNewer: page > 0,
+  };
+}
+
+function buildHostState(identityPath, selectedSessionKey = null, historyPageIndex = 0, historySearchQuery = '') {
+  const identity = loadIdentity(identityPath);
+  const store = openStore(identityPath);
+  try {
+    const sessionManager = new SessionManager(store);
+    const taskManager = new TaskThreadManager(store);
+    const historyManager = new HistoryManager(store);
+    const auditManager = new TrustPolicyAuditManager(store);
+    const sessions = sessionManager.listRecentSessions(50);
+    const bindings = readSessionBindings();
+    const alerts = readSessionBindingAlerts();
+    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 desiredSelectedSessionKey =
+      (selectedSessionKey && sessions.some((session) => session.session_key === selectedSessionKey) ? selectedSessionKey : null) ??
+      sessionManager.getActiveSession()?.session_key ??
+      sessions[0]?.session_key ??
+      null;
+    const policy = readTrustPolicyDoc(identityPath);
+    const runtimeMode = process.env.PINGAGENT_RUNTIME_MODE || 'bridge';
+    const sessionsWithMeta = sessions.map((session) => ({
+      ...session,
+      binding: session.conversation_id ? (bindingByConversation.get(session.conversation_id) ?? null) : null,
+      binding_alert: session.conversation_id ? (alertByConversation.get(session.conversation_id) ?? null) : null,
+      is_active_chat_session: session.session_key === activeChatSession,
+    }));
+    const selectedSession = sessionsWithMeta.find((session) => session.session_key === desiredSelectedSessionKey) ?? null;
+    const selectedTasks = selectedSession
+      ? taskManager.listBySession(selectedSession.session_key, 12)
+      : [];
+    const selectedAuditEvents = selectedSession
+      ? auditManager.listBySession(selectedSession.session_key, 12)
+      : [];
+    const selectedMessages = selectedSession?.conversation_id
+      ? historyManager.listRecent(selectedSession.conversation_id, 12)
+      : [];
+    const selectedHistoryPage = selectedSession?.conversation_id
+      ? loadHistoryPage(historyManager, selectedSession.conversation_id, historyPageIndex, 20)
+      : { messages: [], pageIndex: 0, hasOlder: false, hasNewer: false };
+    const selectedHistorySearchResults = selectedSession?.conversation_id && historySearchQuery.trim()
+      ? historyManager.search(historySearchQuery.trim(), { conversationId: selectedSession.conversation_id, limit: 50 })
+      : [];
+    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,
+      activeChatSessionFile: getActiveSessionFilePath(),
+      sessionMapPath: getSessionMapFilePath(),
+      sessionBindingAlertsPath: getSessionBindingAlertsFilePath(),
+      policyPath: policy.path,
+      policyDoc: policy.doc,
+      sessions: sessionsWithMeta,
+      tasks: taskManager.listRecent(30),
+      auditEvents: auditManager.listRecent(40),
+      selectedSession,
+      selectedTasks,
+      selectedAuditEvents,
+      selectedMessages,
+      selectedHistoryPage,
+      selectedHistorySearchQuery: historySearchQuery.trim(),
+      selectedHistorySearchResults,
+      unreadTotal,
+      alertSessions,
+    };
+  } finally {
+    store.close();
+  }
+}
+
+function renderHostTuiScreen(hostState, uiState) {
+  const sessions = hostState.sessions || [];
+  const selected = hostState.selectedSession || sessions[0] || null;
+  const tasks = hostState.selectedTasks || [];
+  const auditEvents = hostState.selectedAuditEvents || [];
+  const messages = hostState.selectedMessages || [];
+  const historyPage = hostState.selectedHistoryPage || { messages: [], pageIndex: 0, hasOlder: false, hasNewer: false };
+  const historySearchQuery = hostState.selectedHistorySearchQuery || '';
+  const historySearchResults = hostState.selectedHistorySearchResults || [];
+  const view = uiState?.view || 'overview';
+  const selectedTaskIndex = Math.max(0, Math.min(uiState?.selectedTaskIndex || 0, Math.max(0, tasks.length - 1)));
+  const selectedTask = tasks[selectedTaskIndex] || null;
+  const statusCountdown = uiState?.statusExpiresAt
+    ? ` (${Math.max(0, Math.ceil((uiState.statusExpiresAt - Date.now()) / 1000))}s)`
+    : '';
+  const statusTs = uiState?.statusAt ? ` @ ${formatStatusTimestamp(uiState.statusAt)}` : '';
+  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)'}`,
+    `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}`,
+    '',
+  ];
+
+  if (view === 'help') {
+    lines.push('Help');
+    lines.push('- ↑/↓ or j/k: move selection');
+    lines.push('- Enter or l: open detailed session view / task detail');
+    lines.push('- Esc or h: back to previous view');
+    lines.push('- g / G: jump to first / last session');
+    lines.push('- r: refresh now');
+    lines.push('- a: approve selected pending contact');
+    lines.push('- m: mark selected session as read');
+    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('- 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('- b: bind selected conversation to current chat session');
+    lines.push('- c: clear selected binding');
+    lines.push('- q: quit');
+  } else if (view === 'history') {
+    lines.push('Conversation History');
+    if (!selected) {
+      lines.push('No session selected.');
+    } else {
+      lines.push(`session=${selected.session_key}`);
+      lines.push(`conversation=${selected.conversation_id || '(none)'}`);
+      lines.push(`remote=${selected.remote_did || '(unknown)'}`);
+      if (historySearchQuery) {
+        lines.push(`search=${historySearchQuery}  results=${historySearchResults.length}`);
+        lines.push('actions=[s or /] search  [n] clear-search  [h/Esc] back');
+      } else {
+        lines.push(`page=${historyPage.pageIndex + 1}  has_newer=${historyPage.hasNewer}  has_older=${historyPage.hasOlder}`);
+        lines.push('actions=[s or /] search  [n] older  [p] newer  [h/Esc] back');
+      }
+      lines.push('');
+      lines.push(...((historySearchQuery ? historySearchResults : historyPage.messages).length
+        ? (historySearchQuery ? historySearchResults : historyPage.messages).map((message) => formatMessageRow(message))
+        : ['- none']));
+    }
+  } else if (view === 'task-detail') {
+    lines.push('Task Result Detail');
+    if (!selected) {
+      lines.push('No session selected.');
+    } else if (!selectedTask) {
+      lines.push('No task selected.');
+    } else {
+      lines.push(`session=${selected.session_key}`);
+      lines.push(`conversation=${selected.conversation_id || '(none)'}`);
+      lines.push(`remote=${selected.remote_did || '(unknown)'}`);
+      lines.push('');
+      lines.push(`task=${selectedTask.task_id}`);
+      lines.push(`title=${selectedTask.title || '(none)'}`);
+      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)}`);
+      lines.push('actions=[x] cancel-task  [y] dump-stdout  [j/k] switch-task  [h/Esc] back-to-tasks');
+      lines.push('');
+      lines.push('Result');
+      lines.push(selectedTask.result_summary || '(none)');
+      lines.push('');
+      lines.push('Error');
+      lines.push(selectedTask.error_message ? `${selectedTask.error_code || 'E_TASK'} ${selectedTask.error_message}` : '(none)');
+      lines.push('');
+      lines.push('Tasks In Session');
+      lines.push(...tasks.map((task, idx) => `${idx === selectedTaskIndex ? '>' : ' '} ${task.task_id} [${task.status}] ${truncateLine(task.title || task.result_summary || '', 70)}`));
+    }
+  } else if (view === 'tasks') {
+    lines.push('Task Detail');
+    if (!selected) {
+      lines.push('No session selected.');
+    } else if (!selectedTask) {
+      lines.push('No tasks in the selected session.');
+    } else {
+      lines.push(`session=${selected.session_key}`);
+      lines.push(`conversation=${selected.conversation_id || '(none)'}`);
+      lines.push(`remote=${selected.remote_did || '(unknown)'}`);
+      lines.push('');
+      lines.push(`task=${selectedTask.task_id}`);
+      lines.push(`title=${selectedTask.title || '(none)'}`);
+      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.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());
+      }
+      lines.push(`actions=[Enter/l] full-detail  [x] cancel-task  [h/Esc] back  [j/k] select-task`);
+      lines.push('');
+      lines.push('Tasks In Session');
+      lines.push(...tasks.map((task, idx) => `${idx === selectedTaskIndex ? '>' : ' '} ${task.task_id} [${task.status}] ${truncateLine(task.title || task.result_summary || '', 70)}`));
+    }
+  } else {
+    lines.push('Sessions');
+    lines.push(...(sessions.length
+      ? sessions.slice(0, 20).map((session) => formatSessionRow(session, session.session_key === (selected?.session_key || '')))
+      : ['  (no sessions)']));
+    lines.push('');
+
+    if (selected) {
+      lines.push(view === 'detail' ? 'Selected Session Detail' : 'Selected Session');
+      lines.push(`session=${selected.session_key}`);
+      lines.push(`conversation=${selected.conversation_id || '(none)'}`);
+      lines.push(`remote=${selected.remote_did || '(unknown)'}`);
+      lines.push(`trust=${selected.trust_state} unread=${selected.unread_count}`);
+      lines.push(`last_preview=${selected.last_message_preview || '(none)'}`);
+      lines.push(`binding=${selected.binding?.session_key || '(unbound)'}`);
+      lines.push(`current_chat=${hostState.activeChatSession || '(none)'}`);
+      if (selected.binding_alert) {
+        lines.push(`needs_rebind=true`);
+        lines.push(`warning=${selected.binding_alert.message}`);
+      } else {
+        lines.push('needs_rebind=false');
+      }
+      const actionBar = [
+        selected.trust_state === 'pending' ? '[a] approve' : null,
+        '[m] mark-read',
+        '[p] reply',
+        '[o] history',
+        '[t] tasks',
+        '[b] bind-current',
+        '[c] clear-binding',
+      ].filter(Boolean).join('  ');
+      lines.push(`actions=${actionBar}`);
+      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)}`)
+        : ['- none']));
+      if (view === 'detail') {
+        lines.push('');
+        lines.push('Recent Messages');
+        lines.push(...(messages.length ? messages.map((message) => formatMessageRow(message)) : ['- none']));
+      }
+      lines.push('');
+      lines.push('Audit');
+      lines.push(...(auditEvents.length
+        ? auditEvents.map((event) => `- ${event.event_type} ${event.action || event.outcome || ''} ${truncateLine(event.explanation || '', 80)}`)
+        : ['- none']));
+    } else {
+      lines.push('No session selected.');
+    }
+  }
+
+  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');
+  return lines.join('\n');
+}
+
+async function runHostTui(identityPath, opts) {
+  const once = !!opts.once;
+  const refreshMs = Math.max(500, Number.parseInt(String(opts.refreshMs || '2000'), 10) || 2000);
+
+  const uiState = {
+    selectedSessionKey: null,
+    view: 'overview',
+    selectedTaskIndex: 0,
+    statusMessage: '(ready)',
+    statusLevel: 'info',
+    statusExpiresAt: 0,
+    statusAt: 0,
+    selectedHistoryPageIndex: 0,
+    historySearchQuery: '',
+  };
+
+  const render = () => {
+    if (uiState.statusExpiresAt && Date.now() >= uiState.statusExpiresAt) {
+      uiState.statusMessage = '(ready)';
+      uiState.statusLevel = 'info';
+      uiState.statusExpiresAt = 0;
+      uiState.statusAt = 0;
+    }
+    const hostState = buildHostState(
+      identityPath,
+      uiState.selectedSessionKey,
+      uiState.selectedHistoryPageIndex,
+      uiState.historySearchQuery,
+    );
+    uiState.selectedSessionKey = hostState.selectedSession?.session_key || hostState.sessions[0]?.session_key || null;
+    uiState.selectedHistoryPageIndex = hostState.selectedHistoryPage?.pageIndex || 0;
+    const screen = renderHostTuiScreen(hostState, uiState);
+    return { hostState, screen };
+  };
+
+  if (once) {
+    const { screen } = render();
+    console.log(screen);
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error('Host TUI requires a TTY. Use --once for a snapshot in non-interactive environments.');
+    process.exit(1);
+  }
+
+  let interval = null;
+  const redraw = () => {
+    const rendered = render();
+    clearScreen();
+    process.stdout.write(`${rendered.screen}\n`);
+    return rendered.hostState;
+  };
+
+  let latestState = redraw();
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+
+  const cleanup = () => {
+    if (interval) clearInterval(interval);
+    if (process.stdin.setRawMode) process.stdin.setRawMode(false);
+    process.stdin.pause();
+  };
+
+  const setStatus = (message, level = 'info', ttlMs = 5000) => {
+    uiState.statusMessage = truncateLine(message || '(ready)', 160);
+    uiState.statusLevel = level;
+    uiState.statusExpiresAt = ttlMs > 0 ? Date.now() + ttlMs : 0;
+    uiState.statusAt = Date.now();
+  };
+
+  const promptLine = async (question) => {
+    stopInterval();
+    if (process.stdin.setRawMode) process.stdin.setRawMode(false);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const answer = await new Promise((resolve) => {
+        rl.question(question, resolve);
+      });
+      return String(answer ?? '');
+    } finally {
+      rl.close();
+      if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+      startInterval();
+    }
+  };
+
+  const promptMultiline = async (question) => {
+    stopInterval();
+    if (process.stdin.setRawMode) process.stdin.setRawMode(false);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const lines = [];
+    try {
+      process.stdout.write(`${question}\nFinish with a single "." on its own line.\n`);
+      while (true) {
+        // eslint-disable-next-line no-await-in-loop
+        const line = await new Promise((resolve) => rl.question('> ', resolve));
+        const text = String(line ?? '');
+        if (text === '.') break;
+        lines.push(text);
+      }
+      return lines.join('\n').trim();
+    } finally {
+      rl.close();
+      if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+      startInterval();
+    }
+  };
+
+  const dumpStdoutBlock = async (title, body) => {
+    stopInterval();
+    if (process.stdin.setRawMode) process.stdin.setRawMode(false);
+    try {
+      process.stdout.write(`\n===== ${title} =====\n${body}\n===== end =====\nPress Enter to return...`);
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      await new Promise((resolve) => rl.question('', resolve));
+      rl.close();
+    } finally {
+      if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+      startInterval();
+    }
+  };
+
+  const confirmAction = async (question) => {
+    const answer = await promptLine(`${question} [y/N] `);
+    return answer.trim().toLowerCase() === 'y';
+  };
+
+  const moveSelection = (delta) => {
+    if (uiState.view === 'tasks' || uiState.view === 'task-detail') {
+      const tasks = latestState.selectedTasks || [];
+      if (!tasks.length) return;
+      uiState.selectedTaskIndex = Math.min(tasks.length - 1, Math.max(0, uiState.selectedTaskIndex + delta));
+    } else if (uiState.view === 'history' && !uiState.historySearchQuery) {
+      if (delta > 0 && latestState.selectedHistoryPage?.hasOlder) uiState.selectedHistoryPageIndex += 1;
+      if (delta < 0 && latestState.selectedHistoryPage?.hasNewer) uiState.selectedHistoryPageIndex = Math.max(0, uiState.selectedHistoryPageIndex - 1);
+    } else {
+      const sessions = latestState.sessions || [];
+      if (!sessions.length) return;
+      const idx = Math.max(0, sessions.findIndex((session) => session.session_key === uiState.selectedSessionKey));
+      const next = Math.min(sessions.length - 1, Math.max(0, idx + delta));
+      uiState.selectedSessionKey = sessions[next].session_key;
+      uiState.selectedTaskIndex = 0;
+      uiState.selectedHistoryPageIndex = 0;
+      uiState.historySearchQuery = '';
+    }
+    latestState = redraw();
+  };
+
+  const jumpSelection = (target) => {
+    if (uiState.view === 'tasks' || uiState.view === 'task-detail') {
+      const tasks = latestState.selectedTasks || [];
+      if (!tasks.length) return;
+      uiState.selectedTaskIndex = target;
+    } else if (uiState.view === 'history') {
+      uiState.selectedHistoryPageIndex = 0;
+    } else {
+      const sessions = latestState.sessions || [];
+      if (!sessions.length) return;
+      uiState.selectedSessionKey = sessions[target].session_key;
+      uiState.selectedTaskIndex = 0;
+      uiState.selectedHistoryPageIndex = 0;
+      uiState.historySearchQuery = '';
+    }
+    latestState = redraw();
+  };
+
+  const stopInterval = () => {
+    if (interval) clearInterval(interval);
+    interval = null;
+  };
+
+  const startInterval = () => {
+    stopInterval();
+    interval = setInterval(() => {
+      latestState = redraw();
+    }, refreshMs);
+  };
+
+  startInterval();
+
+  process.stdin.on('keypress', async (_str, key) => {
+    if (key?.name === 'q' || (key?.ctrl && key?.name === 'c')) {
+      cleanup();
+      process.stdout.write('\n');
+      process.exit(0);
+    }
+    if (key?.name === 'up' || key?.name === 'k') return moveSelection(-1);
+    if (key?.name === 'down' || key?.name === 'j') return moveSelection(1);
+    if (key?.name === 'g') return jumpSelection(0);
+    if (_str === 'G') {
+      const max = uiState.view === 'tasks' || uiState.view === 'task-detail'
+        ? Math.max(0, (latestState.selectedTasks || []).length - 1)
+        : Math.max(0, (latestState.sessions || []).length - 1);
+      return jumpSelection(max);
+    }
+    if (key?.name === 'return' || key?.name === 'enter' || key?.name === 'l') {
+      if (uiState.view === 'tasks') {
+        uiState.view = 'task-detail';
+      } else {
+        uiState.view = 'detail';
+      }
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'escape' || key?.name === 'h') {
+      if (uiState.view === 'task-detail') uiState.view = 'tasks';
+      else if (uiState.view === 'history') uiState.view = 'detail';
+      else uiState.view = 'overview';
+      latestState = redraw();
+      return;
+    }
+    if (_str === '?') {
+      uiState.view = uiState.view === 'help' ? 'overview' : 'help';
+      latestState = redraw();
+      return;
+    }
+    if (_str === 'n' && uiState.view === 'history') {
+      if (uiState.historySearchQuery) {
+        uiState.historySearchQuery = '';
+        setStatus('Cleared history search.', 'info');
+        latestState = redraw();
+        return;
+      }
+      if (latestState.selectedHistoryPage?.hasOlder) {
+        uiState.selectedHistoryPageIndex += 1;
+        setStatus(`History page ${uiState.selectedHistoryPageIndex + 1}`, 'info');
+        latestState = redraw();
+      }
+      return;
+    }
+    if (_str === 'p' && uiState.view === 'history') {
+      if (uiState.historySearchQuery) return;
+      if (latestState.selectedHistoryPage?.hasNewer) {
+        uiState.selectedHistoryPageIndex = Math.max(0, uiState.selectedHistoryPageIndex - 1);
+        setStatus(`History page ${uiState.selectedHistoryPageIndex + 1}`, 'info');
+        latestState = redraw();
+      }
+      return;
+    }
+    if (key?.name === 't') {
+      uiState.view = 'tasks';
+      uiState.selectedTaskIndex = 0;
+      uiState.selectedHistoryPageIndex = 0;
+      setStatus('Opened task list view.', 'info');
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'r') {
+      setStatus('Refreshed.', 'info');
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'm') {
+      const selected = latestState.selectedSession;
+      if (!selected) return;
+      const store = openStore(identityPath);
+      try {
+        const sessions = new SessionManager(store);
+        sessions.markRead(selected.session_key);
+        setStatus(`Marked session as read: ${selected.session_key}`, 'ok');
+      } finally {
+        store.close();
+      }
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'a') {
+      const selected = latestState.selectedSession;
+      if (!selected?.conversation_id || selected.trust_state !== 'pending') return;
+      const confirmed = await confirmAction(`Approve pending conversation ${selected.conversation_id}\nRemote DID: ${selected.remote_did || '(unknown)'}\nProceed?`);
+      if (confirmed) {
+        const { client, store } = await getClientWithStore(identityPath);
+        try {
+          const res = await client.approveContact(selected.conversation_id);
+          setStatus(res.ok
+            ? `Approved conversation ${selected.conversation_id}${res.data?.dm_conversation_id ? ` -> ${res.data.dm_conversation_id}` : ''}`
+            : `Approve failed: ${res.error?.message || 'unknown error'}`, res.ok ? 'ok' : 'err');
+        } finally {
+          store.close();
+        }
+      } else {
+        setStatus('Approve cancelled.', 'warn');
+      }
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'p' && uiState.view === 'detail') {
+      const selected = latestState.selectedSession;
+      if (!selected?.conversation_id) return;
+      const input = await promptMultiline(`Reply to ${selected.remote_did || selected.conversation_id}`);
+      const message = input.trim();
+      if (!message) {
+        setStatus('Reply cancelled.', 'warn');
+        latestState = redraw();
+        return;
+      }
+      const { client, store } = await getClientWithStore(identityPath);
+      try {
+        const res = await client.sendMessage(selected.conversation_id, SCHEMA_TEXT, { text: message });
+        setStatus(res.ok
+          ? `Sent reply to ${selected.remote_did || selected.conversation_id} (${res.data?.message_id || 'queued'})`
+          : `Reply failed: ${res.error?.message || 'unknown error'}`, res.ok ? 'ok' : 'err');
+      } finally {
+        store.close();
+      }
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'o' && uiState.view === 'detail') {
+      uiState.view = 'history';
+      uiState.selectedHistoryPageIndex = 0;
+      uiState.historySearchQuery = '';
+      setStatus('Opened local history view.', 'info');
+      latestState = redraw();
+      return;
+    }
+    if ((_str === '/' || key?.name === 's') && uiState.view === 'history') {
+      const answer = await promptLine(`Search history (${latestState.selectedSession?.conversation_id || 'current conversation'}). Empty clears search: `);
+      const query = answer.trim();
+      uiState.historySearchQuery = query;
+      uiState.selectedHistoryPageIndex = 0;
+      setStatus(query ? `History search: ${query}` : 'Cleared history search.', 'info');
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'b') {
+      const selected = (latestState.sessions || []).find((session) => session.session_key === uiState.selectedSessionKey);
+      if (!selected?.conversation_id) return;
+      const current = latestState.activeChatSession || '(none)';
+      const previous = selected.binding?.session_key || '(unbound)';
+      const confirmed = await confirmAction(`Rebind conversation ${selected.conversation_id}\nRemote DID: ${selected.remote_did || '(unknown)'}\nCurrent chat: ${current}\nPrevious binding: ${previous}\nProceed?`);
+      if (confirmed) {
+        if (!latestState.activeChatSession) {
+          setStatus('Rebind failed: no active chat session.', 'err');
+          latestState = redraw();
+          return;
+        }
+        setSessionBinding(selected.conversation_id, latestState.activeChatSession);
+        setStatus(`Rebound ${selected.conversation_id} -> ${latestState.activeChatSession}`, 'ok');
+      } else {
+        setStatus('Rebind cancelled.', 'warn');
+      }
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'c') {
+      const selected = (latestState.sessions || []).find((session) => session.session_key === uiState.selectedSessionKey);
+      if (!selected?.conversation_id) return;
+      removeSessionBinding(selected.conversation_id);
+      setStatus(`Cleared binding for ${selected.conversation_id}`, 'ok');
+      latestState = redraw();
+      return;
+    }
+    if (key?.name === 'x' && (uiState.view === 'tasks' || uiState.view === 'task-detail')) {
+      const selected = latestState.selectedSession;
+      const tasks = latestState.selectedTasks || [];
+      const task = tasks[Math.max(0, Math.min(uiState.selectedTaskIndex, Math.max(0, tasks.length - 1)))] || null;
+      if (!selected?.conversation_id || !task) return;
+      const confirmed = await confirmAction(`Cancel task ${task.task_id}\nTitle: ${task.title || '(none)'}\nStatus: ${task.status}\nProceed?`);
+      if (confirmed) {
+        const { client, store } = await getClientWithStore(identityPath);
+        try {
+          const res = await client.cancelTask(selected.conversation_id, task.task_id);
+          setStatus(res.ok
+            ? `Cancel requested for task ${task.task_id}`
+            : `Cancel failed: ${res.error?.message || 'unknown error'}`, res.ok ? 'ok' : 'err');
+        } finally {
+          store.close();
+        }
+      } else {
+        setStatus('Cancel task aborted.', 'warn');
+      }
+      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;
+      if (!task) return;
+      const formatAnswer = await promptLine('Export format [j]son / [p]lain (default plain): ');
+      const format = formatAnswer.trim().toLowerCase().startsWith('j') ? 'json' : 'plain';
+      await dumpStdoutBlock(`task ${task.task_id} (${format})`, buildTaskExportBody(task, format));
+      setStatus(`Dumped task ${task.task_id} to stdout as ${format}.`, 'ok');
+      latestState = redraw();
+      return;
+    }
+  });
+}
+
 /** Format timestamp for display: human-readable by default, raw ms when --raw. */
 function formatTs(tsMs, raw) {
   if (raw) return String(tsMs);
@@ -94,6 +882,19 @@ function makeClient(id, identityPath) {
   });
 }
 
+function makeClientWithStore(id, identityPath) {
+  const p = identityPath ?? getEffectiveIdentityPath();
+  const store = openStore(p);
+  const client = new PingAgentClient({
+    serverUrl: id.serverUrl ?? DEFAULT_SERVER,
+    identity: id,
+    accessToken: id.accessToken ?? '',
+    onTokenRefreshed: (token, expiresAt) => updateStoredToken(token, expiresAt, p),
+    store,
+  });
+  return { client, store };
+}
+
 /** Load identity, proactively refresh token if near/past expiry, then return client. */
 async function getClient(identityPath) {
   const p = identityPath ?? getEffectiveIdentityPath();
@@ -105,6 +906,16 @@ async function getClient(identityPath) {
   return client;
 }
 
+async function getClientWithStore(identityPath) {
+  const p = identityPath ?? getEffectiveIdentityPath();
+  let id = loadIdentity(p);
+  await ensureTokenValid(p, id.serverUrl);
+  id = loadIdentity(p);
+  const { client, store } = makeClientWithStore(id, p);
+  await client.ensureEncryptionKeyPublished().catch(() => undefined);
+  return { client, store };
+}
+
 const program = new Command();
 program
   .name('pingagent')
@@ -1438,6 +2249,25 @@ billing
     }
   });
 
+const host = program
+  .command('host')
+  .description('Headless runtime inspection and control for PingAgent host state');
+
+host
+  .command('tui')
+  .description('Start a terminal UI for runtime, sessions, bindings, and rebind actions')
+  .option('--once', 'Print one snapshot and exit')
+  .option('--refresh-ms <ms>', 'Refresh interval in interactive mode', '2000')
+  .option('--profile <name>', 'Use profile from ~/.pingagent/<name>')
+  .action(async (opts) => {
+    const identityPath = getIdentityPathForCommand(opts);
+    if (!identityExists(identityPath)) {
+      console.error('No identity found. Run: pingagent init');
+      process.exit(1);
+    }
+    await runHostTui(identityPath, opts);
+  });
+
 program
   .command('web')
   .description('Start local web UI and host panel for debugging, runtime inspection, trust policy, and audit. By default scans ~/.pingagent for profiles; use --identity-dir to lock to one profile.')