@kaleidorg/mind 0.7.0 → 0.8.0

package/README.md

@@ -26,7 +26,8 @@ npm i @kaleidorg/mind @qvac/sdk
 ```
 
 You need `@qvac/sdk` only to run QVAC models. The engine accepts any
-`LLMProvider`, and `@kaleidorg/mind/testing` includes a scripted provider that
+`LLMProvider`: `@kaleidorg/mind/openai` talks to any OpenAI-compatible server
+(see below), and `@kaleidorg/mind/testing` includes a scripted provider that
 needs no model. To connect MCP servers, also install
 `@modelcontextprotocol/sdk`.
 
@@ -35,6 +36,27 @@ needs no model. To connect MCP servers, also install
 | 0.19 – 0.21 | Supported (tested with 0.21.0). There is no P2P delegated inference: QVAC removed `startQVACProvider` / `loadModel({ delegate })` in 0.19. |
 | 0.13.1 – 0.18 | Supported, including P2P delegation (`buildDelegateConfig`, `allowListFirewall`). |
 
+The Qwen3.5 model constants used below (`QWEN3_5_*_MULTIMODAL_Q4_K_M`) exist in
+every supported `@qvac/sdk` version (0.13.1+).
+
+## Models
+
+We recommend Qwen3.5. Qwen3 (0.6B–4B) and Hermes 3 kept mangling the arguments of
+multi-field wallet calls such as `rln_issue_asset`, so they are no longer in the
+catalog; any GGUF still loads by path or Hugging Face URL.
+
+| Model | `@qvac/sdk` constant | Download | RAM | Use |
+|---|---|---|---|---|
+| Qwen3.5 0.8B | `QWEN3_5_0_8B_MULTIMODAL_Q4_K_M` | 0.53 GB | ~1.5 GB | Smoke tests only; loops on wallet actions |
+| Qwen3.5 2B | `QWEN3_5_2B_MULTIMODAL_Q4_K_M` | 1.3 GB | ~3 GB | **Default.** All 7 signet RGB wallet tasks passed, 45–150 s per question on an M4 |
+| Qwen3.5 4B | `QWEN3_5_4B_MULTIMODAL_Q4_K_M` | 2.7 GB | ~5 GB | Same correctness, ~2× slower (105–330 s) |
+| Qwen3.5 9B | `QWEN3_5_9B_MULTIMODAL_Q4_K_M` | 5.7 GB | ~9 GB | 16 GB machines; slow for chat (180–690 s) |
+| Qwen3.6 35B-A3B (MoE) | `QWEN3_6_35B_A3B_MULTIMODAL_Q4_K_M` | 22 GB | ~26 GB | 32 GB+ machines |
+
+The same list is exported as data from `@kaleidorg/mind/qvac` (`QWEN35_MODELS`,
+`DEFAULT_MODEL_ID`, `DEFAULT_QVAC_MODEL`, `DEFAULT_SMALL_DEVICE_QVAC_MODEL`).
+Only the text weights are loaded; the vision projector is not needed.
+
 ## Quickstart (5 minutes)
 
 This example loads a small GGUF model through QVAC, registers one tool and one
@@ -42,14 +64,13 @@ skill, and runs one turn.
 
 ```ts
 // quickstart.ts — run with: npx tsx quickstart.ts
-import { completion, cancel, loadModel, unloadModel, close, QWEN3_1_7B_INST_Q4 } from '@qvac/sdk';
+import { completion, cancel, loadModel, unloadModel, close, QWEN3_5_2B_MULTIMODAL_Q4_K_M } from '@qvac/sdk';
 import { Engine, InProcessToolSource, SkillRegistry, ToolRegistry } from '@kaleidorg/mind';
 import { createQvacProvider } from '@kaleidorg/mind/qvac';
 
-// 1. Model: Qwen3 1.7B Q4 (~1 GB, cached after the first download).
-//    QWEN3_600M_INST_Q4 (~380 MB) also works but is weaker at tool calls.
+// 1. Model: Qwen3.5 2B Q4 (~1.3 GB, cached after the first download).
 const modelId = await loadModel({
-  modelSrc: QWEN3_1_7B_INST_Q4,
+  modelSrc: QWEN3_5_2B_MULTIMODAL_Q4_K_M,
   modelConfig: { ctx_size: 4096, tools: true }, // `tools: true` turns on tool calling
 });
 const provider = createQvacProvider({ completion, cancel, getModelId: () => modelId, defaultTemperature: 0.2 });
