@animalabs/connectome-host 0.3.1 → 0.3.5

package/web/src/App.tsx

@@ -12,6 +12,7 @@ import { McplPanel, type McplServerRow } from './Mcpl';
 import { FilesPanel, FileViewerModal, type Mount, type FlatEntry, type FileViewer } from './Files';
 import { ContextPanel } from './Context';
 import { ContextDocument } from './ContextDocument';
+import { ObserverGateScreen } from './ObserverGate';
 import {
   WEB_PROTOCOL_VERSION,
   type WebUiServerMessage,
@@ -836,6 +837,20 @@ export function App() {
     <div class="flex flex-col h-screen">
       <Header welcome={welcome()} usage={usage()} status={wire.status()} />
       <ReconnectBanner status={wire.status()} />
+      <Show when={wire.observerState() === 'observer' && wire.observer()}>
+        {(info) => (
+          <div class="bg-violet-950/60 border-b border-violet-900 px-4 py-1.5 text-xs text-violet-200 flex items-center gap-2">
+            <span class="w-2 h-2 rounded-full bg-violet-500" />
+            <span>
+              Observing as <span class="font-semibold">{info().label}</span> — read-only, scopes:{' '}
+              <code class="font-mono">{info().scopes.join(', ')}</code>. Content outside your scopes is elided.
+            </span>
+          </div>
+        )}
+      </Show>
+      <Show when={wire.observerState() === 'denied' || wire.observerState() === 'unavailable'}>
+        <ObserverGateScreen state={wire.observerState() as 'denied' | 'unavailable'} />
+      </Show>
       <Show when={protoMismatch() !== null}>
         <div class="bg-amber-950/60 border-b border-amber-900 px-4 py-1.5 text-xs text-amber-200 flex items-center gap-2">
           <span class="w-2 h-2 rounded-full bg-amber-500" />

package/web/src/Context.tsx

@@ -8,7 +8,7 @@
  * a per-segment table, with an exact total token count.
  */
 
-import { createSignal, onMount, For, Show } from 'solid-js';
+import { createSignal, onCleanup, onMount, For, Show } from 'solid-js';
 
 interface Seg { messages: number; tokens: number }
 interface Stats {
@@ -28,9 +28,55 @@ interface Makeup {
   error?: string;
 }
 
+interface CoverageLevel {
+  level: number;
+  summaries: number;
+  frontier: number;
+  tokens: number;
+  coveredChunks: number;
+  coveredMessages: number;
+  coveredTokens: number;
+}
+
+interface CoverageChunk {
+  index: number;
+  messages: number;
+  tokens: number;
+  compressed: boolean;
+  summaryId: string | null;
+  maxLevel: number;
+  selectedMin: number;
+  selectedMax: number;
+  queued: boolean;
+}
+
+interface Coverage {
+  agent: string;
+  branch: string;
+  generatedAt: string;
+  supported: boolean;
+  totals: {
+    chunks: number;
+    compressedChunks: number;
+    coveredMessages: number;
+    coveredTokens: number;
+    summaries: number;
+  };
+  levels: CoverageLevel[];
+  chunks: CoverageChunk[];
+  queue: {
+    inFlight: boolean;
+    pending: string | null;
+    l1: number[];
+    merges: Array<{ targetLevel: number; sourceCount: number; firstSource: string | null; lastSource: string | null }>;
+  };
+}
+
 type Row = { key: string; label: string; messages: number; tokens: number; color: string };
 
 const fmt = (n: number) => n.toLocaleString();
+const levelColors = ['#52525b', '#06b6d4', '#10b981', '#f59e0b', '#f43f5e', '#a78bfa', '#60a5fa'];
+const levelColor = (level: number) => levelColors[Math.min(level, levelColors.length - 1)];
 
 function rowsOf(s: Stats): Row[] {
   return [
@@ -45,15 +91,19 @@ function rowsOf(s: Stats): Row[] {
 
 export function ContextPanel(props: { agent?: string }) {
   const [data, setData] = createSignal<Makeup | null>(null);
+  const [coverage, setCoverage] = createSignal<Coverage | null>(null);
   const [loading, setLoading] = createSignal(false);
+  const [coverageLoading, setCoverageLoading] = createSignal(false);
   const [err, setErr] = createSignal<string | null>(null);
+  const [coverageErr, setCoverageErr] = createSignal<string | null>(null);
+
+  const query = () => props.agent ? `?agent=${encodeURIComponent(props.agent)}` : '';
 
   const load = async () => {
     setLoading(true);
     setErr(null);
     try {
-      const q = props.agent ? `?agent=${encodeURIComponent(props.agent)}` : '';
-      const res = await fetch(`/debug/context/makeup${q}`, { credentials: 'same-origin' });
+      const res = await fetch(`/debug/context/makeup${query()}`, { credentials: 'same-origin' });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       const j = (await res.json()) as Makeup;
       if (j.error) throw new Error(j.error);
@@ -65,7 +115,30 @@ export function ContextPanel(props: { agent?: string }) {
     }
   };
 
-  onMount(load);
+  const loadCoverage = async () => {
+    setCoverageLoading(true);
+    setCoverageErr(null);
+    try {
+      const res = await fetch(`/debug/context/coverage${query()}`, { credentials: 'same-origin' });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      setCoverage((await res.json()) as Coverage);
+    } catch (e) {
+      setCoverageErr(e instanceof Error ? e.message : String(e));
+    } finally {
+      setCoverageLoading(false);
+    }
+  };
+
+  const refreshAll = () => {
+    void load();
+    void loadCoverage();
+  };
+
+  onMount(() => {
+    refreshAll();
+    const timer = window.setInterval(() => void loadCoverage(), 5_000);
+    onCleanup(() => window.clearInterval(timer));
+  });
 
   const estTotal = () => data()?.stats?.total.tokens ?? 0;
   const rows = () => {
@@ -80,10 +153,11 @@ export function ContextPanel(props: { agent?: string }) {
         <button
           type="button"
           class="px-2 py-0.5 text-neutral-400 hover:text-neutral-100 border border-neutral-700 rounded"
-          onClick={load}
-          disabled={loading()}
+          onClick={refreshAll}
+          disabled={loading() || coverageLoading()}
+          title="Refresh context diagnostics"
         >
-          {loading() ? '…' : 'refresh'}
+          {loading() || coverageLoading() ? '…' : 'refresh'}
         </button>
       </div>
 
@@ -91,6 +165,106 @@ export function ContextPanel(props: { agent?: string }) {
         <div class="text-rose-400">error: {err()}</div>
       </Show>
 
+      <Show when={coverageErr()}>
+        <div class="text-rose-400">coverage: {coverageErr()}</div>
+      </Show>
+
+      <Show when={coverage()?.supported}>
+        <section class="border-y border-neutral-800 py-3 space-y-2.5">
+          <div class="flex items-center justify-between">
+            <span class="text-neutral-300">Summary coverage</span>
+            <span class="text-neutral-600">
+              {coverage()!.queue.inFlight || coverage()!.queue.l1.length > 0 || coverage()!.queue.merges.length > 0
+                ? 'active'
+                : 'idle'}
+            </span>
+          </div>
+
+          <div class="grid grid-cols-3 gap-2 text-neutral-500">
+            <div>
+              <div class="text-base text-neutral-200">{coverage()!.totals.compressedChunks}/{coverage()!.totals.chunks}</div>
+              <div>chunks</div>
+            </div>
+            <div>
+              <div class="text-base text-neutral-200">{fmt(coverage()!.totals.coveredMessages)}</div>
+              <div>msgs covered</div>
+            </div>
+            <div>
+              <div class="text-base text-neutral-200">{fmt(coverage()!.totals.summaries)}</div>
+              <div>summaries</div>
+            </div>
+          </div>
+
+          <div class="space-y-1.5">
+            <div class="flex justify-between text-neutral-500"><span>available depth</span><span>oldest → newest</span></div>
+            <CoverageStrip chunks={coverage()!.chunks} field="available" />
+            <div class="flex justify-between text-neutral-500"><span>selected depth</span><span>{fmt(coverage()!.totals.coveredTokens)} tok covered</span></div>
+            <CoverageStrip chunks={coverage()!.chunks} field="selected" />
+          </div>
+
+          <div class="flex flex-wrap gap-x-2.5 gap-y-1 text-neutral-500">
+            <For each={[0, ...coverage()!.levels.map(level => level.level)]}>
+              {(level) => (
+                <span><span class="inline-block w-2 h-2 rounded-sm mr-1" style={{ background: levelColor(level) }} />L{level}</span>
+              )}
+            </For>
+          </div>
+
+          <table class="w-full">
+            <thead>
+              <tr class="text-neutral-500 text-left">
+                <th class="font-normal py-1">level</th>
+                <th class="font-normal text-right">frontier</th>
+                <th class="font-normal text-right">total</th>
+                <th class="font-normal text-right">coverage</th>
+              </tr>
+            </thead>
+            <tbody>
+              <For each={coverage()!.levels}>
+                {(level) => (
+                  <tr class="border-t border-neutral-900">
+                    <td class="py-1 text-neutral-200">L{level.level}</td>
+                    <td class="text-right text-neutral-300">{level.frontier}</td>
+                    <td class="text-right text-neutral-500">{level.summaries}</td>
+                    <td class="text-right text-neutral-400">{fmt(level.coveredMessages)} msg</td>
+                  </tr>
+                )}
+              </For>
+            </tbody>
+          </table>
+
+          <div class="border-t border-neutral-900 pt-2 space-y-1">
+            <div class="flex items-center justify-between">
+              <span class="text-neutral-400">Queue</span>
+              <span class={coverage()!.queue.inFlight ? 'text-amber-300' : 'text-neutral-600'}>
+                {coverage()!.queue.inFlight ? 'in flight' : 'waiting'}
+              </span>
+            </div>
+            <Show when={coverage()!.queue.pending}>
+              <div class="text-amber-200 truncate" title={coverage()!.queue.pending ?? ''}>{coverage()!.queue.pending}</div>
+            </Show>
+            <For each={coverage()!.queue.l1}>
+              {(index) => <div class="text-neutral-400">L1 · chunk {index}</div>}
+            </For>
+            <For each={coverage()!.queue.merges}>
+              {(merge) => (
+                <div class="text-neutral-400" title={`${merge.firstSource ?? ''} → ${merge.lastSource ?? ''}`}>
+                  L{merge.targetLevel} · {merge.sourceCount} source summaries
+                </div>
+              )}
+            </For>
+            <Show when={!coverage()!.queue.inFlight && coverage()!.queue.l1.length === 0 && coverage()!.queue.merges.length === 0}>
+              <div class="text-neutral-600">No queued work</div>
+            </Show>
+          </div>
+
+          <div class="flex items-center justify-between gap-2 text-neutral-600">
+            <span class="min-w-0 truncate" title={coverage()!.branch}>{coverage()!.branch}</span>
+            <a class="shrink-0 text-cyan-500 hover:text-cyan-300" href="/curve" target="_blank" rel="noreferrer">curve ↗</a>
+          </div>
+        </section>
+      </Show>
+
       <Show when={data()?.stats} fallback={<Show when={!err()}><div class="text-neutral-500">loading…</div></Show>}>
         {/* headline totals */}
         <div class="flex gap-4">
@@ -156,3 +330,29 @@ export function ContextPanel(props: { agent?: string }) {
     </div>
   );
 }
+
+function CoverageStrip(props: { chunks: CoverageChunk[]; field: 'available' | 'selected' }) {
+  const total = () => props.chunks.reduce((sum, chunk) => sum + Math.max(1, chunk.tokens), 0);
+  return (
+    <div class="flex h-4 w-full overflow-hidden rounded border border-neutral-800 bg-neutral-900">
+      <For each={props.chunks}>
+        {(chunk) => {
+          const level = () => props.field === 'available' ? chunk.maxLevel : chunk.selectedMax;
+          const title = () => {
+            const selected = chunk.selectedMin === chunk.selectedMax
+              ? `L${chunk.selectedMax}`
+              : `L${chunk.selectedMin}–L${chunk.selectedMax}`;
+            return `chunk ${chunk.index} · ${chunk.messages} msg · ${fmt(chunk.tokens)} tok · available L${chunk.maxLevel} · selected ${selected}${chunk.queued ? ' · queued' : ''}`;
+          };
+          return (
+            <div
+              class={`h-full min-w-px ${chunk.queued ? 'ring-1 ring-inset ring-amber-200' : ''}`}
+              style={{ width: `${(Math.max(1, chunk.tokens) / Math.max(1, total())) * 100}%`, background: levelColor(level()) }}
+              title={title()}
+            />
+          );
+        }}
+      </For>
+    </div>
+  );
+}

package/web/src/ObserverGate.tsx

@@ -0,0 +1,68 @@
+/**
+ * Full-screen gate shown when this device's observer key is not granted on
+ * this agent ('denied') or WebCrypto is unavailable ('unavailable' —
+ * insecure context). Shows the device fingerprint to hand to the agent /
+ * operator, and offers password sign-in as the fallback (navigating to
+ * /auth/basic triggers the browser's basic-auth prompt; with cached
+ * credentials the subsequent WS upgrade authenticates as a full client).
+ */
+import { createResource, Show } from 'solid-js';
+import { deviceFingerprint } from './observer-identity';
+
+export function ObserverGateScreen(props: { state: 'denied' | 'unavailable' }) {
+  const [fingerprint] = createResource(deviceFingerprint);
+
+  const copy = (): void => {
+    const fp = fingerprint();
+    if (fp) void navigator.clipboard?.writeText(fp);
+  };
+
+  return (
+    <div class="fixed inset-0 z-50 bg-zinc-950/95 flex items-center justify-center p-6">
+      <div class="max-w-xl w-full border border-zinc-800 rounded-lg bg-zinc-900 p-6 space-y-4 text-sm text-zinc-300">
+        <Show
+          when={props.state === 'denied'}
+          fallback={
+            <>
+              <h2 class="text-base font-semibold text-zinc-100">Observer keys unavailable here</h2>
+              <p>
+                Device-key authentication needs a secure context (https or localhost) for WebCrypto.
+                This page was loaded over plain http, so only password sign-in is available.
+              </p>
+            </>
+          }
+        >
+          <h2 class="text-base font-semibold text-zinc-100">This device isn't authorized yet</h2>
+          <p>
+            This viewer shows an agent's interior — access is granted per device, by the agent or
+            its operator. Share this device's key fingerprint with them:
+          </p>
+          <div class="flex items-center gap-2">
+            <code class="font-mono text-xs bg-zinc-950 border border-zinc-800 rounded px-2 py-1.5 break-all flex-1">
+              {fingerprint() ?? 'generating…'}
+            </code>
+            <button
+              class="px-2 py-1.5 text-xs rounded border border-zinc-700 hover:bg-zinc-800"
+              onClick={copy}
+            >
+              copy
+            </button>
+          </div>
+          <p class="text-zinc-400">
+            Grant (agent tool or operator edit of <code class="font-mono">data/observers.json</code>):{' '}
+            <code class="font-mono text-xs">
+              observers--grant key=&lt;fingerprint&gt; label=&lt;who-you-are&gt; scopes=[health,…]
+            </code>
+            . Takes effect within ~3s — then{' '}
+            <button class="underline" onClick={() => location.reload()}>reload</button>.
+          </p>
+        </Show>
+        <div class="pt-2 border-t border-zinc-800">
+          <a class="underline text-zinc-400 hover:text-zinc-200" href="/auth/basic">
+            Sign in with password instead
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}

package/web/src/observer-identity.ts

@@ -0,0 +1,110 @@
+/**
+ * Device observer identity (docs/observability.md §3, browser side).
+ *
+ * On first use the SPA generates a NON-EXTRACTABLE Ed25519 keypair via
+ * WebCrypto and persists the CryptoKey objects in IndexedDB — the private
+ * key never exists as bytes the page (or an XSS) could read. The public
+ * fingerprint (`ed25519:<base64url raw>`) is what a human shows to the
+ * agent/operator to be granted (`observers--grant`).
+ *
+ * Requires a secure context (https or localhost) — WebCrypto is absent on
+ * plain-http non-localhost origins. Callers get `null` and should offer
+ * password sign-in instead.
+ */
+
+const DB_NAME = 'fkm-observer';
+const STORE = 'keys';
+const KEY_ID = 'device-key';
+
+interface DeviceKey {
+  keyPair: CryptoKeyPair;
+  /** `ed25519:<base64url raw 32-byte public key>` */
+  id: string;
+}
+
+function b64url(buf: ArrayBuffer): string {
+  let s = '';
+  for (const b of new Uint8Array(buf)) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function idb(): Promise<IDBDatabase> {
+  return new Promise((resolvePromise, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolvePromise(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function idbGet<T>(db: IDBDatabase, key: string): Promise<T | undefined> {
+  return new Promise((resolvePromise, reject) => {
+    const tx = db.transaction(STORE, 'readonly').objectStore(STORE).get(key);
+    tx.onsuccess = () => resolvePromise(tx.result as T | undefined);
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+function idbPut(db: IDBDatabase, key: string, value: unknown): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const tx = db.transaction(STORE, 'readwrite').objectStore(STORE).put(value, key);
+    tx.onsuccess = () => resolvePromise();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+async function fingerprintOf(publicKey: CryptoKey): Promise<string> {
+  const raw = await crypto.subtle.exportKey('raw', publicKey);
+  return `ed25519:${b64url(raw)}`;
+}
+
+/** Ed25519 support probe — false on insecure contexts and old browsers. */
+export function observerCryptoAvailable(): boolean {
+  return typeof crypto !== 'undefined' && !!crypto.subtle && typeof indexedDB !== 'undefined';
+}
+
+/** Load (or create on first use) this device's observer key. Null when the
+ *  environment can't do WebCrypto Ed25519. */
+export async function ensureDeviceKey(): Promise<DeviceKey | null> {
+  if (!observerCryptoAvailable()) return null;
+  try {
+    const db = await idb();
+    const existing = await idbGet<CryptoKeyPair>(db, KEY_ID);
+    if (existing?.privateKey && existing.publicKey) {
+      return { keyPair: existing, id: await fingerprintOf(existing.publicKey) };
+    }
+    const keyPair = (await crypto.subtle.generateKey(
+      { name: 'Ed25519' } as AlgorithmIdentifier,
+      false, // non-extractable — the private key never leaves the browser
+      ['sign', 'verify'],
+    )) as CryptoKeyPair;
+    await idbPut(db, KEY_ID, keyPair);
+    return { keyPair, id: await fingerprintOf(keyPair.publicKey) };
+  } catch (err) {
+    console.warn('[observer] device key unavailable:', err);
+    return null;
+  }
+}
+
+/** Build the signed observer-hello identity envelope for `host` (the value
+ *  the server sent in observer-auth-required — its own Host header). */
+export async function buildHelloIdentity(host: string): Promise<{
+  scheme: 'ed25519'; id: string; proof: string; timestamp: string;
+} | null> {
+  const key = await ensureDeviceKey();
+  if (!key) return null;
+  const timestamp = new Date().toISOString();
+  const statement = `connectome-observer|v1|${host}|${timestamp}`;
+  const sig = await crypto.subtle.sign(
+    { name: 'Ed25519' } as AlgorithmIdentifier,
+    key.keyPair.privateKey,
+    new TextEncoder().encode(statement),
+  );
+  return { scheme: 'ed25519', id: key.id, proof: b64url(sig), timestamp };
+}
+
+/** Current device fingerprint for display (creates the key if absent). */
+export async function deviceFingerprint(): Promise<string | null> {
+  const key = await ensureDeviceKey();
+  return key?.id ?? null;
+}

package/web/src/wire.ts

@@ -11,11 +11,31 @@ import type {
   WebUiClientMessage,
   WebUiServerMessage,
 } from '@conhost/web/protocol';
+import { buildHelloIdentity } from './observer-identity.js';
 
 export type ConnectionStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
 
+/**
+ * Observer-auth state (docs/observability.md, browser side).
+ *   'none'        — basic-auth / open server; historical behavior
+ *   'authing'     — server demanded observer auth; hello sent
+ *   'observer'    — key-authenticated; `observer()` carries label + scopes
+ *   'denied'      — this device's key holds no grant on this agent
+ *   'unavailable' — WebCrypto absent (insecure context) — password only
+ */
+export type ObserverAuthState = 'none' | 'authing' | 'observer' | 'denied' | 'unavailable';
+
+export interface ObserverInfo {
+  label: string;
+  scopes: string[];
+}
+
 export interface WireClient {
   status: Accessor<ConnectionStatus>;
+  /** Observer-auth state for this connection. */
+  observerState: Accessor<ObserverAuthState>;
+  /** Grant info after a successful observer handshake. */
+  observer: Accessor<ObserverInfo | null>;
   /** Last received message, or null. Useful for reactive folds. */
   lastMessage: Accessor<WebUiServerMessage | null>;
   /** Subscribe to all incoming messages. Returns an unsubscribe fn. */
@@ -42,6 +62,8 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
 
   const [status, setStatus] = createSignal<ConnectionStatus>('connecting');
   const [lastMessage, setLastMessage] = createSignal<WebUiServerMessage | null>(null);
+  const [observerState, setObserverState] = createSignal<ObserverAuthState>('none');
+  const [observer, setObserver] = createSignal<ObserverInfo | null>(null);
   const handlers = new Set<(m: WebUiServerMessage) => void>();
 
   let socket: WebSocket | null = null;
@@ -49,6 +71,21 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
   let delay = initialDelay;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Server demanded observer auth → sign and reply with this device's key.
+   *  Failure paths surface via observerState so the UI can show the
+   *  fingerprint-grant screen or fall back to password sign-in. */
+  async function respondToAuthRequired(sock: WebSocket, host: string): Promise<void> {
+    setObserverState('authing');
+    const identity = await buildHelloIdentity(host);
+    if (!identity) {
+      setObserverState('unavailable');
+      return;
+    }
+    if (sock.readyState === WebSocket.OPEN) {
+      sock.send(JSON.stringify({ type: 'observer-hello', identity }));
+    }
+  }
+
   function connect(): void {
     if (stopped) return;
     setStatus(socket ? 'reconnecting' : 'connecting');
@@ -67,18 +104,35 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
         console.warn('[wire] failed to parse message', event.data);
         return;
       }
+      // Observer handshake frames are handled here (the wire owns the
+      // socket); they also fan out to handlers for any UI that cares.
+      if (parsed.type === 'observer-auth-required' && socket) {
+        void respondToAuthRequired(socket, parsed.host);
+      } else if (parsed.type === 'observer-ack') {
+        setObserverState('observer');
+        setObserver({ label: parsed.label, scopes: parsed.scopes });
+        // Session cookie lets the SPA hit /debug/* and /healthz over HTTP.
+        document.cookie = `fkm_obs=${parsed.sessionToken}; path=/; SameSite=Lax; max-age=${12 * 3600}`;
+      }
       setLastMessage(parsed);
       for (const h of handlers) {
         try { h(parsed); } catch (err) { console.error('[wire] handler threw', err); }
       }
     });
 
-    socket.addEventListener('close', () => {
+    socket.addEventListener('close', (ev) => {
       socket = null;
       if (stopped) {
         setStatus('closed');
         return;
       }
+      if (ev.code === 4401) {
+        // Observer auth rejected — reconnect loops would spam the server;
+        // hold in 'denied' until the user acts (grant lands / password).
+        setObserverState('denied');
+        setStatus('closed');
+        return;
+      }
       setStatus('reconnecting');
       reconnectTimer = setTimeout(connect, delay);
       delay = Math.min(delay * 2, maxDelay);
@@ -93,6 +147,8 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
 
   return {
     status,
+    observerState,
+    observer,
     lastMessage,
     onMessage(handler) {
       handlers.add(handler);