@blockrun/franklin 3.15.8 → 3.15.10

package/dist/agent/error-classifier.js

@@ -111,6 +111,28 @@ export function classifyAgentError(message) {
             suggestion: 'The model is overloaded. Try /model to switch, or wait and /retry.',
         };
     }
+    // Reasoning / thinking-mode format errors — NOT transient.
+    // DeepSeek V4 family and similar thinking-enabled models reject requests
+    // when the message history's reasoning_content fields don't match the
+    // upstream's expected shape (typically: tool-call assistant messages must
+    // carry reasoning_content; non-tool-call ones must not, or vice versa).
+    // The fix is to drop the polluting history, not to swap models — every
+    // thinking-enabled model has the same constraint just with different
+    // specifics. /clear forces a fresh context that won't have the bad shape.
+    // Classified BEFORE the generic schema branch below so we surface the
+    // right suggestion.
+    if (includesAny(err, [
+        'reasoning_content',
+        'reasoning content',
+        'thinking mode must',
+        'message format incompatible',
+        'reasoning_format_error',
+    ])) {
+        return {
+            category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+            suggestion: 'Thinking-mode history is incompatible with this model. Use /clear to reset and retry, or /model to switch to a non-thinking model.',
+        };
+    }
     // Schema / tool-definition errors — NOT transient, retrying won't help.
     // These can be wrapped in 5xx responses (e.g. '503: 400 Invalid schema'),
     // so classify them BEFORE the generic server-error branch below.

package/dist/agent/evaluator.js

@@ -65,9 +65,36 @@ Flag as tool-use refusal:
 
 VERDICT: GROUNDED | PARTIAL | UNGROUNDED
 
