clementine-agent 1.0.83 → 1.0.84

package/dist/agent/agent-manager.js

@@ -165,6 +165,20 @@ export class AgentManager {
                 catch { /* migration failed — continue with plaintext */ }
             }
         }
+        // Parse active_hours from frontmatter ("HH:MM-HH:MM" → decimal hours).
+        // Same-day windows only; midnight-crossing strings are ignored.
+        let activeHours;
+        const ahRaw = meta.active_hours ?? meta.activeHours;
+        if (typeof ahRaw === 'string') {
+            const m = ahRaw.match(/^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/);
+            if (m) {
+                const start = Number(m[1]) + Number(m[2]) / 60;
+                const end = Number(m[3]) + Number(m[4]) / 60;
+                if (start < end && start >= 0 && end <= 24) {
+                    activeHours = { start, end };
+                }
+            }
+        }
         // Parse sendPolicy from frontmatter
         let sendPolicy;
         if (meta.sendPolicy && typeof meta.sendPolicy === 'object') {
@@ -205,6 +219,7 @@ export class AgentManager {
             status: (['active', 'paused', 'error', 'terminated'].includes(meta.status) ? meta.status : 'active'),
             budgetMonthlyCents: meta.budgetMonthlyCents ? Number(meta.budgetMonthlyCents) : undefined,
             strictMemoryIsolation: meta.strictMemoryIsolation === false ? false : true, // default true for all agents
+            activeHours,
         };
     }
     // ── ProfileManager-compatible interface ───────────────────────────

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

@@ -12,6 +12,16 @@
  */
 import type { AgentHeartbeatState } from '../types.js';
 import type { AgentManager } from '../agent/agent-manager.js';
+/**
+ * Compute the next-check interval (minutes) for an upcoming tick. Pure
+ * function of the inputs — exported for tests.
+ */
+export declare function computeNextInterval(opts: {
+    kind: 'acted' | 'quiet' | 'silent' | 'override';
+    silentStreak: number;
+    isActiveHours: boolean;
+    overrideMin?: number;
+}): number;
 /**
  * Minimal gateway surface the scheduler needs for the LLM tick path.
  * Kept narrow so tests can mock it without pulling in the full Gateway.

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

@@ -20,6 +20,50 @@ const logger = pino({ name: 'clementine.agent-heartbeat' });
 const DEFAULT_INTERVAL_MIN = 30;
 const MIN_INTERVAL_MIN = 5;
 const MAX_INTERVAL_MIN = 12 * 60;
+// ── Adaptive cadence ─────────────────────────────────────────────────
+// Tick-outcome → next-check interval (minutes). Plain numbers tuned for
+// the typical "specialist running on a goal" workload — fast when active,
+// gradually slower when idle.
+const ACTED_INTERVAL_MIN = 10;
+const QUIET_INTERVAL_MIN = 60;
+// Exponential backoff schedule for consecutive silent ticks. Index = streak
+// length (capped at last entry). 0 silent → unused; 1st → 30, 2nd → 60, ...
+const SILENT_BACKOFF_MIN = [30, 60, 120, 240, 480, 720];
+// Off-hours multiplier. Applied after kind-based interval, capped at MAX.
+const OFF_HOURS_MULTIPLIER = 4;
+// Default active hours when an agent's profile doesn't specify
+const DEFAULT_ACTIVE_START_HOUR = 8;
+const DEFAULT_ACTIVE_END_HOUR = 22;
+/**
+ * Compute the next-check interval (minutes) for an upcoming tick. Pure
+ * function of the inputs — exported for tests.
+ */
+export function computeNextInterval(opts) {
+    if (opts.kind === 'override' && typeof opts.overrideMin === 'number') {
+        // User-set override always wins, still clamped to bounds.
+        return Math.max(MIN_INTERVAL_MIN, Math.min(MAX_INTERVAL_MIN, Math.floor(opts.overrideMin)));
+    }
+    let base;
+    if (opts.kind === 'acted') {
+        base = ACTED_INTERVAL_MIN;
+    }
+    else if (opts.kind === 'quiet') {
+        base = QUIET_INTERVAL_MIN;
+    }
+    else {
+        // silent
+        const idx = Math.min(Math.max(0, opts.silentStreak - 1), SILENT_BACKOFF_MIN.length - 1);
+        base = SILENT_BACKOFF_MIN[idx];
+    }
+    if (!opts.isActiveHours)
+        base *= OFF_HOURS_MULTIPLIER;
+    return Math.max(MIN_INTERVAL_MIN, Math.min(MAX_INTERVAL_MIN, base));
+}
+function isWithinActiveHours(now, profile) {
+    const hours = profile.activeHours ?? { start: DEFAULT_ACTIVE_START_HOUR, end: DEFAULT_ACTIVE_END_HOUR };
+    const localHour = now.getHours() + now.getMinutes() / 60;
+    return localHour >= hours.start && localHour < hours.end;
+}
 export class AgentHeartbeatScheduler {
     slug;
     agentManager;
@@ -40,6 +84,10 @@ export class AgentHeartbeatScheduler {
         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 ?? ''),
@@ -47,6 +95,7 @@ export class AgentHeartbeatScheduler {
                     silentTickCount: Number(raw.silentTickCount ?? 0),
                     fingerprint: String(raw.fingerprint ?? ''),
                     ...(raw.lastSignalSummary ? { lastSignalSummary: raw.lastSignalSummary } : {}),
+                    ...(kind ? { lastTickKind: kind } : {}),
                 };
             }
         }
