@kaleidorg/mind 0.5.1 → 0.6.1

package/dist/context/compress.js

@@ -0,0 +1,181 @@
+/**
+ * Tool-output compression — the "fit more into a tiny window" part.
+ *
+ * Tool results are the single biggest, most repetitive thing the engine pushes
+ * into a small on-device model's context. A merchant search returns 40 near
+ * identical rows; a tx history returns hundreds; a swap quote nests config the
+ * model never reads. Every round, the *raw* `JSON.stringify(result)` is fed back
+ * into history — so on a 2k-window 0.6B model the conversation drowns in JSON
+ * the model didn't need, crowding out the system prompt, the skill, and the
+ * actual question.
+ *
+ * `compressToolResult` is a structural crusher (the idea behind Headroom's
+ * SmartCrusher/ToolCrusher, reimplemented natively — no dependency, no network,
+ * no proxy, so it stays on-device and private). It walks the JSON and:
+ *
+ *   • dedupes identical array items, then keeps the first/last few and replaces
+ *     the middle with an honest `{ "__elided__": N }` marker,
+ *   • caps nesting depth (deep config → a one-line summary),
+ *   • truncates long *prose* strings (logs, descriptions),
+ *
+ * and never regresses: if crushing doesn't actually save tokens, the original
+ * is returned untouched.
+ *
+ * SAFETY: it never touches numbers, never elides whole objects, never truncates
+ * whitespace-free strings (addresses, BOLT11 invoices, txids, pubkeys), and
+ * never touches a value under a money/identity key (see DEFAULT_PRESERVE_KEYS).
+ * Amounts and recipients reach the model intact — the confirm readback is built
+ * deterministically from the resolved call anyway, but this keeps the model's
+ * own view honest too. Small results (below `minTokens`) are passed through
+ * verbatim so nothing changes for the common case.
+ */
+import { estimateTokens } from './budget.js';
+/** Keys whose values are never elided or truncated — amounts, ids, recipients. */
+export const DEFAULT_PRESERVE_KEYS = [
+    'amount',
+    'amount_sat',
+    'amount_sats',
+    'amount_msat',
+    'sat',
+    'sats',
+    'msat',
+    'value',
+    'fee',
+    'fee_sat',
+    'fee_sats',
+    'total',
+    'total_sats',
+    'balance',
+    'balance_sat',
+    'address',
+    'invoice',
+    'bolt11',
+    'payment_request',
+    'payment_hash',
+    'preimage',
+    'txid',
+    'tx_id',
+    'pubkey',
+    'node_id',
+    'recipient',
+    'destination',
+    'asset_id',
+    'contract_id',
+    'rate',
+    'price',
+    'price_usd',
+];
+/** A string with no whitespace is treated as an identifier (address/invoice/hash) and never truncated. */
+function isIdentifierLike(s) {
+    return !/\s/.test(s);
+}
+function serialize(value) {
+    return typeof value === 'string' ? value : safeStringify(value);
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Crush a tool result for inclusion in model context. Returns the original,
+ * verbatim, when it's small or when crushing wouldn't save tokens.
+ */
+export function compressToolResult(value, opts = {}) {
+    const cfg = {
+        minTokens: opts.minTokens ?? 200,
+        maxArrayItems: Math.max(2, opts.maxArrayItems ?? 8),
+        maxDepth: Math.max(1, opts.maxDepth ?? 6),
+        maxStringLength: opts.maxStringLength ?? 600,
+        dedupe: opts.dedupe ?? true,
+        preserve: new Set((opts.preserveKeys ?? DEFAULT_PRESERVE_KEYS).map((k) => k.toLowerCase())),
+    };
+    const original = serialize(value);
+    const originalTokens = estimateTokens(original);
+    // Below the floor, never touch it — correctness over savings for small results.
+    if (originalTokens < cfg.minTokens) {
+        return { content: original, originalTokens, compressedTokens: originalTokens, elided: 0, changed: false };
+    }
+    let elided = 0;
+    const crushed = crush(value, cfg, 0, false, () => {
+        elided += 1;
+    });
+    const content = serialize(crushed);
+    const compressedTokens = estimateTokens(content);
+    // Never regress: if crushing didn't actually shrink it, keep the original.
+    if (compressedTokens >= originalTokens) {
+        return { content: original, originalTokens, compressedTokens: originalTokens, elided: 0, changed: false };
+    }
+    return { content, originalTokens, compressedTokens, elided, changed: true };
+}
+/**
+ * Recursively crush a JSON-ish value.
+ *
+ * @param preserved when true, the value sits under a preserve key — kept verbatim.
+ * @param onElide   called once per array item dropped (for stats).
+ */
+function crush(value, cfg, depth, preserved, onElide) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string') {
+        if (preserved || isIdentifierLike(value))
+            return value;
+        if (cfg.maxStringLength > 0 && value.length > cfg.maxStringLength) {
+            const omitted = value.length - cfg.maxStringLength;
+            return `${value.slice(0, cfg.maxStringLength)}… (+${omitted} chars)`;
+        }
+        return value;
+    }
+    if (typeof value !== 'object')
+        return value; // number, boolean — never touched
+    // Beyond max depth, collapse to a one-line shape summary instead of the subtree.
+    if (depth >= cfg.maxDepth) {
+        if (Array.isArray(value))
+            return `[array: ${value.length} items]`;
+        return `[object: ${Object.keys(value).length} keys]`;
+    }
+    if (Array.isArray(value)) {
+        let items = value;
+        if (cfg.dedupe && items.length > cfg.maxArrayItems) {
+            const seen = new Set();
+            const unique = [];
+            for (const item of items) {
+                const key = safeStringify(item);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                unique.push(item);
+            }
+            items = unique;
+        }
+        if (items.length <= cfg.maxArrayItems) {
+            return items.map((v) => crush(v, cfg, depth + 1, preserved, onElide));
+        }
+        // Keep the front and a little of the tail (Headroom's "anchors"); elide the
+        // middle with an honest marker so the model knows data was omitted and can
+        // ask a more specific question / call a narrower tool.
+        const keepFirst = Math.max(1, Math.ceil(cfg.maxArrayItems * 0.6));
+        const keepLast = Math.max(0, cfg.maxArrayItems - keepFirst);
+        const head = items.slice(0, keepFirst);
+        const tail = keepLast > 0 ? items.slice(items.length - keepLast) : [];
+        const droppedCount = items.length - head.length - tail.length;
+        for (let i = 0; i < droppedCount; i++)
+            onElide();
+        const out = head.map((v) => crush(v, cfg, depth + 1, preserved, onElide));
+        out.push({ __elided__: droppedCount, note: 'items omitted to fit context' });
+        for (const v of tail)
+            out.push(crush(v, cfg, depth + 1, preserved, onElide));
+        return out;
+    }
+    const obj = value;
+    const result = {};
+    for (const [key, v] of Object.entries(obj)) {
+        const keep = preserved || cfg.preserve.has(key.toLowerCase());
+        result[key] = crush(v, cfg, depth + 1, keep, onElide);
+    }
+    return result;
+}
+//# sourceMappingURL=compress.js.map

