clementine-agent 1.0.9 → 1.0.11

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,29 @@ 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. Four sources: timeout, user cancel, StallGuard
+                        // tripped (runaway loop), or interrupted by a new user message.
+                        const stallAbort = !!stallGuard?.isBreakerActive();
+                        const abortReason = abortController?.signal.reason;
+                        const interruptAbort = abortReason === 'interrupted-by-new-message';
+                        logger.warn({ sessionKey, stallAbort, interruptAbort }, 'Chat query aborted');
+                        if (interruptAbort) {
+                            // New message came in — let the next query answer. Just mark
+                            // the partial response so the user knows this one was cut off.
+                            // (The next handleMessage call will fold this partial into its prompt.)
+                            responseText = responseText
+                                ? responseText + '\n\n*(interrupted — answering your new message…)*'
+                                : '*(interrupted — switching to your new message…)*';
+                        }
+                        else 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 +2100,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 +2122,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 +3683,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/channels/discord-utils.js

@@ -161,20 +161,37 @@ export class DiscordStreamingMessage {
             this.progressTimer = null;
         }
         if (!text)
-            text = '*(no response)*';
+            text = "*(I didn't have anything to respond with — try rephrasing or giving me more context.)*";
         text = sanitizeResponse(text);
-        if (this.message) {
-            if (text.length <= 1900) {
-                await this.message.edit(text);
-                this.messageId = this.message.id;
+        try {
+            if (this.message) {
+                if (text.length <= 1900) {
+                    await this.message.edit(text);
+                    this.messageId = this.message.id;
+                }
+                else {
+                    await this.message.delete().catch(() => { });
+                    await sendChunked(this.channel, text);
+                }
             }
             else {
-                await this.message.delete().catch(() => { });
                 await sendChunked(this.channel, text);
             }
         }
-        else {
-            await sendChunked(this.channel, text);
+        catch (err) {
+            // Delivery failed after the agent already generated a response.
+            // Log loudly + persist the response text to the daily note so it isn't
+            // lost silently. Don't re-throw — the callers don't have try/catch
+            // around finalize() and we don't want to introduce crashes.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            try {
+                const pino = (await import('pino')).default;
+                pino({ name: 'clementine.discord' }).warn({ err: errMsg, channelId: this.channel.id }, 'Discord delivery failed — response text saved to daily note');
+                const { logToDailyNote } = await import('../gateway/cron-scheduler.js');
+                const preview = text.slice(0, 1500);
+                logToDailyNote(`**[Discord delivery failed]** Channel \`${this.channel.id ?? 'unknown'}\` — response was:\n\n${preview}`);
+            }
+            catch { /* best-effort */ }
         }
     }
     /** Format elapsed milliseconds as human-readable duration. */

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/dist/gateway/heartbeat-scheduler.js

@@ -135,7 +135,16 @@ export class HeartbeatScheduler {
                 this.dispatcher.send(`**Self-Improvement Failed (nightly)**\n` +
                     `The self-improvement loop crashed: ${String(err).slice(0, 200)}\n\n` +
                     `This will keep failing every night until the root cause is fixed. ` +
-                    `Ask me to check the self-improvement status for details.`, {}).catch(() => { });
+                    `Ask me to check the self-improvement status for details.`, {}).catch(async (sendErr) => {
+                    // If the notification about the failure also failed, surface it to the daily note
+                    // so the user sees it on their next check-in instead of it vanishing into logs.
+                    logger.warn({ err: sendErr }, 'Failed to notify about self-improvement failure — writing to daily note');
+                    try {
+                        const { logToDailyNote } = await import('./cron-scheduler.js');
+                        logToDailyNote(`**[Self-improvement crashed]** ${String(err).slice(0, 400)}`);
+                    }
+                    catch { /* best-effort */ }
+                });
             });
         }
         // Weekly per-agent improvement: one agent per day at 2 AM, cycling through

package/dist/gateway/router.d.ts

@@ -121,8 +121,11 @@ export declare class Gateway {
      */
     stopSession(sessionKey: string): boolean;
     /**
-     * Serialize access to a session. Returns a function to call when done,
-     * or waits for the current holder to finish first.
+     * Serialize access to a session. If a query is already in-flight when a new
+     * message arrives, we interrupt it — abort the running query, capture its
+     * partial output so the next handler can fold it into the new prompt, then
+     * wait for the aborted handler to release the lock. This lets users redirect
+     * or correct the agent mid-response instead of queuing behind a long query.
      */
     private acquireSessionLock;
     handleMessage(sessionKey: string, text: string, onText?: OnTextCallback, model?: string, maxTurns?: number, onToolActivity?: OnToolActivityCallback): Promise<string>;

package/dist/gateway/router.js

@@ -193,7 +193,15 @@ export class Gateway {
             logger.warn({ err, sessionKey }, 'Deep mode agent follow-up failed — using raw fallback');
             if (rawFallback.trim()) {
                 await this._dispatcher?.send(rawFallback.slice(0, 1500))
-                    .catch(e => logger.debug({ err: e }, 'Failed to push deep mode fallback'));
+                    .catch(async (e) => {
+                    // Both paths failed — surface it instead of swallowing at debug level.
+                    logger.warn({ err: e, sessionKey }, 'Deep mode fallback delivery failed — persisting to daily note');
+                    try {
+                        const { logToDailyNote } = await import('./cron-scheduler.js');
+                        logToDailyNote(`**[Deep mode delivery failed]** Session ${sessionKey} — result was:\n\n${rawFallback.slice(0, 1500)}`);
+                    }
+                    catch { /* best-effort */ }
+                });
             }
         }
     }
