@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/domain/generation-schema.js

@@ -29,6 +29,10 @@ export function buildCompactAgents() {
         agents[agent.actionName] = {
             name: agent.displayName,
             category: agent.category,
+            description: agent.description,
+            whenToUse: agent.whenToUse,
+            aliases: agent.aliases,
+            tier: agent.tier,
             inputs,
             outputs,
             constraints: agent.criticalRules,
@@ -81,11 +85,11 @@ export function buildConstraints() {
             "Category routing is via runIf conditions, not edges",
         ],
         hitl: [
-            "MUST have both success and failure paths",
-            "Success path: source_output 'hitl_status_HITL Success' (note: space, not underscore)",
-            "Failure path: source_output 'hitl_status_HITL Failure' (note: space, not underscore)",
-            "Both paths must eventually reach WORKFLOW_OUTPUT",
-            "Unlike regular categorizers, NO Fallback category - only Success/Failure",
+            "general_hitl (Human Collaboration Agent): standalone node with Conversational, Standard Form, and Custom Form modes",
+            "Outputs: human_collaboration_status (HITL Success / HITL Failure enum) and summarized_conversation",
+            "Branch downstream nodes with runIf on human_collaboration_status",
+            "MUST handle both HITL Success and HITL Failure paths — both must reach WORKFLOW_OUTPUT",
+            "send_email_agent and entity_extraction_with_documents also support HITL via disable_human_interaction: false flag",
         ],
         outputs: [
             "All user-visible outputs MUST connect to WORKFLOW_OUTPUT",
@@ -117,16 +121,18 @@ export function generateSchema() {
 export function generateSchemaMarkdown() {
     const schema = generateSchema();
     let md = `# Workflow Generation Schema\n\n`;
-    // Agent summary table
+    // Agent summary table with tier and description
     md += `## Available Agents (${Object.keys(schema.agents).length})\n\n`;
-    md += `| Action | Category | Inputs | Outputs |\n`;
-    md += `|--------|----------|--------|--------|\n`;
+    md += `| Action | Tier | Category | Description | Inputs | Outputs |\n`;
+    md += `|--------|------|----------|-------------|--------|--------|\n`;
     for (const [actionName, agent] of Object.entries(schema.agents)) {
         const inputs = Object.entries(agent.inputs)
             .map(([name, { type, required }]) => `${name}${required ? "*" : ""}`)
             .join(", ") || "-";
         const outputs = Object.keys(agent.outputs).join(", ") || "-";
-        md += `| \`${actionName}\` | ${agent.category} | ${inputs} | ${outputs} |\n`;
+        const tier = agent.tier ?? "-";
+        const desc = agent.description ? agent.description.slice(0, 80) : "-";
+        md += `| \`${actionName}\` | ${tier} | ${agent.category} | ${desc} | ${inputs} | ${outputs} |\n`;
     }
     // Type rules
     md += `\n## Type Compatibility\n\n`;

package/dist/mcp/domain/structural-rules.js

@@ -104,7 +104,7 @@ export const STRUCTURAL_INVARIANTS = [
     {
         id: "hitl_has_both_paths",
         name: "HITL Must Have Success AND Failure Paths",
-        rule: "Legacy general_hitl nodes (if present) have two outcomes: approval and rejection. Both MUST have downstream handlers. Note: general_hitl is NOT deployable for new workflows — HITL is a flag on entity_extraction_with_documents and send_email_agent only.",
+        rule: "general_hitl (Human Collaboration Agent) nodes have two outcomes: HITL Success and HITL Failure. Both MUST have downstream handlers via runIf conditions. Additionally, send_email_agent and entity_extraction_with_documents support HITL via their disable_human_interaction flag.",
         violation: "HITL 'approval' only has success path - rejections hang",
         fix: "For legacy workflows: add handler for hitl.approval_decision = 'reject'. For new workflows: use HITL flag on send_email_agent or entity_extraction_with_documents instead.",
         severity: "critical",
@@ -332,12 +332,12 @@ BEFORE finalizing any workflow modification, verify these rules:
    |---------------|------------------|
    | TEXT_WITH_SOURCES | trigger.user_query, conversation_to_search_query.summarized_conversation |
    | CHAT_CONVERSATION | trigger.chat_conversation |
-   | SEARCH_RESULT | search.search_results, combine_search_results.combined_results |
+   | SEARCH_RESULT | search.search_results, combine_and_rerank_search_results.reranked_results |
    | EMAIL_ADDRESS | entity_extraction.email_address (NOT text outputs) |
 
 ### HITL Rules
 
-10. **Both Paths Required**: Legacy general_hitl nodes need handlers for both approval AND rejection. Note: general_hitl is NOT deployable — HITL is a flag on entity_extraction_with_documents and send_email_agent only.
+10. **Both Paths Required**: general_hitl (Human Collaboration Agent) nodes need handlers for both HITL Success AND HITL Failure paths. Additionally, send_email_agent and entity_extraction_with_documents support HITL via disable_human_interaction flag.
 
 ### Raw workflow_def Format Rules (CRITICAL)
 

package/dist/mcp/domain/validation-rules.js

@@ -148,7 +148,7 @@ export const ANTI_PATTERNS = [
         pattern: "send_email_agent without entity_extraction to validate recipient data",
         problem: "Sending emails without extracting and validating recipient data risks sending to wrong people or with wrong content. Emails are high-impact actions with external side effects.",
         solution: "Always: 1) Extract required fields (email_address, subject) via entity_extraction, 2) Validate completeness via categorizer, 3) Ask user if missing. " +
-            "For approval: enable the HITL flag on send_email_agent (disable_human_interaction: false). general_hitl is NOT deployable.",
+            "For simple approval: enable HITL flag on send_email_agent (disable_human_interaction: false). For rich dialogue: use general_hitl (Human Collaboration Agent).",
         detection: {
             issueType: "incomplete_email_validation",
             condition: "send_email_agent without preceding entity_extraction node to extract/validate recipient data",
@@ -208,15 +208,12 @@ export const ANTI_PATTERNS = [
         name: "Incomplete HITL Paths",
         pattern: "HITL with only success path",
         problem: "Rejected requests have no handling, leaving users without response.",
-        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent (only entity_extraction_with_documents and send_email_agent support HITL). general_hitl is NOT deployable.",
+        solution: "general_hitl (Human Collaboration Agent) MUST have both HITL Success AND HITL Failure downstream handlers via runIf. For agent-level HITL (send_email_agent, entity_extraction_with_documents), the platform handles approval UI automatically.",
         detection: {
             issueType: "incomplete_hitl",
             condition: "HITL node missing 'hitl_status_HITL Success' or 'hitl_status_HITL Failure' edge (note: space, not underscore)",
         },
         severity: "critical",
-        // general_hitl is NOT deployable — it appears in catalogs but cannot be deployed.
-        // HITL is a flag on entity_extraction_with_documents and send_email_agent only.
-        // external_action_caller does NOT support HITL. This rule still fires for legacy workflows.
     },
     {
         id: "orphan-nodes",
@@ -234,7 +231,7 @@ export const ANTI_PATTERNS = [
         id: "unused-output",
         name: "Unused Output",
         pattern: "Node produces output that is not consumed by any downstream node",
-        problem: "Node is doing work that goes nowhere. Common with combine_search_results where combined_results isn't wired. Wastes compute and indicates incomplete wiring.",
+        problem: "Node is doing work that goes nowhere. Common with combine_and_rerank_search_results where reranked_results isn't wired. Wastes compute and indicates incomplete wiring.",
         solution: "Connect the output to a downstream node that needs it, or remove the node if not needed.",
         detection: {
             issueType: "unused_output",
@@ -453,31 +450,27 @@ export const ANTI_PATTERNS = [
     },
     {
         id: "chat-conversation-without-chat-response",
-        name: "Chat Conversation Not Wired to Chat Response Node",
-        pattern: "Chat workflow where chat_conversation is consumed by processing nodes but never wired to a chat-aware response node (respond_for_external_actions)",
+        name: "Chat Conversation Not Wired to Response Node",
+        pattern: "Chat workflow where chat_conversation is not wired to the response node's named_inputs",
         problem: "When chat_conversation is processed by nodes like entity_extraction, call_llm, or search, " +
-            "but the final response is generated by a generic call_llm (not a chat-aware response node), " +
-            "the response node lacks conversation history context. This causes:\n" +
+            "but the final response node lacks conversation history context, it causes:\n" +
             "1. Duplicate/repetitive responses — the LLM re-asks questions already answered in conversation\n" +
             "2. Lost context — follow-up messages lose prior context\n" +
-            "3. Hallucinated greetings — the LLM generates its own greeting instead of continuing the conversation\n\n" +
-            "The respond_for_external_actions node is specifically designed to handle conversation history " +
-            "and produce contextually appropriate responses (replacing the deprecated respond_with_sources).",
-        solution: "Wire chat_conversation through to a chat-aware response node:\n" +
-            "• For search results or tool/action results: use respond_for_external_actions (takes query + conversation + external_action_result)\n" +
-            "• If using call_llm as responder: wire chat_conversation into named_inputs so the LLM sees full history\n\n" +
+            "3. Hallucinated greetings — the LLM generates its own greeting instead of continuing the conversation",
+        solution: "Wire chat_conversation into the response node's named_inputs:\n" +
+            "• For KB Q&A: call_llm with named_inputs_Search_Results + named_inputs_Conversation (89% of production)\n" +
+            "• For tool results: respond_for_external_actions (ONLY after external_action_caller)\n" +
+            "• For citations: respond_with_sources\n\n" +
             "Correct patterns:\n" +
-            "  chat_trigger → search → respond_for_external_actions → WORKFLOW_OUTPUT\n" +
-            "  chat_trigger → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT\n" +
-            "  chat_trigger → call_llm(named_inputs includes chat_conversation) → WORKFLOW_OUTPUT\n\n" +
+            "  chat_trigger → search → call_llm(named_inputs_Search_Results + named_inputs_Conversation) → WORKFLOW_OUTPUT\n" +
+            "  chat_trigger → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT\n\n" +
             "Anti-patterns:\n" +
             "  ❌ chat_trigger → search → call_llm (no conversation context) → WORKFLOW_OUTPUT\n" +
-            "  ❌ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT\n" +
-            "  ❌ chat_trigger → search → respond_with_sources (DEPRECATED) → WORKFLOW_OUTPUT",
+            "  ❌ chat_trigger → search → respond_for_external_actions (wrong — that's for tool results only)\n" +
+            "  ❌ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT",
         detection: {
             issueType: "chat_conversation_not_wired_to_response",
-            condition: "Chat workflow (chat_trigger) where terminal response node is call_llm without chat_conversation in named_inputs, " +
-                "and respond_for_external_actions is not used",
+            condition: "Chat workflow (chat_trigger) where terminal response node is call_llm without chat_conversation in named_inputs",
         },
         severity: "critical",
     },
@@ -598,10 +591,10 @@ export const OPTIMIZATION_RULES = [
     },
     {
         id: "use-purpose-built",
-        name: "Use Purpose-Built Response Nodes",
-        currentState: "Using call_llm for search-based responses",
-        recommendation: "Use respond_for_external_actions instead - it has built-in citation handling and conversation awareness (respond_with_sources is deprecated)",
-        benefit: "Better citations, grounded responses, conversation context, less configuration",
+        name: "Wire Conversation Context into Response Nodes",
+        currentState: "Using call_llm for search-based responses without conversation context",
+        recommendation: "Wire chat_conversation via named_inputs_Conversation so the LLM sees multi-turn history. For citation-grounded responses, use respond_with_sources. respond_for_external_actions is ONLY for external_action_caller results.",
+        benefit: "Conversation-aware responses, no repetitive questions, proper multi-turn context",
         priority: "medium",
     },
     {

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

@@ -32,7 +32,7 @@ const FALLBACK_NAMESPACES = {
     send_email_agent: ["actions", "emainternal"],
     conversation_to_search_query: ["actions", "emainternal"],
     entity_extraction: ["actions", "emainternal"],
-    combine_search_results: ["actions", "emainternal"],
+    combine_and_rerank_search_results: ["actions", "emainternal"],
     response_validator: ["actions", "emainternal"],
 };
 /**
@@ -57,7 +57,7 @@ const FALLBACK_VERSIONS = {
     send_email_agent: "v0", // Fixed: was v1
     conversation_to_search_query: "v0", // Fixed: was v1
     entity_extraction: "v0", // entity_extraction_with_documents is v0
-    combine_search_results: "v0", // combine_and_rerank_search_results is v0
+    combine_and_rerank_search_results: "v0",
     response_validator: "v0", // Fixed: was v1
 };
 /**
@@ -66,7 +66,7 @@ const FALLBACK_VERSIONS = {
  */
 const ACTION_TYPE_TO_API_NAME = {
     entity_extraction: "entity_extraction_with_documents",
-    combine_search_results: "combine_and_rerank_search_results",
+    // combine_and_rerank_search_results maps to itself (identity) — no override needed
     general_hitl: "hitl",
     // CRITICAL: respond_with_sources doesn't exist in API - map to call_llm
     respond_with_sources: "call_llm",

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

@@ -26,7 +26,7 @@ const SIDE_EFFECT_FREE = new Set([
     "respond_with_sources",
     "respond_for_external_actions",
     "conversation_to_search_query",
-    "combine_search_results",
+    "combine_and_rerank_search_results",
     "text_categorizer",
     "chat_categorizer",
     "response_validator",

package/dist/mcp/guidance.js

@@ -337,13 +337,18 @@ export const TOOL_GUIDANCE = {
     },
     toolkit_feedback: {
         toolName: "toolkit_feedback",
-        quickTip: "Submit feedback to help improve the MCP toolkit. Report gaps, confusion, successes, or suggestions.",
+        quickTip: "Submit feedback to help improve the MCP toolkit. Report gaps, confusion, successes, or suggestions. Respond to _probe questions when they appear in tool responses.",
         operations: [
             {
                 name: "Submit feedback",
                 description: "Report an issue or positive experience",
                 example: 'toolkit_feedback(method="submit", category="gap", message="Missing docs on X")',
             },
+            {
+                name: "Respond to probe",
+                description: "Answer a targeted question from a _probe field in a tool response",
+                example: 'toolkit_feedback(method="submit", category="probe_response", message="<your answer>", context="<probe.id>")',
+            },
             {
                 name: "List feedback",
                 description: "View recent feedback entries",
@@ -363,6 +368,45 @@ export const TOOL_GUIDANCE = {
         commonMistakes: [
             "Forgetting to include which tool/operation the feedback is about",
             "Not describing what you were trying to accomplish (use context parameter)",
+            "Ignoring _probe questions in tool responses — answering them helps improve the toolkit",
+        ],
+        applicableRules: [],
+    },
+    template: {
+        toolName: "template",
+        quickTip: "Manage persona templates (blueprints for AI Employees). List, create, update, delete templates.",
+        operations: [
+            {
+                name: "List templates",
+                description: "Browse available persona templates",
+                example: 'template(method="list")',
+            },
+            {
+                name: "Get template",
+                description: "Get full details for a template",
+                example: 'template(method="get", id="...")',
+            },
+            {
+                name: "Create template",
+                description: "Create a new persona template",
+                example: 'template(method="create", name="My Template", type="voice")',
+            },
+            {
+                name: "Delete template",
+                description: "Delete a persona template",
+                example: 'template(method="delete", id="...", confirm=true)',
+            },
+        ],
+        nextSteps: {
+            list: "Get details: template(method='get', id='<id>')",
+            get: "Create persona from template: persona(method='create', from='<template_id>', name='...')",
+            create: "View template: template(method='get', id='<template_id>')",
+            update: "Verify changes: template(method='get', id='<template_id>')",
+            delete: "Template removed. List remaining: template(method='list')",
+        },
+        commonMistakes: [
+            "Deleting a template without confirm=true",
+            "Using template tool for read-only browsing when catalog tool would suffice",
         ],
         applicableRules: [],
     },
@@ -486,6 +530,15 @@ Use the \`debug\` tool to inspect workflow runs and troubleshoot issues:
 3. \`debug(method="action_detail", ...)\` → deep trace with LLM calls, inputs/outputs
 Also available as persona sub-resource: \`persona(id="abc", debug={method:"conversations"})\`
 
+## Template Management
+Use the \`template\` tool to create, browse, update, and delete persona templates (blueprints for AI Employees):
+- \`template(method="list")\` → browse available templates
+- \`template(method="get", id="...")\` → get full template details
+- \`template(method="create", name="...", type="chat", proto_config={...})\` → create new template
+- \`template(method="update", id="...", name="...")\` → update template
+- \`template(method="delete", id="...", confirm=true)\` → delete template
+For read-only browsing, \`catalog(type="templates")\` also works.
+
 ## Resources
 - \`ema://docs/usage-guide\` - Complete guide
 - \`ema://docs/debugging-guide\` - Debugging workflow executions
@@ -501,6 +554,12 @@ Help us improve! Use \`toolkit_feedback\` to report issues or successes:
 
 Your feedback is automatically collected and analyzed to improve the toolkit for all agents.
 
+## Probes
+Tool responses may occasionally include a \`_probe\` field with a targeted question.
+When you see one, please respond using the \`how_to_respond\` instructions in the probe.
+This provides valuable contextual feedback that helps us improve specific areas of the toolkit.
+Probes are optional — you can skip them if they are not relevant to your current task.
+
 ## Need Help?
 Use the \`toolkit_onboard\` prompt for comprehensive guidance.
 `;

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

@@ -0,0 +1,13 @@
+/**
+ * Conversation Adapter
+ *
+ * Thin adapter that resolves client from env and delegates to handleConversation.
+ * Same pattern as debug/adapter.ts.
+ */
+import { handleConversation } from "./index.js";
+export async function handleConversationAdapter(args, createClient, getDefaultEnvName) {
+    const targetEnv = args.env ?? getDefaultEnvName();
+    // createClient() returns EmaClientAdapter at runtime (see env/config.ts)
+    const client = createClient(targetEnv);
+    return handleConversation(args, client);
+}

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

@@ -0,0 +1,19 @@
+import { formatCreateResponse } from "./formatters.js";
+/**
+ * Create a new chat conversation for a persona.
+ * Returns the conversation ID and welcome message.
+ */
+export async function handleCreate(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return {
+            error: "persona_id is required",
+            hint: 'conversation(method="create", persona_id="<uuid>")',
+        };
+    }
+    const result = await client.createConversation(personaId, {
+        userContext: args.user_context,
+        caller: args.caller ?? "mcp-toolkit",
+    });
+    return formatCreateResponse(result);
+}

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

@@ -0,0 +1,18 @@
+export async function handleDelete(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return { error: "Missing required parameter: conversation_id" };
+    }
+    const confirm = args.confirm;
+    if (confirm !== true) {
+        return {
+            error: "Deletion requires confirm=true",
+            _tip: `To delete conversation ${conversationId}, call conversation(method='delete', conversation_id='${conversationId}', confirm=true)`,
+        };
+    }
+    await client.deleteConversation(conversationId);
+    return {
+        success: true,
+        deleted_conversation_id: conversationId,
+    };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Conversation response formatters.
+ *
+ * Shapes raw API responses into agent-friendly output with _tip / _next_step hints.
+ */
+const MAX_MESSAGE_PREVIEW = 2000;
+/**
+ * Truncate a string to max length with ellipsis.
+ */
+function truncate(value, max = MAX_MESSAGE_PREVIEW) {
+    const str = typeof value === "string" ? value : JSON.stringify(value) ?? "";
+    return str.length > max ? str.slice(0, max) + "..." : str;
+}
+export function formatCreateResponse(result) {
+    return {
+        conversation_id: result.conversationId,
+        welcome_message: result.message,
+        _next_step: `conversation(method="send", conversation_id="${result.conversationId}", text="your message here")`,
+        _tip: "Send a text message to start the conversation. The AI Employee will respond with its workflow output.",
+    };
+}
+export function formatSendResponse(result) {
+    const msg = result.message;
+    const msgType = msg?.type ?? "unknown";
+    const response = {
+        conversation_id: result.conversationId,
+        message: result.message,
+        snippets: result.snippets,
+    };
+    // Provide contextual next-step based on response message type
+    if (msgType.includes("BUTTONS")) {
+        response._tip = "The AI responded with buttons. Select one using the buttons parameter.";
+        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. 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.";
+        response._next_step = `conversation(method="history", conversation_id="${result.conversationId}")`;
+    }
+    return response;
+}
+export function formatHistoryResponse(conversationId, result) {
+    const messages = result.messages.map((m) => {
+        const text = m.textMessage;
+        const contents = text?.contents;
+        return {
+            ...m,
+            // Add a preview field for quick scanning
+            ...(contents?.[0] && { _preview: truncate(contents[0], 200) }),
+        };
+    });
+    return {
+        conversation_id: conversationId,
+        message_count: messages.length,
+        messages,
+        _tip: "Messages are in chronological order. Use method='send' to continue the conversation.",
+        _next_step: `conversation(method="send", conversation_id="${conversationId}", text="your reply")`,
+    };
+}

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

@@ -0,0 +1,15 @@
+import { formatHistoryResponse } from "./formatters.js";
+/**
+ * Retrieve the message history for a conversation.
+ */
+export async function handleHistory(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return {
+            error: "conversation_id is required",
+            hint: 'conversation(method="history", conversation_id="<uuid>")',
+        };
+    }
+    const result = await client.getConversationHistory(conversationId);
+    return formatHistoryResponse(conversationId, result);
+}

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

@@ -0,0 +1,43 @@
+import { handleCreate } from "./create.js";
+import { handleSend } from "./send.js";
+import { handleHistory } from "./history.js";
+import { handleList } from "./list.js";
+import { handleMessages } from "./messages.js";
+import { handleDelete } from "./delete.js";
+import { handleRename } from "./rename.js";
+const METHOD_HANDLERS = {
+    create: handleCreate,
+    send: handleSend,
+    history: handleHistory,
+    list: handleList,
+    messages: handleMessages,
+    delete: handleDelete,
+    rename: handleRename,
+};
+/**
+ * Top-level conversation handler.
+ * Routes to method-specific handlers based on the `method` parameter.
+ */
+export async function handleConversation(args, client) {
+    const method = args.method;
+    if (!method) {
+        return {
+            error: "method is required",
+            valid_methods: Object.keys(METHOD_HANDLERS),
+            examples: [
+                'conversation(method="create", persona_id="...") - start a live chat session',
+                'conversation(method="send", conversation_id="...", text="hello") - send a message',
+                'conversation(method="history", conversation_id="...") - view messages',
+            ],
+            _tip: "Start with method='create' to open a new chat session with a persona.",
+        };
+    }
+    const handler = METHOD_HANDLERS[method];
+    if (!handler) {
+        return {
+            error: `Unknown method: ${method}`,
+            valid_methods: Object.keys(METHOD_HANDLERS),
+        };
+    }
+    return handler(args, client);
+}

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

@@ -0,0 +1,40 @@
+export async function handleList(args, client) {
+    const personaId = args.persona_id;
+    if (personaId) {
+        // List conversations for a specific persona
+        const limit = args.limit;
+        const paginationToken = args.pagination_token;
+        const result = await client.listConversationsForPersona(personaId, {
+            limit,
+            paginationToken,
+        });
+        const conversations = result.conversations ?? result;
+        const count = Array.isArray(conversations) ? conversations.length : 0;
+        return {
+            persona_id: personaId,
+            count,
+            conversations,
+            ...(typeof result.pagination_token === "string" && {
+                pagination_token: result.pagination_token,
+            }),
+            _tip: count > 0
+                ? "Use conversation(method='messages', conversation_id='<id>') to view messages."
+                : "No conversations found for this persona.",
+        };
+    }
+    // List all conversations for the current user
+    const conversations = await client.listConversations();
+    return {
+        count: conversations.length,
+        conversations: conversations.map((c) => ({
+            id: c.id,
+            display_name: c.display_name,
+            persona_id: c.persona_id,
+            persona_display_name: c.persona_display_name,
+            created_at: c.created_at,
+            updated_at: c.updated_at,
+            status: c.status,
+        })),
+        _tip: "Use conversation(method='messages', conversation_id='<id>') to view messages in a conversation.",
+    };
+}

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

@@ -0,0 +1,13 @@
+export async function handleMessages(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return { error: "Missing required parameter: conversation_id" };
+    }
+    const messages = await client.getConversationMessages(conversationId);
+    return {
+        conversation_id: conversationId,
+        message_count: messages.length,
+        messages,
+        _tip: "Use conversation(method='send', conversation_id='...', text='...') to continue the conversation.",
+    };
+}

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

@@ -0,0 +1,16 @@
+export async function handleRename(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return { error: "Missing required parameter: conversation_id" };
+    }
+    const displayName = args.display_name;
+    if (!displayName) {
+        return { error: "Missing required parameter: display_name" };
+    }
+    await client.updateConversationDisplayName(conversationId, displayName);
+    return {
+        success: true,
+        conversation_id: conversationId,
+        display_name: displayName,
+    };
+}