clementine-agent 1.18.38 → 1.18.40

package/dist/agent/fanout-policy.d.ts

@@ -56,4 +56,37 @@ export declare function buildFanoutDirectiveForText(text: string): {
     directive: string;
     report: FanoutSignalReport;
 };
+export interface PreLlmPlanDecision {
+    shouldRouteToPlanner: boolean;
+    reason: string;
+    signals: FanoutSignal[];
+    actionVerbs: string[];
+}
+export interface PreLlmPlanOptions {
+    /** Result of intent classifier — routing skips followup/chat regardless of content. */
+    intentType?: 'task' | 'followup' | 'chat' | 'lookup' | string;
+    /** Pre-LLM minimum length. Short queries can't be plan-worthy. */
+    minLength?: number;
+    /** Conservative AND-threshold: require ≥N fanout signals AND ≥1 action verb. */
+    minFanoutSignals?: number;
+}
+/**
+ * Decide whether the user's text should bypass the main agent and run
+ * directly through the planner orchestrator.
+ *
+ * Threshold model: combined "evidence count" ≥ 2, where each FANOUT
+ * SIGNAL and each MULTI-TARGET ACTION VERB counts as one piece of
+ * evidence. So "research my 100 leads and email each one" gets:
+ *   - 1 fanout signal (numeric_collection: "100 leads")
+ *   - 1 multi-target verb (research my 100 leads)
+ *   = 2 → routes
+ *
+ * False-positive guards stay in front:
+ *   - intent != followup/chat
+ *   - text length ≥ 30 chars
+ *   - NOT an informational query (what/tell me/show me/...)
+ *   - at least ONE action verb (no orchestration for pure declarative
+ *     statements even if they reference multiple items)
+ */
+export declare function detectPreLlmPlanIntent(text: string, opts?: PreLlmPlanOptions): PreLlmPlanDecision;
 //# sourceMappingURL=fanout-policy.d.ts.map

package/dist/agent/fanout-policy.js

@@ -130,4 +130,114 @@ export function buildFanoutDirectiveForText(text) {
         report,
     };
 }