@@ -524,16 +532,30 @@ export class Gateway {
         return false;
     }
     /**
-     * Serialize access to a session. Returns a function to call when done,
-     * or waits for the current holder to finish first.
+     * Serialize access to a session. If a query is already in-flight when a new
+     * message arrives, we interrupt it — abort the running query, capture its
+     * partial output so the next handler can fold it into the new prompt, then
+     * wait for the aborted handler to release the lock. This lets users redirect
+     * or correct the agent mid-response instead of queuing behind a long query.
      */
     async acquireSessionLock(sessionKey) {
-        // Wait for any existing lock to resolve
         let s = this.getSession(sessionKey);
-        while (s.lock) {
-            logger.info(`Session ${sessionKey} is busy — queuing message`);
-            await s.lock;
-            s = this.getSession(sessionKey);
+        // If a query is in-flight, interrupt it rather than wait indefinitely.
+        if (s.lock) {
+            if (s.abortController && !s.abortController.signal.aborted) {
+                const partial = s.lastStreamedText ?? '';
+                s.pendingInterrupt = { partial, interruptedAt: Date.now() };
+                logger.info({ sessionKey, partialLen: partial.length }, 'New message arrived — interrupting in-flight query');
+                // Pass a reason string so assistant.ts can distinguish this from a
+                // timeout abort and show the right final message.
+                s.abortController.abort('interrupted-by-new-message');
+            }
+            // Drain any remaining lock promises (the aborted handler still needs to
+            // finish its finally block before we can proceed).
+            while (s.lock) {
+                await s.lock;
+                s = this.getSession(sessionKey);
+            }
         }
         // Create a new lock (a promise + its resolver)
         let releaseFn;
@@ -725,8 +747,17 @@ export class Gateway {
                 let toolActivityCount = 0;
                 let lastStreamedText = '';
                 let lastProgressEmitAt = Date.now();
+                const sessState = this.getSession(sessionKey);
                 const wrappedOnText = onText
-                    ? async (token) => { resetIdleTimer(); lastStreamedText = token; lastProgressEmitAt = Date.now(); return onText(token); }
+                    ? async (token) => {
+                        resetIdleTimer();
+                        lastStreamedText = token;
+                        // Mirror to session state so a concurrent acquireSessionLock()
+                        // can capture the partial output on interrupt.
+                        sessState.lastStreamedText = token;
+                        lastProgressEmitAt = Date.now();
+                        return onText(token);
+                    }
                     : undefined;
                 // Progress streaming: emit brief status indicators during long tool chains
                 // so the user doesn't see silence while the agent works
@@ -762,6 +793,24 @@ export class Gateway {
                         ]);
                     }, CHAT_MAX_WALL_MS);
                 });
+                // If the previous query on this session was interrupted by this
+                // incoming message, fold the partial output in so the agent can pivot
+                // smoothly instead of re-planning from scratch.
+                let chatPrompt = text;
+                const interrupt = sessState.pendingInterrupt;
+                if (interrupt && interrupt.partial.trim()) {
+                    delete sessState.pendingInterrupt;
+                    const partialPreview = interrupt.partial.slice(0, 1500);
+                    chatPrompt =
+                        `[You were mid-response when the user sent a new message — they chose not to wait. ` +
+                            `Here's what you had said so far (may be mid-sentence):\n---\n${partialPreview}\n---\n` +
+                            `New message from user:]\n\n${text}`;
+                    logger.info({ sessionKey, partialLen: interrupt.partial.length }, 'Folding interrupted partial into new prompt');
+                }
+                else if (interrupt) {
+                    // Interrupt flag was set but no useful partial text — just clear it.
+                    delete sessState.pendingInterrupt;
+                }
                 try {
                     // No artificial turn cap — let the agent work until done.
                     // Primary guardrail is cost budget (maxBudgetUsd in buildOptions).
@@ -769,7 +818,7 @@ export class Gateway {
                     events.emit('query:start', { sessionKey, model: effectiveModel, maxTurns: maxTurns, timestamp: Date.now() });
                     const queryStartMs = Date.now();
                     const [response] = await Promise.race([
-                        this.assistant.chat(text, effectiveSessionKey, { onText: wrappedOnText, onToolActivity: wrappedOnToolActivity, model: effectiveModel, maxTurns: maxTurns, securityAnnotation, projectOverride, profile: resolvedProfile, verboseLevel, abortController: chatAc }),
+                        this.assistant.chat(chatPrompt, effectiveSessionKey, { onText: wrappedOnText, onToolActivity: wrappedOnToolActivity, model: effectiveModel, maxTurns: maxTurns, securityAnnotation, projectOverride, profile: resolvedProfile, verboseLevel, abortController: chatAc }),
                         hardWallPromise,
                     ]);
                     clearTimeout(chatTimer);

package/package.json

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