@blockrun/franklin 3.8.27 → 3.8.28

package/dist/agent/loop.js

@@ -39,77 +39,12 @@ function replaceHistory(target, replacement) {
     target.splice(0, target.length, ...replacement);
 }
 // ─── Pushback detection ───────────────────────────────────────────────────
-// Cheap models plough forward when users correct them. This detects common
-// correction patterns so the agent can explicitly reset its approach.
-//
-// Precision-biased: we'd rather miss a real pushback than falsely trigger on
-// casual disagreement ("But how do I deploy?"). False positives pollute the
-// conversation and make the agent abandon working approaches unnecessarily.
-// STRONG patterns: high-precision correction language. Fires even on short input.
-const PUSHBACK_STRONG = [
-    /\b(that'?s?\s+(wrong|incorrect|not\s+right)|you'?re?\s+wrong)\b/i,
-    /\b(i\s+(said|told\s+you)|not\s+what\s+i)\b/i,
-    /^(stop|wrong|incorrect|try\s+again)\b/i,
-    /^(不对|不是|错了|再试|重来)/,
-];
-// WEAK patterns: common correction starters that also appear in casual speech.
-// Require a corroborating signal (see detectPushback) to count as pushback.
-const PUSHBACK_WEAK = [
-    /^(but|however|actually|wait|no+\b|hmm)\b/i,
-    /\b(we\s+are\s+using|the\s+correct|the\s+actual)\b/i,
-    /^(但是|其实|等等|停)/,
-];
-/**
- * True if the last assistant turn made a concrete claim worth pushing back
- * against: executed a tool, wrote code, or produced a non-trivial answer.
- * Casual assistant chatter doesn't warrant treating a "but" as a correction.
- */
-function lastAssistantHasClaim(history) {
-    for (let i = history.length - 1; i >= 0; i--) {
-        const msg = history[i];
-        if (msg.role !== 'assistant')
-            continue;
-        if (Array.isArray(msg.content)) {
-            for (const part of msg.content) {
-                const p = part;
-                if (p.type === 'tool_use')
-                    return true;
-                if (p.type === 'text' && typeof p.text === 'string' && p.text.trim().length >= 40) {
-                    return true;
-                }
-            }
-            return false;
-        }
-        if (typeof msg.content === 'string' && msg.content.trim().length >= 40)
-            return true;
-        return false;
-    }
-    return false;
-}
-function detectPushback(input, history) {
-    // Only count as pushback if there's a prior assistant turn to push back against.
-    if (history.length === 0)
-        return false;
-    if (!lastAssistantHasClaim(history))
-        return false;
-    const trimmed = input.trim();
-    if (trimmed.length === 0 || trimmed.length > 500)
-        return false;
-    // Strong patterns: direct correction language — fire immediately.
-    if (PUSHBACK_STRONG.some((re) => re.test(trimmed)))
-        return true;
-    // Weak patterns: only count if the message is short (< 120 chars) AND doesn't
-    // also contain a fresh request. A weak starter followed by "can you also X"
-    // or "please do Y" is scope addition, not correction.
-    if (PUSHBACK_WEAK.some((re) => re.test(trimmed))) {
-        if (trimmed.length > 120)
-            return false;
-        if (/\b(can you|could you|please|also|add|include)\b/i.test(trimmed))
-            return false;
-        return true;
-    }
-    return false;
-}
+// Formerly a pair of regex lists (PUSHBACK_STRONG / PUSHBACK_WEAK) plus a
+// claim-on-prior-turn check — ~70 lines of keyword heuristics. Replaced by
+// `turnAnalysis.isPushback` from `turn-analyzer.ts` (v3.8.27): the free
+// classifier reads the user's actual phrasing AND the prior assistant
+// reply and decides whether this turn is a correction. Zero keyword
+// allowlist, works across languages and phrasings the regex never covered.
 /**
  * Sanitize history: fix orphaned tool results AND inject missing results.
  *
@@ -456,20 +391,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     input = cmdResult.rewritten;
             }
         }
-        // ── Pushback detection ──
-        // When the user corrects us ("no", "but", "actually", "wrong"), we must throw
-        // away the previous plan and reconsider — not continue the failing approach.
-        // Without this signal, cheap models tend to plough forward with the same bad idea.
-        const pushbackSignal = detectPushback(input, history);
-        const effectiveInput = pushbackSignal
-            ? `${input}\n\n[SYSTEM NOTE] The user is correcting you. Your previous response was wrong or off-target. Do NOT continue the previous approach. Re-read the conversation, identify what specifically the user is correcting, and change your strategy. If the user pointed out a fact (e.g. "we are using X"), treat that fact as ground truth and rebuild your answer around it.`
-            : input;
         lastUserInput = input;
-        history.push({ role: 'user', content: effectiveInput });
+        // Push the user's clean message; any harness-injected annotations
+        // (pushback SYSTEM NOTE, prefetch context block) are applied AFTER
+        // the turn analyzer runs so they get driven by model-decided flags
+        // instead of keyword regex.
+        history.push({ role: 'user', content: input });
         turnCount++;
         toolGuard.startTurn();
-        // Persist the user's original message, not the injected SYSTEM NOTE scaffold.
-        // Resumed sessions should show what the user typed, not our internal prompt engineering.
         persistSessionMessage({ role: 'user', content: input });
         // ── Model recovery: try original model at the start of each new turn ──
         // If we fell back to a free model last turn due to a transient error, try original again.
@@ -595,6 +524,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         catch {
             // Analyzer is best-effort; ignore.
         }
+        // ── Pushback annotation ─────────────────────────────────────────
+        // If the analyzer judged this turn as a user correction of the
+        // previous answer, inject a SYSTEM NOTE into the user message so the
+        // model resets its approach rather than doubling down. Replaces the
+        // former PUSHBACK_STRONG / PUSHBACK_WEAK regex lists — model-decided,
+        // no keyword allowlist to rot.
+        if (turnAnalysis?.isPushback) {
+            const lastIdx = history.length - 1;
+            const last = history[lastIdx];
+            if (last && last.role === 'user' && typeof last.content === 'string') {
+                history[lastIdx] = {
+                    role: 'user',
+                    content: `${last.content}\n\n[SYSTEM NOTE] The user is correcting you. Your previous response was wrong or off-target. Do NOT continue the previous approach. Re-read the conversation, identify what specifically the user is correcting, and change your strategy. If the user pointed out a fact (e.g. "we are using X"), treat that fact as ground truth and rebuild your answer around it.`,
+                };
+            }
+        }
         // ── Proactive prefetch ────────────────────────────────────────────
         // Uses the intent the analyzer already extracted. Skips the separate
         // prefetch-classifier call that previously ran here.
@@ -773,8 +718,12 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // Update token estimation model for more accurate byte-per-token ratio
             setEstimationModel(resolvedModel);
             // ── Plan-then-execute: detect and activate ──
+            // `needsPlanning` flag comes from turn-analyzer (one-word LLM decision
+            // on the user's original prompt). shouldPlan still guards env / profile /
+            // ultrathink / per-session overrides — those are operator policy, not
+            // model decisions.
             if (loopCount === 1 && !planActive && routingProfile &&
-                shouldPlan(routingTier, routingProfile, lastUserInput, !!config.ultrathink, !!config.planDisabled)) {
+                shouldPlan(routingProfile, !!config.ultrathink, !!config.planDisabled, turnAnalysis?.needsPlanning ?? false)) {
                 planActive = true;
                 planPlannerModel = resolvedModel;
                 planExecutorModel = getExecutorModel(routingProfile);

package/dist/agent/planner.d.ts

@@ -7,13 +7,19 @@
  * Flow: detect complexity → plan with strong model → execute with cheap model
  *       → escalate back to strong model if executor gets stuck
  */