-If not GROUNDED, list each issue on its own line starting with "- " and the tool that should have been called, like:
-- Claim: "<the ungrounded part, quoted briefly>" → missing tool: <TradingMarket | ExaAnswer | ExaSearch | WebSearch | ...>
-- Refusal: "<the refusal phrase, quoted briefly>" → should have called: <tool name>
+If not GROUNDED, list each issue on its own line starting with "- " and the tool that should have been called.
+
+## Picking the right tool — strict domain rules
+
+**Default for any factual claim:** WebSearch or ExaSearch. These are the
+right answer for the OVERWHELMING majority of "the model said a number it
+didn't look up" cases — current events, statistics, prices for non-crypto
+goods (real estate, retail, salaries), people, companies, news, etc.
+
+**Use specialized tools ONLY when the claim's domain matches:**
+- TradingMarket / TradingSignal — ONLY for cryptocurrency tickers (BTC, ETH, SOL, etc). Never for stocks, real estate, currencies, commodities outside crypto.
+- DefiLlamaProtocol / DefiLlamaYields / DefiLlamaPrice — ONLY for DeFi protocols, TVL, yields, on-chain token prices.
+- SearchX — ONLY for X.com / Twitter posts and accounts.
+- ExaAnswer — research questions where you want a synthesized answer with citations.
+- WebFetch — claims that quote a SPECIFIC URL the model already named.
+
+**Anti-patterns to never produce:**
+- Real-estate price → TradingMarket (TradingMarket is crypto-only — wrong domain)
+- Stock ticker → TradingMarket (also crypto-only — use WebSearch instead)
+- Generic news / statistics → TradingMarket (use WebSearch)
+- Person's biography → TradingMarket (use WebSearch)
+
+When unsure: name **WebSearch**. It's the safe default for factual grounding.
+
+## Format examples
+
+- Claim: "<the ungrounded part, quoted briefly>" → missing tool: WebSearch
+- Claim: "BTC at $67k" → missing tool: TradingMarket
+- Claim: "Westlake $/sqft is $719" → missing tool: WebSearch
+- Refusal: "<the refusal phrase, quoted briefly>" → should have called: WebSearch
 
 Empty line between verdict and list. No other text. No preamble. No apology. Be terse.`;
 // ─── Trigger policy ──────────────────────────────────────────────────────

package/dist/agent/loop.js

@@ -8,6 +8,7 @@ import { estimateHistoryTokens, updateActualTokens, resetTokenAnchor, getAnchore
 import { handleSlashCommand } from './commands.js';
 import { loadBundledSkills, getSkillVars } from '../skills/bootstrap.js';
 import { reduceTokens } from './reduce.js';
+import { redactSecrets, stashSecretsToEnv, formatRedactionWarning } from './secret-redact.js';
 import { PermissionManager } from './permissions.js';
 import { StreamingExecutor } from './streaming-executor.js';
 import { optimizeHistory, CAPPED_MAX_TOKENS, ESCALATED_MAX_TOKENS, getMaxOutputTokens } from './optimize.js';
@@ -241,6 +242,39 @@ export function looksLikeGatewayErrorAsText(parts) {
         return { match: false, message: '' };
     return { match: true, message: m[1].trim() };
 }
+/**
+ * Domain check for the grounding-retry force-tool path. A specialized tool
+ * (TradingMarket, DefiLlama*, jupiter*, base0x*, SearchX) should only be
+ * pinned by tool_choice when the user prompt actually references that
+ * tool's domain — otherwise we let the smart generator pick from any tool.
+ *
+ * The motivating bug: a real-estate question ("可以还价 20% 吗") had its
+ * answer flagged as ungrounded for citing $/sqft figures. The cheap
+ * evaluator model picked TradingMarket as the missing tool because it
+ * was the first example in the evaluator prompt. Forcing TradingMarket
+ * (a crypto-only tool) on a housing question made the retry useless.
+ *
+ * This function returns false for specialized tools when the prompt has
+ * no matching domain keywords; the caller falls back to "any" tool.
+ * General-purpose tools (WebSearch, ExaSearch, ExaAnswer, WebFetch,
+ * ExaReadUrls) always pass — they're domain-agnostic.
+ */
+function isToolRelevantToPrompt(toolName, promptLower) {
+    // Crypto trading tools — need a ticker, "crypto", "coin", "swap", etc.
+    if (/^(Trading|DefiLlama|Jupiter|Base0x|Base0xGasless)/i.test(toolName)) {
+        return /\b(btc|eth|sol|xrp|doge|usdc|usdt|crypto|coin|token|defi|tvl|yield|swap|jupiter|uniswap|pump\.fun|solana|base chain|polygon|ethereum|币|代币|链上|做空|做多)\b/i.test(promptLower);
+    }
+    // X.com search — need an @handle, "twitter", "tweet", "X.com"
+    if (/^SearchX$/i.test(toolName) || /^PostToX$/i.test(toolName)) {
+        return /(@\w+|twitter|x\.com|tweet|推特)/i.test(promptLower);
+    }
+    // Image / video / music gen — need a creative-content request
+    if (/^(ImageGen|VideoGen|MusicGen)$/i.test(toolName)) {
+        return /\b(image|picture|photo|video|clip|music|song|generate|create|render|draw|画|图|视频|音乐|歌)\b/i.test(promptLower);
+    }
+    // General-purpose / file / shell tools — always relevant.
+    return true;
+}
 /**
  * Calculate backoff delay with jitter to avoid thundering herd.
  * Base: exponential (2^attempt * 1000ms), jitter: ±25%.
@@ -443,6 +477,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     input = cmdResult.rewritten;
             }
         }
+        // ── Secret redaction at the input boundary ──
+        // Catch GitHub PATs / API keys / private keys before they enter
+        // history, get persisted, or hit the model. Detected values are
+        // stashed on process.env (predictable name like GITHUB_TOKEN) so
+        // subsequent Bash tool calls can still use them via `$GITHUB_TOKEN`
+        // — the user keeps the convenience of "remember this credential"
+        // without the chat-history exposure that just happened.
+        const { redactedText, matches: secretMatches } = redactSecrets(input);
+        if (secretMatches.length > 0) {
+            const envVarsSet = stashSecretsToEnv(secretMatches);
+            onEvent({
+                kind: 'text_delta',
+                text: formatRedactionWarning(secretMatches, envVarsSet),
+            });
+            input = redactedText;
+        }
         lastUserInput = input;
         // Push the user's clean message; any harness-injected annotations
         // (pushback SYSTEM NOTE, prefetch context block) are applied AFTER
@@ -1349,11 +1399,23 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             // Hard enforcement: set tool_choice so the model can't fabricate
                             // citations in lieu of running tools (the round-2 failure mode
                             // from the Tampa→Miami log). If the evaluator named exactly one
-                            // available tool, pin to it; otherwise force "any" tool use.
+                            // available tool AND that tool's domain matches the user's
+                            // prompt, pin to it; otherwise force "any" tool use and let
+                            // the generator pick the right one.
+                            //
+                            // Domain validation guards against the cheap evaluator model
+                            // hallucinating a wrong specialized tool (e.g., suggesting
+                            // TradingMarket for a real-estate question because the prompt
+                            // listed it as the first example tool). Specialized tools —
+                            // crypto trading, DeFi, swap quotes, X.com search — only get
+                            // pinned when their domain keywords appear in the user prompt;
+                            // otherwise we drop down to "any tool" and let the smart
+                            // generator model decide based on tool descriptions.
                             const namedTools = extractMissingToolNames(gResult);
                             const availableNames = new Set(buildCallToolDefs().map(t => t.name));
                             const matched = namedTools.filter(n => availableNames.has(n));
-                            if (matched.length === 1) {
+                            const promptForDomainCheck = (lastUserInput || '').toLowerCase();
+                            if (matched.length === 1 && isToolRelevantToPrompt(matched[0], promptForDomainCheck)) {
                                 forceToolChoiceNextRound = { type: 'tool', name: matched[0] };
                             }
                             else if (availableNames.size > 0) {

package/dist/agent/secret-redact.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Secret detection + redaction for user-submitted text.
+ *
+ * Why this exists: a user pasted a GitHub PAT (`ghp_...`) directly into
+ * chat as a way to give Franklin authenticated access to the GitHub API.
+ * The model correctly refused to use the raw value and warned the user,
+ * but by then the token had already entered:
+ *   - the LLM API request body (sent to the gateway + upstream provider)
+ *   - the persisted session file on disk
+ *   - any later compaction summary (which would re-send it to the model)
+ *
+ * What the user actually wants is for Franklin to **remember the credential
+ * and keep using it**, not refuse it. So this module's job is two-fold:
+ *
+ *   1. Strip the raw value out of the conversation so it never reaches
+ *      the model, history, or disk.
+ *   2. Stash it on `process.env` under a predictable name so subsequent
+ *      Bash / WebFetch tool calls can reference it via `$GITHUB_TOKEN`,
+ *      `$ANTHROPIC_API_KEY`, etc. — no chat round-trip needed.
+ *
+ * Conservative pattern set: each entry matches a token format with an
+ * unambiguous prefix + length, so false positives are rare. Anything that
+ * could plausibly be a normal long string (random hex, base64 blobs) is
+ * deliberately not in here. False positives are worse than missed
+ * detections — silently mangling a hex hash a user pasted would be
+ * confusing and there's no recovery path.
+ */
+export interface RedactionMatch {
+    label: string;
+    description: string;
+    /** First 4 chars of the secret + ellipsis — for user-facing display. */
+    preview: string;
+    /** Suggested env var name (e.g. GITHUB_TOKEN). */
+    envVar: string;
+    /** The actual secret value. INTERNAL USE ONLY — never log this. */
+    value: string;
+}
+export interface RedactionResult {
+    /** Input with each secret replaced by [REDACTED:label]. */
+    redactedText: string;
+    /** What got redacted. Includes raw `value` for the caller to stash. */
+    matches: RedactionMatch[];
+}
+/**
+ * Scan `input` for secret patterns and return a redacted copy plus a
+ * description of what was caught. Secrets are replaced with the literal
+ * string `[REDACTED:<label>]` so the model can still see *something* was
+ * there (helpful when the user's message refers to the token in context),
+ * just not the value.
+ *
+ * No I/O, no logging — pure transformation. The caller decides how to
+ * surface the warning to the user and whether to stash values on
+ * process.env (recommended for CLI usage so Bash tool calls can reference
+ * $GITHUB_TOKEN etc).
+ */
+export declare function redactSecrets(input: string): RedactionResult;
+/**
+ * Stash matched secrets onto `process.env` so subsequent tool calls
+ * (Bash, WebFetch with `$GITHUB_TOKEN`-style references) can use them
+ * without the value ever round-tripping through chat history.
+ *
+ * Returns the names of env vars that were set, deduped, in stash order.
+ * Safe to call on an empty match list (no-op).
+ */
+export declare function stashSecretsToEnv(matches: RedactionMatch[]): string[];
+/**
+ * Build a one-paragraph warning + usage hint to surface to the user when
+ * their input had secrets redacted and stashed. Names what was caught
+ * (with previews, never values) and tells them how to actually use the
+ * stashed credential going forward.
+ */
+export declare function formatRedactionWarning(matches: RedactionMatch[], envVarsSet: string[]): string;

package/dist/agent/secret-redact.js

@@ -0,0 +1,240 @@
+/**
+ * Secret detection + redaction for user-submitted text.
+ *
+ * Why this exists: a user pasted a GitHub PAT (`ghp_...`) directly into
+ * chat as a way to give Franklin authenticated access to the GitHub API.
+ * The model correctly refused to use the raw value and warned the user,
+ * but by then the token had already entered:
+ *   - the LLM API request body (sent to the gateway + upstream provider)
+ *   - the persisted session file on disk
+ *   - any later compaction summary (which would re-send it to the model)
+ *
+ * What the user actually wants is for Franklin to **remember the credential
+ * and keep using it**, not refuse it. So this module's job is two-fold:
+ *
+ *   1. Strip the raw value out of the conversation so it never reaches
+ *      the model, history, or disk.
+ *   2. Stash it on `process.env` under a predictable name so subsequent
+ *      Bash / WebFetch tool calls can reference it via `$GITHUB_TOKEN`,
+ *      `$ANTHROPIC_API_KEY`, etc. — no chat round-trip needed.
+ *
+ * Conservative pattern set: each entry matches a token format with an
+ * unambiguous prefix + length, so false positives are rare. Anything that
+ * could plausibly be a normal long string (random hex, base64 blobs) is
+ * deliberately not in here. False positives are worse than missed
+ * detections — silently mangling a hex hash a user pasted would be
+ * confusing and there's no recovery path.
+ */
+const SECRET_PATTERNS = [
+    // ── GitHub ──
+    // Personal access tokens, OAuth tokens, app installation/user-to-server
+    // tokens, fine-grained PATs. All have unique prefixes the user can verify.
+    {
+        label: 'github_pat',
+        pattern: /\bghp_[A-Za-z0-9]{36,}\b/g,
+        description: 'GitHub personal access token',
+        envVar: 'GITHUB_TOKEN',
+    },
+    {
+        label: 'github_oauth',
+        pattern: /\bgho_[A-Za-z0-9]{36,}\b/g,
+        description: 'GitHub OAuth token',
+        envVar: 'GITHUB_TOKEN',
+    },
+    {
+        label: 'github_app',
+        pattern: /\bghs_[A-Za-z0-9]{36,}\b/g,
+        description: 'GitHub App installation token',
+        envVar: 'GITHUB_TOKEN',
+    },
+    {
+        label: 'github_user',
+        pattern: /\bghu_[A-Za-z0-9]{36,}\b/g,
+        description: 'GitHub user-to-server token',
+        envVar: 'GITHUB_TOKEN',
+    },
+    {
+        label: 'github_pat_fine',
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g,
+        description: 'GitHub fine-grained PAT',
+        envVar: 'GITHUB_TOKEN',
+    },
+    // ── Anthropic ──
+    {
+        label: 'anthropic_api',
+        pattern: /\bsk-ant-(?:api|admin)\d+-[A-Za-z0-9_-]{20,}\b/g,
+        description: 'Anthropic API key',
+        envVar: 'ANTHROPIC_API_KEY',
+    },
+    // ── OpenAI ──
+    // sk-proj- (project keys, current format) is unambiguous. The legacy
+    // `sk-` + 48 chars format is more ambiguous so we require ≥48 chars to
+    // avoid clashing with normal short hex strings.
+    {
+        label: 'openai_project',
+        pattern: /\bsk-proj-[A-Za-z0-9_-]{40,}\b/g,
+        description: 'OpenAI project API key',
+        envVar: 'OPENAI_API_KEY',
+    },
+    {
+        label: 'openai_api',
+        pattern: /\bsk-[A-Za-z0-9]{48,}\b/g,
+        description: 'OpenAI API key',
+        envVar: 'OPENAI_API_KEY',
+    },
+    // ── AWS ──
+    {
+        label: 'aws_access_key',
+        pattern: /\bAKIA[0-9A-Z]{16}\b/g,
+        description: 'AWS access key ID',
+        envVar: 'AWS_ACCESS_KEY_ID',
+    },
+    // AWS secret keys are 40 base64 chars but have no prefix — too ambiguous
+    // to match safely. Skipped on purpose.
+    // ── Google ──
+    {
+        label: 'google_api',
+        pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+        description: 'Google Cloud / Firebase API key',
+        envVar: 'GOOGLE_API_KEY',
+    },
+    // ── Slack ──
+    {
+        label: 'slack_token',
+        pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+        description: 'Slack token',
+        envVar: 'SLACK_TOKEN',
+    },
+    // ── Stripe ──
+    {
+        label: 'stripe_live',
+        pattern: /\bsk_live_[A-Za-z0-9]{20,}\b/g,
+        description: 'Stripe live secret key',
+        envVar: 'STRIPE_SECRET_KEY',
+    },
+    {
+        label: 'stripe_test',
+        pattern: /\bsk_test_[A-Za-z0-9]{20,}\b/g,
+        description: 'Stripe test secret key',
+        envVar: 'STRIPE_SECRET_KEY',
+    },
+    // ── Twilio ──
+    {
+        label: 'twilio_account',
+        pattern: /\bAC[a-f0-9]{32}\b/g,
+        description: 'Twilio account SID',
+        envVar: 'TWILIO_ACCOUNT_SID',
+    },
+    // ── Private keys ──
+    // Multi-line PEM blocks. Match begin/end markers + content. envVar:
+    // PRIVATE_KEY is generic — if a user has multiple they'll need to rename.
+    {
+        label: 'private_key',
+        pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |PGP )?PRIVATE KEY-----/g,
+        description: 'PEM private key',
+        envVar: 'PRIVATE_KEY',
+    },
+    // ── Cryptocurrency private keys ──
+    // 64-char hex strings preceded by an obvious key context. Standalone hex
+    // strings are too ambiguous (could be hashes) to redact silently.
+    {
+        label: 'eth_private_key',
+        pattern: /\b(?:private[_\s-]?key|priv[_\s-]?key|secret[_\s-]?key)\s*[:=]\s*0x[a-fA-F0-9]{64}\b/gi,
+        description: 'Ethereum-style private key',
+        envVar: 'WALLET_PRIVATE_KEY',
+    },
+];
+/**
+ * Scan `input` for secret patterns and return a redacted copy plus a
+ * description of what was caught. Secrets are replaced with the literal
+ * string `[REDACTED:<label>]` so the model can still see *something* was
+ * there (helpful when the user's message refers to the token in context),
+ * just not the value.
+ *
+ * No I/O, no logging — pure transformation. The caller decides how to
+ * surface the warning to the user and whether to stash values on
+ * process.env (recommended for CLI usage so Bash tool calls can reference
+ * $GITHUB_TOKEN etc).
+ */
+export function redactSecrets(input) {
+    let redactedText = input;
+    const matches = [];
+    // Dedupe by exact value, not by label — a user might paste two distinct
+    // GitHub tokens and we should preserve both for the env-var stash even
+    // though the description would read identically.
+    const seenValues = new Set();
+    for (const { label, pattern, description, envVar } of SECRET_PATTERNS) {
+        // Reset lastIndex on each pattern — RegExp objects with /g preserve it
+        // across calls, which would skip matches if the same regex were reused.
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(input)) !== null) {
+            const secret = match[0];
+            if (seenValues.has(secret))
+                continue;
+            seenValues.add(secret);
+            matches.push({
+                label,
+                description,
+                preview: secret.slice(0, 4) + '…',
+                envVar,
+                value: secret,
+            });
+            // Replace every occurrence of this exact secret in redactedText.
+            // Using the literal secret as a search string handles the common
+            // case where the same token appears multiple times in one message.
+            redactedText = redactedText.split(secret).join(`[REDACTED:${label}]`);
+        }
+    }
+    return { redactedText, matches };
+}
+/**
+ * Stash matched secrets onto `process.env` so subsequent tool calls
+ * (Bash, WebFetch with `$GITHUB_TOKEN`-style references) can use them
+ * without the value ever round-tripping through chat history.
+ *
+ * Returns the names of env vars that were set, deduped, in stash order.
+ * Safe to call on an empty match list (no-op).
+ */
+export function stashSecretsToEnv(matches) {
+    const set = [];
+    for (const m of matches) {
+        // Don't clobber an env var the user has already exported in their
+        // shell — their existing value is presumably the right one and
+        // accidentally overwriting it could cause silent breakage.
+        if (process.env[m.envVar] && process.env[m.envVar] !== m.value) {
+            continue;
+        }
+        process.env[m.envVar] = m.value;
+        if (!set.includes(m.envVar))
+            set.push(m.envVar);
+    }
+    return set;
+}
+/**
+ * Build a one-paragraph warning + usage hint to surface to the user when
+ * their input had secrets redacted and stashed. Names what was caught
+ * (with previews, never values) and tells them how to actually use the
+ * stashed credential going forward.
+ */
+export function formatRedactionWarning(matches, envVarsSet) {
+    if (matches.length === 0)
+        return '';
+    const list = matches
+        .map((m) => `• ${m.description} (${m.preview}) → \`$${m.envVar}\``)
+        .join('\n');
+    const skipped = matches.length - envVarsSet.length;
+    const skippedNote = skipped > 0
+        ? `\n_(${skipped} value${skipped === 1 ? '' : 's'} not stashed because the env var was already set in your shell — your existing export is preserved.)_`
+        : '';
+    return (`\n⚠️ **Secret detected, redacted from chat, and stashed for this session.**\n` +
+        `${list}${skippedNote}\n\n` +
+        `The raw value never reached the model, the conversation history, or the session file. ` +
+        `Tool calls (Bash / WebFetch) can use the env var name — for example: ` +
+        `\`gh api user --header "Authorization: Bearer $GITHUB_TOKEN"\`.\n\n` +
+        `**This still counts as exposed.** Anything you typed is in your terminal scrollback, ` +
+        `and any prior session file may have captured it before this redaction was added. ` +
+        `Treat the secret as compromised and rotate it now.\n\n` +
+        `Next time, set the credential via shell export before launching Franklin ` +
+        `(\`export GITHUB_TOKEN=...\`) instead of pasting it into chat.\n`);
+}

package/package.json

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