clementine-agent 1.0.92 → 1.0.94

package/dist/agent/execution-advisor.d.ts

@@ -5,6 +5,23 @@
  * cron job execution parameters: turn limits, models, timeouts, prompt
  * enrichment, escalation, and circuit-breaking.
  */
+import { CronRunLog } from '../gateway/heartbeat.js';
 import type { CronJobDefinition, ExecutionAdvice } from '../types.js';
+interface ReflectionEntry {
+    jobName: string;
+    timestamp: string;
+    existence: boolean;
+    substance: boolean;
+    actionable: boolean;
+    communication: boolean;
+    criteriaMet: boolean | null;
+    quality: number;
+    gap: string;
+    commNote: string;
+}
 export declare function getExecutionAdvice(jobName: string, job: CronJobDefinition): ExecutionAdvice;
+export declare function checkTurnLimitHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;
+export declare function checkReflectionQuality(reflections: ReflectionEntry[], job: CronJobDefinition, advice: ExecutionAdvice): void;
+export declare function checkTimeoutHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;
+export {};
 //# sourceMappingURL=execution-advisor.d.ts.map

package/dist/agent/execution-advisor.js

@@ -102,7 +102,11 @@ export function getExecutionAdvice(jobName, job) {
     return advice;
 }
 // ── Rule helpers ────────────────────────────────────────────────────
