@ema.co/mcp-toolkit 2026.2.27-1 → 2026.2.27-2

package/dist/mcp/handlers/conversation/formatters.js

@@ -33,8 +33,8 @@ export function formatSendResponse(result) {
         response._next_step = `conversation(method="send", conversation_id="${result.conversationId}", buttons={selected_button:{label:"<button label>"}})`;
     }
     else if (msgType.includes("FORM")) {
-        response._tip = "The AI responded with a form. Fill it out using the form parameter, or cancel with is_cancelled=true.";
-        response._next_step = `conversation(method="send", conversation_id="${result.conversationId}", form={fields:[{name:"<field>", value:{stringValue:"<value>"}}]})`;
+        response._tip = "The AI responded with a form. Echo back the entire formMessage with values filled in using raw_message. The form param only works for cancellation.";
+        response._next_step = `conversation(method="send", conversation_id="${result.conversationId}", original_message_id="<bot_msg_id>", raw_message={type:"MESSAGE_TYPE_FORM", formMessage:{...formMessage from response with values filled...}, isUserMessage:true})`;
     }
     else {
         response._tip = "Check message for the AI's reply. Use method='history' to review the full thread.";

package/dist/mcp/handlers/conversation/send.js

@@ -77,7 +77,7 @@ export async function handleSend(args, client) {
             examples: [
                 'text="hello" - send a text message',
                 'buttons={selected_button:{label:"Yes",description:"Confirm"}} - select a button',
-                'form={fields:[{name:"email",value:{stringValue:"a@b.com"}}]} - submit a form',
+                'raw_message={type:"MESSAGE_TYPE_FORM", formMessage:{...}} - submit a form (echo back formMessage with values)',
                 'form={is_cancelled:true} - cancel a form',
             ],
         };

package/dist/mcp/handlers/persona/delete.js

@@ -4,8 +4,7 @@
  * Deletes a persona with safety confirmation.
  */
 import { resolvePersona, normalizeTriggerType } from "../utils.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 /**
  * Handle persona(mode="delete") - delete persona
  *
@@ -65,47 +64,27 @@ export async function handleDelete(args, client) {
             hint: "Use persona(method='delete', id='...', confirm=true) to proceed with deletion.",
         };
     }
