@nexrall/code-core 1.4.27 → 1.4.28

package/dist/agent/loop.d.ts

@@ -19,6 +19,29 @@ export declare const _stallLimits: {
     STALL_LIMIT: number;
     REPEAT_STALL_LIMIT: number;
 };
+/**
+ * Why an agent run stopped.
+ *
+ * `'clean'` and `'aborted'` are the two silent-by-design outcomes: the model gave a
+ * final answer, or the user pressed Ctrl+C and already knows why it stopped.
+ * EVERYTHING else owes the user an explanation, which is what stopReasonNotice covers.
+ */
+export type StopReason = 'clean' | 'aborted' | 'reported-elsewhere' | 'empty-response' | 'no-balance' | 'stalled' | 'stalled-repeat' | 'budget' | 'unknown';
+/**
+ * The message shown when a run ends for any reason other than a clean finish.
+ *
+ * Pure and exported so every branch is testable: reaching some of these for real needs
+ * an empty wallet, a dead upstream, or hundreds of iterations. Returns null only for
+ * the two outcomes that are deliberately silent.
+ *
+ * `'unknown'` deliberately produces a message rather than nothing. If a future `break`
+ * forgets to set a reason, the symptom should be a visible "ended unexpectedly" line —
+ * annoying and reportable — not the silent stop that made this refactor necessary.
+ */
+export declare function stopReasonNotice(reason: StopReason, ctx?: {
+    budget?: number;
+    repeatError?: string | null;
+}): string | null;
 export declare function resolveMaxIterations(optionValue: number | undefined, settingsRaw: Record<string, unknown>): number;
 /**
  * Minimal concurrency gate. Hand-rolled rather than pulling in `p-limit` because

package/dist/agent/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = exports.ToolNotAllowedError = exports._stallLimits = void 0;
 exports.errorRoundSignature = errorRoundSignature;
+exports.stopReasonNotice = stopReasonNotice;
 exports.resolveMaxIterations = resolveMaxIterations;
 exports.createLimiter = createLimiter;
 exports.extractSubTaskText = extractSubTaskText;
@@ -214,6 +215,50 @@ function errorRoundSignature(errored) {
 }
 /** Runaway-guard limits, exposed for tests. */
 exports._stallLimits = { STALL_LIMIT, REPEAT_STALL_LIMIT };
+/**
+ * The message shown when a run ends for any reason other than a clean finish.
+ *
+ * Pure and exported so every branch is testable: reaching some of these for real needs
+ * an empty wallet, a dead upstream, or hundreds of iterations. Returns null only for
+ * the two outcomes that are deliberately silent.
+ *
+ * `'unknown'` deliberately produces a message rather than nothing. If a future `break`
+ * forgets to set a reason, the symptom should be a visible "ended unexpectedly" line —
+ * annoying and reportable — not the silent stop that made this refactor necessary.
+ */
+function stopReasonNotice(reason, ctx = {}) {
+    switch (reason) {
+        case 'clean':
+        case 'aborted':
+        // A dedicated channel (e.g. the zero-balance bubble via onBalanceStatus) has already
+        // told the user why this stopped. Naming this case explicitly — rather than reusing
+        // 'aborted' — keeps "the user cancelled" from silently coming to mean two things.
+        case 'reported-elsewhere':
+            return null;
+        case 'empty-response':
+            return `\n\u26a0\ufe0f The model returned an empty response, so nothing was done. This is usually a transient ` +
+                `upstream hiccup \u2014 send "continue" to retry.\n`;
+        case 'no-balance':
+            return `\n\ud83d\udcb3 Stopped: your balance is empty, so the request was rejected before it started. ` +
+                `Top up and send "continue" \u2014 no tokens were used for this turn.\n`;
+        case 'stalled':
+            return `\n\ud83d\uded1 Stopped: the last ${STALL_LIMIT} tool rounds all failed, so the agent looked stuck. ` +
+                `Fix the underlying error (or grant the needed permission) and send "continue".\n`;
+        case 'stalled-repeat':
+            return `\n\ud83d\uded1 Stopped: the same tool error repeated ${REPEAT_STALL_LIMIT} rounds in a row, so the agent ` +
+                `was looping without making progress.` +
+                (ctx.repeatError ? ` The recurring error was:\n${ctx.repeatError}\n` : '\n') +
+                `Fix that underlying cause (or grant the needed permission) and send "continue".\n`;
+        case 'budget':
+            return `\n\u23f8\ufe0f Stopped at the ${ctx.budget}-step safety limit \u2014 the task may be incomplete. ` +
+                `Send "continue" to resume, or raise the limit via "maxIterations" in .nexrall/settings.json ` +
+                `(or the NEXRALL_MAX_ITERATIONS env var). Auto-continue can be disabled with "autoContinue": false.\n`;
+        case 'unknown':
+        default:
+            return `\n\u26a0\ufe0f The run ended unexpectedly without completing. Your work so far is preserved \u2014 ` +
+                `send "continue" to resume.\n`;
+    }
+}
 // Resolve the soft iteration budget. Precedence:
 //   options.maxIterations  →  env NEXRALL_MAX_ITERATIONS  →  settings.maxIterations  →  default
 //
