clementine-agent 1.0.30 → 1.0.32

package/dist/agent/complexity-classifier.d.ts

@@ -13,6 +13,13 @@
  */
 export interface ComplexityVerdict {
     complex: boolean;
+    /**
+     * High-confidence subset of `complex`. When true, the task is ambitious
+     * enough that the gateway should route it straight to deep/background
+     * execution instead of running a main-agent turn that would almost
+     * certainly get auto-escalated after burning tool calls.
+     */
+    deepWorthy: boolean;
     reason: string;
     signals: string[];
 }

package/dist/agent/complexity-classifier.js

@@ -11,6 +11,19 @@
  * what "plan" means — but much more consistent than a generic
  * SOUL.md directive that the model ignores half the time.
  */
+/**
+ * Explicit phrasings that essentially request a long-running background job.
+ * Triggers deepWorthy on their own, regardless of other signals.
+ */
+const DEEP_MODE_ASKS = [
+    /\b(deeply|extensively|thoroughly)\s+(research|analy[sz]e|investigate|audit|review)\b/i,
+    /\bcomprehensive(ly)?\s+(research|analy[sz]is|report|audit)\b/i,
+    /\bgo\s+(do|handle|tackle)\s+this\b/i,
+    /\brun\s+in\s+the\s+background\b/i,
+    /\bdeep\s+(mode|dive|work)\b/i,
+    /\bbackground\s+(task|work|job)\b/i,
+    /\btake\s+your\s+time\b/i,
+];
 /**
  * Action verbs that signal the user is asking Clementine to DO things
  * (as opposed to asking questions or making small talk). Multiple
@@ -82,18 +95,24 @@ function countEntities(text) {
  */
 export function classifyComplexity(text) {
     if (!text || typeof text !== 'string')
-        return { complex: false, reason: 'empty', signals: [] };
+        return { complex: false, deepWorthy: false, reason: 'empty', signals: [] };
     const trimmed = text.trim();
     // Skip commands and very short messages
     if (trimmed.length < 30)
-        return { complex: false, reason: 'too short', signals: [] };
+        return { complex: false, deepWorthy: false, reason: 'too short', signals: [] };
     if (trimmed.startsWith('!') || trimmed.startsWith('/'))
-        return { complex: false, reason: 'command', signals: [] };
+        return { complex: false, deepWorthy: false, reason: 'command', signals: [] };
+    // Signal 0: explicit deep-mode ask — short-circuits both gates.
+    for (const re of DEEP_MODE_ASKS) {
+        if (re.test(trimmed)) {
+            return { complex: true, deepWorthy: true, reason: 'explicit deep-mode ask', signals: ['deep-mode-ask'] };
+        }
+    }
     const signals = [];
     // Signal 1: explicit ask for plan-first
     for (const re of EXPLICIT_PLAN_ASKS) {
         if (re.test(trimmed)) {
-            return { complex: true, reason: 'user explicitly asked for a plan', signals: ['explicit-plan-ask'] };
+            return { complex: true, deepWorthy: false, reason: 'user explicitly asked for a plan', signals: ['explicit-plan-ask'] };
         }
     }
     // Signal 2: multiple action verbs
@@ -101,9 +120,11 @@ export function classifyComplexity(text) {
     if (verbs >= 3)
         signals.push(`${verbs} action verbs`);
     // Signal 3: chain markers
+    let hasChain = false;
     for (const re of CHAIN_MARKERS) {
         if (re.test(trimmed)) {
             signals.push('chain marker');
+            hasChain = true;
             break;
         }
     }
@@ -112,21 +133,31 @@ export function classifyComplexity(text) {
     if (entities >= 3)
         signals.push(`${entities} entities`);
     // Signal 5: long message with at least one action verb (big scope, not just a question)
-    if (trimmed.length > 400 && verbs >= 1)
+    const isLong = trimmed.length > 400 && verbs >= 1;
+    if (isLong)
         signals.push('long + action');
     // Gate: at least 2 signals fire, OR a single high-confidence signal
     // (chain markers, explicit-plan-ask, or 3+ action verbs).
-    const highConfidenceSingles = [
+    const highConfidenceSingles = [verbs >= 3, hasChain];
+    const complex = highConfidenceSingles.some(Boolean) || signals.length >= 2;
+    // deepWorthy raises the bar: multiple strong signals AND sustained scope.
+    // Specifically, any TWO of {3+ verbs, chain marker, long+action, 3+ entities}.
+    const strongCount = [
         verbs >= 3,
-        signals.includes('chain marker'),
-    ];
-    if (highConfidenceSingles.some(Boolean)) {
-        return { complex: true, reason: 'strong single signal', signals };
-    }
-    if (signals.length >= 2) {
-        return { complex: true, reason: 'multiple signals', signals };
+        hasChain,
+        isLong,
+        entities >= 3,
+    ].filter(Boolean).length;
+    const deepWorthy = strongCount >= 2;
+    if (complex) {
+        return {
+            complex: true,
+            deepWorthy,
+            reason: deepWorthy ? 'deep-worthy: multiple strong signals' : (highConfidenceSingles.some(Boolean) ? 'strong single signal' : 'multiple signals'),
+            signals,
+        };
     }
-    return { complex: false, reason: 'below threshold', signals };
+    return { complex: false, deepWorthy: false, reason: 'below threshold', signals };
 }
 /**
  * Build a system-prompt directive to inject when a complex message is

package/dist/agent/skill-extractor.js

@@ -17,6 +17,7 @@ import path from 'node:path';
 import matter from 'gray-matter';
 import pino from 'pino';
 import { VAULT_DIR, AGENTS_DIR, PENDING_SKILLS_DIR } from '../config.js';
+import { embed as embedText, cosineSimilarity, isReady as embeddingsReady } from '../memory/embeddings.js';
 const logger = pino({ name: 'clementine.skills' });
 const GLOBAL_SKILLS_DIR = path.join(VAULT_DIR, '00-System', 'skills');
 function agentSkillsDir(agentSlug) {
@@ -316,6 +317,25 @@ async function mergeSkill(assistant, existing, incoming) {
         return null;
     }
 }
+/**
+ * Cache of skill embeddings so we don't re-embed every skill's frontmatter
+ * on every query. Keyed by the absolute path of the skill file; invalidated
+ * implicitly (the cache stays in memory for the daemon's lifetime — skill
+ * edits require a restart, same as the rest of the skill pipeline).
+ */
+const skillEmbeddingCache = new Map();
+function getSkillEmbedding(filePath, triggers, title, description) {
+    const cached = skillEmbeddingCache.get(filePath);
+    if (cached)
+        return cached;
+    const corpus = [title, description, triggers.join(' ')].filter(Boolean).join(' ');
+    if (!corpus)
+        return null;
+    const vec = embedText(corpus);
+    if (vec)
+        skillEmbeddingCache.set(filePath, vec);
+    return vec;
+}
 export function searchSkills(query, limit = 3, agentSlug, opts) {
     const dirs = [];
     // Agent-scoped skills get priority (boost=2)
@@ -333,6 +353,11 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
     const results = [];
     const seen = new Set();
     const suppressed = opts?.suppressedNames;
+    // Semantic matching is optional — only engages if the vault has built an
+    // embedding vocabulary (MemoryStore.buildEmbeddings). Falls back to pure
+    // keyword scoring for fresh installs.
+    const useSemantic = embeddingsReady();
+    const queryVec = useSemantic ? embedText(query) : null;
     for (const { dir, boost } of dirs) {
         const files = readdirSync(dir).filter(f => f.endsWith('.md'));
         for (const file of files) {
@@ -344,8 +369,9 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
             // negative user feedback (see store.getSkillsToSuppress).
             if (suppressed?.has(name))
                 continue;
+            const filePath = path.join(dir, file);
             try {
-                const raw = readFileSync(path.join(dir, file), 'utf-8');
+                const raw = readFileSync(filePath, 'utf-8');
                 const parsed = matter(raw);
                 const triggers = parsed.data.triggers ?? [];
                 const title = parsed.data.title ?? '';
@@ -368,12 +394,27 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
                     if (description.toLowerCase().includes(word))
                         score += 1;
                 }
-                if (score > 0) {
+                // Semantic bonus: add cosine similarity × 4 so a strong semantic
+                // match (cos ~ 0.7+) contributes like a single keyword hit, and
+                // very close matches (cos ~ 0.9+) surface as a solid lead even
+                // when the user's phrasing doesn't share vocabulary with the
+                // skill's triggers. Keyword hits still dominate when present.
+                let semanticScore = 0;
+                if (queryVec) {
+                    const skillVec = getSkillEmbedding(filePath, triggerLower, title, description);
+                    if (skillVec) {
+                        const cos = cosineSimilarity(queryVec, skillVec);
+                        if (cos > 0.3)
+                            semanticScore = cos * 4;
+                    }
+                }
+                const totalScore = score + semanticScore;
+                if (totalScore > 0) {
                     results.push({
                         name,
                         title,
                         content: parsed.content.slice(0, 1500),
-                        score: score + boost,
+                        score: totalScore + boost,
                         toolsUsed: parsed.data.toolsUsed ?? [],
                         attachments: parsed.data.attachments ?? [],
                         skillDir: dir,

package/dist/gateway/failure-monitor.d.ts

@@ -65,4 +65,22 @@ export declare function computeBrokenJobs(now?: number): BrokenJob[];
  * Returns the jobs that triggered a fresh notification (mostly for tests/logs).
  */
 export declare function runFailureSweep(send: (text: string) => Promise<unknown>, gateway?: import('./router.js').Gateway, now?: number): Promise<BrokenJob[]>;
+export interface StaleCronJob {
+    jobName: string;
+    agentSlug?: string;
+    schedule: string;
+    /** ISO timestamp of the job's most recent run, or null if it has never run. */
+    lastRunAt: string | null;
+    /** Expected time between consecutive scheduled runs, in ms. */
+    expectedIntervalMs: number;
+    /** How far past the *second* expected tick we are, in minutes. */
+    overdueMinutes: number;
+}
+/**
+ * Walk enabled cron jobs and find ones that haven't run in at least
+ * SLA_MISSED_TICKS × their expected interval. Distinct from the broken-job
+ * detector which needs actual error entries — this catches the opposite
+ * failure mode: a job that silently stopped firing at all.
+ */
+export declare function computeStaleCronJobs(now?: number): Promise<StaleCronJob[]>;
 //# sourceMappingURL=failure-monitor.d.ts.map

package/dist/gateway/failure-monitor.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 import pino from 'pino';
 import { BASE_DIR, MEMORY_DB_PATH } from '../config.js';
+import { logAuditJsonl } from '../agent/hooks.js';
 const logger = pino({ name: 'clementine.failure-monitor' });
 const RUNS_DIR = path.join(BASE_DIR, 'cron', 'runs');
 const ADVISOR_EVENTS_FILE = path.join(BASE_DIR, 'cron', 'advisor-events.jsonl');
@@ -40,12 +41,15 @@ const NOTIFY_COOLDOWN_HOURS = 24;
 function loadState() {
     try {
         if (!existsSync(STATE_FILE))
-            return { notified: {} };
+            return { notified: {}, staleNotified: {} };
         const raw = JSON.parse(readFileSync(STATE_FILE, 'utf-8'));
-        return { notified: raw.notified ?? {} };
+        return {
+            notified: raw.notified ?? {},
+            staleNotified: raw.staleNotified ?? {},
+        };
     }
     catch {
-        return { notified: {} };
+        return { notified: {}, staleNotified: {} };
     }
 }
 function saveState(state) {
@@ -470,6 +474,15 @@ export async function runFailureSweep(send, gateway, now = Date.now()) {
             logger.warn({ err }, 'Suspicious-run grading pre-pass failed (non-fatal)');
         }
     }
+    // SLA sweep runs unconditionally — catches jobs that silently stopped
+    // firing entirely, which the broken-job detector can't see because those
+    // jobs produce no error entries.
+    try {
+        await runSlaSweep(send, now);
+    }
+    catch (err) {
+        logger.warn({ err }, 'SLA sweep failed (non-fatal)');
+    }
     const broken = computeBrokenJobs(now);
     if (broken.length === 0) {
         // Clear cooldowns AND diagnostic cache entries for jobs that recovered.
@@ -545,6 +558,67 @@ export async function runFailureSweep(send, gateway, now = Date.now()) {
     }
     return fresh;
 }
+/**
+ * Detect and notify about jobs whose last run is >= SLA_MISSED_TICKS
+ * expected intervals old. Each stale job gets one notification per
+ * SLA_NOTIFY_COOLDOWN_HOURS window. Always emits cron_sla_breach to
+ * audit.jsonl regardless of cooldown so the trace record is complete.
+ */
+async function runSlaSweep(send, now) {
+    const stale = await computeStaleCronJobs(now);
+    if (stale.length === 0) {
+        // Clear cooldowns for jobs that recovered (are no longer stale).
+        const state = loadState();
+        let mutated = false;
+        for (const name of Object.keys(state.staleNotified)) {
+            if (!stale.find(s => s.jobName === name)) {
+                delete state.staleNotified[name];
+                mutated = true;
+            }
+        }
+        if (mutated)
+            saveState(state);
+        return;
+    }
+    // Emit audit events for every stale detection so downstream
+    // tooling (dashboards, alerts) has a complete record.
+    for (const job of stale) {
+        logAuditJsonl({
+            event_type: 'cron_sla_breach',
+            jobName: job.jobName,
+            agent_slug: job.agentSlug,
+            schedule: job.schedule,
+            lastRunAt: job.lastRunAt,
+            expectedIntervalMs: job.expectedIntervalMs,
+            overdueMinutes: job.overdueMinutes,
+        });
+    }
+    // Apply per-job notify cooldown so we don't spam.
+    const state = loadState();
+    const cooldownMs = SLA_NOTIFY_COOLDOWN_HOURS * 60 * 60 * 1000;
+    const fresh = [];
+    for (const job of stale) {
+        const prev = state.staleNotified[job.jobName];
+        if (prev && now - Date.parse(prev.lastNotifiedAt) < cooldownMs)
+            continue;
+        fresh.push(job);
+    }
+    if (fresh.length === 0)
+        return;
+    try {
+        await send(formatStaleReport(fresh));
+        const stamp = new Date(now).toISOString();
+        for (const job of fresh) {
+            state.staleNotified[job.jobName] = { lastNotifiedAt: stamp, lastRunAt: job.lastRunAt };
+        }
+        saveState(state);
+        appendAuditLog('sla_notified', fresh.map(j => j.jobName));
+        logger.info({ count: fresh.length, jobs: fresh.map(j => j.jobName) }, 'SLA monitor: notified owner about stale jobs');
+    }
+    catch (err) {
+        logger.warn({ err }, 'SLA monitor: notification dispatch failed');
+    }
+}
 function appendAuditLog(action, jobNames) {
     try {
         const auditPath = path.join(BASE_DIR, 'cron', 'failure-monitor.log');
@@ -606,4 +680,73 @@ async function loadJobPrompt(jobName) {
         return null;
     }
 }
+/** A job is "stale" if it has missed >= this many expected ticks. */
+const SLA_MISSED_TICKS = 3;
+/** Absolute floor so sub-hourly cron jobs don't alert too aggressively. */
+const SLA_MIN_OVERDUE_MS = 30 * 60 * 1000;
+/** Don't re-DM the owner about the same stale job within this window. */
+const SLA_NOTIFY_COOLDOWN_HOURS = 12;
+/**
+ * Walk enabled cron jobs and find ones that haven't run in at least
+ * SLA_MISSED_TICKS × their expected interval. Distinct from the broken-job
+ * detector which needs actual error entries — this catches the opposite
+ * failure mode: a job that silently stopped firing at all.
+ */
+export async function computeStaleCronJobs(now = Date.now()) {
+    const { parseCronJobs, parseAgentCronJobs, CronRunLog } = await import('./cron-scheduler.js');
+    const { AGENTS_DIR } = await import('../config.js');
+    const cronParser = await import('cron-parser');
+    const jobs = [...parseCronJobs(), ...parseAgentCronJobs(AGENTS_DIR)];
+    const runLog = new CronRunLog();
+    const stale = [];
+    for (const job of jobs) {
+        if (!job.enabled)
+            continue;
+        if (job.mode === 'unleashed')
+            continue; // one-shot, no recurring SLA
+        // Normalize schedule — node-cron accepts 6-field (with seconds) but
+        // cron-parser only takes 5-field.
+        const fields = job.schedule.trim().split(/\s+/);
+        const expr = fields.length === 6 ? fields.slice(1).join(' ') : job.schedule;
+        let intervalMs;
+        try {
+            const parser = cronParser.CronExpressionParser.parse(expr);
+            const next = parser.next().toDate().getTime();
+            const prev = parser.prev().toDate().getTime();
+            intervalMs = next - prev;
+        }
+        catch {
+            continue; // malformed schedule — separate concern
+        }
+        if (intervalMs <= 0)
+            continue;
+        const recent = runLog.readRecent(job.name, 1);
+        const lastRunAt = recent[0]?.startedAt ?? null;
+        const lastRunMs = lastRunAt ? Date.parse(lastRunAt) : 0;
+        const threshold = Math.max(intervalMs * SLA_MISSED_TICKS, SLA_MIN_OVERDUE_MS);
+        const sinceLastRun = now - lastRunMs;
+        if (sinceLastRun <= threshold)
+            continue;
+        stale.push({
+            jobName: job.name,
+            agentSlug: job.agentSlug,
+            schedule: job.schedule,
+            lastRunAt,
+            expectedIntervalMs: intervalMs,
+            overdueMinutes: Math.round((sinceLastRun - intervalMs) / 60_000),
+        });
+    }
+    return stale;
+}
+function formatStaleReport(stale) {
+    const lines = ['**Cron SLA breach — jobs that should have run but didn\'t:**', ''];
+    for (const job of stale) {
+        const last = job.lastRunAt ? `last ran ${new Date(job.lastRunAt).toISOString().slice(0, 16).replace('T', ' ')}` : 'never run';
+        const intervalMin = Math.round(job.expectedIntervalMs / 60_000);
+        lines.push(`- **${job.jobName}** (${job.schedule}, every ${intervalMin}m) — ${last}, overdue by ~${job.overdueMinutes}m`);
+    }
+    lines.push('');
+    lines.push('The scheduler may be stuck, the job may have thrown before logging, or it may have been silently disabled. Check the dashboard Scheduled Tasks panel.');
+    return lines.join('\n');
+}
 //# sourceMappingURL=failure-monitor.js.map

package/dist/gateway/router.js

@@ -872,10 +872,43 @@ export class Gateway {
                 const isInteractive = isOwnerDm
                     || sessionKey.startsWith('dashboard:')
                     || sessionKey.startsWith('cli:');
-                if (isInteractive && !isInternalMsg && !text.startsWith('!')) {
+                if (isInteractive && !isInternalMsg && !text.startsWith('!') && !sess?.deepTask) {
                     try {
                         const { classifyComplexity, planFirstDirective } = await import('../agent/complexity-classifier.js');
                         const verdict = classifyComplexity(text);
+                        // deepWorthy: skip the main-agent turn entirely and route
+                        // straight to background execution. Saves the turn that would
+                        // almost certainly get auto-escalated after burning 3+ tool
+                        // calls (see the post-flight auto-escalation path below).
+                        if (verdict.deepWorthy) {
+                            logger.info({ sessionKey, signals: verdict.signals, reason: verdict.reason }, 'Pre-flight deep-mode gate fired — spawning background task');
+                            const currentSess = this.getSession(sessionKey);
+                            const jobName = `deep-${Date.now()}`;
+                            currentSess.deepTask = { jobName, taskDesc: text.slice(0, 200), startedAt: new Date().toISOString() };
+                            const preflightAgentSlug = this._agentSlugFromSessionKey(sessionKey);
+                            this.assistant.runUnleashedTask(jobName, `The user asked: ${text}\n\nThis was routed straight to background execution because it looks like sustained multi-step work. Complete the task thoroughly and return a conversational summary.`, 2, // tier 2 (Bash/Write/Edit enabled)
+                            undefined, // default maxTurns
+                            undefined, // default model
+                            undefined, // default work_dir
+                            1, // maxHours
+                            preflightAgentSlug).then(async (result) => {
+                                logger.info({ sessionKey, jobName, resultLen: result?.length ?? 0 }, 'Pre-flight deep-mode task completed');
+                                if (result && result !== '__NOTHING__') {
+                                    this.assistant.injectPendingContext(sessionKey, text, result);
+                                    await this._deliverDeepResult(sessionKey, `[DEEP_MODE_RESULT] You just completed background work for this user request. Summarize conversationally — lead with what matters.\n\nTask: ${text.slice(0, 500)}\n\nResult:\n${result.slice(0, 3000)}`, result);
+                                }
+                            }).catch(async (err) => {
+                                logger.error({ err, sessionKey, jobName }, 'Pre-flight deep-mode task failed');
+                                const failMsg = `Background work failed: ${String(err).slice(0, 200)}`;
+                                this.assistant.injectPendingContext(sessionKey, text, failMsg);
+                                await this._deliverDeepResult(sessionKey, `[DEEP_MODE_RESULT] The background task failed: ${failMsg}. Let the user know and suggest next steps. Be brief.`, `Background task failed: ${failMsg}`);
+                            }).finally(() => {
+                                const s = this.sessions.get(sessionKey);
+                                if (s?.deepTask?.jobName === jobName)
+                                    delete s.deepTask;
+                            });
+                            return `On it — this looks like real work. Running it in the background; I'll follow up when it's done. Reply "cancel" to stop or "status" to check in.`;
+                        }
                         if (verdict.complex) {
                             logger.info({ sessionKey, signals: verdict.signals, reason: verdict.reason }, 'Pre-flight planning directive injected');
                             enrichedText = `${planFirstDirective()}\n\n---\n\n${text}`;

package/package.json

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