clementine-agent 1.18.190 → 1.18.191

package/dist/agent/clementine-turn-context.d.ts

@@ -85,6 +85,13 @@ export interface BuildTurnContextOptions {
      *  source/output file inventory, and deploy.json summary (if any).
      *  Set by the router's resolver before the chat call. */
     activeProject?: ProjectMeta | null;
+    /** 1.18.191 — message shape from intent-classifier. When 'simple',
+     *  we skip the heavyweight sections (memory recall, bg-task headlines,
+     *  dispute gate) and only emit identity + live state. Saves ~3-4KB
+     *  of injected tokens per routine chat turn. 'multi-step' and
+     *  'unknown' keep the full block. Defaults to 'unknown' = full block
+     *  for back-compat. */
+    messageShape?: 'simple' | 'multi-step' | 'unknown';
 }
 export interface BuildTurnContextResult {
     /** The full ready-to-prepend context block, INCLUDING outer

package/dist/agent/clementine-turn-context.js

@@ -68,12 +68,26 @@ export function buildClementineTurnContext(opts) {
     const parts = [];
     const nowMs = (opts.now ?? Date.now)();
     const nowDate = new Date(nowMs);
+    // 1.18.191 — intent-aware section gating. For 'simple' messages
+    // (one-line questions, casual chat, brief asks), the heavy sections
+    // (memory recall, bg-task headlines, dispute gate) are skipped so
+    // every routine turn doesn't pay 3-4KB of injected tokens for
+    // context the model doesn't need. Identity + live state still
+    // render — they're cheap and always useful. Active project still
+    // renders when the message references it. 'multi-step' and
+    // 'unknown' keep the full block.
+    const messageShape = opts.messageShape ?? 'unknown';
+    const isSimpleMessage = messageShape === 'simple';
     // 1.18.187 — detect dispute pattern (Part E). When the owner is
     // reporting a failure of prior work, we want to suppress "past
     // success" recall items (they bias the model toward defending its
     // memory instead of verifying reality) and add a verification
     // directive at the top of the block.
-    const disputeDetected = detectDisputePattern(opts.userMessage);
+    // 1.18.191 — also suppressed for 'simple' shape since dispute
+    // patterns rarely co-occur with simple messages, and the gate
+    // produces a multi-paragraph directive we don't want to inject
+    // when the message is just "what time is it".
+    const disputeDetected = !isSimpleMessage && detectDisputePattern(opts.userMessage);
     sections.disputeDetected = disputeDetected;
     if (disputeDetected) {
         parts.push('### Dispute mode — verification posture\n' +
@@ -103,7 +117,14 @@ export function buildClementineTurnContext(opts) {
     // hits from the SQLite memory store, scored against the user's
     // current message. Without this, Clementine has no automatic recall
     // — she'd have to spontaneously call memory_search every turn.
-    if (opts.memoryStore?.searchContext && opts.userMessage.trim().length > 0) {
+    //
+    // 1.18.191 — skipped for 'simple' messages. "What time is it" doesn't
+    // need 6 memory hits injected; she has the recall tools and can call
+    // them on demand when the message warrants it. Saves ~2KB/turn on
+    // routine chat. The owner's own posture directive
+    // (BEHAVIORAL_POSTURE in run-agent-context.ts) tells the model to
+    // call memory_search proactively when relevant — that still works.
+    if (!isSimpleMessage && opts.memoryStore?.searchContext && opts.userMessage.trim().length > 0) {
         try {
             const hits = opts.memoryStore.searchContext(opts.userMessage, {
                 limit: MAX_MEMORY_HITS,
@@ -139,7 +160,12 @@ export function buildClementineTurnContext(opts) {
     // that bias the model toward "but my memory says it succeeded."
     // Failed/aborted/interrupted tasks STAY because they're useful
     // signal for the verification posture.
-    if (opts.listBackgroundTasks) {
+    //
+    // 1.18.191 — skipped for 'simple' messages. Routine chat doesn't
+    // need to know what bg tasks landed in the last 24h. If the user
+    // asks "what happened with X" — that's a multi-step / unknown
+    // shape, this section will fire normally.
+    if (!isSimpleMessage && opts.listBackgroundTasks) {
         try {
             const TERMINAL = disputeDetected
                 ? ['failed', 'interrupted', 'aborted']

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

@@ -31,6 +31,51 @@ export declare function classifyIntent(text: string, recentExchanges?: Array<{
  * Injected into the system prompt to steer the agent's response style.
  */
 export declare function getStrategyGuidance(strategy: ResponseStrategy): string;
+export type MessageShape = 
+/** Single ask, single response. "what time is it", "remind me to call X". */
+'simple'
+/** Multiple distinct actions across phases. "send 25 emails after
+ *  scraping data from Salesforce and SEO sources, then summarize". */
+ | 'multi-step'
+/** Ambiguous — falls through to today's full chat path (safe default). */
+ | 'unknown';
+export interface MessageShapeResult {
+    shape: MessageShape;
+    score: number;
+    reasons: string[];
+}
+/**
+ * Classify a chat message's structural shape (simple / multi-step).
+ *
+ * Scoring (sum of triggered signals):
+ *   - 2+ shape-action verbs: +1
+ *   - 3+ shape-action verbs: +2 cumulatively
+ *   - each sequence marker ("and then", "after that"): +1 (up to +2)
+ *   - batch marker ("for each", "25 emails"): +1
+ *   - numbered list: +2
+ *   - 2+ distinct integration domains in same message: +1
+ *   - length > 200 chars: +1
+ *   - length > 500 chars: +2 cumulatively
+ *
+ * Decision:
+ *   - score >= threshold (default 3) → 'multi-step'
+ *   - score === 0 AND <= 1 action verb AND length <= 200 → 'simple'
+ *   - otherwise → 'unknown' (today's chat path, no change)
+ */
+export declare function classifyMessageShape(text: string, opts?: {
+    threshold?: number;
+}): MessageShapeResult;
+/**
+ * Detect whether the user's message is approving / revising / canceling
+ * a pending plan. Used by the chat-side plan-mode state machine when
+ * `sess.planAwaitingApproval` is set.
+ *
+ * Conservative: only short, clearly-affirmative messages qualify as
+ * approval. "yes but also do X" is NOT approval — it's a revision
+ * request and the state machine should re-plan with the feedback.
+ */
+export type PlanApprovalSignal = 'approve' | 'revise' | 'cancel' | 'other';
+export declare function detectPlanApproval(message: string): PlanApprovalSignal;
 /**
  * Generate a follow-up suggestion prompt suffix based on completed work.
  *

package/dist/agent/intent-classifier.js

@@ -188,6 +188,150 @@ No tool calls needed. Just be conversational.
 If there's relevant context from recent work or pending items, briefly mention it.`;
     }
 }
+/** Action verbs that strongly suggest "do work" rather than "answer". */
+const SHAPE_ACTION_VERBS = [
+    'send', 'create', 'build', 'generate', 'write', 'draft', 'compose',
+    'publish', 'deploy', 'upload', 'post', 'push',
+    'scrape', 'fetch', 'pull', 'extract', 'gather', 'collect',
+    'convert', 'merge', 'combine', 'transform', 'consolidate', 'aggregate',
+    'schedule', 'queue', 'run', 'execute', 'process',
+    'email', 'message', 'notify', 'alert', 'reply', 'forward',
+    'import', 'export', 'sync', 'backup',
+];
+const SHAPE_SEQUENCE_MARKERS = [
+    /\band\s+then\b/i,
+    /\b(?:after|once|when)\s+(?:that|you|done|finished|complete)/i,
+    /\b(?:then|next|finally|last)\s*[,]?\s+\w+/i,
+    /\bfollowed\s+by\b/i,
+    /\b(?:step|phase)\s+\d+/i,
+];
+const SHAPE_BATCH_MARKERS = [
+    /\b(?:for|on|to)\s+each\b/i,
+    /\b\d{2,}\s+\w+/, // "25 emails", "100 records"
+    /\beach\s+of\s+(?:them|the)\b/i,
+    /\b(?:all|every)\s+(?:of\s+)?(?:them|the\s+\w+)/i,
+    /\b(?:bulk|batch|mass)\b/i,
+];
+const SHAPE_NUMBERED_LIST = /\n\s*\d+[.)]\s+\w+/;
+const SHAPE_DOMAIN_MARKERS = [
+    /\bsalesforce\b/i, /\bgmail\b/i, /\boutlook\b/i, /\bslack\b/i,
+    /\bdiscord\b/i, /\bnetlify\b/i, /\bvercel\b/i, /\bgithub\b/i,
+    /\bsupabase\b/i, /\bairtable\b/i, /\bhubspot\b/i, /\bnotion\b/i,
+    /\blinkedin\b/i, /\bcalendar\b/i, /\bdrive\b/i, /\bsheets\b/i,
+];
+/**
+ * Classify a chat message's structural shape (simple / multi-step).
+ *
+ * Scoring (sum of triggered signals):
+ *   - 2+ shape-action verbs: +1
+ *   - 3+ shape-action verbs: +2 cumulatively
+ *   - each sequence marker ("and then", "after that"): +1 (up to +2)
+ *   - batch marker ("for each", "25 emails"): +1
+ *   - numbered list: +2
+ *   - 2+ distinct integration domains in same message: +1
+ *   - length > 200 chars: +1
+ *   - length > 500 chars: +2 cumulatively
+ *
+ * Decision:
+ *   - score >= threshold (default 3) → 'multi-step'
+ *   - score === 0 AND <= 1 action verb AND length <= 200 → 'simple'
+ *   - otherwise → 'unknown' (today's chat path, no change)
+ */
+export function classifyMessageShape(text, opts = {}) {
+    const reasons = [];
+    let score = 0;
+    if (!text || !text.trim()) {
+        return { shape: 'simple', score: 0, reasons: ['empty'] };
+    }
+    const trimmed = text.trim();
+    const lower = trimmed.toLowerCase();
+    const words = new Set(lower.replace(/[^\w\s-]/g, ' ').split(/\s+/).filter(Boolean));
+    // Action verbs
+    const matchedVerbs = [];
+    for (const verb of SHAPE_ACTION_VERBS) {
+        if (words.has(verb))
+            matchedVerbs.push(verb);
+    }
+    if (matchedVerbs.length >= 2) {
+        score += 1;
+        reasons.push(`2+ action verbs (${matchedVerbs.slice(0, 4).join(', ')})`);
+    }
+    if (matchedVerbs.length >= 3) {
+        score += 1;
+        reasons.push('3+ action verbs');
+    }
+    // Sequence markers
+    for (const rx of SHAPE_SEQUENCE_MARKERS) {
+        const matches = lower.match(new RegExp(rx.source, 'gi'));
+        if (matches && matches.length > 0) {
+            score += Math.min(matches.length, 2);
+            reasons.push(`sequence marker: ${matches[0]}`);
+            break;
+        }
+    }
+    // Batch markers
+    for (const rx of SHAPE_BATCH_MARKERS) {
+        if (rx.test(trimmed)) {
+            score += 1;
+            reasons.push('batch marker (for each / N items / bulk)');
+            break;
+        }
+    }
+    // Numbered list
+    if (SHAPE_NUMBERED_LIST.test(trimmed)) {
+        score += 2;
+        reasons.push('numbered list');
+    }
+    // Cross-domain
+    let domainCount = 0;
+    for (const rx of SHAPE_DOMAIN_MARKERS) {
+        if (rx.test(trimmed))
+            domainCount += 1;
+    }
+    if (domainCount >= 2) {
+        score += 1;
+        reasons.push(`${domainCount} integration domains mentioned`);
+    }
+    // Length
+    if (trimmed.length > 200) {
+        score += 1;
+        reasons.push(`length > 200 (${trimmed.length})`);
+    }
+    if (trimmed.length > 500) {
+        score += 1;
+        reasons.push(`length > 500`);
+    }
+    // Decision
+    const threshold = opts.threshold ?? 3;
+    let shape;
+    if (score >= threshold) {
+        shape = 'multi-step';
+    }
+    else if (score === 0 && matchedVerbs.length <= 1 && trimmed.length <= 200) {
+        shape = 'simple';
+    }
+    else {
+        shape = 'unknown';
+    }
+    return { shape, score, reasons };
+}
+const APPROVE_RE = /^(?:yes|y|yep|yeah|yup|sure|ok|okay|approve|approved|go|go ahead|run it|do it|sounds good|lgtm|ship it|👍|✅)[\s.!]*$/i;
+const CANCEL_RE = /^(?:cancel|stop|nvm|nevermind|never\s*mind|forget it|don['']?t|abort|kill it)\b/i;
+const REVISE_RE = /\b(?:but|except|instead|change|modify|add(?:\s+also)?|remove|skip|swap|wait|actually|hold on)\b/i;
+export function detectPlanApproval(message) {
+    if (!message)
+        return 'other';
+    const text = message.trim();
+    if (!text)
+        return 'other';
+    if (CANCEL_RE.test(text))
+        return 'cancel';
+    if (text.length <= 30 && APPROVE_RE.test(text))
+        return 'approve';
+    if (text.length > 30 || REVISE_RE.test(text))
+        return 'revise';
+    return 'other';
+}
 /**
  * Generate a follow-up suggestion prompt suffix based on completed work.
  *

package/dist/gateway/router.d.ts

@@ -88,6 +88,31 @@ export declare class Gateway {
     private queueBackgroundOffer;
     private formatBackgroundQueuedResponse;
     private queueBackgroundTaskAfterContextOverflow;
+    /**
+     * 1.18.191 — chat-side plan mode state machine.
+     *
+     * Two paths it handles:
+     *
+     *   A. Approval-pending path. If sess.planAwaitingApproval is set,
+     *      the user's message NOW is either approval / revision / cancel.
+     *      Approval → dispatch the chain. Revision → re-plan with feedback.
+     *      Cancel → clear pending state.
+     *
+     *   B. Multi-step entry path. shape='multi-step' AND no pending plan:
+     *      run planRequest synchronously, post the plan to chat asking
+     *      for approval, set pending state. The owner's NEXT message
+     *      advances via path A.
+     *
+     * Returns `{ handled: true, response }` when plan mode owns this turn
+     * (caller should return the response without running normal chat).
+     * Returns `{ handled: false }` to fall through to normal chat.
+     *
+     * Defensive on every external call — failures degrade to normal chat
+     * rather than blocking the owner's conversation.
+     */
+    private _maybeHandlePlanMode;
+    /** Format a plan for owner approval in chat. */
+    private _formatPlanForApproval;
     acceptBackgroundOffer(sessionKey: string, id: string): {
         ok: boolean;
         response: string;

package/dist/gateway/router.js

@@ -469,6 +469,163 @@ export class Gateway {
             ].join('\n'),
         };
     }
