@blockrun/franklin 3.15.87 → 3.15.89

package/dist/commands/start.js

@@ -1,6 +1,8 @@
 import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm';
-import { loadChain, API_URLS } from '../config.js';
+import { BLOCKRUN_DIR, loadChain, API_URLS } from '../config.js';
 import { retryFetchBalance } from './balance-retry.js';
 import { flushStats, loadStats } from '../stats/tracker.js';
 import { OPUS_PRICING, MODEL_PRICING } from '../pricing.js';
@@ -647,7 +649,18 @@ async function startPanelBackground(startPort) {
                 });
                 server.listen(port, '127.0.0.1', () => {
                     server.unref?.();
-                    resolve(`http://localhost:${port}`);
+                    const url = `http://localhost:${port}`;
+                    // Persist the bound URL so the agent context (assembled per-turn)
+                    // can point users at /#wallet for funding without baking in the
+                    // 3100 default — the panel auto-increments past EADDRINUSE.
+                    // Best-effort write: a stale file from a crashed run is harmless,
+                    // since the user just sees a dead link.
+                    try {
+                        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+                        fs.writeFileSync(path.join(BLOCKRUN_DIR, 'panel-url'), url, 'utf8');
+                    }
+                    catch { /* best-effort */ }
+                    resolve(url);
                 });
             };
             tryListen(startPort, 0);

package/dist/learnings/extractor.js