@@ -1535,16 +1580,28 @@ async function runAgentLoop(initialMessages, options) {
     // condition where one sub-agent's chdir overwrites another's, making every tool
     // that falls back to process.cwd() resolve paths against the wrong directory.
     // workDir is now threaded explicitly through executeTool → resolvePath instead.
-    // Distinguish a clean finish (model produced a final answer) from hitting the
-    // iteration backstop, so we can tell the user what happened rather than
-    // silently returning a half-done task.
-    let completedCleanly = false;
+    // ─── Why did this run stop? ───────────────────────────────────────────────────
+    //
+    // The epilogue used to INFER the reason by re-testing state (`stalledOut`, then
+    // `iteration >= budget`). Inference only covers the cases someone thought to test,
+    // so any `break` that matched none of them fell through and the run ended in total
+    // silence — the worst possible outcome after an hour of work, because the user
+    // cannot tell "finished" from "died". Two such holes existed:
+    //
+    //   • the pre-flight 402 (wallet empty) broke out with no flag set at all, leaving
+    //     the optional onBalanceStatus callback as the ONLY signal;
+    //   • a thinking-only/empty model turn set completedCleanly = true, actively
+    //     claiming success for a turn that produced nothing.
+    //
+    // So the reason is now RECORDED at each exit instead of reconstructed after it.
+    // Anything that isn't an explicit clean finish or a user abort must name itself,
+    // and `default` in the switch below means a future `break` cannot go silent.
+    let stopReason = 'unknown';
     // Tool rounds actually completed in this call. Counted explicitly rather than derived
     // from `messages.length` because auto-compaction splices the history SHORTER mid-run:
     // a long session that compacted and then lost its connection would show a negative
     // length delta and be judged "no progress", discarding the work it most needs to keep.
     let completedRounds = 0;
-    let stalledOut = false; // tripped the runaway guard (all-failed rounds)
     let consecutiveErrorRounds = 0; // rounds where every tool call errored
     // Repeated-identical-failure guard: see the runaway guards below. Tracked
     // separately from consecutiveErrorRounds because a round can contain a succeeding
@@ -1605,8 +1662,10 @@ async function runAgentLoop(initialMessages, options) {
     let compactDisabled = false;
     try {
         for (; iteration < budget; iteration++) {
-            if (options.abortSignal?.aborted)
+            if (options.abortSignal?.aborted) {
+                stopReason = 'aborted';
                 break;
+            }
             // Auto-compact: keep the resent prompt small BEFORE the next stream so we
             // never hit the context-window wall — or the backend body-size limit — and,
             // just as importantly, so we stop paying cache-read on an ever-growing prefix
@@ -1802,8 +1861,10 @@ async function runAgentLoop(initialMessages, options) {
                 }, onEvent);
             }
             catch (err) {
-                if (options.abortSignal?.aborted || err.name === 'AbortError')
+                if (options.abortSignal?.aborted || err.name === 'AbortError') {
+                    stopReason = 'aborted';
                     break;
+                }
                 // Pre-flight 402 (routes/code.js — wallet already empty, the turn couldn't even
                 // start) is tagged with `status`/`balance` by client.ts. Surface it as the same
                 // low/zero-balance nudge a mid-turn 'balance_status' event would, instead of a
@@ -1811,7 +1872,16 @@ async function runAgentLoop(initialMessages, options) {
                 const status = err.status;
                 if (status === 402) {
                     const balance = err.balance ?? 0;
+                    // Prefer the rich, actionable UI (a persistent bubble with a link to Billing)
+                    // where the client implements it…
                     options.onBalanceStatus?.(balance, true);
+                    // …but do not DEPEND on it. The callback is optional, so a client without it
+                    // used to show the user absolutely nothing — the run simply stopped mid-task.
+                    //
+                    // Set the reason ONLY when there is no richer channel, so clients that do
+                    // render the bubble don't also get a redundant plain-text line saying the same
+                    // thing. Either way the user is told something, which is the actual guarantee.
+                    stopReason = options.onBalanceStatus ? 'reported-elsewhere' : 'no-balance';
                     break;
                 }
                 runSimpleHooks(hooks.OnError, options.workDir);
@@ -1824,8 +1894,10 @@ async function runAgentLoop(initialMessages, options) {
                 // assistant→tool_result pair here, so it is valid to resend as-is.
                 throw new types_1.AgentTurnError(`Stream failed: ${err.message}`, trimToResumableBoundary(messages), completedRounds, err);
             }
-            if (options.abortSignal?.aborted)
+            if (options.abortSignal?.aborted) {
+                stopReason = 'aborted';
                 break;
+            }
             // 2. Strip thinking blocks — API rejects them in message history
             assistantMessage.content = assistantMessage.content.filter((b) => b.type !== 'thinking' && b.type !== 'redacted_thinking');
             // If the model returned nothing usable (e.g. thinking-only, then stopped), the
@@ -1841,8 +1913,12 @@ async function runAgentLoop(initialMessages, options) {
                     messages.push({ role: 'user', content: [{ type: 'text', text }] });
                     continue;
                 }
+                // NOT a clean finish. This used to set completedCleanly = true, which told the
+                // caller the task succeeded when the model had in fact produced nothing at all
+                // — indistinguishable, to the user, from a finished job with no summary. An
+                // empty turn is a (usually transient) upstream failure, so name it and say so.
                 runSimpleHooks(hooks.PostMessageComplete, options.workDir);
-                completedCleanly = true;
+                stopReason = 'empty-response';
                 break;
             }
             // stopReason is transient, single-turn metadata for the truncated-tool-call guard
@@ -1990,7 +2066,7 @@ async function runAgentLoop(initialMessages, options) {
                     }
                 }
                 runSimpleHooks(hooks.PostMessageComplete, options.workDir);
-                completedCleanly = true;
+                stopReason = 'clean';
                 break;
             }
             // 5. Execute all tool uses in parallel
@@ -2235,7 +2311,7 @@ async function runAgentLoop(initialMessages, options) {
             const allErrored = toolResults.length > 0 && errored.length === toolResults.length;
             consecutiveErrorRounds = allErrored ? consecutiveErrorRounds + 1 : 0;
             if (consecutiveErrorRounds >= STALL_LIMIT) {
-                stalledOut = true;
+                stopReason = 'stalled';
                 break;
             }
             // Signature of this round's failures, order-independent and truncated so a long
@@ -2249,7 +2325,7 @@ async function runAgentLoop(initialMessages, options) {
                 lastErrorSignature = errSignature;
             }
             if (repeatedErrorRounds >= REPEAT_STALL_LIMIT) {
-                stalledOut = true;
+                stopReason = 'stalled-repeat';
                 stalledRepeatError = errored[0] ? String(errored[0].result.error).slice(0, 300) : null;
                 break;
             }
@@ -2264,27 +2340,23 @@ async function runAgentLoop(initialMessages, options) {
             }
             // Loop back to step 1
         }
-        // Explain why we stopped when it wasn't a clean finish or a user abort, so a
-        // long run never just goes silent. History ends on a tool_result turn, so
-        // "continue" resumes exactly where it left off.
-        if (!options.abortSignal?.aborted && !completedCleanly) {
-            // Routed through onNotice (falling back to onText) like every other housekeeping
-            // message in this file — these are statements from the harness, not from the model,
-            // and splicing them into the assistant's own bubble reads as if it said them.
-            if (stalledOut) {
-                (options.onNotice ?? options.onText)(stalledRepeatError
-                    ? `\n🛑 Stopped: the same tool error repeated ${REPEAT_STALL_LIMIT} rounds in a row, so the agent ` +
-                        `was looping without making progress. The recurring error was:\n${stalledRepeatError}\n` +
-                        `Fix that underlying cause (or grant the needed permission) and send "continue".\n`
-                    : `\n🛑 Stopped: the last ${STALL_LIMIT} tool rounds all failed, so the agent looked stuck. ` +
-                        `Fix the underlying error (or grant the needed permission) and send "continue".\n`);
-            }
-            else if (iteration >= budget) {
-                (options.onNotice ?? options.onText)(`\n⏸️ Stopped at the ${budget}-step safety limit — the task may be incomplete. ` +
-                    `Send "continue" to resume, or raise the limit via "maxIterations" in .nexrall/settings.json ` +
-                    `(or the NEXRALL_MAX_ITERATIONS env var). Auto-continue can be disabled with "autoContinue": false.\n`);
-            }
-        }
+        // Explain why we stopped, so a long run never just goes silent. History ends on a
+        // tool_result turn, so "continue" resumes exactly where it left off.
+        //
+        // The budget case is resolved HERE rather than at a break: exhausting the `for`
+        // condition is a normal loop exit, not a branch we can annotate. Everything else
+        // named itself on the way out, and 'unknown' is the loud fallback for a break that
+        // forgot to.
+        if (stopReason === 'unknown' && iteration >= budget)
+            stopReason = 'budget';
+        if (options.abortSignal?.aborted)
+            stopReason = 'aborted';
+        // Routed through onNotice (falling back to onText) like every other housekeeping
+        // message in this file — these are statements from the harness, not from the model,
+        // and splicing them into the assistant's own bubble reads as if it said them.
+        const notice = stopReasonNotice(stopReason, { budget, repeatError: stalledRepeatError });
+        if (notice)
+            (options.onNotice ?? options.onText)(notice);
     }
     catch (err) {
         // Every other failure path (a tool executor blowing up, a hook throwing, an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.27",
+  "version": "1.4.28",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",