@animalabs/connectome-host 0.3.8 → 0.3.10

package/src/logging-bedrock-adapter.ts

@@ -0,0 +1,145 @@
+// BedrockAdapter wrapper that appends each LLM call's request summary, stop
+// reason, and any error to the same `llm-calls.<iso>.jsonl` file the
+// Anthropic path uses. Purpose-built during the Aria bring-up (2026-07-21)
+// when a 0-token assistant turn proved undiagnosable: the bedrock transport
+// had no wire visibility at all.
+//
+// Kept deliberately lighter than LoggingAnthropicAdapter: request summaries
+// always include tool NAMES (were tools attached at all? — the question that
+// motivated this file), message/system sizes, and the stop sequences; the
+// full raw request is retained only on errors. Responses log stop_reason,
+// usage, and content-block shape (type + size per block) on every call.
+//
+// Each line: { type: 'call'|'error', kind: 'complete'|'stream', timestamp,
+//   durationMs, requestSummary, response?, rawRequest?, error? }
+
+import { BedrockAdapter } from '@animalabs/membrane';
+import type {
+  ProviderRequest,
+  ProviderResponse,
+  ProviderRequestOptions,
+  StreamCallbacks,
+} from '@animalabs/membrane';
+import { appendFileSync } from 'node:fs';
+
+type BedrockConfig = ConstructorParameters<typeof BedrockAdapter>[0];
+
+function summarizeRequest(request: ProviderRequest): Record<string, unknown> {
+  const msgs = (request.messages ?? []) as Array<{ role?: string; content?: unknown }>;
+  const last = msgs[msgs.length - 1];
+  const lastPreview = typeof last?.content === 'string'
+    ? last.content.slice(0, 200)
+    : Array.isArray(last?.content)
+      ? (last.content as Array<{ type?: string; text?: string }>)
+          .map((b) => (b.type === 'text' ? (b.text ?? '').slice(0, 120) : `[${b.type}]`))
+          .join(' | ').slice(0, 300)
+      : undefined;
+  return {
+    model: request.model,
+    maxTokens: request.maxTokens,
+    messageCount: msgs.length,
+    systemChars: typeof request.system === 'string'
+      ? request.system.length
+      : Array.isArray(request.system)
+        ? JSON.stringify(request.system).length
+        : 0,
+    toolNames: (request.tools as Array<{ name?: string }> | undefined)?.map((t) => t.name) ?? null,
+    toolCount: (request.tools as unknown[] | undefined)?.length ?? 0,
+    stopSequences: request.stopSequences ?? null,
+    lastMessageRole: last?.role,
+    lastMessagePreview: lastPreview,
+  };
+}
+
+function summarizeResponse(response: ProviderResponse): Record<string, unknown> {
+  const content = (response.content ?? []) as Array<{ type?: string; text?: string; name?: string }>;
+  return {
+    stopReason: response.stopReason ?? (response.raw as { stop_reason?: string } | undefined)?.stop_reason ?? null,
+    usage: response.usage ?? null,
+    blocks: content.map((b) => ({
+      type: b.type,
+      ...(b.type === 'text' ? { chars: (b.text ?? '').length } : {}),
+      ...(b.type === 'tool_use' ? { name: b.name } : {}),
+    })),
+  };
+}
+
+export class LoggingBedrockAdapter extends BedrockAdapter {
+  private readonly logPath: string;
+
+  constructor(config: BedrockConfig, logPath: string) {
+    super(config);
+    this.logPath = logPath;
+  }
+
+  private log(record: Record<string, unknown>): void {
+    try {
+      appendFileSync(this.logPath, JSON.stringify(record) + '\n');
+    } catch {
+      // Logging must never break inference.
+    }
+  }
+
+  override async complete(
+    request: ProviderRequest,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    let rawRequest: unknown;
+    const opts: ProviderRequestOptions = {
+      ...options,
+      onRequest: (req) => { rawRequest = req; options?.onRequest?.(req); },
+    };
+    try {
+      const response = await super.complete(request, opts);
+      this.log({
+        type: 'call', kind: 'complete', timestamp: new Date(started).toISOString(),
+        durationMs: Date.now() - started,
+        requestSummary: summarizeRequest(request),
+        response: summarizeResponse(response),
+      });
+      return response;
+    } catch (error) {
+      this.log({
+        type: 'error', kind: 'complete', timestamp: new Date(started).toISOString(),
+        durationMs: Date.now() - started,
+        requestSummary: summarizeRequest(request),
+        rawRequest,
+        error: error instanceof Error ? { message: error.message, name: error.name } : String(error),
+      });
+      throw error;
+    }
+  }
+
+  override async stream(
+    request: ProviderRequest,
+    callbacks: StreamCallbacks,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    let rawRequest: unknown;
+    const opts: ProviderRequestOptions = {
+      ...options,
+      onRequest: (req) => { rawRequest = req; options?.onRequest?.(req); },
+    };
+    try {
+      const response = await super.stream(request, callbacks, opts);
+      this.log({
+        type: 'call', kind: 'stream', timestamp: new Date(started).toISOString(),
+        durationMs: Date.now() - started,
+        requestSummary: summarizeRequest(request),
+        response: summarizeResponse(response),
+      });
+      return response;
+    } catch (error) {
+      this.log({
+        type: 'error', kind: 'stream', timestamp: new Date(started).toISOString(),
+        durationMs: Date.now() - started,
+        requestSummary: summarizeRequest(request),
+        rawRequest,
+        error: error instanceof Error ? { message: error.message, name: error.name } : String(error),
+      });
+      throw error;
+    }
+  }
+}

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

