@blockrun/franklin 3.7.10 → 3.8.1

package/dist/agent/bash-guard.js

@@ -30,8 +30,14 @@ const DANGEROUS_PATTERNS = [
     [/\bTRUNCATE\s+TABLE\b/i, 'truncate table'],
     // System-level danger
     [/\bchmod\s+(-R\s+)?777\b/, 'world-writable permissions'],
-    [/\bcurl\s+.*\|\s*(sudo\s+)?(ba)?sh\b/, 'pipe URL to shell'],
-    [/\bwget\s+.*\|\s*(sudo\s+)?(ba)?sh\b/, 'pipe URL to shell'],
+    // Pipe-to-shell: catch sudo/env prefixes and common shell variants (bash/sh/zsh/ksh/dash/fish).
+    // The optional `-e`/`-x` flags after the shell binary are intentionally allowed by \b;
+    // what we block is the routing of downloaded content into an interpreter.
+    [/\bcurl\s+.*\|\s*(sudo\s+)?(env\s+\S*\s*)?(ba|z|k|da|fi)?sh\b/, 'pipe URL to shell'],
+    [/\bwget\s+.*\|\s*(sudo\s+)?(env\s+\S*\s*)?(ba|z|k|da|fi)?sh\b/, 'pipe URL to shell'],
+    // Command substitution of a downloader into argv — `$(curl …)` or `` `curl …` ``.
+    [/\$\(\s*(curl|wget|fetch)\b/, 'command substitution of network downloader'],
+    [/`\s*(curl|wget|fetch)\b[^`]*`/, 'backtick substitution of network downloader'],
     [/\bsudo\s+rm\b/, 'sudo delete'],
     // Kill/shutdown
     [/\bkill\s+-9\s+-1\b/, 'kill all processes'],

package/dist/agent/compact.d.ts

@@ -5,6 +5,20 @@
  */
 import { ModelClient } from './llm.js';
 import type { Dialogue } from './types.js';
+/**
+ * Decide whether compacting is worth the round-trip. Pure function so tests
+ * can pin behavior at specific history shapes without spinning up a client.
+ *
+ * Returns `{ worthIt, currentTokens, projectedTokens, savings }`. Caller
+ * can log the numbers or just branch on `worthIt`.
+ */
+export declare function projectCompactionSavings(history: Dialogue[]): {
+    worthIt: boolean;
+    currentTokens: number;
+    projectedTokens: number;
+    savings: number;
+    floor: number;
+};
 export declare const COMPACT_HEADER = "[CONTEXT COMPACTION \u2014 REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window \u2014 treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Respond ONLY to the latest user message that appears AFTER this summary.";
 /**
  * Check if compaction is needed and perform it if so.

package/dist/agent/compact.js

@@ -9,6 +9,47 @@ import { estimateHistoryTokens, getCompactionThreshold, COMPACTION_SUMMARY_RESER
 const POST_COMPACT_MAX_FILES = 5;
 /** Max tokens to spend on post-compact file restoration */
 const POST_COMPACT_TOKEN_BUDGET = 50_000;
+/**
+ * Minimum projected fraction of total history tokens that compaction must
+ * save to be worth the round-trip. Summarization itself costs roughly
+ * the input payload tokens (read once by the compaction model) plus the
+ * ~16k reserved for the output. If the payload we'd summarize is small
+ * relative to what we'd keep, we pay the full cost for marginal relief.
+ * 0.20 = skip compaction unless projected savings clear 20% of total tokens.
+ * This only applies to autoCompactIfNeeded; /compact (forceCompact) still
+ * runs unconditionally because the user asked for it.
+ */
+const MIN_COMPACTION_SAVINGS_RATIO = 0.20;
+/**
+ * Rough upper bound on how many tokens the summary itself will occupy in
+ * the new history. The model is asked for up to COMPACTION_SUMMARY_RESERVE,
+ * but in practice structured summaries land well under that; be optimistic
+ * on the expected case, pessimistic on the safety margin.
+ */
+const EXPECTED_SUMMARY_TOKENS = 4_000;
+/**
+ * Decide whether compacting is worth the round-trip. Pure function so tests
+ * can pin behavior at specific history shapes without spinning up a client.
+ *
+ * Returns `{ worthIt, currentTokens, projectedTokens, savings }`. Caller
+ * can log the numbers or just branch on `worthIt`.
+ */
+export function projectCompactionSavings(history) {
+    const currentTokens = estimateHistoryTokens(history);
+    const keepCount = findKeepBoundary(history);
+    const toKeep = history.slice(history.length - keepCount);
+    const keptTokens = estimateHistoryTokens(toKeep);
+    const projectedTokens = keptTokens + EXPECTED_SUMMARY_TOKENS;
+    const savings = currentTokens - projectedTokens;
+    const floor = Math.ceil(currentTokens * MIN_COMPACTION_SAVINGS_RATIO);
+    return {
+        worthIt: savings >= floor,
+        currentTokens,
+        projectedTokens,
+        savings,
+        floor,
+    };
+}
 // Structured compaction prompt (pattern from nousresearch/hermes-agent
 // `agent/context_compressor.py`). The structured sections preserve more
 // signal than free-form summaries and make it easier for the model to
@@ -71,8 +112,23 @@ export async function autoCompactIfNeeded(history, model, client, debug) {
     if (currentTokens < threshold) {
         return { history, compacted: false };
     }
+    // ROI gate: project how much the summarization would actually save. The
+    // portion that survives compaction (`toKeep`) doesn't shrink, and the
+    // summary replaces `toSummarize` with ~EXPECTED_SUMMARY_TOKENS. If the
+    // resulting history is within MIN_COMPACTION_SAVINGS_RATIO of the current
+    // size, skip — the round-trip would cost more than the headroom is worth.
+    // The caller then falls back to per-turn emergency handling (413 recovery,
+    // output-tokens clamp) which is much cheaper on the margin.
+    const roi = projectCompactionSavings(history);
+    if (!roi.worthIt) {
+        if (debug) {
+            console.error(`[franklin] Compaction skipped (ROI): current=${roi.currentTokens}, projected=${roi.projectedTokens}, ` +
+                `savings=${roi.savings} < ${roi.floor} floor`);
+        }
+        return { history, compacted: false };
+    }
     if (debug) {
-        console.error(`[franklin] Auto-compacting: ~${currentTokens} tokens, threshold=${threshold}`);
+        console.error(`[franklin] Auto-compacting: ~${currentTokens} tokens, threshold=${threshold}, projected savings=${roi.savings}`);
     }
     const beforeTokens = estimateHistoryTokens(history);
     try {

package/dist/agent/context.js

@@ -463,8 +463,10 @@ function readRuntimeWallet() {
 }
 // ─── Git Context ───────────────────────────────────────────────────────────
 const GIT_TIMEOUT_MS = 5_000;
-// Max chars for git log output — long commit messages can bloat the system prompt
-const MAX_GIT_LOG_CHARS = 2_000;
+// Max chars for git log output — long commit messages can bloat the system prompt.
+// Tightened from 2000: at typical 60-80 chars/commit, 800 comfortably fits
+// the 3 commits we request below with headroom for long subjects.
+const MAX_GIT_LOG_CHARS = 800;
 function getGitContext(workingDir) {
     const gitCmd = (cmd) => execSync(cmd, {
         cwd: workingDir,
@@ -516,9 +518,9 @@ function getGitContext(workingDir) {
         }
     }
     catch { /* ignore */ }
-    // Recent commits
+    // Recent commits — 3 is enough for style/context matching; more just bloats every turn.
     try {
-        let log = gitCmd('git log --oneline -5');
+        let log = gitCmd('git log --oneline -3');
         if (log) {
             if (log.length > MAX_GIT_LOG_CHARS) {
                 log = log.slice(0, MAX_GIT_LOG_CHARS) + '\n... (truncated)';

package/dist/agent/llm.js

@@ -32,6 +32,8 @@ import { USER_AGENT } from '../config.js';
  */
 export function modelHasExtendedThinking(model) {
     const m = model.toLowerCase();
+    // Excluded: Opus 4.7+ uses adaptive thinking; sending `thinking: enabled`
+    // causes the API to 400.
     if (m.includes('opus-4.7') || m.includes('opus-4-7'))
         return false;
     return (m.includes('opus-4.6') || m.includes('opus-4-6') ||
@@ -159,7 +161,6 @@ export class ModelClient {
         }
         if (isAnthropic) {
             // ─ Anthropic extended thinking ──────────────────────────────────────
-            // Enable thinking for Claude models that support it (Opus 4.6, Sonnet 4.6).
             // Enable the `thinking` API block only for models that accept it.
             // Claude Opus 4.7 and newer use *adaptive* thinking (built-in, no API
             // flag); passing the extended-thinking flag to them makes Anthropic

package/dist/agent/loop.js

@@ -12,6 +12,7 @@ import { StreamingExecutor } from './streaming-executor.js';
 import { optimizeHistory, CAPPED_MAX_TOKENS, ESCALATED_MAX_TOKENS, getMaxOutputTokens } from './optimize.js';
 import { classifyAgentError } from './error-classifier.js';
 import { SessionToolGuard } from './tool-guard.js';
+import { resetToolSessionState } from '../tools/index.js';
 import { recordUsage } from '../stats/tracker.js';
 import { recordSessionUsage } from '../stats/session-tracker.js';
 import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
@@ -34,25 +35,74 @@ function replaceHistory(target, replacement) {
 // ─── Pushback detection ───────────────────────────────────────────────────
 // Cheap models plough forward when users correct them. This detects common
 // correction patterns so the agent can explicitly reset its approach.
-const PUSHBACK_PATTERNS = [
-    /^(but|however|actually|wait|no+\b|hmm)\b/i,
+//
+// 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|that))\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,
-    /^(stop|no,|wrong|incorrect|try\s+again)\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;
-    const hasPriorAssistant = history.some((m) => m.role === 'assistant');
-    if (!hasPriorAssistant)
+    if (!lastAssistantHasClaim(history))
         return false;
     const trimmed = input.trim();
     if (trimmed.length === 0 || trimmed.length > 500)
         return false;
-    return PUSHBACK_PATTERNS.some((re) => re.test(trimmed));
+    // 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;
 }
 /**
  * Sanitize history: fix orphaned tool results AND inject missing results.
@@ -227,6 +277,13 @@ function getBackoffDelay(attempt, maxDelayMs = 32_000) {
  * Returns the accumulated conversation history.
  */
 export async function interactiveSession(config, getUserInput, onEvent, onAbortReady) {
+    // Clear module-level tool caches left over from a prior session in the same
+    // process. Matters when Franklin is used as a library or driven by tests
+    // that call interactiveSession() more than once — stale fileReadTracker /
+    // fetchCache / backgroundTasks entries from the previous run would otherwise
+    // fool Edit/Write into skipping the read-before-edit check or serve cached
+    // webfetch content fetched under the previous session's intent.
+    resetToolSessionState();
     const client = new ModelClient({
         apiUrl: config.apiUrl,
         chain: config.chain,
@@ -345,7 +402,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         history.push({ role: 'user', content: effectiveInput });
         turnCount++;
         toolGuard.startTurn();
-        persistSessionMessage({ role: 'user', content: effectiveInput });
+        // 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.
         // But DON'T reset if the original model had a payment failure — it will just fail again.
@@ -446,16 +505,27 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // ── Context awareness injection ──
             // Tell the model how full its context window is so it can self-regulate.
             // At high usage, nudge it to be concise and avoid unnecessary tool calls.
+            //
+            // IMPORTANT: this text is appended to the system prompt, which carries a
+            // prompt-cache breakpoint on Anthropic. Including the exact percentage
+            // invalidated the cache on every turn (the string differed by a digit).
+            // Bucketing the signal to coarse bands (>50 / >65 / >80) keeps the text
+            // byte-identical across many consecutive turns, so the cache actually
+            // holds. The model doesn't need 3% precision to self-regulate.
             const { contextUsagePct: preCallPct } = getAnchoredTokenCount(history);
-            if (preCallPct > 50) {
-                let contextNote = `# Context Window Status\nYou have used approximately ${Math.round(preCallPct)}% of your context window.`;
-                if (preCallPct > 80) {
-                    contextNote += ' Context is critically full. Be extremely concise. Avoid re-reading files already in context. Prioritize completing the current task over exploring new questions.';
-                }
-                else if (preCallPct > 65) {
-                    contextNote += ' Be concise in responses. Avoid unnecessary tool calls. Do not re-read files you already have in context.';
-                }
-                systemParts.push(contextNote);
+            if (preCallPct > 80) {
+                systemParts.push('# Context Window Status\nContext window is critically full (>80%). ' +
+                    'Be extremely concise. Avoid re-reading files already in context. ' +
+                    'Prioritize completing the current task over exploring new questions.');
+            }
+            else if (preCallPct > 65) {
+                systemParts.push('# Context Window Status\nContext window is more than two-thirds full (>65%). ' +
+                    'Be concise in responses. Avoid unnecessary tool calls. ' +
+                    'Do not re-read files you already have in context.');
+            }
+            else if (preCallPct > 50) {
+                systemParts.push('# Context Window Status\nContext window has crossed the halfway mark (>50%). ' +
+                    'Prefer concise responses and batch tool calls when possible.');
             }
             const systemPrompt = systemParts.join('\n\n');
             const modelMaxOut = getMaxOutputTokens(config.model);

package/dist/agent/optimize.js

@@ -21,6 +21,10 @@ export const CAPPED_MAX_TOKENS = 16_384;
 export const ESCALATED_MAX_TOKENS = 65_536;
 /** Per-model max output tokens — prevents requesting more than the model supports */
 const MODEL_MAX_OUTPUT = {
+    // Opus 4.7 supports 128k output per the BlockRun gateway model entry
+    // (anthropic/claude-opus-4.7 maxOutput: 128000). Bumping from 32k to
+    // 128k unlocks the full headroom — runaway generations are gated
+    // separately by CAPPED_MAX_TOKENS / ESCALATED_MAX_TOKENS budgets.
     'anthropic/claude-opus-4.7': 128_000,
     'anthropic/claude-opus-4.6': 32_000,
     'anthropic/claude-sonnet-4.6': 64_000,

package/dist/agent/tokens.d.ts

@@ -31,9 +31,13 @@ export declare function setEstimationModel(model: string): void;
  * Estimate token count for a string using byte-length heuristic.
  * JSON-heavy content uses 2 bytes/token; general text uses model-specific ratio.
  *
- * Padding reduced from 1.33x to 1.15x to prevent premature compaction.
- * The old 1.33x + ceil() combo caused ~36% overestimation, triggering
- * auto-compact when context was still 15-20% below the actual limit.
+ * Padding history:
+ *   1.33x → ~36% overestimate, auto-compact fired 15-20% below real limit.
+ *   1.15x → still triggered compaction around 60% of real context.
+ *   1.05x (current) — combined with Math.ceil() this still leaves a small
+ *   safety margin, and the LLM surfaces a hard 413/context error long before
+ *   the real limit that recovery code can handle. Net effect: fewer
+ *   unnecessary (and expensive) compaction round-trips on mid-sized sessions.
  */
 export declare function estimateTokens(text: string, bytesPerToken?: number): number;
 /**

package/dist/agent/tokens.js

@@ -91,14 +91,17 @@ export function setEstimationModel(model) {
  * Estimate token count for a string using byte-length heuristic.
  * JSON-heavy content uses 2 bytes/token; general text uses model-specific ratio.
  *
- * Padding reduced from 1.33x to 1.15x to prevent premature compaction.
- * The old 1.33x + ceil() combo caused ~36% overestimation, triggering
- * auto-compact when context was still 15-20% below the actual limit.
+ * Padding history:
+ *   1.33x → ~36% overestimate, auto-compact fired 15-20% below real limit.
+ *   1.15x → still triggered compaction around 60% of real context.
+ *   1.05x (current) — combined with Math.ceil() this still leaves a small
+ *   safety margin, and the LLM surfaces a hard 413/context error long before
+ *   the real limit that recovery code can handle. Net effect: fewer
+ *   unnecessary (and expensive) compaction round-trips on mid-sized sessions.
  */
 export function estimateTokens(text, bytesPerToken) {
     const effectiveBPT = bytesPerToken ?? getModelBytesPerToken(_currentModel);
-    // Pad by 15% for safety margin — still conservative but not premature
-    return Math.ceil(Buffer.byteLength(text, 'utf-8') / effectiveBPT * 1.15);
+    return Math.ceil(Buffer.byteLength(text, 'utf-8') / effectiveBPT * 1.05);
 }
 /**
  * Estimate tokens for a content part.
@@ -150,8 +153,12 @@ export function estimateHistoryTokens(history) {
  * Context window sizes for known models.
  */
 const MODEL_CONTEXT_WINDOWS = {
-    // Anthropic
-    'anthropic/claude-opus-4.7': 1_000_000,
+    // Anthropic. The BlockRun gateway model entry advertises 1M context for
+    // Opus 4.7, but the 1M beta header may not be enabled at the gateway
+    // edge yet — sending more than 200k without it 413s. Keep 200k as the
+    // safe Franklin baseline; bump to 1_000_000 in a separate commit once
+    // a real >200k call has been verified end-to-end.
+    'anthropic/claude-opus-4.7': 200_000,
     'anthropic/claude-opus-4.6': 200_000,
     'anthropic/claude-sonnet-4.6': 200_000,
     'anthropic/claude-sonnet-4': 200_000,

package/dist/agent/tool-guard.js

@@ -7,6 +7,55 @@ const SEARCH_FAMILY_SIMILARITY = 0.58;
 const DUPLICATE_READ_TURN_WINDOW = 1;
 const DUPLICATE_FETCH_TURN_WINDOW = 1;
 const MAX_PREVIEW_CHARS = 320;
+// Commands that mutate state or have side effects — never dedup these.
+// Covers: filesystem writes, network downloads, package managers, container/orchestration,
+// git mutations, privileged escalation, archive ops, and output redirection.
+// Hoisted to module scope so beforeBash/afterBash don't recompile on every call.
+// Normalize a filesystem path for cache-key use: collapse whitespace and strip
+// a single trailing slash (so `/foo` and `/foo/` share a cache entry).
+function normalizePath(p) {
+    const trimmed = p.trim().replace(/\s+/g, ' ');
+    if (trimmed.length > 1 && trimmed.endsWith('/'))
+        return trimmed.slice(0, -1);
+    return trimmed;
+}
+// Build a stable Grep cache key — or return '' if the call isn't dedupable.
+// Pattern is case-sensitive by design (grep semantics), but path/glob/type
+// are normalized so cosmetic variation doesn't bypass dedup.
+function grepKey(invocation) {
+    const pattern = String(invocation.input.pattern ?? '').trim();
+    if (!pattern)
+        return '';
+    const path = normalizePath(String(invocation.input.path ?? ''));
+    const glob = String(invocation.input.glob ?? '').trim().replace(/\s+/g, ' ');
+    const type = String(invocation.input.type ?? '').trim();
+    return `${pattern}::${path}::${glob}::${type}`;
+}
+function globKey(invocation) {
+    const pattern = String(invocation.input.pattern ?? '').trim().replace(/\s+/g, ' ');
+    if (!pattern)
+        return '';
+    const path = normalizePath(String(invocation.input.path ?? ''));
+    return `${pattern}::${path}`;
+}
+const WRITE_KEYWORDS = (() => {
+    const words = [
+        'rm', 'mv', 'cp', 'mkdir', 'touch', 'chmod', 'chown', 'ln',
+        'write', 'install', 'uninstall', 'build', 'publish',
+        'push', 'pull', 'fetch', 'clone',
+        'curl', 'wget', 'scp', 'rsync',
+        'npm', 'pnpm', 'yarn', 'bun', 'pip', 'pipx', 'poetry', 'cargo', 'gem',
+        'apt', 'apt-get', 'brew', 'port', 'dnf', 'yum', 'pacman',
+        'make', 'cmake', 'gradle', 'mvn',
+        'go\\s+(?:build|run|test|install|mod)',
+        'git\\s+(?:push|pull|commit|merge|rebase|reset|clean|stash|checkout|add|rm|mv|fetch|clone|revert|cherry-pick)',
+        'docker', 'podman', 'kubectl', 'helm',
+        'tar', 'zip', 'unzip', 'gzip', 'bzip2',
+        'tee', 'sudo', 'doas',
+    ];
+    // Redirect operators are not word chars — match separately, not under \b.
+    return new RegExp(`(?:\\b(?:${words.join('|')})\\b|>>?\\s)`);
+})();
 const SEARCH_STOPWORDS = new Set([
     'a', 'an', 'and', 'april', 'at', 'builder', 'builders', 'com', 'developer',
     'developers', 'for', 'from', 'in', 'latest', 'live', 'may', 'of', 'on', 'or',
@@ -135,10 +184,10 @@ export class SessionToolGuard {
         if (!cmd)
             return null;
         // Only dedup deterministic read-only commands. Skip anything writing/network/long-running.
-        const writeKeywords = /\b(rm|mv|cp|mkdir|touch|chmod|chown|write|install|build|publish|push|pull|curl|wget|fetch|npm|pnpm|yarn|pip|cargo|go\s+(build|run|test)|docker|kubectl|tar|zip|unzip|tee|>\s|>>\s)\b/;
-        if (writeKeywords.test(cmd))
+        if (WRITE_KEYWORDS.test(cmd))
             return null;
-        const key = cmd;
+        // Normalize whitespace so "ls   -la" and "ls -la" share a cache entry.
+        const key = cmd.replace(/\s+/g, ' ');
         const cached = this.recentBash.get(key);
         if (cached) {
             const lead = cached.isError
@@ -152,13 +201,9 @@ export class SessionToolGuard {
         return null;
     }
     beforeGrep(invocation) {
-        const pattern = String(invocation.input.pattern ?? '').trim();
-        const path = String(invocation.input.path ?? '').trim();
-        const glob = String(invocation.input.glob ?? '').trim();
-        const type = String(invocation.input.type ?? '').trim();
-        if (!pattern)
+        const key = grepKey(invocation);
+        if (!key)
             return null;
-        const key = `${pattern}::${path}::${glob}::${type}`;
         const cached = this.recentGreps.get(key);
         if (cached) {
             return {
@@ -169,11 +214,9 @@ export class SessionToolGuard {
         return null;
     }
     beforeGlob(invocation) {
-        const pattern = String(invocation.input.pattern ?? '').trim();
-        const path = String(invocation.input.path ?? '').trim();
-        if (!pattern)
+        const key = globKey(invocation);
+        if (!key)
             return null;
-        const key = `${pattern}::${path}`;
         const cached = this.recentGlobs.get(key);
         if (cached) {
             return {
@@ -216,23 +259,20 @@ export class SessionToolGuard {
         const cmd = String(invocation.input.command ?? '').trim();
         if (!cmd)
             return;
-        const writeKeywords = /\b(rm|mv|cp|mkdir|touch|chmod|chown|write|install|build|publish|push|pull|curl|wget|fetch|npm|pnpm|yarn|pip|cargo|go\s+(build|run|test)|docker|kubectl|tar|zip|unzip|tee|>\s|>>\s)\b/;
-        if (writeKeywords.test(cmd))
+        if (WRITE_KEYWORDS.test(cmd))
             return;
         const output = String(result.output ?? '');
         const preview = output.length > MAX_PREVIEW_CHARS
             ? output.slice(0, MAX_PREVIEW_CHARS) + '…'
             : output;
-        this.recentBash.set(cmd, { preview, turn: this.turn, isError: !!result.isError });
+        // Match the normalization used in beforeBash so reads/writes share keys.
+        const key = cmd.replace(/\s+/g, ' ');
+        this.recentBash.set(key, { preview, turn: this.turn, isError: !!result.isError });
     }
     afterGrep(invocation, result) {
-        const pattern = String(invocation.input.pattern ?? '').trim();
-        const path = String(invocation.input.path ?? '').trim();
-        const glob = String(invocation.input.glob ?? '').trim();
-        const type = String(invocation.input.type ?? '').trim();
-        if (!pattern)
+        const key = grepKey(invocation);
+        if (!key)
             return;
-        const key = `${pattern}::${path}::${glob}::${type}`;
         const output = String(result.output ?? '');
         const preview = output.length > MAX_PREVIEW_CHARS
             ? output.slice(0, MAX_PREVIEW_CHARS) + '…'
@@ -240,11 +280,9 @@ export class SessionToolGuard {
         this.recentGreps.set(key, { preview, turn: this.turn });
     }
     afterGlob(invocation, result) {
-        const pattern = String(invocation.input.pattern ?? '').trim();
-        const path = String(invocation.input.path ?? '').trim();
-        if (!pattern)
+        const key = globKey(invocation);
+        if (!key)
             return;
-        const key = `${pattern}::${path}`;
         const output = String(result.output ?? '');
         const preview = output.length > MAX_PREVIEW_CHARS
             ? output.slice(0, MAX_PREVIEW_CHARS) + '…'

package/dist/content/image-pricing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Best-effort pricing estimate for image generation models Franklin routes
+ * through the BlockRun gateway. Numbers are drawn from published model
+ * pricing and should be treated as *estimates* — the x402 micropayment is
+ * what actually debits the wallet. The purpose of this table is to attach a
+ * USD cost to a generated asset so budget tracking on a Content piece has
+ * something to count against, not to promise an exact price.
+ *
+ * Kept in `content/` (not `tools/`) because the table is content-budget
+ * business logic, not an image-generation implementation detail. If the
+ * gateway ever exposes the realized payment amount on the response, that
+ * should be preferred — fall back to this estimate when it's missing.
+ */
+export declare function estimateImageCostUsd(model: string, size: string): number;

package/dist/content/image-pricing.js

@@ -0,0 +1,32 @@
+/**
+ * Best-effort pricing estimate for image generation models Franklin routes
+ * through the BlockRun gateway. Numbers are drawn from published model
+ * pricing and should be treated as *estimates* — the x402 micropayment is
+ * what actually debits the wallet. The purpose of this table is to attach a
+ * USD cost to a generated asset so budget tracking on a Content piece has
+ * something to count against, not to promise an exact price.
+ *
+ * Kept in `content/` (not `tools/`) because the table is content-budget
+ * business logic, not an image-generation implementation detail. If the
+ * gateway ever exposes the realized payment amount on the response, that
+ * should be preferred — fall back to this estimate when it's missing.
+ */
+export function estimateImageCostUsd(model, size) {
+    const m = model.toLowerCase();
+    const s = size.replace(/\s+/g, '');
+    if (m === 'openai/dall-e-3') {
+        if (s === '1792x1024' || s === '1024x1792')
+            return 0.08;
+        // All other sizes fall back to the standard 1024x1024 tier.
+        return 0.04;
+    }
+    if (m === 'openai/gpt-image-1') {
+        // gpt-image-1 standard tier; larger sizes would tier up but Franklin
+        // sends 1024x1024 as default.
+        return 0.042;
+    }
+    // Unknown model: return 0 rather than a guess. A free/custom model should
+    // not have a phantom charge against the Content budget, and surprise
+    // overcharging from a wrong guess is worse than under-counting.
+    return 0;
+}

package/dist/content/library.d.ts

@@ -0,0 +1,63 @@
+export type ContentType = 'x-thread' | 'blog' | 'podcast' | 'video' | 'ad-copy' | 'image';
+export type ContentStatus = 'outline' | 'drafting' | 'assets' | 'review' | 'published';
+export type AssetKind = 'image' | 'audio' | 'video' | 'text';
+export interface ContentAsset {
+    kind: AssetKind;
+    /** Producer of the asset: model ID like "openai/dall-e-3", or "manual". */
+    source: string;
+    /** USD actually spent producing this asset. 0 is valid (free models). */
+    costUsd: number;
+    /** Optional payload reference — URL, file path, or short inline text. */
+    data?: string;
+    createdAt: number;
+}
+export interface ContentDraft {
+    text: string;
+    createdAt: number;
+}
+export interface DistributionEntry {
+    channel: string;
+    url?: string;
+    at: number;
+}
+export interface Content {
+    id: string;
+    type: ContentType;
+    title: string;
+    status: ContentStatus;
+    outline?: string;
+    drafts: ContentDraft[];
+    assets: ContentAsset[];
+    spentUsd: number;
+    budgetUsd: number;
+    createdAt: number;
+    publishedAt?: number;
+    distribution: DistributionEntry[];
+}
+export interface CreateContentOptions {
+    type: ContentType;
+    title: string;
+    budgetUsd: number;
+}
+export declare class ContentLibrary {
+    private byId;
+    create(opts: CreateContentOptions): Content;
+    get(id: string): Content | undefined;
+    list(): Content[];
+    /** Replace a content record wholesale — used by the persistence layer. */
+    restore(content: Content): void;
+    /**
+     * Record a generated asset against a content, enforcing the budget cap.
+     * Returns `{ ok: false, reason }` on rejection so callers (including the
+     * agent-facing capability) can surface the reason instead of catching an
+     * exception. On the happy path mutates the Content in place and returns
+     * the updated spendUsd.
+     */
+    addAsset(id: string, asset: Omit<ContentAsset, 'createdAt'>): {
+        ok: true;
+        spentUsd: number;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}