@oobe-protocol-labs/sap-mcp-server 0.9.21 → 0.9.35

package/dist/memory/tool-call-store.js

@@ -0,0 +1,189 @@
+/**
+ * @module memory/tool-call-store
+ * @description Store for recording and searching tool call history.
+ *
+ * All methods are synchronous (better-sqlite3 is synchronous). FTS5 search
+ * returns relevance-ranked results using the inverted index.
+ */
+import { memoryDatabase } from './database.js';
+import { truncate } from './utils.js';
+/**
+ * @name ToolCallStore
+ * @description Records and queries tool call execution history.
+ *
+ * Every tool call (paid or free) is recorded with its input, output, outcome,
+ * cost, and latency. The FTS5 index enables full-text search across all
+ * recorded calls for pattern detection and failure analysis.
+ */
+export class ToolCallStore {
+    /**
+     * @name record
+     * @description Records a tool call execution in the memory database.
+     * @param record - Tool call data to record.
+     * @returns The auto-incremented ID of the inserted record, or -1 if degraded.
+     */
+    record(record) {
+        if (memoryDatabase.isDegraded())
+            return -1;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('insert_tool_call');
+        if (!stmt)
+            return -1;
+        const maxBytes = 8192;
+        const result = stmt.run({
+            toolName: record.toolName,
+            sessionId: record.sessionId,
+            callerProfile: record.callerProfile,
+            input: truncate(record.input, maxBytes),
+            output: truncate(record.output, maxBytes),
+            outcome: record.outcome,
+            costUsd: record.costUsd ?? null,
+            txSignature: record.txSignature ?? null,
+            latencyMs: record.latencyMs ?? null,
+        });
+        return result.lastInsertRowid;
+    }
+    /**
+     * @name search
+     * @description Full-text search across tool call history using FTS5.
+     * @param options - Search options including query, filters, and pagination.
+     * @returns Search results with relevance ranking.
+     */
+    search(options) {
+        if (memoryDatabase.isDegraded()) {
+            return { results: [], total: 0, hasMore: false };
+        }
+        memoryDatabase.init();
+        const db = memoryDatabase.getDb();
+        const limit = Math.min(options.limit ?? 20, 100);
+        const offset = options.offset ?? 0;
+        // Build FTS5 query with optional filters.
+        let whereClause = '';
+        const params = { limit, offset };
+        if (options.toolName) {
+            whereClause += ' AND t.tool_name = @toolName';
+            params['toolName'] = options.toolName;
+        }
+        if (options.outcome) {
+            whereClause += ' AND t.outcome = @outcome';
+            params['outcome'] = options.outcome;
+        }
+        // FTS5 MATCH query — use bm25 ranking for relevance.
+        const ftsQuery = this.buildFtsQuery(options.query);
+        const sql = `
+      SELECT t.id, t.tool_name, t.session_id, t.caller_profile, t.input, t.output,
+             t.outcome, t.cost_usd, t.tx_signature, t.latency_ms,
+             t.created_at, t.updated_at
+      FROM tool_calls_fts fts
+      JOIN tool_calls t ON t.id = fts.rowid
+      WHERE tool_calls_fts MATCH @ftsQuery
+      ${whereClause}
+      ORDER BY ${options.sort === 'newest' ? 't.created_at DESC' : options.sort === 'oldest' ? 't.created_at ASC' : 'bm25(tool_calls_fts)'}
+      LIMIT @limit OFFSET @offset
+    `;
+        params['ftsQuery'] = ftsQuery;
+        try {
+            const results = db.prepare(sql).all(params);
+            const countSql = `
+        SELECT COUNT(*) as total
+        FROM tool_calls_fts fts
+        JOIN tool_calls t ON t.id = fts.rowid
+        WHERE tool_calls_fts MATCH @ftsQuery ${whereClause}
+      `;
+            const countResult = db.prepare(countSql).get(params);
+            const total = countResult?.total ?? 0;
+            return {
+                results,
+                total,
+                hasMore: offset + results.length < total,
+            };
+        }
+        catch {
+            return { results: [], total: 0, hasMore: false };
+        }
+    }
+    /**
+     * @name count
+     * @description Returns the total number of tool call records.
+     */
+    count() {
+        if (memoryDatabase.isDegraded())
+            return 0;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('count_tool_calls');
+        if (!stmt)
+            return 0;
+        return stmt.get().count;
+    }
+    /**
+     * @name outcomeBreakdown
+     * @description Returns counts grouped by outcome.
+     */
+    outcomeBreakdown() {
+        if (memoryDatabase.isDegraded()) {
+            return { success: 0, error: 0, partial: 0 };
+        }
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('count_tool_calls_by_outcome');
+        if (!stmt)
+            return { success: 0, error: 0, partial: 0 };
+        const rows = stmt.all();
+        const result = { success: 0, error: 0, partial: 0 };
+        for (const row of rows) {
+            result[row.outcome] = row.count;
+        }
+        return result;
+    }
+    /**
+     * @name lastToolCallAt
+     * @description Returns the timestamp of the most recent tool call.
+     */
+    lastToolCallAt() {
+        if (memoryDatabase.isDegraded())
+            return null;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('last_tool_call_at');
+        if (!stmt)
+            return null;
+        const row = stmt.get();
+        return row?.created_at ?? null;
+    }
+    /**
+     * @name archive
+     * @description Archives tool call records older than the retention period.
+     * @param retentionDays - Number of days to keep records. Default 90.
+     * @returns Number of records archived.
+     */
+    archive(retentionDays = 90) {
+        if (memoryDatabase.isDegraded())
+            return 0;
+        memoryDatabase.init();
+        const db = memoryDatabase.getDb();
+        const result = db.prepare(`DELETE FROM tool_calls WHERE created_at < datetime('now', ?)`).run(`-${retentionDays} days`);
+        return result.changes;
+    }
+    /**
+     * @name buildFtsQuery
+     * @description Converts a natural language query into a FTS5 MATCH expression.
+     * Handles multi-word queries by quoting phrases and prefixing with OR for
+     * broader recall.
+     * @internal
+     */
+    buildFtsQuery(query) {
+        // Escape FTS5 special characters and wrap in quotes for phrase matching.
+        const escaped = query.replace(/["'*:]/g, ' ').trim();
+        if (!escaped)
+            return '*';
+        // For multi-word queries, use OR to match any word (broader recall).
+        const words = escaped.split(/\s+/).filter(w => w.length > 0);
+        if (words.length === 1)
+            return `"${words[0]}"*`;
+        return words.map(w => `"${w}"*`).join(' OR ');
+    }
+}
+/**
+ * @name toolCallStore
+ * @description Singleton instance of the tool call store.
+ */
+export const toolCallStore = new ToolCallStore();
+//# sourceMappingURL=tool-call-store.js.map

package/dist/memory/tool-call-store.js.map

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

package/dist/memory/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @module memory/types
+ * @description Type definitions for the SAP MCP local agent memory subsystem.
+ *
+ * The memory subsystem uses SQLite FTS5 to store and retrieve:
+ * - Tool call history (input, output, outcome, cost, latency)
+ * - Agent memories (LLM-compressed summaries of past interactions)
+ * - Stream buffer events (premium stream data persisted locally)
+ *
+ * All types are designed for non-custodial, local-only operation — no data
+ * leaves the user's machine. The memory DB is stored at
+ * ~/.config/mcp-sap/memory/agent-memory.db.
+ */
+/**
+ * @name ToolCallRecord
+ * @description A single tool call execution record stored in the memory DB.
+ */
+export interface ToolCallRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** MCP tool name (e.g. 'jupiter_getQuote', 'sap_build_sol_transfer'). */
+    toolName: string;
+    /** Session identifier from the MCP transport. */
+    sessionId: string | null;
+    /** Signer profile used for the call, if any. */
+    callerProfile: string | null;
+    /** JSON-serialized tool input. Truncated to 8KB. */
+    input: string;
+    /** JSON-serialized tool output. Truncated to 8KB. */
+    output: string;
+    /** Execution outcome classification. */
+    outcome: ToolCallOutcome;
+    /** x402 cost in USD, if the tool was paid. */
+    costUsd: number | null;
+    /** Solana transaction signature, if the tool produced one. */
+    txSignature: string | null;
+    /** Execution latency in milliseconds. */
+    latencyMs: number | null;
+    /** ISO 8601 timestamp of when the record was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp of when the record was last updated. */
+    updatedAt: string;
+}
+/**
+ * @name ToolCallOutcome
+ * @description Classification of a tool call's execution result.
+ */
+export type ToolCallOutcome = 'success' | 'error' | 'partial';
+/**
+ * @name AgentMemoryRecord
+ * @description An LLM-generated summary of past agent interactions.
+ *
+ * Memories are compressed representations of tool call patterns, failures,
+ * successes, and lessons learned. They decay over time via a relevance
+ * score that decreases as memories age, ensuring the agent prioritizes
+ * recent, high-signal knowledge.
+ */
+export interface AgentMemoryRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** Type of memory — determines how it's used in prompt injection. */
+    memoryType: MemoryType;
+    /** Tool category this memory relates to (e.g. 'jupiter', 'adrena', 'premium'). */
+    category: string;
+    /** LLM-compressed summary text. Max 4KB. */
+    summary: string;
+    /** JSON array of tool_call IDs that were the source of this memory. */
+    sourceToolCalls: string | null;
+    /** Relevance score 0-1. Decays over time. Higher = more relevant. */
+    relevanceScore: number;
+    /** ISO 8601 timestamp of when the memory was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp of when the memory expires. NULL = never expires. */
+    expiresAt: string | null;
+    /** ISO 8601 timestamp of when the memory was last accessed. */
+    lastAccessedAt: string;
+}
+/**
+ * @name MemoryType
+ * @description Classification of agent memory entries.
+ * - 'lesson': A learned pattern or rule (e.g. "Jupiter swaps fail when slippage < 50bps on low-liquidity pairs")
+ * - 'pattern': A recurring behavior (e.g. "Agent consistently buys when SOL price drops > 2%")
+ * - 'failure': A specific failure with root cause (e.g. "BlockhashNotFound after 90s — retry with fresh blockhash")
+ * - 'success': A successful outcome worth remembering (e.g. "Arb opportunity on SOL/USDC at block 123456")
+ */
+export type MemoryType = 'lesson' | 'pattern' | 'failure' | 'success';
+/**
+ * @name StreamBufferRecord
+ * @description A buffered stream event persisted locally for offline analysis.
+ */
+export interface StreamBufferRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** Stream type identifier (e.g. 'pyth-price', 'meme-alerts', 'volatility'). */
+    streamType: string;
+    /** Unique event ID from the provider. */
+    eventId: string;
+    /** Event type from the provider (e.g. 'price.tick', 'volatility.breakout'). */
+    eventType: string;
+    /** JSON-serialized event payload. */
+    payload: string;
+    /** Whether the event has been consumed by the agent. */
+    consumed: number;
+    /** ISO 8601 timestamp of when the event was buffered. */
+    createdAt: string;
+}
+/**
+ * @name MemorySearchResult
+ * @description A result from a full-text search across tool calls or agent memories.
+ */
+export interface MemorySearchResult<T = unknown> {
+    /** The matching records. */
+    results: T[];
+    /** Total number of matching records (before pagination). */
+    total: number;
+    /** Whether there are more results available. */
+    hasMore: boolean;
+}
+/**
+ * @name MemoryQueryOptions
+ * @description Options for searching the memory database.
+ */
+export interface MemoryQueryOptions {
+    /** FTS5 search query (e.g. 'swap failure', 'jupiter slippage'). */
+    query: string;
+    /** Filter by tool name (tool_calls only). */
+    toolName?: string;
+    /** Filter by outcome (tool_calls only). */
+    outcome?: ToolCallOutcome;
+    /** Filter by memory type (agent_memory only). */
+    memoryType?: MemoryType;
+    /** Filter by category. */
+    category?: string;
+    /** Minimum relevance score (agent_memory only). */
+    minRelevance?: number;
+    /** Maximum number of results to return. Default 20. */
+    limit?: number;
+    /** Offset for pagination. Default 0. */
+    offset?: number;
+    /** Sort order. Default 'relevance' for FTS, 'newest' for time-based. */
+    sort?: 'relevance' | 'newest' | 'oldest';
+}
+/**
+ * @name MemoryStats
+ * @description Aggregate statistics about the memory database.
+ */
+export interface MemoryStats {
+    /** Total number of tool call records. */
+    toolCallCount: number;
+    /** Total number of agent memory records. */
+    memoryCount: number;
+    /** Total number of stream buffer records (unconsumed). */
+    pendingStreamEvents: number;
+    /** Total database size in bytes. */
+    dbSizeBytes: number;
+    /** Breakdown of tool calls by outcome. */
+    outcomeBreakdown: Record<ToolCallOutcome, number>;
+    /** Breakdown of agent memories by type. */
+    memoryTypeBreakdown: Record<MemoryType, number>;
+    /** Most recent tool call timestamp. */
+    lastToolCallAt: string | null;
+    /** Most recent memory timestamp. */
+    lastMemoryAt: string | null;
+}
+/**
+ * @name MemoryPruneResult
+ * @description Result of pruning old, low-relevance memories.
+ */
+export interface MemoryPruneResult {
+    /** Number of memories pruned. */
+    pruned: number;
+    /** Number of tool calls archived (old records). */
+    archived: number;
+    /** Database size reduction in bytes. */
+    freedBytes: number;
+}
+/**
+ * @name MemoryConfig
+ * @description Configuration for the memory subsystem.
+ */
+export interface MemoryConfig {
+    /** Path to the SQLite database file. */
+    dbPath: string;
+    /** Whether to enable WAL mode (recommended for concurrent access). */
+    enableWal: boolean;
+    /** Maximum size of tool call input/output stored. Default 8192 bytes. */
+    maxPayloadBytes: number;
+    /** Relevance decay rate per day. Default 0.01 (1% per day). */
+    relevanceDecayPerDay: number;
+    /** Minimum relevance score to keep a memory. Default 0.05. */
+    minRelevanceThreshold: number;
+    /** Number of days to keep tool call records. Default 90. */
+    toolCallRetentionDays: number;
+    /** Maximum number of stream buffer events per type. Default 10000. */
+    maxStreamBufferSize: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

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

package/dist/memory/types.js

@@ -0,0 +1,15 @@
+/**
+ * @module memory/types
+ * @description Type definitions for the SAP MCP local agent memory subsystem.
+ *
+ * The memory subsystem uses SQLite FTS5 to store and retrieve:
+ * - Tool call history (input, output, outcome, cost, latency)
+ * - Agent memories (LLM-compressed summaries of past interactions)
+ * - Stream buffer events (premium stream data persisted locally)
+ *
+ * All types are designed for non-custodial, local-only operation — no data
+ * leaves the user's machine. The memory DB is stored at
+ * ~/.config/mcp-sap/memory/agent-memory.db.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/memory/utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module memory/utils
+ * @description Utility functions for the memory subsystem.
+ */
+/**
+ * @name truncate
+ * @description Truncates a string to the specified byte length, ensuring it
+ * doesn't end in the middle of a multi-byte UTF-8 sequence.
+ * @param str - The string to truncate.
+ * @param maxBytes - Maximum byte length.
+ * @returns The truncated string.
+ */
+export declare function truncate(str: string, maxBytes: number): string;
+/**
+ * @name decayRelevance
+ * @description Computes the decayed relevance score based on days since creation.
+ * @param initialScore - Initial relevance score (0-1).
+ * @param createdAt - ISO 8601 timestamp of creation.
+ * @param decayPerDay - Decay rate per day (e.g. 0.01 = 1% per day).
+ * @returns Decayed relevance score, clamped to [0, 1].
+ */
+export declare function decayRelevance(initialScore: number, createdAt: string, decayPerDay: number): number;
+/**
+ * @name isExpired
+ * @description Checks if a memory record has expired.
+ * @param expiresAt - ISO 8601 timestamp or null (null = never expires).
+ * @returns True if the memory has expired.
+ */
+export declare function isExpired(expiresAt: string | null): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/memory/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/memory/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAG3D"}

package/dist/memory/utils.js

@@ -0,0 +1,47 @@
+/**
+ * @module memory/utils
+ * @description Utility functions for the memory subsystem.
+ */
+/**
+ * @name truncate
+ * @description Truncates a string to the specified byte length, ensuring it
+ * doesn't end in the middle of a multi-byte UTF-8 sequence.
+ * @param str - The string to truncate.
+ * @param maxBytes - Maximum byte length.
+ * @returns The truncated string.
+ */
+export function truncate(str, maxBytes) {
+    if (!str)
+        return '';
+    const buf = Buffer.from(str, 'utf-8');
+    if (buf.length <= maxBytes)
+        return str;
+    return buf.subarray(0, maxBytes).toString('utf-8');
+}
+/**
+ * @name decayRelevance
+ * @description Computes the decayed relevance score based on days since creation.
+ * @param initialScore - Initial relevance score (0-1).
+ * @param createdAt - ISO 8601 timestamp of creation.
+ * @param decayPerDay - Decay rate per day (e.g. 0.01 = 1% per day).
+ * @returns Decayed relevance score, clamped to [0, 1].
+ */
+export function decayRelevance(initialScore, createdAt, decayPerDay) {
+    const created = new Date(createdAt).getTime();
+    const now = Date.now();
+    const daysSince = (now - created) / (1000 * 60 * 60 * 24);
+    const decayed = initialScore * Math.pow(1 - decayPerDay, daysSince);
+    return Math.max(0, Math.min(1, decayed));
+}
+/**
+ * @name isExpired
+ * @description Checks if a memory record has expired.
+ * @param expiresAt - ISO 8601 timestamp or null (null = never expires).
+ * @returns True if the memory has expired.
+ */
+export function isExpired(expiresAt) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() <= Date.now();
+}
+//# sourceMappingURL=utils.js.map

