stagent 0.9.5 → 0.10.0

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

@@ -3,12 +3,13 @@ import { z } from "zod";
 import { db } from "@/lib/db";
 import { tasks } 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 {
   DEFAULT_AGENT_RUNTIME,
   isAgentRuntimeId,
   SUPPORTED_AGENT_RUNTIMES,
 } from "@/lib/agents/runtime/catalog";
+import { getProfile, listProfiles } from "@/lib/agents/profiles/registry";
 
 const VALID_TASK_STATUSES = [
   "planned",
@@ -19,6 +20,25 @@ const VALID_TASK_STATUSES = [
   "cancelled",
 ] as const;
 
+/**
+ * Zod refinement shared by create_task and update_task for the agentProfile
+ * field. Returns true for valid registered profile IDs. The error message
+ * lists a truncated sample of valid IDs from the registry so operators can
+ * self-correct without cross-referencing docs.
+ */
+function isValidAgentProfile(id: string): boolean {
+  return getProfile(id) !== undefined;
+}
+
+function agentProfileErrorMessage(invalid: string): string {
+  const valid = listProfiles()
+    .map((p) => p.id)
+    .sort();
+  const sample = valid.slice(0, 8).join(", ");
+  const more = valid.length > 8 ? `, and ${valid.length - 8} more` : "";
+  return `Invalid agentProfile "${invalid}". Valid profiles: ${sample}${more}. Run list_profiles (or inspect ~/.claude/skills/) to see the full set.`;
+}
+
 export function taskTools(ctx: ToolContext) {
   return [
     defineTool(
@@ -51,6 +71,14 @@ export function taskTools(ctx: ToolContext) {
             .orderBy(tasks.priority, desc(tasks.createdAt))
             .limit(50);
 
+          if (result.length === 0 && effectiveProjectId) {
+            return ok({
+              tasks: [],
+              note: `No tasks found in project ${effectiveProjectId}. ` +
+                `Use projectId: null to list tasks from any project, ` +
+                `or get_task <id> to look up a specific task directly.`,
+            });
+          }
           return ok(result);
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to list tasks");
@@ -90,13 +118,19 @@ export function taskTools(ctx: ToolContext) {
           ),
         agentProfile: z
           .string()
+          .refine(isValidAgentProfile, {
+            message: "Invalid agentProfile (not in profile registry). See list_profiles.",
+          })
           .optional()
           .describe(
-            "Agent profile ID (e.g. general, code-reviewer, researcher, reddit-researcher)"
+            "Agent profile ID (e.g. general, code-reviewer, researcher). Validated against the profile registry."
           ),
       },
       async (args) => {
         try {
+          if (args.agentProfile !== undefined && !isValidAgentProfile(args.agentProfile)) {
+            return err(agentProfileErrorMessage(args.agentProfile));
+          }
           if (args.assignedAgent && !isAgentRuntimeId(args.assignedAgent)) {
             return err(
               `Invalid runtime "${args.assignedAgent}". Valid: ${SUPPORTED_AGENT_RUNTIMES.join(", ")}`
@@ -162,13 +196,23 @@ export function taskTools(ctx: ToolContext) {
           ),
         agentProfile: z
           .string()
+          .refine(isValidAgentProfile, {
+            message: "Invalid agentProfile (not in profile registry). See list_profiles.",
+          })
           .optional()
           .describe(
-            "Agent profile ID (e.g. general, code-reviewer, researcher, reddit-researcher)"
+            "Agent profile ID (e.g. general, code-reviewer, researcher). Validated against the profile registry."
           ),
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(tasks, tasks.id, args.taskId);
+          if ("error" in resolved) return err(resolved.error);
+          const taskId = resolved.id;
+
+          if (args.agentProfile !== undefined && !isValidAgentProfile(args.agentProfile)) {
+            return err(agentProfileErrorMessage(args.agentProfile));
+          }
           if (args.assignedAgent && !isAgentRuntimeId(args.assignedAgent)) {
             return err(
               `Invalid runtime "${args.assignedAgent}". Valid: ${SUPPORTED_AGENT_RUNTIMES.join(", ")}`
@@ -178,10 +222,10 @@ export function taskTools(ctx: ToolContext) {
           const existing = await db
             .select()
             .from(tasks)
-            .where(eq(tasks.id, args.taskId))
+            .where(eq(tasks.id, taskId))
             .get();
 
-          if (!existing) return err(`Task not found: ${args.taskId}`);
+          if (!existing) return err(`Task not found: ${taskId}`);
 
           const updates: Record<string, unknown> = { updatedAt: new Date() };
           if (args.title !== undefined) updates.title = args.title;
@@ -197,12 +241,12 @@ export function taskTools(ctx: ToolContext) {
           await db
             .update(tasks)
             .set(updates)
-            .where(eq(tasks.id, args.taskId));
+            .where(eq(tasks.id, taskId));
 
           const [task] = await db
             .select()
             .from(tasks)
-            .where(eq(tasks.id, args.taskId));
+            .where(eq(tasks.id, taskId));
 
           ctx.onToolResult?.("update_task", task);
           return ok(task);
@@ -220,13 +264,17 @@ export function taskTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(tasks, tasks.id, args.taskId);
+          if ("error" in resolved) return err(resolved.error);
+          const taskId = resolved.id;
+
           const task = await db
             .select()
             .from(tasks)
-            .where(eq(tasks.id, args.taskId))
+            .where(eq(tasks.id, taskId))
             .get();
 
-          if (!task) return err(`Task not found: ${args.taskId}`);
+          if (!task) return err(`Task not found: ${taskId}`);
           ctx.onToolResult?.("get_task", task);
           return ok(task);
         } catch (e) {
@@ -249,6 +297,10 @@ export function taskTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(tasks, tasks.id, args.taskId);
+          if ("error" in resolved) return err(resolved.error);
+          const taskId = resolved.id;
+
           if (args.assignedAgent && !isAgentRuntimeId(args.assignedAgent)) {
             return err(
               `Invalid runtime "${args.assignedAgent}". Valid: ${SUPPORTED_AGENT_RUNTIMES.join(", ")}`
@@ -258,26 +310,34 @@ export function taskTools(ctx: ToolContext) {
           const task = await db
             .select()
             .from(tasks)
-            .where(eq(tasks.id, args.taskId))
+            .where(eq(tasks.id, taskId))
             .get();
 
-          if (!task) return err(`Task not found: ${args.taskId}`);
+          if (!task) return err(`Task not found: ${taskId}`);
           if (task.status === "running") return err("Task is already running");
 
+          if (task.agentProfile && !isValidAgentProfile(task.agentProfile)) {
+            return err(
+              `Task ${taskId} has an invalid agentProfile "${task.agentProfile}" (not in profile registry). ` +
+              `Fix with update_task { taskId, agentProfile: "<valid-id>" } before retrying. ` +
+              agentProfileErrorMessage(task.agentProfile).split(". ").slice(1).join(". ")
+            );
+          }
+
           const runtimeId = args.assignedAgent ?? task.assignedAgent ?? DEFAULT_AGENT_RUNTIME;
 
           // Set status to queued
           await db
             .update(tasks)
             .set({ status: "queued", assignedAgent: runtimeId, updatedAt: new Date() })
-            .where(eq(tasks.id, args.taskId));
+            .where(eq(tasks.id, taskId));
 
           // Fire-and-forget execution
           const { executeTaskWithAgent } = await import("@/lib/agents/router");
-          executeTaskWithAgent(args.taskId, runtimeId).catch(() => {});
+          executeTaskWithAgent(taskId, runtimeId).catch(() => {});
 
-          ctx.onToolResult?.("execute_task", { id: args.taskId, title: task.title });
-          return ok({ message: "Execution started", taskId: args.taskId, runtime: runtimeId });
+          ctx.onToolResult?.("execute_task", { id: taskId, title: task.title });
+          return ok({ message: "Execution started", taskId, runtime: runtimeId });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to execute task");
         }
@@ -292,17 +352,21 @@ export function taskTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(tasks, tasks.id, args.taskId);
+          if ("error" in resolved) return err(resolved.error);
+          const taskId = resolved.id;
+
           const task = await db
             .select()
             .from(tasks)
-            .where(eq(tasks.id, args.taskId))
+            .where(eq(tasks.id, taskId))
             .get();
 
-          if (!task) return err(`Task not found: ${args.taskId}`);
+          if (!task) return err(`Task not found: ${taskId}`);
           if (task.status !== "running") return err(`Task is not running (status: ${task.status})`);
 
           const { getExecution } = await import("@/lib/agents/execution-manager");
-          const execution = getExecution(args.taskId);
+          const execution = getExecution(taskId);
           if (execution?.abortController) {
             execution.abortController.abort();
           }
@@ -310,9 +374,9 @@ export function taskTools(ctx: ToolContext) {
           await db
             .update(tasks)
             .set({ status: "cancelled", updatedAt: new Date() })
-            .where(eq(tasks.id, args.taskId));
+            .where(eq(tasks.id, taskId));
 
-          return ok({ message: "Task cancelled", taskId: args.taskId });
+          return ok({ message: "Task cancelled", taskId });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to cancel task");
         }

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

@@ -10,7 +10,8 @@ import {
   workflowDocumentInputs,
 } from "@/lib/db/schema";
 import { eq, and, desc, inArray, like } from "drizzle-orm";
-import { ok, err, type ToolContext } from "./helpers";
+import { ok, err, resolveEntityId, type ToolContext } from "./helpers";
+import { extractKeywords, jaccard } from "@/lib/util/similarity";
 
 const VALID_WORKFLOW_STATUSES = [
   "draft",
@@ -20,6 +21,107 @@ const VALID_WORKFLOW_STATUSES = [
   "failed",
 ] as const;
 
+/** Minimum Jaccard score for two workflows to count as "near duplicates". */
+const WORKFLOW_DEDUP_THRESHOLD = 0.7;
+
+/**
+ * Pull the comparable text out of a workflow definition JSON string:
+ * name + each step's name + each step's prompt. Invalid JSON returns "".
+ *
+ * Shared by findSimilarWorkflows for the candidate and each existing row.
+ */
+function workflowComparableText(name: string, definitionJson: string | null): string {
+  const parts: string[] = [name];
+  if (!definitionJson) return parts.join(" ");
+  try {
+    const def = JSON.parse(definitionJson);
+    if (Array.isArray(def?.steps)) {
+      for (const step of def.steps) {
+        if (typeof step?.name === "string") parts.push(step.name);
+        if (typeof step?.prompt === "string") parts.push(step.prompt);
+      }
+    }
+  } catch {
+    // Malformed JSON — fall back to just the name.
+  }
+  return parts.join(" ");
+}
+
+export interface SimilarWorkflowMatch {
+  id: string;
+  name: string;
+  similarity: number;
+  reason: string;
+}
+
+/**
+ * Find workflows in the same project that look similar to a candidate.
+ *
+ * Two-tier check:
+ *   1. Exact name match (case-insensitive) → similarity 1.0
+ *   2. Jaccard similarity over extracted keywords from name+step titles+prompts
+ *
+ * Returns up to 3 matches with similarity >= WORKFLOW_DEDUP_THRESHOLD,
+ * sorted by similarity descending. Used by `create_workflow` to warn the
+ * LLM before blindly inserting another row in long conversations where
+ * the sliding-window context builder evicts earlier creations.
+ *
+ * When projectId is null (no active project), returns [] — cross-project
+ * dedup would be misleading, and the handful of null-project rows that
+ * exist aren't worth de-duplicating against each other.
+ */
+export async function findSimilarWorkflows(
+  projectId: string | null,
+  candidateName: string,
+  candidateDefinitionJson: string
+): Promise<SimilarWorkflowMatch[]> {
+  if (!projectId) return [];
+
+  const existing = await db
+    .select({
+      id: workflows.id,
+      name: workflows.name,
+      definition: workflows.definition,
+    })
+    .from(workflows)
+    .where(eq(workflows.projectId, projectId));
+
+  const matches: SimilarWorkflowMatch[] = [];
+  const candidateKeywords = extractKeywords(
+    workflowComparableText(candidateName, candidateDefinitionJson)
+  );
+  const candidateNameLower = candidateName.trim().toLowerCase();
+
+  for (const row of existing) {
+    // Tier 1: exact name match (case-insensitive)
+    if (row.name.trim().toLowerCase() === candidateNameLower) {
+      matches.push({
+        id: row.id,
+        name: row.name,
+        similarity: 1,
+        reason: `Same name: "${row.name}"`,
+      });
+      continue;
+    }
+
+    // Tier 2: Jaccard similarity on keywords
+    const existingKeywords = extractKeywords(
+      workflowComparableText(row.name, row.definition)
+    );
+    const similarity = jaccard(candidateKeywords, existingKeywords);
+    if (similarity >= WORKFLOW_DEDUP_THRESHOLD) {
+      matches.push({
+        id: row.id,
+        name: row.name,
+        similarity,
+        reason: `Similar content to "${row.name}" (${Math.round(similarity * 100)}%)`,
+      });
+    }
+  }
+
+  return matches.sort((a, b) => b.similarity - a.similarity).slice(0, 3);
+}
+
 export function workflowTools(ctx: ToolContext) {
   return [
     defineTool(
@@ -69,7 +171,7 @@ export function workflowTools(ctx: ToolContext) {
 
     defineTool(
       "create_workflow",
-      "Create a new workflow with a definition. The definition must include a pattern (sequence, parallel, checkpoint, planner-executor, swarm, loop) and steps array.",
+      "Create a new workflow with a definition. The definition must include a pattern (sequence, parallel, checkpoint, planner-executor, swarm, loop) and steps array. Sequence-pattern steps can be either task steps (with prompt + assignedAgent/agentProfile) or delay steps (with delayDuration like '3d', '2h', '30m', '1w') that pause the workflow between tasks — use delay steps for time-distributed sequences (outreach cadences, drip campaigns, cooling periods) rather than creating separate workflows or schedules. IMPORTANT: for the 'run agent on every row of a table' pattern, prefer enrich_table over create_workflow — enrich_table generates the optimal loop configuration, binds each row as {{row.field}} context, wires up the postAction row writeback, and handles idempotent skip of already-populated rows. Hand-rolled equivalents miss these safeguards.",
       {
         name: z.string().min(1).max(200).describe("Workflow name"),
         projectId: z
@@ -79,7 +181,11 @@ export function workflowTools(ctx: ToolContext) {
         definition: z
           .string()
           .describe(
-            'Workflow definition as JSON string. Must include "pattern" and "steps" array. Example: {"pattern":"sequence","steps":[{"id":"step-1","name":"step1","prompt":"Do X","assignedAgent":"claude"}]}'
+            'Workflow definition as JSON string. Must include "pattern" and "steps" array. ' +
+            'Task step example: {"id":"s1","name":"Research","prompt":"Do X","assignedAgent":"claude"}. ' +
+            'Delay step example (sequence pattern only): {"id":"s2","name":"Wait 3 days","delayDuration":"3d"}. ' +
+            'A complete drip sequence: {"pattern":"sequence","steps":[{"id":"s1","name":"Initial","prompt":"Send first email","assignedAgent":"claude"},{"id":"s2","name":"Wait","delayDuration":"3d"},{"id":"s3","name":"Follow-up","prompt":"Send follow-up","assignedAgent":"claude"}]}. ' +
+            'Delay bounds: 1m to 30d. Delay steps must NOT have prompt/profile fields.'
           ),
         documentIds: z
           .array(z.string())
@@ -93,6 +199,12 @@ export function workflowTools(ctx: ToolContext) {
           .describe(
             "Runtime to use for workflow execution (e.g., 'openai-direct', 'anthropic-direct'). Use list_runtimes to see available options. Omit to use the system default."
           ),
+        force: z
+          .boolean()
+          .optional()
+          .describe(
+            "Set to true to bypass the near-duplicate check and always create a new workflow. Only use this when the user has explicitly confirmed they want a second workflow alongside a similar existing one (e.g., 'v2', 'alternate approach'). Default false."
+          ),
       },
       async (args) => {
         try {
@@ -127,6 +239,28 @@ export function workflowTools(ctx: ToolContext) {
           }
 
           const effectiveProjectId = args.projectId ?? ctx.projectId ?? null;
+
+          // Dedup guard: long chat conversations can truncate the earlier
+          // create_workflow tool call out of the sliding-window context, so
+          // the LLM loses its own history and re-creates on "redesign"
+          // requests. Check for near-duplicates in the same project before
+          // inserting. Pass force=true to bypass.
+          if (!args.force) {
+            const similar = await findSimilarWorkflows(
+              effectiveProjectId,
+              args.name,
+              args.definition
+            );
+            if (similar.length > 0) {
+              return ok({
+                status: "similar-found",
+                message:
+                  "Found similar workflow(s) in this project. Use update_workflow to modify an existing one, or pass force=true to create a new workflow alongside them.",
+                matches: similar,
+              });
+            }
+          }
+
           const now = new Date();
           const id = crypto.randomUUID();
 
@@ -211,13 +345,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           const { parseWorkflowState } = await import("@/lib/workflows/engine");
           const { definition, state } = parseWorkflowState(workflow.definition);
@@ -266,13 +404,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const existing = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const existing = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!existing) return err(`Workflow not found: ${args.workflowId}`);
+          if (!existing) return err(`Workflow not found: ${workflowId}`);
           if (existing.status !== "draft")
             return err(`Cannot edit a workflow in '${existing.status}' status. Only draft workflows can be edited.`);
 
@@ -293,12 +435,12 @@ export function workflowTools(ctx: ToolContext) {
           await db
             .update(workflows)
             .set(updates)
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           const [workflow] = await db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           ctx.onToolResult?.("update_workflow", workflow);
           return ok({
@@ -321,13 +463,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const existing = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const existing = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!existing) return err(`Workflow not found: ${args.workflowId}`);
+          if (!existing) return err(`Workflow not found: ${workflowId}`);
           if (existing.status === "active")
             return err("Cannot delete an active workflow. Pause or stop it first.");
 
@@ -335,7 +481,7 @@ export function workflowTools(ctx: ToolContext) {
           const childTasks = await db
             .select({ id: tasks.id })
             .from(tasks)
-            .where(eq(tasks.workflowId, args.workflowId));
+            .where(eq(tasks.workflowId, workflowId));
 
           const taskIds = childTasks.map((t) => t.id);
           for (const taskId of taskIds) {
@@ -343,10 +489,10 @@ export function workflowTools(ctx: ToolContext) {
             await db.delete(agentLogs).where(eq(agentLogs.taskId, taskId));
             await db.delete(documents).where(eq(documents.taskId, taskId));
           }
-          await db.delete(tasks).where(eq(tasks.workflowId, args.workflowId));
-          await db.delete(workflows).where(eq(workflows.id, args.workflowId));
+          await db.delete(tasks).where(eq(tasks.workflowId, workflowId));
+          await db.delete(workflows).where(eq(workflows.id, workflowId));
 
-          return ok({ message: "Workflow deleted", workflowId: args.workflowId, name: existing.name });
+          return ok({ message: "Workflow deleted", workflowId, name: existing.name });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to delete workflow");
         }
@@ -361,13 +507,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           // Allow re-execution from crashed "active" if no live tasks
           if (workflow.status === "active") {
@@ -376,7 +526,7 @@ export function workflowTools(ctx: ToolContext) {
               .from(tasks)
               .where(
                 and(
-                  eq(tasks.workflowId, args.workflowId),
+                  eq(tasks.workflowId, workflowId),
                   inArray(tasks.status, ["running", "queued"])
                 )
               );
@@ -404,7 +554,7 @@ export function workflowTools(ctx: ToolContext) {
               .set({ status: "cancelled", updatedAt: new Date() })
               .where(
                 and(
-                  eq(tasks.workflowId, args.workflowId),
+                  eq(tasks.workflowId, workflowId),
                   inArray(tasks.status, ["running", "queued"])
                 )
               );
@@ -419,27 +569,71 @@ export function workflowTools(ctx: ToolContext) {
                 status: "draft",
                 updatedAt: new Date(),
               })
-              .where(eq(workflows.id, args.workflowId));
+              .where(eq(workflows.id, workflowId));
           }
 
           // Atomic claim: set to active
           await db
             .update(workflows)
             .set({ status: "active", updatedAt: new Date() })
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           // Fire-and-forget
           const { executeWorkflow } = await import("@/lib/workflows/engine");
-          executeWorkflow(args.workflowId).catch(() => {});
+          executeWorkflow(workflowId).catch(() => {});
 
-          ctx.onToolResult?.("execute_workflow", { id: args.workflowId, name: workflow.name });
-          return ok({ message: "Workflow execution started", workflowId: args.workflowId, name: workflow.name });
+          ctx.onToolResult?.("execute_workflow", { id: workflowId, name: workflow.name });
+          return ok({ message: "Workflow execution started", workflowId, name: workflow.name });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to execute workflow");
         }
       }
     ),
 
+    defineTool(
+      "resume_workflow",
+      "Resume a workflow that is paused at a delay step, immediately skipping the remaining delay. Use when the user says 'resume now' or 'skip the wait' for a paused workflow. Only works if the workflow status is 'paused' — a 409 response means the scheduler already resumed it. Requires approval.",
+      {
+        workflowId: z.string().describe("The workflow ID to resume"),
+      },
+      async (args) => {
+        try {
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
+            .select()
+            .from(workflows)
+            .where(eq(workflows.id, workflowId))
+            .get();
+
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
+
+          if (workflow.status !== "paused") {
+            return err(
+              `Workflow is not paused (current status: ${workflow.status}). Only paused workflows can be resumed.`,
+            );
+          }
+
+          const { resumeWorkflow } = await import("@/lib/workflows/engine");
+          // Fire-and-forget: resumeWorkflow performs atomic status transition internally.
+          resumeWorkflow(workflowId).catch((error) => {
+            console.error(`Workflow ${workflowId} resume failed:`, error);
+          });
+
+          ctx.onToolResult?.("resume_workflow", { id: workflowId, name: workflow.name });
+          return ok({
+            message: "Workflow resume dispatched",
+            workflowId,
+            name: workflow.name,
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to resume workflow");
+        }
+      },
+    ),
+
     defineTool(
       "get_workflow_status",
       "Get the current execution status of a workflow, including step-by-step progress.",
@@ -448,13 +642,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           const { parseWorkflowState } = await import("@/lib/workflows/engine");
           const { definition, state } = parseWorkflowState(workflow.definition);
@@ -531,11 +729,15 @@ export function workflowTools(ctx: ToolContext) {
           }
 
           if (args.sourceWorkflowId) {
+            const resolvedSrc = await resolveEntityId(workflows, workflows.id, args.sourceWorkflowId);
+            if ("error" in resolvedSrc) return err(resolvedSrc.error);
+            const srcWorkflowId = resolvedSrc.id;
+
             // Find task IDs belonging to the source workflow
             const workflowTasks = await db
               .select({ id: tasks.id })
               .from(tasks)
-              .where(eq(tasks.workflowId, args.sourceWorkflowId));
+              .where(eq(tasks.workflowId, srcWorkflowId));
 
             const taskIds = workflowTasks.map((t) => t.id);
             if (taskIds.length > 0) {