package/dist/context/compress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/context/compress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,QAAQ;IACR,YAAY;IACZ,aAAa;IACb,aAAa;IACb,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,KAAK;IACL,SAAS;IACT,UAAU;IACV,OAAO;IACP,YAAY;IACZ,SAAS;IACT,aAAa;IACb,SAAS;IACT,SAAS;IACT,QAAQ;IACR,iBAAiB;IACjB,cAAc;IACd,UAAU;IACV,MAAM;IACN,OAAO;IACP,QAAQ;IACR,SAAS;IACT,WAAW;IACX,aAAa;IACb,UAAU;IACV,aAAa;IACb,MAAM;IACN,OAAO;IACP,WAAW;CACZ,CAAC;AAuCF,0GAA0G;AAC1G,SAAS,gBAAgB,CAAC,CAAS;IACjC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc,EAAE,OAAyB,EAAE;IAC5E,MAAM,GAAG,GAAa;QACpB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG;QAChC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;QACnD,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACzC,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,GAAG;QAC5C,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;KAC5F,CAAC;IAEF,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,cAAc,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAEhD,gFAAgF;IAChF,IAAI,cAAc,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5G,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE;QAC/C,MAAM,IAAI,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,gBAAgB,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAEjD,2EAA2E;IAC3E,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAAC;QACvC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5G,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,SAAS,KAAK,CAAC,KAAc,EAAE,GAAa,EAAE,KAAa,EAAE,SAAkB,EAAE,OAAmB;IAClG,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAExD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,SAAS,IAAI,gBAAgB,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvD,IAAI,GAAG,CAAC,eAAe,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,eAAe,EAAE,CAAC;YAClE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,eAAe,CAAC;YACnD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,OAAO,SAAS,CAAC;QACvE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,CAAC,kCAAkC;IAE/E,iFAAiF;IACjF,IAAI,KAAK,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,WAAW,KAAK,CAAC,MAAM,SAAS,CAAC;QAClE,OAAO,YAAY,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC,MAAM,QAAQ,CAAC;IACjE,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,GAAG,KAAK,CAAC;QAElB,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;YACnD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,MAAM,MAAM,GAAc,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;gBAChC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC;YACD,KAAK,GAAG,MAAM,CAAC;QACjB,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;YACtC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACxE,CAAC;QAED,4EAA4E;QAC5E,2EAA2E;QAC3E,uDAAuD;QACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC,CAAC;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QAEjD,MAAM,GAAG,GAAc,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACrF,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,8BAA8B,EAAE,CAAC,CAAC;QAC7E,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7E,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,SAAS,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/engine.d.ts

