@hmharness/kernel 0.5.3 → 0.5.5

package/dist/loop.d.ts

@@ -45,4 +45,8 @@ 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). */
+    maxTotalTurns?: number;
+    /** Hard total token spend cap — prompt + completion combined (default: 10M). */
+    maxTotalTokens?: number;
 }): Promise<LoopResult>;

package/dist/loop.js

@@ -8,25 +8,45 @@
  * transcript is compacted against the context budget.
  */
 import { compactMessages, compactWithDigest, transcriptChars } from "./context.js";
-import { adaptiveContextChars } from "./window.js";
+import { adaptiveContextChars, adaptiveMaxTurns } from "./window.js";
 import { chat } from "./provider.js";
 export async function runLoop(opts) {
     const { provider, registry, ctx, events } = opts;
     const modelCall = opts.chatImpl ?? chat;
-    const maxTurns = opts.maxTurns ?? 25;
+    // Soft limit: where the wrap-up nudge fires (adaptive to context window).
+    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 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 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.
+    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({
@@ -34,6 +54,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 (auto-continue).
+        if (turn === softTurnLimit) {
+            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.`,
+            });
+        }
         const chatRes = await modelCall(provider, compacted, tools, {
             onDelta: events?.onDelta,
         });
@@ -107,8 +135,14 @@ export async function runLoop(opts) {
                 content: p.output.length > 60_000 ? p.output.slice(0, 60_000) + '\n...[truncated]' : p.output,
             });
         }
+        // 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.
     }
-    const text = `Turn budget exhausted (${maxTurns}). Last state preserved in the session log.`;
-    events?.onFinal?.(text, maxTurns);
-    return { text, turns: maxTurns, toolUses, messages: working, usage };
+    // 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 };
 }

package/dist/window.d.ts

@@ -38,3 +38,13 @@ export declare function adaptiveContextChars(p: {
     model: string;
     contextWindow?: number;
 }): number;
+/** Adaptive turn limit: larger context windows sustain more turns before
+ *  quality degrades (the context budget system compacts throughout, so the
+ *  real ceiling is how many turns the model can reason over, not raw token
+ *  count). Floor 25 (small models), cap 80 (even 1M windows don't need more).
+ *  This fixes the "25 turns auto-stop" complaint — the context engineering
+ *  was working fine, the turn cap was the bottleneck. */
+export declare function adaptiveMaxTurns(p: {
+    model: string;
+    contextWindow?: number;
+}): number;

package/dist/window.js

@@ -45,3 +45,13 @@ export function contextBudgetChars(windowTokens) {
 export function adaptiveContextChars(p) {
     return contextBudgetChars(contextWindowFor(p).windowTokens);
 }
+/** Adaptive turn limit: larger context windows sustain more turns before
+ *  quality degrades (the context budget system compacts throughout, so the
+ *  real ceiling is how many turns the model can reason over, not raw token
+ *  count). Floor 25 (small models), cap 80 (even 1M windows don't need more).
+ *  This fixes the "25 turns auto-stop" complaint — the context engineering
+ *  was working fine, the turn cap was the bottleneck. */
+export function adaptiveMaxTurns(p) {
+    const budget = contextBudgetChars(contextWindowFor(p).windowTokens);
+    return Math.max(25, Math.min(80, Math.floor(budget / 4000)));
+}

package/package.json

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