+// ── Pre-LLM plan intent detection ─────────────────────────────────────
+//
+// detectFanoutSignals + the directive injection (above) are SOFT
+// enforcement: we tell the agent "fan out for this." If the agent
+// honors it, we win. If not, we still pay for a Sonnet turn that
+// thrashes.
+//
+// Pre-LLM plan intent detection is HARD enforcement: when a user's
+// query clearly maps to multi-step parallel work, route through the
+// orchestrator BEFORE the main agent ever runs. The orchestrator
+// decomposes into parallel Haiku/Sonnet sub-agents, each in its own
+// context. The user's main agent never sees the big tool responses
+// — it never gets a chance to thrash.
+//
+// Conservative gate: false positives waste a planner LLM call (~$0.05)
+// + sub-agent calls. False negatives mean the existing soft-enforcement
+// path runs, which is the status quo. So we tune for false positives.
+const INFORMATIONAL_QUERY_PATTERN = /^\s*(what|tell\s+me|show\s+me|is\s|are\s|do\s+you|how\s+(does|is|do)|why\s|when\s|where\s|who\s|did\s|have\s+you|can\s+you\s+(see|tell|show|describe|explain)|describe|explain|summarize)\b/i;
+const ACTION_VERB_PATTERNS = [
+    {
+        // "research my top 10 prospects", "draft each prospect", "process all leads"
+        pattern: /\b(research|analyze|process|review|draft|write|send|email|message|outreach)\s+(each|all|every|those|these|my|our|the\s+\w+|\d+|\w+\s+(of\s+)?(my|our|the)\s+\w+)/i,
+        reason: 'multi-target action verb (research/analyze/draft/etc. on a collection)',
+    },
+    {
+        // "for each prospect, draft a follow-up"
+        pattern: /\bfor\s+(each|every|all)\b.*\b(do|run|send|draft|process|email|call|review|analyze|build|create|fetch)/i,
+        reason: '"for each X, do Y" pattern',
+    },
+    {
+        // "build a comprehensive content intelligence brief" — allow up to 4
+        // words between the verb and the deliverable noun.
+        pattern: /\b(build|prepare|produce|run|generate)\s+(a\s+|an\s+)?(\w+\s+){0,4}(brief|report|summary|analysis|comparison|recap|breakdown|dashboard|deck|index|list)\b/i,
+        reason: 'compound deliverable (brief/report/analysis)',
+    },
+    {
+        pattern: /\b(go\s+through|walk\s+through|process)\s+(every|all|each|my|the)\s+\w+/i,
+        reason: '"go through everyone/everything" pattern',
+    },
+];
+/**
+ * Decide whether the user's text should bypass the main agent and run
+ * directly through the planner orchestrator.
+ *
+ * Threshold model: combined "evidence count" ≥ 2, where each FANOUT
+ * SIGNAL and each MULTI-TARGET ACTION VERB counts as one piece of
+ * evidence. So "research my 100 leads and email each one" gets:
+ *   - 1 fanout signal (numeric_collection: "100 leads")
+ *   - 1 multi-target verb (research my 100 leads)
+ *   = 2 → routes
+ *
+ * False-positive guards stay in front:
+ *   - intent != followup/chat
+ *   - text length ≥ 30 chars
+ *   - NOT an informational query (what/tell me/show me/...)
+ *   - at least ONE action verb (no orchestration for pure declarative
+ *     statements even if they reference multiple items)
+ */
+export function detectPreLlmPlanIntent(text, opts = {}) {
+    const minLength = opts.minLength ?? 30;
+    const minCombinedEvidence = opts.minFanoutSignals ?? 2;
+    const trimmed = (text ?? '').trim();
+    // Hard skips: intent says "not a task" → don't override.
+    if (opts.intentType === 'followup' || opts.intentType === 'chat') {
+        return { shouldRouteToPlanner: false, reason: `intent_is_${opts.intentType}`, signals: [], actionVerbs: [] };
+    }
+    if (trimmed.length < minLength) {
+        return { shouldRouteToPlanner: false, reason: 'too_short', signals: [], actionVerbs: [] };
+    }
+    // Information-seeking patterns: "what/tell me/show me/etc." Let the
+    // agent answer directly even if collective wording is present
+    // ("tell me about all my prospects" is a status request, not work).
+    if (INFORMATIONAL_QUERY_PATTERN.test(trimmed)) {
+        return { shouldRouteToPlanner: false, reason: 'informational_query', signals: [], actionVerbs: [] };
+    }
+    // Action-verb match: text must contain at least one explicit
+    // multi-target verb. This blocks pure declarative statements ("100
+    // prospects are in the pipeline" — referencing many items but no
+    // ask for work).
+    const matchedVerbs = [];
+    for (const { pattern, reason } of ACTION_VERB_PATTERNS) {
+        if (pattern.test(trimmed))
+            matchedVerbs.push(reason);
+    }
+    if (matchedVerbs.length === 0) {
+        return { shouldRouteToPlanner: false, reason: 'no_action_verb', signals: [], actionVerbs: [] };
+    }
+    // Combined evidence: fanout signals + verb matches. Each piece of
+    // evidence independently suggests multi-step work; together they
+    // strongly do. Threshold ≥ 2 means a query with one numeric collection
+    // ("100 leads") AND one multi-target verb ("research those") routes,
+    // but a query with just a verb and no collection ("research the
+    // prospect Mark") does not.
+    const fanoutReport = detectFanoutSignals(trimmed);
+    const combinedEvidence = fanoutReport.signals.length + matchedVerbs.length;
+    if (combinedEvidence < minCombinedEvidence) {
+        return {
+            shouldRouteToPlanner: false,
+            reason: `weak_evidence_${combinedEvidence}_below_${minCombinedEvidence}_(fanout=${fanoutReport.signals.length},verbs=${matchedVerbs.length})`,
+            signals: fanoutReport.signals,
+            actionVerbs: matchedVerbs,
+        };
+    }
+    return {
+        shouldRouteToPlanner: true,
+        reason: `evidence=${combinedEvidence} (fanout=${fanoutReport.signals.length},verbs=${matchedVerbs.length})`,
+        signals: fanoutReport.signals,
+        actionVerbs: matchedVerbs,
+    };
+}
 //# sourceMappingURL=fanout-policy.js.map

package/dist/gateway/router.js

