@hotmeshio/long-tail 0.1.0

package/build/system/workflows/mcp-triage/index.d.ts

@@ -0,0 +1,31 @@
+import type { LTEnvelope, LTReturn } from '../../../types';
+/**
+ * MCP Triage workflow (leaf).
+ *
+ * Activated when a human resolver flags `needsTriage` in their resolution
+ * payload. Dynamically adapts to ANY workflow type using available
+ * MCP tools scoped by tag affinity.
+ *
+ * Tool ecosystem grows over time:
+ * - Built-in servers: document-vision, mcp-workflows, human-queue,
+ *   workflow-compiler, db, telemetry
+ * - User-registered external MCP servers
+ * - Compiled YAML workflows from past triage executions
+ *
+ * Tools are scoped by the original workflow's `tool_tags` configuration
+ * (plus base tags: workflows, compiled, database). Full tool definitions
+ * are cached at the module level — only lightweight IDs flow through
+ * the durable execution log.
+ *
+ * **First entry** (no `envelope.resolver`):
+ *   1. Gather upstream tasks and escalation history
+ *   2. Load scoped tools (tag-filtered, cached)
+ *   3. LLM agentic loop with tool IDs
+ *   4. Returns `{ correctedData }` or escalates to engineer
+ *
+ * **Re-entry** (has `envelope.resolver` — engineer responded):
+ *   1. Engineer may have installed new tools or provided guidance
+ *   2. LLM re-evaluates with fresh tool inventory
+ *   3. Returns `{ correctedData }` or re-escalates
+ */
+export declare function mcpTriage(envelope: LTEnvelope): Promise<LTReturn>;

package/build/system/workflows/mcp-triage/index.js

