@hailer/mcp 1.1.17-beta.3 → 1.2.0

package/dist/mcp/tools/workflow.js

@@ -6,13 +6,48 @@
  * These are PLAYGROUND tools requiring workspace administrator permissions.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.workflowTools = exports.updateWorkflowPhaseTool = exports.coreInitTool = exports.countActivitiesTool = exports.listWorkflowsMinimalTool = exports.testFunctionFieldTool = exports.updateWorkflowFieldTool = exports.removeWorkflowTool = exports.installWorkflowTool = exports.listWorkflowsTool = exports.listWorkflowPhasesTool = exports.getWorkflowSchemaTool = void 0;
+exports.workflowTools = exports.autoSetKeysTool = exports.updateWorkflowPhaseTool = exports.coreInitTool = exports.countActivitiesTool = exports.listWorkflowsMinimalTool = exports.testFunctionFieldTool = exports.updateWorkflowFieldTool = exports.removeWorkflowTool = exports.installWorkflowTool = exports.listWorkflowsTool = exports.listWorkflowPhasesTool = exports.getWorkflowSchemaTool = void 0;
 const zod_1 = require("zod");
 const tool_registry_1 = require("../tool-registry");
 const logger_1 = require("../../lib/logger");
 const request_logger_1 = require("../../lib/request-logger");
 const workspace_overview_1 = require("../../bot/workspace-overview");
+const config_1 = require("../../config");
 const logger = (0, logger_1.createLogger)({ component: 'workflow-tools' });
+/**
+ * Detect if the SDK workspace/ directory exists (local SDK project mode).
+ * When true, config changes should go through workspace/ files + npm run push,
+ * not through MCP API calls.
+ */
+function isSdkProject() {
+    try {
+        const fs = require('fs');
+        const path = require('path');
+        const workspacePath = config_1.environment.WORKSPACE_CONFIG_PATH || path.join(process.cwd(), 'workspace');
+        return fs.existsSync(workspacePath);
+    }
+    catch {
+        return false;
+    }
+}
+/** Return an SDK redirect message for config tools when SDK is available */
+function sdkRedirect(tool, sdkCommand, sdkFile) {
+    return {
+        content: [{
+                type: "text",
+                text: `⚠️ **SDK project detected — use the SDK instead of \`${tool}\`**\n\n` +
+                    `This project has a \`workspace/\` directory, which means workflow configuration should be managed through SDK files.\n\n` +
+                    `**Instead, do this:**\n` +
+                    `1. Edit \`${sdkFile}\`\n` +
+                    `2. Run \`${sdkCommand}\`\n` +
+                    `3. Run \`npm run pull\` to sync back\n\n` +
+                    `This ensures your local files stay in sync with Hailer and changes are version-controlled.\n\n` +
+                    `💡 If you really need to use the API directly (e.g., no filesystem access), add \`force: true\` to override.`,
+            }],
+    };
+}
+/** Hint prepended to discovery tool responses when SDK workspace/ exists */
+const SDK_DISCOVERY_HINT = `💡 **Tip:** This info is available locally in \`workspace/\` files — read those instead of making API calls next time.\n\n`;
 // ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
@@ -51,11 +86,103 @@ function parseErrorType(errorMessage) {
     const match = errorMessage.match(/^(SyntaxError|ReferenceError|TypeError)/);
     return match ? match[1] : 'Error';
 }
