@blockrun/franklin 3.22.0 → 3.23.1

package/dist/agent/context.js

@@ -242,7 +242,7 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
 - \`GET /.well-known/x402\` — x402 resource list with prices
 
 **LLM (POST, x402-paid)**
-- \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway as of 2026-05: \`anthropic/claude-sonnet-4.6\`, \`anthropic/claude-opus-4.7\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.1\`, \`nvidia/qwen3-coder-480b\`, \`openai/gpt-5-nano\`). Do NOT invent versions like \`openai/gpt-5.1\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
+- \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway as of 2026-05: \`anthropic/claude-sonnet-4.6\`, \`anthropic/claude-opus-4.8\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.1\`, \`nvidia/qwen3-coder-480b\`, \`openai/gpt-5-nano\`). Do NOT invent versions like \`openai/gpt-5.1\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
 - \`POST /v1/messages\` — Anthropic-compatible. Body: \`{ model, messages, max_tokens, system?, tools? }\`.
 
 **Media (POST, x402-paid; GET to poll async jobs)**

package/dist/agent/error-classifier.js

@@ -30,6 +30,17 @@ export function classifyAgentError(message) {
     // `Exa /v1/exa/search failed (402): {"error":"Payment verification failed",...}`.
     // Classify BEFORE the generic 'payment' branch below since the body
     // contains both 'payment' and 'verification failed'.
+    //
+    // Treated as transient with a small retry budget: real-world telemetry
+    // (2026-05-28 audit) shows the gateway intermittently rejects valid
+    // signed payments under burst load — identical prompts succeed 5s
+    // later. Most plausible root cause is a nonce-cache race in the
+    // gateway's replay protection. Retrying re-signs with a fresh nonce on
+    // each attempt (llm.ts derives a new nonce per request), so a retry
+    // is NOT a replay. Three attempts is enough to ride out the blip
+    // without burning tokens on a model whose wallet is genuinely
+    // misconfigured (clock skew, wrong chain) — those failure modes are
+    // deterministic and will exhaust the budget quickly.
     if (includesAny(err, [
         'verification failed',
         'payment verification',
@@ -40,8 +51,8 @@ export function classifyAgentError(message) {
         'replay protection',
     ])) {
         return {
-            category: 'payment_rejected', label: 'PaymentRejected', isTransient: false, maxRetries: 0,
-            suggestion: 'The gateway rejected your signed payment. Run `franklin balance` to confirm funds + chain. Common causes: clock skew (resync system clock), wrong chain selected (use `/chain` to switch), or stale nonce (the same retry will fail). Switch to a free model with `/model free` to keep working.',
+            category: 'payment_rejected', label: 'PaymentRejected', isTransient: true, maxRetries: 3,
+            suggestion: 'The gateway rejected your signed payment. If this keeps happening: run `franklin balance` to confirm funds + chain. Common causes: clock skew (resync system clock), wrong chain selected (use `/chain` to switch). Transient blips are auto-retried.',
         };
     }
     if (includesAny(err, [

package/dist/agent/llm.js

@@ -9,6 +9,7 @@ import { appendSettlementRow } from '../stats/cost-log.js';
 import { routeRequest, parseRoutingProfile } from '../router/index.js';
 import { ThinkTagStripper } from './think-tag-stripper.js';
 import { isNemotronProseModel, stripNemotronProse } from './nemotron-prose-stripper.js';
+import { repairAndParseArgs } from './repair/index.js';
 // Reasoning-tier models the gateway routes to that reject `tool_choice`
 // outright. Pattern: OpenAI o1/o3 family + DeepSeek's reasoner variant.
 // Add new entries as their 400 errors appear in real sessions; this is
@@ -195,6 +196,8 @@ export function modelHasExtendedThinking(model) {
     const m = model.toLowerCase();
     // Excluded: Opus 4.7+ uses adaptive thinking; sending `thinking: enabled`
     // causes the API to 400.
+    if (m.includes('opus-4.8') || m.includes('opus-4-8'))
+        return false;
     if (m.includes('opus-4.7') || m.includes('opus-4-7'))
         return false;
     return (m.includes('opus-4.6') || m.includes('opus-4-6') ||
@@ -774,17 +777,27 @@ export class ModelClient {
                     if (currentToolId) {
                         let parsedInput = {};
                         let inputParseError = false;
+                        // First try strict parse; on failure, fall back to the
+                        // truncation-repair pipeline (closes unbalanced braces,
+                        // trims trailing commas, fills dangling keys with null).
+                        // Saves a turn whenever max_tokens cut a tool_use mid-emit.
                         try {
                             parsedInput = JSON.parse(currentToolInput || '{}');
                         }
                         catch (parseErr) {
-                            // Incomplete JSON from stream abort or model error.
-                            // Mark as error so the executor returns an error result
-                            // instead of silently invoking the tool with empty/wrong params.
-                            inputParseError = true;
-                            if (this.debug) {
-                                console.error(`[franklin] Malformed tool input JSON for ${currentToolName}: ${parseErr.message}`);
-                                console.error(`[franklin] Raw input was: ${currentToolInput.slice(0, 200)}`);
+                            const repaired = repairAndParseArgs(currentToolInput || '{}');
+                            if (repaired) {
+                                parsedInput = repaired.input;
+                                if (this.debug && repaired.repaired) {
+                                    console.error(`[franklin] repaired truncated tool_use JSON for ${currentToolName}: ${repaired.notes.join('; ')}`);
+                                }
+                            }
+                            else {
+                                inputParseError = true;
+                                if (this.debug) {
+                                    console.error(`[franklin] Malformed tool input JSON for ${currentToolName}: ${parseErr.message}`);
+                                    console.error(`[franklin] Raw input was: ${currentToolInput.slice(0, 200)}`);
+                                }
                             }
                         }
                         if (inputParseError) {

package/dist/agent/loop.js

@@ -14,6 +14,7 @@ import { StreamingExecutor } from './streaming-executor.js';
 import { optimizeHistory, CAPPED_MAX_TOKENS, ESCALATED_MAX_TOKENS, getMaxOutputTokens } from './optimize.js';
 import { classifyAgentError } from './error-classifier.js';
 import { SessionToolGuard } from './tool-guard.js';
+import { ToolCallRepair } from './repair/index.js';
 import { resetToolSessionState } from '../tools/index.js';
 import { CORE_TOOL_NAMES, dynamicToolsEnabled } from '../tools/tool-categories.js';
 import { createActivateToolCapability } from '../tools/activate.js';
@@ -608,6 +609,11 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     // outputs, or paths. Fed into opt-in telemetry at session end.
     const sessionToolCounts = new Map();
     const toolGuard = new SessionToolGuard();
+    // Recovers tool calls that the model leaked into the text or thinking
+    // channels instead of the structured tool_use channel. See
+    // src/agent/repair/scavenge.ts for the failure modes — most common on
+    // DeepSeek R1 and small Qwen/Llama variants behind the BlockRun gateway.
+    const callRepair = new ToolCallRepair({ allowedToolNames: activeTools });
     const persistSessionMeta = () => {
         updateSessionMeta(sessionId, {
             model: config.model,
@@ -1302,6 +1308,29 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 responseParts = result.content;
                 usage = result.usage;
                 stopReason = result.stopReason;
+                // ── Tool-call scavenge ──
+                // Recover tool calls the model emitted as text/thinking instead of
+                // structured tool_use blocks. Common on DeepSeek R1 (leaks JSON
+                // into reasoning_content) and small Qwen/Llama variants. If the
+                // scavenger finds anything, splice it into responseParts so the
+                // empty-response and stalled-intent checks below see tools.
+                {
+                    const declaredCalls = responseParts.filter((p) => p.type === 'tool_use');
+                    const reasoningText = responseParts
+                        .filter((p) => p.type === 'thinking')
+                        .map(p => p.thinking)
+                        .join('\n');
+                    const contentText = responseParts
+                        .filter((p) => p.type === 'text')
+                        .map(p => p.text)
+                        .join('\n');
+                    const repaired = callRepair.process(declaredCalls, reasoningText || null, contentText || null);
+                    if (repaired.report.scavenged > 0) {
+                        const novelCalls = repaired.calls.slice(declaredCalls.length);
+                        responseParts = [...responseParts, ...novelCalls];
+                        logger.warn(`[franklin] scavenged ${repaired.report.scavenged} leaked tool call(s) from ${config.model}: ${repaired.report.notes.join('; ')}`);
+                    }
+                }
                 // ── Empty response recovery ──
                 // If the model returns nothing, DON'T just retry the same model with the same input.
                 // That's deterministic waste. Instead: switch to a different model — then give up and tell the user.
@@ -1510,13 +1539,21 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     continue;
                 }
                 // ── Payment failure: auto-fallback to free models ──
-                // Track payment-failed models for the entire session — unlike transient errors,
-                // 402s will keep failing until the user adds funds. Also handles
-                // payment_rejected (signature verified-and-rejected by gateway):
-                // same fallback path, but the suggestion text in classifier guides
-                // the user toward clock-skew / chain-mismatch fixes rather than
-                // "add funds."
-                if (classified.category === 'payment' || classified.category === 'payment_rejected') {
+                // 'payment' (insufficient funds / 402): session-permanent blacklist —
+                // the wallet won't refill mid-session, so retrying the same model
+                // just wastes a turn. Record to elo so the router learns to avoid it.
+                //
+                // 'payment_rejected' (signed payment rejected by gateway): only
+                // fall back FOR THIS TURN — do NOT add to paymentFailedModels and
+                // do NOT record to elo. The retry budget from the transient path
+                // above (3 attempts) has already been exhausted at this point;
+                // this fallback just lets the user keep working. The next user
+                // turn resets to baseModel (see top of outer loop) so a single
+                // gateway nonce-race blip can't permanently demote the user to
+                // free models for the whole session — that's the bug audited
+                // 2026-05-28 from telemetry showing 28/468 PaymentRejected with
+                // identical prompts succeeding 5s apart.
+                if (classified.category === 'payment') {
                     turnFailedModels.add(config.model);
                     paymentFailedModels.set(config.model, Date.now());
                     // Bound the Map so long sessions don't leak. LRU-evict oldest by timestamp.
@@ -1542,6 +1579,25 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         continue; // Retry with next model
                     }
                 }
+                if (classified.category === 'payment_rejected') {
+                    turnFailedModels.add(config.model);
+                    const nextFree = pickFreeFallback(lastRoutedCategory, turnFailedModels);
+                    if (nextFree) {
+                        const oldModel = config.model;
+                        config.model = nextFree;
+                        config.onModelChange?.(nextFree, 'system');
+                        const reason = `gateway rejected payment [${classified.label}] — will retry ${oldModel} next turn`;
+                        // Reset retry counter — the transient path above already burned
+                        // this turn's budget on the rejected model; the free fallback
+                        // model gets its own (mirrors the rate_limit fallback below).
+                        recoveryAttempts = 0;
+                        onEvent({
+                            kind: 'text_delta',
+                            text: `\n*${formatModelSwitch(oldModel, resolvedModel, reason, nextFree)}*\n`,
+                        });
+                        continue; // Retry with next model
+                    }
+                }
                 // ── Rate-limit / quota: auto-fallback to a different provider ──
                 // Per-day TPM caps (Anthropic) won't clear in this session; per-second
                 // limits already had their backoff retry above and still failed. In

package/dist/agent/optimize.js

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

package/dist/agent/repair/flatten.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Schema flatten — ported from reasonix (MIT) and adapted to Franklin's
+ * CapabilitySchema shape. Deep / wide schemas get dropped or hallucinated
+ * by some models (DeepSeek R1, smaller Llamas, some Qwen variants); present
+ * them as dot-paths and re-nest before dispatch.
+ *
+ * Pure functions; no side effects. Wire into a tool registry via
+ * analyzeSchema(spec.input_schema) at registration time, then call
+ * flattenSchema() on the spec sent to the model and nestArguments() on
+ * the parsed call arguments before invoking the handler.
+ */
+import type { CapabilitySchema } from '../types.js';
+/** Loose recursive schema — properties of a CapabilitySchema are typed
+ *  `unknown`, but in practice they are JSON-Schema-like objects. */
+export interface SchemaNode {
+    type?: string | string[];
+    properties?: Record<string, SchemaNode>;
+    required?: string[];
+    items?: SchemaNode;
+    [k: string]: unknown;
+}
+export interface FlattenDecision {
+    shouldFlatten: boolean;
+    leafCount: number;
+    maxDepth: number;
+}
+export declare function analyzeSchema(schema: SchemaNode | CapabilitySchema | undefined, opts?: {
+    leafLimit?: number;
+    depthLimit?: number;
+}): FlattenDecision;
+export declare function flattenSchema(schema: SchemaNode | CapabilitySchema): CapabilitySchema;
+export declare function nestArguments(flatArgs: Record<string, unknown>): Record<string, unknown>;

package/dist/agent/repair/flatten.js

@@ -0,0 +1,77 @@
+/** Caller defines the trigger thresholds; reasonix's defaults are 10/2. */
+const DEFAULT_LEAF_LIMIT = 10;
+const DEFAULT_DEPTH_LIMIT = 2;
+export function analyzeSchema(schema, opts = {}) {
+    if (!schema)
+        return { shouldFlatten: false, leafCount: 0, maxDepth: 0 };
+    const leafLimit = opts.leafLimit ?? DEFAULT_LEAF_LIMIT;
+    const depthLimit = opts.depthLimit ?? DEFAULT_DEPTH_LIMIT;
+    let leafCount = 0;
+    let maxDepth = 0;
+    walk(schema, 0, (depth, isLeaf) => {
+        if (isLeaf)
+            leafCount++;
+        if (depth > maxDepth)
+            maxDepth = depth;
+    });
+    return {
+        shouldFlatten: leafCount > leafLimit || maxDepth > depthLimit,
+        leafCount,
+        maxDepth,
+    };
+}
+export function flattenSchema(schema) {
+    const flatProps = {};
+    const required = [];
+    collect('', schema, flatProps, required, true);
+    return {
+        type: 'object',
+        properties: flatProps,
+        required,
+    };
+}
+export function nestArguments(flatArgs) {
+    const out = {};
+    for (const [key, value] of Object.entries(flatArgs)) {
+        setByPath(out, key.split('.'), value);
+    }
+    return out;
+}
+function walk(schema, depth, visit) {
+    if (schema.type === 'object' && schema.properties) {
+        for (const child of Object.values(schema.properties)) {
+            walk(child, depth + 1, visit);
+        }
+        return;
+    }
+    if (schema.type === 'array' && schema.items) {
+        walk(schema.items, depth + 1, visit);
+        return;
+    }
+    visit(depth, true);
+}
+function collect(prefix, schema, out, required, isRootRequired) {
+    if (schema.type === 'object' && schema.properties) {
+        const requiredSet = new Set(schema.required ?? []);
+        for (const [key, child] of Object.entries(schema.properties)) {
+            const nextPrefix = prefix ? `${prefix}.${key}` : key;
+            const childRequired = isRootRequired && requiredSet.has(key);
+            collect(nextPrefix, child, out, required, childRequired);
+        }
+        return;
+    }
+    out[prefix] = schema;
+    if (isRootRequired)
+        required.push(prefix);
+}
+function setByPath(target, path, value) {
+    let cur = target;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        const next = cur[key];
+        if (typeof next !== 'object' || next === null)
+            cur[key] = {};
+        cur = cur[key];
+    }
+    cur[path[path.length - 1]] = value;
+}

package/dist/agent/repair/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool-call repair pipeline — ported and adapted from reasonix (MIT).
+ *
+ * The pipeline has three layers, each used at a different boundary:
+ *
+ *   1. `repairTruncatedJson(rawArgs)` — call at the LLM-client boundary,
+ *      right before JSON.parse on the streamed tool_use input. Catches
+ *      max_tokens-cut-mid-structure and rebalances the braces.
+ *   2. `ToolCallRepair.process(calls, reasoning, content)` — call once
+ *      the assistant turn has finished but before dispatch. Scavenges
+ *      tool calls the model leaked into text/reasoning channels and
+ *      merges them in (deduped).
+ *   3. `analyzeSchema` + `flattenSchema` + `nestArguments` — apply at
+ *      tool-registration time for tools whose schemas are deep or wide
+ *      enough that smaller models drop required params.
+ *
+ * Storm suppression is intentionally not part of this pipeline.
+ * Franklin's `SessionToolGuard` (src/agent/tool-guard.ts) already does
+ * per-tool repeat suppression with richer logic — Jaccard search
+ * families, mtime-aware Read cache, per-tool circuit breakers.
+ */
+import type { CapabilityInvocation } from '../types.js';
+export { analyzeSchema, flattenSchema, nestArguments } from './flatten.js';
+export type { FlattenDecision, SchemaNode } from './flatten.js';
+export { repairTruncatedJson } from './truncation.js';
+export type { TruncationRepairResult } from './truncation.js';
+export { scavengeToolCalls } from './scavenge.js';
+export type { ScavengeOptions, ScavengeResult } from './scavenge.js';
+export interface RepairReport {
+    scavenged: number;
+    duplicatesDropped: number;
+    notes: string[];
+}
+export interface ToolCallRepairOptions {
+    allowedToolNames: ReadonlySet<string>;
+    maxScavenge?: number;
+}
+/** Boundary-level helper: parse tool-use argument JSON with truncation
+ *  recovery. Returns `null` if every attempt fails and the caller should
+ *  reject the call (better than dispatching with `{}`).
+ *
+ *  Usage at the streaming-client boundary:
+ *    const args = repairAndParseArgs(jsonAccumulator);
+ *    if (args == null) return reject("invalid JSON in tool_use");
+ */
+export declare function repairAndParseArgs(raw: string): {
+    input: Record<string, unknown>;
+    repaired: boolean;
+    notes: string[];
+} | null;
+export declare class ToolCallRepair {
+    private readonly opts;
+    constructor(opts: ToolCallRepairOptions);
+    /**
+     * Scavenge leaked tool calls from text/reasoning channels and merge
+     * into the declared list, deduped.
+     *
+     * @param declaredCalls  Tool calls the model emitted structurally.
+     * @param reasoningText  Optional reasoning_content / thinking text.
+     * @param contentText    Optional plain text-channel content.
+     */
+    process(declaredCalls: CapabilityInvocation[], reasoningText: string | null, contentText?: string | null): {
+        calls: CapabilityInvocation[];
+        report: RepairReport;
+    };
+}

package/dist/agent/repair/index.js

@@ -0,0 +1,77 @@
+import { scavengeToolCalls } from './scavenge.js';
+import { repairTruncatedJson } from './truncation.js';
+export { analyzeSchema, flattenSchema, nestArguments } from './flatten.js';
+export { repairTruncatedJson } from './truncation.js';
+export { scavengeToolCalls } from './scavenge.js';
+/** Boundary-level helper: parse tool-use argument JSON with truncation
+ *  recovery. Returns `null` if every attempt fails and the caller should
+ *  reject the call (better than dispatching with `{}`).
+ *
+ *  Usage at the streaming-client boundary:
+ *    const args = repairAndParseArgs(jsonAccumulator);
+ *    if (args == null) return reject("invalid JSON in tool_use");
+ */
+export function repairAndParseArgs(raw) {
+    const r = repairTruncatedJson(raw);
+    if (r.fallback)
+        return null;
+    try {
+        const parsed = JSON.parse(r.repaired);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { input: parsed, repaired: r.changed, notes: r.notes };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export class ToolCallRepair {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Scavenge leaked tool calls from text/reasoning channels and merge
+     * into the declared list, deduped.
+     *
+     * @param declaredCalls  Tool calls the model emitted structurally.
+     * @param reasoningText  Optional reasoning_content / thinking text.
+     * @param contentText    Optional plain text-channel content.
+     */
+    process(declaredCalls, reasoningText, contentText = null) {
+        const report = { scavenged: 0, duplicatesDropped: 0, notes: [] };
+        const combined = [reasoningText ?? '', contentText ?? ''].filter(Boolean).join('\n');
+        const scavenged = scavengeToolCalls(combined || null, {
+            allowedNames: this.opts.allowedToolNames,
+            maxCalls: this.opts.maxScavenge ?? 4,
+        });
+        const seenSignatures = new Set(declaredCalls.map(signature));
+        const merged = [...declaredCalls];
+        for (const sc of scavenged.calls) {
+            const sig = signature(sc);
+            if (seenSignatures.has(sig)) {
+                report.duplicatesDropped++;
+                continue;
+            }
+            merged.push(sc);
+            report.scavenged++;
+            seenSignatures.add(sig);
+        }
+        report.notes.push(...scavenged.notes);
+        return { calls: merged, report };
+    }
+}
+function signature(call) {
+    return `${call.name}::${stableStringify(call.input)}`;
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}

package/dist/agent/repair/scavenge.d.ts

@@ -0,0 +1,12 @@
+import type { CapabilityInvocation } from '../types.js';
+export interface ScavengeOptions {
+    /** Allowlist of tool names the model is permitted to call. */
+    allowedNames: ReadonlySet<string>;
+    /** Cap on scavenged calls per pass — defence against runaway. */
+    maxCalls?: number;
+}
+export interface ScavengeResult {
+    calls: CapabilityInvocation[];
+    notes: string[];
+}
+export declare function scavengeToolCalls(text: string | null | undefined, opts: ScavengeOptions): ScavengeResult;