+    /**
+     * 1.18.191 — chat-side plan mode state machine.
+     *
+     * Two paths it handles:
+     *
+     *   A. Approval-pending path. If sess.planAwaitingApproval is set,
+     *      the user's message NOW is either approval / revision / cancel.
+     *      Approval → dispatch the chain. Revision → re-plan with feedback.
+     *      Cancel → clear pending state.
+     *
+     *   B. Multi-step entry path. shape='multi-step' AND no pending plan:
+     *      run planRequest synchronously, post the plan to chat asking
+     *      for approval, set pending state. The owner's NEXT message
+     *      advances via path A.
+     *
+     * Returns `{ handled: true, response }` when plan mode owns this turn
+     * (caller should return the response without running normal chat).
+     * Returns `{ handled: false }` to fall through to normal chat.
+     *
+     * Defensive on every external call — failures degrade to normal chat
+     * rather than blocking the owner's conversation.
+     */
+    async _maybeHandlePlanMode(opts) {
+        const sess = this.sessions.get(opts.sessionKey);
+        const { detectPlanApproval } = await import('../agent/intent-classifier.js');
+        const { planRequest, savePlan, loadPlan } = await import('../agent/bg-planner.js');
+        const { dispatchChain } = await import('../agent/bg-orchestrator.js');
+        // ── Path A: approval-pending ────────────────────────────────────
+        if (sess?.planAwaitingApproval) {
+            const pending = sess.planAwaitingApproval;
+            const signal = detectPlanApproval(opts.userMessage);
+            logger.info({
+                sessionKey: opts.sessionKey,
+                planId: pending.planId,
+                chainId: pending.chainId,
+                signal,
+            }, 'Plan mode: approval signal received');
+            const plan = loadPlan(pending.planId, opts.activeProject?.path);
+            if (!plan) {
+                // Plan disappeared from disk — clear the pending state and
+                // let the message fall through to normal chat.
+                delete sess.planAwaitingApproval;
+                logger.warn({ planId: pending.planId }, 'Plan mode: pending plan not found on disk — clearing');
+                return { handled: false };
+            }
+            if (signal === 'approve') {
+                try {
+                    const firstTask = dispatchChain(plan);
+                    delete sess.planAwaitingApproval;
+                    const response = [
+                        `**Plan approved — starting step 1: ${plan.steps[0]?.title ?? '(first step)'}**`,
+                        '',
+                        `Background task **${firstTask.id}** is now running.`,
+                        'I\'ll post step-by-step updates as each step completes.',
+                    ].join('\n');
+                    return { handled: true, response };
+                }
+                catch (err) {
+                    logger.warn({ err, planId: plan.id }, 'Plan mode: dispatchChain failed on approval');
+                    return { handled: true, response: `Couldn't start the chain: ${String(err).slice(0, 200)}. Tell me to retry or try a different approach.` };
+                }
+            }
+            if (signal === 'cancel') {
+                delete sess.planAwaitingApproval;
+                return { handled: true, response: 'Cancelled the plan. Tell me what you\'d like to do instead.' };
+            }
+            if (signal === 'revise') {
+                // Re-plan with the user's revision as additional context.
+                try {
+                    const revisedRequest = `${plan.userRequest}\n\n[Revision from owner: ${opts.userMessage}]`;
+                    const newPlan = await planRequest({
+                        userRequest: revisedRequest,
+                        originatingSessionKey: opts.sessionKey,
+                        ...(opts.activeProject ? { project: opts.activeProject } : {}),
+                    });
+                    savePlan(newPlan, newPlan.projectPath);
+                    sess.planAwaitingApproval = {
+                        planId: newPlan.id,
+                        chainId: newPlan.chainId,
+                        proposedAt: Date.now(),
+                    };
+                    return {
+                        handled: true,
+                        response: this._formatPlanForApproval(newPlan, /* revised */ true),
+                    };
+                }
+                catch (err) {
+                    logger.warn({ err }, 'Plan mode: revision planRequest failed');
+                    return { handled: true, response: `Couldn't revise the plan: ${String(err).slice(0, 200)}. Want me to start fresh or try something else?` };
+                }
+            }
+            // signal='other' — let it fall through to normal chat, but keep
+            // pending state. The model will see the user message normally.
+            return { handled: false };
+        }
+        // ── Path B: multi-step entry ────────────────────────────────────
+        if (opts.shape === 'multi-step' && sess) {
+            try {
+                // Stream a "thinking..." update so the user knows planning is
+                // happening rather than seeing 30s of silence.
+                if (opts.onText) {
+                    try {
+                        opts.onText('🤔 Planning the steps...');
+                    }
+                    catch { /* non-fatal */ }
+                }
+                const plan = await planRequest({
+                    userRequest: opts.userMessage,
+                    originatingSessionKey: opts.sessionKey,
+                    ...(opts.activeProject ? { project: opts.activeProject } : {}),
+                });
+                savePlan(plan, plan.projectPath);
+                sess.planAwaitingApproval = {
+                    planId: plan.id,
+                    chainId: plan.chainId,
+                    proposedAt: Date.now(),
+                };
+                return {
+                    handled: true,
+                    response: this._formatPlanForApproval(plan, /* revised */ false),
+                };
+            }
+            catch (err) {
+                logger.warn({ err, sessionKey: opts.sessionKey }, 'Plan mode: planRequest failed at entry');
+                // Fall through to normal chat. Better than blocking the owner.
+                return { handled: false };
+            }
+        }
+        // Not a plan-mode case — fall through to normal chat.
+        return { handled: false };
+    }
+    /** Format a plan for owner approval in chat. */
+    _formatPlanForApproval(plan, revised) {
+        const lines = [];
+        lines.push(revised
+            ? `**Revised plan (${plan.steps.length} steps)**`
+            : `**Here's how I'd do this (${plan.steps.length} steps)**`);
+        lines.push('');
+        for (const step of plan.steps) {
+            lines.push(`${step.index + 1}. **${step.title}**`);
+            if (step.scope)
+                lines.push(`   ${step.scope}`);
+            if (step.deliverable)
+                lines.push(`   → ${step.deliverable}`);
+        }
+        if (plan.notes) {
+            lines.push('');
+            lines.push(`_Notes_: ${plan.notes}`);
+        }
+        if (typeof plan.estimatedCostUsd === 'number') {
+            lines.push('');
+            lines.push(`Estimated cost: ~$${plan.estimatedCostUsd.toFixed(2)}`);
+        }
+        lines.push('');
+        lines.push('Say **yes / approve / go** to start, **cancel** to skip, or describe a revision (e.g., "swap step 3" or "add a verification step").');
+        return lines.join('\n');
+    }
     // Offer-message formatter was removed in the Saturday-feel restoration —
     // the chat path no longer asks "want me to run this in the background?".
     // Auto-queue on explicit user intent is silent; everything else just runs.
