clementine-agent 1.18.142 → 1.18.143

package/dist/gateway/agent-heartbeat-scheduler.d.ts

@@ -3,6 +3,18 @@
  * the user's team. Runs autonomously alongside Clementine's own
  * HeartbeatScheduler.
  *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It has NO loop. Unlike HeartbeatScheduler (setInterval) and
+ *     CronScheduler (node-cron), this one is ticked externally by
+ *     whatever orchestrator manages the agent fleet. Its `tick()` is a
+ *     pure function of state + signals.
+ *   - Its scheduling decision is *adaptive* (computeNextInterval) based
+ *     on the previous tick's outcome — not a fixed cadence. Forcing it
+ *     into a generic "interval-based" base would lose this behavior.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
+ *
  * Phase 2 — cheap path only. No LLM call. The tick loads state, scans
  * three signals (pending delegated tasks, recent goal updates, recent
  * cron completions), updates fingerprint, and persists state.

package/dist/gateway/agent-heartbeat-scheduler.js

@@ -3,6 +3,18 @@
  * the user's team. Runs autonomously alongside Clementine's own
  * HeartbeatScheduler.
  *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It has NO loop. Unlike HeartbeatScheduler (setInterval) and
+ *     CronScheduler (node-cron), this one is ticked externally by
+ *     whatever orchestrator manages the agent fleet. Its `tick()` is a
+ *     pure function of state + signals.
+ *   - Its scheduling decision is *adaptive* (computeNextInterval) based
+ *     on the previous tick's outcome — not a fixed cadence. Forcing it
+ *     into a generic "interval-based" base would lose this behavior.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
+ *
  * Phase 2 — cheap path only. No LLM call. The tick loads state, scans
  * three signals (pending delegated tasks, recent goal updates, recent
  * cron completions), updates fingerprint, and persists state.
@@ -11,11 +23,12 @@
  * agent's profile) when the fingerprint indicates a real signal change.
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
 import { AGENTS_DIR, BASE_DIR } from '../config.js';
 import { listAllGoals } from '../tools/shared.js';
+import { loadStateFile, saveStateFile } from './scheduler-state.js';
 const logger = pino({ name: 'clementine.agent-heartbeat' });
 const DEFAULT_INTERVAL_MIN = 30;
 const MIN_INTERVAL_MIN = 5;
