@pingagent/sdk 0.1.11 → 0.1.13

package/bin/pingagent.js

@@ -5,6 +5,8 @@ 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 { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import {
   PingAgentClient,
   generateIdentity,
@@ -40,6 +42,8 @@ import {
 } from '../dist/index.js';
 import { ERROR_HINTS, SCHEMA_TEXT } from '@pingagent/schemas';
 
+const require = createRequire(import.meta.url);
+const THIS_FILE = fileURLToPath(import.meta.url);
 const DEFAULT_SERVER = 'https://pingagent.chat';
 const UPGRADE_URL = 'https://pingagent.chat';
 const DEFAULT_IDENTITY_PATH = path.join(os.homedir(), '.pingagent', 'identity.json');
@@ -140,29 +144,69 @@ function writeTrustPolicyDoc(identityPath, doc) {
 
 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;
+  if (explicit) return { cmd: process.execPath, args: [resolvePath(explicit)], source: 'env' };
+
+  const localCandidates = [
+    path.resolve(process.cwd(), 'packages', 'openclaw-install', 'install.mjs'),
+    path.resolve(path.dirname(THIS_FILE), '..', '..', 'openclaw-install', 'install.mjs'),
+  ];
+  for (const candidate of localCandidates) {
+    if (fs.existsSync(candidate)) return { cmd: process.execPath, args: [candidate], source: 'repo' };
+  }
+
+  try {
+    const pkgJsonPath = require.resolve('@pingagent/openclaw-install/package.json');
+    const installedScript = path.join(path.dirname(pkgJsonPath), 'install.mjs');
+    if (fs.existsSync(installedScript)) {
+      return { cmd: process.execPath, args: [installedScript], source: 'installed-package' };
+    }
+  } catch {
+    // fall through to npx fallback
+  }
+
+  return { cmd: 'npx', args: ['-y', '@pingagent/openclaw-install'], source: 'npx' };
 }
 
 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,
   });
+  const errorMessage = result.error
+    ? (result.error.code === 'ENOENT'
+      ? `Failed to launch ${resolved.cmd}. Install npx/Node tooling or set PINGAGENT_OPENCLAW_INSTALL_BIN.`
+      : String(result.error.message || result.error))
+    : '';
   return {
-    ok: result.status === 0,
+    ok: result.status === 0 && !result.error,
     stdout: String(result.stdout ?? ''),
-    stderr: String(result.stderr ?? ''),
+    stderr: errorMessage || String(result.stderr ?? ''),
     status: result.status ?? 1,
+    source: resolved.source,
   };
 }
 
+function getHostPanelSurfaceUrl() {
+  const portRaw = String(process.env.PINGAGENT_WEB_PORT || '3846').trim();
+  const port = Number.parseInt(portRaw, 10);
+  return `http://127.0.0.1:${Number.isFinite(port) ? port : 3846}/host-panel`;
+}
+
+function getSurfaceRecommendationLines(primaryCommandPrefix = 'npx @pingagent/sdk', secondaryCommandPrefix = 'pingagent') {
+  return [
+    'With GUI: Host Panel',
+    `  Start locally: ${primaryCommandPrefix} web`,
+    ...(secondaryCommandPrefix && secondaryCommandPrefix !== primaryCommandPrefix ? [`  Or via local bin: ${secondaryCommandPrefix} web`] : []),
+    `  URL when running: ${getHostPanelSurfaceUrl()}`,
+    'Headless / low-token: TUI',
+    `  ${primaryCommandPrefix} host tui`,
+    ...(secondaryCommandPrefix && secondaryCommandPrefix !== primaryCommandPrefix ? [`  ${secondaryCommandPrefix} host tui`] : []),
+    `  ${primaryCommandPrefix} host tui --once`,
+    'MCP: agent/runtime control surface, not the default human operator UI',
+  ];
+}
+
 function clearScreen() {
   process.stdout.write('\x1Bc');
 }
