stagent 0.9.6 → 0.11.0

package/src/lib/chat/tools/__tests__/workflow-tools-dedup.test.ts

@@ -0,0 +1,351 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+interface WorkflowRow {
+  id: string;
+  name: string;
+  definition: string | null;
+  projectId: string | null;
+}
+
+const { mockWorkflowRows } = vi.hoisted(() => ({
+  mockWorkflowRows: { value: [] as WorkflowRow[] },
+}));
+
+// Minimal drizzle query builder stub — supports
+//   db.select({...}).from(table).where(...)
+// by returning a thenable that resolves to mockWorkflowRows.value.
+vi.mock("@/lib/db", () => {
+  const builder = {
+    from() {
+      return this;
+    },
+    where() {
+      return this;
+    },
+    then<TResolve>(resolve: (rows: WorkflowRow[]) => TResolve) {
+      return Promise.resolve(mockWorkflowRows.value).then(resolve);
+    },
+  };
+  return {
+    db: {
+      select: () => builder,
+    },
+  };
+});
+
+// Stub the schema import so drizzle-orm doesn't try to read a real table.
+vi.mock("@/lib/db/schema", () => ({
+  workflows: { projectId: "projectId" },
+  tasks: {},
+  agentLogs: {},
+  notifications: {},
+  documents: {},
+  workflowDocumentInputs: {},
+}));
+
+// Stub drizzle-orm operators used in workflow-tools.ts — the tests only
+// care about the return value of the builder, not the operator objects.
+vi.mock("drizzle-orm", () => ({
+  eq: () => ({}),
+  and: () => ({}),
+  desc: () => ({}),
+  inArray: () => ({}),
+  like: () => ({}),
+}));
+
+import { findSimilarWorkflows } from "../workflow-tools";
+
+function setRows(rows: WorkflowRow[]) {
+  mockWorkflowRows.value = rows;
+}
+
+describe("findSimilarWorkflows", () => {
+  beforeEach(() => {
+    setRows([]);
+  });
+
+  it("returns [] when projectId is null (no cross-project dedup)", async () => {
+    setRows([
+      {
+        id: "wf1",
+        name: "Research Customer Feedback",
+        definition: JSON.stringify({
+          pattern: "sequence",
+          steps: [{ id: "s1", name: "Research customer feedback", prompt: "do research" }],
+        }),
+        projectId: null,
+      },
+    ]);
+
+    const result = await findSimilarWorkflows(
+      null,
+      "Research Customer Feedback",
+      JSON.stringify({ pattern: "sequence", steps: [] })
+    );
+    expect(result).toEqual([]);
+  });
+
+  it("returns [] when no workflows exist in the project", async () => {
+    setRows([]);
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "Any name",
+      JSON.stringify({ pattern: "sequence", steps: [] })
+    );
+    expect(result).toEqual([]);
+  });
+
+  it("matches exact name (case-insensitive) with similarity 1.0", async () => {
+    setRows([
+      {
+        id: "wf1",
+        name: "Research Customer Feedback",
+        definition: null,
+        projectId: "proj_a",
+      },
+    ]);
+
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "research customer feedback",
+      JSON.stringify({ pattern: "sequence", steps: [] })
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      id: "wf1",
+      similarity: 1,
+    });
+    expect(result[0].reason).toContain("Same name");
+  });
+
+  it("matches on Jaccard similarity over step names + prompts (redesign scenario)", async () => {
+    // Simulates the bug scenario: LLM "redesigns" a workflow mid-conversation,
+    // using mostly the same vocabulary as the original. The definitions are
+    // near-identical (as redesigns typically are in practice) so Jaccard
+    // should exceed the 0.7 threshold.
+    const sharedSteps = [
+      { id: "s1", name: "Research customer cohort", prompt: "Investigate customer research cohort feedback insights" },
+      { id: "s2", name: "Interview protocol draft", prompt: "Draft customer interview questions protocol script" },
+      { id: "s3", name: "Synthesize findings", prompt: "Summarize customer research findings insights report" },
+    ];
+    setRows([
+      {
+        id: "wf1",
+        name: "Customer Discovery Pipeline",
+        definition: JSON.stringify({ pattern: "sequence", steps: sharedSteps }),
+        projectId: "proj_a",
+      },
+    ]);
+
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "Customer Discovery Workflow v2",
+      JSON.stringify({ pattern: "sequence", steps: sharedSteps })
+    );
+
+    expect(result.length).toBeGreaterThanOrEqual(1);
+    expect(result[0].id).toBe("wf1");
+    expect(result[0].similarity).toBeGreaterThanOrEqual(0.7);
+  });
+
+  it("does NOT match when names and step text are completely different", async () => {
+    setRows([
+      {
+        id: "wf1",
+        name: "Deploy frontend release",
+        definition: JSON.stringify({
+          pattern: "sequence",
+          steps: [{ id: "s1", name: "Deploy staging", prompt: "Push release artifact to staging environment" }],
+        }),
+        projectId: "proj_a",
+      },
+    ]);
+
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "Customer interview analysis",
+      JSON.stringify({
+        pattern: "sequence",
+        steps: [{ id: "s2", name: "Summarize interviews", prompt: "Pull insights from recent customer interviews" }],
+      })
+    );
+
+    expect(result).toEqual([]);
+  });
+
+  it("caps results at 3 and sorts by similarity descending", async () => {
+    // Four rows, all exact-name matches (similarity 1.0). Expect exactly 3 returned.
+    setRows(
+      Array.from({ length: 4 }).map((_, i) => ({
+        id: `wf${i}`,
+        name: "Duplicate Workflow",
+        definition: null,
+        projectId: "proj_a",
+      }))
+    );
+
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "Duplicate Workflow",
+      JSON.stringify({ pattern: "sequence", steps: [] })
+    );
+
+    expect(result).toHaveLength(3);
+    expect(result.every((r) => r.similarity === 1)).toBe(true);
+  });
+
+  it("handles malformed definition JSON without crashing", async () => {
+    setRows([
+      {
+        id: "wf1",
+        name: "Legit Workflow",
+        definition: "not-json-at-all",
+        projectId: "proj_a",
+      },
+    ]);
+
+    // Should not throw — just degrades to name-only comparison.
+    const result = await findSimilarWorkflows(
+      "proj_a",
+      "Legit Workflow",
+      "also not json"
+    );
+    expect(result).toHaveLength(1);
+    expect(result[0].similarity).toBe(1); // exact name match
+  });
+
+  // ── Legitimate variant tolerance ────────────────────────────────────
+  //
+  // Regression tests for the concern flagged in the code review of
+  // commit b5ed09b: that WORKFLOW_DEDUP_THRESHOLD = 0.7 on a pooled
+  // Jaccard over keywords would flag legitimate target-entity variants
+  // (e.g. "Enrich contacts" vs "Enrich accounts") as duplicates,
+  // eroding trust in the guardrail. Each pair here shares a dominant
+  // verb and most of the step structure — the only difference is the
+  // target entity noun.
+  //
+  // Success criterion per spec:
+  //   - the two "positive-variant" cases must return [] (no match)
+  //   - the two "guard" cases must still flag duplicates (similarity >=
+  //     WORKFLOW_DEDUP_THRESHOLD, or exact-name match)
+  describe("legitimate variant tolerance", () => {
+    it("allows Enrich contacts and Enrich accounts as distinct workflows", async () => {
+      setRows([
+        {
+          id: "wf1",
+          name: "Enrich contacts",
+          definition: JSON.stringify({
+            pattern: "sequence",
+            steps: [
+              { id: "s1", name: "Load rows from contacts table", prompt: "Select rows from the contacts table" },
+              { id: "s2", name: "Call enrichment agent", prompt: "Invoke enrichment agent on each row" },
+              { id: "s3", name: "Write back to table", prompt: "Write enriched data back to the contacts table" },
+            ],
+          }),
+          projectId: "proj_a",
+        },
+      ]);
+
+      const result = await findSimilarWorkflows(
+        "proj_a",
+        "Enrich accounts",
+        JSON.stringify({
+          pattern: "sequence",
+          steps: [
+            { id: "s1", name: "Load rows from accounts table", prompt: "Select rows from the accounts table" },
+            { id: "s2", name: "Call enrichment agent", prompt: "Invoke enrichment agent on each row" },
+            { id: "s3", name: "Write back to table", prompt: "Write enriched data back to the accounts table" },
+          ],
+        })
+      );
+
+      expect(result).toEqual([]);
+    });
+
+    it("allows Daily standup digest and Weekly standup digest as distinct workflows", async () => {
+      setRows([
+        {
+          id: "wf1",
+          name: "Daily standup digest",
+          definition: JSON.stringify({
+            pattern: "sequence",
+            steps: [
+              { id: "s1", name: "Fetch standup messages", prompt: "Pull daily standup messages from the team channel" },
+              { id: "s2", name: "Summarize daily topics", prompt: "Write a daily digest of key topics and blockers" },
+              { id: "s3", name: "Post digest to channel", prompt: "Post the daily summary digest to the #ops channel" },
+            ],
+          }),
+          projectId: "proj_a",
+        },
+      ]);
+
+      const result = await findSimilarWorkflows(
+        "proj_a",
+        "Weekly standup digest",
+        JSON.stringify({
+          pattern: "sequence",
+          steps: [
+            { id: "s1", name: "Fetch standup messages", prompt: "Pull weekly standup messages from the team channel" },
+            { id: "s2", name: "Summarize weekly topics", prompt: "Write a weekly digest of key topics and blockers" },
+            { id: "s3", name: "Post digest to channel", prompt: "Post the weekly summary digest to the #ops channel" },
+          ],
+        })
+      );
+
+      expect(result).toEqual([]);
+    });
+
+    it("still blocks exact case-insensitive name matches (guard)", async () => {
+      setRows([
+        {
+          id: "wf1",
+          name: "Enrich contacts",
+          definition: JSON.stringify({
+            pattern: "sequence",
+            steps: [
+              { id: "s1", name: "Load rows from contacts table", prompt: "Select rows from the contacts table" },
+            ],
+          }),
+          projectId: "proj_a",
+        },
+      ]);
+
+      const result = await findSimilarWorkflows(
+        "proj_a",
+        "ENRICH CONTACTS", // same name, different case
+        JSON.stringify({ pattern: "sequence", steps: [] })
+      );
+
+      expect(result).toHaveLength(1);
+      expect(result[0].similarity).toBe(1);
+      expect(result[0].reason).toContain("Same name");
+    });
+
+    it("still blocks near-identical step content with near-identical name (guard)", async () => {
+      const sharedSteps = [
+        { id: "s1", name: "Fetch customer segments list", prompt: "Load the customer segments list from BigQuery warehouse" },
+        { id: "s2", name: "Classify each segment bucket", prompt: "Classify each customer segment bucket using ML model" },
+        { id: "s3", name: "Write segments back warehouse", prompt: "Write segment classifications back into BigQuery warehouse" },
+      ];
+      setRows([
+        {
+          id: "wf1",
+          name: "Classify customer segments v1",
+          definition: JSON.stringify({ pattern: "sequence", steps: sharedSteps }),
+          projectId: "proj_a",
+        },
+      ]);
+
+      const result = await findSimilarWorkflows(
+        "proj_a",
+        "Classify customer segments v2",
+        JSON.stringify({ pattern: "sequence", steps: sharedSteps })
+      );
+
+      expect(result.length).toBeGreaterThanOrEqual(1);
+      expect(result[0].id).toBe("wf1");
+      expect(result[0].similarity).toBeGreaterThanOrEqual(0.7);
+    });
+  });
+});

