fix(dashboard,core,engine): statically import @fusion/engine to fix createFnAgent undefined in published CLI

The dashboard modules used a variable-specifier dynamic import (`const m = "@fusion/engine"; await import(m)`) to defeat bundler static analysis. tsup honored that and left the dynamic import in dist/bin.js, so the published `@runfusion/fusion` package failed at runtime with "createFnAgent2 is not a function" — `@fusion/engine` isn't on npm and the silent catch set the binding to undefined. Replaces the trick with static imports across planning, chat, subtask-breakdown, mission-interview, agent-generation, ai-refine, roadmap-suggestions, milestone-slice-interview, and routes. Core can't statically import engine (cycle), so it now exposes setCreateFnAgent and engine wires itself in at module load. Documents the pattern in AGENTS.md. Fixes Runfusion/Fusion#9. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 14:43:03 -07:00
parent 861fb50df1
commit 544d8d77e3
13 changed files with 114 additions and 231 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,6 +46,28 @@ The release script is also the required path for keeping both public npm package

 Only `@runfusion/fusion` is published. The others are internal workspace packages.

+### Importing across `@fusion/*` packages
+
+Because `@fusion/core`, `@fusion/dashboard`, and `@fusion/engine` are **not** on npm, the published CLI bundle (`packages/cli/dist/bin.js`) only works because tsup is configured with `noExternal: [/^@fusion\//]` — every `@fusion/*` import gets inlined into the bundle.
+
+For that inlining to happen the import must be **statically analyzable**. The following anti-pattern silently breaks on the published `npm i -g @runfusion/fusion`:
+
+```ts
+// ❌ BROKEN: variable specifier defeats static analysis
+const engineModule = "@fusion/engine";
+const engine = await import(/* @vite-ignore */ engineModule);
+createFnAgent = engine.createFnAgent;
+```
+
+esbuild leaves the dynamic `import("@fusion/engine")` in the output, the package isn't installed at runtime, the import throws, the catch silently sets the binding to `undefined`, and the next call fails with a confusing TypeError like `createFnAgent2 is not a function` (issue Runfusion/Fusion#9, FN-2613). Affects every AI flow in the dashboard.
+
+**Rules:**
+
+1. **Default to a static import** — `import { createFnAgent } from "@fusion/engine"` — so esbuild can bundle it and tests can `vi.mock("@fusion/engine", …)` it.
+2. **The one exception is `@fusion/core` itself**, which can't statically import engine without a circular dependency (engine → core). Core uses dependency injection: `setCreateFnAgent` (in `packages/core/src/ai-engine-loader.ts`) is called by `packages/engine/src/index.ts` at module load. Don't add new dynamic `import("@fusion/engine")` calls in core — extend the loader instead.
+3. **Never reintroduce the `engineModule = "@fusion/engine"` + `await import(/* @vite-ignore */ engineModule)` trick.** If you find one, treat it as a bug.
+4. Test mocking still works with static imports — vitest's module-level `vi.mock("@fusion/engine", …)` hoists above the static import.
+
 ## Storage Model

 Fusion uses a hybrid storage architecture: structured metadata lives in SQLite (`.fusion/fusion.db`) while large blob files (PROMPT.md, attachments) remain on the filesystem under `.fusion/tasks/{ID}/`. The database runs in WAL mode for concurrent access.
--- a/packages/core/src/ai-engine-loader.ts
+++ b/packages/core/src/ai-engine-loader.ts
@@ -1,45 +1,40 @@
 /**
- * Shared lazy loader for `@fusion/engine`'s `createFnAgent`.
+ * Shared lazy accessor for `@fusion/engine`'s `createFnAgent`.
 *
- * @fusion/engine must be imported dynamically (not statically) so that:
- *   - core can be consumed in test environments where engine isn't resolvable
- *   - a missing engine package fails soft instead of breaking module load
+ * Core can't import engine statically (engine depends on core, so a static
+ * import would create a cycle). Instead, engine wires its `createFnAgent` in
+ * via `setCreateFnAgent` when its module loads, and consumers in core read it
+ * back through `getFnAgent`.
 *
- * Using a variable module specifier also prevents bundlers (Vite) from
- * statically analysing and trying to resolve the import at build time.
+ * If engine never loads (e.g. tests that only import core), `getFnAgent`
+ * returns `undefined` and callers degrade gracefully.
 */

 // Engine exports a function type we intentionally don't pull in here — importing
