@donkeylabs/server 2.0.22 → 2.0.24

package/docs/cron.md

@@ -26,7 +26,7 @@ ctx.core.cron.schedule("0 0 * * *", async () => {
 interface Cron {
   schedule(
     expression: string,
-    handler: () => void | Promise<void>,
+    handler: (logger?: Logger, ctx?: CronRunContext) => void | Promise<void>,
     options?: { name?: string; enabled?: boolean }
   ): string;
   unschedule(taskId: string): boolean;
@@ -43,11 +43,19 @@ interface CronTask {
   id: string;
   name: string;
   expression: string;
-  handler: () => void | Promise<void>;
+  handler: (logger?: Logger, ctx?: CronRunContext) => void | Promise<void>;
   enabled: boolean;
   lastRun?: Date;
   nextRun?: Date;
 }
+
+interface CronRunContext {
+  taskId: string;
+  name: string;
+  logger?: Logger;
+  emit?: (event: string, data?: Record<string, any>) => Promise<void>;
+  log?: (level: LogLevel, message: string, data?: Record<string, any>) => void;
+}
 ```
 
 ### Methods
@@ -356,6 +364,24 @@ ctx.core.cron.schedule("0 * * * *", async () => {
 
 ---
 
+## Logs and Custom Events
+
+Cron handlers receive a scoped logger and a context helper. Logs are persisted and emitted as events:
+
+- `log.cron` (all cron logs)
+- `log.cron.<taskName>` (per task)
+
+You can also emit custom events scoped to a cron task:
+
+```ts
+ctx.core.cron.schedule("0 * * * *", async (logger, ctx) => {
+  ctx?.log?.("info", "Hourly cleanup started");
+  await ctx?.emit?.("cleanup.started", { when: new Date().toISOString() });
+});
+```
+
+---
+
 ## Testing Cron Tasks
 
 ```ts

package/docs/jobs.md

@@ -438,6 +438,21 @@ interface JobAdapter {
 }
 ```
 
+---
+
+## Logs and Custom Events
+
+Job handlers receive a scoped logger and helpers. Logs are persisted and emitted as events:
+
+- `log.job` (all job logs)
+- `log.job.<jobId>` (per job)
+
+Custom events are emitted via `ctx.emit`:
+
+- `job.event`
+- `job.<jobName>.event`
+- `job.<jobId>.event`
+
 ### SQLite Adapter Example
 
 ```ts

package/docs/workflows.md

@@ -487,6 +487,62 @@ 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();
+```
+
+#### Workflow Logs and Custom Events
+
+Workflow handlers get a scoped logger and helpers:
+
+- `ctx.logger` and `ctx.core.logger` are scoped to `source=workflow`, `sourceId=<instanceId>`
+- Logs are persisted and emitted as events:
+  - `log.workflow` (all workflow logs)
+  - `log.workflow.<instanceId>` (per workflow instance)
+
+Custom events can be emitted with `ctx.emit`:
+
+```typescript
+export const reportWorkflow = workflow("report.generate")
+  .task("run", {
+    handler: async (input, ctx) => {
+      ctx.log?.("info", "Starting report", { reportId: input.reportId });
+      await ctx.emit?.("progress", { stage: "fetch" });
+      const data = await ctx.plugins.reports.generate(input.reportId);
+      await ctx.emit?.("progress", { stage: "write" });
+      return { data };
+    },
+  })
+  .build();
+```
+
 ### Inline Mode
 
 For lightweight workflows that complete quickly, you can opt into inline execution:
@@ -512,7 +568,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 +601,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.24",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/cron.ts

@@ -1,13 +1,14 @@
 // Core Cron Service
 // Schedule recurring tasks with cron expressions
 
-import type { Logger } from "./logger";
+import type { Logger, LogLevel } from "./logger";
+import type { Events } from "./events";
 
 export interface CronTask {
   id: string;
   name: string;
   expression: string;
-  handler: (logger?: Logger) => void | Promise<void>;
+  handler: (logger?: Logger, ctx?: CronRunContext) => void | Promise<void>;
   enabled: boolean;
   lastRun?: Date;
   nextRun?: Date;
@@ -16,12 +17,13 @@ export interface CronTask {
 export interface CronConfig {
   timezone?: string; // For future use
   logger?: Logger;
+  events?: Events;
 }
 
 export interface Cron {
   schedule(
     expression: string,
-    handler: (logger?: Logger) => void | Promise<void>,
+    handler: (logger?: Logger, ctx?: CronRunContext) => void | Promise<void>,
     options?: { name?: string; enabled?: boolean }
   ): string;
   unschedule(taskId: string): boolean;
@@ -34,6 +36,14 @@ export interface Cron {
   stop(): Promise<void>;
 }
 
+export interface CronRunContext {
+  taskId: string;
+  name: string;
+  logger?: Logger;
+  emit?: (event: string, data?: Record<string, any>) => Promise<void>;
+  log?: (level: LogLevel, message: string, data?: Record<string, any>) => void;
+}
+
 // Simple cron expression parser
 // Supports: * (any), specific values, ranges (1-5), steps (*/5)
 // Format: second minute hour dayOfMonth month dayOfWeek
@@ -263,14 +273,16 @@ class CronImpl implements Cron {
   private timer: ReturnType<typeof setInterval> | null = null;
   private taskCounter = 0;
   private logger?: Logger;
+  private events?: Events;
 
   constructor(config: CronConfig = {}) {
     this.logger = config.logger;
+    this.events = config.events;
   }
 
   schedule(
     expression: string,
-    handler: (logger?: Logger) => void | Promise<void>,
+    handler: (logger?: Logger, ctx?: CronRunContext) => void | Promise<void>,
     options: { name?: string; enabled?: boolean } = {}
   ): string {
     const id = `cron_${++this.taskCounter}_${Date.now()}`;
@@ -341,7 +353,7 @@ class CronImpl implements Cron {
 
     task.lastRun = new Date();
     const scopedLogger = this.logger?.scoped("cron", task.name);
-    await task.handler(scopedLogger);
+    await task.handler(scopedLogger, this.createRunContext(task, scopedLogger));
   }
 
   start(): void {
@@ -365,7 +377,7 @@ class CronImpl implements Cron {
 
           // Execute handler with scoped logger (fire and forget, but log errors)
           const scopedLogger = this.logger?.scoped("cron", task.name);
-          Promise.resolve(task.handler(scopedLogger)).catch(err => {
+          Promise.resolve(task.handler(scopedLogger, this.createRunContext(task, scopedLogger))).catch(err => {
             console.error(`[Cron] Task "${task.name}" failed:`, err);
           });
         }
@@ -396,7 +408,7 @@ class CronImpl implements Cron {
 
           // Execute the handler asynchronously with scoped logger
           const scopedLogger = this.logger?.scoped("cron", task.name);
-          Promise.resolve(task.handler(scopedLogger)).catch(err => {
+          Promise.resolve(task.handler(scopedLogger, this.createRunContext(task, scopedLogger))).catch(err => {
             console.error(`[Cron] Catch-up task "${task.name}" failed:`, err);
           });
 
@@ -424,6 +436,37 @@ class CronImpl implements Cron {
       this.timer = null;
     }
   }
+
+  private createRunContext(task: InternalCronTask, logger?: Logger): CronRunContext {
+    const emit = this.events
+      ? async (event: string, data?: Record<string, any>) => {
+          const payload = {
+            taskId: task.id,
+            name: task.name,
+            event,
+            data,
+          };
+
+          await this.events!.emit("cron.event", payload);
+          await this.events!.emit(`cron.${task.name}.event`, payload);
+          await this.events!.emit(`cron.${task.id}.event`, payload);
+        }
+      : undefined;
+
+    const log = logger
+      ? (level: LogLevel, message: string, data?: Record<string, any>) => {
+          logger[level](message, data);
+        }
+      : undefined;
+
+    return {
+      taskId: task.id,
+      name: task.name,
+      logger,
+      emit,
+      log,
+    };
+  }
 }
 
 export function createCron(config?: CronConfig): Cron {

package/src/core/index.ts

@@ -32,6 +32,7 @@ export {
 export {
   type Cron,
   type CronTask,
+  type CronRunContext,
   type CronConfig,
   createCron,
 } from "./cron";
@@ -41,6 +42,7 @@ export {
   type Job,
   type JobStatus,
   type JobHandler,
+  type JobHandlerContext,
   type JobAdapter,
   type JobsConfig,
   type GetAllJobsOptions,
@@ -149,6 +151,7 @@ export {
   type PassStepDefinition,
   type RetryConfig,
   type GetAllWorkflowsOptions,
+  type PluginMetadata,
   WorkflowBuilder,
   MemoryWorkflowAdapter,
   workflow,

package/src/core/jobs.ts

@@ -3,7 +3,7 @@
 // Supports both in-process handlers and external processes (Python, Go, Shell, etc.)
 
 import type { Events } from "./events";
-import type { Logger } from "./logger";
+import type { Logger, LogLevel } from "./logger";
 import type {
   ExternalJobConfig,
   ExternalJob,
@@ -59,7 +59,13 @@ export interface Job {
 }
 
 export interface JobHandler<T = any, R = any> {
-  (data: T, ctx?: { logger: Logger }): Promise<R>;
+  (data: T, ctx?: JobHandlerContext): Promise<R>;
+}
+
+export interface JobHandlerContext {
+  logger?: Logger;
+  emit?: (event: string, data?: Record<string, any>) => Promise<void>;
+  log?: (level: LogLevel, message: string, data?: Record<string, any>) => void;
 }
 
 /** Options for listing all jobs */
@@ -999,6 +1005,7 @@ class JobsImpl implements Jobs {
   ): void {
     const decoder = new TextDecoder();
     const events = this.events;
+    const scopedLogger = this.logger?.scoped("job", jobId);
 
     // Helper to stream a ReadableStream
     const streamOutput = async (
@@ -1028,6 +1035,10 @@ class JobsImpl implements Jobs {
               message: text.trim(),
             });
           }
+
+          if (scopedLogger) {
+            scopedLogger[level](text.trim(), { external: true });
+          }
         }
       } catch {
         // Stream may be closed
@@ -1067,7 +1078,18 @@ class JobsImpl implements Jobs {
 
       // Create scoped logger for this job execution
       const scopedLogger = this.logger?.scoped("job", job.id);
-      const result = await handler(job.data, scopedLogger ? { logger: scopedLogger } : undefined);
+      const emit = this.createJobEmitter(job);
+      const log = scopedLogger
+        ? (level: LogLevel, message: string, data?: Record<string, any>) => {
+            scopedLogger[level](message, data);
+          }
+        : undefined;
+
+      const result = await handler(job.data, {
+        logger: scopedLogger,
+        emit,
+        log,
+      });
 
       await this.adapter.update(job.id, {
         status: "completed",
@@ -1141,6 +1163,23 @@ class JobsImpl implements Jobs {
       this.activeJobs--;
     }
   }
+
+  private createJobEmitter(job: Job): JobHandlerContext["emit"] {
+    const events = this.events;
+    if (!events) return undefined;
+    return async (event: string, data?: Record<string, any>) => {
+      const payload = {
+        jobId: job.id,
+        name: job.name,
+        event,
+        data,
+      };
+
+      await events.emit("job.event", payload);
+      await events.emit(`job.${job.name}.event`, payload);
+      await events.emit(`job.${job.id}.event`, payload);
+    };
+  }
 }
 
 export function createJobs(config?: JobsConfig): Jobs {

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, events });
+
+  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;
+}