@@ -23,6 +23,7 @@ import { assessActionResponse, buildActionEnforcementPrompt, buildApprovalFollow
 import { updateClementineJson } from '../config/clementine-json.js';
 import { buildCronDiagnosticResponse } from './cron-diagnostic-turn.js';
 import { classifyIntent } from '../agent/intent-classifier.js';
+import { detectPreLlmPlanIntent } from '../agent/fanout-policy.js';
 import { decideTurn } from '../agent/turn-policy.js';
 import { recordProactiveNotificationEvent, } from './notification-context.js';
 import { isInternalSyntheticPrompt, resolveRecentOperationalContext } from './recent-context.js';
@@ -2087,6 +2088,60 @@ export class Gateway {
                     delete sessState.pendingInterrupt;
                 }
                 try {
+                    // ── Pre-LLM plan routing (Gap #3 from orchestration audit) ──
+                    // When the user's text clearly maps to multi-step parallel
+                    // work, route through the orchestrator BEFORE the main agent
+                    // runs. This is HARD enforcement — independent of whether
+                    // the agent self-detects via [PLAN_NEEDED:]. Saves a Sonnet
+                    // turn that would likely thrash, and the planner's parallel
+                    // sub-agents (Haiku-default) keep big tool responses out of
+                    // the user's main context.
+                    //
+                    // Conservative gate: requires explicit action verbs +
+                    // multiple fanout signals + non-informational intent. False
+                    // positives waste a planner LLM call (~$0.05); false
+                    // negatives let the existing soft-enforcement path run, which
+                    // is the status quo. Trusted personal sessions only — we
+                    // don't surprise random Discord users with auto-orchestration.
+                    if (this.isTrustedPersonalSession(sessionKey)
+                        && !sessState.pendingInterrupt /* don't override mid-thought continuations */) {
+                        const planIntentDecision = detectPreLlmPlanIntent(originalText, {
+                            intentType: classifyIntent(originalText)?.type,
+                        });
+                        if (planIntentDecision.shouldRouteToPlanner) {
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                reason: planIntentDecision.reason,
+                                signals: planIntentDecision.signals.map(s => s.pattern),
+                                actionVerbs: planIntentDecision.actionVerbs,
+                                originalTextPreview: originalText.slice(0, 200),
+                            }, 'Pre-LLM plan routing: bypassing main agent for orchestrator');
+                            if (wrappedOnText) {
+                                try {
+                                    await wrappedOnText('Detected a multi-step task — decomposing into parallel sub-agents…\n\n');
+                                }
+                                catch { /* streaming is best-effort */ }
+                            }
+                            try {
+                                const planResult = await this.handlePlan(effectiveSessionKey, originalText, undefined, // chat path doesn't need structured progress callbacks
+                                undefined);
+                                clearTimeout(chatTimer);
+                                clearTimeout(hardWallTimer);
+                                logger.info({
+                                    sessionKey: effectiveSessionKey,
+                                    totalMs: Date.now() - tInnerStart,
+                                    routedVia: 'pre_llm_planner',
+                                    responseLen: planResult.length,
+                                }, 'chat:latency');
+                                return planResult;
+                            }
+                            catch (err) {
+                                logger.warn({ err, sessionKey: effectiveSessionKey }, 'Pre-LLM plan routing failed — falling back to direct agent');
+                                // Fall through to the regular agent path so the user
+                                // still gets a response.
+                            }
+                        }
+                    }
                     // No artificial turn cap — let the agent work until done.
                     // Primary guardrail is cost budget (maxBudgetUsd in buildOptions).
                     // Wall clock (CHAT_MAX_WALL_MS) and StallGuard are safety nets.
@@ -2553,7 +2608,15 @@ export class Gateway {
                 this.getSession(sessionKey).abortController = planAc;
                 const { PlanOrchestrator } = await import('../agent/orchestrator.js');
                 const orchestrator = new PlanOrchestrator(this.assistant);
-                const result = await orchestrator.run(taskDescription, onProgress, onApproval, undefined, planAc.signal);
+                // Make hired agents (Ross, Sasha, Nora, etc.) visible to the
+                // planner so it can `delegateTo: <slug>` for steps that match
+                // an agent's specialty. Without this the planner generates
+                // generic steps even when a specialized agent is the right
+                // choice. Empty list = solo Clementine, planner stays generic.
+                const teamAgents = this.getAgentManager()
+                    .listAll()
+                    .filter(a => a.slug !== 'clementine');
+                const result = await orchestrator.run(taskDescription, onProgress, onApproval, teamAgents.length > 0 ? teamAgents : undefined, planAc.signal);
                 scanner.refreshIntegrity();
                 this.assistant.injectContext(sessionKey, `[Plan: ${taskDescription}]`, result);
                 return result;

package/package.json

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