clementine-agent 1.0.83 → 1.0.85

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/cli/dashboard.js

@@ -1084,6 +1084,7 @@ function getAgentHeartbeats() {
                 silentTickCount: Number(state.silentTickCount ?? 0),
                 fingerprint: state.fingerprint ?? '',
                 lastSignalSummary: state.lastSignalSummary ?? null,
+                lastTickKind: state.lastTickKind ?? null,
                 lastTickAgoMs: lastTickMs ? now - lastTickMs : null,
                 nextCheckInMs: nextCheckMs ? nextCheckMs - now : null,
                 isDue: nextCheckMs > 0 && nextCheckMs <= now,
@@ -8977,6 +8978,26 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
   .desk-kpi-strip .dss-icon { font-size: 12px; opacity: 0.7; }
   .desk-kpi-strip .dss-val { font-weight: 700; color: var(--accent); }
 
+  /* ── Heartbeat Strip ────────────── */
+  .desk-hb-strip {
+    display: flex;
+    justify-content: center;
+    gap: 6px;
+    padding: 2px 12px;
+    font-size: 10px;
+    color: var(--text-muted);
+    min-height: 0;
+  }
+  .desk-hb-strip:empty { display: none; }
+  .desk-hb-strip .dss-item {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    white-space: nowrap;
+  }
+  .desk-hb-strip .dss-icon { font-size: 11px; opacity: 0.85; }
+  .desk-hb-strip .dss-val { font-weight: 600; color: var(--text-secondary); }
+
   /* ── Health Badge ──────────────────── */
   .desk-health-badge {
     display: none;
@@ -17272,6 +17293,9 @@ async function refreshTeam() {
             '</details>';
           }
 
+          // Heartbeat strip — last/next tick, populated async from /api/agent-heartbeats
+          var hbStrip = '<div class="desk-hb-strip" id="hb-' + a.slug + '"></div>';
+
           // SDR KPI strip (fetched async, populated by data attribute)
           var kpiStrip = '<div class="desk-kpi-strip" id="kpi-' + a.slug + '"></div>';
 
@@ -17299,6 +17323,7 @@ async function refreshTeam() {
               (actions ? '<div class="desk-actions">' + actions + '</div>' : '') +
             '</div>' +
             statsStrip +
+            hbStrip +
             kpiStrip +
             cronDetails +
           '</div>';
@@ -17312,6 +17337,54 @@ async function refreshTeam() {
 
         grid.innerHTML = cards.join('');
 
+        // Heartbeat strip — single batch fetch, populate per-agent (avoids N requests).
+        apiFetch('/api/agent-heartbeats').then(function(r) { return r.json(); }).then(function(hbList) {
+          if (!Array.isArray(hbList)) return;
+          var byAgent = {};
+          for (var i = 0; i < hbList.length; i++) byAgent[hbList[i].slug] = hbList[i];
+          agents.forEach(function(a) {
+            var hb = byAgent[a.slug];
+            var el = document.getElementById('hb-' + a.slug);
+            if (!el || !hb) return;
+            // "in 12 min" / "due now" / "10s ago tick"
+            var nextLabel;
+            if (hb.isDue) {
+              nextLabel = 'due now';
+            } else if (typeof hb.nextCheckInMs === 'number') {
+              var mins = Math.max(1, Math.round(hb.nextCheckInMs / 60000));
+              nextLabel = mins < 60 ? 'in ' + mins + 'm' : 'in ' + Math.floor(mins / 60) + 'h';
+            } else {
+              nextLabel = '—';
+            }
+            var lastLabel = hb.lastTickAt ? fmtTimeAgo(hb.lastTickAt) : 'never';
+            // Tick-kind icon — small visual signal
+            var kindIcon = '';
+            var kindTitle = '';
+            switch (hb.lastSignalSummary && hb.lastSignalSummary.indexOf('llm tick error') === 0
+              ? 'error' : '') {
+              case 'error':
+                kindIcon = '⚠'; kindTitle = 'Last tick errored — fell back to quiet cadence';
+                break;
+            }
+            // Use a literal field if available — backend exposes lastTickKind via state file
+            // (we read it through getAgentHeartbeats which preserves the field)
+            if (!kindIcon) {
+              switch (hb.lastTickKind) {
+                case 'acted':    kindIcon = '⚡'; kindTitle = 'Active — agent took action last tick'; break;
+                case 'quiet':    kindIcon = '◌'; kindTitle = 'Quiet — agent saw signals but had nothing to do'; break;
+                case 'silent':   kindIcon = '·'; kindTitle = 'Silent — fingerprint unchanged, backing off'; break;
+                case 'override': kindIcon = '◇'; kindTitle = 'Override — cadence set explicitly by the agent'; break;
+                default:         kindIcon = '·'; kindTitle = 'No tick recorded yet';
+              }
+            }
+            el.innerHTML =
+              '<span class="dss-item" title="' + kindTitle + '">' +
+                '<span class="dss-icon">' + kindIcon + '</span> ' +
+                '<span class="dss-val">' + lastLabel + '</span> · next ' + nextLabel +
+              '</span>';
+          });
+        }).catch(function() { /* heartbeat endpoint missing or daemon old — silently skip */ });
+
         // Async-fetch KPIs and health for each agent
         agents.forEach(function(a) {
           // KPI strip

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

@@ -10,7 +10,7 @@
  * out. Per-agent failures are caught so one buggy agent can't crash the
  * daemon or stall others.
  */
-import { existsSync, mkdirSync, watch } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, watch } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
 import { AGENTS_DIR, BASE_DIR } from '../config.js';
@@ -107,22 +107,15 @@ export class AgentHeartbeatManager {
                 if (!filename.endsWith('.json'))
                     return;
                 const slug = filename.replace(/\.json$/, '');
-                // Consume the sentinel + wake the agent
-                try {
-                    // Use unlinkSync via require to keep top-level import surface tight
-                    // (already imported existsSync — we use it before unlink to be safe)
-                    const sentinelPath = path.join(wakeDir, filename);
-                    if (existsSync(sentinelPath)) {
-                        // best-effort: import unlinkSync inline
-                        // eslint-disable-next-line @typescript-eslint/no-var-requires
-                        const fs = require('node:fs');
-                        try {
-                            fs.unlinkSync(sentinelPath);
-                        }
-                        catch { /* ignore */ }
+                // Consume the sentinel + wake the agent. Best-effort delete so the
+                // same sentinel can't fire repeatedly.
+                const sentinelPath = path.join(wakeDir, filename);
+                if (existsSync(sentinelPath)) {
+                    try {
+                        unlinkSync(sentinelPath);
                     }
+                    catch { /* ignore */ }
                 }
-                catch { /* non-fatal */ }
                 this.scheduleWake(slug, 'wake-sentinel');
             });
         }
@@ -197,9 +190,7 @@ export class AgentHeartbeatManager {
             const triggerPath = path.join(BASE_DIR, 'cron', 'goal-triggers', filename);
             if (!existsSync(triggerPath))
                 return; // file was already consumed by cron-scheduler
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            const fs = require('node:fs');
-            const trigger = JSON.parse(fs.readFileSync(triggerPath, 'utf-8'));
+            const trigger = JSON.parse(readFileSync(triggerPath, 'utf-8'));
             if (!trigger.goalId)
                 return;
             const lookup = listAllGoals().find((g) => g.goal && g.goal.id === trigger.goalId);

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.85",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",