-// the type would reintroduce the static resolution this module is designed to avoid.
+// the type would reintroduce the cycle this module is designed to avoid.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type CreateFnAgent = any;

 let createFnAgent: CreateFnAgent | undefined;

-async function initEngine(): Promise<void> {
-  try {
-    const engineModule = "@fusion/engine";
-    const engine = await import(/* @vite-ignore */ engineModule);
-    createFnAgent = engine.createFnAgent;
-  } catch {
-    createFnAgent = undefined;
-  }
-}
-
 /** Shape of a message in an agent session's state. */
 export interface AgentMessage {
  role: string;
  content?: string | Array<{ type: string; text: string }>;
 }

-/** Promise that resolves once the initial load attempt has completed. */
-const engineReady: Promise<void> = initEngine();
+/**
+ * Wire engine's `createFnAgent` into core. Called by `@fusion/engine` at module
+ * load. Tests can also call this with a stub.
+ */
+export function setCreateFnAgent(fn: CreateFnAgent | undefined): void {
+  createFnAgent = fn;
+}

 /**
- * Returns `createFnAgent` from `@fusion/engine`, or `undefined` if the engine
- * could not be loaded (typical in tests or when engine isn't installed).
+ * Returns `createFnAgent` from `@fusion/engine`, or `undefined` if engine has
+ * not registered itself yet (typical in tests).
 */
 export async function getFnAgent(): Promise<CreateFnAgent> {
-  await engineReady;
  return createFnAgent;
 }
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -8,6 +8,9 @@ export {
  getTemplatesForRole,
 } from "./agent-prompts.js";

