claude-flow 3.71.3 → 3.72.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/.claude/helpers/auto-memory-hook.mjs +17 -0
  2. package/.claude/helpers/hook-handler.cjs +23 -10
  3. package/.claude/helpers/intelligence.cjs +23 -1
  4. package/.claude/helpers/statusline.cjs +29 -14
  5. package/.claude/proven-config.json +1 -1
  6. package/README.md +18 -3
  7. package/README.zh-CN.md +16 -3
  8. package/package.json +1 -1
  9. package/v3/@claude-flow/cli/README.md +18 -3
  10. package/v3/@claude-flow/cli/bin/cli.js +13 -18
  11. package/v3/@claude-flow/cli/bin/mcp-server.js +13 -18
  12. package/v3/@claude-flow/cli/catalog-manifest.json +2 -2
  13. package/v3/@claude-flow/cli/dist/src/appliance/rvfa-distribution.js +2 -2
  14. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-critic.d.ts +1 -7
  15. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-critic.js +1 -7
  16. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-decomposer.d.ts +1 -8
  17. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-decomposer.js +1 -8
  18. package/v3/@claude-flow/cli/dist/src/commands/agent-wasm.js +2 -2
  19. package/v3/@claude-flow/cli/dist/src/commands/analyze.js +1 -1
  20. package/v3/@claude-flow/cli/dist/src/commands/daemon.js +1 -1
  21. package/v3/@claude-flow/cli/dist/src/commands/doctor.js +3 -2
  22. package/v3/@claude-flow/cli/dist/src/commands/guidance.js +9 -9
  23. package/v3/@claude-flow/cli/dist/src/commands/hooks.js +13 -8
  24. package/v3/@claude-flow/cli/dist/src/commands/init.js +14 -16
  25. package/v3/@claude-flow/cli/dist/src/commands/memory.js +4 -3
  26. package/v3/@claude-flow/cli/dist/src/commands/neural.js +8 -6
  27. package/v3/@claude-flow/cli/dist/src/commands/route.js +1 -1
  28. package/v3/@claude-flow/cli/dist/src/commands/ruvector/backup.js +7 -5
  29. package/v3/@claude-flow/cli/dist/src/commands/ruvector/benchmark.js +6 -1
  30. package/v3/@claude-flow/cli/dist/src/commands/ruvector/import.js +19 -5
  31. package/v3/@claude-flow/cli/dist/src/commands/ruvector/init.js +1 -1
  32. package/v3/@claude-flow/cli/dist/src/commands/start.js +1 -1
  33. package/v3/@claude-flow/cli/dist/src/commands/status.js +1 -1
  34. package/v3/@claude-flow/cli/dist/src/commands/task.js +18 -1
  35. package/v3/@claude-flow/cli/dist/src/commands/update.js +1 -1
  36. package/v3/@claude-flow/cli/dist/src/funnel/local-signals.js +7 -2
  37. package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js +16 -1
  38. package/v3/@claude-flow/cli/dist/src/mcp-protocol.d.ts +90 -0
  39. package/v3/@claude-flow/cli/dist/src/mcp-protocol.js +179 -0
  40. package/v3/@claude-flow/cli/dist/src/mcp-server.d.ts +1 -0
  41. package/v3/@claude-flow/cli/dist/src/mcp-server.js +20 -22
  42. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js +9 -1
  43. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.d.ts +13 -0
  44. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js +63 -12
  45. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-federation.d.ts +18 -1
  46. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-federation.js +23 -7
  47. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-argv.d.ts +27 -0
  48. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-argv.js +92 -0
  49. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-session-tools.js +4 -0
  50. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-tools.d.ts +1 -1
  51. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-tools.js +25 -8
  52. package/v3/@claude-flow/cli/dist/src/mcp-tools/coordination-tools.js +5 -4
  53. package/v3/@claude-flow/cli/dist/src/mcp-tools/embeddings-tools.js +12 -4
  54. package/v3/@claude-flow/cli/dist/src/mcp-tools/glob-exclusions.d.ts +6 -0
  55. package/v3/@claude-flow/cli/dist/src/mcp-tools/glob-exclusions.js +81 -0
  56. package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js +104 -35
  57. package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js +12 -5
  58. package/v3/@claude-flow/cli/dist/src/mcp-tools/import-limits.d.ts +4 -0
  59. package/v3/@claude-flow/cli/dist/src/mcp-tools/import-limits.js +28 -0
  60. package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js +68 -72
  61. package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js +8 -2
  62. package/v3/@claude-flow/cli/dist/src/mcp-tools/path-containment.d.ts +34 -0
  63. package/v3/@claude-flow/cli/dist/src/mcp-tools/path-containment.js +133 -0
  64. package/v3/@claude-flow/cli/dist/src/mcp-tools/performance-tools.js +7 -2
  65. package/v3/@claude-flow/cli/dist/src/mcp-tools/record-store.d.ts +15 -0
  66. package/v3/@claude-flow/cli/dist/src/mcp-tools/record-store.js +117 -3
  67. package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.d.ts +9 -0
  68. package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.js +39 -3
  69. package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js +9 -41
  70. package/v3/@claude-flow/cli/dist/src/mcp-tools/swarm-tools.js +36 -14
  71. package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js +68 -5
  72. package/v3/@claude-flow/cli/dist/src/mcp-tools/terminal-tools.js +16 -2
  73. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.d.ts +2 -0
  74. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.js +14 -0
  75. package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js +13 -12
  76. package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-join.js +55 -14
  77. package/v3/@claude-flow/cli/dist/src/memory/intelligence.d.ts +11 -0
  78. package/v3/@claude-flow/cli/dist/src/memory/intelligence.js +84 -6
  79. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts +6 -2
  80. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js +15 -6
  81. package/v3/@claude-flow/cli/dist/src/ruvector/model-router.d.ts +6 -1
  82. package/v3/@claude-flow/cli/dist/src/ruvector/model-router.js +16 -4
  83. package/v3/@claude-flow/cli/dist/src/services/worker-daemon.js +30 -12
  84. package/v3/@claude-flow/cli/dist/src/transfer/storage/gcs.js +3 -2
  85. package/v3/@claude-flow/cli/package.json +1 -1
  86. package/.claude/security-scans/scan-all-quick.json +0 -201
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
8
8
  import { join } from 'node:path';