@@ -2183,6 +2340,56 @@ export class Gateway {
                     const { buildClementineTurnContext } = await import('../agent/clementine-turn-context.js');
                     const { listBackgroundTasks } = await import('../agent/background-tasks.js');
                     const { resolveProjectFromMessage } = await import('../agent/project-resolver.js');
+                    const { classifyMessageShape } = await import('../agent/intent-classifier.js');
+                    // 1.18.191 — classify message shape early. Simple messages
+                    // get a lean turn-context block (no memory recall, no bg
+                    // headlines, no dispute gate); multi-step messages keep
+                    // the full block AND may trigger plan mode (below).
+                    // Builder sessions skip — they have their own routing.
+                    const shapeResult = !isBuilderSession
+                        ? classifyMessageShape(originalText)
+                        : { shape: 'simple', score: 0, reasons: ['builder-session'] };
+                    logger.debug({
+                        sessionKey: effectiveSessionKey,
+                        shape: shapeResult.shape,
+                        score: shapeResult.score,
+                        reasons: shapeResult.reasons,
+                    }, 'Message shape classified');
+                    // 1.18.191 — plan mode state machine.
+                    //
+                    // Two entry points for plan mode:
+                    //
+                    //   A. Approval-pending path. If the previous turn proposed a
+                    //      plan, the user's message NOW is either approval,
+                    //      revision, or cancel. Handle and return without
+                    //      running normal chat.
+                    //
+                    //   B. Multi-step entry path. If shape='multi-step' AND no
+                    //      pending plan, generate a plan, post it, set pending
+                    //      state, return. The owner's NEXT message advances via
+                    //      path A.
+                    //
+                    // Builder sessions skip both paths.
+                    if (!isBuilderSession) {
+                        const planMode = await this._maybeHandlePlanMode({
+                            sessionKey: effectiveSessionKey,
+                            userMessage: originalText,
+                            shape: shapeResult.shape,
+                            activeProject: this.getSessionProject(effectiveSessionKey) ?? null,
+                            onText: wrappedOnText,
+                        });
+                        if (planMode.handled) {
+                            clearTimeout(chatTimer);
+                            if (hardWallTimer)
+                                clearTimeout(hardWallTimer);
+                            {
+                                const cs = this.sessions.get(sessionKey);
+                                if (cs)
+                                    delete cs.abortController;
+                            }
+                            return planMode.response;
+                        }
+                    }
                     // 1.18.187 — auto-resolve project from the user's message.
                     // If a linked project's name/keyword matches with high
                     // confidence, set sess.project for this turn so cwd shifts,
@@ -2294,6 +2501,10 @@ export class Gateway {
                                 // 1.18.187 — pass active project so the turn-context block
                                 // can include path / STATUS.md / inventory / deploy config.
                                 activeProject: this.getSessionProject(effectiveSessionKey) ?? null,
+                                // 1.18.191 — pass message shape so simple messages get the
+                                // lean turn-context (skip memory recall, bg-task headlines,
+                                // dispute gate). Token-optimization for routine chat.
+                                messageShape: shapeResult.shape,
                             });
                             clementineContextBlock = turnCtx.block;
                             logger.debug({

package/package.json

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