shellward 0.5.16 → 0.6.1

package/dist/core/engine.js

@@ -8,10 +8,11 @@ import { randomBytes } from 'crypto';
 import { resolve } from 'path';
 import { homedir } from 'os';
 import { DANGEROUS_COMMANDS, splitCommands } from '../rules/dangerous-commands.js';
+import { TOOL_POISONING_RULES } from '../rules/tool-poisoning.js';
 import { PROTECTED_PATHS } from '../rules/protected-paths.js';
 import { INJECTION_RULES_ZH } from '../rules/injection-zh.js';
 import { INJECTION_RULES_EN } from '../rules/injection-en.js';
-import { redactSensitive } from '../rules/sensitive-patterns.js';
+import { redactSensitive, compileSensitivePatterns } from '../rules/sensitive-patterns.js';
 import { AuditLog } from '../audit-log.js';
 import { resolveLocale, DEFAULT_CONFIG } from '../types.js';
 // ===== Constants =====
@@ -27,6 +28,7 @@ const EXEC_TOOLS = new Set([
 ]);
 const OUTBOUND_TOOLS = new Set([
     'send_email', 'send_message', 'post_tweet', 'message', 'sessions_send',
+    'http_post', 'curl_post',
 ]);
 const DUAL_USE_TOOLS = new Set([
     'web_fetch', 'http_request',
@@ -57,6 +59,12 @@ const HIDDEN_CHAR_RANGES = [
     [0xFEFF, 0xFEFF, 'BOM/Zero-width no-break'],
     [0x00AD, 0x00AD, 'Soft hyphen'],
     [0xFFF9, 0xFFFB, 'Interlinear annotation'],
+    // Variation selectors — abused to smuggle hidden bytes/instructions
+    [0xFE00, 0xFE0F, 'Variation selector'],
+    [0xE0100, 0xE01EF, 'Variation selector supplement'],
+    // Unicode Tag characters — the primary "invisible prompt injection" vector
+    [0xE0001, 0xE0001, 'Language tag'],
+    [0xE0020, 0xE007F, 'Tag character'],
 ];
 const TEXT_FIELDS = [
     'content', 'body', 'text', 'message', 'query',
@@ -110,6 +118,14 @@ export class ShellWard {
     log;
     _canaryToken;
     compiledRules;
+    // Tool policy sets — built-ins merged with config.customRules (allowedTools wins).
+    blockedTools;
+    allowedTools;
+    sensitiveTools;
+    outboundTools;
+    honeypots;
+    customSensitive;
+    customDangerous;
     sensitiveReads = new Map();
     TRACKING_WINDOW_MS = 5 * 60 * 1000;
     MAX_TRACKED_READS = 500;
@@ -118,11 +134,31 @@ export class ShellWard {
         this.locale = resolveLocale(this.config);
         this.log = new AuditLog(this.config);
         this._canaryToken = 'SW-' + randomBytes(8).toString('hex');
-        const allRules = [...INJECTION_RULES_ZH, ...INJECTION_RULES_EN];
-        this.compiledRules = allRules.map(rule => ({
-            ...rule,
-            compiled: new RegExp(rule.pattern, rule.flags || 'i'),
-        }));
+        const custom = this.config.customRules || {};
+        const lower = (s) => s.toLowerCase();
+        this.allowedTools = new Set((custom.allowedTools || []).map(lower));
+        this.blockedTools = new Set([...BLOCKED_TOOLS, ...(custom.blockedTools || []).map(lower)]);
+        this.sensitiveTools = new Set([...SENSITIVE_TOOLS, ...(custom.sensitiveTools || []).map(lower)]);
+        this.outboundTools = new Set([...OUTBOUND_TOOLS, ...(custom.outboundTools || []).map(lower)]);
+        // allowedTools always wins — strip them from the block/sensitive sets.
+        for (const t of this.allowedTools) {
+            this.blockedTools.delete(t);
+            this.sensitiveTools.delete(t);
+        }
+        this.honeypots = [...HONEYPOT_PATTERNS, ...compileRegexList(custom.honeypotPaths || [])];
+        this.customSensitive = compileSensitivePatterns(custom.sensitivePatterns || []);
+        this.customDangerous = compileDangerousRules(custom.dangerousCommands || []);
+        const allRules = [...INJECTION_RULES_ZH, ...INJECTION_RULES_EN, ...(custom.injectionRules || [])];
+        this.compiledRules = allRules
+            .map(rule => {
+            try {
+                return { ...rule, compiled: new RegExp(rule.pattern, rule.flags || 'i') };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((r) => r !== null);
     }
     // ========== L1: Prompt Guard ==========
     getSecurityPrompt() {
@@ -137,7 +173,8 @@ export class ShellWard {
     }
     // ========== L2: Data Scanner ==========
     scanData(text, toolName) {
-        const [, findings] = redactSensitive(text);
+        text = asString(text);
+        const [, findings] = redactSensitive(text, this.customSensitive);
         const hasSensitiveData = findings.length > 0;
         const summary = findings.map(f => `${f.name}(${f.count})`).join(', ');
         if (hasSensitiveData) {
@@ -159,9 +196,12 @@ export class ShellWard {
     }
     // ========== L3: Tool & Command Checker ==========
     checkTool(toolName) {
-        const toolLower = toolName.toLowerCase();
+        const toolLower = asString(toolName).toLowerCase();
         const enforce = this.config.mode === 'enforce';
-        if (BLOCKED_TOOLS.has(toolLower)) {
+        // allowedTools always wins — user-trusted tools bypass policy.
+        if (this.allowedTools.has(toolLower))
+            return { allowed: true };
+        if (this.blockedTools.has(toolLower)) {
             const reason = this.locale === 'zh'
                 ? `安全策略禁止自动执行: ${toolName}`
                 : `Blocked by security policy: ${toolName}`;
@@ -174,7 +214,7 @@ export class ShellWard {
             });
             return { allowed: false, level: 'CRITICAL', reason };
         }
-        if (SENSITIVE_TOOLS.has(toolLower)) {
+        if (this.sensitiveTools.has(toolLower)) {
             this.log.write({
                 level: 'MEDIUM',
                 layer: 'L3',
@@ -187,10 +227,14 @@ export class ShellWard {
     }
     checkCommand(cmd, toolName) {
         const enforce = this.config.mode === 'enforce';
-        const parts = splitCommands(cmd);
+        const parts = splitCommands(asString(cmd));
         for (const part of parts) {
-            for (const rule of DANGEROUS_COMMANDS) {
-                if (rule.pattern.test(part)) {
+            // Normalize shell-quote obfuscation (e.g. r''m / r""m → rm) before matching.
+            // Only empty quote pairs are stripped, so a real quoted arg like
+            // echo "rm -rf /" is untouched (no false positive).
+            const normalized = normalizeCommand(part);
+            for (const rule of [...DANGEROUS_COMMANDS, ...this.customDangerous]) {
+                if (rule.pattern.test(part) || rule.pattern.test(normalized)) {
                     const desc = this.locale === 'zh' ? rule.description_zh : rule.description_en;
                     const reason = this.locale === 'zh'
                         ? `检测到危险命令: ${truncate(part, 80)}\n原因: ${desc}`
@@ -210,6 +254,7 @@ export class ShellWard {
         return { allowed: true };
     }
     checkPath(path, operation, toolName) {
+        path = asString(path);
         const enforce = this.config.mode === 'enforce';
         const normalizedPath = normalizePath(path);
         for (const rule of PROTECTED_PATHS) {
@@ -233,6 +278,7 @@ export class ShellWard {
     }
     // ========== L4: Injection Detection ==========
     checkInjection(text, options) {
+        text = asString(text);
         const threshold = options?.threshold ?? this.config.injectionThreshold;
         const enforce = this.config.mode === 'enforce';
         const hiddenChars = detectHiddenChars(text);
@@ -244,10 +290,13 @@ export class ShellWard {
                 detail: `Hidden characters detected: ${[...new Set(hiddenChars.map(h => h.name))].join(', ')} (${hiddenChars.length} chars)`,
             });
         }
+        // Strip invisible characters before rule matching so an attacker can't break
+        // a pattern by interleaving zero-width spaces (e.g. "ig​nore previous").
+        const normText = hiddenChars.length > 0 ? stripInvisible(text) : text;
         let score = 0;
         const matched = [];
         for (const rule of this.compiledRules) {
-            if (rule.compiled.test(text)) {
+            if (rule.compiled.test(text) || (normText !== text && rule.compiled.test(normText))) {
                 score += rule.riskScore;
                 matched.push({ id: rule.id, name: rule.name, score: rule.riskScore });
             }
@@ -267,13 +316,91 @@ export class ShellWard {
         return { safe: score < threshold, score, threshold, matched, hiddenChars: hiddenChars.length };
     }
     getInjectionThreshold(toolName) {
-        if (toolName && LOW_RISK_TOOLS.has(toolName.toLowerCase())) {
+        const lower = toolName?.toLowerCase();
+        if (lower && (LOW_RISK_TOOLS.has(lower) || this.allowedTools.has(lower))) {
             return Math.max(this.config.injectionThreshold, 80);
         }
         return this.config.injectionThreshold;
     }
+    // ========== L4b: MCP Tool-Poisoning Scanner ==========
+    //
+    // Inspects an MCP tool *definition* (not user input) for instructions hidden
+    // in its description / parameter descriptions — the "tool poisoning" attack.
+    // Reuses the injection engine + hidden-char detection and layers on rules
+    // tuned for tool-metadata attacks. Pure & side-effect-light: callable from
+    // the SDK, the MCP server, or at plugin tool-discovery time.
+    scanToolDefinition(tool, options) {
+        tool = (tool && typeof tool === 'object') ? tool : { name: 'unknown' };
+        const threshold = options?.threshold ?? 40;
+        const findings = [];
+        let score = 0;
+        const description = typeof tool.description === 'string' ? tool.description : '';
+        const paramText = collectSchemaText(tool.inputSchema);
+        const combined = `${description}\n${paramText}`;
+        // 1. Hidden / invisible characters anywhere in the metadata
+        const hidden = detectHiddenChars(combined);
+        if (hidden.length > 0) {
+            const s = hidden.length > 3 ? 35 : 20;
+            score += s;
+            findings.push({
+                id: 'tp_hidden_chars',
+                name: `Hidden characters in tool metadata (${[...new Set(hidden.map(h => h.name))].join(', ')})`,
+                category: 'concealment',
+                score: s,
+                source: 'hidden_chars',
+            });
+        }
+        // 2. Tool-poisoning specific rules (description + parameters)
+        for (const rule of TOOL_POISONING_RULES) {
+            const inDesc = rule.pattern.test(description);
+            const inParam = !inDesc && rule.pattern.test(paramText);
+            if (inDesc || inParam) {
+                score += rule.riskScore;
+                findings.push({
+                    id: rule.id,
+                    name: rule.name,
+                    category: rule.category,
+                    score: rule.riskScore,
+                    source: inDesc ? 'description' : 'parameter',
+                });
+            }
+        }
+        // 3. Generic prompt-injection patterns reused on the description
+        for (const rule of this.compiledRules) {
+            if (rule.compiled.test(combined)) {
+                score += rule.riskScore;
+                findings.push({
+                    id: rule.id,
+                    name: rule.name,
+                    category: rule.category,
+                    score: rule.riskScore,
+                    source: 'description',
+                });
+            }
+        }
+        const safe = score < threshold;
+        if (!safe) {
+            this.log.write({
+                level: score >= 80 ? 'CRITICAL' : 'HIGH',
+                layer: 'L4',
+                action: this.config.mode === 'enforce' ? 'block' : 'detect',
+                detail: this.locale === 'zh'
+                    ? `检测到 MCP 工具投毒: ${tool.name}\n风险评分: ${score}\n命中: ${findings.map(f => f.name).join('; ')}`
+                    : `MCP tool poisoning detected: ${tool.name}\nRisk score: ${score}\nMatched: ${findings.map(f => f.name).join('; ')}`,
+                tool: tool.name,
+                pattern: 'tool_poisoning',
+            });
+        }
+        return { toolName: tool.name, safe, score, threshold, findings, hiddenChars: hidden.length };
+    }
+    /** Scan a list of MCP tool definitions; returns only the unsafe ones. */
+    scanToolDefinitions(tools, options) {
+        return tools.map(t => this.scanToolDefinition(t, options)).filter(r => !r.safe);
+    }
     // ========== L5: Security Gate ==========
     checkAction(action, details) {
+        action = asString(action);
+        details = asString(details);
         if (action === 'exec' || action === 'shell') {
             return this.checkCommand(details);
         }
@@ -293,20 +420,14 @@ export class ShellWard {
             });
             return { allowed: false, level: 'CRITICAL', reason, ruleId: 'no_payment' };
         }
-        // Block outbound actions when sensitive data was recently accessed (DLP via Gate)
-        const outboundActions = ['send_email', 'send_message', 'post_tweet', 'http_post', 'curl_post'];
-        if (outboundActions.includes(action) && this.hasSensitiveData) {
-            const reason = this.locale === 'zh'
-                ? `数据外泄拦截: 近期访问了敏感数据，禁止通过 ${action} 向外部发送`
-                : `Data exfiltration blocked: sensitive data recently accessed, ${action} denied`;
-            this.log.write({
-                level: 'CRITICAL',
-                layer: 'L5',
-                action: 'block',
-                detail: `Gate denied (DLP): ${action}`,
-                pattern: 'gate_data_exfil',
-            });
-            return { allowed: false, level: 'CRITICAL', reason, ruleId: 'gate_data_exfil' };
+        // Outbound actions: delegate the DLP decision to the canonical data-flow
+        // guard (L7) so the Gate and the Outbound Guard can never diverge. The set
+        // of outbound tools (incl. http_post/curl_post + any customRules) lives in
+        // one place: this.outboundTools, consulted by checkOutbound.
+        if (this.outboundTools.has(action.toLowerCase())) {
+            const dlp = this.checkOutbound(action, details ? { body: details } : {});
+            if (!dlp.allowed)
+                return dlp;
         }
         this.log.write({
             level: 'INFO',
@@ -318,6 +439,7 @@ export class ShellWard {
     }
     // ========== L6: Response Checker ==========
     checkResponse(content) {
+        content = asString(content);
         const canaryLeak = this._canaryToken ? content.includes(this._canaryToken) : false;
         if (canaryLeak) {
             this.log.write({
@@ -330,7 +452,7 @@ export class ShellWard {
                 pattern: 'canary_leak',
             });
         }
-        const [, findings] = redactSensitive(content);
+        const [, findings] = redactSensitive(content, this.customSensitive);
         const hasSensitiveData = findings.length > 0;
         const summary = findings.map(f => `${f.name}(${f.count})`).join(', ');
         if (hasSensitiveData) {
@@ -359,7 +481,7 @@ export class ShellWard {
         this.sensitiveReads.set(`pii-${Date.now()}-${toolName}`, { path: `[${toolName}: ${summary}]`, ts: Date.now() });
     }
     trackFileRead(toolName, path) {
-        for (const hp of HONEYPOT_PATTERNS) {
+        for (const hp of this.honeypots) {
             if (hp.test(path)) {
                 this.log.write({
                     level: 'CRITICAL',
@@ -394,8 +516,9 @@ export class ShellWard {
         this.evictExpired();
     }
     checkOutbound(toolName, params) {
-        const toolLower = toolName.toLowerCase();
-        const isOutbound = OUTBOUND_TOOLS.has(toolLower);
+        params = (params && typeof params === 'object') ? params : {};
+        const toolLower = asString(toolName).toLowerCase();
+        const isOutbound = this.outboundTools.has(toolLower);
         const isDualUse = DUAL_USE_TOOLS.has(toolLower);
         const enforce = this.config.mode === 'enforce';
         this.evictExpired();
@@ -499,6 +622,8 @@ export class ShellWard {
     }
     extractTextFields(args) {
         const results = [];
+        if (!args || typeof args !== 'object')
+            return results;
         for (const field of TEXT_FIELDS) {
             if (typeof args[field] === 'string' && args[field].length > 0) {
                 results.push(args[field]);
@@ -541,8 +666,36 @@ function mergeConfig(userConfig) {
         injectionThreshold: threshold,
         autoCheckOnStartup,
         layers: { ...DEFAULT_CONFIG.layers, ...(userConfig.layers || {}) },
+        ...(userConfig.customRules ? { customRules: userConfig.customRules } : {}),
     };
 }
+/** Compile a list of regex-source strings; invalid ones are skipped. */
+function compileRegexList(sources) {
+    const out = [];
+    for (const src of sources) {
+        try {
+            out.push(new RegExp(src, 'i'));
+        }
+        catch { /* skip invalid */ }
+    }
+    return out;
+}
+/** Compile user dangerous-command rules; invalid regexes are skipped. */
+function compileDangerousRules(rules) {
+    const out = [];
+    for (const r of rules) {
+        try {
+            out.push({
+                id: r.id,
+                pattern: new RegExp(r.pattern, r.flags || 'i'),
+                description_zh: r.description || r.id,
+                description_en: r.description || r.id,
+            });
+        }
+        catch { /* skip invalid */ }
+    }
+    return out;
+}
 function normalizePath(p) {
     const expanded = p.startsWith('~')
         ? p.replace(/^~/, homedir() || process.env.HOME || '/root')
@@ -557,6 +710,75 @@ function normalizePath(p) {
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max) + '...' : s;
 }
+/**
+ * Defensive coercion at public API boundaries: a security check must fail safe
+ * on hostile/garbage input, never throw. null/undefined → '', everything else
+ * is stringified.
+ */
+function asString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (v == null)
+        return '';
+    try {
+        return String(v);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Defeat shell-quote obfuscation for DETECTION (not execution): strip empty
+ * quote pairs so `r''m -rf /` and `r""m -rf /` normalize to `rm -rf /`.
+ * Deliberately conservative — non-empty quoted arguments (echo "rm -rf /")
+ * are left intact to avoid false positives. Runs a few passes for r''''m.
+ */
+function normalizeCommand(cmd) {
+    let prev = cmd;
+    for (let i = 0; i < 4; i++) {
+        const next = prev.replace(/''|""/g, '');
+        if (next === prev)
+            break;
+        prev = next;
+    }
+    return prev;
+}
+/**
+ * Recursively collect all `description`/`title` string values out of a JSON
+ * Schema (an MCP tool's inputSchema), so poisoning hidden in a nested
+ * parameter description is scanned too. Bounded to avoid pathological schemas.
+ */
+function collectSchemaText(schema, depth = 0) {
+    if (!schema || typeof schema !== 'object' || depth > 6)
+        return '';
+    const out = [];
+    for (const [key, val] of Object.entries(schema)) {
+        if ((key === 'description' || key === 'title') && typeof val === 'string') {
+            out.push(val);
+        }
+        else if (val && typeof val === 'object') {
+            out.push(collectSchemaText(val, depth + 1));
+        }
+    }
+    return out.join('\n');
+}
+/** Remove all invisible/zero-width characters (the HIDDEN_CHAR_RANGES). */
+function stripInvisible(text) {
+    let out = '';
+    for (const char of text) {
+        const cp = char.codePointAt(0);
+        let hidden = false;
+        for (const [start, end] of HIDDEN_CHAR_RANGES) {
+            if (cp >= start && cp <= end) {
+                hidden = true;
+                break;
+            }
+        }
+        if (!hidden)
+            out += char;
+    }
+    return out;
+}
 function detectHiddenChars(text) {
     const found = [];
     for (const char of text) {

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { ShellWard } from './core/engine.js';
-export type { CheckResult, ScanResult, InjectionResult, ResponseCheckResult } from './core/engine.js';
-export type { ShellWardConfig } from './types.js';
+export type { CheckResult, ScanResult, InjectionResult, ResponseCheckResult, McpToolDefinition, ToolPoisoningResult, ToolPoisoningFinding, } from './core/engine.js';
+export { McpBaseline } from './mcp-baseline.js';
+export type { RugPullResult, RugPullStatus } from './mcp-baseline.js';
+export type { ShellWardConfig, CustomRules, CustomSensitivePattern, CustomCommandRule, } from './types.js';
 declare const _default: {
     id: string;
     register(api: any): void;

package/dist/index.js

@@ -6,6 +6,9 @@
 //
 // See docs/定位.md — ShellWard is an AI Agent Security Layer,
 // NOT just an OpenClaw plugin. The core engine is platform-agnostic.
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { ShellWard } from './core/engine.js';
 import { setupPromptGuard } from './layers/prompt-guard.js';
 import { setupOutputScanner } from './layers/output-scanner.js';
@@ -18,9 +21,21 @@ import { setupSessionGuard } from './layers/session-guard.js';
 import { registerAllCommands } from './commands/index.js';
 import { checkForUpdate } from './update-check.js';
 import { runAutoCheckOnStartup } from './auto-check.js';
-const CURRENT_VERSION = '0.5.16';
+// Single source of truth: read version from package.json at load time.
+// dist/index.js → ../package.json (package.json is shipped via "files").
+const CURRENT_VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '../package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 // Re-export core engine for SDK usage
 export { ShellWard } from './core/engine.js';
+export { McpBaseline } from './mcp-baseline.js';
 /**
  * Wrap api.on so every hook handler gets try-catch protection.
  * If a security hook throws, we log the error and fail-safe:
@@ -106,8 +121,8 @@ export default {
         }
         // === Slash Commands ===
         if (api.registerCommand) {
-            registerAllCommands(api, guard.config);
-            api.logger.info('[ShellWard] 6 commands registered');
+            const commandCount = registerAllCommands(api, guard.config);
+            api.logger.info(`[ShellWard] ${commandCount} commands registered`);
         }
         const allLayers = ['promptGuard', 'outputScanner', 'toolBlocker', 'inputAuditor', 'securityGate', 'outboundGuard', 'dataFlowGuard', 'sessionGuard'];
         const enabledCount = allLayers.filter(k => guard.config.layers[k]).length;

package/dist/mcp-baseline.d.ts

@@ -0,0 +1,27 @@
+import type { McpToolDefinition } from './core/engine.js';
+export type RugPullStatus = 'new' | 'unchanged' | 'changed';
+export interface RugPullResult {
+    key: string;
+    status: RugPullStatus;
+    currentHash: string;
+    previousHash?: string;
+}
+export declare class McpBaseline {
+    private readonly path;
+    private store;
+    /** @param filePath override the baseline file (tests pass a temp path). */
+    constructor(filePath?: string);
+    /** Fingerprint a tool's externally-visible contract (description + schema). */
+    private fingerprint;
+    /** Stable key for a tool, namespaced by its server. */
+    static keyFor(server: string, toolName: string): string;
+    /** Compare against the stored baseline WITHOUT persisting. */
+    diff(key: string, tool: McpToolDefinition): RugPullResult;
+    /** Compare, then update the in-memory baseline. Call save() to persist. */
+    record(key: string, tool: McpToolDefinition): RugPullResult;
+    /** Number of tracked tools. */
+    get size(): number;
+    private load;
+    /** Flush the baseline to disk (owner-only perms). Never throws. */
+    save(): void;
+}

package/dist/mcp-baseline.js

@@ -0,0 +1,73 @@
+// src/mcp-baseline.ts — MCP "rug-pull" detection via tool-definition baselining
+//
+// A rug-pull attack: an MCP tool ships a benign description, gets approved/trusted,
+// then later silently swaps in a malicious description. ShellWard fingerprints each
+// tool's description+schema on first sight and flags later mismatches.
+//
+// Zero dependencies — sha256 from node:crypto, JSON store under the audit dir.
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { getHomeDir } from './utils.js';
+const DEFAULT_PATH = join(getHomeDir(), '.openclaw', 'shellward', 'mcp-baseline.json');
+export class McpBaseline {
+    path;
+    store;
+    /** @param filePath override the baseline file (tests pass a temp path). */
+    constructor(filePath) {
+        this.path = filePath || DEFAULT_PATH;
+        this.store = this.load();
+    }
+    /** Fingerprint a tool's externally-visible contract (description + schema). */
+    fingerprint(tool) {
+        const canonical = JSON.stringify({
+            description: tool.description || '',
+            inputSchema: tool.inputSchema ?? null,
+        });
+        return createHash('sha256').update(canonical).digest('hex');
+    }
+    /** Stable key for a tool, namespaced by its server. */
+    static keyFor(server, toolName) {
+        return `${server}::${toolName}`;
+    }
+    /** Compare against the stored baseline WITHOUT persisting. */
+    diff(key, tool) {
+        const currentHash = this.fingerprint(tool);
+        const prev = this.store[key];
+        if (!prev)
+            return { key, status: 'new', currentHash };
+        return {
+            key,
+            status: prev.hash === currentHash ? 'unchanged' : 'changed',
+            currentHash,
+            previousHash: prev.hash,
+        };
+    }
+    /** Compare, then update the in-memory baseline. Call save() to persist. */
+    record(key, tool) {
+        const res = this.diff(key, tool);
+        this.store[key] = { hash: res.currentHash, name: tool.name, ts: new Date().toISOString() };
+        return res;
+    }
+    /** Number of tracked tools. */
+    get size() {
+        return Object.keys(this.store).length;
+    }
+    load() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Flush the baseline to disk (owner-only perms). Never throws. */
+    save() {
+        try {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            writeFileSync(this.path, JSON.stringify(this.store, null, 2), { mode: 0o600 });
+        }
+        catch { /* best-effort; baselining must not break the host */ }
+    }
+}

package/dist/mcp-client.d.ts

@@ -0,0 +1,29 @@
+import type { McpToolDefinition } from './core/engine.js';
+export interface McpServerSpec {
+    name: string;
+    /** 'stdio' servers are spawned; 'remote' servers are scanned over HTTP. */
+    transport: 'stdio' | 'remote';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    source: string;
+}
+/**
+ * Discover MCP servers declared in known config files.
+ * Recognizes the standard `{ "mcpServers": { name: {...} } }` shape.
+ * @param paths override config paths (tests pass a temp file)
+ */
+export declare function discoverMcpServers(paths?: string[]): McpServerSpec[];
+/**
+ * Spawn a stdio MCP server, initialize, and return its tool definitions.
+ * Always resolves (never hangs): on error/timeout it cleans up and rejects.
+ */
+export declare function listToolsStdio(spec: McpServerSpec, timeoutMs?: number): Promise<McpToolDefinition[]>;
+/**
+ * Initialize a remote MCP server over Streamable HTTP and return its tool
+ * definitions. Best-effort: returns [] if the server speaks an unsupported
+ * dialect. Rejects on network error / timeout.
+ */
+export declare function listToolsHttp(spec: McpServerSpec, timeoutMs?: number): Promise<McpToolDefinition[]>;