@@ -190,18 +239,33 @@ export class AgentHeartbeatScheduler {
         const prior = this.loadState();
         const { fingerprint, signals } = this.buildFingerprint();
         const changed = fingerprint !== prior.fingerprint;
-        let nextCheckMinutes = DEFAULT_INTERVAL_MIN;
         let lastSignalSummary;
+        let llmResult = {
+            nextCheckMinutes: undefined,
+            summary: '',
+            ranLlm: false,
+            tookAction: false,
+        };
         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);
+                // Heuristic: a meaningful response means the agent took action. Short
+                // "all quiet" / "[ALL_QUIET]" responses don't count.
+                const summary = result.summary ?? '';
+                const tookAction = summary.length > 200 && !/\[ALL_QUIET\]/i.test(summary);
+                llmResult = {
+                    nextCheckMinutes: result.nextCheckMinutes,
+                    summary,
+                    ranLlm: true,
+                    tookAction,
+                };
+                lastSignalSummary = 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)}`;
+                llmResult.ranLlm = true; // we attempted, treat as 'quiet' for backoff
             }
         }
         else if (changed) {
@@ -210,22 +274,40 @@ export class AgentHeartbeatScheduler {
         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);
+        // Classify outcome → drives adaptive cadence.
+        const newSilentStreak = changed ? 0 : prior.silentTickCount + 1;
+        const tickKind = (() => {
+            if (typeof llmResult.nextCheckMinutes === 'number')
+                return 'override';
+            if (!changed)
+                return 'silent';
+            if (llmResult.ranLlm && llmResult.tookAction)
+                return 'acted';
+            return 'quiet';
+        })();
+        const isActive = isWithinActiveHours(now, profile);
+        const computedMin = computeNextInterval({
+            kind: tickKind,
+            silentStreak: newSilentStreak,
+            isActiveHours: isActive,
+            overrideMin: llmResult.nextCheckMinutes,
+        });
+        const next = new Date(now.getTime() + computedMin * 60_000);
         const state = {
             slug: this.slug,
             lastTickAt: now.toISOString(),
             nextCheckAt: next.toISOString(),
-            silentTickCount: changed ? 0 : prior.silentTickCount + 1,
+            silentTickCount: newSilentStreak,
             fingerprint,
+            lastTickKind: tickKind,
             ...(lastSignalSummary ? { lastSignalSummary } : {}),
         };
         this.saveState(state);
         if (changed) {
-            logger.info({ slug: this.slug, signals, fingerprint, ranLlm: shouldRunLlm, nextCheckMin: clampedMin }, 'Agent heartbeat tick');
+            logger.info({ slug: this.slug, signals, fingerprint, ranLlm: shouldRunLlm, kind: tickKind, nextCheckMin: computedMin, isActive }, 'Agent heartbeat tick');
         }
         else {
-            logger.debug({ slug: this.slug, silentTicks: state.silentTickCount }, 'Agent heartbeat: silent tick');
+            logger.debug({ slug: this.slug, silentTicks: state.silentTickCount, nextCheckMin: computedMin, isActive }, 'Agent heartbeat: silent tick');
         }
         return state;
     }

package/dist/types.d.ts

@@ -183,6 +183,17 @@ export interface AgentProfile {
     budgetMonthlyCents?: number;
     spentMonthlyCents?: number;
     strictMemoryIsolation?: boolean;
+    /**
+     * Active-hours window for adaptive heartbeat cadence. Decimal hours in
+     * the local timezone, e.g., { start: 8, end: 18 } = 8:00am–6:00pm.
+     * When the current time is outside this window, the agent's next-check
+     * interval is multiplied by 4. Parsed from `active_hours: "HH:MM-HH:MM"`
+     * in agent.md frontmatter; same-day windows only.
+     */
+    activeHours?: {
+        start: number;
+        end: number;
+    };
 }
 export type AgentStatus = 'active' | 'paused' | 'error' | 'terminated';
 export interface HeartbeatReportedTopic {
@@ -240,6 +251,15 @@ export interface AgentHeartbeatState {
     silentTickCount: number;
     fingerprint: string;
     lastSignalSummary?: string;
+    /**
+     * Outcome of the last tick. Drives adaptive cadence:
+     *   - 'acted' → next check at active-mode interval (10 min default)
+     *   - 'quiet' → next check at quiet interval (60 min)
+     *   - 'silent' → exponential backoff (30 → 60 → 120 → 240 → 480, capped)
+     *   - 'override' → agent explicitly set [NEXT_CHECK: Xm], honored as-is
+     *   - undefined → first tick or pre-1.0.84 state
+     */
+    lastTickKind?: 'acted' | 'quiet' | 'silent' | 'override';
 }
 export interface CronJobDefinition {
     name: string;

package/package.json

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