@hmharness/kernel 0.6.6 → 0.6.8

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.ts';
+export * from './shellgate.ts';
 export * from './registry.ts';
 export * from './provider.ts';
 export * from './window.ts';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./types.js";
+export * from "./shellgate.js";
 export * from "./registry.js";
 export * from "./provider.js";
 export * from "./window.js";

package/dist/loop.js

@@ -72,6 +72,18 @@ export async function runLoop(opts) {
         });
         usage.promptTokens += chatRes.usage?.prompt_tokens ?? 0;
         usage.completionTokens += chatRes.usage?.completion_tokens ?? 0;
+        // Usage fallback: many OpenAI-compatible gateways never report usage
+        // (even with stream_options.include_usage), which used to leave the token
+        // valve counting zero - a runaway loop had NO stop. Estimate from the
+        // wire text instead (chars/4 heuristic): coarse, but the valve only needs
+        // an order of magnitude to trip at 50M.
+        if (!chatRes.usage || (!chatRes.usage.prompt_tokens && !chatRes.usage.completion_tokens)) {
+            const promptChars = compacted.reduce((n, m) => n + (m.content?.length ?? 0), 0);
+            const replyChars = (chatRes.message.content?.length ?? 0)
+                + (chatRes.message.tool_calls ?? []).reduce((n, c) => n + c.function.arguments.length, 0);
+            usage.promptTokens += Math.ceil(promptChars / 4);
+            usage.completionTokens += Math.ceil(replyChars / 4);
+        }
         const { message } = chatRes;
         events?.onAssistant?.(message);
         const calls = message.tool_calls ?? [];
@@ -105,7 +117,7 @@ export async function runLoop(opts) {
                 p.isError = true;
                 p.skip = true;
             }
