@hmharness/kernel 0.6.5 → 0.6.7

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/provider.d.ts

@@ -15,6 +15,13 @@ export interface ChatResponse {
     };
 }
 export type DeltaKind = 'text' | 'reasoning';
+/** 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. */

package/dist/provider.js

@@ -1,3 +1,20 @@
+/** 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 };
@@ -31,9 +48,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;

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. */
@@ -68,6 +68,14 @@ export interface ProviderConfig {
      *  built-in registry; the transcript budget then scales to the window
      *  (see window.ts) instead of the fixed legacy default. */
     contextWindow?: number;
+    /** Capability marker: can this model accept image input?
+     *  Set `false` on a text-only model that is (or might be) named by
+     *  `routing.vision`. resolveProvider('vision') then SKIPS it instead of
+     *  silently posting screenshots to a blind model - which answers HTTP 200
+     *  with "I can't view the image" and used to be graded as "the expected
+     *  UI text is not on screen" (a FALSE-NEGATIVE regression FAIL).
+     *  Omitted = unknown, and the provider is used as before. */
+    supportsVision?: boolean;
 }
 /** User-level configuration (HMH_HOME/config.json). */
 export interface HmhConfig {
@@ -98,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`. */
@@ -114,8 +132,46 @@ export interface HmhConfig {
         bench?: string;
     };
 }
-/** Resolve a purpose to a concrete provider config (routing > legacy fields). */
+/** Resolve a purpose to a concrete provider config (routing > legacy fields).
+ *
+ * For 'vision' a provider explicitly marked `supportsVision: false` is NOT
+ * accepted: it is skipped so the dedicated `vision` block (or the chat
+ * default) wins instead. Rationale - `routing.vision` used to shadow the
+ * `vision` block unconditionally, so a text-only model there received every
+ * screenshot and replied "I can't view the image" with HTTP 200; the UI
+ * regression tool then reported a FAIL about the app instead of a provider
+ * failure (false negative, mis-attributed to the product). */
 export declare function resolveProvider(cfg: HmhConfig, purpose: 'chat' | 'vision' | 'evolve' | 'bench'): ProviderConfig;
+/**
+ * Ordered vision candidates: routing.vision provider, the legacy `vision`
+ * block, then `visionFallbacks`; de-duplicated by endpoint+model and with
+ * providers marked `supportsVision: false` removed. If everything is marked
+ * blind the unfiltered list is returned, so callers still get today's
+ * (failing, but informative) behaviour instead of "no vision provider".
+ * A caller looping this chain turns a blind/dead provider into a retry
+ * rather than a wrong answer.
+ */
+export declare function visionProviderChain(cfg: HmhConfig): ProviderConfig[];
+/**
+ * Did the model answer "I can't see any image" instead of describing one?
+ * A blind (text-only) provider returns HTTP 200 with prose like this, so
+ * callers MUST NOT treat such a reply as evidence about the image - for UI
+ * regression that is the difference between a provider failure and a
+ * product FAIL. Checked on the head of the answer, where refusals live.
+ */
+export declare function isVisionRefusal(text: string): boolean;
+/** Head-of-answer phrases that mean "I never looked at the image". Kept as
+ *  small separate patterns so each one is verifiable on its own. */
+export declare const VISION_REFUSAL_PATTERNS: RegExp[];
+/** The `FOUND: <text>` line the regression prompt demands, or null. */
+export declare function foundLineText(described: string): string | null;
+/**
+ * Did the model itself report reading NO text? Then there is no evidence
+ * about the app either way - the screen may be blank, or the provider may be
+ * blind. Either way this is "no verdict", NOT a product FAIL (confirm from
+ * the device view tree instead).
+ */
+export declare function foundNothing(described: string): boolean;
 /** One row of `/model` listings: a named provider and what it currently serves. */
 export interface ProviderView {
     name: string;

package/dist/types.js

@@ -3,22 +3,116 @@
  * The kernel contract surface. Deliberately small: a Tool, a chat message,
  * a provider config. Everything else in hmharness composes from these.
  */
-/** Resolve a purpose to a concrete provider config (routing > legacy fields). */
+/** Resolve a purpose to a concrete provider config (routing > legacy fields).
+ *
+ * For 'vision' a provider explicitly marked `supportsVision: false` is NOT
+ * accepted: it is skipped so the dedicated `vision` block (or the chat
+ * default) wins instead. Rationale - `routing.vision` used to shadow the
+ * `vision` block unconditionally, so a text-only model there received every
+ * screenshot and replied "I can't view the image" with HTTP 200; the UI
+ * regression tool then reported a FAIL about the app instead of a provider
+ * failure (false negative, mis-attributed to the product). */
 export function resolveProvider(cfg, purpose) {
-    const named = cfg.routing?.[purpose] ?? (purpose === 'vision' ? undefined : cfg.routing?.chat);
+    if (purpose === 'vision') {
+        const chain = visionProviderChain(cfg);
+        if (chain.length > 0)
+            return chain[0];
+        return cfg.vision ?? cfg.provider;
+    }
+    const named = cfg.routing?.[purpose] ?? cfg.routing?.chat;
     if (named && cfg.providers?.[named])
         return cfg.providers[named];
-    if (purpose === 'vision')
-        return cfg.vision ?? cfg.provider;
     return cfg.provider;
 }
+/**
+ * Ordered vision candidates: routing.vision provider, the legacy `vision`
+ * block, then `visionFallbacks`; de-duplicated by endpoint+model and with
+ * providers marked `supportsVision: false` removed. If everything is marked
+ * blind the unfiltered list is returned, so callers still get today's
+ * (failing, but informative) behaviour instead of "no vision provider".
+ * A caller looping this chain turns a blind/dead provider into a retry
+ * rather than a wrong answer.
+ */
+export function visionProviderChain(cfg) {
+    const routed = cfg.routing?.vision ? cfg.providers?.[cfg.routing.vision] : undefined;
+    const all = [routed, cfg.vision, ...(cfg.visionFallbacks ?? []), cfg.provider].filter((p) => Boolean(p && p.baseUrl));
+    const seen = new Set();
+    const unique = all.filter((p) => {
+        const k = `${p.baseUrl}|${p.model}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+    const sighted = unique.filter((p) => p.supportsVision !== false);
+    return sighted.length > 0 ? sighted : unique;
+}
+/**
+ * Did the model answer "I can't see any image" instead of describing one?
+ * A blind (text-only) provider returns HTTP 200 with prose like this, so
+ * callers MUST NOT treat such a reply as evidence about the image - for UI
+ * regression that is the difference between a provider failure and a
+ * product FAIL. Checked on the head of the answer, where refusals live.
+ */
+export function isVisionRefusal(text) {
+    const head = (text ?? '').trim().slice(0, 600);
+    if (!head)
+        return false;
+    return VISION_REFUSAL_PATTERNS.some((re) => re.test(head));
+}
+/** Head-of-answer phrases that mean "I never looked at the image". Kept as
+ *  small separate patterns so each one is verifiable on its own. */
+export const VISION_REFUSAL_PATTERNS = [
+    /i\s*(?:'|\u2019)?(?:m|am)\s*(?:not\s+able|unable)\s+to\s+(?:view|see|access|read|analy[sz]e)/i,
+    /i\s+can(?:'|\u2019)?t\s+(?:view|see|access|read|analy[sz]e)\s+(?:the|this|that|any|an)?\s*(?:\w+\s+)?(?:image|images|picture|photo|screenshot)/i,
+    /\bcannot\s+(?:view|see|access|read)\s+(?:the|this|that|any)?\s*(?:\w+\s+)?(?:image|images|picture|photo|screenshot)/i,
+    /unable\s+to\s+(?:view|see|process|access|analy[sz]e)\s+(?:the|this|any)?\s*(?:\w+\s+)?(?:image|images|picture|photo|screenshot)/i,
+    /no\s+image\s+(?:was\s+|is\s+)?(?:provided|attached|received|supplied|included)/i,
+    /i\s+don(?:'|\u2019)?t\s+see\s+(?:an|any)\s+image/i,
+    /i\s+(?:do\s+not|don(?:'|\u2019)?t)\s+have\s+(?:the\s+)?(?:ability|capability)\s+to\s+(?:view|see|process)\s+(?:image|images|the\s+image)/i,
+    /as\s+an?\s+(?:ai|artificial\s+intelligence|language\s+model|text[- ]only\s+model)[^.\n]{0,60}(?:can(?:'|\u2019)?t|cannot|unable|do\s+not)/i,
+    /\bi\s+can(?:'|\u2019)?t\s+\w+\s+(?:the|this)\s+(?:image|screenshot|picture|photo)/i,
+    /\u6211\s*(?:\u65e0\u6cd5|\u4e0d\u80fd|\u6ca1\u6cd5|\u770b\u4e0d\u5230)\s*(?:\u67e5\u770b|\u770b\u5230|\u8bc6\u522b|\u8bfb\u53d6|\u7406\u89e3|\u770b\u89c1)?[^\u3002\n]{0,12}(?:\u56fe\u7247|\u56fe\u50cf)/,
+    /(?:\u65e0\u6cd5|\u4e0d\u80fd)\s*(?:\u67e5\u770b|\u8bc6\u522b|\u8bfb\u53d6)\s*(?:\u56fe\u7247|\u56fe\u50cf)/,
+    /\u4f5c\u4e3a\s*(?:\u4e00\u4e2a)?\s*(?:AI|\u4eba\u5de5\u667a\u80fd|\u8bed\u8a00\u6a21\u578b|\u6587\u672c\u6a21\u578b)[^\u3002\n]{0,30}(?:\u65e0\u6cd5|\u4e0d\u80fd)/,
+    /(?:\u672a|\u6ca1\u6709)(?:\u6536\u5230|\u770b\u5230|\u68c0\u6d4b\u5230)\s*(?:\u4efb\u4f55)?\s*\u56fe\u7247/,
+    // observed live 2026-09-11 from the local text-only @quality endpoint:
+    // "The device screen cannot be described because the provided image is
+    //  unsupported or unavailable. FOUND: No readable UI text" - it parroted
+    // the required FOUND: line while admitting it never received the image.
+    /(?:image|screenshot|picture|photo)\s+(?:is\s+|was\s+|appears\s+)?(?:unsupported|unavailable|not\s+supported|invalid|unreadable|missing)/i,
+    /(?:unsupported|unavailable|invalid|unreadable)\s+(?:image|screenshot|picture|photo|image\s+format|attachment)/i,
+    /(?:cannot|can(?:'|\u2019)?t|unable\s+to)\s+be\s+described/i,
+    /(?:unable|not\s+able)\s+to\s+describe\s+(?:the|this|any)?\s*(?:image|screenshot|screen|picture|photo)/i,
+];
+/** The `FOUND: <text>` line the regression prompt demands, or null. */
+export function foundLineText(described) {
+    const m = /found:\s*(.+)/i.exec(described ?? '');
+    return m ? m[1].trim().replace(/[.。]+$/, '') : null;
+}
+/**
+ * Did the model itself report reading NO text? Then there is no evidence
+ * about the app either way - the screen may be blank, or the provider may be
+ * blind. Either way this is "no verdict", NOT a product FAIL (confirm from
+ * the device view tree instead).
+ */
+export function foundNothing(described) {
+    const fnd = foundLineText(described);
+    if (fnd === null)
+        return false;
+    return /^(?:no|none|n\/?a|nil|nothing|null|-{1,3})[\s\S]{0,40}$/i.test(fnd) || /no\s+readable\s+(?:ui\s+)?text/i.test(fnd);
+}
 export function listProviders(cfg) {
     const purposesOf = (n) => {
         const out = [];
         for (const p of ['chat', 'vision', 'evolve', 'bench']) {
             const named = cfg.routing?.[p] ?? (p !== 'vision' ? cfg.routing?.chat : undefined);
-            if (named === n)
-                out.push(p);
+            if (named !== n)
+                continue;
+            // a provider marked text-only does not serve vision, whatever routing says
+            if (p === 'vision' && cfg.providers?.[n]?.supportsVision === false)
+                continue;
+            out.push(p);
         }
         return out;
     };

package/package.json

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