@blockrun/franklin 3.21.9 → 3.23.0

package/README.md

@@ -487,6 +487,18 @@ Same wallet. Same tools. From your phone.
 
 ---
 
+## Contributors
+
+External contributors whose work has shipped into Franklin:
+
+- [**@KillerQueen-Z**](https://github.com/KillerQueen-Z) — typed Phone & Voice tools (#58), permissions classifier + internal VoiceStatus polling (#59), inline-paste threshold (#60), voicemail controls (#61), PredictionMarket / Predexon v2 schema realignment + agent-loop retry guard (#62)
+- [**@BeneficialVast1048**](https://github.com/BeneficialVast1048) — VoiceCall `interruption_threshold` + `model` controls (#66)
+- [**@TateLyman**](https://github.com/TateLyman) — test path-with-spaces fix (#57)
+
+PRs welcome — see the Development section below for the local loop.
+
+---
+
 ## Development
 
 ```bash

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)**
@@ -305,8 +305,10 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - US/CA destinations only. Marketing/sales calls require prior express consent (TCPA).
 
 **Surf — crypto data + chat (x402-paid)** via the generic \`BlockRun\` capability. ~55 curated endpoints. Tier-1 $0.001, Tier-2 $0.005, Tier-3 / chat $0.02.
-- \`/v1/surf/exchange/*\` — CEX trading pairs, prices, perps, depth, klines, funding history, long/short ratio.
-- \`/v1/surf/market/*\` — token rankings, fear/greed, futures, ETF flows, options skew, liquidations, on-chain indicators (NUPL/SOPR/MVRV), price indicators (RSI/MACD/BBANDS).
+- \`/v1/surf/market/ranking\` — token rankings (market cap, volume, change). **This is the token-ranking endpoint — there is no \`market/token-ranking\` or \`market/concept-ranking\`.**
+- \`/v1/surf/market/fear-greed\` — Fear & Greed index. \`market/futures\` — futures overview. \`market/price\` (needs \`symbol\`) — price history. \`market/etf\` (needs \`symbol\`) — spot ETF flows. \`market/options\` (needs \`symbol\`) — options skew/IV.
+- \`/v1/surf/market/{liquidation/chart,liquidation/order,onchain-indicator,price-indicator}\` — liquidations, on-chain indicators (NUPL/SOPR/MVRV), technical indicators (RSI/MACD/BBANDS). Tier-2 $0.005.
+- \`/v1/surf/exchange/{price,perp,markets,depth,klines,funding-history}\` — CEX ticker, perps, pairs catalog, depth, klines, funding.
 - \`/v1/surf/news/{feed,detail}\` — AI-curated crypto news.
 - \`/v1/surf/onchain/{bridge,yield,gas-price,tx,schema,query,sql}\` — bridge/yield rankings, gas, tx detail, **raw SQL against 80+ indexed chain tables (Tier-3, $0.02)**, structured chain query, schema introspection.
 - \`/v1/surf/token/{tokenomics,dex-trades,holders,transfers}\` — token analytics.
@@ -315,7 +317,7 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/surf/fund/{detail,portfolio,ranking}\` — VC fund profiles, portfolios, ranking.
 - \`/v1/surf/project/{detail,defi/metrics,defi/ranking}\` — project profiles + DeFi protocol metrics.
 
-For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). The Surf chat surface (\`/v1/surf/chat/completions\`, surf-1.5) is **not currently exposed** by the BlockRun gateway — removed from the registry pending an upstream redesign around per-token billing. Do not attempt to call it; use the data endpoints above for crypto context, or any of the standard LLMs on \`/v1/chat/completions\` for general chat.
+**Endpoint discovery**: if you are unsure of the exact Surf path, do NOT guess blindly — any wrong \`/v1/surf/...\` path returns a 404 whose body lists every valid endpoint under \`available\`. Read that list and retry with a real path. The bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) also document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). The Surf chat surface (\`/v1/surf/chat/completions\`, surf-1.5) is **not currently exposed** by the BlockRun gateway — removed from the registry pending an upstream redesign around per-token billing. Do not attempt to call it; use the data endpoints above for crypto context, or any of the standard LLMs on \`/v1/chat/completions\` for general chat.
 
 **Generic gateway primitive**: \`BlockRun({ path, method, params, body })\` is a single capability that signs x402 and forwards to ANY path under \`/api\`. Use it for Surf endpoints (above) and any future BlockRun partner that doesn't have a dedicated capability yet. Always specify the exact path; the primitive will not guess.
 

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.

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;

package/dist/agent/repair/scavenge.js

@@ -0,0 +1,193 @@
+/**
+ * Scavenge tool calls that the model emitted as text instead of via the
+ * structured tool_use channel. Ported from reasonix (MIT) and adapted to
+ * Franklin's Anthropic-shape `CapabilityInvocation` (parsed `input` object
+ * + synthetic id).
+ *
+ * Triggers we've actually seen:
+ *  - DeepSeek R1 leaks tool-call JSON into `reasoning_content` and forgets
+ *    to populate `tool_calls`. The text channel ends up with raw JSON like
+ *    `{"name":"Read","arguments":{...}}`.
+ *  - DeepSeek V3.1 sometimes emits its chat-template DSML markup
+ *    (`<｜DSML｜invoke …>`) in the content channel.
+ *  - Smaller OpenAI-compatible models (some Qwen / Llama variants behind
+ *    the BlockRun gateway) leak the OpenAI tool-call shape inline.
+ *
+ * All three are recoverable. This module turns the leaked text back into
+ * a `CapabilityInvocation` so the agent loop doesn't waste a turn telling
+ * the model "you forgot to call a tool".
+ */
+import { randomBytes } from 'node:crypto';
+/** Bounds regex input — DSML matchers are O(n²) on adversarial input. */
+const MAX_SCAVENGE_INPUT = 100 * 1024;
+export function scavengeToolCalls(text, opts) {
+    if (!text)
+        return { calls: [], notes: [] };
+    if (text.length > MAX_SCAVENGE_INPUT) {
+        return {
+            calls: [],
+            notes: [`scavenge skipped: input too large (${text.length} chars)`],
+        };
+    }
+    const max = opts.maxCalls ?? 4;
+    const notes = [];
+    const out = [];
+    // Pattern A — DSML invoke blocks (DeepSeek chat-template markup leaked
+    // into the content channel).
+    for (const invoke of iterateDsmlInvokes(text)) {
+        if (out.length >= max)
+            break;
+        if (!opts.allowedNames.has(invoke.name))
+            continue;
+        out.push(makeInvocation(invoke.name, invoke.args));
+        notes.push(`scavenged DSML call: ${invoke.name}`);
+    }
+    // Pattern B — raw JSON objects in the three canonical shapes. Strip
+    // DSML blocks first so their parameter payloads don't get re-scavenged
+    // as standalone JSON calls.
+    const nonDsml = stripDsmlBlocks(text);
+    for (const candidate of iterateJsonObjects(nonDsml)) {
+        if (out.length >= max)
+            break;
+        const call = coerceToInvocation(candidate, opts.allowedNames);
+        if (call) {
+            out.push(call);
+            notes.push(`scavenged call: ${call.name}`);
+        }
+    }
+    return { calls: out, notes };
+}
+function stripDsmlBlocks(text) {
+    let out = text;
+    out = out.replace(/<[｜|]DSML[｜|]function_calls>[\s\S]*?<\/?[｜|]DSML[｜|]function_calls>/g, '');
+    out = out.replace(/<[｜|]DSML[｜|]invoke\s+[^>]*>[\s\S]*?<\/[｜|]DSML[｜|]invoke>/g, '');
+    return out;
+}
+function* iterateDsmlInvokes(text) {
+    // `｜` (U+FF5C) in practice; `|` (ASCII) as a fallback variant.
+    const INVOKE_RE = /<[｜|]DSML[｜|]invoke\s+name="([^"]+)">([\s\S]*?)<\/[｜|]DSML[｜|]invoke>/g;
+    for (const match of text.matchAll(INVOKE_RE)) {
+        const name = match[1];
+        const body = match[2];
+        if (!name || body === undefined)
+            continue;
+        yield { name, args: parseDsmlParameters(body) };
+    }
+}
+function parseDsmlParameters(body) {
+    const PARAM_RE = /<[｜|]DSML[｜|]parameter\s+name="([^"]+)"(?:\s+string="(true|false)")?\s*>([\s\S]*?)<\/[｜|]DSML[｜|]parameter>/g;
+    const args = {};
+    for (const m of body.matchAll(PARAM_RE)) {
+        const key = m[1];
+        const stringFlag = m[2];
+        const raw = (m[3] ?? '').trim();
+        if (!key)
+            continue;
+        if (stringFlag === 'false') {
+            try {
+                args[key] = JSON.parse(raw);
+                continue;
+            }
+            catch {
+                // Fall through — preserve literal so info isn't lost.
+            }
+        }
+        args[key] = raw;
+    }
+    return args;
+}
+function* iterateJsonObjects(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== '{')
+            continue;
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let j = i; j < text.length; j++) {
+            const c = text[j];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (inString) {
+                if (c === '\\') {
+                    escaped = true;
+                    continue;
+                }
+                if (c === '"')
+                    inString = false;
+                continue;
+            }
+            if (c === '"')
+                inString = true;
+            else if (c === '{')
+                depth++;
+            else if (c === '}') {
+                depth--;
+                if (depth === 0) {
+                    yield text.slice(i, j + 1);
+                    i = j;
+                    break;
+                }
+            }
+        }
+    }
+}
+function coerceToInvocation(candidateJson, allowedNames) {
+    let parsed;
+    try {
+        parsed = JSON.parse(candidateJson);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    // Pattern 1 — { name, arguments } (Anthropic-ish flat form).
+    if (typeof obj.name === 'string' && allowedNames.has(obj.name)) {
+        return makeInvocation(obj.name, normalizeArgs(obj.arguments));
+    }
+    // Pattern 2 — OpenAI-style { type: "function", function: { name, arguments } }.
+    if (obj.type === 'function' &&
+        obj.function &&
+        typeof obj.function === 'object') {
+        const fn = obj.function;
+        if (typeof fn.name === 'string' && allowedNames.has(fn.name)) {
+            return makeInvocation(fn.name, normalizeArgs(fn.arguments));
+        }
+    }
+    // Pattern 3 — { tool_name, tool_args } (R1 free-form variant).
+    if (typeof obj.tool_name === 'string' && allowedNames.has(obj.tool_name)) {
+        return makeInvocation(obj.tool_name, normalizeArgs(obj.tool_args));
+    }
+    return null;
+}
+function normalizeArgs(raw) {
+    if (raw == null)
+        return {};
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return {};
+        }
+        catch {
+            return {};
+        }
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        return raw;
+    }
+    return {};
+}
+function makeInvocation(name, input) {
+    return {
+        type: 'tool_use',
+        id: `toolu_repair_${randomBytes(6).toString('hex')}`,
+        name,
+        input,
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Truncated-JSON repair — ported from reasonix (MIT). Format-agnostic:
+ * works on any raw JSON argument string. Common trigger: model hits
+ * max_tokens mid-structure; the last useful argument is half-emitted.
+ *
+ * Local-only — never makes a continuation call. The agent loop owns
+ * budgets; this just patches what we have so the dispatcher can either
+ * parse it or report a clean fallback.
+ */
+export interface TruncationRepairResult {
+    repaired: string;
+    changed: boolean;
+    notes: string[];
+    /** True when all repair attempts failed and the result fell back to "{}". */
+    fallback: boolean;
+}
+export declare function repairTruncatedJson(input: string): TruncationRepairResult;