@@ -81,8 +102,9 @@ Call get_btc_price, then answer in one sentence with the number.`);
 
 // 4. A turn.
 const question = 'What is bitcoin worth in EUR?';
-const { system, allowedTools } = skills.compose('You are a concise assistant.', skills.select(question));
 const engine = new Engine({ provider, tools });
+// composeSkill picks a skill that can act with these tools, then composes its prompt.
+const { system, allowedTools } = await engine.composeSkill(skills, question, 'You are a concise assistant.');
 const result = await engine.runAgentic(
   [{ role: 'system', content: system }, { role: 'user', content: question }],
   { allowedTools },
@@ -96,12 +118,37 @@ await close();
 A runnable copy (with a `--mock` mode) is in
 [`examples/node-minimal`](https://github.com/kaleidoswap/kaleido-mind/tree/main/examples/node-minimal).
 
+## Models you already serve
+
+`createOpenAICompatibleProvider` runs the same engine on any server that speaks
+the OpenAI Chat Completions API with tool calling: Ollama, LM Studio, llama.cpp
+`llama-server`, vLLM, `qvac serve` or a hosted API. It has no dependencies
+(it uses `fetch`).
+
+```ts
+import { createOpenAICompatibleProvider } from '@kaleidorg/mind/openai';
+
+const provider = createOpenAICompatibleProvider({
+  baseUrl: 'http://localhost:11434/v1', // Ollama
+  model: 'qwen3.5:2b',
+  apiKey: process.env.OPENAI_API_KEY,    // optional; sent as a bearer token
+  defaultTemperature: 0.1,
+  defaultMaxTokens: 1536,
+});
+```
+
+It streams tokens, forwards `toolChoice` as `tool_choice`, reports arguments
+that are not valid JSON as `toolErrors` (so the engine retries once), and
+aborts the request on `signal`. Reasoning deltas (`reasoning_content`) go to
+`onThinking`. Server-specific fields go in `extraBody`.
+
 ## Subpath exports
 
 | Import | What it gives you | Runtime |
 |---|---|---|
 | `@kaleidorg/mind` | `Engine`, `Funnel` (fast-path → recipe → agent), `ToolRegistry`, `InProcessToolSource`, `SkillRegistry`, wallet / KaleidoSwap / LSPS1 / Bitrefill / Flashnet contracts and binders, `confirmReadback`, recipes, memory, RAG, context budgeting, L402 and CLI tool sources | Any (RN-safe) |
 | `@kaleidorg/mind/qvac` | `createQvacProvider`, `toQvacTools`, `consumeRun`, voice (`createQvacVoice`, `runVoiceAssistant`), model configs, delegation helpers | Any; you inject the SDK functions |
+| `@kaleidorg/mind/openai` | `createOpenAICompatibleProvider` for Ollama, LM Studio, llama.cpp, vLLM, hosted APIs | Any with `fetch` |
 | `@kaleidorg/mind/mcp` | `McpToolSource`: tools from an MCP server over stdio or streamable HTTP | Node |
 | `@kaleidorg/mind/skills` | `loadSkillsDir`, `loadSkillFromDir`, `packagedSkillsDir()` (the 14 bundled skills) | Node (fs) |
 | `@kaleidorg/mind/testing` | `MockWallet` (stateful fake wallet bound to the real contract), `scriptedProvider` | Any |
@@ -161,10 +208,15 @@ Never guess an address.
 ```ts
 import { loadSkillsDir, packagedSkillsDir } from '@kaleidorg/mind/skills';
 const skills = new SkillRegistry([...loadSkillsDir(packagedSkillsDir()), ...loadSkillsDir('./skills')]);
