@blockrun/franklin 3.15.9 → 3.15.11

package/README.md

@@ -71,6 +71,8 @@ That's it. Zero signup, zero credit card, zero phone verification. Send **$5 of
 
 ### Prefer a GUI? Try Franklin for VS Code
 
+[![Franklin for VS Code — Beta is here](assets/franklin-vscode-banner.png)](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode)
+
 The same agent ships as a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode) — chat panel, model picker, wallet balance, image / video generation, inline diff cards — all driven by the wallet you already funded for the CLI.
 
 ```

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';
@@ -19,6 +20,7 @@ import { createActivateToolCapability } from '../tools/activate.js';
 import { recordUsage } from '../stats/tracker.js';
 import { recordSessionUsage } from '../stats/session-tracker.js';
 import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
+import { logger, setDebugMode } from '../logger.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
@@ -324,6 +326,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     // fool Edit/Write into skipping the read-before-edit check or serve cached
     // webfetch content fetched under the previous session's intent.
     resetToolSessionState();
+    // Wire stderr-mirroring of log lines to the same flag the agent already
+    // uses to gate verbose console output. File writes happen regardless.
+    setDebugMode(!!config.debug);
     const client = new ModelClient({
         apiUrl: config.apiUrl,
         chain: config.chain,
@@ -476,6 +481,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
@@ -708,16 +729,12 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             kind: 'text_delta',
                             text: `\n*🗜 Auto-compacted: ~${(beforeTokens / 1000).toFixed(0)}K → ~${(afterTokens / 1000).toFixed(0)}K tokens (saved ${pct}%)*\n\n`,
                         });
-                        if (config.debug) {
-                            console.error(`[franklin] History compacted: ~${afterTokens} tokens`);
-                        }
+                        logger.info(`[franklin] History compacted: ~${afterTokens} tokens`);
                     }
                 }
                 catch (compactErr) {
                     compactFailures++;
-                    if (config.debug) {
-                        console.error(`[franklin] Compaction failed (${compactFailures}/3): ${compactErr.message}`);
-                    }
+                    logger.warn(`[franklin] Compaction failed (${compactFailures}/3): ${compactErr.message}`);
                 }
             }
             // Inject ultrathink instruction when mode is active
@@ -922,9 +939,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const oldModel = config.model;
                         config.model = nextModel;
                         config.onModelChange?.(nextModel, 'system');
-                        if (config.debug) {
-                            console.error(`[franklin] ${oldModel} returned empty — switching to ${nextModel}`);
-                        }
+                        logger.warn(`[franklin] ${oldModel} returned empty — switching to ${nextModel}`);
                         onEvent({ kind: 'text_delta', text: `\n*${oldModel} returned empty — switching to ${nextModel}*\n` });
                         continue;
                     }
@@ -956,9 +971,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 // ── Media size error recovery (strip images/PDFs + retry) ──
                 if (isMediaSizeError(errMsg) && recoveryAttempts < MAX_RECOVERY_ATTEMPTS) {
                     recoveryAttempts++;
-                    if (config.debug) {
-                        console.error(`[franklin] Media too large — stripping and retrying (attempt ${recoveryAttempts})`);
-                    }
+                    logger.warn(`[franklin] Media too large — stripping and retrying (attempt ${recoveryAttempts})`);
                     const { history: stripped, stripped: didStrip } = stripMediaFromHistory(history);
                     if (didStrip) {
                         replaceHistory(history, stripped);
@@ -972,9 +985,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 // the prompt is too long, so we must compact regardless of our threshold estimate.
                 if (classified.category === 'context_limit' && recoveryAttempts < MAX_RECOVERY_ATTEMPTS) {
                     recoveryAttempts++;
-                    if (config.debug) {
-                        console.error(`[franklin] Prompt too long — force compacting (attempt ${recoveryAttempts})`);
-                    }
+                    logger.warn(`[franklin] Prompt too long — force compacting (attempt ${recoveryAttempts})`);
                     onEvent({ kind: 'text_delta', text: '\n*Context limit hit — compacting conversation...*\n' });
                     const { history: compactedAgain } = await forceCompact(history, config.model, client, config.debug);
                     replaceHistory(history, compactedAgain);
@@ -1000,9 +1011,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             const continuationPrompt = buildContinuationPrompt();
                             history.push(continuationPrompt);
                             persistSessionMessage(continuationPrompt);
-                            if (config.debug) {
-                                console.error(`[franklin] Stream timeout on ${resolvedModel} — auto-continuing with chunked-task prompt`);
-                            }
+                            logger.warn(`[franklin] Stream timeout on ${resolvedModel} — auto-continuing with chunked-task prompt`);
                             onEvent({
                                 kind: 'text_delta',
                                 text: '\n*Task too big for one streaming turn — auto-continuing with a smaller chunk...*\n',
@@ -1014,10 +1023,8 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const costText = retryDecision.estimatedReplayCostUsd > 0
                             ? ` and at least $${retryDecision.estimatedReplayCostUsd.toFixed(4)} in input charges`
                             : '';
-                        if (config.debug) {
-                            console.error(`[franklin] Timeout retry skipped for ${resolvedModel}: ` +
-                                `~${tokenText} input tokens, replayCost=$${retryDecision.estimatedReplayCostUsd.toFixed(4)}`);
-                        }
+                        logger.warn(`[franklin] Timeout retry skipped for ${resolvedModel}: ` +
+                            `~${tokenText} input tokens, replayCost=$${retryDecision.estimatedReplayCostUsd.toFixed(4)}`);
                         onEvent({
                             kind: 'turn_done',
                             reason: 'error',
@@ -1062,9 +1069,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     }
                     recoveryAttempts++;
                     const backoffMs = getBackoffDelay(recoveryAttempts);
-                    if (config.debug) {
-                        console.error(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries}): ${errMsg.slice(0, 100)}`);
-                    }
+                    logger.warn(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries}): ${errMsg.slice(0, 100)}`);
                     // Surface the actual error + model so the user can see which model
                     // is failing and what the upstream said. Old "Retrying after Server
                     // error" was uninformative — users couldn't tell whether to wait,
@@ -1232,9 +1237,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 if (maxTokensOverride === undefined) {
                     // First hit: escalate to 64K
                     maxTokensOverride = ESCALATED_MAX_TOKENS;
-                    if (config.debug) {
-                        console.error(`[franklin] Max tokens hit — escalating to ${maxTokensOverride}`);
-                    }
+                    logger.warn(`[franklin] Max tokens hit — escalating to ${maxTokensOverride}`);
                 }
                 // Append what we got + a continuation prompt with last-line anchor
                 const partialAssistant = { role: 'assistant', content: responseParts };
@@ -1276,9 +1279,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // the existing recovery flow handle it.
             const gatewayErr = looksLikeGatewayErrorAsText(responseParts);
             if (gatewayErr.match) {
-                if (config.debug) {
-                    console.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
-                }
+                logger.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
                 throw new Error(gatewayErr.message);
             }
             // Reset recovery counter on successful completion
@@ -1555,9 +1556,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }
             // Hard stop: if cap exceeded, force end this agent loop iteration
             if (turnToolCalls >= MAX_TOOL_CALLS_PER_TURN) {
-                if (config.debug) {
-                    console.error(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn`);
-                }
+                logger.warn(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn`);
                 // Don't break — let the model respond one more time to summarize,
                 // but inject the stop signal above so it knows to finish up.
             }

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/dist/agent/tool-guard.js

@@ -188,9 +188,23 @@ export class SessionToolGuard {
         }
     }
     async beforeExecute(invocation, scope) {
-        // Hard-block tools that have failed too many times this session
+        // Hard-block tools that have failed too many times this session.
+        // Modal lifecycle tools are exempt: orphan sandboxes keep billing
+        // GPU time, and ModalTerminate is the only way to recover from
+        // agent-side. Auto-disabling it after 3 transient errors would
+        // strand a $0.40/hr H100 until the session ends. Same logic for
+        // media-gen tools: failures are usually transient (gateway hiccup,
+        // prompt rejection) and the user often wants to retry.
+        const FAILURE_EXEMPT = new Set([
+            'ImageGen',
+            'VideoGen',
+            'ModalCreate',
+            'ModalExec',
+            'ModalStatus',
+            'ModalTerminate',
+        ]);
         const errorCount = this.toolErrorCounts.get(invocation.name) ?? 0;
-        if (errorCount >= 3) {
+        if (errorCount >= 3 && !FAILURE_EXEMPT.has(invocation.name)) {
             return {
                 output: `${invocation.name} has failed ${errorCount} times this session and is now disabled. ` +
                     'Tell the user what went wrong and suggest alternatives.',

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function setDebugMode(enabled: boolean): void;
+export declare function isDebugMode(): boolean;
+export declare function getLogFilePath(): string;
+export declare const logger: {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+};

package/dist/logger.js

@@ -0,0 +1,74 @@
+/**
+ * Unified logger — always persists to ~/.blockrun/franklin-debug.log,
+ * optionally mirrors to stderr when debug mode is on.
+ *
+ * Why this exists: before this module, agent diagnostics were emitted with
+ * `if (config.debug) console.error(...)`. That meant `franklin logs` showed
+ * nothing in normal use because the events never hit the file. Now every
+ * level writes to disk; stderr mirroring is the opt-in part.
+ *
+ * Errors during a log write are swallowed — the agent loop must never die
+ * because the disk is full or the home dir is read-only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from './config.js';
+const LOG_FILE = path.join(BLOCKRUN_DIR, 'franklin-debug.log');
+// Strip ANSI escapes + carriage returns so the log stays grep-able.
+const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\][^\x07]*\x07|\r/g;
+let debugMode = false;
+let dirEnsured = false;
+export function setDebugMode(enabled) {
+    debugMode = enabled;
+}
+export function isDebugMode() {
+    return debugMode;
+}
+export function getLogFilePath() {
+    return LOG_FILE;
+}
+function ensureDir() {
+    if (dirEnsured)
+        return;
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        dirEnsured = true;
+    }
+    catch { /* readonly mount / disk full — keep trying so a remount recovers */ }
+}
+function writeFile(level, msg) {
+    ensureDir();
+    try {
+        const clean = msg.replace(ANSI_RE, '');
+        fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [${level.toUpperCase()}] ${clean}\n`);
+    }
+    catch { /* best-effort — never break the agent on log failure */ }
+}
+function writeStderr(msg) {
+    try {
+        process.stderr.write(msg + '\n');
+    }
+    catch { /* swallow */ }
+}
+export const logger = {
+    debug(msg) {
+        writeFile('debug', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    info(msg) {
+        writeFile('info', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    warn(msg) {
+        writeFile('warn', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    error(msg) {
+        writeFile('error', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+};

package/dist/stats/audit.d.ts

@@ -24,6 +24,12 @@ export interface AuditEntry {
     routingTier?: string;
 }
 export declare function appendAudit(entry: AuditEntry): void;
+/**
+ * Trim the audit log to the last MAX_AUDIT_ENTRIES lines if it has grown
+ * past the cap. Exported so admin/debug tooling (and tests) can force a
+ * compaction without waiting for the next interval probe.
+ */
+export declare function enforceRetention(): void;
 export declare function getAuditFilePath(): string;
 export declare function readAudit(): AuditEntry[];
 /** Pull the last user message from a Dialogue history, flatten, and strip newlines. */