stagent 0.9.5 → 0.10.0

package/src/lib/workflows/__tests__/post-action.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import {
+  resolvePostAction,
+  shouldSkipPostActionValue,
+  extractPostActionValue,
+} from "../post-action";
+import type { StepPostAction } from "../types";
+
+describe("resolvePostAction", () => {
+  it("substitutes {{row.id}} with the row's id field", () => {
+    const action: StepPostAction = {
+      type: "update_row",
+      tableId: "tbl_contacts",
+      rowId: "{{row.id}}",
+      column: "linkedin",
+    };
+    const row = { id: "row_abc", name: "Alice" };
+
+    const resolved = resolvePostAction(action, row, "row");
+
+    expect(resolved.rowId).toBe("row_abc");
+    expect(resolved.tableId).toBe("tbl_contacts");
+    expect(resolved.column).toBe("linkedin");
+  });
+
+  it("respects a custom itemVariable name", () => {
+    const action: StepPostAction = {
+      type: "update_row",
+      tableId: "tbl_x",
+      rowId: "{{contact.id}}",
+      column: "email",
+    };
+    const row = { id: "c_42" };
+
+    const resolved = resolvePostAction(action, row, "contact");
+
+    expect(resolved.rowId).toBe("c_42");
+  });
+
+  it("supports nested field paths like {{row.meta.id}}", () => {
+    const action: StepPostAction = {
+      type: "update_row",
+      tableId: "tbl_x",
+      rowId: "{{row.meta.id}}",
+      column: "value",
+    };
+    const row = { meta: { id: "nested_99" } };
+
+    const resolved = resolvePostAction(action, row, "row");
+
+    expect(resolved.rowId).toBe("nested_99");
+  });
+
+  it("leaves rowId untouched when no placeholder is present", () => {
+    const action: StepPostAction = {
+      type: "update_row",
+      tableId: "tbl_x",
+      rowId: "literal_row_id",
+      column: "value",
+    };
+
+    const resolved = resolvePostAction(action, { id: "ignored" }, "row");
+
+    expect(resolved.rowId).toBe("literal_row_id");
+  });
+});
+
+describe("shouldSkipPostActionValue", () => {
+  it("skips empty strings", () => {
+    expect(shouldSkipPostActionValue("")).toBe(true);
+    expect(shouldSkipPostActionValue("   ")).toBe(true);
+    expect(shouldSkipPostActionValue("\n\t")).toBe(true);
+  });
+
+  it("skips NOT_FOUND sentinel (case-insensitive)", () => {
+    expect(shouldSkipPostActionValue("NOT_FOUND")).toBe(true);
+    expect(shouldSkipPostActionValue("not_found")).toBe(true);
+    expect(shouldSkipPostActionValue("  NOT_FOUND  ")).toBe(true);
+    expect(shouldSkipPostActionValue("Not_Found")).toBe(true);
+  });
+
+  it("does not skip real values", () => {
+    expect(shouldSkipPostActionValue("https://linkedin.com/in/alice")).toBe(false);
+    expect(shouldSkipPostActionValue("alice@example.com")).toBe(false);
+    expect(shouldSkipPostActionValue("0")).toBe(false);
+  });
+
+  it("does not skip values that merely contain NOT_FOUND as a substring", () => {
+    // We only skip when the trimmed value IS the sentinel; substrings stay.
+    expect(shouldSkipPostActionValue("Status: NOT_FOUND in registry")).toBe(false);
+  });
+});
+
+describe("extractPostActionValue", () => {
+  it("trims whitespace from the agent result", () => {
+    expect(extractPostActionValue("  hello  ")).toBe("hello");
+    expect(extractPostActionValue("\nhttps://example.com\n")).toBe("https://example.com");
+  });
+
+  it("returns the raw string for normal values", () => {
+    expect(extractPostActionValue("plain")).toBe("plain");
+  });
+
+  it("returns empty string for null/undefined-shaped inputs", () => {
+    expect(extractPostActionValue(undefined)).toBe("");
+    expect(extractPostActionValue("")).toBe("");
+  });
+});