9
- import { readRecordStore } from './record-store.js';
9
+ import { nullPrototypeRecords, readRecordStore } from './record-store.js';
10
10
  import { getProjectCwd } from './types.js';
11
11
  import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';
12
12
  import { executeAgentTask } from './agent-execute-core.js';
@@ -36,6 +36,11 @@ function ensureAgentDir() {
36
36
  function loadAgentStore() {
37
37
  return readRecordStore(getAgentPath(), 'agents', () => ({ agents: {}, version: '3.0.0' }));
38
38
  }
39
+ /** Live canonical registry members, excluding stale or duplicate swarm IDs. */
40
+ export function getLiveAgentIds(agentIds) {
41
+ const { agents } = loadAgentStore();
42
+ return [...new Set(agentIds)].filter(id => agents[id] && agents[id].status !== 'terminated');
43
+ }
39
44
  function saveAgentStore(store) {
40
45
  ensureAgentDir();
41
46
  writeFileSync(getAgentPath(), JSON.stringify(store, null, 2), 'utf-8');
@@ -50,14 +55,14 @@ function loadHiveAgents() {
50
55
  if (existsSync(path)) {
51
56
  const data = JSON.parse(readFileSync(path, 'utf-8'));
52
57
  if (data && typeof data.agents === 'object' && data.agents) {
53
- return data.agents;
58
+ return nullPrototypeRecords(data.agents);
54
59
  }
55
60
  }
56
61
  }
57
62
  catch {
58
63
  // Ignore — hive store is optional/best-effort.
59
64
  }
60
- return {};
65
+ return nullPrototypeRecords(undefined);
61
66
  }
62
67
  /**
63
68
  * #1916: merged view of every tracked agent — the canonical agent store
@@ -65,7 +70,41 @@ function loadHiveAgents() {
65
70
  * wins (it carries model-routing + lastResult that the hive store omits).
66
71
  */
67
72
  function loadAllAgents() {
68
- return { ...loadHiveAgents(), ...loadAgentStore().agents };
73
+ return Object.assign(nullPrototypeRecords(undefined), loadHiveAgents(), loadAgentStore().agents);
74
+ }
75
+ export const AGENT_STATUSES = ['idle', 'busy', 'terminated'];
76
+ // Spellings callers write for the three stored states. v2 `agent/list` used
77
+ // "active" for a working agent; hive liveness folds running/working into busy.
78
+ const AGENT_STATUS_ALIASES = {
79
+ active: 'busy', running: 'busy', working: 'busy',
80
+ ready: 'idle', waiting: 'idle',
81
+ stopped: 'terminated', inactive: 'terminated', offline: 'terminated',
82
+ };
83
+ /** Canonical lifecycle status (trimmed, any case, known aliases), or null. */
84
+ export function agentStatusOf(value) {
85
+ if (typeof value !== 'string')
86
+ return null;
87
+ const key = value.trim().toLowerCase();
88
+ if (AGENT_STATUSES.includes(key))
89
+ return key;
90
+ return Object.hasOwn(AGENT_STATUS_ALIASES, key) ? AGENT_STATUS_ALIASES[key] : null;
91
+ }
92
+ /**
93
+ * Statuses `agent_list` should keep. `null` means no status filter:
94
+ * omitted, empty, whitespace, or `all` (any case, including inside a comma list).
95
+ * The caller still hides terminated agents unless includeTerminated is set.
96
+ */
97
+ export function agentListStatusFilter(status) {
98
+ if (typeof status !== 'string' || status.trim() === '')
99
+ return null;
100
+ const canonical = status.split(',').map(part => part.trim()).filter(Boolean).map(part => {
101
+ if (part.toLowerCase() === 'all')
102
+ return 'all';
103
+ return agentStatusOf(part) ?? part.toLowerCase();
104
+ });
105
+ if (canonical.length === 0 || canonical.includes('all'))
106
+ return null;
107
+ return canonical;
69
108
  }
70
109
  // Default model mappings for agent types (can be overridden)
71
110
  const AGENT_TYPE_MODEL_DEFAULTS = {
@@ -568,17 +607,24 @@ export const agentTools = [
568
607
  inputSchema: {
569
608
  type: 'object',
570
609
  properties: {
571
- status: { type: 'string', description: 'Filter by status' },
610
+ 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.' },
572
611
  domain: { type: 'string', description: 'Filter by domain' },
573
612
  agentType: { type: 'string', description: 'Filter by agent type' },
574
613
  includeTerminated: { type: 'boolean', description: 'Include terminated agents' },
575
614
  },
576
615
  },
577
616
  handler: async (input) => {
578
- if (input.status) {
579
- const v = validateIdentifier(input.status, 'status');
580
- if (!v.valid)
581
- return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
617
+ // Validate each status token. Commas separate values (`active,idle`);
618
+ // the whole string is not one identifier.
619
+ if (typeof input.status === 'string' && input.status.trim() !== '') {
620
+ for (const part of input.status.split(',')) {
621
+ const token = part.trim();
622
+ if (!token || token.toLowerCase() === 'all')
623
+ continue;
624
+ const v = validateIdentifier(token, 'status');
625
+ if (!v.valid)
626
+ return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
627
+ }
582
628
  }
583
629
  if (input.domain) {
584
630
  const v = validateIdentifier(input.domain, 'domain');
@@ -591,9 +637,14 @@ export const agentTools = [
591
637
  return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
592
638
  }
593
639
  let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
594
- // Filter by status
595
- if (input.status) {
596
- agents = agents.filter(a => a.status === input.status);
640
+ // Filter by status. `all` and empty mean no status filter (#4732),
641
+ // matching task_list: comma-separated, case-insensitive, known aliases.
642
+ const statuses = agentListStatusFilter(input.status);
643
+ if (statuses) {
644
+ agents = agents.filter(a => {
645
+ const stored = agentStatusOf(a.status) ?? String(a.status).trim().toLowerCase();
646
+ return statuses.includes(stored);
647
+ });
597
648
  }
598
649
  else if (!input.includeTerminated) {
599
650
  agents = agents.filter(a => a.status !== 'terminated');
@@ -143,6 +143,20 @@ export interface MergeResult {
143
143
  skippedUnverified: number;
144
144
  skippedOversize: number;
145
145
  skippedHopLimit: number;
146
+ /** Envelopes whose `origin` names a node the signature does not belong to. */
147
+ skippedForeignOrigin: number;
148
+ /** Highest `seq` among envelopes merged or already held; the next sync starts after it. */
149
+ acceptedMaxSeq: number;
150
+ }
151
+ /**
152
+ * Who may have signed an envelope. `origin` is inside the signature, but a
153
+ * signature only proves which key signed, not which node the envelope names.
154
+ * An envelope is accepted only when its origin is the syncing peer itself or
155
+ * another pinned peer, and it verifies against that origin's pinned key.
156
+ */
157
+ export interface OriginKeys {
158
+ peerNodeId: string;
159
+ pinned: ReadonlyMap<string, string>;
146
160
  }
147
161
  /**
148
162
  * Union-merge verified envelopes from a peer into the local room log.
@@ -150,8 +164,11 @@ export interface MergeResult {
150
164
  * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
151
165
  * no-op. Anything that fails verification is dropped and counted rather than
152
166
  * quarantined — a receiver has no use for an envelope it cannot attribute.
167
+ *
168
+ * `hops` is not signed (relays change it), so it only limits propagation and
169
+ * is never trusted for anything else.
153
170
  */
154
- export declare function mergeEnvelopes(basePath: string, roomId: string, incoming: SignedEnvelope[], peerPublicKey: string): Promise<MergeResult>;
171
+ export declare function mergeEnvelopes(basePath: string, roomId: string, incoming: SignedEnvelope[], peerPublicKey: string, origins?: OriginKeys): Promise<MergeResult>;
155
172
  /** Pull one room from one peer and merge what verifies. */
156
173
  export declare function syncRoomFromPeer(basePath: string, peer: FederationPeer, roomId: string, fetchImpl?: typeof fetch): Promise<MergeResult & {
157
174
  peerNodeId: string;
@@ -315,15 +315,19 @@ export function validateRoomId(roomId) {
315
315
  * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
316
316
  * no-op. Anything that fails verification is dropped and counted rather than
317
317
  * quarantined — a receiver has no use for an envelope it cannot attribute.
318
+ *
319
+ * `hops` is not signed (relays change it), so it only limits propagation and
320
+ * is never trusted for anything else.
318
321
  */
319
- export async function mergeEnvelopes(basePath, roomId, incoming, peerPublicKey) {
322
+ export async function mergeEnvelopes(basePath, roomId, incoming, peerPublicKey, origins) {
320
323
  validateRoomId(roomId);
321
324
  ensureDir(basePath);
322
325
  const result = {
323
326
  merged: 0, skippedDuplicate: 0, skippedUnverified: 0, skippedOversize: 0, skippedHopLimit: 0,
327
+ skippedForeignOrigin: 0, acceptedMaxSeq: 0,
324
328
  };
325
329
  const existing = readEnvelopes(basePath, roomId);
326
- const seen = new Set(existing.map(e => e.envelopeId));
330
+ const seen = new Map(existing.map(e => [e.envelopeId, Number(e.seq) || 0]));
327
331
  const logPath = roomLogPath(basePath, roomId);
328
332
  const batch = incoming.slice(0, MAX_ENVELOPES_PER_SYNC);
329
333
  for (const env of batch) {
@@ -337,6 +341,7 @@ export async function mergeEnvelopes(basePath, roomId, incoming, peerPublicKey)
337
341
  }
338
342
  if (seen.has(env.envelopeId)) {
339
343
  result.skippedDuplicate++;
344
+ result.acceptedMaxSeq = Math.max(result.acceptedMaxSeq, seen.get(env.envelopeId) ?? 0);
340
345
  continue;
341
346
  }
342
347
  if (JSON.stringify(env).length > MAX_ENVELOPE_BYTES) {
@@ -347,12 +352,22 @@ export async function mergeEnvelopes(basePath, roomId, incoming, peerPublicKey)
347
352
  result.skippedHopLimit++;
348
353
  continue;
349
354
  }
350
- if (!(await verifyEnvelope(env, peerPublicKey))) {
355
+ let signerKey = peerPublicKey;
356
+ if (origins) {
357
+ const key = env.origin === origins.peerNodeId ? peerPublicKey : typeof env.origin === 'string' ? origins.pinned.get(env.origin) : undefined;
358
+ if (!key) {
359
+ result.skippedForeignOrigin++;
360
+ continue;
361
+ }
362
+ signerKey = key;
363
+ }
364
+ if (!(await verifyEnvelope(env, signerKey))) {
351
365
  result.skippedUnverified++;
352
366
  continue;
353
367
  }
354
368
  appendFileSync(logPath, JSON.stringify({ ...env, hops: (env.hops ?? 0) + 1 }) + '\n');
355
- seen.add(env.envelopeId);
369
+ seen.set(env.envelopeId, Number(env.seq) || 0);
370
+ result.acceptedMaxSeq = Math.max(result.acceptedMaxSeq, Number(env.seq) || 0);
356
371
  result.merged++;
357
372
  }
358
373
  return result;
@@ -378,14 +393,15 @@ export async function syncRoomFromPeer(basePath, peer, roomId, fetchImpl = fetch
378
393
  clearTimeout(timer);
379
394
  }
380
395
  const envelopes = Array.isArray(body?.envelopes) ? body.envelopes : [];
381
- const merged = await mergeEnvelopes(basePath, roomId, envelopes, peer.publicKey);
382
396
  const peers = readPeers(basePath);
397
+ const pinned = new Map(peers.filter(p => typeof p.publicKey === 'string').map(p => [p.nodeId, p.publicKey]));
398
+ const merged = await mergeEnvelopes(basePath, roomId, envelopes, peer.publicKey, { peerNodeId: peer.nodeId, pinned });
383
399
  const rec = peers.find(p => p.nodeId === peer.nodeId);
384
400
  if (rec) {
385
401
  rec.lastSyncedAt = new Date().toISOString();
386
402
  rec.lastSeq = rec.lastSeq ?? {};
387
- const maxSeq = envelopes.reduce((m, e) => Math.max(m, Number(e.seq) || 0), since);
388
- rec.lastSeq[roomId] = maxSeq;
403
+ // Advance only past envelopes that verified; an unverifiable batch must not skip the cursor forward.
404
+ rec.lastSeq[roomId] = Math.max(since, merged.acceptedMaxSeq);
389
405
  writePeers(basePath, peers);
390
406
  }
391
407
  return { ...merged, peerNodeId: peer.nodeId, roomId };
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Argument checks for the agent-browser bridge.
3
+ *
4
+ * agent-browser reads its own options anywhere in argv, and forwards `--args`
5
+ * to the Chromium it launches. Both are reachable from MCP tool input, so
6
+ * caller text must never be able to add an option, and launch flags are
7
+ * limited to a fixed list of plain switches.
8
+ */
9
+ /** Chromium launch switches a caller may request. Exact matches only; none takes a value. */
10
+ export declare const ALLOWED_LAUNCH_ARGS: ReadonlySet<string>;
11
+ /** Returns an error when a launch-flag list contains anything outside the allowlist. */
12
+ export declare function launchArgsError(value: unknown): string | null;
13
+ /**
14
+ * Returns an error when argv contains an option the tools did not mean to
15
+ * pass — for example a selector or typed text of "--executable-path".
16
+ */
17
+ export declare function commandArgvError(args: readonly string[]): string | null;
18
+ /**
19
+ * Returns an error when a navigation target is not a web page. The browser
20
+ * tools return page text to the caller, so a `file:` URL (or `view-source:`,
21
+ * `chrome:`, `data:` and the like) would read local files or browser state
22
+ * that `http_fetch` never serves. Only http(s) URLs, `about:blank`, and
23
+ * scheme-less targets such as `example.com/path` or `localhost:3000` (which
24
+ * agent-browser opens over http(s)) are accepted.
25
+ */
26
+ export declare function browserUrlError(value: unknown): string | null;
27
+ //# sourceMappingURL=browser-argv.d.ts.map
@@ -0,0 +1,92 @@
1
+ /**
2
+ * Argument checks for the agent-browser bridge.
3
+ *
4
+ * agent-browser reads its own options anywhere in argv, and forwards `--args`
5
+ * to the Chromium it launches. Both are reachable from MCP tool input, so
6
+ * caller text must never be able to add an option, and launch flags are
7
+ * limited to a fixed list of plain switches.
8
+ */
9
+ /** Chromium launch switches a caller may request. Exact matches only; none takes a value. */
10
+ export const ALLOWED_LAUNCH_ARGS = new Set([
11
+ '--no-sandbox',
12
+ '--disable-setuid-sandbox',
13
+ '--disable-gpu',
14
+ '--disable-dev-shm-usage',
15
+ '--disable-extensions',
16
+ '--mute-audio',
17
+ '--hide-scrollbars',
18
+ '--incognito',
19
+ ]);
20
+ /** The agent-browser options the browser tools themselves emit after a subcommand. */
21
+ const COMMAND_FLAGS = new Set([
22
+ '--wait-until', '--full', '--button', '--count', '--delay', '--text', '--url',
23
+ '-i', '-c', '-d', '-s',
24
+ ]);
25
+ /** Returns an error when a launch-flag list contains anything outside the allowlist. */
26
+ export function launchArgsError(value) {
27
+ if (value === undefined || value === null)
28
+ return null;
29
+ if (!Array.isArray(value))
30
+ return 'args must be an array of strings';
31
+ for (const arg of value) {
32
+ if (typeof arg !== 'string')
33
+ return 'args must be an array of strings';
34
+ if (!ALLOWED_LAUNCH_ARGS.has(arg)) {
35
+ return `launch arg not allowed: ${JSON.stringify(arg.slice(0, 80))} (allowed: ${[...ALLOWED_LAUNCH_ARGS].join(', ')})`;
36
+ }
37
+ }
38
+ return null;
39
+ }
40
+ /**
41
+ * Returns an error when argv contains an option the tools did not mean to
42
+ * pass — for example a selector or typed text of "--executable-path".
43
+ */
44
+ export function commandArgvError(args) {
45
+ if (args[0] === 'open') {
46
+ const urlError = browserUrlError(args[1]);
47
+ if (urlError)
48
+ return urlError;
49
+ }
50
+ for (const arg of args) {
51
+ if (typeof arg !== 'string')
52
+ return 'browser command arguments must be strings';
53
+ if (arg.startsWith('--')) {
54
+ const name = arg.split('=', 1)[0];
55
+ if (!COMMAND_FLAGS.has(name))
56
+ return `value must not start with "--": ${JSON.stringify(arg.slice(0, 80))}`;
57
+ }
58
+ else if (/^-[A-Za-z]$/.test(arg) && !COMMAND_FLAGS.has(arg)) {
59
+ return `value must not be an option: ${JSON.stringify(arg)}`;
60
+ }
61
+ }
62
+ return null;
63
+ }
64
+ /**
65
+ * Returns an error when a navigation target is not a web page. The browser
66
+ * tools return page text to the caller, so a `file:` URL (or `view-source:`,
67
+ * `chrome:`, `data:` and the like) would read local files or browser state
68
+ * that `http_fetch` never serves. Only http(s) URLs, `about:blank`, and
69
+ * scheme-less targets such as `example.com/path` or `localhost:3000` (which
70
+ * agent-browser opens over http(s)) are accepted.
71
+ */
72
+ export function browserUrlError(value) {
73
+ if (typeof value !== 'string' || !value.trim())
74
+ return 'url must be a non-empty string';
75
+ // Chromium drops tabs and newlines anywhere in a URL and trims leading
76
+ // control characters and spaces, so check what it would actually parse.
77
+ const url = value.replace(/[\t\n\r]/g, '').replace(/^[\u0000- ]+/, '');
78
+ const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url);
79
+ if (!scheme)
80
+ return null;
81
+ const name = scheme[1].toLowerCase();
82
+ if (name === 'http' || name === 'https')
83
+ return null;
84
+ if (url.toLowerCase() === 'about:blank')
85
+ return null;
86
+ // `host:port` with no scheme, e.g. `localhost:3000/app`. The host must be
87
+ // `localhost` or contain a dot, so `file:1/...` is not mistaken for one.
88
+ if ((name === 'localhost' || name.includes('.')) && /^[a-z0-9.-]+:\d{1,5}(?:[/?#]|$)/i.test(url))
89
+ return null;
90
+ return `url scheme not allowed: ${JSON.stringify(name.slice(0, 40))} (use http or https)`;
91
+ }
92
+ //# sourceMappingURL=browser-argv.js.map
@@ -22,6 +22,7 @@
22
22
  * rather than a process crash.
23
23
  */
24
24
  import { validateIdentifier, validateText } from './validate-input.js';
25
+ import { browserUrlError } from './browser-argv.js';
25
26
  // Pin matches the version in this package's own dependency tree so the npx
26
27
  // fallback never downloads a second ruvector. Subcommand surface verified
27
28
  // against ruvector@0.2.27 --help: `rvf create/compact/status/derive/segments`
@@ -144,6 +145,9 @@ export const browserSessionTools = [
144
145
  const vUrl = validateText(input.url, 'url');
145
146
  if (!vUrl.valid)
146
147
  return fail(vUrl.error || 'invalid url');
148
+ const urlError = browserUrlError(input.url);
149
+ if (urlError)
150
+ return fail(urlError);
147
151
  const vTask = validateText(input.task, 'task');
148
152
  if (!vTask.valid)
149
153
  return fail(vTask.error || 'invalid task');
@@ -12,7 +12,7 @@ import type { MCPTool, MCPToolResult } from './types.js';
12
12
  * Exported so browser-intent-tools.ts (ADR-175 `browser_act`) can reuse the same
13
13
  * exec + fallback + session-plumbing instead of duplicating it.
14
14
  */
15
- export declare function execBrowserCommand(args: string[], session?: string): Promise<MCPToolResult>;
15
+ export declare function execBrowserCommand(args: string[], session?: string, launchArgs?: readonly string[]): Promise<MCPToolResult>;
16
16
  /**
17
17
  * Browser MCP Tools
18
18
  */
@@ -7,6 +7,9 @@
7
7
  import { readFileSync, existsSync } from 'node:fs';
8
8
  import { validateIdentifier, validateText } from './validate-input.js';
9
9
  import { resolveAgentBrowserLaunch, resolveNpxLaunch } from '../runtime/browser-command.js';
10
+ import { commandArgvError, launchArgsError } from './browser-argv.js';
11
+ import { containedWritePath } from './path-containment.js';
12
+ const SCREENSHOT_EXTENSIONS = ['.png', '.jpg', '.jpeg'];
10
13
  // Session registry for multi-session support
11
14
  const browserSessions = new Map();
12
15
  /** Preserve agent-browser's JSON error on non-zero exit without echoing other process output. */
@@ -44,9 +47,14 @@ function browserCommandFailure(error, missingExecutable) {
44
47
  * Exported so browser-intent-tools.ts (ADR-175 `browser_act`) can reuse the same
45
48
  * exec + fallback + session-plumbing instead of duplicating it.
46
49
  */
47
- export async function execBrowserCommand(args, session = 'default') {
50
+ export async function execBrowserCommand(args, session = 'default', launchArgs = []) {
51
+ const argvError = commandArgvError(args) ?? launchArgsError(launchArgs);
52
+ if (argvError)
53
+ return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: argvError }) }], isError: true };
48
54
  const { execFileSync } = await import('child_process');
49
55
  const fullArgs = ['--session', session, '--json', ...args];
56
+ if (launchArgs.length > 0)
57
+ fullArgs.push('--args', launchArgs.join(','));
50
58
  // ADR-401: fullArgs carries tool-supplied text (fill values, eval scripts,
51
59
  // selectors), so no spawn here may use a shell. On Windows the npm shims are
52
60
  // resolved to the process behind them instead of enabling `shell: true`,
@@ -147,7 +155,7 @@ export const browserTools = [
147
155
  args: {
148
156
  type: 'array',
149
157
  items: { type: 'string' },
150
- description: 'Additional Chrome launch args (e.g., ["--no-sandbox", "--disable-dev-shm-usage"])',
158
+ description: 'Additional Chrome launch switches. Only these are accepted: --no-sandbox, --disable-setuid-sandbox, --disable-gpu, --disable-dev-shm-usage, --disable-extensions, --mute-audio, --hide-scrollbars, --incognito',
151
159
  },
152
160
  },
153
161
  required: ['url'],
@@ -162,15 +170,16 @@ export const browserTools = [
162
170
  return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: vS.error }) }], isError: true };
163
171
  }
164
172
  const { url, session, waitUntil } = input;
165
- const launchArgs = input.args || [];
173
+ const vArgs = launchArgsError(input.args);
174
+ if (vArgs)
175
+ return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: vArgs }) }], isError: true };
176
+ const launchArgs = [...(input.args || [])];
166
177
  if (needsNoSandbox() && !launchArgs.includes('--no-sandbox')) {
167
178
  launchArgs.push('--no-sandbox');
168
179
  }
169
180
  const args = ['open', url];
170
181
  if (waitUntil)
171
182
  args.push('--wait-until', waitUntil);
172
- if (launchArgs.length > 0)
173
- args.push('--args', launchArgs.join(','));
174
183
  // Create session if new
175
184
  const sessionId = session || 'default';
176
185
  if (!browserSessions.has(sessionId)) {
@@ -180,7 +189,7 @@ export const browserTools = [
180
189
  lastActivity: new Date().toISOString(),
181
190
  });
182
191
  }
183
- return execBrowserCommand(args, sessionId);
192
+ return execBrowserCommand(args, sessionId, launchArgs);
184
193
  },
185
194
  },
