@ema.co/mcp-toolkit 1.4.2 → 1.4.3

package/dist/sdk/client.js

@@ -229,33 +229,46 @@ export class EmaClient {
         return this.getPersonasForTenant();
     }
     /**
-     * Get a single persona by ID with full details including workflow_def.
+     * Get a single persona by ID with full details including workflow_def and proto_config.
      * Uses /api/personas/{id} endpoint which returns the complete persona including workflow_def.
+     * Falls back to /api/ai_employee/get_ai_employee for additional data if needed.
      */
     async getPersonaById(personaId) {
+        let persona = null;
         // Primary: /api/personas/{id} - returns full persona with workflow_def
         // Note: get_minimal_persona=false is REQUIRED to get workflow_def in response
         try {
             const resp = await this.requestWithRetries("GET", `/api/personas/${personaId}?get_minimal_persona=false`, {});
             if (resp.ok) {
-                return (await resp.json());
+                persona = (await resp.json());
             }
         }
         catch {
             // Fall through to fallback
         }
         // Fallback: /api/ai_employee/get_ai_employee endpoint
+        // Also used to supplement proto_config if missing from primary endpoint
         try {
             const resp = await this.requestWithRetries("GET", `/api/ai_employee/get_ai_employee?persona_id=${personaId}`, {});
             if (resp.ok) {
                 const data = (await resp.json());
-                return data.persona ?? data.ai_employee ?? data.config ?? null;
+                const fallbackPersona = data.persona ?? data.ai_employee ?? data.config ?? null;
+                if (!persona) {
+                    // Primary failed, use fallback entirely
+                    persona = fallbackPersona;
+                }
+                else if (fallbackPersona) {
+                    // Merge proto_config from fallback if missing in primary
+                    if (!persona.proto_config && fallbackPersona.proto_config) {
+                        persona.proto_config = fallbackPersona.proto_config;
+                    }
+                }
             }
         }
         catch {
-            // Fall through to return null
+            // Fallback failed, continue with what we have
         }
-        return null;
+        return persona;
     }
     /**
      * Get workflow definition by workflow_id.
@@ -492,33 +505,164 @@ export class EmaClient {
             clearTimeout(timeoutId);
         }
     }
+    /**
+     * Make a Connect-RPC style request with persona context.
+     * DataIngestService requires x-persona-id header.
+     */
+    async connectRequest(path, body, personaId) {
+        const fullUrl = `${this.env.baseUrl.replace(/\/$/, "")}${path}`;
+        return fetch(fullUrl, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.env.bearerToken}`,
+                "Content-Type": "application/json",
+                "x-persona-id": personaId,
+                "Connect-Protocol-Version": "1",
+            },
+            body: JSON.stringify(body),
+        });
+    }
     /**
      * List data source files for an AI Employee.
-     * Uses the DataIngestService gRPC endpoint.
+     * Uses the DataIngestService GetRootContentNodes gRPC endpoint.
+     *
+     * @param personaId - The persona ID
+     * @param opts - Optional parameters for pagination and filtering
      */
-    async listDataSourceFiles(personaId) {
-        // Try the content aggregates endpoint (may return limited info)
+    async listDataSourceFiles(personaId, opts) {
+        const widgetName = opts?.widgetName ?? "fileUpload";
+        const page = opts?.page ?? 1;
+        const limit = opts?.limit ?? 50;
         try {
-            const resp = await this.requestWithRetries("POST", "/dataingest.v1.DataIngestService/GetContentNodeAggregates", {
-                json: {
-                    widget_name: "fileUpload",
-                    include_files: true,
-                    persona_id: personaId,
-                },
-            });
+            // Use Connect-RPC JSON encoding
+            const resp = await this.connectRequest("/dataingest.v1.DataIngestService/GetRootContentNodes", {
+                widgetName: widgetName,
+                includeFiles: true,
+                groupId: personaId,
+                groupType: "FILE_PICKER_GROUP_TYPE_PERSONA", // 2 in proto enum
+                page: page,
+                limit: limit,
+            }, personaId);
             if (resp.ok) {
                 const data = await resp.json();
-                return (data.files ?? []).map((f) => ({
-                    id: f.id,
-                    filename: f.name,
-                    status: f.status ?? "unknown",
+                const files = (data.data ?? []).map((f) => ({
+                    id: f.contentNodeId ?? "",
+                    filename: f.nodeName ?? "",
+                    status: this.normalizeContentNodeStatus(f.status),
+                    createdAt: f.createdAt,
+                    updatedAt: f.updatedAt,
+                    sourceType: f.sourceType,
                 }));
+                return {
+                    files,
+                    pagination: {
+                        page: data.pagination?.page ?? page,
+                        limit: data.pagination?.limit ?? limit,
+                        total: data.pagination?.total ?? files.length,
+                        totalPages: data.pagination?.totalPages ?? 1,
+                    },
+                    widgetName: data.meta?.widgetName ?? widgetName,
+                };
+            }
+            // If Connect-JSON fails, try to get files from persona's status_log
+            const persona = await this.getPersonaById(personaId);
+            if (persona) {
+                const statusLogFiles = this.extractFilesFromStatusLog(persona, widgetName);
+                if (statusLogFiles.length > 0) {
+                    return {
+                        files: statusLogFiles,
+                        pagination: {
+                            page: 1,
+                            limit: statusLogFiles.length,
+                            total: statusLogFiles.length,
+                            totalPages: 1
+                        },
+                        widgetName,
+                        source: "status_log",
+                    };
+                }
             }
         }
         catch {
             // Fall through to return empty
         }
-        return [];
+        return {
+            files: [],
+            pagination: { page: 1, limit: 0, total: 0, totalPages: 0 },
+            widgetName,
+        };
+    }
+    /**
+     * Extract file list from persona's status_log.
+     * This is available when persona is fetched with get_minimal_persona=false.
+     *
+     * @param persona - The persona DTO with status_log
+     * @param widgetName - Widget name to extract files for (default: "fileUpload")
+     */
+    extractFilesFromStatusLog(persona, widgetName = "fileUpload") {
+        const statusLog = persona.status_log;
+        if (!statusLog) {
+            return [];
+        }
+        const files = statusLog[widgetName];
+        if (!Array.isArray(files)) {
+            return [];
+        }
+        return files
+            .filter((f) => typeof f === "object" && f !== null)
+            .map((f) => ({
+            id: f.id ?? f.filename ?? "",
+            filename: f.filename ?? f.id ?? "",
+            status: f.status ?? "unknown",
+            tags: Array.isArray(f.tags) ? f.tags : undefined,
+        }))
+            .filter((f) => f.id !== "");
+    }
+    /**
+     * Get data source aggregates (file counts by status).
+     */
+    async getDataSourceAggregates(personaId, widgetName = "fileUpload") {
+        try {
+            const resp = await this.connectRequest("/dataingest.v1.DataIngestService/GetContentNodeAggregates", {
+                widgetName: widgetName,
+                includeFiles: true,
+                groupId: personaId,
+                groupType: "FILE_PICKER_GROUP_TYPE_PERSONA",
+            }, personaId);
+            if (resp.ok) {
+                const data = await resp.json();
+                const agg = data.widgetAggregates?.find(w => w.widgetName === widgetName);
+                const counts = agg?.totalCounts ?? {};
+                return {
+                    total: (counts.pending ?? 0) + (counts.success ?? 0) + (counts.failed ?? 0),
+                    pending: counts.pending ?? 0,
+                    success: counts.success ?? 0,
+                    failed: counts.failed ?? 0,
+                    widgetName,
+                };
+            }
+        }
+        catch {
+            // Fall through
+        }
+        return { total: 0, pending: 0, success: 0, failed: 0, widgetName };
+    }
+    /**
+     * Normalize content node status from proto enum to readable string.
+     */
+    normalizeContentNodeStatus(status) {
+        if (!status)
+            return "unknown";
+        // Handle both enum name and human-readable formats
+        const statusMap = {
+            "CONTENT_NODE_STATUS_UNSPECIFIED": "unknown",
+            "CONTENT_NODE_STATUS_PENDING": "pending",
+            "CONTENT_NODE_STATUS_INDEXING": "indexing",
+            "CONTENT_NODE_STATUS_INDEXED": "indexed",
+            "CONTENT_NODE_STATUS_FAILED": "failed",
+            "CONTENT_NODE_STATUS_SUCCESS": "success",
+        };
+        return statusMap[status] ?? status.toLowerCase().replace("content_node_status_", "");
     }
     /**
      * Detect MIME type from filename extension.

package/dist/sdk/contracts.js

@@ -153,6 +153,7 @@ export const CreatePersonaRequestSchema = z.object({
     description: z.string().optional(),
     template_id: z.string().optional(),
     source_persona_id: z.string().optional(),
+    clone_data: z.boolean().optional(), // Clone knowledge base files when cloning from source_persona_id
     proto_config: z.record(z.unknown()).optional(),
     welcome_messages: WelcomeMessageSchema.optional(),
     trigger_type: z.string().optional(),

package/docs/mcp-tools-guide.md

@@ -28,24 +28,40 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`).
 
 ## Start-here flows (LLM-friendly)
 