-import type { Tier, RoutingProfile } from '../router/index.js';
+import type { RoutingProfile } from '../router/index.js';
 /**
  * Should this task use plan-then-execute?
- * Returns true only for complex, multi-step tasks where the savings justify
- * the overhead of an extra planning call.
+ *
+ * Replaces the former AGENTIC_KEYWORDS / MULTI_STEP_PATTERN regex heuristics
+ * with a single read of `turnAnalysis.needsPlanning`. The free model judged
+ * whether the task is substantive-multi-step from the user's actual phrasing,
+ * no keyword allowlist to maintain.
+ *
+ * Environment gates (opt-in / opt-out / profile / ultrathink / session
+ * override) remain — those are operator decisions, not model decisions.
  */
-export declare function shouldPlan(tier: Tier | undefined, profile: RoutingProfile | undefined, userText: string, ultrathink: boolean, planDisabled: boolean): boolean;
+export declare function shouldPlan(profile: RoutingProfile | undefined, ultrathink: boolean, planDisabled: boolean, analyzerSaysNeedsPlanning: boolean): boolean;
 /**
  * Returns the planning system prompt section.
  * Injected alongside the normal system prompt during the planning call.

package/dist/agent/planner.js

@@ -7,53 +7,38 @@
  * Flow: detect complexity → plan with strong model → execute with cheap model
  *       → escalate back to strong model if executor gets stuck
  */