-const skill = skills.select(userText);                 // keyword selector by default
-const { system, allowedTools } = skills.compose(baseSystem, skill);
+// Skips skills whose tools the engine's registry lacks (e.g. spark-wallet with
+// no Spark tools), so the model never runs inside a skill it can't act in.
+const { skill, system, allowedTools } = await engine.composeSkill(skills, userText, baseSystem);
 ```
 
+`skills.select()` alone only scores keywords; prefer `engine.composeSkill()`
+(or `selectAvailableSkill(skills, text, liveToolNames)`). The `Funnel` does this
+for you.
+
 ## The wallet tool contract
 
 `WALLET_TOOLS` is the single source of truth for wallet tool names, schemas and
@@ -184,6 +236,42 @@ spend flags. Use `walletTools({ layers })` to select tools,
 deterministic sentence for your confirm sheet, e.g. *"Send 5 USDT to utxob:…ij90
 over RLN. Confirm?"*.
 
+### Agent guards
+
+The engine and funnel check the model's tool use before anything reaches the
+user:
+
+- **Schema validation.** Arguments are checked against the tool's JSON Schema
+  (or Zod schema) before `onConfirm`: required fields, types, enums, ranges,
+  finite numbers. Invalid calls go back to the model as a tool error and the
+  user is never asked. `onConfirm` receives the validated arguments plus a
+  `summary` readback.
+- **Repeated calls.** A second identical call (same name and arguments) is not
+  re-run; the model gets the earlier result and is told to answer. A third
+  forces a final answer with no tools.
+- **Declines end the turn.** When the user declines every call in a turn, the
+  run ends with a fixed reply ("Cancelled — you declined: Create 5 RGB UTXOs
+  on-chain over RLN. Nothing was sent or changed.") and no further inference.
+  The tool result in history is the same for every tool:
+  `{ status: 'cancelled_by_user', declined_by: 'user', tool, message }`.
+  Turn it off with `endTurnOnDecline: false`.
+- **No empty answers.** If the model runs tools but its answer comes back empty
+  (reasoning used the output budget), the engine asks once more without tools,
+  then falls back to showing the last tool result.
+- **No made-up payment data.** A final answer containing an invoice, offer,
+  address or RGB invoice that no tool returned and the user never typed is
+  replaced with a refusal (`guardUngroundedPaymentData`, default on).
+- **Skills that can act.** `engine.composeSkill()` and the funnel skip skills
+  whose `requires-tools` are not live and prefer skills with at least one live
+  tool. If the request is a wallet action (create an invoice, get an address,
+  pay, send) and no exposed tool can do it, the engine answers "I can't do that
+  here" without calling the model (`guardMissingTools`, default on).
+
+Qwen3.5 reasons before it answers: in our signet runs the 2B model used 80–390
+thinking tokens per turn. Keep `maxThinkingTokens` around 512 and the output cap
+(`defaultMaxTokens`) well above it (we use 1536); a tighter cap cuts the turn
+off before it calls a tool or answers.
+
 ```ts
 const wallet = bindWalletTools(
   { rln_list_assets: async () => rln.listAssets(), rln_send_asset: async (a) => rln.sendAsset(a) /* … */ },

package/dist/context/compress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/context/compress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAiClD,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AA4BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,WAAW,CA+B3F"}
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/context/compress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAkClD,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AA4BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,WAAW,CA+B3F"}

package/dist/context/compress.js

@@ -46,6 +46,7 @@ export const DEFAULT_PRESERVE_KEYS = [
     'total',
     'total_sats',
     'balance',
+    'balance_display',
     'balance_sat',
     'address',
     'invoice',

package/dist/context/compress.js.map

@@ -1 +1 @@
-{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/context/compress.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/context/compress.ts"],"names":[],"mappings":"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"}

package/dist/context/rgb-units.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RGB asset balances are raw integers in the asset's own unit, scaled by its
+ * `precision`. Nothing in the tool result says so, and small models fill the
+ * gap with "satoshis" ("USDT — Balance: 1,000 satoshis").
+ *
+ * `annotateRgbBalances` adds a `balance_display` next to each asset's
+ * `balance` before the result reaches the model ("1,000 USDT").
+ * `fixRgbBalanceUnits` corrects a final answer that still labels an asset
+ * balance as sats: the number must equal one of that asset's balances and the
+ * nearest ticker before it must be that asset's.
+ */
+/** A raw RGB amount in display units, e.g. 1500000 at precision 6 → "1.5". */
+export declare function formatRgbAmount(raw: number, precision: number): string;
+/** Return a copy of `result` where every RGB asset carries `balance_display`. */
+export declare function annotateRgbBalances(result: unknown): unknown;
+/** Relabel asset balances that the answer calls sats, using the tool results it was built from. */
+export declare function fixRgbBalanceUnits(text: string, toolResults: unknown[]): string;
+//# sourceMappingURL=rgb-units.d.ts.map

package/dist/context/rgb-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb-units.d.ts","sourceRoot":"","sources":["../../src/context/rgb-units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsBH,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAe5D;AAeD,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,MAAM,CAkB/E"}

package/dist/context/rgb-units.js

@@ -0,0 +1,86 @@
+/**
+ * RGB asset balances are raw integers in the asset's own unit, scaled by its
+ * `precision`. Nothing in the tool result says so, and small models fill the
+ * gap with "satoshis" ("USDT — Balance: 1,000 satoshis").
+ *
+ * `annotateRgbBalances` adds a `balance_display` next to each asset's
+ * `balance` before the result reaches the model ("1,000 USDT").
+ * `fixRgbBalanceUnits` corrects a final answer that still labels an asset
+ * balance as sats: the number must equal one of that asset's balances and the
+ * nearest ticker before it must be that asset's.
+ */
+const BALANCE_FIELDS = ['settled', 'spendable', 'future'];
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function asAsset(v) {
+    if (typeof v.ticker !== 'string' || !v.ticker || !isObj(v.balance))
+        return null;
+    const amounts = BALANCE_FIELDS.map((k) => v.balance[k]).filter((n) => typeof n === 'number');
+    if (!amounts.length)
+        return null;
+    const precision = typeof v.precision === 'number' && v.precision > 0 ? v.precision : 0;
+    return { ticker: v.ticker, precision, amounts };
+}
+/** A raw RGB amount in display units, e.g. 1500000 at precision 6 → "1.5". */
+export function formatRgbAmount(raw, precision) {
+    const value = raw / 10 ** precision;
+    return value.toLocaleString('en-US', { maximumFractionDigits: precision });
+}
+/** Return a copy of `result` where every RGB asset carries `balance_display`. */
+export function annotateRgbBalances(result) {
+    if (Array.isArray(result))
+        return result.map(annotateRgbBalances);
+    if (!isObj(result))
+        return result;
+    const out = {};
+    for (const [k, v] of Object.entries(result))
+        out[k] = annotateRgbBalances(v);
+    const asset = asAsset(result);
+    if (asset) {
+        const balance = result.balance;
+        const display = {};
+        for (const k of BALANCE_FIELDS) {
+            if (typeof balance[k] === 'number')
+                display[k] = `${formatRgbAmount(balance[k], asset.precision)} ${asset.ticker}`;
+        }
+        out.balance_display = display;
+    }
+    return out;
+}
+function collectAssets(value, into) {
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectAssets(v, into);
+    }
+    else if (isObj(value)) {
+        const asset = asAsset(value);
+        if (asset)
+            into.push(asset);
+        for (const v of Object.values(value))
+            collectAssets(v, into);
+    }
+}
+const AMOUNT_IN_SATS = /(\d[\d,]*(?:\.\d+)?)\s*(?:satoshis|sats?)\b/gi;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Relabel asset balances that the answer calls sats, using the tool results it was built from. */
+export function fixRgbBalanceUnits(text, toolResults) {
+    const assets = [];
+    for (const r of toolResults)
+        collectAssets(r, assets);
+    if (!assets.length)
+        return text;
+    const tickerRe = new RegExp(`\\b(${[...new Set(assets.map((a) => escapeRe(a.ticker)))].join('|')})\\b`, 'g');
+    return text.replace(AMOUNT_IN_SATS, (match, num, offset) => {
+        let nearest;
+        for (const m of text.slice(Math.max(0, offset - 300), offset).matchAll(tickerRe))
+            nearest = m[1];
+        if (!nearest)
+            return match;
+        const value = Number(num.replace(/,/g, ''));
+        const asset = assets.find((a) => a.ticker === nearest && a.amounts.some((raw) => raw === value || raw / 10 ** a.precision === value));
+        if (!asset)
+            return match;
+        const raw = asset.amounts.find((r) => r === value) ?? value * 10 ** asset.precision;
+        return `${formatRgbAmount(raw, asset.precision)} ${asset.ticker}`;
+    });
+}
+//# sourceMappingURL=rgb-units.js.map

package/dist/context/rgb-units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb-units.js","sourceRoot":"","sources":["../../src/context/rgb-units.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -15,9 +15,11 @@
  */
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 import type { LLMProvider } from './providers/types.js';
-import type { InferenceMetrics } from './providers/types.js';
+import type { InferenceMetrics, ToolChoice } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { type ToolCrushOptions } from './context/compress.js';
+import type { SkillRegistry } from './skills/registry.js';
+import type { Skill } from './skills/types.js';
 export interface EngineOptions {
     provider: LLMProvider;
     tools: ToolRegistry;
@@ -34,6 +36,30 @@ export interface EngineOptions {
      * The `onToolResult` callback and `toolCalls` still carry the raw result.
      */
     compressToolOutput?: boolean | ToolCrushOptions;
+    /**
+     * Replace a final answer that contains an invoice/address/payment request no
+     * tool returned and the user never typed. Default true.
+     */
+    guardUngroundedPaymentData?: boolean;
+    /**
+     * Keep amounts honest: recompute BTC figures paired with a sats amount, add
+     * `balance_display` to RGB asset balances the model sees, and relabel an
+     * asset balance the answer calls sats. Default true.
+     */
+    fixAmountConversions?: boolean;
+    /**
+     * Answer a wallet action (create an invoice, get an address, pay, send) with
+     * a fixed "no tool" reply, without inference, when no exposed tool can do it.
+     * Default true.
+     */
+    guardMissingTools?: boolean;
+    /** End the run with a fixed "Cancelled" reply when the user declines every call in a turn. Default true. */
+    endTurnOnDecline?: boolean;
+}
+export interface ComposedSkill {
+    skill: Skill | null;
+    system: string;
+    allowedTools?: string[];
 }
 export interface AgenticOptions {
     maxTurns?: number;
@@ -59,12 +85,19 @@ export interface AgenticOptions {
     onConfirm?: (call: {
         name: string;
         arguments: Record<string, unknown>;
+        summary?: string;
     }) => Promise<ConfirmDecision>;
     /**
      * Restrict the tools exposed to the model this run (progressive disclosure).
      * Typically the active skill's tool list — see SkillRegistry.compose().
      */
     allowedTools?: string[];
+    /**
+     * Tool choice for the FIRST model call only — e.g. `'required'` when the
+     * request is a wallet action, so the model can't answer in prose with
+     * made-up data. Later rounds are left to the model.
+     */
+    firstTurnToolChoice?: ToolChoice;
     signal?: AbortSignal;
 }
 export interface AgenticResult {
@@ -85,8 +118,27 @@ export declare class Engine {
     private readonly defaultSystem?;
     private readonly defaultMaxTurns;
     private readonly compressOpts?;
+    private readonly guardPaymentData;
+    private readonly fixAmounts;
+    private readonly guardMissingTools;
+    private readonly endTurnOnDecline;
     constructor(opts: EngineOptions);
+    /**
+     * Select the skill for `query` among those that can act with this engine's
+     * tools (skills whose `requires-tools` are missing are skipped), then
+     * compose its system prompt. Pass the result to runAgentic:
+     *
+     *   const { system, allowedTools } = await engine.composeSkill(skills, question, base);
+     *   await engine.runAgentic([{ role: 'system', content: system }, { role: 'user', content: question }], { allowedTools });
+     */
+    composeSkill(skills: SkillRegistry, query: string, base: string): Promise<ComposedSkill>;
     runAgentic(messages: Message[], opts?: AgenticOptions): Promise<AgenticResult>;
+    /**
+     * The model ran tools but produced no visible answer (e.g. reasoning used the
+     * whole output budget). Ask once more without tools; if that is empty too,
+     * show the last tool result instead of an empty reply.
+     */
+    private recoverAnswer;
     cancel(requestId: string): Promise<void>;
     /**
      * Serialize a tool result for history, optionally crushing verbose JSON so

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}