-### Create a new AI Employee (recommended sequence)
+### Create a new AI Employee (greenfield)
 
 1. **Requirements**: `template(questions=true)` (and `template(questions=true, category="Voice")` for voice)
 2. **Pick agents/pattern**: `action(suggest="<use case>")`
 3. **Get the pattern**: `template(pattern="<pattern>")`
-4. **Generate configs**:
-   - `workflow(input="<requirements>", type="chat|voice|dashboard")`
-   - If you want deterministic local generation: add `use_autobuilder=false`
+4. **Generate workflow** (preview by default):
+   ```typescript
+   workflow(input="<requirements>", type="chat|voice|dashboard")
+   ```
 5. **Create persona** (if needed): `persona(mode="create", name="...", type="chat|voice|dashboard")`
-6. **Deploy**: `workflow(mode="deploy", persona_id="...", workflow_def=<...>, proto_config=<...>)`
+6. **Deploy** (preview=false):
+   ```typescript
+   workflow(input="<requirements>", persona_id="<id>", preview=false)
+   ```
 7. **Review**: `workflow(mode="analyze", persona_id="...")`
 
+### Extend an existing AI Employee (brownfield)
+
+**Combine multiple changes in one command!**
+
+```typescript
+// Preview changes (safe default)
+workflow(mode="extend", persona_id="abc-123", input="add caller_type categorizer, add HITL before email")
+
+// Deploy changes
+workflow(mode="extend", persona_id="abc-123", input="...", preview=false)
+```
+
 ### Review or debug an existing AI Employee
 
 1. Fetch full workflow: `persona(id="<id-or-exact-name>", include_workflow=true)`
 2. Analyze: `workflow(mode="analyze", persona_id="<persona_id>")`
