@synergenius/flow-weaver-pack-weaver 0.9.193 → 0.9.196

package/src/bot/post-turn-hooks.ts

@@ -0,0 +1,137 @@
+/**
+ * Post-turn hook system for the agent loop.
+ *
+ * Hooks run after each iteration of the agent loop, enabling cost checks,
+ * steering, progress reporting, and knowledge extraction between LLM turns.
+ *
+ * Hooks run sequentially (not parallel) so abort hooks fire before
+ * subsequent hooks. Errors are caught per-hook — a failing hook does
+ * not block other hooks or the agent loop.
+ */
+
+import type { TurnEndContext, TurnEndResult } from '@synergenius/flow-weaver/agent';
+import { CostTracker } from './cost-tracker.js';
+
+// ---------------------------------------------------------------------------
+// Hook interface
+// ---------------------------------------------------------------------------
+
+export type HookTiming = 'every' | 'final' | 'between';
+
+export interface PostTurnHook {
+  name: string;
+  /** When to run: 'every' = every turn, 'final' = only final turn, 'between' = only between turns */
+  timing: HookTiming;
+  execute(context: TurnEndContext): Promise<PostTurnHookResult>;
+}
+
+export interface PostTurnHookResult {
+  /** If false, abort the agent loop. Default: true. */
+  continue?: boolean;
+  /** Optional message to inject into conversation (steering nudge). */
+  injectMessage?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Hook runner
+// ---------------------------------------------------------------------------
+
+export class PostTurnHookRunner {
+  private hooks: PostTurnHook[] = [];
+
+  register(hook: PostTurnHook): void {
+    this.hooks.push(hook);
+  }
+
+  /** Returns the onTurnEnd callback to pass to runAgentLoop options. */
+  createCallback(): (ctx: TurnEndContext) => Promise<TurnEndResult | void> {
+    return async (ctx: TurnEndContext): Promise<TurnEndResult | void> => {
+      let injectMessage: string | undefined;
+
+      for (const hook of this.hooks) {
+        // Check timing
+        if (hook.timing === 'final' && !ctx.isFinalTurn) continue;
+        if (hook.timing === 'between' && ctx.isFinalTurn) continue;
+
+        try {
+          const result = await hook.execute(ctx);
+          if (result.continue === false) {
+            return { continue: false, injectMessage: result.injectMessage };
+          }
+          if (result.injectMessage) {
+            injectMessage = injectMessage
+              ? injectMessage + '\n' + result.injectMessage
+              : result.injectMessage;
+          }
+        } catch (err) {
+          // Hook failure is non-fatal — log and continue
+          if (process.env.WEAVER_VERBOSE) {
+            console.error(`[post-turn-hook] ${hook.name} failed:`, err);
+          }
+        }
+      }
+
+      if (injectMessage) return { injectMessage };
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Built-in hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Cost checkpoint — aborts the loop when cumulative cost exceeds budget.
+ * Subsumes the standalone #6 per-turn budget enforcement approach.
+ */
+export class CostCheckpointHook implements PostTurnHook {
+  name = 'cost-checkpoint';
+  timing: HookTiming = 'between';
+
+  constructor(
+    private maxCost: number,
+    private model: string,
+  ) {}
+
+  async execute(ctx: TurnEndContext): Promise<PostTurnHookResult> {
+    const cost = CostTracker.estimateCost(this.model, {
+      inputTokens: ctx.usage.promptTokens,
+      outputTokens: ctx.usage.completionTokens,
+    });
+
+    if (cost >= this.maxCost) {
+      return {
+        continue: false,
+        injectMessage: `Budget exceeded: $${cost.toFixed(4)} >= $${this.maxCost.toFixed(4)}`,
+      };
+    }
+    return {};
+  }
+}
+
+/**
+ * Progress report — emits a stream event with turn progress for UI updates.
+ */
+export class ProgressReportHook implements PostTurnHook {
+  name = 'progress-report';
+  timing: HookTiming = 'every';
+
+  constructor(
+    private emitEvent: (event: { type: string; timestamp: number; data: Record<string, unknown> }) => void,
+  ) {}
+
+  async execute(ctx: TurnEndContext): Promise<PostTurnHookResult> {
+    this.emitEvent({
+      type: 'turn-progress',
+      timestamp: Date.now(),
+      data: {
+        iteration: ctx.iteration,
+        maxIterations: ctx.maxIterations,
+        toolCallCount: ctx.toolCallCount,
+        isFinalTurn: ctx.isFinalTurn,
+        usage: ctx.usage,
+      },
+    });
+    return {};
+  }
+}

package/src/bot/profile-types.ts

@@ -92,6 +92,21 @@ export interface PhaseDescriptor {
  * not hardcoded. Each workflow can have different phases (e.g. a review
  * bot might have analyze/report/suggest instead of plan/execute/review).
  */
+/** Post-run verification config — independent review of completed work. */
+export interface VerificationConfig {
+  /** Whether verification is enabled. Default: false. */
+  enabled: boolean;
+  /** Model tier for the verification agent. Default: 'standard'. */
+  tier: ModelTier;
+  /**
+   * How often to run verification (1 = every completed task, 2 = every other, etc.).
+   * Default: 1 (always verify).
+   */
+  frequency: number;
+  /** Re-open the task if verification fails. Default: true. */
+  reopenOnFail: boolean;
+}
+
 export interface ProfileBehavior {
   /** Capability names this profile can use (e.g. ['core', 'file-ops', 'shell']). */
   capabilities?: string[];
@@ -107,6 +122,8 @@ export interface ProfileBehavior {
   exitProtocol: ExitProtocol;
   /** Structured output requirements. */
   outputContract?: OutputContract;
+  /** Post-run verification by an independent agent. */
+  verification?: VerificationConfig;
 }
 
 /** Structured exit status from a bot run. */

package/src/bot/swarm-controller.ts

@@ -32,7 +32,11 @@ import { ProfileStore } from './profile-store.js';
 import type { BotProfile, BotInstance, OrchestratorInput, OrchestratorDecision, ProfileBehavior } from './profile-types.js';
 import { buildDefaultBehavior, adjustBehaviorForComplexity } from './behavior-defaults.js';
 import type { Task, RunProgress } from './task-types.js';
-import type { WorkflowResult } from './types.js';
+import type { WorkflowResult, ProviderInfo } from './types.js';
+import { scheduleMemoryExtraction } from './memory-extraction-worker.js';
+import { shouldCompact, compactRunHistory } from './context-compactor.js';
+import { DreamTask } from './dream-task.js';
+import { callAI } from './ai-client.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -118,6 +122,15 @@ export class SwarmController {
   /** Last emitted dispatch-filter-summary JSON (for dedup / throttling). */
   private lastFilterSummaryJson: string | null = null;
 
+  /** Frozen system prompt prefix for cross-slot Anthropic cache sharing. */
+  private frozenPromptPrefix: string | null = null;
+
+  /** Background knowledge consolidation during idle periods. */
+  private dreamTask: DreamTask;
+
+  /** Counter for verification frequency gating (incremented per completed task). */
+  private verificationCounter = 0;
+
   // -----------------------------------------------------------------------
   // Singleton
   // -----------------------------------------------------------------------
@@ -148,6 +161,7 @@ export class SwarmController {
     this.orchestrator = new Orchestrator({ aiRouter: new AIRouterImpl(projectDir) });
     this.instanceManager = new InstanceManager();
     this.profileStore = new ProfileStore(projectDir);
+    this.dreamTask = new DreamTask({ projectDir });
 
     // Load persisted state or create default
     this.state = this._loadState();
@@ -210,6 +224,16 @@ export class SwarmController {
     this.state.startedAt = new Date().toISOString();
     this._persist();
 
+    // Freeze the stable system prompt prefix for cross-slot cache sharing.
+    // All bot slots will use this identical prefix; only the per-task suffix varies.
+    try {
+      const { buildSystemPrompt } = await import('./system-prompt.js');
+      this.frozenPromptPrefix = await buildSystemPrompt();
+    } catch (err) {
+      if (process.env.WEAVER_VERBOSE) console.warn('[swarm] failed to freeze system prompt prefix:', err);
+      this.frozenPromptPrefix = null;
+    }
+
     console.log(`\x1b[36m[swarm] started (pack-weaver v${PACK_VERSION})\x1b[0m`);
     this.eventLog.emit({ type: 'swarm-started', timestamp: Date.now(), data: { packVersion: PACK_VERSION } });
 
@@ -593,6 +617,7 @@ export class SwarmController {
           return !routableTasks.includes(t);
         }).length;
         _dl(`[dispatch] 0 routable from ${pendingTasks.length} open. parent=${pendingTasks.filter(t => t.isParent).length} budget=${pendingTasks.filter(t => t.context.budgetExhausted).length} deps-blocked=${depsBlocked}`);
+        await this._maybeDream();
         await this._sleep(DISPATCH_LOOP_SLEEP_MS, signal);
         continue;
       }
@@ -775,6 +800,26 @@ export class SwarmController {
     }
   }
 
+  // -----------------------------------------------------------------------
+  // Idle-time knowledge consolidation
+  // -----------------------------------------------------------------------
+
+  private async _maybeDream(): Promise<void> {
+    if (!this.dreamTask.shouldRun()) return;
+    try {
+      const result = await this.dreamTask.consolidate();
+      if (result.staleEntriesCleaned + result.insightsConverted > 0) {
+        this.eventLog.emit({
+          type: 'dream-consolidation',
+          timestamp: Date.now(),
+          data: result as unknown as Record<string, unknown>,
+        });
+      }
+    } catch (err) {
+      if (process.env.WEAVER_VERBOSE) console.warn('[swarm] dream-task failed:', err);
+    }
+  }
+
   // -----------------------------------------------------------------------
   // Task execution
   // -----------------------------------------------------------------------
@@ -793,6 +838,31 @@ export class SwarmController {
       const task = await this.taskStore.get(taskId);
       if (!task) throw new Error(`Task not found: ${taskId}`);
 
+      // LLM-based context compaction — produces a structured summary of all runs
+      // when the task has enough history. The summary replaces verbose per-run
+      // sections in the prompt, preserving semantic signal.
+      if (shouldCompact(task, profile.preferences?.costStrategy)) {
+        try {
+          const { resolveModelTier } = await import('./behavior-defaults.js');
+          const { resolveProviderConfig } = await import('./agent-provider.js');
+          const detected = resolveProviderConfig('auto');
+          const providerType = detected.name;
+          const compactModel = detected.model ?? resolveModelTier('fast', providerType);
+          const compactPInfo = {
+            type: providerType as ProviderInfo['type'],
+            apiKey: process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY,
+            model: compactModel,
+          };
+          const summary = await compactRunHistory(task, compactPInfo, callAI);
+          if (summary) {
+            task.context.compactedSummary = summary;
+            await this.taskStore.update(taskId, { context: task.context });
+          }
+        } catch {
+          // Compaction failure is non-fatal — prompt builder falls back to context decay
+        }
+      }
+
       // Build prompt from task context
       const parentTask = task.parentId ? await this.taskStore.get(task.parentId) : null;
       const siblingTasks = task.parentId ? await this.taskStore.getSubtasks(task.parentId) : [];
@@ -834,7 +904,12 @@ export class SwarmController {
         taskId,
         botId: workerId,
         config: { provider: 'auto' },
-        params: { taskJson, projectDir: this.projectDir, behaviorJson },
+        params: {
+          taskJson,
+          projectDir: this.projectDir,
+          behaviorJson,
+          ...(this.frozenPromptPrefix ? { frozenPromptPrefix: this.frozenPromptPrefix } : {}),
+        },
         eventLog: runEventLog,
       });
 
@@ -911,6 +986,53 @@ export class SwarmController {
       }
     }
 
+    // Independent verification — runs after acceptance passes, before release.
+    // Uses a fresh LLM session with a potentially different model tier.
+    if (releaseStatus === 'done' && task) {
+      const behavior: import('./profile-types.js').ProfileBehavior | undefined =
+        profile.preferences?.behavior;
+      const vConfig = behavior?.verification;
+      if (vConfig?.enabled) {
+        this.verificationCounter++;
+        const shouldVerify = this.verificationCounter % vConfig.frequency === 0;
+        if (shouldVerify) {
+          try {
+            const { runVerification } = await import('../node-types/verify-task.js');
+            const { resolveProviderConfig } = await import('./agent-provider.js');
+            const { resolveModelTier } = await import('./behavior-defaults.js');
+            const detected = resolveProviderConfig('auto');
+            const verifyModel = resolveModelTier(vConfig.tier, detected.name);
+            const verifyResult = await runVerification(
+              {
+                taskTitle: task.title,
+                taskDescription: task.description,
+                filesCreated: runProgress.filesCreated,
+                filesModified: runProgress.filesModified,
+                summary: runProgress.summary,
+                checks: runProgress.checks,
+              },
+              detected.name,
+              verifyModel,
+              process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY,
+            );
+            await this.taskStore.update(taskId, { lastVerification: verifyResult } as Record<string, unknown>);
+            this.eventLog.emit({
+              type: 'verification',
+              timestamp: Date.now(),
+              data: { taskId, runId, verdict: verifyResult.verdict, summary: verifyResult.summary, cost: verifyResult.cost } as unknown as Record<string, unknown>,
+            });
+            if (verifyResult.verdict === 'fail' && vConfig.reopenOnFail) {
+              releaseStatus = 'open';
+              console.log(`\x1b[33m[swarm] verification FAILED for task ${taskId}: ${verifyResult.summary}\x1b[0m`);
+            }
+          } catch (verifyErr) {
+            if (process.env.WEAVER_VERBOSE) console.warn('[swarm] verification failed:', verifyErr);
+            // Verification failure is non-fatal — release as originally planned
+          }
+        }
+      }
+    }
+
     // Health checks — detect suspicious runs before releasing
     if (tokensUsed === 0 && runProgress.outcome === 'completed') {
       console.warn(`[swarm] HEALTH: zero-token completion task=${taskId} worker=${workerId} duration=${durationMs}ms`);
@@ -925,6 +1047,11 @@ export class SwarmController {
 
     await this.taskStore.release(taskId, releaseStatus, runProgress);
 
+    // Fire-and-forget memory extraction — persists project facts for future runs
+    if (task) {
+      scheduleMemoryExtraction(this.projectDir, task, runProgress);
+    }
+
     // Record token usage
     this.recordTokenUsage(workerId, taskId, tokensUsed, costUsed);
 

package/src/bot/task-prompt-builder.ts

@@ -65,10 +65,13 @@ function buildFull(
   }
 
   // --- Context decay: workspace is the source of truth, not history ---
-  // Workers see: last acceptance check, last run's remainingWork/blockers,
-  // stagnation count, and a directive to read the workspace.
+  // If a compacted summary exists (from LLM compaction after 3+ runs),
+  // use it instead of the per-run sections — it preserves semantic signal.
+  if (task.context.compactedSummary) {
+    sections.push(`### Execution History (Compacted)\n${task.context.compactedSummary}`);
+  }
 
-  // 2.3.2: Last acceptance check result
+  // 2.3.2: Last acceptance check result (always shown, even with compacted summary)
   if (task.lastAcceptanceCheck) {
     const ac = task.lastAcceptanceCheck;
     const checkLines = ac.results
@@ -78,6 +81,7 @@ function buildFull(
   }
 
   // 2.3.3: Continue from last run's remaining work
+  // (always shown — most recent actionable data, even with compacted summary)
   const lastRun = task.context.runHistory.length > 0
     ? task.context.runHistory[task.context.runHistory.length - 1]
     : undefined;
@@ -90,18 +94,21 @@ function buildFull(
     sections.push(`### Previous Run Blocked By\n${(lastRun.blockers as string[]).map((b: string) => `- ${b}`).join('\n')}`);
   }
 
-  // Last run summary (one run only, not full history)
-  if (lastRun && 'summary' in lastRun) {
-    sections.push(`### Last Run\nOutcome: ${lastRun.outcome} | ${lastRun.summary}`);
-  }
+  // Per-run sections — skipped when compacted summary exists (it covers this info)
+  if (!task.context.compactedSummary) {
+    // Last run summary (one run only, not full history)
+    if (lastRun && 'summary' in lastRun) {
+      sections.push(`### Last Run\nOutcome: ${lastRun.outcome} | ${lastRun.summary}`);
+    }
 
-  // Run count + stagnation
-  if (task.context.runHistory.length > 0) {
-    let meta = `Total runs: ${task.context.runHistory.length}`;
-    if (task.context.stagnationCount > 0) {
-      meta += ` | Stagnation: ${task.context.stagnationCount} run(s) with no new changes — try a different approach`;
+    // Run count + stagnation
+    if (task.context.runHistory.length > 0) {
+      let meta = `Total runs: ${task.context.runHistory.length}`;
+      if (task.context.stagnationCount > 0) {
+        meta += ` | Stagnation: ${task.context.stagnationCount} run(s) with no new changes — try a different approach`;
+      }
+      sections.push(`### Run History\n${meta}`);
     }
-    sections.push(`### Run History\n${meta}`);
   }
 
   // Directive: read the workspace, don't rely on stale context
@@ -226,6 +233,11 @@ function buildWithTruncation(
     sections.push(`### Relevant Files\n${task.context.files.join('\n')}`);
   }
 
+  // Compacted summary (same guard as buildFull)
+  if (task.context.compactedSummary) {
+    sections.push(`### Execution History (Compacted)\n${task.context.compactedSummary}`);
+  }
+
   // Context decay: last acceptance check + last run only
   if (task.lastAcceptanceCheck) {
     const ac = task.lastAcceptanceCheck;
@@ -244,16 +256,20 @@ function buildWithTruncation(
   if (lastRunT && 'blockers' in lastRunT && Array.isArray(lastRunT.blockers) && lastRunT.blockers.length > 0) {
     sections.push(`### Previous Run Blocked By\n${(lastRunT.blockers as string[]).map((b: string) => `- ${b}`).join('\n')}`);
   }
-  if (lastRunT && 'summary' in lastRunT) {
-    sections.push(`### Last Run\nOutcome: ${lastRunT.outcome} | ${lastRunT.summary}`);
-  }
 
-  if (task.context.runHistory.length > 0) {
-    let meta = `Total runs: ${task.context.runHistory.length}`;
-    if (task.context.stagnationCount > 0) {
-      meta += ` | Stagnation: ${task.context.stagnationCount} — try a different approach`;
+  // Per-run sections — skipped when compacted summary exists
+  if (!task.context.compactedSummary) {
+    if (lastRunT && 'summary' in lastRunT) {
+      sections.push(`### Last Run\nOutcome: ${lastRunT.outcome} | ${lastRunT.summary}`);
+    }
+
+    if (task.context.runHistory.length > 0) {
+      let meta = `Total runs: ${task.context.runHistory.length}`;
+      if (task.context.stagnationCount > 0) {
+        meta += ` | Stagnation: ${task.context.stagnationCount} — try a different approach`;
+      }
+      sections.push(`### Run History\n${meta}`);
     }
-    sections.push(`### Run History\n${meta}`);
   }
 
   // Directive: read the workspace, don't rely on stale context

package/src/bot/task-types.ts

@@ -60,6 +60,22 @@ export interface AcceptanceResult {
   checkedAt: string;
 }
 
+// ---------------------------------------------------------------------------
+// Verification result — independent post-run review
+// ---------------------------------------------------------------------------
+
+export type VerificationVerdict = 'pass' | 'fail' | 'inconclusive';
+
+export interface VerificationResult {
+  verdict: VerificationVerdict;
+  summary: string;
+  issues: string[];
+  filesReviewed: string[];
+  verifiedAt: string;
+  /** Cost of the verification run in USD. */
+  cost: number;
+}
+
 // ---------------------------------------------------------------------------
 // Task context
 // ---------------------------------------------------------------------------
@@ -71,6 +87,8 @@ export interface TaskContext {
   stagnationCount: number;
   budgetExhausted?: boolean;
   projectBrief?: string;
+  /** LLM-generated summary of all runs, replacing verbose run history in prompts. */
+  compactedSummary?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -103,6 +121,9 @@ export interface Task {
   acceptance?: AcceptanceCriteria;
   lastAcceptanceCheck?: AcceptanceResult;
 
+  // Verification
+  lastVerification?: VerificationResult;
+
   // Context
   context: TaskContext;
 

package/src/bot/tool-registry.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ToolDefinition } from '@synergenius/flow-weaver/agent';
+import { getCapability } from './capability-registry.js';
 
 export interface WeaverTool extends ToolDefinition {
   verboseOutput?: boolean;
@@ -575,6 +576,94 @@ export const BOT_TOOLS: ToolDefinition[] = ALL_TOOLS.filter(t => t.contexts.incl
 export const ASSISTANT_TOOLS: ToolDefinition[] = ALL_TOOLS.filter(t => t.contexts.includes('assistant'));
 export const VERBOSE_TOOL_NAMES = new Set(ALL_TOOLS.filter(t => t.verboseOutput).map(t => t.name));
 
+// ── Mode-based tool filtering ───────────────────────────────────────
+
+/** Core tools included in every mode regardless of profile. */
+const CORE_TOOLS = new Set([
+  'read_file', 'list_files', 'run_shell', 'validate', 'learn', 'recall',
+]);
+
+/** Tools allowed per task mode. Keys match task.mode values. */
+const MODE_TOOLS: Record<string, Set<string>> = {
+  create: new Set([
+    'read_file', 'list_files', 'write_file', 'patch_file',
+    'run_shell', 'validate', 'tsc_check', 'run_tests',
+    'learn', 'recall',
+  ]),
+  modify: new Set([
+    'read_file', 'list_files', 'patch_file',
+    'run_shell', 'validate', 'tsc_check', 'run_tests',
+    'learn', 'recall',
+  ]),
+  read: new Set([
+    'read_file', 'list_files', 'run_shell', 'validate',
+    'learn', 'recall',
+  ]),
+  batch: new Set([
+    'read_file', 'list_files', 'write_file', 'patch_file',
+    'run_shell', 'validate', 'tsc_check', 'run_tests',
+    'learn', 'recall',
+  ]),
+};
+
+/**
+ * Resolve which tools a bot should have for a given task and profile.
+ *
+ * Uses the task mode to select a base tool pool, then intersects with
+ * profile-granted tools (from capabilities). Core tools are always included.
+ *
+ * @param task - Task with mode and optional capabilities
+ * @param capabilities - Profile capability names (e.g., ['role-developer', 'file-ops', 'shell'])
+ * @returns Set of tool names the bot should receive
+ */
+export function resolveToolsForTask(
+  task: { mode?: string },
+  capabilities?: string[],
+): Set<string> {
+  // Start with the mode-based pool (default to 'create' = full set)
+  const modePool = MODE_TOOLS[task.mode ?? 'create'] ?? MODE_TOOLS.create;
+
+  // If capabilities are specified, compute the capability-granted tools
+  if (capabilities && capabilities.length > 0) {
+    const capTools = new Set<string>();
+    for (const capName of capabilities) {
+      const cap = getCapability(capName);
+      if (cap?.tools) {
+        for (const tool of cap.tools) capTools.add(tool);
+      }
+    }
+
+    // Build the tool set in two steps:
+    // 1. Mode-restricted tools: must be in BOTH mode pool AND capability set (or core).
+    //    This ensures modify mode excludes write_file even if the capability grants it.
+    // 2. Role-specific tools: tools granted by capabilities but not present in ANY
+    //    mode pool (e.g., task_create, ask_user). These are additive — the capability
+    //    is the sole authority for them.
+    const allModeTools = new Set<string>();
+    for (const pool of Object.values(MODE_TOOLS)) {
+      for (const t of pool) allModeTools.add(t);
+    }
+
+    const result = new Set<string>();
+    // Step 1: mode-restricted intersection
+    for (const tool of modePool) {
+      if (capTools.has(tool) || CORE_TOOLS.has(tool)) {
+        result.add(tool);
+      }
+    }
+    // Step 2: role-specific tools (not in any mode pool)
+    for (const tool of capTools) {
+      if (!allModeTools.has(tool)) {
+        result.add(tool);
+      }
+    }
+    return result;
+  }
+
+  // No capability restriction — use mode pool as-is
+  return new Set(modePool);
+}
+
 /**
  * Generate a prompt section grouping assistant tools by category.
  */

package/src/bot/types.ts

@@ -642,6 +642,8 @@ export interface WeaverContext {
   allValid?: boolean;
   gitResultJson?: string;
   reviewJson?: string;
+  /** Frozen system prompt prefix from swarm controller for cross-slot cache sharing. */
+  frozenPromptPrefix?: string;
 }
 
 export interface GenesisContext {