@kaleidorg/mind 0.5.1 → 0.6.0

package/src/funnel.mind.test.ts

@@ -0,0 +1,390 @@
+/**
+ * Desktop "mind" smoke tests — drive the SAME Funnel the desktop sidecar builds
+ * (apps/provider/src/index.ts: recipes [buyAssetChannel, kaleidoswapAtomic,
+ * assetSend, payments, receive] over the MCP tool surface) through each
+ * user-facing intent, end to end, with a SCRIPTED provider standing in for the
+ * on-device QVAC model.
+ *
+ * Why mind-level (not just MCP-level, which mcp.live.test.ts covers): the
+ * desktop "tool-less" bugs live in the wiring BETWEEN the brain and the tools —
+ * tier routing (fast/recipe/agentic), recipe orchestration, and agentic tool
+ * selection. These assert that, given a real tool surface, the mind:
+ *   - balance        → agentic → calls rln_get_balances, surfaces the balance
+ *   - list channels  → agentic → calls rln_list_channels
+ *   - buy via swap    → recipe  → quote → init → node → whitelist → execute (1 confirm)
+ *   - merchant near city → agentic → search_knowledge over the merchant corpus
+ *
+ * Fully deterministic (no node/model/maker), so it runs in CI. Live tool
+ * execution against a real node is the separate mcp.live.test.ts.
+ */
+import { describe, expect, it } from 'vitest';
+import { Funnel } from './funnel.js';
+import { ToolRegistry } from './tools/registry.js';
+import { InProcessToolSource } from './tools/in-process.js';
+import { merchantsToDocuments } from './knowledge/merchants.js';
+import { buyAssetChannelRecipe } from './recipe/buy-asset-channel.js';
+import { kaleidoswapAtomicRecipe } from './recipe/kaleidoswap-atomic.js';
+import { assetSendRecipe } from './recipe/asset-send.js';
+import { paymentsRecipe } from './recipe/payments.js';
+import { receiveRecipe } from './recipe/receive.js';
+import { loadSkillsDir, packagedSkillsDir } from './skills/loader.js';
+import type { Skill } from './skills/types.js';
+import type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+import type { ConfirmDecision, ToolCall } from './types.js';
+
+// The exact recipe set the desktop provider registers, in order. Order matters:
+// kaleidoswapAtomicRecipe is FIRST, so a plain "buy 1 USDT" on a funded node
+// routes to the atomic SWAP (BTC→USDT over existing liquidity). The
+// channel-onboarding recipe wins only for explicit channel/inbound/liquidity
+// phrasing, which the atomic matcher excludes. (See the routing tests below.)
+const DESKTOP_RECIPES = [
+  kaleidoswapAtomicRecipe,
+  buyAssetChannelRecipe,
+  assetSendRecipe,
+  paymentsRecipe,
+  receiveRecipe,
+];
+
+// ── A scripted provider: each script entry is one model turn. Returning tool
+//    calls makes the agentic engine execute them and ask for the next turn. ──
+function scripted(script: Array<{ text: string; toolCalls?: ToolCall[] }>): LLMProvider {
+  let turn = 0;
+  return {
+    name: 'scripted',
+    async runTurn(input: TurnInput): Promise<TurnOutput> {
+      const step = script[Math.min(turn, script.length - 1)];
+      turn += 1;
+      input.onToken?.(step.text);
+      return { text: step.text, rawContent: step.text, toolCalls: step.toolCalls ?? [], requestId: `req-${turn}` };
+    },
+  };
+}
+
+// ── Merchant corpus: real merchantsToDocuments transform over a small fixture,
+//    queried by city so "near Rome" surfaces the Rome places (not Milan). ──
+const MERCHANTS = [
+  { id: 'm1', name: 'Bitcoin Caffè', category: 'cafe', city: 'Rome', address: 'Via Roma 1', acceptedAssets: ['lightning', 'onchain'] },
+  { id: 'm2', name: 'Satoshi Pizzeria', category: 'restaurant', city: 'Milan', acceptedAssets: ['lightning'] },
+  { id: 'm3', name: 'Nakamoto Books', category: 'shop', city: 'Rome', address: 'Via Veneto 9', acceptedAssets: ['onchain'] },
+];
+const MERCHANT_DOCS = merchantsToDocuments(MERCHANTS);
+function searchMerchants(query: string): string {
+  const q = query.toLowerCase();
+  const hits = MERCHANT_DOCS.filter((d) => {
+    const city = String((d.metadata as { city?: string })?.city ?? '').toLowerCase();
+    return city.length > 0 && q.includes(city);
+  });
+  return hits.length ? hits.map((h, i) => `[${i + 1}] ${h.text}`).join('\n\n') : 'No relevant passages found.';
+}
+
+/**
+ * Build the desktop mind with canned MCP-named tools. Every call is recorded in
+ * `calls` (name + args, in execution order) so we can assert routing + sequence.
+ */
+function buildMind(
+  provider: LLMProvider,
+  opts: { skills?: Skill[]; log?: (m: string) => void } = {},
+): { funnel: Funnel; calls: Array<{ name: string; args: any }> } {
+  const calls: Array<{ name: string; args: any }> = [];
+  const tool = (name: string, response: any, spend = false) => ({
+    name,
+    description: '',
+    parameters: { type: 'object' as const, properties: {} },
+    requiresConfirmation: spend,
+    handler: async (a: Record<string, unknown>) => {
+      calls.push({ name, args: a });
+      return typeof response === 'function' ? response(a) : response;
+    },
+  });
+
+  const tools = new ToolRegistry([
+    new InProcessToolSource('wallet', [
+      // reads
+      tool('rln_get_balances', { lightning_balance_sat: 1_949_753, btc_onchain: { vanilla_spendable_sats: 100_000 } }),
+      tool('rln_list_channels', {
+        channels: [
+          { channel_id: '5d4487c8', capacity_sat: 1_000_000, outbound_balance_msat: 987_240_000, ready: true },
+          { channel_id: 'a1b2c3d4', capacity_sat: 1_000_000, outbound_balance_msat: 500_000_000, ready: true },
+        ],
+      }),
+      // atomic-swap chain (quote read; init/whitelist/execute are spends)
+      tool('kaleidoswap_get_quote', {
+        rfq_id: 'rfq-1',
+        from_asset: { asset_id: 'BTC', ticker: 'BTC', amount: 100_000 },
+        to_asset: { asset_id: 'rgb:USDT', ticker: 'USDT', amount: 1_000_000 },
+        from_amount_display: '100,000 sats',
+        to_amount_display: '1 USDT',
+        fee_display: '154 sats',
+      }),
+      tool('kaleidoswap_atomic_init', { swapstring: 'SWAP/abc/def', payment_hash: 'ph-1' }, /* spend */ true),
+      tool('rln_get_node_info', { pubkey: '030637ec' }),
+      tool('rln_atomic_taker', { ok: true }, /* spend */ true),
+      tool('kaleidoswap_atomic_execute', { status: 200, message: 'Swap executed successfully.' }, /* spend */ true),
+      // LSPS1 asset-channel onboarding (the rail "buy N USDT" routes to)
+      tool('kaleidoswap_lsp_quote_asset_channel', {
+        total_sat: 29_946,
+        btc_amount_sat: 13_807,
+        channel_fee_sat: 16_139,
+        expires_at: 0,
+      }),
+      tool('kaleidoswap_lsp_create_asset_channel', { order_id: 'cf2981c4', order_state: 'CREATED' }, /* spend */ true),
+      // knowledge (merchant discovery)
+      {
+        name: 'search_knowledge',
+        description: 'Search the knowledge base (merchants, docs) for relevant passages.',
+        parameters: { type: 'object' as const, properties: { query: { type: 'string' } }, required: ['query'] },
+        handler: async (a: Record<string, unknown>) => {
+          calls.push({ name: 'search_knowledge', args: a });
+          return searchMerchants(String(a.query ?? ''));
+        },
+      },
+    ]),
+  ]);
+
+  return {
+    funnel: new Funnel({ provider, tools, recipes: DESKTOP_RECIPES, maxTurns: 8, skills: opts.skills, log: opts.log }),
+    calls,
+  };
+}
+
+describe('desktop mind — balance', () => {
+  it('routes "what\'s my balance?" to the agentic tier and calls rln_get_balances', async () => {
+    const { funnel, calls } = buildMind(
+      scripted([
+        { text: '', toolCalls: [{ name: 'rln_get_balances', arguments: {} }] },
+        { text: 'You have 1,949,753 sats in Lightning.' },
+      ]),
+    );
+
+    const res = await funnel.runTurn("what's my balance?");
+
+    expect(res.tier).toBe('agentic');
+    expect(calls.map((c) => c.name)).toContain('rln_get_balances');
+    const exec = res.toolCalls?.find((c) => c.name === 'rln_get_balances');
+    expect((exec?.result as { lightning_balance_sat?: number })?.lightning_balance_sat).toBe(1_949_753);
+    expect(res.text).toBeTruthy();
+  });
+});
+
+describe('desktop mind — list channels', () => {
+  it('routes "list my channels" to the agentic tier and calls rln_list_channels', async () => {
+    const { funnel, calls } = buildMind(
+      scripted([
+        { text: '', toolCalls: [{ name: 'rln_list_channels', arguments: {} }] },
+        { text: 'You have 2 open channels.' },
+      ]),
+    );
+
+    const res = await funnel.runTurn('list my channels');
+
+    expect(res.tier).toBe('agentic');
+    expect(calls.map((c) => c.name)).toContain('rln_list_channels');
+    const exec = res.toolCalls?.find((c) => c.name === 'rln_list_channels');
+    expect((exec?.result as { channels?: unknown[] })?.channels).toHaveLength(2);
+  });
+});
+
+describe('desktop mind — buy assets via atomic swap', () => {
+  it('routes "swap … for usdt" to the atomic recipe and runs quote→init→node→whitelist→execute with ONE confirm', async () => {
+    // The recipe forces a model inference for slot extraction (forceModelExtract):
+    // the runner injects a synthetic `extract_request` tool; the model fills slots.
+    const provider: LLMProvider = {
+      name: 'extract',
+      async runTurn(input) {
+        if (input.tools?.some((t) => t.name === 'extract_request')) {
+          return {
+            text: '',
+            rawContent: '',
+            toolCalls: [
+              { id: 'ex1', name: 'extract_request', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 100_000, amount_side: 'from' } },
+            ],
+          };
+        }
+        return { text: '', rawContent: '', toolCalls: [] };
+      },
+    };
+
+    const { funnel, calls } = buildMind(provider);
+    const confirms: Array<{ name: string; summary?: string }> = [];
+
+    const res = await funnel.runTurn('swap 100000 sats for usdt', {
+      onConfirm: async (call): Promise<ConfirmDecision> => {
+        confirms.push({ name: call.name, summary: call.summary });
+        return { approved: true };
+      },
+    });
+
+    expect(res.tier).toBe('recipe');
+    expect(res.route).toBe('kaleidoswap-atomic');
+    // The full deterministic chain, in order.
+    expect(calls.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'kaleidoswap_atomic_init',
+      'rln_get_node_info',
+      'rln_atomic_taker',
+      'kaleidoswap_atomic_execute',
+    ]);
+    // init sources the asset ids + maker-unit amounts straight from the quote.
+    const init = calls.find((c) => c.name === 'kaleidoswap_atomic_init')!;
+    expect(init.args).toMatchObject({ rfq_id: 'rfq-1', from_asset: 'BTC', to_asset: 'rgb:USDT' });
+    // execute carries the node pubkey as taker_pubkey + the maker's payment_hash.
+    const exec = calls.find((c) => c.name === 'kaleidoswap_atomic_execute')!;
+    expect(exec.args).toMatchObject({ swapstring: 'SWAP/abc/def', taker_pubkey: '030637ec', payment_hash: 'ph-1' });
+    // EXACTLY ONE confirmation gate, fired before the first spend, with real numbers.
+    expect(confirms).toHaveLength(1);
+    expect(confirms[0]!.name).toBe('kaleidoswap_atomic_init');
+    expect(confirms[0]!.summary).toMatch(/swap/i);
+    expect(res.text).toMatch(/submitted|settling/i);
+  });
+
+  it('routes a plain "buy 1 usdt" to the ATOMIC swap (funded node), not channel onboarding', async () => {
+    // On a node with existing BTC liquidity, "buy 1 usdt" = swap BTC→USDT, NOT
+    // open a new channel. The model fills the implicit source (BTC) + buy leg.
+    const buyExtract: LLMProvider = {
+      name: 'extract',
+      async runTurn(input) {
+        if (input.tools?.some((t) => t.name === 'extract_request')) {
+          return {
+            text: '',
+            rawContent: '',
+            toolCalls: [
+              { id: 'ex1', name: 'extract_request', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 1, amount_side: 'to' } },
+            ],
+          };
+        }
+        return { text: '', rawContent: '', toolCalls: [] };
+      },
+    };
+
+    const { funnel, calls } = buildMind(buyExtract);
+    const res = await funnel.runTurn('buy 1 usdt', { onConfirm: async () => ({ approved: true }) });
+
+    expect(res.tier).toBe('recipe');
+    expect(res.route).toBe('kaleidoswap-atomic');
+    expect(calls.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'kaleidoswap_atomic_init',
+      'rln_get_node_info',
+      'rln_atomic_taker',
+      'kaleidoswap_atomic_execute',
+    ]);
+  });
+
+  it('routes explicit inbound-liquidity phrasing to channel onboarding', async () => {
+    // The channel-onboarding rail still wins for explicit channel/inbound
+    // phrasing (the atomic matcher excludes channel/inbound/liquidity).
+    const { funnel } = buildMind(scripted([{ text: '' }]));
+    const res = await funnel.runTurn('get 100 usdt inbound liquidity', {
+      onConfirm: async () => ({ approved: false }),
+    });
+    expect(res.tier).toBe('recipe');
+    expect(res.route).toBe(buyAssetChannelRecipe.name);
+  });
+});
+
+describe('desktop mind — find a merchant near a city', () => {
+  it('routes "where can I spend bitcoin near Rome" to agentic search_knowledge and surfaces the Rome merchants', async () => {
+    const { funnel, calls } = buildMind(
+      scripted([
+        { text: '', toolCalls: [{ name: 'search_knowledge', arguments: { query: 'bitcoin merchants in Rome' } }] },
+        { text: 'Near Rome you can spend at Bitcoin Caffè and Nakamoto Books.' },
+      ]),
+    );
+
+    const res = await funnel.runTurn('where can I spend bitcoin near Rome?');
+
+    expect(res.tier).toBe('agentic');
+    const sk = calls.find((c) => c.name === 'search_knowledge');
+    expect(sk).toBeTruthy();
+    expect(String(sk!.args.query)).toMatch(/rome/i);
+    // Real retrieval over merchantsToDocuments: Rome places in, Milan out.
+    const result = String(res.toolCalls?.find((c) => c.name === 'search_knowledge')?.result ?? '');
+    expect(result).toMatch(/Bitcoin Caffè/);
+    expect(result).toMatch(/Nakamoto Books/);
+    expect(result).not.toMatch(/Satoshi Pizzeria|Milan/);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Skill scoping — the layer that actually caused the desktop "I cannot check
+// your balance, the tool is not available" bug. The agentic tier filters the
+// model's tools to the SELECTED SKILL's `tools:` allowlist (engine.ts honours
+// allowedTools). If a skill's allowlist names tools that don't exist on the
+// host (e.g. `get_balances` while the desktop MCP exposes `rln_get_balances`),
+// the real tool is filtered out and the model goes tool-less. These load the
+// REAL desktop skills and assert the needed tool survives scoping.
+// (The scenario tests above ran skill-LESS, which is exactly why they missed it.)
+// ─────────────────────────────────────────────────────────────────────
+describe('desktop mind — skill scoping (real skills)', () => {
+  const SKILLS = loadSkillsDir(packagedSkillsDir());
+
+  it('loads the real desktop skills', () => {
+    expect(SKILLS.length).toBeGreaterThan(0);
+    expect(SKILLS.map((s) => s.name)).toEqual(
+      expect.arrayContaining(['wallet-assistant', 'rgb-lightning-node', 'kaleido-trading']),
+    );
+  });
+
+  it('wallet-assistant (triggers on "balance") exposes the real rln_*/wdk_* tool names', () => {
+    const wallet = SKILLS.find((s) => s.name === 'wallet-assistant')!;
+    expect(wallet.tools).toEqual(expect.arrayContaining(['rln_get_balances', 'wdk_get_balances']));
+    expect(wallet.tools).toEqual(expect.arrayContaining(['rln_get_address', 'rln_send_btc', 'rln_create_ln_invoice']));
+  });
+
+  it('rgb-lightning-node (triggers on "channels") exposes only canonical rln_* tools', () => {
+    const node = SKILLS.find((s) => s.name === 'rgb-lightning-node')!;
+    expect(node.tools).toContain('rln_list_channels');
+    expect(node.tools?.every((tool) => tool.startsWith('rln_'))).toBe(true);
+  });
+
+  it('kaleido-trading drops the phantom kaleidoswap_get_nodeinfo / get_order_history names', () => {
+    const trading = SKILLS.find((s) => s.name === 'kaleido-trading')!;
+    expect(trading.tools).not.toContain('kaleidoswap_get_nodeinfo');
+    expect(trading.tools).not.toContain('kaleidoswap_get_order_history');
+    expect(trading.tools).toEqual(expect.arrayContaining(['kaleidoswap_get_quote', 'kaleidoswap_place_order']));
+    expect(trading.tools).not.toEqual(
+      expect.arrayContaining([
+        'kaleidoswap_get_spreads',
+        'kaleidoswap_get_open_orders',
+        'kaleidoswap_cancel_order',
+        'kaleidoswap_get_position',
+      ]),
+    );
+  });
+
+  it('balance through the FULL mind WITH skills loaded still reaches rln_get_balances', async () => {
+    const logs: string[] = [];
+    const { funnel, calls } = buildMind(
+      scripted([
+        { text: '', toolCalls: [{ name: 'rln_get_balances', arguments: {} }] },
+        { text: 'You have 1,949,753 sats.' },
+      ]),
+      { skills: SKILLS, log: (m) => logs.push(m) },
+    );
+
+    const res = await funnel.runTurn("what's my balance?");
+
+    expect(res.tier).toBe('agentic');
+    // wallet-assistant is selected AND rln_get_balances survives its scoping…
+    const agenticLine = logs.find((l) => l.startsWith('tier=agentic'));
+    expect(agenticLine).toMatch(/skill=wallet-assistant/);
+    expect(agenticLine).toMatch(/rln_get_balances/);
+    // …and the tool actually executes (not narrated).
+    expect(calls.map((c) => c.name)).toContain('rln_get_balances');
+  });
+
+  it('list channels through the FULL mind WITH skills loaded reaches rln_list_channels', async () => {
+    const { funnel, calls } = buildMind(
+      scripted([
+        { text: '', toolCalls: [{ name: 'rln_list_channels', arguments: {} }] },
+        { text: 'You have 2 channels.' },
+      ]),
+      { skills: SKILLS },
+    );
+
+    const res = await funnel.runTurn('list my channels');
+
+    expect(res.tier).toBe('agentic');
+    expect(calls.map((c) => c.name)).toContain('rln_list_channels');
+  });
+});

package/src/funnel.ts

@@ -302,6 +302,20 @@ export class Funnel {
     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).

package/src/index.ts

@@ -186,3 +186,44 @@ export type { Skill, SkillReference, SkillSelector } from './skills/types.js';
 
 export { TurnLogger, defaultMask } from './logger.js';
 export type { TurnLog, Device, LoggerIO, LoggerOptions } from './logger.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/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' },
   },
   {

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

@@ -18,6 +18,7 @@
  */
 import type * as QvacSdk from '@qvac/sdk';
 import type { 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,13 +119,28 @@ 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);
+
       return {
-        text: result.text,
+        text,
         rawContent: result.rawContent,
         toolCalls: result.toolCalls,
         requestId: result.requestId,

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(