@donkeylabs/server 2.0.20 → 2.0.22

package/docs/workflows.md

@@ -79,7 +79,7 @@ const orderWorkflow = workflow("process-order")
 ### 2. Register and Start
 
 ```typescript
-// Register the workflow
+// Register the workflow — modulePath is auto-detected from build()
 ctx.core.workflows.register(orderWorkflow);
 
 // Start an instance
@@ -462,6 +462,60 @@ for (const event of workflowEvents) {
 }
 ```
 
+## Execution Modes
+
+Workflows support two execution modes controlled by the `.isolated()` builder method:
+
+### Isolated Mode (Default)
+
+By default, workflows run in a **separate subprocess**. This prevents long-running step handlers from blocking the main server's event loop. The subprocess owns its own database connection and state machine, communicating events back to the main server via Unix sockets (TCP on Windows).
+
+```typescript
+// Isolated mode (default) - runs in subprocess
+const myWorkflow = workflow("heavy-processing")
+  .task("compute", {
+    handler: async (input, ctx) => {
+      // CPU-intensive work runs in subprocess, won't block the server
+      return await heavyComputation(input);
+    },
+  })
+  .build();
+
+// Just register — modulePath is auto-detected from build()
+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.
+
+### Inline Mode
+
+For lightweight workflows that complete quickly, you can opt into inline execution:
+
+```typescript
+const quickWorkflow = workflow("quick-validation")
+  .isolated(false) // Run in the main server process
+  .task("validate", {
+    handler: async (input, ctx) => {
+      return { valid: true };
+    },
+    end: true,
+  })
+  .build();
+
+// No modulePath needed for inline workflows
+ctx.core.workflows.register(quickWorkflow);
+```
+
+### Choosing a Mode
+
+| | Isolated (default) | Inline |
+|---|---|---|
+| 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 |
+| Best for | Long-running, CPU-intensive workflows | Quick validations, lightweight flows |
+| Setup | `workflows.register(wf)` | `workflows.register(wf)` |
+
 ## API Reference
 
 ### Workflows Service
@@ -469,7 +523,7 @@ for (const event of workflowEvents) {
 ```typescript
 interface Workflows {
   /** Register a workflow definition */
-  register(definition: WorkflowDefinition): void;
+  register(definition: WorkflowDefinition, options?: WorkflowRegisterOptions): void;
 
   /** Start a new workflow instance */
   start<T = any>(workflowName: string, input: T): Promise<string>;
@@ -486,9 +540,21 @@ interface Workflows {
   /** Resume workflows after server restart */
   resume(): Promise<void>;
 
+  /** Update metadata for a workflow instance */
+  updateMetadata(instanceId: string, metadata: Record<string, any>): Promise<void>;
+
   /** Stop the workflow service */
   stop(): Promise<void>;
 }
+
+interface WorkflowRegisterOptions {
+  /**
+   * Module path for isolated workflows.
+   * Auto-detected from build() in most cases.
+   * Only needed when re-exporting from a different module.
+   */
+  modulePath?: string;
+}
 ```
 
 ### Workflow Instance
@@ -576,13 +642,13 @@ const server = new AppServer({
 Workflows automatically resume after server restart:
 
 1. On startup, `workflows.resume()` is called
-2. All instances with `status: "running"` are retrieved
-3. Execution continues from the current step
+2. All instances with `status: "running"` are retrieved from the database
+3. Isolated workflows re-launch a new subprocess that continues from the current step
+4. Inline workflows re-create the state machine and continue from the current step
 
 For this to work properly:
 - Use a persistent adapter (not in-memory) in production
-- Jobs should be idempotent when possible
-- The Jobs service must also support restart resilience
+- Step handlers should be idempotent when possible (a step may re-execute after a crash)
 
 ## Complete Example
 
@@ -670,7 +736,7 @@ const onboardingWorkflow = workflow("user-onboarding")
 // Setup server
 const server = new AppServer({ db: createDatabase() });
 
-// Register workflow
+// Register workflow — modulePath auto-detected from build()
 server.getCore().workflows.register(onboardingWorkflow);
 
 // Start workflow from a route

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
@@ -43,7 +43,7 @@
     "src",
     "docs",
     "examples",
-    "CLAUDE.md",
+    "agents.md",
     "context.d.ts",
     "registry.d.ts",
     "LICENSE",

package/src/admin/dashboard.ts

@@ -18,6 +18,7 @@ const icons = {
   cache: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4"/></svg>`,
   plugins: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 4a2 2 0 114 0v1a1 1 0 001 1h3a1 1 0 011 1v3a1 1 0 01-1 1h-1a2 2 0 100 4h1a1 1 0 011 1v3a1 1 0 01-1 1h-3a1 1 0 01-1-1v-1a2 2 0 10-4 0v1a1 1 0 01-1 1H7a1 1 0 01-1-1v-3a1 1 0 00-1-1H4a2 2 0 110-4h1a1 1 0 001-1V7a1 1 0 011-1h3a1 1 0 001-1V4z"/></svg>`,
   routes: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-.553-.894L15 4m0 13V4m0 0L9 7"/></svg>`,
+  logs: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 10h16M4 14h16M4 18h16"/></svg>`,
   refresh: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"/></svg>`,
   server: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01"/></svg>`,
 };
