monomind 1.11.13 → 1.12.0

package/packages/@monomind/cli/dist/src/mcp/deprecation-injector.js

@@ -0,0 +1,48 @@
+/**
+ * Deprecation Injector (Task 31)
+ *
+ * Injects deprecation warnings into MCP tool responses when the
+ * invoked tool has been marked as deprecated in the ToolRegistry.
+ */
+/**
+ * Injects deprecation metadata into MCP responses.
+ */
+export class DeprecationInjector {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    /**
+     * If `toolName` is deprecated, augment the response with a warning.
+     *
+     * Returns the original response unmodified when the tool is not
+     * deprecated. When deprecated, adds `_deprecation` metadata.
+     *
+     * Warning format:
+     *   [DEPRECATED] Tool "<name>" is deprecated. <message>. Use "<successor>" instead.
+     */
+    inject(response, toolName) {
+        const tool = this.registry.getVersion(toolName);
+        if (!tool || !tool.deprecated) {
+            return response;
+        }
+        const parts = [`[DEPRECATED] Tool "${toolName}" is deprecated.`];
+        if (tool.deprecationMessage) {
+            parts.push(tool.deprecationMessage + '.');
+        }
+        if (tool.successor) {
+            parts.push(`Use "${tool.successor}" instead.`);
+        }
+        const warning = parts.join(' ');
+        return {
+            ...response,
+            _deprecation: {
+                warning,
+                deprecated: true,
+                successor: tool.successor ?? null,
+                deprecatedAt: tool.deprecatedAt ?? null,
+            },
+        };
+    }
+}
+//# sourceMappingURL=deprecation-injector.js.map