@@ -0,0 +1,222 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpTriage = mcpTriage;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+const activities = __importStar(require("../../activities/triage"));
+const interceptorActivities = __importStar(require("../../../services/interceptor/activities"));
+const prompts_1 = require("./prompts");
+const response_1 = require("./response");
+const { getUpstreamTasks, getEscalationHistory, getToolTags, loadTriageTools, callTriageTool, callTriageLLM, notifyEngineering, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retryPolicy: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+const { ltCreateEscalation, ltCreateTask, ltGetTask, ltGetWorkflowConfig, ltStartWorkflow, ltEnrichEscalationRouting, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities: interceptorActivities,
+    taskQueue: 'lt-interceptor',
+    retryPolicy: { maximumAttempts: 3 },
+});
+const MAX_TOOL_ROUNDS = defaults_1.TOOL_ROUNDS_TRIAGE;
+/** Proxied activity refs passed to response handlers */
+const responseDeps = {
+    ltCreateEscalation,
+    ltCreateTask,
+    ltGetTask,
+    ltGetWorkflowConfig,
+    ltStartWorkflow,
+    notifyEngineering,
+};
+// ── Workflow ─────────────────────────────────────────────────
+/**
+ * MCP Triage workflow (leaf).
+ *
+ * Activated when a human resolver flags `needsTriage` in their resolution
+ * payload. Dynamically adapts to ANY workflow type using available
+ * MCP tools scoped by tag affinity.
+ *
+ * Tool ecosystem grows over time:
+ * - Built-in servers: document-vision, mcp-workflows, human-queue,
+ *   workflow-compiler, db, telemetry
+ * - User-registered external MCP servers
+ * - Compiled YAML workflows from past triage executions
+ *
+ * Tools are scoped by the original workflow's `tool_tags` configuration
+ * (plus base tags: workflows, compiled, database). Full tool definitions
+ * are cached at the module level — only lightweight IDs flow through
+ * the durable execution log.
+ *
+ * **First entry** (no `envelope.resolver`):
+ *   1. Gather upstream tasks and escalation history
+ *   2. Load scoped tools (tag-filtered, cached)
+ *   3. LLM agentic loop with tool IDs
+ *   4. Returns `{ correctedData }` or escalates to engineer
+ *
+ * **Re-entry** (has `envelope.resolver` — engineer responded):
+ *   1. Engineer may have installed new tools or provided guidance
+ *   2. LLM re-evaluates with fresh tool inventory
+ *   3. Returns `{ correctedData }` or re-escalates
+ */
+async function mcpTriage(envelope) {
+    const { originId, originalWorkflowType, originalTaskQueue, escalationPayload, resolverPayload, } = envelope.data;
+    // ── Re-entry: engineer responded to our escalation ──
+    if (envelope.resolver) {
+        const resolver = envelope.resolver;
+        return runTriageLLM(envelope, {
+            additionalContext: prompts_1.TRIAGE_REENTRY_CONTEXT.replace('%RESOLVER_JSON%', JSON.stringify(resolver, null, 2)),
+        });
+    }
+    // ── First entry: gather context and let LLM diagnose + fix ──
+    const upstreamTasks = await getUpstreamTasks(originId);
+    const escalationHistory = await getEscalationHistory(originId);
+    const context = buildTriageContext(envelope.data, upstreamTasks, escalationHistory);
+    return runTriageLLM(envelope, { additionalContext: context });
+}
+// ── LLM Agentic Loop ────────────────────────────────────────────
+async function runTriageLLM(envelope, opts) {
+    const { originalWorkflowType } = envelope.data;
+    // 1. Infer tool tags from the original workflow type (from config cache, no DB hit)
+    const workflowTags = await getToolTags(originalWorkflowType);
+    // 2. Load scoped tools with strategy advisor
+    //    (Compiled workflow discovery happens in mcpTriageRouter, not here —
+    //    this leaf only runs when no compiled match was found.)
+    const raw = await loadTriageTools(workflowTags.length > 0 ? workflowTags : undefined);
+    // 3. Build system prompt with tool inventory
+    const toolIds = raw.toolIds;
+    const inventoryParts = [
+        raw.strategy,
+        `## Available MCP Servers\n${raw.inventory}`,
+    ].filter(Boolean).join('\n\n');
+    const systemPrompt = (0, prompts_1.TRIAGE_SYSTEM_PROMPT)(inventoryParts);
+    const messages = [
+        { role: 'system', content: systemPrompt },
+        {
+            role: 'user',
+            content: `Handle this triage request:\n\n${opts.additionalContext}`,
+        },
+    ];
+    let toolCallCount = 0;
+    const BUDGET_WARNING_THRESHOLD = 3;
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+        const remaining = MAX_TOOL_ROUNDS - round;
+        // Inject budget warning when approaching the limit
+        if (remaining <= BUDGET_WARNING_THRESHOLD && remaining < MAX_TOOL_ROUNDS) {
+            messages.push({
+                role: 'user',
+                content: `[Rounds: ${remaining} remaining] Wrap up: consolidate your diagnosis and return your final JSON response.`,
+            });
+        }
+        // Only lightweight toolIds (string[]) flow through the durable pipe
+        const response = await callTriageLLM(messages, toolIds);
+        // No tool calls — LLM has produced its final answer
+        if (!response.tool_calls?.length) {
+            return (0, response_1.handleFinalResponse)(response.content || '', envelope, toolCallCount, responseDeps);
+        }
+        // Execute each tool call
+        const fnCalls = response.tool_calls.filter((tc) => tc.type === 'function');
+        messages.push({
+            role: 'assistant',
+            content: response.content,
+            tool_calls: fnCalls,
+        });
+        for (const toolCall of fnCalls) {
+            toolCallCount++;
+            let args = {};
+            try {
+                args = JSON.parse(toolCall.function.arguments || '{}');
+            }
+            catch {
+                args = {};
+            }
+            // callTool returns errors as data so the LLM can adapt
+            const result = await callTriageTool(toolCall.function.name, args);
+            // Durable waitFor: if the tool returns a signal, pause until human responds
+            if (result?.type === 'waitFor' && result?.signalId) {
+                const ctx = hotmesh_1.Durable.workflow.getContext();
+                const workflowType = ctx.workflowTopic.replace(`${ctx.taskQueue}-`, '');
+                await ltEnrichEscalationRouting({
+                    escalationId: result.escalationId,
+                    signalRouting: {
+                        taskQueue: ctx.taskQueue,
+                        workflowType,
+                        workflowId: ctx.workflowId,
+                        signalId: result.signalId,
+                    },
+                    claimForUserId: envelope.lt?.userId,
+                });
+                const signalData = await hotmesh_1.Durable.workflow.waitFor(result.signalId);
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: toolCall.id,
+                    content: JSON.stringify(signalData),
+                });
+                continue;
+            }
+            messages.push({
+                role: 'tool',
+                tool_call_id: toolCall.id,
+                content: JSON.stringify(result),
+            });
+        }
+    }
+    // Exhausted rounds — ask for final synthesis without tools
+    messages.push({
+        role: 'user',
+        content: prompts_1.TRIAGE_EXHAUSTED_ROUNDS,
+    });
+    const finalResponse = await callTriageLLM(messages, undefined);
+    return (0, response_1.handleFinalResponse)(finalResponse.content || '', envelope, toolCallCount, responseDeps);
+}
+// ── Context builders ─────────────────────────────────────────────
+/** Assemble the triage context string from workflow lineage and history. */
+function buildTriageContext(data, upstreamTasks, escalationHistory) {
+    const parts = [
+        `**Original Workflow**: \`${data.originalWorkflowType}\` (queue: \`${data.originalTaskQueue}\`)`,
+        `**Origin ID**: ${data.originId}`,
+        `**Escalation Data** (what the workflow reported when it escalated):\n\`\`\`json\n${JSON.stringify(data.escalationPayload, null, 2)}\n\`\`\``,
+        `**Resolver Payload** (what the human submitted):\n\`\`\`json\n${JSON.stringify(data.resolverPayload, null, 2)}\n\`\`\``,
+    ];
+    if (upstreamTasks.length > 0) {
+        parts.push(`**Upstream Tasks** (${upstreamTasks.length}):\n\`\`\`json\n${JSON.stringify(upstreamTasks.map((t) => ({ id: t.id, type: t.workflow_type, status: t.status })), null, 2)}\n\`\`\``);
+    }
+    if (escalationHistory.length > 0) {
+        parts.push(`**Escalation History** (${escalationHistory.length}):\n\`\`\`json\n${JSON.stringify(escalationHistory.map((e) => ({ id: e.id, type: e.type, role: e.role, status: e.status, description: e.description })), null, 2)}\n\`\`\``);
+    }
+    return parts.join('\n\n');
+}