-            else if (tool.needsApproval?.(args)) {
+            else if (tool.needsApproval?.(args, ctx)) {
                 // Safe default: with no gate wired in, risky tools are denied.
                 const granted = opts.approval ? await opts.approval.ask(name, args) : false;
                 events?.onApproval?.(name, args, granted);

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,11 +14,26 @@ 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
+ *  does NOT read x-ratelimit-reset: that header is an epoch timestamp in the
+ *  wild, which naive Number() parsing turned into a ~1.7e12 ms setTimeout
+ *  that overflowed and fired immediately - a retry storm. */
+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,36 @@
+/** 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
+ *  does NOT read x-ratelimit-reset: that header is an epoch timestamp in the
+ *  wild, which naive Number() parsing turned into a ~1.7e12 ms setTimeout
+ *  that overflowed and fired immediately - a retry storm. */
+export function parseRetryAfterMs(raw, maxMs = 120_000) {
+    if (!raw)
+        return 0;
+    const v = raw.trim();
+    if (/^\d{1,10}$/.test(v))
+        return Math.min(maxMs, Number(v) * 1000);
+    const at = Date.parse(v);
+    if (!Number.isNaN(at))
+        return Math.min(maxMs, Math.max(0, at - Date.now()));
+    return 0;
+}
 export async function chat(cfg, messages, tools, opts = {}) {
     const streaming = typeof opts.onDelta === 'function';
     const body = { model: cfg.model, messages };
@@ -16,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',
@@ -31,9 +72,10 @@ export async function chat(cfg, messages, tools, opts = {}) {
                 signal: ctrl.signal,
             });
             if (res.status === 429) {
-                // honour server-provided retry delay; fall back to exponential backoff
-                const retryAfter = Number(res.headers.get('retry-after')) || Number(res.headers.get('x-ratelimit-reset')) || 0;
-                const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 2000 * Math.pow(2, attempt));
+                // Retry-After per RFC/MDN has two legal forms: delta-seconds ("120")
+                // or HTTP-date ("Wed, 21 Oct 2015 07:28:00 GMT"). See
+                // parseRetryAfterMs for why x-ratelimit-reset is deliberately ignored.
+                const delay = parseRetryAfterMs(res.headers.get('retry-after')) || Math.min(30_000, 2000 * Math.pow(2, attempt));
                 lastError = `HTTP 429 (rate limited): ${(await res.text()).slice(0, 200)}`;
                 await sleep(delay + Math.random() * 1000); // jitter
                 continue;
@@ -54,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];
@@ -71,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
@@ -83,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 = '';
@@ -166,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/dist/shellgate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @hmharness/kernel - shell fast-path gate
+ *
+ * One shared implementation for every "run this without an approval card"
+ * decision over remotely/exec-ed shell strings (the agent's ssh_run tool and
+ * the web /api/ssh proxy). String allowlists are bypassable in general -
+ * documented bypass classes include command substitution `$()`/backticks
+ * (cli-mcp-server 0.2.5, CVE-2026-28470), `&&`-blind-spots (Claude Code),
+ * and argument-level execution such as `find -exec`/`-delete`
+ * (GHSA-cv3g-hj65-pcfh). The design here closes all of them at once:
+ *
+ *   fast path = ONE bare read-only verb + plain arguments + ZERO shell
+ *   metacharacters anywhere (no $ ` ( ) { } < > | ; & \ quotes/newlines)
+ *   and no verb whose own ARGUMENTS can execute or mutate (find, echo,
+ *   xargs, awk, date -s are excluded outright).
+ *
+ * Everything else returns false - i.e. needs an approval card. Fail closed:
+ * an unknown or oddly-shaped command is never a fast path.
+ */
+/**
+ * True only for a bare read-only probe (e.g. `df -h`, `ps aux`, `cat /etc/hosts`).
+ * Callers: `if (!isBareProbe(cmd)) → approval required`.
+ */
+export declare function isBareProbe(cmd: string): boolean;

package/dist/shellgate.js

@@ -0,0 +1,34 @@
+/**
+ * @hmharness/kernel - shell fast-path gate
+ *
+ * One shared implementation for every "run this without an approval card"
+ * decision over remotely/exec-ed shell strings (the agent's ssh_run tool and
+ * the web /api/ssh proxy). String allowlists are bypassable in general -
+ * documented bypass classes include command substitution `$()`/backticks
+ * (cli-mcp-server 0.2.5, CVE-2026-28470), `&&`-blind-spots (Claude Code),
+ * and argument-level execution such as `find -exec`/`-delete`
+ * (GHSA-cv3g-hj65-pcfh). The design here closes all of them at once:
+ *
+ *   fast path = ONE bare read-only verb + plain arguments + ZERO shell
+ *   metacharacters anywhere (no $ ` ( ) { } < > | ; & \ quotes/newlines)
+ *   and no verb whose own ARGUMENTS can execute or mutate (find, echo,
+ *   xargs, awk, date -s are excluded outright).
+ *
+ * Everything else returns false - i.e. needs an approval card. Fail closed:
+ * an unknown or oddly-shaped command is never a fast path.
+ */
+/** Metacharacters that enable substitution, chaining, or redirection. */
+const SHELL_METACHARS = /[$`(){}<>|;&'"\\\n\r]/;
+/** Verbs safe to run with plain arguments only (read-only, no exec-in-args). */
+const BARE_PROBE_VERBS = /^(ls|cat|head|tail|df|du|free|uptime|whoami|hostname|uname|ps|grep|wc|id|pwd|date)(\s+[A-Za-z0-9_.:@/=,-]+)*\s*$/;
+/**
+ * True only for a bare read-only probe (e.g. `df -h`, `ps aux`, `cat /etc/hosts`).
+ * Callers: `if (!isBareProbe(cmd)) → approval required`.
+ */
+export function isBareProbe(cmd) {
+    if (!cmd || SHELL_METACHARS.test(cmd))
+        return false;
+    if (/\bdate\b/.test(cmd) && /\s--?s(e[rt])?\b/.test(cmd))
+        return false; // clock set
+    return BARE_PROBE_VERBS.test(cmd);
+}

package/dist/types.d.ts

@@ -33,7 +33,7 @@ export interface Tool {
      * false means read-only / safe. Remote (MCP) tools default to needing
      * approval unless their server is marked trusted.
      */
-    needsApproval?(args: Record<string, unknown>): boolean;
+    needsApproval?(args: Record<string, unknown>, ctx?: ToolContext): boolean;
     execute(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
 }
 /** OpenAI-style chat message, reused across provider adapters. */
@@ -106,8 +106,18 @@ export interface HmhConfig {
      *  error self-notes (every task, zero cost), Tier 2 = one model-call
      *  lesson per erroring task (instant reflection), Tier 3 = this - full
      *  cycle with bench gate. Guards unchanged: double-gate, holdout, poison
-     *  screen, writes only under skills/ and memory/. */
+     *  screen; writes skills/ + memory/ + evolution logs, and repo code only
+     *  when evolution.autoPatch is explicitly enabled. */
     autoEvolveEvery?: number;
+    /** Evolution-cycle options. autoPatch (default FALSE) opts into code-level
+     *  self-evolution (the DGM-style sandboxed patch loop). Off by default:
+     *  self-modifying systems are unsafe by default (the DGM paper's own
+     *  framing) - with it off, evolution writes only skills/ + memory/ + its
+     *  own logs, never repo code. */
+    evolution?: {
+        /** Enable the code-patch (self-modification) step. Default false. */
+        autoPatch?: boolean;
+    };
     /** Named vendor endpoints for multi-provider routing. */
     providers?: Record<string, ProviderConfig>;
     /** Per-purpose provider names resolved against `providers`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/kernel",
-  "version": "0.6.6",
+  "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",