package/src/lib/chat/tools/blueprint-tools.ts

@@ -0,0 +1,190 @@
+import { defineTool } from "../tool-registry";
+import { z } from "zod";
+import { ok, err, type ToolContext } from "./helpers";
+
+export function blueprintTools(ctx: ToolContext) {
+  return [
+    defineTool(
+      "list_blueprints",
+      "List available workflow blueprints. Blueprints are reusable workflow templates with configurable variables. Use instantiate_blueprint to create a workflow from one.",
+      {
+        domain: z
+          .enum(["work", "personal"])
+          .optional()
+          .describe("Filter by domain"),
+        search: z
+          .string()
+          .optional()
+          .describe("Search in name, description, and tags"),
+      },
+      async (args) => {
+        try {
+          const { listBlueprints } = await import(
+            "@/lib/workflows/blueprints/registry"
+          );
+          let blueprints = listBlueprints();
+
+          if (args.domain) {
+            blueprints = blueprints.filter((b) => b.domain === args.domain);
+          }
+          if (args.search) {
+            const q = args.search.toLowerCase();
+            blueprints = blueprints.filter(
+              (b) =>
+                b.name.toLowerCase().includes(q) ||
+                b.description.toLowerCase().includes(q) ||
+                b.tags.some((t) => t.toLowerCase().includes(q))
+            );
+          }
+
+          return ok(
+            blueprints.map((b) => ({
+              id: b.id,
+              name: b.name,
+              description: b.description,
+              domain: b.domain,
+              pattern: b.pattern,
+              tags: b.tags,
+              difficulty: b.difficulty,
+              estimatedDuration: b.estimatedDuration,
+              isBuiltin: b.isBuiltin,
+              variableCount: b.variables.length,
+              stepCount: b.steps.length,
+            }))
+          );
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to list blueprints"
+          );
+        }
+      }
+    ),
+
+    defineTool(
+      "get_blueprint",
+      "Get full details of a workflow blueprint, including its variables and steps. Use this to understand what inputs are needed before calling instantiate_blueprint.",
+      {
+        blueprintId: z.string().describe("The blueprint ID to look up"),
+      },
+      async (args) => {
+        try {
+          const { getBlueprint } = await import(
+            "@/lib/workflows/blueprints/registry"
+          );
+          const blueprint = getBlueprint(args.blueprintId);
+          if (!blueprint)
+            return err(`Blueprint not found: ${args.blueprintId}`);
+          return ok(blueprint);
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to get blueprint"
+          );
+        }
+      }
+    ),
+
+    defineTool(
+      "instantiate_blueprint",
+      "Create a draft workflow from a blueprint by filling in its variables. The workflow is created in 'draft' status — use execute_workflow to run it. Call get_blueprint first to see required variables.",
+      {
+        blueprintId: z
+          .string()
+          .describe("The blueprint ID to instantiate"),
+        variables: z
+          .record(z.string(), z.unknown())
+          .describe(
+            "Key-value map of variable values. Keys are variable IDs from the blueprint. Required variables must be provided."
+          ),
+        projectId: z
+          .string()
+          .optional()
+          .describe(
+            "Project ID to attach the workflow to. Omit to use the active project."
+          ),
+      },
+      async (args) => {
+        try {
+          const { instantiateBlueprint } = await import(
+            "@/lib/workflows/blueprints/instantiator"
+          );
+          const effectiveProjectId =
+            args.projectId ?? ctx.projectId ?? undefined;
+
+          const result = await instantiateBlueprint(
+            args.blueprintId,
+            args.variables,
+            effectiveProjectId
+          );
+
+          ctx.onToolResult?.("instantiate_blueprint", result);
+          return ok({
+            workflowId: result.workflowId,
+            name: result.name,
+            stepsCount: result.stepsCount,
+            skippedSteps: result.skippedSteps,
+            status: "draft",
+            message:
+              "Workflow created from blueprint. Use execute_workflow to run it.",
+          });
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to instantiate blueprint"
+          );
+        }
+      }
+    ),
+
+    defineTool(
+      "create_blueprint",
+      "Create a custom workflow blueprint from YAML content. The YAML must include id, name, description, version, domain, tags, pattern, variables, and steps. Use get_blueprint on an existing blueprint to see the expected structure.",
+      {
+        yaml: z
+          .string()
+          .describe(
+            "Full blueprint YAML content. Must validate against the blueprint schema."
+          ),
+      },
+      async (args) => {
+        try {
+          const { createBlueprint } = await import(
+            "@/lib/workflows/blueprints/registry"
+          );
+          const blueprint = createBlueprint(args.yaml);
+          ctx.onToolResult?.("create_blueprint", blueprint);
+          return ok({
+            id: blueprint.id,
+            name: blueprint.name,
+            message: "Blueprint created successfully",
+          });
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to create blueprint"
+          );
+        }
+      }
+    ),
+
+    defineTool(
+      "delete_blueprint",
+      "Delete a custom workflow blueprint. Built-in blueprints cannot be deleted.",
+      {
+        blueprintId: z.string().describe("The blueprint ID to delete"),
+      },
+      async (args) => {
+        try {
+          const { deleteBlueprint } = await import(
+            "@/lib/workflows/blueprints/registry"
+          );
+          deleteBlueprint(args.blueprintId);
+          return ok({
+            message: `Blueprint "${args.blueprintId}" deleted`,
+          });
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to delete blueprint"
+          );
+        }
+      }
+    ),
+  ];
+}

