@donkeylabs/server 2.0.27 → 2.0.28

package/docs/workflows.md

@@ -285,6 +285,51 @@ workflow("example")
   .end("done")
 ```
 
+### Poll
+
+Use a poll step for wait → check loops that persist across restarts.
+
+```typescript
+workflow("batch.status")
+  .poll("wait-for-result", {
+    interval: 5000,
+    timeout: 600000,
+    maxAttempts: 120,
+    check: async (input, ctx) => {
+      const status = await fetchStatus(input.operationId);
+      if (status.state === "FAILED") throw new Error(status.error);
+      if (status.state === "SUCCEEDED") {
+        return { done: true, result: status.data };
+      }
+      return { done: false };
+    },
+  })
+  .build();
+```
+
+Each poll cycle emits `workflow.step.poll` events and persists progress to the instance.
+
+### Loop
+
+Use a loop step to jump back to a previous step until a condition is false.
+
+```typescript
+workflow("loop-example")
+  .task("increment", {
+    handler: async (input) => ({ count: (input.count ?? 0) + 1 }),
+  })
+  .loop("repeat", {
+    condition: (ctx) => ctx.steps.increment.count < 3,
+    target: "increment",
+    interval: 1000,
+    maxIterations: 10,
+    timeout: 30000,
+  })
+  .build();
+```
+
+Each loop iteration emits `workflow.step.loop` and persists loop counters to the instance.
+
 ## Workflow Context
 
 Every step receives a `WorkflowContext` with:

package/package.json

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

package/src/admin/routes.ts

@@ -505,6 +505,17 @@ export function createAdminRouter(config: AdminRouteContext) {
         stepName: z.string(),
         error: z.string(),
       }),
+      "step.poll": z.object({
+        stepName: z.string(),
+        pollCount: z.number(),
+        done: z.boolean(),
+        result: z.any().optional(),
+      }),
+      "step.loop": z.object({
+        stepName: z.string(),
+        loopCount: z.number(),
+        target: z.string(),
+      }),
       completed: z.object({
         output: z.any().optional(),
       }),
@@ -548,6 +559,19 @@ export function createAdminRouter(config: AdminRouteContext) {
         workflowName: z.string(),
         error: z.string(),
       }),
+      "workflow.step.poll": z.object({
+        instanceId: z.string(),
+        stepName: z.string(),
+        pollCount: z.number(),
+        done: z.boolean(),
+        result: z.any().optional(),
+      }),
+      "workflow.step.loop": z.object({
+        instanceId: z.string(),
+        stepName: z.string(),
+        loopCount: z.number(),
+        target: z.string(),
+      }),
     },
     handle: (input, ctx) => {
       if (!checkAuth(ctx)) {

package/src/core/index.ts

@@ -149,6 +149,9 @@ export {
   type ChoiceStepDefinition,
   type ChoiceCondition,
   type PassStepDefinition,
+  type PollStepDefinition,
+  type PollStepResult,
+  type LoopStepDefinition,
   type RetryConfig,
   type GetAllWorkflowsOptions,
   type PluginMetadata,

package/src/core/workflow-adapter-kysely.ts

@@ -258,6 +258,11 @@ export class KyselyWorkflowAdapter implements WorkflowAdapter {
         startedAt: sr.startedAt ? new Date(sr.startedAt) : undefined,
         completedAt: sr.completedAt ? new Date(sr.completedAt) : undefined,
         attempts: sr.attempts,
+        pollCount: sr.pollCount,
+        lastPolledAt: sr.lastPolledAt ? new Date(sr.lastPolledAt) : undefined,
+        loopCount: sr.loopCount,
+        lastLoopedAt: sr.lastLoopedAt ? new Date(sr.lastLoopedAt) : undefined,
+        loopStartedAt: sr.loopStartedAt ? new Date(sr.loopStartedAt) : undefined,
       };
     }
 

package/src/core/workflow-executor.ts

@@ -184,6 +184,27 @@ function createIpcEventBridge(socket: Socket, instanceId: string): StateMachineE
         error,
       });
     },
+    onStepPoll: (id, stepName, pollCount, done, result) => {
+      sendEvent(socket, {
+        type: "step.poll",
+        instanceId: id,
+        timestamp: Date.now(),
+        stepName,
+        pollCount,
+        done,
+        result,
+      });
+    },
+    onStepLoop: (id, stepName, loopCount, target) => {
+      sendEvent(socket, {
+        type: "step.loop",
+        instanceId: id,
+        timestamp: Date.now(),
+        stepName,
+        loopCount,
+        target,
+      });
+    },
     onStepRetry: () => {
       // Retry is internal to the state machine - no IPC event needed
     },

package/src/core/workflow-socket.ts

@@ -20,6 +20,8 @@ export type WorkflowEventType =
   | "step.started"
   | "step.completed"
   | "step.failed"
+  | "step.poll"
+  | "step.loop"
   | "progress"
   | "completed"
   | "failed"
@@ -41,6 +43,11 @@ export interface WorkflowEvent {
   totalSteps?: number;
   /** Next step to execute (for step.completed events) */
   nextStep?: string;
+  pollCount?: number;
+  done?: boolean;
+  result?: any;
+  loopCount?: number;
+  target?: string;
   /** Custom event name (for event type) */
   event?: string;
   /** Custom event payload or log data */

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

@@ -12,6 +12,8 @@ import type {
   WorkflowContext,
   StepDefinition,
   TaskStepDefinition,
+  LoopStepDefinition,
+  PollStepDefinition,
   ParallelStepDefinition,
   ChoiceStepDefinition,
   PassStepDefinition,
@@ -28,6 +30,8 @@ export interface StateMachineEvents {
   onStepCompleted(instanceId: string, stepName: string, output: any, nextStep?: string): void;
   onStepFailed(instanceId: string, stepName: string, error: string, attempts: number): void;
   onStepRetry(instanceId: string, stepName: string, attempt: number, max: number, delayMs: number): void;
+  onStepPoll(instanceId: string, stepName: string, pollCount: number, done: boolean, result?: any): void;
+  onStepLoop(instanceId: string, stepName: string, loopCount: number, target: string): void;
   onProgress(instanceId: string, progress: number, currentStep: string, completed: number, total: number): void;
   onCompleted(instanceId: string, output: any): void;
   onFailed(instanceId: string, error: string): void;
@@ -136,11 +140,17 @@ export class WorkflowStateMachine {
       this.events.onStepStarted(instanceId, stepName, step.type);
 
       // Update step result as running
+      const previousStep = freshInstance.stepResults[stepName];
       const stepResult: StepResult = {
         stepName,
         status: "running",
-        startedAt: new Date(),
-        attempts: (freshInstance.stepResults[stepName]?.attempts ?? 0) + 1,
+        startedAt: previousStep?.startedAt ?? new Date(),
+        attempts: (previousStep?.attempts ?? 0) + 1,
+        pollCount: previousStep?.pollCount,
+        lastPolledAt: previousStep?.lastPolledAt,
+        loopCount: previousStep?.loopCount,
+        lastLoopedAt: previousStep?.lastLoopedAt,
+        loopStartedAt: previousStep?.loopStartedAt,
       };
       await this.adapter.updateInstance(instanceId, {
         currentStep: stepName,
@@ -166,6 +176,12 @@ export class WorkflowStateMachine {
           case "pass":
             output = await this.executePassStep(step, ctx);
             break;
+          case "poll":
+            output = await this.executePollStep(instanceId, step, ctx, definition);
+            break;
+          case "loop":
+            output = await this.executeLoopStep(instanceId, step, ctx);
+            break;
         }
 
         // Persist step completion
@@ -176,6 +192,8 @@ export class WorkflowStateMachine {
         if (step.type === "choice") {
           // Choice step returns { chosen: "nextStepName" }
           currentStepName = output?.chosen;
+        } else if (step.type === "loop" && output?.loopTo) {
+          currentStepName = output.loopTo;
         } else if (step.end) {
           currentStepName = undefined;
         } else if (step.next) {
@@ -445,6 +463,87 @@ export class WorkflowStateMachine {
     return output;
   }
 
+  private async executePollStep(
+    instanceId: string,
+    step: PollStepDefinition,
+    ctx: WorkflowContext,
+    _definition: WorkflowDefinition,
+  ): Promise<any> {
+    let input: any;
+
+    if (step.inputSchema) {
+      if (typeof step.inputSchema === "function") {
+        input = step.inputSchema(ctx.prev, ctx.input);
+      } else {
+        const parseResult = step.inputSchema.safeParse(ctx.input);
+        if (!parseResult.success) {
+          throw new Error(`Input validation failed: ${parseResult.error.message}`);
+        }
+        input = parseResult.data;
+      }
+    } else {
+      input = ctx.input;
+    }
+
+    let instance = await this.adapter.getInstance(instanceId);
+    const stepResult = instance?.stepResults[step.name];
+    const startedAt = stepResult?.startedAt ?? new Date();
+
+    if (instance && stepResult) {
+      stepResult.input = stepResult.input ?? input;
+      stepResult.pollCount = stepResult.pollCount ?? 0;
+      await this.adapter.updateInstance(instanceId, {
+        stepResults: { ...instance.stepResults, [step.name]: stepResult },
+      });
+    }
+
+    while (true) {
+      if (step.timeout && Date.now() - startedAt.getTime() > step.timeout) {
+        throw new Error(`Poll step "${step.name}" timed out`);
+      }
+
+      instance = await this.adapter.getInstance(instanceId);
+      const sr = instance?.stepResults[step.name];
+      const pollCount = sr?.pollCount ?? 0;
+
+      if (step.maxAttempts && pollCount >= step.maxAttempts) {
+        throw new Error(`Poll step "${step.name}" exceeded maxAttempts`);
+      }
+
+      if (step.interval > 0) {
+        await new Promise((resolve) => setTimeout(resolve, step.interval));
+      }
+
+      const result = await step.check(input, ctx);
+      const nextPollCount = pollCount + 1;
+
+      if (instance && sr) {
+        sr.pollCount = nextPollCount;
+        sr.lastPolledAt = new Date();
+        sr.output = result;
+        await this.adapter.updateInstance(instanceId, {
+          stepResults: { ...instance.stepResults, [step.name]: sr },
+        });
+      }
+
+      this.events.onStepPoll(instanceId, step.name, nextPollCount, result.done, result.result);
+
+      if (result.done) {
+        let output = result.result;
+
+        if (step.outputSchema) {
+          const parseResult = step.outputSchema.safeParse(output);
+          if (!parseResult.success) {
+            throw new Error(`Output validation failed: ${parseResult.error.message}`);
+          }
+          output = parseResult.data;
+        }
+
+        return output;
+      }
+    }
+  }
+
   private async executePassStep(
     step: PassStepDefinition,
     ctx: WorkflowContext,
@@ -458,6 +557,52 @@ export class WorkflowStateMachine {
     return ctx.input;
   }
 
+  private async executeLoopStep(
+    instanceId: string,
+    step: LoopStepDefinition,
+    ctx: WorkflowContext,
+  ): Promise<{ loopTo?: string }> {
+    const instance = await this.adapter.getInstance(instanceId);
+    const stepResult = instance?.stepResults[step.name] ?? {
+      stepName: step.name,
+      status: "running" as const,
+      attempts: 0,
+      startedAt: new Date(),
+    };
+    const loopStartedAt = stepResult.loopStartedAt ?? stepResult.startedAt ?? new Date();
+    const loopCount = stepResult.loopCount ?? 0;
+
+    if (step.timeout && Date.now() - loopStartedAt.getTime() > step.timeout) {
+      throw new Error(`Loop step "${step.name}" timed out`);
+    }
+
+    if (step.maxIterations && loopCount >= step.maxIterations) {
+      throw new Error(`Loop step "${step.name}" exceeded maxIterations`);
+    }
+
+    const shouldLoop = step.condition(ctx);
+
+    if (instance) {
+      stepResult.loopCount = shouldLoop ? loopCount + 1 : loopCount;
+      stepResult.loopStartedAt = loopStartedAt;
+      stepResult.lastLoopedAt = shouldLoop ? new Date() : stepResult.lastLoopedAt;
+      stepResult.output = { looped: shouldLoop };
+      await this.adapter.updateInstance(instanceId, {
+        stepResults: { ...instance.stepResults, [step.name]: stepResult },
+      });
+    }
+
+    if (shouldLoop) {
+      this.events.onStepLoop(instanceId, step.name, loopCount + 1, step.target);
+      if (step.interval && step.interval > 0) {
+        await new Promise((resolve) => setTimeout(resolve, step.interval));
+      }
+      return { loopTo: step.target };
+    }
+
+    return {};
+  }
+
   // ============================================
   // Context Building
   // ============================================

package/src/core/workflows.ts

@@ -59,7 +59,7 @@ type InferZodOutput<T extends ZodSchema> = z.infer<T>;
 // Step Types
 // ============================================
 
-export type StepType = "task" | "parallel" | "choice" | "pass";
+export type StepType = "task" | "parallel" | "choice" | "pass" | "poll" | "loop";
 
 export interface BaseStepDefinition {
   name: string;
@@ -146,11 +146,54 @@ export interface PassStepDefinition extends BaseStepDefinition {
   result?: any;
 }
 
+export interface PollStepResult<T = any> {
+  done: boolean;
+  result?: T;
+}
+
+export interface PollStepDefinition<
+  TInput extends ZodSchema = ZodSchema,
+  TOutput extends ZodSchema = ZodSchema,
+> extends BaseStepDefinition {
+  type: "poll";
+  /** Wait duration between checks in ms */
+  interval: number;
+  /** Max total time before failing this step (ms) */
+  timeout?: number;
+  /** Max number of check cycles before failing */
+  maxAttempts?: number;
+  /** Input schema or mapper */
+  inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+  /** Output schema for the final result */
+  outputSchema?: TOutput;
+  /** Check handler: return done:true to proceed */
+  check: (
+    input: InferZodOutput<TInput>,
+    ctx: WorkflowContext
+  ) => Promise<PollStepResult<InferZodOutput<TOutput>>> | PollStepResult<InferZodOutput<TOutput>>;
+}
+
+export interface LoopStepDefinition extends BaseStepDefinition {
+  type: "loop";
+  /** Condition to continue looping */
+  condition: (ctx: WorkflowContext) => boolean;
+  /** Step name to jump back to when condition is true */
+  target: string;
+  /** Optional delay before looping (ms) */
+  interval?: number;
+  /** Max total time before failing this loop (ms) */
+  timeout?: number;
+  /** Max number of loop iterations before failing */
+  maxIterations?: number;
+}
+
 export type StepDefinition =
   | TaskStepDefinition
   | ParallelStepDefinition
   | ChoiceStepDefinition
-  | PassStepDefinition;
+  | PassStepDefinition
+  | PollStepDefinition
+  | LoopStepDefinition;
 
 // ============================================
 // Workflow Definition
@@ -203,6 +246,11 @@ export interface StepResult {
   startedAt?: Date;
   completedAt?: Date;
   attempts: number;
+  pollCount?: number;
+  lastPolledAt?: Date;
+  loopCount?: number;
+  lastLoopedAt?: Date;
+  loopStartedAt?: Date;
 }
 
 export interface WorkflowInstance {
@@ -569,6 +617,69 @@ export class WorkflowBuilder {
     return this;
   }
 
+  loop(
+    name: string,
+    config: {
+      condition: (ctx: WorkflowContext) => boolean;
+      target: string;
+      interval?: number;
+      timeout?: number;
+      maxIterations?: number;
+      next?: string;
+      end?: boolean;
+    }
+  ): this {
+    const step: LoopStepDefinition = {
+      name,
+      type: "loop",
+      condition: config.condition,
+      target: config.target,
+      interval: config.interval,
+      timeout: config.timeout,
+      maxIterations: config.maxIterations,
+      next: config.next,
+      end: config.end,
+    };
+
+    this.addStep(step);
+    return this;
+  }
+
+  poll<TInput extends ZodSchema = ZodSchema, TOutput extends ZodSchema = ZodSchema>(
+    name: string,
+    config: {
+      check: (
+        input: InferZodOutput<TInput>,
+        ctx: WorkflowContext
+      ) => Promise<PollStepResult<InferZodOutput<TOutput>>> | PollStepResult<InferZodOutput<TOutput>>;
+      interval: number;
+      timeout?: number;
+      maxAttempts?: number;
+      inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+      outputSchema?: TOutput;
+      retry?: RetryConfig;
+      next?: string;
+      end?: boolean;
+    }
+  ): this {
+    const step: PollStepDefinition<TInput, TOutput> = {
+      name,
+      type: "poll",
+      check: config.check,
+      interval: config.interval,
+      timeout: config.timeout,
+      maxAttempts: config.maxAttempts,
+      inputSchema: config.inputSchema,
+      outputSchema: config.outputSchema,
+      retry: config.retry,
+      next: config.next,
+      end: config.end,
+    };
+
+    this.addStep(step);
+    return this;
+  }
+
   /** Add an end step (shorthand for pass with end: true) */
   end(name: string = "end"): this {
     return this.pass(name, { end: true });
@@ -1198,6 +1309,51 @@ class WorkflowsImpl implements Workflows {
           });
         }
       },
+      onStepPoll: (id, stepName, pollCount, done, result) => {
+        this.emitEvent("workflow.step.poll", {
+          instanceId: id,
+          stepName,
+          pollCount,
+          done,
+          result,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${id}`, "step.poll", {
+            stepName,
+            pollCount,
+            done,
+            result,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.poll", {
+            instanceId: id,
+            stepName,
+            pollCount,
+            done,
+            result,
+          });
+        }
+      },
+      onStepLoop: (id, stepName, loopCount, target) => {
+        this.emitEvent("workflow.step.loop", {
+          instanceId: id,
+          stepName,
+          loopCount,
+          target,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${id}`, "step.loop", {
+            stepName,
+            loopCount,
+            target,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.loop", {
+            instanceId: id,
+            stepName,
+            loopCount,
+            target,
+          });
+        }
+      },
       onStepRetry: (id, stepName, attempt, max, delayMs) => {
         this.emitEvent("workflow.step.retry", {
           instanceId: id,
@@ -1484,6 +1640,55 @@ class WorkflowsImpl implements Workflows {
         break;
       }
 
+      case "step.poll": {
+        await this.emitEvent("workflow.step.poll", {
+          instanceId,
+          stepName: event.stepName,
+          pollCount: event.pollCount,
+          done: event.done,
+          result: event.result,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "step.poll", {
+            stepName: event.stepName,
+            pollCount: event.pollCount,
+            done: event.done,
+            result: event.result,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.poll", {
+            instanceId,
+            stepName: event.stepName,
+            pollCount: event.pollCount,
+            done: event.done,
+            result: event.result,
+          });
+        }
+        break;
+      }
+
+      case "step.loop": {
+        await this.emitEvent("workflow.step.loop", {
+          instanceId,
+          stepName: event.stepName,
+          loopCount: event.loopCount,
+          target: event.target,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "step.loop", {
+            stepName: event.stepName,
+            loopCount: event.loopCount,
+            target: event.target,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.loop", {
+            instanceId,
+            stepName: event.stepName,
+            loopCount: event.loopCount,
+            target: event.target,
+          });
+        }
+        break;
+      }
+
       case "progress": {
         await this.emitEvent("workflow.progress", {
           instanceId,