@claude-flow/cli 3.71.4 → 3.72.1

package/dist/src/mcp-protocol.js

@@ -0,0 +1,179 @@
+/**
+ * MCP protocol-version handling for the stdio servers (ADR-524).
+ *
+ * Ruflo ships three stdio entry points (`bin/cli.js` auto-detect, `bin/mcp-server.js`,
+ * and `MCPServerManager` in mcp-server.ts). All three answered `initialize` with a
+ * hardcoded `2024-11-05` and knew nothing of the 2026-07-28 revision, which drops the
+ * handshake and carries the version on every request. This module is the one place
+ * that decides which revision a message speaks, so the three handlers cannot drift.
+ *
+ * Dual-era behaviour (spec: basic/versioning):
+ *  - `initialize` selects legacy semantics; the requested legacy version is echoed.
+ *  - a request carrying `_meta["io.modelcontextprotocol/protocolVersion"]` is served
+ *    statelessly: `resultType` and `serverInfo` on every result, cache hints on lists,
+ *    `-32602` for an unknown resource, `-32022` for an unsupported version.
+ *  - `server/discover` is always answered, so a dual-era client's stdio probe succeeds.
+ */
+import { readFileSync } from 'node:fs';
+export const MODERN_PROTOCOL_VERSIONS = ['2026-07-28'];
+// 2025-03-26 is deliberately absent: it is the one revision that allowed JSON-RPC batching, which these
+// line-at-a-time handlers do not accept. A client asking for it is offered 2025-11-25 instead.
+export const LEGACY_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2024-11-05'];
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+    ...MODERN_PROTOCOL_VERSIONS,
+    ...LEGACY_PROTOCOL_VERSIONS,
+];
+/** Offered to a legacy client whose requested version we do not know. */
+export const LATEST_LEGACY_PROTOCOL_VERSION = LEGACY_PROTOCOL_VERSIONS[0];
+export const META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion';
+export const META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+export const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+export const ERROR_INVALID_PARAMS = -32602;
+export const ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** 2025-11-25 and earlier; replaced by -32602 in 2026-07-28. */
+export const ERROR_LEGACY_RESOURCE_NOT_FOUND = -32002;
+/** Tool catalogue is fixed for the life of a stdio process; five minutes is a conservative hint. */
+export const TOOLS_LIST_TTL_MS = 300_000;
+export const DISCOVER_TTL_MS = 3_600_000;
+const LIST_METHODS = new Set(['tools/list', 'prompts/list', 'resources/list', 'resources/templates/list']);
+// W3C Trace Context: version-traceid-parentid-flags, lowercase hex, ids not all zero, version != ff.
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+let cachedVersion;
+/** The CLI package version, read once from package.json (dist/src/ → ../../). */
+export function rufloPackageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    for (const rel of ['../../package.json', '../package.json']) {
+        try {
+            const pkg = JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+            if (pkg.name === '@claude-flow/cli' && typeof pkg.version === 'string') {
+                cachedVersion = pkg.version;
+                return cachedVersion;
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    cachedVersion = '0.0.0';
+    return cachedVersion;
+}
+export function defaultServerIdentity() {
+    return { name: 'ruflo', version: rufloPackageVersion() };
+}
+/** Pick the legacy version to answer `initialize` with (spec: echo if supported, else our latest). */
+export function negotiateLegacyVersion(requested) {
+    return typeof requested === 'string' && LEGACY_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : LATEST_LEGACY_PROTOCOL_VERSION;
+}
+export function isValidTraceparent(value) {
+    if (typeof value !== 'string')
+        return false;
+    const m = TRACEPARENT.exec(value);
+    if (!m)
+        return false;
+    const [, version, traceId, parentId] = m;
+    return version !== 'ff' && !/^0+$/.test(traceId) && !/^0+$/.test(parentId);
+}
+function metaOf(params) {
+    if (!params || typeof params !== 'object')
+        return undefined;
+    const meta = params._meta;
+    return meta && typeof meta === 'object' && !Array.isArray(meta) ? meta : undefined;
+}
+function error(id, code, message, data) {
+    return { jsonrpc: '2.0', id: id ?? null, error: data === undefined ? { code, message } : { code, message, data } };
+}
+/**
+ * Decide how to serve one inbound message before the handler's own switch runs.
+ * Returns a complete response for `initialize`, `server/discover` and protocol
+ * errors; otherwise returns the context the handler passes to `finalizeResponse`.
+ */
+export function protocolPreflight(message, capabilities, identity = defaultServerIdentity()) {
+    const meta = metaOf(message.params);
+    const traceparent = isValidTraceparent(meta?.traceparent) ? meta.traceparent : undefined;
+    const tracestate = traceparent && typeof meta?.tracestate === 'string' && meta.tracestate.length <= 512
+        ? meta.tracestate
+        : undefined;
+    const declared = meta?.[META_PROTOCOL_VERSION];
+    const isNotification = message.id === undefined || message.id === null;
+    if (message.method === 'initialize') {
+        const requested = message.params?.protocolVersion;
+        return {
+            response: {
+                jsonrpc: '2.0',
+                id: message.id,
+                result: { protocolVersion: negotiateLegacyVersion(requested), serverInfo: identity, capabilities },
+            },
+        };
+    }
+    if (declared !== undefined && !isNotification) {
+        if (typeof declared !== 'string' || !SUPPORTED_PROTOCOL_VERSIONS.includes(declared)) {
+            return {
+                response: error(message.id, ERROR_UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', {
+                    supported: [...SUPPORTED_PROTOCOL_VERSIONS],
+                    requested: declared,
+                }),
+            };
+        }
+        const modern = MODERN_PROTOCOL_VERSIONS.includes(declared);
+        if (modern) {
+            const caps = meta?.[META_CLIENT_CAPABILITIES];
+            if (message.method !== 'server/discover' && (!caps || typeof caps !== 'object' || Array.isArray(caps))) {
+                return { response: error(message.id, ERROR_INVALID_PARAMS, `Missing required _meta field: ${META_CLIENT_CAPABILITIES}`) };
+            }
+        }
+        if (message.method === 'server/discover')
+            return { response: discoverResponse(message.id, capabilities, identity) };
+        return { context: { modern, version: declared, traceparent, tracestate } };
+    }
+    if (message.method === 'server/discover')
+        return { response: discoverResponse(message.id, capabilities, identity) };
+    return { context: { modern: false, traceparent, tracestate } };
+}
+function discoverResponse(id, capabilities, identity) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+            resultType: 'complete',
+            supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+            capabilities,
+            _meta: { [META_SERVER_INFO]: identity },
+            ttlMs: DISCOVER_TTL_MS,
+            cacheScope: 'private',
+        },
+    };
+}
+/** The resource-not-found code the request's revision expects. */
+export function resourceNotFoundCode(context) {
+    return context.modern ? ERROR_INVALID_PARAMS : ERROR_LEGACY_RESOURCE_NOT_FOUND;
+}
+/** Stable, name-ordered copy so `tools/list` is byte-identical across calls (prompt-cache friendly). */
+export function sortToolsDeterministically(tools) {
+    return [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/** Tool-call context fields to forward, so handlers and logs can join the caller's trace. */
+export function traceContextFields(context) {
+    const out = {};
+    if (context.traceparent)
+        out.traceparent = context.traceparent;
+    if (context.tracestate)
+        out.tracestate = context.tracestate;
+    return out;
+}
+/** Add the 2026-07-28 result fields to a handler's response. Legacy responses pass through untouched. */
+export function finalizeResponse(response, method, context, identity = defaultServerIdentity()) {
+    if (!response || !context.modern || !response.result)
+        return response;
+    const result = { resultType: 'complete', ...response.result };
+    const priorMeta = result._meta && typeof result._meta === 'object' ? result._meta : {};
+    result._meta = { ...priorMeta, [META_SERVER_INFO]: identity };
+    if (method && LIST_METHODS.has(method)) {
+        result.ttlMs = TOOLS_LIST_TTL_MS;
+        result.cacheScope = 'private';
+    }
+    return { ...response, result };
+}
+//# sourceMappingURL=mcp-protocol.js.map

package/dist/src/mcp-server.d.ts

@@ -182,6 +182,7 @@ export declare class MCPServerManager extends EventEmitter {
      * Handle incoming MCP message
      */
     private handleMCPMessage;
+    private dispatchMCPMessage;
     /**
      * Start HTTP server in-process
      */

package/dist/src/mcp-server.js

@@ -26,6 +26,7 @@ import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { trackRequest } from './mcp-tools/request-tracker.js';
+import { defaultServerIdentity, finalizeResponse, protocolPreflight, resourceNotFoundCode, sortToolsDeterministically, traceContextFields, } from './mcp-protocol.js';
 import { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall, } from './mcp-tools/policy-enforcer.js';
 /** A failed task can be valid data; only an explicit error denotes tool failure. */
 function hasToolError(result) {
@@ -275,6 +276,11 @@ export function assessMcpSchemaOverhead(tools, contextWindowTokens) {
             : 'normal',
     };
 }
+/** Capabilities every ruflo stdio server advertises (initialize and server/discover). */
+const MCP_STDIO_CAPABILITIES = {
+    tools: { listChanged: true },
+    resources: {},
+};
 /**
  * MCP Server Manager
  *
@@ -616,7 +622,7 @@ export class MCPServerManager extends EventEmitter {
         });
         // Import the tool registry
         const { listMCPTools, callMCPTool, hasTool } = await import('./mcp-client.js');
-        const VERSION = '3.0.0';
+        const VERSION = defaultServerIdentity().version;
         const sessionId = `mcp-${Date.now()}-${randomUUID().slice(0, 8)}`;
         // Log to stderr to not corrupt stdout
         console.error(`[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Starting in stdio mode`);
@@ -663,10 +669,7 @@ export class MCPServerManager extends EventEmitter {
                 serverInfo: {
                     name: 'ruflo',
                     version: VERSION,
-                    capabilities: {
-                        tools: { listChanged: true },
-                        resources: {},
-                    },
+                    capabilities: MCP_STDIO_CAPABILITIES,
                 },
             },
         });
@@ -722,7 +725,6 @@ export class MCPServerManager extends EventEmitter {
      * Handle incoming MCP message
      */
     async handleMCPMessage(message, sessionId) {
-        const { listMCPTools, callMCPTool, hasTool } = await import('./mcp-client.js');
         if (!message.method) {
             return {
                 jsonrpc: '2.0',
@@ -730,24 +732,20 @@ export class MCPServerManager extends EventEmitter {
                 error: { code: -32600, message: 'Invalid Request: missing method' },
             };
         }
+        // ADR-524: one decision point for which MCP revision this message speaks.
+        const preflight = protocolPreflight(message, MCP_STDIO_CAPABILITIES);
+        if (preflight.response)
+            return preflight.response;
+        const response = await this.dispatchMCPMessage(message, sessionId, preflight.context);
+        return finalizeResponse(response, message.method, preflight.context);
+    }
+    async dispatchMCPMessage(message, sessionId, protocol) {
+        const { listMCPTools, callMCPTool, hasTool } = await import('./mcp-client.js');
         const params = (message.params || {});
         try {
             switch (message.method) {
-                case 'initialize':
-                    return {
-                        jsonrpc: '2.0',
-                        id: message.id,
-                        result: {
-                            protocolVersion: '2024-11-05',
-                            serverInfo: { name: 'ruflo', version: '3.0.0' },
-                            capabilities: {
-                                tools: { listChanged: true },
-                                resources: {},
-                            },
-                        },
-                    };
                 case 'tools/list':
-                    const tools = filterAdvertisedMcpTools(listMCPTools(), this.options.tools);
+                    const tools = sortToolsDeterministically(filterAdvertisedMcpTools(listMCPTools(), this.options.tools));
                     return {
                         jsonrpc: '2.0',
                         id: message.id,
@@ -781,7 +779,7 @@ export class MCPServerManager extends EventEmitter {
                         }
                     }
                     try {
-                        const result = await callMCPTool(toolName, toolParams, { sessionId, transport: 'stdio' });
+                        const result = await callMCPTool(toolName, toolParams, { sessionId, transport: 'stdio', ...traceContextFields(protocol) });
                         const isError = hasToolError(result);
                         trackRequest(toolName, !isError);
                         return {
@@ -808,7 +806,7 @@ export class MCPServerManager extends EventEmitter {
                 case 'resources/templates/list':
                     return { jsonrpc: '2.0', id: message.id, result: { resourceTemplates: [] } };
                 case 'resources/read':
-                    return { jsonrpc: '2.0', id: message.id, error: { code: -32002, message: 'Resource not found' } };
+                    return { jsonrpc: '2.0', id: message.id, error: { code: resourceNotFoundCode(protocol), message: 'Resource not found' } };
                 case 'notifications/initialized':
                     // Client notification - no response needed
                     console.error(`[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Client initialized`);

package/dist/src/mcp-tools/agent-execute-core.js

@@ -147,10 +147,18 @@ export async function callAnthropicMessages(input) {
         // checked in that order — matching callOllamaCompat's own precedence).
         const resolvedBaseUrl = process.env.OLLAMA_BASE_URL || persistedOllama?.baseUrl;
         const isSelfHosted = !!resolvedBaseUrl && !/^https:\/\/ollama\.com\/?$/i.test(resolvedBaseUrl);
+        // The persisted baseUrl comes from project config, which a cloned repo
+        // can commit. Never hand the environment's OLLAMA_API_KEY to an endpoint
+        // the project chose: that endpoint gets only the key saved beside it (or
+        // none). The env key goes to OLLAMA_BASE_URL, or to Ollama Cloud itself.
+        const baseFromProject = !process.env.OLLAMA_BASE_URL && !!persistedOllama?.baseUrl && isSelfHosted;
+        const apiKey = baseFromProject
+            ? persistedOllama?.apiKey || 'local'
+            : ollamaKey || persistedOllama?.apiKey || 'local';
         if (ollamaKey || persistedOllama?.apiKey || isSelfHosted) {
             return callOllamaCompat({
                 ...input,
-                apiKey: ollamaKey || persistedOllama?.apiKey || 'local',
+                apiKey,
                 baseUrl: resolvedBaseUrl,
                 model: input.model,
                 // Local default for tier aliases / Anthropic ids (see

package/dist/src/mcp-tools/agent-tools.d.ts

@@ -5,5 +5,18 @@
  * Includes model routing integration for intelligent model selection.
  */
 import { type MCPTool } from './types.js';
+/** Live canonical registry members, excluding stale or duplicate swarm IDs. */
+export declare function getLiveAgentIds(agentIds: string[]): string[];
+export declare const AGENT_STATUSES: readonly ["idle", "busy", "terminated"];
+type AgentLifecycleStatus = (typeof AGENT_STATUSES)[number];
+/** Canonical lifecycle status (trimmed, any case, known aliases), or null. */
+export declare function agentStatusOf(value: unknown): AgentLifecycleStatus | null;
+/**
+ * Statuses `agent_list` should keep. `null` means no status filter:
+ * omitted, empty, whitespace, or `all` (any case, including inside a comma list).
+ * The caller still hides terminated agents unless includeTerminated is set.
+ */
+export declare function agentListStatusFilter(status: unknown): string[] | null;
 export declare const agentTools: MCPTool[];
+export {};
 //# sourceMappingURL=agent-tools.d.ts.map

package/dist/src/mcp-tools/agent-tools.js

@@ -36,6 +36,11 @@ function ensureAgentDir() {
 function loadAgentStore() {
     return readRecordStore(getAgentPath(), 'agents', () => ({ agents: {}, version: '3.0.0' }));
 }
+/** Live canonical registry members, excluding stale or duplicate swarm IDs. */
+export function getLiveAgentIds(agentIds) {
+    const { agents } = loadAgentStore();
+    return [...new Set(agentIds)].filter(id => agents[id] && agents[id].status !== 'terminated');
+}
 function saveAgentStore(store) {
     ensureAgentDir();
     writeFileSync(getAgentPath(), JSON.stringify(store, null, 2), 'utf-8');
@@ -67,6 +72,40 @@ function loadHiveAgents() {
 function loadAllAgents() {
     return Object.assign(nullPrototypeRecords(undefined), loadHiveAgents(), loadAgentStore().agents);
 }
+export const AGENT_STATUSES = ['idle', 'busy', 'terminated'];
+// Spellings callers write for the three stored states. v2 `agent/list` used
+// "active" for a working agent; hive liveness folds running/working into busy.
+const AGENT_STATUS_ALIASES = {
+    active: 'busy', running: 'busy', working: 'busy',
+    ready: 'idle', waiting: 'idle',
+    stopped: 'terminated', inactive: 'terminated', offline: 'terminated',
+};
+/** Canonical lifecycle status (trimmed, any case, known aliases), or null. */
+export function agentStatusOf(value) {
+    if (typeof value !== 'string')
+        return null;
+    const key = value.trim().toLowerCase();
+    if (AGENT_STATUSES.includes(key))
+        return key;
+    return Object.hasOwn(AGENT_STATUS_ALIASES, key) ? AGENT_STATUS_ALIASES[key] : null;
+}
+/**
+ * Statuses `agent_list` should keep. `null` means no status filter:
+ * omitted, empty, whitespace, or `all` (any case, including inside a comma list).
+ * The caller still hides terminated agents unless includeTerminated is set.
+ */
+export function agentListStatusFilter(status) {
+    if (typeof status !== 'string' || status.trim() === '')
+        return null;
+    const canonical = status.split(',').map(part => part.trim()).filter(Boolean).map(part => {
+        if (part.toLowerCase() === 'all')
+            return 'all';
+        return agentStatusOf(part) ?? part.toLowerCase();
+    });
+    if (canonical.length === 0 || canonical.includes('all'))
+        return null;
+    return canonical;
+}
 // Default model mappings for agent types (can be overridden)
 const AGENT_TYPE_MODEL_DEFAULTS = {
     // Complex agents → opus
@@ -568,17 +607,24 @@ export const agentTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                status: { type: 'string', description: 'Filter by status' },
+                status: { type: 'string', description: 'Filter by status (idle, busy, terminated; case-insensitive, aliases such as active/running/stopped). "all" or empty applies no status filter. Comma-separated values match any of them.' },
                 domain: { type: 'string', description: 'Filter by domain' },
                 agentType: { type: 'string', description: 'Filter by agent type' },
                 includeTerminated: { type: 'boolean', description: 'Include terminated agents' },
             },
         },
         handler: async (input) => {
-            if (input.status) {
-                const v = validateIdentifier(input.status, 'status');
-                if (!v.valid)
-                    return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+            // Validate each status token. Commas separate values (`active,idle`);
+            // the whole string is not one identifier.
+            if (typeof input.status === 'string' && input.status.trim() !== '') {
+                for (const part of input.status.split(',')) {
+                    const token = part.trim();
+                    if (!token || token.toLowerCase() === 'all')
+                        continue;
+                    const v = validateIdentifier(token, 'status');
+                    if (!v.valid)
+                        return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+                }
             }
             if (input.domain) {
                 const v = validateIdentifier(input.domain, 'domain');
@@ -591,9 +637,14 @@ export const agentTools = [
                     return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
             }
             let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
-            // Filter by status
-            if (input.status) {
-                agents = agents.filter(a => a.status === input.status);
+            // Filter by status. `all` and empty mean no status filter (#4732),
+            // matching task_list: comma-separated, case-insensitive, known aliases.
+            const statuses = agentListStatusFilter(input.status);
+            if (statuses) {
+                agents = agents.filter(a => {
+                    const stored = agentStatusOf(a.status) ?? String(a.status).trim().toLowerCase();
+                    return statuses.includes(stored);
+                });
             }
             else if (!input.includeTerminated) {
                 agents = agents.filter(a => a.status !== 'terminated');

package/dist/src/mcp-tools/agentdb-tools.js

@@ -1502,6 +1502,8 @@ export const agentdbGraphPathfinder = {
             }
             const edges = rawEdges;
             let paths = [];
+            let mincutInfo;
+            let approximation;
             // Check millisecond budget before heavy computation
             if (Date.now() - t0 > budget.maxMillis) {
                 return { success: true, paths: [], count: 0, message: `complexityBudget.maxMillis (${budget.maxMillis}ms) exceeded before solver dispatch`, seedNodeId, algorithm, elapsedMs: Date.now() - t0 };
@@ -1557,10 +1559,38 @@ export const agentdbGraphPathfinder = {
                     paths = witnessChain.slice(0, topK);
                     break;
                 }
+                case 'dynamic-mincut': {
+                    // Exact minimum cut of the seed's depth-hop neighbourhood: the
+                    // weakest boundary around the seed, and the nodes on its side of it.
+                    // Wasm solver via ruvector (@ruvector/mincut-wasm), JS Stoer-Wagner
+                    // fallback for small neighbourhoods.
+                    const edgeTuples = edges.map(r => [String(r[0]), String(r[1]), Number(r[2]) || 1.0]);
+                    const { seedLocalMinCut } = await import('../ruvector/mincut-bridge.js');
+                    const { fallbackMinCut } = await import('../ruvector/graph-analyzer.js');
+                    const cut = await seedLocalMinCut(seedNodeId, edgeTuples, depth, budget.maxNodesVisited, fallbackMinCut);
+                    if (!cut) {
+                        mincutInfo = { backend: 'none', message: 'seed neighbourhood too large for the JS fallback and the wasm solver is unavailable (install ruvector)' };
+                        break;
+                    }
+                    paths = cut.seedSide
+                        .map(r => ({ nodeId: r.nodeId, score: 1 / (1 + r.depth), depth: r.depth }))
+                        .filter(r => r.score >= threshold)
+                        .slice(0, topK);
+                    mincutInfo = {
+                        backend: cut.backend,
+                        cutValue: cut.cutValue,
+                        seedSideSize: cut.seedSide.length + 1,
+                        otherSideSize: cut.otherSide.length,
+                        subgraphNodes: cut.subgraphNodes,
+                        cutEdges: cut.cutEdges.slice(0, 50),
+                    };
+                    break;
+                }
                 case 'connected-component-churn':
-                case 'dynamic-mincut':
                 case 'spectral-sparsify': {
-                    // Simplified implementations: return k-hop neighbors with basic score
+                    // Not implemented natively yet: approximated by k-hop neighbours with
+                    // a rank-decay score. The response says so via `implementation`.
+                    approximation = 'k-hop';
                     const edgeTuples = edges.map(r => [r[0], r[1], Number(r[2]) || 1.0]);
                     const khopResult = await agentdbGraphQuery.handler({
                         nodeId: seedNodeId, mode: 'k-hop', depth, complexityBudget: budget,
@@ -1582,6 +1612,8 @@ export const agentdbGraphPathfinder = {
                 count: paths.length,
                 elapsedMs,
                 budgetUsed: { millis: elapsedMs, nodes: rawEdges.length },
+                ...(mincutInfo && { mincut: mincutInfo }),
+                ...(approximation && { implementation: `${approximation} approximation` }),
                 ...(depthWarning && { warning: depthWarning }),
             };
         }

package/dist/src/mcp-tools/browser-argv.d.ts

@@ -15,4 +15,13 @@ export declare function launchArgsError(value: unknown): string | null;
  * pass — for example a selector or typed text of "--executable-path".
  */
 export declare function commandArgvError(args: readonly string[]): string | null;
+/**
+ * Returns an error when a navigation target is not a web page. The browser
+ * tools return page text to the caller, so a `file:` URL (or `view-source:`,
+ * `chrome:`, `data:` and the like) would read local files or browser state
+ * that `http_fetch` never serves. Only http(s) URLs, `about:blank`, and
+ * scheme-less targets such as `example.com/path` or `localhost:3000` (which
+ * agent-browser opens over http(s)) are accepted.
+ */
+export declare function browserUrlError(value: unknown): string | null;
 //# sourceMappingURL=browser-argv.d.ts.map

package/dist/src/mcp-tools/browser-argv.js

@@ -42,6 +42,11 @@ export function launchArgsError(value) {
  * pass — for example a selector or typed text of "--executable-path".
  */
 export function commandArgvError(args) {
+    if (args[0] === 'open') {
+        const urlError = browserUrlError(args[1]);
+        if (urlError)
+            return urlError;
+    }
     for (const arg of args) {
         if (typeof arg !== 'string')
             return 'browser command arguments must be strings';
@@ -56,4 +61,32 @@ export function commandArgvError(args) {
     }
     return null;
 }
+/**
+ * Returns an error when a navigation target is not a web page. The browser
+ * tools return page text to the caller, so a `file:` URL (or `view-source:`,
+ * `chrome:`, `data:` and the like) would read local files or browser state
+ * that `http_fetch` never serves. Only http(s) URLs, `about:blank`, and
+ * scheme-less targets such as `example.com/path` or `localhost:3000` (which
+ * agent-browser opens over http(s)) are accepted.
+ */
+export function browserUrlError(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return 'url must be a non-empty string';
+    // Chromium drops tabs and newlines anywhere in a URL and trims leading
+    // control characters and spaces, so check what it would actually parse.
+    const url = value.replace(/[\t\n\r]/g, '').replace(/^[\u0000- ]+/, '');
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url);
+    if (!scheme)
+        return null;
+    const name = scheme[1].toLowerCase();
+    if (name === 'http' || name === 'https')
+        return null;
+    if (url.toLowerCase() === 'about:blank')
+        return null;
+    // `host:port` with no scheme, e.g. `localhost:3000/app`. The host must be
+    // `localhost` or contain a dot, so `file:1/...` is not mistaken for one.
+    if ((name === 'localhost' || name.includes('.')) && /^[a-z0-9.-]+:\d{1,5}(?:[/?#]|$)/i.test(url))
+        return null;
+    return `url scheme not allowed: ${JSON.stringify(name.slice(0, 40))} (use http or https)`;
+}
 //# sourceMappingURL=browser-argv.js.map

package/dist/src/mcp-tools/browser-session-tools.js

@@ -22,6 +22,7 @@
  *     rather than a process crash.
  */
 import { validateIdentifier, validateText } from './validate-input.js';
+import { browserUrlError } from './browser-argv.js';
 // Pin matches the version in this package's own dependency tree so the npx
 // fallback never downloads a second ruvector. Subcommand surface verified
 // against ruvector@0.2.27 --help: `rvf create/compact/status/derive/segments`
@@ -144,6 +145,9 @@ export const browserSessionTools = [
             const vUrl = validateText(input.url, 'url');
             if (!vUrl.valid)
                 return fail(vUrl.error || 'invalid url');
+            const urlError = browserUrlError(input.url);
+            if (urlError)
+                return fail(urlError);
             const vTask = validateText(input.task, 'task');
             if (!vTask.valid)
                 return fail(vTask.error || 'invalid task');

package/dist/src/mcp-tools/browser-tools.js

@@ -8,6 +8,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { validateIdentifier, validateText } from './validate-input.js';
 import { resolveAgentBrowserLaunch, resolveNpxLaunch } from '../runtime/browser-command.js';
 import { commandArgvError, launchArgsError } from './browser-argv.js';
+import { containedWritePath } from './path-containment.js';
+const SCREENSHOT_EXTENSIONS = ['.png', '.jpg', '.jpeg'];
 // Session registry for multi-session support
 const browserSessions = new Map();
 /** Preserve agent-browser's JSON error on non-zero exit without echoing other process output. */
@@ -324,8 +326,16 @@ export const browserTools = [
             }
             const { session, path, fullPage } = input;
             const args = ['screenshot'];
-            if (path)
-                args.push(path);
+            if (path) {
+                // The browser writes the image wherever it is told and replaces what
+                // is there, so a caller-named path must stay inside the project.
+                const target = containedWritePath(path, SCREENSHOT_EXTENSIONS);
+                if (!target) {
+                    const error = `path must be a new or regular file inside the project ending in ${SCREENSHOT_EXTENSIONS.join(', ')}`;
+                    return { content: [{ type: 'text', text: JSON.stringify({ success: false, error }) }], isError: true };
+                }
+                args.push(target);
+            }
             if (fullPage)
                 args.push('--full');
             return execBrowserCommand(args, session);

package/dist/src/mcp-tools/coordination-tools.js

@@ -346,11 +346,12 @@ export const coordinationTools = [
             }
             if (action === 'heartbeat') {
                 const nodeId = input.nodeId;
-                if (store.nodes[nodeId]) {
-                    store.nodes[nodeId].lastHeartbeat = new Date().toISOString();
-                    store.nodes[nodeId].status = 'active';
-                    saveCoordStore(store);
+                if (!store.nodes[nodeId]) {
+                    return { success: false, error: 'Node not found' };
                 }
+                store.nodes[nodeId].lastHeartbeat = new Date().toISOString();
+                store.nodes[nodeId].status = 'active';
+                saveCoordStore(store);
                 return {
                     success: true,
                     action: 'heartbeat',

package/dist/src/mcp-tools/embeddings-tools.js

@@ -50,11 +50,14 @@ async function getRealEmbeddingFunction() {
     }
     return realEmbeddingFn;
 }
-async function generateRealEmbedding(text, dimension) {
+async function generateRealEmbedding(text, dimension, normalize = true) {
     const realFn = await getRealEmbeddingFunction();
     if (realFn) {
         try {
-            const result = await realFn(text);
+            // Default callers stay a single-argument call so existing mocks and
+            // the unit-norm path are unchanged. Only an explicit opt-out asks the
+            // generator for the pre-L2 vector.
+            const result = normalize ? await realFn(text) : await realFn(text, { normalize: false });
             return {
                 embedding: result.embedding,
                 backend: result.backend ?? 'onnx',
@@ -76,7 +79,10 @@ async function generateRealEmbedding(text, dimension) {
         const seed = hash + i * 1337;
         embedding.push(Math.sin(seed) * Math.cos(seed * 0.5));
     }
-    // L2 normalize
+    // L2 normalize unless the caller opted out (#4724).
+    if (!normalize) {
+        return { embedding, backend: 'mock', model: 'hash-fallback' };
+    }
     const norm = Math.sqrt(embedding.reduce((sum, x) => sum + x * x, 0));
     return {
         embedding: embedding.map(x => x / norm),
@@ -256,8 +262,10 @@ export const embeddingsTools = [
                     return { success: false, error: v.error };
             }
             const useHyperbolic = input.hyperbolic === true && config.hyperbolic.enabled;
+            // Default true: omitted and explicit true keep the historical unit vector.
+            const shouldNormalize = input.normalize !== false;
             // Generate real ONNX embedding
-            const generated = await generateRealEmbedding(text, config.dimension);
+            const generated = await generateRealEmbedding(text, config.dimension, shouldNormalize);
             const embedding = generated.embedding;
             let result;
             let geometry;