@hmharness/kernel 0.5.4 → 0.6.0

package/dist/loop.d.ts

@@ -45,4 +45,13 @@ export declare function runLoop(opts: {
         previousDigest: string | null;
         evicted: string[];
     }) => Promise<string>;
+    /** 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;
+    /** 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,24 +13,41 @@ import { chat } from "./provider.js";
 export async function runLoop(opts) {
     const { provider, registry, ctx, events } = opts;
     const modelCall = opts.chatImpl ?? chat;
-    // Turn limit scales with the model's context window: 25 for small models,
-    // up to 80 for 1M-window models. The context compaction keeps the
-    // transcript within budget throughout, so the real ceiling is how many
-    // reasoning turns the model can sustain, not raw token count.
-    const maxTurns = opts.maxTurns ?? adaptiveMaxTurns(provider);
+    // 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);
+    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;
     const usage = { promptTokens: 0, completionTokens: 0 };
     const tools = registry.toOpenAITools();
     let wrapupSignaled = false;
-    for (let turn = 1; turn <= maxTurns; turn++) {
+    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), 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) {
+            reason = 'turn-valve';
+            break;
+        }
+        if (usage.promptTokens + usage.completionTokens > hardTokenLimit) {
+            reason = 'token-valve';
+            break;
+        }
         const compacted = opts.summarizeContext
             ? await compactWithDigest(working, budget, opts.summarizeContext)
             : compactMessages(working, budget);
-        // Budget wrap-up signal: when context usage crosses 80%, inject a
-        // single system nudge to wind down instead of hard-cutting mid-thought
-        // (Codex's token-budget-context pattern; DeepSeek's 80% pressure trigger).
+        // Context budget wrap-up signal: when usage crosses 80%, nudge the model
+        // to wind down (Codex token_budget_context + DeepSeek 80% pressure).
         if (!wrapupSignaled && transcriptChars(compacted) > budget * 0.8) {
             wrapupSignaled = true;
             working.push({
@@ -38,6 +55,14 @@ export async function runLoop(opts) {
                 content: '[context budget] Context is running low. Wrap up the current task: summarize what was accomplished, suggest concrete next steps, and stop starting new sub-tasks.',
             });
         }
+        // Soft turn checkpoint: at the adaptive limit, nudge to conclude — but
+        // 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. If not, continue — there is no turn limit; work until done.`,
+            });
+        }
         const chatRes = await modelCall(provider, compacted, tools, {
             onDelta: events?.onDelta,
         });
@@ -111,8 +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
+        // indefinitely (no turn cap). Only idle detection or the token valve stops us.
     }
-    const text = `Turn limit reached (${maxTurns} turns). The session is preserved — continue with "hmh resume" or just send another message to pick up where this left off.`;
-    events?.onFinal?.(text, maxTurns);
-    return { text, turns: maxTurns, 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.4",
+  "version": "0.6.0",
   "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",