@kaleidorg/mind 0.8.0 → 0.9.0

package/README.md

@@ -33,11 +33,11 @@ needs no model. To connect MCP servers, also install
 
 | `@qvac/sdk` | Status |
 |---|---|
-| 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`). |
+| 0.20 – 0.21 | Supported (tested with 0.21.0). |
+| < 0.20 | Not supported from mind 0.9: the provider sends `tool_choice` and `reasoning_budget`, which older SDKs reject or ignore. Use mind 0.8.x. |
 
 The Qwen3.5 model constants used below (`QWEN3_5_*_MULTIMODAL_Q4_K_M`) exist in
-every supported `@qvac/sdk` version (0.13.1+).
+every supported `@qvac/sdk` version.
 
 ## Models
 
@@ -146,9 +146,11 @@ aborts the request on `signal`. Reasoning deltas (`reasoning_content`) go to
 
 | 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` | `Engine`, `Funnel` (fast-path → recipe → agent), `ToolRegistry`, `InProcessToolSource`, `SkillRegistry`, the wallet contract and binder, `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 | Any; you inject the SDK functions |
 | `@kaleidorg/mind/openai` | `createOpenAICompatibleProvider` for Ollama, LM Studio, llama.cpp, vLLM, hosted APIs | Any with `fetch` |
+| `@kaleidorg/mind/kaleidoswap` · `/lsps1` · `/submarine` · `/bitrefill` · `/flashnet` | Each domain's tool contract (`*_TOOLS`, `bind*Tools`) and its recipes. Also re-exported from the root until 1.0 | Any |
+| `@kaleidorg/mind/knowledge` | Knowledge packs (`BITCOIN_COPILOT_DOCS`), corpus adapters for RAG, `createBtcMapToolSource` | Any |
 | `@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 |

package/dist/bitrefill/index.d.ts

@@ -0,0 +1,4 @@
+/** Bitrefill (gift cards, top-ups, eSIMs): tool contract. */
+export { BITREFILL_TOOLS, BITREFILL_SPEND_TOOLS, isBitrefillSpendTool, getBitrefillTool, bindBitrefillTools, } from './contract.js';
+export type { BitrefillToolDef, BitrefillHandler, BindBitrefillOptions, } from './contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/bitrefill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bitrefill/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/bitrefill/index.js

@@ -0,0 +1,3 @@
+/** Bitrefill (gift cards, top-ups, eSIMs): tool contract. */
+export { BITREFILL_TOOLS, BITREFILL_SPEND_TOOLS, isBitrefillSpendTool, getBitrefillTool, bindBitrefillTools, } from './contract.js';
+//# sourceMappingURL=index.js.map

package/dist/bitrefill/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bitrefill/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC"}

package/dist/capabilities.d.ts

