qlogicagent 2.13.3 → 2.13.5

package/dist/skills/mcp/mcp-manager.js

@@ -0,0 +1,358 @@
+// ============================================================
+// MCP Manager — mcporter-backed orchestration of MCP servers.
+//
+// Protocol layer = official @modelcontextprotocol/sdk via the mcporter
+// runtime (openclaw's standard MCP toolkit) — no hand-rolled transports.
+// This class only:
+//   1. maps qlogicagent's mcp.json entries → mcporter ServerDefinitions
+//   2. snapshots each server's tools at connect time
+//   3. injects them into the tool pool as `mcp__{server}__{tool}`
+//   4. enforces the workspace boundary on local-path arguments
+//
+// Tool lists are connect-time snapshots: mcporter does not surface
+// tools/list_changed, so a server that mutates its tool set needs a
+// reload (config save → bootstrap re-runs) to be picked up.
+// ============================================================
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRuntime } from "mcporter";
+import { addTools, removeTool } from "../tools.js";
+import { deriveMcpPortableToolTraits } from "./mcp-tool-metadata.js";
+/** Default per-call budget for MCP tool invocations. */
+const MCP_CALL_TIMEOUT_MS = 120_000;
+// ── Manager class ───────────────────────────────────────────
+export class McpManager {
+    runtime = null;
+    definitions = [];
+    toolsByServer = new Map();
+    injectedNames = new Set();
+    log;
+    workspaceRoot;
+    toolCatalog;
+    constructor(config) {
+        this.log = config.log ?? { info: () => { }, warn: () => { } };
+        this.workspaceRoot = config.workspaceRoot ? path.resolve(config.workspaceRoot) : undefined;
+        this.toolCatalog = config.toolCatalog;
+        this.definitions = config.servers
+            .filter((entry) => !entry.disabled)
+            .map((entry) => this.toServerDefinition(entry))
+            .filter((definition) => definition !== null);
+    }
+    toServerDefinition(entry) {
+        const transport = entry.type ?? (entry.url ? "http" : "stdio");
+        if (transport === "http") {
+            if (!entry.url) {
+                this.log.warn(`[mcp] server "${entry.name}" is type "http" but has no url, skipping`);
+                return null;
+            }
+            let url;
+            try {
+                url = new URL(entry.url);
+            }
+            catch {
+                this.log.warn(`[mcp] server "${entry.name}" has an invalid url "${entry.url}", skipping`);
+                return null;
+            }
+            return {
+                name: entry.name,
+                command: { kind: "http", url, headers: entry.headers },
+            };
+        }
+        if (!entry.command) {
+            this.log.warn(`[mcp] server "${entry.name}" is type "stdio" but has no command, skipping`);
+            return null;
+        }
+        return {
+            name: entry.name,
+            command: {
+                kind: "stdio",
+                command: entry.command,
+                args: entry.args ?? [],
+                cwd: entry.cwd ?? this.workspaceRoot ?? process.cwd(),
+            },
+            env: entry.env,
+        };
+    }
+    /**
+     * Connect to all configured MCP servers and snapshot their tools.
+     * Per-server failures are logged but don't block the rest.
+     */
+    async connectAll() {
+        if (this.definitions.length === 0)
+            return;
+        // The agent process speaks JSON-RPC on stdout — mcporter logging is
+        // routed to our logger (stderr-backed), never the console.
+        this.runtime = await createRuntime({
+            servers: this.definitions,
+            clientInfo: { name: "qlogicagent", version: "1.0.0" },
+            logger: {
+                info: (message) => this.log.info(`[mcp] ${message}`),
+                warn: (message) => this.log.warn(`[mcp] ${message}`),
+                error: (message, error) => this.log.warn(`[mcp] ${message}${error ? ` (${error instanceof Error ? error.message : String(error)})` : ""}`),
+                debug: () => { },
+            },
+        });
+        await Promise.allSettled(this.definitions.map(async (definition) => {
+            try {
+                // Headless agent process: rely on cached tokens only — an OAuth
+                // browser launch from inside the agent would hang the turn.
+                const tools = await this.runtime.listTools(definition.name, { includeSchema: true, disableOAuth: true });
+                this.toolsByServer.set(definition.name, tools);
+                this.log.info(`[mcp] connected to ${definition.name} (${tools.length} tools)`);
+            }
+            catch (err) {
+                this.log.warn(`[mcp] failed to connect to ${definition.name}: ${err instanceof Error ? err.message : err}`);
+            }
+        }));
+    }
+    /**
+     * Register all snapshotted MCP tools into the tool pool.
+     */
+    injectTools() {
+        for (const [serverName, tools] of this.toolsByServer) {
+            const portable = this.wrapToolsForWorkspaceBoundary(tools.map((tool) => this.toPortableTool(serverName, tool)));
+            this.registerTools(portable);
+            for (const tool of portable)
+                this.injectedNames.add(tool.name);
+            this.log.info(`[mcp] injected ${portable.length} tools from ${serverName}`);
+        }
+    }
+    /** Get names of all connected servers. */
+    getConnectedServers() {
+        return Array.from(this.toolsByServer.keys());
+    }
+    /** Get total number of MCP tools across all servers. */
+    getToolCount() {
+        let count = 0;
+        for (const tools of this.toolsByServer.values())
+            count += tools.length;
+        return count;
+    }
+    /**
+     * Close all MCP connections and retract the injected tools, so a config
+     * reload never leaves ghost tools bound to a closed runtime.
+     */
+    async disconnectAll() {
+        for (const name of this.injectedNames) {
+            this.removeRegisteredTool(name);
+        }
+        this.injectedNames.clear();
+        this.toolsByServer.clear();
+        const runtime = this.runtime;
+        this.runtime = null;
+        if (runtime) {
+            try {
+                await runtime.close();
+            }
+            catch {
+                // Ignore close errors — the process is shutting down or reloading.
+            }
+        }
+    }
+    // ── Private ──────────────────────────────────────────────
+    toPortableTool(serverName, mcpTool) {
+        const traits = deriveMcpPortableToolTraits({
+            name: mcpTool.name,
+            description: mcpTool.description,
+        });
+        return {
+            name: `mcp__${normalizeServerName(serverName)}__${mcpTool.name}`,
+            label: `[${serverName}] ${mcpTool.name}`,
+            category: "mcp",
+            description: mcpTool.description ?? `MCP tool from ${serverName}`,
+            parameters: mcpTool.inputSchema ?? { type: "object", properties: {} },
+            isConcurrencySafe: traits.isConcurrencySafe,
+            isReadOnly: traits.isReadOnly,
+            isDestructive: traits.isDestructive,
+            searchHint: `mcp ${serverName} ${mcpTool.name}`,
+            execute: async (_toolCallId, params) => {
+                const runtime = this.runtime;
+                if (!runtime) {
+                    return {
+                        content: [{ type: "text", text: `MCP server "${serverName}" is not connected.` }],
+                        details: { error: "mcp_not_connected" },
+                    };
+                }
+                try {
+                    const result = await runtime.callTool(serverName, mcpTool.name, {
+                        args: params,
+                        timeoutMs: MCP_CALL_TIMEOUT_MS,
+                    });
+                    return toPortableResult(result);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: `MCP tool error: ${msg}` }],
+                        details: { error: msg },
+                    };
+                }
+            },
+        };
+    }
+    wrapToolsForWorkspaceBoundary(tools) {
+        if (!this.workspaceRoot)
+            return tools;
+        return tools.map((tool) => {
+            if (!tool.execute)
+                return tool;
+            const execute = tool.execute;
+            return {
+                ...tool,
+                execute: async (toolCallId, params, signal) => {
+                    const blocked = validateMcpToolWorkspaceBoundary(tool.name, params, this.workspaceRoot);
+                    if (blocked) {
+                        return {
+                            content: [{ type: "text", text: blocked }],
+                            details: { type: "mcp", error: "workspace_boundary" },
+                        };
+                    }
+                    return execute(toolCallId, params, signal);
+                },
+            };
+        });
+    }
+    registerTools(tools) {
+        if (this.toolCatalog) {
+            this.toolCatalog.addTools(tools);
+        }
+        else {
+            addTools(tools);
+        }
+    }
+    removeRegisteredTool(name) {
+        return this.toolCatalog?.removeTool(name) ?? removeTool(name);
+    }
+}
+/** Flatten an MCP CallToolResult into a text-bearing PortableToolResult. */
+function toPortableResult(result) {
+    const record = (result && typeof result === "object") ? result : {};
+    const content = Array.isArray(record.content) ? record.content : [];
+    const textParts = content
+        .filter((item) => !!item && typeof item === "object")
+        .filter((item) => item.type === "text" && typeof item.text === "string")
+        .map((item) => item.text);
+    const text = textParts.join("\n") || "(no text output)";
+    return {
+        content: [{ type: "text", text }],
+        ...(record.isError ? { details: { error: "mcp_tool_error" } } : {}),
+    };
+}
+function normalizeServerName(serverName) {
+    return serverName.replace(/[^a-zA-Z0-9_]/g, "_").toLowerCase();
+}
+// ── Workspace boundary (security: local paths must stay inside the project) ──
+const MCP_LOCAL_PATH_KEY = /(?:^|_)(path|paths|file|files|filename|filenames|dir|dirs|directory|directories|folder|folders|cwd|root|uri)(?:$|_)/i;
+export function validateMcpToolWorkspaceBoundary(toolName, args, workspaceRoot) {
+    if (!workspaceRoot)
+        return null;
+    for (const candidate of collectMcpPathCandidates(args)) {
+        const resolved = resolveMcpPathCandidate(candidate.value, workspaceRoot);
+        if (!resolved)
+            continue;
+        if (!isPathWithinRoot(resolved.candidate, resolved.root, resolved.pathApi)) {
+            return `Blocked: MCP tool "${toolName}" path "${candidate.value}" is outside the workspace boundary "${resolved.root}"`;
+        }
+    }
+    return null;
+}
+function collectMcpPathCandidates(value, key = "", depth = 0) {
+    if (depth > 8)
+        return [];
+    if (typeof value === "string") {
+        return isMcpLocalPathCandidate(key, value) ? [{ key, value }] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => collectMcpPathCandidates(item, key, depth + 1));
+    }
+    if (!value || typeof value !== "object")
+        return [];
+    const result = [];
+    for (const [childKey, childValue] of Object.entries(value)) {
+        result.push(...collectMcpPathCandidates(childValue, childKey, depth + 1));
+    }
+    return result;
+}
+function isMcpLocalPathCandidate(key, value) {
+    if (!MCP_LOCAL_PATH_KEY.test(key))
+        return false;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    if (/^https?:\/\//i.test(trimmed))
+        return false;
+    return isLocalPathLike(trimmed);
+}
+function isLocalPathLike(value) {
+    return path.isAbsolute(value)
+        || /^[A-Za-z]:[\\/]/.test(value)
+        || /^\\\\/.test(value)
+        || /^file:\/\//i.test(value)
+        || value.includes("../")
+        || value.includes("..\\")
+        || value.startsWith(".\\")
+        || value.startsWith("./")
+        || value.includes("/")
+        || value.includes("\\");
+}
+function resolveMcpPathCandidate(value, workspaceRoot) {
+    let raw = value.trim();
+    if (/^file:\/\//i.test(raw)) {
+        try {
+            raw = fileURLToPath(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    const pathApi = isWindowsPathLike(raw) || isWindowsPathLike(workspaceRoot) ? path.win32 : path;
+    const root = pathApi.resolve(workspaceRoot);
+    const candidate = pathApi.isAbsolute(raw) ? pathApi.resolve(raw) : pathApi.resolve(root, raw);
+    return { candidate, root, pathApi };
+}
+function isPathWithinRoot(candidate, root, pathApi) {
+    const relative = pathApi.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !pathApi.isAbsolute(relative));
+}
+function isWindowsPathLike(value) {
+    return /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+}
+// ── Config parser (mcp.json — Claude Code compatible) ───────
+export function parseMcpConfig(json) {
+    if (!json || typeof json !== "object")
+        return [];
+    const obj = json;
+    const servers = [];
+    // Format 1: { "mcpServers": { "name": { "command": "...", "args": [...] } } }
+    const mcpServers = (obj.mcpServers ?? obj.servers ?? obj);
+    for (const [name, config] of Object.entries(mcpServers)) {
+        if (!config || typeof config !== "object")
+            continue;
+        const c = config;
+        // HTTP transport: has "url" field
+        if (typeof c.url === "string") {
+            servers.push({
+                name,
+                type: "http",
+                url: c.url,
+                headers: (c.headers && typeof c.headers === "object") ? c.headers : undefined,
+                disabled: c.disabled === true,
+                initTimeoutMs: typeof c.initTimeoutMs === "number" ? c.initTimeoutMs : undefined,
+            });
+            continue;
+        }
+        // Stdio transport: has "command" field
+        if (typeof c.command !== "string")
+            continue;
+        servers.push({
+            name,
+            type: "stdio",
+            command: c.command,
+            args: Array.isArray(c.args) ? c.args : undefined,
+            env: (c.env && typeof c.env === "object") ? c.env : undefined,
+            cwd: typeof c.cwd === "string" ? c.cwd : undefined,
+            disabled: c.disabled === true,
+        });
+    }
+    return servers;
+}

package/dist/skills/mcp/mcp-tool-metadata.d.ts

@@ -0,0 +1,18 @@
+export interface McpToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    title?: string;
+}
+export interface McpToolMetadataInput {
+    name: string;
+    description?: string;
+    annotations?: McpToolAnnotations;
+}
+export interface McpPortableToolTraits {
+    isReadOnly: boolean;
+    isConcurrencySafe: boolean;
+    isDestructive: boolean;
+}
+export declare function deriveMcpPortableToolTraits(tool: McpToolMetadataInput): McpPortableToolTraits;

package/dist/skills/mcp/mcp-tool-metadata.js

@@ -0,0 +1,48 @@
+const READ_ONLY_VERBS = new Set([
+    "describe",
+    "fetch",
+    "find",
+    "get",
+    "inspect",
+    "list",
+    "query",
+    "read",
+    "search",
+    "stat",
+]);
+const MUTATING_VERBS = new Set([
+    "append",
+    "copy",
+    "create",
+    "delete",
+    "edit",
+    "move",
+    "patch",
+    "remove",
+    "rename",
+    "set",
+    "update",
+    "upload",
+    "write",
+]);
+export function deriveMcpPortableToolTraits(tool) {
+    const annotations = tool.annotations;
+    const tokens = tokenizeToolName(tool.name);
+    const hasMutatingVerb = tokens.some((token) => MUTATING_VERBS.has(token));
+    const hasReadOnlyVerb = tokens.some((token) => READ_ONLY_VERBS.has(token));
+    const isDestructive = annotations?.destructiveHint === true || hasMutatingVerb;
+    const isReadOnly = annotations?.readOnlyHint === true || (!isDestructive && hasReadOnlyVerb);
+    const isConcurrencySafe = isReadOnly || (annotations?.idempotentHint === true && !isDestructive);
+    return {
+        isReadOnly,
+        isConcurrencySafe,
+        isDestructive,
+    };
+}
+function tokenizeToolName(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}

package/dist/skills/memory/categories.d.ts

@@ -0,0 +1 @@
+export type { QMemoryCategory } from "../../runtime/memory/categories.js";

package/dist/skills/memory/categories.js

@@ -0,0 +1 @@
+export {};

package/dist/skills/memory/find-relevant-memories.d.ts

@@ -0,0 +1 @@
+export * from "../../runtime/memory/find-relevant-memories.js";

package/dist/skills/memory/find-relevant-memories.js

@@ -0,0 +1 @@
+export * from "../../runtime/memory/find-relevant-memories.js";

package/dist/skills/memory/implicit-extraction.d.ts

@@ -0,0 +1 @@
+export * from "../../runtime/memory/implicit-extraction.js";

package/dist/skills/memory/implicit-extraction.js

@@ -0,0 +1 @@
+export * from "../../runtime/memory/implicit-extraction.js";

package/dist/skills/memory/local-embedding.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Local Embedding — Pluggable embedding interface for local memory.
+ *
+ * Provides a unified interface for text → vector embedding.
+ * If no API config is provided, memory search falls back to FTS-only.
+ */
+export interface EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+export interface EmbeddingApiConfig {
+    /** OpenAI-compatible embedding API base URL */
+    baseUrl: string;
+    /** API key */
+    apiKey: string;
+    /** Model name (e.g. "text-embedding-3-small") */
+    model: string;
+    /** Expected dimensions (default: 1536 for text-embedding-3-small) */
+    dimensions?: number;
+    /** Request timeout in ms (default: 10000) */
+    timeoutMs?: number;
+    /**
+     * Provider-specific API format.
+     * - "openai": Standard /v1/embeddings with input:string[] → data[].embedding (default)
+     * - "minimax": /v1/embeddings with texts:string[] → vectors[]
+     * - "volcengine": /v1/embeddings/multimodal with input:[{type,text}] → data.embedding
+     */
+    format?: "openai" | "minimax" | "volcengine";
+}
+export declare class NullEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions = 0;
+    readonly model = "none";
+    embed(_text: string): Promise<Float32Array>;
+    embedBatch(_texts: string[]): Promise<Float32Array[]>;
+}
+export declare class ApiEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    private format;
+    constructor(config: EmbeddingApiConfig);
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    private buildRequest;
+    private parseResponse;
+}
+export interface LocalEmbeddingConfig {
+    api?: EmbeddingApiConfig;
+}
+/**
+ * Create an embedding provider based on configuration.
+ *
+ * Resolution order:
+ *   1. API config → ApiEmbeddingProvider
+ *   2. No API config → NullEmbeddingProvider (FTS-only)
+ */
+export declare function createEmbeddingProvider(config?: LocalEmbeddingConfig): EmbeddingProvider;
+/**
+ * Known provider → format mapping.
+ * Used only for the explicit ModelRegistry embedding binding.
+ */
+export declare const PROVIDER_EMBEDDING_REGISTRY: Record<string, {
+    format: "openai" | "minimax" | "volcengine";
+    baseUrl: string;
+    defaultModel: string;
+    defaultDimensions: number;
+}>;
+/**
+ * Resolve EmbeddingApiConfig from a known provider name + API key.
+ * Returns null if the provider has no known embedding endpoint.
+ */
+export declare function resolveProviderEmbeddingConfig(provider: string, apiKey: string, overrides?: {
+    model?: string;
+    baseUrl?: string;
+    dimensions?: number;
+}): EmbeddingApiConfig | null;