186
195
  {
@@ -317,8 +326,16 @@ export const browserTools = [
317
326
  }
318
327
  const { session, path, fullPage } = input;
319
328
  const args = ['screenshot'];
320
- if (path)
321
- args.push(path);
329
+ if (path) {
330
+ // The browser writes the image wherever it is told and replaces what
331
+ // is there, so a caller-named path must stay inside the project.
332
+ const target = containedWritePath(path, SCREENSHOT_EXTENSIONS);
333
+ if (!target) {
334
+ const error = `path must be a new or regular file inside the project ending in ${SCREENSHOT_EXTENSIONS.join(', ')}`;
335
+ return { content: [{ type: 'text', text: JSON.stringify({ success: false, error }) }], isError: true };
336
+ }
337
+ args.push(target);
338
+ }
322
339
  if (fullPage)
323
340
  args.push('--full');
324
341
  return execBrowserCommand(args, session);
@@ -346,11 +346,12 @@ export const coordinationTools = [
346
346
  }
347
347
  if (action === 'heartbeat') {
348
348
  const nodeId = input.nodeId;
349
- if (store.nodes[nodeId]) {
350
- store.nodes[nodeId].lastHeartbeat = new Date().toISOString();
351
- store.nodes[nodeId].status = 'active';
352
- saveCoordStore(store);
349
+ if (!store.nodes[nodeId]) {
350
+ return { success: false, error: 'Node not found' };
353
351
  }
352
+ store.nodes[nodeId].lastHeartbeat = new Date().toISOString();
353
+ store.nodes[nodeId].status = 'active';
354
+ saveCoordStore(store);
354
355
  return {
355
356
  success: true,
356
357
  action: 'heartbeat',
@@ -50,11 +50,14 @@ async function getRealEmbeddingFunction() {
50
50
  }
51
51
  return realEmbeddingFn;
52
52
  }
53
- async function generateRealEmbedding(text, dimension) {
53
+ async function generateRealEmbedding(text, dimension, normalize = true) {
54
54
  const realFn = await getRealEmbeddingFunction();
55
55
  if (realFn) {
56
56
  try {
57
- const result = await realFn(text);
57
+ // Default callers stay a single-argument call so existing mocks and
58
+ // the unit-norm path are unchanged. Only an explicit opt-out asks the
59
+ // generator for the pre-L2 vector.
60
+ const result = normalize ? await realFn(text) : await realFn(text, { normalize: false });
58
61
  return {
59
62
  embedding: result.embedding,
60
63
  backend: result.backend ?? 'onnx',
@@ -76,7 +79,10 @@ async function generateRealEmbedding(text, dimension) {
76
79
  const seed = hash + i * 1337;
77
80
  embedding.push(Math.sin(seed) * Math.cos(seed * 0.5));
78
81
  }
79
- // L2 normalize
82
+ // L2 normalize unless the caller opted out (#4724).
83
+ if (!normalize) {
84
+ return { embedding, backend: 'mock', model: 'hash-fallback' };
85
+ }
80
86
  const norm = Math.sqrt(embedding.reduce((sum, x) => sum + x * x, 0));
81
87
  return {
82
88
  embedding: embedding.map(x => x / norm),
@@ -256,8 +262,10 @@ export const embeddingsTools = [
256
262
  return { success: false, error: v.error };
257
263
  }
258
264
  const useHyperbolic = input.hyperbolic === true && config.hyperbolic.enabled;
265
+ // Default true: omitted and explicit true keep the historical unit vector.
266
+ const shouldNormalize = input.normalize !== false;
259
267
  // Generate real ONNX embedding
260
- const generated = await generateRealEmbedding(text, config.dimension);
268
+ const generated = await generateRealEmbedding(text, config.dimension, shouldNormalize);
261
269
  const embedding = generated.embedding;
262
270
  let result;
263
271
  let geometry;
@@ -0,0 +1,6 @@
1
+ /** Bounded glob matching for caller-provided memory-import exclusions. */
2
+ export declare const MAX_EXCLUDE_PATTERNS = 64;
3
+ export declare const MAX_EXCLUDE_PATTERN_LENGTH = 1024;
4
+ export declare const MAX_EXCLUDE_WILDCARDS = 32;
5
+ export declare function compileExclusionPatterns(input: unknown): Array<(path: string) => boolean>;
6
+ //# sourceMappingURL=glob-exclusions.d.ts.map
@@ -0,0 +1,81 @@
1
+ /** Bounded glob matching for caller-provided memory-import exclusions. */
2
+ export const MAX_EXCLUDE_PATTERNS = 64;
3
+ export const MAX_EXCLUDE_PATTERN_LENGTH = 1024;
4
+ export const MAX_EXCLUDE_WILDCARDS = 32;
5
+ function tokenize(pattern) {
6
+ const tokens = [];
7
+ let wildcards = 0;
8
+ for (let i = 0; i < pattern.length; i++) {
9
+ const char = pattern[i];
10
+ if (char === '*') {
11
+ let end = i + 1;
12
+ while (pattern[end] === '*')
13
+ end++;
14
+ tokens.push({ kind: end - i > 1 ? 'globstar' : 'star' });
15
+ // Preserve the trailing segment-star in odd runs, including its newline behavior.
16
+ if (end - i > 1 && (end - i) % 2 === 1) {
17
+ tokens.push({ kind: 'star' });
18
+ wildcards++;
19
+ }
20
+ i = end - 1;
21
+ wildcards++;
22
+ }
23
+ else if (char === '?') {
24
+ tokens.push({ kind: 'question' });
25
+ wildcards++;
26
+ }
27
+ else {
28
+ tokens.push({ kind: 'literal', value: char });
29
+ }
30
+ }
31
+ if (wildcards > MAX_EXCLUDE_WILDCARDS) {
32
+ throw new Error(`excludeFilePatterns entries may contain at most ${MAX_EXCLUDE_WILDCARDS} wildcard operators`);
33
+ }
34
+ return tokens;
35
+ }
36
+ function matches(tokens, path) {
37
+ // Each path character visits each token once; wildcard placement cannot cause backtracking.
38
+ let previous = new Uint8Array(tokens.length + 1);
39
+ let current = new Uint8Array(tokens.length + 1);
40
+ previous[0] = 1;
41
+ for (let j = 1; j <= tokens.length; j++) {
42
+ const token = tokens[j - 1];
43
+ if (token.kind === 'star' || token.kind === 'globstar')
44
+ previous[j] = previous[j - 1];
45
+ }
46
+ for (let i = 0; i < path.length; i++) {
47
+ current[0] = 0;
48
+ const char = path[i];
49
+ const inSegment = char !== '/' && char !== '\\';
50
+ for (let j = 1; j <= tokens.length; j++) {
51
+ const token = tokens[j - 1];
52
+ if (token.kind === 'star' || token.kind === 'globstar') {
53
+ const canConsume = token.kind === 'globstar'
54
+ ? !'\n\r\u2028\u2029'.includes(char)
55
+ : inSegment;
56
+ current[j] = current[j - 1] || (canConsume ? previous[j] : 0);
57
+ }
58
+ else {
59
+ const canConsume = token.kind === 'literal' ? token.value === char : inSegment;
60
+ current[j] = canConsume ? previous[j - 1] : 0;
61
+ }
62
+ }
63
+ [previous, current] = [current, previous];
64
+ }
65
+ return previous[tokens.length] === 1;
66
+ }
67
+ export function compileExclusionPatterns(input) {
68
+ if (input === undefined)
69
+ return [];
70
+ if (!Array.isArray(input) || input.length > MAX_EXCLUDE_PATTERNS) {
71
+ throw new Error(`excludeFilePatterns must be an array of at most ${MAX_EXCLUDE_PATTERNS} patterns`);
72
+ }
73
+ return Array.from(input, (pattern) => {
74
+ if (typeof pattern !== 'string' || pattern.length > MAX_EXCLUDE_PATTERN_LENGTH) {
75
+ throw new Error(`excludeFilePatterns entries must be strings of at most ${MAX_EXCLUDE_PATTERN_LENGTH} characters`);
76
+ }
77
+ const tokens = tokenize(pattern);
78
+ return (path) => matches(tokens, path);
79
+ });
80
+ }
81
+ //# sourceMappingURL=glob-exclusions.js.map