@dypai-ai/mcp 1.0.10 → 1.2.0

package/src/tools/trace-summarize.js

@@ -0,0 +1,178 @@
+/**
+ * Summarize a per-node workflow trace for the agent without blowing its
+ * context window.
+ *
+ * The engine returns trace shape:
+ *   { execution_id, workflow: {...}, execution_order: [...],
+ *     nodes: { <id>: { status, duration_ms, output_summary, error?,
+ *                      failure_snapshot?, branch_decision?, events } } }
+ *
+ * Modes:
+ *   - "smart" (default) — success → minimal; failure → focused on failing node
+ *   - "full"            — raw trace (opt-in, for deep dives)
+ *   - "minimal"         — just success/failure + duration + execution_order
+ *
+ * The raw `events[]` array (node-scoped event log) is always dropped from
+ * "smart" and "minimal" — it's redundant with the parsed fields.
+ */
+
+const MAX_FIELD_CHARS = 2000   // per-string truncation threshold
+const MAX_SNAPSHOT_KEYS = 6    // summarize large snapshots into a key outline
+
+function truncateString(s, max = MAX_FIELD_CHARS) {
+  if (typeof s !== "string") return s
+  if (s.length <= max) return s
+  return s.slice(0, max) + `... [truncated ${s.length - max} chars, call dypai_trace with full=true]`
+}
+
+function summarizeValue(v) {
+  if (v == null) return v
+  if (typeof v === "string") return truncateString(v)
+  if (Array.isArray(v)) {
+    if (v.length > MAX_SNAPSHOT_KEYS) {
+      return [...v.slice(0, MAX_SNAPSHOT_KEYS).map(summarizeValue), `... ${v.length - MAX_SNAPSHOT_KEYS} more`]
+    }
+    return v.map(summarizeValue)
+  }
+  if (typeof v === "object") {
+    const keys = Object.keys(v)
+    if (keys.length > MAX_SNAPSHOT_KEYS) {
+      const sample = {}
+      for (const k of keys.slice(0, MAX_SNAPSHOT_KEYS)) sample[k] = summarizeValue(v[k])
+      sample[`_truncated_keys`] = keys.length - MAX_SNAPSHOT_KEYS
+      return sample
+    }
+    const out = {}
+    for (const [k, val] of Object.entries(v)) out[k] = summarizeValue(val)
+    return out
+  }
+  return v
+}
+
+/** Build a hint string from the error message based on common patterns. */
+function hintFromError(err) {
+  const m = String(err?.message || "")
+  if (/relation .* does not exist/i.test(m)) return "Table not found. Check dypai/schema.sql."
+  if (/column .* does not exist/i.test(m)) return "Column not found. Verify the SQL column against the table schema."
+  if (/placeholder|\$\{/i.test(m)) return "Placeholder resolution failed. Inspect node inputs."
+  if (/credential/i.test(m)) return "Credential lookup failed. Check the credential name exists remotely."
+  if (/timeout|timed out/i.test(m)) return "Node timed out. Consider a faster query or raise the node timeout."
+  return null
+}
+
+export function summarizeTrace(trace, mode = "smart") {
+  if (!trace || typeof trace !== "object") return trace
+  if (mode === "full") return trace
+
+  const wf = trace.workflow || {}
+  const execOrder = Array.isArray(trace.execution_order) ? trace.execution_order : []
+  const nodes = trace.nodes || {}
+
+  if (mode === "minimal") {
+    return {
+      execution_id: trace.execution_id,
+      status: wf.status,
+      duration_ms: wf.duration_ms,
+      execution_order: execOrder,
+      error: wf.error || undefined,
+    }
+  }
+
+  // "smart" mode
+  const failed = wf.status === "failed"
+  const failedNodeId = failed
+    ? Object.values(nodes).find(n => n && n.status === "failed")?.node_id
+    : null
+
+  const nodeSummaries = []
+  for (const id of execOrder) {
+    const n = nodes[id]
+    if (!n) continue
+
+    const base = {
+      id: n.node_id,
+      type: n.node_type,
+      status: n.status,
+      duration_ms: n.duration_ms,
+    }
+
+    // On success: keep it tiny — just id/type/status/duration
+    if (n.status === "completed") {
+      // include output_summary only if it's the LAST node (likely the final result)
+      if (id === execOrder[execOrder.length - 1] && n.output_summary) {
+        base.output_summary = summarizeValue(n.output_summary)
+      }
+      nodeSummaries.push(base)
+      continue
+    }
+
+    // On the failing node: include full detail (error + snapshot outline)
+    if (n.status === "failed") {
+      base.error = {
+        message: truncateString(n.error?.message),
+        type: n.error?.type,
+        stack: truncateString(n.error?.stack, 800),
+      }
+      // failure_snapshot: reduce to a key outline — not full values
+      if (n.failure_snapshot) {
+        const snap = n.failure_snapshot
+        base.failure_snapshot = {
+          inputs_keys: Object.keys(snap.nodes_inputs || {}),
+          results_keys: Object.keys(snap.nodes_results || {}),
+          hint: "Use dypai_trace(execution_id, full=true) to see full snapshot values.",
+        }
+      }
+      if (n.branch_decision) base.branch_decision = summarizeValue(n.branch_decision)
+      nodeSummaries.push(base)
+      continue
+    }
+
+    nodeSummaries.push(base)
+  }
+
+  const summary = {
+    execution_id: trace.execution_id,
+    success: wf.status === "completed",
+    status: wf.status,
+    duration_ms: wf.duration_ms,
+    failed_at: failedNodeId,
+    execution_order: execOrder,
+    nodes: nodeSummaries,
+  }
+
+  if (failed) {
+    const failedNode = nodes[failedNodeId]
+    const hint = hintFromError(failedNode?.error)
+    if (hint) summary.hint = hint
+    summary.next_step =
+      `Inspect the failing node's input above. For full snapshot use: dypai_trace(execution_id='${trace.execution_id}', full=true).`
+  }
+
+  return summary
+}
+
+/**
+ * Given a test_workflow response that includes a `trace` field (from the
+ * updated remote MCP), apply summarization. Safe no-op if no trace present.
+ */
+export function summarizeTestWorkflowResponse(response, mode = "smart") {
+  if (!response || typeof response !== "object") return response
+  if (!response.trace) return response  // older engine or trace fetch failed
+  return {
+    ...response,
+    trace: summarizeTrace(response.trace, mode),
+  }
+}
+
+/**
+ * Summarize a dypai_trace response. The response may contain either:
+ *   - { execution_id, trace: {...} }            (single trace)
+ *   - { executions: [...] }                     (listing, already compact)
+ */
+export function summarizeDypaiTraceResponse(response, mode = "smart") {
+  if (!response || typeof response !== "object") return response
+  if (response.trace) {
+    return { ...response, trace: summarizeTrace(response.trace, mode) }
+  }
+  return response
+}