+/** Find workflow in cached data by _id or key */
+function resolveWorkflow(processes, idOrKey) {
+    return processes.find((p) => p._id === idOrKey || p.key === idOrKey);
+}
+/** Generate a camelCase key from a name (e.g., "Customer Acquisition" → "customerAcquisition") */
+function generateKey(name, existingKeys) {
+    const words = name
+        .replace(/[^a-zA-Z0-9\s-_]/g, '')
+        .split(/[\s\-_]+/)
+        .filter(w => w.length > 0);
+    if (words.length === 0)
+        return 'unnamed';
+    const base = words[0].toLowerCase() + words.slice(1).map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+    const key = base.slice(0, 64);
+    if (!existingKeys || !existingKeys.has(key))
+        return key;
+    // Dedup: append incrementing suffix
+    for (let i = 2; i <= 99; i++) {
+        const candidate = `${key}${i}`.slice(0, 64);
+        if (!existingKeys.has(candidate))
+            return candidate;
+    }
+    return `${key}${Date.now()}`.slice(0, 64);
+}
+/**
+ * Auto-set keys on a workflow, its phases, and its fields.
+ * Skips any that already have keys. Returns a summary of what was set.
+ */
+async function autoSetKeys(workflowId, context) {
+    const result = { workflow: undefined, phases: {}, fields: {}, errors: [] };
+    // Get workflow from cache
+    const workflow = resolveWorkflow(context.init.processes || [], workflowId);
+    if (!workflow) {
+        result.errors.push(`Workflow "${workflowId}" not found`);
+        return result;
+    }
+    // Collect existing keys to avoid duplicates
+    const existingPhaseKeys = new Set();
+    for (const phase of Object.values(workflow.phases || {})) {
+        if (phase.key)
+            existingPhaseKeys.add(phase.key);
+    }
+    const existingFieldKeys = new Set();
+    for (const field of Object.values(workflow.fields || {})) {
+        if (field.key)
+            existingFieldKeys.add(field.key);
+    }
+    // Set workflow key (unique per workspace — no local dedup needed, API rejects duplicates)
+    if (!workflow.key && workflow.name) {
+        const key = generateKey(workflow.name);
+        try {
+            await context.hailer.request('process.set_info', [workflow._id, { key }]);
+            result.workflow = key;
+        }
+        catch (e) {
+            result.errors.push(`Workflow key "${key}": ${e?.message || e}`);
+        }
+    }
+    // Set phase keys (unique per workflow)
+    for (const [phaseId, phase] of Object.entries(workflow.phases || {})) {
+        const p = phase;
+        if (!p.key && p.name) {
+            const key = generateKey(p.name, existingPhaseKeys);
+            existingPhaseKeys.add(key);
+            try {
+                await context.hailer.request('phase.update', [phaseId, { key }]);
+                result.phases[phaseId] = key;
+            }
+            catch (e) {
+                result.errors.push(`Phase "${p.name}" key "${key}": ${e?.message || e}`);
+            }
+        }
+    }
+    // Set field keys (unique per workflow)
+    for (const [fieldId, field] of Object.entries(workflow.fields || {})) {
+        const f = field;
+        if (!f.key && f.label) {
+            const key = generateKey(f.label, existingFieldKeys);
+            existingFieldKeys.add(key);
+            try {
+                await context.hailer.request('process.update_field', [workflow._id, fieldId, { key }]);
+                result.fields[fieldId] = key;
+            }
+            catch (e) {
+                result.errors.push(`Field "${f.label}" key "${key}": ${e?.message || e}`);
+            }
+        }
+    }
+    return result;
+}
 // ============================================================================
 // READ TOOLS - Workflow Schema and Information
 // ============================================================================
 const getWorkflowSchemaDescription = `Get workflow field structure - CALL THIS BEFORE create_activity or update_activity.
 
+**SDK project?** If workspace/ exists, read field definitions from workspace/<WorkflowName>_<id>/fields.ts instead of calling this tool.
+
 **Hailer Concept:** Shows all fields (columns) in a workflow with their IDs, types, and options. You MUST know field IDs to create or update activities.
 
 **Returns:** Field IDs, labels, types (text, numeric, date, dropdown, user, activitylink), required status, dropdown options.
@@ -66,23 +193,18 @@ exports.getWorkflowSchemaTool = {
     group: tool_registry_1.ToolGroup.READ,
     description: getWorkflowSchemaDescription,
     schema: zod_1.z.object({
-        workflowId: zod_1.z.string().describe("Workflow ID to get schema from"),
-        phaseId: zod_1.z.string().describe("Phase ID to get schema from (use list_workflow_phases to get available phases)"),
+        workflowId: zod_1.z.string().describe("Workflow ID or key to get schema from"),
+        phaseId: zod_1.z.string().describe("Phase ID or key to get schema from (use list_workflow_phases to get available phases)"),
         compact: zod_1.z.boolean().optional().describe("Return compact summary instead of full field details (default: false)"),
+        force: zod_1.z.boolean().optional().describe("Override SDK redirect — use API even when workspace/ exists"),
     }),
     async execute(args, context) {
+        if (isSdkProject() && !args.force) {
+            return sdkRedirect('get_workflow_schema', 'cat workspace/<WorkflowName>_<id>/fields.ts', 'workspace/<WorkflowName>_<id>/fields.ts');
+        }
         try {
-            // Validate phaseId format early - must be 24-char MongoDB ID, not a simple number
-            if (args.phaseId && args.phaseId.length !== 24) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Invalid phaseId "${args.phaseId}" - must be a 24-character ID.\n\n**How to get valid phase IDs:**\n1. Call \`list_workflow_phases\` with the workflowId first\n2. Use the returned phase IDs (24 characters like "691ffdf84217e9e8434e56a5")\n\n**Example:**\n\`\`\`\nlist_workflow_phases({ workflowId: "${args.workflowId}" })\n\`\`\``,
-                        }],
-                };
-            }
             // Use cached workflow data from context.init (already fetched during initialization)
