open-multi-agent-kit 0.78.0

package/dist/mcp/client.d.ts

@@ -0,0 +1,112 @@
+export interface InitializeParams {
+    protocolVersion: string;
+    capabilities: {
+        tools?: object;
+        resources?: object;
+        prompts?: object;
+        sampling?: object;
+    };
+    clientInfo: {
+        name: string;
+        version: string;
+    };
+}
+export interface InitializeResult {
+    protocolVersion: string;
+    capabilities: {
+        tools?: object;
+        resources?: {
+            listChanged?: boolean;
+        };
+        prompts?: {
+            listChanged?: boolean;
+        };
+        sampling?: object;
+    };
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+}
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType?: string;
+}
+export interface McpPrompt {
+    name: string;
+    description: string;
+    arguments?: Array<{
+        name: string;
+        description: string;
+        required?: boolean;
+    }>;
+}
+export interface McpServerConfig {
+    name: string;
+    transport: "stdio" | "streamable-http" | "http";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    headers?: Record<string, string>;
+    http_headers?: Record<string, string>;
+    startupTimeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+export declare class McpClientSession {
+    private config;
+    private transport;
+    private requestIdCounter;
+    private pendingRequests;
+    private initialized;
+    private notificationHandlers;
+    private closed;
+    private readonly startupTimeoutMs;
+    private readonly requestTimeoutMs;
+    private malformedMessageCount;
+    private cleanupTimer;
+    private static readonly MAX_MALFORMED_MESSAGES;
+    private static readonly CLOSE_TIMEOUT_MS;
+    serverInfo: {
+        name: string;
+        version: string;
+    } | undefined;
+    constructor(config: McpServerConfig);
+    private createTransport;
+    connect(): Promise<void>;
+    get transportPid(): number | undefined;
+    close(): Promise<void>;
+    private handleTransportError;
+    private rejectAllPending;
+    private rejectPendingRequest;
+    private startCleanupTimer;
+    private handleIncoming;
+    private handleNotification;
+    private sendRequest;
+    private sendNotification;
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    listTools(): Promise<{
+        tools: McpTool[];
+    }>;
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    listResources(): Promise<{
+        resources: McpResource[];
+    }>;
+    readResource(uri: string): Promise<unknown>;
+    listPrompts(): Promise<{
+        prompts: McpPrompt[];
+    }>;
+    getPrompt(name: string, args?: Record<string, string>): Promise<unknown>;
+    onNotification(method: string, handler: (params: unknown) => void): () => void;
+}

package/dist/mcp/client.js

@@ -0,0 +1,276 @@
+// ─── MCP Client Session ─────────────────────────────────────────────────────
+// Per-server MCP client that handles the JSON-RPC 2.0 protocol over
+// a pluggable transport (stdio or streamable-http).
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function hasValidServerInfo(result) {
+    if (!isRecord(result) || !isRecord(result.serverInfo))
+        return false;
+    return typeof result.serverInfo.name === "string" && result.serverInfo.name.trim().length > 0
+        && typeof result.serverInfo.version === "string" && result.serverInfo.version.trim().length > 0;
+}
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 300_000;
+function normalizeTimeoutMs(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return Math.max(1, Math.floor(value));
+    }
+    return fallback;
+}
+function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+// ─── MCP Client Session ─────────────────────────────────────────────────────
+export class McpClientSession {
+    config;
+    transport = null;
+    requestIdCounter = 0;
+    pendingRequests = new Map();
+    initialized = false;
+    notificationHandlers = new Map();
+    closed = false;
+    startupTimeoutMs;
+    requestTimeoutMs;
+    malformedMessageCount = 0;
+    cleanupTimer = null;
+    static MAX_MALFORMED_MESSAGES = 3;
+    static CLOSE_TIMEOUT_MS = 10_000;
+    serverInfo;
+    constructor(config) {
+        this.config = config;
+        this.startupTimeoutMs = normalizeTimeoutMs(config.startupTimeoutMs, DEFAULT_STARTUP_TIMEOUT_MS);
+        this.requestTimeoutMs = normalizeTimeoutMs(config.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+    }
+    async createTransport() {
+        const config = this.config;
+        if (config.url) {
+            const { StreamableHttpTransport } = await import("./transports/streamable-http.js");
+            return new StreamableHttpTransport(config.url, {
+                ...(config.http_headers ?? {}),
+                ...(config.headers ?? {}),
+            });
+        }
+        if (config.command) {
+            const { StdioTransport } = await import("./transports/stdio.js");
+            return new StdioTransport(config.command, config.args ?? [], config.env ?? {});
+        }
+        throw new Error(`Cannot create transport for server ${config.name}: no url or command specified`);
+    }
+    // ── Connection lifecycle ──────────────────────────────────────────────
+    async connect() {
+        if (this.initialized)
+            return;
+        this.transport = await this.createTransport();
+        try {
+            await withTimeout(this.transport.connect(), this.startupTimeoutMs, `MCP transport connect timed out after ${this.startupTimeoutMs}ms`);
+        }
+        catch (err) {
+            await this.transport.close?.().catch(() => { });
+            this.transport = null;
+            throw err;
+        }
+        // Start listening for incoming messages
+        this.transport.onMessage((raw) => this.handleIncoming(raw));
+        this.transport.onNotification((method, params) => this.handleNotification(method, params));
+        this.transport.onError((err) => this.handleTransportError(err));
+        this.startCleanupTimer();
+    }
+    get transportPid() {
+        return this.transport?.pid;
+    }
+    async close() {
+        this.closed = true;
+        this.initialized = false;
+        this.rejectAllPending(new Error("Session closed"));
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        if (this.transport) {
+            await withTimeout(Promise.resolve(this.transport.close?.()), McpClientSession.CLOSE_TIMEOUT_MS, `MCP transport close timed out after ${McpClientSession.CLOSE_TIMEOUT_MS}ms`).catch(() => { });
+        }
+        this.transport = null;
+    }
+    handleTransportError(err) {
+        this.rejectAllPending(err);
+    }
+    rejectAllPending(err) {
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            pending.abort();
+            pending.reject(err);
+        }
+        this.pendingRequests.clear();
+    }
+    rejectPendingRequest(id, err) {
+        const pending = this.pendingRequests.get(id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeout);
+        pending.abort();
+        this.pendingRequests.delete(id);
+        pending.reject(err);
+    }
+    startCleanupTimer() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => {
+            if (this.pendingRequests.size === 0)
+                return;
+            if (this.closed || !this.transport) {
+                this.rejectAllPending(new Error("MCP session no longer active"));
+                return;
+            }
+            const now = Date.now();
+            for (const [id, pending] of this.pendingRequests) {
+                if (now - pending.createdAt > this.requestTimeoutMs) {
+                    this.rejectPendingRequest(id, new Error(`MCP request stale: ${id}`));
+                }
+            }
+        }, 30_000);
+        this.cleanupTimer.unref?.();
+    }
+    // ── Message handling ──────────────────────────────────────────────────
+    handleIncoming(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+            this.malformedMessageCount = 0;
+        }
+        catch {
+            this.malformedMessageCount++;
+            if (this.malformedMessageCount > McpClientSession.MAX_MALFORMED_MESSAGES) {
+                this.rejectAllPending(new Error("MCP server sent too many malformed JSON messages"));
+                this.malformedMessageCount = 0;
+            }
+            return;
+        }
+        if (msg.id !== undefined && this.pendingRequests.has(msg.id)) {
+            const pending = this.pendingRequests.get(msg.id);
+            clearTimeout(pending.timeout);
+            pending.abort();
+            this.pendingRequests.delete(msg.id);
+            if (msg.error) {
+                pending.reject(new Error(msg.error.message ?? `JSON-RPC error ${msg.error.code}`));
+            }
+            else {
+                pending.resolve(msg.result);
+            }
+        }
+    }
+    handleNotification(method, params) {
+        const handlers = this.notificationHandlers.get(method);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(params);
+                }
+                catch {
+                    // ignore handler errors
+                }
+            }
+        }
+    }
+    // ── JSON-RPC request/response ─────────────────────────────────────────
+    sendRequest(method, params, timeoutMs = this.requestTimeoutMs, signal) {
+        if (this.closed)
+            return Promise.reject(new Error("Session is closed"));
+        if (!this.transport)
+            return Promise.reject(new Error("Session is not connected"));
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new Error("Request aborted"));
+        const transport = this.transport;
+        const id = ++this.requestIdCounter;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.rejectPendingRequest(id, signal.reason ?? new Error("Request aborted"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const controller = new AbortController();
+            const timeout = setTimeout(() => {
+                controller.abort();
+                this.rejectPendingRequest(id, new Error(`MCP request timed out: ${method}`));
+            }, timeoutMs);
+            this.pendingRequests.set(id, {
+                resolve,
+                reject: (e) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    reject(e);
+                },
+                timeout,
+                abort: () => {
+                    controller.abort();
+                    signal?.removeEventListener("abort", onAbort);
+                },
+                createdAt: Date.now(),
+            });
+            const payload = { jsonrpc: "2.0", id, method, params };
+            const sendTimeoutMs = timeoutMs;
+            withTimeout(transport.send(JSON.stringify(payload) + "\n", { signal: controller.signal, timeoutMs }), sendTimeoutMs, `MCP transport send timed out after ${sendTimeoutMs}ms: ${method}`).catch((err) => {
+                controller.abort();
+                this.rejectPendingRequest(id, err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    sendNotification(method, params) {
+        if (this.closed || !this.transport)
+            return;
+        const payload = { jsonrpc: "2.0", method, params };
+        const timeoutMs = Math.min(this.requestTimeoutMs, 30_000);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        this.transport.send(JSON.stringify(payload) + "\n", {
+            signal: controller.signal,
+            timeoutMs,
+        }).catch(() => { }).finally(() => clearTimeout(timeout));
+    }
+    // ── MCP protocol methods ──────────────────────────────────────────────
+    async initialize(params) {
+        try {
+            const result = (await this.sendRequest("initialize", params, this.startupTimeoutMs));
+            if (!hasValidServerInfo(result)) {
+                throw new Error("MCP initialize response missing serverInfo.name/version");
+            }
+            this.initialized = true;
+            this.serverInfo = result.serverInfo;
+            // Send initialized notification
+            this.sendNotification("notifications/initialized", {});
+            return result;
+        }
+        catch (err) {
+            await this.close().catch(() => { });
+            throw err;
+        }
+    }
+    async listTools() {
+        return (await this.sendRequest("tools/list", {}));
+    }
+    async callTool(name, args) {
+        return this.sendRequest("tools/call", { name, arguments: args });
+    }
+    async listResources() {
+        return (await this.sendRequest("resources/list", {}));
+    }
+    async readResource(uri) {
+        return this.sendRequest("resources/read", { uri });
+    }
+    async listPrompts() {
+        return (await this.sendRequest("prompts/list", {}));
+    }
+    async getPrompt(name, args) {
+        return this.sendRequest("prompts/get", { name, arguments: args });
+    }
+    // ── Notification subscriptions ────────────────────────────────────────
+    onNotification(method, handler) {
+        if (!this.notificationHandlers.has(method)) {
+            this.notificationHandlers.set(method, new Set());
+        }
+        const handlers = this.notificationHandlers.get(method);
+        handlers.add(handler);
+        return () => handlers.delete(handler);
+    }
+}

package/dist/mcp/config-permissions.d.ts

@@ -0,0 +1,23 @@
+declare const MCP_PERMISSION_PROFILES: readonly ["default", "docs", "repo", "browser", "graph"];
+export type McpPermissionProfile = typeof MCP_PERMISSION_PROFILES[number];
+export declare function canWriteConfig(env?: NodeJS.ProcessEnv): boolean;
+export declare function configWriteDeniedMessage(): string;
+export declare function getMcpPermissionProfile(env?: NodeJS.ProcessEnv): McpPermissionProfile;
+export declare function canCallMcpTool(toolName: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function filterAllowedMcpTools<T extends {
+    name: string;
+}>(tools: readonly T[], env?: NodeJS.ProcessEnv): T[];
+export declare function mcpToolDeniedMessage(toolName: string, env?: NodeJS.ProcessEnv): string;
+export {};
+/**
+ * Recommended MCP permission profiles:
+ *
+ * - default : Read-only project info, goals, runs, and memory. Safe for general use.
+ * - docs    : Includes default + write access to memory and ontology. For documentation agents.
+ * - repo    : Includes docs + quality gates and evidence checks. For code-change agents.
+ * - browser : Includes repo + config write approval. For agents that need to mutate project settings.
+ * - graph   : Includes repo + full graph query and memory write. For ontology-heavy analysis agents.
+ *
+ * Profiles are enforced for write-capable omk-project MCP tools. Default sessions expose
+ * read-only tools only; trusted local sessions can opt into docs/repo/browser/graph.
+ */

package/dist/mcp/config-permissions.js

@@ -0,0 +1,66 @@
+const TRUTHY_VALUES = new Set(["1", "true", "yes", "on"]);
+const MCP_PERMISSION_PROFILES = ["default", "docs", "repo", "browser", "graph"];
+const WRITE_TOOL_PROFILES = new Map([
+    ["omk_memory_write", new Set(["docs", "repo", "browser", "graph"])],
+    ["omk_write_memory", new Set(["docs", "repo", "browser", "graph"])],
+    ["omk_goal_create", new Set(["repo", "browser"])],
+    ["omk_goal_close", new Set(["repo", "browser"])],
+    ["omk_goal_verify", new Set(["repo", "browser"])],
+    ["omk_evidence_add", new Set(["repo", "browser"])],
+    ["omk_evidence_check", new Set(["repo", "browser"])],
+    ["omk_quality_gate", new Set(["repo", "browser"])],
+    ["omk_run_quality_gate", new Set(["repo", "browser"])],
+    ["omk_run_quality_gate_print", new Set(["repo", "browser"])],
+    ["omk_write_todos", new Set(["repo", "browser"])],
+    ["TodoWrite", new Set(["repo", "browser"])],
+    ["omk_todo_write", new Set(["repo", "browser"])],
+    ["todo_write", new Set(["repo", "browser"])],
+    ["omk_save_checkpoint", new Set(["repo", "browser"])],
+    ["omk_restore_checkpoint", new Set(["repo", "browser"])],
+    ["omk_save_snippet", new Set(["docs", "repo", "browser", "graph"])],
+    ["omk_delete_snippet", new Set(["repo", "browser"])],
+    ["omk_write_config", new Set(["browser"])],
+]);
+export function canWriteConfig(env = process.env) {
+    return TRUTHY_VALUES.has(String(env.OMK_MCP_ALLOW_WRITE_CONFIG ?? "").trim().toLowerCase());
+}
+export function configWriteDeniedMessage() {
+    return "omk_write_config is disabled by default. Set OMK_MCP_ALLOW_WRITE_CONFIG=1 for trusted local sessions.";
+}
+export function getMcpPermissionProfile(env = process.env) {
+    const raw = String(env.OMK_MCP_PERMISSION_PROFILE ?? "default").trim().toLowerCase();
+    return MCP_PERMISSION_PROFILES.includes(raw) ? raw : "default";
+}
+export function canCallMcpTool(toolName, env = process.env) {
+    const allowedProfiles = WRITE_TOOL_PROFILES.get(toolName);
+    if (!allowedProfiles)
+        return true;
+    const profile = getMcpPermissionProfile(env);
+    if (!allowedProfiles.has(profile))
+        return false;
+    if (toolName === "omk_write_config")
+        return canWriteConfig(env);
+    return true;
+}
+export function filterAllowedMcpTools(tools, env = process.env) {
+    return tools.filter((tool) => canCallMcpTool(tool.name, env));
+}
+export function mcpToolDeniedMessage(toolName, env = process.env) {
+    if (toolName === "omk_write_config" && getMcpPermissionProfile(env) === "browser" && !canWriteConfig(env)) {
+        return configWriteDeniedMessage();
+    }
+    const profile = getMcpPermissionProfile(env);
+    return `${toolName} is not allowed by OMK MCP permission profile '${profile}'. Set OMK_MCP_PERMISSION_PROFILE to a trusted profile for write-capable tools.`;
+}
+/**
+ * Recommended MCP permission profiles:
+ *
+ * - default : Read-only project info, goals, runs, and memory. Safe for general use.
+ * - docs    : Includes default + write access to memory and ontology. For documentation agents.
+ * - repo    : Includes docs + quality gates and evidence checks. For code-change agents.
+ * - browser : Includes repo + config write approval. For agents that need to mutate project settings.
+ * - graph   : Includes repo + full graph query and memory write. For ontology-heavy analysis agents.
+ *
+ * Profiles are enforced for write-capable omk-project MCP tools. Default sessions expose
+ * read-only tools only; trusted local sessions can opt into docs/repo/browser/graph.
+ */

package/dist/mcp/consent-flow.d.ts

@@ -0,0 +1,152 @@
+import { EventEmitter } from "node:events";
+import { ToolPermissionLevel, type ResolvedToolPermission } from "./governance.js";
+/** User's consent decision */
+export declare enum ConsentDecision {
+    /** Allow this single invocation */
+    ALLOW_ONCE = "allow_once",
+    /** Deny this single invocation */
+    DENY_ONCE = "deny_once",
+    /** Allow always for this tool pattern (session-scoped) */
+    ALLOW_ALWAYS = "allow_always",
+    /** Deny always for this tool pattern (session-scoped) */
+    DENY_ALWAYS = "deny_always"
+}
+/** Scope for persistent decisions */
+export declare enum ConsentScope {
+    /** Only for this session */
+    SESSION = "session",
+    /** Persist across sessions (stored in config) */
+    PERMANENT = "permanent"
+}
+/** A pending consent request presented to the user */
+export interface ConsentRequest {
+    /** Unique request ID */
+    id: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Tool name being invoked */
+    toolName: string;
+    /** MCP server providing the tool */
+    serverName: string;
+    /** Arguments passed to the tool (sanitized) */
+    args: Record<string, unknown>;
+    /** Resolved permission that triggered this request */
+    permission: ResolvedToolPermission;
+    /** Matched rule reason (if any) */
+    reason?: string;
+    /** Rule severity */
+    severity?: string;
+    /** Rule category */
+    category?: string;
+}
+/** Result of a consent flow */
+export interface ConsentResult {
+    /** The decision made */
+    decision: ConsentDecision;
+    /** The original request */
+    request: ConsentRequest;
+    /** ISO 8601 timestamp of decision */
+    decidedAt: string;
+    /** Scope of the decision */
+    scope: ConsentScope;
+}
+/** Stored consent decision for future reference */
+export interface StoredConsent {
+    /** Tool name pattern */
+    toolPattern: string;
+    /** Server name (null = any server) */
+    serverName: string | null;
+    /** Decision (allow or deny) */
+    permission: ToolPermissionLevel.ALLOW | ToolPermissionLevel.DENY;
+    /** Scope */
+    scope: ConsentScope;
+    /** ISO 8601 timestamp when stored */
+    storedAt: string;
+    /** Optional reason */
+    reason?: string;
+}
+export interface ConsentFlowOptions {
+    /** Auto-deny if no response within timeout (ms, 0 = no timeout) */
+    timeoutMs?: number;
+    /** Default scope for decisions */
+    defaultScope?: ConsentScope;
+    /** Whether to emit events for UI integration */
+    emitEvents?: boolean;
+}
+export declare class ConsentFlowManager extends EventEmitter {
+    private decisions;
+    private pendingRequests;
+    private options;
+    constructor(options?: ConsentFlowOptions);
+    /**
+     * Check if a tool invocation needs consent.
+     * Returns null if already decided, or a ConsentRequest if user input is needed.
+     */
+    checkConsent(toolName: string, serverName: string, args: Record<string, unknown>, resolved: ResolvedToolPermission): ConsentRequest | null;
+    /**
+     * Record a user's consent decision.
+     */
+    recordDecision(requestId: string, decision: ConsentDecision, scope?: ConsentScope): ConsentResult;
+    /**
+     * Resolve permission considering stored consent decisions.
+     * Returns the effective permission (ALLOW/DENY) or null if still ASK.
+     */
+    resolveConsent(toolName: string, serverName: string): ToolPermissionLevel.ALLOW | ToolPermissionLevel.DENY | null;
+    /**
+     * Get all stored decisions.
+     */
+    getStoredDecisions(): StoredConsent[];
+    /**
+     * Remove a stored decision by tool pattern.
+     */
+    removeDecision(toolPattern: string, serverName?: string): boolean;
+    /**
+     * Clear all stored decisions.
+     */
+    clearDecisions(): void;
+    /**
+     * Get pending consent requests.
+     */
+    getPendingRequests(): ConsentRequest[];
+    /**
+     * Cancel a pending consent request.
+     */
+    cancelRequest(requestId: string): boolean;
+    /**
+     * Format a consent request for terminal display.
+     */
+    static formatRequest(request: ConsentRequest): string;
+    /**
+     * Format a consent result for terminal display.
+     */
+    static formatResult(result: ConsentResult): string;
+    private static getSeverityIcon;
+    private getStoredDecision;
+    private makeKey;
+}
+/**
+ * Interactive CLI consent prompt using readline.
+ * Returns the user's decision.
+ */
+export declare function promptConsent(request: ConsentRequest, inputStream?: NodeJS.ReadableStream, outputStream?: NodeJS.WritableStream): Promise<ConsentDecision>;
+/**
+ * Wraps a PermissionMatcher with consent flow.
+ * When permission resolves to ASK, triggers consent flow.
+ */
+export declare class ConsentAwareResolver {
+    private consentManager;
+    constructor(consentManager?: ConsentFlowManager);
+    /**
+     * Get the underlying consent manager.
+     */
+    getConsentManager(): ConsentFlowManager;
+    /**
+     * Resolve permission with consent flow.
+     * Returns ALLOW or DENY (never ASK — consent is resolved before returning).
+     */
+    resolveWithConsent(toolName: string, serverName: string, args: Record<string, unknown>, resolved: ResolvedToolPermission): {
+        permission: ToolPermissionLevel.ALLOW | ToolPermissionLevel.DENY;
+        consentRequest?: ConsentRequest;
+        consentResult?: ConsentResult;
+    };
+}