denpex-mcp 0.2.5 → 0.2.7

package/README.md

@@ -19,7 +19,10 @@ straight off disk and hands back the root cause and the fix.
 Sign in at **[denpex.com/dashboard](https://denpex.com/dashboard) → API Keys** and create a key (`dpx_…`).
 The key unlocks authenticated cloud diagnosis, your diagnosis history, quota, and fleet
 incidents. *Without a key, `diagnose_crash` uses the same canonical anonymous engine as
-the homepage's three free diagnoses. Set `DENPEX_LOCAL=1` explicitly for zero-egress;
+the homepage's three free diagnoses. Anonymous clarifications reuse the server-issued,
+log-bound refinement token automatically (or accept it explicitly after an MCP restart),
+so answering Denpex does not spend another diagnosis and cannot be forged with a public
+boolean header. Set `DENPEX_LOCAL=1` explicitly for zero-egress;
 `lookup_failure` and `analyze_cascade` remain available from the bundled offline data.*
 
 ### 2. Add it to your client
@@ -103,7 +106,7 @@ errors is cloud-only and simply unavailable offline.
 
 | Tool | What it does | Needs |
 |------|--------------|-------|
-| `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. Also accepts `telemetry` (dmesg / nvidia-smi / ibstat), `codeContext` and `topologyMap`. | canonical cloud by default; explicit offline mode |
+| `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. Also accepts `telemetry` (dmesg / nvidia-smi / ibstat), `codeContext`, `topologyMap`, typed `operatorAnswers`, and (after an anonymous MCP restart) the prior `refinementToken`. | canonical cloud by default; explicit offline mode |
 | `lookup_failure` | Search the bundled encyclopedia (300+ classes) by code/keyword/symptom. | works offline |
 | `analyze_cascade` | Find the culprit rank in a distributed hang; route Xid faults. | works offline |
 | `submit_fix_outcome` | Report whether a fix worked. **This is what makes the next diagnosis better.** | API key |
@@ -154,7 +157,7 @@ Two fields deserve attention when you write the agent loop:
 ```bash
 npm install
 npm run build      # regenerates the offline corpus, then bundles dist/index.js
-npm test           # 88 unit + protocol-integration tests
+npm test           # 111 unit + protocol-integration tests
 npm run inspector  # interactive protocol inspector (MCP Inspector)
 ```
 

package/dist/index.js

@@ -106,6 +106,7 @@ var DenpexClient = class {
     const headers = { Accept: "application/json" };
     if (this.config.apiKey) headers["X-Denpex-Key"] = this.config.apiKey;
     if (body !== void 0) headers["Content-Type"] = "application/json";
+    Object.assign(headers, opts.headers ?? {});
     let res;
     try {
       res = await fetch(`${this.config.apiUrl}${path2}`, {
@@ -139,6 +140,7 @@ var DenpexClient = class {
 
 // src/tools/diagnose.ts
 import { z as z2 } from "zod";
+import { createHash } from "crypto";
 
 // src/logs.ts
 import { promises as fs } from "fs";
@@ -697,6 +699,10 @@ function viewFromCloud(payload, note) {
     steps: asArray(fix.steps),
     evidence: asArray(fix.evidence),
     clarifying: asArray(fix.clarifyingQuestions),
+    clarifyingChoices: objArray(fix.clarifyingChoices),
+    evidenceRequests: objArray(fix.evidenceRequests),
+    awaitingEvidence: fix.awaitingEvidence === true,
+    refinementToken: str(payload.refinementToken) ?? void 0,
     advisories: [
       ...advisory.map((a) => `${(a.summary ?? "Advisory").trim()}${a.action ? ` \u2014 ${a.action}` : ""}`),
       ...advisoriesFromAdvanced(payload.advanced)
@@ -740,6 +746,9 @@ function viewFromLocal(r, note) {
     steps: r.steps ?? [],
     evidence: r.evidence ?? [],
     clarifying: [],
+    clarifyingChoices: [],
+    evidenceRequests: [],
+    awaitingEvidence: false,
     advisories: (r.detectors ?? []).map((d) => `${d.severity.toUpperCase()} \u2014 ${d.summary}`),
     // The offline engine has no advisory array, no falsification contracts, no
     // community/research grounding and no ranked-hypotheses ledger. Emit the fields as
@@ -844,7 +853,33 @@ function renderDiagnosis(v) {
   }
   if (v.priorIncident) lines.push("", `**You hit this before:** ${v.priorIncident}`);
   if (v.costHeadline) lines.push("", `**Cost:** ${v.costHeadline}`);
-  if (v.clarifying.length) {
+  if (v.evidenceRequests.length) {
+    lines.push("", "**Collect this evidence next (the selection itself was not treated as evidence):**");
+    for (const request of v.evidenceRequests) {
+      if (request.label) lines.push(`- **${request.label}**${request.why ? ` \u2014 ${request.why}` : ""}`);
+      if (request.command) lines.push("```bash", request.command, "```");
+    }
+    lines.push("Paste the complete output back into the original log evidence and call `diagnose_crash` again.");
+  }
+  if (v.clarifyingChoices.length) {
+    lines.push("", "**To narrow it down, answer any of these:**");
+    for (const q of v.clarifyingChoices) {
+      if (!q?.question) continue;
+      lines.push("", `_${q.question}_`);
+      for (const o of q.options ?? []) {
+        if (!o?.label) continue;
+        const rec = o.recommended && q.kind === "action" ? " **(Recommended)**" : "";
+        const detail = o.detail ? ` \u2014 ${o.detail}` : "";
+        lines.push(`- \`${o.id ?? o.label}\` ${o.label}${rec}${detail}`);
+        if (o.command) lines.push(`  - Evidence command: \`${o.command}\``);
+      }
+      if (q.kind === "fact") {
+        lines.push(`  _Answer only from what was actually observed. If it is not known, say so rather than guessing \u2014 a wrong answer here sends the diagnosis the wrong way._`);
+      }
+      if (q.command) lines.push(`  _Recommended check:_ \`${q.command}\``);
+    }
+    lines.push("", "_Call `diagnose_crash` again with the same original logs and an `operatorAnswers` array containing questionId, optionId, kind, question, and answer. Send the full answer history on every round. The anonymous refinement token is cached automatically; if the MCP process restarts, pass the `refinementToken` from structured output._");
+  } else if (v.clarifying.length) {
     lines.push("", "**To narrow it down, tell me:**");
     v.clarifying.forEach((q) => lines.push(`- ${q}`));
     lines.push("", "_Use `ask_followup` to continue this conversation._");
@@ -903,6 +938,30 @@ var diagnosisOutputShape = {
   steps: z.array(z.string()).describe("The full prescriptive fix ladder, in order."),
   evidence: z.array(z.string()).describe("Literal lines quoted from the submitted log that support this verdict. An EMPTY array on a high-confidence verdict means the engine could not quote its own log \u2014 weigh it accordingly."),
   clarifying: z.array(z.string()).describe("Discriminating questions. Answer them with `ask_followup` to narrow the verdict."),
+  clarifyingChoices: z.array(z.object({
+    id: z.string().optional(),
+    kind: z.enum(["fact", "action"]).optional().describe("`fact` = what was observed; `action` = what you could run. Only `action` questions carry a recommended option \u2014 a recommendation on a question of fact would bias the evidence the next verdict is built on."),
+    question: z.string().optional(),
+    options: z.array(z.object({
+      id: z.string().optional(),
+      label: z.string().optional(),
+      detail: z.string().optional(),
+      recommended: z.boolean().optional(),
+      command: z.string().optional()
+    })).optional(),
+    allowOther: z.boolean().optional(),
+    command: z.string().optional().describe("The exact command behind the recommended option.")
+  })).optional().describe("Structured form of `clarifying`: call `diagnose_crash` again with the same logs plus a typed `operatorAnswers` array. Answer FACT questions only from what was observed; selecting an ACTION is intent to collect evidence, not the check result."),
+  evidenceRequests: z.array(z.object({
+    questionId: z.string().optional(),
+    optionId: z.string().optional(),
+    label: z.string().optional(),
+    command: z.string().optional(),
+    why: z.string().optional(),
+    pasteBack: z.string().optional()
+  })).describe("Exact evidence checks selected by the operator. Run them and paste back the actual output; the selection was not counted as evidence."),
+  awaitingEvidence: z.boolean().optional(),
+  refinementToken: z.string().optional().describe("Anonymous-only capability for refining this exact original log. Normally cached by the MCP server; pass it back after a process restart."),
   advisories: z.array(z.string()).describe("Human-readable one-liners, severity-sorted."),
   advisory: z.array(advisorySchema).describe("Structured cross-cutting advisories, severity-sorted (critical first)."),
   contradictions: z.array(z.string()).describe("What the engine ruled OUT and why \u2014 the falsification trail."),
@@ -958,6 +1017,19 @@ function fmtDate(ms) {
 }
 
 // src/tools/diagnose.ts
+var anonymousRefinementTokens = /* @__PURE__ */ new Map();
+function refinementKey(logs) {
+  return createHash("sha256").update(logs).digest("hex");
+}
+function rememberRefinement(key, token) {
+  anonymousRefinementTokens.delete(key);
+  anonymousRefinementTokens.set(key, token);
+  while (anonymousRefinementTokens.size > 50) {
+    const oldest = anonymousRefinementTokens.keys().next().value;
+    if (!oldest) break;
+    anonymousRefinementTokens.delete(oldest);
+  }
+}
 function registerDiagnose(server, ctx) {
   server.registerTool(
     "diagnose_crash",
@@ -982,17 +1054,29 @@ function registerDiagnose(server, ctx) {
           "Hardware telemetry captured from the failing node. Keys the engine reads: `dmesg` (output of `dmesg -T`), `nvidia_smi` (`nvidia-smi -q`), `ibstat`. Sending these turns an ambiguous NCCL timeout into a specific Xid/ECC verdict \u2014 and, just as importantly, lets the engine EXONERATE the GPU when the counters are clean."
         ),
         codeContext: z2.record(z2.string()).optional().describe("Relevant source files as { path: contents }. Only send real files you read \u2014 the engine never fabricates code context, and neither should you."),
-        topologyMap: z2.record(z2.array(z2.string())).optional().describe("Rank \u2192 node placement as { nodeName: [rank, ...] }, e.g. from the launcher. Lets the engine map a failing rank to a physical node and GPU.")
+        topologyMap: z2.record(z2.array(z2.string())).optional().describe("Rank \u2192 node placement as { nodeName: [rank, ...] }, e.g. from the launcher. Lets the engine map a failing rank to a physical node and GPU."),
+        operatorAnswers: z2.array(z2.object({
+          questionId: z2.string().optional(),
+          optionId: z2.string().optional(),
+          kind: z2.enum(["fact", "action"]).optional(),
+          question: z2.string().optional(),
+          answer: z2.string()
+        })).max(12).optional().describe("Answers from a previous diagnose_crash result. Send the full answer history with the same original logs. Selecting an ACTION asks Denpex for that evidence; it is not treated as the result of the check."),
+        refinementToken: z2.string().max(160).optional().describe("Anonymous-only capability returned by the prior diagnosis. Normally cached automatically in this MCP process; pass it explicitly after a process restart.")
       },
       outputSchema: diagnosisOutputShape
     },
-    async ({ logs, file, dir, jobName, runtimeHours, gpuRate, telemetry, codeContext, topologyMap }) => {
+    async ({ logs, file, dir, jobName, runtimeHours, gpuRate, telemetry, codeContext, topologyMap, operatorAnswers, refinementToken }) => {
       try {
         const resolved = await resolveLogs({ logs, file, dir });
         assertEnoughLog(resolved.text);
         const prepared = applyPrivacy(condenseLogs(resolved.text), ctx.config.privacy);
+        const preparedRefinementKey = refinementKey(prepared);
         const sourceNote = resolved.source === "inline" ? void 0 : `Read \`${resolved.source}\`.`;
         if (ctx.config.local) {
+          if (operatorAnswers?.length) {
+            return toolText("Offline mode cannot re-run the evidence-bound conversational reasoner. Run the selected check, append its actual output to the original logs, and call `diagnose_crash` again. No action selection was treated as evidence.", true);
+          }
           const result = localDiagnose(prepared);
           const localView = viewFromLocal(result, sourceNote);
           return toolResult(renderDiagnosis(localView), structuredDiagnosis(localView));
@@ -1013,6 +1097,10 @@ function registerDiagnose(server, ctx) {
         const preparedCodeContext = codeContext ? scrubKeys(codeContext, (v) => scrub(String(v))) : void 0;
         const preparedTopologyMap = topologyMap ? scrubKeys(topologyMap, (ranks) => (Array.isArray(ranks) ? ranks : []).map((r) => scrub(String(r)))) : void 0;
         const endpoint = ctx.config.apiKey ? "/api/diagnose" : "/api/diagnose/anon";
+        const activeRefinementToken = refinementToken ?? anonymousRefinementTokens.get(preparedRefinementKey);
+        if (operatorAnswers?.length && !ctx.config.apiKey && !activeRefinementToken) {
+          return toolText("Anonymous clarification is missing the refinement token from the prior diagnosis. Re-run diagnose_crash with the same original logs, then answer the questions it returns. No answer was submitted or charged.", true);
+        }
         const payload = await ctx.client.request(endpoint, {
           method: "POST",
           body: {
@@ -1022,13 +1110,23 @@ function registerDiagnose(server, ctx) {
             gpuRate,
             ...preparedTelemetry ? { telemetry: preparedTelemetry } : {},
             ...preparedCodeContext ? { codeContext: preparedCodeContext } : {},
-            ...preparedTopologyMap ? { topologyMap: preparedTopologyMap } : {}
+            ...preparedTopologyMap ? { topologyMap: preparedTopologyMap } : {},
+            ...operatorAnswers?.length ? { operatorAnswers } : {}
           },
+          ...operatorAnswers?.length && !ctx.config.apiKey && activeRefinementToken ? {
+            headers: {
+              "X-Denpex-Followup": "1",
+              "X-Denpex-Refinement": activeRefinementToken
+            }
+          } : {},
           // The server budgets up to 290s for the deep/LLM path. Keep a small
           // transport buffer so MCP never discards a result that completed inside
           // the server's supported window.
           timeoutMs: 32e4
         });
+        if (!ctx.config.apiKey && typeof payload.refinementToken === "string" && payload.refinementToken) {
+          rememberRefinement(preparedRefinementKey, payload.refinementToken);
+        }
         const view = viewFromCloud(payload, sourceNote);
         return toolResult(renderDiagnosis(view), structuredDiagnosis(view));
       } catch (e) {
@@ -1726,7 +1824,7 @@ function registerPrompts(server) {
 
 // src/version.ts
 var SERVER_NAME = "denpex";
-var SERVER_VERSION = "0.2.5";
+var SERVER_VERSION = "0.2.7";
 
 // src/server.ts
 function createServer() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "denpex-mcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Denpex MCP server — diagnose GPU/ML training failures (CUDA OOM, NCCL timeouts, Xid faults, NaN loss) from Claude Desktop, Cursor, or Claude Code, with optional explicit zero-egress mode.",
   "type": "module",
   "license": "MIT",