package/src/lib/chat/tools/document-tools.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { db } from "@/lib/db";
 import { documents } from "@/lib/db/schema";
 import { eq, and, desc } from "drizzle-orm";
-import { ok, err, type ToolContext } from "./helpers";
+import { ok, err, resolveEntityId, type ToolContext } from "./helpers";
 import { access, stat, copyFile, mkdir } from "fs/promises";
 import { basename, extname, join } from "path";
 import crypto from "crypto";
@@ -105,6 +105,10 @@ export function documentTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(documents, documents.id, args.documentId);
+          if ("error" in resolved) return err(resolved.error);
+          const documentId = resolved.id;
+
           const doc = await db
             .select({
               id: documents.id,
@@ -122,10 +126,10 @@ export function documentTools(ctx: ToolContext) {
               updatedAt: documents.updatedAt,
             })
             .from(documents)
-            .where(eq(documents.id, args.documentId))
+            .where(eq(documents.id, documentId))
             .get();
 
-          if (!doc) return err(`Document not found: ${args.documentId}`);
+          if (!doc) return err(`Document not found: ${documentId}`);
           ctx.onToolResult?.("get_document", doc);
           return ok(doc);
         } catch (e) {
@@ -204,13 +208,17 @@ export function documentTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(documents, documents.id, args.documentId);
+          if ("error" in resolved) return err(resolved.error);
+          const documentId = resolved.id;
+
           const doc = await db
             .select()
             .from(documents)
-            .where(eq(documents.id, args.documentId))
+            .where(eq(documents.id, documentId))
             .get();
 
-          if (!doc) return err(`Document not found: ${args.documentId}`);
+          if (!doc) return err(`Document not found: ${documentId}`);
 
           const updates: Record<string, unknown> = { updatedAt: new Date() };
 
@@ -232,10 +240,10 @@ export function documentTools(ctx: ToolContext) {
           await db
             .update(documents)
             .set(updates)
-            .where(eq(documents.id, args.documentId));
+            .where(eq(documents.id, documentId));
 
           if (args.reprocess) {
-            processDocument(args.documentId).catch(() => {});
+            processDocument(documentId).catch(() => {});
           }
 
           const updatedFields = [];
@@ -243,7 +251,7 @@ export function documentTools(ctx: ToolContext) {
           if (args.reprocess) updatedFields.push("processingStatus");
 
           const result = {
-            documentId: args.documentId,
+            documentId,
             updatedFields,
             processingStatus: args.reprocess ? "queued" : doc.status,
           };
@@ -264,13 +272,17 @@ export function documentTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(documents, documents.id, args.documentId);
+          if ("error" in resolved) return err(resolved.error);
+          const documentId = resolved.id;
+
           const doc = await db
             .select()
             .from(documents)
-            .where(eq(documents.id, args.documentId))
+            .where(eq(documents.id, documentId))
             .get();
 
-          if (!doc) return err(`Document not found: ${args.documentId}`);
+          if (!doc) return err(`Document not found: ${documentId}`);
 
           // Check task linkage
           if (doc.taskId && !args.cascadeDelete) {
@@ -285,7 +297,7 @@ export function documentTools(ctx: ToolContext) {
             // File may already be deleted
           }
 
-          await db.delete(documents).where(eq(documents.id, args.documentId));
+          await db.delete(documents).where(eq(documents.id, documentId));
 
           const result = {
             success: true,
@@ -308,6 +320,10 @@ export function documentTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(documents, documents.id, args.documentId);
+          if ("error" in resolved) return err(resolved.error);
+          const documentId = resolved.id;
+
           const doc = await db
             .select({
               id: documents.id,
@@ -316,10 +332,10 @@ export function documentTools(ctx: ToolContext) {
               extractedText: documents.extractedText,
             })
             .from(documents)
-            .where(eq(documents.id, args.documentId))
+            .where(eq(documents.id, documentId))
             .get();
 
-          if (!doc) return err(`Document not found: ${args.documentId}`);
+          if (!doc) return err(`Document not found: ${documentId}`);
           if (doc.status !== "ready")
             return err(`Document not ready (status: ${doc.status}). Wait for preprocessing to complete.`);
           if (!doc.extractedText)