@@ -15,7 +15,9 @@
  */
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 import type { LLMProvider } from './providers/types.js';
+import type { InferenceMetrics } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
+import { type ToolCrushOptions } from './context/compress.js';
 export interface EngineOptions {
     provider: LLMProvider;
     tools: ToolRegistry;
@@ -23,6 +25,15 @@ export interface EngineOptions {
     defaultSystem?: string;
     /** Max reasoning↔tool rounds before forcing a stop. Default 5. */
     defaultMaxTurns?: number;
+    /**
+     * Crush verbose tool results before they're fed back into history, so a
+     * tiny on-device model's context window isn't drowned in repetitive JSON
+     * (merchant lists, tx history, nested quotes). `true` uses safe defaults;
+     * pass options to tune. Off by default — small results are never touched and
+     * amounts/addresses/invoices are always preserved (see compressToolResult).
+     * The `onToolResult` callback and `toolCalls` still carry the raw result.
+     */
+    compressToolOutput?: boolean | ToolCrushOptions;
 }
 export interface AgenticOptions {
     maxTurns?: number;
@@ -65,15 +76,24 @@ export interface AgenticResult {
     messages: Message[];
     /** Wall-clock duration of the whole agentic run, ms. */
     latencyMs: number;
+    /** One receipt per model call in this agentic run. */
+    inference: InferenceMetrics[];
 }
 export declare class Engine {
     private readonly provider;
     private readonly registry;
     private readonly defaultSystem?;
     private readonly defaultMaxTurns;
+    private readonly compressOpts?;
     constructor(opts: EngineOptions);
     runAgentic(messages: Message[], opts?: AgenticOptions): Promise<AgenticResult>;
     cancel(requestId: string): Promise<void>;
+    /**
+     * Serialize a tool result for history, optionally crushing verbose JSON so
+     * it doesn't swamp a small context window. The raw result is unchanged for
+     * callbacks/logs — only the model-facing history copy is compressed.
+     */
+    private toHistoryContent;
     private safeExecute;
 }
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,gEAAgE;IAChE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChG;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpH,qEAAqE;IACrE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACrG;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,IAAI,EAAE,aAAa;IAOzB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAoFlF,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIhC,WAAW;CAO1B"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -13,16 +13,23 @@
  * wherever the ToolSource lives (on the phone for the wallet), even when
  * inference is delegated to a remote provider.
  */
+import { compressToolResult } from './context/compress.js';
 export class Engine {
     provider;
     registry;
     defaultSystem;
     defaultMaxTurns;
+    compressOpts;
     constructor(opts) {
         this.provider = opts.provider;
         this.registry = opts.tools;
         this.defaultSystem = opts.defaultSystem;
         this.defaultMaxTurns = opts.defaultMaxTurns ?? 5;
+        this.compressOpts = opts.compressToolOutput
+            ? opts.compressToolOutput === true
+                ? {}
+                : opts.compressToolOutput
+            : undefined;
     }
     async runAgentic(messages, opts = {}) {
         const maxTurns = opts.maxTurns ?? this.defaultMaxTurns;
@@ -39,6 +46,7 @@ export class Engine {
         let lastRequestId;
         let finalText = '';
         let turns = 0;
+        const inference = [];
         for (let turn = 1; turn <= maxTurns; turn++) {
             turns = turn;
             if (opts.signal?.aborted)
@@ -51,6 +59,8 @@ export class Engine {
                 signal: opts.signal,
             });
             lastRequestId = out.requestId;
+            if (out.inference)
+                inference.push(out.inference);
             if (out.requestId)
                 opts.onStart?.(out.requestId, turn);
             finalText = (out.text || '').trim();
@@ -79,10 +89,7 @@ export class Engine {
                 }
                 executed.push({ name: call.name, arguments: call.arguments, result });
                 opts.onToolResult?.({ name: call.name, arguments: call.arguments, result }, turn);
-                history.push({
-                    role: 'tool',
-                    content: typeof result === 'string' ? result : JSON.stringify(result),
-                });
+                history.push({ role: 'tool', content: this.toHistoryContent(result) });
             }
             if (turn === maxTurns && !finalText) {
                 finalText = 'I had to stop after several steps — please try a more specific request.';
@@ -99,11 +106,23 @@ export class Engine {
             requestId: lastRequestId,
             messages: history,
             latencyMs: Date.now() - startedAt,
+            inference,
         };
     }
     async cancel(requestId) {
         await this.provider.cancel?.(requestId);
     }
+    /**
+     * Serialize a tool result for history, optionally crushing verbose JSON so
+     * it doesn't swamp a small context window. The raw result is unchanged for
+     * callbacks/logs — only the model-facing history copy is compressed.
+     */
+    toHistoryContent(result) {
+        if (!this.compressOpts) {
+            return typeof result === 'string' ? result : JSON.stringify(result);
+        }
+        return compressToolResult(result, this.compressOpts).content;
+    }
     async safeExecute(name, args) {
         try {
             return await this.registry.execute(name, args);

package/dist/engine.js.map

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

package/dist/evidence.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Hackathon evidence JSONL.
+ *
+ * This is deliberately transport-neutral: Node writes it to disk, React Native
+ * writes it to the app documents directory, and tests keep it in memory.
+ */
+import type { InferenceMetrics } from './providers/types.js';
+export declare const EVIDENCE_SCHEMA: "kaleidomind.evidence.v1";
+export type EvidenceSurface = 'desktop' | 'mobile' | 'cli' | 'test';
+export type EvidenceEventType = 'model_load' | 'model_unload' | 'inference' | 'tool_call' | 'tool_result' | 'confirmation' | 'error';
+export interface EvidenceEvent {
+    schema: typeof EVIDENCE_SCHEMA;
+    event: EvidenceEventType;
+    ts: string;
+    runId: string;
+    surface: EvidenceSurface;
+    model?: {
+        name: string;
+        version?: string;
+        source?: 'local' | 'delegated';
+    };
+    hardware?: {
+        device: string;
+        os?: string;
+        memoryGb?: number;
+    };
+    prompt?: string;
+    response?: string;
+    inference?: InferenceMetrics | InferenceMetrics[];
+    tool?: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        result?: unknown;
+    };
+    confirmation?: {
+        tool: string;
+        approved: boolean;
+        reason?: string;
+    };
+    error?: {
+        name: string;
+        message: string;
+    };
+    meta?: Record<string, unknown>;
+}
+export type EvidenceInput = Omit<EvidenceEvent, 'schema' | 'ts'>;
+export interface EvidenceIO {
+    appendLine(line: string): Promise<void>;
+    now(): Date;
+}
+export interface EvidenceRecorderOptions {
+    io: EvidenceIO;
+    sanitize?: (event: EvidenceEvent) => EvidenceEvent;
+}
+export declare class EvidenceRecorder {
+    private readonly opts;
+    constructor(opts: EvidenceRecorderOptions);
+    record(input: EvidenceInput): Promise<EvidenceEvent>;
+}
+/** Mask wallet secrets while preserving prompts, model output and benchmark value. */
+export declare function sanitizeEvidenceEvent(event: EvidenceEvent): EvidenceEvent;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,eAAO,MAAM,eAAe,EAAG,yBAAkC,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AACpE,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,cAAc,GACd,WAAW,GACX,WAAW,GACX,aAAa,GACb,cAAc,GACd,OAAO,CAAC;AAEZ,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,KAAK,EAAE,iBAAiB,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IAClD,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,YAAY,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,GAAG,IAAI,IAAI,CAAC;CACb;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,UAAU,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;CACpD;AAED,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,uBAAuB;IAEpD,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;CAU3D;AAkBD,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAazE"}

package/dist/evidence.js

@@ -0,0 +1,47 @@
+export const EVIDENCE_SCHEMA = 'kaleidomind.evidence.v1';
+export class EvidenceRecorder {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async record(input) {
+        let event = {
+            ...input,
+            schema: EVIDENCE_SCHEMA,
+            ts: this.opts.io.now().toISOString(),
+        };
+        event = (this.opts.sanitize ?? sanitizeEvidenceEvent)(event);
+        await this.opts.io.appendLine(JSON.stringify(event));
+        return event;
+    }
+}
+const SENSITIVE_KEYS = new Set([
+    'address',
+    'invoice',
+    'bolt11',
+    'seed',
+    'mnemonic',
+    'private_key',
+    'privateKey',
+    'access_token',
+    'accessToken',
+    'preimage',
+]);
+const PAYMENT_TOKEN = /\b(?:ln(?:bc|tb|bcrt)[0-9a-z]{20,}|(?:bc1|tb1|bcrt1)[0-9a-z]{20,})\b/gi;
+/** Mask wallet secrets while preserving prompts, model output and benchmark value. */
+export function sanitizeEvidenceEvent(event) {
+    const walk = (value, key) => {
+        if (key && SENSITIVE_KEYS.has(key))
+            return '[redacted]';
+        if (typeof value === 'string')
+            return value.replace(PAYMENT_TOKEN, '[payment-data-redacted]');
+        if (Array.isArray(value))
+            return value.map((item) => walk(item));
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, walk(v, k)]));
+        }
+        return value;
+    };
+    return walk(event);
+}
+//# sourceMappingURL=evidence.js.map

package/dist/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,eAAe,GAAG,yBAAkC,CAAC;AA4DlE,MAAM,OAAO,gBAAgB;IACE;IAA7B,YAA6B,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;IAAG,CAAC;IAE9D,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,IAAI,KAAK,GAAkB;YACzB,GAAG,KAAK;YACR,MAAM,EAAE,eAAe;YACvB,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;SACrC,CAAC;QACF,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,qBAAqB,CAAC,CAAC,KAAK,CAAC,CAAC;QAC7D,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,SAAS;IACT,SAAS;IACT,QAAQ;IACR,MAAM;IACN,UAAU;IACV,aAAa;IACb,YAAY;IACZ,cAAc;IACd,aAAa;IACb,UAAU;CACX,CAAC,CAAC;AAEH,MAAM,aAAa,GACjB,wEAAwE,CAAC;AAE3E,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,KAAoB;IACxD,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,GAAY,EAAW,EAAE;QACrD,IAAI,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,YAAY,CAAC;QACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC,aAAa,EAAE,yBAAyB,CAAC,CAAC;QAC9F,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACjE,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAClF,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,CAAkB,CAAC;AACtC,CAAC"}

package/dist/flashnet/contract.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Canonical Flashnet tool contract — AMM swaps on Spark.
+ *
+ * Flashnet is a Spark-native AMM (constant-product + V3 concentrated-liquidity
+ * pools). The agent surface is small and intent-aligned:
+ *
+ *   flashnet_list_pools       — discover pools by asset pair (read)
+ *   flashnet_get_pool         — pool details + reserves (read)
+ *   flashnet_simulate_swap    — quote a swap, no funds move (read)
+ *   flashnet_execute_swap     — SPEND, confirmation-gated (the swap itself)
+ *   flashnet_get_balance      — Spark wallet balance (BTC + tokens) as the
+ *                               AMM client sees it
+ *
+ * The model picks a pool, simulates to see the rate/output, optionally shows
+ * the user the quote, and then executes. The host's `FlashnetClient` (built
+ * over a `SparkWallet`) does the actual signing.
+ *
+ * Asset addresses on Flashnet:
+ *   - BTC is a constant pubkey: `BTC_ASSET_PUBKEY` per network.
+ *   - Tokens are Spark Bech32m token identifiers (or hex; the client coerces).
+ *
+ * Pure data — no deps, RN-safe.
+ */
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+export interface FlashnetToolDef extends ToolDef {
+    /** Moves funds → confirmation-gated. */
+    spend?: boolean;
+}
+/** Canonical Flashnet tools. */
+export declare const FLASHNET_TOOLS: FlashnetToolDef[];
+/** All Flashnet tool names that move funds (confirmation-gated). */
+export declare const FLASHNET_SPEND_TOOLS: Set<string>;
+export declare function isFlashnetSpendTool(name: string): boolean;
+export declare function getFlashnetTool(name: string): FlashnetToolDef | undefined;
+/** A handler bound to one Flashnet tool. */
+export type FlashnetHandler = (args: Record<string, unknown>) => Promise<unknown>;
+export interface BindFlashnetOptions {
+    /** Skip tools without a handler instead of throwing (default false). */
+    allowMissing?: boolean;
+    /** ToolSource id for the registry (default 'flashnet'). */
+    id?: string;
+}
+/**
+ * Bind Flashnet contract tools to in-process handlers → an InProcessToolSource.
+ *
+ *   const source = bindFlashnetTools({
+ *     flashnet_list_pools:     async (a) => client.listPools(a),
+ *     flashnet_get_pool:       async ({ pool_id }) => client.getPoolDetails(pool_id),
+ *     flashnet_simulate_swap:  async (a) => client.simulateSwap(a),
+ *     flashnet_execute_swap:   async (a) => client.executeSwap(a),
+ *     flashnet_get_balance:    async () => client.getBalance(),
+ *   });
+ */
+export declare function bindFlashnetTools(handlers: Record<string, FlashnetHandler>, opts?: BindFlashnetOptions): InProcessToolSource;
+//# sourceMappingURL=contract.d.ts.map

