@hmharness/kernel 0.6.7 → 0.6.8

package/dist/mcp.js

@@ -14,6 +14,11 @@ function nextId() {
     nextId.n = (nextId.n ?? 0) + 1;
     return nextId.n;
 }
+/** Transport-level failure worth one retry (and worth explaining in the tool
+ *  result instead of leaking a bare "TypeError: fetch failed"). */
+function isTransientTransport(msg) {
+    return /fetch failed|terminated|ECONN|EAI_AGAIN|ENOTFOUND|ETIMEDOUT|timeout|abort|socket|premature close|UND_ERR/i.test(msg);
+}
 (function (nextId) {
 })(nextId || (nextId = {}));
 export class McpClient {
@@ -161,7 +166,25 @@ export class McpClient {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), timeoutMs);
         try {
-            const res = await fetch(cfg.url, { method: 'POST', headers, body: JSON.stringify(payload), signal: ctrl.signal });
+            // one retry for transient transport failures: a dead/restarting MCP
+            // server used to surface a bare "TypeError: fetch failed" straight to
+            // the model as the tool result
+            let res;
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    res = await fetch(cfg.url, { method: 'POST', headers, body: JSON.stringify(payload), signal: ctrl.signal });
+                    break;
+                }
+                catch (err) {
+                    if (attempt === 0 && isTransientTransport(String(err))) {
+                        await new Promise((r) => setTimeout(r, 800));
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (!res)
+                throw new Error('no response');
             const sid = res.headers.get('mcp-session-id');
             if (sid)
                 this.sessionId = sid;
@@ -177,6 +200,15 @@ export class McpClient {
             }
             return body;
         }
+        catch (err) {
+            const msg = String(err);
+            if (/^mcp\//.test(msg))
+                throw err; // already annotated (HTTP status, parse)
+            const hint = isTransientTransport(msg)
+                ? ` - the MCP server at ${cfg.url} is unreachable or cut the connection`
+                : '';
+            throw new Error(`mcp/${this.serverName}: request failed (${msg})${hint}`);
+        }
         finally {
             clearTimeout(timer);
         }

package/dist/provider.d.ts

@@ -14,7 +14,7 @@ export interface ChatResponse {
         completion_tokens?: number;
     };
 }
-export type DeltaKind = 'text' | 'reasoning';
+export type DeltaKind = 'text' | 'reasoning' | 'reset';
 /** Parse a Retry-After header into a delay in ms (MDN: exactly two legal
  *  forms - delta-seconds or HTTP-date), clamped to [0, 120s]. Returns 0 when
  *  absent/illegal (caller falls back to exponential backoff). Deliberately
@@ -24,8 +24,16 @@ export type DeltaKind = 'text' | 'reasoning';
 export declare function parseRetryAfterMs(raw: string | null | undefined, maxMs?: number): number;
 export interface ChatOptions {
     timeoutMs?: number;
-    /** Streaming callback; presence switches the request to stream:true. */
+    /** Streaming callback; presence switches the request to stream:true.
+     *  kind 'reset' carries an empty chunk and means: the previous attempt died
+     *  mid-stream and is being retried - discard what you streamed for it. */
     onDelta?(kind: DeltaKind, chunk: string): void;
+    /** Retry policy for transient failures. Defaults: 6 attempts, 3s base with
+     *  exponential backoff and jitter, capped at 60s per wait. */
+    retry?: {
+        attempts?: number;
+        baseMs?: number;
+    };
 }
 export declare function chat(cfg: ProviderConfig, messages: ChatMessage[], tools?: unknown[], opts?: ChatOptions): Promise<ChatResponse>;
 /** Accept bases with any /vN suffix (v1 OpenAI convention, v4 zhipu coding

package/dist/provider.js

@@ -1,3 +1,19 @@
+/** Transient failures worth retrying. `terminated` is undici's TypeError for
+ *  a socket cut mid-body (gateway dropped a long stream, proxy reset, server
+ *  restart) - the case that used to kill the whole task with a raw
+ *  `TypeError: terminated` because it matched none of the old patterns. */
+const TRANSIENT_RE = /abort|terminated|fetch failed|ECONN|EAI_AGAIN|ENOTFOUND|ETIMEDOUT|timeout|socket hang up|other side closed|premature close|UND_ERR|EPIPE|no response body/i;
+/** Human hint for the failure classes users actually hit. */
+function transientHint(msg) {
+    if (/terminated|socket hang up|other side closed|premature close/i.test(msg)) {
+        return ' - the connection was cut mid-response (gateway dropped a long stream or a proxy reset it)';
+    }
+    if (/abort|timeout/i.test(msg))
+        return ' - the provider stopped sending data (idle/timeout)';
+    if (/fetch failed|ECONN|EAI_AGAIN|ENOTFOUND|UND_ERR/i.test(msg))
+        return ' - the provider endpoint was unreachable (network/DNS)';
+    return '';
+}
 /** Parse a Retry-After header into a delay in ms (MDN: exactly two legal
  *  forms - delta-seconds or HTTP-date), clamped to [0, 120s]. Returns 0 when
  *  absent/illegal (caller falls back to exponential backoff). Deliberately
@@ -33,13 +49,21 @@ export async function chat(cfg, messages, tools, opts = {}) {
     let authScheme = cfg.authHeader ?? 'bearer';
     let lastError = '';
     // Resilient retry: exponential backoff with jitter, up to 6 attempts
-    // (Codex-style fire-and-forget: network hiccups, 429s, and provider
-    // restarts should NEVER kill a long-running task). Retry-After header
-    // from 429s is honoured when present.
-    const MAX_RETRIES = 6;
+    // (Codex-style fire-and-forget: network hiccups, 429s, provider restarts,
+    // and mid-stream socket cuts should NEVER kill a long-running task).
+    const MAX_RETRIES = opts.retry?.attempts ?? 6;
+    const BASE_MS = opts.retry?.baseMs ?? 3000;
     for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? cfg.timeoutMs ?? 120_000);
+        // Did this attempt stream anything to the UI before dying? A mid-stream
+        // cut leaves partial deltas on screen; retrying would duplicate them, so
+        // clients are told to drop the partial block first (DeltaKind 'reset').
+        let emitted = false;
+        const emit = streaming
+            ? (kind, chunk) => { if (kind !== 'reset')
+                emitted = true; opts.onDelta(kind, chunk); }
+            : undefined;
         try {
             const res = await fetch(endpoint(cfg.baseUrl), {
                 method: 'POST',
@@ -72,7 +96,7 @@ export async function chat(cfg, messages, tools, opts = {}) {
             }
             if (streaming) {
                 clearTimeout(timer);
-                return await consumeStream(res, opts.onDelta);
+                return await consumeStream(res, emit);
             }
             const data = (await res.json());
             const choice = data.choices?.[0];
@@ -89,10 +113,14 @@ export async function chat(cfg, messages, tools, opts = {}) {
         }
         catch (err) {
             lastError = String(err);
-            // transient (network, timeout, connection reset): retry with backoff
-            if (/abort|fetch failed|ECONN|EAI_AGAIN|ENOTFOUND|timeout|socket hang up/i.test(lastError)) {
-                const delay = Math.min(60_000, 3000 * Math.pow(2, attempt));
-                await sleep(delay + Math.random() * 2000);
+            // transient (network, timeout, connection reset, mid-stream cut): retry
+            if (TRANSIENT_RE.test(lastError)) {
+                // the attempt already painted partial text: tell clients to drop it so
+                // the retry does not append a second copy of the same answer
+                if (emitted)
+                    opts.onDelta?.('reset', '');
+                const delay = Math.min(60_000, BASE_MS * Math.pow(2, attempt));
+                await sleep(delay + Math.random() * Math.min(2000, BASE_MS));
                 continue;
             }
             throw err; // permanent error (bad JSON, logic error): don't retry
@@ -101,10 +129,12 @@ export async function chat(cfg, messages, tools, opts = {}) {
             clearTimeout(timer);
         }
     }
-    throw new Error(`provider: failed after ${MAX_RETRIES} retries (${cfg.baseUrl}): ${lastError}`);
+    throw new Error(`provider: failed after ${MAX_RETRIES} attempts (${cfg.baseUrl}): ${lastError}${transientHint(lastError)}`);
 }
 /** Assemble a ChatResponse from an SSE stream, emitting deltas as they land. */
 async function consumeStream(res, onDelta) {
+    if (!res.body)
+        throw new TypeError('provider: no response body (streaming requested)');
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buf = '';
@@ -184,6 +214,11 @@ async function consumeStream(res, onDelta) {
     }
     finally {
         clearTimeout(idleTimer);
+        // Cancel the body rather than releaseLock(): when the idle guard won the
+        // race, reader.read() is still outstanding and releaseLock() throws
+        // "Cannot release a readable stream reader..." - which would REPLACE the
+        // real error (a mid-stream cut / idle timeout) with a meaningless one.
+        await reader.cancel().catch(() => undefined);
         reader.releaseLock();
     }
     const ordered = [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([, c]) => c);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/kernel",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "hmharness kernel: tool registry, provider adapters, the agent loop, session log, config. Zero runtime dependencies (Node >=22 native fetch).",
   "type": "module",
   "main": "dist/index.js",