@hmharness/kernel 0.5.5 → 0.6.1

package/dist/loop.d.ts

@@ -45,8 +45,13 @@ export declare function runLoop(opts: {
         previousDigest: string | null;
         evicted: string[];
     }) => Promise<string>;
-    /** Hard total turn cap — the safety valve (default: 5x the adaptive soft limit, max 400). */
+    /** Hard total turn cap — override for testing (default: unlimited; the
+     *  loop stops on idle detection, not turn count — Codex-style
+     *  fire-and-forget for long-running development tasks). */
     maxTotalTurns?: number;
-    /** Hard total token spend cap — prompt + completion combined (default: 10M). */
+    /** Idle detection: consecutive turns with zero successful tool calls
+     *  before the loop concludes the agent is stuck (default: 15). */
+    maxIdleTurns?: number;
+    /** Hard total token spend cap (default: 50M — generous enough for days). */
     maxTotalTokens?: number;
 }): Promise<LoopResult>;

package/dist/loop.js

@@ -13,12 +13,13 @@ import { chat } from "./provider.js";
 export async function runLoop(opts) {
     const { provider, registry, ctx, events } = opts;
     const modelCall = opts.chatImpl ?? chat;
-    // Soft limit: where the wrap-up nudge fires (adaptive to context window).
+    // Codex-style: no turn cap. The loop runs until the model gives a final
+    // answer, goes idle (no successful tool calls for N turns), or hits a
+    // very generous token valve. Soft checkpoint nudges remain as guidance.
     const softTurnLimit = adaptiveMaxTurns(provider);
-    // Hard limit: the actual safety valve. If the model is still calling tools
-    // at the soft limit, we auto-continue — the loop only hard-stops here.
-    const hardTurnLimit = opts.maxTotalTurns ?? Math.min(softTurnLimit * 5, 400);
-    const hardTokenLimit = opts.maxTotalTokens ?? 10_000_000;
+    const hardTurnLimit = opts.maxTotalTurns ?? Infinity; // no cap by default
+    const maxIdle = opts.maxIdleTurns ?? 15; // stuck detector
+    const hardTokenLimit = opts.maxTotalTokens ?? 50_000_000;
     const budget = opts.maxContextChars ?? adaptiveContextChars(provider);
     const working = [...opts.messages];
     let toolUses = 0;
@@ -26,12 +27,12 @@ export async function runLoop(opts) {
     const tools = registry.toOpenAITools();
     let wrapupSignaled = false;
     let turn = 0;
+    let idleTurns = 0; // consecutive turns with no successful tool calls
     let reason = 'final';
-    // The loop runs until the model gives a final answer (no tool calls) OR a
-    // safety valve fires. The old "maxTurns stop" is replaced by a soft
-    // checkpoint: if the model is still actively working (calling tools) at
-    // the soft limit, the loop auto-continues — long-running tasks feel
-    // unlimited while the hard valves protect against runaway loops and cost.
+    // The loop runs until the model gives a final answer (no tool calls), goes
+    // idle (stuck), or hits a safety valve. Soft checkpoints at the adaptive
+    // turn limit nudge the model but don't stop it — days-long tasks run
+    // uninterrupted (Codex fire-and-forget philosophy).
     while (true) {
         turn++;
         if (turn > hardTurnLimit) {
@@ -55,11 +56,11 @@ export async function runLoop(opts) {
             });
         }
         // Soft turn checkpoint: at the adaptive limit, nudge to conclude — but
-        // the model can keep working if it's mid-task (auto-continue).
-        if (turn === softTurnLimit) {
+        // the model can keep working if it's mid-task (no cap, fire-and-forget).
+        if (turn === softTurnLimit || (turn > softTurnLimit && turn % softTurnLimit === 0)) {
             working.push({
                 role: 'system',
-                content: `[turn checkpoint] You have been working for ${turn} turns. If the task is substantially complete, give your final answer now. If not, continue — the turn limit has been lifted; work until done.`,
+                content: `[turn checkpoint] You have been working for ${turn} turns. If the task is substantially complete, give your final answer. If not, continue — there is no turn limit; work until done.`,
             });
         }
         const chatRes = await modelCall(provider, compacted, tools, {
@@ -135,14 +136,31 @@ export async function runLoop(opts) {
                 content: p.output.length > 60_000 ? p.output.slice(0, 60_000) + '\n...[truncated]' : p.output,
             });
         }
+        // Idle detection: count consecutive turns where NO tool succeeded. A
+        // productive agent always has at least one successful call; N consecutive
+        // all-fail/all-skip turns = the agent is stuck in a loop (this replaces
+        // the old hard turn cap — Codex-style "run until done, not until N").
+        const anySuccess = planned.some((p) => !p.isError && !p.skip);
+        if (anySuccess) {
+            idleTurns = 0;
+        }
+        else {
+            idleTurns++;
+            if (idleTurns >= maxIdle) {
+                reason = 'idle';
+                break;
+            }
+        }
         // Loop continues: the model was actively calling tools, so we keep going
-        // (auto-continuation past the soft turn limit). Only the safety valves
-        // (hardTurnLimit / hardTokenLimit) can stop us now.
+        // indefinitely (no turn cap). Only idle detection or the token valve stops us.
     }
-    // Safety valve fired
-    const text = reason === 'turn-valve'
-        ? `Safety turn limit reached (${turn - 1} turns, hard cap ${hardTurnLimit}). The session is preserved — send another message to continue with fresh limits.`
-        : `Token budget limit reached (~${usage.promptTokens + usage.completionTokens} tokens, cap ${hardTokenLimit}). The session is preserved — send another message to continue.`;
-    events?.onFinal?.(text, turn - 1);
-    return { text, turns: turn - 1, toolUses, messages: working, usage };
+    // Safety valve or idle detection fired
+    const executedTurns = reason === 'idle' ? turn : turn - 1;
+    const text = reason === 'idle'
+        ? `Agent appears stuck: ${maxIdle} consecutive turns with no successful tool calls. The session is preserved — review the transcript, adjust the approach, and send a new message to continue.`
+        : reason === 'turn-valve'
+            ? `Turn limit reached (${executedTurns} turns). The session is preserved — send another message to continue.`
+            : `Token budget limit reached (~${usage.promptTokens + usage.completionTokens} tokens). The session is preserved — send another message to continue.`;
+    events?.onFinal?.(text, executedTurns);
+    return { text, turns: executedTurns, toolUses, messages: working, usage };
 }

package/dist/provider.js

@@ -15,7 +15,12 @@ export async function chat(cfg, messages, tools, opts = {}) {
         : { 'Content-Type': 'application/json', [typeof scheme === 'string' ? scheme : 'X-Api-Key']: cfg.apiKey };
     let authScheme = cfg.authHeader ?? 'bearer';
     let lastError = '';
-    for (let attempt = 0; attempt < 2; attempt++) {
+    // 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;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? cfg.timeoutMs ?? 120_000);
         try {
@@ -25,16 +30,23 @@ export async function chat(cfg, messages, tools, opts = {}) {
                 body: JSON.stringify(body),
                 signal: ctrl.signal,
             });
-            if (res.status === 429 || res.status >= 500) {
+            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));
+                lastError = `HTTP 429 (rate limited): ${(await res.text()).slice(0, 200)}`;
+                await sleep(delay + Math.random() * 1000); // jitter
+                continue;
+            }
+            if (res.status >= 500) {
+                const delay = Math.min(30_000, 2000 * Math.pow(2, attempt));
                 lastError = `HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`;
-                await sleep(1500 * (attempt + 1));
+                await sleep(delay + Math.random() * 1000);
                 continue;
             }
             if (res.status === 401 && !cfg.authHeader && authScheme === 'bearer' && cfg.apiKey) {
-                // gateway rejected Bearer - try the other common scheme once
                 authScheme = 'X-Api-Key';
                 lastError = 'renegotiating auth: Bearer rejected, retrying with X-Api-Key';
-                attempt--;
                 continue;
             }
             if (!res.ok) {
@@ -59,15 +71,19 @@ export async function chat(cfg, messages, tools, opts = {}) {
         }
         catch (err) {
             lastError = String(err);
-            if (!/abort|fetch failed|ECONN|timeout/i.test(lastError))
-                throw err;
-            await sleep(1500 * (attempt + 1));
+            // 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);
+                continue;
+            }
+            throw err; // permanent error (bad JSON, logic error): don't retry
         }
         finally {
             clearTimeout(timer);
         }
     }
-    throw new Error(`provider: failed after retry (${cfg.baseUrl}): ${lastError}`);
+    throw new Error(`provider: failed after ${MAX_RETRIES} retries (${cfg.baseUrl}): ${lastError}`);
 }
 /** Assemble a ChatResponse from an SSE stream, emitting deltas as they land. */
 async function consumeStream(res, onDelta) {

package/package.json

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