@donkeylabs/server 2.0.22 → 2.0.23

package/docs/workflows.md

@@ -487,6 +487,37 @@ ctx.core.workflows.register(myWorkflow);
 
 > **Advanced:** The module path is captured automatically when you call `.build()`. If you re-export a workflow definition from a different module, pass `{ modulePath: import.meta.url }` explicitly so the subprocess can find the definition.
 
+#### Isolated Plugin Initialization
+
+In isolated mode, the subprocess **boots a full plugin manager** and runs plugin `init` hooks locally. This means your workflow handlers can use `ctx.plugins` without IPC fallbacks, and cron/jobs/workflows/services registered in `init` are available inside the subprocess.
+
+Requirements:
+- Plugin modules must be discoverable from their module path (captured during `createPlugin.define()` / `pluginFactory()` calls).
+- Plugin configs and `ctx.core.config` must be JSON-serializable.
+
+```typescript
+// plugins/reports/index.ts
+export const reportsPlugin = createPlugin.define({
+  name: "reports",
+  service: async (ctx) => ({
+    generate: async (id: string) => ctx.db.selectFrom("reports").selectAll().execute(),
+  }),
+  init: async (ctx) => {
+    ctx.core.jobs.register("reports.generate", async () => undefined);
+  },
+});
+
+// workflows/report.ts
+export const reportWorkflow = workflow("report.generate")
+  .task("run", {
+    handler: async (input, ctx) => {
+      const data = await ctx.plugins.reports.generate(input.reportId);
+      return { data };
+    },
+  })
+  .build();
+```
+
 ### Inline Mode
 
 For lightweight workflows that complete quickly, you can opt into inline execution:
@@ -512,7 +543,7 @@ ctx.core.workflows.register(quickWorkflow);
 |---|---|---|
 | Step types | All (task, choice, parallel, pass) | All (task, choice, parallel, pass) |
 | Event loop | Separate process, won't block server | Runs on main thread |
-| Plugin access | Via IPC proxy | Direct access |
+| Plugin access | Local plugin services in subprocess | Direct access |
 | Best for | Long-running, CPU-intensive workflows | Quick validations, lightweight flows |
 | Setup | `workflows.register(wf)` | `workflows.register(wf)` |
 
@@ -545,6 +576,9 @@ interface Workflows {
 
   /** Stop the workflow service */
   stop(): Promise<void>;
+
+  /** Set plugin metadata for isolated workflows (AppServer sets this automatically) */
+  setPluginMetadata(metadata: PluginMetadata): void;
 }
 
 interface WorkflowRegisterOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.22",
+  "version": "2.0.23",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/index.ts

