stagent 0.9.6 → 0.11.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/__tests__/render-prompt.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import {
+  renderBlueprintPrompt,
+  UnresolvedTokenError,
+} from "../render-prompt";
+import type { WorkflowBlueprint } from "../types";
+
+function makeBlueprint(
+  overrides: Partial<WorkflowBlueprint> = {}
+): WorkflowBlueprint {
+  return {
+    id: "test-bp",
+    name: "Test Blueprint",
+    description: "A blueprint for tests",
+    version: "1.0.0",
+    domain: "work",
+    tags: [],
+    pattern: "sequence",
+    variables: [],
+    steps: [],
+    ...overrides,
+  };
+}
+
+describe("renderBlueprintPrompt", () => {
+  it("uses chatPrompt when present", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Research {{topic}} for {{timeframe}}.",
+      steps: [
+        { name: "s1", promptTemplate: "fallback should not be used", requiresApproval: false },
+      ],
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "AI agents", timeframe: "2026" });
+    expect(out.firstMessage).toBe("Research AI agents for 2026.");
+  });
+
+  it("falls back to steps[0].promptTemplate when chatPrompt absent", () => {
+    const bp = makeBlueprint({
+      steps: [
+        {
+          name: "s1",
+          promptTemplate: "Summarize {{topic}} in ≤500 words.",
+          requiresApproval: false,
+        },
+      ],
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "browser agents" });
+    expect(out.firstMessage).toBe("Summarize browser agents in ≤500 words.");
+  });
+
+  it("renders title with variable substitution", () => {
+    const bp = makeBlueprint({
+      name: "Research {{topic}}",
+      chatPrompt: "go",
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "SSE streams" });
+    expect(out.title).toBe("Research SSE streams");
+  });
+
+  it("returns empty firstMessage when no chatPrompt and no steps", () => {
+    const bp = makeBlueprint({ steps: [] });
+    const out = renderBlueprintPrompt(bp, {});
+    expect(out.firstMessage).toBe("");
+    expect(out.title).toBe("Test Blueprint");
+  });
+
+  it("substitutes missing optional variables with empty string (non-strict)", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Topic: {{topic}}. Scope: {{scope}}.",
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "rate limits" });
+    expect(out.firstMessage).toBe("Topic: rate limits. Scope: .");
+  });
+
+  it("handles {{#if}} conditional blocks", () => {
+    const bp = makeBlueprint({
+      chatPrompt:
+        "Base prompt.{{#if extra}}\n\nExtra: {{extra}}{{/if}}",
+    });
+    const withExtra = renderBlueprintPrompt(bp, { extra: "deep dive" });
+    expect(withExtra.firstMessage).toBe("Base prompt.\n\nExtra: deep dive");
+
+    const withoutExtra = renderBlueprintPrompt(bp, {});
+    expect(withoutExtra.firstMessage).toBe("Base prompt.");
+  });
+
+  it("throws UnresolvedTokenError in strict mode when token is missing", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Hello {{name}}, today is {{date}}.",
+    });
+    expect(() =>
+      renderBlueprintPrompt(bp, { name: "Ada" }, { strict: true })
+    ).toThrow(UnresolvedTokenError);
+
+    try {
+      renderBlueprintPrompt(bp, { name: "Ada" }, { strict: true });
+    } catch (err) {
+      expect(err).toBeInstanceOf(UnresolvedTokenError);
+      expect((err as UnresolvedTokenError).tokens).toEqual(["date"]);
+    }
+  });
+
+  it("does not throw in strict mode when all tokens resolve", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Hello {{name}}.",
+    });
+    const out = renderBlueprintPrompt(
+      bp,
+      { name: "Ada" },
+      { strict: true }
+    );
+    expect(out.firstMessage).toBe("Hello Ada.");
+  });
+
+  it("strict mode treats empty-string values as resolved (not unresolved)", () => {
+    // Empty string is a resolved-to-empty substitution, distinct from an
+    // undefined variable which leaves {{token}} in the output string.
+    const bp = makeBlueprint({
+      chatPrompt: "Name: [{{name}}]",
+    });
+    const out = renderBlueprintPrompt(bp, { name: "" }, { strict: true });
+    expect(out.firstMessage).toBe("Name: []");
+  });
+});

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/render-prompt.ts

@@ -0,0 +1,71 @@
+/**
+ * Render a blueprint into a chat-ready first message.
+ *
+ * Pure template substitution over `blueprint.chatPrompt` with fallback to
+ * `blueprint.steps[0].promptTemplate` for the 13 existing built-ins that
+ * predate the `chatPrompt` field. Variable resolution is shared with the
+ * workflow engine via `resolveTemplate` so behavior stays consistent.
+ */
+
+import type { WorkflowBlueprint } from "./types";
+import { resolveTemplate } from "./template";
+
+export interface RenderedBlueprintPrompt {
+  /** The seed message to pre-fill into the chat composer. */
+  firstMessage: string;
+  /** The conversation title, with variable substitution applied. */
+  title: string;
+}
+
+export interface RenderBlueprintPromptOptions {
+  /**
+   * Throw if any `{{token}}` references an undefined variable. Defaults to
+   * false — the underlying `resolveTemplate` substitutes undefined values with
+   * empty strings, which is the right behavior for optional blueprint vars.
+   * Set to `true` to validate that all referenced tokens were resolved.
+   */
+  strict?: boolean;
+}
+
+export class UnresolvedTokenError extends Error {
+  constructor(public readonly tokens: string[]) {
+    super(`Unresolved template tokens: ${tokens.join(", ")}`);
+    this.name = "UnresolvedTokenError";
+  }
+}
+
+/**
+ * Render a blueprint's chat prompt and title with the provided parameters.
+ *
+ * Falls back to `steps[0].promptTemplate` if `chatPrompt` is absent. If the
+ * blueprint has no steps and no `chatPrompt`, returns an empty first message
+ * (the picker UI is expected to validate this case upstream).
+ */
+export function renderBlueprintPrompt(
+  blueprint: WorkflowBlueprint,
+  params: Record<string, unknown>,
+  options: RenderBlueprintPromptOptions = {}
+): RenderedBlueprintPrompt {
+  const source =
+    blueprint.chatPrompt ?? blueprint.steps[0]?.promptTemplate ?? "";
+
+  if (options.strict) {
+    // Collect {{token}} names from the source (before resolveTemplate
+    // substitutes undefined with empty string). Skip `#if`/`/if` directives.
+    const unresolved = new Set<string>();
+    for (const combined of [source, blueprint.name]) {
+      const matches = combined.matchAll(/\{\{(\w+)\}\}/g);
+      for (const m of matches) {
+        if (!(m[1] in params)) unresolved.add(m[1]);
+      }
+    }
+    if (unresolved.size > 0) {
+      throw new UnresolvedTokenError([...unresolved]);
+    }
+  }
+
+  const firstMessage = resolveTemplate(source, params);
+  const title = resolveTemplate(blueprint.name, params);
+
+  return { firstMessage, title };
+}

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;
@@ -35,4 +43,10 @@ export interface WorkflowBlueprint {
   estimatedDuration?: string;
   difficulty?: "beginner" | "intermediate" | "advanced";
   isBuiltin?: boolean;
+  /**
+   * Optional chat-composer seed prompt. When present, `chat-conversation-templates`
+   * renders this (with variable substitution) into the first user message of a
+   * new conversation. When absent, consumers fall back to `steps[0].promptTemplate`.
+   */
+  chatPrompt?: 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`;
+}