@kaleidorg/mind 0.5.1 → 0.6.1

package/src/funnel.ts

@@ -20,6 +20,7 @@
  */
 
 import { Engine } from './engine.js';
+import type { ToolCrushOptions } from './context/compress.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { FastPath, WALLET_FAST_INTENTS } from './fastpath/fastpath.js';
 import type { FastIntent } from './fastpath/fastpath.js';
@@ -31,6 +32,7 @@ import type { Recipe } from './recipe/types.js';
 import { SkillRegistry } from './skills/registry.js';
 import type { Skill } from './skills/types.js';
 import type { LLMProvider } from './providers/types.js';
+import type { InferenceMetrics } from './providers/types.js';
 import type { Retriever } from './rag/retriever.js';
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 
@@ -123,6 +125,8 @@ export interface FunnelResult {
   /** Agentic tier only: executed tool calls + reasoning turns. */
   toolCalls?: ToolResult[];
   turns?: number;
+  /** Agentic tier only: one local-inference receipt per model call. */
+  inference?: InferenceMetrics[];
 }
 
 export interface FunnelOptions {
@@ -139,6 +143,13 @@ export interface FunnelOptions {
   system?: string;
   /** Max reasoning↔tool rounds in the agentic tier. Default 5. */
   maxTurns?: number;
+  /**
+   * Crush verbose tool results before they re-enter the agentic loop's history,
+   * so a tiny on-device model's window isn't drowned in repetitive JSON. `true`
+   * uses safe defaults (amounts/addresses/invoices preserved); pass options to
+   * tune. Off by default. See compressToolResult.
+   */
+  compressToolOutput?: boolean | ToolCrushOptions;
   /** User settings, read fresh each turn. */
   getSettings?: () => FunnelSettings;
   /** Render a fast-path tool result as user-facing text. Default: built-in. */
@@ -196,6 +207,7 @@ export class Funnel {
       provider: opts.provider,
       tools: opts.tools,
       defaultMaxTurns: opts.maxTurns ?? 5,
+      compressToolOutput: opts.compressToolOutput,
     });
     this.fastPath = new FastPath(opts.fastIntents ?? WALLET_FAST_INTENTS);
     this.recipes = new RecipeRegistry(opts.recipes ?? [assetSendRecipe, paymentsRecipe, receiveRecipe]);
@@ -226,6 +238,8 @@ export class Funnel {
 
   async runTurn(text: string, cbs: FunnelCallbacks = {}): Promise<FunnelResult> {
     const settings = this.getSettings();
+    const memoryOn = settings.memoryEnabled !== false;
+    const ragOn = settings.ragEnabled !== false;
 
     // ── T0: deterministic fast-path (no LLM) ──
     // Only fires when the host's registry actually implements the intent's
@@ -247,15 +261,27 @@ export class Funnel {
     //       running steps with bad data.
     // Either way the registry must implement the recipe's final action.
     const recipe = this.recipes.select(text);
-    const slots = recipe?.extract?.(text) ?? null;
-    const deterministicallyConfident =
-      !!slots && (recipe?.confident ? recipe.confident(slots) : Object.keys(slots).length > 0);
+    // For forceModelExtract recipes (channel-order, atomic) the det extractor is
+    // de-emphasized: only used inside runRecipe as a backfill safety net; firing
+    // decision + log do not depend on brittle regex for varied NL.
+    let slotsForLog: any = null;
+    let detConfident = false;
+    if (recipe) {
+      if (recipe.forceModelExtract === true) {
+        slotsForLog = { forceModelExtract: true };
+        detConfident = true; // force path handles via LLM inside; prefilter only needs tool presence
+      } else {
+        const d = recipe.extract?.(text) ?? null;
+        slotsForLog = d;
+        detConfident = !!d && (recipe.confident ? recipe.confident(d) : Object.keys(d).length > 0);
+      }
+    }
     const fires =
       !!recipe &&
-      (recipe.forceModelExtract === true || deterministicallyConfident) &&
+      (recipe.forceModelExtract === true || detConfident) &&
       !!(await this.registry.getDef(recipe.final.tool));
     if (recipe && fires) {
-      this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slots)}`);
+      this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slotsForLog)}`);
       const res = await runRecipe(recipe, text, {
         provider: this.provider,
         tools: this.registry,
@@ -265,6 +291,26 @@ export class Funnel {
           cbs.onStep?.(name);
         },
       });
+      // Auto-remember ids/tokens from recipe summaries (the "remember: ..." lines)
+      // via the tool so status follow-ups can reliably recall even cross-session.
+      if (res.status === 'done' && memoryOn) {
+        try {
+          const hasRemember = await this.registry.getDef('remember');
+          if (hasRemember) {
+            const text = res.text || '';
+            const lines = text.split(/\n+/).filter((l) => /^\s*remember:/i.test(l));
+            for (const line of lines) {
+              const clean = line.trim();
+              if (clean.length > 8) {
+                void this.registry
+                  .execute('remember', { text: clean, kind: 'event', tags: ['recipe', 'order', 'status'] })
+                  .catch(() => {});
+                this.log(`auto-remembered: ${clean.slice(0, 80)}`);
+              }
+            }
+          }
+        } catch {}
+      }
       return { text: res.text, tier: 'recipe', route: recipe.name };
     }
 
@@ -278,7 +324,6 @@ export class Funnel {
     // RAG block sits above history so the model treats it as authoritative).
     // Only fires for agentic turns and only when the host opts in via
     // `retriever` AND the user hasn't disabled RAG in settings.
-    const ragOn = settings.ragEnabled !== false;
     if (this.retriever && ragOn && this.topKRag > 0) {
       try {
         const hits = await this.retriever.search(text, this.topKRag);
@@ -296,12 +341,25 @@ export class Funnel {
 
     // Ambient tools stay available even when a skill narrows the set — gated
     // by the user's memory/knowledge toggles (default on).
-    const memoryOn = settings.memoryEnabled !== false;
     const ambient = [...(memoryOn ? AMBIENT_MEMORY : []), ...(ragOn ? AMBIENT_RAG : [])];
     const disabledAmbient = [...(memoryOn ? [] : AMBIENT_MEMORY), ...(ragOn ? [] : AMBIENT_RAG)];
     let scoped: string[] | undefined;
     if (allowedTools) {
       scoped = [...new Set([...allowedTools, ...ambient])];
+      // Resilience against host tool-name drift: a skill's allowlist may name
+      // tools that don't exist on this host (e.g. the skill says `get_balances`
+      // but the desktop MCP exposes `rln_get_balances`). engine.runAgentic
+      // filters the model's tools to this list, so a fully-mismatched skill
+      // leaves the model TOOL-LESS — it then narrates "the tool isn't available"
+      // instead of acting. If NONE of the scoped tools resolve against the live
+      // registry, widen to the full surface so the agent can still work.
+      const present = new Set((await this.registry.listTools()).map((t) => t.name));
+      if (!scoped.some((n) => present.has(n))) {
+        this.log(
+          `tier=agentic: skill '${skill?.name ?? '?'}' tools resolved to 0 live tools — using full tool surface`,
+        );
+        scoped = undefined;
+      }
     } else if (disabledAmbient.length) {
       // No skill matched but a toggle is off: expose everything except the
       // disabled ambient tools (the sources stay mounted — no rebuild).
@@ -335,6 +393,13 @@ export class Funnel {
       onToolResult: cbs.onToolResult,
       onConfirm: cbs.onConfirm,
     });
-    return { text: res.text ?? '', tier: 'agentic', route: skill?.name, toolCalls: res.toolCalls, turns: res.turns };
+    return {
+      text: res.text ?? '',
+      tier: 'agentic',
+      route: skill?.name,
+      toolCalls: res.toolCalls,
+      turns: res.turns,
+      inference: res.inference,
+    };
   }
 }

package/src/index.ts

@@ -17,7 +17,12 @@ export type {
   ConfirmDecision,
 } from './types.js';
 
-export type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+export type {
+  InferenceMetrics,
+  LLMProvider,
+  TurnInput,
+  TurnOutput,
+} from './providers/types.js';
 
 export type { ToolSource } from './tools/source.js';
 export { InProcessToolSource } from './tools/in-process.js';
@@ -81,12 +86,41 @@ export type {
   BindLsps1Options,
 } from './lsps1/contract.js';
 
+// ── Bitrefill (gift cards / mobile top-ups / eSIMs) ─────────────────────────
+export {
+  BITREFILL_TOOLS,
+  BITREFILL_SPEND_TOOLS,
+  isBitrefillSpendTool,
+  getBitrefillTool,
+  bindBitrefillTools,
+} from './bitrefill/contract.js';
+export type {
+  BitrefillToolDef,
+  BitrefillHandler,
+  BindBitrefillOptions,
+} from './bitrefill/contract.js';
+
+// ── Flashnet (Spark-native AMM — swaps over Spark) ──────────────────────────
+export {
+  FLASHNET_TOOLS,
+  FLASHNET_SPEND_TOOLS,
+  isFlashnetSpendTool,
+  getFlashnetTool,
+  bindFlashnetTools,
+} from './flashnet/contract.js';
+export type {
+  FlashnetToolDef,
+  FlashnetHandler,
+  BindFlashnetOptions,
+} from './flashnet/contract.js';
+
 // ── KaleidoSwap recipes (opt-in — register via Funnel.recipes) ──
 // price recipe is read-only (quote-only); atomic recipe runs the full swap.
 // Register the price recipe FIRST so phrasings like "BTC price" are answered
 // without firing any spend.
 export { kaleidoswapPriceRecipe } from './recipe/kaleidoswap-price.js';
 export { kaleidoswapAtomicRecipe } from './recipe/kaleidoswap-atomic.js';
+export { flashnetSwapRecipe } from './recipe/flashnet-swap.js';
 export {
   kaleidoswapChannelOrderRecipe,
   extractChannelOrder,
@@ -147,6 +181,8 @@ export {
   contextBudgetTokens,
 } from './context/budget.js';
 export type { BudgetReserves } from './context/budget.js';
+export { compressToolResult, DEFAULT_PRESERVE_KEYS } from './context/compress.js';
+export type { ToolCrushOptions, CrushResult } from './context/compress.js';
 export { capabilityProfile } from './capabilities.js';
 export type { CapabilityInput, MindCapabilities } from './capabilities.js';
 
@@ -186,3 +222,58 @@ export type { Skill, SkillReference, SkillSelector } from './skills/types.js';
 
 export { TurnLogger, defaultMask } from './logger.js';
 export type { TurnLog, Device, LoggerIO, LoggerOptions } from './logger.js';
+
+export {
+  EVIDENCE_SCHEMA,
+  EvidenceRecorder,
+  sanitizeEvidenceEvent,
+} from './evidence.js';
+export type {
+  EvidenceEvent,
+  EvidenceEventType,
+  EvidenceInput,
+  EvidenceIO,
+  EvidenceRecorderOptions,
+  EvidenceSurface,
+} from './evidence.js';
+
+// ── Autonomy (the task brain: scheduled tasks + run history + spend guardrails)
+// The operational half of the agent's memory — the state nanobot kept in
+// tasks.json + cron + run history, lifted into core (storage/timers injected).
+export {
+  InMemoryTaskStore,
+  defaultTaskSeeds,
+  TaskRunLog,
+  createTaskScheduler,
+  evaluateSpend,
+  DEFAULT_RISK_LIMITS,
+  buildTaskPrompt,
+  ZERO_ALLOCATION,
+} from './autonomy/index.js';
+export type {
+  TaskAllocation,
+  AgentTask,
+  NewTask,
+  TaskSeed,
+  TaskStore,
+  TaskStoreIO,
+  TaskStoreOptions,
+  TaskRunCost,
+  TaskStats,
+  TaskRunRecord,
+  RunLogSnapshot,
+  RunLogIO,
+  RunLogOptions,
+  TaskRunOutcome,
+  RunTask,
+  TimerHandle,
+  SchedulerOptions,
+  TaskScheduler,
+  SpendKind,
+  RiskLimits,
+  SpendAction,
+  RiskContext,
+  RiskOutcome,
+  RiskVerdict,
+  TaskPromptOptions,
+} from './autonomy/index.js';

package/src/kaleidoswap/contract.ts

@@ -100,7 +100,7 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
       order_id: { type: 'string', description: 'The order id returned by kaleidoswap_place_order.' },
       access_token: { type: 'string', description: 'The per-order access token returned by kaleidoswap_place_order. Required for status checks on the order.' },
     },
-    ['order_id']),
+    ['order_id', 'access_token']),
 
   t('orders',
     'kaleidoswap_get_order_history',

package/src/knowledge/bitcoin-copilot.ts

@@ -218,8 +218,8 @@ export const BITCOIN_COPILOT_DOCS: RagDocument[] = [
       'channel size you can buy, fees, accepted payment options). It is NOT ' +
       'your current inbound capacity — it describes what the LSP is willing ' +
       'to sell you. To learn your CURRENT receive capacity, sum the remote ' +
-      'balance of your existing channels; to BUY MORE, use lsp_get_info and ' +
-      'lsp_create_order.',
+      'balance of your existing channels; to BUY MORE, use kaleidoswap_lsp_get_info and ' +
+      'kaleidoswap_lsp_create_order.',
     metadata: { topic: 'channels' },
   },
   {
@@ -285,4 +285,98 @@ export const BITCOIN_COPILOT_DOCS: RagDocument[] = [
       "(not just inbound capacity).",
     metadata: { topic: 'rgb-channels' },
   },
+
+  // ── Layer / protocol taxonomy ─────────────────────────────────────────
+  // The single biggest source of model confusion is mixing up which assets
+  // live on which layer. Small models pattern-match on "USDT" or "Bitcoin"
+  // and assume every L2 supports every asset — they don't. Each L2 has its
+  // OWN asset family, and assets do not move between them without an
+  // explicit cross-layer swap or bridge.
+
+  {
+    id: 'kaleidomind-layers-overview',
+    text:
+      'This wallet supports THREE distinct Bitcoin L2s, each with its own ' +
+      'asset family. They are NOT interchangeable: a balance on one layer ' +
+      'cannot be spent on another without an explicit swap. ' +
+      '(1) SPARK — an off-chain BTC scaling layer (Lightspark / buildonspark, ' +
+      'Statechains-based). Assets: BTC (sats) + Spark-native tokens like ' +
+      'USDB. Tools: spark_* (balance/address/invoice/pay). Swap venue: ' +
+      'Flashnet AMM (BTC ⇄ Spark tokens). ' +
+      '(2) RLN / RGB — a Lightning node that carries RGB assets over ' +
+      'BOLT11 channels (colored channels). Assets: BTC + RGB assets like ' +
+      'USDT, XAUT. Tools: rln_* (nodeinfo/invoice/pay/whitelist). Swap ' +
+      'venue: KaleidoSwap maker (BTC ⇄ RGB assets via atomic HTLC swap). ' +
+      '(3) ARKADE — an Ark-based off-chain BTC layer. Assets: BTC. Tools: ' +
+      'arkade_* (balance/address/send). No native non-BTC assets today.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'spark-layer-assets',
+    text:
+      'Spark is an off-chain BTC scaling layer (Lightspark / buildonspark). ' +
+      "It holds BTC (sats) and Spark-native tokens. USDB is a Spark token. " +
+      'Spark addresses look like spark1… (or sparkrt1… on regtest). ' +
+      'CRITICAL: Spark does NOT carry RGB assets. USDT and XAUT are RGB ' +
+      'assets that live on the RLN (RGB Lightning Node) layer — not on ' +
+      "Spark. A user's USDT balance, if they have one, is on RLN, NOT " +
+      'Spark. Conversely, USDB lives only on Spark (and trades on ' +
+      'Flashnet); it has no presence on RLN/RGB. When asked "what assets ' +
+      'are on Spark / what can I trade on Spark", answer with Spark-native ' +
+      'tokens (BTC + USDB and any other Spark tokens the AMM lists via ' +
+      'flashnet_list_pools), NOT USDT/XAUT/RGB.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'rln-layer-assets',
+    text:
+      'RLN (RGB Lightning Node) is a Lightning node that carries RGB ' +
+      'assets over BOLT11 channels (a.k.a. colored channels). It holds ' +
+      'BTC on standard Lightning channels and RGB assets — USDT, XAUT, ' +
+      'and any other client-side-validated asset issued via RGB — on ' +
+      'asset channels. Each asset needs its own channel. RGB assets do ' +
+      'NOT live on Spark or Arkade; they are RLN-only. Swap venue for ' +
+      'BTC ⇄ RGB asset is the KaleidoSwap maker (atomic HTLC: quote → ' +
+      'init → whitelist → execute). To receive an RGB asset over ' +
+      'Lightning, you first need an LSPS1-opened asset channel.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'swap-venue-split',
+    text:
+      "Two swap venues, two asset families — DO NOT confuse them. " +
+      "FLASHNET is a Spark-native AMM. It trades between BTC and " +
+      "Spark-native tokens (e.g. USDB). It uses the same Spark wallet " +
+      "as the user's balance. Tools: flashnet_list_pools, " +
+      "flashnet_simulate_swap, flashnet_execute_swap. Skill: " +
+      "flashnet-swaps. ASSETS: BTC, USDB, and anything else " +
+      "flashnet_list_pools returns. NEVER offer USDT/XAUT on Flashnet. " +
+      "KALEIDOSWAP is an atomic HTLC maker. It trades between BTC and " +
+      "RGB assets (USDT, XAUT). It uses the RLN node. Tools: " +
+      "kaleidoswap_get_quote, kaleidoswap_atomic_init, " +
+      "kaleidoswap_atomic_execute. Skill: kaleido-trading. ASSETS: BTC, " +
+      "USDT, XAUT, and other RGB assets the maker prices. NEVER offer " +
+      "USDB on KaleidoSwap.",
+    metadata: { topic: 'venues' },
+  },
+
+  {
+    id: 'asset-to-layer-routing',
+    text:
+      "How to route by asset name. The asset names tell you which layer " +
+      "to use — don't guess: " +
+      "BTC / sats → all layers (Spark / RLN / Arkade / on-chain) carry " +
+      "BTC; pick by user context. " +
+      "USDB → Spark only, via Flashnet (flashnet-swaps). " +
+      "USDT → RLN/RGB only, via KaleidoSwap (kaleido-trading). " +
+      "XAUT (tether-gold) → RLN/RGB only, via KaleidoSwap. " +
+      "If a user names an asset you don't recognise, do NOT assume a " +
+      "layer — ask, or list pools/assets via the right tool first " +
+      "(flashnet_list_pools for Spark-side, kaleidoswap_get_pairs / " +
+      "kaleidoswap_get_assets for RGB-side).",
+    metadata: { topic: 'venues' },
+  },
 ];

package/src/providers/types.ts

@@ -22,6 +22,22 @@ export interface TurnInput {
   signal?: AbortSignal;
 }
 
+/** Judge-auditable metrics for one provider inference request. */
+export interface InferenceMetrics {
+  requestId?: string;
+  backendDevice?: 'cpu' | 'gpu';
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  /** Milliseconds from completion() start to the first generated delta. */
+  ttftMs?: number;
+  /** End-to-end completion duration measured by the host. */
+  durationMs: number;
+  tokensPerSecond?: number;
+  stopReason?: string;
+  status: 'completed' | 'cancelled' | 'truncated' | 'failed';
+}
+
 export interface TurnOutput {
   /** Cleaned assistant content for display. */
   text: string;
@@ -36,6 +52,8 @@ export interface TurnOutput {
   toolCalls: ToolCall[];
   /** Provider request id, for cancellation. */
   requestId?: string;
+  /** Optional local-inference receipt. Hosts may persist this as JSONL evidence. */
+  inference?: InferenceMetrics;
 }
 
 export interface LLMProvider {

package/src/qvac/index.ts

@@ -27,6 +27,7 @@ export {
   finalToTurn,
   type QvacFinalLike,
   type ParsedTurn,
+  type QvacTurnStats,
 } from './parse.js';
 
 export {

package/src/qvac/parse.ts

@@ -6,6 +6,21 @@
  */
 import { cleanAssistantVisibleText } from './text.js';
 
+/**
+ * Per-turn inference stats from a QVAC `completion().final.stats` frame. The
+ * authoritative source for which backend actually ran (`backendDevice`) and the
+ * real throughput — hosts surface these instead of guessing from load config.
+ */
+export interface QvacTurnStats {
+  /** The backend that actually executed this turn — the real "is GPU active". */
+  backendDevice?: 'cpu' | 'gpu';
+  tokensPerSecond?: number;
+  totalTokens?: number;
+  promptTokens?: number;
+  contextSize?: number;
+  totalTime?: number;
+}
+
 /** Structural subset of a QVAC `completion().final` we depend on. */
 export interface QvacFinalLike {
   /** Visible assistant text (excludes `<think>` reasoning). */
@@ -20,6 +35,8 @@ export interface QvacFinalLike {
    * it so the funnel can tell a truncated tool-call from a complete one.
    */
   stopReason?: 'length' | 'cancelled' | string;
+  /** Inference stats (backend device, throughput). Present on a natural finish. */
+  stats?: QvacTurnStats;
 }
 
 export interface ParsedTurn {
@@ -33,6 +50,8 @@ export interface ParsedTurn {
   truncated: boolean;
   /** Raw stop reason from the SDK, when provided. */
   stopReason?: string;
+  /** Inference stats for this turn (backend device, throughput), when provided. */
+  stats?: QvacTurnStats;
 }
 
 /** Parse the first balanced `{…}` from a string as a `{name, arguments}` call. */
@@ -119,5 +138,6 @@ export function finalToTurn(final: QvacFinalLike, streamed = ''): ParsedTurn {
     toolCalls,
     truncated: final.stopReason === 'length',
     stopReason: final.stopReason,
+    stats: final.stats,
   };
 }

package/src/qvac/provider.test.ts

@@ -84,6 +84,23 @@ describe('createQvacProvider.runTurn', () => {
     expect(calls[0].generationParams).toBeUndefined();
   });
 
+  it('caps thinking by tokens — cancels the run and returns a fallback', async () => {
+    const cancel = vi.fn(async () => {});
+    const { fn } = fakeCompletion(
+      { contentText: '', toolCalls: [], raw: { fullText: '' }, stopReason: 'cancelled' },
+      [{ type: 'thinkingDelta', text: 'z'.repeat(40) }], // ~10 tokens, budget 4
+    );
+    const p = createQvacProvider({
+      completion: fn as any,
+      cancel: cancel as any,
+      getModelId: () => 'm1',
+      maxThinkingTokens: 4,
+    });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'think hard' }], tools: [] });
+    expect(cancel).toHaveBeenCalledWith({ requestId: 'req-1' });
+    expect(out.text).toMatch(/thinking budget/i);
+  });
+
   it('streams visible content tokens to onToken', async () => {
     const { fn } = fakeCompletion(
       { contentText: 'Hi there', toolCalls: [], raw: { fullText: 'Hi there' } },

package/src/qvac/provider.ts

@@ -17,7 +17,8 @@
  * delegated to a desktop peer.
  */
 import type * as QvacSdk from '@qvac/sdk';
-import type { LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
+import type { InferenceMetrics, LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
+import type { QvacTurnStats } from './parse.js';
 import { consumeRun } from './stream.js';
 
 type CompletionFn = typeof QvacSdk.completion;
@@ -38,17 +39,37 @@ export interface QvacProviderOptions {
   defaultTemperature?: number;
   /** Default max output tokens — caps a turn so it can't ramble. Omit for uncapped. */
   defaultMaxTokens?: number;
+  /**
+   * Cap `<think>` reasoning at this many TOKENS (not seconds — tok/s varies, and
+   * the SDK has no numeric reasoning budget). When a turn's thinking exceeds it,
+   * the run is cancelled and a short fallback is returned instead of hanging on
+   * "Thinking…". Omit for unlimited reasoning.
+   */
+  maxThinkingTokens?: number;
   /** Stream the model's `<think>` reasoning, when a host wants to surface it. */
   onThinking?: (token: string) => void;
+  /**
+   * Per-turn inference stats (real backend device + throughput), when a host
+   * wants to surface them. Fires once per turn after the `final` frame resolves.
+   */
+  onStats?: (stats: QvacTurnStats) => void;
 }
 
 /** TurnInput plus the per-call knobs the funnel/voice paths pass through. */
 export interface QvacTurnInput extends TurnInput {
   temperature?: number;
   maxTokens?: number;
+  /** Per-turn override of the thinking-token cap (see QvacProviderOptions). */
+  maxThinkingTokens?: number;
   onThinking?: (token: string) => void;
+  onStats?: (stats: QvacTurnStats) => void;
 }
 
+/** Shown when a turn is cut off because it blew its thinking-token budget. */
+const THINKING_BUDGET_FALLBACK =
+  'I spent my whole thinking budget on that one without landing an answer. ' +
+  'Try asking again, more specifically.';
+
 export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
   return {
     name: 'qvac',
@@ -98,16 +119,55 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         ...(tools ? { tools } : {}),
       } as unknown as Parameters<CompletionFn>[0]);
 
+      const maxThinkingTokens = input.maxThinkingTokens ?? options.maxThinkingTokens;
       const result = await consumeRun(run, {
         onToken: input.onToken,
         onThinking: input.onThinking ?? options.onThinking,
+        maxThinkingTokens,
+        // Cancel the in-flight run the moment the thinking budget is blown — the
+        // SDK keeps generating otherwise. Fire-and-forget; `final` then resolves.
+        onThinkingBudgetExceeded: () => {
+          void options.cancel({ requestId: run.requestId }).catch(() => {});
+        },
       });
 
+      // Surface the real per-turn inference stats (backend device + throughput).
+      if (result.stats) (input.onStats ?? options.onStats)?.(result.stats);
+
+      // A turn cut off mid-reasoning has no visible answer — return a short note
+      // instead of an empty bubble so the agentic loop ends cleanly.
+      const text =
+        result.text || (result.thinkingBudgetExceeded ? THINKING_BUDGET_FALLBACK : result.text);
+      const totalTokens = result.stats?.totalTokens;
+      const promptTokens = result.stats?.promptTokens;
+      const inference: InferenceMetrics = {
+        requestId: result.requestId,
+        durationMs: result.timing.durationMs,
+        status:
+          result.stopReason === 'cancelled'
+            ? 'cancelled'
+            : result.truncated
+              ? 'truncated'
+              : 'completed',
+        ...(result.stats?.backendDevice ? { backendDevice: result.stats.backendDevice } : {}),
+        ...(typeof promptTokens === 'number' ? { promptTokens } : {}),
+        ...(typeof totalTokens === 'number' ? { totalTokens } : {}),
+        ...(typeof totalTokens === 'number' && typeof promptTokens === 'number'
+          ? { completionTokens: Math.max(0, totalTokens - promptTokens) }
+          : {}),
+        ...(typeof result.timing.ttftMs === 'number' ? { ttftMs: result.timing.ttftMs } : {}),
+        ...(typeof result.stats?.tokensPerSecond === 'number'
+          ? { tokensPerSecond: result.stats.tokensPerSecond }
+          : {}),
+        ...(result.stopReason ? { stopReason: result.stopReason } : {}),
+      };
+
       return {
-        text: result.text,
+        text,
         rawContent: result.rawContent,
         toolCalls: result.toolCalls,
         requestId: result.requestId,
+        inference,
       };
     },
 

package/src/qvac/stream.test.ts

@@ -67,6 +67,31 @@ describe('consumeRun', () => {
     expect(out.truncated).toBe(true);
   });
 
+  it('stops forwarding and flags when thinking exceeds maxThinkingTokens', async () => {
+    const thinking: string[] = [];
+    let exceeded = 0;
+    // 8-char deltas ≈ 2 tokens each; budget 4 tokens trips after the 2nd.
+    const run = fakeRun(
+      [
+        { type: 'thinkingDelta', text: 'aaaaaaaa' },
+        { type: 'thinkingDelta', text: 'bbbbbbbb' },
+        { type: 'thinkingDelta', text: 'cccccccc' },
+        { type: 'contentDelta', text: 'should-not-arrive' },
+      ],
+      { contentText: '', toolCalls: [], raw: { fullText: '' }, stopReason: 'cancelled' },
+    );
+    const out = await consumeRun(run, {
+      onThinking: (t) => thinking.push(t),
+      maxThinkingTokens: 4,
+      onThinkingBudgetExceeded: () => {
+        exceeded += 1;
+      },
+    });
+    expect(exceeded).toBe(1);
+    expect(out.thinkingBudgetExceeded).toBe(true);
+    expect(thinking).toEqual(['aaaaaaaa', 'bbbbbbbb']); // stopped at the trip
+  });
+
   it('ignores delta events with no text', async () => {
     const tokens: string[] = [];
     const run = fakeRun(
@@ -76,4 +101,15 @@ describe('consumeRun', () => {
     await consumeRun(run, { onToken: (t) => tokens.push(t) });
     expect(tokens).toEqual(['hi']);
   });
+
+  it('measures first-token and total completion timing', async () => {
+    const ticks = [100, 145, 190];
+    const out = await consumeRun(
+      fakeRun([{ type: 'thinkingDelta', text: 'plan' }, { type: 'contentDelta', text: 'answer' }], {
+        contentText: 'answer',
+      }),
+      { now: () => ticks.shift() ?? 190 },
+    );
+    expect(out.timing).toEqual({ ttftMs: 45, durationMs: 90 });
+  });
 });