@animalabs/connectome-host 0.3.9 → 0.4.0

package/src/commands.ts

@@ -14,6 +14,7 @@
  *   /clear         — Clear conversation display
  *   /mcp list|add|remove|env — Manage MCPL server config
  *   /budget [N]    — Show/set stream token budget (e.g. /budget 1m)
+ *   /fast [on|off|status] — Toggle Codex subscription Fast mode
  *   /session       — Session management (list, new, switch, rename, delete)
  *   /recipe        — Show current recipe info
  *   /newtopic      — Reset head window (auto-summarize or with user context)
@@ -37,6 +38,10 @@ interface AppContext {
   sessionManager: import('./session-manager.js').SessionManager;
   recipe: Recipe;
   branchState: BranchState;
+  codexAdapter?: {
+    isFastMode(): boolean;
+    setFastMode(enabled: boolean): void;
+  };
   switchSession(id: string): Promise<void>;
 }
 
@@ -146,12 +151,15 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
           { text: '  /restore <name>        Restore to checkpoint', style: 'system' },
           { text: '  /branches              List Chronicle branches', style: 'system' },
           { text: '  /checkout <name>       Switch to branch', style: 'system' },
-          { text: '  /history               Show state transitions', style: 'system' },
+          { text: '  /history [n]           Show state transitions (last n)', style: 'system' },
+          { text: '  /find <text>           Search messages for text', style: 'system' },
+          { text: '  /branchto <msgId>      Branch from a specific message', style: 'system' },
           { text: '  /mcp list              List MCPL servers', style: 'system' },
           { text: '  /mcp add <id> <cmd>    Add/overwrite server', style: 'system' },
           { text: '  /mcp remove <id>       Remove a server', style: 'system' },
           { text: '  /mcp env <id> K=V ...  Set env vars on server', style: 'system' },
           { text: '  /budget [tokens]       Show/set stream token budget', style: 'system' },
+          { text: '  /fast [on|off|status]  Toggle Codex subscription Fast mode', style: 'system' },
           { text: '  /session               Show current session', style: 'system' },
           { text: '  /session list          List all sessions', style: 'system' },
           { text: '  /session new [name]    Create new session', style: 'system' },
@@ -211,6 +219,9 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
     case 'budget':
       return handleBudget(framework, args[0]);
 
+    case 'fast':
+      return handleFast(app, args[0]);
+
     case 'session':
       return handleSession(app, args);
 
@@ -233,6 +244,42 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
   }
 }
 
