@donkeylabs/server 2.0.23 → 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

@@ -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.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,

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-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,
@@ -482,6 +483,35 @@ export class WorkflowStateMachine {
     const adapter = this.adapter;
     const instanceId = instance.id;
 
+    const scopedLogger = this.core?.logger?.scoped("workflow", instance.id);
+    const emit = this.core?.events
+      ? async (event: string, data?: Record<string, any>) => {
+          const payload = {
+            instanceId: instance.id,
+            workflowName: instance.workflowName,
+            event,
+            data,
+          };
+
+          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);
+        }
+      : undefined;
+
+    const log = scopedLogger
+      ? (level: LogLevel, message: string, data?: Record<string, any>) => {
+          scopedLogger[level](message, data);
+        }
+      : undefined;
+
+    const core = this.core
+      ? {
+          ...this.core,
+          logger: scopedLogger ?? this.core.logger,
+        }
+      : this.core;
+
     return {
       input: instance.input,
       steps,
@@ -490,7 +520,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>;
   /**

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