clementine-agent 1.0.9 → 1.0.10

package/dist/agent/assistant.js

@@ -1357,6 +1357,13 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                 if (stallGuard) {
                     const stallCheck = stallGuard.shouldBlockTool(toolName);
                     if (stallCheck.block) {
+                        // When the breaker engages we also abort the whole query —
+                        // denying a single tool isn't enough for a runaway loop,
+                        // the agent will just try the next read-only tool.
+                        if (abortController && !abortController.signal.aborted) {
+                            logger.warn({ sessionKey, toolName }, 'StallGuard breaker engaged — aborting query');
+                            abortController.abort();
+                        }
                         return { behavior: 'deny', message: stallCheck.message ?? 'Stall breaker.' };
                     }
                 }
@@ -2034,9 +2041,19 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                 catch (e) {
                     const errStr = String(e).toLowerCase();
                     if (errStr.includes('abort') || errStr.includes('cancel')) {
-                        // Query was aborted (timeout or user cancel) — return partial output
-                        logger.warn({ sessionKey }, 'Chat query aborted');
-                        if (!responseText) {
+                        // Query was aborted. Three sources: timeout, user cancel, or
+                        // StallGuard tripped (runaway loop detected).
+                        const stallAbort = !!stallGuard?.isBreakerActive();
+                        logger.warn({ sessionKey, stallAbort }, 'Chat query aborted');
+                        if (stallAbort) {
+                            const reason = stallGuard?.getBreakerReason() ?? 'runaway loop';
+                            const stallMsg = `I got stuck in a loop — ${reason} ` +
+                                `I stopped to save budget. Options:\n` +
+                                `• Rephrase your request more specifically\n` +
+                                `• Reply "deep mode" to queue this as a background task with a bigger budget`;
+                            responseText = responseText ? responseText + '\n\n' + stallMsg : stallMsg;
+                        }
+                        else if (!responseText) {
                             responseText = 'I ran out of time on this one. Let me know if you want me to pick it back up.';
                         }
                         else {
@@ -2073,7 +2090,8 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                         responseText = responseText || 'The conversation context filled up from large tool outputs. I\'ve reset the session — please try again, and I\'ll keep query results smaller this time.';
                     }
                     else if (errStr.includes('prompt is too long') || errStr.includes('prompt too long') || errStr.includes('context_length')) {
-                        responseText = responseText || 'Error: prompt is too long — context window overflow from large tool responses.';
+                        responseText = responseText || ('The conversation got too large to process (tool responses filled the context window). ' +
+                            "I've reset the session. Try again — I'll keep result sets smaller this time.");
                     }
                     else if (errStr.includes('no conversation found') || errStr.includes('conversation not found') || errStr.includes('session not found')) {
                         // Stale session — clear and retry
@@ -2094,9 +2112,20 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     else {
                         logger.error({ err: e, sessionKey }, 'SDK query failed');
                         if (!responseText) {
-                            // Surface a concise error description instead of a generic message
+                            // Classify so the user gets a useful suggestion instead of raw error text.
                             const shortErr = String(e).replace(/\n.*$/s, '').slice(0, 200);
-                            responseText = `Hit an error: ${shortErr}. Try again or \`!clear\` to reset the session.`;
+                            const lowerErr = String(e).toLowerCase();
+                            let hint = '';
+                            if (lowerErr.includes('econnrefused') || lowerErr.includes('socket') || lowerErr.includes('network')) {
+                                hint = 'Looks like a network issue — check your internet and try again.';
+                            }
+                            else if (lowerErr.includes('spawn') || lowerErr.includes('enoent')) {
+                                hint = 'A required binary seems to be missing. Try `clementine doctor` to diagnose.';
+                            }
+                            else {
+                                hint = 'Try again, or `!clear` to reset the session. If it keeps happening, check `~/.clementine/logs/clementine.log`.';
+                            }
+                            responseText = `I hit an error: ${shortErr}\n\n${hint}`;
                         }
                     }
                 }
@@ -3644,7 +3673,9 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     appendProgress({ event: 'aborted', phase, reason: `${MAX_CONSECUTIVE_ERRORS} consecutive phase errors` });
                     writeStatus({ jobName, status: 'error', phase, startedAt, finishedAt: new Date().toISOString() });
                     logger.error(`Unleashed task ${jobName} aborted after ${MAX_CONSECUTIVE_ERRORS} consecutive errors`);
-                    const errorResult = lastOutput || `Task "${jobName}" aborted after ${MAX_CONSECUTIVE_ERRORS} consecutive phase errors.`;
+                    const errorResult = lastOutput || (`Task "${jobName}" aborted after ${MAX_CONSECUTIVE_ERRORS} consecutive phase errors. ` +
+                        `Check \`clementine cron runs ${jobName}\` for the failing phase, or retry with ` +
+                        `\`clementine cron run ${jobName}\`.`);
                     if (this.onUnleashedComplete) {
                         try {
                             this.onUnleashedComplete(jobName, errorResult);

package/dist/agent/metacognition.js

@@ -94,7 +94,22 @@ export class MetacognitiveMonitor {
             this.interventionCount++;
             return signal;
         }
-        // Signal: excessive tool calls (>20 in a single execution)
+        // Signal: excessive tool calls with near-zero output.
+        // Warn at 20, intervene (hard stop) at 60 — beyond 60 the agent is
+        // almost certainly in a runaway loop that will burn through the
+        // budget cap with nothing to show for it.
+        if (this.toolCalls.length >= 60 && this.outputCharCount < 200) {
+            this.confidence = 'low';
+            if (!this.signals.includes('high_effort_low_output')) {
+                this.signals.push('high_effort_low_output');
+            }
+            this.interventionCount++;
+            return {
+                type: 'intervene',
+                reason: 'high_effort_low_output',
+                guidance: `You've made ${this.toolCalls.length} tool calls across ${this.uniqueTools.size} tools with only ${this.outputCharCount} chars of output. This is a runaway loop. Stopping now to prevent budget waste.`,
+            };
+        }
         if (this.toolCalls.length > 20 && this.outputCharCount < 200) {
             this.confidence = 'low';
             if (!this.signals.includes('high_effort_low_output')) {

package/dist/agent/stall-guard.d.ts

@@ -33,6 +33,10 @@ export declare class StallGuard {
         block: boolean;
         message?: string;
     };
+    /** True when the stall breaker has been engaged during this query. */
+    isBreakerActive(): boolean;
+    /** Reason string set when the breaker engaged (empty if not active). */
+    getBreakerReason(): string;
     /**
      * Record a tool call. Runs loop detection and metacognition.
      * Activates the breaker if either detector fires.

package/dist/agent/stall-guard.js

@@ -41,6 +41,10 @@ export class StallGuard {
         }
         return { block: false };
     }
+    /** True when the stall breaker has been engaged during this query. */
+    isBreakerActive() { return this.breakerActive; }
+    /** Reason string set when the breaker engaged (empty if not active). */
+    getBreakerReason() { return this.breakerReason; }
     /**
      * Record a tool call. Runs loop detection and metacognition.
      * Activates the breaker if either detector fires.

package/dist/gateway/cron-scheduler.js

@@ -1184,7 +1184,8 @@ export class CronScheduler {
         // Truncate
         if (msg.length > 300)
             msg = msg.slice(0, 297) + '...';
-        return `${jobName} failed: ${msg.trim()}`;
+        return (`Cron \`${jobName}\` failed: ${msg.trim()}\n` +
+            `Check \`clementine cron runs ${jobName}\` for details, or retry with \`clementine cron run ${jobName}\`.`);
     }
     listJobs() {
         if (this.jobs.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",