@ema.co/mcp-toolkit 1.5.2 → 1.6.0

package/dist/mcp/tools-consolidated.js

@@ -46,138 +46,183 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
             inputSchema: { type: "object", properties: {}, required: [] },
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 2. PERSONA - AI Employee management (CRUD + compare + versioning)
+        // 2. PERSONA - Unified AI Employee management (create, modify, analyze, list)
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "persona",
-            description: `Unified AI Employee (persona) management.
+            description: `Create, modify, analyze, or list AI Employees. ONE tool for everything.
 
-**Get single** (default when id provided):
-  persona(id="IT Support Bot")
+## ⚠️ ONE CALL CREATES EVERYTHING - THEN STOP
+
+If requirements are unclear, first call \`template(questions=true)\` to get what to ask.
+Then make ONE call with all gathered info:
+
+\`\`\`
+persona(
+  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
+  type="voice",
+  name="SP - SDR Test",  // REQUIRED: The actual persona name shown in Ema
+  preview=false
+)
+\`\`\`
+
+**After success, STOP. Do NOT make follow-up calls to "fix" or "enhance".**
+
+**MCP handles internally:** template selection, config generation, widget formatting, welcome message, API calls.
+
+## CRITICAL: The \`name\` Parameter
+
+The \`name\` parameter is the **actual persona name** in the Ema platform - NOT derived from input.
+
+  ❌ name omitted → MCP parses name from input (often wrong)
+  ✅ name="SP - SDR Test" → Exact name shown in platform
+
+## Create NEW AI Employee
+
+  persona(input="<what it should do>", type="voice", name="Actual Name", preview=false)
+
+## Modify EXISTING (workflow changes)
+
+  persona(id="abc-123", input="add HITL before email", preview=false)
+
+## Update Config Only (voice settings, welcome message)
+
+  persona(id="abc-123", input="Update welcome message to: Hello!", preview=false)
+
+MCP auto-detects config vs workflow changes.
+
+## Analyze/Get
+
+  persona(id="abc-123")
   persona(id="abc-123", include_workflow=true)
 
-**List/Search** (when --all or filters used):
+## Optimize (auto-fix issues)
+
+  persona(id="abc-123", optimize=true, preview=false)
+
+## List/Search
+
   persona(all=true)
   persona(query="support", status="active")
-  persona(trigger_type="voice")
 
-**Create**:
-  persona(mode="create", name="New Bot", type="voice")
+## Simple vs Complex Workflows
 
-**Update**:
-  persona(id="abc-123", mode="update", name="Renamed")
+**Simple** (Q&A, search + respond): Deploys directly → \`status: "success"\`
 
-**Compare**:
-  persona(id="abc-123", mode="compare", compare_to="def-456")
+**Complex** (email, HITL, multi-intent): Returns \`status: "needs_llm_generation"\` with:
+- \`llm_prompt\`: System + user prompts for workflow generation
+- \`available_actions\`: Action catalog from API
+- \`hint\`: How to complete deployment
 
-**Templates** (list available templates):
-  persona(templates=true)
+For complex workflows, send the prompt to an LLM and deploy:
+  \`persona(workflow_def=<llm_response>, ...)\`
+
+## Key Rules
 
-**Version Management** (track configuration history):
-  persona(id="abc-123", mode="version_create", message="Before major update")
-  persona(id="abc-123", mode="version_list")
-  persona(id="abc-123", mode="version_get", version="v3")
-  persona(id="abc-123", mode="version_compare", v1="v2", v2="v3")
-  persona(id="abc-123", mode="version_restore", version="v2")
-  persona(id="abc-123", mode="version_policy", auto_on_deploy=true)`,
+1. **ONE CALL** - Put everything in \`input\`, explicit \`name\`, MCP handles rest
+2. **STOP after success** - Don't make follow-up "fix" calls
+3. **preview=false** - Deploys to Ema platform`,
             inputSchema: withEnv({
-                // ID (or exact name) (optional - if omitted with all=true, lists all)
+                // === IDENTITY ===
                 id: {
                     type: "string",
-                    description: "Persona ID (UUID) or exact name. Omit for list operations."
+                    description: "Persona ID (UUID) or exact name. Omit when creating new."
                 },
-                // Deprecated alias (backwards compatibility)
                 identifier: {
                     type: "string",
                     deprecated: true,
-                    description: "DEPRECATED: use id. Persona ID (UUID) or exact name.",
+                    description: "DEPRECATED: use id.",
                 },
-                // Mode (defaults to "get" if id provided, "list" if all=true)
-                mode: {
+                // === CREATE/MODIFY (the main way to use this tool) ===
+                input: {
                     type: "string",
-                    enum: ["get", "list", "create", "update", "compare", "version_create", "version_list", "version_get", "version_compare", "version_restore", "version_policy"],
-                    description: "Operation mode. Default: 'get' with id, 'list' without."
+                    description: "Natural language description. For new: 'Voice AI for sales...'. For modify: 'add HITL before email'.",
                 },
-                // List/Search flags
+                type: {
+                    type: "string",
+                    enum: ["voice", "chat", "dashboard"],
+                    description: "AI Employee type. REQUIRED for creating new."
+                },
+                name: { type: "string", description: "REQUIRED for new: The actual persona name shown in Ema platform (e.g., 'SP - SDR Test'). Don't derive from input." },
+                description: { type: "string", description: "Description of what it does." },
+                preview: {
+                    type: "boolean",
+                    description: "Default: true (safe). Set false to deploy changes."
+                },
+                // === ANALYZE/OPTIMIZE ===
+                optimize: {
+                    type: "boolean",
+                    description: "Auto-fix detected issues. Use with id.",
+                },
+                include: {
+                    type: "array",
+                    items: { type: "string", enum: ["issues", "connections", "fixes", "metrics"] },
+                    description: "What to include in analysis output.",
+                },
+                include_workflow: { type: "boolean", description: "Include full workflow_def in response" },
+                include_fingerprint: { type: "boolean", description: "Include config hash" },
+                // === LIST/SEARCH ===
                 all: { type: "boolean", description: "List all personas" },
                 query: { type: "string", description: "Search by name (partial match)" },
                 status: { type: "string", description: "Filter: 'active', 'inactive', 'draft'" },
                 trigger_type: { type: "string", description: "Filter: 'voice', 'chat', 'dashboard'" },
                 limit: { type: "number", description: "Max results (default: 50)" },
-                // Get flags
-                include_workflow: { type: "boolean", description: "Include full workflow_def" },
-                include_fingerprint: { type: "boolean", description: "Include config hash" },
-                // Create flags
-                name: { type: "string", description: "Name (for create/update)" },
-                description: { type: "string", description: "Description (for create/update)" },
-                type: {
-                    type: "string",
-                    enum: ["voice", "chat", "dashboard"],
-                    description: "Persona type (for create)"
-                },
-                template_id: { type: "string", description: "Template ID (for create)" },
-                clone_from: { type: "string", description: "Clone from persona ID (for create)" },
-                clone_data: { type: "boolean", description: "Also clone knowledge base files when using clone_from (default: false)" },
-                // Update flags
-                enabled: { type: "boolean", description: "Enable/disable (for update)" },
+                // === COMPARE ===
+                compare_to: { type: "string", description: "Second persona ID for comparison" },
+                compare_env: { type: "string", description: "Environment of compare_to persona" },
+                // === ADVANCED/OVERRIDE ===
                 proto_config: {
                     type: "object",
-                    description: "Voice/chat settings (welcomeMessage, identityAndPurpose, etc.) for update"
+                    description: "Override voice/chat settings. Usually auto-generated from input."
                 },
                 workflow: {
                     type: "object",
-                    description: "Workflow definition to set (for update)"
+                    description: "Direct workflow JSON (advanced). Usually auto-generated."
                 },
-                // Compare flags
-                compare_to: { type: "string", description: "Second persona ID (for compare)" },
-                compare_env: { type: "string", description: "Environment of compare_to persona" },
-                // Templates flag
+                workflow_def: {
+                    type: "object",
+                    description: "Alias for workflow (backwards compatibility)."
+                },
+                template_id: { type: "string", description: "Specific template ID (usually auto-selected)" },
+                clone_from: { type: "string", description: "Clone from existing persona ID" },
+                clone_data: { type: "boolean", description: "Also clone knowledge base files" },
+                enabled: { type: "boolean", description: "Enable/disable persona" },
+                // === TEMPLATES ===
                 templates: { type: "boolean", description: "List available templates" },
-                // Version management flags
-                version: { type: "string", description: "Version identifier (e.g., 'v3', 'latest', or UUID)" },
-                v1: { type: "string", description: "First version for comparison (version_compare mode)" },
-                v2: { type: "string", description: "Second version for comparison (version_compare mode)" },
-                message: { type: "string", description: "Version message/description (version_create mode)" },
-                auto_on_deploy: { type: "boolean", description: "Auto-create version on deploy (version_policy mode)" },
-                auto_on_sync: { type: "boolean", description: "Auto-create version on sync (version_policy mode)" },
-                max_versions: { type: "number", description: "Max versions to keep (version_policy mode)" },
+                // === VERSION MANAGEMENT ===
+                mode: {
+                    type: "string",
+                    enum: ["version_create", "version_list", "version_get", "version_compare", "version_restore", "version_policy"],
+                    description: "Version management mode. Only needed for version operations."
+                },
+                version: { type: "string", description: "Version identifier (e.g., 'v3', 'latest')" },
+                v1: { type: "string", description: "First version for comparison" },
+                v2: { type: "string", description: "Second version for comparison" },
+                message: { type: "string", description: "Version message/description" },
+                auto_on_deploy: { type: "boolean", description: "Auto-create version on deploy" },
+                auto_on_sync: { type: "boolean", description: "Auto-create version on sync" },
+                max_versions: { type: "number", description: "Max versions to keep" },
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 3. WORKFLOW - Unified workflow operations (greenfield & brownfield)
+        // 3. WORKFLOW - DEPRECATED: Use persona() instead
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "workflow",
-            description: `Create, modify, analyze, or deploy AI Employee workflows.
-
-## Creating a NEW AI Employee (Greenfield)
-
-Creates persona from template, configures settings. Template provides valid workflow structure.
-
-  workflow(input="Voice AI for sales development", name="My Sales SDR", type="voice", preview=false)
+            description: `⚠️ DEPRECATED: Use \`persona()\` instead. This tool routes to persona.
 
-Returns: { deployed_to: { persona_id, created: true }, next_steps: [...] }
+## Migration Guide
 
-To customize the workflow AFTER creation, use modify mode with the persona_id.
+OLD (deprecated):
+  workflow(input="...", type="voice", name="Bot", preview=false)
+  workflow(persona_id="abc", input="add HITL")
 
-## Modifying an EXISTING AI Employee (Brownfield)
+NEW (use this):
+  persona(input="...", type="voice", name="Bot", preview=false)
+  persona(id="abc", input="add HITL")
 
-Uses LLM-native workflow transformation. Fetches existing workflow, transforms it, deploys.
-
-  workflow(persona_id="abc-123", input="add HITL approval before sending emails")
-  workflow(persona_id="abc-123", input="add a new Sales intent category", preview=false)
-
-## Analyzing a Workflow
-
-  workflow(persona_id="abc-123")  # Returns issues, connections, metrics
-  workflow(persona_id="abc-123", optimize=true, preview=false)  # Auto-fix and deploy
-
-## Key Rules
-
-1. **preview=true (default)**: Safe - returns result without deploying
-2. **preview=false**: Deploys changes to Ema platform  
-3. **Greenfield creates from template** - then modify workflow separately if needed
-4. **Brownfield transforms existing** - uses decompile → transform → compile`,
+The \`persona\` tool now handles everything: create, modify, analyze, list.
+This \`workflow\` tool still works but shows a deprecation warning.`,
             inputSchema: withEnv({
                 // === REQUIRED for creating/modifying ===
                 input: {
@@ -296,23 +341,24 @@ Uses LLM-native workflow transformation. Fetches existing workflow, transforms i
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "template",
-            description: `Get workflow patterns, widget references, and configuration templates.
+            description: `Get qualifying questions and reference patterns.
+
+## 🎯 PRIMARY USE: Get Questions to Ask User
+
+**Before creating an AI Employee, call this to get what to ask:**
+  template(questions=true)                    // All qualifying questions
+  template(questions=true, category="Voice")  // Voice-specific questions
 
-**Workflow patterns**:
-  template(pattern="intent-routing")
-  template(patterns=true)
-  template(patterns=true, type="voice")
+Returns structured questions about: type, intents, data sources, actions, approvals, etc.
+Ask the user these questions, then put answers into ONE workflow() call.
 
-**Widget reference**:
-  template(widgets="voice")
-  template(widgets="chat")
+## Reference (understand options, not for manual building)
 
-**Persona config template**:
-  template(config="voice")  # Voice AI settings template
+  template(pattern="intent-routing")  // See pattern structure
+  template(patterns=true)             // List available patterns
+  template(widgets="voice")           // Widget reference
 
-**Qualifying questions** (for requirements gathering):
-  template(questions=true)
-  template(questions=true, category="Voice")`,
+⚠️ Do NOT copy/paste configs from these - MCP generates them internally.`,
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/sdk/action-registry.js

@@ -0,0 +1,128 @@
+/**
+ * Action Registry - Helpers for extracting action metadata from API
+ *
+ * Uses existing client.listActions() - no duplicate caching needed.
+ * Just provides helpers to extract version/namespace from raw API response.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers to extract version/namespace from raw API response
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract action name, version, and namespaces from raw API response.
+ */
+export function parseActionDefinition(action) {
+    // API returns typeName.name.namespaces and typeName.version
+    const raw = action;
+    const typeName = raw.typeName;
+    if (!typeName?.name?.name)
+        return null;
+    return {
+        name: typeName.name.name,
+        version: typeName.version ?? "v0",
+        namespaces: typeName.name.namespaces ?? ["actions", "emainternal"],
+    };
+}
+/**
+ * Extract template info from raw API response.
+ */
+export function parseTemplateDefinition(template) {
+    if (!template.id || !template.name)
+        return null;
+    const raw = template;
+    return {
+        id: template.id,
+        name: template.name,
+        triggerType: raw.trigger_type ?? 1,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry Class (lightweight, uses client directly)
+// ─────────────────────────────────────────────────────────────────────────────
+export class ActionRegistry {
+    actions = new Map();
+    templates = new Map();
+    templatesByType = new Map();
+    loaded = false;
+    /**
+     * Load from raw API data.
+     * Call client.listActions() and client.getPersonaTemplates() externally
+     * and pass the results here.
+     */
+    loadFromData(actions, templates) {
+        this.actions.clear();
+        this.templates.clear();
+        this.templatesByType.clear();
+        for (const action of actions) {
+            const def = parseActionDefinition(action);
+            if (def) {
+                this.actions.set(def.name, def);
+            }
+        }
+        for (const template of templates) {
+            const def = parseTemplateDefinition(template);
+            if (def) {
+                this.templates.set(def.id, def);
+                // First template of each trigger type wins
+                if (!this.templatesByType.has(def.triggerType)) {
+                    this.templatesByType.set(def.triggerType, def);
+                }
+            }
+        }
+        this.loaded = true;
+    }
+    /**
+     * Get action version. Falls back to "v0".
+     */
+    getVersion(actionName) {
+        return this.actions.get(actionName)?.version ?? "v0";
+    }
+    /**
+     * Get action namespaces. Falls back to ["actions", "emainternal"].
+     */
+    getNamespaces(actionName) {
+        return this.actions.get(actionName)?.namespaces ?? ["actions", "emainternal"];
+    }
+    /**
+     * Get action definition.
+     */
+    getAction(actionName) {
+        return this.actions.get(actionName);
+    }
+    /**
+     * Get template by ID.
+     */
+    getTemplate(id) {
+        return this.templates.get(id);
+    }
+    /**
+     * Get template for persona type.
+     * Trigger types: 1=CHAT, 2=DASHBOARD, 4=VOICE
+     */
+    getTemplateForType(type) {
+        const triggerTypes = {
+            voice: 4,
+            chat: 1,
+            dashboard: 2,
+        };
+        return this.templatesByType.get(triggerTypes[type]);
+    }
+    isLoaded() {
+        return this.loaded;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory function (loads from API)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create and load action registry from API.
+ * Uses client methods directly - no caching here (resources.ts handles that for MCP).
+ */
+export async function ensureActionRegistry(client) {
+    const registry = new ActionRegistry();
+    const [actions, templates] = await Promise.all([
+        client.listActions().catch(() => []),
+        client.getPersonaTemplates().catch(() => []),
+    ]);
+    registry.loadFromData(actions, templates);
+    return registry;
+}

package/dist/sdk/client.js

@@ -100,80 +100,22 @@ export class EmaClient {
                 const controller = new AbortController();
                 const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
                 const fullUrl = `${this.env.baseUrl.replace(/\/$/, "")}${path}`;
-                // #region agent log
-                // H3/H4: verify wire-level request shape + size (no secrets).
-                try {
-                    if (process.env.EMA_MCP_DEBUG_LOGS !== "1") {
-                        // disabled
-                    }
-                    else {
-                        const isUpdatePersona = path.includes("/api/personas/update_persona");
-                        const jsonAny = opts?.json;
-                        const workflowAny = jsonAny?.workflow ?? jsonAny?.workflow_def;
-                        const actions = workflowAny?.actions ?? [];
-                        const actionNames = Array.isArray(actions)
-                            ? actions
-                                .slice(0, 50)
-                                .map((a) => a?.name)
-                                .filter((n) => typeof n === "string")
-                            : [];
-                        const containsHitl = actionNames.some((n) => n.toLowerCase().includes("hitl")) || JSON.stringify(actionNames).toLowerCase().includes("hitl");
-                        const jsonSize = opts?.json !== undefined ? JSON.stringify(opts.json).length : 0;
-                        fetch('http://127.0.0.1:7245/ingest/c9b6768a-494d-4365-bd46-bf6c43dc1e22', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location: 'src/sdk/client.ts:requestWithRetries:pre', message: 'HTTP request', data: { env: this.env.name, codeDir: process.env.EMA_MCP_CODE_DIR ?? null, cwd: process.cwd(), method, path, isUpdatePersona, attempt, retries, hasJson: opts?.json !== undefined, jsonSize, hasWorkflow: !!workflowAny, actionCount: Array.isArray(actions) ? actions.length : 0, containsHitl }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'pre-fix', hypothesisId: 'H3' }) }).catch(() => { });
-                    }
+                // gRPC-Connect endpoints need Connect-Protocol-Version header
+                const isGrpcConnect = path.includes(".v1.") || path.includes(".v2.");
+                const headers = {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "Content-Type": "application/json",
+                };
+                if (isGrpcConnect) {
+                    headers["Connect-Protocol-Version"] = "1";
                 }
-                catch { }
-                // #endregion agent log
                 const response = await fetch(fullUrl, {
                     method,
-                    headers: {
-                        Authorization: `Bearer ${this.env.bearerToken}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers,
                     body: opts?.json !== undefined ? JSON.stringify(opts.json) : undefined,
                     signal: controller.signal,
                 });
                 clearTimeout(timeoutId);
-                // #region agent log
-                // H1/H2/H4: capture response status + request id for correlation (no secrets).
-                try {
-                    if (process.env.EMA_MCP_DEBUG_LOGS !== "1") {
-                        // disabled
-                    }
-                    else {
-                        const reqId = response.headers.get("x-request-id") ?? response.headers.get("x-correlation-id") ?? response.headers.get("x-amzn-trace-id");
-                        fetch('http://127.0.0.1:7245/ingest/c9b6768a-494d-4365-bd46-bf6c43dc1e22', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location: 'src/sdk/client.ts:requestWithRetries:post', message: 'HTTP response', data: { env: this.env.name, method, path, status: response.status, ok: response.ok, attempt, durationMs: Date.now() - startedAt, reqId }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'pre-fix', hypothesisId: 'H1' }) }).catch(() => { });
-                    }
-                }
-                catch { }
-                // #endregion agent log
-                // #region agent log
-                // H1/H2: for update_persona failures, log first part of error body (redacted/truncated).
-                try {
-                    if (process.env.EMA_MCP_DEBUG_LOGS !== "1") {
-                        // disabled
-                    }
-                    else {
-                        const isUpdatePersona = path.includes("/api/personas/update_persona");
-                        if (isUpdatePersona && !response.ok) {
-                            const cloned = response.clone();
-                            const txt = await cloned.text();
-                            const snippet = txt.length > 1200 ? `${txt.slice(0, 1200)}…(truncated)` : txt;
-                            let parsedDetail;
-                            let hasGweIssues = false;
-                            try {
-                                const j = JSON.parse(txt);
-                                const detail = j.detail ?? j.message ?? j.error;
-                                parsedDetail = typeof detail === "string" ? detail : undefined;
-                                hasGweIssues = Array.isArray(j.gwe_issues);
-                            }
-                            catch { }
-                            fetch('http://127.0.0.1:7245/ingest/c9b6768a-494d-4365-bd46-bf6c43dc1e22', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location: 'src/sdk/client.ts:requestWithRetries:errorBody', message: 'HTTP error body (update_persona)', data: { env: this.env.name, method, path, status: response.status, parsedDetail, hasGweIssues, bodySnippet: snippet }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'pre-fix', hypothesisId: 'H2' }) }).catch(() => { });
-                        }
-                    }
-                }
-                catch { }
-                // #endregion agent log
                 // Handle 401 - attempt token refresh once
                 if (response.status === 401 && !hasAttemptedRefresh && this.tokenRefreshConfig?.refreshCallback) {
                     hasAttemptedRefresh = true;
@@ -324,15 +266,6 @@ export class EmaClient {
         });
         if (!resp.ok) {
             const body = await resp.text();
-            // #region agent log
-            try {
-                if (this.debugLogsEnabled) {
-                    const snippet = body.length > 2000 ? `${body.slice(0, 2000)}…(truncated)` : body;
-                    fetch('http://127.0.0.1:7245/ingest/c9b6768a-494d-4365-bd46-bf6c43dc1e22', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location: 'src/sdk/client.ts:checkWorkflow:error', message: 'CheckWorkflow failed', data: { env: this.env.name, status: resp.status, bodySnippet: snippet }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'pre-fix', hypothesisId: 'H5' }) }).catch(() => { });
-                }
-            }
-            catch { }
-            // #endregion agent log
             throw new EmaApiError({
                 statusCode: resp.status,
                 body,
@@ -340,35 +273,70 @@ export class EmaClient {
             });
         }
         const data = (await resp.json());
-        // #region agent log
-        try {
-            if (this.debugLogsEnabled) {
-                const keys = Object.keys(data);
-                fetch('http://127.0.0.1:7245/ingest/c9b6768a-494d-4365-bd46-bf6c43dc1e22', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location: 'src/sdk/client.ts:checkWorkflow:ok', message: 'CheckWorkflow ok', data: { env: this.env.name, keys }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'pre-fix', hypothesisId: 'H5' }) }).catch(() => { });
-            }
-        }
-        catch { }
-        // #endregion agent log
         return data;
     }
     async updateAiEmployee(req, opts) {
         // Use /api/personas/update_persona - same endpoint as Ema frontend
+        // Debug logging for troubleshooting
+        if (opts?.verbose || process.env.EMA_DEBUG) {
+            console.error("[EmaClient] updateAiEmployee request:", JSON.stringify({
+                persona_id: req.persona_id,
+                has_workflow: !!req.workflow,
+                workflow_actions: req.workflow ? req.workflow.actions : undefined,
+                has_proto_config: !!req.proto_config,
+            }, null, 2));
+        }
         const resp = await this.requestWithRetries("POST", "/api/personas/update_persona", {
             json: req,
         });
         if (!resp.ok) {
             const body = await resp.text();
+            // Debug logging for errors
+            if (opts?.verbose || process.env.EMA_DEBUG) {
+                console.error("[EmaClient] updateAiEmployee FAILED:", resp.status, body);
+                console.error("[EmaClient] Request that failed:", JSON.stringify(req, null, 2).slice(0, 5000));
+            }
             // Try to parse error body for better error messages
             let errorDetail = "";
             try {
                 const errorJson = JSON.parse(body);
                 // Ema API returns InvalidPersonaResponse with 'detail' field
                 errorDetail = errorJson.detail ?? errorJson.message ?? errorJson.error ?? "";
-                // Also check for GWE (workflow) issues
-                if (errorJson.gwe_issues) {
-                    const issues = errorJson.gwe_issues;
-                    if (Array.isArray(issues)) {
-                        errorDetail += ` Workflow issues: ${issues.map((i) => i.message ?? i.detail ?? JSON.stringify(i)).join("; ")}`;
+                // Parse GWE (workflow) issues - it's an object, not an array
+                // See WorkflowIssues schema in OpenAPI spec
+                if (errorJson.gwe_issues && typeof errorJson.gwe_issues === "object") {
+                    const gwe = errorJson.gwe_issues;
+                    const issuesParts = [];
+                    if (gwe.detail) {
+                        issuesParts.push(`Detail: ${gwe.detail}`);
+                    }
+                    if (Array.isArray(gwe.missing_widgets) && gwe.missing_widgets.length > 0) {
+                        issuesParts.push(`Missing widgets: ${gwe.missing_widgets.join(", ")}`);
+                    }
+                    if (Array.isArray(gwe.unready_widgets) && gwe.unready_widgets.length > 0) {
+                        const unready = gwe.unready_widgets.map((w) => `${w.widget_name}: ${w.message}`);
+                        issuesParts.push(`Unready widgets: ${unready.join("; ")}`);
+                    }
+                    if (Array.isArray(gwe.missing_inputs) && gwe.missing_inputs.length > 0) {
+                        const missing = gwe.missing_inputs.map((i) => `${i.action_name}.${i.input_name}`);
+                        issuesParts.push(`Missing inputs: ${missing.join(", ")}`);
+                    }
+                    if (Array.isArray(gwe.mismatched_inputs) && gwe.mismatched_inputs.length > 0) {
+                        const mismatched = gwe.mismatched_inputs.map((i) => `${i.action_name}.${i.input_name}`);
+                        issuesParts.push(`Mismatched inputs: ${mismatched.join(", ")}`);
+                    }
+                    if (Array.isArray(gwe.named_result_errors) && gwe.named_result_errors.length > 0) {
+                        const resultErrs = gwe.named_result_errors.map((e) => `${e.named_result_key}: ${e.error_description}`);
+                        issuesParts.push(`Result errors: ${resultErrs.join("; ")}`);
+                    }
+                    if (gwe.has_cycles) {
+                        issuesParts.push("Workflow has cycles");
+                    }
+                    if (gwe.has_no_outputs) {
+                        issuesParts.push("Workflow has no outputs");
+                    }
+                    if (issuesParts.length > 0) {
+                        errorDetail += ` [GWE Issues: ${issuesParts.join(" | ")}]`;
                     }
                 }
             }

package/dist/sdk/generated/api-types.js

@@ -0,0 +1,11 @@
+/**
+ * Auto-generated TypeScript types from Ema Platform OpenAPI spec.
+ * Generated from: Ema Platform API v1.0.0
+ * Generated at: 2026-01-16T13:46:50.729Z
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:types
+ */
+export {};
+// ─────────────────────────────────────────────────────────────────────────────
+// API Operation Types
+// ─────────────────────────────────────────────────────────────────────────────