+function handleFast(app: AppContext, mode?: string): CommandResult {
+  const adapter = app.codexAdapter;
+  if (!adapter) {
+    return {
+      lines: [{
+        text: '/fast is available only when agent.provider is "openai-codex".',
+        style: 'system',
+      }],
+    };
+  }
+
+  const normalized = mode?.toLowerCase();
+  if (normalized === undefined || normalized === 'status') {
+    return {
+      lines: [{
+        text: `Codex Fast mode request is ${adapter.isFastMode() ? 'ON' : 'OFF'}.`,
+        style: 'system',
+      }],
+    };
+  }
+  if (normalized !== 'on' && normalized !== 'off') {
+    return { lines: [{ text: 'Usage: /fast [on|off|status]', style: 'system' }] };
+  }
+
+  const enabled = normalized === 'on';
+  adapter.setFastMode(enabled);
+  return {
+    lines: [{
+      text: enabled
+        ? 'Codex Fast mode requested (higher subscription credit consumption when applied).'
+        : 'Codex Fast mode request disabled.',
+      style: 'system',
+    }],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // /session subcommands
 // ---------------------------------------------------------------------------
@@ -702,7 +749,13 @@ function handleCheckpoint(app: AppContext, name?: string): CommandResult {
   if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
 
   const branch = cm.currentBranch();
-  app.branchState.checkpoints.set(name, { branchName: branch.name });
+  // A checkpoint is a *position*, not just a branch: record the id of the
+  // last message so /restore can branch back to this exact point even after
+  // the branch head has moved on. branchName alone would restore to the
+  // branch HEAD — i.e. not roll anything back.
+  const { messages } = cm.queryMessages({});
+  const messageId = messages.length > 0 ? messages[messages.length - 1]!.id : undefined;
+  app.branchState.checkpoints.set(name, { branchName: branch.name, messageId });
 
   return { lines: [{ text: `Checkpoint "${name}" saved at branch ${branch.name} (head: ${branch.head}).`, style: 'system' }] };
 }
@@ -729,12 +782,50 @@ function handleRestore(app: AppContext, name?: string): CommandResult {
   const cm = getAgentCM(app.framework);
   if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
 
-  const target = point.branchName;
+  // Restore to the recorded *position*. If the checkpoint captured a message
+  // id, branch at that message (same machinery as /undo) — switching to the
+  // stored branch name alone would land on its head, which by now may
+  // include everything the user wanted to roll back. Checkpoints from before
+  // the messageId field (or taken on an empty branch) fall back to the head.
+  let target = point.branchName;
+  let exact = false;
+  if (point.messageId) {
+    // A checkpoint is a POSITION, so position equality is the whole
+    // "already there" test. Comparing branch names too would kill the guard
+    // after the first restore (you'd be on restore-{name}-{ts}, never the
+    // original branch again) and every repeat /restore would mint another
+    // branch pointing at the same message.
+    const { messages } = cm.queryMessages({});
+    const atCheckpoint = messages.length > 0
+      && messages[messages.length - 1]!.id === point.messageId;
+    if (atCheckpoint) {
+      return { lines: [{ text: `Already at checkpoint "${name}".`, style: 'system' }] };
+    }
+    try {
+      // branchAt returns the new branch's NAME (the only thing switchBranch accepts).
+      target = cm.branchAt(point.messageId, `restore-${name}-${Date.now()}`);
+      exact = true;
+      // The record follows the position: keep the newest branch that holds
+      // the checkpoint message as the fallback for future restores.
+      app.branchState.checkpoints.set(name, { branchName: target, messageId: point.messageId });
+    } catch {
+      // branchAt resolves ids against the CURRENT branch's view of the log;
+      // after e.g. /undo the checkpoint message may not be reachable from
+      // here. Degrade to the checkpoint's branch head (the pre-messageId
+      // behavior) rather than failing the restore outright.
+      target = point.branchName;
+    }
+  }
 
   // switchBranch is async — strategy reinit needs to complete before next op.
   const asyncWork = Promise.resolve(cm.switchBranch(target))
     .then(() => ({
-      lines: [{ text: `Restored to checkpoint "${name}" (branch: ${target}).`, style: 'system' as const }],
+      lines: [
+        { text: `Restored to checkpoint "${name}" (branch: ${target}).`, style: 'system' as const },
+        ...(point.messageId && !exact
+          ? [{ text: '  (note: exact checkpoint position unreachable from the current branch — restored to the branch head instead)', style: 'system' as const }]
+          : []),
+      ],
       branchChanged: true,
     }))
     .catch(err => ({

package/src/extensions.ts

@@ -0,0 +1,201 @@
+/**
+ * Recipe extensions — the loading seam for deployment-specific code.
+ *
+ * A recipe may declare an `extensions` block mapping a name to a local
+ * TypeScript/JavaScript module that registers custom context strategies
+ * and/or framework modules:
+ *
+ *   "extensions": {
+ *     "zk-strategy": {
+ *       "kind": "strategy",
+ *       "path": "./extensions/zk-strategy/index.ts",
+ *       "config": { "floodWindowMs": 250 }
+ *     }
+ *   }
+ *
+ * The entry module must export a `register` function (named or default):
+ *
+ *   export function register(api: ExtensionApi, config: Record<string, unknown>) {
+ *     api.registerStrategy('zk', (ctx) => new ZkStrategy({ ...ctx.config }));
+ *     api.registerModule((ctx) => new ZkFeederModule(config));
+ *   }
+ *
+ * Design constraint: this loader is deliberately dumb. It resolves nothing,
+ * fetches nothing, and negotiates no versions — it imports a local path and
+ * calls `register`. The invariant "this path exists and is compatible with
+ * the host's dependency tree" is established at install time by build
+ * tooling (connectome-cook), not here. Extensions run in-process and share
+ * the host's node_modules, so `extends AutobiographicalStrategy` resolves
+ * against the exact @animalabs/* versions the host ships.
+ *
+ * `kind` declares the extension's primary purpose. It gates recipe
+ * validation (a non-built-in `agent.strategy.type` is only accepted when at
+ * least one `kind: "strategy"` extension is declared) and informs build
+ * tooling; it does NOT restrict what `register` may call — a strategy
+ * extension may also register a companion module.
+ */
+
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ContextStrategy, Module } from '@animalabs/agent-framework';
+import type { Recipe, RecipeExtension, RecipeStrategy } from './recipe.js';
+
+// ---------------------------------------------------------------------------
+// Factory contexts
+// ---------------------------------------------------------------------------
+
+export interface StrategyFactoryContext {
+  /** The recipe's `agent.strategy` block verbatim — including keys the
+   *  built-in schema doesn't know about, so custom strategies can define
+   *  their own knobs without upstream schema changes. */
+  config: RecipeStrategy & Record<string, unknown>;
+  /** Resolved agent model id (recipe/env fallback chain already applied). */
+  model: string;
+  /** Resolved IANA time zone for the session. */
+  timeZone: string;
+}
+
+export type StrategyFactory = (ctx: StrategyFactoryContext) => ContextStrategy;
+
+export interface ModuleFactoryContext {
+  timeZone: string;
+  /** Session store path (Chronicle data dir) — same value createFramework uses. */
+  storePath: string;
+  /** Resolved agent model id. */
+  model: string;
+  /** The declaring extension entry's `config` blob, verbatim. */
+  config: Record<string, unknown>;
+}
+
+export type ModuleFactory = (ctx: ModuleFactoryContext) => Module;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export interface ExtensionApi {
+  /** Register a context-strategy factory under a `agent.strategy.type` name.
+   *  Built-in names and duplicate registrations are rejected. */
+  registerStrategy(type: string, factory: StrategyFactory): void;
+  /** Register a framework-module factory. Instantiated after the built-in
+   *  module list is assembled; if the instance has a `setFramework` method
+   *  it is called after framework creation (same duck-typed contract the
+   *  built-in modules use). */
+  registerModule(factory: ModuleFactory): void;
+}
+
+export interface RegisteredModule {
+  /** Name of the extension entry that registered this factory. */
+  extensionName: string;
+  factory: ModuleFactory;
+  /** The extension entry's `config`, passed to the factory context. */
+  config: Record<string, unknown>;
+}
+
+export interface ExtensionRegistry {
+  strategies: Map<string, StrategyFactory>;
+  modules: RegisteredModule[];
+}
+
+export const BUILTIN_STRATEGY_TYPES = ['autobiographical', 'passthrough', 'frontdesk'] as const;
+
+export function isBuiltinStrategyType(type: string): boolean {
+  return (BUILTIN_STRATEGY_TYPES as readonly string[]).includes(type);
+}
+
+/** An empty registry — used when a recipe declares no extensions. */
+export function emptyExtensionRegistry(): ExtensionRegistry {
+  return { strategies: new Map(), modules: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Import every extension declared by the recipe and collect registrations.
+ *
+ * Paths must be absolute by the time this runs — `loadRecipe` resolves
+ * relative extension paths against the recipe file's directory. Errors are
+ * wrapped with the extension name + path so a broken deployment names the
+ * component instead of surfacing a bare import stack.
+ */
+export async function loadExtensions(recipe: Recipe): Promise<ExtensionRegistry> {
+  const registry = emptyExtensionRegistry();
+  for (const [name, ext] of Object.entries(recipe.extensions ?? {})) {
+    await loadOneExtension(name, ext, registry);
+  }
+  return registry;
+}
+
+async function loadOneExtension(
+  name: string,
+  ext: RecipeExtension,
+  registry: ExtensionRegistry,
+): Promise<void> {
+  if (!isAbsolute(ext.path)) {
+    throw new Error(
+      `extension "${name}": path "${ext.path}" is not absolute. ` +
+      `Relative paths are resolved by loadRecipe against the recipe file's directory; ` +
+      `URL-loaded recipes must use absolute extension paths.`,
+    );
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(pathToFileURL(ext.path).href) as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(
+      `extension "${name}": failed to import ${ext.path}: ` +
+      `${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+
+  const register = (mod.register ?? mod.default) as unknown;
+  if (typeof register !== 'function') {
+    throw new Error(
+      `extension "${name}" (${ext.path}) must export a "register" function ` +
+      `(named export or default export); got ${typeof register}.`,
+    );
+  }
+
+  const config = ext.config ?? {};
+  const api: ExtensionApi = {
+    registerStrategy(type, factory) {
+      if (typeof type !== 'string' || !type) {
+        throw new Error(`extension "${name}": registerStrategy requires a non-empty type name`);
+      }
+      if (isBuiltinStrategyType(type)) {
+        throw new Error(
+          `extension "${name}": strategy type "${type}" collides with a built-in strategy`,
+        );
+      }
+      if (registry.strategies.has(type)) {
+        throw new Error(
+          `extension "${name}": strategy type "${type}" is already registered by another extension`,
+        );
+      }
+      if (typeof factory !== 'function') {
+        throw new Error(`extension "${name}": registerStrategy("${type}") requires a factory function`);
+      }
+      registry.strategies.set(type, factory);
+    },
+    registerModule(factory) {
+      if (typeof factory !== 'function') {
+        throw new Error(`extension "${name}": registerModule requires a factory function`);
+      }
+      registry.modules.push({ extensionName: name, factory, config });
+    },
+  };
+
+  try {
+    await Promise.resolve((register as (api: ExtensionApi, config: Record<string, unknown>) => unknown)(api, config));
+  } catch (err) {
+    throw new Error(
+      `extension "${name}" (${ext.path}): register() threw: ` +
+      `${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+}

package/src/framework-agent-config.ts

@@ -24,20 +24,28 @@ export function buildFrameworkAgentConfig(
     maxStreamTokens: recipe.agent.maxStreamTokens ?? 150000,
     contextBudgetTokens: recipe.agent.contextBudgetTokens,
     ...(recipe.agent.cacheTtl && { cacheTtl: recipe.agent.cacheTtl }),
-    ...(recipe.agent.provider === 'openai-responses' && {
+    // Bedrock legacy Claude models reject cache_control outright
+    // ("your request did not allow prompt caching") — suppress markers.
+    ...(recipe.agent.provider === 'bedrock' && { promptCaching: false }),
+    // Prefill scaffold (anthropic-xml formatter), e.g. chapterx CLI-sim's
+    // '<cmd>cat untitled.txt</cmd>' — part of migrating prefill-era bots.
+    ...(recipe.agent.prefillUserMessage && { prefillUserMessage: recipe.agent.prefillUserMessage }),
+    ...((recipe.agent.provider === 'openai-responses' || recipe.agent.provider === 'openai-codex') && {
       providerParams: {
         reasoning: {
           effort: recipe.agent.responses?.reasoningEffort ?? 'high',
           context: recipe.agent.responses?.reasoningContext ?? 'all_turns',
         },
-        ...(recipe.agent.responses?.serviceTier ? {
-          service_tier: recipe.agent.responses.serviceTier,
-        } : {}),
-        ...(recipe.agent.responses?.compactThreshold ? {
-          context_management: [{
-            type: 'compaction',
-            compact_threshold: recipe.agent.responses.compactThreshold,
-          }],
+        ...(recipe.agent.provider === 'openai-responses' ? {
+          ...(recipe.agent.responses?.serviceTier ? {
+            service_tier: recipe.agent.responses.serviceTier,
+          } : {}),
+          ...(recipe.agent.responses?.compactThreshold ? {
+            context_management: [{
+              type: 'compaction',
+              compact_threshold: recipe.agent.responses.compactThreshold,
+            }],
+          } : {}),
         } : {}),
       },
     }),
@@ -47,5 +55,8 @@ export function buildFrameworkAgentConfig(
     ...(recipe.agent.sameRoundThinkTextPolicy !== undefined
       ? { sameRoundThinkTextPolicy: recipe.agent.sameRoundThinkTextPolicy }
       : {}),
+    ...(recipe.agent.proseRouting !== undefined
+      ? { proseRouting: recipe.agent.proseRouting }
+      : {}),
   };
 }

package/src/framework-strategy.ts

@@ -5,6 +5,7 @@ import {
 } from '@animalabs/agent-framework';
 import type { Recipe, RecipeStrategy } from './recipe.js';
 import { FrontdeskStrategy } from './strategies/frontdesk-strategy.js';
+import { isBuiltinStrategyType, type ExtensionRegistry } from './extensions.js';
 
 const PASSTHROUGH_KEYS: ReadonlyArray<keyof RecipeStrategy> = [
   'enforceBudget',
@@ -39,13 +40,36 @@ export function buildFrameworkStrategy(
   recipe: Recipe,
   model: string,
   timeZone: string,
+  extensions?: ExtensionRegistry,
 ): ContextStrategy {
   const strategyConfig = recipe.agent.strategy;
   const strategyType = strategyConfig?.type ?? 'autobiographical';
+
+  // Non-built-in types resolve through the extension registry. Validation
+  // already required a strategy-kind extension to be declared; this catches
+  // the declared-but-didn't-register case with a precise error.
+  if (!isBuiltinStrategyType(strategyType)) {
+    const factory = extensions?.strategies.get(strategyType);
+    if (!factory) {
+      const known = extensions ? Array.from(extensions.strategies.keys()) : [];
+      throw new Error(
+        `strategy type "${strategyType}" is not built-in and no loaded extension registered it. ` +
+        `Registered custom types: ${known.length ? known.join(', ') : '(none)'}.`,
+      );
+    }
+    return factory({
+      config: (strategyConfig ?? {}) as RecipeStrategy & Record<string, unknown>,
+      model,
+      timeZone,
+    });
+  }
   const autobiographicalOpts: Record<string, unknown> = {
     headWindowTokens: strategyConfig?.headWindowTokens ?? 4000,
     recentWindowTokens: strategyConfig?.recentWindowTokens ?? 30000,
     compressionModel: strategyConfig?.compressionModel ?? model,
+    ...(strategyConfig?.compressionMaxTokens !== undefined
+      ? { compressionMaxTokens: strategyConfig.compressionMaxTokens }
+      : {}),
     autoTickOnNewMessage: true,
     maxMessageTokens: strategyConfig?.maxMessageTokens ?? 10000,
     ...(strategyType === 'frontdesk' ? { timeZone } : {}),