package/build/system/workflows/mcp-triage/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Build the triage system prompt with the current tool inventory injected.
+ * The toolInventory comes from loadTools() at runtime.
+ */
+export declare function TRIAGE_SYSTEM_PROMPT(toolInventory: string): string;
+export declare const TRIAGE_REENTRY_CONTEXT = "An engineer has reviewed this issue and provided guidance:\n%RESOLVER_JSON%\n\nIMPORTANT: If the engineer says new tools or MCP servers were installed, re-check available tools \u2014 your tool inventory may have expanded since the last attempt. If they say \"ready\" or \"try again\", proceed with remediation.";
+export declare const TRIAGE_EXHAUSTED_ROUNDS = "You have used all available tool rounds. Please provide your final assessment now as the required JSON object. If you could not fully resolve the issue, set correctedData to null and provide a detailed recommendation.";

package/build/system/workflows/mcp-triage/prompts.js

@@ -0,0 +1,159 @@
+"use strict";
+// ── MCP Triage system prompt ────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRIAGE_EXHAUSTED_ROUNDS = exports.TRIAGE_REENTRY_CONTEXT = void 0;
+exports.TRIAGE_SYSTEM_PROMPT = TRIAGE_SYSTEM_PROMPT;
+/**
+ * Build the triage system prompt with the current tool inventory injected.
+ * The toolInventory comes from loadTools() at runtime.
+ */
+function TRIAGE_SYSTEM_PROMPT(toolInventory) {
+    return `You are a dynamic triage controller for Long Tail — a durable workflow system with human-in-the-loop escalation and MCP tool integration. A workflow escalated to a human, and the human has flagged the issue back for AI-assisted remediation.
+
+Your job is to understand the human's intent, the original workflow context, and use MCP tools to fix the problem. When you have the answer, return it as \`correctedData\`.
+
+## The Triage Vortex
+
+You operate inside a **triage vortex** — a separate dimension from the original workflow. The original workflow is paused, waiting. You can take as many steps as needed within this vortex: call tools, create escalations to engineers, wait for guidance, retry. But the moment you have the corrected data, you exit the vortex by returning it. The orchestrator then creates a final escalation targeting the original task with your polished answer.
+
+**Your output IS the delivery mechanism.** When you return \`correctedData\`, the orchestrator:
+1. Creates an escalation on the original task with your corrected data as the primary payload
+2. A human reviews and resolves that escalation
+3. The original workflow re-runs with the fix applied
+
+You do NOT need to submit, POST, deliver, or resolve anything yourself. Just produce the corrected data and return it.
+
+## Available MCP Servers
+
+${toolInventory}
+
+Tool names in function calls are prefixed with the server slug: \`server_slug__tool_name\`.
+
+## Tool Categories
+
+**Compiled Workflows** (\`long_tail_mcp_workflows__*\`):
+Deterministic pipelines hardened from past triage successes. ALWAYS check these first — if a compiled workflow matches the problem, invoke it directly. This is the most efficient path.
+
+**Document Processing** (\`long_tail_document_vision__*\`):
+Image rotation, member info extraction, content translation, member validation. Use for document-related issues.
+
+**Human Queue** (\`long_tail_human_queue__*\`):
+Create escalations within the triage vortex when you need human help (e.g., asking an engineer to install tools). Note: you can also escalate simply by returning \`correctedData: null\` — the orchestrator will create an engineer escalation automatically. Using human-queue tools gives you more control over routing but is usually unnecessary.
+
+**Database Query** (\`long_tail_db__*\`):
+Read-only queries against tasks, escalations, processes, workflow types, system health. Use to investigate context.
+
+**Workflow Compiler** (\`long_tail_workflow_compiler__*\`):
+Convert this triage execution into a compiled YAML workflow after solving the problem.
+
+**HTTP Fetch** (\`long_tail_http_fetch__*\`):
+Fetch external data needed during investigation. Not for delivering results — your JSON response handles that.
+
+**Telemetry** (\`long_tail_telemetry__*\`):
+Honeycomb trace links for debugging.
+
+**External servers**: Any user-registered MCP servers also appear in the tool list.
+
+## Decision Framework
+
+**Step 1 — Read the resolver's notes.**
+The \`resolverPayload\` contains the human's intent:
+- \`notes\`: free-text description of the problem or instruction
+- \`_lt.needsTriage\`: true (this is why you're running)
+- \`_lt.hint\`: optional short hint
+- There may also be domain-specific fields from the workflow's resolver schema.
+
+**Step 2 — Understand the workflow type.**
+The \`originalWorkflowType\` tells you what kind of workflow is waiting. DO NOT assume any specific workflow type. The \`escalationPayload\` shows what the workflow reported when it escalated.
+
+**Step 3 — Choose your approach.**
+
+For simple intent (approval, rejection, basic pass-through):
+→ Return correctedData immediately. No tool calls needed.
+→ Set \`directResolution: true\` — this tells the orchestrator to bypass human review and directly re-run the original workflow with your correctedData. Use this when the human's intent is unambiguous (e.g., "I approve", "looks good", "reject this").
+
+For investigation or remediation:
+1. Check compiled workflows first: \`long_tail_mcp_workflows__list_workflows\`
+2. If a match exists: \`long_tail_mcp_workflows__invoke_workflow\`
+3. If no compiled solution: use domain-specific tools (vision, db, etc.)
+4. If you lack the right tools: return \`correctedData: null\` with a recommendation — the orchestrator will escalate to engineering
+
+For re-entry after engineer guidance (when an engineer responds to your escalation):
+→ They may say "tools are ready" or provide specific guidance. Re-check available tools and proceed.
+
+**Step 4 — Return corrected data.**
+
+CRITICAL: Your \`correctedData\` becomes \`envelope.resolver\` when the original workflow is re-invoked.
+
+- Approval workflows expect: \`{ approved: true }\` or \`{ approved: false }\`
+- Data correction workflows expect: the corrected field values that REPLACE the originals
+- The original workflow's escalation data is in \`escalationPayload\` — use it to understand what fields exist
+- Put the CORRECTED version in the SAME field name as the original. For example, if \`escalationPayload.content\` was in Spanish, set \`correctedData.content\` to the English translation — do NOT create a new \`translatedContent\` field. The correctedData should be a drop-in replacement.
+- When tools return references (e.g., \`rotated_ref\` from \`rotate_page\`), use the EXACT reference returned — do NOT invent filenames. The \`rotate_page\` tool handles cleanup of the original file automatically.
+
+## Credential Tokens
+Values formatted as \`eph:v1:<label>:<id>\` are opaque credential tokens provided by human operators.
+NEVER modify, decode, split, or log these values. Pass them exactly as received into tool arguments.
+They are automatically resolved at execution time.
+
+Return ONLY a JSON object (no markdown fences, no explanation outside the JSON):
+{
+  "diagnosis": "What you found and what you did",
+  "actions_taken": ["Step 1", "Step 2"],
+  "correctedData": { ... the corrected fields for the original workflow ... },
+  "directResolution": false,
+  "confidence": 0.0-1.0,
+  "recommendation": "Optional: suggest pipeline improvements or recommend compiling this into a workflow"
+}
+
+For simple pass-through (approval, rejection, basic acknowledgment):
+{
+  "diagnosis": "Human approved — pass-through",
+  "actions_taken": [],
+  "correctedData": { "approved": true },
+  "directResolution": true,
+  "confidence": 1.0
+}
+
+If you performed useful work but want a human to review before it goes back to the original workflow, STILL return the correctedData and set \`needsHumanReview: true\`:
+{
+  "diagnosis": "What you found and did",
+  "actions_taken": ["Step 1", "Step 2"],
+  "correctedData": { ... your results ... },
+  "needsHumanReview": true,
+  "confidence": 0.7,
+  "recommendation": "Translation completed — human should verify quality before approval"
+}
+
+Only return \`correctedData: null\` when you truly could NOT produce any useful output:
+{
+  "diagnosis": "What you found and tried",
+  "actions_taken": ["Step 1", "Step 2"],
+  "correctedData": null,
+  "confidence": 0,
+  "recommendation": "Specific guidance: what tool or capability is needed"
+}
+
+## Rules
+- Match effort to complexity. Simple approvals = simple responses.
+- Prefer compiled workflows over raw tool calls.
+- Return tool errors as data — adapt, don't crash.
+- Never fabricate data. If uncertain, use tools to verify.
+- If a tool call fails, try an alternative approach before giving up.
+- **If you successfully produced corrected data (e.g., translated content, rotated image), ALWAYS include it in \`correctedData\` — even if an unrelated step failed afterward.** Do not discard good work.
+- Do NOT use \`claim_and_resolve\` or \`resolve_escalation\` on the ORIGINAL escalation — the orchestrator handles that when you return correctedData.
+- Do NOT use HTTP tools to "submit" or "deliver" results. Your JSON response IS the delivery.`;
+}
+// ── Re-entry context (engineer responded to triage escalation) ──────────────
+exports.TRIAGE_REENTRY_CONTEXT = `\
+An engineer has reviewed this issue and provided guidance:
+%RESOLVER_JSON%
+
+IMPORTANT: If the engineer says new tools or MCP servers were installed, \
+re-check available tools — your tool inventory may have expanded since the \
+last attempt. If they say "ready" or "try again", proceed with remediation.`;
+// ── Exhausted tool rounds ──────────────────────────────────────────────────
+exports.TRIAGE_EXHAUSTED_ROUNDS = `\
+You have used all available tool rounds. Please provide your final assessment \
+now as the required JSON object. If you could not fully resolve the issue, set \
+correctedData to null and provide a detailed recommendation.`;

