@animalabs/connectome-host 0.4.0 → 0.5.1

package/src/web/protocol.ts

@@ -391,6 +391,41 @@ export interface McplListMessage {
   }>;
 }
 
+/**
+ * Runtime context-settings snapshot.
+ *
+ * BROADCAST to every welcomed client on change — unlike `mcpl-list`, these are
+ * live process state, not a config file, so two operators must not see
+ * divergent values.
+ */
+export interface SettingsStateMessage {
+  type: 'settings-state';
+  agent: string;
+  /** Live values. `transition` is 'converging' while a paced descent runs. */
+  settings: {
+    contextBudgetTokens: number;
+    tailTokens?: number;
+    transitionPaceTokens?: number;
+    sameRoundThinkTextPolicy?: string;
+    sameRoundThinkTextPolicySource?: string;
+    transition: 'stable' | 'converging' | 'blocked';
+    /** Why a descent is stuck: pace below floor, or protected context too big. */
+    transitionReason?: string;
+  };
+  /** Keys currently overridden away from the recipe (i.e. persisted). */
+  overrides: string[];
+  /** Which keys this build can apply live. Everything else needs a restart —
+   *  the UI must show that split rather than implying all knobs are hot. */
+  hotKeys: string[];
+  /** False when the strategy is not hot-configurable at all (e.g. passthrough):
+   *  the panel should go read-only rather than offer controls that will throw. */
+  hotConfigurable: boolean;
+  /** True when this build's context-manager exposes dry-run preview. Older
+   *  context-manager versions resolve without it, and the panel must say
+   *  "preview unavailable" rather than silently showing nothing. */
+  previewAvailable: boolean;
+}
+
 /** A page of older history — response to `request-history`, routed only to
  *  the requesting client and correlated by `corrId`. */
 export interface HistoryPageMessage {
@@ -474,6 +509,7 @@ export type WebUiServerMessage =
   | QuitConfirmRequiredMessage
   | LessonsListMessage
   | McplListMessage
+  | SettingsStateMessage
   | WorkspaceMountsMessage
   | WorkspaceTreeMessage
   | WorkspaceFileMessage
@@ -633,6 +669,58 @@ export interface McplSetEnvMessage {
   env: Record<string, string>;
 }
 
+/** Pull the current runtime context settings for an agent, plus which knobs are
+ *  live-appliable vs restart-only. Response is a `settings-state` envelope. */
+export interface RequestSettingsMessage {
+  type: 'request-settings';
+  /** Agent name; defaults to the recipe's primary agent. */
+  agent?: string;
+}
+
+/**
+ * Apply runtime context settings live.
+ *
+ * Semantics that the UI must not misrepresent:
+ *  - RAISING contextBudgetTokens applies immediately.
+ *  - LOWERING it starts a PACED convergence (`transition: 'converging'`)
+ *    rather than folding everything at once; it can be cancelled.
+ *  - Only these keys are hot. Chunk size, head window, merge threshold and
+ *    friends are recipe-and-restart only.
+ *
+ * `persist: false` makes the change ephemeral — live now, gone on restart —
+ * which is the mode for operator experiments. Default persists.
+ *
+ * `notify: true` pushes a notice into the agent's context. OFF by default and
+ * deliberately so: the notice is new text in the very context being tuned, so
+ * it invalidates the KV prefix and can itself trip a refusal classifier. The
+ * agent can always PULL current settings via its own `agent_settings` tool.
+ */
+export interface SettingsUpdateMessage {
+  type: 'settings-update';
+  agent?: string;
+  contextBudgetTokens?: number;
+  tailTokens?: number;
+  transitionPaceTokens?: number;
+  persist?: boolean;
+  notify?: boolean;
+}
+
+/** Revert named settings to their recipe values (all four when omitted). */
+export interface SettingsResetMessage {
+  type: 'settings-reset';
+  agent?: string;
+  keys?: string[];
+  persist?: boolean;
+  notify?: boolean;
+}
+
+/** Abandon an in-flight paced descent, holding the current frontier. */
+export interface SettingsCancelTransitionMessage {
+  type: 'settings-cancel-transition';
+  agent?: string;
+  persist?: boolean;
+}
+
 /** Pull the list of workspace mounts. Response is `workspace-mounts`.
  *  Optional `scope` selects a fleet child instead of the parent. */
 export interface RequestWorkspaceMountsMessage {
@@ -706,6 +794,10 @@ export type WebUiClientMessage =
   | McplAddMessage
   | McplRemoveMessage
   | McplSetEnvMessage
+  | RequestSettingsMessage
+  | SettingsUpdateMessage
+  | SettingsResetMessage
+  | SettingsCancelTransitionMessage
   | RequestWorkspaceMountsMessage
   | RequestWorkspaceTreeMessage
   | RequestWorkspaceFileMessage
@@ -768,6 +860,30 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
       return isValidMcplId(v.id);
     case 'mcpl-set-env':
       return isValidMcplId(v.id) && isStringMap(v.env);
+    case 'request-settings':
+      return isOptionalNonEmptyString(v.agent);
+    case 'settings-update': {
+      if (!isOptionalNonEmptyString(v.agent)) return false;
+      if (!isOptionalBool(v.persist) || !isOptionalBool(v.notify)) return false;
+      // Positive-integer-or-absent for each knob. The semantic gate (budget must
+      // exceed max response tokens; tail/pace need a hot-configurable strategy)
+      // lives in Agent.validateRuntimeSettingsPatch — this only guarantees the
+      // shape so that gate gets numbers instead of strings.
+      for (const k of ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens']) {
+        if (!isOptionalPositiveInt(v[k])) return false;
+      }
+      // Require at least one actual knob: an empty patch would throw downstream.
+      return v.contextBudgetTokens !== undefined
+        || v.tailTokens !== undefined
+        || v.transitionPaceTokens !== undefined;
+    }
+    case 'settings-reset':
+      return isOptionalNonEmptyString(v.agent)
+        && isOptionalBool(v.persist)
+        && isOptionalBool(v.notify)
+        && isOptionalStringArray(v.keys);
+    case 'settings-cancel-transition':
+      return isOptionalNonEmptyString(v.agent) && isOptionalBool(v.persist);
     case 'request-workspace-mounts':
       return v.scope === undefined || typeof v.scope === 'string';
     case 'request-workspace-tree':
@@ -822,3 +938,17 @@ function isOptionalStringArray(v: unknown): v is string[] | undefined {
   if (!Array.isArray(v)) return false;
   return v.every((x) => typeof x === 'string');
 }
+
+function isOptionalNonEmptyString(v: unknown): v is string | undefined {
+  return v === undefined || isNonEmptyString(v);
+}
+
+function isOptionalBool(v: unknown): v is boolean | undefined {
+  return v === undefined || typeof v === 'boolean';
+}
+
+/** Token counts: safe positive integers only. Rejects strings, NaN, Infinity,
+ *  fractions and negatives before they reach the settings validator. */
+function isOptionalPositiveInt(v: unknown): v is number | undefined {
+  return v === undefined || (typeof v === 'number' && Number.isSafeInteger(v) && v > 0);
+}

package/test/settings-protocol.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Wire validation for the context-settings messages.
+ *
+ * These messages mutate a LIVE agent's context budget, so malformed payloads
+ * must be rejected at the protocol edge rather than reaching
+ * Agent.validateRuntimeSettingsPatch as strings/NaN/fractions.
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { isClientMessage } from '../src/web/protocol.js';
+
+describe('settings messages — wire validation', () => {
+  it('accepts a minimal budget update', () => {
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 120_000 })).toBe(true);
+  });
+
+  it('accepts tail-only and pace-only updates', () => {
+    expect(isClientMessage({ type: 'settings-update', tailTokens: 30_000 })).toBe(true);
+    expect(isClientMessage({ type: 'settings-update', transitionPaceTokens: 8_000 })).toBe(true);
+  });
+
+  it('accepts persist/notify flags and an agent name', () => {
+    expect(isClientMessage({
+      type: 'settings-update',
+      contextBudgetTokens: 100_000,
+      persist: false,
+      notify: true,
+      agent: 'mythos',
+    })).toBe(true);
+  });
+
+  it('rejects an empty patch — it would throw downstream', () => {
+    expect(isClientMessage({ type: 'settings-update' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', persist: true })).toBe(false);
+  });
+
+  it('rejects non-integer / non-positive / stringly token counts', () => {
+    for (const bad of ['100000', 100.5, -1, 0, NaN, Infinity, null, {}]) {
+      expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: bad }))
+        .toBe(false);
+    }
+  });
+
+  it('rejects non-boolean flags and empty agent names', () => {
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, persist: 'yes' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, notify: 1 })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, agent: '' })).toBe(false);
+  });
+
+  it('validates reset and cancel shapes', () => {
+    expect(isClientMessage({ type: 'settings-reset' })).toBe(true);
+    expect(isClientMessage({ type: 'settings-reset', keys: ['contextBudgetTokens'] })).toBe(true);
+    expect(isClientMessage({ type: 'settings-reset', keys: 'contextBudgetTokens' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-cancel-transition' })).toBe(true);
+    expect(isClientMessage({ type: 'settings-cancel-transition', persist: false })).toBe(true);
+    expect(isClientMessage({ type: 'settings-cancel-transition', agent: 42 })).toBe(false);
+  });
+
+  it('validates request-settings', () => {
+    expect(isClientMessage({ type: 'request-settings' })).toBe(true);
+    expect(isClientMessage({ type: 'request-settings', agent: 'mythos' })).toBe(true);
+    expect(isClientMessage({ type: 'request-settings', agent: 7 })).toBe(false);
+  });
+});

package/web/src/App.tsx

@@ -9,6 +9,7 @@ import { StreamPanel, formatStreamEvent, type StreamLine } from './Stream';
 import { UsagePanel } from './Usage';
 import { LessonsPanel, type LessonRow } from './Lessons';
 import { McplPanel, type McplServerRow } from './Mcpl';
+import { SettingsPanel, type SettingsState } from './Settings';
 import { FilesPanel, FileViewerModal, type Mount, type FlatEntry, type FileViewer } from './Files';
 import { ContextPanel } from './Context';
 import { ContextDocument } from './ContextDocument';
@@ -272,7 +273,7 @@ export function App() {
 
   /** Right-sidebar tab selection. The Tree is the most-used surface so it's
    *  the default; lessons / mcp / files are operator-driven panels. */
-  type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'health';
+  type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
   const [sidebarTab, setSidebarTab] = createSignal<SidebarTab>('tree');
   const [mainView, setMainView] = createSignal<'chat' | 'context'>('chat');
 
@@ -311,6 +312,16 @@ export function App() {
     wire.send({ type: 'request-mcpl' });
   };
 
+  /** Context-settings panel state. The server BROADCASTS `settings-state` after
+   *  every mutation (unlike mcpl-list, which is requester-only), because these
+   *  are live process values — two operators must not see divergent budgets. */
+  const [settingsState, setSettingsState] = createSignal<SettingsState | null>(null);
+  const [settingsLoaded, setSettingsLoaded] = createSignal(false);
+  const refreshSettings = (): void => {
+    setSettingsLoaded(false);
+    wire.send({ type: 'request-settings' });
+  };
+
   /** Workspace files panel state — mounts list + per-mount tree cache. */
   const [mounts, setMounts] = createSignal<Mount[]>([]);
   const [mountsLoaded, setMountsLoaded] = createSignal(false);
@@ -876,6 +887,10 @@ export function App() {
           setMcplConfigPath(configPath);
           setMcplServers(servers);
         },
+        setSettings: (state) => {
+          setSettingsLoaded(true);
+          setSettingsState(state);
+        },
         setMounts: (loaded, moduleLoaded, list) => {
           setMountsLoaded(loaded);
           setWorkspaceModuleLoaded(moduleLoaded);
@@ -1174,6 +1189,7 @@ export function App() {
               if (tab === 'lessons' && !lessonsLoaded()) refreshLessons();
               if (tab === 'mcp' && !mcplLoaded()) refreshMcpl();
               if (tab === 'files' && !mountsLoaded()) refreshMounts();
+              if (tab === 'settings' && !settingsLoaded()) refreshSettings();
             }}
           />
           <div class="flex-1 min-h-0">
@@ -1212,6 +1228,17 @@ export function App() {
                 onSetEnv={(id, env) => wire.send({ type: 'mcpl-set-env', id, env })}
               />
             </Show>
+            <Show when={sidebarTab() === 'settings'}>
+              <SettingsPanel
+                loaded={settingsLoaded()}
+                state={settingsState()}
+                onRefresh={refreshSettings}
+                onApply={(patch) => wire.send({ type: 'settings-update', ...patch })}
+                onReset={(keys, persist) =>
+                  wire.send({ type: 'settings-reset', ...(keys ? { keys } : {}), persist })}
+                onCancelTransition={() => wire.send({ type: 'settings-cancel-transition' })}
+              />
+            </Show>
             <Show when={sidebarTab() === 'files'}>
               <FilesPanel
                 loaded={mountsLoaded()}
@@ -1282,6 +1309,8 @@ interface HandlerHooks {
   setLessons: (loaded: boolean, moduleLoaded: boolean, lessons: LessonRow[]) => void;
   /** Apply an mcpl-list response from the server. */
   setMcpl: (configPath: string, servers: McplServerRow[]) => void;
+  /** Apply a settings-state broadcast. */
+  setSettings: (state: SettingsState) => void;
   /** Apply a workspace-mounts response. */
   setMounts: (loaded: boolean, moduleLoaded: boolean, mounts: Mount[]) => void;
   /** Apply a workspace-tree response for one mount. */
@@ -1412,6 +1441,9 @@ function handleServerMessage(
     case 'mcpl-list':
       hooks.setMcpl(msg.configPath, msg.servers);
       return;
+    case 'settings-state':
+      hooks.setSettings(msg as unknown as SettingsState);
+      return;
     case 'workspace-mounts':
       hooks.setMounts(true, msg.loaded, msg.mounts);
       return;
@@ -1942,7 +1974,7 @@ function CommandSuggestions(props: { draft: string; onPick: (cmd: string) => voi
   );
 }
 
-type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'health';
+type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
 
 function SidebarTabs(props: {
   current: SidebarTabId;
@@ -1954,6 +1986,7 @@ function SidebarTabs(props: {
     { id: 'mcp', label: 'MCP', title: 'MCPL servers' },
     { id: 'files', label: 'Files', title: 'Workspace mounts + files' },
     { id: 'context', label: 'Context', title: 'Compiled context makeup' },
+    { id: 'settings', label: 'Settings', title: 'Live context budget / tail, with preview' },
     { id: 'health', label: 'Health', title: 'Runtime settings, failures, quarantine' },
   ];
   return (