clementine-agent 1.0.31 → 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/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.31",
+  "version": "1.0.32",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",