clementine-agent 1.0.76 → 1.0.78

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

@@ -0,0 +1,123 @@
+/**
+ * Owns the lifecycle of all per-agent heartbeat schedulers.
+ *
+ * Boots at daemon start, scans the AgentManager's active list, spawns one
+ * AgentHeartbeatScheduler per agent. An outer 60s interval iterates the
+ * registry and fires `tick()` on any agent whose nextCheckAt is due.
+ *
+ * Reconciliation runs each outer tick: agents added to AGENTS_DIR start
+ * heartbeats automatically; agents removed (or paused/terminated) drop
+ * out. Per-agent failures are caught so one buggy agent can't crash the
+ * daemon or stall others.
+ */
+import pino from 'pino';
+import { AgentHeartbeatScheduler } from './agent-heartbeat-scheduler.js';
+const logger = pino({ name: 'clementine.agent-heartbeat-manager' });
+const OUTER_TICK_MS = 60_000;
+export class AgentHeartbeatManager {
+    agentManager;
+    schedulers = new Map();
+    timer = null;
+    running = false;
+    ticking = false;
+    constructor(agentManager) {
+        this.agentManager = agentManager;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.reconcile();
+        // Run an immediate tick so schedulers boot up without a 60s delay.
+        this.outerTick().catch((err) => logger.error({ err }, 'Initial agent heartbeat tick failed'));
+        this.timer = setInterval(() => {
+            this.outerTick().catch((err) => logger.error({ err }, 'Agent heartbeat outer tick failed'));
+        }, OUTER_TICK_MS);
+        logger.info({ agents: this.schedulers.size }, 'Agent heartbeat manager started');
+    }
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.schedulers.clear();
+        logger.info('Agent heartbeat manager stopped');
+    }
+    /** Add/remove schedulers to match the current AgentManager listing. */
+    reconcile() {
+        let active = [];
+        try {
+            active = this.agentManager
+                .listAll()
+                .filter((p) => p.slug !== 'clementine' && this.agentManager.isRunnable(p.slug))
+                .map((p) => p.slug);
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to list agents during reconcile — keeping current set');
+            return;
+        }
+        const activeSet = new Set(active);
+        // Add new
+        for (const slug of active) {
+            if (!this.schedulers.has(slug)) {
+                this.schedulers.set(slug, new AgentHeartbeatScheduler(slug, this.agentManager));
+                logger.info({ slug }, 'Agent heartbeat: registered scheduler');
+            }
+        }
+        // Remove gone-or-paused
+        for (const slug of [...this.schedulers.keys()]) {
+            if (!activeSet.has(slug)) {
+                this.schedulers.delete(slug);
+                logger.info({ slug }, 'Agent heartbeat: deregistered scheduler');
+            }
+        }
+    }
+    /**
+     * One outer-loop tick. Reconcile the registry, then fire agents whose
+     * nextCheckAt has come due. Runs serially to avoid races on shared
+     * state (goals dir, cron runs dir).
+     */
+    async outerTick(now = new Date()) {
+        if (this.ticking)
+            return; // prior outer tick still in flight — skip
+        this.ticking = true;
+        try {
+            this.reconcile();
+            for (const [slug, scheduler] of this.schedulers) {
+                try {
+                    if (!scheduler.isDue(now))
+                        continue;
+                    await scheduler.tick(now);
+                }
+                catch (err) {
+                    logger.warn({ err, slug }, 'Agent heartbeat tick failed — continuing');
+                }
+            }
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    /** Diagnostic helper for the dashboard / CLI. */
+    getStatus() {
+        const out = [];
+        for (const [slug, scheduler] of this.schedulers) {
+            const state = scheduler.loadState();
+            out.push({
+                slug,
+                nextCheckAt: state.nextCheckAt,
+                lastTickAt: state.lastTickAt,
+                silentTickCount: state.silentTickCount,
+            });
+        }
+        return out;
+    }
+    /** Look up a scheduler — useful for CLI commands like "tick this agent now." */
+    getScheduler(slug) {
+        return this.schedulers.get(slug) ?? null;
+    }
+}
+//# sourceMappingURL=agent-heartbeat-manager.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * Per-agent heartbeat scheduler — one instance per specialist agent
+ * (Ross, Sasha, Nora, etc.). Runs autonomously alongside Clementine's
+ * own HeartbeatScheduler.
+ *
+ * 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.
+ *
+ * Phase 3 will add the LLM-path tick (assistant.heartbeat() with the
+ * agent's profile) when the fingerprint indicates a real signal change.
+ */
+import type { AgentHeartbeatState } from '../types.js';
+import type { AgentManager } from '../agent/agent-manager.js';
+export interface AgentHeartbeatOptions {
+    /** Override the base directory for test isolation. Defaults to config.BASE_DIR. */
+    baseDir?: string;
+    /** Override the agents directory for test isolation. Defaults to config.AGENTS_DIR. */
+    agentsDir?: string;
+}
+export declare class AgentHeartbeatScheduler {
+    private readonly slug;
+    private readonly agentManager;
+    private readonly baseDir;
+    private readonly agentsDir;
+    private readonly stateFile;
+    constructor(slug: string, agentManager: AgentManager, opts?: AgentHeartbeatOptions);
+    /** Read persisted state, or return a fresh state ready to tick now. */
+    loadState(): AgentHeartbeatState;
+    saveState(state: AgentHeartbeatState): void;
+    /** True if the agent is due for a tick. */
+    isDue(now?: Date): boolean;
+    /**
+     * Compute a cheap fingerprint of "anything material to this agent."
+     * Three signals: pending delegated tasks, latest goal update, latest
+     * cron run timestamp. Sync filesystem reads — bounded and small.
+     */
+    private buildFingerprint;
+    /**
+     * Cheap-path tick. Returns the new state. P3 will branch into an LLM
+     * call when the fingerprint changed; for now we just observe and log.
+     */
+    tick(now?: Date): Promise<AgentHeartbeatState>;
+    /** Schedule the next check explicitly. Clamped to [MIN, MAX] minutes. */
+    setNextCheckIn(minutes: number, now?: Date): void;
+    getSlug(): string;
+}
+//# sourceMappingURL=agent-heartbeat-scheduler.d.ts.map

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

@@ -0,0 +1,223 @@
+/**
+ * Per-agent heartbeat scheduler — one instance per specialist agent
+ * (Ross, Sasha, Nora, etc.). Runs autonomously alongside Clementine's
+ * own HeartbeatScheduler.
+ *
+ * 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.
+ *
+ * Phase 3 will add the LLM-path tick (assistant.heartbeat() with the
+ * 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 path from 'node:path';
+import pino from 'pino';
+import { AGENTS_DIR, BASE_DIR } from '../config.js';
+import { listAllGoals } from '../tools/shared.js';
+const logger = pino({ name: 'clementine.agent-heartbeat' });
+const DEFAULT_INTERVAL_MIN = 30;
+const MIN_INTERVAL_MIN = 5;
+const MAX_INTERVAL_MIN = 12 * 60;
+export class AgentHeartbeatScheduler {
+    slug;
+    agentManager;
+    baseDir;
+    agentsDir;
+    stateFile;
+    constructor(slug, agentManager, opts = {}) {
+        this.slug = slug;
+        this.agentManager = agentManager;
+        this.baseDir = opts.baseDir ?? BASE_DIR;
+        this.agentsDir = opts.agentsDir ?? AGENTS_DIR;
+        this.stateFile = path.join(this.baseDir, 'heartbeat', 'agents', slug, 'state.json');
+    }
+    /** 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'));
+                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 } : {}),
+                };
+            }
+        }
+        catch (err) {
+            logger.warn({ err, slug: this.slug }, 'Failed to load agent heartbeat state — starting fresh');
+        }
+        return {
+            slug: this.slug,
+            lastTickAt: '',
+            nextCheckAt: new Date().toISOString(),
+            silentTickCount: 0,
+            fingerprint: '',
+        };
+    }
+    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');
+        }
+    }
+    /** True if the agent is due for a tick. */
+    isDue(now = new Date()) {
+        const state = this.loadState();
+        if (!state.nextCheckAt)
+            return true;
+        return new Date(state.nextCheckAt).getTime() <= now.getTime();
+    }
+    /**
+     * Compute a cheap fingerprint of "anything material to this agent."
+     * Three signals: pending delegated tasks, latest goal update, latest
+     * cron run timestamp. Sync filesystem reads — bounded and small.
+     */
+    buildFingerprint() {
+        const signals = { slug: this.slug };
+        // 1. Pending delegated task count
+        try {
+            const tasksDir = path.join(this.agentsDir, this.slug, 'tasks');
+            if (existsSync(tasksDir)) {
+                const files = readdirSync(tasksDir).filter((f) => f.endsWith('.json'));
+                let pendingCount = 0;
+                for (const file of files) {
+                    try {
+                        const task = JSON.parse(readFileSync(path.join(tasksDir, file), 'utf-8'));
+                        if (task && task.status === 'pending')
+                            pendingCount++;
+                    }
+                    catch { /* skip malformed */ }
+                }
+                signals.pendingTasks = pendingCount;
+            }
+            else {
+                signals.pendingTasks = 0;
+            }
+        }
+        catch {
+            signals.pendingTasks = 0;
+        }
+        // 2. Latest goal updatedAt for this agent's goals
+        try {
+            let latest = '';
+            for (const { goal, owner } of listAllGoals()) {
+                if (owner !== this.slug)
+                    continue;
+                const updatedAt = goal.updatedAt ?? '';
+                if (updatedAt > latest)
+                    latest = updatedAt;
+            }
+            signals.latestGoalUpdate = latest;
+        }
+        catch {
+            signals.latestGoalUpdate = '';
+        }
+        // 3. Latest cron run for any of this agent's crons (file mtime is enough)
+        try {
+            const runsDir = path.join(this.baseDir, 'cron', 'runs');
+            let latestMs = 0;
+            if (existsSync(runsDir)) {
+                const prefix = `${this.slug}:`;
+                for (const file of readdirSync(runsDir)) {
+                    if (!file.endsWith('.jsonl'))
+                        continue;
+                    if (!file.startsWith(prefix) && !file.startsWith(this.slug + '_'))
+                        continue;
+                    try {
+                        const mtime = statSync(path.join(runsDir, file)).mtimeMs;
+                        if (mtime > latestMs)
+                            latestMs = mtime;
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            signals.latestCronRunMs = latestMs;
+        }
+        catch {
+            signals.latestCronRunMs = 0;
+        }
+        const fingerprint = createHash('sha1')
+            .update(JSON.stringify(signals))
+            .digest('hex')
+            .slice(0, 16);
+        return { fingerprint, signals };
+    }
+    /**
+     * Cheap-path tick. Returns the new state. P3 will branch into an LLM
+     * call when the fingerprint changed; for now we just observe and log.
+     */
+    async tick(now = new Date()) {
+        const profile = this.agentManager.get(this.slug);
+        if (!profile) {
+            // Agent was removed mid-flight — return a state that won't tick again soon.
+            return {
+                slug: this.slug,
+                lastTickAt: now.toISOString(),
+                nextCheckAt: new Date(now.getTime() + MAX_INTERVAL_MIN * 60_000).toISOString(),
+                silentTickCount: 0,
+                fingerprint: '',
+                lastSignalSummary: 'agent profile not found',
+            };
+        }
+        if (!this.agentManager.isRunnable(this.slug)) {
+            logger.debug({ slug: this.slug, status: profile.status }, 'Agent not runnable — skipping tick');
+            const next = new Date(now.getTime() + DEFAULT_INTERVAL_MIN * 60_000);
+            const prior = this.loadState();
+            const state = {
+                ...prior,
+                slug: this.slug,
+                lastTickAt: now.toISOString(),
+                nextCheckAt: next.toISOString(),
+            };
+            this.saveState(state);
+            return state;
+        }
+        const prior = this.loadState();
+        const { fingerprint, signals } = this.buildFingerprint();
+        const changed = fingerprint !== prior.fingerprint;
+        const next = new Date(now.getTime() + DEFAULT_INTERVAL_MIN * 60_000);
+        const state = {
+            slug: this.slug,
+            lastTickAt: now.toISOString(),
+            nextCheckAt: next.toISOString(),
+            silentTickCount: changed ? 0 : prior.silentTickCount + 1,
+            fingerprint,
+            ...(changed
+                ? { lastSignalSummary: `signal change: ${JSON.stringify(signals)}`.slice(0, 240) }
+                : prior.lastSignalSummary
+                    ? { lastSignalSummary: prior.lastSignalSummary }
+                    : {}),
+        };
+        this.saveState(state);
+        if (changed) {
+            logger.info({ slug: this.slug, signals, fingerprint }, 'Agent heartbeat: signal change detected (LLM path is P3)');
+        }
+        else {
+            logger.debug({ slug: this.slug, silentTicks: state.silentTickCount }, 'Agent heartbeat: silent tick');
+        }
+        return state;
+    }
+    /** Schedule the next check explicitly. Clamped to [MIN, MAX] minutes. */
+    setNextCheckIn(minutes, now = new Date()) {
+        const clamped = Math.max(MIN_INTERVAL_MIN, Math.min(MAX_INTERVAL_MIN, Math.floor(minutes)));
+        const prior = this.loadState();
+        const state = {
+            ...prior,
+            slug: this.slug,
+            nextCheckAt: new Date(now.getTime() + clamped * 60_000).toISOString(),
+        };
+        this.saveState(state);
+    }
+    getSlug() {
+        return this.slug;
+    }
+}
+//# sourceMappingURL=agent-heartbeat-scheduler.js.map

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

@@ -159,6 +159,7 @@ export declare class CronScheduler {
      * Creates the causal link: "action X was attempted for goal Y, result was Z."
      */
     private logGoalOutcome;
+    private logProactiveDecisionOutcome;
     /**
      * Apply non-destructive cron changes suggested by the daily planner.
      * Only auto-applies suggestions that reference a high-priority goal with autoSchedule=true.

package/dist/gateway/cron-scheduler.js

@@ -18,6 +18,7 @@ import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
 import { logAuditJsonl } from '../agent/hooks.js';
+import { outcomeStatusFromGoalDisposition, recentDecisions, recordDecisionOutcome, } from '../agent/proactive-ledger.js';
 const logger = pino({ name: 'clementine.cron' });
 /** Default timeout for standard cron jobs (10 minutes). */
 const CRON_STANDARD_TIMEOUT_MS = 10 * 60 * 1000;
@@ -1643,7 +1644,7 @@ export class CronScheduler {
                     const advice = getExecutionAdvice(jobName, syntheticJob);
                     if (advice.shouldSkip) {
                         logger.info({ goalId: trigger.goalId, reason: advice.skipReason }, 'Goal work skipped by advisor (circuit breaker)');
-                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source, null, `Skipped: ${advice.skipReason}`);
+                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source ?? 'unknown', null, `Skipped: ${advice.skipReason}`, trigger.decision);
                         return;
                     }
                     const effectiveMaxTurns = advice.adjustedMaxTurns ?? syntheticJob.maxTurns ?? 15;
@@ -1667,10 +1668,10 @@ export class CronScheduler {
                             this.dispatcher.send(`🎯 **Goal work: ${goal.title}**\n\n${result.slice(0, 1500)}`, dispatchOpts).catch(err => logger.debug({ err }, 'Failed to send goal work notification'));
                         }
                         logToDailyNote(`**Goal work: ${goal.title}** — ${(result || 'completed').slice(0, 100).replace(/\n/g, ' ')}`);
-                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source, result);
+                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source ?? 'unknown', result, undefined, trigger.decision);
                     }).catch((err) => {
                         logger.error({ err, goalId: trigger.goalId }, 'Goal work session failed');
-                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source, null, String(err));
+                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source ?? 'unknown', null, String(err), trigger.decision);
                     });
                 }).catch((err) => {
                     // Advisor import failed — fall back to basic execution
@@ -1686,10 +1687,10 @@ export class CronScheduler {
                             this.dispatcher.send(`🎯 **Goal work: ${goal.title}**\n\n${result.slice(0, 1500)}`, dispatchOpts).catch(err => logger.debug({ err }, 'Failed to send goal work notification'));
                         }
                         logToDailyNote(`**Goal work: ${goal.title}** — ${(result || 'completed').slice(0, 100).replace(/\n/g, ' ')}`);
-                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source, result);
+                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source ?? 'unknown', result, undefined, trigger.decision);
                     }).catch((goalErr) => {
                         logger.error({ err: goalErr, goalId: trigger.goalId }, 'Goal work session failed');
-                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source, null, String(goalErr));
+                        this.logGoalOutcome(trigger.goalId, goalPath, goalSnapshotUpdatedAt, goalSnapshotNotes, trigger.focus, trigger.source ?? 'unknown', null, String(goalErr), trigger.decision);
                     });
                 });
             }