@@ -72,6 +73,7 @@ export function renderDashboardLayout(
     { id: "processes", label: "Processes", icon: icons.processes },
     { id: "workflows", label: "Workflows", icon: icons.workflows },
     { id: "audit", label: "Audit Logs", icon: icons.audit },
+    { id: "logs", label: "Logs", icon: icons.logs },
     { id: "sse", label: "SSE Clients", icon: icons.sse },
     { id: "websocket", label: "WebSocket", icon: icons.websocket },
     { id: "events", label: "Events", icon: icons.events },
@@ -120,7 +122,7 @@ export function renderDashboardLayout(
       <nav class="nav-section">
         <div class="nav-section-title">Core Services</div>
         ${navItems
-          .slice(1, 5)
+          .slice(1, 6)
           .map(
             (item) => `
           <a href="/${prefix}.dashboard?view=${item.id}"
@@ -138,7 +140,7 @@ export function renderDashboardLayout(
       <nav class="nav-section">
         <div class="nav-section-title">Connections</div>
         ${navItems
-          .slice(5, 8)
+          .slice(6, 9)
           .map(
             (item) => `
           <a href="/${prefix}.dashboard?view=${item.id}"
@@ -156,7 +158,7 @@ export function renderDashboardLayout(
       <nav class="nav-section">
         <div class="nav-section-title">Configuration</div>
         ${navItems
-          .slice(8)
+          .slice(9)
           .map(
             (item) => `
           <a href="/${prefix}.dashboard?view=${item.id}"
@@ -675,6 +677,75 @@ export function renderPlugins(prefix: string, plugins: any[]): string {
   `;
 }
 
+export function renderLogs(prefix: string, logs: any[]): string {
+  const levelBadgeClass = (level: string) => {
+    switch (level) {
+      case "error": return "badge-failed";
+      case "warn": return "badge-pending";
+      case "info": return "badge-running";
+      case "debug": return "badge-completed";
+      default: return "";
+    }
+  };
+
+  return `
+    <div class="page-header">
+      <h2 class="page-title">Logs</h2>
+      <button class="btn" hx-get="/${prefix}.dashboard?view=logs&partial=1" hx-target="#main-content">
+        ${icons.refresh}
+        Refresh
+      </button>
+    </div>
+
+    <div class="filters">
+      <select class="filter-select" hx-get="/${prefix}.dashboard?view=logs&partial=1" hx-target="#main-content" hx-include="this" name="status">
+        <option value="">All Sources</option>
+        <option value="system">System</option>
+        <option value="cron">Cron</option>
+        <option value="job">Job</option>
+        <option value="workflow">Workflow</option>
+        <option value="plugin">Plugin</option>
+        <option value="route">Route</option>
+      </select>
+    </div>
+
+    <div class="card">
+      <div class="table-container">
+        <table>
+          <thead>
+            <tr>
+              <th>Level</th>
+              <th>Source</th>
+              <th>Source ID</th>
+              <th>Message</th>
+              <th>Timestamp</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${
+              logs.length === 0
+                ? '<tr><td colspan="5" class="empty-state">No log entries found</td></tr>'
+                : logs
+                    .map(
+                      (log: any) => `
+              <tr>
+                <td><span class="badge ${levelBadgeClass(log.level)}">${log.level}</span></td>
+                <td>${log.source}</td>
+                <td class="mono truncate" title="${log.sourceId ?? ""}">${log.sourceId ?? "-"}</td>
+                <td class="truncate" title="${log.message}">${log.message.slice(0, 80)}${log.message.length > 80 ? "..." : ""}</td>
+                <td class="relative-time">${formatRelativeTime(log.timestamp)}</td>
+              </tr>
+            `
+                    )
+                    .join("")
+            }
+          </tbody>
+        </table>
+      </div>
+    </div>
+  `;
+}
+
 export function renderRoutes(prefix: string, routes: any[]): string {
   return `
     <div class="page-header">

package/src/admin/routes.ts

@@ -13,6 +13,7 @@ import {
   renderProcessesList,
   renderWorkflowsList,
   renderAuditLogs,
+  renderLogs,
   renderSSEClients,
   renderWebSocketClients,
   renderEvents,
@@ -124,6 +125,14 @@ export function createAdminRouter(config: AdminRouteContext) {
           content = renderWorkflowsList(prefix, workflows);
           break;
         }
+        case "logs": {
+          const logEntries = await ctx.core.logs.query({
+            source: (status as any) || undefined,
+            limit: 100,
+          });
+          content = renderLogs(prefix, logEntries);
+          break;
+        }
         case "audit": {
           const logs = await ctx.core.audit.query({
             limit: 100,
@@ -550,6 +559,59 @@ export function createAdminRouter(config: AdminRouteContext) {
     },
   });
 
+  // Logs list route
+  router.route("logs.list").typed(
+    defineRoute({
+      input: z.object({
+        source: z.enum(["system", "cron", "job", "workflow", "plugin", "route"]).optional(),
+        sourceId: z.string().optional(),
+        level: z.enum(["debug", "info", "warn", "error"]).optional(),
+        search: z.string().optional(),
+        startDate: z.string().optional(),
+        endDate: z.string().optional(),
+        limit: z.number().default(100),
+        offset: z.number().default(0),
+      }),
+      output: z.array(
+        z.object({
+          id: z.string(),
+          timestamp: z.string(),
+          level: z.string(),
+          message: z.string(),
+          source: z.string(),
+          sourceId: z.string().nullable(),
+          tags: z.array(z.string()).nullable(),
+          data: z.any().nullable(),
+        })
+      ),
+      handle: async (input, ctx) => {
+        if (!checkAuth(ctx)) {
+          throw ctx.errors.Forbidden("Unauthorized");
+        }
+        const entries = await ctx.core.logs.query({
+          source: input.source as any,
+          sourceId: input.sourceId,
+          level: input.level as any,
+          search: input.search,
+          startDate: input.startDate ? new Date(input.startDate) : undefined,
+          endDate: input.endDate ? new Date(input.endDate) : undefined,
+          limit: input.limit,
+          offset: input.offset,
+        });
+        return entries.map((entry) => ({
+          id: entry.id,
+          timestamp: entry.timestamp.toISOString(),
+          level: entry.level,
+          message: entry.message,
+          source: entry.source,
+          sourceId: entry.sourceId ?? null,
+          tags: entry.tags ?? null,
+          data: entry.data ?? null,
+        }));
+      },
+    })
+  );
+
   // Audit list route
   router.route("audit.list").typed(
     defineRoute({

package/src/core/cron.ts

@@ -1,11 +1,13 @@
 // Core Cron Service
 // Schedule recurring tasks with cron expressions
 
+import type { Logger } from "./logger";
+
 export interface CronTask {
   id: string;
   name: string;
   expression: string;
-  handler: () => void | Promise<void>;
+  handler: (logger?: Logger) => void | Promise<void>;
   enabled: boolean;
   lastRun?: Date;
   nextRun?: Date;
@@ -13,12 +15,13 @@ export interface CronTask {
 
 export interface CronConfig {
   timezone?: string; // For future use
+  logger?: Logger;
 }
 
 export interface Cron {
   schedule(
     expression: string,
-    handler: () => void | Promise<void>,
+    handler: (logger?: Logger) => void | Promise<void>,
     options?: { name?: string; enabled?: boolean }
   ): string;
   unschedule(taskId: string): boolean;
@@ -259,14 +262,15 @@ class CronImpl implements Cron {
   private running = false;
   private timer: ReturnType<typeof setInterval> | null = null;
   private taskCounter = 0;
+  private logger?: Logger;
 
-  constructor(_config: CronConfig = {}) {
-    // timezone handling for future use
+  constructor(config: CronConfig = {}) {
+    this.logger = config.logger;
   }
 
   schedule(
     expression: string,
-    handler: () => void | Promise<void>,
+    handler: (logger?: Logger) => void | Promise<void>,
     options: { name?: string; enabled?: boolean } = {}
   ): string {
     const id = `cron_${++this.taskCounter}_${Date.now()}`;
@@ -336,7 +340,8 @@ class CronImpl implements Cron {
     if (!task) throw new Error(`Task ${taskId} not found`);
 
     task.lastRun = new Date();
-    await task.handler();
+    const scopedLogger = this.logger?.scoped("cron", task.name);
+    await task.handler(scopedLogger);
   }
 
   start(): void {
@@ -358,8 +363,9 @@ class CronImpl implements Cron {
           task.lastRun = now;
           task.nextRun = cronExpr.getNextRun(now);
 
-          // Execute handler (fire and forget, but log errors)
-          Promise.resolve(task.handler()).catch(err => {
+          // 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 => {
             console.error(`[Cron] Task "${task.name}" failed:`, err);
           });
         }
@@ -388,8 +394,9 @@ class CronImpl implements Cron {
         while (missedRun && missedRun < now && catchUpCount < maxCatchUp) {
           console.log(`[Cron] Catching up missed run for "${task.name}" at ${missedRun.toISOString()}`);
 
-          // Execute the handler asynchronously
-          Promise.resolve(task.handler()).catch(err => {
+          // Execute the handler asynchronously with scoped logger
+          const scopedLogger = this.logger?.scoped("cron", task.name);
+          Promise.resolve(task.handler(scopedLogger)).catch(err => {
             console.error(`[Cron] Catch-up task "${task.name}" failed:`, err);
           });
 

package/src/core/index.ts

@@ -217,6 +217,12 @@ export {
   createProcessSocketServer,
 } from "./process-socket";
 
+export {
+  WorkflowStateMachine,
+  type StateMachineEvents,
+  type StateMachineConfig,
+} from "./workflow-state-machine";
+
 export {
   KyselyWorkflowAdapter,
   type KyselyWorkflowAdapterConfig,
@@ -266,3 +272,25 @@ export {
 
 export { LocalStorageAdapter } from "./storage-adapter-local";
 export { S3StorageAdapter } from "./storage-adapter-s3";
+
+export {
+  type Logs,
+  type LogSource,
+  type PersistentLogEntry,
+  type LogsQueryFilters,
+  type LogsRetentionConfig,
+  type LogsConfig,
+  type LogsAdapter,
+  MemoryLogsAdapter,
+  createLogs,
+} from "./logs";
+
+export {
+  KyselyLogsAdapter,
+  type KyselyLogsAdapterConfig,
+} from "./logs-adapter-kysely";
+
+export {
+  PersistentTransport,
+  type PersistentTransportConfig,
+} from "./logs-transport";

package/src/core/jobs.ts

@@ -3,6 +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 {
   ExternalJobConfig,
   ExternalJob,
@@ -58,7 +59,7 @@ export interface Job {
 }
 
 export interface JobHandler<T = any, R = any> {
-  (data: T): Promise<R>;
+  (data: T, ctx?: { logger: Logger }): Promise<R>;
 }
 
 /** Options for listing all jobs */
@@ -94,6 +95,7 @@ export interface JobAdapter {
 export interface JobsConfig {
   adapter?: JobAdapter;
   events?: Events;
+  logger?: Logger;
   concurrency?: number; // Max concurrent jobs, default 5
   pollInterval?: number; // ms, default 1000
   maxAttempts?: number; // Default retry attempts, default 3
@@ -247,6 +249,7 @@ class JobsImpl implements Jobs {
   private adapter: JobAdapter;
   private sqliteAdapter?: SqliteJobAdapter;
   private events?: Events;
+  private logger?: Logger;
   private handlers = new Map<string, JobHandler>();
   private running = false;
   private timer: ReturnType<typeof setInterval> | null = null;
@@ -268,6 +271,7 @@ class JobsImpl implements Jobs {
 
   constructor(config: JobsConfig = {}) {
     this.events = config.events;
+    this.logger = config.logger;
     this.concurrency = config.concurrency ?? 5;
     this.pollInterval = config.pollInterval ?? 1000;
     this.defaultMaxAttempts = config.maxAttempts ?? 3;
@@ -1061,7 +1065,9 @@ class JobsImpl implements Jobs {
         attempts: job.attempts + 1,
       });
 
-      const result = await handler(job.data);
+      // 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);
 
       await this.adapter.update(job.id, {
         status: "completed",

package/src/core/logger.ts

@@ -32,6 +32,8 @@ export interface Logger {
   child(context: Record<string, any>): Logger;
   /** Create a tagged child logger with colored prefix */
   tag(name: string): Logger;
+  /** Create a scoped child logger with source attribution for persistent logging */
+  scoped(source: string, sourceId: string): Logger;
 }
 
 const LOG_LEVELS: Record<LogLevel, number> = {
@@ -55,6 +57,14 @@ const TAG_COLORS: ((s: string) => string)[] = [
 const tagColorCache = new Map<string, (s: string) => string>();
 let colorIndex = 0;
 
+// Pre-seed fixed colors for source types
+tagColorCache.set("cron", pc.yellow);
+tagColorCache.set("job", pc.magenta);
+tagColorCache.set("workflow", pc.cyan);
+tagColorCache.set("plugin", pc.green);
+tagColorCache.set("system", pc.blue);
+tagColorCache.set("route", pc.red);
+
 /**
  * Get a consistent color for a tag name.
  * Same tag always gets the same color within a process.
@@ -187,6 +197,10 @@ class LoggerImpl implements Logger {
       [...this.tags, name]
     );
   }
+
+  scoped(source: string, sourceId: string): Logger {
+    return this.tag(source).child({ logSource: source, logSourceId: sourceId });
+  }
 }
 
 export function createLogger(config?: LoggerConfig): Logger {