claude-flow 3.77.1 → 3.77.2

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 (43) hide show
  1. package/.claude/helpers/hook-handler.cjs +85 -5
  2. package/README.md +12 -2
  3. package/node_modules/@claude-flow/plugin-agent-federation/README.md +18 -0
  4. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.d.ts +4 -1
  5. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.d.ts.map +1 -1
  6. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.js +11 -0
  7. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.js.map +1 -1
  8. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-envelope-guard.d.ts +29 -0
  9. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-envelope-guard.d.ts.map +1 -0
  10. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-envelope-guard.js +96 -0
  11. package/node_modules/@claude-flow/plugin-agent-federation/dist/application/inbound-envelope-guard.js.map +1 -0
  12. package/node_modules/@claude-flow/plugin-agent-federation/dist/plugin.d.ts.map +1 -1
  13. package/node_modules/@claude-flow/plugin-agent-federation/dist/plugin.js +3 -0
  14. package/node_modules/@claude-flow/plugin-agent-federation/dist/plugin.js.map +1 -1
  15. package/package.json +8 -5
  16. package/v3/@claude-flow/cli/README.md +5 -0
  17. package/v3/@claude-flow/cli/bin/cli.js +8 -3
  18. package/v3/@claude-flow/cli/dist/src/commands/init.js +8 -1
  19. package/v3/@claude-flow/cli/dist/src/commands/session.js +2 -1
  20. package/v3/@claude-flow/cli/dist/src/commands/workflow.js +2 -1
  21. package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js +85 -5
  22. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js +26 -25
  23. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js +161 -157
  24. package/v3/@claude-flow/cli/dist/src/mcp-tools/claims-tools.js +257 -258
  25. package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js +48 -29
  26. package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js +6 -0
  27. package/v3/@claude-flow/cli/dist/src/mcp-tools/locked-json-store.d.ts +20 -0
  28. package/v3/@claude-flow/cli/dist/src/mcp-tools/locked-json-store.js +99 -0
  29. package/v3/@claude-flow/cli/dist/src/mcp-tools/managed-agent-tools.js +51 -7
  30. package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js +19 -9
  31. package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js +299 -270
  32. package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js +245 -215
  33. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js +5 -4
  34. package/v3/@claude-flow/cli/dist/src/missions/schemas.d.ts +38 -38
  35. package/v3/@claude-flow/cli/dist/src/mods/command-registry/schema.d.ts +210 -210
  36. package/v3/@claude-flow/cli/dist/src/services/managed-run-store.d.ts +11 -0
  37. package/v3/@claude-flow/cli/dist/src/services/managed-run-store.js +125 -3
  38. package/v3/@claude-flow/cli/dist/src/services/policy-runtime.d.ts +3 -0
  39. package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js +3 -1
  40. package/v3/@claude-flow/cli/package.json +9 -6
  41. package/v3/@claude-flow/guidance/package.json +1 -0
  42. package/.claude/.proven-config-version +0 -1
  43. package/.claude/proven-config.json +0 -42
@@ -4,9 +4,10 @@
4
4
  * Tool definitions for agent lifecycle management with file persistence.
5
5
  * Includes model routing integration for intelligent model selection.
6
6
  */
7
- import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
7
+ import { existsSync, readFileSync } from 'node:fs';
8
8
  import { join } from 'node:path';
9
9
  import { nullPrototypeRecords, readRecordStore } from './record-store.js';
10
+ import { saved, unchanged, updateJsonStore } from './locked-json-store.js';
10
11
  import { getProjectCwd } from './types.js';
11
12
  import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';
12
13
  import { executeAgentTask } from './agent-execute-core.js';