@@ -16,7 +16,8 @@
  * fan-out across many VMs are the reverse-proxy's job; an optional Basic-Auth
  * check is available as defense-in-depth.
  *
- * See WEBUI-PLAN.md and src/web/protocol.ts for the wire shape.
+ * See src/web/protocol.ts for the wire shape and docs/webui-deployment.md
+ * for the deployment story.
  */
 
 import { CURVE_PAGE_HTML } from './web-ui-curve-page.js';
@@ -57,6 +58,7 @@ import {
   type TokenUsage,
   type CallLedgerSnapshot,
   type McplListMessage,
+  type BranchesListMessage,
   type LessonsListMessage,
 } from '../web/protocol.js';
 import {
@@ -1547,6 +1549,9 @@ export class WebUiModule implements Module {
     if (client.auth !== 'observer') return false;
     if (type === 'ping') return true;
     if (type === 'request-history') return client.scopes?.has('messages') ?? false;
+    // Branch listing is conversation-shape metadata (names, fork points) —
+    // same sensitivity tier as the message window, so same scope.
+    if (type === 'request-branches') return client.scopes?.has('messages') ?? false;
     return false; // observers are read-only: no user-message/command/mcpl/fleet
   }
 
@@ -1698,6 +1703,11 @@ export class WebUiModule implements Module {
         return;
       }
 
+      case 'request-branches': {
+        this.sendBranchesList(client);
+        return;
+      }
+
       case 'mcpl-add': {
         try {
           const servers = readMcplServersFile(DEFAULT_CONFIG_PATH);
@@ -1983,6 +1993,40 @@ export class WebUiModule implements Module {
     this.send(client, out);
   }
 
+  /** Build a BranchesListMessage from the agent's context manager. Lineage
+   *  (parentId + branchPoint) comes straight from Chronicle's branch records;
+   *  the SPA folds it into a tree. */
+  private sendBranchesList(client: ClientState): void {
+    if (!sharedServer?.app) return;
+    const cm = sharedServer.app.framework.getAllAgents()[0]?.getContextManager();
+    if (!cm) {
+      this.send(client, { type: 'error', message: 'no agent context manager' });
+      return;
+    }
+    try {
+      const branches = cm.listBranches();
+      const current = cm.currentBranch();
+      const out: BranchesListMessage = {
+        type: 'branches-list',
+        branches: branches.map((b) => ({
+          id: b.id,
+          name: b.name,
+          head: b.head,
+          ...(b.parentId !== undefined ? { parentId: b.parentId } : {}),
+          ...(b.branchPoint !== undefined ? { branchPoint: b.branchPoint } : {}),
+          created: b.created instanceof Date ? b.created.getTime() : Number(b.created),
+        })),
+        currentId: current.id,
+      };
+      this.send(client, out);
+    } catch (err) {
+      this.send(client, {
+        type: 'error',
+        message: `branch listing failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
   /** Build a LessonsListMessage from the bound LessonsModule, if present. */
   private sendLessonsList(client: ClientState): void {
     if (!sharedServer?.app) return;

package/src/recipe.ts

@@ -19,7 +19,11 @@ import { dirname, isAbsolute, resolve } from 'node:path';
 // ---------------------------------------------------------------------------
 
 export interface RecipeStrategy {
-  type: 'autobiographical' | 'passthrough' | 'frontdesk';
+  /** Built-in strategy name, or a custom type registered by a
+   *  `kind: "strategy"` extension (see `Recipe.extensions`). The
+   *  `string & {}` arm keeps literal autocompletion while admitting
+   *  extension-registered names. */
+  type: 'autobiographical' | 'passthrough' | 'frontdesk' | (string & {});
   // Core window/compression sizing
   headWindowTokens?: number;
   recentWindowTokens?: number;
@@ -85,7 +89,15 @@ export interface RecipeAgent {
   /** IANA zone used when rendering wall-clock times to the agent. */
   timezone?: string;
   /** Provider transport. Omitted preserves the historical Anthropic default. */
-  provider?: 'anthropic' | 'openai-responses';
+  provider?: 'anthropic' | 'openai-responses' | 'openai-codex' | 'openrouter' | 'bedrock';
+  /** Message formatter. 'native' (default) = structured user/assistant turns.
+   * 'anthropic-xml' = classic prefill format ("participant: text" runs, XML
+   * tools) — for migrating prefill-era bots (chapterx borgs) with their exact
+   * prompting structure intact. */
+  formatter?: 'native' | 'anthropic-xml';
+  /** Prefill scaffold user message appended after the conversation (e.g.
+   * chapterx CLI-sim's "<cmd>cat untitled.txt</cmd>"). Prefill formatter only. */
+  prefillUserMessage?: string;
   systemPrompt: string;
   maxTokens?: number;
   /**
@@ -105,6 +117,13 @@ export interface RecipeAgent {
    * Omitted preserves the compatibility carry-forward in Agent Framework.
    */
   sameRoundThinkTextPolicy?: 'public' | 'private';
+  /**
+   * 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
+   * models where it is opt-in, like claude-sonnet-4-5). Merged with any
+   * transport-required betas (OAuth). Anthropic provider only.
+   */
+  anthropicBetas?: string[];
   strategy?: RecipeStrategy;
   /**
    * Native extended thinking. When `enabled: true`, the agent's API requests
@@ -115,13 +134,20 @@ export interface RecipeAgent {
     enabled: boolean;
     budgetTokens?: number;
   };
-  /** Stateless OpenAI Responses settings. Only used with
-   * `provider: "openai-responses"`. */
+  /** OpenAI Responses settings. Reasoning applies to both OpenAI providers;
+   * compaction and serviceTier are API-key transport settings. */
   responses?: {
     reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
     reasoningContext?: 'current_turn' | 'all_turns';
-    serviceTier?: string;
     compactThreshold?: number;
+    /** OpenAI Responses API processing tier. `priority` is the API-key
+     * equivalent of Codex fast mode. */
+    serviceTier?: 'auto' | 'default' | 'flex' | 'priority';
+  };
+  /** ChatGPT-subscription Codex settings. Only used with
+   * `provider: "openai-codex"`. Runtime `/fast` overrides fastMode. */
+  codex?: {
+    fastMode?: boolean;
   };
   /**
    * Content-refusal handling. When `autoRewind` is on, a `stop_reason: refusal`
@@ -132,11 +158,6 @@ export interface RecipeAgent {
     autoRewind?: boolean;
     maxRewinds?: number;
     announceHumanTurns?: boolean;
-    primarySummaryFallback?: {
-      enabled?: boolean;
-      maxNewSummaries?: number;
-      requestBudgetTokens?: number;
-    };
   };
 }
 
@@ -508,6 +529,31 @@ export interface RecipeFleetChild {
   autoRestart?: boolean;
 }
 
+/**
+ * A deployment-specific code extension: a local TS/JS module that registers
+ * custom context strategies and/or framework modules at boot. See
+ * src/extensions.ts for the loader and the `register(api, config)` contract.
+ */
+export interface RecipeExtension {
+  /** Primary purpose. Gates validation (a non-built-in `agent.strategy.type`
+   *  requires at least one `kind: "strategy"` extension) and informs build
+   *  tooling; does not restrict what `register` may call. */
+  kind: 'strategy' | 'module';
+  /** Path to the extension entry module. Relative paths resolve against the
+   *  recipe file's directory at load time; URL-loaded recipes must use
+   *  absolute paths (the host never imports code over the network). */
+  path: string;
+  /** Opaque blob passed verbatim to the extension's `register` function and
+   *  to module factory contexts. */
+  config?: Record<string, unknown>;
+  /** Build-tooling acquisition metadata (git url/ref/install pattern) —
+   *  consumed by connectome-cook at build time, ignored at runtime. */
+  source?: Record<string, unknown>;
+  /** Build-only provenance: `source` demoted by build tooling into the
+   *  shipped recipe. Ignored at runtime. */
+  sourceMeta?: Record<string, unknown>;
+}
+
 export interface Recipe {
   name: string;
   description?: string;
@@ -515,6 +561,8 @@ export interface Recipe {
   agent: RecipeAgent;
   mcpServers?: Record<string, RecipeMcpServer>;
   modules?: RecipeModules;
+  /** Deployment-specific code extensions, keyed by a human-readable name. */
+  extensions?: Record<string, RecipeExtension>;
   sessionNaming?: { examples?: string[] };
 }
 
@@ -644,6 +692,7 @@ export async function loadRecipe(source: string): Promise<Recipe> {
   raw = substituteEnvVars(raw, source);
   const recipe = validateRecipe(raw);
   resolveChildRecipePaths(recipe, sourceBase);
+  resolveExtensionPaths(recipe, sourceBase);
   return resolveSystemPrompt(recipe);
 }
 
@@ -668,6 +717,25 @@ function resolveChildRecipePaths(recipe: Recipe, base: RecipeSourceBase): void {
   }
 }
 
+/**
+ * Resolve relative `extensions[].path` values against the recipe file's
+ * directory. URL-loaded recipes cannot carry relative extension paths — the
+ * host never fetches code over the network, so there is nothing local to
+ * resolve them against.
+ */
+function resolveExtensionPaths(recipe: Recipe, base: RecipeSourceBase): void {
+  for (const [name, ext] of Object.entries(recipe.extensions ?? {})) {
+    if (isAbsolute(ext.path)) continue;
+    if (base.kind === 'url') {
+      throw new Error(
+        `extensions.${name}.path "${ext.path}" is relative, but the recipe was loaded from a URL. ` +
+        `Extension code is never fetched remotely — use an absolute path to a local install.`,
+      );
+    }
+    ext.path = resolve(base.dir, ext.path);
+  }
+}
+
 /**
  * If systemPrompt is an HTTP(S) URL, fetch its contents as plain text.
  * Only treated as a URL if it looks like a single URL (no spaces/newlines).
@@ -706,8 +774,16 @@ export function validateRecipe(raw: unknown): Recipe {
     throw new Error('Recipe agent must have a "systemPrompt" string');
   }
 
-  if (agent.provider !== undefined && agent.provider !== 'anthropic' && agent.provider !== 'openai-responses') {
-    throw new Error(`Recipe agent.provider must be 'anthropic' or 'openai-responses', got ${JSON.stringify(agent.provider)}.`);
+  if (agent.provider !== undefined &&
+      agent.provider !== 'anthropic' &&
+      agent.provider !== 'openai-responses' &&
+      agent.provider !== 'openai-codex' &&
+      agent.provider !== 'openrouter' &&
+      agent.provider !== 'bedrock') {
+    throw new Error(
+      `Recipe agent.provider must be 'anthropic', 'openai-responses', 'openai-codex', 'openrouter', or 'bedrock', ` +
+      `got ${JSON.stringify(agent.provider)}.`,
+    );
   }
 
   if (agent.timezone !== undefined) {
@@ -740,6 +816,20 @@ export function validateRecipe(raw: unknown): Recipe {
         (typeof responses.compactThreshold !== 'number' || responses.compactThreshold <= 0)) {
       throw new Error('Recipe agent.responses.compactThreshold must be a positive number.');
     }
+    const serviceTiers = ['auto', 'default', 'flex', 'priority'];
+    if (responses.serviceTier !== undefined && !serviceTiers.includes(String(responses.serviceTier))) {
+      throw new Error(`Invalid agent.responses.serviceTier ${JSON.stringify(responses.serviceTier)}.`);
+    }
+  }
+
+  if (agent.codex !== undefined) {
+    if (!agent.codex || typeof agent.codex !== 'object' || Array.isArray(agent.codex)) {
+      throw new Error('Recipe agent.codex must be an object.');
+    }
+    const codex = agent.codex as Record<string, unknown>;
+    if (codex.fastMode !== undefined && typeof codex.fastMode !== 'boolean') {
+      throw new Error('Recipe agent.codex.fastMode must be a boolean.');
+    }
   }
 
   if (agent.maxStreamTokens !== undefined && (typeof agent.maxStreamTokens !== 'number' || agent.maxStreamTokens <= 0)) {
@@ -787,6 +877,37 @@ export function validateRecipe(raw: unknown): Recipe {
     }
   }
 
+  // Validate the extensions block if present (before the strategy check,
+  // which consults it to admit custom strategy types).
+  let hasStrategyExtension = false;
+  if (obj.extensions !== undefined) {
+    if (!obj.extensions || typeof obj.extensions !== 'object' || Array.isArray(obj.extensions)) {
+      throw new Error('Recipe "extensions" must be an object mapping names to extension entries.');
+    }
+    for (const [name, entry] of Object.entries(obj.extensions as Record<string, unknown>)) {
+      if (!name) throw new Error('Recipe extensions keys must be non-empty names.');
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        throw new Error(`extensions.${name} must be an object.`);
+      }
+      const ext = entry as Record<string, unknown>;
+      if (ext.kind !== 'strategy' && ext.kind !== 'module') {
+        throw new Error(`extensions.${name}.kind must be "strategy" or "module", got ${JSON.stringify(ext.kind)}.`);
+      }
+      if (typeof ext.path !== 'string' || !ext.path) {
+        throw new Error(`extensions.${name}.path must be a non-empty string.`);
+      }
+      if (ext.config !== undefined && (!ext.config || typeof ext.config !== 'object' || Array.isArray(ext.config))) {
+        throw new Error(`extensions.${name}.config must be an object.`);
+      }
+      for (const metaKey of ['source', 'sourceMeta'] as const) {
+        if (ext[metaKey] !== undefined && (!ext[metaKey] || typeof ext[metaKey] !== 'object' || Array.isArray(ext[metaKey]))) {
+          throw new Error(`extensions.${name}.${metaKey} must be an object.`);
+        }
+      }
+      if (ext.kind === 'strategy') hasStrategyExtension = true;
+    }
+  }
+
   // Validate strategy type if present
   if (agent.strategy) {
     const strategy = agent.strategy as Record<string, unknown>;
@@ -794,10 +915,13 @@ export function validateRecipe(raw: unknown): Recipe {
       strategy.type &&
       strategy.type !== 'autobiographical' &&
       strategy.type !== 'passthrough' &&
-      strategy.type !== 'frontdesk'
+      strategy.type !== 'frontdesk' &&
+      !hasStrategyExtension
     ) {
       throw new Error(
-        `Invalid strategy type "${strategy.type}". Must be "autobiographical", "passthrough", or "frontdesk".`,
+        `Invalid strategy type "${strategy.type}". Must be "autobiographical", "passthrough", ` +
+        `or "frontdesk" — or a custom type registered by a "kind": "strategy" entry in the ` +
+        `recipe's "extensions" block (none is declared).`,
       );
     }
     if (
@@ -823,35 +947,8 @@ export function validateRecipe(raw: unknown): Recipe {
   }
 
   const refusalHandling = agent.refusalHandling as Record<string, unknown> | undefined;
-  const primarySummaryFallback = refusalHandling?.primarySummaryFallback;
-  if (primarySummaryFallback !== undefined) {
-    if (!primarySummaryFallback || typeof primarySummaryFallback !== 'object' || Array.isArray(primarySummaryFallback)) {
-      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback must be an object.');
-    }
-    const fallback = primarySummaryFallback as Record<string, unknown>;
-    if (fallback.enabled !== undefined && typeof fallback.enabled !== 'boolean') {
-      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.enabled must be a boolean.');
-    }
-    if (
-      fallback.maxNewSummaries !== undefined &&
-      (
-        typeof fallback.maxNewSummaries !== 'number' ||
-        !Number.isSafeInteger(fallback.maxNewSummaries) ||
-        fallback.maxNewSummaries < 0
-      )
-    ) {
-      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.maxNewSummaries must be a non-negative safe integer.');
-    }
-    if (
-      fallback.requestBudgetTokens !== undefined &&
-      (
-        typeof fallback.requestBudgetTokens !== 'number' ||
-        !Number.isSafeInteger(fallback.requestBudgetTokens) ||
-        fallback.requestBudgetTokens <= 0
-      )
-    ) {
-      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.requestBudgetTokens must be a positive safe integer.');
-    }
+  if (refusalHandling && Object.hasOwn(refusalHandling, 'primarySummaryFallback')) {
+    throw new Error('Recipe agent.refusalHandling.primarySummaryFallback was removed and is unsupported.');
   }
 
   // Validate mcpServers entries if present