@@ -81,43 +94,32 @@ export class AgentHeartbeatScheduler {
     }
     /** Read persisted state, or return a fresh state ready to tick now. */
     loadState() {
-        try {
-            if (existsSync(this.stateFile)) {
-                const raw = JSON.parse(readFileSync(this.stateFile, 'utf-8'));
-                const validKinds = ['acted', 'quiet', 'silent', 'override'];
-                const kind = validKinds.includes(raw.lastTickKind)
-                    ? raw.lastTickKind
-                    : undefined;
-                return {
-                    slug: this.slug,
-                    lastTickAt: String(raw.lastTickAt ?? ''),
-                    nextCheckAt: String(raw.nextCheckAt ?? new Date().toISOString()),
-                    silentTickCount: Number(raw.silentTickCount ?? 0),
-                    fingerprint: String(raw.fingerprint ?? ''),
-                    ...(raw.lastSignalSummary ? { lastSignalSummary: raw.lastSignalSummary } : {}),
-                    ...(kind ? { lastTickKind: kind } : {}),
-                };
-            }
-        }
-        catch (err) {
-            logger.warn({ err, slug: this.slug }, 'Failed to load agent heartbeat state — starting fresh');
-        }
-        return {
+        const fresh = {
             slug: this.slug,
             lastTickAt: '',
             nextCheckAt: new Date().toISOString(),
             silentTickCount: 0,
             fingerprint: '',
         };
+        return loadStateFile(this.stateFile, fresh, (raw) => {
+            const r = raw;
+            const validKinds = ['acted', 'quiet', 'silent', 'override'];
+            const kind = validKinds.includes(r.lastTickKind)
+                ? r.lastTickKind
+                : undefined;
+            return {
+                slug: this.slug,
+                lastTickAt: String(r.lastTickAt ?? ''),
+                nextCheckAt: String(r.nextCheckAt ?? new Date().toISOString()),
+                silentTickCount: Number(r.silentTickCount ?? 0),
+                fingerprint: String(r.fingerprint ?? ''),
+                ...(r.lastSignalSummary ? { lastSignalSummary: r.lastSignalSummary } : {}),
+                ...(kind ? { lastTickKind: kind } : {}),
+            };
+        });
     }
     saveState(state) {
-        try {
-            mkdirSync(path.dirname(this.stateFile), { recursive: true });
-            writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
-        }
-        catch (err) {
-            logger.warn({ err, slug: this.slug }, 'Failed to save agent heartbeat state — non-fatal');
-        }
+        saveStateFile(this.stateFile, state);
     }
     /** True if the agent is due for a tick. */
     isDue(now = new Date()) {

package/dist/gateway/cron-scheduler.d.ts

@@ -1,10 +1,28 @@
 /**
  * Clementine TypeScript — Cron scheduler (autonomous execution).
  *
- * CronScheduler: precise scheduled tasks using node-cron
+ * CronScheduler: precise per-job scheduled tasks using node-cron. Each
+ * cron job (defined in CRON.md or via the schedule registry) gets its
+ * own ScheduledTask instance with that job's cron expression, so the
+ * scheduling primitive here is fundamentally different from the
+ * fixed-interval HeartbeatScheduler and the externally-ticked
+ * AgentHeartbeatScheduler.
  *
- * Also contains shared parsers (parseCronJobs, parseAgentCronJobs, validateCronYaml),
- * retry helpers, CronRunLog, and daily-note logging utilities used by both schedulers.
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - One node-cron task per job. CronScheduler maintains the
+ *     scheduledTasks/workflowTasks maps; a generic base class would
+ *     have to model "N independent timers" which the other two don't
+ *     need.
+ *   - Owns crash-safe idempotency (cron-running.json), workflow
+ *     execution, file watching, trigger directories, broken-job
+ *     tracking. None of these belong in a generic base.
+ *
+ * Also contains shared parsers (parseCronJobs, parseAgentCronJobs,
+ * validateCronYaml), retry helpers, CronRunLog, and daily-note logging
+ * utilities used by both schedulers.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import type { CronJobDefinition, CronRunEntry, SelfImproveConfig, SelfImproveExperiment, SelfImproveState, WorkflowDefinition } from '../types.js';
 import type { NotificationDispatcher } from './notifications.js';

package/dist/gateway/cron-scheduler.js

@@ -1,13 +1,31 @@
 /**
  * Clementine TypeScript — Cron scheduler (autonomous execution).
  *
- * CronScheduler: precise scheduled tasks using node-cron
+ * CronScheduler: precise per-job scheduled tasks using node-cron. Each
+ * cron job (defined in CRON.md or via the schedule registry) gets its
+ * own ScheduledTask instance with that job's cron expression, so the
+ * scheduling primitive here is fundamentally different from the
+ * fixed-interval HeartbeatScheduler and the externally-ticked
+ * AgentHeartbeatScheduler.
  *
- * Also contains shared parsers (parseCronJobs, parseAgentCronJobs, validateCronYaml),
- * retry helpers, CronRunLog, and daily-note logging utilities used by both schedulers.
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - One node-cron task per job. CronScheduler maintains the
+ *     scheduledTasks/workflowTasks maps; a generic base class would
+ *     have to model "N independent timers" which the other two don't
+ *     need.
+ *   - Owns crash-safe idempotency (cron-running.json), workflow
+ *     execution, file watching, trigger directories, broken-job
+ *     tracking. None of these belong in a generic base.
+ *
+ * Also contains shared parsers (parseCronJobs, parseAgentCronJobs,
+ * validateCronYaml), retry helpers, CronRunLog, and daily-note logging
+ * utilities used by both schedulers.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import { execSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, watchFile, unwatchFile, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, watchFile, unwatchFile, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import cron from 'node-cron';
 import matter from 'gray-matter';
@@ -15,6 +33,7 @@ import pino from 'pino';
 import { CRON_FILE, WORKFLOWS_DIR, AGENTS_DIR, DAILY_NOTES_DIR, BASE_DIR, DISCORD_OWNER_ID, GOALS_DIR, CRON_REFLECTIONS_DIR, ADVISOR_LOG_PATH, TIMEZONE, } from '../config.js';
 import { listAllGoals, findGoalPath, readGoalById } from '../tools/shared.js';
 import { listSchedules } from '../agent/schedule-registry.js';
+import { saveStateFile } from './scheduler-state.js';
 import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
@@ -579,20 +598,13 @@ export class CronScheduler {
      * rename so a crash mid-write cannot corrupt the file.
      */
     persistRunningJobs(metaByName) {
-        try {
-            const entries = [...this.runningJobs].map(name => ({
-                jobName: name,
-                startedAt: metaByName?.get(name)?.startedAt ?? new Date().toISOString(),
-                runId: metaByName?.get(name)?.runId ?? '',
-                pid: process.pid,
-            }));
-            const tmp = CronScheduler.RUNNING_JOBS_FILE + '.tmp';
-            writeFileSync(tmp, JSON.stringify(entries, null, 2));
-            renameSync(tmp, CronScheduler.RUNNING_JOBS_FILE);
-        }
-        catch (err) {
-            logger.debug({ err }, 'Failed to persist running-jobs file');
-        }
+        const entries = [...this.runningJobs].map(name => ({
+            jobName: name,
+            startedAt: metaByName?.get(name)?.startedAt ?? new Date().toISOString(),
+            runId: metaByName?.get(name)?.runId ?? '',
+            pid: process.pid,
+        }));
+        saveStateFile(CronScheduler.RUNNING_JOBS_FILE, entries, { atomic: true });
     }
     /**
      * On startup, read the persisted running-jobs file. Any entries present

package/dist/gateway/heartbeat-scheduler.d.ts

@@ -1,8 +1,21 @@
 /**
  * Clementine TypeScript — Heartbeat scheduler.
  *
- * HeartbeatScheduler: periodic general check-ins using setInterval.
- * Channel-agnostic — sends notifications via the NotificationDispatcher.
+ * HeartbeatScheduler: periodic general check-ins using setInterval
+ * (one tick every HEARTBEAT_INTERVAL_MINUTES, default 30 min, gated to
+ * the HEARTBEAT_ACTIVE_START..ACTIVE_END window). Channel-agnostic —
+ * sends notifications via the NotificationDispatcher.
+ *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It uses a fixed setInterval. Different scheduling primitive than
+ *     CronScheduler (which uses node-cron per-job) and AgentHeartbeat
+ *     Scheduler (which is ticked externally — has no loop of its own).
+ *   - It owns autonomous concerns: insight engine, proactive ledger,
+ *     dense-vector backfill, salience decay, episodic consolidation.
+ *     None of these belong in a generic scheduler base.
+ *
+ * Shared with the other two schedulers: only the JSON state-file
+ * load/save pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import type { HeartbeatWorkItem } from '../types.js';
 import type { CronScheduler } from './cron-scheduler.js';

package/dist/gateway/heartbeat-scheduler.js

@@ -1,8 +1,21 @@
 /**
  * Clementine TypeScript — Heartbeat scheduler.
  *
- * HeartbeatScheduler: periodic general check-ins using setInterval.
- * Channel-agnostic — sends notifications via the NotificationDispatcher.
+ * HeartbeatScheduler: periodic general check-ins using setInterval
+ * (one tick every HEARTBEAT_INTERVAL_MINUTES, default 30 min, gated to
+ * the HEARTBEAT_ACTIVE_START..ACTIVE_END window). Channel-agnostic —
+ * sends notifications via the NotificationDispatcher.
+ *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It uses a fixed setInterval. Different scheduling primitive than
+ *     CronScheduler (which uses node-cron per-job) and AgentHeartbeat
+ *     Scheduler (which is ticked externally — has no loop of its own).
+ *   - It owns autonomous concerns: insight engine, proactive ledger,
+ *     dense-vector backfill, salience decay, episodic consolidation.
+ *     None of these belong in a generic scheduler base.
+ *
+ * Shared with the other two schedulers: only the JSON state-file
+ * load/save pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
@@ -11,6 +24,7 @@ import matter from 'gray-matter';
 import pino from 'pino';
 import { HEARTBEAT_FILE, TASKS_FILE, INBOX_DIR, DAILY_NOTES_DIR, HEARTBEAT_INTERVAL_MINUTES, HEARTBEAT_ACTIVE_START, HEARTBEAT_ACTIVE_END, BASE_DIR, GOALS_DIR, AGENTS_DIR, HEARTBEAT_WORK_QUEUE_FILE, DISCORD_OWNER_ID, } from '../config.js';
 import { findGoalPath, listAllGoals } from '../tools/shared.js';
+import { loadStateFile, saveStateFile } from './scheduler-state.js';
 import { gatherInsightSignals, buildInsightPrompt, parseInsightResponse, canSendInsight, recordInsightSent, recordInsightAcked, maybeIncreaseCooldown, } from '../agent/insight-engine.js';
 import { decideDailyPlanPriority, decideDiscoveredWorkItem, decideGoalAdvancement, decisionShouldCreateGoalTrigger, decisionShouldQueueHeartbeatWork, } from '../agent/proactive-engine.js';
 import { recentDecisions, recordDecision, recordDecisionOutcome, wasRecentlyDecided, } from '../agent/proactive-ledger.js';
@@ -1144,23 +1158,10 @@ export class HeartbeatScheduler {
         return parsed.content;
     }
     loadState() {
-        if (existsSync(this.stateFile)) {
-            try {
-                return JSON.parse(readFileSync(this.stateFile, 'utf-8'));
-            }
-            catch {
-                logger.warn('Failed to load heartbeat state — starting fresh');
-            }
-        }
-        return { fingerprint: '', details: {}, timestamp: '' };
+        return loadStateFile(this.stateFile, { fingerprint: '', details: {}, timestamp: '' });
     }
     saveState() {
-        try {
-            writeFileSync(this.stateFile, JSON.stringify(this.lastState, null, 2));
-        }
-        catch (err) {
-            logger.warn({ err }, 'Failed to save heartbeat state');
-        }
+        saveStateFile(this.stateFile, this.lastState);
     }
     computeStateFingerprint() {
         const details = {};

package/dist/gateway/scheduler-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Scheduler state-file helpers (1.18.143)
+ *
+ * Three schedulers each persist a JSON state file (heartbeat,
+ * cron-running-jobs, per-agent heartbeat). Before this module they
+ * each reimplemented "try parse, fall back on error" + "write JSON,
+ * log on error". The patterns are tiny but they were drifting (some
+ * had `mkdirSync`, some had atomic write-then-rename, some had
+ * neither — and a future addition would have copied yet another
+ * variant).
+ *
+ * This module is the single source of truth for both shapes:
+ *
+ *   loadStateFile(path, default, validator?)
+ *     — read JSON, fall back to default on missing/invalid file,
+ *       optionally run a validator that can clean/coerce the parsed
+ *       payload before returning it.
+ *
+ *   saveStateFile(path, state, opts)
+ *     — ensure parent dir exists, then either plain
+ *       writeFileSync (default) or atomic write-then-rename for
+ *       crash-safe persistence (set `atomic: true`).
+ *
+ * Both swallow filesystem errors and log a warning — the schedulers
+ * treat persistence as best-effort (a missing/corrupt state file
+ * means "start fresh", not "crash"). Callers that need failure
+ * surfaced should check the boolean return on saveStateFile.
+ */
+/**
+ * Read a JSON state file. Returns `defaultValue` if the file is
+ * missing, unreadable, or fails JSON parse. Optional validator runs
+ * after parse and can return a cleaned-up version (e.g. coerce
+ * missing fields, drop invalid values).
+ */
+export declare function loadStateFile<T>(filePath: string, defaultValue: T, validator?: (raw: unknown) => T): T;
+export interface SaveStateOptions {
+    /**
+     * If true, write to `<file>.tmp` then rename — guarantees the on-disk
+     * file is either the previous state or the new state, never a half-
+     * written file. Use for state that must survive crashes mid-write
+     * (cron-running.json relies on this for idempotency).
+     */
+    atomic?: boolean;
+}
+/**
+ * Write a JSON state file. Creates the parent directory if missing.
+ * Returns true on success, false on failure (always logs a warning
+ * on failure — caller doesn't need to log again).
+ */
+export declare function saveStateFile<T>(filePath: string, state: T, opts?: SaveStateOptions): boolean;
+//# sourceMappingURL=scheduler-state.d.ts.map

package/dist/gateway/scheduler-state.js

@@ -0,0 +1,75 @@
+/**
+ * Scheduler state-file helpers (1.18.143)
+ *
+ * Three schedulers each persist a JSON state file (heartbeat,
+ * cron-running-jobs, per-agent heartbeat). Before this module they
+ * each reimplemented "try parse, fall back on error" + "write JSON,
+ * log on error". The patterns are tiny but they were drifting (some
+ * had `mkdirSync`, some had atomic write-then-rename, some had
+ * neither — and a future addition would have copied yet another
+ * variant).
+ *
+ * This module is the single source of truth for both shapes:
+ *
+ *   loadStateFile(path, default, validator?)
+ *     — read JSON, fall back to default on missing/invalid file,
+ *       optionally run a validator that can clean/coerce the parsed
+ *       payload before returning it.
+ *
+ *   saveStateFile(path, state, opts)
+ *     — ensure parent dir exists, then either plain
+ *       writeFileSync (default) or atomic write-then-rename for
+ *       crash-safe persistence (set `atomic: true`).
+ *
+ * Both swallow filesystem errors and log a warning — the schedulers
+ * treat persistence as best-effort (a missing/corrupt state file
+ * means "start fresh", not "crash"). Callers that need failure
+ * surfaced should check the boolean return on saveStateFile.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.scheduler-state' });
+/**
+ * Read a JSON state file. Returns `defaultValue` if the file is
+ * missing, unreadable, or fails JSON parse. Optional validator runs
+ * after parse and can return a cleaned-up version (e.g. coerce
+ * missing fields, drop invalid values).
+ */
+export function loadStateFile(filePath, defaultValue, validator) {
+    try {
+        if (!existsSync(filePath))
+            return defaultValue;
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        return validator ? validator(raw) : raw;
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to load state file — starting fresh');
+        return defaultValue;
+    }
+}
+/**
+ * Write a JSON state file. Creates the parent directory if missing.
+ * Returns true on success, false on failure (always logs a warning
+ * on failure — caller doesn't need to log again).
+ */
+export function saveStateFile(filePath, state, opts = {}) {
+    try {
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        const json = JSON.stringify(state, null, 2);
+        if (opts.atomic) {
+            const tmp = filePath + '.tmp';
+            writeFileSync(tmp, json);
+            renameSync(tmp, filePath);
+        }
+        else {
+            writeFileSync(filePath, json);
+        }
+        return true;
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to save state file');
+        return false;
+    }
+}
+//# sourceMappingURL=scheduler-state.js.map

package/package.json

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