@@ -56,12 +57,6 @@ function getAgentDir() {
56
57
  function getAgentPath() {
57
58
  return join(getAgentDir(), AGENT_FILE);
58
59
  }
59
- function ensureAgentDir() {
60
- const dir = getAgentDir();
61
- if (!existsSync(dir)) {
62
- mkdirSync(dir, { recursive: true });
63
- }
64
- }
65
60
  function loadAgentStore() {
66
61
  return readRecordStore(getAgentPath(), 'agents', () => ({ agents: {}, version: '3.0.0' }));
67
62
  }
@@ -70,9 +65,10 @@ export function getLiveAgentIds(agentIds) {
70
65
  const { agents } = loadAgentStore();
71
66
  return [...new Set(agentIds)].filter(id => agents[id] && agents[id].status !== 'terminated');
72
67
  }
73
- function saveAgentStore(store) {
74
- ensureAgentDir();
75
- writeFileSync(getAgentPath(), JSON.stringify(store, null, 2), 'utf-8');
68
+ /** Every agent-store write goes through here, under the agents lock.
69
+ * agent-execute-core.ts and task-tools.ts write the same file and take the same lock. */
70
+ function updateAgentStore(mutate) {
71
+ return updateJsonStore(getAgentPath(), loadAgentStore, mutate, 'agents');
76
72
  }
77
73
  // #1916: read hive-mind-spawned workers from `.claude-flow/agents.json`.
78
74
  function getHiveAgentPath() {
@@ -385,10 +381,10 @@ export const agentTools = [
385
381
  : routingResult.provider ? { provider: routingResult.provider } : {}),
386
382
  ...(routingResult.openrouterModel ? { openrouterModel: routingResult.openrouterModel } : {}),
387
383
  };
388
- const store = loadAgentStore();
389
384
  // #2085 — the agent is also pushed to the swarm store's agents array so
390
385
  // that swarm_status reports it. Resolve that swarm first: #4572 — an
391
386
  // active swarm already holding maxAgents live agents refuses the spawn.
387
+ // Resolved before the agents lock, so the lock covers only sync work.
392
388
  let swarmTools;
393
389
  let swarmStore;
394
390
  let targetSwarmId = input.swarmId || '';
@@ -405,21 +401,25 @@ export const agentTools = [
405
401
  catch { /* swarm store unavailable — agent still registered globally */ }
406
402
  const swarm = targetSwarmId ? swarmStore?.swarms[targetSwarmId] : undefined;
407
403
  const members = Array.isArray(swarm?.agents) ? swarm.agents : [];
408
- if (swarm && swarm.status !== 'terminated' && !members.includes(agentId)) {
409
- // Terminated agents stay listed in swarm.agents; they no longer hold a slot.
410
- const live = members.filter((id) => store.agents[id] && store.agents[id].status !== 'terminated').length;
411
- if (live >= swarm.maxAgents) {
412
- return {
413
- success: false,
414
- error: `Swarm ${swarm.swarmId} is full: ${live}/${swarm.maxAgents} agents. Terminate an agent (agent_terminate) or init a swarm with a larger maxAgents.`,
415
- swarmId: swarm.swarmId,
416
- agentCount: live,
417
- maxAgents: swarm.maxAgents,
418
- };
404
+ const refused = await updateAgentStore((store) => {
405
+ if (swarm && swarm.status !== 'terminated' && !members.includes(agentId)) {
406
+ // Terminated agents stay listed in swarm.agents; they no longer hold a slot.
407
+ const live = members.filter((id) => store.agents[id] && store.agents[id].status !== 'terminated').length;
408
+ if (live >= swarm.maxAgents) {
409
+ return unchanged({
410
+ success: false,
411
+ error: `Swarm ${swarm.swarmId} is full: ${live}/${swarm.maxAgents} agents. Terminate an agent (agent_terminate) or init a swarm with a larger maxAgents.`,
412
+ swarmId: swarm.swarmId,
413
+ agentCount: live,
414
+ maxAgents: swarm.maxAgents,
415
+ });
416
+ }
419
417
  }
420
- }
421
- store.agents[agentId] = agent;
422
- saveAgentStore(store);
418
+ store.agents[agentId] = agent;
419
+ return saved(undefined);
420
+ });
421
+ if (refused)
422
+ return refused;
423
423
  if (swarm && swarmTools && swarmStore) {
424
424
  try {
425
425
  if (!Array.isArray(swarm.agents))
@@ -455,13 +455,14 @@ export const agentTools = [
455
455
  memoryBranch = br.branchPath;
456
456
  agent.memoryBranch = br.branchPath;
457
457
  agent.memoryBase = br.basePath;
458
- const latest = loadAgentStore();
459
- const current = latest.agents[agentId];
460
- if (current && current.status !== 'terminated') {
458
+ await updateAgentStore((latest) => {
459
+ const current = latest.agents[agentId];
460
+ if (!current || current.status === 'terminated')
461
+ return unchanged(undefined);
461
462
  current.memoryBranch = br.branchPath;
462
463
  current.memoryBase = br.basePath;
463
- saveAgentStore(latest);
464
- }
464
+ return saved(undefined);
465
+ });
465
466
  }
466
467
  // else: degraded (agenticow missing / kill-switched) — agent stands
467
468
  // without an isolated branch; callers see no memoryBranch field.
@@ -572,12 +573,15 @@ export const agentTools = [
572
573
  const v = validateIdentifier(input.agentId, 'agentId');
573
574
  if (!v.valid)
574
575
  return { success: false, error: `Input validation failed: ${v.error}` };
575
- const store = loadAgentStore();
576
576
  const agentId = input.agentId;
577
- if (store.agents[agentId]) {
578
- const rec = store.agents[agentId];
579
- rec.status = 'terminated';
580
- saveAgentStore(store);
577
+ const rec = await updateAgentStore((store) => {
578
+ const found = store.agents[agentId];
579
+ if (!found)
580
+ return unchanged(undefined);
581
+ found.status = 'terminated';
582
+ return saved(found);
583
+ });
584
+ if (rec) {
581
585
  // ACOW — resolve the agent's COW memory branch on teardown: promote
582
586
  // (merge into base) when asked, else discard. Non-fatal — a failure
583
587
  // here never blocks termination. Discard needs no agenticow (pure fs),
@@ -742,107 +746,107 @@ export const agentTools = [
742
746
  if (!v.valid)
743
747
  return { action: input.action, error: `Input validation failed: ${v.error}` };
744
748
  }
745
- const store = loadAgentStore();
746
- const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
747
- const action = input.action || 'status'; // Default to status
748
- if (action === 'status') {
749
- const byType = {};
750
- const byStatus = {};
751
- for (const agent of agents) {
752
- byType[agent.agentType] = (byType[agent.agentType] || 0) + 1;
753
- byStatus[agent.status] = (byStatus[agent.status] || 0) + 1;
754
- }
755
- const idleAgents = agents.filter(a => a.status === 'idle').length;
756
- const busyAgents = agents.filter(a => a.status === 'busy').length;
757
- const utilization = agents.length > 0 ? busyAgents / agents.length : 0;
758
- return {
759
- action,
760
- // CLI expected fields
761
- poolId: 'agent-pool-default',
762
- currentSize: agents.length,
763
- minSize: input.min || 0,
764
- maxSize: input.max || 100,
765
- autoScale: input.autoScale ?? false,
766
- utilization,
767
- agents: agents.map(a => ({
768
- id: a.agentId,
769
- type: a.agentType,
770
- status: a.status,
771
- })),
772
- // Additional fields
773
- id: 'agent-pool-default',
774
- size: agents.length,
775
- totalAgents: agents.length,
776
- byType,
777
- byStatus,
778
- avgHealth: agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 0,
779
- };
780
- }
781
- // #4555: fill was advertised in the enum but had no branch. It is scale
782
- // without the shrink step: grow agentType's pool to targetSize, never terminate.
783
- if (action === 'scale' || action === 'fill') {
784
- const targetSize = input.targetSize === undefined ? 5 : input.targetSize;
785
- if (typeof targetSize !== 'number' || !Number.isSafeInteger(targetSize) || targetSize < 0) {
786
- return { action, error: 'targetSize must be a non-negative safe integer' };
787
- }
788
- const agentType = input.agentType || 'worker';
789
- const currentSize = agents.filter(a => a.agentType === agentType).length;
790
- const delta = targetSize - currentSize;
791
- const added = [];
792
- const removed = [];
793
- if (delta > 0) {
794
- for (let i = 0; i < delta; i++) {
795
- const agentId = `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
796
- store.agents[agentId] = {
797
- agentId,
798
- agentType,
799
- status: 'idle',
800
- health: 1.0,
801
- taskCount: 0,
802
- config: {},
803
- createdAt: new Date().toISOString(),
804
- };
805
- added.push(agentId);
749
+ // Every action decides from the same locked read it changes.
750
+ return updateAgentStore((store) => {
751
+ const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
752
+ const action = input.action || 'status'; // Default to status
753
+ if (action === 'status') {
754
+ const byType = {};
755
+ const byStatus = {};
756
+ for (const agent of agents) {
757
+ byType[agent.agentType] = (byType[agent.agentType] || 0) + 1;
758
+ byStatus[agent.status] = (byStatus[agent.status] || 0) + 1;
806
759
  }
760
+ const idleAgents = agents.filter(a => a.status === 'idle').length;
761
+ const busyAgents = agents.filter(a => a.status === 'busy').length;
762
+ const utilization = agents.length > 0 ? busyAgents / agents.length : 0;
763
+ return unchanged({
764
+ action,
765
+ // CLI expected fields
766
+ poolId: 'agent-pool-default',
767
+ currentSize: agents.length,
768
+ minSize: input.min || 0,
769
+ maxSize: input.max || 100,
770
+ autoScale: input.autoScale ?? false,
771
+ utilization,
772
+ agents: agents.map(a => ({
773
+ id: a.agentId,
774
+ type: a.agentType,
775
+ status: a.status,
776
+ })),
777
+ // Additional fields
778
+ id: 'agent-pool-default',
779
+ size: agents.length,
780
+ totalAgents: agents.length,
781
+ byType,
782
+ byStatus,
783
+ avgHealth: agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 0,
784
+ });
807
785
  }
808
- else if (delta < 0 && action === 'scale') {
809
- const toRemove = agents.filter(a => a.agentType === agentType && a.status === 'idle').slice(0, -delta);
810
- for (const agent of toRemove) {
811
- store.agents[agent.agentId].status = 'terminated';
812
- removed.push(agent.agentId);
786
+ // #4555: fill was advertised in the enum but had no branch. It is scale
787
+ // without the shrink step: grow agentType's pool to targetSize, never terminate.
788
+ if (action === 'scale' || action === 'fill') {
789
+ const targetSize = input.targetSize === undefined ? 5 : input.targetSize;
790
+ if (typeof targetSize !== 'number' || !Number.isSafeInteger(targetSize) || targetSize < 0) {
791
+ return unchanged({ action, error: 'targetSize must be a non-negative safe integer' });
813
792
  }
814
- }
815
- saveAgentStore(store);
816
- return {
817
- action,
818
- agentType,
819
- previousSize: currentSize,
820
- targetSize,
821
- newSize: currentSize + added.length - removed.length,
822
- added,
823
- removed,
824
- };
825
- }
826
- if (action === 'drain') {
827
- const agentType = input.agentType;
828
- let drained = 0;
829
- for (const agent of agents) {
830
- if (!agentType || agent.agentType === agentType) {
831
- if (agent.status === 'idle') {
793
+ const agentType = input.agentType || 'worker';
794
+ const currentSize = agents.filter(a => a.agentType === agentType).length;
795
+ const delta = targetSize - currentSize;
796
+ const added = [];
797
+ const removed = [];
798
+ if (delta > 0) {
799
+ for (let i = 0; i < delta; i++) {
800
+ const agentId = `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
801
+ store.agents[agentId] = {
802
+ agentId,
803
+ agentType,
804
+ status: 'idle',
805
+ health: 1.0,
806
+ taskCount: 0,
807
+ config: {},
808
+ createdAt: new Date().toISOString(),
809
+ };
810
+ added.push(agentId);
811
+ }
812
+ }
813
+ else if (delta < 0 && action === 'scale') {
814
+ const toRemove = agents.filter(a => a.agentType === agentType && a.status === 'idle').slice(0, -delta);
815
+ for (const agent of toRemove) {
832
816
  store.agents[agent.agentId].status = 'terminated';
833
- drained++;
817
+ removed.push(agent.agentId);
834
818
  }
835
819
  }
820
+ return saved({
821
+ action,
822
+ agentType,
823
+ previousSize: currentSize,
824
+ targetSize,
825
+ newSize: currentSize + added.length - removed.length,
826
+ added,
827
+ removed,
828
+ });
836
829
  }
837
- saveAgentStore(store);
838
- return {
839
- action,
840
- agentType: agentType || 'all',
841
- drained,
842
- remaining: agents.length - drained,
843
- };
844
- }
845
- return { action, error: 'Unknown action' };
830
+ if (action === 'drain') {
831
+ const agentType = input.agentType;
832
+ let drained = 0;
833
+ for (const agent of agents) {
834
+ if (!agentType || agent.agentType === agentType) {
835
+ if (agent.status === 'idle') {
836
+ store.agents[agent.agentId].status = 'terminated';
837
+ drained++;
838
+ }
839
+ }
840
+ }
841
+ return saved({
842
+ action,
843
+ agentType: agentType || 'all',
844
+ drained,
845
+ remaining: agents.length - drained,
846
+ });
847
+ }
848
+ return unchanged({ action, error: 'Unknown action' });
849
+ });
846
850
  },
847
851
  },
848
852
  {
@@ -966,37 +970,37 @@ export const agentTools = [
966
970
  if (!vs.valid)
967
971
  return { success: false, agentId: input.agentId, error: `Input validation failed: ${vs.error}` };
968
972
  }
969
- const store = loadAgentStore();
970
973
  const agentId = input.agentId;
971
- const agent = store.agents[agentId];
972
- if (agent) {
973
- if (input.status)
974
- agent.status = input.status;
975
- if (typeof input.health === 'number')
976
- agent.health = input.health;
977
- if (typeof input.taskCount === 'number')
978
- agent.taskCount = input.taskCount;
979
- if (input.config) {
980
- agent.config = { ...agent.config, ...input.config };
974
+ return updateAgentStore((store) => {
975
+ const agent = store.agents[agentId];
976
+ if (agent) {
977
+ if (input.status)
978
+ agent.status = input.status;
979
+ if (typeof input.health === 'number')
980
+ agent.health = input.health;
981
+ if (typeof input.taskCount === 'number')
982
+ agent.taskCount = input.taskCount;
983
+ if (input.config) {
984
+ agent.config = { ...agent.config, ...input.config };
985
+ }
986
+ return saved({
987
+ success: true,
988
+ agentId,
989
+ updated: true,
990
+ agent: {
991
+ agentId: agent.agentId,
992
+ status: agent.status,
993
+ health: agent.health,
994
+ taskCount: agent.taskCount,
995
+ },
996
+ });
981
997
  }
982
- saveAgentStore(store);
983
- return {
984
- success: true,
998
+ return unchanged({
999
+ success: false,
985
1000
  agentId,
986
- updated: true,
987
- agent: {
988
- agentId: agent.agentId,
989
- status: agent.status,
990
- health: agent.health,
991
- taskCount: agent.taskCount,
992
- },
993
- };
994
- }
995
- return {
996
- success: false,
997
- agentId,
998
- error: 'Agent not found',
999
- };
1001
+ error: 'Agent not found',
1002
+ });
1003
+ });
1000
1004
  },
1001
1005
  },
1002
1006
  {