@@ -194,11 +238,11 @@ function truncateLine(value, max = 100) {
 
 function formatSessionRow(session, selected) {
   const marker = selected ? '>' : ' ';
-  const rebind = session.binding_alert ? ' !rebind' : '';
+  const reconnect = session.binding_alert ? ' !reconnect' : '';
   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}`;
+  return `${marker} ${who} [${trust}] unread=${unread}${reconnect}`;
 }
 
 function formatMessageRow(message) {
@@ -410,13 +454,13 @@ function renderHostTuiScreen(hostState, uiState) {
     'PingAgent Host TUI',
     `DID: ${hostState.identity.did}`,
     `status=${formatStatusLine(uiState?.statusLevel || 'info', uiState?.statusMessage || '(ready)')}${statusTs}${statusCountdown}`,
-    `runtime_mode=${hostState.runtimeMode}  receive_mode=${hostState.ingressRuntime?.receive_mode || 'webhook'}  active_chat_session=${hostState.activeChatSession || '(none)'}`,
+    `runtime_mode=${hostState.runtimeMode}  receive_mode=${hostState.ingressRuntime?.receive_mode || 'webhook'}  current_openclaw_chat=${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}`,
+    `chat_link_map=${hostState.sessionMapPath}`,
+    `chat_link_alerts=${hostState.sessionBindingAlertsPath}`,
     hostState.ingressRuntime?.hooks_last_error ? `hooks_error=${truncateLine(hostState.ingressRuntime.hooks_last_error, 120)}` : null,
     '',
   ].filter(Boolean);
@@ -443,8 +487,8 @@ function renderHostTuiScreen(hostState, uiState) {
     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('- b: attach selected session to the current OpenClaw chat');
+    lines.push('- c: detach the selected chat link');
     lines.push('- q: quit');
   } else if (view === 'history') {
     lines.push('Conversation History');
@@ -543,13 +587,13 @@ function renderHostTuiScreen(hostState, uiState) {
       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)'}`);
+      lines.push(`chat_link=${selected.binding?.session_key || '(none)'}`);
+      lines.push(`current_openclaw_chat=${hostState.activeChatSession || '(none)'}`);
       if (selected.binding_alert) {
-        lines.push(`needs_rebind=true`);
+        lines.push('needs_reconnect=true');
         lines.push(`warning=${selected.binding_alert.message}`);
       } else {
-        lines.push('needs_rebind=false');
+        lines.push('needs_reconnect=false');
       }
       if (openRecommendation) {
         lines.push(`trust_action=${getTrustRecommendationActionLabel(openRecommendation)}`);
@@ -573,8 +617,8 @@ function renderHostTuiScreen(hostState, uiState) {
         '[S] summary',
         '[o] history',
         '[t] tasks',
-        '[b] bind-current',
-        '[c] clear-binding',
+        '[b] attach-chat',
+        '[c] detach-chat',
       ].filter(Boolean).join('  ');
       lines.push(`actions=${actionBar}`);
       lines.push('');
@@ -611,7 +655,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  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');
+  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 attach-chat  c detach-chat  ? help  q quit');
   return lines.join('\n');
 }
 
