@animalabs/connectome-host 0.3.10 → 0.5.0

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

@@ -58,6 +58,7 @@ import {
   type TokenUsage,
   type CallLedgerSnapshot,
   type McplListMessage,
+  type SettingsStateMessage,
   type BranchesListMessage,
   type LessonsListMessage,
 } from '../web/protocol.js';
@@ -1076,6 +1077,9 @@ export class WebUiModule implements Module {
     if (url.pathname === '/debug/context/maintenance') {
       return this.handleContextMaintenance();
     }
+    if (url.pathname === '/debug/context/preview') {
+      return this.handleContextPreview(url);
+    }
     if (url.pathname === '/curve') {
       return new Response(CURVE_PAGE_HTML, {
         headers: { 'content-type': 'text/html; charset=utf-8' },
@@ -1181,6 +1185,79 @@ export class WebUiModule implements Module {
     return Response.json(buildContextCoverageSnapshot(agentName, cm));
   }
 
+  /**
+   * Preview the fold plan at a HYPOTHETICAL budget / tail, without applying it.
+   *
+   *   GET /debug/context/preview?budget=<tokens>[&tail=<tokens>][&agent=<name>]
+   *
+   * Commits nothing — no fold resolutions persisted, no compression enqueued,
+   * no transition bookkeeping advanced. That guarantee lives in
+   * context-manager's `previewContext` (dry-run select); this endpoint only
+   * forwards. An infeasible budget is reported as `fits: false` with the
+   * per-component diagnostics, NOT as an error: learning that a budget can't
+   * work is the reason to preview instead of applying and taking the outage.
+   *
+   * Returns 501 when the resolved context-manager predates dry-run support, so
+   * the panel can say so instead of rendering an empty result.
+   */
+  private handleContextPreview(url: URL): Response {
+    const app = sharedServer?.app;
+    if (!app) return Response.json({ error: 'app not bound yet' }, { status: 503 });
+    const agentName = url.searchParams.get('agent') || app.recipe.agent.name || 'agent';
+    const agent = app.framework.getAgent(agentName);
+    if (!agent) {
+      return Response.json({ error: `Agent not found: ${agentName}` }, { status: 404 });
+    }
+
+    const budgetRaw = url.searchParams.get('budget');
+    const budget = budgetRaw === null ? NaN : Number(budgetRaw);
+    if (!Number.isSafeInteger(budget) || budget <= 0) {
+      return Response.json({ error: 'budget must be a positive integer' }, { status: 400 });
+    }
+    const tailRaw = url.searchParams.get('tail');
+    const overrides: Record<string, unknown> = {};
+    if (tailRaw !== null) {
+      const tail = Number(tailRaw);
+      if (!Number.isSafeInteger(tail) || tail < 0) {
+        return Response.json({ error: 'tail must be a non-negative integer' }, { status: 400 });
+      }
+      // The strategy knob behind "tail" is recentWindowTokens.
+      overrides.recentWindowTokens = tail;
+    }
+
+    const fw = app.framework as unknown as {
+      previewContextSettings?: (n: string, b: number, o?: Record<string, unknown>) => unknown;
+    };
+    if (typeof fw.previewContextSettings !== 'function') {
+      return Response.json(
+        { error: 'preview unsupported: this agent-framework build has no previewContextSettings' },
+        { status: 501 },
+      );
+    }
+    try {
+      const result = fw.previewContextSettings(
+        agentName,
+        budget,
+        Object.keys(overrides).length > 0 ? overrides : undefined,
+      );
+      if (result === null || result === undefined) {
+        return Response.json(
+          {
+            error: 'preview unavailable: the resolved context-manager has no dry-run support, '
+              + 'or the active strategy has no fold plan (non-adaptive)',
+          },
+          { status: 501 },
+        );
+      }
+      return Response.json({ agent: agentName, budget, ...(overrides as object), preview: result });
+    } catch (err) {
+      return Response.json(
+        { error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+  }
+
   /**
    * Debug endpoint: return the membrane-normalized request the framework would
    * hand to the model if the agent were activated right now. Delegates to
@@ -1254,7 +1331,18 @@ export class WebUiModule implements Module {
     }
     try {
       const cm = (agent as unknown as { getContextManager: () => any }).getContextManager();
-      const maxTokens = app.recipe.agent.contextBudgetTokens ?? 200_000;
+      // Use the LIVE budget, not the recipe's. Runtime overrides persist in the
+      // `framework/state` Chronicle slot and win over the recipe, so reading
+      // app.recipe here plotted the wrong curve on any agent whose budget had
+      // ever been changed at runtime — which is every agent the settings panel
+      // touches. Fall back to the recipe only if the live read is unavailable.
+      let maxTokens = app.recipe.agent.contextBudgetTokens ?? 200_000;
+      try {
+        const live = (app.framework as unknown as {
+          getAgentRuntimeSettings?: (n: string) => { contextBudgetTokens?: number };
+        }).getAgentRuntimeSettings?.(agentName)?.contextBudgetTokens;
+        if (typeof live === 'number' && live > 0) maxTokens = live;
+      } catch { /* keep the recipe fallback */ }
       const reserveForResponse = app.recipe.agent.maxTokens ?? 16_384;
       const compiled = await cm.compile({ maxTokens, reserveForResponse });
 
@@ -1763,6 +1851,78 @@ export class WebUiModule implements Module {
         return;
       }
 
+      case 'request-settings': {
+        this.sendSettingsState(client, parsed.agent);
+        return;
+      }
+
+      // Settings mutations are live process state, so every case BROADCASTS
+      // rather than replying to the requester only (contrast sendMcplList,
+      // which is file-only). Two operators must not see divergent budgets.
+      case 'settings-update': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const patch: Record<string, number> = {};
+          if (parsed.contextBudgetTokens !== undefined) patch.contextBudgetTokens = parsed.contextBudgetTokens;
+          if (parsed.tailTokens !== undefined) patch.tailTokens = parsed.tailTokens;
+          if (parsed.transitionPaceTokens !== undefined) patch.transitionPaceTokens = parsed.transitionPaceTokens;
+          const fw = sharedServer!.app.framework as unknown as {
+            updateAgentRuntimeSettings: (n: string, p: unknown, o?: { persist?: boolean }) => unknown;
+          };
+          fw.updateAgentRuntimeSettings(agentName, patch, { persist: parsed.persist !== false });
+        } catch (err) {
+          // Expected failures land here and must reach the operator verbatim:
+          // budget ≤ max response tokens, or a strategy that cannot prepare a
+          // smaller window live. Silently swallowing them would look like the
+          // apply worked.
+          this.send(client, {
+            type: 'error',
+            message: `settings-update failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        if (parsed.notify === true) this.notifyAgentOfSettingsChange(agentName, 'update');
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
+      case 'settings-reset': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const fw = sharedServer!.app.framework as unknown as {
+            resetAgentRuntimeSettings: (n: string, k?: string[], o?: { persist?: boolean }) => unknown;
+          };
+          fw.resetAgentRuntimeSettings(agentName, parsed.keys, { persist: parsed.persist !== false });
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `settings-reset failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        if (parsed.notify === true) this.notifyAgentOfSettingsChange(agentName, 'reset');
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
+      case 'settings-cancel-transition': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const fw = sharedServer!.app.framework as unknown as {
+            cancelAgentRuntimeSettingsTransition: (n: string) => unknown;
+          };
+          fw.cancelAgentRuntimeSettingsTransition(agentName);
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `settings-cancel-transition failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
       case 'request-workspace-mounts': {
         if (parsed.scope && parsed.scope !== 'local') {
           this.routeFleetRequest(client, parsed.scope, 'workspace-mounts',
@@ -2426,6 +2586,125 @@ export class WebUiModule implements Module {
     }
   }
 
+  /** Default to the recipe's primary agent when the client omits a name. */
+  private resolveSettingsAgent(name?: string): string {
+    if (name) return name;
+    const app = sharedServer?.app;
+    return app?.recipe.agent.name ?? app?.framework.getAllAgents()[0]?.name ?? 'agent';
+  }
+
+  /**
+   * Build the settings snapshot. Never throws: this feeds a panel, and a
+   * strategy that isn't hot-configurable is a legitimate state to render
+   * read-only rather than an error to surface.
+   */
+  private buildSettingsState(agentName: string): SettingsStateMessage | null {
+    const app = sharedServer?.app;
+    if (!app) return null;
+    const fw = app.framework as unknown as {
+      getAgentRuntimeSettings?: (n: string) => Record<string, unknown>;
+      getAgent?: (n: string) => unknown;
+    };
+    if (typeof fw.getAgentRuntimeSettings !== 'function') return null;
+
+    let settings: Record<string, unknown>;
+    try {
+      settings = fw.getAgentRuntimeSettings(agentName);
+    } catch {
+      return null;
+    }
+
+    // Which knobs this build can apply live, probed rather than assumed: the
+    // hot set is a property of the ACTIVE strategy, not of the host version.
+    let hotConfigurable = false;
+    let previewAvailable = false;
+    try {
+      const agent = app.framework.getAgent(agentName);
+      const cm = agent?.getContextManager() as unknown as {
+        getHotContextSettings?: () => unknown;
+        previewContext?: unknown;
+      } | undefined;
+      hotConfigurable = !!cm && typeof cm.getHotContextSettings === 'function'
+        && cm.getHotContextSettings() !== null;
+      // Older context-manager builds resolve without previewContext. Report it
+      // so the panel says "preview unavailable on this build" instead of
+      // rendering an empty chart and looking broken.
+      previewAvailable = !!cm && typeof cm.previewContext === 'function';
+    } catch { /* leave both false — read-only panel */ }
+
+    const overrides: string[] = [];
+    try {
+      const agent = app.framework.getAgent(agentName) as unknown as {
+        getRuntimeSettingsOverrides?: () => Record<string, unknown>;
+      } | undefined;
+      const ov = agent?.getRuntimeSettingsOverrides?.() ?? {};
+      for (const [k, val] of Object.entries(ov)) if (val !== undefined) overrides.push(k);
+    } catch { /* informational only */ }
+
+    return {
+      type: 'settings-state',
+      agent: agentName,
+      settings: settings as SettingsStateMessage['settings'],
+      overrides,
+      // contextBudgetTokens is applied by the Agent itself; the other three are
+      // forwarded into the strategy's hot-settings channel, so they need a
+      // hot-configurable strategy to mean anything.
+      hotKeys: hotConfigurable
+        ? ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens', 'sameRoundThinkTextPolicy']
+        : ['contextBudgetTokens'],
+      hotConfigurable,
+      previewAvailable,
+    };
+  }
+
+  private sendSettingsState(client: ClientState, agentName?: string): void {
+    const msg = this.buildSettingsState(this.resolveSettingsAgent(agentName));
+    if (!msg) {
+      this.send(client, { type: 'error', message: 'runtime settings unavailable on this build' });
+      return;
+    }
+    this.send(client, msg);
+  }
+
+  /** Fan out to every welcomed client — settings are live process state. */
+  private broadcastSettingsState(agentName: string): void {
+    if (!sharedServer?.app) return;
+    const msg = this.buildSettingsState(agentName);
+    if (!msg) return;
+    for (const c of sharedServer.clients.values()) {
+      if (c.welcomed) this.send(c, msg);
+    }
+  }
+
+  /**
+   * Opt-in push notice to the agent that an operator changed its context
+   * settings. OFF by default at the protocol level, because this injects text
+   * into the very context being tuned: it invalidates the KV prefix and is
+   * itself classifier-visible. The zero-cost alternative the agent always has
+   * is to PULL via its `agent_settings` tool.
+   */
+  private notifyAgentOfSettingsChange(agentName: string, kind: 'update' | 'reset'): void {
+    try {
+      const app = sharedServer?.app;
+      if (!app) return;
+      const s = this.buildSettingsState(agentName);
+      const budget = s?.settings.contextBudgetTokens;
+      const tail = s?.settings.tailTokens;
+      const transition = s?.settings.transition;
+      const text = kind === 'reset'
+        ? `[operator] context settings reset to recipe defaults`
+        : `[operator] context settings changed`
+          + (budget !== undefined ? ` — budget ${budget}` : '')
+          + (tail !== undefined ? `, tail ${tail}` : '')
+          + (transition === 'converging' ? ' (converging gradually)' : '');
+      const cm = app.framework.getAgent(agentName)?.getContextManager();
+      cm?.addMessage('Context Manager', [{ type: 'text', text }], { system: true });
+    } catch (err) {
+      // A failed notice must never fail the apply that already succeeded.
+      console.warn('[settings] notify failed (change still applied):', err);
+    }
+  }
+
   private broadcastBranchChanged(): void {
     if (!sharedServer?.app) return;
     const cm = sharedServer?.app.framework.getAllAgents()[0]?.getContextManager();

package/src/recipe.ts

@@ -28,6 +28,10 @@ export interface RecipeStrategy {
   headWindowTokens?: number;
   recentWindowTokens?: number;
   compressionModel?: string;
+  /** Cap compression `max_tokens` at the compression model's OUTPUT ceiling.
+   *  Required for pre-4.x models (Claude 3 Opus caps at 4096) — without it the
+   *  summarizer's 16k floor is rejected and the agent never folds. */
+  compressionMaxTokens?: number;
   maxMessageTokens?: number;
   overBudgetGraceRatio?: number;
   // Compression/merge tuning passed through to the underlying
@@ -117,6 +121,12 @@ export interface RecipeAgent {
    * Omitted preserves the compatibility carry-forward in Agent Framework.
    */
   sameRoundThinkTextPolicy?: 'public' | 'private';
+  /**
+   * Prose delivery mode (agent-framework docs/explicit-prose-routing.md).
+   * 'explicit' = model prefixes plain text with `>>destination`; unprefixed
+   * prose bounces to a clipboard instead of auto-routing. Default 'locus'.
+   */
+  proseRouting?: 'locus' | 'explicit';
   /**
    * Extra Anthropic beta flags sent as the `anthropic-beta` header on every
    * request (e.g. `["context-1m-2025-08-07"]` for the 1M context window on
@@ -420,6 +430,18 @@ export interface RecipeModules {
    */
   webui?: boolean | RecipeWebUi;
 
+  /**
+   * Live TTS streaming tap (melodeus-tts-relay). Off by default. When set,
+   * the host mirrors the agent's streaming generation — chunks, block
+   * boundaries, activation start/end, tagged with the turn's channel — to the
+   * relay's `/bot` WebSocket, where voice clients (Melodeus / iOS) speak it.
+   * Also handles the relay's `interruption` events: the just-posted Discord
+   * message is edited down to the words actually voiced, and a note lands in
+   * the agent's context. Pure trace-bus tap — no effect on the agent loop.
+   * `token` should be `${VAR}`-substituted from .env, never literal.
+   */
+  ttsRelay?: RecipeTtsRelay;
+
   /**
    * Auto-unsubscribe noisy ambient channels. On by default. Per subscribed
    * channel, the host counts ambient (non-mention, non-DM) characters since the
@@ -428,7 +450,7 @@ export interface RecipeModules {
    * tracking what's then missed). Counters reset on every activation — the
    * agent sees all subscribed channels in context, compressed if large — and
    * persist across restarts. The agent can override the per-channel limit at
-   * runtime via the `subscription-gc--set_channel_idle_limit` tool.
+   * runtime via `agent_settings` (field `channel_idle_limits`).
    *
    * `false` disables entirely. `defaultLimitChars` sets the global default
    * (20000 if omitted). `serverId`/`toolPrefix` target the MCPL surface that
@@ -471,6 +493,25 @@ export interface RecipeWebUi {
   allowedOrigins?: string[];
 }
 
+export interface RecipeTtsRelay {
+  /** Relay bot endpoint, e.g. "ws://localhost:8800/bot". */
+  url: string;
+  /** Shared secret for the relay's /bot auth (its BOT_TOKENS). */
+  token: string;
+  /** Relay-side bot identifier. Defaults to the agent's name. */
+  botId?: string;
+  /** Discord user id stamped on stream events (client voice-config key).
+   *  Defaults to botId. */
+  userId?: string;
+  /** Display name stamped on stream events. Defaults to the agent's name. */
+  username?: string;
+  /** MCPL server id owning `edit_message` for interruption trims. Default 'discord'. */
+  editServerId?: string;
+  reconnectIntervalMs?: number;
+  /** Drop a context note when an interruption trims a posted message. Default true. */
+  notifyOnInterruption?: boolean;
+}
+
 export interface RecipeFleet {
   /** Children to manage. autoStart children launch when the framework starts. */
   children?: RecipeFleetChild[];
@@ -1110,6 +1151,22 @@ export function validateRecipe(raw: unknown): Recipe {
       }
     }
 
+    // Validate ttsRelay if present — url + token are load-bearing, and a
+    // recipe that names the module but can't reach a relay should fail at
+    // load, not silently stream nowhere.
+    if (mods.ttsRelay !== undefined && mods.ttsRelay !== false) {
+      if (typeof mods.ttsRelay !== 'object' || mods.ttsRelay === null) {
+        throw new Error('modules.ttsRelay must be an object ({ url, token, ... })');
+      }
+      const tr = mods.ttsRelay as Record<string, unknown>;
+      if (typeof tr.url !== 'string' || !/^wss?:\/\//.test(tr.url)) {
+        throw new Error('modules.ttsRelay.url must be a ws:// or wss:// URL');
+      }
+      if (typeof tr.token !== 'string' || !tr.token) {
+        throw new Error('modules.ttsRelay.token must be a non-empty string (use ${VAR} substitution)');
+      }
+    }
+
     // Validate fleet if present (object form only — boolean is trivially valid).
     if (mods.fleet && typeof mods.fleet === 'object') {
       const fleet = mods.fleet as Record<string, unknown>;