@@ -149,6 +149,7 @@ export {
   type PassStepDefinition,
   type RetryConfig,
   type GetAllWorkflowsOptions,
+  type PluginMetadata,
   WorkflowBuilder,
   MemoryWorkflowAdapter,
   workflow,

package/src/core/subprocess-bootstrap.ts

@@ -0,0 +1,241 @@
+import { Kysely } from "kysely";
+import { BunSqliteDialect } from "kysely-bun-sqlite";
+import Database from "bun:sqlite";
+import {
+  createLogger,
+  createCache,
+  createEvents,
+  createCron,
+  createJobs,
+  createSSE,
+  createRateLimiter,
+  createErrors,
+  createWorkflows,
+  createProcesses,
+  createAudit,
+  createWebSocket,
+  createStorage,
+  createLogs,
+  KyselyJobAdapter,
+  KyselyWorkflowAdapter,
+  MemoryAuditAdapter,
+  MemoryLogsAdapter,
+} from "./index";
+import { PluginManager, type CoreServices, type ConfiguredPlugin } from "../core";
+
+export interface SubprocessPluginMetadata {
+  names: string[];
+  modulePaths: Record<string, string>;
+  configs: Record<string, any>;
+}
+
+export interface SubprocessBootstrapOptions {
+  dbPath: string;
+  coreConfig?: Record<string, any>;
+  pluginMetadata: SubprocessPluginMetadata;
+  startServices?: {
+    cron?: boolean;
+    jobs?: boolean;
+    workflows?: boolean;
+    processes?: boolean;
+  };
+}
+
+export interface SubprocessBootstrapResult {
+  core: CoreServices;
+  manager: PluginManager;
+  db: Kysely<any>;
+  workflowAdapter: KyselyWorkflowAdapter;
+  cleanup: () => Promise<void>;
+}
+
+export async function bootstrapSubprocess(
+  options: SubprocessBootstrapOptions
+): Promise<SubprocessBootstrapResult> {
+  const sqlite = new Database(options.dbPath);
+  sqlite.run("PRAGMA busy_timeout = 5000");
+
+  const db = new Kysely<any>({
+    dialect: new BunSqliteDialect({ database: sqlite }),
+  });
+
+  const cache = createCache();
+  const events = createEvents();
+  const sse = createSSE();
+  const rateLimiter = createRateLimiter();
+  const errors = createErrors();
+
+  const logs = createLogs({ adapter: new MemoryLogsAdapter(), events });
+  const logger = createLogger();
+
+  const cron = createCron({ logger });
+
+  const jobAdapter = new KyselyJobAdapter(db, { cleanupDays: 0 });
+  const workflowAdapter = new KyselyWorkflowAdapter(db, { cleanupDays: 0 });
+  const auditAdapter = new MemoryAuditAdapter();
+
+  const jobs = createJobs({
+    events,
+    logger,
+    adapter: jobAdapter,
+    persist: false,
+  });
+
+  const workflows = createWorkflows({
+    events,
+    jobs,
+    sse,
+    adapter: workflowAdapter,
+  });
+
+  const processes = createProcesses({ events, autoRecoverOrphans: false });
+  const audit = createAudit({ adapter: auditAdapter });
+  const websocket = createWebSocket();
+  const storage = createStorage();
+
+  const core: CoreServices = {
+    db,
+    config: options.coreConfig ?? {},
+    logger,
+    cache,
+    events,
+    cron,
+    jobs,
+    sse,
+    rateLimiter,
+    errors,
+    workflows,
+    processes,
+    audit,
+    websocket,
+    storage,
+    logs,
+  };
+
+  workflows.setCore(core);
+
+  const manager = new PluginManager(core);
+  const plugins = await loadConfiguredPlugins(options.pluginMetadata);
+
+  for (const plugin of plugins) {
+    manager.register(plugin);
+  }
+
+  await manager.init();
+  workflows.setPlugins(manager.getServices());
+
+  if (options.startServices?.cron) {
+    core.cron.start();
+  }
+  if (options.startServices?.jobs) {
+    core.jobs.start();
+  }
+  if (options.startServices?.workflows) {
+    await core.workflows.resolveDbPath();
+    await core.workflows.resume();
+  }
+  if (options.startServices?.processes) {
+    core.processes.start();
+  }
+
+  const cleanup = async () => {
+    await core.cron.stop();
+    await core.jobs.stop();
+    await core.workflows.stop();
+    await core.processes.shutdown();
+
+    if (typeof (logs as any).stop === "function") {
+      (logs as any).stop();
+    }
+
+    if (typeof (audit as any).stop === "function") {
+      (audit as any).stop();
+    }
+
+    await db.destroy();
+    sqlite.close();
+  };
+
+  return { core, manager, db, workflowAdapter, cleanup };
+}
+
+async function loadConfiguredPlugins(
+  metadata: SubprocessPluginMetadata
+): Promise<ConfiguredPlugin[]> {
+  const plugins: ConfiguredPlugin[] = [];
+
+  for (const name of metadata.names) {
+    const modulePath = metadata.modulePaths[name];
+    if (!modulePath) {
+      throw new Error(`Missing module path for plugin "${name}"`);
+    }
+
+    const module = await import(modulePath);
+    const config = metadata.configs?.[name];
+    const plugin = findPluginDefinition(module, name, config);
+
+    if (!plugin) {
+      throw new Error(
+        `Plugin "${name}" not found in module ${modulePath}. ` +
+          `Ensure the plugin is exported and its config is serializable.`
+      );
+    }
+
+    plugins.push(plugin);
+  }
+
+  return plugins;
+}
+
+function findPluginDefinition(
+  mod: any,
+  pluginName: string,
+  boundConfig?: any
+): ConfiguredPlugin | null {
+  for (const key of Object.keys(mod)) {
+    const exported = mod[key];
+    const direct = resolvePluginDefinition(exported, pluginName, boundConfig);
+    if (direct) return direct;
+  }
+
+  if (mod.default) {
+    const direct = resolvePluginDefinition(mod.default, pluginName, boundConfig);
+    if (direct) return direct;
+  }
+
+  return null;
+}
+
+function resolvePluginDefinition(
+  exported: any,
+  pluginName: string,
+  boundConfig?: any
+): ConfiguredPlugin | null {
+  if (!exported) return null;
+
+  if (
+    typeof exported === "object" &&
+    exported.name === pluginName &&
+    typeof exported.service === "function"
+  ) {
+    return exported as ConfiguredPlugin;
+  }
+
+  if (typeof exported === "function" && boundConfig !== undefined) {
+    try {
+      const result = exported(boundConfig);
+      if (
+        result &&
+        typeof result === "object" &&
+        result.name === pluginName &&
+        typeof result.service === "function"
+      ) {
+        return result as ConfiguredPlugin;
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}

package/src/core/workflow-executor.ts

@@ -1,18 +1,13 @@
 #!/usr/bin/env bun
 // Workflow Executor - Subprocess Entry Point
-// Thin shell that creates a WorkflowStateMachine with IPC event bridge.
-// The state machine owns all execution logic and persistence.
+// Bootstraps core services and plugins locally for isolated workflows.
 
 import { connect } from "node:net";
 import type { Socket } from "node:net";
-import { Kysely } from "kysely";
-import { BunSqliteDialect } from "kysely-bun-sqlite";
-import Database from "bun:sqlite";
 import type { WorkflowEvent } from "./workflow-socket";
-import { WorkflowProxyConnection, createPluginsProxy, createCoreServicesProxy } from "./workflow-proxy";
 import type { WorkflowDefinition } from "./workflows";
-import { KyselyWorkflowAdapter } from "./workflow-adapter-kysely";
 import { WorkflowStateMachine, type StateMachineEvents } from "./workflow-state-machine";
+import { bootstrapSubprocess } from "./subprocess-bootstrap";
 
 // ============================================
 // Types
@@ -26,6 +21,10 @@ interface ExecutorConfig {
   tcpPort?: number;
   modulePath: string;
   dbPath: string;
+  pluginNames: string[];
+  pluginModulePaths: Record<string, string>;
+  pluginConfigs: Record<string, any>;
+  coreConfig?: Record<string, any>;
 }
 
 // ============================================
@@ -37,19 +36,23 @@ async function main(): Promise<void> {
   const stdin = await Bun.stdin.text();
   const config: ExecutorConfig = JSON.parse(stdin);
 
-  const { instanceId, workflowName, socketPath, tcpPort, modulePath, dbPath } = config;
+  const {
+    instanceId,
+    workflowName,
+    socketPath,
+    tcpPort,
+    modulePath,
+    dbPath,
+    pluginNames,
+    pluginModulePaths,
+    pluginConfigs,
+    coreConfig,
+  } = config;
 
-  // Connect to IPC socket
   const socket = await connectToSocket(socketPath, tcpPort);
-  const proxyConnection = new WorkflowProxyConnection(socket);
 
-  // Create database connection + adapter (subprocess owns its own persistence)
-  const sqlite = new Database(dbPath);
-  sqlite.run("PRAGMA busy_timeout = 5000");
-  const db = new Kysely<any>({
-    dialect: new BunSqliteDialect({ database: sqlite }),
-  });
-  const adapter = new KyselyWorkflowAdapter(db, { cleanupDays: 0 });
+  let cleanup: (() => Promise<void>) | undefined;
+  let exitCode = 0;
 
   // Start heartbeat
   const heartbeatInterval = setInterval(() => {
@@ -61,39 +64,41 @@ async function main(): Promise<void> {
   }, 5000);
 
   try {
-    // Send started event
-    sendEvent(socket, {
-      type: "started",
-      instanceId,
-      timestamp: Date.now(),
-    });
-
     // Import the workflow module to get the definition
     const module = await import(modulePath);
     const definition = findWorkflowDefinition(module, workflowName, modulePath);
 
-    // Create proxy objects for plugin/core access via IPC
-    const plugins = createPluginsProxy(proxyConnection);
-    const coreServices = createCoreServicesProxy(proxyConnection);
-
-    // Wrap coreServices proxy so that `db` resolves locally instead of via IPC.
-    // Spreading a Proxy with no ownKeys trap loses all proxied properties.
-    const coreWithDb = new Proxy(coreServices, {
-      get(target, prop, receiver) {
-        if (prop === "db") return db;
-        return Reflect.get(target, prop, receiver);
+    const bootstrap = await bootstrapSubprocess({
+      dbPath,
+      coreConfig,
+      pluginMetadata: {
+        names: pluginNames,
+        modulePaths: pluginModulePaths,
+        configs: pluginConfigs,
       },
     });
+    cleanup = bootstrap.cleanup;
+
+    sendEvent(socket, {
+      type: "ready",
+      instanceId,
+      timestamp: Date.now(),
+    });
 
-    // Create state machine with IPC event bridge
     const sm = new WorkflowStateMachine({
-      adapter,
-      core: coreWithDb as any,
-      plugins,
+      adapter: bootstrap.workflowAdapter,
+      core: bootstrap.core as any,
+      plugins: bootstrap.manager.getServices(),
       events: createIpcEventBridge(socket, instanceId),
       pollInterval: 1000,
     });
 
+    sendEvent(socket, {
+      type: "started",
+      instanceId,
+      timestamp: Date.now(),
+    });
+
     // Run the state machine to completion
     const result = await sm.run(instanceId, definition);
 
@@ -112,16 +117,16 @@ async function main(): Promise<void> {
       timestamp: Date.now(),
       error: error instanceof Error ? error.message : String(error),
     });
-    process.exit(1);
+    exitCode = 1;
   } finally {
     clearInterval(heartbeatInterval);
-    proxyConnection.close();
     socket.end();
-    adapter.stop();
-    await db.destroy();
+    if (cleanup) {
+      await cleanup();
+    }
   }
 
-  process.exit(0);
+  process.exit(exitCode);
 }
 
 // ============================================

package/src/core/workflow-socket.ts

@@ -12,6 +12,7 @@ import { createServer as createNetServer } from "node:net";
 // ============================================
 
 export type WorkflowEventType =
+  | "ready"
   | "started"
   | "heartbeat"
   | "step.started"

package/src/core/workflows.ts

@@ -640,6 +640,8 @@ export interface WorkflowsConfig {
   dbPath?: string;
   /** Heartbeat timeout in ms (default: 60000) */
   heartbeatTimeout?: number;
+  /** Timeout waiting for isolated subprocess readiness (ms, default: 10000) */
+  readyTimeout?: number;
 }
 
 /** Options for registering a workflow */
@@ -689,6 +691,16 @@ export interface Workflows {
   setPlugins(plugins: Record<string, any>): void;
   /** Update metadata for a workflow instance (used by isolated workflows) */
   updateMetadata(instanceId: string, key: string, value: any): Promise<void>;
+  /** Set plugin metadata for local instantiation in isolated workflows */
+  setPluginMetadata(metadata: PluginMetadata): void;
+}
+
+export interface PluginMetadata {
+  names: string[];
+  modulePaths: Record<string, string>;
+  configs: Record<string, any>;
+  dependencies: Record<string, string[]>;
+  customErrors: Record<string, Record<string, any>>;
 }
 
 // ============================================
@@ -719,8 +731,25 @@ class WorkflowsImpl implements Workflows {
   private tcpPortRange: [number, number];
   private dbPath?: string;
   private heartbeatTimeoutMs: number;
+  private readyTimeoutMs: number;
   private workflowModulePaths = new Map<string, string>();
   private isolatedProcesses = new Map<string, IsolatedProcessInfo>();
+  private readyWaiters = new Map<
+    string,
+    {
+      promise: Promise<void>;
+      resolve: () => void;
+      reject: (error: Error) => void;
+      timeout: ReturnType<typeof setTimeout>;
+    }
+  >();
+
+  // Plugin metadata for local instantiation in isolated workflows
+  private pluginNames: string[] = [];
+  private pluginModulePaths: Record<string, string> = {};
+  private pluginConfigs: Record<string, any> = {};
+  private pluginDependencies: Record<string, string[]> = {};
+  private pluginCustomErrors: Record<string, Record<string, any>> = {};
 
   constructor(config: WorkflowsConfig = {}) {
     this.adapter = config.adapter ?? new MemoryWorkflowAdapter();
@@ -735,6 +764,7 @@ class WorkflowsImpl implements Workflows {
     this.tcpPortRange = config.tcpPortRange ?? [49152, 65535];
     this.dbPath = config.dbPath;
     this.heartbeatTimeoutMs = config.heartbeatTimeout ?? 60000;
+    this.readyTimeoutMs = config.readyTimeout ?? 10000;
   }
 
   private getSocketServer(): WorkflowSocketServer {
@@ -786,6 +816,14 @@ class WorkflowsImpl implements Workflows {
     this.plugins = plugins;
   }
 
+  setPluginMetadata(metadata: PluginMetadata): void {
+    this.pluginNames = metadata.names;
+    this.pluginModulePaths = metadata.modulePaths;
+    this.pluginConfigs = metadata.configs;
+    this.pluginDependencies = metadata.dependencies;
+    this.pluginCustomErrors = metadata.customErrors;
+  }
+
   async updateMetadata(instanceId: string, key: string, value: any): Promise<void> {
     const instance = await this.adapter.getInstance(instanceId);
     if (!instance) return;
@@ -855,7 +893,7 @@ class WorkflowsImpl implements Workflows {
 
     if (isIsolated && modulePath && this.dbPath) {
       // Execute in isolated subprocess
-      this.executeIsolatedWorkflow(instance.id, definition, input, modulePath);
+      await this.executeIsolatedWorkflow(instance.id, definition, input, modulePath);
     } else {
       // Execute inline using state machine
       if (isIsolated && !modulePath) {
@@ -952,7 +990,14 @@ class WorkflowsImpl implements Workflows {
       const modulePath = this.workflowModulePaths.get(instance.workflowName);
 
       if (isIsolated && modulePath && this.dbPath) {
-        this.executeIsolatedWorkflow(instance.id, definition, instance.input, modulePath);
+        try {
+          await this.executeIsolatedWorkflow(instance.id, definition, instance.input, modulePath);
+        } catch (error) {
+          console.error(
+            `[Workflows] Failed to resume isolated workflow ${instance.id}:`,
+            error instanceof Error ? error.message : String(error)
+          );
+        }
       } else {
         this.startInlineWorkflow(instance.id, definition);
       }
@@ -989,6 +1034,12 @@ class WorkflowsImpl implements Workflows {
     }
     this.running.clear();
 
+    for (const [instanceId, waiter] of this.readyWaiters) {
+      clearTimeout(waiter.timeout);
+      waiter.reject(new Error(`Workflows stopped before ready: ${instanceId}`));
+    }
+    this.readyWaiters.clear();
+
     // Stop adapter (cleanup timers and prevent further DB access)
     if (this.adapter && typeof (this.adapter as any).stop === "function") {
       (this.adapter as any).stop();
@@ -1182,20 +1233,36 @@ class WorkflowsImpl implements Workflows {
   ): Promise<void> {
     const socketServer = this.getSocketServer();
 
+    const pluginNames = this.pluginNames.length > 0
+      ? this.pluginNames
+      : Object.keys(this.pluginModulePaths);
+
+    if (pluginNames.length === 0 && Object.keys(this.plugins).length > 0) {
+      throw new Error(
+        "[Workflows] Plugin metadata is required for isolated workflows. " +
+          "Call workflows.setPluginMetadata() during server initialization."
+      );
+    }
+
+    const missingModulePaths = pluginNames.filter((name) => !this.pluginModulePaths[name]);
+    if (missingModulePaths.length > 0) {
+      throw new Error(
+        `[Workflows] Missing module paths for plugins: ${missingModulePaths.join(", ")}. ` +
+          `Ensure plugins are created with createPlugin.define() and registered before workflows start.`
+      );
+    }
+
+    const pluginConfigs = serializePluginConfigsOrThrow(this.pluginConfigs, pluginNames);
+    const coreConfig = serializeCoreConfigOrThrow(this.core?.config);
+
     // Create socket for this workflow instance
     const { socketPath, tcpPort } = await socketServer.createSocket(instanceId);
 
-    // Mark workflow as running
-    await this.adapter.updateInstance(instanceId, {
-      status: "running",
-      startedAt: new Date(),
-    });
-
     // Get the executor path
     const currentDir = dirname(fileURLToPath(import.meta.url));
     const executorPath = join(currentDir, "workflow-executor.ts");
 
-    // Prepare config for the executor
+    // Prepare config for the executor, including plugin metadata for local instantiation
     const config = {
       instanceId,
       workflowName: definition.name,
@@ -1204,6 +1271,10 @@ class WorkflowsImpl implements Workflows {
       tcpPort,
       modulePath,
       dbPath: this.dbPath,
+      pluginNames,
+      pluginModulePaths: this.pluginModulePaths,
+      pluginConfigs,
+      coreConfig,
     };
 
     // Spawn the subprocess
@@ -1240,6 +1311,19 @@ class WorkflowsImpl implements Workflows {
     // Set up heartbeat timeout
     this.resetHeartbeatTimeout(instanceId, proc.pid);
 
+    const exitBeforeReady = proc.exited.then((exitCode) => {
+      throw new Error(`Subprocess exited before ready (code ${exitCode})`);
+    });
+
+    try {
+      await Promise.race([this.waitForIsolatedReady(instanceId), exitBeforeReady]);
+    } catch (error) {
+      await this.handleIsolatedStartFailure(instanceId, proc.pid, error);
+      exitBeforeReady.catch(() => undefined);
+      throw error;
+    }
+    exitBeforeReady.catch(() => undefined);
+
     // Handle process exit
     proc.exited.then(async (exitCode) => {
       const info = this.isolatedProcesses.get(instanceId);
@@ -1250,9 +1334,9 @@ class WorkflowsImpl implements Workflows {
       }
       await socketServer.closeSocket(instanceId);
 
-      // Check if workflow is still running (crashed before completion)
+      // Check if workflow is still pending/running (crashed before completion)
       const instance = await this.adapter.getInstance(instanceId);
-      if (instance && instance.status === "running") {
+      if (instance && (instance.status === "running" || instance.status === "pending")) {
         console.error(`[Workflows] Isolated workflow ${instanceId} crashed with exit code ${exitCode}`);
         await this.adapter.updateInstance(instanceId, {
           status: "failed",
@@ -1293,6 +1377,11 @@ class WorkflowsImpl implements Workflows {
     }
 
     switch (type) {
+      case "ready": {
+        this.resolveIsolatedReady(instanceId);
+        break;
+      }
+
       case "started":
       case "heartbeat":
         // No-op: heartbeat handled above, started is handled by executeIsolatedWorkflow
@@ -1382,6 +1471,7 @@ class WorkflowsImpl implements Workflows {
       case "completed": {
         // Clean up isolated process tracking
         this.cleanupIsolatedProcess(instanceId);
+        this.resolveIsolatedReady(instanceId);
 
         // Subprocess already persisted state - just emit events
         await this.emitEvent("workflow.completed", {
@@ -1398,6 +1488,7 @@ class WorkflowsImpl implements Workflows {
       case "failed": {
         // Clean up isolated process tracking
         this.cleanupIsolatedProcess(instanceId);
+        this.rejectIsolatedReady(instanceId, new Error(event.error ?? "Isolated workflow failed"));
 
         // Subprocess already persisted state - just emit events
         await this.emitEvent("workflow.failed", {
@@ -1416,6 +1507,91 @@ class WorkflowsImpl implements Workflows {
     }
   }
 
+  private waitForIsolatedReady(instanceId: string): Promise<void> {
+    const existing = this.readyWaiters.get(instanceId);
+    if (existing) {
+      return existing.promise;
+    }
+
+    let resolveFn!: () => void;
+    let rejectFn!: (error: Error) => void;
+    const promise = new Promise<void>((resolve, reject) => {
+      resolveFn = resolve;
+      rejectFn = reject;
+    });
+
+    const timeout = setTimeout(() => {
+      this.readyWaiters.delete(instanceId);
+      rejectFn(new Error(`Timed out waiting for isolated workflow ${instanceId} readiness`));
+    }, this.readyTimeoutMs);
+
+    this.readyWaiters.set(instanceId, {
+      promise,
+      resolve: () => resolveFn(),
+      reject: (error) => rejectFn(error),
+      timeout,
+    });
+
+    return promise;
+  }
+
+  private resolveIsolatedReady(instanceId: string): void {
+    const waiter = this.readyWaiters.get(instanceId);
+    if (!waiter) return;
+    clearTimeout(waiter.timeout);
+    this.readyWaiters.delete(instanceId);
+    waiter.resolve();
+  }
+
+  private rejectIsolatedReady(instanceId: string, error: Error): void {
+    const waiter = this.readyWaiters.get(instanceId);
+    if (!waiter) return;
+    clearTimeout(waiter.timeout);
+    this.readyWaiters.delete(instanceId);
+    waiter.reject(error);
+  }
+
+  private async handleIsolatedStartFailure(
+    instanceId: string,
+    pid: number,
+    error: unknown
+  ): Promise<void> {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // Process might already be dead
+    }
+
+    this.cleanupIsolatedProcess(instanceId);
+    await this.getSocketServer().closeSocket(instanceId);
+
+    const instance = await this.adapter.getInstance(instanceId);
+    if (instance && (instance.status === "pending" || instance.status === "running")) {
+      await this.adapter.updateInstance(instanceId, {
+        status: "failed",
+        error: errorMessage,
+        completedAt: new Date(),
+      });
+
+      await this.emitEvent("workflow.failed", {
+        instanceId,
+        workflowName: instance.workflowName,
+        error: errorMessage,
+      });
+
+      if (this.sse) {
+        this.sse.broadcast(`workflow:${instanceId}`, "failed", { error: errorMessage });
+        this.sse.broadcast("workflows:all", "workflow.failed", {
+          instanceId,
+          workflowName: instance.workflowName,
+          error: errorMessage,
+        });
+      }
+    }
+  }
+
   /**
    * Handle proxy calls from isolated subprocess
    */
@@ -1460,6 +1636,7 @@ class WorkflowsImpl implements Workflows {
       if (info.heartbeatTimeout) clearTimeout(info.heartbeatTimeout);
       this.isolatedProcesses.delete(instanceId);
     }
+    this.rejectIsolatedReady(instanceId, new Error("Isolated workflow cleaned up"));
   }
 
   /**
@@ -1532,6 +1709,102 @@ class WorkflowsImpl implements Workflows {
   }
 }
 
+// ============================================
+// Helpers
+// ============================================
+
+function serializePluginConfigsOrThrow(
+  configs: Record<string, any>,
+  pluginNames: string[]
+): Record<string, any> {
+  const result: Record<string, any> = {};
+  const failures: string[] = [];
+
+  for (const name of pluginNames) {
+    if (!(name in configs)) continue;
+    try {
+      assertJsonSerializable(configs[name], `pluginConfigs.${name}`);
+      const serialized = JSON.stringify(configs[name]);
+      result[name] = JSON.parse(serialized);
+    } catch {
+      failures.push(name);
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(
+      `[Workflows] Non-serializable plugin config(s): ${failures.join(", ")}. ` +
+        `Provide JSON-serializable configs for isolated workflows.`
+    );
+  }
+
+  return result;
+}
+
+function serializeCoreConfigOrThrow(config?: Record<string, any>): Record<string, any> | undefined {
+  if (!config) return undefined;
+  try {
+    assertJsonSerializable(config, "coreConfig");
+    const serialized = JSON.stringify(config);
+    return JSON.parse(serialized);
+  } catch {
+    throw new Error(
+      "[Workflows] Core config is not JSON-serializable. Provide JSON-serializable values for isolated workflows."
+    );
+  }
+}
+
+function assertJsonSerializable(value: any, path: string, seen = new WeakSet<object>()): void {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return;
+  }
+
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
+    throw new Error(`[Workflows] Non-serializable value at ${path}`);
+  }
+
+  if (typeof value === "bigint") {
+    throw new Error(`[Workflows] Non-serializable bigint at ${path}`);
+  }
+
+  if (value instanceof Date) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      assertJsonSerializable(value[i], `${path}[${i}]`, seen);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      throw new Error(`[Workflows] Circular reference at ${path}`);
+    }
+    seen.add(value);
+
+    if (!isPlainObject(value)) {
+      throw new Error(`[Workflows] Non-serializable object at ${path}`);
+    }
+
+    for (const [key, nested] of Object.entries(value)) {
+      assertJsonSerializable(nested, `${path}.${key}`, seen);
+    }
+    return;
+  }
+}
+
+function isPlainObject(value: Record<string, any>): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 // ============================================
 // Factory Function
 // ============================================

package/src/core.ts

@@ -1,7 +1,7 @@
 import { sql, type Kysely } from "kysely";
 import { readdir } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import type { z } from "zod";
 import type { Logger } from "./core/logger";
 import type { Cache } from "./core/cache";
@@ -18,6 +18,32 @@ import type { WebSocketService } from "./core/websocket";
 import type { Storage } from "./core/storage";
 import type { Logs } from "./core/logs";
 
+// ============================================
+// Auto-detect caller module for plugin define()
+// ============================================
+
+const CORE_FILE = resolve(fileURLToPath(import.meta.url));
+
+/**
+ * Walk the call stack to find the file that invoked define().
+ * Returns a file:// URL string or undefined if detection fails.
+ * Skips frames originating from this file (core.ts).
+ */
+function captureCallerUrl(): string | undefined {
+  const stack = new Error().stack ?? "";
+  for (const line of stack.split("\n").slice(1)) {
+    const match = line.match(/at\s+(?:.*?\s+\(?)?([^\s():]+):\d+:\d+/);
+    if (match) {
+      let filePath = match[1];
+      if (filePath.startsWith("file://")) filePath = fileURLToPath(filePath);
+      if (filePath.startsWith("native")) continue;
+      filePath = resolve(filePath);
+      if (filePath !== CORE_FILE) return pathToFileURL(filePath).href;
+    }
+  }
+  return undefined;
+}
+
 export interface PluginRegistry {}
 
 export interface ClientConfig {
@@ -330,7 +356,7 @@ export class PluginBuilder<LocalSchema = {}> {
     client?: ClientConfig;
     customErrors?: CustomErrors;
   } {
-    return config as any;
+    return { ...config, _modulePath: captureCallerUrl() } as any;
   }
 }
 
@@ -386,9 +412,11 @@ export class ConfiguredPluginBuilder<LocalSchema, Config> {
     client?: ClientConfig;
     customErrors?: CustomErrors;
   }> {
+    const modulePath = captureCallerUrl();
     const factory = (config: Config) => ({
       ...pluginDef,
       _boundConfig: config,
+      _modulePath: modulePath,
     });
     return factory as any;
   }
@@ -425,6 +453,8 @@ export type Plugin = {
     service: (ctx: any) => any;
     /** Called after service is created - use for registering crons, events, etc. */
     init?: (ctx: any, service: any) => void | Promise<void>;
+    /** Auto-detected module path where the plugin was defined */
+    _modulePath?: string;
 };
 
 export type PluginWithConfig<Config = void> = Plugin & {
@@ -454,6 +484,54 @@ export class PluginManager {
       return Array.from(this.plugins.values());
   }
 
+  getPluginNames(): string[] {
+      return Array.from(this.plugins.keys());
+  }
+
+  /** Returns { name: modulePath } for plugins that have a captured module path */
+  getPluginModulePaths(): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [name, plugin] of this.plugins) {
+      if (plugin._modulePath) {
+        result[name] = plugin._modulePath;
+      }
+    }
+    return result;
+  }
+
+  /** Returns { name: boundConfig } for configured plugins */
+  getPluginConfigs(): Record<string, any> {
+    const result: Record<string, any> = {};
+    for (const [name, plugin] of this.plugins) {
+      if ((plugin as ConfiguredPlugin)._boundConfig !== undefined) {
+        result[name] = (plugin as ConfiguredPlugin)._boundConfig;
+      }
+    }
+    return result;
+  }
+
+  /** Returns { name: [...deps] } for plugins with dependencies */
+  getPluginDependencies(): Record<string, string[]> {
+    const result: Record<string, string[]> = {};
+    for (const [name, plugin] of this.plugins) {
+      if (plugin.dependencies && plugin.dependencies.length > 0) {
+        result[name] = [...plugin.dependencies];
+      }
+    }
+    return result;
+  }
+
+  /** Returns custom error definitions per plugin */
+  getPluginCustomErrors(): Record<string, Record<string, any>> {
+    const result: Record<string, Record<string, any>> = {};
+    for (const [name, plugin] of this.plugins) {
+      if (plugin.customErrors && Object.keys(plugin.customErrors).length > 0) {
+        result[name] = plugin.customErrors;
+      }
+    }
+    return result;
+  }
+
   register(plugin: ConfiguredPlugin): void {
     if (this.plugins.has(plugin.name)) {
       throw new Error(`Plugin ${plugin.name} is already registered.`);

package/src/server.ts

@@ -1023,6 +1023,15 @@ ${factoryFunction}
     // Pass plugins to workflows so handlers can access ctx.plugins
     this.coreServices.workflows.setPlugins(this.manager.getServices());
 
+    // Forward plugin metadata so isolated workflows can instantiate plugins locally
+    this.coreServices.workflows.setPluginMetadata({
+      names: this.manager.getPluginNames(),
+      modulePaths: this.manager.getPluginModulePaths(),
+      configs: this.manager.getPluginConfigs(),
+      dependencies: this.manager.getPluginDependencies(),
+      customErrors: this.manager.getPluginCustomErrors(),
+    });
+
     this.isInitialized = true;
 
     this.coreServices.cron.start();