-3. Preview fixes: `workflow(mode="optimize", persona_id="<persona_id>", preview=true)`
-4. Apply fixes: `workflow(mode="optimize", persona_id="<persona_id>")`
+3. Preview fixes: `workflow(mode="optimize", persona_id="<persona_id>")`
+4. Apply fixes: `workflow(mode="optimize", persona_id="<persona_id>", preview=false)`
 
 ### Upload / manage knowledge base documents
 
@@ -61,6 +77,28 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`).
 - List all synced in env: `sync(mode="status", list_synced=true, env="dev")`
 - Config: `sync(mode="config")`
 
+### Version / snapshot AI Employees
+
+Take snapshots before making changes, restore if something breaks.
+
+```typescript
+// Before a risky change - create a snapshot
+persona(id="My Bot", mode="version_create", message="Before adding HITL")
+
+// Make changes...
+workflow(mode="extend", persona_id="abc", input="add HITL before email", preview=false)
+
+// If something breaks - list versions and restore
+persona(id="My Bot", mode="version_list")
+persona(id="My Bot", mode="version_restore", version="v3")
+```
+
+**Auto-snapshot on deploy:**
+```typescript
+persona(id="My Bot", mode="version_policy", auto_on_deploy=true)
+// Now every deploy automatically creates a snapshot first
+```
+
 ### Demo data → RAG-ready Markdown → upload
 
 1. Get a template: `demo(mode="template", entity="customer")`
@@ -77,18 +115,55 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`).
 - **Update**: `persona(id="<id>", mode="update", name="...", description="...", enabled=true|false)`
 - **Compare**: `persona(id="<id>", mode="compare", compare_to="<id>", compare_env="dev")`
 - **Templates**: `persona(templates=true)`
+- **Version management**:
+  ```typescript
+  persona(id="abc", mode="version_create", message="Before major update")  // Create snapshot
+  persona(id="abc", mode="version_list")                                   // List all versions
+  persona(id="abc", mode="version_get", version="v3")                      // Get specific version
+  persona(id="abc", mode="version_compare", v1="v2", v2="v3")              // Compare versions
+  persona(id="abc", mode="version_restore", version="v2")                  // Restore to version
+  persona(id="abc", mode="version_policy", auto_on_deploy=true)            // Auto-snapshot settings
+  ```
 
 ### `workflow`
 