package/dist/flashnet/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/flashnet/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,MAAM,WAAW,eAAgB,SAAQ,OAAO;IAC9C,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuBD,gCAAgC;AAChC,eAAO,MAAM,cAAc,EAAE,eAAe,EAoD3C,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAE5C,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEzE;AAED,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,IAAI,GAAE,mBAAwB,GAC7B,mBAAmB,CAiBrB"}

package/dist/flashnet/contract.js

@@ -0,0 +1,100 @@
+/**
+ * Canonical Flashnet tool contract — AMM swaps on Spark.
+ *
+ * Flashnet is a Spark-native AMM (constant-product + V3 concentrated-liquidity
+ * pools). The agent surface is small and intent-aligned:
+ *
+ *   flashnet_list_pools       — discover pools by asset pair (read)
+ *   flashnet_get_pool         — pool details + reserves (read)
+ *   flashnet_simulate_swap    — quote a swap, no funds move (read)
+ *   flashnet_execute_swap     — SPEND, confirmation-gated (the swap itself)
+ *   flashnet_get_balance      — Spark wallet balance (BTC + tokens) as the
+ *                               AMM client sees it
+ *
+ * The model picks a pool, simulates to see the rate/output, optionally shows
+ * the user the quote, and then executes. The host's `FlashnetClient` (built
+ * over a `SparkWallet`) does the actual signing.
+ *
+ * Asset addresses on Flashnet:
+ *   - BTC is a constant pubkey: `BTC_ASSET_PUBKEY` per network.
+ *   - Tokens are Spark Bech32m token identifiers (or hex; the client coerces).
+ *
+ * Pure data — no deps, RN-safe.
+ */
+import { InProcessToolSource } from '../tools/in-process.js';
+function t(name, description, properties = {}, required = [], spend = false) {
+    return {
+        name,
+        description,
+        spend,
+        requiresConfirmation: spend,
+        parameters: { type: 'object', properties, required },
+    };
+}
+/** Canonical Flashnet tools. */
+export const FLASHNET_TOOLS = [
+    t('flashnet_list_pools', "List Flashnet AMM pools. Filter by asset pair to find a venue for a swap (e.g. asset_a=BTC, asset_b=<USDB address> → pools that swap between them). Returns pools sorted by TVL by default. Use this BEFORE simulate_swap to pick a `pool_id`.", {
+        asset_a: { type: 'string', description: 'OPTIONAL — first asset address (BTC pubkey or Spark token id). Filters pools.' },
+        asset_b: { type: 'string', description: 'OPTIONAL — second asset address. Filters pools containing both assets.' },
+        sort: { type: 'string', description: 'OPTIONAL — sort order. Default TVL_DESC.', enum: ['TVL_DESC', 'TVL_ASC', 'VOLUME24H_DESC', 'VOLUME24H_ASC', 'CREATED_AT_DESC', 'CREATED_AT_ASC'] },
+        limit: { type: 'number', description: 'OPTIONAL — max pools (1–50, default 10).' },
+    }),
+    t('flashnet_get_pool', "Get a single pool's details — reserves, fees, current price, TVL. Use after flashnet_list_pools when the user wants to inspect a pool before swapping.", {
+        pool_id: { type: 'string', description: 'Pool id (LP pubkey) from flashnet_list_pools.' },
+    }, ['pool_id']),
+    t('flashnet_simulate_swap', "Simulate a swap WITHOUT executing — returns `amount_out`, `execution_price`, `price_impact_pct`, `fee_paid`. Read-only. Use this to quote the user before they confirm. The `amount_in` is in smallest units of `asset_in` (sats for BTC, smallest unit of the token).", {
+        pool_id: { type: 'string', description: 'Pool id from flashnet_list_pools.' },
+        asset_in_address: { type: 'string', description: 'Address of the asset the user is selling (BTC pubkey or Spark token id).' },
+        asset_out_address: { type: 'string', description: 'Address of the asset the user is buying.' },
+        amount_in: { type: 'string', description: 'Amount to swap, in smallest units of asset_in. Strings (BigInt-safe). e.g. "100000" for 100k sats.' },
+    }, ['pool_id', 'asset_in_address', 'asset_out_address', 'amount_in']),
+    t('flashnet_execute_swap', "SPEND: confirmation-gated. Execute a swap quoted by flashnet_simulate_swap. `min_amount_out` and `max_slippage_bps` cap the worst-case fill (basis points: 100 = 1%, 50 = 0.5%). Returns the swap request id and the amount actually received.", {
+        pool_id: { type: 'string', description: 'Pool id from flashnet_list_pools.' },
+        asset_in_address: { type: 'string' },
+        asset_out_address: { type: 'string' },
+        amount_in: { type: 'string', description: 'Amount to swap, smallest units.' },
+        min_amount_out: { type: 'string', description: 'Minimum acceptable output, smallest units. Calculate from simulate_swap.amount_out × (1 − max_slippage_bps/10000) and pass that — never trust the simulated value as-is.' },
+        max_slippage_bps: { type: 'number', description: 'Maximum slippage in basis points (default 50 = 0.5%). 100 = 1%, 500 = 5%.' },
+    }, ['pool_id', 'asset_in_address', 'asset_out_address', 'amount_in', 'min_amount_out'], 
+    /* spend */ true),
+    t('flashnet_get_balance', "Get the Spark wallet's BTC + token balances as the Flashnet client sees them. Useful to verify the user has enough of asset_in before quoting or executing a swap. Returns `{ btc_sats, tokens: [{ address, balance, symbol?, decimals? }] }`."),
+];
+/** All Flashnet tool names that move funds (confirmation-gated). */
+export const FLASHNET_SPEND_TOOLS = new Set(FLASHNET_TOOLS.filter((t) => t.spend).map((t) => t.name));
+export function isFlashnetSpendTool(name) {
+    return FLASHNET_SPEND_TOOLS.has(name);
+}
+export function getFlashnetTool(name) {
+    return FLASHNET_TOOLS.find((t) => t.name === name);
+}
+/**
+ * Bind Flashnet contract tools to in-process handlers → an InProcessToolSource.
+ *
+ *   const source = bindFlashnetTools({
+ *     flashnet_list_pools:     async (a) => client.listPools(a),
+ *     flashnet_get_pool:       async ({ pool_id }) => client.getPoolDetails(pool_id),
+ *     flashnet_simulate_swap:  async (a) => client.simulateSwap(a),
+ *     flashnet_execute_swap:   async (a) => client.executeSwap(a),
+ *     flashnet_get_balance:    async () => client.getBalance(),
+ *   });
+ */
+export function bindFlashnetTools(handlers, opts = {}) {
+    const bound = [];
+    for (const def of FLASHNET_TOOLS) {
+        const handler = handlers[def.name];
+        if (!handler) {
+            if (opts.allowMissing)
+                continue;
+            throw new Error(`bindFlashnetTools: no handler for "${def.name}"`);
+        }
+        bound.push({
+            name: def.name,
+            description: def.description,
+            parameters: def.parameters,
+            requiresConfirmation: def.requiresConfirmation,
+            handler,
+        });
+    }
+    return new InProcessToolSource(opts.id ?? 'flashnet', bound);
+}
+//# sourceMappingURL=contract.js.map

package/dist/flashnet/contract.js.map

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