@animalabs/connectome-host 0.3.9 → 0.4.0

package/src/recipe.ts

@@ -19,11 +19,19 @@ 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;
   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
@@ -85,7 +93,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 +121,19 @@ 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
+   * 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 +144,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`
@@ -394,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
@@ -402,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
@@ -445,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[];
@@ -503,6 +570,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;
@@ -510,6 +602,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[] };
 }
 
@@ -639,6 +733,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);
 }
 
@@ -663,6 +758,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).
@@ -701,8 +815,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) {
@@ -735,6 +857,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)) {
@@ -782,6 +918,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>;
@@ -789,10 +956,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 (
@@ -981,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>;