-function checkTurnLimitHits(runs, job, advice) {
+export function checkTurnLimitHits(runs, job, advice) {
+    // Unleashed jobs manage per-phase turns via UNLEASHED_PHASE_TURNS, not job.maxTurns.
+    // Bumping maxTurns here would override the unleashed limit with a small value.
+    if (job.mode === 'unleashed')
+        return;
     // Use precise TerminalReason when available, fall back to regex on error text
     const turnLimitHits = runs.slice(0, 5).filter(r => {
         if (r.status !== 'error' && r.status !== 'retried')
@@ -131,7 +135,9 @@ function checkTurnLimitHits(runs, job, advice) {
         logger.debug({ job: job.name, from: currentMax, to: advice.adjustedMaxTurns }, 'Adjusting maxTurns due to turn-limit hits');
     }
 }
-function checkReflectionQuality(reflections, job, advice) {
+export function checkReflectionQuality(reflections, job, advice) {
+    if (job.mode === 'unleashed')
+        return;
     const recent = reflections.slice(0, 5); // already newest-first
     if (recent.length < 3)
         return;
@@ -166,7 +172,9 @@ function checkModelUpgrade(runs, job, advice) {
         logger.debug({ job: job.name, failures: recentFailures.length }, 'Upgrading model from haiku to sonnet due to repeated failures');
     }
 }
-function checkTimeoutHits(runs, job, advice) {
+export function checkTimeoutHits(runs, job, advice) {
+    if (job.mode === 'unleashed')
+        return;
     const timeoutMs = DEFAULT_TIMEOUT_MS; // standard cron timeout
     const threshold = timeoutMs * 0.95;
     const timeoutHits = runs.slice(0, 5).filter(r => {

package/dist/agent/safe-restart.js

@@ -14,11 +14,15 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import pino from 'pino';
-import { BASE_DIR } from '../config.js';
+import { ALLOW_SOURCE_EDITS, BASE_DIR } from '../config.js';
 import { preflightSourceChange } from './source-preflight.js';
 import { recordSourceMod } from './source-mods.js';
 const logger = pino({ name: 'clementine.safe-restart' });
 const SENTINEL_PATH = path.join(BASE_DIR, '.restart-sentinel.json');
+const DEPRECATION_MESSAGE = 'Source self-editing is disabled. Use advisor-rule YAML, CRON.md frontmatter, ' +
+    'or prompt-override markdown instead — those land without a restart and survive ' +
+    'npm updates. Set CLEMENTINE_ALLOW_SOURCE_EDITS=1 in ~/.clementine/.env only for ' +
+    'genuine engine bugs that cannot be expressed as data.';
 /** Files that cannot be self-edited (security-critical or self-referential). */
 const BLOCKLIST = new Set([
     'src/config.ts',
@@ -47,6 +51,11 @@ const BLOCKLIST = new Set([
  */
 export async function safeSourceEdit(pkgDir, changes, opts) {
     const reason = opts?.reason ?? 'source self-edit';
+    // Quarantine: source self-edit is deprecated. Off by default.
+    if (!ALLOW_SOURCE_EDITS) {
+        logger.warn({ fileCount: changes.length, files: changes.map(c => c.relativePath), reason }, 'Source self-edit refused — primitive is disabled');
+        return { success: false, error: DEPRECATION_MESSAGE };
+    }
     // Validate against blocklist
     for (const change of changes) {
         if (BLOCKLIST.has(change.relativePath)) {

package/dist/agent/self-improve-loop.d.ts

@@ -51,12 +51,21 @@ export interface SelfImproveDispatcher {
     }>;
 }
 export interface SelfImproveLoopOptions {
-    /** Override scan interval for tests. */
+    /**
+     * Override the fallback safety-net tick interval. The loop is primarily
+     * event-driven; this is just a backstop. Used by tests to disable the
+     * timer entirely (set to 0 or a very large number).
+     */
     tickMs?: number;
     /** Override directories for tests. */
     triggersDir?: string;
     pendingDir?: string;
     cronPath?: string;
+    /**
+     * Disable the fs.watch event-driven path. Tests use this so they can
+     * call tick() directly without racing the watcher.
+     */
+    disableWatch?: boolean;
 }
 export declare function classifyFailure(recentErrors: string[]): FixRecipe;
 export declare class SelfImproveLoop {
@@ -65,12 +74,18 @@ export declare class SelfImproveLoop {
     private readonly pendingDir;
     private readonly cronPath;
     private readonly dispatcher;
+    private readonly watchEnabled;
     private timer;
+    private watcher;
+    private debounceTimer;
     private running;
     private ticking;
     constructor(dispatcher: SelfImproveDispatcher, opts?: SelfImproveLoopOptions);
     start(): void;
     stop(): void;
+    /** Coalesce a burst of fs.watch events (multiple triggers landing in
+     * quick succession) into a single tick. */
+    private scheduleDebouncedTick;
     /**
      * Process all pending triggers. Public so tests + manual invocations
      * (e.g., a `clementine self-improve tick` CLI command) can call it.

package/dist/agent/self-improve-loop.js

@@ -24,13 +24,25 @@
  * Idempotent: re-applying the same fix to an already-fixed job is a
  * no-op; the trigger gets removed regardless.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, watch, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
 import pino from 'pino';
 import { BASE_DIR, SYSTEM_DIR } from '../config.js';
 const logger = pino({ name: 'clementine.self-improve-loop' });
-const TICK_MS = 10 * 60 * 1000;
+/**
+ * Fallback tick interval. The loop is primarily event-driven via fs.watch
+ * on the triggers directory — this is just a slow safety net for cases
+ * where fs.watch dropped an event (rare but possible) or where the
+ * daemon booted with triggers already in place from before fs.watch was
+ * registered. 1h is plenty: the upstream cron scheduler runs at most
+ * once per minute, and a job needs 3+ consecutive errors to even produce
+ * a trigger, so the situation is already hours-stale by the time we see
+ * a trigger.
+ */
+const FALLBACK_TICK_MS = 60 * 60 * 1000;
+/** Coalesce a burst of fs.watch events into a single tick. */
+const WATCH_DEBOUNCE_MS = 2000;
 const TRIGGERS_DIR = path.join(BASE_DIR, 'self-improve', 'triggers');
 const PENDING_CHANGES_DIR = path.join(BASE_DIR, 'self-improve', 'pending-changes');
 const CRON_PATH = path.join(SYSTEM_DIR, 'CRON.md');
@@ -141,27 +153,49 @@ export class SelfImproveLoop {
     pendingDir;
     cronPath;
     dispatcher;
+    watchEnabled;
     timer = null;
+    watcher = null;
+    debounceTimer = null;
     running = false;
     ticking = false;
     constructor(dispatcher, opts = {}) {
         this.dispatcher = dispatcher;
-        this.tickMs = opts.tickMs ?? TICK_MS;
+        this.tickMs = opts.tickMs ?? FALLBACK_TICK_MS;
         this.triggersDir = opts.triggersDir ?? TRIGGERS_DIR;
         this.pendingDir = opts.pendingDir ?? PENDING_CHANGES_DIR;
         this.cronPath = opts.cronPath ?? CRON_PATH;
+        this.watchEnabled = opts.disableWatch !== true;
     }
     start() {
         if (this.running)
             return;
         this.running = true;
         // Run immediately so any backlog from the prior daemon gets handled
-        // without a 10-minute wait.
+        // without a long wait.
         this.tick().catch((err) => logger.error({ err }, 'Initial self-improve tick failed'));
+        // Event-driven primary path: watch the triggers dir. cron-scheduler
+        // writes a file when a job hits consErrors >= 3; we react within
+        // ~2 seconds (debounce window) instead of polling every 10 minutes
+        // for a directory that's empty 99% of the time.
+        if (this.watchEnabled) {
+            try {
+                mkdirSync(this.triggersDir, { recursive: true });
+                this.watcher = watch(this.triggersDir, (eventType, filename) => {
+                    if (eventType !== 'rename' || !filename || !filename.endsWith('.json'))
+                        return;
+                    this.scheduleDebouncedTick();
+                });
+            }
+            catch (err) {
+                logger.warn({ err, dir: this.triggersDir }, 'Failed to watch triggers dir — falling back to polling only');
+            }
+        }
+        // Slow fallback safety net — covers fs.watch event drops + boot-with-backlog.
         this.timer = setInterval(() => {
-            this.tick().catch((err) => logger.error({ err }, 'Self-improve tick failed'));
+            this.tick().catch((err) => logger.error({ err }, 'Self-improve fallback tick failed'));
         }, this.tickMs);
-        logger.info({ tickMs: this.tickMs }, 'Self-improve loop started');
+        logger.info({ fallbackTickMs: this.tickMs, watchEnabled: this.watchEnabled && this.watcher !== null }, 'Self-improve loop started');
     }
     stop() {
         if (!this.running)
@@ -171,8 +205,29 @@ export class SelfImproveLoop {
             clearInterval(this.timer);
             this.timer = null;
         }
+        if (this.watcher) {
+            try {
+                this.watcher.close();
+            }
+            catch { /* ignore */ }
+            this.watcher = null;
+        }
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
         logger.info('Self-improve loop stopped');
     }
+    /** Coalesce a burst of fs.watch events (multiple triggers landing in
+     * quick succession) into a single tick. */
+    scheduleDebouncedTick() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.tick().catch((err) => logger.error({ err }, 'Self-improve event-driven tick failed'));
+        }, WATCH_DEBOUNCE_MS);
+    }
     /**
      * Process all pending triggers. Public so tests + manual invocations
      * (e.g., a `clementine self-improve tick` CLI command) can call it.

package/dist/agent/self-improve.js

@@ -23,9 +23,11 @@ const DEFAULT_CONFIG = {
     maxDurationMs: 3_600_000, // 1 hour
     acceptThreshold: 0.7,
     plateauLimit: 3,
-    areas: ['soul', 'cron', 'workflow', 'memory', 'agent', 'source', 'communication', 'goal'],
+    // 'source' deprecated — self-improvement should produce data (cron, workflow, etc.),
+    // not engine TS edits. Re-add only with CLEMENTINE_ALLOW_SOURCE_EDITS=1.
+    areas: ['soul', 'cron', 'workflow', 'memory', 'agent', 'communication', 'goal'],
     autoApply: true,
-    sourceMode: 'propose-only',
+    sourceMode: 'skip',
 };
 // ── Paths ────────────────────────────────────────────────────────────
 const EXPERIMENT_LOG = path.join(SELF_IMPROVE_DIR, 'experiment-log.jsonl');

package/dist/channels/webhook.js

@@ -6,10 +6,13 @@
  */
 import express from 'express';
 import pino from 'pino';
-import { WEBHOOK_PORT, WEBHOOK_SECRET } from '../config.js';
+import { WEBHOOK_BIND, WEBHOOK_PORT, WEBHOOK_SECRET } from '../config.js';
 const logger = pino({ name: 'clementine.webhook' });
 // ── Entry point ───────────────────────────────────────────────────────
 export async function startWebhook(gateway) {
+    if (!WEBHOOK_SECRET) {
+        throw new Error('WEBHOOK_ENABLED=true requires WEBHOOK_SECRET to be set. Refusing to start an unauthenticated webhook server.');
+    }
     const app = express();
     app.use(express.json());
     // ── Bearer token auth middleware ──────────────────────────────────
@@ -54,8 +57,8 @@ export async function startWebhook(gateway) {
             res.status(500).json({ error: 'Internal server error' });
         }
     });
-    // ── GET /api/status — health check ────────────────────────────────
-    app.get('/api/status', (_req, res) => {
+    // ── GET /api/status — health check (auth-gated to avoid uptime leakage) ──
+    app.get('/api/status', requireAuth, (_req, res) => {
         res.json({
             status: 'ok',
             uptime: process.uptime(),
@@ -64,9 +67,13 @@ export async function startWebhook(gateway) {
     });
     // ── Start server ──────────────────────────────────────────────────
     const port = WEBHOOK_PORT;
+    const bind = WEBHOOK_BIND;
+    if (bind !== '127.0.0.1' && bind !== 'localhost') {
+        logger.warn({ bind }, '⚠ Webhook bound to non-localhost address — bearer auth is your only protection. Prefer tunneling (cloudflared) over exposing directly.');
+    }
     await new Promise((resolve) => {
-        app.listen(port, '0.0.0.0', () => {
-            logger.info(`Webhook API server listening on port ${port}`);
+        app.listen(port, bind, () => {
+            logger.info({ bind, port }, 'Webhook API server listening');
             resolve();
         });
     });

package/dist/config.d.ts

@@ -80,6 +80,7 @@ export declare const WHATSAPP_WEBHOOK_PORT: number;
 export declare const WEBHOOK_ENABLED: boolean;
 export declare const WEBHOOK_PORT: number;
 export declare const WEBHOOK_SECRET: string;
+export declare const WEBHOOK_BIND: string;
 export declare const GROQ_API_KEY: string;
 export declare const ELEVENLABS_API_KEY: string;
 export declare const ELEVENLABS_VOICE_ID: string;
@@ -150,6 +151,7 @@ export declare const PLANS_DIR: string;
 export declare const ADVISOR_LOG_PATH: string;
 export declare const REMOTE_ACCESS_CONFIG: string;
 export declare const STAGING_DIR: string;
+export declare const ALLOW_SOURCE_EDITS: boolean;
 export declare const CLAUDE_CODE_OAUTH_TOKEN: string;
 export declare const ANTHROPIC_API_KEY: string;
 export declare const CREDENTIALS_FILE: string;

package/dist/config.js

@@ -172,6 +172,9 @@ export const WHATSAPP_WEBHOOK_PORT = parseInt(getEnv('WHATSAPP_WEBHOOK_PORT', '8
 export const WEBHOOK_ENABLED = getEnv('WEBHOOK_ENABLED', 'false').toLowerCase() === 'true';
 export const WEBHOOK_PORT = parseInt(getEnv('WEBHOOK_PORT', '8420'), 10);
 export const WEBHOOK_SECRET = getSecret('WEBHOOK_SECRET');
+// Default bind to localhost only — flip to 0.0.0.0 explicitly via WEBHOOK_BIND
+// for tunneled or LAN-exposed setups. Avoids the OpenClaw CVE-2026-25253 shape.
+export const WEBHOOK_BIND = getEnv('WEBHOOK_BIND', '127.0.0.1');
 // ── Voice ────────────────────────────────────────────────────────────
 export const GROQ_API_KEY = getSecret('GROQ_API_KEY');
 export const ELEVENLABS_API_KEY = getSecret('ELEVENLABS_API_KEY');
@@ -302,6 +305,15 @@ export const ADVISOR_LOG_PATH = path.join(BASE_DIR, 'cron', 'advisor-decisions.j
 export const REMOTE_ACCESS_CONFIG = path.join(BASE_DIR, 'remote-access.json');
 // ── Source Self-Edit Staging ─────────────────────────────────────────
 export const STAGING_DIR = path.join(BASE_DIR, 'staging');
+// Source self-editing is deprecated. The data-driven path (advisor rules,
+// CRON.md frontmatter, prompt overrides) is the supported way to evolve
+// behavior without requiring a new release. Set CLEMENTINE_ALLOW_SOURCE_EDITS=1
+// in ~/.clementine/.env to re-enable for genuine engine bugs that can't be
+// expressed as data — the primitive itself stays on disk for that escape hatch.
+export const ALLOW_SOURCE_EDITS = (() => {
+    const raw = getEnv('CLEMENTINE_ALLOW_SOURCE_EDITS', '').toLowerCase().trim();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+})();
 // ── API ──────────────────────────────────────────────────────────────
 // Long-lived OAuth token from `clementine login` / `claude setup-token`.
 // Takes priority over ANTHROPIC_API_KEY in the SDK subprocess env.

package/dist/tools/admin-tools.js

@@ -15,6 +15,7 @@ import path from 'node:path';
 import Anthropic from '@anthropic-ai/sdk';
 import { z } from 'zod';
 import { BASE_DIR, CRON_FILE, SYSTEM_DIR, env, getStore, logger, textResult, } from './shared.js';
+import { ALLOW_SOURCE_EDITS } from '../config.js';
 import { getInteractionSource } from '../agent/hooks.js';
 import { renameSync } from 'node:fs';
 import * as keychain from '../secrets/keychain.js';
@@ -1628,11 +1629,22 @@ 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 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")'),
+    server.tool('self_edit_source', 'DEPRECATED — source self-editing is disabled. Improvements should be expressed as data, not TypeScript: edit advisor rules in ~/.clementine/advisor-rules/, CRON.md frontmatter, or prompt overrides. Those land without a restart and survive npm updates. Only re-enabled (CLEMENTINE_ALLOW_SOURCE_EDITS=1) for genuine engine bugs that cannot be expressed as data.', {
+        file: z.string().describe('Path relative to src/'),
         content: z.string().describe('Complete new file content'),
         reason: z.string().describe('Why this change is being made'),
-    }, async ({ file, content, reason }) => {
+    }, async ({ file, content: _content, reason }) => {
+        if (!ALLOW_SOURCE_EDITS) {
+            logger.warn({ file, reason }, 'self_edit_source called while disabled — rejecting');
+            return textResult('Source self-editing is disabled. The fix you want belongs in user-space data, not engine TypeScript:\n' +
+                '  • Cron job behavior → edit ~/.clementine/vault/00-System/CRON.md frontmatter\n' +
+                '  • Advisor logic → write a YAML file in ~/.clementine/advisor-rules/ (coming in next phase)\n' +
+                '  • Prompt content → edit the per-job prompt in CRON.md\n' +
+                '  • Agent behavior → edit the agent.md / SOUL.md\n\n' +
+                'Those changes land without a restart and survive `npm update -g clementine`. ' +
+                'If this is a genuine engine bug that cannot be expressed as data, ask the owner to set ' +
+                'CLEMENTINE_ALLOW_SOURCE_EDITS=1 in ~/.clementine/.env.');
+        }
         // Security blocklist
         const BLOCKLIST = ['config.ts', 'gateway/security-scanner.ts', 'security/scanner.ts'];
         if (BLOCKLIST.some(b => file === b || file.startsWith(b))) {
@@ -1646,7 +1658,7 @@ export function registerAdminTools(server) {
         const pending = {
             id,
             file: `src/${file}`,
-            content,
+            content: _content,
             reason,
             createdAt: new Date().toISOString(),
         };

package/package.json

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