@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/client.js

@@ -0,0 +1,788 @@
+export class EmaApiError extends Error {
+    statusCode;
+    body;
+    constructor(opts) {
+        super(opts.message);
+        this.statusCode = opts.statusCode;
+        this.body = opts.body;
+        this.name = "EmaApiError";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class EmaClient {
+    env;
+    timeoutMs;
+    tokenRefreshConfig;
+    refreshIntervalId;
+    isRefreshing = false;
+    constructor(env, opts) {
+        this.env = env;
+        this.timeoutMs = opts?.timeoutMs ?? 30_000;
+        this.tokenRefreshConfig = opts?.tokenRefresh;
+        // Start background refresh if configured
+        if (this.tokenRefreshConfig?.backgroundRefresh !== false && this.tokenRefreshConfig?.refreshCallback) {
+            this.startBackgroundRefresh();
+        }
+    }
+    /**
+     * Start background token refresh.
+     * Refreshes tokens proactively before expiration.
+     */
+    startBackgroundRefresh() {
+        if (this.refreshIntervalId)
+            return;
+        const intervalMs = this.tokenRefreshConfig?.refreshIntervalMs ?? 50 * 60 * 1000; // 50 minutes default
+        this.refreshIntervalId = setInterval(async () => {
+            await this.refreshToken();
+        }, intervalMs);
+        // Don't prevent process exit
+        if (this.refreshIntervalId.unref) {
+            this.refreshIntervalId.unref();
+        }
+    }
+    /**
+     * Stop background token refresh.
+     */
+    stopBackgroundRefresh() {
+        if (this.refreshIntervalId) {
+            clearInterval(this.refreshIntervalId);
+            this.refreshIntervalId = undefined;
+        }
+    }
+    /**
+     * Manually refresh the token.
+     * Returns true if refresh succeeded.
+     */
+    async refreshToken() {
+        if (!this.tokenRefreshConfig?.refreshCallback)
+            return false;
+        if (this.isRefreshing)
+            return false;
+        this.isRefreshing = true;
+        try {
+            const newToken = await this.tokenRefreshConfig.refreshCallback();
+            if (newToken) {
+                this.env = { ...this.env, bearerToken: newToken };
+                return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            this.isRefreshing = false;
+        }
+    }
+    /**
+     * Update the bearer token directly.
+     */
+    updateToken(newToken) {
+        this.env = { ...this.env, bearerToken: newToken };
+    }
+    /**
+     * Get the current environment (read-only).
+     */
+    getEnvironment() {
+        return this.env;
+    }
+    async requestWithRetries(method, path, opts) {
+        const retries = opts?.retries ?? 4;
+        const baseDelayMs = opts?.baseDelayMs ?? 500;
+        let hasAttemptedRefresh = false;
+        let lastErr;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+                const fullUrl = `${this.env.baseUrl.replace(/\/$/, "")}${path}`;
+                const response = await fetch(fullUrl, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.env.bearerToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: opts?.json !== undefined ? JSON.stringify(opts.json) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                // Handle 401 - attempt token refresh once
+                if (response.status === 401 && !hasAttemptedRefresh && this.tokenRefreshConfig?.refreshCallback) {
+                    hasAttemptedRefresh = true;
+                    const refreshed = await this.refreshToken();
+                    if (refreshed) {
+                        // Retry immediately with new token
+                        continue;
+                    }
+                }
+                // Retry on transient errors
+                if ([429, 500, 502, 503, 504].includes(response.status) && attempt < retries) {
+                    const delay = baseDelayMs * 2 ** attempt;
+                    await sleep(delay);
+                    continue;
+                }
+                return response;
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e : new Error(String(e));
+                if (attempt >= retries)
+                    throw lastErr;
+                const delay = baseDelayMs * 2 ** attempt;
+                await sleep(delay);
+            }
+        }
+        throw lastErr ?? new Error("Unreachable");
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // AI Employees (Personas)
+    // ─────────────────────────────────────────────────────────────────────────────
+    async getPersonasForTenant() {
+        // Try POST first (original API), fall back to GET if 405
+        let resp = await this.requestWithRetries("POST", "/api/personas/get_personas_for_tenant", {
+            json: {},
+        });
+        // If POST fails with 405, try GET method
+        if (resp.status === 405) {
+            resp = await this.requestWithRetries("GET", "/api/personas/get_personas_for_tenant", {});
+        }
+        if (!resp.ok) {
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body: await resp.text(),
+                message: `get_personas_for_tenant failed (${this.env.name})`,
+            });
+        }
+        const data = (await resp.json());
+        const personas = data.personas ?? data.configs ?? [];
+        return personas;
+    }
+    /** Alias: in the UI, personas are called "AI Employees" */
+    async getAiEmployeesForTenant() {
+        return this.getPersonasForTenant();
+    }
+    /**
+     * Get a single persona by ID with full details including workflow_def.
+     * Uses /api/personas/{id} endpoint which returns the complete persona including workflow_def.
+     */
+    async getPersonaById(personaId) {
+        // 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());
+            }
+        }
+        catch {
+            // Fall through to fallback
+        }
+        // Fallback: /api/ai_employee/get_ai_employee 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;
+            }
+        }
+        catch {
+            // Fall through to return null
+        }
+        return null;
+    }
+    /**
+     * Get workflow definition by workflow_id.
+     * Tries multiple API endpoints to fetch the workflow.
+     */
+    async getWorkflowDef(workflowId) {
+        // Try gRPC-web style GetWorkflow endpoint
+        try {
+            const resp = await this.requestWithRetries("POST", "/workflows.v1.WorkflowManager/GetWorkflow", {
+                json: { workflow_id: workflowId },
+            });
+            if (resp.ok) {
+                const data = (await resp.json());
+                return data.workflow ?? (Object.keys(data).length > 0 ? data : null);
+            }
+        }
+        catch {
+            // Fall through
+        }
+        // Try GetWorkflowDefinition endpoint (alternate name)
+        try {
+            const resp = await this.requestWithRetries("POST", "/workflows.v1.WorkflowManager/GetWorkflowDefinition", {
+                json: { workflow_id: workflowId },
+            });
+            if (resp.ok) {
+                const data = (await resp.json());
+                return data;
+            }
+        }
+        catch {
+            // Fall through
+        }
+        // Try listing actions and constructing workflow
+        try {
+            const actions = await this.listActionsFromWorkflow(workflowId);
+            if (actions && actions.length > 0) {
+                // Return actions as part of workflow def (partial reconstruction)
+                return { workflow_id: workflowId, actions: actions };
+            }
+        }
+        catch {
+            // Fall through
+        }
+        return null;
+    }
+    async updateAiEmployee(req, opts) {
+        // Use /api/personas/update_persona - same endpoint as Ema frontend
+        const resp = await this.requestWithRetries("POST", "/api/personas/update_persona", {
+            json: req,
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            // 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("; ")}`;
+                    }
+                }
+            }
+            catch {
+                // Body is not JSON, use as-is
+                errorDetail = body;
+            }
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body,
+                message: errorDetail
+                    ? `update_ai_employee failed (${this.env.name}): ${errorDetail}`
+                    : `update_ai_employee failed (${this.env.name}) - status ${resp.status}`,
+            });
+        }
+        return (await resp.json());
+    }
+    async createAiEmployee(req, opts) {
+        const resp = await this.requestWithRetries("POST", "/api/ai_employee/create_ai_employee", {
+            json: req,
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body,
+                message: `create_ai_employee failed (${this.env.name})`,
+            });
+        }
+        return (await resp.json());
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Data Source Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Upload a file to an AI Employee's knowledge base.
+     * API endpoint: POST /api/v2/upload/files (multipart/form-data)
+     */
+    async uploadDataSource(personaId, fileContent, filename, opts) {
+        const widgetName = opts?.widgetName ?? "fileUpload";
+        const tags = opts?.tags ?? widgetName;
+        const mimeType = opts?.mimeType ?? this.detectMimeType(filename);
+        // Build multipart form data manually
+        const boundary = `----EmaUploadBoundary${Date.now()}`;
+        const parts = [];
+        // persona_id field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="persona_id"\r\n\r\n${personaId}`);
+        // tags field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="tags"\r\n\r\n${tags}`);
+        // widget_name field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="widget_name"\r\n\r\n${widgetName}`);
+        // Encode file content parts separately to handle binary data
+        const textEncoder = new TextEncoder();
+        const headerPart = textEncoder.encode(parts.join("\r\n") + "\r\n" +
+            `--${boundary}\r\nContent-Disposition: form-data; name="files-0"; filename="${filename}"\r\nContent-Type: ${mimeType}\r\n\r\n`);
+        const filenamePart = textEncoder.encode(`\r\n--${boundary}\r\nContent-Disposition: form-data; name="files-0"\r\n\r\n${filename}`);
+        const pathPart = textEncoder.encode(`\r\n--${boundary}\r\nContent-Disposition: form-data; name="files-0-path"\r\n\r\n`);
+        const closingPart = textEncoder.encode(`\r\n--${boundary}--\r\n`);
+        // Combine all parts
+        const totalLength = headerPart.length + fileContent.length + filenamePart.length + pathPart.length + closingPart.length;
+        const body = new Uint8Array(totalLength);
+        let offset = 0;
+        body.set(headerPart, offset);
+        offset += headerPart.length;
+        body.set(fileContent, offset);
+        offset += fileContent.length;
+        body.set(filenamePart, offset);
+        offset += filenamePart.length;
+        body.set(pathPart, offset);
+        offset += pathPart.length;
+        body.set(closingPart, offset);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs * 2); // Longer timeout for uploads
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                    "X-Persona-Id": personaId,
+                },
+                body: body,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!resp.ok) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `uploadDataSource failed (${this.env.name})`,
+                });
+            }
+            const result = await resp.json();
+            return {
+                fileId: result.file_id ?? result.id ?? "",
+                status: result.status ?? "uploaded",
+                filename: filename,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Delete a data source file from an AI Employee's knowledge base.
+     * API endpoint: DELETE /api/v2/upload/files/{file_id} or via persona update
+     */
+    async deleteDataSource(personaId, fileId) {
+        // Try direct delete endpoint first
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        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,
+            });
+            clearTimeout(timeoutId);
+            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);
+        }
+    }
+    /**
+     * List data source files for an AI Employee.
+     * Uses the DataIngestService gRPC endpoint.
+     */
+    async listDataSourceFiles(personaId) {
+        // Try the content aggregates endpoint (may return limited info)
+        try {
+            const resp = await this.requestWithRetries("POST", "/dataingest.v1.DataIngestService/GetContentNodeAggregates", {
+                json: {
+                    widget_name: "fileUpload",
+                    include_files: true,
+                    persona_id: personaId,
+                },
+            });
+            if (resp.ok) {
+                const data = await resp.json();
+                return (data.files ?? []).map((f) => ({
+                    id: f.id,
+                    filename: f.name,
+                    status: f.status ?? "unknown",
+                }));
+            }
+        }
+        catch {
+            // Fall through to return empty
+        }
+        return [];
+    }
+    /**
+     * Detect MIME type from filename extension.
+     */
+    detectMimeType(filename) {
+        const ext = filename.toLowerCase().split(".").pop() ?? "";
+        const mimeTypes = {
+            pdf: "application/pdf",
+            doc: "application/msword",
+            docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            txt: "text/plain",
+            md: "text/markdown",
+            csv: "text/csv",
+            json: "application/json",
+            xml: "application/xml",
+            html: "text/html",
+            htm: "text/html",
+            xls: "application/vnd.ms-excel",
+            xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            ppt: "application/vnd.ms-powerpoint",
+            pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            svg: "image/svg+xml",
+        };
+        return mimeTypes[ext] ?? "application/octet-stream";
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Actions (displayed as "Agents" in the UI)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * List all actions available to the tenant.
+     * API endpoint: workflows.v1.ActionManager/ListActions
+     * UI label: "Agents"
+     */
+    async listActions() {
+        const resp = await this.requestWithRetries("POST", "/workflows.v1.ActionManager/ListActions", {
+            json: {},
+        });
+        if (!resp.ok) {
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body: await resp.text(),
+                message: `listActions failed (${this.env.name})`,
+            });
+        }
+        const data = (await resp.json());
+        return data.actions ?? [];
+    }
+    /** Alias: in the UI, actions are called "Agents" */
+    async listAgents() {
+        return this.listActions();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Persona Templates
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * List persona templates available to the current tenant.
+     * API endpoint: /api/personas/get_persona_templates
+     *
+     * Returns system templates (chatbot_starter, voicebot_ai_employee, etc.)
+     * that define pre-configured AI Employee configurations.
+     */
+    async getPersonaTemplates() {
+        // Try GET first (newer API), fall back to POST
+        let resp = await this.requestWithRetries("GET", "/api/personas/get_persona_templates", {});
+        if (resp.status === 405) {
+            // Fall back to POST
+            resp = await this.requestWithRetries("POST", "/api/personas/get_persona_templates", {
+                json: {},
+            });
+        }
+        if (!resp.ok) {
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body: await resp.text(),
+                message: `getPersonaTemplates failed (${this.env.name})`,
+            });
+        }
+        const data = (await resp.json());
+        return data.templates ?? [];
+    }
+    /**
+     * Get a specific persona template by ID.
+     *
+     * @param templateId - The template ID to fetch
+     */
+    async getPersonaTemplateById(templateId) {
+        const templates = await this.getPersonaTemplates();
+        return templates.find((t) => t.id === templateId) ?? null;
+    }
+    /**
+     * List actions associated with a specific workflow.
+     * API endpoint: workflows.v1.ActionManager/ListActionsFromWorkflow
+     * UI label: "Agents"
+     *
+     * @param workflowId - The workflow ID to list actions for
+     */
+    async listActionsFromWorkflow(workflowId) {
+        const resp = await this.requestWithRetries("POST", "/workflows.v1.ActionManager/ListActionsFromWorkflow", { json: { workflow_id: workflowId } });
+        if (!resp.ok) {
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body: await resp.text(),
+                message: `listActionsFromWorkflow failed (${this.env.name})`,
+            });
+        }
+        const data = (await resp.json());
+        return data.actions ?? [];
+    }
+    /** Alias: in the UI, actions are called "Agents" */
+    async listAgentsFromWorkflow(workflowId) {
+        return this.listActionsFromWorkflow(workflowId);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Sync Metadata (tagging synced personas)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Sync tag regex patterns.
+     * Current format: <!-- synced_from:env/id -->
+     * Legacy formats also supported for backward compatibility.
+     */
+    static SYNC_TAG_REGEX = /<!-- synced_from:([^/]+)\/([a-f0-9-]+) -->/;
+    static LEGACY_JSON_REGEX = /<!-- _ema_sync:(.+?) -->/;
+    /**
+     * Get sync metadata from a persona's description.
+     * Returns null if the persona has never been synced.
+     */
+    getSyncMetadata(persona) {
+        // Check top-level description for sync tag
+        const desc = persona.description;
+        if (desc) {
+            const meta = this.extractSyncMetadataFromString(desc);
+            if (meta)
+                return meta;
+        }
+        // Fallback: check proto_config._ema_sync (legacy)
+        const protoConfig = persona.proto_config;
+        if (protoConfig?._ema_sync) {
+            return protoConfig._ema_sync;
+        }
+        return null;
+    }
+    /**
+     * Extract sync metadata from a string (description field).
+     * Supports both new compact format and legacy JSON format.
+     */
+    extractSyncMetadataFromString(text) {
+        // Try new compact format: <!-- synced_from:env/id -->
+        const compactMatch = text.match(EmaClient.SYNC_TAG_REGEX);
+        if (compactMatch) {
+            return {
+                master_env: compactMatch[1],
+                master_id: compactMatch[2],
+                synced_at: new Date().toISOString(),
+            };
+        }
+        // Try legacy JSON format: <!-- _ema_sync:{...} -->
+        const legacyMatch = text.match(EmaClient.LEGACY_JSON_REGEX);
+        if (legacyMatch) {
+            try {
+                return JSON.parse(legacyMatch[1]);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a persona was synced from a master environment.
+     */
+    isSyncedPersona(persona) {
+        return this.getSyncMetadata(persona) !== null;
+    }
+    /**
+     * Regex to clean all sync tag formats from description.
+     */
+    static SYNC_CLEANUP_REGEX = /<!-- (?:synced_from|sync|_ema_sync):[^\n]*-->/g;
+    /**
+     * Extract the clean description (without sync marker).
+     */
+    getCleanDescription(description) {
+        if (!description)
+            return "";
+        return description.replace(EmaClient.SYNC_CLEANUP_REGEX, "").trim();
+    }
+    /**
+     * Build description with compact sync tag appended.
+     */
+    buildDescriptionWithSyncTag(cleanDescription, metadata) {
+        const marker = `<!-- synced_from:${metadata.master_env}/${metadata.master_id} -->`;
+        return cleanDescription ? `${cleanDescription}\n\n${marker}` : marker;
+    }
+    /**
+     * Tag a persona as synced by appending metadata to description.
+     */
+    async tagAsSynced(personaId, metadata, currentDescription, existingProtoConfig) {
+        const cleanDesc = this.getCleanDescription(currentDescription);
+        const newDescription = this.buildDescriptionWithSyncTag(cleanDesc, metadata);
+        await this.updateAiEmployee({
+            persona_id: personaId,
+            proto_config: existingProtoConfig ?? {},
+            description: newDescription,
+        });
+    }
+    /**
+     * Remove sync metadata from a persona (unlink from master).
+     */
+    async removeSyncTag(personaId, currentDescription, existingProtoConfig) {
+        const cleanDesc = this.getCleanDescription(currentDescription);
+        await this.updateAiEmployee({
+            persona_id: personaId,
+            proto_config: existingProtoConfig ?? {},
+            description: cleanDesc,
+        });
+    }
+    /**
+     * List all personas that have sync metadata (were synced from master).
+     */
+    async listSyncedPersonas() {
+        const personas = await this.getPersonasForTenant();
+        const synced = [];
+        for (const p of personas) {
+            const meta = this.getSyncMetadata(p);
+            if (meta) {
+                synced.push({ persona: p, syncMetadata: meta });
+            }
+        }
+        return synced;
+    }
+    /**
+     * Find a synced persona by its master environment and master ID.
+     */
+    async findSyncedPersona(masterEnv, masterId) {
+        const synced = await this.listSyncedPersonas();
+        return (synced.find((s) => s.syncMetadata.master_env === masterEnv && s.syncMetadata.master_id === masterId) ?? null);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Autobuilder Chat API
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Cache for discovered Autobuilder persona
+    autobuilderPersonaId = null;
+    // Cache for active conversation per target persona
+    autobuilderConversations = new Map();
+    /**
+     * Auto-discover the Autobuilder persona in the tenant.
+     * Looks for personas with template_id matching the Autobuilder template.
+     */
+    async findAutobuilderPersona() {
+        if (this.autobuilderPersonaId) {
+            return this.autobuilderPersonaId;
+        }
+        // Known Autobuilder template IDs
+        const AUTOBUILDER_TEMPLATE_IDS = [
+            "00000000-0000-0000-0000-000000000014", // Ema Auto Builder
+            "00000000-0000-0000-0000-00000000000a", // Autobuilder for X
+        ];
+        const allPersonas = await this.getPersonasForTenant();
+        // First, look for the main "Ema Auto Builder" by name and template
+        const mainAutobuilder = allPersonas.find(p => p.name === "Ema Auto Builder" &&
+            AUTOBUILDER_TEMPLATE_IDS.includes(p.template_id ?? ""));
+        if (mainAutobuilder) {
+            this.autobuilderPersonaId = mainAutobuilder.id;
+            return mainAutobuilder.id;
+        }
+        // Fallback: any persona with Autobuilder template
+        const anyAutobuilder = allPersonas.find(p => AUTOBUILDER_TEMPLATE_IDS.includes(p.template_id ?? ""));
+        if (anyAutobuilder) {
+            this.autobuilderPersonaId = anyAutobuilder.id;
+            return anyAutobuilder.id;
+        }
+        throw new EmaApiError({
+            statusCode: 404,
+            message: `No Autobuilder persona found in tenant (${this.env.name}). Please contact your Ema administrator.`,
+        });
+    }
+    /**
+     * Create a new conversation with the Autobuilder.
+     * API endpoint: POST /api/conversations/create?persona_id=<autobuilder_id>
+     */
+    async createAutobuilderConversation(autobuilderPersonaId) {
+        const resp = await this.requestWithRetries("POST", `/api/conversations/create?persona_id=${autobuilderPersonaId}`, {});
+        if (!resp.ok) {
+            const body = await resp.text();
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body,
+                message: `create_autobuilder_conversation failed (${this.env.name})`,
+            });
+        }
+        const result = await resp.json();
+        return { conversation_id: String(result.conversation_id ?? result.id ?? "") };
+    }
+    /**
+     * Send a message to the Autobuilder chat.
+     * API endpoint: POST /api/web/
+     *
+     * @param conversationId - The conversation ID from createAutobuilderConversation
+     * @param prompt - The message to send (e.g., "test", "add error handling", etc.)
+     * @param workflowDef - Optional workflow definition to iterate on
+     */
+    async chatWithAutobuilder(conversationId, prompt, workflowDef) {
+        const body = {
+            prompt,
+            conversation_id: conversationId,
+        };
+        if (workflowDef) {
+            body.workflow_def = workflowDef;
+        }
+        const resp = await this.requestWithRetries("POST", "/api/web/", { json: body });
+        if (!resp.ok) {
+            const errorBody = await resp.text();
+            throw new EmaApiError({
+                statusCode: resp.status,
+                body: errorBody,
+                message: `chat_with_autobuilder failed (${this.env.name})`,
+            });
+        }
+        const result = await resp.json();
+        return {
+            response: String(result.response ?? result.message ?? ""),
+            workflow_def: result.workflow_def,
+            conversation_id: conversationId,
+            raw: result,
+        };
+    }
+    /**
+     * High-level: Iterate on a persona's workflow using the Autobuilder.
+     * Abstracts away Autobuilder discovery and conversation management.
+     *
+     * @param personaId - The target AI Employee whose workflow to iterate on
+     * @param instruction - Natural language instruction (e.g., "add error handling", "optimize search")
+     * @param opts.newConversation - Force create a new conversation (default: reuse existing)
+     */
+    async iterateWorkflow(personaId, instruction, opts) {
+        // 1. Auto-discover Autobuilder
+        const autobuilderId = await this.findAutobuilderPersona();
+        // 2. Get or create conversation for this persona
+        let conversationId = this.autobuilderConversations.get(personaId);
+        if (!conversationId || opts?.newConversation) {
+            const conv = await this.createAutobuilderConversation(autobuilderId);
+            conversationId = conv.conversation_id;
+            this.autobuilderConversations.set(personaId, conversationId);
+        }
+        // 3. Fetch target persona's current workflow
+        const persona = await this.getPersonaById(personaId);
+        if (!persona) {
+            throw new EmaApiError({
+                statusCode: 404,
+                message: `AI Employee not found: ${personaId}`,
+            });
+        }
+        const workflowDef = persona.workflow_def;
+        // 4. Chat with Autobuilder
+        const response = await this.chatWithAutobuilder(conversationId, instruction, workflowDef);
+        return {
+            persona_id: personaId,
+            persona_name: persona.name ?? "Unknown",
+            autobuilder_id: autobuilderId,
+            conversation_id: conversationId,
+            instruction,
+            response: response.response,
+            updated_workflow: response.workflow_def,
+            has_changes: !!response.workflow_def,
+        };
+    }
+}