package/packages/@monomind/cli/dist/src/mcp/tool-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool Registry (Task 31)
+ *
+ * Manages semver versioning for MCP tools with deprecation tracking
+ * and tool-to-agent impact analysis. Uses JSONL file storage.
+ */
+import type { VersionedMCPTool, ToolVersionEntry } from '../../../shared/src/types/tool-version.js';
+/**
+ * Registry for versioned MCP tools.
+ *
+ * Stores tool metadata and version history in a JSONL file.
+ * Supports deprecation marking and agent impact analysis.
+ */
+export declare class ToolRegistry {
+    private tools;
+    private history;
+    private readonly storagePath;
+    constructor(storagePath?: string);
+    /**
+     * Register a new tool or update an existing one.
+     */
+    register(tool: VersionedMCPTool): void;
+    /**
+     * Mark a tool as deprecated with an optional successor.
+     */
+    deprecate(toolName: string, message: string, successor?: string): void;
+    /**
+     * Get the current version info for a tool.
+     * Returns null if the tool is not registered.
+     */
+    getVersion(toolName: string): VersionedMCPTool | null;
+    /**
+     * List all deprecated tools.
+     */
+    listDeprecated(): VersionedMCPTool[];
+    /**
+     * Find agents that reference the given tool.
+     *
+     * Scans agent markdown files under the provided agents directory
+     * and returns slugs of agents whose `tools:` frontmatter or body
+     * mention the tool name.
+     */
+    getImpactedAgents(toolName: string, agentsDir?: string): string[];
+    /**
+     * Get the full version history for a tool, or all tools if no name given.
+     */
+    getHistory(toolName?: string): ToolVersionEntry[];
+    /**
+     * Get all registered tools.
+     */
+    listAll(): VersionedMCPTool[];
+    /**
+     * Load existing entries from the JSONL file on disk.
+     */
+    private loadFromDisk;
+    /**
+     * Append a version history entry and the current tool state to disk.
+     */
+    private appendEntry;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/packages/@monomind/cli/dist/src/mcp/tool-registry.js

@@ -0,0 +1,246 @@
+/**
+ * Tool Registry (Task 31)
+ *
+ * Manages semver versioning for MCP tools with deprecation tracking
+ * and tool-to-agent impact analysis. Uses JSONL file storage.
+ */
+import { appendFileSync, readFileSync, existsSync, mkdirSync, readdirSync, lstatSync, } from 'fs';
+import { join, dirname, extname, resolve, sep } from 'path';
+/** Default JSONL storage path relative to project root. */
+const DEFAULT_STORAGE_PATH = '.monomind/tool-versions.jsonl';
+/**
+ * Registry for versioned MCP tools.
+ *
+ * Stores tool metadata and version history in a JSONL file.
+ * Supports deprecation marking and agent impact analysis.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    history = [];
+    storagePath;
+    constructor(storagePath = DEFAULT_STORAGE_PATH) {
+        const resolvedPath = resolve(storagePath);
+        const allowedRoot = process.env.MONOMIND_DATA_DIR
+            ? resolve(process.env.MONOMIND_DATA_DIR)
+            : resolve(process.cwd());
+        if (resolvedPath !== allowedRoot && !resolvedPath.startsWith(allowedRoot + sep)) {
+            throw new Error(`Tool registry storagePath escapes allowed root: ${resolvedPath}`);
+        }
+        this.storagePath = resolvedPath;
+        this.loadFromDisk();
+    }
+    /**
+     * Register a new tool or update an existing one.
+     */
+    register(tool) {
+        const existing = this.tools.get(tool.toolName);
+        const changeType = existing
+            ? 'updated'
+            : 'added';
+        this.tools.set(tool.toolName, { ...tool });
+        const entry = {
+            toolName: tool.toolName,
+            version: tool.version,
+            changeType,
+            changedAt: new Date().toISOString(),
+            description: changeType === 'added'
+                ? `Registered tool ${tool.toolName} v${tool.version}`
+                : `Updated tool ${tool.toolName} to v${tool.version}`,
+        };
+        this.history.push(entry);
+        this.appendEntry(entry);
+    }
+    /**
+     * Mark a tool as deprecated with an optional successor.
+     */
+    deprecate(toolName, message, successor) {
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            throw new Error(`Tool "${toolName}" not found in registry`);
+        }
+        tool.deprecated = true;
+        tool.deprecationMessage = message;
+        tool.deprecatedAt = new Date().toISOString();
+        if (successor) {
+            tool.successor = successor;
+        }
+        const entry = {
+            toolName,
+            version: tool.version,
+            changeType: 'deprecated',
+            changedAt: tool.deprecatedAt,
+            description: message,
+        };
+        this.history.push(entry);
+        this.appendEntry(entry);
+    }
+    /**
+     * Get the current version info for a tool.
+     * Returns null if the tool is not registered.
+     */
+    getVersion(toolName) {
+        return this.tools.get(toolName) ?? null;
+    }
+    /**
+     * List all deprecated tools.
+     */
+    listDeprecated() {
+        const result = [];
+        for (const tool of this.tools.values()) {
+            if (tool.deprecated) {
+                result.push({ ...tool });
+            }
+        }
+        return result;
+    }
+    /**
+     * Find agents that reference the given tool.
+     *
+     * Scans agent markdown files under the provided agents directory
+     * and returns slugs of agents whose `tools:` frontmatter or body
+     * mention the tool name.
+     */
+    getImpactedAgents(toolName, agentsDir = 'agents') {
+        // Reject empty or short tool names — `content.includes('')` returns true
+        // for every file, turning the registry into a directory enumerator.
+        if (typeof toolName !== 'string' || toolName.length < 2 || !/^[a-zA-Z0-9_.-]+$/.test(toolName)) {
+            return [];
+        }
+        const impacted = [];
+        const mdFiles = collectMdFiles(agentsDir);
+        for (const filePath of mdFiles) {
+            let content;
+            try {
+                content = readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            if (content.includes(toolName)) {
+                // Derive slug from filename (strip .md extension)
+                const parts = filePath.split('/');
+                const filename = parts[parts.length - 1];
+                const slug = filename.replace(/\.md$/, '');
+                impacted.push(slug);
+            }
+        }
+        return impacted;
+    }
+    /**
+     * Get the full version history for a tool, or all tools if no name given.
+     */
+    getHistory(toolName) {
+        if (!toolName) {
+            return [...this.history];
+        }
+        return this.history.filter((e) => e.toolName === toolName);
+    }
+    /**
+     * Get all registered tools.
+     */
+    listAll() {
+        return Array.from(this.tools.values()).map((t) => ({ ...t }));
+    }
+    // ---- Private helpers ----
+    /**
+     * Load existing entries from the JSONL file on disk.
+     */
+    loadFromDisk() {
+        if (!existsSync(this.storagePath)) {
+            return;
+        }
+        let raw;
+        try {
+            raw = readFileSync(this.storagePath, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        const NAME_RE = /^[a-zA-Z0-9_.-]{1,128}$/;
+        const STR_MAX = 500;
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const record = JSON.parse(trimmed);
+                if (!record || typeof record !== 'object')
+                    continue;
+                // Validate fields before storage. The JSONL file lives on disk; an
+                // attacker with local write access could otherwise plant attacker-controlled
+                // strings (e.g. malicious deprecationMessage with markup) that reach
+                // downstream renderers (DOT visualizer, deprecation-injector warnings).
+                if (record._type === 'tool') {
+                    if (typeof record.toolName !== 'string' || !NAME_RE.test(record.toolName))
+                        continue;
+                    if (record.successor !== undefined && (typeof record.successor !== 'string' || !NAME_RE.test(record.successor)))
+                        continue;
+                    if (record.deprecationMessage !== undefined && (typeof record.deprecationMessage !== 'string' || record.deprecationMessage.length > STR_MAX))
+                        continue;
+                    this.tools.set(record.toolName, record);
+                }
+                else if (record._type === 'history') {
+                    if (typeof record.toolName !== 'string' || !NAME_RE.test(record.toolName))
+                        continue;
+                    this.history.push(record);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    /**
+     * Append a version history entry and the current tool state to disk.
+     */
+    appendEntry(entry) {
+        const dir = dirname(this.storagePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const tool = this.tools.get(entry.toolName);
+        const lines = [];
+        if (tool) {
+            lines.push(JSON.stringify({ _type: 'tool', ...tool }));
+        }
+        lines.push(JSON.stringify({ _type: 'history', ...entry }));
+        appendFileSync(this.storagePath, lines.join('\n') + '\n', 'utf-8');
+    }
+}
+/**
+ * Recursively collect all `.md` files under a directory.
+ */
+function collectMdFiles(root) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(root, entry);
+        let stat;
+        try {
+            // Use lstatSync so symlinks aren't followed — otherwise a symlink under
+            // `agentsDir` could redirect this scan into arbitrary filesystem
+            // locations, which combined with `getImpactedAgents` becomes a content
+            // oracle that fingerprints arbitrary text files outside the project.
+            stat = lstatSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            results.push(...collectMdFiles(full));
+        }
+        else if (stat.isFile() && extname(entry) === '.md') {
+            results.push(full);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=tool-registry.js.map

package/packages/@monomind/cli/dist/src/mcp-tools/a2a-tools.js

@@ -9,6 +9,57 @@
  *
  * @module v1/cli/mcp-tools/a2a-tools
  */
+// ===== Input validation helpers =====
+const MAX_AGENT_TYPE_LEN = 64; // slug length — catalogue keys are all < 30 chars
+const MAX_BASE_URL_LEN = 2048; // typical browser URL limit
+const MAX_TASK_ID_LEN = 256;
+const MAX_SESSION_ID_LEN = 256;
+// Allowlist of URL schemes that are safe to embed in returned Agent Card urls.
+// Prevents javascript:, data:, file:// etc. from being reflected back to callers.
+const ALLOWED_URL_SCHEMES = new Set(['http:', 'https:']);
+/**
+ * Validate and return an agent type slug.
+ * Returns null when the value is not a string or exceeds the max length.
+ */
+function validateAgentType(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_AGENT_TYPE_LEN)
+        return null;
+    return value;
+}
+/**
+ * Validate and return a base URL.
+ * Accepts only http/https schemes and caps length to prevent oversized reflected values.
+ * Falls back to the default localhost URL on failure.
+ */
+function validateBaseUrl(value, fallback = 'http://localhost:3000') {
+    if (typeof value !== 'string' || value.length === 0)
+        return fallback;
+    if (value.length > MAX_BASE_URL_LEN)
+        return fallback;
+    try {
+        const parsed = new URL(value);
+        if (!ALLOWED_URL_SCHEMES.has(parsed.protocol))
+            return fallback;
+        // Reject URLs with credentials — they should never appear in Agent Card endpoints
+        if (parsed.username || parsed.password)
+            return fallback;
+    }
+    catch {
+        return fallback;
+    }
+    return value;
+}
+/**
+ * Validate an optional string ID (taskId / sessionId).
+ * Returns undefined when the value is absent; null when it is present but invalid.
+ */
+function validateOptionalId(value, maxLen) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0 || value.length > maxLen)
+        return null;
+    return value;
+}
 // ===== Agent type catalogue =====
 /** Well-known agent types and their A2A card metadata */
 const AGENT_CARD_CATALOGUE = {
@@ -116,13 +167,16 @@ export const a2aTools = [
             required: ['agentType'],
         },
         handler: async (input) => {
-            const agentType = input.agentType;
-            const baseUrl = input.baseUrl || 'http://localhost:3000';
+            const agentType = validateAgentType(input.agentType);
+            if (!agentType) {
+                return { success: false, error: 'agentType is required (non-empty string, max 64 chars)' };
+            }
+            const baseUrl = validateBaseUrl(input.baseUrl);
             const card = buildAgentCard(agentType, baseUrl);
             if (!card) {
                 return {
                     success: false,
-                    error: `Unknown agent type: "${agentType}". Available: ${Object.keys(AGENT_CARD_CATALOGUE).join(', ')}`,
+                    error: `Unknown agent type. Available: ${Object.keys(AGENT_CARD_CATALOGUE).join(', ')}`,
                 };
             }
             return { success: true, agentCard: card, protocol: 'a2a', source: 'https://a2a-protocol.org' };
@@ -146,8 +200,19 @@ export const a2aTools = [
             },
         },
         handler: async (input) => {
-            const baseUrl = input.baseUrl || 'http://localhost:3000';
-            const capabilityFilter = input.capabilities;
+            const baseUrl = validateBaseUrl(input.baseUrl);
+            // Only accept a plain object capability filter to prevent prototype pollution.
+            // Object.create(null) maps and class instances are intentionally rejected.
+            const rawCap = input.capabilities;
+            const capabilityFilter = rawCap !== null &&
+                typeof rawCap === 'object' &&
+                !Array.isArray(rawCap) &&
+                Object.getPrototypeOf(rawCap) === Object.prototype
+                ? rawCap
+                : undefined;
+            const KNOWN_CAPABILITY_KEYS = new Set([
+                'streaming', 'pushNotifications', 'stateTransitionHistory',
+            ]);
             const cards = Object.keys(AGENT_CARD_CATALOGUE)
                 .map(type => buildAgentCard(type, baseUrl))
                 .filter((card) => {
@@ -155,9 +220,12 @@ export const a2aTools = [
                     return false;
                 if (!capabilityFilter)
                     return true;
-                // Apply capability filter
-                for (const [key, value] of Object.entries(capabilityFilter)) {
-                    if (card.capabilities[key] !== value)
+                // Apply capability filter — only iterate known keys to prevent
+                // prototype-chain access via attacker-controlled property names.
+                for (const key of KNOWN_CAPABILITY_KEYS) {
+                    if (!(key in capabilityFilter))
+                        continue;
+                    if (card.capabilities[key] !== capabilityFilter[key])
                         return false;
                 }
                 return true;
@@ -203,15 +271,32 @@ export const a2aTools = [
             required: ['agentType', 'message'],
         },
         handler: async (input) => {
-            const agentType = input.agentType;
+            const agentType = validateAgentType(input.agentType);
+            if (!agentType) {
+                return { success: false, error: 'agentType is required (non-empty string, max 64 chars)' };
+            }
             const message = input.message;
-            const taskId = input.taskId || `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-            const sessionId = input.sessionId;
-            const metadata = input.metadata || {};
+            const rawTaskId = validateOptionalId(input.taskId, MAX_TASK_ID_LEN);
+            if (rawTaskId === null) {
+                return { success: false, error: `taskId must be a non-empty string up to ${MAX_TASK_ID_LEN} chars` };
+            }
+            const taskId = rawTaskId ?? `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const rawSessionId = validateOptionalId(input.sessionId, MAX_SESSION_ID_LEN);
+            if (rawSessionId === null) {
+                return { success: false, error: `sessionId must be a non-empty string up to ${MAX_SESSION_ID_LEN} chars` };
+            }
+            const sessionId = rawSessionId;
+            // Only accept plain objects for metadata to prevent prototype pollution
+            const metadata = input.metadata !== null &&
+                typeof input.metadata === 'object' &&
+                !Array.isArray(input.metadata) &&
+                Object.getPrototypeOf(input.metadata) === Object.prototype
+                ? input.metadata
+                : {};
             if (!AGENT_CARD_CATALOGUE[agentType]) {
                 return {
                     success: false,
-                    error: `Unknown agent type: "${agentType}". Run a2a_discover to see available agents.`,
+                    error: `Unknown agent type. Run a2a_discover to see available agents.`,
                 };
             }
             // Return the A2A-compliant task submission envelope

package/packages/@monomind/cli/dist/src/mcp-tools/agent-tools.js

@@ -122,8 +122,18 @@ export const agentTools = [
         },
         handler: async (input) => {
             const store = loadAgentStore();
-            const agentId = input.agentId || `agent-${Date.now()}-${randomBytes(4).toString('hex')}`;
-            const agentType = input.agentType;
+            // Cap agentId: used as the JSON object key in store.agents[agentId].
+            // An oversized key inflates the on-disk store for every spawned agent.
+            // Cap agentType/domain: persisted as AgentRecord field values.
+            const MAX_AGENT_ID_LEN = 256;
+            const MAX_AGENT_TYPE_LEN = 128;
+            const MAX_AGENT_DOMAIN_LEN = 256;
+            const rawAgentId = input.agentId || `agent-${Date.now()}-${randomBytes(4).toString('hex')}`;
+            const agentId = typeof rawAgentId === 'string' && rawAgentId.length > MAX_AGENT_ID_LEN
+                ? rawAgentId.slice(0, MAX_AGENT_ID_LEN) : rawAgentId;
+            const rawAgentType = input.agentType;
+            const agentType = typeof rawAgentType === 'string' && rawAgentType.length > MAX_AGENT_TYPE_LEN
+                ? rawAgentType.slice(0, MAX_AGENT_TYPE_LEN) : rawAgentType;
             if (['__proto__', 'constructor', 'prototype'].includes(agentId)) {
                 return { success: false, agentId, error: 'Forbidden agent ID' };
             }
@@ -141,6 +151,9 @@ export const agentTools = [
             }
             // Get task from either top-level or config (CLI passes it in config.task)
             const task = input.task || config.task || undefined;
+            const rawDomain = input.domain;
+            const domain = typeof rawDomain === 'string' && rawDomain.length > MAX_AGENT_DOMAIN_LEN
+                ? rawDomain.slice(0, MAX_AGENT_DOMAIN_LEN) : rawDomain;
             // Determine model using ADR-026 3-tier routing logic
             const routingResult = await determineAgentModel(agentType, config, task);
             const agent = {
@@ -151,7 +164,7 @@ export const agentTools = [
                 taskCount: 0,
                 config,
                 createdAt: new Date().toISOString(),
-                domain: input.domain,
+                domain,
                 model: routingResult.model,
                 modelRoutedBy: routingResult.routedBy,
             };