@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

package/dist/cli/index.js

@@ -11,7 +11,7 @@
  *   config validate       - Validate config file
  */
 import { loadConfig } from "../sdk/config.js";
-import { EmaClient } from "../sdk/client.js";
+import { EmaClientAdapter } from "../sdk/client-adapter.js";
 import { SyncSDK } from "../sync/sdk.js";
 function printUsage() {
     console.log(`
@@ -220,7 +220,7 @@ async function runAgentsCommand(subcommand, args, options) {
         baseUrl: master.baseUrl,
         bearerToken: getEnvOrThrow(master.bearerTokenEnv),
     };
-    const client = new EmaClient(env);
+    const client = new EmaClientAdapter(env);
     switch (subcommand) {
         case "list": {
             const actions = await client.listAgents();

package/dist/mcp/domain/loop-detection.js

@@ -1,31 +1,18 @@
 /**
  * Loop Detection for Workflow Graphs
  *
- * Extracted from workflow-execution-analyzer.ts — only the parts
- * used by live validation code (detectLoops + LoopInfo).
+ * Uses the shared WorkflowGraph representation from workflow-graph.ts
+ * for cycle and re-entry detection in workflow validation.
  */
-import { parseWorkflowDef } from "../knowledge.js";
-function buildGraphMaps(nodes) {
-    const forward = new Map();
-    const nodeMap = new Map();
-    for (const node of nodes) {
-        nodeMap.set(node.id, node);
-        forward.set(node.id, new Set());
-    }
-    for (const node of nodes) {
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                const sourceId = edge.source_node_id;
-                forward.get(sourceId)?.add(node.id);
-            }
-        }
-    }
-    return { forward, nodeMap };
-}
+import { buildWorkflowGraph } from "./workflow-graph.js";
 export function detectLoops(workflowDef) {
-    const nodes = parseWorkflowDef(workflowDef);
+    if (!workflowDef || typeof workflowDef !== "object")
+        return [];
+    const graph = buildWorkflowGraph(workflowDef);
+    if (graph.nodes.size === 0)
+        return [];
     const loops = [];
-    const { forward, nodeMap } = buildGraphMaps(nodes);
+    const { forward } = graph;
     const visited = new Set();
     const recursionStack = new Set();
     const path = [];
@@ -33,7 +20,7 @@ export function detectLoops(workflowDef) {
         visited.add(nodeId);
         recursionStack.add(nodeId);
         path.push(nodeId);
-        for (const neighbor of (forward.get(nodeId) || [])) {
+        for (const neighbor of (forward.get(nodeId) ?? [])) {
             if (!visited.has(neighbor)) {
                 if (dfs(neighbor))
                     return true;
@@ -56,42 +43,47 @@ export function detectLoops(workflowDef) {
         recursionStack.delete(nodeId);
         return false;
     }
-    const trigger = nodes.find(n => n.action_name === 'trigger' || n.id === 'trigger');
-    if (trigger)
-        dfs(trigger.id);
-    for (const node of nodes) {
-        if (!visited.has(node.id))
-            dfs(node.id);
+    if (graph.trigger)
+        dfs(graph.trigger);
+    for (const nodeId of graph.nodes.keys()) {
+        if (!visited.has(nodeId))
+            dfs(nodeId);
     }
     // Detect categorizer routing back to upstream (re-entry)
-    for (const node of nodes) {
-        if (node.action_name === 'chat_categorizer') {
-            const downstream = forward.get(node.id) || new Set();
-            const upstream = new Set();
-            function findUpstream(nId, depth = 0) {
-                if (depth > 20)
-                    return;
-                const nodeInfo = nodeMap.get(nId);
-                if (!nodeInfo?.incoming_edges)
-                    return;
-                for (const edge of nodeInfo.incoming_edges) {
-                    upstream.add(edge.source_node_id);
-                    findUpstream(edge.source_node_id, depth + 1);
+    detectReentryLoops(graph, loops);
+    return loops;
+}
+/**
+ * Detect categorizer nodes routing back to upstream nodes (re-entry risk).
+ * Uses the graph's reverse adjacency map instead of manual edge traversal.
+ */
+function detectReentryLoops(graph, loops) {
+    for (const [nodeId, graphNode] of graph.nodes) {
+        if (graphNode.actionType !== 'chat_categorizer')
+            continue;
+        const downstream = graph.forward.get(nodeId) ?? new Set();
+        const upstream = new Set();
+        function collectUpstream(nId, depth = 0) {
+            if (depth > 20)
+                return;
+            for (const parent of (graph.reverse.get(nId) ?? [])) {
+                if (!upstream.has(parent)) {
+                    upstream.add(parent);
+                    collectUpstream(parent, depth + 1);
                 }
             }
-            findUpstream(node.id);
-            for (const downNode of downstream) {
-                if (upstream.has(downNode)) {
-                    loops.push({
-                        type: 'reentry_loop',
-                        nodes: [node.id, downNode],
-                        description: `Categorizer "${node.display_name || node.id}" routes to "${downNode}" which is upstream - can cause re-processing`,
-                        severity: 'warning',
-                        fixSuggestion: `Add state tracking or one-time-execution gate to prevent re-processing.`,
-                    });
-                }
+        }
+        collectUpstream(nodeId);
+        for (const downNode of downstream) {
+            if (upstream.has(downNode)) {
+                loops.push({
+                    type: 'reentry_loop',
+                    nodes: [nodeId, downNode],
+                    description: `Categorizer "${graphNode.displayName || nodeId}" routes to "${downNode}" which is upstream - can cause re-processing`,
+                    severity: 'warning',
+                    fixSuggestion: `Add state tracking or one-time-execution gate to prevent re-processing.`,
+                });
             }
         }
     }
-    return loops;
 }

package/dist/mcp/domain/sanitizer.js

@@ -896,7 +896,7 @@ export function applySessionMappings(text, session) {
  * Content fields that SHOULD be sanitized (allowlist approach).
  * Only these fields contain user-facing content that may have PII.
  *
- * TODO: Generate this from OpenAPI spec or gRPC definitions
+ * Manually maintained — candidate for auto-generation from OpenAPI/gRPC definitions.
  */
 const CONTENT_FIELDS = new Set([
     // Persona-level

package/dist/mcp/domain/workflow-graph.js

@@ -4,8 +4,8 @@
  * Single source of truth for parsing workflow_def JSON into a typed graph.
  * Used by the workflow optimizer for static analysis.
  *
- * NOTE: `loop-detection.ts` has its own `buildGraphMaps()` for validation
- * (cycle/re-entry detection). Future work: consolidate both into this module.
+ * `loop-detection.ts` uses `buildWorkflowGraph()` from this module for
+ * cycle and re-entry detection (consolidated from a prior local `buildGraphMaps`).
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants

package/dist/mcp/domain/workflow-path-enumerator.js

@@ -50,7 +50,7 @@ export function enumeratePaths(workflow, options) {
                 throw new Error("Branch outcome without branch_point");
             }
             for (const value of result.branch_point.possible_values) {
-                const forkedSession = forkSessionForBranching(session, result.branch_point, value);
+                const forkedSession = forkSessionForBranching(session, result.branch_point, value, workflow);
                 sessionsToProcess.push(forkedSession);
             }
         }
@@ -80,7 +80,7 @@ function createInitialSession(workflow) {
         action_states: new Map(),
     };
 }
-function forkSessionForBranching(session, branchInfo, chosenValue) {
+function forkSessionForBranching(session, branchInfo, chosenValue, workflow) {
     // Deep copy session
     const forked = {
         completed_actions: [...session.completed_actions],
@@ -102,8 +102,11 @@ function forkSessionForBranching(session, branchInfo, chosenValue) {
         node_id: branchInfo.action_that_branched,
         output_name: branchInfo.branching_output_name,
     });
-    // TODO: Generate dummy outputs for other outputs of branching action
-    // TODO: Generate dummy outputs for non-branching actions
+    // Add remaining outputs from the branching action (e.g. categorizer also produces confidence)
+    const branchingNode = workflow.nodes?.find(n => n.id === branchInfo.action_that_branched);
+    if (branchingNode) {
+        addActionOutputs(forked, branchingNode);
+    }
     return forked;
 }
 // ─────────────────────────────────────────────────────────────────────────────

package/dist/mcp/guidance.js

@@ -366,6 +366,51 @@ export const TOOL_GUIDANCE = {
         ],
         applicableRules: [],
     },
+    debug: {
+        toolName: "debug",
+        quickTip: "Inspect workflow executions and audit conversations. Follow the drill-down: conversations → detail → show_work → action_detail.",
+        operations: [
+            {
+                name: "List conversations",
+                description: "List audit conversations for a persona",
+                example: 'debug(method="conversations", persona_id="abc")',
+            },
+            {
+                name: "Conversation detail",
+                description: "Get messages with workflow_run_ids",
+                example: 'debug(method="conversation_detail", conversation_id="...")',
+            },
+            {
+                name: "Show work",
+                description: "See all actions' execution traces for a workflow run",
+                example: 'debug(method="show_work", persona_id="abc", workflow_run_id="...")',
+            },
+            {
+                name: "Action detail",
+                description: "Deep trace: inputs, outputs, LLM calls, steps",
+                example: 'debug(method="action_detail", persona_id="abc", workflow_run_id="...", action_name="...")',
+            },
+            {
+                name: "Search messages",
+                description: "Full-text search across conversation messages",
+                example: 'debug(method="search", persona_id="abc", query="pricing")',
+            },
+        ],
+        nextSteps: {
+            conversations: "Pick a conversation_id → debug(method='conversation_detail')",
+            conversation_detail: "Pick a workflow_run_id → debug(method='show_work', persona_id='...', workflow_run_id='...')",
+            show_work: "Pick an action_name (especially ERRORED ones) → debug(method='action_detail', persona_id='...', ...)",
+            action_detail: "Examine inputs/outputs/llm_calls to find the root cause",
+            search: "Pick a conversation_id from results → debug(method='conversation_detail')",
+        },
+        commonMistakes: [
+            "Jumping to action_detail without running show_work first (you need the action_name)",
+            "Forgetting persona_id — required for conversations, show_work, action_detail, and search",
+            "Not following _next_step hints in responses",
+            "The search method depends on DebuggerService which may not be deployed in all environments",
+        ],
+        applicableRules: [],
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Contextual Tips (for tool responses)
@@ -434,8 +479,16 @@ All workflow modifications follow a 3-step flow:
 
 The LLM generates the full workflow_def. MCP provides data and executes.
 
+## Debugging Workflow Executions
+Use the \`debug\` tool to inspect workflow runs and troubleshoot issues:
+1. \`debug(method="conversations", persona_id="...")\` → list audit conversations
+2. \`debug(method="show_work", workflow_run_id="...")\` → see action execution traces
+3. \`debug(method="action_detail", ...)\` → deep trace with LLM calls, inputs/outputs
+Also available as persona sub-resource: \`persona(id="abc", debug={method:"conversations"})\`
+
 ## Resources
 - \`ema://docs/usage-guide\` - Complete guide
+- \`ema://docs/debugging-guide\` - Debugging workflow executions
 - \`ema://catalog/agents-summary\` - Action catalog
 - \`ema://rules/anti-patterns\` - Common mistakes
 

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

@@ -0,0 +1,15 @@
+/**
+ * Debug Adapter
+ *
+ * Thin adapter that resolves client from env and delegates to handleDebug.
+ * Same pattern as workflow/adapter.ts.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { handleDebug } from "./index.js";
+export async function handleDebugAdapter(args, createClient, getDefaultEnvName) {
+    const targetEnv = args.env ?? getDefaultEnvName();
+    // createClient() returns EmaClientAdapter at runtime (see env/config.ts)
+    const client = createClient(targetEnv);
+    return handleDebug(args, client);
+}

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

@@ -0,0 +1,282 @@
+/**
+ * Debug Handler Formatters
+ *
+ * Transforms raw proto→JSON debug responses into concise, actionable summaries.
+ * Applies value truncation for large strings and adds _next_step hints
+ * to guide the agent through the drill-down flow.
+ */
+const MAX_VALUE_LENGTH = 2000;
+/** Action run status enum values from ShowWorkLog.ActionRunStatus */
+const STATUS_LABELS = {
+    0: "UNSPECIFIED",
+    1: "SUCCESS",
+    2: "ERRORED",
+    3: "WARNING",
+    4: "NOT_RUN",
+    5: "PAUSED",
+    ACTION_RUN_STATUS_UNSPECIFIED: "UNSPECIFIED",
+    ACTION_RUN_STATUS_SUCCESS: "SUCCESS",
+    ACTION_RUN_STATUS_ERRORED: "ERRORED",
+    ACTION_RUN_STATUS_WARNING: "WARNING",
+    ACTION_RUN_STATUS_NOT_RUN: "NOT_RUN",
+    ACTION_RUN_STATUS_PAUSED: "PAUSED",
+};
+function truncateValue(value) {
+    if (typeof value === "string" && value.length > MAX_VALUE_LENGTH) {
+        return value.slice(0, MAX_VALUE_LENGTH) + `... [truncated, ${value.length} total chars]`;
+    }
+    if (Array.isArray(value)) {
+        return value.map(truncateValue);
+    }
+    if (value !== null && typeof value === "object") {
+        return truncateObject(value);
+    }
+    return value;
+}
+function truncateObject(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        result[k] = truncateValue(v);
+    }
+    return result;
+}
+function resolveStatus(raw) {
+    if (typeof raw === "number" || typeof raw === "string") {
+        return STATUS_LABELS[raw] ?? String(raw);
+    }
+    return "UNKNOWN";
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// conversations
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatConversations(data, personaId) {
+    // toJson() serializes the response field as "items" (proto field name)
+    const reviews = data.items ?? data.conversationReviews ?? data.conversation_reviews;
+    const items = Array.isArray(reviews) ? reviews : [];
+    return {
+        persona_id: personaId,
+        total: items.length,
+        conversations: items.map((c) => ({
+            conversation_id: c.conversationId ?? c.conversation_id,
+            channel: c.channel,
+            resolution_status: c.resolutionStatus ?? c.resolution_status,
+            user_rating: c.userRating ?? c.user_rating,
+            message_count: c.messageCount ?? c.message_count,
+            created_at: c.createdAt ?? c.created_at,
+            last_message_at: c.lastMessageAt ?? c.last_message_at,
+            user_identifier: c.userIdentifier ?? c.user_identifier,
+        })),
+        _tip: "Use conversation_id with debug(method='conversation_detail') to see messages and workflow_run_ids.",
+        _next_step: items.length > 0
+            ? `debug(method="conversation_detail", conversation_id="${items[0].conversationId ?? items[0].conversation_id}")`
+            : "No conversations found. Try adjusting filters or date range.",
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// conversation_detail
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatConversationDetail(data, conversationId, personaId) {
+    const messages = data.messages ?? data.messageDetails ?? data.message_details;
+    const items = Array.isArray(messages) ? messages : [];
+    const formatted = items.map((m) => {
+        const workflowRunId = m.workflowRunId ?? m.workflow_run_id;
+        const chatMsg = (m.chatbotMessage ?? m.chatbot_message ?? {});
+        // Derive role from ChatbotMessage.type + isUserMessage
+        const msgType = chatMsg.type ?? chatMsg.message_type;
+        const isUser = chatMsg.isUserMessage ?? chatMsg.is_user_message;
+        const role = isUser ? "user" : (msgType ? "assistant" : undefined);
+        // Extract content from the message oneof (textMessage, buttonsMessage, etc.)
+        const textMsg = (chatMsg.textMessage ?? chatMsg.text_message);
+        const buttonsMsg = (chatMsg.buttonsMessage ?? chatMsg.buttons_message);
+        const content = textMsg?.contents ?? textMsg?.content ?? buttonsMsg?.content ?? chatMsg.content;
+        return {
+            workflow_run_id: workflowRunId,
+            role,
+            type: msgType,
+            content: truncateValue(content),
+            user_feedback: m.userFeedback ?? m.user_feedback,
+            work_log_steps_count: Array.isArray(m.workLogSteps ?? m.work_log_steps)
+                ? (m.workLogSteps ?? m.work_log_steps).length
+                : 0,
+        };
+    });
+    // Find the first message with a workflow_run_id for the next step hint
+    const withRunId = formatted.find((m) => m.workflow_run_id);
+    return {
+        conversation_id: conversationId,
+        message_count: formatted.length,
+        messages: formatted,
+        _tip: "Messages with workflow_run_id can be inspected with debug(method='show_work', persona_id='...', workflow_run_id='...').",
+        _next_step: withRunId
+            ? `debug(method="show_work", persona_id="${personaId ?? "<persona_id>"}", workflow_run_id="${withRunId.workflow_run_id}")`
+            : "No workflow_run_ids found in this conversation.",
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// show_work
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatShowWork(data, workflowRunId, personaId) {
+    const showWorkLogs = (data.showWorkLogs ?? data.show_work_logs ?? {});
+    const actions = [];
+    const erroredActions = [];
+    for (const [actionName, logRaw] of Object.entries(showWorkLogs)) {
+        const log = logRaw;
+        const status = resolveStatus(log.actionRunStatus ?? log.action_run_status);
+        const inputs = log.inputs;
+        const outputs = log.outputs;
+        const inputEntries = Array.isArray(inputs?.entries) ? inputs.entries : [];
+        const outputEntries = Array.isArray(outputs?.entries) ? outputs.entries : [];
+        const actionSummary = {
+            action_name: actionName,
+            title: log.actionTitle ?? log.action_title,
+            status,
+            llm_call_count: log.llmCallCount ?? log.llm_call_count ?? 0,
+            llm_cost_usd: log.llmCostUsd ?? log.llm_cost_usd ?? 0,
+            llm_latency_ms: log.llmLatencyMs ?? log.llm_latency_ms ?? 0,
+            input_names: inputEntries.map((e) => e.name),
+            output_names: outputEntries.map((e) => e.name),
+            step_count: Array.isArray(log.workLogs ?? log.work_logs) ? (log.workLogs ?? log.work_logs).length : 0,
+            hitl_round_count: Array.isArray(log.hitlRounds ?? log.hitl_rounds) ? (log.hitlRounds ?? log.hitl_rounds).length : 0,
+        };
+        // Include error info if present
+        const messages = Array.isArray(log.messages) ? log.messages : [];
+        const errorMessages = messages.filter((m) => m.logLevel === "LOG_LEVEL_ERROR" || m.log_level === "LOG_LEVEL_ERROR" || m.logLevel === 1 || m.log_level === 1);
+        if (errorMessages.length > 0) {
+            actionSummary.errors = errorMessages.map((m) => {
+                const errorInfo = (m.errorInfo ?? m.error_info);
+                return {
+                    message: m.messageTemplate ?? m.message_template,
+                    error_name: errorInfo?.name,
+                    external_message: errorInfo?.externalMessage ?? errorInfo?.external_message,
+                };
+            });
+        }
+        if (status === "ERRORED") {
+            erroredActions.push(actionName);
+        }
+        actions.push(actionSummary);
+    }
+    const result = {
+        workflow_run_id: workflowRunId,
+        action_count: actions.length,
+        actions,
+        _tip: "Use action_name with debug(method='action_detail', persona_id='...') to see full inputs, outputs, LLM calls, and steps for any action.",
+    };
+    // Smart _next_step: auto-suggest drilling into errored actions
+    if (erroredActions.length > 0) {
+        const pid = personaId ?? "<persona_id>";
+        result._next_step = `Action(s) ERRORED: ${erroredActions.join(", ")}. Investigate with: debug(method="action_detail", persona_id="${pid}", workflow_run_id="${workflowRunId}", action_name="${erroredActions[0]}")`;
+    }
+    else {
+        const pid = personaId ?? "<persona_id>";
+        result._next_step = actions.length > 0
+            ? `debug(method="action_detail", persona_id="${pid}", workflow_run_id="${workflowRunId}", action_name="${actions[0].action_name}") to see detailed execution trace.`
+            : "No actions found in this workflow run.";
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// action_detail
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatActionDetail(data, workflowRunId, actionName) {
+    const log = (data.showWorkLog ?? data.show_work_log ?? {});
+    const status = resolveStatus(log.actionRunStatus ?? log.action_run_status);
+    // Inputs
+    const inputs = log.inputs;
+    const inputEntries = Array.isArray(inputs?.entries) ? inputs.entries : [];
+    const formattedInputs = inputEntries.map((e) => ({
+        name: e.name,
+        value: truncateValue(e.value),
+        type: e.type,
+        source_agent: e.sourceAgentName ?? e.source_agent_name,
+    }));
+    // Outputs
+    const outputs = log.outputs;
+    const outputEntries = Array.isArray(outputs?.entries) ? outputs.entries : [];
+    const formattedOutputs = outputEntries.map((e) => ({
+        name: e.name,
+        value: truncateValue(e.value),
+        type: e.type,
+        published_as_chat_response: e.publishedAsChatResponse ?? e.published_as_chat_response,
+    }));
+    // Steps (work logs)
+    const steps = Array.isArray(log.workLogs ?? log.work_logs) ? (log.workLogs ?? log.work_logs) : [];
+    const formattedSteps = steps.map((s) => {
+        const msgs = Array.isArray(s.messages) ? s.messages : [];
+        const stepLlmCalls = Array.isArray(s.llmCalls ?? s.llm_calls) ? (s.llmCalls ?? s.llm_calls) : [];
+        return {
+            name: s.name,
+            messages: msgs.map((m) => ({
+                heading: m.heading,
+                template: truncateValue(m.messageTemplate ?? m.message_template),
+                log_level: m.logLevel ?? m.log_level,
+                error_info: m.errorInfo ?? m.error_info,
+            })),
+            llm_calls: stepLlmCalls.map((c) => formatLlmCall(c)),
+        };
+    });
+    // Top-level LLM calls
+    const topLlmCalls = Array.isArray(log.llmCalls ?? log.llm_calls) ? (log.llmCalls ?? log.llm_calls) : [];
+    const formattedLlmCalls = topLlmCalls.map((c) => formatLlmCall(c));
+    // HITL rounds
+    const hitlRounds = Array.isArray(log.hitlRounds ?? log.hitl_rounds) ? (log.hitlRounds ?? log.hitl_rounds) : [];
+    const formattedHitl = hitlRounds.map((r) => truncateObject(r));
+    return {
+        workflow_run_id: workflowRunId,
+        action_name: actionName,
+        action_type: data.actionType ?? data.action_type,
+        title: log.actionTitle ?? log.action_title,
+        status,
+        llm_call_count: log.llmCallCount ?? log.llm_call_count ?? 0,
+        llm_cost_usd: log.llmCostUsd ?? log.llm_cost_usd ?? 0,
+        llm_latency_ms: log.llmLatencyMs ?? log.llm_latency_ms ?? 0,
+        inputs: formattedInputs,
+        outputs: formattedOutputs,
+        steps: formattedSteps,
+        llm_calls: formattedLlmCalls,
+        hitl_rounds: formattedHitl.length > 0 ? formattedHitl : undefined,
+        _tip: status === "ERRORED"
+            ? "Check the steps and error_info fields for failure details. LLM calls show the exact prompts and responses."
+            : "Review inputs/outputs for data flow and llm_calls for prompt details.",
+    };
+}
+function formatLlmCall(call) {
+    const prompt = (call.prompt ?? {});
+    const metrics = (call.metrics ?? {});
+    return {
+        heading: call.heading,
+        success: call.success,
+        error_message: call.errorMessage ?? call.error_message,
+        fusion_used: call.fusionUsed ?? call.fusion_used,
+        cost_final_choice: call.llmCostFinalChoice ?? call.llm_cost_final_choice,
+        timestamp_ms: call.timestampMs ?? call.timestamp_ms,
+        prompt: {
+            system_prompt: truncateValue(prompt.systemPrompt ?? prompt.system_prompt),
+            user_prompt: truncateValue(prompt.userPrompt ?? prompt.user_prompt),
+            response: truncateValue(prompt.response),
+        },
+        metrics: Object.keys(metrics).length > 0 ? truncateObject(metrics) : undefined,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// search
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatSearch(data, query, personaId) {
+    const results = Array.isArray(data.results) ? data.results : [];
+    return {
+        persona_id: personaId,
+        query,
+        total: results.length,
+        results: results.map((r) => ({
+            run_id: r.runId ?? r.run_id,
+            conversation_id: r.conversationId ?? r.conversation_id,
+            user_message_created_at: r.userMessageCreatedAt ?? r.user_message_created_at,
+            user_message: truncateValue(r.userMessage ?? r.user_message),
+            bot_message: truncateValue(r.botMessage ?? r.bot_message),
+        })),
+        _tip: "Use conversation_id with debug(method='conversation_detail') to see the full conversation, or run_id to identify the workflow execution.",
+        _next_step: results.length > 0
+            ? `debug(method="conversation_detail", conversation_id="${results[0].conversationId ?? results[0].conversation_id}")`
+            : "No messages matched the search query.",
+    };
+}