@donkeylabs/server 2.3.0 → 2.5.0

package/docs/processes.md

@@ -323,9 +323,12 @@ interface ProcessDefinition {
   /** Environment variables */
   env?: Record<string, string>;
 
-  /** Typed events the process can emit */
+  /** Typed events the process can emit (validated at runtime) */
   events?: Record<string, ZodSchema>;
 
+  /** Typed command schemas for messages sent TO the process via send() (validated at runtime) */
+  commands?: Record<string, ZodSchema>;
+
   /** Heartbeat timeout in ms (default: 30000) */
   heartbeatTimeout?: number;
 
@@ -363,9 +366,12 @@ interface Processes {
   /** Get processes by name */
   getByName(name: string): ManagedProcess[];
 
-  /** Send a message to a running process */
+  /** Send a message to a running process (validated against command schemas if defined) */
   send(processId: string, message: any): Promise<boolean>;
 
+  /** Get all registered process definitions */
+  getDefinitions(): Map<string, ProcessDefinition>;
+
   /** Stop a process */
   stop(processId: string, signal?: NodeJS.Signals): Promise<void>;
 
@@ -575,6 +581,51 @@ ctx.core.events.on("process.stats", ({ processId, name, stats }) => {
 
 The server can send messages to running processes via `ctx.core.processes.send()`. The ProcessClient receives these messages through the `onMessage` callback.
 
+### Typed Commands
+
+Define command schemas to get runtime validation on `send()`. If a command fails validation, `send()` returns `false` and the message is not sent.
+
+```typescript
+import { z } from "zod";
+
+ctx.core.processes.register({
+  name: "ws-daemon",
+  config: {
+    command: "bun",
+    args: ["./workers/ws-daemon.ts"],
+  },
+  events: {
+    ready: z.object({ port: z.number() }),
+    clientCount: z.object({ count: z.number() }),
+  },
+  // Commands are validated before sending to the process
+  commands: {
+    subscribe: z.object({
+      type: z.literal("subscribe"),
+      channel: z.string(),
+    }),
+    configUpdate: z.object({
+      type: z.literal("configUpdate"),
+      settings: z.record(z.any()),
+    }),
+  },
+});
+
+// Valid command - sends successfully
+await ctx.core.processes.send(processId, {
+  type: "subscribe",
+  channel: "live-scores",
+}); // true
+
+// Invalid command - returns false, message not sent
+await ctx.core.processes.send(processId, {
+  type: "subscribe",
+  channel: 12345, // schema requires string
+}); // false
+```
+
+Commands without schemas are not validated (passthrough). The `type` field of the message is used to match against the command schema name.
+
 ### Sending Messages from Server
 
 ```typescript

package/package.json

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

package/src/core/core-events.ts

@@ -0,0 +1,116 @@
+/**
+ * Core Event Map
+ *
+ * Single source of truth for all core service event types.
+ * These events are emitted by workflows, jobs, processes, cron, and logs.
+ * They are always available in EventRegistry without code generation.
+ */
+
+import type { ProcessStats } from "./processes";
+import type { PersistentLogEntry } from "./logs";
+
+export interface CoreEventMap {
+  // Workflow events
+  "workflow.started": { instanceId: string; workflowName: string; input: any };
+  "workflow.completed": { instanceId: string; output: any };
+  "workflow.failed": { instanceId: string; workflowName: string; error: string };
+  "workflow.cancelled": { instanceId: string; workflowName: string };
+  "workflow.progress": { instanceId: string; progress: number; currentStep: string; completedSteps: number; totalSteps: number };
+  "workflow.event": { instanceId: string; workflowName: string; event: string; data: any };
+  "workflow.step.started": { instanceId: string; stepName: string; stepType: string };
+  "workflow.step.completed": { instanceId: string; stepName: string; output: any };
+  "workflow.step.failed": { instanceId: string; stepName: string; error: string; attempts: number };
+  "workflow.step.poll": { instanceId: string; stepName: string; pollCount: number; done: boolean; result: any };
+  "workflow.step.loop": { instanceId: string; stepName: string; loopCount: number; target: string };
+  "workflow.step.retry": { instanceId: string; stepName: string; attempt: number; maxAttempts: number; delay: number };
+  "workflow.watchdog.stale": { instanceId: string; reason: string; timeoutMs: number };
+  "workflow.watchdog.killed": { instanceId: string; reason: string; timeoutMs: number };
+
+  // Job events
+  "job.completed": { jobId: string; name: string; result: any };
+  "job.failed": { jobId: string; name: string; error: string; attempts?: number; stack?: string };
+  "job.stale": { jobId: string; name: string; timeSinceHeartbeat: number };
+  "job.reconnected": { jobId: string; name: string };
+  "job.lost": { jobId: string; name: string };
+  "job.event": { jobId: string; name: string; event: string; data?: any };
+  "job.external.spawned": { jobId: string; name: string };
+  "job.external.progress": { jobId: string; name: string; percent: number; message: string; data: any };
+  "job.external.log": { jobId: string; name: string; level: string; message: string; data?: any };
+  "job.watchdog.stale": { jobId: string; name: string; timeSinceHeartbeat: number };
+  "job.watchdog.killed": { jobId: string; name: string; reason: string };
+
+  // Process events
+  "process.spawned": { processId: string; name: string; pid: number };
+  "process.stopped": { processId: string; name: string };
+  "process.crashed": { processId: string; name: string; exitCode: number | null };
+  "process.restarted": { oldProcessId: string; newProcessId: string; name: string; attempt: number };
+  "process.reconnected": { processId: string; name: string; pid: number };
+  "process.stats": { processId: string; name: string; stats: ProcessStats };
+  "process.limits_exceeded": { processId: string; name: string; reason: string; limit: number; value?: number };
+  "process.heartbeat_missed": { processId: string; name: string };
+  "process.event": { processId: string; name: string; event: string; data: any };
+  "process.message": { processId: string; name: string; message: any };
+  "process.watchdog.stale": { processId: string; name: string; reason: string; timeoutMs: number };
+  "process.watchdog.killed": { processId: string; name: string; reason: string; value?: number };
+
+  // Cron events
+  "cron.event": { taskId: string; name: string; event: string; data?: any };
+
+  // Log events
+  "log.created": PersistentLogEntry;
+}
+
+/**
+ * Serializable core event definitions for CLI type generation.
+ * Maps event name to TypeScript type string (used by `donkeylabs generate`).
+ */
+export const CORE_EVENT_DEFINITIONS: Record<string, string> = {
+  // Workflow events
+  "workflow.started": "{ instanceId: string; workflowName: string; input: any }",
+  "workflow.completed": "{ instanceId: string; output: any }",
+  "workflow.failed": "{ instanceId: string; workflowName: string; error: string }",
+  "workflow.cancelled": "{ instanceId: string; workflowName: string }",
+  "workflow.progress": "{ instanceId: string; progress: number; currentStep: string; completedSteps: number; totalSteps: number }",
+  "workflow.event": "{ instanceId: string; workflowName: string; event: string; data: any }",
+  "workflow.step.started": "{ instanceId: string; stepName: string; stepType: string }",
+  "workflow.step.completed": "{ instanceId: string; stepName: string; output: any }",
+  "workflow.step.failed": "{ instanceId: string; stepName: string; error: string; attempts: number }",
+  "workflow.step.poll": "{ instanceId: string; stepName: string; pollCount: number; done: boolean; result: any }",
+  "workflow.step.loop": "{ instanceId: string; stepName: string; loopCount: number; target: string }",
+  "workflow.step.retry": "{ instanceId: string; stepName: string; attempt: number; maxAttempts: number; delay: number }",
+  "workflow.watchdog.stale": "{ instanceId: string; reason: string; timeoutMs: number }",
+  "workflow.watchdog.killed": "{ instanceId: string; reason: string; timeoutMs: number }",
+
+  // Job events
+  "job.completed": "{ jobId: string; name: string; result: any }",
+  "job.failed": "{ jobId: string; name: string; error: string; attempts?: number; stack?: string }",
+  "job.stale": "{ jobId: string; name: string; timeSinceHeartbeat: number }",
+  "job.reconnected": "{ jobId: string; name: string }",
+  "job.lost": "{ jobId: string; name: string }",
+  "job.event": "{ jobId: string; name: string; event: string; data?: any }",
+  "job.external.spawned": "{ jobId: string; name: string }",
+  "job.external.progress": "{ jobId: string; name: string; percent: number; message: string; data: any }",
+  "job.external.log": "{ jobId: string; name: string; level: string; message: string; data?: any }",
+  "job.watchdog.stale": "{ jobId: string; name: string; timeSinceHeartbeat: number }",
+  "job.watchdog.killed": "{ jobId: string; name: string; reason: string }",
+
+  // Process events
+  "process.spawned": "{ processId: string; name: string; pid: number }",
+  "process.stopped": "{ processId: string; name: string }",
+  "process.crashed": "{ processId: string; name: string; exitCode: number | null }",
+  "process.restarted": "{ oldProcessId: string; newProcessId: string; name: string; attempt: number }",
+  "process.reconnected": "{ processId: string; name: string; pid: number }",
+  "process.stats": "{ processId: string; name: string; stats: { cpu: { user: number; system: number; percent: number }; memory: { rss: number; heapTotal: number; heapUsed: number; external: number }; uptime: number } }",
+  "process.limits_exceeded": "{ processId: string; name: string; reason: string; limit: number; value?: number }",
+  "process.heartbeat_missed": "{ processId: string; name: string }",
+  "process.event": "{ processId: string; name: string; event: string; data: any }",
+  "process.message": "{ processId: string; name: string; message: any }",
+  "process.watchdog.stale": "{ processId: string; name: string; reason: string; timeoutMs: number }",
+  "process.watchdog.killed": "{ processId: string; name: string; reason: string; value?: number }",
+
+  // Cron events
+  "cron.event": "{ taskId: string; name: string; event: string; data?: any }",
+
+  // Log events
+  "log.created": "{ id: string; timestamp: Date; level: string; message: string; source: string; sourceId?: string; tags?: string[]; data?: Record<string, any>; context?: Record<string, any> }",
+};

package/src/core/index.ts

@@ -1,5 +1,7 @@
 // Core Services - Re-export all services
 
+export { type CoreEventMap, CORE_EVENT_DEFINITIONS } from "./core-events";
+
 export {
   type Logger,
   type LogLevel,

package/src/core/processes.ts

@@ -136,6 +136,19 @@ export interface ProcessDefinition {
    * ```
    */
   events?: Record<string, import("zod").ZodType<any>>;
+  /**
+   * Command schemas for messages sent TO the process via send().
+   * Commands are validated at runtime using safeParse() before sending.
+   *
+   * @example
+   * ```ts
+   * commands: {
+   *   subscribe: z.object({ channel: z.string() }),
+   *   configUpdate: z.object({ settings: z.record(z.any()) }),
+   * }
+   * ```
+   */
+  commands?: Record<string, import("zod").ZodType<any>>;
   /** Called when a message is received from the process */
   onMessage?: (process: ManagedProcess, message: any) => void | Promise<void>;
   /** Called when the process crashes unexpectedly */
@@ -209,6 +222,8 @@ export interface Processes {
   getRunning(): Promise<ManagedProcess[]>;
   /** Send a message to a process via socket */
   send(processId: string, message: any): Promise<boolean>;
+  /** Get all registered process definitions */
+  getDefinitions(): Map<string, ProcessDefinition>;
   /** Start the service (recovery, monitoring) */
   start(): void;
   /** Shutdown the service and all managed processes */
@@ -552,9 +567,32 @@ export class ProcessesImpl implements Processes {
   }
 
   async send(processId: string, message: any): Promise<boolean> {
+    // Validate message against command schemas if defined
+    if (message && typeof message === "object" && message.type) {
+      const proc = await this.adapter.get(processId);
+      if (proc) {
+        const definition = this.definitions.get(proc.name);
+        if (definition?.commands) {
+          const commandSchema = definition.commands[message.type];
+          if (commandSchema) {
+            const result = commandSchema.safeParse(message);
+            if (!result.success) {
+              console.warn(
+                `[Processes] Command validation failed for '${message.type}' on ${proc.name}: ${result.error.message}`
+              );
+              return false;
+            }
+          }
+        }
+      }
+    }
     return this.socketServer.send(processId, message);
   }
 
+  getDefinitions(): Map<string, ProcessDefinition> {
+    return this.definitions;
+  }
+
   start(): void {
     // Recover orphaned processes
     if (this.autoRecoverOrphans) {
@@ -684,7 +722,23 @@ export class ProcessesImpl implements Processes {
     // Handle typed event messages from ProcessClient.emit()
     if (type === "event" && message.event) {
       const eventName = message.event as string;
-      const eventData = message.data ?? {};
+      let eventData = message.data ?? {};
+
+      // Validate event data against schema if defined
+      const definition = this.definitions.get(proc.name);
+      if (definition?.events) {
+        const eventSchema = definition.events[eventName];
+        if (eventSchema) {
+          const result = eventSchema.safeParse(eventData);
+          if (!result.success) {
+            console.warn(
+              `[Processes] Event validation failed for '${eventName}' on ${proc.name}: ${result.error.message}`
+            );
+            return; // Drop invalid events
+          }
+          eventData = result.data;
+        }
+      }
 
       // Emit to events service as "process.<name>.<event>"
       await this.emitEvent(`process.${proc.name}.${eventName}`, {

package/src/core.ts

@@ -18,6 +18,7 @@ import type { WebSocketService } from "./core/websocket";
 import type { Storage } from "./core/storage";
 import type { Logs } from "./core/logs";
 import type { Health } from "./core/health";
+import type { CoreEventMap } from "./core/core-events";
 
 // ============================================
 // Auto-detect caller module for plugin define()
@@ -71,7 +72,26 @@ export type EventSchemas = Record<string, z.ZodType<any>>;
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface EventRegistry {}
+export interface EventRegistry extends CoreEventMap {}
+
+/**
+ * Registry for process type definitions.
+ * Augment this interface to add typed process commands/events:
+ *
+ * @example
+ * ```ts
+ * declare module "@donkeylabs/server" {
+ *   interface ProcessRegistry {
+ *     "video-encoder": {
+ *       events: { progress: { percent: number }; complete: { outputPath: string } };
+ *       commands: { subscribe: { channel: string }; configUpdate: { settings: Record<string, any> } };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ProcessRegistry {}
 
 /**
  * Define server-level events with Zod schemas.
@@ -240,7 +260,7 @@ type ExtractServices<T extends readonly (keyof PluginRegistry)[] | undefined> =
   T extends readonly []
     ? {}
     : T extends readonly (infer K)[]
-      ? K extends keyof PluginRegistry
+      ? [K] extends [keyof PluginRegistry]
         ? { [P in K]: PluginRegistry[P] extends { service: infer S } ? S : unknown }
         : {}
       : {};

package/src/index.ts

@@ -51,7 +51,9 @@ export {
   defineEvents,
   type EventRegistry,
   type EventSchemas,
+  // Registries
   type PluginRegistry,
+  type ProcessRegistry,
   type PluginHandlerRegistry,
   type PluginMiddlewareRegistry,
   type CoreServices,
@@ -110,6 +112,9 @@ export {
   type EventMetadata,
 } from "./core/index";
 
+// Core event types
+export { type CoreEventMap, CORE_EVENT_DEFINITIONS } from "./core/core-events";
+
 // Health checks
 export {
   type Health,

package/src/server.ts

@@ -56,6 +56,7 @@ import {
 import { createHealth, createDbHealthCheck, type HealthConfig } from "./core/health";
 import type { AdminConfig } from "./admin";
 import { zodSchemaToTs } from "./generator/zod-to-ts";
+import { CORE_EVENT_DEFINITIONS } from "./core/core-events";
 
 export interface TypeGenerationConfig {
   /** Output path for generated client types (e.g., "./src/lib/api.ts") */
@@ -855,7 +856,30 @@ export class AppServer {
       }
     }
 
-    console.log(JSON.stringify({ routes }));
+    // Collect process definitions with their schemas
+    const processes = [];
+    const definitions = this.coreServices.processes.getDefinitions();
+    for (const [name, def] of definitions) {
+      const events: Record<string, string> = {};
+      if (def.events) {
+        for (const [eventName, schema] of Object.entries(def.events)) {
+          events[eventName] = zodSchemaToTs(schema);
+        }
+      }
+      const commands: Record<string, string> = {};
+      if (def.commands) {
+        for (const [cmdName, schema] of Object.entries(def.commands)) {
+          commands[cmdName] = zodSchemaToTs(schema);
+        }
+      }
+      processes.push({
+        name,
+        events: Object.keys(events).length > 0 ? events : undefined,
+        commands: Object.keys(commands).length > 0 ? commands : undefined,
+      });
+    }
+
+    console.log(JSON.stringify({ routes, processes, coreEvents: CORE_EVENT_DEFINITIONS }));
   }
 
   /**