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

package/dist/memory/async-processor.js

@@ -0,0 +1,204 @@
+/**
+ * @module memory/async-processor
+ * @description Async background processor for memory maintenance tasks.
+ *
+ * Runs periodic maintenance on the memory database without blocking the main
+ * event loop:
+ * - Relevance decay application (every 1 hour)
+ * - Stream buffer eviction (every 5 minutes)
+ * - Tool call archiving (every 1 hour)
+ * - Memory pruning (every 6 hours)
+ * - WAL checkpoint (every 10 minutes)
+ *
+ * Uses setImmediate + setTimeout for non-blocking scheduling. The processor
+ * is a singleton that starts when the MCP server boots and stops on shutdown.
+ */
+import { memoryDatabase } from './database.js';
+import { toolCallStore } from './tool-call-store.js';
+import { memoryStore } from './memory-store.js';
+import { streamBufferStore } from './stream-buffer-store.js';
+import { logger } from '../core/logger.js';
+const DEFAULT_SCHEDULE = {
+    decayIntervalMs: 60 * 60 * 1000, // 1 hour
+    evictIntervalMs: 5 * 60 * 1000, // 5 minutes
+    archiveIntervalMs: 60 * 60 * 1000, // 1 hour
+    pruneIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
+    checkpointIntervalMs: 10 * 60 * 1000, // 10 minutes
+};
+/**
+ * @name AsyncMemoryProcessor
+ * @description Background processor for memory maintenance.
+ *
+ * Runs non-blocking periodic tasks using setTimeout chains (not setInterval,
+ * to avoid overlapping executions). Each task catches its own errors and logs
+ * them — a failure in one task doesn't stop the others.
+ */
+export class AsyncMemoryProcessor {
+    timers = new Set();
+    running = false;
+    schedule;
+    constructor(schedule = {}) {
+        this.schedule = { ...DEFAULT_SCHEDULE, ...schedule };
+    }
+    /**
+     * @name start
+     * @description Starts all background maintenance tasks.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.scheduleTask('decay', this.schedule.decayIntervalMs, () => this.runDecay());
+        this.scheduleTask('evict', this.schedule.evictIntervalMs, () => this.runEvict());
+        this.scheduleTask('archive', this.schedule.archiveIntervalMs, () => this.runArchive());
+        this.scheduleTask('prune', this.schedule.pruneIntervalMs, () => this.runPrune());
+        this.scheduleTask('checkpoint', this.schedule.checkpointIntervalMs, () => this.runCheckpoint());
+        logger.info('Memory async processor started', {
+            tasks: ['decay', 'evict', 'archive', 'prune', 'checkpoint'],
+        });
+    }
+    /**
+     * @name stop
+     * @description Stops all background tasks and clears timers.
+     */
+    stop() {
+        this.running = false;
+        for (const timer of this.timers) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        logger.info('Memory async processor stopped');
+    }
+    /**
+     * @name isRunning
+     * @description Returns whether the processor is running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    // ── Task Scheduling ────────────────────────────────────────────────────────
+    /**
+     * @name scheduleTask
+     * @description Schedules a recurring task using setTimeout chains.
+     * Uses setImmediate for the first run to avoid blocking server startup.
+     * @internal
+     */
+    scheduleTask(name, intervalMs, task) {
+        const run = () => {
+            if (!this.running)
+                return;
+            // Execute the task — errors are caught and logged, never propagated.
+            try {
+                task();
+            }
+            catch (error) {
+                logger.warn(`Memory maintenance task "${name}" failed`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            // Schedule the next run.
+            if (this.running) {
+                const timer = setTimeout(run, intervalMs);
+                this.timers.add(timer);
+                // Auto-clean the timer reference when it fires.
+                timer.unref?.();
+            }
+        };
+        // First run after a short delay (don't block startup).
+        const timer = setTimeout(run, 5000);
+        this.timers.add(timer);
+        timer.unref?.();
+    }
+    // ── Maintenance Tasks ──────────────────────────────────────────────────────
+    /**
+     * @name runDecay
+     * @description Applies relevance decay to all agent memories.
+     * The decay is computed in JS (better-sqlite3 is synchronous) and applied
+     * as a batch UPDATE.
+     * @internal
+     */
+    runDecay() {
+        if (memoryDatabase.isDegraded())
+            return;
+        memoryDatabase.init();
+        const db = memoryDatabase.getDb();
+        const rows = db.prepare('SELECT id, relevance_score, created_at FROM agent_memory WHERE expires_at IS NULL OR expires_at > datetime(\'now\')').all();
+        let updated = 0;
+        const updateStmt = db.prepare('UPDATE agent_memory SET relevance_score = ? WHERE id = ?');
+        const now = Date.now();
+        for (const row of rows) {
+            const created = new Date(row.created_at).getTime();
+            const daysSince = (now - created) / (1000 * 60 * 60 * 24);
+            const decayed = row.relevance_score * Math.pow(0.99, daysSince);
+            const clamped = Math.max(0, Math.min(1, decayed));
+            if (Math.abs(clamped - row.relevance_score) > 0.001) {
+                updateStmt.run(clamped, row.id);
+                updated++;
+            }
+        }
+        if (updated > 0) {
+            logger.debug('Memory decay applied', { updated, total: rows.length });
+        }
+    }
+    /**
+     * @name runEvict
+     * @description Evicts old consumed stream events to keep the buffer bounded.
+     * @internal
+     */
+    runEvict() {
+        if (memoryDatabase.isDegraded())
+            return;
+        const evicted = streamBufferStore.evict(10_000);
+        if (evicted > 0) {
+            logger.debug('Stream buffer evicted', { evicted });
+        }
+    }
+    /**
+     * @name runArchive
+     * @description Archives tool call records older than the retention period.
+     * @internal
+     */
+    runArchive() {
+        if (memoryDatabase.isDegraded())
+            return;
+        const archived = toolCallStore.archive(90);
+        if (archived > 0) {
+            logger.debug('Tool calls archived', { archived });
+        }
+    }
+    /**
+     * @name runPrune
+     * @description Prunes expired and low-relevance memories.
+     * @internal
+     */
+    runPrune() {
+        if (memoryDatabase.isDegraded())
+            return;
+        const pruned = memoryStore.prune(0.05);
+        if (pruned > 0) {
+            logger.debug('Memories pruned', { pruned });
+        }
+    }
+    /**
+     * @name runCheckpoint
+     * @description Forces a WAL checkpoint to prevent the WAL file from growing
+     * unbounded. Uses PASSIVE mode to avoid blocking readers.
+     * @internal
+     */
+    runCheckpoint() {
+        if (memoryDatabase.isDegraded())
+            return;
+        try {
+            memoryDatabase.getDb().pragma('wal_checkpoint(PASSIVE)');
+        }
+        catch {
+            // Best-effort checkpoint.
+        }
+    }
+}
+/**
+ * @name asyncMemoryProcessor
+ * @description Singleton instance of the async memory processor.
+ */
+export const asyncMemoryProcessor = new AsyncMemoryProcessor();
+//# sourceMappingURL=async-processor.js.map

package/dist/memory/async-processor.js.map

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

package/dist/memory/auto-record.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module memory/auto-record
+ * @description Automatic tool call recording hook.
+ *
+ * Wraps the MCP tool handler to automatically record every tool call in the
+ * local memory database — no agent action required. The hook measures
+ * latency, captures the outcome, and stores truncated input/output.
+ *
+ * The hook is designed to be non-blocking: if the memory DB is degraded or
+ * the recording fails, the tool call proceeds normally. Recording errors
+ * are logged but never propagated to the caller.
+ */
+/**
+ * @name AutoRecordResult
+ * @description Result of a tool call with metadata for recording.
+ */
+export interface AutoRecordResult {
+    /** The original tool result text. */
+    result: string;
+    /** Whether the result indicates an error. */
+    isError: boolean;
+}
+/**
+ * @name recordToolCall
+ * @description Records a tool call execution in the memory database.
+ *
+ * This function is called after every tool handler executes. It captures:
+ * - toolName: the MCP tool name
+ * - input: JSON-serialized input (truncated to 8KB)
+ * - output: JSON-serialized output (truncated to 8KB)
+ * - outcome: 'success' | 'error' | 'partial'
+ * - latencyMs: wall-clock time from start to finish
+ * - costUsd: estimated from the pricing tier (if available)
+ * - txSignature: extracted from the output if present
+ *
+ * The function never throws — recording failures are logged and swallowed.
+ *
+ * @param toolName - The MCP tool name.
+ * @param input - The raw input object passed to the tool.
+ * @param output - The tool result text.
+ * @param isError - Whether the tool returned an error.
+ * @param latencyMs - Execution latency in milliseconds.
+ * @param sessionId - Optional session identifier.
+ * @param callerProfile - Optional signer profile.
+ */
+export declare function recordToolCall(toolName: string, input: unknown, output: string, isError: boolean, latencyMs: number, sessionId?: string, callerProfile?: string): void;
+//# sourceMappingURL=auto-record.d.ts.map

package/dist/memory/auto-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-record.d.ts","sourceRoot":"","sources":["../../src/memory/auto-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAuCN"}

package/dist/memory/auto-record.js

@@ -0,0 +1,133 @@
+/**
+ * @module memory/auto-record
+ * @description Automatic tool call recording hook.
+ *
+ * Wraps the MCP tool handler to automatically record every tool call in the
+ * local memory database — no agent action required. The hook measures
+ * latency, captures the outcome, and stores truncated input/output.
+ *
+ * The hook is designed to be non-blocking: if the memory DB is degraded or
+ * the recording fails, the tool call proceeds normally. Recording errors
+ * are logged but never propagated to the caller.
+ */
+import { toolCallStore } from './tool-call-store.js';
+import { memoryDatabase } from './database.js';
+import { logger } from '../core/logger.js';
+/**
+ * @name recordToolCall
+ * @description Records a tool call execution in the memory database.
+ *
+ * This function is called after every tool handler executes. It captures:
+ * - toolName: the MCP tool name
+ * - input: JSON-serialized input (truncated to 8KB)
+ * - output: JSON-serialized output (truncated to 8KB)
+ * - outcome: 'success' | 'error' | 'partial'
+ * - latencyMs: wall-clock time from start to finish
+ * - costUsd: estimated from the pricing tier (if available)
+ * - txSignature: extracted from the output if present
+ *
+ * The function never throws — recording failures are logged and swallowed.
+ *
+ * @param toolName - The MCP tool name.
+ * @param input - The raw input object passed to the tool.
+ * @param output - The tool result text.
+ * @param isError - Whether the tool returned an error.
+ * @param latencyMs - Execution latency in milliseconds.
+ * @param sessionId - Optional session identifier.
+ * @param callerProfile - Optional signer profile.
+ */
+export function recordToolCall(toolName, input, output, isError, latencyMs, sessionId, callerProfile) {
+    // Skip recording for memory tools themselves — avoid infinite recursion.
+    if (toolName.startsWith('sap_memory_') || toolName.startsWith('sap_audit_') || toolName.startsWith('sap_strategy_') || toolName.startsWith('sap_stream_')) {
+        return;
+    }
+    // Skip if the memory database is degraded.
+    if (memoryDatabase.isDegraded())
+        return;
+    try {
+        // Serialize input/output with truncation.
+        const inputJson = safeStringify(input, 8192);
+        const outputJson = safeStringify(output, 8192);
+        // Determine outcome.
+        const outcome = isError ? 'error' : determineOutcome(output);
+        // Extract transaction signature from output if present.
+        const txSignature = extractTxSignature(output);
+        // Record in the database.
+        toolCallStore.record({
+            toolName,
+            sessionId: sessionId ?? null,
+            callerProfile: callerProfile ?? null,
+            input: inputJson,
+            output: outputJson,
+            outcome,
+            costUsd: null, // Cost is tracked by the x402 gate, not here.
+            txSignature,
+            latencyMs,
+        });
+    }
+    catch (error) {
+        // Never propagate recording errors — the tool call already succeeded.
+        logger.debug('Auto-record failed', {
+            toolName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * @name determineOutcome
+ * @description Classifies the tool call outcome from the output text.
+ * Checks for partial success indicators (e.g. "partial", "some failed", "retry").
+ * @internal
+ */
+function determineOutcome(output) {
+    const lower = output.toLowerCase();
+    if (lower.includes('"partial"') || lower.includes('"some failed"') || lower.includes('"retry-safe": false')) {
+        return 'partial';
+    }
+    return 'success';
+}
+/**
+ * @name extractTxSignature
+ * @description Extracts a Solana transaction signature from the tool output.
+ * Looks for common patterns like "signature": "..." or "txSignature": "...".
+ * @internal
+ */
+function extractTxSignature(output) {
+    // Try JSON parsing first.
+    try {
+        const parsed = JSON.parse(output);
+        if (typeof parsed['signature'] === 'string')
+            return parsed['signature'];
+        if (typeof parsed['txSignature'] === 'string')
+            return parsed['txSignature'];
+        if (typeof parsed['transactionSignature'] === 'string')
+            return parsed['transactionSignature'];
+    }
+    catch {
+        // Not JSON — try regex.
+    }
+    // Regex fallback for base58 signatures (64-88 chars).
+    const match = output.match(/\b[1-9A-HJ-NP-Za-km-z]{64,88}\b/);
+    return match ? match[0] : null;
+}
+/**
+ * @name safeStringify
+ * @description Safely serializes a value to JSON with truncation.
+ * Handles circular references and large objects.
+ * @internal
+ */
+function safeStringify(value, maxBytes) {
+    try {
+        const json = JSON.stringify(value);
+        if (!json)
+            return '';
+        const buf = Buffer.from(json, 'utf-8');
+        if (buf.length <= maxBytes)
+            return json;
+        return buf.subarray(0, maxBytes).toString('utf-8') + '...[truncated]';
+    }
+    catch {
+        return String(value).slice(0, maxBytes);
+    }
+}
+//# sourceMappingURL=auto-record.js.map

package/dist/memory/auto-record.js.map

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

package/dist/memory/database.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module memory/database
+ * @description Thread-safe SQLite database manager for the SAP MCP agent memory subsystem.
+ *
+ * Uses better-sqlite3 (synchronous, native, FTS5-enabled) with WAL mode for
+ * concurrent read access. The database is a singleton — one connection per process.
+ *
+ * Design principles:
+ * - Synchronous I/O: better-sqlite3 is synchronous, no async overhead, no callback hell.
+ * - WAL mode: readers don't block writers, crash-safe via WAL journal.
+ * - Prepared statements: cached for performance, reused across calls.
+ * - FTS5: inverted full-text index for relevance-ranked retrieval.
+ * - Schema versioning: idempotent migrations on init.
+ * - Graceful degradation: if the DB can't be opened, tools return empty results.
+ */
+import type { Database as DatabaseType, Statement } from 'better-sqlite3';
+import type { MemoryConfig } from './types.js';
+/**
+ * @name DEFAULT_CONFIG
+ * @description Default memory configuration. The DB is stored in
+ * ~/.config/mcp-sap/memory/ which is the standard SAP MCP config directory.
+ */
+export declare const DEFAULT_CONFIG: MemoryConfig;
+/**
+ * @name MemoryDatabase
+ * @description Thread-safe singleton managing the SQLite connection for agent memory.
+ *
+ * The class lazily initializes the database on first access and caches prepared
+ * statements for performance. All methods are synchronous (better-sqlite3 is
+ * synchronous by design). The database runs in WAL mode for concurrent reads.
+ *
+ * If the database cannot be opened (e.g. disk full, permissions), the instance
+ * enters a degraded mode where all queries return empty results instead of
+ * crashing the MCP server.
+ */
+export declare class MemoryDatabase {
+    private db;
+    private readonly config;
+    private degraded;
+    private initialized;
+    private statements;
+    constructor(config?: Partial<MemoryConfig>);
+    /**
+     * @name init
+     * @description Initializes the database connection, creates the schema, and
+     * enables WAL mode. Called lazily on first query.
+     */
+    init(): void;
+    /**
+     * @name getDb
+     * @description Returns the underlying Database instance. Throws if degraded.
+     * @internal
+     */
+    getDb(): DatabaseType;
+    /**
+     * @name isDegraded
+     * @description Returns true if the database is in degraded mode (init failed).
+     */
+    isDegraded(): boolean;
+    /**
+     * @name getStatement
+     * @description Returns a cached prepared statement by key.
+     * @internal
+     */
+    getStatement(key: string): Statement | undefined;
+    /**
+     * @name close
+     * @description Closes the database connection gracefully.
+     */
+    close(): void;
+    /**
+     * @name getDbSize
+     * @description Returns the database file size in bytes.
+     */
+    getDbSize(): number;
+    /**
+     * @name runMigrations
+     * @description Runs idempotent schema migrations. Each migration checks if
+     * the current schema version is below the target and applies changes.
+     * @internal
+     */
+    private runMigrations;
+    /**
+     * @name migrateToV1
+     * @description Creates the initial schema: tool_calls, agent_memory,
+     * stream_buffers, and their FTS5 indexes.
+     * @internal
+     */
+    private migrateToV1;
+    /**
+     * @name prepareStatements
+     * @description Pre-compiles and caches frequently used SQL statements.
+     * @internal
+     */
+    private prepareStatements;
+}
+/**
+ * @name memoryDatabase
+ * @description Singleton instance of the memory database.
+ * Lazily initialized on first access. Shared across all memory tools.
+ */
+export declare const memoryDatabase: MemoryDatabase;
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/memory/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAK1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,YAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAA6B;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAqC;gBAE3C,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM;IAI9C;;;;OAIG;IACI,IAAI,IAAI,IAAI;IA0CnB;;;;OAIG;IACI,KAAK,IAAI,YAAY;IAO5B;;;OAGG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;OAIG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIvD;;;OAGG;IACI,KAAK,IAAI,IAAI;IAapB;;;OAGG;IACI,SAAS,IAAI,MAAM;IAU1B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA4BrB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAkHnB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAyD1B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}