package/dist/memory/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/memory/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,QAAgB;IACpD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,GAAG,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,GAAG,CAAC;IACvC,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,SAAiB,EACjB,WAAmB;IAEnB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,SAAS,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,SAAwB;IAChD,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AACrD,CAAC"}

package/dist/payments/hosted-tool-eligibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-tool-eligibility.d.ts","sourceRoot":"","sources":["../../src/payments/hosted-tool-eligibility.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,IAAI,CAAC;QACxB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,UAAU,EAAE,2BAA2B,CAAC;QACxC,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH;AAoID,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,gBAAgB,EAC/B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,mBAAmB,CAAC,GACtE,4BAA4B,GAAG,SAAS,CAiC1C;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWxE"}
+{"version":3,"file":"hosted-tool-eligibility.d.ts","sourceRoot":"","sources":["../../src/payments/hosted-tool-eligibility.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,IAAI,CAAC;QACxB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,UAAU,EAAE,2BAA2B,CAAC;QACxC,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH;AAgID,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,gBAAgB,EAC/B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,mBAAmB,CAAC,GACtE,4BAA4B,GAAG,SAAS,CAmC1C;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWxE"}

package/dist/payments/hosted-tool-eligibility.js

@@ -17,12 +17,6 @@ const LOCAL_SIGNER_ONLY_EXACT_TOOLS = new Set([
     'blinks_executeAction',
     'bridging_bridgeDeBridge',
     'bridging_bridgeWormhole',
-    'drift_borrow',
-    'drift_closePerpPosition',
-    'drift_deposit',
-    'drift_lend',
-    'drift_openPerpPosition',
-    'drift_withdraw',
     'gibwork_createBounty',
     'gibwork_submitWork',
     'jito_sendBundle',
@@ -115,6 +109,8 @@ const HOSTED_SAFE_PREFIXES = [
 ];
 const HOSTED_SAFE_EXACT_TOOLS = new Set([
     'sap_submit_signed_transaction',
+    'sap_build_sol_transfer',
+    'sap_build_spl_transfer',
     'sap_sns_check_domain',
     'sap_sns_batch_check_domains',
     'sap_sns_validate_records',
@@ -151,6 +147,8 @@ export function evaluateHostedToolEligibility(parsedRequest, config) {
                 'sap_payments_readiness',
                 'sap_payments_call_paid_tool',
                 'sap_payments_finalize_transaction',
+                'sap_build_sol_transfer',
+                'sap_build_spl_transfer',
                 'sap_escrow_build_create_transaction',
                 'sap_escrow_build_settle_transaction',
                 'sap_sns_build_manage_record_transaction',

package/dist/payments/hosted-tool-eligibility.js.map

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

package/dist/payments/monetization-gate.d.ts

@@ -46,6 +46,23 @@ export declare class McpMonetizationGate {
     private readonly monetization;
     private readonly httpResourceServer;
     private readonly usageLedger;
+    /**
+     * @description x402 idempotency cache — prevents double-charge on retry.
+     *
+     * Keyed by `requestHash`. When a settlement succeeds, the receipt is cached
+     * for 5 minutes. If the same requestHash is retried (e.g. network failure
+     * after the tool executed but before the response reached the client), the
+     * cached settlement is returned without re-charging the payer's USDC.
+     *
+     * The cache is bounded to 10,000 entries (evicts oldest on overflow). Each
+     * entry has a TTL of 5 minutes — long enough for client retry logic, short
+     * enough to avoid stale receipts blocking legitimate re-requests.
+     *
+     * @internal
+     */
+    private readonly idempotencyCache;
+    private static readonly IDEMPOTENCY_TTL_MS;
+    private static readonly IDEMPOTENCY_MAX_ENTRIES;
     private constructor();
     /**
      * @name create
@@ -57,6 +74,28 @@ export declare class McpMonetizationGate {
      * @description Flushes hosted payment audit state before the remote server exits.
      */
     close(): Promise<void>;
+    /**
+     * @name isJsonRpcError
+     * @description Checks if a buffered HTTP response body contains a JSON-RPC error.
+     *
+     * JSON-RPC errors have the shape `{ "error": { "code": <number>, "message": <string> } }`
+     * or MCP tool results with `isError: true`. When detected, settlement is skipped
+     * so the user is not charged for failed tool calls.
+     *
+     * @internal
+     */
+    private isJsonRpcError;
+    /**
+     * @name pruneExpiredIdempotencyEntries
+     * @description Opportunistically remove expired entries from the idempotency cache.
+     *
+     * Called after each successful settlement to keep the cache bounded without
+     * a separate timer. Scans at most 100 entries per call to avoid O(n) overhead
+     * on every settle.
+     *
+     * @internal
+     */
+    private pruneExpiredIdempotencyEntries;
     /**
      * @name handle
      * @description Authorizes a request via x402 when required, then forwards it to MCP and settles on success.

package/dist/payments/monetization-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monetization-gate.d.ts","sourceRoot":"","sources":["../../src/payments/monetization-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAiB7B,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,kBAAkB,CAAC;AAK/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKpD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,UAAU,CAAC,EAAE,OAAO,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,+BAA+B,KAAK,+BAA+B,GAAG,SAAS,CAAC;CACjH;AA+CD;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C,OAAO;IAWP;;;OAGG;WACiB,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IA6C7F;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;;OAGG;IACU,MAAM,CACjB,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC;IAuPhB;;;OAGG;YACW,mBAAmB;YAwLnB,eAAe;IAa7B,OAAO,CAAC,mBAAmB;IAoB3B;;;;;;OAMG;YACW,mBAAmB;YA8CnB,gBAAgB;YAyDhB,eAAe;CAsD9B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAclE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY/D;AAgFD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxH"}
+{"version":3,"file":"monetization-gate.d.ts","sourceRoot":"","sources":["../../src/payments/monetization-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAiB7B,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,kBAAkB,CAAC;AAK/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKpD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,UAAU,CAAC,EAAE,OAAO,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,+BAA+B,KAAK,+BAA+B,GAAG,SAAS,CAAC;CACjH;AA+CD;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwE;IACzG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAiB;IAC3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAU;IAEzD,OAAO;IAWP;;;OAGG;WACiB,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IA6C7F;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAiDtB;;;;;;;;;OASG;IACH,OAAO,CAAC,8BAA8B;IAWtC;;;OAGG;IACU,MAAM,CACjB,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC;IAuPhB;;;OAGG;YACW,mBAAmB;YA0OnB,eAAe;IAa7B,OAAO,CAAC,mBAAmB;IAoB3B;;;;;;OAMG;YACW,mBAAmB;YA8CnB,gBAAgB;YAyDhB,eAAe;CAsD9B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAclE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY/D;AAgFD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxH"}