clementine-agent 1.0.8 → 1.0.9

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

@@ -1966,7 +1966,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;

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/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.9",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",