clementine-agent 1.0.8 → 1.0.10

package/README.md

@@ -434,6 +434,43 @@ ENABLE_1M_CONTEXT=false    # Enable 1M token context for Sonnet (toggle in dashb
 
 Secrets can also be stored in macOS Keychain (`security find-generic-password`) — Clementine checks Keychain as a fallback for any missing `.env` value.
 
+### Tuning Clementine
+
+Clementine ships with sensible defaults. To change anything, use:
+
+```bash
+clementine config set <KEY> <value>   # writes to ~/.clementine/.env
+clementine config get <KEY>
+clementine config list                # show all overrides
+clementine restart                    # apply changes
+```
+
+Your overrides live in `~/.clementine/.env` — **they survive every `npm update -g` / `clementine update`** because they're in your data home, not the package directory.
+
+**Commonly tuned knobs:**
+
+| Key | Default | What it does |
+|-----|---------|--------------|
+| `BUDGET_CHAT_USD` | `5.00` | Max spend per interactive chat message |
+| `BUDGET_CRON_T1_USD` | `2.00` | Max spend per tier-1 cron job |
+| `BUDGET_CRON_T2_USD` | `5.00` | Max spend per tier-2 cron job |
+| `BUDGET_HEARTBEAT_USD` | `0.50` | Max spend per heartbeat tick |
+| `DEFAULT_MODEL_TIER` | `sonnet` | Default model: `haiku` / `sonnet` / `opus` |
+| `ENABLE_1M_CONTEXT` | `false` | Enable Sonnet 1M-token context (beta) |
+| `HEARTBEAT_INTERVAL_MINUTES` | `30` | How often the agent auto-checks in |
+| `HEARTBEAT_ACTIVE_START` | `8` | First hour of the active window (0–23) |
+| `HEARTBEAT_ACTIVE_END` | `22` | Last hour of the active window |
+| `TIMEZONE` | system TZ | IANA timezone string (e.g., `America/Los_Angeles`) |
+| `ALLOW_ALL_USERS` | `false` | `true` = skip owner-only gate (trust all DMs) |
+| `ASSISTANT_NAME` | `Clementine` | Display name across channels |
+
+Example — raise the chat budget to `$10` without ever touching source:
+
+```bash
+clementine config set BUDGET_CHAT_USD 10
+clementine restart
+```
+
 ---
 
 ## Models

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.' };
                     }
                 }
@@ -1966,7 +1973,10 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                                     const lower = errorText.toLowerCase();
                                     if (lower.includes('max_budget_usd') || lower.includes('budget')) {
                                         logger.warn({ sessionKey }, 'Chat query hit budget cap');
-                                        responseText = responseText || 'I hit the cost limit for this query. Try breaking it into smaller requests.';
+                                        responseText = responseText || (`I hit the $${BUDGET.chat.toFixed(2)} cost cap for this query. Options:\n` +
+                                            `• Break it into smaller requests\n` +
+                                            `• Reply "deep mode" to queue this as a background task with a bigger budget\n` +
+                                            `• Raise the cap permanently: \`clementine config set BUDGET_CHAT_USD 10\` then \`clementine restart\``);
                                     }
                                     else if (lower.includes('rate') && lower.includes('limit')) {
                                         hitRateLimit = true;
@@ -2031,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 {
@@ -2070,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
@@ -2091,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}`;
                         }
                     }
                 }
@@ -3641,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/config.d.ts

@@ -39,14 +39,14 @@ export declare const OWNER_NAME: string;
 export declare function shellEscape(s: string): string;
 export declare const MODELS: Models;
 export declare const BUDGET: {
-    readonly heartbeat: 0.5;
-    readonly cronT1: 2;
-    readonly cronT2: 5;
-    readonly chat: 5;
-    readonly unleashedPhase: undefined;
-    readonly memoryExtraction: undefined;
-    readonly summarization: undefined;
-    readonly reflection: undefined;
+    heartbeat: number;
+    cronT1: number;
+    cronT2: number;
+    chat: number;
+    unleashedPhase: undefined;
+    memoryExtraction: undefined;
+    summarization: undefined;
+    reflection: undefined;
 };
 export declare const DEFAULT_MODEL_TIER: keyof Models;
 export declare const MODEL: string;

package/dist/config.js

@@ -98,11 +98,13 @@ export const MODELS = {
     opus: 'claude-opus-4-6',
 };
 // ── Budget caps (USD per query) ──────────────────────────────────────
+// User-tunable via `clementine config set BUDGET_<NAME>_USD <value>`
+// (writes to ~/.clementine/.env, survives npm update -g).
 export const BUDGET = {
-    heartbeat: 0.50, // $0.50 per heartbeat (Haiku, cheap)
-    cronT1: 2.00, // $2 per tier-1 cron job (needs room for outlook+search)
-    cronT2: 5.00, // $5 per tier-2 cron job
-    chat: 5.00, // $5 per interactive chat message
+    heartbeat: Number(getEnv('BUDGET_HEARTBEAT_USD', '0.50')), // per heartbeat (Haiku)
+    cronT1: Number(getEnv('BUDGET_CRON_T1_USD', '2.00')), // per tier-1 cron job
+    cronT2: Number(getEnv('BUDGET_CRON_T2_USD', '5.00')), // per tier-2 cron job
+    chat: Number(getEnv('BUDGET_CHAT_USD', '5.00')), // per interactive chat
     unleashedPhase: undefined,
     memoryExtraction: undefined,
     summarization: undefined,

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/tools/admin-tools.js

@@ -1137,7 +1137,7 @@ export function registerAdminTools(server) {
     // ── Source Self-Edit Tools ──────────────────────────────────────────────
     const SELF_IMPROVE_DIR = path.join(BASE_DIR, 'self-improve');
     const PENDING_SOURCE_DIR = path.join(SELF_IMPROVE_DIR, 'pending-source-changes');
-    server.tool('self_edit_source', 'Edit Clementine source code safely. Validates in a staging worktree, commits, builds, and triggers restart only if compilation succeeds. The daemon picks up the pending change and executes it.', {
+    server.tool('self_edit_source', 'Edit most Clementine TypeScript source files (for new features or bug fixes). Validates in a staging worktree, compiles, and triggers restart on success. Blocked files: `src/config.ts`, `src/gateway/security-scanner.ts`, `src/security/scanner.ts`. Do NOT use this tool to change user-tunable settings (budget caps, model tier, heartbeat interval, timezone, channel IDs, etc.) — those live in `~/.clementine/.env` and are managed by the user via `clementine config set KEY value`, which survives `clementine update` / `npm update -g`.', {
         file: z.string().describe('Path relative to src/ (e.g., "channels/discord-agent-bot.ts")'),
         content: z.string().describe('Complete new file content'),
         reason: z.string().describe('Why this change is being made'),

package/package.json

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