@blockrun/franklin 3.29.4 → 3.29.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -104,6 +104,9 @@ export function classifyAgentError(message) {
104
104
  if (includesAny(err, [
105
105
  'prompt is too long',
106
106
  'context length',
107
+ 'context_length_exceeded', // OpenAI-style code, leaks via gateway for non-Anthropic models
108
+ 'context window',
109
+ 'context_window',
107
110
  'maximum context',
108
111
  'prompt too long',
109
112
  'token limit exceeded',
@@ -53,6 +53,19 @@ export interface PrefetchResult {
53
53
  }
54
54
  /** Run the prefetch for an intent. Concurrent fan-out for price + news. */
55
55
  export declare function prefetchForIntent(intent: Intent, client: ModelClient): Promise<PrefetchResult | null>;
56
+ /**
57
+ * Read an ExaAnswer response through BOTH wire shapes — the live BlockRun
58
+ * gateway returns `{ answer, costDollars }` at the TOP level, while older or
59
+ * proxied deployments nest them under `data`. This mirrors the `res.data ?? res`
60
+ * read in src/tools/exa.ts; this prefetch path is the twin of the ExaAnswer
61
+ * tool and historically drifted out of sync, paying the USDC then dropping the
62
+ * answer. Exported for regression tests. `paid` records whether a real x402
63
+ * charge settled, so a paid-but-empty answer still counts against spend.
64
+ */
65
+ export declare function readExaAnswer(raw: unknown, paid: boolean): {
66
+ text: string | null;
67
+ costUsd: number;
68
+ };
56
69
  /**
57
70
  * Augment a user message with the prefetch context block prepended. The
58
71
  * final model sees the data as part of the "incoming" user turn — no
@@ -26,6 +26,7 @@
26
26
  * coordination gap (harness fetches, model synthesizes)."
27
27
  */
28
28
  import { getStockPrice, getPrice } from '../trading/data.js';
29
+ import { blockrunSpendUsdToday } from '../trading/providers/telemetry.js';
29
30
  // ─── Intent source ──────────────────────────────────────────────────────
30
31
  //
31
32
  // Historical note: this file used to host its own LLM classifier
@@ -54,16 +55,24 @@ export async function prefetchForIntent(intent, client) {
54
55
  if (intent.kind === 'ticker') {
55
56
  if (intent.assetClass === 'stock') {
56
57
  const market = intent.market || 'us';
57
- tasks.push(getStockPrice(intent.symbol, market).then((r) => {
58
+ tasks.push((async () => {
59
+ // The stock price is a paid x402 call ($0.001) BUT cached for 5 min,
60
+ // so a repeat ticker within the window pays nothing. Book the REAL
61
+ // spend by diffing telemetry around the call (recordFetch fires only
62
+ // on a fresh paid fetch, never a cache hit) instead of hardcoding
63
+ // $0.001 — otherwise a cached hit over-reports the prefetch cost.
64
+ const before = blockrunSpendUsdToday();
65
+ const r = await getStockPrice(intent.symbol, market);
66
+ const paidUsd = Math.max(0, blockrunSpendUsdToday() - before);
58
67
  if (typeof r === 'string') {
59
- return { ok: false, line: `- ${intent.symbol} (${market}): lookup failed — ${r.slice(0, 80)}`, cost: 0 };
68
+ return { ok: false, line: `- ${intent.symbol} (${market}): lookup failed — ${r.slice(0, 80)}`, cost: paidUsd };
60
69
  }
61
70
  return {
62
71
  ok: true,
63
72
  line: `- ${intent.symbol} (${market}) live price: ${formatUsd(r.price)} (BlockRun Gateway / Pyth)`,
64
- cost: 0.001,
73
+ cost: paidUsd,
65
74
  };
66
- }));
75
+ })());
67
76
  }
68
77
  else {
69
78
  // crypto
@@ -85,14 +94,16 @@ export async function prefetchForIntent(intent, client) {
85
94
  const query = intent.assetClass === 'stock'
86
95
  ? `Why did ${intent.symbol} stock move over the past week? Recent news and catalysts for ${intent.symbol} as of today.`
87
96
  : `What are the most important recent news events affecting ${intent.symbol} cryptocurrency in the past week?`;
88
- tasks.push(exaAnswerTry(query, client).then(snippet => {
89
- if (!snippet) {
90
- return { ok: false, line: `- Recent ${intent.symbol} news: ExaAnswer lookup failed`, cost: 0 };
97
+ tasks.push(exaAnswerTry(query, client).then(({ text, costUsd }) => {
98
+ if (!text) {
99
+ // costUsd is non-zero only when a paid call actually settled but came
100
+ // back empty — count it so spend telemetry never under-reports USDC.
101
+ return { ok: false, line: `- Recent ${intent.symbol} news: ExaAnswer lookup failed`, cost: costUsd };
91
102
  }
92
103
  return {
93
104
  ok: true,
94
- line: `- Recent ${intent.symbol} news (ExaAnswer synthesized):\n ${snippet.replace(/\n/g, '\n ')}`,
95
- cost: 0.01,
105
+ line: `- Recent ${intent.symbol} news (ExaAnswer synthesized):\n ${text.replace(/\n/g, '\n ')}`,
106
+ cost: costUsd,
96
107
  };
97
108
  }));
98
109
  }
@@ -112,7 +123,30 @@ export async function prefetchForIntent(intent, client) {
112
123
  const statusLine = `*Prefetched ${lines.length} source${lines.length === 1 ? '' : 's'} · cost ${formatUsd(cost)}*`;
113
124
  return { contextBlock, statusLine, costUsd: cost, anyOk };
114
125
  }
115
- /** Thin wrapper: call ExaAnswer via the gateway, return first-paragraph text or null. */
126
+ /** Fallback per-call ExaAnswer estimate when the gateway omits costDollars. */
127
+ const EXA_ANSWER_EST_USD = 0.01;
128
+ /**
129
+ * Read an ExaAnswer response through BOTH wire shapes — the live BlockRun
130
+ * gateway returns `{ answer, costDollars }` at the TOP level, while older or
131
+ * proxied deployments nest them under `data`. This mirrors the `res.data ?? res`
132
+ * read in src/tools/exa.ts; this prefetch path is the twin of the ExaAnswer
133
+ * tool and historically drifted out of sync, paying the USDC then dropping the
134
+ * answer. Exported for regression tests. `paid` records whether a real x402
135
+ * charge settled, so a paid-but-empty answer still counts against spend.
136
+ */
137
+ export function readExaAnswer(raw, paid) {
138
+ // Defensive against a drifted/malformed wire shape: a non-object body or a
139
+ // non-string `answer` must degrade to null text (NOT throw), otherwise the
140
+ // throw is swallowed by exaAnswerTry's catch and a settled paid call is
141
+ // mis-booked as $0 — the exact under-report this function exists to prevent.
142
+ const body = (raw && typeof raw === 'object' ? raw : {});
143
+ const b = (body.data && typeof body.data === 'object' ? body.data : body);
144
+ const text = (typeof b.answer === 'string' ? b.answer : '').slice(0, 600).trim() || null;
145
+ const reported = typeof b.costDollars?.total === 'number' ? b.costDollars.total : undefined;
146
+ const costUsd = reported ?? (paid ? EXA_ANSWER_EST_USD : 0);
147
+ return { text, costUsd };
148
+ }
149
+ /** Thin wrapper: call ExaAnswer via the gateway, return parsed text + real cost. */
116
150
  async function exaAnswerTry(query, client) {
117
151
  try {
118
152
  // Reuse the BlockRun gateway chat endpoint the ExaAnswer tool already uses.
@@ -131,7 +165,7 @@ async function exaAnswerTry(query, client) {
131
165
  if (res.status === 402) {
132
166
  const payHdr = await extractPaymentReq(res);
133
167
  if (!payHdr)
134
- return null;
168
+ return { text: null, costUsd: 0 };
135
169
  const { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK } = await import('@blockrun/llm');
136
170
  const paymentRequired = parsePaymentRequired(payHdr);
137
171
  let headers = { 'Content-Type': 'application/json' };
@@ -163,17 +197,16 @@ async function exaAnswerTry(query, client) {
163
197
  method: 'POST', headers, body: JSON.stringify({ query }),
164
198
  });
165
199
  if (!res2.ok)
166
- return null;
167
- const body = await res2.json();
168
- return (body.data?.answer || '').slice(0, 600).trim() || null;
200
+ return { text: null, costUsd: 0 };
201
+ // A 200 here means the x402 charge settled — count it even if empty.
202
+ return readExaAnswer(await res2.json(), true);
169
203
  }
170
204
  if (!res.ok)
171
- return null;
172
- const body = await res.json();
173
- return (body.data?.answer || '').slice(0, 600).trim() || null;
205
+ return { text: null, costUsd: 0 };
206
+ return readExaAnswer(await res.json(), false);
174
207
  }
175
208
  catch {
176
- return null;
209
+ return { text: null, costUsd: 0 };
177
210
  }
178
211
  }
179
212
  async function extractPaymentReq(response) {
@@ -19,7 +19,7 @@ import { ToolCallRepair } from './repair/index.js';
19
19
  import { resetToolSessionState } from '../tools/index.js';
20
20
  import { CORE_TOOL_NAMES, dynamicToolsEnabled } from '../tools/tool-categories.js';
21
21
  import { createActivateToolCapability } from '../tools/activate.js';
22
- import { recordUsage } from '../stats/tracker.js';
22
+ import { recordUsage, getLiveSpendUsd } from '../stats/tracker.js';
23
23
  import { recordSessionUsage } from '../stats/session-tracker.js';
24
24
  import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
25
25
  import { logger, setDebugMode } from '../logger.js';
@@ -1322,6 +1322,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1322
1322
  // "this model is consistently slow" or "fallback was faster" until
1323
1323
  // this was fixed.
1324
1324
  const llmCallStartedAt = Date.now();
1325
+ // Snapshot live spend BEFORE the stream starts. Concurrent paid tools
1326
+ // (DeFiLlama/RPC/Prediction/...) are kicked off mid-stream via
1327
+ // onToolReceived and can settle their x402 charge before collectResults —
1328
+ // a snapshot taken AFTER the stream would miss them and let them slip the
1329
+ // --max-spend cap. We subtract the LLM's own callCost from the post-tool
1330
+ // delta below (it is added to sessionCostUsd separately), leaving a clean
1331
+ // paid-tool-only total that captures concurrent and sequential tools alike.
1332
+ const turnSpendBefore = getLiveSpendUsd();
1325
1333
  try {
1326
1334
  const result = await client.complete({
1327
1335
  model: resolvedModel,
@@ -1446,6 +1454,19 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1446
1454
  }
1447
1455
  }
1448
1456
  catch (err) {
1457
+ // ── Count a paid-but-dropped LLM charge before any retry resets it ──
1458
+ // recordSettledPayment debits the wallet BEFORE the SSE stream is parsed;
1459
+ // if the stream then fails (idle timeout, mid-stream error, or Esc), that
1460
+ // USDC is real but the success-path accounting (which reads
1461
+ // getLastPaidUsd) never ran, and the next attempt resets the accumulator.
1462
+ // Fold it into the session total NOW so --max-spend and the running cost
1463
+ // stay honest. The on-chain charge is already in cost_log via the SDK;
1464
+ // this fixes the in-session view / ceiling, not the wire ledger.
1465
+ const droppedPaidUsd = client.getLastPaidUsd();
1466
+ if (droppedPaidUsd > 0) {
1467
+ sessionCostUsd += droppedPaidUsd;
1468
+ turnCostUsd += droppedPaidUsd;
1469
+ }
1449
1470
  // ── User abort (Esc key) ──
1450
1471
  if (err.name === 'AbortError' || abort.signal.aborted) {
1451
1472
  // Save any partial response that was streamed before abort
@@ -1459,6 +1480,20 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1459
1480
  onEvent({ kind: 'turn_done', reason: 'aborted' });
1460
1481
  break;
1461
1482
  }
1483
+ // If the dropped charge pushed us over the hard cap, stop rather than
1484
+ // retry (a retry would spend more). Abort already returned above.
1485
+ const capAfterDrop = config.maxSpendUsd;
1486
+ if (droppedPaidUsd > 0 && typeof capAfterDrop === 'number' && Number.isFinite(capAfterDrop) &&
1487
+ capAfterDrop > 0 && sessionCostUsd >= capAfterDrop) {
1488
+ onEvent({
1489
+ kind: 'text_delta',
1490
+ text: `\n\n_Max-spend reached: $${sessionCostUsd.toFixed(4)} ≥ cap $${capAfterDrop.toFixed(2)} ` +
1491
+ `(incl. a charged-but-failed call). Stopping session._\n`,
1492
+ });
1493
+ persistSessionMeta();
1494
+ onEvent({ kind: 'turn_done', reason: 'budget' });
1495
+ return history;
1496
+ }
1462
1497
  const errMsg = err.message || '';
1463
1498
  const classified = classifyAgentError(errMsg);
1464
1499
  // ── Media size error recovery (strip images/PDFs + retry) ──
@@ -1531,15 +1566,17 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1531
1566
  }
1532
1567
  }
1533
1568
  if (classified.isTransient && recoveryAttempts < effectiveMaxRetries) {
1534
- // Server-error streak guard: if the same model 5xx's twice in a row
1535
- // it's almost always an upstream incident, not a blip. Switch to
1536
- // the next routing fallback instead of waiting out 5 backoffs on a
1537
- // dead provider — same idea as the payment-failure auto-fallback
1538
- // below, but for transient server errors. Skipped for non-server
1539
- // transients (rate limits, network blips) where retry is the right
1540
- // call. Also skipped when the user picked a concrete model — they
1541
- // explicitly chose this one, so we shouldn't silently swap.
1542
- if (classified.category === 'server' && parseRoutingProfile(config.model)) {
1569
+ // Server/overloaded streak guard: if the same model 5xx's or stays
1570
+ // overloaded (529) twice in a row it's almost always an upstream
1571
+ // incident, not a blip. Switch to the next routing fallback instead
1572
+ // of waiting out the backoffs on a dead/busy provider — same idea
1573
+ // as the payment-failure auto-fallback below. Skipped for other
1574
+ // transients (rate limits, network blips) where in-place retry is
1575
+ // the right call, and skipped when the user picked a concrete model
1576
+ // — they explicitly chose this one, so we shouldn't silently swap.
1577
+ // (An overloaded model's own suggestion text already says "/model
1578
+ // to switch"; this does it automatically when routing is in auto.)
1579
+ if ((classified.category === 'server' || classified.category === 'overloaded') && parseRoutingProfile(config.model)) {
1543
1580
  const streak = (serverErrorsByModel.get(resolvedModel) ?? 0) + 1;
1544
1581
  serverErrorsByModel.set(resolvedModel, streak);
1545
1582
  if (streak >= SERVER_ERROR_STREAK_BEFORE_SWITCH) {
@@ -1549,9 +1586,10 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1549
1586
  config.model = nextModel;
1550
1587
  config.onModelChange?.(nextModel, 'system');
1551
1588
  recoveryAttempts = 0;
1589
+ const failKind = classified.category === 'overloaded' ? 'is overloaded' : "keeps 5xx'ing";
1552
1590
  onEvent({
1553
1591
  kind: 'text_delta',
1554
- text: `\n*${resolvedModel} keeps 5xx'ing (${streak} in a row) — switching to ${nextModel}*\n`,
1592
+ text: `\n*${resolvedModel} ${failKind} (${streak} in a row) — switching to ${nextModel}*\n`,
1555
1593
  });
1556
1594
  continue;
1557
1595
  }
@@ -1863,21 +1901,55 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1863
1901
  continue; // Retry with higher limit
1864
1902
  }
1865
1903
  // ── Gateway error masquerading as text (BlockRun → Anthropic TPM) ──
1866
- // Some upstreams swallow rate-limit / quota errors and emit them as a
1867
- // single bracketed text block on a 200 OK. Persisting that as a real
1868
- // assistant reply poisons history (the next turn sees an "answer" that
1869
- // is actually a transport error) and triggers grounding-check retries
1870
- // that hit the same wall. Detect, throw into the classifier, and let
1871
- // the existing recovery flow handle it.
1904
+ // Some upstreams swallow rate-limit / quota / overload errors and emit
1905
+ // them as a single bracketed text block on a 200 OK. responseParts has
1906
+ // NOT been appended to history yet, so we never persist the transport
1907
+ // error as a real assistant reply (which would poison the next turn and
1908
+ // trigger grounding-check retries against the same wall). When the leaked
1909
+ // error is recoverable by switching providers, retry the turn on a free
1910
+ // model — mirroring the classifier's HTTP-error path: rate_limit always
1911
+ // falls back; overloaded only under a routing profile, so a user-pinned
1912
+ // concrete model is respected (matching the 529 streak-guard) rather than
1913
+ // silently demoted. Otherwise surface a terminal turn error and break.
1872
1914
  const gatewayErr = looksLikeGatewayErrorAsText(responseParts);
1873
1915
  if (gatewayErr.match) {
1874
1916
  logger.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
1917
+ const leaked = classifyAgentError(gatewayErr.message);
1918
+ const canFallback = leaked.category === 'rate_limit'
1919
+ || (leaked.category === 'overloaded' && !!parseRoutingProfile(config.model));
1920
+ if (canFallback) {
1921
+ // Exclude BOTH the alias (config.model may be a profile like
1922
+ // "blockrun/free") AND the concrete model that actually leaked, so
1923
+ // pickFreeFallback can't hand back the same model and waste a retry.
1924
+ turnFailedModels.add(config.model);
1925
+ turnFailedModels.add(resolvedModel);
1926
+ if (leaked.category === 'rate_limit' && lastRoutedCategory) {
1927
+ recordOutcome(lastRoutedCategory, resolvedModel, 'rate_limit');
1928
+ }
1929
+ const nextFree = pickFreeFallback(lastRoutedCategory, turnFailedModels);
1930
+ if (nextFree && nextFree !== resolvedModel) {
1931
+ const oldModel = config.model;
1932
+ config.model = nextFree;
1933
+ config.onModelChange?.(nextFree, 'system');
1934
+ recoveryAttempts = 0; // new model gets its own retry budget
1935
+ onEvent({
1936
+ kind: 'text_delta',
1937
+ text: `\n*${formatModelSwitch(oldModel, resolvedModel, leaked.category === 'overloaded' ? 'overloaded' : 'rate-limited', nextFree)}*\n`,
1938
+ });
1939
+ continue; // Retry the turn on a different provider
1940
+ }
1941
+ }
1875
1942
  lastSessionActivity = Date.now();
1876
1943
  persistSessionMeta();
1944
+ // Mirror the real-429 terminal path: if free models were exhausted this
1945
+ // turn, point a funded-wallet user at paid models as the escape hatch.
1946
+ const exhaustedHint = turnFailedModels.size > 0
1947
+ ? `\nTip: All free models tried this turn are rate-limited. Switch to a paid model with /model anthropic/claude-sonnet-4.6 and retry — your wallet handles it.`
1948
+ : '';
1877
1949
  onEvent({
1878
1950
  kind: 'turn_done',
1879
1951
  reason: 'error',
1880
- error: gatewayErr.message,
1952
+ error: `${gatewayErr.message}${exhaustedHint}`,
1881
1953
  });
1882
1954
  break;
1883
1955
  }
@@ -2047,6 +2119,31 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
2047
2119
  for (const [inv, result] of results) {
2048
2120
  onEvent({ kind: 'capability_done', id: inv.id, result });
2049
2121
  }
2122
+ // ── Fold paid-TOOL spend into the session cost ceiling ──
2123
+ // sessionCostUsd above only tracks LLM token cost; paid tools (ImageGen,
2124
+ // VideoGen, MusicGen, Exa, Surf, RealFace, Voice, Phone, Modal, DeFiLlama,
2125
+ // RPC, Prediction) settle USDC through their own x402 paths and report it
2126
+ // via recordUsage. Diff the live-spend accumulator across the WHOLE turn
2127
+ // (snapshot taken before the stream, so mid-stream concurrent tools are
2128
+ // captured too) and subtract the LLM's own callCost — which recordUsage at
2129
+ // line ~1948 already added to liveSpendUsd and which sessionCostUsd counts
2130
+ // separately — leaving paid-tool-only spend so --max-spend bounds total USDC.
2131
+ const toolSpendUsd = Math.max(0, getLiveSpendUsd() - turnSpendBefore - callCost);
2132
+ if (toolSpendUsd > 0) {
2133
+ sessionCostUsd += toolSpendUsd;
2134
+ turnCostUsd += toolSpendUsd;
2135
+ const cap = config.maxSpendUsd;
2136
+ if (typeof cap === 'number' && Number.isFinite(cap) && cap > 0 && sessionCostUsd >= cap) {
2137
+ onEvent({
2138
+ kind: 'text_delta',
2139
+ text: `\n\n_Max-spend reached: $${sessionCostUsd.toFixed(4)} ≥ cap $${cap.toFixed(2)} (incl. paid-tool spend). ` +
2140
+ `Stopping session — further calls would exceed the budget._\n`,
2141
+ });
2142
+ persistSessionMeta();
2143
+ onEvent({ kind: 'turn_done', reason: 'budget' });
2144
+ return history;
2145
+ }
2146
+ }
2050
2147
  // ── Tool call guardrails ──
2051
2148
  turnToolCalls += results.length;
2052
2149
  for (const [inv, result] of results) {
@@ -18,6 +18,14 @@ export interface RecordImageAssetInput {
18
18
  imagePath: string;
19
19
  model: string;
20
20
  size: string;
21
+ /**
22
+ * Authoritative per-image USD cost resolved by the caller (e.g. from the
23
+ * live gateway catalog). When omitted, falls back to the static estimate
24
+ * table — which returns 0 for models it doesn't list, so callers spending
25
+ * real USDC on a paid model MUST pass this or the spend bypasses the
26
+ * content budget cap.
27
+ */
28
+ costUsd?: number;
21
29
  }
22
30
  export type RecordImageDecision = {
23
31
  ok: true;
@@ -34,7 +42,7 @@ export type RecordImageDecision = {
34
42
  * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
35
43
  * content doesn't exist. Non-mutating.
36
44
  */
37
- export declare function checkImageBudget(library: ContentLibrary, contentId: string, model: string, size: string, count?: number): {
45
+ export declare function checkImageBudget(library: ContentLibrary, contentId: string, model: string, size: string, count?: number, costUsdOverride?: number): {
38
46
  ok: true;
39
47
  } | {
40
48
  ok: false;
@@ -20,12 +20,15 @@ import { estimateImageCostUsd } from './image-pricing.js';
20
20
  * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
21
21
  * content doesn't exist. Non-mutating.
22
22
  */
23
- export function checkImageBudget(library, contentId, model, size, count = 1) {
23
+ export function checkImageBudget(library, contentId, model, size, count = 1,
24
+ // Total USD the caller already resolved for `count` images (live catalog).
25
+ // Falls back to the static estimate when omitted — see RecordImageAssetInput.
26
+ costUsdOverride) {
24
27
  const content = library.get(contentId);
25
28
  if (!content) {
26
29
  return { ok: false, reason: `Content ${contentId} not found` };
27
30
  }
28
- const cost = estimateImageCostUsd(model, size, count);
31
+ const cost = costUsdOverride ?? estimateImageCostUsd(model, size, count);
29
32
  if (content.spentUsd + cost > content.budgetUsd + 1e-9) {
30
33
  return {
31
34
  ok: false,
@@ -36,7 +39,7 @@ export function checkImageBudget(library, contentId, model, size, count = 1) {
36
39
  return { ok: true };
37
40
  }
38
41
  export function recordImageAsset(library, input) {
39
- const costUsd = estimateImageCostUsd(input.model, input.size);
42
+ const costUsd = input.costUsd ?? estimateImageCostUsd(input.model, input.size);
40
43
  const result = library.addAsset(input.contentId, {
41
44
  kind: 'image',
42
45
  source: input.model,
@@ -10,14 +10,15 @@
10
10
  * best-effort, load returns `null` on any error so the agent falls back
11
11
  * to a fresh in-memory library rather than refusing to start.
12
12
  */
13
- import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
14
- import { dirname } from 'node:path';
13
+ import { existsSync, readFileSync, } from 'node:fs';
15
14
  import { ContentLibrary } from './library.js';
15
+ import { atomicWriteFileSync } from '../storage/atomic.js';
16
16
  export function saveLibrary(lib, filePath) {
17
17
  try {
18
- mkdirSync(dirname(filePath), { recursive: true });
19
18
  const payload = { version: 1, contents: lib.list() };
20
- writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf-8');
19
+ // Atomic write so a crash mid-save can't truncate the library and lose
20
+ // the budget-load-bearing spentUsd (see storage/atomic.ts).
21
+ atomicWriteFileSync(filePath, JSON.stringify(payload, null, 2));
21
22
  }
22
23
  catch {
23
24
  // Persistence is best-effort; never block a capability call on disk
@@ -26,6 +27,11 @@ export function saveLibrary(lib, filePath) {
26
27
  }
27
28
  }
28
29
  export function loadLibrary(filePath) {
30
+ // Prefer the live file; fall back to the atomic-write backup if it's
31
+ // missing or corrupt rather than starting empty.
32
+ return readLibraryFile(filePath) ?? readLibraryFile(`${filePath}.bak`);
33
+ }
34
+ function readLibraryFile(filePath) {
29
35
  if (!existsSync(filePath))
30
36
  return null;
31
37
  try {
@@ -14,6 +14,7 @@
14
14
  */
15
15
  import { API_URLS, loadChain } from '../config.js';
16
16
  import { postWithPayment } from '../payments/post-with-payment.js';
17
+ import { recordUsage } from '../stats/tracker.js';
17
18
  import { writeCache } from './cache.js';
18
19
  function phoneEndpoint(chain, path) {
19
20
  return `${API_URLS[chain]}/v1/phone/${path}`;
@@ -24,6 +25,7 @@ function phoneEndpoint(chain, path) {
24
25
  */
25
26
  export async function listNumbers(opts) {
26
27
  const chain = loadChain();
28
+ const startedAt = Date.now();
27
29
  const result = await postWithPayment(phoneEndpoint(chain, 'numbers/list'), {}, 'List wallet-owned BlockRun phone numbers');
28
30
  if (!result.ok) {
29
31
  const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
@@ -33,15 +35,28 @@ export async function listNumbers(opts) {
33
35
  ? result.body.numbers
34
36
  : [];
35
37
  writeCache({ wallet: opts.walletAddress, chain, numbers });
38
+ // Record the $0.001 x402 spend so panel/background list calls land in
39
+ // franklin stats — same label the agent's ListPhoneNumbers tool uses so the
40
+ // two aggregate (panel-initiated spend was previously dropped entirely).
41
+ try {
42
+ recordUsage('ListPhoneNumbers', 0, 0, 0.001, Date.now() - startedAt);
43
+ }
44
+ catch { /* best-effort */ }
36
45
  return { numbers, count: numbers.length, paid: 0.001 };
37
46
  }
38
47
  export async function renewNumber(phoneNumber) {
39
48
  const chain = loadChain();
49
+ const startedAt = Date.now();
40
50
  const result = await postWithPayment(phoneEndpoint(chain, 'numbers/renew'), { phoneNumber }, `Renew BlockRun phone number ${phoneNumber}`);
41
51
  if (!result.ok) {
42
52
  const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
43
53
  throw new Error(message);
44
54
  }
55
+ // Record the $5 x402 spend (parity with the agent's RenewPhoneNumber tool).
56
+ try {
57
+ recordUsage('RenewPhoneNumber', 0, 0, 5.0, Date.now() - startedAt);
58
+ }
59
+ catch { /* best-effort */ }
45
60
  return {
46
61
  phone_number: String(result.body.phone_number ?? phoneNumber),
47
62
  expires_at: String(result.body.expires_at ?? ''),
@@ -50,6 +65,7 @@ export async function renewNumber(phoneNumber) {
50
65
  }
51
66
  export async function buyNumber(opts) {
52
67
  const chain = loadChain();
68
+ const startedAt = Date.now();
53
69
  const body = { country: opts.country || 'US' };
54
70
  if (opts.areaCode)
55
71
  body.areaCode = opts.areaCode;
@@ -58,6 +74,12 @@ export async function buyNumber(opts) {
58
74
  const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
59
75
  throw new Error(message);
60
76
  }
77
+ // Record the $5 x402 spend (parity with the agent's BuyPhoneNumber tool) so a
78
+ // panel-initiated buy is no longer invisible to franklin stats / the ledger.
79
+ try {
80
+ recordUsage('BuyPhoneNumber', 0, 0, 5.0, Date.now() - startedAt);
81
+ }
82
+ catch { /* best-effort */ }
61
83
  return {
62
84
  phone_number: String(result.body.phone_number ?? ''),
63
85
  expires_at: String(result.body.expires_at ?? ''),
@@ -39,6 +39,10 @@ export declare function saveStats(stats: Stats): void;
39
39
  export declare function clearStats(): void;
40
40
  /** Flush stats to disk immediately (call on process exit) */
41
41
  export declare function flushStats(): void;
42
+ /** Cumulative USDC recorded via recordUsage this process. */
43
+ export declare function getLiveSpendUsd(): number;
44
+ /** Test helper: reset the live-spend accumulator. */
45
+ export declare function resetLiveSpend(): void;
42
46
  /**
43
47
  * Record a completed request for stats tracking
44
48
  */
@@ -154,10 +154,29 @@ export function flushStats() {
154
154
  if (cachedStats)
155
155
  saveStats(cachedStats);
156
156
  }
157
+ // ── Live spend accumulator (process-lifetime) ──────────────────────────────
158
+ // Sum of every positive costUsd passed to recordUsage, counted BEFORE the
159
+ // test/audit gates below so it reflects REAL USDC spend regardless of whether
160
+ // the row is persisted to history. The agent loop diffs this around tool
161
+ // execution to fold paid-tool spend into the --max-spend session ceiling, which
162
+ // would otherwise only see LLM token cost. See src/agent/loop.ts.
163
+ let liveSpendUsd = 0;
164
+ /** Cumulative USDC recorded via recordUsage this process. */
165
+ export function getLiveSpendUsd() {
166
+ return liveSpendUsd;
167
+ }
168
+ /** Test helper: reset the live-spend accumulator. */
169
+ export function resetLiveSpend() {
170
+ liveSpendUsd = 0;
171
+ }
157
172
  /**
158
173
  * Record a completed request for stats tracking
159
174
  */
160
175
  export function recordUsage(model, inputTokens, outputTokens, costUsd, latencyMs, fallback = false) {
176
+ // Count real spend BEFORE the test/audit gates — the --max-spend ceiling must
177
+ // see every paid tool call even when history persistence is suppressed.
178
+ if (Number.isFinite(costUsd) && costUsd > 0)
179
+ liveSpendUsd += costUsd;
161
180
  // Same rationale as appendAudit — tests run in-process with
162
181
  // local/test* models and would otherwise mix into franklin-stats.json
163
182
  // history (verified: 8.4% of a real user's 1000-entry history was
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Crash-safe file writes.
3
+ *
4
+ * `writeFileSync` truncates the target before writing its bytes, so a crash
5
+ * or kill mid-write leaves a half-written (often empty) file. For Franklin
6
+ * that means a wiped portfolio (cross-session P&L — the Trading vertical's
7
+ * headline feature) or a wiped content library (budget `spentUsd`). We
8
+ * instead write to a sibling temp file and `renameSync` it into place:
9
+ * rename is atomic on the same filesystem, so a reader ever sees only the
10
+ * complete old file or the complete new one — never a torn write. The
11
+ * previous good copy is preserved as `<file>.bak` for recovery.
12
+ */
13
+ export declare function atomicWriteFileSync(filePath: string, data: string): void;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Crash-safe file writes.
3
+ *
4
+ * `writeFileSync` truncates the target before writing its bytes, so a crash
5
+ * or kill mid-write leaves a half-written (often empty) file. For Franklin
6
+ * that means a wiped portfolio (cross-session P&L — the Trading vertical's
7
+ * headline feature) or a wiped content library (budget `spentUsd`). We
8
+ * instead write to a sibling temp file and `renameSync` it into place:
9
+ * rename is atomic on the same filesystem, so a reader ever sees only the
10
+ * complete old file or the complete new one — never a torn write. The
11
+ * previous good copy is preserved as `<file>.bak` for recovery.
12
+ */
13
+ import { writeFileSync, renameSync, copyFileSync, existsSync, mkdirSync, openSync, fsyncSync, closeSync, unlinkSync, } from 'node:fs';
14
+ import { dirname } from 'node:path';
15
+ export function atomicWriteFileSync(filePath, data) {
16
+ mkdirSync(dirname(filePath), { recursive: true });
17
+ const tmp = `${filePath}.tmp`;
18
+ // Write AND fsync the temp file before renaming it into place. rename is
19
+ // atomic w.r.t. concurrent readers, but it is not durable across a hard
20
+ // crash/power loss on its own: the filesystem can persist the rename while
21
+ // the temp file's data blocks are still in the page cache, leaving a
22
+ // zero-length target after reboot — exactly the wiped-state failure this
23
+ // module exists to prevent. fsync forces the bytes down first.
24
+ const fd = openSync(tmp, 'w');
25
+ try {
26
+ writeFileSync(fd, data, 'utf-8');
27
+ fsyncSync(fd);
28
+ }
29
+ finally {
30
+ closeSync(fd);
31
+ }
32
+ // Snapshot the last good file before swapping, so an interrupted future
33
+ // write (or a corrupt new payload) is still recoverable from <file>.bak.
34
+ if (existsSync(filePath)) {
35
+ try {
36
+ copyFileSync(filePath, `${filePath}.bak`);
37
+ }
38
+ catch { /* best-effort */ }
39
+ }
40
+ try {
41
+ renameSync(tmp, filePath);
42
+ }
43
+ catch (err) {
44
+ // Don't litter a half-written temp file on a failed swap (callers treat
45
+ // persistence as best-effort and swallow the throw, so nothing else reaps it).
46
+ try {
47
+ unlinkSync(tmp);
48
+ }
49
+ catch { /* ignore */ }
50
+ throw err;
51
+ }
52
+ // fsync the directory so the rename itself survives a crash. Some platforms
53
+ // (and Windows) reject directory fsync — best-effort.
54
+ try {
55
+ const dfd = openSync(dirname(filePath), 'r');
56
+ try {
57
+ fsyncSync(dfd);
58
+ }
59
+ finally {
60
+ closeSync(dfd);
61
+ }
62
+ }
63
+ catch { /* best-effort */ }
64
+ }