@@ -1706,7 +1707,7 @@ export class CronScheduler {
      * Log goal work session outcome to a per-goal progress JSONL file.
      * Creates the causal link: "action X was attempted for goal Y, result was Z."
      */
-    logGoalOutcome(goalId, goalPath, prevUpdatedAt, prevNotesCount, focus, source, result, error) {
+    logGoalOutcome(goalId, goalPath, prevUpdatedAt, prevNotesCount, focus, source, result, error, proactiveDecision) {
         try {
             let madeProgress = false;
             let newNotesCount = prevNotesCount;
@@ -1738,12 +1739,46 @@ export class CronScheduler {
             mkdirSync(progressDir, { recursive: true });
             const progressFile = path.join(progressDir, `${goalId}.progress.jsonl`);
             appendFileSync(progressFile, JSON.stringify(entry) + '\n');
+            if (proactiveDecision) {
+                this.logProactiveDecisionOutcome(proactiveDecision, {
+                    goalId,
+                    focus,
+                    source,
+                    disposition,
+                    madeProgress,
+                    resultSnippet: entry.resultSnippet,
+                    newProgressNotes: entry.newProgressNotes,
+                });
+            }
             logger.info({ goalId, madeProgress, disposition, status: entry.status }, 'Goal outcome logged');
         }
         catch (err) {
             logger.debug({ err, goalId }, 'Failed to log goal outcome (non-fatal)');
         }
     }
+    logProactiveDecisionOutcome(decision, details) {
+        try {
+            const existing = recentDecisions({ idempotencyKey: decision.idempotencyKey }, undefined)[0];
+            const decisionId = existing?.id ?? decision.idempotencyKey;
+            recordDecisionOutcome(decisionId, decision, {
+                signalType: 'goal-work-outcome',
+                description: details.focus,
+                goalId: details.goalId,
+                metadata: {
+                    source: details.source,
+                    disposition: details.disposition,
+                    madeProgress: details.madeProgress,
+                    newProgressNotes: details.newProgressNotes,
+                },
+            }, {
+                status: outcomeStatusFromGoalDisposition(details.disposition),
+                summary: details.resultSnippet || details.disposition,
+            });
+        }
+        catch (err) {
+            logger.debug({ err, goalId: details.goalId }, 'Failed to log proactive decision outcome (non-fatal)');
+        }
+    }
     /**
      * Apply non-destructive cron changes suggested by the daily planner.
      * Only auto-applies suggestions that reference a high-priority goal with autoSchedule=true.

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

@@ -93,10 +93,12 @@ export declare class HeartbeatScheduler {
     private claimNextItem;
     private completeItem;
     private failItem;
+    private recordWorkItemOutcome;
     static enqueueWork(opts: {
         description: string;
         prompt: string;
         source: string;
+        idempotencyKey?: string;
         priority?: 'high' | 'normal';
         maxTurns?: number;
         tier?: number;