@pingagent/sdk 0.1.11 → 0.1.12

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;

package/dist/web-server.js

@@ -153,6 +153,20 @@ function getHostPanelHtml() {
     }
     .empty { color: #94a3b8; font-size: 13px; }
     .link-row { display: flex; gap: 10px; margin-top: 20px; }
+    .toolbar-row { display: flex; justify-content: space-between; gap: 10px; align-items: center; flex-wrap: wrap; margin-bottom: 12px; }
+    .toolbar-actions { display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }
+    .mode-toggle { display: inline-flex; gap: 6px; padding: 4px; border-radius: 999px; border: 1px solid #334155; background: #020617; }
+    .mode-toggle button {
+      border: 0;
+      background: transparent;
+      color: #94a3b8;
+      border-radius: 999px;
+      padding: 6px 10px;
+      cursor: pointer;
+    }
+    .mode-toggle button.active { background: #0f766e; color: #ecfeff; }
+    .summary-pills { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 8px; }
+    .summary-pills .pill { font-size: 11px; }
     @media (max-width: 1000px) {
       .layout { grid-template-columns: 1fr; }
       .sidebar { border-right: none; border-bottom: 1px solid #1e293b; }
@@ -196,7 +210,17 @@ function getHostPanelHtml() {
         <div class="grid stats" id="statsGrid"></div>
         <div class="grid runtime-layout" style="margin-top:16px">
           <div class="card">
-            <h2>Recent Sessions</h2>
+            <div class="toolbar-row">
+              <h2 style="margin:0">Recent Sessions</h2>
+              <div class="toolbar-actions">
+                <button class="secondary-btn" id="toggleUnreadBtn" style="width:auto">Unread only: off</button>
+                <button class="secondary-btn" id="nextUnreadBtn" style="width:auto">Next unread</button>
+                <div class="mode-toggle" aria-label="Runtime detail mode">
+                  <button id="detailModeBasicBtn" class="active" type="button">Basic</button>
+                  <button id="detailModeAdvancedBtn" type="button">Advanced</button>
+                </div>
+              </div>
+            </div>
             <div class="sessions" id="sessionList"></div>
           </div>
           <div class="grid">
@@ -325,14 +349,28 @@ function getHostPanelHtml() {
   </div>
 
   <script>
+    const initialQuery = (function () {
+      const params = new URLSearchParams(window.location.search);
+      const profile = params.get('profile');
+      const sessionKey = params.get('session_key');
+      const view = params.get('view');
+      return {
+        profile: profile && profile.trim() ? profile.trim() : null,
+        sessionKey: sessionKey && sessionKey.trim() ? sessionKey.trim() : null,
+        view: view === 'policy' ? 'policy' : 'runtime',
+      };
+    })();
+
     const state = {
-      selectedProfile: sessionStorage.getItem('pingagent_host_panel_profile') || null,
-      currentTab: 'runtime',
+      selectedProfile: initialQuery.profile || sessionStorage.getItem('pingagent_host_panel_profile') || null,
+      currentTab: initialQuery.view,
       profiles: [],
       overview: null,
       session: null,
       policy: null,
-      selectedSessionKey: null,
+      selectedSessionKey: initialQuery.sessionKey || null,
+      detailMode: sessionStorage.getItem('pingagent_host_panel_detail_mode') || 'basic',
+      showUnreadOnly: false,
     };
 
     function esc(value) {
@@ -356,6 +394,45 @@ function getHostPanelHtml() {
       try { return new Date(value).toLocaleString(); } catch { return String(value); }
     }
 
+    function syncUrlState() {
+      const url = new URL(window.location.href);
+      if (state.selectedProfile) url.searchParams.set('profile', state.selectedProfile);
+      else url.searchParams.delete('profile');
+      if (state.selectedSessionKey) url.searchParams.set('session_key', state.selectedSessionKey);
+      else url.searchParams.delete('session_key');
+      url.searchParams.set('view', state.currentTab === 'policy' ? 'policy' : 'runtime');
+      history.replaceState(null, '', url.pathname + (url.search ? url.search : ''));
+    }
+
+    function setDetailMode(mode) {
+      state.detailMode = mode === 'advanced' ? 'advanced' : 'basic';
+      sessionStorage.setItem('pingagent_host_panel_detail_mode', state.detailMode);
+      document.getElementById('detailModeBasicBtn').classList.toggle('active', state.detailMode === 'basic');
+      document.getElementById('detailModeAdvancedBtn').classList.toggle('active', state.detailMode === 'advanced');
+      if (state.overview) renderOverview();
+      if (state.session) renderSession();
+    }
+
+    function buildSessionLink(sessionKey) {
+      const url = new URL(window.location.href);
+      if (state.selectedProfile) url.searchParams.set('profile', state.selectedProfile);
+      else url.searchParams.delete('profile');
+      if (sessionKey) url.searchParams.set('session_key', sessionKey);
+      else url.searchParams.delete('session_key');
+      url.searchParams.set('view', 'runtime');
+      return url.toString();
+    }
+
+    async function copyText(text, fallbackLabel) {
+      try {
+        await navigator.clipboard.writeText(text);
+        window.alert((fallbackLabel || 'Copied') + ':
+' + text);
+      } catch {
+        window.prompt(fallbackLabel || 'Copy', text);
+      }
+    }
+
     async function api(path, opts) {
       let url = path;
       if (state.selectedProfile) {
@@ -405,6 +482,7 @@ function getHostPanelHtml() {
       document.getElementById('navPolicy').classList.toggle('active', tab === 'policy');
       document.getElementById('runtimePanel').classList.toggle('active', tab === 'runtime');
       document.getElementById('policyPanel').classList.toggle('active', tab === 'policy');
+      syncUrlState();
     }
 
     function renderHeader() {
@@ -494,9 +572,40 @@ function getHostPanelHtml() {
         '</div>';
     }
 
+    function getOverviewSessions() {
+      return state.overview && Array.isArray(state.overview.sessions) ? state.overview.sessions : [];
+    }
+
+    function getVisibleSessions() {
+      const sessions = getOverviewSessions();
+      return state.showUnreadOnly
+        ? sessions.filter(function (session) { return Number(session.unread_count || 0) > 0; })
+        : sessions;
+    }
+
+    function syncSelectedSessionFromOverview() {
+      const allSessions = getOverviewSessions();
+      const visibleSessions = getVisibleSessions();
+      if (!allSessions.length) {
+        state.selectedSessionKey = null;
+        state.session = null;
+        return;
+      }
+      const hasSelected = allSessions.some(function (session) { return session.session_key === state.selectedSessionKey; });
+      if (!hasSelected) {
+        state.selectedSessionKey = visibleSessions.length ? visibleSessions[0].session_key : allSessions[0].session_key;
+        return;
+      }
+      if (state.showUnreadOnly) {
+        const stillVisible = visibleSessions.some(function (session) { return session.session_key === state.selectedSessionKey; });
+        if (!stillVisible) state.selectedSessionKey = visibleSessions.length ? visibleSessions[0].session_key : null;
+      }
+    }
+
     function renderOverview() {
       const overview = state.overview;
       if (!overview) return;
+      syncSelectedSessionFromOverview();
       const ingressState = ingressStatusModel(overview);
       document.getElementById('activationCard').innerHTML =
         '<div class="status-strip">' +
@@ -536,24 +645,27 @@ function getHostPanelHtml() {
         return '<div class="card"><div class="label">' + esc(item.label) + '</div><div class="value">' + esc(item.value) + '</div><div class="muted small">' + esc(item.sub) + '</div></div>';
       }).join('');
 
-      const sessions = Array.isArray(overview.sessions) ? overview.sessions : [];
+      const toggleUnreadBtn = document.getElementById('toggleUnreadBtn');
+      if (toggleUnreadBtn) toggleUnreadBtn.textContent = 'Unread only: ' + (state.showUnreadOnly ? 'on' : 'off');
+      const sessions = getVisibleSessions();
       if (!sessions.length) {
-        document.getElementById('sessionList').innerHTML = '<div class="empty">No sessions yet.</div>';
+        document.getElementById('sessionList').innerHTML = '<div class="empty">' + (state.showUnreadOnly ? 'No unread sessions.' : 'No sessions yet.') + '</div>';
       } else {
-        if (!state.selectedSessionKey) state.selectedSessionKey = sessions[0].session_key;
         document.getElementById('sessionList').innerHTML = sessions.map(function (session) {
           const active = session.session_key === state.selectedSessionKey ? ' active' : '';
           const badges = [
             '<span class="badge ' + esc(session.trust_state) + '">' + esc(session.trust_state) + '</span>',
             session.binding_alert
-              ? '<button type="button" class="badge alert rebind-badge-btn" data-session="' + esc(session.session_key) + '" data-conversation="' + esc(session.conversation_id || '') + '" data-bound-session="' + esc(session.mapped_work_session || '') + '" data-remote-did="' + esc(session.remote_did || '') + '" title="' + esc(session.binding_alert.message || 'Rebind this conversation to the current chat session') + '">Needs rebind</button>'
+              ? '<button type="button" class="badge alert rebind-badge-btn" data-session="' + esc(session.session_key) + '" data-conversation="' + esc(session.conversation_id || '') + '" data-bound-session="' + esc(session.mapped_work_session || '') + '" data-remote-did="' + esc(session.remote_did || '') + '" title="OpenClaw chat link needs attention">Needs reconnect</button>'
               : '',
           ].filter(Boolean).join('');
           return '<div class="session-row' + active + '" data-session="' + esc(session.session_key) + '">' +
-            '<div class="top"><strong>' + esc(session.remote_did || session.conversation_id || 'unknown') + '</strong><div style="display:flex;gap:6px;flex-wrap:wrap;justify-content:flex-end">' + badges + '</div></div>' +
-            '<div class="muted small" style="margin-top:6px">conversation=' + esc(session.conversation_id || '(none)') + '</div>' +
+            '<div class="top"><strong>' + esc(session.remote_did || session.session_key || 'unknown') + '</strong><div style="display:flex;gap:6px;flex-wrap:wrap;justify-content:flex-end">' + badges + '</div></div>' +
             '<div class="muted small">unread=' + esc(session.unread_count) + ' \xB7 last=' + esc(fmtTs(session.last_remote_activity_at || session.updated_at)) + '</div>' +
-            '<div class="muted small">work_session=' + esc(session.mapped_work_session || '(unbound)') + (session.is_active_work_session ? ' \xB7 active_chat=true' : '') + '</div>' +
+            (state.detailMode === 'advanced'
+              ? '<div class="muted small" style="margin-top:6px">conversation=' + esc(session.conversation_id || '(none)') + '</div>' +
+                '<div class="muted small">work_session=' + esc(session.mapped_work_session || '(unbound)') + (session.is_active_work_session ? ' \xB7 active_chat=true' : '') + '</div>'
+              : '') +
             '<div class="muted small" style="margin-top:6px">' + esc(session.last_message_preview || '(no preview)') + '</div>' +
           '</div>';
         }).join('');
@@ -678,25 +790,47 @@ conversation=' + result.conversation_id));
       const bindingAlert = detail.bindingAlert || null;
       const activeWorkSession = detail.activeWorkSession || null;
       const summary = detail.sessionSummary || null;
+      const isAdvanced = state.detailMode === 'advanced';
+      const sessionLink = buildSessionLink(session.session_key);
+      const summaryPills = [];
+      if (contact && contact.action) summaryPills.push('<span class="pill">contact=' + esc(contact.action) + '</span>');
+      if (task && task.action) summaryPills.push('<span class="pill">task=' + esc(task.action) + '</span>');
+      if (session.trust_state) summaryPills.push('<span class="pill">trust=' + esc(session.trust_state) + '</span>');
+      if (Number(session.unread_count || 0) > 0) summaryPills.push('<span class="pill">unread=' + esc(session.unread_count) + '</span>');
+      if (binding && binding.session_key) summaryPills.push('<span class="pill">chat link attached</span>');
+      else if (activeWorkSession) summaryPills.push('<span class="pill">current OpenClaw chat available</span>');
+      const policyBlock = isAdvanced
+        ? '<pre style="margin-top:8px">[Contact]\\naction=' + esc(contact.action) + '\\nsource=' + esc(contact.source) + (contact.matched_rule ? '\\nmatched_rule=' + esc(contact.matched_rule) : '') + '\\n' + esc(contact.explanation) + '\\n\\n[Task]\\naction=' + esc(task.action) + '\\nsource=' + esc(task.source) + (task.matched_rule ? '\\nmatched_rule=' + esc(task.matched_rule) : '') + '\\n' + esc(task.explanation) + '</pre>'
+        : '<div class="summary-pills" style="margin-top:8px">' + summaryPills.join('') + '</div>' +
+          '<div class="muted small" style="margin-top:10px">' + esc(contact.explanation || '(no contact explanation)') + '</div>' +
+          '<div class="muted small" style="margin-top:6px">' + esc(task.explanation || '(no task explanation)') + '</div>';
 
       el.innerHTML = '' +
         '<div class="two-col">' +
           '<div>' +
             '<div class="label">Session</div>' +
             '<div style="margin-top:8px"><strong>' + esc(session.remote_did || '(unknown)') + '</strong></div>' +
-            '<div class="muted small">session=' + esc(session.session_key) + '</div>' +
-            '<div class="muted small">conversation=' + esc(session.conversation_id || '(none)') + '</div>' +
             '<div class="muted small">trust=' + esc(session.trust_state) + ' \xB7 unread=' + esc(session.unread_count) + '</div>' +
             '<div class="muted small">last activity=' + esc(fmtTs(session.last_remote_activity_at || session.updated_at)) + '</div>' +
-            '<div class="muted small" style="margin-top:8px">active_chat_session=' + esc(activeWorkSession || '(none)') + '</div>' +
-            '<div class="muted small">binding=' + esc(binding ? binding.session_key : '(unbound)') + '</div>' +
+            (isAdvanced
+              ? '<div style="margin-top:8px">' +
+                  '<div class="muted small">session=' + esc(session.session_key) + '</div>' +
+                  '<div class="muted small">conversation=' + esc(session.conversation_id || '(none)') + '</div>' +
+                  '<div class="muted small">active_chat_session=' + esc(activeWorkSession || '(none)') + '</div>' +
+                  '<div class="muted small">binding=' + esc(binding ? binding.session_key : '(unbound)') + '</div>' +
+                '</div>'
+              : '') +
             (openRecommendation
               ? '<div class="muted small" style="margin-top:8px">trust_action=' + esc(recommendationActionLabel(openRecommendation)) + '</div>'
               : (reopenRecommendation ? '<div class="muted small" style="margin-top:8px">trust_action=' + esc(recommendationActionLabel(reopenRecommendation)) + '</div>' : '')) +
+            (summaryPills.length ? '<div class="summary-pills">' + summaryPills.join('') + '</div>' : '') +
             (bindingAlert
-              ? '<div style="margin-top:10px;padding:10px 12px;border:1px solid #ef4444;border-radius:10px;background:rgba(127,29,29,0.25);color:#fecaca"><strong>Needs rebind</strong><div class="small" style="margin-top:6px">' + esc(bindingAlert.message || 'Bound work session is missing. Rebind this PingAgent conversation to the current chat session.') + '</div></div>'
+              ? '<div style="margin-top:10px;padding:10px 12px;border:1px solid #ef4444;border-radius:10px;background:rgba(127,29,29,0.25);color:#fecaca"><strong>Needs reconnect</strong><div class="small" style="margin-top:6px">' + esc(isAdvanced ? (bindingAlert.message || 'Bound work session is missing. Rebind this PingAgent conversation to the current chat session.') : 'OpenClaw chat link is stale. Attach this PingAgent session to the current OpenClaw chat.') + '</div></div>'
               : '') +
             '<div class="row-actions">' +
+              (session.trust_state === 'pending'
+                ? '<button class="action-btn approve-session-btn" data-session="' + esc(session.session_key) + '">Approve Contact</button>'
+                : '') +
               (openRecommendation
                 ? '<button class="action-btn apply-session-recommendation-btn" data-session="' + esc(session.session_key) + '">' + esc(recommendationActionLabel(openRecommendation)) + '</button>'
                 : '') +
@@ -706,13 +840,24 @@ conversation=' + result.conversation_id));
               (!openRecommendation && reopenRecommendation
                 ? '<button class="secondary-btn reopen-session-recommendation-btn" data-session="' + esc(session.session_key) + '">Reopen</button>'
                 : '') +
-              '<button class="action-btn bind-current-btn" data-conversation="' + esc(session.conversation_id || '') + '">Bind Current Chat</button>' +
-              '<button class="danger-btn clear-binding-btn" data-conversation="' + esc(session.conversation_id || '') + '">Clear Binding</button>' +
+              '<button class="action-btn bind-current-btn" data-conversation="' + esc(session.conversation_id || '') + '">Attach to Current Chat</button>' +
+              '<button class="secondary-btn mark-read-btn" data-session="' + esc(session.session_key) + '">Mark read</button>' +
+              '<button class="secondary-btn copy-session-link-btn" data-session="' + esc(session.session_key) + '">Copy Session Link</button>' +
+              '<button class="danger-btn clear-binding-btn" data-conversation="' + esc(session.conversation_id || '') + '">Detach Chat Link</button>' +
+            '</div>' +
+            '<div class="form-grid" style="margin-top:16px">' +
+              '<label class="label">Reply in this session</label>' +
+              '<textarea id="sessionReplyInput" placeholder="Send a text reply in this session"></textarea>' +
+              '<div class="row-actions"><button class="action-btn" id="sendSessionReplyBtn">Send Reply</button></div>' +
             '</div>' +
           '</div>' +
           '<div>' +
             '<div class="label">Policy Decisions</div>' +
-            '<pre style="margin-top:8px">[Contact]\\naction=' + esc(contact.action) + '\\nsource=' + esc(contact.source) + (contact.matched_rule ? '\\nmatched_rule=' + esc(contact.matched_rule) : '') + '\\n' + esc(contact.explanation) + '\\n\\n[Task]\\naction=' + esc(task.action) + '\\nsource=' + esc(task.source) + (task.matched_rule ? '\\nmatched_rule=' + esc(task.matched_rule) : '') + '\\n' + esc(task.explanation) + '</pre>' +
+            policyBlock +
+            (isAdvanced && recommendations.length
+              ? '<pre style="margin-top:12px">recommendations_debug=' + esc(JSON.stringify(recommendations.map(function (item) { return { id: item.id, status: item.status, policy: item.policy, action: item.action, current_action: item.current_action, match: item.match, confidence: item.confidence }; }), null, 2)) + '</pre>'
+              : '') +
+            (isAdvanced ? '<div class="muted small" style="margin-top:10px">permalink=' + esc(sessionLink) + '</div>' : '') +
           '</div>' +
         '</div>' +
         '<div class="grid two-col" style="margin-top:16px">' +
@@ -730,9 +875,7 @@ conversation=' + result.conversation_id));
               '<textarea id="sessionSummaryOpenQuestions" placeholder="Open questions">' + esc(summary && summary.open_questions ? summary.open_questions : '') + '</textarea>' +
               '<textarea id="sessionSummaryNextAction" placeholder="Next action">' + esc(summary && summary.next_action ? summary.next_action : '') + '</textarea>' +
               '<textarea id="sessionSummaryHandoff" placeholder="Handoff-ready summary">' + esc(summary && summary.handoff_ready_text ? summary.handoff_ready_text : '') + '</textarea>' +
-              '<div class="row-actions">' +
-                '<button class="action-btn" id="saveSessionSummaryBtn">Save Summary</button>' +
-              '</div>' +
+              '<div class="row-actions"><button class="action-btn" id="saveSessionSummaryBtn">Save Summary</button></div>' +
             '</div>' +
           '</div>' +
         '</div>' +
@@ -759,8 +902,8 @@ conversation=' + result.conversation_id));
                 ? '<button class="secondary-btn reopen-session-recommendation-btn" data-session="' + esc(session.session_key) + '">Reopen</button>'
                 : '';
               return '<div class="recommendation-row"><div class="top"><strong>' + esc(item.policy) + '</strong><span class="badge">' + esc(item.status + ' \xB7 ' + item.action) + '</span></div>' +
-                '<div class="muted small">current=' + esc(item.current_action) + ' \xB7 confidence=' + esc(item.confidence) + '</div>' +
-                '<div class="muted small">match=' + esc(item.match) + '</div>' +
+                (isAdvanced ? '<div class="muted small">current=' + esc(item.current_action) + ' \xB7 confidence=' + esc(item.confidence) + '</div>' : '') +
+                (isAdvanced ? '<div class="muted small">match=' + esc(item.match) + '</div>' : '') +
                 '<div style="margin-top:8px">' + esc(item.reason) + '</div>' +
                 '<div class="row-actions">' + actionButton + dismissButton + reopenButton + '</div>' +
               '</div>';
@@ -770,10 +913,10 @@ conversation=' + result.conversation_id));
         '<div class="grid two-col" style="margin-top:16px">' +
           '<div><div class="label">Recent Messages</div><div class="message-list" style="margin-top:8px">' +
             (messages.length ? messages.map(function (msg) {
-              const summary = msg.schema === 'pingagent.text@1' && msg.payload && msg.payload.text
+              const messageSummary = msg.schema === 'pingagent.text@1' && msg.payload && msg.payload.text
                 ? msg.payload.text
                 : JSON.stringify(msg.payload || {});
-              return '<div class="message-row"><div class="muted small">' + esc(fmtTs(msg.ts_ms)) + ' \xB7 ' + esc(msg.direction) + ' \xB7 ' + esc(msg.schema) + '</div><div style="margin-top:8px">' + esc(summary) + '</div></div>';
+              return '<div class="message-row"><div class="muted small">' + esc(fmtTs(msg.ts_ms)) + ' \xB7 ' + esc(msg.direction) + ' \xB7 ' + esc(msg.schema) + '</div><div style="margin-top:8px">' + esc(messageSummary) + '</div></div>';
             }).join('') : '<div class="empty">No local message history yet.</div>') +
           '</div></div>' +
           '<div><div class="label">Policy Audit</div><div class="audit-list" style="margin-top:8px">' +
@@ -786,6 +929,24 @@ conversation=' + result.conversation_id));
           '</div></div>' +
         '</div>';
 
+      el.querySelectorAll('.approve-session-btn').forEach(function (btn) {
+        btn.addEventListener('click', async function () {
+          const sessionKey = btn.getAttribute('data-session');
+          const result = await api('/api/runtime/session/approve', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ session_key: sessionKey }),
+          });
+          await refreshAll();
+          const promoted = result && result.dm_conversation_id
+            ? getOverviewSessions().find(function (item) { return item.conversation_id === result.dm_conversation_id; })
+            : null;
+          state.selectedSessionKey = promoted ? promoted.session_key : sessionKey;
+          renderOverview();
+          if (state.selectedSessionKey) await loadSession(state.selectedSessionKey);
+          setTab('runtime');
+        });
+      });
       el.querySelectorAll('.bind-current-btn').forEach(function (btn) {
         btn.addEventListener('click', async function () {
           const conversationId = btn.getAttribute('data-conversation');
@@ -793,6 +954,22 @@ conversation=' + result.conversation_id));
           await promptBindCurrentChat(conversationId);
         });
       });
+      el.querySelectorAll('.mark-read-btn').forEach(function (btn) {
+        btn.addEventListener('click', async function () {
+          await api('/api/runtime/session/mark-read', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ session_key: btn.getAttribute('data-session') }),
+          });
+          await refreshAll();
+          setTab('runtime');
+        });
+      });
+      el.querySelectorAll('.copy-session-link-btn').forEach(function (btn) {
+        btn.addEventListener('click', async function () {
+          await copyText(buildSessionLink(btn.getAttribute('data-session')), 'Session link');
+        });
+      });
       el.querySelectorAll('.clear-binding-btn').forEach(function (btn) {
         btn.addEventListener('click', async function () {
           await api('/api/runtime/session-bindings/clear', {
@@ -837,23 +1014,42 @@ conversation=' + result.conversation_id));
           setTab('runtime');
         });
       });
+      const sendSessionReplyBtn = document.getElementById('sendSessionReplyBtn');
+      if (sendSessionReplyBtn) {
+        sendSessionReplyBtn.addEventListener('click', async function () {
+          const input = document.getElementById('sessionReplyInput');
+          const message = input.value.trim();
+          if (!message) {
+            window.alert('Reply text is required.');
+            return;
+          }
+          await api('/api/runtime/session/reply', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ session_key: session.session_key, message: message }),
+          });
+          input.value = '';
+          await refreshAll();
+          setTab('runtime');
+        });
+      }
       const saveSessionSummaryBtn = document.getElementById('saveSessionSummaryBtn');
       if (saveSessionSummaryBtn) {
         saveSessionSummaryBtn.addEventListener('click', async function () {
           await api('/api/runtime/session-summary', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({
-                session_key: session.session_key,
-                objective: document.getElementById('sessionSummaryObjective').value.trim(),
-                context: document.getElementById('sessionSummaryContext').value.trim(),
-                constraints: document.getElementById('sessionSummaryConstraints').value.trim(),
-                decisions: document.getElementById('sessionSummaryDecisions').value.trim(),
-                open_questions: document.getElementById('sessionSummaryOpenQuestions').value.trim(),
-                next_action: document.getElementById('sessionSummaryNextAction').value.trim(),
-                handoff_ready_text: document.getElementById('sessionSummaryHandoff').value.trim(),
-              }),
-            });
+            body: JSON.stringify({
+              session_key: session.session_key,
+              objective: document.getElementById('sessionSummaryObjective').value.trim(),
+              context: document.getElementById('sessionSummaryContext').value.trim(),
+              constraints: document.getElementById('sessionSummaryConstraints').value.trim(),
+              decisions: document.getElementById('sessionSummaryDecisions').value.trim(),
+              open_questions: document.getElementById('sessionSummaryOpenQuestions').value.trim(),
+              next_action: document.getElementById('sessionSummaryNextAction').value.trim(),
+              handoff_ready_text: document.getElementById('sessionSummaryHandoff').value.trim(),
+            }),
+          });
           await refreshAll();
           setTab('runtime');
         });
@@ -867,7 +1063,7 @@ conversation=' + result.conversation_id));
       const previous = previousBinding || (state.session && state.session.binding ? state.session.binding.session_key : null) || '(unbound)';
       const targetRemoteDid = remoteDid || (state.session && state.session.session ? state.session.session.remote_did : null) || '(unknown)';
       const confirmed = window.confirm(
-        'Rebind this PingAgent conversation to the current chat session?' +
+        'Attach this PingAgent session to the current OpenClaw chat?' +
         '
 
 Conversation: ' + conversationId +
@@ -875,9 +1071,9 @@ Conversation: ' + conversationId +
 Remote DID: ' + targetRemoteDid +
         '
 
-Current chat: ' + (current || '(none)') +
+Current OpenClaw chat: ' + (current || '(none)') +
         '
-Previous binding: ' + previous
+Previous chat link: ' + previous
       );
       if (!confirmed) return;
       await api('/api/runtime/session-bindings/bind-current', {
@@ -1061,14 +1257,15 @@ Previous binding: ' + previous
 
     async function loadOverview() {
       state.overview = await api('/api/runtime/overview');
+      syncSelectedSessionFromOverview();
       renderHeader();
       renderOverview();
-      const sessions = state.overview && Array.isArray(state.overview.sessions) ? state.overview.sessions : [];
-      if (!state.selectedSessionKey && sessions.length) {
-        state.selectedSessionKey = sessions[0].session_key;
-      }
       if (state.selectedSessionKey) {
         await loadSession(state.selectedSessionKey);
+      } else {
+        state.session = null;
+        renderSession();
+        syncUrlState();
       }
     }
 
@@ -1076,6 +1273,7 @@ Previous binding: ' + previous
       if (!sessionKey) return;
       state.selectedSessionKey = sessionKey;
       state.session = await api('/api/runtime/session?session_key=' + encodeURIComponent(sessionKey));
+      syncUrlState();
       renderSession();
     }
 
@@ -1096,6 +1294,30 @@ Previous binding: ' + previous
 
     document.getElementById('navRuntime').addEventListener('click', function () { setTab('runtime'); });
     document.getElementById('navPolicy').addEventListener('click', function () { setTab('policy'); });
+    document.getElementById('toggleUnreadBtn').addEventListener('click', async function () {
+      state.showUnreadOnly = !state.showUnreadOnly;
+      syncSelectedSessionFromOverview();
+      renderOverview();
+      if (state.selectedSessionKey) await loadSession(state.selectedSessionKey);
+      else {
+        syncUrlState();
+        renderSession();
+      }
+    });
+    document.getElementById('nextUnreadBtn').addEventListener('click', async function () {
+      const unreadSessions = getOverviewSessions().filter(function (session) { return Number(session.unread_count || 0) > 0; });
+      if (!unreadSessions.length) {
+        window.alert('No unread sessions.');
+        return;
+      }
+      const currentIndex = unreadSessions.findIndex(function (session) { return session.session_key === state.selectedSessionKey; });
+      const next = unreadSessions[(currentIndex + 1 + unreadSessions.length) % unreadSessions.length];
+      state.selectedSessionKey = next.session_key;
+      renderOverview();
+      await loadSession(state.selectedSessionKey);
+    });
+    document.getElementById('detailModeBasicBtn').addEventListener('click', function () { setDetailMode('basic'); });
+    document.getElementById('detailModeAdvancedBtn').addEventListener('click', function () { setDetailMode('advanced'); });
     document.getElementById('rulePolicy').addEventListener('change', updateRuleActionOptions);
     document.getElementById('saveDefaultsBtn').addEventListener('click', async function () {
       await api('/api/runtime/policy/defaults', {
@@ -1178,9 +1400,12 @@ Previous binding: ' + previous
     });
 
     async function init() {
+      setTab(state.currentTab);
+      setDetailMode(state.detailMode);
       await loadProfiles();
       updateRuleActionOptions();
       await refreshAll();
+      syncUrlState();
     }
 
     init().catch(function (error) {
@@ -1679,6 +1904,18 @@ async function buildSessionOverviewPayload(ctx, sessionKey) {
     }))
   };
 }
+function resolveSessionForInput(sessionManager, input) {
+  if (!sessionManager) return null;
+  const sessionKey = String(input.session_key ?? "").trim();
+  const conversationId = String(input.conversation_id ?? "").trim();
+  const remoteDid = String(input.remote_did ?? "").trim();
+  let session = sessionKey ? sessionManager.get(sessionKey) : null;
+  if (!session && conversationId) session = sessionManager.getByConversationId(conversationId);
+  if (!session && remoteDid) {
+    session = sessionManager.listRecentSessions(100).find((item) => item.remote_did === remoteDid) ?? null;
+  }
+  return session ?? sessionManager.getActiveSession() ?? sessionManager.listRecentSessions(1)[0] ?? null;
+}
 async function handleApi(pathname, req, ctx) {
   const client = ctx.client;
   const contactManager = ctx.contactManager;
@@ -1780,6 +2017,48 @@ async function handleApi(pathname, req, ctx) {
       };
     }
     if (parts[1] === "session") {
+      const sessionManager = ctx.client.getSessionManager();
+      if (!sessionManager) throw new Error("Session actions require a writable local store");
+      if (parts[2] === "reply" && req.method === "POST") {
+        const body = await readBody(req);
+        const session = resolveSessionForInput(sessionManager, body);
+        if (!session?.conversation_id) throw new Error("No session selected");
+        const text = String(body?.message ?? "").trim();
+        if (!text) throw new Error("Missing message");
+        const sendRes = await client.sendMessage(session.conversation_id, SCHEMA_TEXT, { text });
+        if (!sendRes.ok) throw new Error(sendRes.error?.message ?? "Failed to send");
+        sessionManager.focusSession(session.session_key);
+        return {
+          ok: true,
+          session: sessionManager.get(session.session_key),
+          message_id: sendRes.data?.message_id ?? null
+        };
+      }
+      if (parts[2] === "approve" && req.method === "POST") {
+        const body = await readBody(req);
+        const session = resolveSessionForInput(sessionManager, body);
+        if (!session?.conversation_id) throw new Error("No session selected");
+        const approveRes = await client.approveContact(session.conversation_id);
+        if (!approveRes.ok) throw new Error(approveRes.error?.message ?? "Failed to approve contact");
+        sessionManager.focusSession(session.session_key);
+        return {
+          ok: true,
+          session: sessionManager.get(session.session_key),
+          trusted: approveRes.data?.trusted ?? true,
+          dm_conversation_id: approveRes.data?.dm_conversation_id ?? session.conversation_id
+        };
+      }
+      if (parts[2] === "mark-read" && req.method === "POST") {
+        const body = await readBody(req);
+        const session = resolveSessionForInput(sessionManager, body);
+        if (!session?.session_key) throw new Error("No session selected");
+        const updated = sessionManager.markRead(session.session_key);
+        if (!updated) throw new Error("Failed to mark session as read");
+        return {
+          ok: true,
+          session: updated
+        };
+      }
       const url = new URL(req.url || "", "http://x");
       const sessionKey = url.searchParams.get("session_key");
       return buildSessionOverviewPayload(ctx, sessionKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingagent/sdk",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -35,8 +35,8 @@
     "uuid": "^11.0.0",
     "ws": "^8.0.0",
     "@pingagent/protocol": "0.1.1",
-    "@pingagent/schemas": "0.1.2",
-    "@pingagent/a2a": "0.1.1"
+    "@pingagent/a2a": "0.1.1",
+    "@pingagent/schemas": "0.1.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",