clementine-agent 1.0.78 → 1.0.79

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

@@ -11,14 +11,15 @@
  * daemon or stall others.
  */
 import type { AgentManager } from '../agent/agent-manager.js';
-import { AgentHeartbeatScheduler } from './agent-heartbeat-scheduler.js';
+import { AgentHeartbeatScheduler, type AgentHeartbeatGateway } from './agent-heartbeat-scheduler.js';
 export declare class AgentHeartbeatManager {
     private readonly agentManager;
+    private readonly gateway;
     private readonly schedulers;
     private timer;
     private running;
     private ticking;
-    constructor(agentManager: AgentManager);
+    constructor(agentManager: AgentManager, gateway?: AgentHeartbeatGateway);
     start(): void;
     stop(): void;
     /** Add/remove schedulers to match the current AgentManager listing. */

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

@@ -16,12 +16,14 @@ const logger = pino({ name: 'clementine.agent-heartbeat-manager' });
 const OUTER_TICK_MS = 60_000;
 export class AgentHeartbeatManager {
     agentManager;
+    gateway;
     schedulers = new Map();
     timer = null;
     running = false;
     ticking = false;
-    constructor(agentManager) {
+    constructor(agentManager, gateway) {
         this.agentManager = agentManager;
+        this.gateway = gateway ?? null;
     }
     start() {
         if (this.running)
@@ -63,7 +65,7 @@ export class AgentHeartbeatManager {
         // Add new
         for (const slug of active) {
             if (!this.schedulers.has(slug)) {
-                this.schedulers.set(slug, new AgentHeartbeatScheduler(slug, this.agentManager));
+                this.schedulers.set(slug, new AgentHeartbeatScheduler(slug, this.agentManager, this.gateway ? { gateway: this.gateway } : {}));
                 logger.info({ slug }, 'Agent heartbeat: registered scheduler');
             }
         }

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

@@ -12,11 +12,24 @@
  */
 import type { AgentHeartbeatState } from '../types.js';
 import type { AgentManager } from '../agent/agent-manager.js';
+/**
+ * Minimal gateway surface the scheduler needs for the LLM tick path.
+ * Kept narrow so tests can mock it without pulling in the full Gateway.
+ */
+export interface AgentHeartbeatGateway {
+    handleCronJob(jobName: string, jobPrompt: string, tier?: number, maxTurns?: number, model?: string, workDir?: string, mode?: 'standard' | 'unleashed', maxHours?: number, timeoutMs?: number, successCriteria?: string[], agentSlug?: string): Promise<string>;
+}
 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;
+    /**
+     * Gateway used for the LLM tick path. When omitted, the scheduler runs in
+     * cheap-path-only mode (observation + logging, no LLM call). Tests pass
+     * mocks here; production passes the real Gateway.
+     */
+    gateway?: AgentHeartbeatGateway;
 }
 export declare class AgentHeartbeatScheduler {
     private readonly slug;
@@ -24,6 +37,7 @@ export declare class AgentHeartbeatScheduler {
     private readonly baseDir;
     private readonly agentsDir;
     private readonly stateFile;
+    private readonly gateway;
     constructor(slug: string, agentManager: AgentManager, opts?: AgentHeartbeatOptions);
     /** Read persisted state, or return a fresh state ready to tick now. */
     loadState(): AgentHeartbeatState;
@@ -37,10 +51,26 @@ export declare class AgentHeartbeatScheduler {
      */
     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. Loads state, builds fingerprint, decides whether to invoke the
+     * LLM path, persists the new state. The LLM call is only made when:
+     *
+     *   1. The fingerprint changed (something material moved since last tick), AND
+     *   2. The prior fingerprint was non-empty (we don't fire LLM on the very
+     *      first tick after daemon start — those are noisy and not signal), AND
+     *   3. A gateway is wired (opts.gateway). Tests run cheap-path-only.
      */
     tick(now?: Date): Promise<AgentHeartbeatState>;
+    /**
+     * Build and dispatch the LLM tick prompt via gateway.handleCronJob.
+     * Output already routes to the agent's Discord channel (dispatcher.send
+     * is called inside the cron path with the agentSlug).
+     */
+    private runLlmTick;
+    /** Parse `[NEXT_CHECK: Xm]` directive from the agent's output. Public for tests. */
+    static parseLlmTickOutput(output: string): {
+        nextCheckMinutes: number | undefined;
+        summary: string;
+    };
     /** Schedule the next check explicitly. Clamped to [MIN, MAX] minutes. */
     setNextCheckIn(minutes: number, now?: Date): void;
     getSlug(): string;

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

@@ -26,12 +26,14 @@ export class AgentHeartbeatScheduler {
     baseDir;
     agentsDir;
     stateFile;
+    gateway;
     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');
+        this.gateway = opts.gateway ?? null;
     }
     /** Read persisted state, or return a fresh state ready to tick now. */
     loadState() {
@@ -151,8 +153,13 @@ export class AgentHeartbeatScheduler {
         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.
+     * Tick. Loads state, builds fingerprint, decides whether to invoke the
+     * LLM path, persists the new state. The LLM call is only made when:
+     *
+     *   1. The fingerprint changed (something material moved since last tick), AND
+     *   2. The prior fingerprint was non-empty (we don't fire LLM on the very
+     *      first tick after daemon start — those are noisy and not signal), AND
+     *   3. A gateway is wired (opts.gateway). Tests run cheap-path-only.
      */
     async tick(now = new Date()) {
         const profile = this.agentManager.get(this.slug);
@@ -183,28 +190,91 @@ export class AgentHeartbeatScheduler {
         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);
+        let nextCheckMinutes = DEFAULT_INTERVAL_MIN;
+        let lastSignalSummary;
+        const shouldRunLlm = changed && prior.fingerprint !== '' && this.gateway !== null;
+        if (shouldRunLlm) {
+            try {
+                const result = await this.runLlmTick(profile, signals, prior, now);
+                nextCheckMinutes = result.nextCheckMinutes ?? DEFAULT_INTERVAL_MIN;
+                lastSignalSummary = result.summary?.slice(0, 240);
+            }
+            catch (err) {
+                logger.warn({ err, slug: this.slug }, 'Agent LLM tick failed — using default cadence');
+                lastSignalSummary = `llm tick error: ${String(err).slice(0, 200)}`;
+            }
+        }
+        else if (changed) {
+            lastSignalSummary = `signal change: ${JSON.stringify(signals)}`.slice(0, 240);
+        }
+        else {
+            lastSignalSummary = prior.lastSignalSummary;
+        }
+        const clampedMin = Math.max(MIN_INTERVAL_MIN, Math.min(MAX_INTERVAL_MIN, Math.floor(nextCheckMinutes)));
+        const next = new Date(now.getTime() + clampedMin * 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 }
-                    : {}),
+            ...(lastSignalSummary ? { lastSignalSummary } : {}),
         };
         this.saveState(state);
         if (changed) {
-            logger.info({ slug: this.slug, signals, fingerprint }, 'Agent heartbeat: signal change detected (LLM path is P3)');
+            logger.info({ slug: this.slug, signals, fingerprint, ranLlm: shouldRunLlm, nextCheckMin: clampedMin }, 'Agent heartbeat tick');
         }
         else {
             logger.debug({ slug: this.slug, silentTicks: state.silentTickCount }, 'Agent heartbeat: silent tick');
         }
         return state;
     }
+    /**
+     * Build and dispatch the LLM tick prompt via gateway.handleCronJob.
+     * Output already routes to the agent's Discord channel (dispatcher.send
+     * is called inside the cron path with the agentSlug).
+     */
+    async runLlmTick(profile, signals, prior, now) {
+        if (!this.gateway) {
+            return { nextCheckMinutes: undefined, summary: '' };
+        }
+        const sinceLastMin = prior.lastTickAt
+            ? Math.max(0, Math.round((now.getTime() - new Date(prior.lastTickAt).getTime()) / 60_000))
+            : 0;
+        const prompt = [
+            `[Heartbeat check-in: ${profile.slug}]`,
+            '',
+            `You are ${profile.name}. ${profile.description}`,
+            '',
+            `## Routine check-in`,
+            `This is your scheduled heartbeat tick (${sinceLastMin}min since last).`,
+            `Something in your scope has changed since you last checked in.`,
+            '',
+            `### Signals`,
+            `- Pending delegated tasks: ${signals.pendingTasks ?? 0}`,
+            `- Latest goal update: ${signals.latestGoalUpdate || 'none'}`,
+            `- Latest cron run: ${signals.latestCronRunMs ? new Date(Number(signals.latestCronRunMs)).toISOString() : 'none'}`,
+            '',
+            `### Instructions`,
+            `1. Quickly scan TASKS.md, your goals, and recent cron output for anything that needs action right now.`,
+            `2. If there's a clear next action you can take in 1–2 turns, do it.`,
+            `3. If you're blocked, waiting on someone, or it's all-quiet, say so concisely.`,
+            `4. End your response with \`[NEXT_CHECK: Xm]\` to set when to check in next (5–720 min). Default 30m. Use shorter intervals during active work, longer during quiet hours.`,
+            `5. Keep your response under 3 sentences unless you actually took action.`,
+        ].join('\n');
+        const jobName = `heartbeat:${this.slug}`;
+        const result = await this.gateway.handleCronJob(jobName, prompt, 1, 5, undefined, undefined, 'standard', undefined, undefined, undefined, this.slug);
+        const parsed = AgentHeartbeatScheduler.parseLlmTickOutput(result);
+        return { nextCheckMinutes: parsed.nextCheckMinutes, summary: parsed.summary };
+    }
+    /** Parse `[NEXT_CHECK: Xm]` directive from the agent's output. Public for tests. */
+    static parseLlmTickOutput(output) {
+        const match = output.match(/\[NEXT_CHECK:\s*(\d+)\s*m?\]/i);
+        const nextCheckMinutes = match ? parseInt(match[1], 10) : undefined;
+        // Strip the directive from the summary so logs don't echo it back
+        const summary = output.replace(/\[NEXT_CHECK:[^\]]*\]/gi, '').trim();
+        return { nextCheckMinutes, summary };
+    }
     /** 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)));

package/dist/index.js

@@ -661,9 +661,10 @@ async function asyncMain() {
     const cronScheduler = new CronScheduler(gateway, dispatcher);
     heartbeat.setCronScheduler(cronScheduler);
     // Per-agent heartbeats (Ross / Sasha / Nora / future hires). Cheap-path
-    // observation only in P2 — LLM ticks land in P3.
+    // observation on every tick; LLM tick fires on signal change with the
+    // agent's profile and routes output to their Discord channel.
     const { AgentHeartbeatManager } = await import('./gateway/agent-heartbeat-manager.js');
-    const agentHeartbeats = new AgentHeartbeatManager(gateway.getAgentManager());
+    const agentHeartbeats = new AgentHeartbeatManager(gateway.getAgentManager(), gateway);
     // ── Build channel tasks ──────────────────────────────────────────
     const channelTasks = [];
     const activeChannels = [];

package/package.json

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