package/src/lib/workflows/blueprints/instantiator.ts

@@ -2,7 +2,7 @@ import { db } from "@/lib/db";
 import { workflows } from "@/lib/db/schema";
 import { getBlueprint } from "./registry";
 import { resolveTemplate, evaluateCondition } from "./template";
-import type { BlueprintVariable, WorkflowBlueprint } from "./types";
+import type { BlueprintVariable } from "./types";
 import type { WorkflowStep } from "../types";
 
 interface InstantiateResult {
@@ -48,6 +48,27 @@ export async function instantiateBlueprint(
       continue;
     }
 
+    // Delay step: a pure time wait with no prompt/profile. Blueprint validation
+    // enforces that delayDuration and profileId+promptTemplate are mutually
+    // exclusive (XOR), so branching here is safe.
+    if (step.delayDuration) {
+      resolvedSteps.push({
+        id: crypto.randomUUID(),
+        name: step.name,
+        prompt: "",
+        requiresApproval: step.requiresApproval,
+        delayDuration: step.delayDuration,
+      });
+      continue;
+    }
+
+    // Task step: profileId + promptTemplate must be present (XOR contract).
+    if (!step.promptTemplate) {
+      throw new Error(
+        `Blueprint step "${step.name}" has no promptTemplate — blueprint validation should have caught this.`,
+      );
+    }
+
     const resolvedPrompt = resolveTemplate(step.promptTemplate, resolvedVars);
 
     resolvedSteps.push({

package/src/lib/workflows/blueprints/types.ts

@@ -11,10 +11,18 @@ export interface BlueprintVariable {
   max?: number;
 }
 
+/**
+ * A blueprint step is either a task step (profileId + promptTemplate) OR a
+ * delay step (delayDuration only). The XOR is enforced at validation time
+ * by BlueprintStepSchema in src/lib/validators/blueprint.ts — at the type
+ * level, all three fields are optional so either shape is assignable.
+ */
 export interface BlueprintStep {
   name: string;
-  profileId: string;
-  promptTemplate: string;
+  profileId?: string;
+  promptTemplate?: string;
+  /** If set, this step is a pure time delay. Format: Nm|Nh|Nd|Nw. */
+  delayDuration?: string;
   requiresApproval: boolean;
   expectedOutput?: string;
   condition?: string;

package/src/lib/workflows/delay.ts

@@ -0,0 +1,106 @@
+/**
+ * Duration parser and formatter for workflow step delays.
+ *
+ * Format: Nm (minutes), Nh (hours), Nd (days), Nw (weeks).
+ * Bounds: minimum 1 minute, maximum 30 days.
+ * Compound formats (e.g. "3d2h") are not supported.
+ *
+ * See features/workflow-step-delays.md for the spec.
+ */
+
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const MS_PER_WEEK = 7 * MS_PER_DAY;
+
+const MIN_DURATION_MS = MS_PER_MINUTE;
+const MAX_DURATION_MS = 30 * MS_PER_DAY;
+
+const DURATION_PATTERN = /^(\d+)(m|h|d|w)$/;
+
+const UNIT_MS: Record<string, number> = {
+  m: MS_PER_MINUTE,
+  h: MS_PER_HOUR,
+  d: MS_PER_DAY,
+  w: MS_PER_WEEK,
+};
+
+/**
+ * Parse a duration string into milliseconds.
+ *
+ * @throws if the format is invalid or the value is outside bounds.
+ */
+export function parseDuration(input: string): number {
+  const match = input.match(DURATION_PATTERN);
+  if (!match) {
+    throw new Error(
+      `Invalid duration: "${input}". Use format: 30m, 2h, 3d, 1w`,
+    );
+  }
+
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  const ms = value * UNIT_MS[unit];
+
+  if (ms < MIN_DURATION_MS) {
+    throw new Error(`Duration below minimum: "${input}". Minimum is 1 minute (1m).`);
+  }
+  if (ms > MAX_DURATION_MS) {
+    throw new Error(`Duration above maximum: "${input}". Maximum is 30 days (30d).`);
+  }
+
+  return ms;
+}
+
+/**
+ * Result of checking whether a workflow step is a delay step or a task step.
+ * The engine branches on this — delay steps pause the workflow, task steps
+ * execute normally.
+ */
+export type DelayCheck =
+  | { type: "task" }
+  | { type: "delay"; resumeAt: number };
+
+/**
+ * Classify a workflow step as either a delay step or a task step, and compute
+ * the resume timestamp for delay steps.
+ *
+ * Pure function: no I/O, no side effects. The engine calls this inside the
+ * sequence executor loop and branches on the result. Invalid duration formats
+ * throw — blueprint validation (src/lib/validators/blueprint.ts) should catch
+ * these at the workflow-creation boundary, so any invalid duration reaching
+ * here is a programming error and must fail loudly.
+ *
+ * @param step  Workflow step (any object with an optional delayDuration field)
+ * @param now   Current epoch timestamp in milliseconds (injected for testability)
+ */
+export function checkDelayStep(
+  step: { delayDuration?: string },
+  now: number,
+): DelayCheck {
+  if (!step.delayDuration) {
+    return { type: "task" };
+  }
+  return {
+    type: "delay",
+    resumeAt: now + parseDuration(step.delayDuration),
+  };
+}
+
+/**
+ * Format a millisecond duration back into the canonical string form.
+ * Prefers the largest unit that divides cleanly; falls back to minutes
+ * when no larger unit divides evenly.
+ */
+export function formatDuration(ms: number): string {
+  if (ms >= MS_PER_WEEK && ms % MS_PER_WEEK === 0) {
+    return `${ms / MS_PER_WEEK}w`;
+  }
+  if (ms >= MS_PER_DAY && ms % MS_PER_DAY === 0) {
+    return `${ms / MS_PER_DAY}d`;
+  }
+  if (ms >= MS_PER_HOUR && ms % MS_PER_HOUR === 0) {
+    return `${ms / MS_PER_HOUR}h`;
+  }
+  return `${ms / MS_PER_MINUTE}m`;
+}

package/src/lib/workflows/engine.ts

@@ -1,11 +1,12 @@
 import { db } from "@/lib/db";
 import { workflows, tasks, agentLogs, notifications } from "@/lib/db/schema";
-import { eq } from "drizzle-orm";
+import { and, eq } from "drizzle-orm";
 import { executeTaskWithRuntime } from "@/lib/agents/runtime";
 import { classifyTaskProfile } from "@/lib/agents/router";
 import type { WorkflowDefinition, WorkflowState, StepState, LoopState } from "./types";
 import { createInitialState } from "./types";
 import { executeLoop } from "./loop-executor";
+import { checkDelayStep } from "./delay";
 import {
   buildParallelSynthesisPrompt,
   getParallelWorkflowStructure,
@@ -138,6 +139,24 @@ export async function executeWorkflow(workflowId: string): Promise<void> {
         break;
     }
 
+    // A delay step may have paused the workflow. The sequence executor already
+    // persisted the paused state and wrote resume_at; we just need to log the
+    // pause and return without marking the workflow "completed".
+    if (state.status === "paused") {
+      await db.insert(agentLogs).values({
+        id: crypto.randomUUID(),
+        taskId: null,
+        agentType: "workflow-engine",
+        event: "workflow_paused_for_delay",
+        payload: JSON.stringify({
+          workflowId,
+          delayedStepIndex: state.currentStepIndex,
+        }),
+        timestamp: new Date(),
+      });
+      return;
+    }
+
     state.status = "completed";
     state.completedAt = new Date().toISOString();
     await updateWorkflowState(workflowId, state, "completed");
@@ -179,20 +198,56 @@ export async function executeWorkflow(workflowId: string): Promise<void> {
 
 /**
  * Sequence pattern: execute steps one after another, passing output forward.
+ *
+ * @param fromStepIndex  Start index for resuming after a delay. Defaults to 0
+ *                       for fresh executions. resumeWorkflow passes the index
+ *                       of the step after the one that was delayed.
  */
 async function executeSequence(
   workflowId: string,
   definition: WorkflowDefinition,
   state: WorkflowState,
   parentTaskId?: string,
-  workflowRuntimeId?: string
+  workflowRuntimeId?: string,
+  fromStepIndex: number = 0,
 ): Promise<void> {
   let previousOutput = "";
 
-  for (let i = 0; i < definition.steps.length; i++) {
+  for (let i = fromStepIndex; i < definition.steps.length; i++) {
     const step = definition.steps[i];
     state.currentStepIndex = i;
 
+    // Delay step: pause the workflow and return. The scheduler tick will call
+    // resumeWorkflow when workflows.resume_at <= now(). See features/workflow-step-delays.md.
+    const delayCheck = checkDelayStep(step, Date.now());
+    if (delayCheck.type === "delay") {
+      state.stepStates[i].status = "delayed";
+      state.stepStates[i].startedAt = new Date().toISOString();
+      state.status = "paused";
+      await updateWorkflowState(workflowId, state, "paused");
+      // Write resume_at to the indexed workflows column so the scheduler tick
+      // can find this workflow efficiently via the partial index.
+      await db
+        .update(workflows)
+        .set({ resumeAt: delayCheck.resumeAt, updatedAt: new Date() })
+        .where(eq(workflows.id, workflowId));
+      await db.insert(agentLogs).values({
+        id: crypto.randomUUID(),
+        taskId: null,
+        agentType: "workflow-engine",
+        event: "step_delayed",
+        payload: JSON.stringify({
+          workflowId,
+          stepId: step.id,
+          stepName: step.name,
+          delayDuration: step.delayDuration,
+          resumeAt: delayCheck.resumeAt,
+        }),
+        timestamp: new Date(),
+      });
+      return;
+    }
+
     // Build prompt with context from previous step
     const contextPrompt = previousOutput
       ? `Previous step output:\n${previousOutput}\n\n---\n\n${step.prompt}`
@@ -1101,7 +1156,20 @@ export async function updateWorkflowState(
 
   if (!workflow) throw new Error(`Workflow ${workflowId} not found — cannot update state`);
 
-  const definition = JSON.parse(workflow.definition);
+  // Defensive parse: a workflow row with a missing or corrupted definition
+  // should not crash the engine. We still write the new _state on top, so a
+  // recoverable run can continue even from a partially-written row.
+  let definition: Record<string, unknown> = {};
+  if (workflow.definition) {
+    try {
+      definition = JSON.parse(workflow.definition);
+    } catch (err) {
+      console.error(
+        `[workflow-engine] Failed to parse definition for ${workflowId}, writing fresh state:`,
+        err
+      );
+    }
+  }
   const combined = { ...definition, _state: state };
 
   await db
@@ -1114,6 +1182,141 @@ export async function updateWorkflowState(
     .where(eq(workflows.id, workflowId));
 }
 
+/**
+ * Resume a workflow that was paused at a delay step.
+ *
+ * Called by the scheduler tick when workflows.resume_at <= now(), and also
+ * by the manual POST /api/workflows/[id]/resume endpoint when the user clicks
+ * "Resume Now". The status transition is atomic (UPDATE ... WHERE status='paused')
+ * so a scheduler tick and a user click racing each other produces exactly one
+ * resume — the loser sees zero affected rows and returns silently.
+ *
+ * Only supports sequence-pattern workflows — other patterns never enter the
+ * paused state in the first place (delay steps are sequence-only per spec).
+ */
+export async function resumeWorkflow(workflowId: string): Promise<void> {
+  // Atomic status transition: only proceed if still paused.
+  const updated = await db
+    .update(workflows)
+    .set({ status: "active", resumeAt: null, updatedAt: new Date() })
+    .where(and(eq(workflows.id, workflowId), eq(workflows.status, "paused")))
+    .returning();
+
+  if (updated.length === 0) {
+    // Workflow is not paused — either already resumed (scheduler raced user,
+    // or vice versa) or doesn't exist. Idempotent: no error, no action.
+    return;
+  }
+
+  const workflow = updated[0];
+  const { definition, state } = parseWorkflowState(workflow.definition);
+
+  if (!state) {
+    throw new Error(
+      `Workflow ${workflowId} is marked paused but has no persisted state to resume`,
+    );
+  }
+
+  if (definition.pattern !== "sequence") {
+    throw new Error(
+      `Workflow ${workflowId} has pattern "${definition.pattern}" — resume is only supported for sequence pattern`,
+    );
+  }
+
+  // Mark the delayed step as completed, advance to the next step.
+  const delayedIdx = state.currentStepIndex;
+  const delayedStepState = state.stepStates[delayedIdx];
+  if (delayedStepState && delayedStepState.status === "delayed") {
+    delayedStepState.status = "completed";
+    delayedStepState.completedAt = new Date().toISOString();
+  }
+  state.status = "running";
+  const resumeFromIndex = delayedIdx + 1;
+
+  await db.insert(agentLogs).values({
+    id: crypto.randomUUID(),
+    taskId: null,
+    agentType: "workflow-engine",
+    event: "workflow_resumed",
+    payload: JSON.stringify({ workflowId, resumeFromIndex }),
+    timestamp: new Date(),
+  });
+
+  const parentTaskId = definition.sourceTaskId;
+  const workflowRuntimeId = workflow.runtimeId ?? undefined;
+
+  // Reopen the learning session for this resume. Context proposals gathered
+  // during the pre-pause run were already flushed when the original execute
+  // closed its session; resume starts a fresh batch.
+  openLearningSession(workflowId);
+
+  try {
+    await executeSequence(
+      workflowId,
+      definition,
+      state,
+      parentTaskId,
+      workflowRuntimeId,
+      resumeFromIndex,
+    );
+
+    // Another delay step may have been encountered during resume. TS narrows
+    // state.status to "running" at this point because of the assignment above,
+    // but executeSequence mutates state.status to "paused" when it hits a delay
+    // step — the `as` cast forces TS to forget the narrowing and evaluate the
+    // comparison at runtime.
+    if ((state.status as WorkflowState["status"]) === "paused") {
+      await db.insert(agentLogs).values({
+        id: crypto.randomUUID(),
+        taskId: null,
+        agentType: "workflow-engine",
+        event: "workflow_paused_for_delay",
+        payload: JSON.stringify({
+          workflowId,
+          delayedStepIndex: state.currentStepIndex,
+        }),
+        timestamp: new Date(),
+      });
+      return;
+    }
+
+    state.status = "completed";
+    state.completedAt = new Date().toISOString();
+    await updateWorkflowState(workflowId, state, "completed");
+
+    await db.insert(agentLogs).values({
+      id: crypto.randomUUID(),
+      taskId: null,
+      agentType: "workflow-engine",
+      event: "workflow_completed",
+      payload: JSON.stringify({ workflowId }),
+      timestamp: new Date(),
+    });
+  } catch (error) {
+    state.status = "failed";
+    await updateWorkflowState(workflowId, state, "failed");
+
+    await db.insert(agentLogs).values({
+      id: crypto.randomUUID(),
+      taskId: null,
+      agentType: "workflow-engine",
+      event: "workflow_failed",
+      payload: JSON.stringify({
+        workflowId,
+        error: error instanceof Error ? error.message : String(error),
+      }),
+      timestamp: new Date(),
+    });
+  } finally {
+    updateExecutionStats(workflowId).catch((err) => {
+      console.error("[workflow-engine] Stats update failed:", err);
+    });
+    await closeLearningSession(workflowId).catch((err) => {
+      console.error("[workflow-engine] Failed to close learning session:", err);
+    });
+  }
+}
+
 /**
  * Get the current state of a workflow.
  */