-- **Generate**: `workflow(input="<requirements>", type="chat|voice|dashboard")`
-- **Analyze**:
-  - By persona: `workflow(mode="analyze", persona_id="<id>")`
-  - By JSON: `workflow(mode="analyze", workflow_def={<...>})`
-  - Limit output: `workflow(mode="analyze", persona_id="<id>", include=["issues"|"connections"|"fixes"|"metrics"])`
-- **Deploy**: `workflow(mode="deploy", persona_id="<id>", workflow_def={<...>}, proto_config={<...>}, auto_fix=true)`
-- **Optimize** (analyze + fixes + deploy): `workflow(mode="optimize", persona_id="<id>", preview=true|false)`
-- **Compare**: `workflow(mode="compare", persona_id="<before>", compare_to="<after>")`
-- **Compile** (from explicit nodes): `workflow(mode="compile", name="...", description="...", type="chat|voice|dashboard", nodes=[...], result_mappings=[...])`
+All modification modes default to `preview=true` for safety. Use `preview=false` to deploy.
+
+- **Generate (greenfield)**: Create new workflow
+  ```typescript
+  workflow(input="IT helpdesk with KB search")                    // Preview
+  workflow(input="...", persona_id="abc", preview=false)          // Generate AND deploy
+  ```
+
+- **Extend (brownfield)**: Modify existing workflow with natural language
+  ```typescript
+  workflow(mode="extend", persona_id="abc", input="add caller_type categorizer")
+  workflow(mode="extend", persona_id="abc", input="add X, add Y, add Z")  // Multiple changes!
+  workflow(mode="extend", persona_id="abc", input="...", preview=false)   // Extend AND deploy
+  ```
+
+- **Optimize**: Fix issues in existing workflow
+  ```typescript
+  workflow(mode="optimize", persona_id="abc")                     // Preview fixes
+  workflow(mode="optimize", persona_id="abc", preview=false)      // Apply fixes
+  ```
+
+- **Analyze** (always read-only):
+  ```typescript
+  workflow(mode="analyze", persona_id="abc")
+  workflow(mode="analyze", workflow_def={...})
+  workflow(mode="analyze", persona_id="abc", include=["issues", "fixes"])
+  ```
+
+- **Compare** (always read-only):
+  ```typescript
+  workflow(mode="compare", persona_id="abc", compare_to="def")
+  ```
+
+- **Compile** (returns workflow_def from explicit node spec):
+  ```typescript
+  workflow(mode="compile", name="...", description="...", nodes=[...])
+  ```
 
 ### `action`
 
@@ -150,7 +225,49 @@ The `workflow(mode="optimize")` can automatically fix common issues:
 | External API call | ❌ No HITL | Request explicitly: "require human approval" |
 | Create/update records | ❌ No HITL | Request explicitly in prompt |
 
-To add HITL after deployment: `workflow(mode="extend", persona_id="...", description="add human approval before email")`
+To add HITL after deployment: `workflow(persona_id="...", input="add human approval before email")`
+
+
+## Brownfield Workflow Extension
+
+Extend existing workflows with new capabilities while preserving existing logic.
+
+### Usage
+
+```typescript
+// Add new nodes/intents
+workflow(persona_id="abc", input="add caller_type categorizer with Advisor and Client roles")
+
+// Add enum options to existing categorizer
+workflow(persona_id="abc", input="add Market Analysis intent to the categorizer")
+
+// Add custom wiring  
+workflow(persona_id="abc", input="add send_email node connected to entity_extractor output")
+
+// Merge a complete workflow_def (extend mode - preserves existing)
+workflow(persona_id="abc", workflow_def={...}, merge_mode="extend")
+
+// Replace with a new workflow (destructive)
+workflow(persona_id="abc", workflow_def={...}, merge_mode="replace", force=true)
+```
+
+### Merge Modes
+
+| Mode | Behavior |
+|------|----------|
+| `extend` (default) | Add new nodes, preserve existing, merge enums |
+| `replace` | Replace nodes not in incoming (destructive) |
+
+### Capabilities
+
+| Capability | Example |
+|------------|---------|
+| ✅ Add new nodes | `input="add password reset intent"` |
+| ✅ Add enum options | `input="add Advisor/Client to caller_type"` |
+| ✅ Add HITL gates | `input="add approval before sending emails"` |
+| ✅ Modify node wiring | `input="wire entity_extraction to email handler"` |
+| ✅ Preserve existing logic | Existing nodes/enums kept unless modified |
+
 
 ## Auto Builder Prompt Length Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",