@donkeylabs/server 2.0.23 → 2.0.25

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

@@ -518,6 +518,31 @@ export const reportWorkflow = workflow("report.generate")
   .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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "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,

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

@@ -68,7 +68,7 @@ export async function bootstrapSubprocess(
   const logs = createLogs({ adapter: new MemoryLogsAdapter(), events });
   const logger = createLogger();
 
-  const cron = createCron({ logger });
+  const cron = createCron({ logger, events });
 
   const jobAdapter = new KyselyJobAdapter(db, { cleanupDays: 0 });
   const workflowAdapter = new KyselyWorkflowAdapter(db, { cleanupDays: 0 });

package/src/core/workflow-executor.ts

@@ -91,6 +91,27 @@ async function main(): Promise<void> {
       plugins: bootstrap.manager.getServices(),
       events: createIpcEventBridge(socket, instanceId),
       pollInterval: 1000,
+      emitCustomEvent: async (payload) => {
+        sendEvent(socket, {
+          type: "event",
+          instanceId: payload.instanceId,
+          workflowName: payload.workflowName,
+          timestamp: Date.now(),
+          event: payload.event,
+          data: payload.data,
+        });
+      },
+      emitLog: async (payload) => {
+        sendEvent(socket, {
+          type: "log",
+          instanceId: payload.instanceId,
+          workflowName: payload.workflowName,
+          timestamp: Date.now(),
+          level: payload.level,
+          message: payload.message,
+          data: payload.data,
+        });
+      },
     });
 
     sendEvent(socket, {

package/src/core/workflow-socket.ts

@@ -11,6 +11,8 @@ import { createServer as createNetServer } from "node:net";
 // Message Protocol Types
 // ============================================
 
+import type { LogLevel } from "./logger";
+
 export type WorkflowEventType =
   | "ready"
   | "started"
@@ -20,11 +22,14 @@ export type WorkflowEventType =
   | "step.failed"
   | "progress"
   | "completed"
-  | "failed";
+  | "failed"
+  | "event"
+  | "log";
 
 export interface WorkflowEvent {
   type: WorkflowEventType;
   instanceId: string;
+  workflowName?: string;
   timestamp: number;
   stepName?: string;
   /** Step type (for step.started events) */
@@ -36,6 +41,14 @@ export interface WorkflowEvent {
   totalSteps?: number;
   /** Next step to execute (for step.completed events) */
   nextStep?: string;
+  /** Custom event name (for event type) */
+  event?: string;
+  /** Custom event payload or log data */
+  data?: Record<string, any>;
+  /** Log level (for log type) */
+  level?: LogLevel;
+  /** Log message (for log type) */
+  message?: string;
 }
 
 export interface ProxyRequest {

package/src/core/workflow-state-machine.ts

@@ -3,6 +3,7 @@
 // Communicates through an event callback interface - no knowledge of IPC, SSE, or process management.
 
 import type { CoreServices } from "../core";
+import type { LogLevel } from "./logger";
 import type { Jobs } from "./jobs";
 import type {
   WorkflowAdapter,
@@ -44,6 +45,19 @@ export interface StateMachineConfig {
   jobs?: Jobs;
   /** Poll interval for checking job completion (ms) */
   pollInterval?: number;
+  emitCustomEvent?: (payload: {
+    instanceId: string;
+    workflowName: string;
+    event: string;
+    data?: Record<string, any>;
+  }) => Promise<void>;
+  emitLog?: (payload: {
+    instanceId: string;
+    workflowName: string;
+    level: LogLevel;
+    message: string;
+    data?: Record<string, any>;
+  }) => Promise<void>;
 }
 
 // ============================================
@@ -57,6 +71,8 @@ export class WorkflowStateMachine {
   private events: StateMachineEvents;
   private jobs?: Jobs;
   private pollInterval: number;
+  private emitCustomEvent?: StateMachineConfig["emitCustomEvent"];
+  private emitLog?: StateMachineConfig["emitLog"];
   private cancelledInstances = new Set<string>();
 
   constructor(config: StateMachineConfig) {
@@ -66,6 +82,8 @@ export class WorkflowStateMachine {
     this.events = config.events;
     this.jobs = config.jobs;
     this.pollInterval = config.pollInterval ?? 1000;
+    this.emitCustomEvent = config.emitCustomEvent;
+    this.emitLog = config.emitLog;
   }
 
   /**
@@ -482,6 +500,48 @@ export class WorkflowStateMachine {
     const adapter = this.adapter;
     const instanceId = instance.id;
 
+    const scopedLogger = this.core?.logger?.scoped("workflow", instance.id);
+    const emit = async (event: string, data?: Record<string, any>) => {
+      const payload = {
+        instanceId: instance.id,
+        workflowName: instance.workflowName,
+        event,
+        data,
+      };
+
+      if (this.core?.events) {
+        await this.core.events.emit("workflow.event", payload);
+        await this.core.events.emit(`workflow.${instance.workflowName}.event`, payload);
+        await this.core.events.emit(`workflow.${instance.id}.event`, payload);
+      }
+
+      if (this.emitCustomEvent) {
+        await this.emitCustomEvent(payload);
+      }
+    };
+
+    const log = (level: LogLevel, message: string, data?: Record<string, any>) => {
+      if (scopedLogger) {
+        scopedLogger[level](message, data);
+      }
+      if (this.emitLog) {
+        return this.emitLog({
+          instanceId: instance.id,
+          workflowName: instance.workflowName,
+          level,
+          message,
+          data,
+        });
+      }
+    };
+
+    const core = this.core
+      ? {
+          ...this.core,
+          logger: scopedLogger ?? this.core.logger,
+        }
+      : this.core;
+
     return {
       input: instance.input,
       steps,
@@ -490,7 +550,10 @@ export class WorkflowStateMachine {
       getStepResult: <T = any>(stepName: string): T | undefined => {
         return steps[stepName] as T | undefined;
       },
-      core: this.core!,
+      core: core!,
+      logger: scopedLogger,
+      emit,
+      log,
       plugins: this.plugins,
       metadata,
       setMetadata: async (key: string, value: any): Promise<void> => {

package/src/core/workflows.ts

@@ -14,6 +14,7 @@ import type { SSE } from "./sse";
 import type { z } from "zod";
 import { sql } from "kysely";
 import type { CoreServices } from "../core";
+import type { Logger, LogLevel } from "./logger";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
@@ -243,6 +244,12 @@ export interface WorkflowContext {
   getStepResult<T = any>(stepName: string): T | undefined;
   /** Core services (logger, events, cache, etc.) */
   core: CoreServices;
+  /** Scoped logger for this workflow instance (source=workflow, sourceId=instanceId) */
+  logger?: Logger;
+  /** Emit a workflow-scoped custom event */
+  emit?: (event: string, data?: Record<string, any>) => Promise<void>;
+  /** Write a scoped log entry for this workflow instance */
+  log?: (level: LogLevel, message: string, data?: Record<string, any>) => void;
   /** Plugin services - available for business logic in workflow handlers */
   plugins: Record<string, any>;
   /**
@@ -1468,6 +1475,53 @@ class WorkflowsImpl implements Workflows {
         break;
       }
 
+      case "event": {
+        const workflowName = event.workflowName ?? (await this.adapter.getInstance(instanceId))?.workflowName;
+        const payload = {
+          instanceId,
+          workflowName,
+          event: event.event,
+          data: event.data,
+        };
+
+        await this.emitEvent("workflow.event", payload);
+        if (workflowName) {
+          await this.emitEvent(`workflow.${workflowName}.event`, payload);
+        }
+        await this.emitEvent(`workflow.${instanceId}.event`, payload);
+
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "event", payload);
+          this.sse.broadcast("workflows:all", "workflow.event", payload);
+        }
+        break;
+      }
+
+      case "log": {
+        const workflowName = event.workflowName ?? (await this.adapter.getInstance(instanceId))?.workflowName;
+
+        if (this.core?.logs && event.level && event.message) {
+          this.core.logs.write({
+            level: event.level,
+            message: event.message,
+            source: "workflow",
+            sourceId: instanceId,
+            data: event.data,
+            context: workflowName ? { workflowName } : undefined,
+          });
+        }
+
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "log", {
+            level: event.level,
+            message: event.message,
+            data: event.data,
+            workflowName,
+          });
+        }
+        break;
+      }
+
       case "completed": {
         // Clean up isolated process tracking
         this.cleanupIsolatedProcess(instanceId);

package/src/server.ts

@@ -264,6 +264,7 @@ export class AppServer {
     const cron = createCron({
       ...options.cron,
       logger,
+      events,
     });
 
     // Create adapters - use Kysely by default, or legacy SQLite if requested