-    // Strict guidance: snapshot before any destructive change (local, forced)
+    // Best-effort: snapshot before any destructive change (via central DIS storage)
     const force = args.force;
     const targetEnv = args.env ?? "unknown";
     if (fullPersona) {
         try {
-            const storage = createVersionStorage(process.cwd());
-            const engine = createVersionPolicyEngine(storage);
-            const snap = engine.forceCreateVersion(fullPersona, {
+            const { engine } = createCentralStorageEngine(client, fullPersona.id);
+            const snap = await engine.forceCreateVersion(fullPersona, {
                 environment: targetEnv,
                 tenant_id: targetEnv,
                 message: "Before delete",
                 created_by: "mcp-toolkit",
             });
-            if (!snap.created || !snap.version) {
-                if (!force) {
-                    return {
-                        error: "Failed to create pre-delete snapshot (required before delete)",
-                        persona_id: persona.id,
-                        details: snap.reason,
-                        hint: "Fix snapshotting (workspace storage) and retry deletion. Use force=true to bypass.",
-                    };
-                }
-                // force=true: proceed without snapshot (emergency only)
-            }
-            else {
+            if (snap.created && snap.version) {
                 deletionSummary.version_snapshot = {
                     id: snap.version.id,
                     version_name: snap.version.version_name,
                 };
             }
         }
-        catch (e) {
-            if (!force) {
-                return {
-                    error: "Failed to create pre-delete snapshot (required before delete)",
-                    persona_id: persona.id,
-                    details: e instanceof Error ? e.message : String(e),
-                    hint: "Fix snapshotting (workspace storage) and retry deletion. Use force=true to bypass.",
-                };
-            }
-            // force=true: proceed without snapshot (emergency only)
+        catch {
+            // Best-effort: snapshot failure does not block the delete
         }
     }
     // Perform deletion

package/dist/mcp/handlers/persona/update.js

@@ -16,8 +16,7 @@ import { PROJECT_TYPES } from "../../knowledge.js";
 import { resolvePersona, validateWidgetsForApi } from "../utils.js";
 import { validateSearchDataSourceConsistency, validationToHandlerResult } from "../workflow/validation.js";
 import { checkRemovedParams } from "../deprecation.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 import { fingerprintPersona } from "../../../sync.js";
 /**
  * Apply WorkflowSpec changes to an existing workflow_def.
@@ -234,41 +233,23 @@ export async function handleUpdate(args, client) {
             hint: "Re-run persona(method='get') / workflow(mode='get') to fetch the latest state, re-apply your changes, then update again. Use force=true only if you intend to overwrite out-of-band changes.",
         };
     }
-    // Strict guidance: snapshot before any update/change (local, forced)
+    // Best-effort: snapshot before any update/change (via central DIS storage)
     const targetEnv = args.env ?? "unknown";
     let versionSnapshot;
     try {
-        const storage = createVersionStorage(process.cwd());
-        const engine = createVersionPolicyEngine(storage);
-        const snap = engine.forceCreateVersion(fullPersona, {
+        const { engine } = createCentralStorageEngine(client, fullPersona.id);
+        const snap = await engine.forceCreateVersion(fullPersona, {
             environment: targetEnv,
             tenant_id: targetEnv,
             message: "Pre-update snapshot",
             created_by: "mcp-toolkit",
         });
-        if (!snap.created || !snap.version) {
-            if (!force) {
-                return {
-                    error: "Failed to create pre-update snapshot (required before update)",
-                    persona_id: persona.id,
-                    details: snap.reason,
-                    hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
-                };
-            }
-        }
-        else {
+        if (snap.created && snap.version) {
             versionSnapshot = { id: snap.version.id, version_name: snap.version.version_name };
         }
     }
-    catch (e) {
-        if (!force) {
-            return {
-                error: "Failed to create pre-update snapshot (required before update)",
-                persona_id: persona.id,
-                details: e instanceof Error ? e.message : String(e),
-                hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
-            };
-        }
+    catch {
+        // Best-effort: snapshot failure does not block the update
     }
     const existingProtoConfig = (fullPersona?.proto_config ?? persona.proto_config ?? {});
     const existingWorkflow = fullPersona

package/dist/mcp/handlers/persona/version.js

@@ -1,11 +1,11 @@
 /**
  * Version Management Handlers
  *
- * Provides local version tracking for personas (snapshot, history, restore).
- * Versions are stored in the local workspace, not on the Ema platform.
+ * Provides version tracking for personas (snapshot, history, restore).
+ * Uses IVersionStorage — can be local (.ema-versions/) or central (DIS).
  */
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine, migrateLocalToCentral } from "../../../sync/central-factory.js";
+import { VersionStorage } from "../../../sync/version-storage.js";
 /**
  * Check if a mode is a version management mode.
  */
@@ -32,20 +32,27 @@ export function isVersionMode(mode) {
  * @param versionContext - Workspace and environment context
  */
 export async function handleVersion(mode, args, client, persona, versionContext) {
-    const storage = createVersionStorage(versionContext.workspaceRoot);
-    const engine = createVersionPolicyEngine(storage);
+    const { storage, engine } = createCentralStorageEngine(client, persona.id);
     switch (mode) {
         // ─────────────────────────────────────────────────────────────────────────
         // snapshot / version_create - Create a new version snapshot
         // ─────────────────────────────────────────────────────────────────────────
         case "snapshot":
         case "version_create": {
+            // Lazy migration: seed central from local on first snapshot
+            try {
+                const localStorage = new VersionStorage(versionContext.workspaceRoot);
+                await migrateLocalToCentral(localStorage, storage, persona.id);
+            }
+            catch {
+                // Best-effort: migration failure should not block snapshot creation
+            }
             // Fetch full persona with workflow
             const fullPersona = await client.getPersonaById(persona.id);
             if (!fullPersona) {
                 return { error: `Could not fetch full persona: ${persona.id}` };
             }
-            const result = engine.forceCreateVersion(fullPersona, {
+            const result = await engine.forceCreateVersion(fullPersona, {
                 environment: versionContext.environment,
                 tenant_id: versionContext.tenant_id,
                 message: args.message,
@@ -73,7 +80,15 @@ export async function handleVersion(mode, args, client, persona, versionContext)
         // ─────────────────────────────────────────────────────────────────────────
         case "history":
         case "version_list": {
-            const versions = engine.listVersions(persona.id, {
+            // Lazy migration: seed central from local so history shows existing versions
+            try {
+                const localStorage = new VersionStorage(versionContext.workspaceRoot);
+                await migrateLocalToCentral(localStorage, storage, persona.id);
+            }
+            catch {
+                // Best-effort
+            }
+            const versions = await engine.listVersions(persona.id, {
                 limit: args.limit,
             });
             return {
@@ -88,7 +103,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
         // ─────────────────────────────────────────────────────────────────────────
         case "version_get": {
             const versionId = args.version ?? "latest";
-            const version = engine.getVersion(persona.id, versionId);
+            const version = await engine.getVersion(persona.id, versionId);
             if (!version) {
                 return { error: `Version not found: ${versionId}` };
             }
@@ -126,7 +141,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             if (!v1 || !v2) {
                 return { error: "v1 and v2 required for version_compare mode" };
             }
-            const result = engine.compareVersions(persona.id, v1, v2);
+            const result = await engine.compareVersions(persona.id, v1, v2);
             if (!result.success) {
                 return { error: result.error };
             }
@@ -152,14 +167,14 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             if (!versionId) {
                 return { error: "version required for restore mode" };
             }
-            const restoreData = engine.getRestoreData(persona.id, versionId);
+            const restoreData = await engine.getRestoreData(persona.id, versionId);
             if (!restoreData.success || !restoreData.restore_payload) {
                 return { error: restoreData.error ?? "Failed to get restore data" };
             }
             // Create a version snapshot before restoring (audit trail)
             const fullPersona = await client.getPersonaById(persona.id);
             if (fullPersona) {
-                engine.forceCreateVersion(fullPersona, {
+                await engine.forceCreateVersion(fullPersona, {
                     environment: versionContext.environment,
                     tenant_id: versionContext.tenant_id,
                     message: `Before restore to ${restoreData.version?.version_name}`,
@@ -180,7 +195,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             // Create post-restore version
             const restoredPersona = await client.getPersonaById(persona.id);
             if (restoredPersona) {
-                engine.forceCreateVersion(restoredPersona, {
+                await engine.forceCreateVersion(restoredPersona, {
                     environment: versionContext.environment,
                     tenant_id: versionContext.tenant_id,
                     message: `Restored to ${restoreData.version?.version_name}`,
@@ -207,7 +222,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
                 args.auto_on_sync !== undefined ||
                 args.max_versions !== undefined;
             if (hasUpdates) {
-                const updated = engine.updatePolicy(persona.id, {
+                const updated = await engine.updatePolicy(persona.id, {
                     auto_version_on_deploy: args.auto_on_deploy,
                     auto_version_on_sync: args.auto_on_sync,
                     max_versions: args.max_versions,
@@ -221,7 +236,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
                 };
             }
             // Just get current policy
-            const policy = engine.getPolicy(persona.id);
+            const policy = await engine.getPolicy(persona.id);
             return {
                 persona_id: persona.id,
                 persona_name: persona.name,

package/dist/mcp/handlers/workflow/adapter.js

@@ -7,8 +7,7 @@
  * Extracted from server.ts to keep the dispatch table thin.
  */
 import { fingerprintPersona } from "../../../sync.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 import { handleWorkflow } from "./index.js";
 import { handleWorkflowOptimize } from "./optimize.js";
 export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName) {
@@ -84,60 +83,45 @@ export async function handleWorkflowAdapter(args, createClient, getDefaultEnvNam
                 return { error: 'persona_id is required for workflow(mode="deploy")' };
             }
             const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
+            // Fetch persona and validate fingerprint (blocking — these are safety checks)
+            const personaBefore = await client.getPersonaById(personaId);
+            if (!personaBefore) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            const currentFp = fingerprintPersona(personaBefore);
+            if (!force && !baseFingerprint) {
+                return {
+                    error: "base_fingerprint is required for workflow deploy (stale-state protection)",
+                    persona_id: personaId,
+                    current_fingerprint: currentFp,
+                    hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
+                };
+            }
+            if (!force && baseFingerprint && baseFingerprint !== currentFp) {
+                return {
+                    error: "Persona changed since you last fetched it (fingerprint mismatch)",
+                    persona_id: personaId,
+                    base_fingerprint: baseFingerprint,
+                    current_fingerprint: currentFp,
+                    hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
+                };
+            }
+            // Best-effort: snapshot before any destructive change (via central DIS storage)
             let versionCreated;
             try {
-                const personaBefore = await client.getPersonaById(personaId);
-                if (!personaBefore) {
-                    return { error: `Persona not found: ${personaId}` };
-                }
-                const currentFp = fingerprintPersona(personaBefore);
-                if (!force && !baseFingerprint) {
-                    return {
-                        error: "base_fingerprint is required for workflow deploy (stale-state protection)",
-                        persona_id: personaId,
-                        current_fingerprint: currentFp,
-                        hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
-                    };
-                }
-                if (!force && baseFingerprint && baseFingerprint !== currentFp) {
-                    return {
-                        error: "Persona changed since you last fetched it (fingerprint mismatch)",
-                        persona_id: personaId,
-                        base_fingerprint: baseFingerprint,
-                        current_fingerprint: currentFp,
-                        hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
-                    };
-                }
-                const storage = createVersionStorage(process.cwd());
-                const engine = createVersionPolicyEngine(storage);
-                const snap = engine.forceCreateVersion(personaBefore, {
+                const { engine } = createCentralStorageEngine(client, personaId);
+                const snap = await engine.forceCreateVersion(personaBefore, {
                     environment: targetEnv,
                     tenant_id: targetEnv,
                     message: "Pre-deploy snapshot",
                     created_by: "mcp-toolkit",
                 });
-                if (!snap.created || !snap.version) {
-                    if (!force) {
-                        return {
-                            error: "Failed to create pre-deploy snapshot (required before deploy)",
-                            persona_id: personaId,
-                            details: snap.reason,
-                            hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
-                        };
-                    }
-                }
-                else {
+                if (snap.created && snap.version) {
                     versionCreated = { id: snap.version.id, version_name: snap.version.version_name };
                 }
             }
-            catch (snapshotErr) {
-                if (!force) {
-                    return {
-                        error: "Failed to create pre-deploy snapshot (required before deploy)",
-                        persona_id: personaId,
-                        hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
-                    };
-                }
+            catch {
+                // Best-effort: snapshot failure does not block the deploy
             }
             const deployResult = await handleWorkflow({
                 mode: "deploy",

package/dist/mcp/handlers/workflow/validation.js

@@ -222,7 +222,7 @@ export function getSearchNodeWidgetNames(workflowDef) {
         const elements = dc?.multiBinding?.elements ?? [];
         for (const el of elements) {
             const name = el.widgetConfig?.widgetName;
-            if (typeof name === "string" && name.trim().length > 0) {
+            if (typeof name === "string" && name.trim().length > 0 && !name.startsWith("_")) {
                 widgetNames.add(name.trim());
             }
         }

package/dist/mcp/tools.js

@@ -53,7 +53,7 @@ export function generateTools(envNames, defaultEnv) {
 **IMPORTANT (strict)**:
 - Always fetch latest state immediately before changing: \`persona(method="get", id="abc", include_fingerprint=true)\`
 - Pass \`base_fingerprint\` to update to prevent overwriting out-of-band changes
-- The toolkit snapshots the persona locally before applying updates
+- The toolkit automatically snapshots the persona before applying updates
 
 **For workflow changes**: Use the workflow tool:
 1. \`workflow(mode="get", persona_id="abc")\` - get current workflow_def
@@ -830,8 +830,35 @@ When the bot responds with a continuation (form, buttons, or text prompt), respo
 
 - **Text**: \`conversation(method="send", conversation_id="...", text="user reply")\`
 - **Buttons**: \`conversation(method="send", conversation_id="...", buttons={selected_button:{label:"Yes", description:"Confirm"}})\`
-- **Form submit**: \`conversation(method="send", conversation_id="...", form={fields:[{name:"email", value:{stringValue:"a@b.com"}}]})\`
 - **Form cancel**: \`conversation(method="send", conversation_id="...", form={is_cancelled:true})\`
+- **Form submit**: Use \`raw_message\` — the simplified \`form\` param does NOT work for form submissions because the backend expects the full form structure echoed back.
+
+### Form HITL (CRITICAL — use raw_message)
+Forms require echoing back the **entire formMessage** from the bot's response with your values filled in:
+
+\`\`\`
+conversation(method="send", conversation_id="...", original_message_id="<id from bot message>", raw_message={
+  type: "MESSAGE_TYPE_FORM",
+  formMessage: { ...entire formMessage from bot response with field values filled in... },
+  isUserMessage: true
+})
+\`\`\`
+
+**Field value patterns by wellKnown type (from WellKnownValue proto):**
+- **String** (\`WELL_KNOWN_TYPE_STRING\`): \`value: {wellKnown: {stringValue: "text"}}\`
+- **Int** (\`WELL_KNOWN_TYPE_INT\`): \`value: {wellKnown: {int64Value: "42"}}\` (string-encoded integer)
+- **Float** (\`WELL_KNOWN_TYPE_FLOAT\`): \`value: {wellKnown: {doubleValue: 3.14}}\`
+- **Boolean** (\`WELL_KNOWN_TYPE_BOOL\`): \`value: {wellKnown: {boolValue: true}}\`
+- **Date** (\`WELL_KNOWN_TYPE_DATE\`): \`value: {wellKnown: {dateValue: {year: 2026, month: 3, day: 2}}}\`
+- **DateTime** (\`WELL_KNOWN_TYPE_DATETIME\`): \`value: {wellKnown: {datetimeValue: {utcTime: "2026-03-02T09:00:00Z"}}}\`
+
+**Dropdown fields:** Check \`inputValidation.validValues\` to determine format:
+- Struct options \`{wellKnown: {structValue: {Name:"Engineering", Id:"E"}}}\` → use the **Id** as stringValue: \`value: {wellKnown: {stringValue: "E"}}\`
+- Enum options \`{enumValue: "Sick Leave"}\` → use the enum value as stringValue: \`value: {wellKnown: {stringValue: "Sick Leave"}}\`
+
+**Intermediate forms**: If the response has \`isIntermediate: true\`, the bot will return another form with more fields after you submit. Previously filled fields will have \`editDisabled: true\`. The final form (no \`isIntermediate\`) submits all fields at once.
+
+**Async responses**: Some workflows (e.g. agentic search) run long tasks after HITL exits. If \`send\` times out, poll with \`conversation(method="history")\` until the response appears with \`processing_status: "completed"\`.
 
 ## History
 - \`conversation(method="history", conversation_id="...")\` - get all messages in the conversation
@@ -850,7 +877,7 @@ When the bot responds with a continuation (form, buttons, or text prompt), respo
 - \`conversation(method="delete", conversation_id="...", confirm=true)\` - delete a conversation
 
 ## Raw Message
-- \`conversation(method="send", conversation_id="...", raw_message={type:"MESSAGE_TYPE_TEXT", ...})\` - send a pre-built ChatbotMessage dict`,
+- \`conversation(method="send", conversation_id="...", raw_message={...})\` - send a pre-built ChatbotMessage dict. **Required for form HITL submissions.**`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -888,7 +915,7 @@ When the bot responds with a continuation (form, buttons, or text prompt), respo
                     },
                     form: {
                         type: "object",
-                        description: "Form data for HITL continuation (for method=send). Include fields with values, or set is_cancelled=true to cancel.",
+                        description: "Form HITL cancellation only (for method=send). Set is_cancelled=true to cancel a form. For form SUBMISSIONS, use raw_message instead — the backend requires the full formMessage echoed back.",
                         properties: {
                             fields: {
                                 type: "array",
@@ -914,7 +941,7 @@ When the bot responds with a continuation (form, buttons, or text prompt), respo
                     },
                     raw_message: {
                         type: "object",
-                        description: "Pre-built ChatbotMessage dict (for method=send). Use when convenience params (text/buttons/form) are insufficient.",
+                        description: "Pre-built ChatbotMessage dict (for method=send). REQUIRED for form HITL submissions — echo back the full formMessage from the bot's response with values filled in. Use correct wellKnown value types: stringValue (strings), int64Value (ints, string-encoded), doubleValue (floats), boolValue (bools), dateValue {year,month,day} (dates), datetimeValue {utcTime} (datetimes). For struct dropdowns use the Id as stringValue; for enum dropdowns use the enumValue as stringValue.",
                     },
                     original_message_id: {
                         type: "string",

package/dist/sdk/client-adapter.js

@@ -345,8 +345,15 @@ export class EmaClientAdapter {
     /**
      * Delete a data source file
      */
-    async deleteDataSource(personaId, fileId) {
-        return this.client.deleteDataSource(personaId, fileId);
+    async deleteDataSource(personaId, fileId, opts) {
+        return this.client.deleteDataSource(personaId, fileId, opts);
+    }
+    /**
+     * Download a file's content by UploadedFile.Id.
+     * Uses GetSignedUrl gRPC → HTTP fetch.
+     */
+    async downloadFile(fileId, personaId) {
+        return this.client.downloadFile(fileId, personaId);
     }
     /**
      * List data source files

package/dist/sdk/ema-client.js

@@ -406,6 +406,50 @@ export class EmaClientV2 {
     async getDataSourceAggregates(personaId, widgetName) {
         return this.grpcClient.getContentNodeAggregates(personaId, widgetName);
     }
+    /**
+     * Download a file's content by its UploadedFile.Id.
+     * Uses GetSignedUrl gRPC → HTTP fetch on the signed URL.
+     *
+     * @param fileId - The UploadedFile.Id (from ContentNodeResponse.id)
+     * @returns Raw file content as Buffer
+     * @throws If file is deleted or signed URL fetch fails
+     */
+    async downloadFile(fileId, personaId) {
+        const signedUrlResponse = await this.grpcClient.getSignedUrl(fileId, personaId);
+        if (signedUrlResponse.isDeleted) {
+            throw new EmaApiError({
+                statusCode: 410,
+                body: `File ${fileId} has been deleted`,
+                message: `downloadFile: file is deleted (${this.env.name})`,
+            });
+        }
+        if (!signedUrlResponse.signedUrl) {
+            throw new EmaApiError({
+                statusCode: 404,
+                body: `No signed URL returned for file ${fileId}`,
+                message: `downloadFile: no signed URL (${this.env.name})`,
+            });
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(signedUrlResponse.signedUrl, {
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: await resp.text(),
+                    message: `downloadFile: fetch failed (${this.env.name})`,
+                });
+            }
+            const arrayBuffer = await resp.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     /**
      * Replicate data between personas
      */
@@ -720,34 +764,16 @@ export class EmaClientV2 {
         }
     }
     /**
-     * Delete a data source file from an AI Employee's knowledge base.
-     * API endpoint: DELETE /api/v2/upload/files/{file_id}
+     * Delete data source file(s) from an AI Employee's knowledge base.
+     * Uses gRPC DeleteFilesForGroup — the ONLY deletion method DIS exposes.
+     *
+     * @param personaId - The persona owning the files
+     * @param fileId - Single file ID to delete
+     * @param opts - Optional widget name scope
      */
-    async deleteDataSource(personaId, fileId) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 30_000);
-        try {
-            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files/${fileId}?persona_id=${personaId}`, {
-                method: "DELETE",
-                headers: {
-                    Authorization: `Bearer ${this.env.bearerToken}`,
-                    "X-Persona-Id": personaId,
-                },
-                signal: controller.signal,
-            });
-            if (!resp.ok && resp.status !== 404) {
-                const errorBody = await resp.text();
-                throw new EmaApiError({
-                    statusCode: resp.status,
-                    body: errorBody,
-                    message: `deleteDataSource failed (${this.env.name})`,
-                });
-            }
-            return { success: true, fileId };
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+    async deleteDataSource(personaId, fileId, opts) {
+        await this.grpcClient.deleteFilesForGroup(personaId, [fileId], opts?.widgetName);
+        return { success: true, fileId };
     }
     /**
      * Delete a persona