@kaleidorg/mind 0.7.0 → 0.8.0

package/src/providers/openai.ts

@@ -0,0 +1,282 @@
+/**
+ * createOpenAICompatibleProvider — an LLMProvider over any server that speaks
+ * the OpenAI Chat Completions API with tool calling: Ollama, llama.cpp
+ * `llama-server`, LM Studio, vLLM, `qvac serve`, or a hosted API.
+ *
+ * No dependencies: it uses `fetch` (pass your own for older runtimes or tests).
+ *
+ * The Engine keeps history as plain `{ role, content }` messages. Tool calls
+ * are written into the assistant's `rawContent` as `<tool_call>{json}</tool_call>`
+ * blocks and turned back into `tool_calls` / `tool_call_id` pairs on the next
+ * request, so the server always receives a valid tool-calling conversation.
+ */
+import type { Message, ToolCall } from '../types.js';
+import type { InferenceMetrics, LLMProvider, ToolCallError, ToolChoice, TurnInput, TurnOutput } from './types.js';
+import { extractTextToolCalls } from '../qvac/parse.js';
+import { toolParametersSchema } from '../qvac/tools.js';
+
+export interface OpenAICompatibleOptions {
+  /** API root including the version, e.g. `http://localhost:11434/v1`. */
+  baseUrl: string;
+  /** Model name as the server knows it, e.g. `qwen3.5:4b`. */
+  model: string;
+  /** Sent as `Authorization: Bearer …` when set. */
+  apiKey?: string;
+  defaultTemperature?: number;
+  defaultMaxTokens?: number;
+  /** Stream tokens (default true). Set false for servers without SSE. */
+  stream?: boolean;
+  /** Extra JSON merged into every request body (e.g. `{ reasoning_effort: 'low' }`). */
+  extraBody?: Record<string, unknown>;
+  /** Extra request headers. */
+  headers?: Record<string, string>;
+  /** Reasoning deltas (`reasoning_content` / `reasoning`), when the server sends them. */
+  onThinking?: (token: string) => void;
+  fetch?: typeof fetch;
+}
+
+export interface OpenAITurnInput extends TurnInput {
+  temperature?: number;
+  maxTokens?: number;
+}
+
+type WireMessage =
+  | { role: 'system' | 'user'; content: string }
+  | { role: 'assistant'; content: string | null; tool_calls?: WireToolCall[] }
+  | { role: 'tool'; content: string; tool_call_id: string };
+
+interface WireToolCall {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+}
+
+const TOOL_CALL_BLOCK = /<tool_call\b[^>]*>[\s\S]*?<\/tool_call>/gi;
+
+/** The assistant frame the Engine stores: visible text plus one block per call. */
+export function encodeToolCalls(text: string, calls: ToolCall[]): string {
+  const blocks = calls.map((c) => `<tool_call>${JSON.stringify({ name: c.name, arguments: c.arguments })}</tool_call>`);
+  return [text.trim(), ...blocks].filter(Boolean).join('\n');
+}
+
+/** Engine history → Chat Completions messages, with ids pairing calls and results. */
+export function toWireMessages(messages: Message[], system?: string): WireMessage[] {
+  const out: WireMessage[] = system ? [{ role: 'system', content: system }] : [];
+  let pending: string[] = [];
+  messages.forEach((m, i) => {
+    if (m.role === 'assistant') {
+      const calls = extractTextToolCalls(m.content);
+      const text = m.content.replace(TOOL_CALL_BLOCK, '').trim();
+      pending = calls.map((_, j) => `call_${i}_${j}`);
+      out.push(
+        calls.length
+          ? {
+              role: 'assistant',
+              content: text || null,
+              tool_calls: calls.map((c, j) => ({
+                id: pending[j]!,
+                type: 'function',
+                function: { name: c.name, arguments: JSON.stringify(c.arguments) },
+              })),
+            }
+          : { role: 'assistant', content: m.content },
+      );
+    } else if (m.role === 'tool') {
+      const id = pending.shift();
+      // A tool message with no call to answer (e.g. a parse-error note) would
+      // be rejected by the server; send it as user context instead.
+      out.push(id ? { role: 'tool', content: m.content, tool_call_id: id } : { role: 'user', content: `Tool result: ${m.content}` });
+    } else {
+      pending = [];
+      out.push({ role: m.role as 'system' | 'user', content: m.content });
+    }
+  });
+  return out;
+}
+
+function wireToolChoice(choice: ToolChoice | undefined): unknown {
+  if (!choice) return undefined;
+  if (choice === 'auto' || choice === 'none' || choice === 'required') return choice;
+  return { type: 'function', function: { name: choice } };
+}
+
+interface Accumulated {
+  content: string;
+  calls: Map<number, { id?: string; name: string; args: string }>;
+  finishReason?: string;
+  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+}
+
+function absorbDelta(acc: Accumulated, delta: any, onToken?: (t: string) => void, onThinking?: (t: string) => void) {
+  if (typeof delta?.content === 'string' && delta.content) {
+    acc.content += delta.content;
+    onToken?.(delta.content);
+  }
+  const reasoning = delta?.reasoning_content ?? delta?.reasoning;
+  if (typeof reasoning === 'string' && reasoning) onThinking?.(reasoning);
+  for (const tc of delta?.tool_calls ?? []) {
+    const index = typeof tc.index === 'number' ? tc.index : acc.calls.size;
+    const cur = acc.calls.get(index) ?? { name: '', args: '' };
+    if (tc.id) cur.id = tc.id;
+    if (tc.function?.name) cur.name += tc.function.name;
+    if (tc.function?.arguments) {
+      cur.args += typeof tc.function.arguments === 'string' ? tc.function.arguments : JSON.stringify(tc.function.arguments);
+    }
+    acc.calls.set(index, cur);
+  }
+}
+
+async function readSse(body: ReadableStream<Uint8Array>, onEvent: (data: string) => void): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let nl: number;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line.startsWith('data:')) onEvent(line.slice(5).trim());
+    }
+  }
+  const last = buffer.trim();
+  if (last.startsWith('data:')) onEvent(last.slice(5).trim());
+}
+
+export function createOpenAICompatibleProvider(options: OpenAICompatibleOptions): LLMProvider {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  if (!doFetch) throw new Error('No fetch available; pass options.fetch');
+  const url = `${options.baseUrl.replace(/\/+$/, '')}/chat/completions`;
+  const inflight = new Map<string, AbortController>();
+  let seq = 0;
+
+  return {
+    name: 'openai-compatible',
+
+    async runTurn(input: OpenAITurnInput): Promise<TurnOutput> {
+      const requestId = `oai-${Date.now().toString(36)}-${++seq}`;
+      const controller = new AbortController();
+      inflight.set(requestId, controller);
+      const onAbort = () => controller.abort();
+      input.signal?.addEventListener('abort', onAbort, { once: true });
+      if (input.signal?.aborted) controller.abort();
+
+      const stream = options.stream ?? true;
+      const temperature = input.temperature ?? options.defaultTemperature;
+      const maxTokens = input.maxTokens ?? options.defaultMaxTokens;
+      const tools = input.tools.map((t) => ({
+        type: 'function' as const,
+        function: { name: t.name, description: t.description ?? '', parameters: toolParametersSchema(t) },
+      }));
+      const toolChoice = tools.length ? wireToolChoice(input.toolChoice) : undefined;
+      const body = {
+        model: options.model,
+        messages: toWireMessages(input.messages, input.system),
+        stream,
+        ...(stream ? { stream_options: { include_usage: true } } : {}),
+        ...(temperature !== undefined ? { temperature } : {}),
+        ...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
+        ...(tools.length ? { tools } : {}),
+        ...(toolChoice ? { tool_choice: toolChoice } : {}),
+        ...options.extraBody,
+      };
+
+      const startedAt = Date.now();
+      let firstTokenAt: number | undefined;
+      const mark = (f?: (t: string) => void) => (t: string) => {
+        firstTokenAt ??= Date.now();
+        f?.(t);
+      };
+      const acc: Accumulated = { content: '', calls: new Map() };
+      let cancelled = false;
+      try {
+        const res = await doFetch(url, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
+            ...options.headers,
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+        if (!res.ok) {
+          const detail = await res.text().catch(() => '');
+          throw new Error(`${options.baseUrl} returned ${res.status}: ${detail.slice(0, 300)}`);
+        }
+        if (stream && res.body) {
+          await readSse(res.body, (data) => {
+            if (data === '[DONE]') return;
+            let chunk: any;
+            try {
+              chunk = JSON.parse(data);
+            } catch {
+              return;
+            }
+            if (chunk.usage) acc.usage = chunk.usage;
+            const choice = chunk.choices?.[0];
+            if (!choice) return;
+            absorbDelta(acc, choice.delta, mark(input.onToken), mark(options.onThinking));
+            if (choice.finish_reason) acc.finishReason = choice.finish_reason;
+          });
+        } else {
+          const json: any = await res.json();
+          const choice = json.choices?.[0];
+          absorbDelta(acc, { ...choice?.message, tool_calls: choice?.message?.tool_calls?.map((c: any, index: number) => ({ index, ...c })) }, input.onToken, options.onThinking);
+          acc.finishReason = choice?.finish_reason;
+          acc.usage = json.usage;
+        }
+      } catch (err) {
+        if (!controller.signal.aborted) throw err;
+        cancelled = true;
+      } finally {
+        inflight.delete(requestId);
+        input.signal?.removeEventListener('abort', onAbort);
+      }
+
+      const toolCalls: ToolCall[] = [];
+      const toolErrors: ToolCallError[] = [];
+      for (const c of [...acc.calls.entries()].sort(([a], [b]) => a - b).map(([, v]) => v)) {
+        if (!c.name) continue;
+        try {
+          const args = c.args.trim() ? JSON.parse(c.args) : {};
+          toolCalls.push({ ...(c.id ? { id: c.id } : {}), name: c.name, arguments: args && typeof args === 'object' ? args : {} });
+        } catch {
+          toolErrors.push({ code: 'PARSE_ERROR', message: `arguments for ${c.name} are not valid JSON`, raw: c.args });
+        }
+      }
+      // Models that ignore the tools API sometimes write the call as text.
+      if (!toolCalls.length && !toolErrors.length) {
+        for (const c of extractTextToolCalls(acc.content)) toolCalls.push(c);
+      }
+      const text = acc.content.replace(TOOL_CALL_BLOCK, '').trim();
+
+      const truncated = acc.finishReason === 'length';
+      const inference: InferenceMetrics = {
+        requestId,
+        durationMs: Date.now() - startedAt,
+        status: cancelled ? 'cancelled' : truncated ? 'truncated' : 'completed',
+        ...(firstTokenAt !== undefined ? { ttftMs: firstTokenAt - startedAt } : {}),
+        ...(acc.usage?.prompt_tokens !== undefined ? { promptTokens: acc.usage.prompt_tokens } : {}),
+        ...(acc.usage?.completion_tokens !== undefined ? { completionTokens: acc.usage.completion_tokens } : {}),
+        ...(acc.usage?.total_tokens !== undefined ? { totalTokens: acc.usage.total_tokens } : {}),
+        ...(acc.finishReason ? { stopReason: acc.finishReason } : {}),
+      };
+
+      return {
+        text,
+        rawContent: encodeToolCalls(text, toolCalls),
+        toolCalls,
+        ...(toolErrors.length && !toolCalls.length ? { toolErrors } : {}),
+        requestId,
+        inference,
+      };
+    },
+
+    async cancel(requestId: string): Promise<void> {
+      inflight.get(requestId)?.abort();
+    },
+  };
+}

package/src/providers/types.ts

@@ -17,11 +17,26 @@ export interface TurnInput {
   tools: ToolDef[];
   /** System prompt, when not already present as a message. */
   system?: string;
+  /**
+   * `'required'` forces a tool call, a tool name forces that tool, `'none'`
+   * forbids tools. Omit for the model's own choice. Ignored when `tools` is
+   * empty or the provider has no such control.
+   */
+  toolChoice?: ToolChoice;
   /** Visible content tokens as they stream. */
   onToken?: (token: string) => void;
   signal?: AbortSignal;
 }
 
+export type ToolChoice = 'auto' | 'none' | 'required' | (string & {});
+
+/** A tool-call region the model emitted that the provider could not turn into a call. */
+export interface ToolCallError {
+  code: 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'UNKNOWN_TOOL' | (string & {});
+  message: string;
+  raw?: string;
+}
+
 /** Judge-auditable metrics for one provider inference request. */
 export interface InferenceMetrics {
   requestId?: string;
@@ -50,10 +65,17 @@ export interface TurnOutput {
   rawContent: string;
   /** Tool calls the model requested this turn (empty ⇒ final answer). */
   toolCalls: ToolCall[];
+  /** Tool-call attempts that failed to parse or validate this turn. */
+  toolErrors?: ToolCallError[];
   /** Provider request id, for cancellation. */
   requestId?: string;
   /** Optional local-inference receipt. Hosts may persist this as JSONL evidence. */
   inference?: InferenceMetrics;
+  /**
+   * True when the turn produced no visible answer because it ran out of budget
+   * (e.g. reasoning used the whole output cap). `text` may hold a placeholder.
+   */
+  incomplete?: boolean;
 }
 
 export interface LLMProvider {

package/src/qvac/config.ts

@@ -30,7 +30,7 @@ export const LOCAL_LLM_CONFIG_GPU = {
 
 /**
  * Delegated to a desktop provider — it has the RAM to run a big context, so give
- * the agentic prompt plenty of room (Qwen3-600M supports up to 32k). 2048
+ * the agentic prompt plenty of room (Qwen3.5 supports far more than this). 2048
  * overflowed with the system prompt + tool/skill definitions alone.
  */
 export const DELEGATE_LLM_CONFIG = {

package/src/qvac/index.ts

@@ -23,6 +23,16 @@ export {
   normalizeWhisperLang,
 } from './config.js';
 
+export {
+  QWEN35_MODELS,
+  DEFAULT_MODEL_ID,
+  DEFAULT_SMALL_DEVICE_MODEL_ID,
+  DEFAULT_QVAC_MODEL,
+  DEFAULT_SMALL_DEVICE_QVAC_MODEL,
+  getRecommendedModel,
+  type RecommendedModel,
+} from './models.js';
+
 export {
   finalToTurn,
   type QvacFinalLike,

package/src/qvac/models.ts

@@ -0,0 +1,98 @@
+/**
+ * Recommended local models. Plain data (no SDK import): `qvacConstant` is the
+ * name of the matching @qvac/sdk registry export (present since @qvac/sdk
+ * 0.13.1), `hfRepo`/`hfFile` the same GGUF on Hugging Face for hosts that
+ * download directly. Sizes are the exact file sizes.
+ */
+
+export interface RecommendedModel {
+  id: string;
+  family: string;
+  displayName: string;
+  /** Name of the @qvac/sdk model constant, e.g. `QWEN3_5_4B_MULTIMODAL_Q4_K_M`. */
+  qvacConstant: string;
+  quant: string;
+  sizeBytes: number;
+  hfRepo: string;
+  hfFile: string;
+  /** Rough RAM needed to run it with the agent's context window. */
+  ramHintGb: number;
+  notes: string;
+}
+
+export const QWEN35_MODELS: readonly RecommendedModel[] = [
+  {
+    id: 'qwen3.5-0.8b-q4_k_m',
+    family: 'qwen3.5',
+    displayName: 'Qwen 3.5 · 0.8B',
+    qvacConstant: 'QWEN3_5_0_8B_MULTIMODAL_Q4_K_M',
+    quant: 'Q4_K_M',
+    sizeBytes: 532_517_120,
+    hfRepo: 'unsloth/Qwen3.5-0.8B-GGUF',
+    hfFile: 'Qwen3.5-0.8B-Q4_K_M.gguf',
+    ramHintGb: 1.5,
+    notes: 'Smoke tests only. Loops on wallet actions in our signet bench; fine for chat and single read-only calls.',
+  },
+  {
+    id: 'qwen3.5-2b-q4_k_m',
+    family: 'qwen3.5',
+    displayName: 'Qwen 3.5 · 2B',
+    qvacConstant: 'QWEN3_5_2B_MULTIMODAL_Q4_K_M',
+    quant: 'Q4_K_M',
+    sizeBytes: 1_280_835_840,
+    hfRepo: 'unsloth/Qwen3.5-2B-GGUF',
+    hfFile: 'Qwen3.5-2B-Q4_K_M.gguf',
+    ramHintGb: 3,
+    notes: 'Recommended default. Passed all 7 wallet tasks of our signet RGB bench at 45–150 s per question on an M4 laptop; also fits phones.',
+  },
+  {
+    id: 'qwen3.5-4b-q4_k_m',
+    family: 'qwen3.5',
+    displayName: 'Qwen 3.5 · 4B',
+    qvacConstant: 'QWEN3_5_4B_MULTIMODAL_Q4_K_M',
+    quant: 'Q4_K_M',
+    sizeBytes: 2_740_937_888,
+    hfRepo: 'unsloth/Qwen3.5-4B-GGUF',
+    hfFile: 'Qwen3.5-4B-Q4_K_M.gguf',
+    ramHintGb: 5,
+    notes: 'Same correctness as 2B in our bench, about twice as slow (105–330 s per question on an M4). Pick it for longer free-form answers.',
+  },
+  {
+    id: 'qwen3.5-9b-q4_k_m',
+    family: 'qwen3.5',
+    displayName: 'Qwen 3.5 · 9B',
+    qvacConstant: 'QWEN3_5_9B_MULTIMODAL_Q4_K_M',
+    quant: 'Q4_K_M',
+    sizeBytes: 5_680_522_464,
+    hfRepo: 'unsloth/Qwen3.5-9B-GGUF',
+    hfFile: 'Qwen3.5-9B-Q4_K_M.gguf',
+    ramHintGb: 9,
+    notes: 'Needs 16 GB of RAM. Slow for interactive use (180–690 s per question on an M4); for unattended multi-step tasks.',
+  },
+  {
+    id: 'qwen3.6-35b-a3b-q4_k_m',
+    family: 'qwen3.6',
+    displayName: 'Qwen 3.6 · 35B-A3B (MoE)',
+    qvacConstant: 'QWEN3_6_35B_A3B_MULTIMODAL_Q4_K_M',
+    quant: 'UD-Q4_K_M',
+    sizeBytes: 22_134_528_992,
+    hfRepo: 'unsloth/Qwen3.6-35B-A3B-GGUF',
+    hfFile: 'Qwen3.6-35B-A3B-UD-Q4_K_M.gguf',
+    ramHintGb: 26,
+    notes: 'Big machines only (32 GB+). MoE with ~3B active parameters: best quality, 22 GB download.',
+  },
+];
+
+/** Default model for every host (provider sidecar, CLI, examples). */
+export const DEFAULT_MODEL_ID = 'qwen3.5-2b-q4_k_m';
+/** Default model for phones and other small devices. */
+export const DEFAULT_SMALL_DEVICE_MODEL_ID = 'qwen3.5-2b-q4_k_m';
+
+export function getRecommendedModel(id: string): RecommendedModel | undefined {
+  return QWEN35_MODELS.find((m) => m.id === id);
+}
+
+/** @qvac/sdk constant name of the default, e.g. for `sdk[DEFAULT_QVAC_MODEL]`. */
+export const DEFAULT_QVAC_MODEL = getRecommendedModel(DEFAULT_MODEL_ID)!.qvacConstant;
+/** @qvac/sdk constant name of the small-device default. */
+export const DEFAULT_SMALL_DEVICE_QVAC_MODEL = getRecommendedModel(DEFAULT_SMALL_DEVICE_MODEL_ID)!.qvacConstant;

package/src/qvac/parse.test.ts

@@ -114,6 +114,13 @@ describe('finalToTurn', () => {
       ]);
     });
 
+    it('recovers a Qwen3.5 XML-style call', () => {
+      const calls = extractTextToolCalls(
+        '<tool_call>\n<function=rln_issue_asset>\n<parameter=name>\nHack\n</parameter>\n<parameter=amount>\n1000\n</parameter>\n</function>\n</tool_call>',
+      );
+      expect(calls).toEqual([{ name: 'rln_issue_asset', arguments: { name: 'Hack', amount: 1000 } }]);
+    });
+
     it('returns [] for plain prose', () => {
       expect(extractTextToolCalls('just a normal answer')).toEqual([]);
     });

package/src/qvac/parse.ts

@@ -4,6 +4,7 @@
  * is testable without loading a model, and so the same mapping runs on mobile,
  * desktop, and the eval harness.
  */
+import type { ToolCallError } from '../providers/types.js';
 import { cleanAssistantVisibleText } from './text.js';
 
 /**
@@ -32,6 +33,8 @@ export interface QvacFinalLike {
   raw?: { fullText?: string };
   /** Tool calls the model requested this turn (empty ⇒ final answer). */
   toolCalls?: Array<{ id?: string; name: string; arguments?: Record<string, unknown> }>;
+  /** Tool-call regions that failed to parse or validate (QVAC 0.20+; omitted when none). */
+  toolErrors?: ToolCallError[];
   /**
    * Why generation stopped: `"length"` when the token budget is exhausted,
    * `"cancelled"` on abort, `"eos"`/`"stopSequence"`/`undefined` on a natural stop. We surface
@@ -49,6 +52,8 @@ export interface ParsedTurn {
   rawContent: string;
   /** Tool calls the model requested (arguments defaulted to `{}`). */
   toolCalls: Array<{ id?: string; name: string; arguments: Record<string, unknown> }>;
+  /** Tool-call attempts the SDK could not parse, when no call was recovered from text. */
+  toolErrors?: ToolCallError[];
   /** True when generation was cut off by the token budget (incomplete output). */
   truncated: boolean;
   /** Raw stop reason from the SDK, when provided. */
@@ -89,6 +94,31 @@ function parseCallObject(
   return null;
 }
 
+/**
+ * Parse Qwen3.5's XML call body:
+ * `<function=name><parameter=key>value</parameter>…</function>`. Values that
+ * read as JSON (numbers, booleans, arrays, objects) are decoded; the rest stay
+ * strings.
+ */
+function parseXmlCall(s: string): { name: string; arguments: Record<string, unknown> } | null {
+  const fn = s.match(/<function=([^>\s]+)\s*>([\s\S]*?)(?:<\/function>|$)/i);
+  if (!fn?.[1]) return null;
+  const args: Record<string, unknown> = {};
+  for (const m of (fn[2] ?? '').matchAll(/<parameter=([^>\s]+)\s*>([\s\S]*?)<\/parameter>/gi)) {
+    const raw = (m[2] ?? '').trim();
+    let value: unknown = raw;
+    if (/^(-?\d+(\.\d+)?|true|false|null|\[[\s\S]*\]|\{[\s\S]*\})$/.test(raw)) {
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        value = raw;
+      }
+    }
+    args[m[1]!] = value;
+  }
+  return { name: fn[1], arguments: args };
+}
+
 /**
  * Recover tool calls a model emitted as PLAIN TEXT instead of structured frames
  * — `<tool_call>{"name":…,"arguments":…}</tool_call>` (Qwen/Hermes) or a bare
@@ -101,7 +131,8 @@ export function extractTextToolCalls(
 ): Array<{ name: string; arguments: Record<string, unknown> }> {
   const calls: Array<{ name: string; arguments: Record<string, unknown> }> = [];
   for (const m of text.matchAll(/<tool_call\b[^>]*>([\s\S]*?)<\/tool_call>/gi)) {
-    const c = parseCallObject(m[1] ?? '');
+    const body = m[1] ?? '';
+    const c = parseCallObject(body) ?? parseXmlCall(body);
     if (c) calls.push(c);
   }
   if (calls.length) return calls;
@@ -139,6 +170,7 @@ export function finalToTurn(final: QvacFinalLike, streamed = ''): ParsedTurn {
     text,
     rawContent: final.raw?.fullText ?? rawText,
     toolCalls,
+    ...(toolCalls.length === 0 && final.toolErrors?.length ? { toolErrors: final.toolErrors } : {}),
     truncated: final.stopReason === 'length',
     stopReason: final.stopReason,
     stats: final.stats,

package/src/qvac/provider.test.ts

@@ -100,7 +100,7 @@ describe('createQvacProvider.runTurn', () => {
     const cancel = vi.fn(async () => {});
     const { fn } = fakeCompletion(
       { contentText: '', toolCalls: [], raw: { fullText: '' }, stopReason: 'cancelled' },
-      [{ type: 'thinkingDelta', text: 'z'.repeat(40) }], // ~10 tokens, budget 4
+      [{ type: 'thinkingDelta', text: 'z'.repeat(400) }], // ~100 tokens, budget 4 (+ backstop headroom)
     );
     const p = createQvacProvider({
       completion: fn as any,
@@ -113,6 +113,39 @@ describe('createQvacProvider.runTurn', () => {
     expect(out.text).toMatch(/thinking budget/i);
   });
 
+  it('sends the thinking cap as the SDK reasoning_budget', async () => {
+    const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1', maxThinkingTokens: 128 });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(calls[0].generationParams).toEqual({ reasoning_budget: 128 });
+  });
+
+  it('keeps the reasoning budget below the output cap', async () => {
+    const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1', defaultMaxTokens: 512, maxThinkingTokens: 512 });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(calls[0].generationParams).toEqual({ predict: 512, reasoning_budget: 256 });
+  });
+
+  it('forwards toolChoice only when tools are present', async () => {
+    const tool = { name: 'get_balance', description: 'b', parameters: { type: 'object', properties: {} } };
+    const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [tool as any], toolChoice: 'required' });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [], toolChoice: 'required' });
+    expect(calls[0].generationParams).toEqual({ tool_choice: 'required' });
+    expect(calls[1].generationParams).toBeUndefined();
+  });
+
+  it('returns toolErrors when the model emitted a tool call that did not parse', async () => {
+    const toolErrors = [{ code: 'PARSE_ERROR', message: 'unterminated string', raw: '{"ticker":"HCK' }];
+    const { fn } = fakeCompletion({ contentText: '', toolCalls: [], toolErrors, raw: { fullText: '<tool_call>{"ticker":"HCK' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(out.toolCalls).toEqual([]);
+    expect(out.toolErrors).toEqual(toolErrors);
+  });
+
   it('returns a cancelled turn when the SDK rejects final on abort', async () => {
     const cancel = vi.fn(async () => {});
     const fn = () => ({

package/src/qvac/provider.ts

@@ -41,10 +41,11 @@ export interface QvacProviderOptions {
   /** 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.
+   * Cap `<think>` reasoning at this many TOKENS (not seconds — tok/s varies).
+   * Sent as the SDK's `reasoning_budget`, so the model closes its reasoning and
+   * answers. If the stream still runs well past 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. */
@@ -93,13 +94,23 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
       // when a value is set so a host that passes neither keeps SDK defaults.
       const temp = input.temperature ?? options.defaultTemperature;
       const predict = input.maxTokens ?? options.defaultMaxTokens;
-      const generationParams =
-        temp !== undefined || predict !== undefined
-          ? {
-              ...(temp !== undefined ? { temp } : {}),
-              ...(predict !== undefined ? { predict } : {}),
-            }
-          : undefined;
+      // A thinking budget at or above the output cap never binds: the model can
+      // spend the whole turn reasoning and return no answer. Keep half for it.
+      const thinkingCap = input.maxThinkingTokens ?? options.maxThinkingTokens;
+      const maxThinkingTokens =
+        thinkingCap !== undefined && predict !== undefined && thinkingCap >= predict
+          ? Math.floor(predict / 2)
+          : thinkingCap;
+      // `tool_choice` is only meaningful with tools; the SDK rejects a named
+      // choice that isn't among them.
+      const toolChoice = tools && input.toolChoice ? input.toolChoice : undefined;
+      const generationParamsRaw = {
+        ...(temp !== undefined ? { temp } : {}),
+        ...(predict !== undefined ? { predict } : {}),
+        ...(maxThinkingTokens !== undefined ? { reasoning_budget: maxThinkingTokens } : {}),
+        ...(toolChoice ? { tool_choice: toolChoice } : {}),
+      };
+      const generationParams = Object.keys(generationParamsRaw).length ? generationParamsRaw : undefined;
 
       const run = options.completion({
         modelId,
@@ -129,11 +140,13 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         }
       }
 
-      const maxThinkingTokens = input.maxThinkingTokens ?? options.maxThinkingTokens;
       const result = await consumeRun(run, {
         onToken: input.onToken,
         onThinking: input.onThinking ?? options.onThinking,
-        maxThinkingTokens,
+        // Backstop only: the SDK enforces the budget itself, and our count is a
+        // char-based estimate, so leave headroom before cancelling.
+        maxThinkingTokens:
+          maxThinkingTokens === undefined ? undefined : Math.ceil(maxThinkingTokens * 1.25) + 32,
         // Cancel the in-flight run the moment the thinking budget is blown — the
         // SDK keeps generating otherwise. Fire-and-forget; `final` then resolves.
         onThinkingBudgetExceeded: () => {
@@ -175,12 +188,16 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         ...(result.stopReason ? { stopReason: result.stopReason } : {}),
       };
 
+      const incomplete =
+        !result.text && result.toolCalls.length === 0 && (result.thinkingBudgetExceeded || !!result.truncated);
       return {
         text,
         rawContent: result.rawContent,
         toolCalls: result.toolCalls,
+        ...(result.toolErrors ? { toolErrors: result.toolErrors } : {}),
         requestId: result.requestId,
         inference,
+        ...(incomplete ? { incomplete: true } : {}),
       };
     },