-            const workflow = context.init.processes?.find(p => p._id === args.workflowId);
+            const workflow = resolveWorkflow(context.init.processes || [], args.workflowId);
             if (!workflow) {
                 return {
                     content: [{
@@ -111,7 +233,7 @@ exports.getWorkflowSchemaTool = {
                         }],
                 };
             }
-            let responseText = `📋 **WORKFLOW SCHEMA** for "${workflow.name}":\n\n`;
+            let responseText = (isSdkProject() ? SDK_DISCOVERY_HINT : '') + `📋 **WORKFLOW SCHEMA** for "${workflow.name}":\n\n`;
             if (schemaData.name) {
                 responseText += `**Name Field:**\n`;
                 responseText += `- Type: ${schemaData.name.type}\n`;
@@ -187,6 +309,8 @@ exports.getWorkflowSchemaTool = {
 };
 const listWorkflowPhasesDescription = `List phases (stages/statuses) in a workflow - REQUIRED to get phase IDs.
 
+**SDK project?** If workspace/ exists, read phases from workspace/<WorkflowName>_<id>/phases.ts instead of calling this tool.
+
 **Hailer Concept:** Phases are stages like "New" → "In Progress" → "Done". Activities move through phases as work progresses.
 
 **When to use:** Before list_activities (need phaseId), before create_activity (need initial phase), before update_activity (to move to new phase).
@@ -197,12 +321,16 @@ exports.listWorkflowPhasesTool = {
     group: tool_registry_1.ToolGroup.READ,
     description: listWorkflowPhasesDescription,
     schema: zod_1.z.object({
-        workflowId: zod_1.z.string().describe("Workflow ID to get phases from"),
+        workflowId: zod_1.z.string().describe("Workflow ID or key to get phases from"),
+        force: zod_1.z.boolean().optional().describe("Override SDK redirect — use API even when workspace/ exists"),
     }),
     async execute(args, context) {
+        if (isSdkProject() && !args.force) {
+            return sdkRedirect('list_workflow_phases', 'cat workspace/<WorkflowName>_<id>/phases.ts', 'workspace/<WorkflowName>_<id>/phases.ts');
+        }
         try {
             // Use cached workflow data from context.init (already fetched during initialization)
-            const workflowData = context.init.processes?.find(p => p._id === args.workflowId);
+            const workflowData = resolveWorkflow(context.init.processes || [], args.workflowId);
             if (!workflowData) {
                 return {
                     content: [{
@@ -213,7 +341,7 @@ exports.listWorkflowPhasesTool = {
             }
             const phases = workflowData.phases || {};
             const phasesOrder = workflowData.phasesOrder || [];
-            let responseText = `📊 **WORKFLOW PHASES** for "${workflowData.name}":\n\n`;
+            let responseText = (isSdkProject() ? SDK_DISCOVERY_HINT : '') + `📊 **WORKFLOW PHASES** for "${workflowData.name}":\n\n`;
             if (Object.keys(phases).length === 0) {
                 responseText += `❌ No phases found in workflow "${workflowData.name}".`;
                 return {
@@ -227,6 +355,9 @@ exports.listWorkflowPhasesTool = {
                 if (phase) {
                     responseText += `${index + 1}. **${phase.name}**\n`;
                     responseText += `   - Phase ID: \`${phase._id}\`\n`;
+                    if (phase.key) {
+                        responseText += `   - Key: \`${phase.key}\`\n`;
+                    }
                     if (phase.description) {
                         responseText += `   - Description: ${phase.description}\n`;
                     }
@@ -441,6 +572,7 @@ const installWorkflowSchema = zod_1.z.object({
         .min(1, "At least one workflow template is required")
         .max(100, "Maximum 100 workflow templates per installation")
         .describe("Array of workflow template objects to install"),
+    force: zod_1.z.boolean().optional().describe("Override SDK redirect — use API directly even when workspace/ exists"),
 });
 exports.installWorkflowTool = {
     name: 'install_workflow',
@@ -448,6 +580,10 @@ exports.installWorkflowTool = {
     description: installWorkflowDescription,
     schema: installWorkflowSchema,
     async execute(args, context) {
+        // Guard: redirect to SDK when workspace/ exists
+        if (isSdkProject() && !args.force) {
+            return sdkRedirect('install_workflow', 'npm run workflows-sync:force && npm run push:force', 'workspace/workflows.ts');
+        }
         logger.debug('Installing workflow', {
             templateCount: args.workflowTemplates.length,
             apiKey: context.apiKey.substring(0, 8) + '...'
@@ -537,6 +673,29 @@ exports.installWorkflowTool = {
                 logger.warn('Failed to refresh workflow cache after installation', { error: refreshError });
                 // Non-fatal - the workflow was created, just cache is stale
             }
+            // Auto-set keys on newly created workflows
+            const keyResults = [];
+            // Extract workflow IDs from the result map first
+            const newWorkflowIds = Object.entries(result)
+                .filter(([tpl]) => tpl.startsWith('_0') || tpl.startsWith('_00'))
+                .map(([, id]) => id);
+            // Fallback: if no _0xxx pattern, take all values that look like workflow IDs
+            if (newWorkflowIds.length === 0) {
+                for (const [, id] of Object.entries(result)) {
+                    if (id.length === 24)
+                        newWorkflowIds.push(id);
+                    break; // Just take the first one
+                }
+            }
+            for (const wfId of newWorkflowIds) {
+                try {
+                    const keys = await autoSetKeys(wfId, context);
+                    keyResults.push({ workflowId: wfId, keys });
+                }
+                catch {
+                    logger.warn('Failed to auto-set keys for new workflow', { workflowId: wfId });
+                }
+            }
             // Build success response - clearly separate workflow/field/phase IDs
             const templates = transformedTemplates;
             // Extract workflow ID (the one that starts with workflow template ID or is for the workflow)
@@ -586,18 +745,35 @@ exports.installWorkflowTool = {
                 }
                 responseText += `\n`;
             }
-            // Example
-            const firstFieldId = Object.values(fieldIds)[0];
-            const firstPhaseId = Object.values(phaseIds)[0];
+            // Show auto-generated keys
+            if (keyResults.length > 0) {
+                const kr = keyResults[0].keys;
+                responseText += `**🔑 Auto-generated keys:**\n`;
+                if (kr.workflow)
+                    responseText += `- Workflow: \`${kr.workflow}\`\n`;
+                for (const [, key] of Object.entries(kr.phases))
+                    responseText += `- Phase: \`${key}\`\n`;
+                for (const [, key] of Object.entries(kr.fields))
+                    responseText += `- Field: \`${key}\`\n`;
+                if (kr.errors.length > 0) {
+                    responseText += `- ⚠️ ${kr.errors.length} key(s) failed\n`;
+                }
+                responseText += `\n`;
+            }
+            // Example using keys (preferred) with ID fallback
+            const kr = keyResults[0]?.keys;
+            const exampleWorkflow = kr?.workflow || workflowIds[0] || 'WORKFLOW_ID';
+            const examplePhase = Object.values(kr?.phases || {})[0] || Object.values(phaseIds)[0];
+            const exampleField = Object.values(kr?.fields || {})[0] || Object.values(fieldIds)[0];
             responseText += `**Example create_activity:**\n`;
             responseText += `\`\`\`json\n`;
             responseText += `{\n`;
-            responseText += `  "workflowId": "${workflowIds[0] || 'WORKFLOW_ID'}",\n`;
+            responseText += `  "workflowId": "${exampleWorkflow}",\n`;
             responseText += `  "name": "New Activity",\n`;
-            if (firstPhaseId)
-                responseText += `  "phaseId": "${firstPhaseId}",\n`;
-            if (firstFieldId)
-                responseText += `  "fields": { "${firstFieldId}": "value" }\n`;
+            if (examplePhase)
+                responseText += `  "phaseId": "${examplePhase}",\n`;
+            if (exampleField)
+                responseText += `  "fields": { "${exampleField}": "value" }\n`;
             responseText += `}\n`;
             responseText += `\`\`\``;
             return {
@@ -637,7 +813,7 @@ const removeWorkflowSchema = zod_1.z.object({
     workflowId: zod_1.z
         .string()
         .min(1, "Workflow ID is required")
-        .describe("The workflow ID to remove (get from list_workflows)"),
+        .describe("The workflow ID or key to remove (get from list_workflows)"),
     workspaceId: zod_1.z
         .string()
         .optional()
@@ -665,7 +841,7 @@ exports.removeWorkflowTool = {
         });
         try {
             // Get workflow info from cached init data
-            const workflow = context.init.processes?.find(p => p._id === args.workflowId);
+            const workflow = resolveWorkflow(context.init.processes || [], args.workflowId);
             if (!workflow) {
                 return {
                     content: [{
@@ -779,7 +955,7 @@ const updateWorkflowFieldSchema = zod_1.z.object({
     workflowId: zod_1.z
         .string()
         .min(1, "Workflow ID is required")
-        .describe("The workflow ID containing the field (get from list_workflows)"),
+        .describe("The workflow ID or key containing the field (get from list_workflows)"),
     fieldId: zod_1.z
         .string()
         .min(1, "Field ID is required")
@@ -801,6 +977,7 @@ const updateWorkflowFieldSchema = zod_1.z.object({
         .default(true)
         .optional()
         .describe("Auto-generate camelCase key from label if key not provided (default: true). IMPORTANT: Set to false when updating ONLY the label to prevent key regeneration errors."),
+    force: zod_1.z.boolean().optional().describe("Override SDK redirect — use API directly even when workspace/ exists"),
 });
 exports.updateWorkflowFieldTool = {
     name: 'update_workflow_field',
@@ -808,6 +985,9 @@ exports.updateWorkflowFieldTool = {
     description: updateWorkflowFieldDescription,
     schema: updateWorkflowFieldSchema,
     async execute(args, context) {
+        if (isSdkProject() && !args.force) {
+            return sdkRedirect('update_workflow_field', 'npm run fields-push:force', 'workspace/<WorkflowName>_<id>/fields.ts');
+        }
         logger.debug('Updating workflow field', {
             workflowId: args.workflowId,
             fieldId: args.fieldId,
@@ -953,7 +1133,7 @@ exports.testFunctionFieldTool = {
                 };
             }
             // Get workflow field definition from cached data (may be stale for newly created fields)
-            const workflow = context.init.processes?.find(p => p._id === activity.process);
+            const workflow = resolveWorkflow(context.init.processes || [], activity.process);
             const field = workflow?.fields?.[args.fieldId];
             // Resolve function variables: caller-provided takes priority, then field definition
             const functionVariables = args.functionVariables || field?.functionVariables;
@@ -1094,7 +1274,7 @@ const listWorkflowsMinimalSchema = zod_1.z.object({
 });
 exports.listWorkflowsMinimalTool = {
     name: 'list_workflows_minimal',
-    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    group: tool_registry_1.ToolGroup.READ,
     description: listWorkflowsMinimalDescription,
     schema: listWorkflowsMinimalSchema,
     async execute(args, context) {
@@ -1135,7 +1315,7 @@ exports.listWorkflowsMinimalTool = {
                 activityCount: w.createdActivities || 0,
                 isStarred: w.isStarred || false
             }));
-            let responseText = `📋 **Workflows Found**\n\n`;
+            let responseText = (isSdkProject() ? SDK_DISCOVERY_HINT : '') + `📋 **Workflows Found**\n\n`;
             responseText += `Total: ${totalCount}\n`;
             responseText += `Showing: ${workflows.length}\n`;
             if (offset > 0)
@@ -1203,11 +1383,11 @@ count_activities({
 - This tool makes 1 API call per workflow
 - Use list_workflows to get workflow IDs`;
 const countActivitiesSchema = zod_1.z.object({
-    workflowId: zod_1.z.string().describe("Workflow ID to count activities from (24 characters)"),
+    workflowId: zod_1.z.string().describe("Workflow ID or key"),
 });
 exports.countActivitiesTool = {
     name: 'count_activities',
-    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    group: tool_registry_1.ToolGroup.READ,
     description: countActivitiesDescription,
     schema: countActivitiesSchema,
     async execute(args, context) {
@@ -1217,7 +1397,7 @@ exports.countActivitiesTool = {
         });
         try {
             // Get workflow name from cached data
-            const workflow = context.init.processes?.find(p => p._id === args.workflowId);
+            const workflow = resolveWorkflow(context.init.processes || [], args.workflowId);
             if (!workflow) {
                 return {
                     content: [{
@@ -1300,14 +1480,15 @@ update_workflow_phase({
 - User must be workspace administrator
 `;
 const updateWorkflowPhaseSchema = zod_1.z.object({
-    workflowId: zod_1.z.string().describe("The workflow ID containing the phase (24 characters)"),
-    phaseId: zod_1.z.string().describe("The phase ID to update"),
+    workflowId: zod_1.z.string().describe("The workflow ID or key containing the phase"),
+    phaseId: zod_1.z.string().describe("The phase ID or key to update"),
     phaseData: zod_1.z.object({
         name: zod_1.z.string().optional().describe("New phase name"),
         description: zod_1.z.string().optional().describe("New phase description"),
         color: zod_1.z.string().optional().describe("Phase color code"),
     }).passthrough().describe("Phase properties to update"),
     workspaceId: zod_1.z.string().optional().describe("Optional workspace ID - defaults to current workspace"),
+    force: zod_1.z.boolean().optional().describe("Override SDK redirect — use API directly even when workspace/ exists"),
 });
 // ============================================================================
 // CORE INIT TOOL - Workspace overview for terminal Claude Code sessions
@@ -1348,10 +1529,21 @@ exports.coreInitTool = {
     async execute(_args, context) {
         try {
             const overview = (0, workspace_overview_1.generateWorkspaceOverview)(context.init);
+            const sdkMode = isSdkProject();
+            let prefix = `Use this workspace context for all subsequent tool calls. Do NOT call core_init again this session.\n\n`;
+            if (sdkMode) {
+                prefix += `⚡ **SDK project detected** — \`workspace/\` directory exists.\n\n` +
+                    `**IMPORTANT: Read local files for discovery, not API calls:**\n` +
+                    `- Workflow/field/phase IDs → read \`workspace/\` files (fields.ts, phases.ts, enums.ts)\n` +
+                    `- Field types, labels, options → read \`workspace/<WorkflowName>_<id>/fields.ts\`\n` +
+                    `- Phase names and order → read \`workspace/<WorkflowName>_<id>/phases.ts\`\n` +
+                    `- Workflow config changes → edit workspace/ files + \`npm run push:force\`\n\n` +
+                    `**Use MCP tools ONLY for runtime data:** create_activity, update_activity, list_activities, preview_insight, discussions.\n\n`;
+            }
             return {
                 content: [{
                         type: "text",
-                        text: `Use this workspace context for all subsequent tool calls. Do NOT call core_init again this session.\n\n${overview}`,
+                        text: prefix + overview,
                     }],
             };
         }
@@ -1373,21 +1565,15 @@ exports.updateWorkflowPhaseTool = {
     description: updateWorkflowPhaseDescription,
     schema: updateWorkflowPhaseSchema,
     async execute(args, context) {
+        if (isSdkProject() && !args.force) {
+            return sdkRedirect('update_workflow_phase', 'npm run phases-push:force', 'workspace/<WorkflowName>_<id>/phases.ts');
+        }
         logger.debug('Updating workflow phase', {
             workflowId: args.workflowId,
             phaseId: args.phaseId,
             apiKey: context.apiKey.substring(0, 8) + '...'
         });
         try {
-            // Validate phaseId format early - must be 24-char MongoDB ID, not a simple number
-            if (args.phaseId && args.phaseId.length !== 24) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Invalid phaseId "${args.phaseId}" - must be a 24-character ID.\n\n**How to get valid phase IDs:**\n1. Call \`list_workflow_phases\` with the workflowId first\n2. Use the returned phase IDs (24 characters like "691ffdf84217e9e8434e56a5")\n\n**Example:**\n\`\`\`\nlist_workflow_phases({ workflowId: "${args.workflowId}" })\n\`\`\``,
-                        }],
-                };
-            }
             // Get current workspace from cached init data
             let workspaceId = args.workspaceId;
             if (!workspaceId) {
@@ -1468,6 +1654,66 @@ exports.updateWorkflowPhaseTool = {
         }
     }
 };
+// ============================================================================
+// AUTO SET KEYS TOOL
+// ============================================================================
+const autoSetKeysDescription = `Auto-generate human-readable keys for a workflow, its phases, and its fields. Keys are derived from names/labels (e.g., "Customer Acquisition" → "customer-acquisition"). Skips entities that already have keys set. After setting keys, you can use them instead of hex ObjectIds in all tools.`;
+exports.autoSetKeysTool = {
+    name: 'auto_set_keys',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: autoSetKeysDescription,
+    schema: zod_1.z.object({
+        workflowId: zod_1.z.string().describe("Workflow ID or key to set keys on"),
+    }),
+    async execute(args, context) {
+        try {
+            const result = await autoSetKeys(args.workflowId, context);
+            let responseText = `✅ **Keys Auto-Generated**\n\n`;
+            if (result.workflow) {
+                responseText += `**Workflow key:** \`${result.workflow}\`\n\n`;
+            }
+            else {
+                const workflow = resolveWorkflow(context.init.processes || [], args.workflowId);
+                if (workflow?.key) {
+                    responseText += `**Workflow key:** \`${workflow.key}\` (already set)\n\n`;
+                }
+            }
+            const phaseEntries = Object.entries(result.phases);
+            if (phaseEntries.length > 0) {
+                responseText += `**Phase keys set (${phaseEntries.length}):**\n`;
+                for (const [, key] of phaseEntries) {
+                    responseText += `- \`${key}\`\n`;
+                }
+                responseText += `\n`;
+            }
+            const fieldEntries = Object.entries(result.fields);
+            if (fieldEntries.length > 0) {
+                responseText += `**Field keys set (${fieldEntries.length}):**\n`;
+                for (const [, key] of fieldEntries) {
+                    responseText += `- \`${key}\`\n`;
+                }
+                responseText += `\n`;
+            }
+            if (phaseEntries.length === 0 && fieldEntries.length === 0 && !result.workflow) {
+                responseText += `All keys already set — nothing to do.\n`;
+            }
+            if (result.errors.length > 0) {
+                responseText += `\n⚠️ **Errors (${result.errors.length}):**\n`;
+                for (const err of result.errors) {
+                    responseText += `- ${err}\n`;
+                }
+            }
+            responseText += `\n💡 You can now use these keys instead of hex IDs in all tools.`;
+            return { content: [{ type: "text", text: responseText }] };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `❌ **Error setting keys:** ${errorMessage}` }],
+            };
+        }
+    }
+};
 /** All workflow tools */
 exports.workflowTools = [
     exports.getWorkflowSchemaTool,
@@ -1481,5 +1727,6 @@ exports.workflowTools = [
     exports.listWorkflowsMinimalTool,
     exports.countActivitiesTool,
     exports.coreInitTool,
+    exports.autoSetKeysTool,
 ];
 //# sourceMappingURL=workflow.js.map