@animalabs/connectome-host 0.7.2 → 0.7.4

package/src/index.ts

@@ -37,6 +37,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { SubagentModule } from './modules/subagent-module.js';
 import { LessonsModule } from './modules/lessons-module.js';
 import { RetrievalModule } from './modules/retrieval-module.js';
+import { buildRetrievalModuleConfig } from './retrieval-config.js';
 import type { RecipeWorkspaceMount } from './recipe.js';
 import { TuiModule } from './modules/tui-module.js';
 import { TimeModule } from './modules/time-module.js';
@@ -46,6 +47,7 @@ import { SubscriptionGcModule } from './modules/subscription-gc-module.js';
 import { ChannelModeModule } from './modules/channel-mode-module.js';
 import { WebUiModule } from './modules/web-ui-module.js';
 import { ObserversModule } from './modules/observers-module.js';
+import { IdentityModule } from './modules/identity-module.js';
 import { McplAdminModule } from './modules/mcpl-admin-module.js';
 import { TtsRelayModule } from './modules/tts-relay-module.js';
 import { loadMcplServers, applyAgentOverlay, DEFAULT_CONFIG_PATH, DEFAULT_AGENT_OVERLAY_PATH } from './mcpl-config.js';
@@ -62,7 +64,7 @@ import {
   parseRecipeArg,
 } from './recipe.js';
 import { createBranchState, resetBranchState, handleExport, type BranchState } from './commands.js';
-import { buildFrameworkAgentConfig } from './framework-agent-config.js';
+import { buildFrameworkAgentConfig, membraneCachingOverride } from './framework-agent-config.js';
 import { buildFrameworkStrategy } from './framework-strategy.js';
 import { loadExtensions } from './extensions.js';
 
