@animalabs/connectome-host 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.5.3 — 2026-07-26
+
+### Added
+
+- **Dry-run buttons, and the resulting context in the main pane.** Settings now
+  has explicit `dry run` and `dry run + show context` buttons; the latter
+  renders the context those settings WOULD produce in a new main-pane view,
+  behind an unmissable "dry run — not applied" banner. Entries come from
+  context-manager's dry-run select, so it is the actual layout, not an estimate.
+- Dry runs report how long they took, and the panel states the cost up front: a
+  full compile, seconds on a large store, briefly pausing the agent.
+
+### Fixed
+
+- **Preview no longer fires on every keystroke.** It was debounced-on-input, but
+  a dry run is a real compile and `select()` is synchronous — so each one blocks
+  the agent's event loop (no heartbeat, no Discord, no MCPL). Typing a budget
+  stacked those stalls and made the UI look hung. It is now operator-initiated
+  only, with server-side single-flight and a 3s cooldown that returns 429 rather
+  than queueing more agent pauses.
+- `middleChunkCount` was labelled "middle chunks" but the adaptive picker's unit
+  is the MESSAGE (14,057 for a store with 800 chunks). Relabelled "middle
+  messages (picker units)".
+- The sidebar was `w-72` (288px) and clipped the dense numeric tables; now
+  `w-96`, wider still on xl displays.
+
 ## 0.5.2 — 2026-07-26
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {

package/src/modules/web-ui-module.ts

@@ -1200,6 +1200,18 @@ export class WebUiModule implements Module {
    * Returns 501 when the resolved context-manager predates dry-run support, so
    * the panel can say so instead of rendering an empty result.
    */
+  /**
+   * Single-flight + cooldown for preview.
+   *
+   * A preview is a real compile: ~8s on a large store, and `select()` is
+   * synchronous so it BLOCKS the agent's event loop for that whole time (no
+   * heartbeat, no Discord, no MCPL). Overlapping or rapid-fire previews
+   * therefore don't just queue — they stack agent stalls. Reject instead.
+   */
+  private previewInFlight = false;
+  private previewLastAt = 0;
+  private static readonly PREVIEW_COOLDOWN_MS = 3_000;
+
   private handleContextPreview(url: URL): Response {
     const app = sharedServer?.app;
     if (!app) return Response.json({ error: 'app not bound yet' }, { status: 503 });
@@ -1225,8 +1237,33 @@ export class WebUiModule implements Module {
       overrides.recentWindowTokens = tail;
     }
 
+    // `render=1` additionally returns the rendered dry context for display.
+    const wantRender = (() => {
+      const v = url.searchParams.get('render');
+      return v !== null && v !== '0' && v !== 'false';
+    })();
+
+    if (this.previewInFlight) {
+      return Response.json(
+        { error: 'a preview is already running — it blocks the agent, so they are serialized' },
+        { status: 429 },
+      );
+    }
+    const sinceLast = Date.now() - this.previewLastAt;
+    if (sinceLast < WebUiModule.PREVIEW_COOLDOWN_MS) {
+      return Response.json(
+        {
+          error: `preview cooling down — ${Math.ceil((WebUiModule.PREVIEW_COOLDOWN_MS - sinceLast) / 1000)}s left. `
+            + 'Each run is a full compile and briefly pauses the agent.',
+        },
+        { status: 429 },
+      );
+    }
+
     const fw = app.framework as unknown as {
-      previewContextSettings?: (n: string, b: number, o?: Record<string, unknown>) => unknown;
+      previewContextSettings?: (
+        n: string, b: number, o?: Record<string, unknown>, x?: { render?: boolean },
+      ) => unknown;
     };
     if (typeof fw.previewContextSettings !== 'function') {
       return Response.json(
@@ -1234,11 +1271,14 @@ export class WebUiModule implements Module {
         { status: 501 },
       );
     }
+    this.previewInFlight = true;
+    const startedAt = Date.now();
     try {
       const result = fw.previewContextSettings(
         agentName,
         budget,
         Object.keys(overrides).length > 0 ? overrides : undefined,
+        wantRender ? { render: true } : undefined,
       );
       if (result === null || result === undefined) {
         return Response.json(
@@ -1284,6 +1324,8 @@ export class WebUiModule implements Module {
           /** Exhausted AND over the request => this budget is UNREACHABLE. */
           unreachable: r.exhausted === true && !fitsRequested,
         },
+        /** How long the agent was blocked, so the operator sees the real cost. */
+        elapsedMs: Date.now() - startedAt,
         preview: result,
       });
     } catch (err) {
@@ -1291,6 +1333,9 @@ export class WebUiModule implements Module {
         { error: err instanceof Error ? err.message : String(err) },
         { status: 500 },
       );
+    } finally {
+      this.previewInFlight = false;
+      this.previewLastAt = Date.now();
     }
   }
 

package/web/src/App.tsx

@@ -10,6 +10,7 @@ import { UsagePanel } from './Usage';
 import { LessonsPanel, type LessonRow } from './Lessons';
 import { McplPanel, type McplServerRow } from './Mcpl';
 import { SettingsPanel, type SettingsState } from './Settings';
+import { DryContext, type DryContextData } from './DryContext';
 import { FilesPanel, FileViewerModal, type Mount, type FlatEntry, type FileViewer } from './Files';
 import { ContextPanel } from './Context';
 import { ContextDocument } from './ContextDocument';
@@ -275,7 +276,9 @@ export function App() {
    *  the default; lessons / mcp / files are operator-driven panels. */
   type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
   const [sidebarTab, setSidebarTab] = createSignal<SidebarTab>('tree');
-  const [mainView, setMainView] = createSignal<'chat' | 'context'>('chat');
+  const [mainView, setMainView] = createSignal<'chat' | 'context' | 'dry'>('chat');
+  /** Rendered dry-run context awaiting display. Never applied — see DryContext. */
+  const [dryContext, setDryContext] = createSignal<DryContextData | null>(null);
 
   /** Scope shared by Lessons / Files / Recipe panels. 'local' means the
    *  parent process; otherwise the fleet child's name. The scope is shared
@@ -1075,13 +1078,19 @@ export function App() {
           <div class="flex border-b border-neutral-800 bg-neutral-900/40 text-[11px] font-mono">
             <button type="button" class={`px-3 py-1.5 ${mainView() === 'chat' ? 'text-neutral-100 bg-neutral-900 border-b border-cyan-700' : 'text-neutral-500 hover:text-neutral-300'}`} onClick={() => setMainView('chat')}>Chat</button>
             <button type="button" class={`px-3 py-1.5 ${mainView() === 'context' ? 'text-neutral-100 bg-neutral-900 border-b border-cyan-700' : 'text-neutral-500 hover:text-neutral-300'}`} onClick={() => setMainView('context')}>Context</button>
+            <Show when={dryContext()}>
+              <button type="button" class={`px-3 py-1.5 ${mainView() === 'dry' ? 'text-amber-200 bg-neutral-900 border-b border-amber-600' : 'text-amber-500/70 hover:text-amber-300'}`} onClick={() => setMainView('dry')}>Dry run</button>
+            </Show>
           </div>
           <div
             ref={scrollPane}
             class="flex-1 overflow-y-auto px-4 py-3 space-y-3"
             onScroll={onScrollPane}
           >
-            <Show when={mainView() === 'context'} fallback={<>
+            <Show when={mainView() === 'dry'}>
+              <DryContext data={dryContext()} onClose={() => { setDryContext(null); setMainView('chat'); }} />
+            </Show>
+            <Show when={mainView() === 'context'} fallback={<Show when={mainView() === 'chat'}>
             <Show when={(historyInfo()?.startIndex ?? 0) > 0}>
               <button
                 type="button"
@@ -1102,7 +1111,7 @@ export function App() {
             <For each={messages}>{(m) => (
               <MessageView msg={m} results={toolResults()} toolUseIds={toolUseIds()} />
             )}</For>
-            </>}>
+            </Show>}>
               <ContextDocument agent={panelScope() === 'local' ? undefined : panelScope()} />
             </Show>
           </div>
@@ -1179,7 +1188,9 @@ export function App() {
             onClose={closePanel}
           />
         </Show>
-        <aside class="w-72 border-l border-neutral-800 bg-neutral-950 shrink-0 flex flex-col">
+        {/* Was w-72 (288px): the context/settings panels have dense numeric
+            tables that did not fit. Widen, and give large displays more. */}
+        <aside class="w-96 xl:w-[30rem] border-l border-neutral-800 bg-neutral-950 shrink-0 flex flex-col">
           <SidebarTabs
             current={sidebarTab()}
             onSelect={(tab) => {
@@ -1237,6 +1248,7 @@ export function App() {
                 onReset={(keys, persist) =>
                   wire.send({ type: 'settings-reset', ...(keys ? { keys } : {}), persist })}
                 onCancelTransition={() => wire.send({ type: 'settings-cancel-transition' })}
+                onDryContext={(ctx) => { setDryContext(ctx as DryContextData); setMainView('dry'); }}
               />
             </Show>
             <Show when={sidebarTab() === 'files'}>

package/web/src/DryContext.tsx

@@ -0,0 +1,163 @@
+/**
+ * DryContext — the context a hypothetical settings change WOULD produce,
+ * rendered in the main pane.
+ *
+ * Distinct from `ContextDocument`, which shows the agent's live context. This
+ * one shows the output of a dry run: nothing here has been applied, and the
+ * agent is still running the settings shown in the sidebar. The banner says so,
+ * because a rendered context that looks exactly like the real thing is a good
+ * way for an operator to lose track of which is which.
+ *
+ * Entries come straight from context-manager's dry-run select, so this is the
+ * actual layout that budget would produce — not an approximation.
+ */
+
+import { createSignal, For, Show } from 'solid-js';
+
+interface Seg { messages: number; tokens: number }
+interface DryStats {
+  head: Seg; tail: Seg; middleRaw: Seg;
+  summaries?: Record<string, { count: number; tokens: number }>;
+  total: Seg;
+}
+
+export interface DryContextData {
+  entries: unknown[];
+  stats?: unknown;
+  label: string;
+}
+
+const fmt = (n: number) => n.toLocaleString();
+
+function textOf(content: unknown): string {
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => {
+        if (!b || typeof b !== 'object') return String(b ?? '');
+        const t = (b as { type?: string }).type;
+        if (t === 'text') return (b as { text?: string }).text ?? '';
+        if (t === 'image') return '[image]';
+        if (t === 'thinking' || t === 'redacted_thinking') return '[thinking]';
+        if (t === 'tool_use') return `[tool_use ${(b as { name?: string }).name ?? ''}]`;
+        if (t === 'tool_result') return '[tool_result]';
+        return '';
+      })
+      .join('');
+  }
+  return String(content ?? '');
+}
+
+/** Recall pairs render as a CM prompt followed by the summary text. */
+const RECALL_MARKERS = ['what do you remember', 'recall memory', '[cm]'];
+const isRecallPrompt = (s: string) =>
+  s.length < 400 && RECALL_MARKERS.some((m) => s.toLowerCase().includes(m));
+
+export function DryContext(props: { data: DryContextData | null; onClose(): void }) {
+  const [expanded, setExpanded] = createSignal<Set<number>>(new Set());
+  const toggle = (i: number) => {
+    const next = new Set(expanded());
+    next.has(i) ? next.delete(i) : next.add(i);
+    setExpanded(next);
+  };
+
+  const rows = () =>
+    (props.data?.entries ?? []).map((e, i) => {
+      const o = (e ?? {}) as { participant?: string; role?: string; content?: unknown };
+      const body = textOf(o.content);
+      return {
+        i,
+        who: o.participant ?? o.role ?? '?',
+        body,
+        recall: isRecallPrompt(body),
+        chars: body.length,
+      };
+    });
+
+  const stats = () => props.data?.stats as DryStats | undefined;
+
+  return (
+    <div class="h-full overflow-y-auto">
+      <Show
+        when={props.data}
+        fallback={
+          <div class="p-6 text-neutral-500 text-sm">
+            No dry run yet. Open <span class="font-mono text-neutral-400">Settings</span> in the
+            sidebar, set a budget, and press{' '}
+            <span class="font-mono text-cyan-300">dry run + show context</span>.
+          </div>
+        }
+      >
+        {/* Unmissable: this is NOT the live context. */}
+        <div class="sticky top-0 z-10 bg-amber-950/80 backdrop-blur border-b border-amber-800
+                    px-4 py-2 text-[11px] text-amber-200 flex items-center gap-3 flex-wrap">
+          <span class="font-semibold uppercase tracking-wider">dry run — not applied</span>
+          <span class="font-mono text-amber-300/90">{props.data!.label}</span>
+          <span class="text-amber-300/70">
+            the agent is still running its current settings
+          </span>
+          <button
+            type="button"
+            class="ml-auto px-2 py-0.5 rounded bg-neutral-800 hover:bg-neutral-700
+                   text-neutral-300 font-mono text-[10px]"
+            onClick={() => props.onClose()}
+          >
+            close
+          </button>
+        </div>
+
+        <Show when={stats()}>
+          <div class="px-4 py-2 border-b border-neutral-800 text-[11px] font-mono
+                      text-neutral-400 flex gap-4 flex-wrap">
+            <span>entries <span class="text-neutral-200">{fmt(rows().length)}</span></span>
+            <span>head <span class="text-neutral-200">{fmt(stats()!.head?.tokens ?? 0)}</span></span>
+            <span>middle <span class="text-neutral-200">{fmt(stats()!.middleRaw?.tokens ?? 0)}</span></span>
+            <span>tail <span class="text-neutral-200">{fmt(stats()!.tail?.tokens ?? 0)}</span></span>
+            <span>total <span class="text-neutral-200">{fmt(stats()!.total?.tokens ?? 0)}</span></span>
+          </div>
+        </Show>
+
+        <div class="px-4 py-3 space-y-2">
+          <For each={rows()}>
+            {(r) => (
+              <div
+                class={`rounded border px-2.5 py-1.5 ${
+                  r.recall
+                    ? 'border-orange-900/60 bg-orange-950/20'
+                    : 'border-neutral-800 bg-neutral-900/40'
+                }`}
+              >
+                <div class="flex items-baseline gap-2 mb-0.5">
+                  <span class="text-[10px] font-mono text-neutral-500">#{r.i}</span>
+                  <span
+                    class={`text-[11px] font-mono ${
+                      r.recall ? 'text-orange-300' : 'text-cyan-300'
+                    }`}
+                  >
+                    {r.who}
+                  </span>
+                  <span class="text-[10px] text-neutral-600">{fmt(r.chars)} chars</span>
+                  <Show when={r.chars > 600}>
+                    <button
+                      type="button"
+                      class="ml-auto text-[10px] font-mono text-neutral-500 hover:text-neutral-300"
+                      onClick={() => toggle(r.i)}
+                    >
+                      {expanded().has(r.i) ? 'collapse' : 'expand'}
+                    </button>
+                  </Show>
+                </div>
+                <div
+                  class="text-[12px] text-neutral-300 whitespace-pre-wrap break-words leading-relaxed"
+                >
+                  {expanded().has(r.i) || r.chars <= 600
+                    ? r.body
+                    : r.body.slice(0, 600) + ' …'}
+                </div>
+              </div>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  );
+}

package/web/src/Settings.tsx

@@ -15,7 +15,7 @@
  *     that looks like "nothing would change".
  */
 
-import { createSignal, Show, For, onCleanup } from 'solid-js';
+import { createSignal, Show, For } from 'solid-js';
 
 export interface SettingsSnapshot {
   contextBudgetTokens: number;
@@ -101,6 +101,8 @@ export function SettingsPanel(props: {
   }): void;
   onReset(keys: string[] | undefined, persist: boolean): void;
   onCancelTransition(): void;
+  /** Hand a rendered dry context to the main pane for display. */
+  onDryContext?(ctx: { entries: unknown[]; stats?: unknown; label: string }): void;
 }) {
   const [budget, setBudget] = createSignal<string>('');
   const [tail, setTail] = createSignal<string>('');
@@ -113,8 +115,7 @@ export function SettingsPanel(props: {
   const [previewErr, setPreviewErr] = createSignal<string | null>(null);
   const [previewing, setPreviewing] = createSignal(false);
 
-  let debounce: number | undefined;
-  onCleanup(() => { if (debounce) window.clearTimeout(debounce); });
+  const [elapsed, setElapsed] = createSignal<number | null>(null);
 
   const s = () => props.state?.settings;
   const isHot = (k: string) => props.state?.hotKeys.includes(k) ?? false;
@@ -134,38 +135,55 @@ export function SettingsPanel(props: {
     return Number.isSafeInteger(n) && n > 0 ? n : undefined;
   };
 
-  /** Debounced: an operator dragging a value should not fire a compile per keystroke.
-   *  The request itself is non-committing, but it is still real CPU on a live agent. */
-  const runPreview = () => {
-    if (!props.state?.previewAvailable) return;
+  /**
+   * Explicit dry run. NOT wired to input events on purpose.
+   *
+   * A dry run is a real compile: seconds on a large store, and the compile is
+   * synchronous, so it briefly blocks the agent's event loop — no heartbeat, no
+   * Discord, no MCPL for the duration. An earlier version of this panel fired it
+   * on every keystroke (debounced), which stacked agent stalls and made the UI
+   * look hung. The operator asks for it now.
+   *
+   * `render` also fetches the resulting context for the main pane.
+   */
+  const runDryRun = async (render: boolean) => {
+    if (!props.state?.previewAvailable || previewing()) return;
     const b = num(budget());
-    if (b === undefined) { setPreview(null); setPreviewErr(null); return; }
-    if (debounce) window.clearTimeout(debounce);
-    debounce = window.setTimeout(async () => {
-      setPreviewing(true);
-      setPreviewErr(null);
-      try {
-        const qs = new URLSearchParams({ budget: String(b), agent: props.state!.agent });
-        const t = num(tail());
-        if (t !== undefined) qs.set('tail', String(t));
-        const res = await fetch(`/debug/context/preview?${qs}`, { credentials: 'same-origin' });
-        const body = await res.json();
-        if (!res.ok) {
-          setPreview(null);
-          setAcct(null);
-          setPreviewErr(body?.error ?? `HTTP ${res.status}`);
-          return;
-        }
-        setPreview(body.preview as PreviewResult);
-        setAcct((body.accounting ?? null) as PreviewAccounting | null);
-      } catch (e) {
+    if (b === undefined) { setPreviewErr('budget must be a positive integer'); return; }
+    setPreviewing(true);
+    setPreviewErr(null);
+    setElapsed(null);
+    try {
+      const qs = new URLSearchParams({ budget: String(b), agent: props.state!.agent });
+      const t = num(tail());
+      if (t !== undefined) qs.set('tail', String(t));
+      if (render) qs.set('render', '1');
+      const res = await fetch(`/debug/context/preview?${qs}`, { credentials: 'same-origin' });
+      const body = await res.json();
+      if (!res.ok) {
         setPreview(null);
         setAcct(null);
-        setPreviewErr(e instanceof Error ? e.message : String(e));
-      } finally {
-        setPreviewing(false);
+        // 429 is the single-flight / cooldown guard, not a failure.
+        setPreviewErr(body?.error ?? `HTTP ${res.status}`);
+        return;
       }
-    }, 350) as unknown as number;
+      setPreview(body.preview as PreviewResult);
+      setAcct((body.accounting ?? null) as PreviewAccounting | null);
+      setElapsed(typeof body.elapsedMs === 'number' ? body.elapsedMs : null);
+      if (render && body.preview?.entries) {
+        props.onDryContext?.({
+          entries: body.preview.entries,
+          stats: body.preview.stats,
+          label: `budget ${b.toLocaleString()}${t !== undefined ? `, tail ${t.toLocaleString()}` : ''}`,
+        });
+      }
+    } catch (e) {
+      setPreview(null);
+      setAcct(null);
+      setPreviewErr(e instanceof Error ? e.message : String(e));
+    } finally {
+      setPreviewing(false);
+    }
   };
 
   const apply = () => {
@@ -297,7 +315,7 @@ export function SettingsPanel(props: {
                   disabled={!isHot(key)}
                   value={get()}
                   placeholder={isHot(key) ? 'tokens' : 'restart only'}
-                  onInput={(e) => { set(e.currentTarget.value); runPreview(); }}
+                  onInput={(e) => set(e.currentTarget.value)}
                   class="flex-1 bg-neutral-900 border border-neutral-700 rounded px-1.5 py-0.5
                          font-mono text-[11px] text-neutral-100 disabled:opacity-40"
                 />
@@ -356,13 +374,40 @@ export function SettingsPanel(props: {
 
         {/* ---- preview ---- */}
         <div class="border-t border-neutral-800 pt-2">
-          <div class="flex items-center gap-2 mb-1">
+          <div class="flex items-center gap-2 mb-1 flex-wrap">
             <span class="text-neutral-500 uppercase tracking-wider text-[10px] font-semibold">
-              preview
+              dry run
             </span>
+            <button
+              type="button"
+              disabled={previewing() || !props.state!.previewAvailable}
+              class="px-2 py-0.5 text-[10px] rounded font-mono bg-neutral-800 hover:bg-neutral-700
+                     text-neutral-200 disabled:opacity-30"
+              onClick={() => void runDryRun(false)}
+              title="Compile at these settings without applying them. Does not commit anything."
+            >
+              dry run
+            </button>
+            <button
+              type="button"
+              disabled={previewing() || !props.state!.previewAvailable}
+              class="px-2 py-0.5 text-[10px] rounded font-mono bg-cyan-900/40 hover:bg-cyan-900/60
+                     text-cyan-200 disabled:opacity-30"
+              onClick={() => void runDryRun(true)}
+              title="Dry run and show the resulting context in the main pane."
+            >
+              dry run + show context
+            </button>
             <Show when={previewing()}>
-              <span class="text-neutral-600 text-[10px]">computing…</span>
+              <span class="text-amber-400/90 text-[10px]">running — agent paused…</span>
             </Show>
+            <Show when={!previewing() && elapsed() !== null}>
+              <span class="text-neutral-600 text-[10px]">{(elapsed()! / 1000).toFixed(1)}s</span>
+            </Show>
+          </div>
+          <div class="text-[10px] text-neutral-600 mb-1.5 leading-relaxed">
+            A dry run is a full compile — seconds on a large store — and it briefly pauses the
+            agent. It commits nothing: no fold resolutions, no compression queued.
           </div>
 
           <Show when={!props.state!.previewAvailable}>
@@ -432,7 +477,7 @@ export function SettingsPanel(props: {
                       ['head (verbatim)', p().headTokens],
                       ['tail (verbatim)', p().tailTokens],
                       ['middle (foldable)', p().middleTokens],
-                      ['middle chunks', p().middleChunkCount],
+                      ['middle messages (picker units)', p().middleChunkCount],
                       ['deepest fold level', `L${p().deepestLevel}`],
                       ['folds applied', p().appliedCount],
                     ] as Array<[string, unknown]>}>