@@ -21,7 +21,7 @@ const VALID_CATEGORIES = new Set([
 const EXTRACTION_PROMPT = `You are analyzing a conversation between a user and an AI coding agent. Extract user preferences, behavioral patterns, and project knowledge that would help personalize future interactions.
 
 Analyze for:
-1. Language — what language does the user write in? (English, Chinese, mixed?)
+1. Language — what language does the user write in? (English, another language, mixed?)
 2. Model preferences — did they switch models or express a preference?
 3. Coding style — did they correct the agent's code style? (naming, formatting, conventions)
 4. Communication — are they terse or verbose? Do they want explanations or just code?

package/dist/proxy/server.js

@@ -1,6 +1,7 @@
 import http from 'node:http';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { recordUsage } from '../stats/tracker.js';
+import { appendSettlementRow } from '../stats/cost-log.js';
 import { appendAudit } from '../stats/audit.js';
 import { buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from './fallback.js';
 import { routeRequest, parseRoutingProfile, } from '../router/index.js';
@@ -430,6 +431,11 @@ export function createProxy(options) {
                 };
                 let response;
                 let finalModel = requestModel;
+                // Real x402 charge for the call that ultimately succeeded. 0 when
+                // no payment was needed (free model / cached). Fed into recordUsage
+                // and appendAudit below so franklin-stats.json reflects what the
+                // wallet actually paid, not a token-catalog estimate.
+                let paidUsd = 0;
                 const requestTimeoutMs = effectiveRequestTimeoutMs;
                 // Use fallback chain if enabled
                 if (fallbackEnabled && body && requestPath.includes('messages')) {
@@ -457,6 +463,7 @@ export function createProxy(options) {
                     // Use the body with the correct fallback model for payment
                     body = result.bodyUsed;
                     usedFallback = result.fallbackUsed;
+                    paidUsd = result.paidUsd;
                     // Skip the success log when the request originated from a test
                     // fixture, even if the fallback ended on a real model. Verified
                     // on a real machine: 5 spurious "↺ Fallback successful: using
@@ -473,7 +480,7 @@ export function createProxy(options) {
                     }
                 }
                 else {
-                    response = await fetchModelAttempt(targetUrl, requestInit, body, requestModel, {
+                    const attempt = await fetchModelAttempt(targetUrl, requestInit, body, requestModel, {
                         method: req.method || 'POST',
                         headers,
                         chain,
@@ -481,6 +488,8 @@ export function createProxy(options) {
                         solanaWallet,
                         timeoutMs: requestTimeoutMs,
                     });
+                    response = attempt.response;
+                    paidUsd = attempt.paidUsd;
                 }
                 const responseHeaders = {};
                 response.headers.forEach((v, k) => {
@@ -569,7 +578,13 @@ export function createProxy(options) {
                                     if (outputTokens > 0) {
                                         trackOutputTokens(finalModel, outputTokens);
                                         const latencyMs = Date.now() - requestStartTime;
-                                        const cost = estimateCost(finalModel, inputTokens, outputTokens);
+                                        // Real x402 charge wins over the token-catalog estimate.
+                                        // estimateCost only fills in for the no-payment path
+                                        // (free models / cached) so stats stay non-null there.
+                                        const cost = paidUsd > 0
+                                            ? paidUsd
+                                            : estimateCost(finalModel, inputTokens, outputTokens);
+                                        const costSource = paidUsd > 0 ? 'charged' : 'estimated';
                                         recordUsage(finalModel, inputTokens, outputTokens, cost, latencyMs, usedFallback);
                                         appendAudit({
                                             ts: Date.now(),
@@ -582,7 +597,7 @@ export function createProxy(options) {
                                             source: 'proxy',
                                         });
                                         if (options.debug)
-                                            logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} fallback=${usedFallback}`);
+                                            logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} (${costSource}) fallback=${usedFallback}`);
                                     }
                                 }
                                 res.end();
@@ -609,7 +624,10 @@ export function createProxy(options) {
                             trackOutputTokens(finalModel, outputTokens);
                             const inputTokens = parsed.usage?.input_tokens || 0;
                             const latencyMs = Date.now() - requestStartTime;
-                            const cost = estimateCost(finalModel, inputTokens, outputTokens);
+                            const cost = paidUsd > 0
+                                ? paidUsd
+                                : estimateCost(finalModel, inputTokens, outputTokens);
+                            const costSource = paidUsd > 0 ? 'charged' : 'estimated';
                             recordUsage(finalModel, inputTokens, outputTokens, cost, latencyMs, usedFallback);
                             appendAudit({
                                 ts: Date.now(),
@@ -622,7 +640,7 @@ export function createProxy(options) {
                                 source: 'proxy',
                             });
                             if (options.debug)
-                                logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} fallback=${usedFallback}`);
+                                logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} (${costSource}) fallback=${usedFallback}`);
                         }
                     }
                     catch {
@@ -645,16 +663,17 @@ export function createProxy(options) {
     return server;
 }
 async function fetchModelAttempt(url, init, body, model, payment) {
-    let response = await fetchWithTimeout(url, { ...init, body: body || undefined }, payment.timeoutMs, `Proxy request for ${model}`);
+    const response = await fetchWithTimeout(url, { ...init, body: body || undefined }, payment.timeoutMs, `Proxy request for ${model}`);
+    // Non-402 path: free model or cached response — no payment, paidUsd = 0.
     if (response.status !== 402)
-        return response;
+        return { response, paidUsd: 0 };
     if (payment.chain === 'solana' && payment.solanaWallet) {
         return handleSolanaPayment(response, url, payment.method, payment.headers, body, payment.solanaWallet.privateKey, payment.solanaWallet.address, payment.timeoutMs, model);
     }
     if (payment.baseWallet) {
         return handleBasePayment(response, url, payment.method, payment.headers, body, payment.baseWallet.privateKey, payment.baseWallet.address, payment.timeoutMs, model);
     }
-    return response;
+    return { response, paidUsd: 0 };
 }
 /**
  * Try each fallback model as a full x402 attempt:
@@ -670,7 +689,7 @@ async function fetchWithPaymentFallback(url, init, originalBody, config, payment
         const body = replaceModelInBody(originalBody, model);
         try {
             attempts++;
-            const response = await fetchModelAttempt(url, init, body, model, payment);
+            const { response, paidUsd } = await fetchModelAttempt(url, init, body, model, payment);
             if (!config.retryOn.includes(response.status)) {
                 return {
                     response,
@@ -679,6 +698,7 @@ async function fetchWithPaymentFallback(url, init, originalBody, config, payment
                     fallbackUsed: i > 0,
                     attemptsCount: attempts,
                     failedModels,
+                    paidUsd,
                 };
             }
             try {
@@ -719,17 +739,24 @@ function sleep(ms) {
 async function handleBasePayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
-        throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
+        throw new Error('402 Payment Required — wallet may need funding. Open http://localhost:3100/#wallet to deposit USDC (or run: franklin balance)');
     }
     const paymentRequired = parsePaymentRequired(paymentHeader);
     const details = extractPaymentDetails(paymentRequired);
+    const paidUsd = paymentAmountToUsd(details.amount);
+    appendSettlementRow(extractEndpointPath(url), paidUsd, {
+        model,
+        wallet: fromAddress,
+        network: details.network || 'base-mainnet',
+        client_kind: 'ProxyClient',
+    });
     const paymentPayload = await createPaymentPayload(privateKey, fromAddress, details.recipient, details.amount, details.network || 'eip155:8453', {
         resourceUrl: details.resource?.url || url,
         resourceDescription: details.resource?.description || 'BlockRun AI API call',
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetchWithTimeout(url, {
+    const paid = await fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
@@ -737,6 +764,7 @@ async function handleBasePayment(response, url, method, headers, body, privateKe
         },
         body: body || undefined,
     }, timeoutMs, `Paid proxy request for ${model}`);
+    return { response: paid, paidUsd };
 }
 // ======================================================================
 // Solana payment handler
@@ -744,10 +772,17 @@ async function handleBasePayment(response, url, method, headers, body, privateKe
 async function handleSolanaPayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
-        throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
+        throw new Error('402 Payment Required — wallet may need funding. Open http://localhost:3100/#wallet to deposit USDC (or run: franklin balance)');
     }
     const paymentRequired = parsePaymentRequired(paymentHeader);
     const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+    const paidUsd = paymentAmountToUsd(details.amount);
+    appendSettlementRow(extractEndpointPath(url), paidUsd, {
+        model,
+        wallet: fromAddress,
+        network: details.network || 'solana-mainnet',
+        client_kind: 'ProxyClient',
+    });
     const secretKey = await solanaKeyToBytes(privateKey);
     const feePayer = details.extra?.feePayer || details.recipient;
     const paymentPayload = await createSolanaPaymentPayload(secretKey, fromAddress, details.recipient, details.amount, feePayer, {
@@ -756,7 +791,7 @@ async function handleSolanaPayment(response, url, method, headers, body, private
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetchWithTimeout(url, {
+    const paid = await fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
@@ -764,6 +799,35 @@ async function handleSolanaPayment(response, url, method, headers, body, private
         },
         body: body || undefined,
     }, timeoutMs, `Paid proxy request for ${model}`);
+    return { response: paid, paidUsd };
+}
+/**
+ * Extract just the path portion of a URL — `https://api.blockrun.ai/v1/messages`
+ * → `/v1/messages`. Used as the `endpoint` field in `cost_log.jsonl` so
+ * proxy entries match the SDK's path-only convention. Falls back to the
+ * raw input if URL parsing throws (defensive — better to log a weird
+ * string than skip the row).
+ */
+function extractEndpointPath(url) {
+    try {
+        return new URL(url).pathname || url;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Convert an x402 `details.amount` field (USDC in micro-units, 6 decimals)
+ * to a USD float. Mirrors the SDK's `appendCostLog` math so the proxy and
+ * `cost_log.jsonl` agree to the cent.
+ */
+function paymentAmountToUsd(amount) {
+    if (amount === undefined || amount === null)
+        return 0;
+    const n = typeof amount === 'string' ? parseFloat(amount) : amount;
+    if (!Number.isFinite(n))
+        return 0;
+    return n / 1e6;
 }
 export function classifyRequest(body) {
     try {

package/dist/router/categories.js

@@ -4,44 +4,42 @@
  * using keyword matching from router weights or built-in defaults.
  */
 // Built-in category keywords (used when no learned weights available)
+// Keyword fast-path uses English only by policy (English-only-source rule).
+// Non-English user queries route through the LLM-level classifier above this
+// fast-path, which is multilingual and handles intent correctly without
+// needing a per-language keyword list here.
 const DEFAULT_CATEGORY_KEYWORDS = {
     coding: [
         'function', 'class', 'import', 'def', 'SELECT', 'async', 'await',
         'const', 'let', 'var', 'return', '```', 'bug', 'error', 'fix',
         'refactor', 'implement', 'test', 'npm', 'pip', 'git', 'deploy',
         'API', 'endpoint', 'database', 'query', 'migration', 'lint',
-        '函数', '类', '导入', '修复', '调试', '部署',
     ],
     trading: [
         'BTC', 'ETH', 'SOL', 'bitcoin', 'ethereum', 'solana', 'crypto',
         'price', 'market', 'signal', 'trade', 'buy', 'sell', 'RSI',
         'MACD', 'volume', 'bullish', 'bearish', 'support', 'resistance',
         'portfolio', 'risk', 'leverage', 'DeFi', 'token', 'swap',
-        '比特币', '以太坊', '价格', '市场', '交易', '信号',
     ],
     reasoning: [
         'prove', 'theorem', 'derive', 'step by step', 'chain of thought',
         'formally', 'mathematical', 'proof', 'logically', 'analyze',
         'compare', 'evaluate', 'trade-off', 'pros and cons', 'why',
         'explain why', 'reasoning', 'logic', 'deduce', 'infer',
-        '证明', '定理', '推导', '分析', '比较',
     ],
     creative: [
         'write a story', 'poem', 'creative', 'brainstorm', 'imagine',
         'generate an image', 'design', 'logo', 'illustration', 'art',
         'narrative', 'fiction', 'song', 'lyrics', 'slogan', 'tagline',
-        '写一个故事', '诗', '创意', '设计', '头脑风暴',
     ],
     research: [
         'search', 'find', 'look up', 'what is', 'who is', 'when was',
         'summarize', 'report', 'overview', 'comparison', 'review',
         'article', 'paper', 'study', 'data', 'statistics', 'trend',
-        '搜索', '查找', '什么是', '总结', '报告',
     ],
     chat: [
         'hello', 'hi', 'thanks', 'thank you', 'how are you', 'help',
         'translate', 'yes', 'no', 'ok', 'sure', 'good',
-        '你好', '谢谢', '帮我', '翻译',
     ],
 };
 /**

package/dist/router/index.js

@@ -70,13 +70,18 @@ const AUTO_TIERS = {
     },
 };
 // ─── Keywords for Classification ───
+//
+// Keyword fast-path uses English only by policy (English-only-source rule).
+// Non-English user queries route through the LLM-level classifier above this
+// fast-path, which is multilingual and handles intent correctly without
+// needing per-language keyword lists here.
 const CODE_KEYWORDS = [
     'function', 'class', 'import', 'def', 'SELECT', 'async', 'await',
-    'const', 'let', 'var', 'return', '```', '函数', '类', '导入',
+    'const', 'let', 'var', 'return', '```',
 ];
 const REASONING_KEYWORDS = [
     'prove', 'theorem', 'derive', 'step by step', 'chain of thought',
-    'formally', 'mathematical', 'proof', 'logically', '证明', '定理', '推导',
+    'formally', 'mathematical', 'proof', 'logically',
 ];
 const SIMPLE_KEYWORDS = [
     // True simple intents: greeting, definition lookup, translation. Factual
@@ -84,7 +89,7 @@ const SIMPLE_KEYWORDS = [
     // because they look easy but require external recall — sending them to
     // SIMPLE-tier models reliably produces hallucinated subscriber counts,
     // birth years, etc. that the post-hoc grounding check then has to flag.
-    'define', 'translate', 'hello', 'yes or no', '翻译', '你好',
+    'define', 'translate', 'hello', 'yes or no',
 ];
 // Research / fact-retrieval intent: questions whose correct answer depends
 // on data the model can't reliably recall from weights — current statistics,
@@ -98,19 +103,16 @@ const RESEARCH_KEYWORDS = [
     'best', 'top ', 'most popular', 'compare', 'vs ', ' vs.',
     'latest', 'current', 'recent', 'today', 'now',
     'subscribers', 'members', 'followers', 'market cap', 'price of',
-    '最好的', '最新', '最近', '现在', '当前', '排名', '对比',
 ];
 const TECHNICAL_KEYWORDS = [
     'algorithm', 'optimize', 'architecture', 'distributed', 'kubernetes',
-    'microservice', 'database', 'infrastructure', '算法', '架构', '优化',
+    'microservice', 'database', 'infrastructure',
 ];
 const AGENTIC_KEYWORDS = [
     'read file', 'edit', 'modify', 'update', 'create file', 'execute',
     'deploy', 'install', 'npm', 'pip', 'fix', 'debug', 'verify',
     'commit', 'push', 'pull', 'merge', 'rename', 'replace', 'delete',
     'remove', 'add', 'change', 'move', 'refactor', 'migrate',
-    '编辑', '修改', '部署', '安装', '修复', '调试',
-    '更新', '替换', '删除', '添加', '提交', '改',
 ];
 // URL patterns that signal agentic/coding tasks
 const AGENTIC_URL_PATTERNS = [
@@ -223,7 +225,7 @@ function classifyRequest(prompt, tokenCount) {
     // Imperative verbs (build, create, implement, etc.)
     const imperativeMatches = countMatches(prompt, [
         'build', 'create', 'implement', 'design', 'develop', 'write', 'make',
-        'generate', 'construct', '构建', '创建', '实现', '设计', '开发'
+        'generate', 'construct',
     ]);
     if (imperativeMatches >= 1) {
         score += 0.15;

package/dist/social/a11y.d.ts

@@ -51,4 +51,4 @@ export declare function extractArticleBlocks(tree: string): Array<{
  * This doubles as the "this is a tweet" signal in social-bot — the only link
  * inside an article block with this label shape is the permalink to the tweet.
  */
-export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\u5E74\\d{1,2}\u6708\\d{1,2}\u65E5";
+export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\p{Script=Han}\\d{1,2}\\p{Script=Han}\\d{1,2}\\p{Script=Han}";

package/dist/social/a11y.js

@@ -23,7 +23,7 @@
  * @returns       Array of ref ids like ["0-0", "1-3"] in document order
  */
 export function findRefs(tree, role, label = '.*') {
-    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*${label}`, 'g');
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(?:${label})`, 'gu');
     const out = [];
     let m;
     while ((m = re.exec(tree)) !== null) {
@@ -36,7 +36,7 @@ export function findRefs(tree, role, label = '.*') {
  * (ref) and the visible text (label) in one pass.
  */
 export function findRefsWithLabels(tree, role, label = '.*') {
-    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(${label})`, 'g');
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(${label})`, 'gu');
     const out = [];
     let m;
     while ((m = re.exec(tree)) !== null) {
@@ -86,8 +86,9 @@ export function extractArticleBlocks(tree) {
 // Matches all known X time-link formats:
 //   "Mar 16", "Apr 12, 2026", "5h", "5m", "2d", "30s", "just now", "now"
 //   "31 seconds ago", "35 minutes ago", "4 hours ago" (full-word format)
-//   "Yesterday", "Apr 12", "12:30 AM", "2026年4月12日" (CJK)
-export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}年\\d{1,2}月\\d{1,2}日';
+//   "Yesterday", "Apr 12", "12:30 AM"
+//   Locale-rendered numeric dates separated by Han-script date markers
+export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\p{Script=Han}\\d{1,2}\\p{Script=Han}\\d{1,2}\\p{Script=Han}';
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/social/browser.js

@@ -78,6 +78,54 @@ export function serializeAxTree(root) {
     walk(root, 0);
     return { tree: lines.join('\n'), refs };
 }
+function cdpStringValue(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return String(v);
+}
+function cdpNodesToAxTree(nodes) {
+    if (!nodes || nodes.length === 0)
+        return null;
+    const byId = new Map();
+    const childSet = new Set();
+    for (const n of nodes) {
+        byId.set(n.nodeId, n);
+        if (n.childIds)
+            for (const cid of n.childIds)
+                childSet.add(cid);
+    }
+    // The root has no parent (or no entry pointing at it as a child).
+    const root = nodes.find((n) => !n.parentId && !childSet.has(n.nodeId)) ??
+        nodes.find((n) => !n.parentId) ??
+        nodes[0];
+    const seen = new Set();
+    function build(node) {
+        if (seen.has(node.nodeId))
+            return null;
+        seen.add(node.nodeId);
+        const ax = {
+            role: cdpStringValue(node.role?.value),
+            name: cdpStringValue(node.name?.value),
+            value: cdpStringValue(node.value?.value),
+            description: cdpStringValue(node.description?.value),
+            children: [],
+        };
+        if (node.childIds) {
+            for (const cid of node.childIds) {
+                const child = byId.get(cid);
+                if (!child)
+                    continue;
+                const built = build(child);
+                if (built)
+                    ax.children.push(built);
+            }
+        }
+        return ax;
+    }
+    return build(root);
+}
 /**
  * Franklin's social browser driver. Lazy-imports playwright-core so the
  * rest of the CLI stays fast to start.
@@ -144,10 +192,21 @@ export class SocialBrowser {
      */
     async snapshot() {
         this.requirePage();
-        // Playwright's accessibility snapshot returns a full AX tree
-        // page.accessibility was removed from Playwright types in v1.46 but still works at runtime
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const axRoot = await this.page.accessibility.snapshot({ interestingOnly: false });
+        // page.accessibility was removed from playwright-core (gone by 1.59).
+        // Calling it threw `Cannot read properties of undefined (reading 'snapshot')`
+        // in production (failures.jsonl entries 1776662596215 / 1776662608060).
+        // The supported replacement is the CDP Accessibility domain, which still
+        // ships with Chromium-based browsers.
+        const cdp = await this.page.context().newCDPSession(this.page);
+        let axRoot;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = (await cdp.send('Accessibility.getFullAXTree'));
+            axRoot = cdpNodesToAxTree(result?.nodes);
+        }
+        finally {
+            await cdp.detach().catch(() => { });
+        }
         if (!axRoot)
             return '';
         const { tree, refs } = serializeAxTree(axRoot);

package/dist/stats/cost-log.d.ts

@@ -1,24 +1,26 @@
 /**
- * Reader for `~/.blockrun/cost_log.jsonl` — the SDK-owned ledger of every
- * settled x402 payment.
+ * Reader (and limited writer) for `~/.blockrun/cost_log.jsonl` — the
+ * append-only ledger of every settled x402 payment.
  *
- * Franklin's own `franklin-stats.json` and `franklin-audit.jsonl` only
- * capture calls that pass through specific code paths (the main agent
- * loop and the proxy). Helper LLM calls (analyzeTurn, prefetchForIntent,
- * compaction, evaluator, verification, MoA, subagent, learning extraction,
- * etc.) all settle x402 payments through the SDK — those payments DO get
- * recorded in cost_log.jsonl by `@blockrun/llm` itself, but Franklin's
- * stats infra had been ignoring this file entirely.
+ * History: this file was originally SDK-only territory. `@blockrun/llm`'s
+ * internal `appendCostLog` writes one line per micropayment when callers
+ * use SDK helper methods (modal sandbox, prediction market, exa, etc.).
+ * But Franklin's main LLM stream — both the in-process agent loop
+ * (`src/agent/llm.ts`) and the proxy server (`src/proxy/server.ts`) —
+ * have **their own** x402 signers that bypass the SDK entirely. Verified
+ * 2026-05-09 on a real machine: a single paid agent turn dropped the
+ * wallet by $0.001 and updated `franklin-stats.json` correctly, but
+ * cost_log.jsonl gained zero entries. So cost_log was never the
+ * "wallet truth" it advertised — it was an SDK-subset.
  *
- * Verified 2026-05-06 against a real machine: cost_log.jsonl is written
- * by the SDK with snake_case keys (`cost_usd`, `ts` in unix seconds with
- * subsecond precision — Python convention) and Franklin's reads/writes
- * use camelCase + ms. This module bridges the format gap so stats /
- * insights / `franklin balance` can surface the wallet-truth total
- * alongside the recorded total.
+ * Fix (2026-05-09): expose `appendSettlementRow` so the agent and proxy
+ * signers can write the same shape the SDK does. The format contract
+ * (snake_case `cost_usd`, `ts` in unix seconds with subsecond precision,
+ * one JSON object per line) is preserved exactly so both writers
+ * interleave cleanly. Order in the file follows wall-clock arrival.
  *
- * Responsibility: read-only. We never write or trim cost_log.jsonl —
- * the SDK owns it.
+ * Responsibility: read + append-only write. We never trim or rotate
+ * cost_log.jsonl — that contract still belongs to the SDK / hygiene.
  */
 export interface SettlementRow {
     /** Endpoint path that was paid for, e.g. `/v1/chat/completions`. */
@@ -61,6 +63,39 @@ interface ReadOptions {
  * is only created on the first paid call.
  */
 export declare function loadSdkSettlements(opts?: ReadOptions): SettlementRow[];
+/**
+ * Optional metadata fields the SDK writes alongside `endpoint` / `cost_usd`.
+ * Adding these to agent + proxy entries keeps cost_log.jsonl uniformly
+ * queryable (group by model, filter by wallet, etc.). Verified 2026-05-10
+ * against a real cost_log: the SDK writes
+ *   {endpoint, cost_usd, model, wallet, network, client_kind}
+ * Without these on agent rows you can't tell which model burned a $0.001
+ * — the row is just `/v1/messages: 0.001`. With them, every line is a
+ * complete forensic record.
+ */
+export interface SettlementMeta {
+    model?: string;
+    wallet?: string;
+    network?: string;
+    client_kind?: string;
+}
+/**
+ * Append one settlement row to ~/.blockrun/cost_log.jsonl in the same
+ * shape `@blockrun/llm`'s internal `appendCostLog` writes. Best-effort:
+ * silently swallows fs errors so a logging failure never breaks the
+ * paid call that just succeeded. Costs <= 0 are treated as no-op (no
+ * point logging $0 — the file's purpose is "what was actually paid").
+ *
+ * Honors FRANKLIN_NO_AUDIT=1 the same way `appendAudit` and `recordUsage`
+ * do, so test runs (test/e2e.mjs sets this) don't pollute the user's
+ * real cost_log. Verified 2026-05-10 on a real machine: two
+ * `/v1/messages: $0.000001` rows leaked into the user's cost_log from
+ * a paid e2e run because this gate was missing — paid e2e was hitting
+ * the real gateway with a real wallet, but the test framework expected
+ * NO writes to land. Restoring the gate keeps cost_log a clean ledger
+ * of REAL traffic.
+ */
+export declare function appendSettlementRow(endpoint: string, costUsd: number, meta?: SettlementMeta): void;
 /** Aggregate the SDK ledger into a single summary object. */
 export declare function summarizeSdkSettlements(opts?: ReadOptions): SettlementSummary;
 export {};