clementine-agent 1.0.82 → 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/channels/discord.js

@@ -1122,7 +1122,7 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
             const streamer = new DiscordStreamingMessage(message.channel);
             await streamer.start();
             try {
-                const response = await gateway.handleMessage(sessionKey, effectiveText, (t) => streamer.update(t), oneOffModel, oneOffMaxTurns, (toolName, toolInput) => { streamer.setToolStatus(friendlyToolName(toolName, toolInput)); return Promise.resolve(); });
+                const response = await gateway.handleMessage(sessionKey, effectiveText, (t) => streamer.update(t), oneOffModel, oneOffMaxTurns, (toolName, toolInput) => { streamer.setToolStatus(friendlyToolName(toolName, toolInput)); return Promise.resolve(); }, (status) => { streamer.setToolStatus(status); return Promise.resolve(); });
                 await streamer.finalize(response);
                 updatePresence(sessionKey);
                 // Track bot message for feedback reactions

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/gateway/router.d.ts

@@ -5,7 +5,7 @@
  * Manages per-user/channel sessions for conversation continuity.
  */
 import { PersonalAssistant, type ProjectMeta } from '../agent/assistant.js';
-import type { OnTextCallback, OnToolActivityCallback, PlanProgressUpdate, PlanStep, SelfImproveConfig, SelfImproveExperiment, SessionProvenance, TeamMessage, VerboseLevel, WorkflowDefinition } from '../types.js';
+import type { OnProgressCallback, OnTextCallback, OnToolActivityCallback, PlanProgressUpdate, PlanStep, SelfImproveConfig, SelfImproveExperiment, SessionProvenance, TeamMessage, VerboseLevel, WorkflowDefinition } from '../types.js';
 import { AgentManager } from '../agent/agent-manager.js';
 import { TeamRouter } from '../agent/team-router.js';
 import { TeamBus } from '../agent/team-bus.js';
@@ -149,7 +149,7 @@ export declare class Gateway {
      * or correct the agent mid-response instead of queuing behind a long query.
      */
     private acquireSessionLock;
-    handleMessage(sessionKey: string, text: string, onText?: OnTextCallback, model?: string, maxTurns?: number, onToolActivity?: OnToolActivityCallback): Promise<string>;
+    handleMessage(sessionKey: string, text: string, onText?: OnTextCallback, model?: string, maxTurns?: number, onToolActivity?: OnToolActivityCallback, onProgress?: OnProgressCallback): Promise<string>;
     private _handleMessageInner;
     handleHeartbeat(standingInstructions: string, changesSummary?: string, timeContext?: string, dedupContext?: string, profile?: import('../types.js').AgentProfile | null): Promise<string>;
     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>;

package/dist/gateway/router.js

@@ -691,7 +691,7 @@ export class Gateway {
         };
     }
     // ── Message handling ────────────────────────────────────────────────
-    async handleMessage(sessionKey, text, onText, model, maxTurns, onToolActivity) {
+    async handleMessage(sessionKey, text, onText, model, maxTurns, onToolActivity, onProgress) {
         if (this.draining) {
             return "I'm restarting momentarily — your message will be processed after I'm back online.";
         }
@@ -713,7 +713,7 @@ export class Gateway {
                 text_len: text.length,
             });
             try {
-                const result = await this._handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity);
+                const result = await this._handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity, onProgress);
                 logAuditJsonl({
                     event_type: 'message_completed',
                     duration_ms: Date.now() - traceStart,
@@ -731,7 +731,7 @@ export class Gateway {
             }
         });
     }
-    async _handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity) {
+    async _handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity, onProgress) {
         // ── Auth circuit breaker — stop spamming error messages ────────
         if (this.authCircuitOpen) {
             if (!this.shouldProbeAuth()) {
@@ -743,10 +743,31 @@ export class Gateway {
             // Allow this one message through as a probe to see if auth recovered
             logger.info({ sessionKey }, 'Auth circuit open — allowing probe message');
         }
+        // Show "queued" status if either lane or session lock is contended,
+        // so the user doesn't stare at "thinking..." for up to 60s while a
+        // previous message is still processing.
+        const laneWaitStart = Date.now();
+        let queuedStatusShown = false;
+        const queuedTimer = onProgress
+            ? setTimeout(() => {
+                queuedStatusShown = true;
+                onProgress('waiting for previous message to finish...').catch(() => { });
+            }, 750)
+            : null;
         const releaseLane = await lanes.acquire('chat');
+        if (queuedTimer)
+            clearTimeout(queuedTimer);
         try {
             const release = await this.acquireSessionLock(sessionKey);
             try {
+                if (queuedStatusShown && onProgress) {
+                    // Lane was busy — clear the wait notice now that we're moving
+                    await onProgress('thinking...').catch(() => { });
+                }
+                const laneWaitMs = Date.now() - laneWaitStart;
+                if (laneWaitMs > 1000) {
+                    logger.info({ sessionKey, laneWaitMs }, 'Chat lane wait was non-trivial');
+                }
                 logger.info(`Message from ${sessionKey}: ${text.slice(0, 100)}...`);
                 events.emit('message:received', { sessionKey, text, timestamp: Date.now() });
                 // ── Register provenance on first interaction ────────────────
@@ -849,6 +870,9 @@ export class Gateway {
                     || text.startsWith('[Approval:')
                     || text.startsWith('[Reaction:')
                     || text.startsWith('[System:');
+                if (!isInternalMsg && !sess?.profile && !text.startsWith('!') && !isStructuredWorkflowMsg && onProgress) {
+                    await onProgress('checking if a teammate should handle this...').catch(() => { });
+                }
                 const routingResult = !isInternalMsg && !sess?.profile && !text.startsWith('!') && !isStructuredWorkflowMsg
                     ? await this._maybeRouteToSpecialist(sessionKey, text, onText)
                     : null;
@@ -1058,6 +1082,9 @@ export class Gateway {
                     // Primary guardrail is cost budget (maxBudgetUsd in buildOptions).
                     // Wall clock (CHAT_MAX_WALL_MS) and StallGuard are safety nets.
                     events.emit('query:start', { sessionKey, model: effectiveModel, maxTurns: maxTurns, timestamp: Date.now() });
+                    if (onProgress) {
+                        await onProgress('thinking...').catch(() => { });
+                    }
                     const queryStartMs = Date.now();
                     const [response] = await Promise.race([
                         this.assistant.chat(chatPrompt, effectiveSessionKey, { onText: wrappedOnText, onToolActivity: wrappedOnToolActivity, model: effectiveModel, maxTurns: maxTurns, securityAnnotation, projectOverride, profile: resolvedProfile, verboseLevel, abortController: chatAc }),

package/dist/types.d.ts

@@ -103,6 +103,13 @@ export interface ChannelCapabilities {
 export declare const DEFAULT_CHANNEL_CAPABILITIES: ChannelCapabilities;
 export type OnTextCallback = (text: string) => Promise<void>;
 export type OnToolActivityCallback = (toolName: string, toolInput: Record<string, unknown>) => Promise<void>;
+/**
+ * Pre-query progress callback. Fired at stage transitions BEFORE the SDK
+ * query starts (routing, complexity classification, lock waits, etc.) so
+ * the user sees the indicator change instead of staring at "thinking..."
+ * for several seconds.
+ */
+export type OnProgressCallback = (status: string) => Promise<void>;
 export interface NotificationContext {
     agentSlug?: string;
     /** When set, the dispatcher routes the message back to the channel that owns this session. */
@@ -176,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 {
@@ -233,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.82",
+  "version": "1.0.84",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",