@@ -102,6 +104,10 @@ interface AppContext {
   branchState: BranchState;
   userMessageCount: number;
   codexAdapter?: CodexSubscriptionAdapter;
+  /** Content-free recent provider-call ledger. Consumed by the panel-data
+   *  layer (health snapshots) in BOTH runtimes — WebUI host and headless
+   *  fleet child. Null when the provider adapter exposes no ledger. */
+  callLedger: CallLedger | null;
 
   /** Stop current framework, switch to a different session, start new framework. */
   switchSession(id: string): Promise<void>;
@@ -146,6 +152,11 @@ async function resolveRecipe(): Promise<Recipe> {
 // Framework factory
 // ---------------------------------------------------------------------------
 
+function resolveModel(recipe: Recipe): string {
+  return config.model || recipe.agent.model ||
+    (recipe.agent.provider === 'openai-codex' ? 'gpt-5.4' : 'claude-opus-4-6');
+}
+
 async function createFramework(
   membrane: Membrane,
   storePath: string,
@@ -154,8 +165,7 @@ async function createFramework(
   settingsModule: SettingsModule,
   callLedger: CallLedger | null,
 ): Promise<AgentFramework> {
-  const model = config.model || recipe.agent.model ||
-    (recipe.agent.provider === 'openai-codex' ? 'gpt-5.4' : 'claude-opus-4-6');
+  const model = resolveModel(recipe);
   const modules = recipe.modules ?? {};
   const timeZone = resolveTimeZone(recipe.agent.timezone);
 
@@ -169,9 +179,10 @@ async function createFramework(
   // adapter can read its state for cross-cutting concerns like reasoning).
   const moduleInstances: Module[] = [new TuiModule(), new TimeModule(timeZone), settingsModule];
 
-  // Subagents
+  // Subagents. OPT-IN — not part of the standard recipe; enable explicitly
+  // via modules.subagents when an agent should fork parallel workers.
   let subagentModule: SubagentModule | null = null;
-  if (modules.subagents !== false) {
+  if (modules.subagents) {
     const subagentConfig = typeof modules.subagents === 'object' ? modules.subagents : {};
     subagentModule = new SubagentModule({
       parentAgentName: agentName,
@@ -181,9 +192,10 @@ async function createFramework(
     moduleInstances.push(subagentModule);
   }
 
-  // Lessons
+  // Lessons. OPT-IN — not part of the standard recipe; enable explicitly via
+  // modules.lessons for agents that curate a lesson library.
   let lessonsModule: LessonsModule | null = null;
-  if (modules.lessons !== false) {
+  if (modules.lessons) {
     const globalLessonsPath = resolve(join(storePath, '..', '..', 'lessons.json'));
     lessonsModule = new LessonsModule({ globalPath: globalLessonsPath });
     moduleInstances.push(lessonsModule);
@@ -219,14 +231,14 @@ async function createFramework(
     moduleInstances.push(new FleetModule(fleetModuleConfig));
   }
 
-  // Retrieval (requires lessons)
-  if (modules.retrieval !== false && lessonsModule) {
-    const retrievalConfig = typeof modules.retrieval === 'object' ? modules.retrieval : {};
-    moduleInstances.push(new RetrievalModule({
-      membrane,
-      retrievalModel: retrievalConfig.model,
-      maxInjectedLessons: retrievalConfig.maxInjected,
-    }));
+  // Retrieval (requires lessons). OPT-IN — not part of the standard recipe:
+  // it injects context-dependent content into every compile (plus up to two
+  // configured retrieval-model calls), which adds per-turn context churn.
+  // Enable explicitly only when an agent actually curates a lesson library.
+  if (modules.retrieval && lessonsModule) {
+    moduleInstances.push(new RetrievalModule(
+      buildRetrievalModuleConfig(membrane, modules.retrieval, recipe.agent.provider),
+    ));
   }
 
   // Gate config — core AF EventGate feature.
@@ -332,11 +344,27 @@ async function createFramework(
   // MCPL self-administration — opt-in per recipe (grants the agent the
   // ability to spawn arbitrary commands via mcpl_deploy; see recipe.ts).
   let mcplAdminModule: McplAdminModule | null = null;
-  if (modules.mcplAdmin === true) {
-    mcplAdminModule = new McplAdminModule({ timeZone });
+  if (modules.mcplAdmin === true || typeof modules.mcplAdmin === 'object') {
+    const surface = typeof modules.mcplAdmin === 'object' ? modules.mcplAdmin.surface : undefined;
+    mcplAdminModule = new McplAdminModule({ timeZone, ...(surface ? { surface } : {}) });
     moduleInstances.push(mcplAdminModule);
   }
 
+  // Archipelago identity — opt-in per recipe. Utilities-only: enrollment is
+  // one-time and token refresh is rare, so it costs no tool slots (see
+  // identity-module.ts header). Keypair lives at the dataDir level — an
+  // identity belongs to the deployment, not the session.
+  let identityModule: IdentityModule | null = null;
+  if (modules.identity !== undefined && modules.identity !== false) {
+    const idCfg = typeof modules.identity === 'object' ? modules.identity : {};
+    identityModule = new IdentityModule({
+      keyPath: process.env.IDENTITY_KEY_FILE || resolve(config.dataDir, 'identity-key.pem'),
+      home: idCfg.home ?? process.env.IDENTITY_HOME ?? 'id.animalabs.ai',
+      ...(idCfg.audience ? { defaultAudience: idCfg.audience } : {}),
+    });
+    moduleInstances.push(identityModule);
+  }
+
   // Web admin UI — opt-in per recipe
   let webUiModule: WebUiModule | null = null;
   if (modules.webui !== undefined && modules.webui !== false) {
@@ -356,7 +384,10 @@ async function createFramework(
       ...(callLedger ? { callLedger } : {}),
     });
     moduleInstances.push(webUiModule);
-    moduleInstances.push(new ObserversModule({ path: observersPath }));
+    moduleInstances.push(new ObserversModule({
+      path: observersPath,
+      ...(webuiConfig.observersSurface ? { surface: webuiConfig.observersSurface } : {}),
+    }));
   }
 
   // TTS relay tap — opt-in per recipe. Pure trace-bus consumer: mirrors the
@@ -415,6 +446,7 @@ async function createFramework(
       if (recipeEntry.url !== undefined) merged.url = recipeEntry.url;
       if (recipeEntry.transport !== undefined) merged.transport = recipeEntry.transport;
       if (recipeEntry.token !== undefined) merged.token = recipeEntry.token;
+      if (recipeEntry.access !== undefined) merged.access = recipeEntry.access;
       allServers.push(merged as { id: string; command?: string; url?: string; [k: string]: unknown });
     } else if (recipeEntry.command || recipeEntry.url) {
       // Recipe-defined server (not in the file config). Spread ALL recipe fields
@@ -426,12 +458,30 @@ async function createFramework(
   // Apply the agent overlay (mcpl-servers.agent.json): servers the agent
   // deployed for itself load unconditionally (no recipe opt-in), and
   // tombstones suppress recipe/file servers the agent unloaded.
-  const finalServers = applyAgentOverlay(allServers, DEFAULT_AGENT_OVERLAY_PATH).map((server) => ({
-    ...server,
-    // Stdio MCPL children inherit a single agent-facing wall clock. Protocol
-    // timestamps remain UTC; only their rendered text uses this setting.
-    env: { ...(server.env ?? {}), AGENT_TIMEZONE: timeZone },
-  }));
+  const finalServers = applyAgentOverlay(allServers, DEFAULT_AGENT_OVERLAY_PATH).map((server) => {
+    const withEnv: { id: string; command?: string; url?: string; [k: string]: unknown } = {
+      ...server,
+      // Stdio MCPL children inherit a single agent-facing wall clock. Protocol
+      // timestamps remain UTC; only their rendered text uses this setting.
+      env: { ...(server.env ?? {}), AGENT_TIMEZONE: timeZone },
+    };
+    // `access` is a declarative name (recipe/file/overlay); the credential
+    // provider it implies is attached HERE, at load time — fresh credential
+    // per dial via the identity module, never serialized, never in model
+    // context (see identity-module.ts header).
+    if (typeof withEnv.access === 'string' && withEnv.access) {
+      if (identityModule) {
+        const identity = identityModule;
+        const audience = withEnv.access as string;
+        withEnv.accessProvider = () => identity.accessFor(audience);
+      } else {
+        console.error(
+          `[mcpl] server "${server.id}": access "${withEnv.access}" declared but the recipe has no identity module — connecting without credentials`,
+        );
+      }
+    }
+    return withEnv;
+  });
 
   // No server augmentation needed — gate is wired via FrameworkConfig.gate
 
@@ -513,6 +563,7 @@ agents: [agentConfig],
 
   if (mcplAdminModule) {
     mcplAdminModule.setFramework(framework);
+    if (identityModule) mcplAdminModule.setIdentity(identityModule);
   }
 
   if (workspaceModule) {
@@ -827,13 +878,18 @@ async function main() {
         xTitle: recipe.agent.name ?? recipe.name,
       })
     : undefined;
-  // Bedrock: legacy Claude models (3.5 Sonnet 0620/1022, Opus 3) that have
-  // left the Anthropic API but survive on AWS. The adapter reads AWS_* env
-  // vars (AWS_REGION defaults us-west-2) and maps standard Claude model IDs
-  // to Bedrock IDs (explicit map + `anthropic.<id>-v1:0` fallback). Uses the
-  // Anthropic-native message shape, so NativeFormatter applies unchanged.
-  // No CallLedger: prompt caching is rejected outright by legacy Bedrock
-  // models (tested 2026-07-21). Wrapped for llm-calls.jsonl visibility.
+  // Bedrock: an alternate Claude transport. (Historically for models that
+  // left the direct API — as of 2026-07-31 every 3.5-era id and opus-4-0514
+  // are EOL on Bedrock too, so what actually runs here is the 4-era via
+  // inference profiles.) The adapter reads AWS_* env vars (AWS_REGION
+  // defaults us-west-2) and maps standard Claude model IDs to Bedrock IDs.
+  // Uses the Anthropic-native message shape, so NativeFormatter applies
+  // unchanged. Prompt caching is model-gated
+  // (bedrockModelSupportsPromptCaching): pre-GA families (Claude 3,
+  // 3.5 Sonnet) off, everything currently invokable caches — verified by
+  // live probe 2026-07-31. Still no CallLedger — it's
+  // anthropic-transport-only for now; cache metrics are visible in
+  // llm-calls.jsonl via the logging wrapper.
   const bedrockAdapter = provider === 'bedrock'
     ? new LoggingBedrockAdapter({}, llmLogPath)
     : undefined;
@@ -915,10 +971,13 @@ async function main() {
       : recipe.agent.formatter === 'anthropic-xml'
         ? new AnthropicXmlFormatter()
         : new NativeFormatter(),
-    // Bedrock legacy Claude models 400 on any cache_control block
-    // ("your request did not allow prompt caching") — suppress the
-    // historical promptCaching=true default on that transport.
-    ...(provider === 'bedrock' ? { defaultPromptCaching: false } : {}),
+    // Caching default for internal callers (autobio compression,
+    // executeMerge), which read Membrane's defaultPromptCaching rather
+    // than the per-agent flag. Applies on EVERY provider whenever the
+    // recipe/model resolves an explicit answer — an Anthropic recipe with
+    // promptCaching:false must disable internal calls too, and on bedrock
+    // the model gate decides (see bedrockModelSupportsPromptCaching).
+    ...membraneCachingOverride(recipe, resolveModel(recipe)),
     // Anchor the assistant role for internal callers that don't set
     // request.assistantParticipant themselves (autobio compression,
     // executeMerge). Mismatch here flips stored assistant turns to
@@ -939,6 +998,7 @@ async function main() {
     branchState: createBranchState(),
     userMessageCount: 0,
     codexAdapter,
+    callLedger,
 
     async switchSession(id: string) {
       handleExport(this);

package/src/logging-adapter.ts

@@ -32,7 +32,11 @@ import { summarizeCacheControls, type ProviderCallRecord } from './call-ledger.j
 /** Live read of the current reasoning setting. The host wires this to
  *  `SettingsModule.getReasoning()` so toggles via the `agent_settings` tool's
  *  reasoning_enabled field take effect on the next call without restart. */
-export type ReasoningGetter = () => { enabled: boolean; budgetTokens: number };
+export type ReasoningGetter = () => {
+  enabled: boolean;
+  budgetTokens: number;
+  display?: 'summarized' | 'omitted';
+};
 export type ProviderCallObserver = (record: ProviderCallRecord) => void;
 
 /** Exact first-system-block identity Anthropic requires on subscription
@@ -119,9 +123,16 @@ export class LoggingAnthropicAdapter extends AnthropicAdapter {
     // request.extra; Object.assign(params, rest)`), so we route thinking
     // through the typed `extra` bag — no type assertion, and it survives the
     // next dependency reshuffle instead of hiding it from the compiler.
+    //
+    // `display`: models 4.7+ default to 'omitted' (empty `thinking` text,
+    // signature only). We pass the setting through — default 'summarized' —
+    // so reasoning summaries are visible again (stores, webui, estimators).
     return {
       ...request,
-      extra: { ...request.extra, thinking: { type: 'adaptive' } },
+      extra: {
+        ...request.extra,
+        thinking: { type: 'adaptive', display: r.display ?? 'summarized' },
+      },
     };
   }
 

package/src/mcpl-config.ts

@@ -27,6 +27,14 @@ export interface ServerFileEntry {
   disabledTools?: string[];
   /** @deprecated One-time migration input for legacy installations. */
   channelSubscription?: 'auto' | 'manual' | string[];
+  /**
+   * Name of a network access grant (an archipelago audience, e.g.
+   * "eidoverse"). Purely declarative here: at load/deploy time the host
+   * attaches a credential provider that fetches something fresh on every
+   * dial via the identity module. The agent (and this file) never holds a
+   * credential — `access` is a name, not a secret.
+   */
+  access?: string;
 }
 
 export interface McplServersFile {

package/src/modules/fleet-module.ts

@@ -34,7 +34,7 @@ import { spawn as spawnProcess, type ChildProcess } from 'node:child_process';
 import { connect as netConnect, type Socket } from 'node:net';
 import { existsSync, mkdirSync, unlinkSync, openSync, closeSync, appendFileSync, realpathSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { type IncomingCommand, type WireEvent, matchesSubscription } from './fleet-types.js';
+import { type IncomingCommand, type WireEvent, type PanelResponseEvent, matchesSubscription } from './fleet-types.js';
 import { loadRecipe } from '../recipe.js';
 import { REDUCER_REQUIRED_EVENTS } from '../state/agent-tree-reducer.js';
 
@@ -1621,6 +1621,65 @@ export class FleetModule implements Module {
     catch { return false; }
   }
 
+  /** Monotonic corrId source for requestPanel. */
+  private panelSeq = 0;
+
+  /**
+   * Run one operator-panel op (see src/web/panel-data.ts) in a fleet child
+   * and await its `panel-response`. Promise-based counterpart to the
+   * fire-and-forget request* verbs above: HTTP proxy routes need to await a
+   * body, and the WS handlers are simpler for it too.
+   *
+   * Never rejects — a dead child, send failure, or timeout resolves as
+   * `{ok:false, error, status}` (502 unreachable, 504 timeout), so callers
+   * translate straight into a response without try/catch.
+   */
+  requestPanel(
+    childName: string,
+    op: string,
+    params?: Record<string, unknown>,
+    timeoutMs = 30_000,
+  ): Promise<{ ok: boolean; data?: unknown; error?: string; status?: number }> {
+    const child = this.children.get(childName);
+    if (!child || !child.socket) {
+      return Promise.resolve({
+        ok: false,
+        error: child ? `child '${childName}' is ${child.status}, not running` : `unknown child: ${childName}`,
+        status: child ? 502 : 404,
+      });
+    }
+    const corrId = `panel-${op}-${++this.panelSeq}-${Date.now().toString(36)}`;
+    return new Promise((resolvePanel) => {
+      let settled = false;
+      const finish = (result: { ok: boolean; data?: unknown; error?: string; status?: number }): void => {
+        if (settled) return;
+        settled = true;
+        unsub();
+        clearTimeout(timer);
+        resolvePanel(result);
+      };
+      const unsub = this.onChildEvent(childName, (_name, evt) => {
+        if (evt.type !== 'panel-response') return;
+        const e = evt as unknown as PanelResponseEvent;
+        if (e.corrId !== corrId) return;
+        finish({
+          ok: e.ok === true,
+          ...(e.data !== undefined ? { data: e.data } : {}),
+          ...(typeof e.error === 'string' ? { error: e.error } : {}),
+          ...(typeof e.status === 'number' ? { status: e.status } : {}),
+        });
+      });
+      const timer = setTimeout(() => {
+        finish({ ok: false, error: `panel op '${op}' timed out after ${timeoutMs}ms (child '${childName}' unresponsive)`, status: 504 });
+      }, timeoutMs);
+      try {
+        this.sendToChild(child, { type: 'panel-request', op, ...(params ? { params } : {}), corrId });
+      } catch (err) {
+        finish({ ok: false, error: `send to child failed: ${err instanceof Error ? err.message : String(err)}`, status: 502 });
+      }
+    });
+  }
+
   private async killChild(child: FleetChild): Promise<void> {
     if (child.status === 'exited' || child.status === 'crashed') return;
     const proc = child.process;

package/src/modules/fleet-types.ts

@@ -38,7 +38,18 @@ export type IncomingCommand =
    *  `cancel-subagent-result`. The child looks the agent up in its own
    *  SubagentModule, so this is the only way to stop a subagent that lives
    *  in a fleet child rather than the conductor. */
-  | { type: 'cancel-subagent'; name: string; corrId?: string };
+  | { type: 'cancel-subagent'; name: string; corrId?: string }
+  /**
+   * Run one operator-panel operation in the child (see PANEL_OPS in
+   * src/web/panel-data.ts: mcpl / settings(-update|-reset|-cancel-transition)
+   * / pins / pin-add / pin-remove / health / context-makeup /
+   * context-coverage / context-curve / context-preview / debug-context).
+   * Response is a single `panel-response` with the same corrId. One generic
+   * verb rather than a verb per panel: both ends dispatch through the SAME
+   * shared handler (`runPanelOp`), so a new panel surface needs no protocol
+   * change to work across the fleet.
+   */
+  | { type: 'panel-request'; op: string; params?: Record<string, unknown>; corrId?: string };
 
 // ---------------------------------------------------------------------------
 // Child → Parent: events
@@ -134,6 +145,23 @@ export interface CancelSubagentResultEvent {
   ts?: number;
 }
 
+/** Response to a {type:'panel-request'} request. `data` is the same
+ *  wire-shaped JSON the WebUI host serves locally for the given op;
+ *  `ok:false` carries the error plus an HTTP-ish `status` so the parent's
+ *  proxy routes can answer faithfully (404 unknown agent, 429 preview
+ *  cooldown, 501 unsupported build). */
+export interface PanelResponseEvent {
+  type: 'panel-response';
+  corrId?: string;
+  /** Echo of the requested op. */
+  op: string;
+  ok: boolean;
+  data?: unknown;
+  error?: string;
+  status?: number;
+  ts?: number;
+}
+
 /** Response to a {type:'request-workspace-file'} request. */
 export interface WorkspaceFileSnapshotEvent {
   type: 'workspace-file-snapshot';
@@ -163,6 +191,7 @@ export type WireEvent =
   | WorkspaceTreeSnapshotEvent
   | WorkspaceFileSnapshotEvent
   | CancelSubagentResultEvent
+  | PanelResponseEvent
   // Arbitrary framework TraceEvent passthrough. The child stamps every emitted
   // event with `ts: Date.now()` in `emit()` (see headless.ts), so ts is always
   // present on the wire even when the underlying TraceEvent doesn't declare it.