@denpex/sdk 0.8.0 → 0.8.2

package/README.md

@@ -1,49 +1,50 @@
-# @denpex/sdk
-
-TypeScript/JavaScript client for the [Denpex](https://denpex.com) API — diagnose GPU training
-failures from logs, report fix outcomes, and check your plan quota. Zero runtime dependencies,
-Node ≥ 18.
-
-## Install
-
-```bash
-npm install @denpex/sdk
-```
-
-## Quick start
-
-```ts
-import { DenpexClient } from "@denpex/sdk";
-
-const denpex = new DenpexClient({ apiKey: process.env.DENPEX_API_KEY! });
-
-// Diagnose a training log
-const result = await denpex.diagnose(logText, { jobName: "llama3-405b-pretrain" });
-console.log(result.meta?.failureType, result.meta?.confidence);
-console.log(result.fix?.summary);
-console.log(result.fix?.action);
-
-// Close the accuracy flywheel by reporting whether the fix worked
-await denpex.feedback(result.diagnosisId, "worked");
-
-// Check remaining headroom for the key's plan
-const quota = await denpex.quota();
-console.log(quota.quota);
-```
-
-Create an API key at <https://denpex.com/dashboard>. It is sent as the `X-Denpex-Key` header.
-
-## API
-
-| Method | Description |
-|---|---|
-| `new DenpexClient({ apiKey, baseUrl?, timeoutMs? })` | Construct a client. `baseUrl` defaults to `https://api.denpex.com`; the default 320-second timeout covers the server's 290-second deep path. |
-| `diagnose(logs, opts?)` | `POST /api/diagnose` — returns the diagnosis (failure type, confidence, root cause, fix, evidence). |
-| `feedback(diagnosisId, outcome, note?)` | `POST /api/diagnose/feedback` — `outcome` is `"worked"` or `"did_not_work"`. |
-| `quota()` | `GET /api/diagnose/quota` — remaining diagnoses for the key's plan. |
-
-Errors throw `DenpexError` with the HTTP status and server message.
-
-## License
-
-Proprietary. © Denpex. Use of this SDK is governed by your Denpex subscription agreement.
+# @denpex/sdk
+
+TypeScript/JavaScript client for the [Denpex](https://denpex.com) API — diagnose GPU training
+failures from logs, report fix outcomes, and check your plan quota. Zero runtime dependencies,
+Node ≥ 18.
+
+## Install
+
+```bash
+npm install @denpex/sdk
+```
+
+## Quick start
+
+```ts
+import { DenpexClient } from "@denpex/sdk";
+
+const denpex = new DenpexClient({ apiKey: process.env.DENPEX_API_KEY! });
+
+// Diagnose a training log
+const result = await denpex.diagnose(logText, { jobName: "llama3-405b-pretrain" });
+console.log(result.meta?.failureType, result.meta?.confidence);
+console.log(result.fix?.summary);
+console.log(result.fix?.action);
+
+// Close the accuracy flywheel by reporting whether the fix worked
+await denpex.feedback(result.diagnosisId, "worked");
+
+// Check remaining headroom for the key's plan
+const quota = await denpex.quota();
+console.log(quota.quota);
+```
+
+Create an API key at <https://denpex.com/dashboard>. It is sent as the `X-Denpex-Key` header.
+
+## API
+
+| Method | Description |
+|---|---|
+| `new DenpexClient({ apiKey, baseUrl?, timeoutMs? })` | Construct a client. `baseUrl` defaults to `https://api.denpex.com`; the default 320-second timeout covers the server's 290-second deep path. |
+| `diagnose(logs, opts?)` | `POST /api/diagnose` — returns the diagnosis (failure type, confidence, root cause, fix, evidence). |
+| `refine(logs, operatorAnswers, opts?)` | Re-run the same canonical diagnosis with typed answers from `clarifyingChoices`. Send the full answer history; action selections become evidence requests, not evidence. |
+| `feedback(diagnosisId, outcome, note?)` | `POST /api/diagnose/feedback` — `outcome` is `"worked"` or `"did_not_work"`. |
+| `quota()` | `GET /api/diagnose/quota` — remaining diagnoses for the key's plan. |
+
+Errors throw `DenpexError` with the HTTP status and server message.
+
+## License
+
+Proprietary. © Denpex. Use of this SDK is governed by your Denpex subscription agreement.

package/dist/client.d.ts

@@ -4,7 +4,7 @@ export interface DenpexClientOptions {
     baseUrl?: string;
     /** Override fetch (tests, custom agents). Defaults to globalThis.fetch. */
     fetchImpl?: typeof fetch;
-    /** Per-request timeout in ms (AbortController). Default 320s — server deep-path ceiling is 290s. */
+    /** Per-request timeout in ms (AbortController). Default 320s. The server deep-path ceiling is 290s. */
     timeoutMs?: number;
 }
 export interface DiagnoseOptions {
@@ -18,18 +18,27 @@ export interface DiagnoseOptions {
     codeContext?: Record<string, unknown>;
     /** Client-side signature matches (e.g. from denpex_lite) so Tier 0 starts from evidence. */
     signatures?: unknown;
+    /** Prior clarification answers. Keep these typed and outside `logs`. */
+    operatorAnswers?: OperatorAnswerInput[];
+}
+export interface OperatorAnswerInput {
+    questionId?: string;
+    optionId?: string;
+    kind?: 'fact' | 'action';
+    question?: string;
+    answer: string;
 }
 export interface DiagnoseMeta {
     failureType?: string;
     confidence?: number;
     source?: string;
     tier?: number;
-    /** Engine build stamp — compare across surfaces to detect a stale deploy. */
+    /** Engine build stamp. Compare across surfaces to detect a stale deploy. */
     engineVersion?: string;
 }
 /**
  * The known response fields. The engine attaches additional sections as it
- * grows (forensics, advisories, execution plans) — they pass through untyped
+ * grows (forensics, advisories, execution plans). They pass through untyped
  * rather than being silently dropped, so SDK users always receive everything
  * the API returned.
  */
@@ -42,7 +51,7 @@ export interface DiagnoseMeta {
  * few lines, so treat the node as the stronger signal of the two.
  *
  * `analyzedLines` < `totalLines` means the paste exceeded the window the engine
- * reads — the verdict covers only what was analysed.
+ * reads. The verdict covers only what was analysed.
  */
 export interface DiagnoseInitiator {
     rank?: number | null;
@@ -52,11 +61,53 @@ export interface DiagnoseInitiator {
     totalLines?: number | null;
     analyzedLines?: number | null;
 }
+export interface ClarifyingOption {
+    id?: string;
+    label?: string;
+    detail?: string;
+    /**
+     * Present only on an `action` question. The engine never recommends an answer to a
+     * question of fact: a recommendation there returns the answer that was hinted at
+     * rather than the one that happened, and the next verdict is built on an
+     * observation nobody made. Render this marker only when `kind === 'action'`.
+     */
+    recommended?: boolean;
+    /** Exact evidence command represented by this option on an action question. */
+    command?: string;
+}
+export interface ClarifyingQuestion {
+    id?: string;
+    /** `fact` = what the operator observed; `action` = what they could run next. */
+    kind?: 'fact' | 'action';
+    question?: string;
+    options?: ClarifyingOption[];
+    allowOther?: boolean;
+    /** The exact command behind the recommended option, on `action` questions. */
+    command?: string;
+}
 export interface DiagnoseResponse {
     fix?: {
         summary?: string;
         action?: string;
         evidence?: unknown[];
+        /**
+         * Set when the engine declined to name one cause and is asking for evidence
+         * instead. Answer with the option ids to get a sharper diagnosis. `inviteFollowup`
+         * is the flag that says this happened.
+         */
+        clarifyingChoices?: ClarifyingQuestion[];
+        /** Plain-text form of the same questions, for older callers. */
+        clarifyingQuestions?: string[];
+        inviteFollowup?: boolean;
+        evidenceRequests?: Array<{
+            questionId: string;
+            optionId: string;
+            label: string;
+            command: string;
+            why?: string;
+            pasteBack?: string;
+        }>;
+        awaitingEvidence?: boolean;
         [k: string]: unknown;
     };
     meta?: DiagnoseMeta;
@@ -88,9 +139,11 @@ export declare class DenpexClient {
     private readonly fetchImpl;
     private readonly timeoutMs;
     constructor(options: DenpexClientOptions);
-    /** Diagnose a training failure from raw logs (20 chars – 256 KB). */
+    /** Diagnose a training failure from raw logs. Oversized input is evidence-selected. */
     diagnose(logs: string, opts?: DiagnoseOptions): Promise<DiagnoseResponse>;
-    /** Report whether a diagnosis worked — this feedback directly improves future priors. */
+    /** Re-run the canonical diagnosis with observed facts or a selected evidence check. */
+    refine(logs: string, operatorAnswers: OperatorAnswerInput[], opts?: Omit<DiagnoseOptions, 'operatorAnswers'>): Promise<DiagnoseResponse>;
+    /** Report whether a diagnosis worked. This feedback directly improves future priors. */
     feedback(diagnosisId: string, outcome: FeedbackOutcome, note?: string): Promise<Record<string, unknown>>;
     /** Remaining diagnosis headroom for this key's plan. */
     quota(): Promise<QuotaResponse>;

package/dist/client.js

@@ -1,5 +1,5 @@
 "use strict";
-// @denpex/sdk — TypeScript client for the Denpex public API.
+// @denpex/sdk: TypeScript client for the Denpex public API.
 //
 // Rewritten 2026-07-20: the previous file was a stub for /v1/{tenant}/incidents
 // routes that do not exist in the api-worker. This client targets the REAL
@@ -15,6 +15,7 @@
 // Zero dependencies. Requires global fetch (Node >= 18 or any browser/worker).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = exports.DenpexClient = exports.DenpexError = void 0;
+const evidence_1 = require("./evidence");
 class DenpexError extends Error {
     constructor(message, status, 
     /** Machine-readable code when the API provides one (e.g. AUTH_REQUIRED, GPU_LIMIT_EXCEEDED). */
@@ -26,7 +27,7 @@ class DenpexError extends Error {
     }
 }
 exports.DenpexError = DenpexError;
-const MIN_LOG_CHARS = 20;
+const MIN_LOG_CHARS = 6;
 const MAX_LOG_CHARS = 256000;
 class DenpexClient {
     constructor(options) {
@@ -37,19 +38,21 @@ class DenpexClient {
         this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
         this.timeoutMs = options.timeoutMs ?? 320000;
         if (!this.fetchImpl)
-            throw new Error('DenpexClient: global fetch not found — Node >= 18 required, or pass fetchImpl');
+            throw new Error('DenpexClient: global fetch not found. Node >= 18 required, or pass fetchImpl');
     }
-    /** Diagnose a training failure from raw logs (20 chars – 256 KB). */
+    /** Diagnose a training failure from raw logs. Oversized input is evidence-selected. */
     async diagnose(logs, opts = {}) {
         if (typeof logs !== 'string' || logs.length < MIN_LOG_CHARS) {
             throw new DenpexError(`logs must be at least ${MIN_LOG_CHARS} characters`, 400);
         }
-        if (logs.length > MAX_LOG_CHARS) {
-            throw new DenpexError(`logs too large (max ${MAX_LOG_CHARS} chars) — send the failing excerpt`, 400);
-        }
-        return this.request('POST', '/api/diagnose', { logs, ...opts });
+        const selected = (0, evidence_1.selectEvidence)(logs, MAX_LOG_CHARS);
+        return this.request('POST', '/api/diagnose', { logs: selected.text, ...opts });
+    }
+    /** Re-run the canonical diagnosis with observed facts or a selected evidence check. */
+    async refine(logs, operatorAnswers, opts = {}) {
+        return this.diagnose(logs, { ...opts, operatorAnswers });
     }
-    /** Report whether a diagnosis worked — this feedback directly improves future priors. */
+    /** Report whether a diagnosis worked. This feedback directly improves future priors. */
     async feedback(diagnosisId, outcome, note) {
         if (!diagnosisId)
             throw new DenpexError('diagnosisId required', 400);
@@ -79,7 +82,11 @@ class DenpexClient {
             }
             catch { /* non-JSON error body */ }
             if (!res.ok) {
-                const message = typeof json.error === 'string' ? json.error : `Denpex API error (status ${res.status})`;
+                const message = typeof json.guidance === 'string'
+                    ? json.guidance
+                    : typeof json.error === 'string'
+                        ? json.error
+                        : `Denpex API error (status ${res.status})`;
                 throw new DenpexError(message, res.status, typeof json.code === 'string' ? json.code : undefined);
             }
             return json;

package/dist/evidence.d.ts

@@ -0,0 +1,4 @@
+export declare function selectEvidence(logs: string, max: number): {
+    text: string;
+    truncated: boolean;
+};

package/dist/evidence.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectEvidence = selectEvidence;
+const EVIDENCE_RE = /error|fail|fatal|traceback|exception|assert|panic|segfault|xid|nvrm|ecc|fallen off the bus|nccl|cuda|oom|out of memory|timeout|nan\b|\binf\b|node_fail|killed|terminated|version|driver|kernel|container|slurm|kubernetes|rank|node|host|gpu|pci|topology|nvlink|nvswitch|infiniband|rdma|roce/i;
+const CAUSAL_RE = /fatal|critical|traceback|exception|assert|panic|segfault|xid|uncorrectable|fallen off the bus|out of memory|watchdog timeout|crc mismatch|loss\s*=\s*(?:nan|inf)|insufficient|unhealthy|ibv_modify_qp|no space left|compil(?:e|ation) (?:error|failed)|no available memory|checksum mismatch|childfailederror|backendcompilerfailed|failedscheduling|input\/output error|nonfinite|divergence|first failure|initiator|caused by/i;
+const MAX_LINE_CHARS = 2000;
+function clipLine(line) {
+    if (line.length <= MAX_LINE_CHARS)
+        return line;
+    const marker = ' [line clipped by Denpex] ';
+    const side = Math.max(1, Math.floor((MAX_LINE_CHARS - marker.length) / 2));
+    return `${line.slice(0, side)}${marker}${line.slice(-side)}`.slice(0, MAX_LINE_CHARS);
+}
+function selectEvidence(logs, max) {
+    if (logs.length <= max)
+        return { text: logs, truncated: false };
+    const lines = logs.split(/\r?\n/);
+    const candidates = new Map();
+    const add = (index, radius, priority) => {
+        for (let i = Math.max(0, index - radius); i <= Math.min(lines.length - 1, index + radius); i++) {
+            candidates.set(i, Math.max(priority, candidates.get(i) ?? 0));
+        }
+    };
+    for (let i = 0; i < Math.min(48, lines.length); i++)
+        candidates.set(i, 300);
+    for (let i = Math.max(0, lines.length - 96); i < lines.length; i++)
+        candidates.set(i, 800);
+    let foundFirst = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (!EVIDENCE_RE.test(line))
+            continue;
+        const causal = CAUSAL_RE.test(line);
+        add(i, causal ? 3 : 1, causal ? 1000 : 700);
+        if (!foundFirst) {
+            add(i, 6, 1100);
+            foundFirst = true;
+        }
+    }
+    const warning = `[Denpex condensed input: input exceeded ${max.toLocaleString()} characters. Environment, causal, rank, topology, middle, and final-tail evidence were selected.]`;
+    let used = warning.length;
+    const selected = new Set();
+    for (const [index] of [...candidates].sort((a, b) => b[1] - a[1] || a[0] - b[0])) {
+        const line = clipLine(lines[index] ?? '');
+        if (used + line.length + 1 > max)
+            continue;
+        selected.add(index);
+        used += line.length + 1;
+    }
+    return {
+        text: [warning, ...[...selected].sort((a, b) => a - b).map((index) => clipLine(lines[index] ?? ''))].join('\n'),
+        truncated: true,
+    };
+}

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@denpex/sdk",
-  "version": "0.8.0",
-  "description": "TypeScript client for the Denpex API — diagnose GPU training failures from logs (POST /api/diagnose), report fix outcomes, check quota. Zero dependencies, Node >= 18.",
-  "keywords": [
-    "denpex",
-    "gpu",
-    "ml-training",
-    "distributed-training",
-    "diagnosis",
-    "nccl",
-    "cuda",
-    "observability",
-    "sdk"
-  ],
-  "homepage": "https://denpex.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MisaMisaAI/Denpex.git",
-    "directory": "denpex-sdk-ts"
-  },
-  "bugs": {
-    "url": "https://denpex.com/contact"
-  },
-  "license": "Proprietary",
-  "main": "dist/client.js",
-  "types": "dist/client.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "test": "tsx --test tests/client.test.ts"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0",
-    "tsx": "^4.23.1"
-  }
-}
+{
+  "name": "@denpex/sdk",
+  "version": "0.8.2",
+  "description": "TypeScript client for the Denpex API : diagnose GPU training failures from logs (POST /api/diagnose), report fix outcomes, check quota. Zero dependencies, Node >= 18.",
+  "keywords": [
+    "denpex",
+    "gpu",
+    "ml-training",
+    "distributed-training",
+    "diagnosis",
+    "nccl",
+    "cuda",
+    "observability",
+    "sdk"
+  ],
+  "homepage": "https://denpex.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MisaMisaAI/Denpex.git",
+    "directory": "denpex-sdk-ts"
+  },
+  "bugs": {
+    "url": "https://denpex.com/contact"
+  },
+  "license": "Proprietary",
+  "main": "dist/client.js",
+  "types": "dist/client.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test tests/client.test.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.23.1"
+  }
+}