-// ─── Agentic keywords that suggest multi-step work ───────────────────────
-const AGENTIC_KEYWORDS = /\b(implement|refactor|build|fix|debug|migrate|deploy|create|add|remove|update|restructure|extract|rewrite|optimize|convert|integrate|setup|configure)\b/i;
-const MULTI_STEP_PATTERN = /first.*then|step\s+\d|\d+\.\s|and\s+then|after\s+that|next\s*,|finally\b/i;
 // ─── Detection ───────────────────────────────────────────────────────────
 /**
  * Should this task use plan-then-execute?
- * Returns true only for complex, multi-step tasks where the savings justify
- * the overhead of an extra planning call.
+ *
+ * Replaces the former AGENTIC_KEYWORDS / MULTI_STEP_PATTERN regex heuristics
+ * with a single read of `turnAnalysis.needsPlanning`. The free model judged
+ * whether the task is substantive-multi-step from the user's actual phrasing,
+ * no keyword allowlist to maintain.
+ *
+ * Environment gates (opt-in / opt-out / profile / ultrathink / session
+ * override) remain — those are operator decisions, not model decisions.
  */
-export function shouldPlan(tier, profile, userText, ultrathink, planDisabled) {
-    // Default: plan-then-execute is OFF (v3.8.18). Observed failure: router
-    // correctly picks Sonnet for a "should I sell CRCL" prompt, but the
-    // executor swap downgrades actual execution to gemini-2.5-flash, which
-    // then answers from memory instead of calling TradingMarket / ExaAnswer.
-    // The cheap-executor pattern was load-bearing for Sonnet 4.0-era models;
-    // Opus 4.7 / Sonnet 4.6 handle multi-step tool use coherently in a
-    // single pass, so the two-call path is pure overhead — and it actively
-    // hurts when the executor is weaker than the planner.
-    // Opt back in with FRANKLIN_PLAN=1 (for experiments / ablation).
+export function shouldPlan(profile, ultrathink, planDisabled, analyzerSaysNeedsPlanning) {
+    // Default: plan-then-execute is OFF (since v3.8.18). The cheap-executor
+    // pattern was load-bearing for Sonnet-4.0-era models but Opus 4.7 /
+    // Sonnet 4.6 handle multi-step tool use in a single pass. Opt in with
+    // FRANKLIN_PLAN=1 for ablation / experiments.
     if (process.env.FRANKLIN_PLAN !== '1')
         return false;
-    // Legacy env opt-out — still honored for users who set it previously.
+    // Legacy env opt-out still honored for users who set it previously.
     if (process.env.FRANKLIN_NOPLAN === '1')
         return false;
-    // User disabled planning for this session
+    // Per-session / per-turn overrides from the agent surface.
     if (planDisabled)
         return false;
-    // Ultrathink already provides deep reasoning
     if (ultrathink)
-        return false;
-    // Only auto or premium profiles (eco/free are cost-constrained)
+        return false; // ultrathink already provides deep reasoning
+    // Only auto / premium profiles — eco / free are cost-constrained.
     if (profile !== 'auto' && profile !== 'premium')
         return false;
-    // Explicit multi-step language always plans, regardless of tier / length
-    // ("first ... then ...", "step 1 ... step 2 ...", numbered lists, etc.)
-    if (MULTI_STEP_PATTERN.test(userText))
-        return true;
-    // Planning is high-ROI on COMPLEX / REASONING tiers for agentic verbs,
-    // even when the prompt is short ("refactor the wallet module", "migrate to TS")
-    if (tier === 'COMPLEX' || tier === 'REASONING') {
-        return AGENTIC_KEYWORDS.test(userText) || userText.length >= 60;
-    }
-    // On MEDIUM tier: plan only if long AND agentic
-    if (tier === 'MEDIUM' && userText.length >= 120 && AGENTIC_KEYWORDS.test(userText)) {
-        return true;
-    }
-    return false;
+    // Final decision comes from the turn analyzer's boolean flag.
+    return analyzerSaysNeedsPlanning;
 }
 // ─── Planning Prompt ─────────────────────────────────────────────────────
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.8.27",
+  "version": "3.8.28",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {