stagent 0.9.5 → 0.10.0

package/src/lib/validators/__tests__/blueprint.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { BlueprintStepSchema } from "../blueprint";
+
+// ── Task step fixtures ──────────────────────────────────────────────────
+
+const validTaskStep = {
+  name: "Research prospect",
+  profileId: "sales-researcher",
+  promptTemplate: "Research {{row.name}}",
+  requiresApproval: false,
+};
+
+// ── Delay step fixtures ─────────────────────────────────────────────────
+
+const validDelayStep = {
+  name: "Wait 3 days",
+  delayDuration: "3d",
+  requiresApproval: false,
+};
+
+describe("BlueprintStepSchema", () => {
+  describe("task step (profile + prompt)", () => {
+    it("accepts a valid task step", () => {
+      const result = BlueprintStepSchema.safeParse(validTaskStep);
+      expect(result.success).toBe(true);
+    });
+
+    it("accepts a task step with optional expectedOutput and condition", () => {
+      const result = BlueprintStepSchema.safeParse({
+        ...validTaskStep,
+        expectedOutput: "structured-findings",
+        condition: "rowCount > 0",
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it("rejects a task step missing profileId", () => {
+      const { profileId: _profileId, ...stepWithoutProfile } = validTaskStep;
+      const result = BlueprintStepSchema.safeParse(stepWithoutProfile);
+      expect(result.success).toBe(false);
+    });
+
+    it("rejects a task step missing promptTemplate", () => {
+      const { promptTemplate: _promptTemplate, ...stepWithoutPrompt } = validTaskStep;
+      const result = BlueprintStepSchema.safeParse(stepWithoutPrompt);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe("delay step (duration only)", () => {
+    it("accepts a valid delay step", () => {
+      const result = BlueprintStepSchema.safeParse(validDelayStep);
+      expect(result.success).toBe(true);
+    });
+
+    it("accepts all valid duration formats", () => {
+      for (const duration of ["1m", "30m", "2h", "3d", "1w", "30d"]) {
+        const result = BlueprintStepSchema.safeParse({
+          ...validDelayStep,
+          delayDuration: duration,
+        });
+        expect(result.success, `duration "${duration}" should validate`).toBe(true);
+      }
+    });
+
+    it("rejects a delay step with invalid duration format", () => {
+      const result = BlueprintStepSchema.safeParse({
+        ...validDelayStep,
+        delayDuration: "bogus",
+      });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(JSON.stringify(result.error.issues)).toMatch(/30m, 2h, 3d, 1w/);
+      }
+    });
+
+    it("rejects a delay step with duration below 1 minute", () => {
+      const result = BlueprintStepSchema.safeParse({
+        ...validDelayStep,
+        delayDuration: "0m",
+      });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(JSON.stringify(result.error.issues)).toMatch(/minimum/i);
+      }
+    });
+
+    it("rejects a delay step with duration above 30 days", () => {
+      const result = BlueprintStepSchema.safeParse({
+        ...validDelayStep,
+        delayDuration: "31d",
+      });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(JSON.stringify(result.error.issues)).toMatch(/maximum/i);
+      }
+    });
+
+    it("rejects compound duration formats", () => {
+      const result = BlueprintStepSchema.safeParse({
+        ...validDelayStep,
+        delayDuration: "3d2h",
+      });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe("XOR cross-field validation", () => {
+    it("rejects a step that mixes delayDuration with profileId", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Mixed",
+        profileId: "sales-researcher",
+        delayDuration: "3d",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(JSON.stringify(result.error.issues)).toMatch(/delay|task|both/i);
+      }
+    });
+
+    it("rejects a step that mixes delayDuration with promptTemplate", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Mixed",
+        promptTemplate: "Do the thing",
+        delayDuration: "3d",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it("rejects a step that mixes all three fields", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Mixed",
+        profileId: "sales-researcher",
+        promptTemplate: "Do the thing",
+        delayDuration: "3d",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it("rejects a step with neither delay nor task fields", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Empty",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(JSON.stringify(result.error.issues)).toMatch(/delay|profile|prompt|required/i);
+      }
+    });
+
+    it("rejects a step with profileId but missing promptTemplate (partial task step)", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Partial",
+        profileId: "sales-researcher",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it("rejects a step with promptTemplate but missing profileId (partial task step)", () => {
+      const result = BlueprintStepSchema.safeParse({
+        name: "Partial",
+        promptTemplate: "Do the thing",
+        requiresApproval: false,
+      });
+      expect(result.success).toBe(false);
+    });
+  });
+});

package/src/lib/validators/__tests__/settings.test.ts

@@ -83,14 +83,24 @@ describe("updateAuthSettingsSchema", () => {
 describe("updateOpenAISettingsSchema", () => {
   it("accepts valid OpenAI API keys", () => {
     const result = updateOpenAISettingsSchema.safeParse({
+      method: "api_key",
       apiKey: "sk-test-openai",
     });
 
     expect(result.success).toBe(true);
   });
 
+  it("accepts oauth mode without an API key", () => {
+    const result = updateOpenAISettingsSchema.safeParse({
+      method: "oauth",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
   it("rejects keys without the sk- prefix", () => {
     const result = updateOpenAISettingsSchema.safeParse({
+      method: "api_key",
       apiKey: "invalid",
     });
 

package/src/lib/validators/blueprint.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { parseDuration } from "@/lib/workflows/delay";
 
 export const BlueprintVariableSchema = z.object({
   id: z.string(),
@@ -15,14 +16,74 @@ export const BlueprintVariableSchema = z.object({
   max: z.number().optional(),
 });
 
-export const BlueprintStepSchema = z.object({
-  name: z.string(),
-  profileId: z.string(),
-  promptTemplate: z.string(),
-  requiresApproval: z.boolean(),
-  expectedOutput: z.string().optional(),
-  condition: z.string().optional(),
-});
+/**
+ * A blueprint step is either a task step (profileId + promptTemplate) OR a
+ * delay step (delayDuration). The discriminator lives in the cross-field
+ * refinement below — we can't use Zod's discriminatedUnion directly because
+ * YAML blueprints don't carry an explicit `type` field, and we want validation
+ * errors to point at the actual offending field, not a missing discriminator.
+ *
+ * See features/workflow-step-delays.md for the XOR rule rationale.
+ */
+export const BlueprintStepSchema = z
+  .object({
+    name: z.string(),
+    profileId: z.string().optional(),
+    promptTemplate: z.string().optional(),
+    delayDuration: z.string().optional(),
+    requiresApproval: z.boolean(),
+    expectedOutput: z.string().optional(),
+    condition: z.string().optional(),
+  })
+  .superRefine((step, ctx) => {
+    const hasDelay = step.delayDuration != null;
+    const hasProfile = step.profileId != null;
+    const hasPrompt = step.promptTemplate != null;
+    const hasAnyTaskField = hasProfile || hasPrompt;
+
+    // XOR: exactly one of (delay step) or (task step) must be present.
+    if (hasDelay && hasAnyTaskField) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["delayDuration"],
+        message:
+          "Step cannot be both a delay and a task: remove delayDuration, or remove profileId/promptTemplate.",
+      });
+      return;
+    }
+
+    if (hasDelay) {
+      // Delay step: validate the duration string parses and is within bounds.
+      try {
+        parseDuration(step.delayDuration as string);
+      } catch (err) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["delayDuration"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      return;
+    }
+
+    // Task step: profileId AND promptTemplate are both required.
+    if (!hasProfile) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["profileId"],
+        message:
+          "Task step requires profileId. For a delay step, set delayDuration instead (e.g. '3d').",
+      });
+    }
+    if (!hasPrompt) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["promptTemplate"],
+        message:
+          "Task step requires promptTemplate. For a delay step, set delayDuration instead (e.g. '3d').",
+      });
+    }
+  });
 
 export const BlueprintSchema = z.object({
   id: z.string(),
@@ -35,7 +96,7 @@ export const BlueprintSchema = z.object({
   variables: z.array(BlueprintVariableSchema),
   steps: z.array(BlueprintStepSchema).min(1),
   author: z.string().optional(),
-  source: z.string().url().optional(),
+  source: z.url().optional(),
   estimatedDuration: z.string().optional(),
   difficulty: z.enum(["beginner", "intermediate", "advanced"]).optional(),
 });

package/src/lib/validators/profile.ts

@@ -33,7 +33,7 @@ const profileRuntimeCapabilityOverrideSchema = z.object({
 });
 
 export const importMetaSchema = z.object({
-  repoUrl: z.string().url(),
+  repoUrl: z.url(),
   repoOwner: z.string(),
   repoName: z.string(),
   branch: z.string(),
@@ -64,7 +64,7 @@ export const ProfileConfigSchema = z.object({
   maxTurns: z.number().positive().optional(),
   outputFormat: z.string().optional(),
   author: z.string().optional(),
-  source: z.string().url().optional(),
+  source: z.url().optional(),
   tests: profileTestsSchema.optional(),
   importMeta: importMetaSchema.optional(),
   supportedRuntimes: z.array(runtimeIdSchema).optional(),

package/src/lib/validators/settings.ts

@@ -12,9 +12,11 @@ export const updateAuthSettingsSchema = z.object({
 export type UpdateAuthSettingsInput = z.infer<typeof updateAuthSettingsSchema>;
 
 export const updateOpenAISettingsSchema = z.object({
+  method: z.enum(["api_key", "oauth"]),
   apiKey: z
     .string()
-    .startsWith("sk-", "API key must start with sk-"),
+    .startsWith("sk-", "API key must start with sk-")
+    .optional(),
 });
 
 export type UpdateOpenAISettingsInput = z.infer<typeof updateOpenAISettingsSchema>;

package/src/lib/workflows/__tests__/delay.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { parseDuration, formatDuration, checkDelayStep } from "../delay";
+
+describe("parseDuration", () => {
+  describe("valid inputs", () => {
+    it("parses minutes", () => {
+      expect(parseDuration("1m")).toBe(60_000);
+      expect(parseDuration("30m")).toBe(30 * 60_000);
+    });
+
+    it("parses hours", () => {
+      expect(parseDuration("1h")).toBe(60 * 60_000);
+      expect(parseDuration("2h")).toBe(2 * 60 * 60_000);
+    });
+
+    it("parses days", () => {
+      expect(parseDuration("1d")).toBe(24 * 60 * 60_000);
+      expect(parseDuration("3d")).toBe(3 * 24 * 60 * 60_000);
+    });
+
+    it("parses weeks", () => {
+      expect(parseDuration("1w")).toBe(7 * 24 * 60 * 60_000);
+      expect(parseDuration("2w")).toBe(14 * 24 * 60 * 60_000);
+    });
+  });
+
+  describe("bounds", () => {
+    it("accepts minimum of 1 minute", () => {
+      expect(parseDuration("1m")).toBe(60_000);
+    });
+
+    it("accepts maximum of 30 days", () => {
+      expect(parseDuration("30d")).toBe(30 * 24 * 60 * 60_000);
+    });
+
+    it("rejects durations below 1 minute", () => {
+      // Note: "0m" is syntactically valid but below minimum
+      expect(() => parseDuration("0m")).toThrow(/minimum/i);
+    });
+
+    it("rejects durations above 30 days", () => {
+      expect(() => parseDuration("31d")).toThrow(/maximum/i);
+      expect(() => parseDuration("5w")).toThrow(/maximum/i);
+    });
+  });
+
+  describe("invalid formats", () => {
+    it("rejects empty string", () => {
+      expect(() => parseDuration("")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects missing unit", () => {
+      expect(() => parseDuration("30")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects missing number", () => {
+      expect(() => parseDuration("m")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects unsupported units", () => {
+      expect(() => parseDuration("30s")).toThrow(/invalid duration/i);
+      expect(() => parseDuration("1y")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects compound durations", () => {
+      expect(() => parseDuration("3d2h")).toThrow(/invalid duration/i);
+      expect(() => parseDuration("1h30m")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects decimal values", () => {
+      expect(() => parseDuration("1.5h")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects negative values", () => {
+      expect(() => parseDuration("-1h")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects whitespace", () => {
+      expect(() => parseDuration(" 1h")).toThrow(/invalid duration/i);
+      expect(() => parseDuration("1h ")).toThrow(/invalid duration/i);
+      expect(() => parseDuration("1 h")).toThrow(/invalid duration/i);
+    });
+
+    it("rejects uppercase units", () => {
+      // Strict format — users must use lowercase per the pattern hint
+      expect(() => parseDuration("1H")).toThrow(/invalid duration/i);
+    });
+  });
+
+  describe("error messages", () => {
+    it("includes format hint in invalid-format errors", () => {
+      expect(() => parseDuration("bogus")).toThrow(/30m, 2h, 3d, 1w/);
+    });
+
+    it("includes the minimum bound in too-small errors", () => {
+      expect(() => parseDuration("0m")).toThrow(/1 minute|1m/i);
+    });
+
+    it("includes the maximum bound in too-large errors", () => {
+      expect(() => parseDuration("31d")).toThrow(/30 day|30d/i);
+    });
+  });
+});
+
+describe("formatDuration", () => {
+  it("formats exact minutes", () => {
+    expect(formatDuration(60_000)).toBe("1m");
+    expect(formatDuration(30 * 60_000)).toBe("30m");
+  });
+
+  it("formats exact hours", () => {
+    expect(formatDuration(60 * 60_000)).toBe("1h");
+    expect(formatDuration(2 * 60 * 60_000)).toBe("2h");
+  });
+
+  it("formats exact days", () => {
+    expect(formatDuration(24 * 60 * 60_000)).toBe("1d");
+    expect(formatDuration(3 * 24 * 60 * 60_000)).toBe("3d");
+  });
+
+  it("formats exact weeks", () => {
+    expect(formatDuration(7 * 24 * 60 * 60_000)).toBe("1w");
+    expect(formatDuration(2 * 7 * 24 * 60 * 60_000)).toBe("2w");
+  });
+
+  it("prefers the largest exact unit", () => {
+    // 7 days = 1w, not 7d
+    expect(formatDuration(7 * 24 * 60 * 60_000)).toBe("1w");
+    // 24 hours = 1d, not 24h
+    expect(formatDuration(24 * 60 * 60_000)).toBe("1d");
+    // 60 minutes = 1h, not 60m
+    expect(formatDuration(60 * 60_000)).toBe("1h");
+  });
+
+  it("falls back to minutes when no larger unit divides cleanly", () => {
+    // 90 minutes — not a clean hour
+    expect(formatDuration(90 * 60_000)).toBe("90m");
+    // 95 minutes — not a clean hour, day, or week
+    expect(formatDuration(95 * 60_000)).toBe("95m");
+  });
+
+  it("uses hour level when minutes divide cleanly into hours but not days", () => {
+    // 25 hours — divides cleanly as hours, but not as a day
+    expect(formatDuration(25 * 60 * 60_000)).toBe("25h");
+  });
+
+  it("roundtrips with parseDuration for canonical forms", () => {
+    const canonical = ["1m", "30m", "1h", "2h", "1d", "3d", "1w", "2w", "30d"];
+    for (const input of canonical) {
+      expect(formatDuration(parseDuration(input))).toBe(input);
+    }
+  });
+});
+
+describe("checkDelayStep", () => {
+  const now = 1_700_000_000_000; // fixed epoch ms for deterministic tests
+
+  it("returns type 'task' for a step without delayDuration", () => {
+    expect(checkDelayStep({}, now)).toEqual({ type: "task" });
+  });
+
+  it("returns type 'task' when delayDuration is undefined explicitly", () => {
+    expect(checkDelayStep({ delayDuration: undefined }, now)).toEqual({ type: "task" });
+  });
+
+  it("returns type 'delay' with resumeAt = now + duration for a valid delay", () => {
+    const result = checkDelayStep({ delayDuration: "3d" }, now);
+    expect(result).toEqual({
+      type: "delay",
+      resumeAt: now + 3 * 24 * 60 * 60_000,
+    });
+  });
+
+  it("computes resumeAt correctly for each unit", () => {
+    expect(checkDelayStep({ delayDuration: "30m" }, now)).toEqual({
+      type: "delay",
+      resumeAt: now + 30 * 60_000,
+    });
+    expect(checkDelayStep({ delayDuration: "2h" }, now)).toEqual({
+      type: "delay",
+      resumeAt: now + 2 * 60 * 60_000,
+    });
+    expect(checkDelayStep({ delayDuration: "1w" }, now)).toEqual({
+      type: "delay",
+      resumeAt: now + 7 * 24 * 60 * 60_000,
+    });
+  });
+
+  it("throws when delayDuration is present but invalid (boundary responsibility)", () => {
+    // The engine should call checkDelayStep AFTER blueprint validation, so invalid
+    // formats reaching here are a programming error and must fail loudly.
+    expect(() => checkDelayStep({ delayDuration: "bogus" }, now)).toThrow(
+      /invalid duration/i,
+    );
+  });
+});

package/src/lib/workflows/__tests__/engine.test.ts

@@ -46,16 +46,24 @@ vi.mock("@/lib/db", () => ({
 vi.mock("@/lib/db/schema", () => ({
   workflows: {
     id: "workflows.id",
+    status: "workflows.status",
   },
   tasks: {
     id: "tasks.id",
   },
   agentLogs: {},
   notifications: {},
+  // usageLedger is read by execution-stats.ts in the finally-block fire-and-forget.
+  // Without this export the import throws, cascading through the catch handler
+  // and causing downstream updateWorkflowState reads to run out of mock entries.
+  usageLedger: {
+    workflowId: "usageLedger.workflowId",
+  },
 }));
 
 vi.mock("drizzle-orm", () => ({
   eq: vi.fn((column: string, value: unknown) => ({ column, value })),
+  and: vi.fn((...conditions: unknown[]) => ({ and: conditions })),
 }));
 
 vi.mock("@/lib/agents/runtime", () => ({

package/src/lib/workflows/__tests__/loop-executor.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import {
   buildIterationPrompt,
+  buildRowIterationPrompt,
   detectCompletionSignal,
 } from "../loop-executor";
 
@@ -52,3 +53,56 @@ describe("detectCompletionSignal", () => {
     expect(detectCompletionSignal("LOOP_COMPLETE", [])).toBe(true);
   });
 });
+
+describe("buildRowIterationPrompt", () => {
+  it("renders the iteration header using row index out of total rows", () => {
+    const result = buildRowIterationPrompt(
+      "Research {{row}}",
+      { name: "Alice", company: "Acme" },
+      "row",
+      1,
+      3
+    );
+    expect(result).toContain("Row 1 of 3.");
+  });
+
+  it("includes the bound row data so the agent can read it", () => {
+    const row = { name: "Alice", company: "Acme" };
+    const result = buildRowIterationPrompt(
+      "Find LinkedIn for the contact above",
+      row,
+      "row",
+      1,
+      3
+    );
+    // Row payload must be visible in the prompt under the bound name
+    expect(result).toContain("row");
+    expect(result).toContain("Alice");
+    expect(result).toContain("Acme");
+    expect(result).toContain("Find LinkedIn for the contact above");
+  });
+
+  it("respects a custom itemVariable name", () => {
+    const result = buildRowIterationPrompt(
+      "Process item",
+      { id: 42, label: "widget" },
+      "contact",
+      2,
+      5
+    );
+    expect(result).toContain("contact");
+    expect(result).toContain("widget");
+    expect(result).toContain("Row 2 of 5.");
+  });
+
+  it("does not append the LOOP_COMPLETE instruction (row-driven loops finish when items are exhausted)", () => {
+    const result = buildRowIterationPrompt(
+      "Do work",
+      { x: 1 },
+      "row",
+      1,
+      1
+    );
+    expect(result).not.toContain("LOOP_COMPLETE");
+  });
+});