@@ -13,8 +13,8 @@ export interface CapabilityInput {
     modelCtxTokens: number;
     /** Whether an EmbeddingProvider is wired (QVAC embed, etc.). */
     hasEmbeddings?: boolean;
-    /** Running inference on a remote provider (desktop/server) — relaxes limits. */
-    delegated?: boolean;
+    /** Inference runs on a larger remote model (e.g. an OpenAI-compatible server) — relaxes limits. */
+    remote?: boolean;
 }
 export interface MindCapabilities {
     /** Long-term memory (cheap — on unless the window is tiny). */
@@ -23,7 +23,7 @@ export interface MindCapabilities {
     semanticMemory: boolean;
     /** Embedding-only dedup of near-duplicate memories (zero inference — mobile-safe). */
     dedupeMemory: boolean;
-    /** LLM merge of near-duplicate memories (an extra inference — capable/delegated only). */
+    /** LLM merge of near-duplicate memories (an extra inference — capable/remote only). */
     mergeMemory: boolean;
     /** Retrieval-augmented generation (needs embeddings + enough RAM/context). */
     rag: boolean;

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,YAAY,EAAE,OAAO,CAAC;IACtB,0FAA0F;IAC1F,WAAW,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;IACb,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAmC1E"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,YAAY,EAAE,OAAO,CAAC;IACtB,uFAAuF;IACvF,WAAW,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;IACb,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAmC1E"}

package/dist/capabilities.js

@@ -9,7 +9,7 @@
 import { contextBudgetTokens } from './context/budget.js';
 const GiB = 1024 * 1024 * 1024;
 export function capabilityProfile(input) {
-    const ramGb = input.delegated ? Infinity : (input.ramBytes ?? 0) / GiB;
+    const ramGb = input.remote ? Infinity : (input.ramBytes ?? 0) / GiB;
     const ctx = input.modelCtxTokens;
     const hasEmb = !!input.hasEmbeddings;
     const budget = contextBudgetTokens(ctx);
@@ -18,12 +18,12 @@ export function capabilityProfile(input) {
     const semanticMemory = memory && hasEmb;
     // Consolidation: embedding-only dedup is cheap (no inference) — on wherever
     // semantic memory is. The LLM merge costs an extra inference, so reserve it
-    // for delegated or roomy on-device setups; never run it on a tiny phone model.
+    // for remote or roomy on-device setups; never run it on a tiny phone model.
     const dedupeMemory = semanticMemory;
-    const mergeMemory = dedupeMemory && (input.delegated || (ramGb >= 4 && ctx >= 4096));
+    const mergeMemory = dedupeMemory && (input.remote || (ramGb >= 4 && ctx >= 4096));
     // RAG is the expensive one: needs embeddings, a non-tiny context window, and
     // (on-device) enough RAM to hold an embedding model + index.
-    const rag = hasEmb && ctx >= 4096 && (input.delegated || ramGb >= 3);
+    const rag = hasEmb && ctx >= 4096 && (input.remote || ramGb >= 3);
     // Scale how much we pull in with the available window.
     const topKMemory = budget >= 1500 ? 4 : budget >= 700 ? 3 : 2;
     const topKRag = rag ? (budget >= 2500 ? 5 : 3) : 0;

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAgC1D,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/B,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;IACvE,MAAM,GAAG,GAAG,KAAK,CAAC,cAAc,CAAC;IACjC,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;IAErC,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAExC,+EAA+E;IAC/E,MAAM,MAAM,GAAG,MAAM,IAAI,GAAG,CAAC;IAC7B,MAAM,cAAc,GAAG,MAAM,IAAI,MAAM,CAAC;IAExC,4EAA4E;IAC5E,4EAA4E;IAC5E,+EAA+E;IAC/E,MAAM,YAAY,GAAG,cAAc,CAAC;IACpC,MAAM,WAAW,GAAG,YAAY,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;IAErF,6EAA6E;IAC7E,6DAA6D;IAC7D,MAAM,GAAG,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;IAErE,uDAAuD;IACvD,MAAM,UAAU,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,OAAO;QACL,MAAM;QACN,cAAc;QACd,YAAY;QACZ,WAAW;QACX,GAAG;QACH,mBAAmB,EAAE,MAAM;QAC3B,UAAU;QACV,OAAO;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAgC1D,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/B,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;IACpE,MAAM,GAAG,GAAG,KAAK,CAAC,cAAc,CAAC;IACjC,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;IAErC,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAExC,+EAA+E;IAC/E,MAAM,MAAM,GAAG,MAAM,IAAI,GAAG,CAAC;IAC7B,MAAM,cAAc,GAAG,MAAM,IAAI,MAAM,CAAC;IAExC,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,YAAY,GAAG,cAAc,CAAC;IACpC,MAAM,WAAW,GAAG,YAAY,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;IAElF,6EAA6E;IAC7E,6DAA6D;IAC7D,MAAM,GAAG,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;IAElE,uDAAuD;IACvD,MAAM,UAAU,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,OAAO;QACL,MAAM;QACN,cAAc;QACd,YAAY;QACZ,WAAW;QACX,GAAG;QACH,mBAAmB,EAAE,MAAM;QAC3B,UAAU;QACV,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/engine/answer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How an agentic run ends: the Engine's fixed replies, and the checks every
+ * answer the model wrote goes through before the user sees it.
+ *
+ * An answer is tagged with where it came from. Fixed replies are final; only
+ * model text is rewritten (amount fixes) or replaced (payment data no tool
+ * returned). Keeping that rule in one place is what stops a fixed reply that
+ * quotes a readback from being mistaken for an invented invoice.
+ */
+import type { ToolCallError } from '../providers/types.js';
+export interface Answer {
+    text: string;
+    /** `engine`: one of the fixed replies below, never rewritten. */
+    source: 'model' | 'engine';
+}
+export declare const model: (text: string) => Answer;
+export declare const engine: (text: string) => Answer;
+export declare const STOPPED_REPLY = "I had to stop after several steps \u2014 please try a more specific request.";
+export declare const TOOL_CALL_FAILED_REPLY = "I couldn't put together a valid request for that. Please rephrase it with the exact values (asset, amount, recipient).";
+export declare const REPEATED_CALL_REPLY = "I could not get a different result from the wallet \u2014 please try a more specific request.";
+export declare function cancelledReply(declined: string[]): string;
+/** Fed back to the model after a tool call it emitted could not be parsed. */
+export declare function toolErrorFeedback(errors: ToolCallError[], cutOff: boolean): string;
+export interface FinalizeOptions {
+    /** Recompute BTC figures and relabel RGB balances. */
+    fixAmounts: boolean;
+    /** Replace answers carrying payment data no tool returned and the user never typed. */
+    guardPaymentData: boolean;
+    /** What the answer may legitimately quote: the user's messages and the tool results. */
+    sources: unknown[];
+    /** Tool results, for relabelling RGB balances. */
+    toolResults: unknown[];
+    aborted: boolean;
+}
+/** The text the user sees. */
+export declare function finalizeAnswer(answer: Answer, opts: FinalizeOptions): string;
+//# sourceMappingURL=answer.d.ts.map

package/dist/engine/answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/engine/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED,eAAO,MAAM,KAAK,SAAU,MAAM,KAAG,MAAqC,CAAC;AAC3E,eAAO,MAAM,MAAM,SAAU,MAAM,KAAG,MAAsC,CAAC;AAE7E,eAAO,MAAM,aAAa,iFAA4E,CAAC;AAEvG,eAAO,MAAM,sBAAsB,2HACuF,CAAC;AAE3H,eAAO,MAAM,mBAAmB,kGAA6F,CAAC;AAE9H,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzD;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAMlF;AAED,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,UAAU,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wFAAwF;IACxF,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,kDAAkD;IAClD,WAAW,EAAE,OAAO,EAAE,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8BAA8B;AAC9B,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAU5E"}

package/dist/engine/answer.js

@@ -0,0 +1,35 @@
+import { findUngroundedPaymentData, fixSatsBtcConversions, ungroundedReply } from '../guards.js';
+import { fixRgbBalanceUnits } from '../context/rgb-units.js';
+export const model = (text) => ({ text, source: 'model' });
+export const engine = (text) => ({ text, source: 'engine' });
+export const STOPPED_REPLY = 'I had to stop after several steps — please try a more specific request.';
+export const TOOL_CALL_FAILED_REPLY = "I couldn't put together a valid request for that. Please rephrase it with the exact values (asset, amount, recipient).";
+export const REPEATED_CALL_REPLY = 'I could not get a different result from the wallet — please try a more specific request.';
+export function cancelledReply(declined) {
+    return `Cancelled — you declined: ${declined.join('; ')}. Nothing was sent or changed.`;
+}
+/** Fed back to the model after a tool call it emitted could not be parsed. */
+export function toolErrorFeedback(errors, cutOff) {
+    if (cutOff) {
+        return 'Your tool call was cut off because the output got too long. Make ONE tool call at a time with only the required arguments, or answer from the results you already have.';
+    }
+    const detail = errors.map((e) => e.message).join('; ');
+    return `Your tool call could not be read (${detail}). Call the tool again with valid JSON arguments that match its schema, or ask the user for the missing values.`;
+}
+/** The text the user sees. */
+export function finalizeAnswer(answer, opts) {
+    if (!answer.text)
+        return opts.aborted ? '' : STOPPED_REPLY;
+    if (answer.source === 'engine')
+        return answer.text;
+    let text = answer.text;
+    if (opts.fixAmounts)
+        text = fixRgbBalanceUnits(fixSatsBtcConversions(text), opts.toolResults);
+    if (opts.guardPaymentData) {
+        const ungrounded = findUngroundedPaymentData(text, opts.sources);
+        if (ungrounded.length)
+            text = ungroundedReply(ungrounded);
+    }
+    return text;
+}
+//# sourceMappingURL=answer.js.map

package/dist/engine/answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.js","sourceRoot":"","sources":["../../src/engine/answer.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAQ7D,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,aAAa,GAAG,yEAAyE,CAAC;AAEvG,MAAM,CAAC,MAAM,sBAAsB,GACjC,wHAAwH,CAAC;AAE3H,MAAM,CAAC,MAAM,mBAAmB,GAAG,0FAA0F,CAAC;AAE9H,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,6BAA6B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC,CAAC;AAC1F,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,MAAuB,EAAE,MAAe;IACxE,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,yKAAyK,CAAC;IACnL,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,qCAAqC,MAAM,iHAAiH,CAAC;AACtK,CAAC;AAcD,8BAA8B;AAC9B,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,IAAqB;IAClE,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;IAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACnD,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,UAAU;QAAE,IAAI,GAAG,kBAAkB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9F,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACjE,IAAI,UAAU,CAAC,MAAM;YAAE,IAAI,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/engine.d.ts

@@ -11,11 +11,10 @@
  * `{role:'tool'}` results into history each round, loop until the model stops
  * calling tools. Money tools pause for an `onConfirm` gate; their handlers run
  * wherever the ToolSource lives (on the phone for the wallet), even when
- * inference is delegated to a remote provider.
+ * inference runs on a remote server.
  */
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
-import type { LLMProvider } from './providers/types.js';
-import type { InferenceMetrics, ToolChoice } from './providers/types.js';
+import type { InferenceMetrics, LLMProvider, 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';
@@ -47,6 +46,8 @@ export interface EngineOptions {
      * asset balance the answer calls sats. Default true.
      */
     fixAmountConversions?: boolean;
+    /** Let the model reason on a forced first tool call. Default false (thinking off). */
+    thinkOnForcedCalls?: 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.
@@ -98,6 +99,8 @@ export interface AgenticOptions {
      * made-up data. Later rounds are left to the model.
      */
     firstTurnToolChoice?: ToolChoice;
+    /** Session key passed to every model call of this run. Default: a fresh key per run. */
+    sessionKey?: string;
     signal?: AbortSignal;
 }
 export interface AgenticResult {
@@ -120,6 +123,7 @@ export declare class Engine {
     private readonly compressOpts?;
     private readonly guardPaymentData;
     private readonly fixAmounts;
+    private readonly thinkOnForcedCalls;
     private readonly guardMissingTools;
     private readonly endTurnOnDecline;
     constructor(opts: EngineOptions);
@@ -133,6 +137,14 @@ export declare class Engine {
      */
     composeSkill(skills: SkillRegistry, query: string, base: string): Promise<ComposedSkill>;
     runAgentic(messages: Message[], opts?: AgenticOptions): Promise<AgenticResult>;
+    private runAgenticSession;
+    /** One model call within the run's session; records its receipt. */
+    private callModel;
+    /**
+     * Validate, confirm (for spends) and execute one tool call, and add its
+     * result to the history. Returns the readback when the user declined it.
+     */
+    private executeCall;
     /**
      * 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,

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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"}