+// ── Engine wiring (set by @fusion/engine at module load) ────────────
+export { setCreateFnAgent, getFnAgent, type AgentMessage } from "./ai-engine-loader.js";
+
 // ── Prompt Overrides ─────────────────────────────────────────────────
 export {
  PROMPT_KEY_CATALOG,
--- a/packages/dashboard/src/agent-generation.ts
+++ b/packages/dashboard/src/agent-generation.ts
@@ -40,28 +40,13 @@ async function initPromptCatalog() {
 // Initialize prompt catalog (will be awaited in actual usage)
 const promptCatalogReadyPromise = initPromptCatalog();

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

-// Initialize the import (this runs in actual server, mocked in tests)
-async function initEngine() {
-  if (!createFnAgent) {
-    try {
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      // Allow failure in test environments - agent functionality will be stubbed
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 // ── Constants ───────────────────────────────────────────────────────────────
--- a/packages/dashboard/src/ai-refine.ts
+++ b/packages/dashboard/src/ai-refine.ts
@@ -14,29 +14,13 @@
 import type { PromptOverrideMap } from "@fusion/core";
 import { resolvePrompt } from "@fusion/core";

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

-// Initialize the import (this runs in actual server, mocked in tests)
-async function initEngine() {
-  if (!createFnAgent) {
-    try {
-      // Use dynamic import with variable to prevent static analysis
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      // Allow failure in test environments - agent functionality will be stubbed
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 // ── Types ───────────────────────────────────────────────────────────────────
--- a/packages/dashboard/src/chat.ts
+++ b/packages/dashboard/src/chat.ts
@@ -25,13 +25,17 @@ import { EventEmitter } from "node:events";
 import { join, resolve, relative } from "node:path";
 import { SessionEventBuffer } from "./sse-buffer.js";

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import {
+  createFnAgent as engineCreateFnAgent,
+  buildAgentChatPrompt as engineBuildAgentChatPrompt,
+} from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AgentResult = any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let buildAgentChatPromptFn: any;
+let buildAgentChatPromptFn: any = engineBuildAgentChatPrompt;

 /**
 * Diagnostics logger for the chat module.
@@ -93,35 +97,8 @@ const diagnostics: DiagnosticsLogger = {
  },
 };

-// Initialize the import (this runs in actual server, mocked in tests)
-async function initEngine() {
-  if (!createFnAgent || !buildAgentChatPromptFn) {
-    try {
-      // Use dynamic import with variable to prevent static analysis
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      if (!createFnAgent) {
-        createFnAgent = engine.createFnAgent;
-      }
-      if (!buildAgentChatPromptFn) {
-        buildAgentChatPromptFn = engine.buildAgentChatPrompt;
-      }
-    } catch {
-      // Allow failure in test environments - agent functionality will be stubbed
-      if (!createFnAgent) {
-        createFnAgent = undefined;
-      }
-      if (!buildAgentChatPromptFn) {
-        buildAgentChatPromptFn = undefined;
-      }
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 // ── Constants ───────────────────────────────────────────────────────────────
@@ -912,8 +889,7 @@ export function __setBuildAgentChatPrompt(mock: typeof buildAgentChatPromptFn):
 export function __resetChatState(): void {
  chatStreamManager.reset();
  rateLimits.clear();
-  engineReady = undefined;
-  buildAgentChatPromptFn = undefined;
+  buildAgentChatPromptFn = engineBuildAgentChatPrompt;

  // Reset diagnostics logger to default
  __setChatDiagnostics(null);
--- a/packages/dashboard/src/milestone-slice-interview.ts
+++ b/packages/dashboard/src/milestone-slice-interview.ts
@@ -94,29 +94,15 @@ function parseTargetInterviewResponseImpl(text: string): TargetInterviewResponse
 // Export the parse function for tests
 export { parseTargetInterviewResponseImpl as parseTargetInterviewResponse };

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AgentResult = any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

-async function initEngine() {
-  if (!createFnAgent) {
-    try {
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      // Allow failure in test environments
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 // ── Constants ───────────────────────────────────────────────────────────────
--- a/packages/dashboard/src/mission-interview.ts
+++ b/packages/dashboard/src/mission-interview.ts
@@ -27,11 +27,12 @@ import {
  nonfatal,
 } from "./ai-session-diagnostics.js";

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AgentResult = any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

 /**
 * Shared diagnostics helper for the mission-interview module.
@@ -64,23 +65,8 @@ export function __setMissionInterviewDiagnostics(_logger: unknown): void {
  }
 }

-async function initEngine() {
-  if (!createFnAgent) {
-    try {
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      // Allow failure in test environments
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 // ── Constants ───────────────────────────────────────────────────────────────
--- a/packages/dashboard/src/planning.ts
+++ b/packages/dashboard/src/planning.ts
@@ -30,12 +30,17 @@ import {
  resetDiagnosticsSink,
  nonfatal,
 } from "./ai-session-diagnostics.js";
+import {
+  createFnAgent as engineCreateFnAgent,
+  isNtfyEventEnabled as engineIsNtfyEventEnabled,
+  buildNtfyClickUrl as engineBuildNtfyClickUrl,
+  sendNtfyNotification as engineSendNtfyNotification,
+} from "@fusion/engine";

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AgentResult = any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

 interface PlanningNtfyConfig {
  enabled: boolean;
@@ -58,8 +63,11 @@ interface PlanningNtfyHelpers {
  }) => Promise<void>;
 }

-let planningNtfyHelpers: PlanningNtfyHelpers | undefined;
-let ntfyHelpersReady: Promise<void> | undefined;
+let planningNtfyHelpers: PlanningNtfyHelpers | undefined = {
+  isNtfyEventEnabled: engineIsNtfyEventEnabled,
+  buildNtfyClickUrl: engineBuildNtfyClickUrl,
+  sendNtfyNotification: engineSendNtfyNotification,
+};

 /**
 * Shared diagnostics helper for the planning module.
@@ -92,39 +100,12 @@ export function __setPlanningDiagnostics(_logger: unknown): void {
  }
 }

-// Initialize the import (this runs in actual server, mocked in tests)
-async function initEngine() {
-  try {
-    // Use dynamic import with variable to prevent static analysis
-    const engineModule = "@fusion/engine";
-    const engine = await import(/* @vite-ignore */ engineModule);
-    if (!createFnAgent) {
-      createFnAgent = engine.createFnAgent;
-    }
-    if (!planningNtfyHelpers) {
-      planningNtfyHelpers = {
-        isNtfyEventEnabled: engine.isNtfyEventEnabled,
-        buildNtfyClickUrl: engine.buildNtfyClickUrl,
-        sendNtfyNotification: engine.sendNtfyNotification,
-      };
-    }
-  } catch {
-    // Allow failure in test environments - agent functionality will be stubbed
-    if (!createFnAgent) {
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 async function ensureNtfyHelpersReady(): Promise<void> {
-  ntfyHelpersReady ??= initEngine();
-  await ntfyHelpersReady;
+  // Helpers are bound statically at module load; nothing to await.
 }

 // ── Constants ───────────────────────────────────────────────────────────────
@@ -1712,8 +1693,11 @@ export function __resetPlanningState(): void {
  _aiSessionDeletedListener = undefined;
  _aiSessionStore = undefined;

-  planningNtfyHelpers = undefined;
-  ntfyHelpersReady = undefined;
+  planningNtfyHelpers = {
+    isNtfyEventEnabled: engineIsNtfyEventEnabled,
+    buildNtfyClickUrl: engineBuildNtfyClickUrl,
+    sendNtfyNotification: engineSendNtfyNotification,
+  };

  // Reset diagnostics sink to default
  resetDiagnosticsSink();
@@ -1729,7 +1713,6 @@ export function __setCreateFnAgent(mock: typeof createFnAgent): void {
 /** Inject ntfy helper implementations (test-only). */
 export function __setPlanningNtfyHelpers(mock: PlanningNtfyHelpers | undefined): void {
  planningNtfyHelpers = mock;
-  ntfyHelpersReady = undefined;
 }

 // ── Custom Errors ───────────────────────────────────────────────────────────
--- a/packages/dashboard/src/roadmap-suggestions.ts
+++ b/packages/dashboard/src/roadmap-suggestions.ts
@@ -13,38 +13,13 @@
 * - Error mapping (validation 400, not found 404, AI/parser 500/503)
 */

-// Dynamic import for @fusion/engine to avoid resolution issues in test environment
+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
+let createFnAgent: any = engineCreateFnAgent;

-// Track if engine has been initialized (prevents multiple imports)
-let engineInitialized = false;
-
-// Flag to indicate if createFnAgent was explicitly set (even to undefined)
-let createFnAgentExplicitlySet = false;
-
-// Initialize the import (this runs in actual server, mocked in tests)
 async function initEngine(): Promise<void> {
-  if (engineInitialized) return;
-
-  // If createFnAgent was explicitly set (even to undefined), don't try to import
-  if (createFnAgentExplicitlySet) {
-    engineInitialized = true;
-    return;
-  }
-
-  if (!createFnAgent) {
-    try {
-      // Use dynamic import with variable to prevent static analysis
-      const engineModule = "@fusion/engine";
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      // Allow failure in test environments - agent functionality will be stubbed
-      createFnAgent = undefined;
-    }
-  }
-  engineInitialized = true;
+  // Engine is statically imported; nothing to do.
 }

 // ── Types ───────────────────────────────────────────────────────────────────
@@ -893,9 +868,7 @@ export class ServiceUnavailableError extends Error {
 * Reset module state. Used for testing only.
 */
 export function __resetSuggestionState(): void {
-  createFnAgent = undefined;
-  engineInitialized = false;
-  createFnAgentExplicitlySet = false;
+  createFnAgent = engineCreateFnAgent;
 }

 /**
@@ -903,5 +876,4 @@ export function __resetSuggestionState(): void {
 */
 export function __setCreateFnAgent(mock: typeof createFnAgent): void {
  createFnAgent = mock;
-  createFnAgentExplicitlySet = true;
 }
--- a/packages/dashboard/src/routes.ts
+++ b/packages/dashboard/src/routes.ts
@@ -218,8 +218,10 @@ async function discoverDashboardPiExtensions(cwd: string): Promise<PiExtensionSe
  };
 }

-// Dynamic import fallback for @fusion/engine with injectable override for tests.
-let createFnAgentForRefine: typeof import("@fusion/engine").createFnAgent | undefined;
+import { createFnAgent as engineCreateFnAgentForRefine } from "@fusion/engine";
+
+// Test-injectable override; defaults to the statically imported engine binding.
+let createFnAgentForRefine: typeof import("@fusion/engine").createFnAgent | undefined = engineCreateFnAgentForRefine;

 /** @internal Inject a mock createFnAgent function for workflow-step refine route tests. */
 export function __setCreateFnAgentForRefine(mock: typeof createFnAgentForRefine): void {
@@ -2513,13 +2515,7 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
      // Use AI to refine the description into a detailed agent prompt
      let refinedPrompt: string;
      try {
-        let createFnAgent = createFnAgentForRefine;
-        if (!createFnAgent) {
-          // Dynamic import to avoid resolution issues in tests
-          const engineModule = "@fusion/engine";
-          const engine = await import(/* @vite-ignore */ engineModule);
-          createFnAgent = engine.createFnAgent;
-        }
+        const createFnAgent = createFnAgentForRefine;

        const settings = await scopedStore.getSettings();

--- a/packages/dashboard/src/subtask-breakdown.ts
+++ b/packages/dashboard/src/subtask-breakdown.ts
@@ -9,9 +9,10 @@ import {
  resetDiagnosticsSink,
 } from "./ai-session-diagnostics.js";

+import { createFnAgent as engineCreateFnAgent } from "@fusion/engine";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let createFnAgent: any;
-const engineModule = "@fusion/engine";
+let createFnAgent: any = engineCreateFnAgent;

 /**
 * Shared diagnostics helper for the subtask-breakdown module.
@@ -45,21 +46,8 @@ export function __setSubtaskBreakdownDiagnostics(_logger: unknown): void {
  }
 }

-async function initEngine() {
-  if (!createFnAgent) {
-    try {
-      const engine = await import(/* @vite-ignore */ engineModule);
-      createFnAgent = engine.createFnAgent;
-    } catch {
-      createFnAgent = undefined;
-    }
-  }
-}
-
-let engineReady: Promise<void> | undefined;
-function ensureEngineReady() {
-  engineReady ??= initEngine();
-  return engineReady;
+function ensureEngineReady(): Promise<void> {
+  return Promise.resolve();
 }

 export interface SubtaskItem {
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -18,6 +18,13 @@ export { MissionExecutionLoop, type MissionExecutionLoopOptions, type Validation
 export { aiMergeTask, type MergerOptions } from "./merger.js";
 export { reviewStep, type ReviewType, type ReviewVerdict, type ReviewResult, type ReviewOptions } from "./reviewer.js";
 export { createFnAgent, promptWithFallback, describeModel, setHostExtensionPaths, getHostExtensionPaths, type AgentOptions, type AgentResult } from "./pi.js";
+
+// Register createFnAgent into core's loader so consumers in @fusion/core
+// (e.g. ai-summarize, memory-compaction) can resolve it without a circular
+// static import. Runs once at engine module load.
+import { setCreateFnAgent } from "@fusion/core";
+import { createFnAgent as _createFnAgentForCore } from "./pi.js";
+setCreateFnAgent(_createFnAgentForCore);
 export {
  resolveSessionSkills,
  createSkillsOverrideFromSelection,