package/build/system/workflows/mcp-triage/response-builders.d.ts

@@ -0,0 +1,17 @@
+import type { LTReturn } from '../../../types';
+import type { TriageContext } from './types';
+export declare function buildMilestones(toolCallCount: number): {
+    name: string;
+    value: string;
+}[];
+export declare function buildDirectResolutionReturn(ctx: TriageContext, parsed: Record<string, any>, correctedData: Record<string, any>, rerunId: string, toolCallCount: number, milestones: Array<{
+    name: string;
+    value: string;
+}>): LTReturn;
+export declare function buildVortexUnwoundReturn(ctx: TriageContext, parsed: Record<string, any>, correctedData: Record<string, any>, toolCallCount: number, milestones: Array<{
+    name: string;
+    value: string;
+}>): LTReturn;
+export declare function buildUnresolvedReturn(ctx: TriageContext, parsed: Record<string, any>, toolCallCount: number): LTReturn;
+export declare function stripJsonComments(text: string): string;
+export declare function parseTriageResponse(content: string): Record<string, any>;

package/build/system/workflows/mcp-triage/response-builders.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMilestones = buildMilestones;
+exports.buildDirectResolutionReturn = buildDirectResolutionReturn;
+exports.buildVortexUnwoundReturn = buildVortexUnwoundReturn;
+exports.buildUnresolvedReturn = buildUnresolvedReturn;
+exports.stripJsonComments = stripJsonComments;
+exports.parseTriageResponse = parseTriageResponse;
+// ── Milestones ────────────────────────────────────────────────
+function buildMilestones(toolCallCount) {
+    return [
+        { name: 'triage', value: 'completed' },
+        { name: 'triage_method', value: toolCallCount > 0 ? 'llm_with_tools' : 'llm_direct' },
+        { name: 'tool_calls', value: String(toolCallCount) },
+    ];
+}
+// ── Return builders ───────────────────────────────────────────
+function buildDirectResolutionReturn(ctx, parsed, correctedData, rerunId, toolCallCount, milestones) {
+    return {
+        type: 'return',
+        data: {
+            triaged: true, exitedVortex: true, directResolution: true,
+            targetedOriginalTask: ctx.originalTaskId,
+            hasCorrectedData: true, rerunWorkflowId: rerunId, correctedData,
+            originalWorkflowType: ctx.originalWorkflowType,
+            originalTaskQueue: ctx.originalTaskQueue,
+            originId: ctx.originId,
+            diagnosis: parsed.diagnosis, actions_taken: parsed.actions_taken,
+            tool_calls_made: toolCallCount, confidence: parsed.confidence,
+        },
+        milestones: [...milestones, { name: 'vortex', value: 'direct_resolution' }],
+    };
+}
+function buildVortexUnwoundReturn(ctx, parsed, correctedData, toolCallCount, milestones) {
+    return {
+        type: 'return',
+        data: {
+            triaged: true, exitedVortex: true, directResolution: false,
+            targetedOriginalTask: ctx.originalTaskId || null,
+            hasCorrectedData: true, correctedData,
+            originalWorkflowType: ctx.originalWorkflowType,
+            originalTaskQueue: ctx.originalTaskQueue,
+            originId: ctx.originId,
+            diagnosis: parsed.diagnosis, actions_taken: parsed.actions_taken,
+            tool_calls_made: toolCallCount, confidence: parsed.confidence,
+        },
+        milestones: [...milestones, { name: 'vortex', value: 'unwound' }],
+    };
+}
+function buildUnresolvedReturn(ctx, parsed, toolCallCount) {
+    return {
+        type: 'return',
+        data: {
+            triaged: true, exitedVortex: false, hasCorrectedData: false, correctedData: null,
+            originId: ctx.originId,
+            originalWorkflowType: ctx.originalWorkflowType,
+            originalTaskQueue: ctx.originalTaskQueue,
+            originalTaskId: ctx.originalTaskId,
+            diagnosis: parsed.diagnosis || 'AI triage could not determine a fix',
+            actions_taken: parsed.actions_taken || [],
+            tool_calls_made: toolCallCount,
+            recommendation: parsed.recommendation || '',
+            confidence: parsed.confidence || 0,
+        },
+        milestones: [
+            { name: 'triage', value: 'completed' },
+            { name: 'triage_method', value: toolCallCount > 0 ? 'llm_with_tools' : 'llm_direct' },
+            { name: 'tool_calls', value: String(toolCallCount) },
+            { name: 'vortex', value: 'unresolved' },
+        ],
+    };
+}
+// ── JSON parsing ──────────────────────────────────────────────
+function stripJsonComments(text) {
+    return text.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+}
+function parseTriageResponse(content) {
+    const cleaned = content
+        .replace(/^```(?:json)?\s*/m, '')
+        .replace(/\s*```$/m, '')
+        .trim();
+    const noComments = stripJsonComments(cleaned);
+    try {
+        return JSON.parse(noComments);
+    }
+    catch {
+        const jsonMatch = noComments.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                return JSON.parse(jsonMatch[0]);
+            }
+            catch { /* fall through */ }
+        }
+        return { diagnosis: cleaned || 'No response generated', actions_taken: [], correctedData: null, confidence: 0 };
+    }
+}

package/build/system/workflows/mcp-triage/response.d.ts

@@ -0,0 +1,8 @@
+import type { LTEnvelope, LTReturn } from '../../../types';
+import type { TriageResponseDeps } from './types';
+export { parseTriageResponse, stripJsonComments } from './response-builders';
+/**
+ * Process the LLM's final response and route corrected data
+ * back to the original workflow through the appropriate exit path.
+ */
+export declare function handleFinalResponse(content: string, envelope: LTEnvelope, toolCallCount: number, deps: TriageResponseDeps): Promise<LTReturn>;