@@ -1156,18 +1200,18 @@ async function runHostTui(identityPath, opts) {
       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?`);
+      const previous = selected.binding?.session_key || '(none)';
+      const confirmed = await confirmAction(`Attach chat link for conversation ${selected.conversation_id}\nRemote DID: ${selected.remote_did || '(unknown)'}\nCurrent OpenClaw chat: ${current}\nPrevious chat link: ${previous}\nProceed?`);
       if (confirmed) {
         if (!latestState.activeChatSession) {
-          setStatus('Rebind failed: no active chat session.', 'err');
+          setStatus('Attach failed: no active OpenClaw chat.', 'err');
           latestState = redraw();
           return;
         }
         setSessionBinding(selected.conversation_id, latestState.activeChatSession);
-        setStatus(`Rebound ${selected.conversation_id} -> ${latestState.activeChatSession}`, 'ok');
+        setStatus(`Attached chat link ${selected.conversation_id} -> ${latestState.activeChatSession}`, 'ok');
       } else {
-        setStatus('Rebind cancelled.', 'warn');
+        setStatus('Attach chat link cancelled.', 'warn');
       }
       latestState = redraw();
       return;
@@ -1176,7 +1220,7 @@ async function runHostTui(identityPath, opts) {
       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');
+      setStatus(`Detached chat link for ${selected.conversation_id}`, 'ok');
       latestState = redraw();
       return;
     }
@@ -3121,13 +3165,116 @@ program
     else console.log(`Connected. conversation=${convo.data.conversation_id} did=${targetDid}`);
   });
 
+async function runHostBootstrap(opts) {
+  const validTemplates = new Set(['launchd', 'systemd', 'docker', 'pm2', 'supervisord']);
+  const template = opts.template ? String(opts.template).trim() : '';
+  if (template && !validTemplates.has(template)) {
+    console.error(`Unsupported template: ${template}. Valid: ${Array.from(validTemplates).join(', ')}`);
+    process.exit(1);
+  }
+
+  const steps = [];
+  const runStep = (label, args) => {
+    const result = runOpenClawInstall(args);
+    steps.push({ label, args, result });
+    return { label, args, result };
+  };
+
+  const installStep = runStep('install', []);
+  const hooksStep = installStep.result.ok ? runStep('hooks repair', ['fix-hooks']) : null;
+  const verifyStep = installStep.result.ok && hooksStep?.result.ok
+    ? runStep('runtime verify', ['verify-runtime', '--fix-hooks'])
+    : null;
+
+  let runnerStep = null;
+  if (verifyStep?.result.ok && opts.write) {
+    const runnerArgs = ['init-runner', '--ingress', '--panel'];
+    if (template) runnerArgs.push('--template', template);
+    const supportsWrite = !template || template === 'launchd' || template === 'systemd';
+    if (supportsWrite) runnerArgs.push('--write');
+    runnerStep = runStep(supportsWrite ? 'runner setup' : 'runner template', runnerArgs);
+  }
+
+  if (runnerStep?.result.stdout && opts.write) {
+    console.log(runnerStep.result.stdout.trim());
+    if (runnerStep.result.stderr.trim()) console.error(runnerStep.result.stderr.trim());
+    console.log('');
+  }
+
+  const failed = steps.find((step) => !step.result.ok) ?? null;
+  const formatStepStatus = (step, fallback = 'skipped') => (step ? (step.result.ok ? 'ok' : 'failed') : fallback);
+  const runnerStatus = !opts.write
+    ? 'not_written'
+    : !runnerStep
+      ? 'skipped'
+      : !runnerStep.result.ok
+        ? 'failed'
+        : (template && template !== 'launchd' && template !== 'systemd')
+          ? 'template_printed_not_started'
+          : 'written_not_started';
+  const installerSource = installStep.result.source || 'unknown';
+
+  console.log('PingAgent Host Bootstrap');
+  console.log('========================');
+  console.log(`install=${formatStepStatus(installStep)}`);
+  console.log(`hooks_repair=${formatStepStatus(hooksStep)}`);
+  console.log(`runtime_verify=${formatStepStatus(verifyStep)}`);
+  console.log(`installer_source=${installerSource}`);
+  console.log(`runner=${runnerStatus}`);
+  console.log(`host_panel_url=${getHostPanelSurfaceUrl()}`);
+  console.log('host_panel_started_by_bootstrap=false');
+  console.log('host_panel_start=npx @pingagent/sdk web');
+  console.log('host_panel_start_local=pingagent web');
+  console.log('tui=npx @pingagent/sdk host tui');
+  console.log('tui_local=pingagent host tui');
+  console.log('');
+  console.log('Control surfaces:');
+  for (const line of getSurfaceRecommendationLines('npx @pingagent/sdk', 'pingagent')) console.log(line);
+  console.log('');
+  if (!opts.write) {
+    console.log('Next steps:');
+    console.log('  Bootstrap validates and repairs config, but it does not start long-lived daemons.');
+    console.log('  Start the Host Panel now with: npx @pingagent/sdk web (or pingagent web)');
+    console.log('  Use the headless surface now with: npx @pingagent/sdk host tui (or pingagent host tui)');
+    console.log(`  Re-run with: npx @pingagent/sdk host bootstrap --write${template ? ` --template ${template}` : ''}`);
+    console.log('  Manual path: npx @pingagent/openclaw-install init-runner --ingress --panel');
+  } else if (runnerStep?.result.ok) {
+    console.log('Next steps:');
+    console.log('  Runner files/templates were generated, but bootstrap did not start those services.');
+    if (!template || template === 'launchd' || template === 'systemd') {
+      console.log('  Follow the printed launchctl/systemctl instructions to start them.');
+    } else {
+      console.log('  Start the generated runner with your chosen process manager.');
+    }
+  }
+
+  if (failed) {
+    const stdout = failed.result.stdout.trim();
+    const stderr = failed.result.stderr.trim();
+    console.error('');
+    console.error(`Bootstrap failed during ${failed.label}.`);
+    if (stdout) console.error(stdout);
+    if (stderr) console.error(stderr);
+    process.exit(1);
+  }
+}
+
 const host = program
   .command('host')
-  .description('Headless runtime inspection and control for PingAgent host state');
+  .description('OpenClaw host activation and operator control surfaces for GUI, headless, and low-token workflows');
+
+host
+  .command('bootstrap')
+  .description('Run the idempotent OpenClaw activation flow and print the recommended Host Panel / TUI surfaces')
+  .option('--write', 'Write launchd/systemd runner files when supported')
+  .option('--template <name>', 'Runner template: launchd, systemd, docker, pm2, or supervisord')
+  .action(async (opts) => {
+    await runHostBootstrap(opts);
+  });
 
 host
   .command('tui')
-  .description('Start a terminal UI for runtime, sessions, bindings, and rebind actions')
+  .description('Start the headless / low-token terminal UI for runtime, sessions, chat links, and repair 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>')
@@ -3142,7 +3289,7 @@ host
 
 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.')
+  .description('Start the Host Panel, the primary GUI surface for runtime inspection, trust policy, and repair. Use pingagent host tui for headless or low-token operation.')
   .option('--port <port>', 'Port for the web server', '3846')
   .action(async (opts) => {
     const serverUrl = process.env.PINGAGENT_SERVER_URL || DEFAULT_SERVER;