🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(agent): report measured execution health instead of registry defaults
Rudy Celeklifa5e7baf9e8c
diff --git a/v3/@claude-flow/cli/__tests__/agent-health-observed.test.ts b/v3/@claude-flow/cli/__tests__/agent-health-observed.test.tsnew file mode 100644index 0000000000..f52dffdaf4--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/agent-health-observed.test.ts@@ -0,0 +1,102 @@+import { afterEach, beforeEach, expect, it, vi } from 'vitest';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { agentTools } from '../src/mcp-tools/agent-tools.js';+import { executeAgentTask } from '../src/mcp-tools/agent-execute-core.js';+import { appendAgentExecution, summarizeAgentExecutions } from '../src/mcp-tools/agent-health-metrics.js';++const ENV_KEYS = ['CLAUDE_FLOW_CWD', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY', 'OLLAMA_API_KEY', 'RUFLO_PROVIDER'] as const;+let dir: string;+let originalEnv: Record<string, string | undefined>;++const health = (input: Record<string, unknown>) =>+ agentTools.find(tool => tool.name === 'agent_health')!.handler(input) as Promise<any>;++function storePath(): string {+ return join(dir, '.claude-flow', 'agents', 'store.json');+}++function writeAgents(): void {+ mkdirSync(join(dir, '.claude-flow', 'agents'), { recursive: true });+ writeFileSync(storePath(), JSON.stringify({ version: '3.0.0', agents: {+ observed: { agentId: 'observed', agentType: 'worker', status: 'idle', health: 1, taskCount: 0, config: {}, createdAt: '2026-01-01T00:00:00.000Z' },+ untouched: { agentId: 'untouched', agentType: 'worker', status: 'idle', health: 1, taskCount: 100, config: {}, createdAt: '2026-01-01T00:00:00.000Z' },+ } }));+}++beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'ruflo-health-observed-'));+ originalEnv = Object.fromEntries(ENV_KEYS.map(key => [key, process.env[key]]));+ for (const key of ENV_KEYS) delete process.env[key];+ process.env.CLAUDE_FLOW_CWD = dir;+ writeAgents();+});++afterEach(() => {+ vi.restoreAllMocks();+ for (const key of ENV_KEYS) {+ if (originalEnv[key] === undefined) delete process.env[key];+ else process.env[key] = originalEnv[key];+ }+ rmSync(dir, { recursive: true, force: true });+});++it('reports unobserved registry entries as unknown instead of healthy with zero failures', async () => {+ expect(await health({ agentId: 'untouched' })).toMatchObject({ health: null, healthy: null, sampleCount: 0, uptime: null });+ expect(await health({})).toMatchObject({+ observedCount: 0, unknownCount: 2, avgHealth: null,+ overall: { healthy: 0, unknown: 2, score: null },+ });+});++it('persists failed and successful agent_execute outcomes in the bounded health window', async () => {+ expect((await executeAgentTask({ agentId: 'observed', prompt: 'first' })).success).toBe(false);+ expect(await health({ agentId: 'observed' })).toMatchObject({ health: 0, errorRate: 1, failures: 1, sampleCount: 1 });++ process.env.ANTHROPIC_API_KEY = 'test-key';+ vi.spyOn(globalThis, 'fetch').mockResolvedValue({ ok: true, json: async () => ({+ id: 'msg-test', model: 'claude-sonnet-5', content: [{ type: 'text', text: 'done' }],+ stop_reason: 'end_turn', usage: { input_tokens: 1, output_tokens: 1 },+ }) } as Response);+ expect((await executeAgentTask({ agentId: 'observed', prompt: 'second' })).success).toBe(true);++ expect(await health({ agentId: 'observed' })).toMatchObject({+ health: 0.5, errorRate: 0.5, failures: 1, successes: 1, sampleCount: 2,+ latency: { p50: expect.any(Number), p95: expect.any(Number) },+ });+ const aggregate = await health({});+ expect(aggregate).toMatchObject({+ observedCount: 1, unknownCount: 1, avgHealth: 0.5,+ agents: [expect.objectContaining({ id: 'observed', tasks: { active: 0, queued: null, completed: 1, failed: 1 } }), expect.objectContaining({ id: 'untouched', health: 'unknown' })],+ });+ expect(JSON.parse(readFileSync(storePath(), 'utf-8')).agents.observed).toMatchObject({ health: 0.5, executionHistory: [{ success: false }, { success: true }] });+});++it('keeps only the newest 20 samples and computes latency percentiles from measured durations', () => {+ let history: unknown = [];+ for (let i = 1; i <= 25; i++) {+ history = appendAgentExecution(history, { at: new Date().toISOString(), success: i % 5 !== 0, durationMs: i });+ }+ expect(summarizeAgentExecutions(history)).toMatchObject({+ health: 0.8, errorRate: 0.2, sampleCount: 20, failures: 4,+ latency: { avg: 15.5, p50: 15, p95: 24, p99: 25 },+ });+});++it('preserves an explicit health update made while a provider call is in flight', async () => {+ process.env.ANTHROPIC_API_KEY = 'test-key';+ let complete!: (response: Response) => void;+ vi.spyOn(globalThis, 'fetch').mockReturnValue(new Promise(resolve => { complete = resolve; }));+ const pending = executeAgentTask({ agentId: 'observed', prompt: 'slow response' });+ const store = JSON.parse(readFileSync(storePath(), 'utf-8'));+ store.agents.observed.health = 0.7;+ writeFileSync(storePath(), JSON.stringify(store));+ complete({ ok: true, json: async () => ({+ id: 'msg-test', model: 'claude-sonnet-5', content: [{ type: 'text', text: 'done' }],+ stop_reason: 'end_turn', usage: { input_tokens: 1, output_tokens: 1 },+ }) } as Response);+ expect((await pending).success).toBe(true);+ expect(JSON.parse(readFileSync(storePath(), 'utf-8')).agents.observed.health).toBe(0.7);+ expect(await health({ agentId: 'observed' })).toMatchObject({ health: 1, sampleCount: 1 });+});diff --git a/v3/@claude-flow/cli/src/commands/agent.ts b/v3/@claude-flow/cli/src/commands/agent.tsindex 99168d6e09..b0ae163eb7 100644--- a/v3/@claude-flow/cli/src/commands/agent.ts+++ b/v3/@claude-flow/cli/src/commands/agent.ts@@ -857,20 +857,24 @@ const healthCommand: Command = {agents: Array<{id: string;type: string;- health: 'healthy' | 'degraded' | 'unhealthy';- uptime: number;+ health: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';+ uptime: number | null;+ registryAgeMs?: number;memory: { used: number; limit: number };cpu: number;tasks: { active: number; queued: number; completed: number; failed: number };- latency: { avg: number; p99: number };+ latency: { avg: number | null; p50?: number | null; p95?: number | null; p99: number | null };errors: { count: number; lastError?: string };}>;overall: {healthy: number;degraded: number;unhealthy: number;- avgCpu: number;- avgMemory: number;+ unknown?: number;+ avgCpu?: number | null;+ avgMemory?: number | null;+ cpu?: number | null;+ memory?: number | null;};}>('agent_health', {agentId,@@ -887,16 +891,17 @@ const healthCommand: Command = {output.writeln();// Overall summary with null checks- const overall = result.overall ?? { healthy: 0, degraded: 0, unhealthy: 0, avgCpu: 0, avgMemory: 0 };- const avgCpu = overall.avgCpu ?? 0;- const avgMemory = overall.avgMemory ?? 0;+ const overall = result.overall ?? { healthy: 0, degraded: 0, unhealthy: 0, unknown: 0 };+ const avgCpu = overall.avgCpu ?? overall.cpu;+ const avgMemory = overall.avgMemory ?? overall.memory;output.printBox([`Healthy: ${output.success(String(overall.healthy ?? 0))}`,`Degraded: ${output.warning(String(overall.degraded ?? 0))}`,`Unhealthy: ${output.error(String(overall.unhealthy ?? 0))}`,- `Avg CPU: ${avgCpu.toFixed(1)}%`,- `Avg Memory: ${(avgMemory * 100).toFixed(1)}%`+ `Unknown: ${String(overall.unknown ?? 0)}`,+ `Avg CPU: ${typeof avgCpu === 'number' ? `${avgCpu.toFixed(1)}%` : 'n/a'}`,+ `Avg Memory: ${typeof avgMemory === 'number' ? `${(avgMemory * 100).toFixed(1)}%` : 'n/a'}`].join(' | '),'Overall Status');@@ -908,13 +913,13 @@ const healthCommand: Command = {{ key: 'id', header: 'Agent ID', width: 18 },{ key: 'type', header: 'Type', width: 12 },{ key: 'health', header: 'Health', width: 10, format: formatHealthStatus },- { key: 'cpu', header: 'CPU %', width: 8, align: 'right', format: (v) => `${Number(v ?? 0).toFixed(1)}%` },+ { key: 'cpu', header: 'CPU %', width: 8, align: 'right', format: (v) => typeof v === 'number' ? `${v.toFixed(1)}%` : 'n/a' },{ key: 'memory', header: 'Memory', width: 10, align: 'right', format: (v: unknown) => {const mem = v as { used: number; limit: number } | undefined;- if (!mem) return '0%';+ if (!mem || !mem.limit) return 'n/a';return `${(mem.used / mem.limit * 100).toFixed(0)}%`;}},- { key: 'tasks', header: 'Tasks', width: 12, align: 'right', format: (v: unknown) => {+ { key: 'tasks', header: 'Calls', width: 12, align: 'right', format: (v: unknown) => {const t = v as { active: number; completed: number } | undefined;if (!t) return '0/0';return `${t.active ?? 0}/${t.completed ?? 0}`;@@ -929,15 +934,14 @@ const healthCommand: Command = {for (const agent of healthAgents) {output.writeln();output.writeln(output.highlight(agent.id));- const uptime = agent.uptime ?? 0;- const latency = agent.latency ?? { avg: 0, p99: 0 };- const tasks = agent.tasks ?? { completed: 0, failed: 0, queued: 0 };- const errors = agent.errors ?? { count: 0 };+ const latency = agent.latency;+ const tasks = agent.tasks;+ const errors = agent.errors;output.printList([- `Uptime: ${(uptime / 1000 / 60).toFixed(1)} min`,- `Latency: avg ${(latency.avg ?? 0).toFixed(1)}ms, p99 ${(latency.p99 ?? 0).toFixed(1)}ms`,- `Tasks: ${tasks.completed ?? 0} completed, ${tasks.failed ?? 0} failed, ${tasks.queued ?? 0} queued`,- `Errors: ${errors.count ?? 0}${errors.lastError ? ` (${errors.lastError})` : ''}`+ `Registry age: ${typeof agent.registryAgeMs === 'number' ? `${(agent.registryAgeMs / 1000 / 60).toFixed(1)} min` : 'n/a'}`,+ `Latency: p50 ${typeof latency?.p50 === 'number' ? `${latency.p50.toFixed(1)}ms` : 'n/a'}, p95 ${typeof latency?.p95 === 'number' ? `${latency.p95.toFixed(1)}ms` : 'n/a'}`,+ `Observed provider calls (last 20): ${tasks?.completed ?? 0} API-success, ${tasks?.failed ?? 0} error`,+ `Errors: ${errors?.count ?? 0}${errors?.lastError ? ` (${errors.lastError})` : ''}`]);}}diff --git a/v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts b/v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.tsindex 2a165cc460..794a5857eb 100644--- a/v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts@@ -11,6 +11,7 @@import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { join } from 'node:path';import { getProjectCwd } from './types.js';+import { appendAgentExecution, summarizeAgentExecutions, type AgentExecutionSample } from './agent-health-metrics.js';import { configManager } from '../services/config-file-manager.js';const STORAGE_DIR = '.claude-flow';@@ -43,6 +44,7 @@ export interface AgentRecord {/** ADR-148 phase 2 — concrete OpenRouter slug when provider='openrouter'. */openrouterModel?: string;lastResult?: Record<string, unknown>;+ executionHistory?: AgentExecutionSample[];}interface AgentStore {@@ -797,6 +799,20 @@ export async function executeAgentTask(input: AgentExecuteInput): Promise<AgentEcurrent.modelId = agent.modelId;}if (out) current.lastResult = out as unknown as Record<string, unknown>;+ const previousMeasuredHealth = summarizeAgentExecutions(current.executionHistory).health;+ const mayUpdateStoredHealth = previousMeasuredHealth === null+ ? current.health === agent.health+ : current.health === previousMeasuredHealth;+ current.executionHistory = appendAgentExecution(current.executionHistory, {+ at: new Date().toISOString(),+ success: result.success,+ durationMs: result.durationMs ?? Date.now() - startedAt,+ });+ // An explicit agent_update during the provider call still wins. The+ // measured value remains available from executionHistory in agent_health.+ if (mayUpdateStoredHealth) {+ current.health = summarizeAgentExecutions(current.executionHistory).health ?? current.health;+ }saveAgentStore(latest);};diff --git a/v3/@claude-flow/cli/src/mcp-tools/agent-health-metrics.ts b/v3/@claude-flow/cli/src/mcp-tools/agent-health-metrics.tsnew file mode 100644index 0000000000..00f65e5c45--- /dev/null+++ b/v3/@claude-flow/cli/src/mcp-tools/agent-health-metrics.ts@@ -0,0 +1,44 @@+/** Bounded execution evidence for agent_health. Registry records are not processes. */+export interface AgentExecutionSample {+ at: string;+ success: boolean;+ durationMs: number;+}++export const AGENT_HEALTH_WINDOW = 20;++function validSamples(value: unknown): AgentExecutionSample[] {+ if (!Array.isArray(value)) return [];+ return value.filter((sample): sample is AgentExecutionSample =>+ sample !== null && typeof sample === 'object' &&+ typeof sample.at === 'string' && typeof sample.success === 'boolean' &&+ typeof sample.durationMs === 'number' && Number.isFinite(sample.durationMs) && sample.durationMs >= 0,+ ).slice(-AGENT_HEALTH_WINDOW);+}++export function appendAgentExecution(value: unknown, sample: AgentExecutionSample): AgentExecutionSample[] {+ return [...validSamples(value), sample].slice(-AGENT_HEALTH_WINDOW);+}++export function summarizeAgentExecutions(value: unknown) {+ const samples = validSamples(value);+ const sampleCount = samples.length;+ const successes = samples.filter(sample => sample.success).length;+ const failures = sampleCount - successes;+ const durations = samples.map(sample => sample.durationMs).sort((a, b) => a - b);+ const percentile = (p: number): number | null =>+ sampleCount ? durations[Math.ceil(p * sampleCount) - 1] : null;+ return {+ health: sampleCount ? successes / sampleCount : null,+ errorRate: sampleCount ? failures / sampleCount : null,+ sampleCount,+ successes,+ failures,+ latency: {+ avg: sampleCount ? durations.reduce((sum, duration) => sum + duration, 0) / sampleCount : null,+ p50: percentile(0.5),+ p95: percentile(0.95),+ p99: percentile(0.99),+ },+ };+}diff --git a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.tsindex 4c737c994c..e4cb0b4f15 100644--- a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts@@ -11,6 +11,7 @@ import { readRecordStore } from './record-store.js';import { type MCPTool, getProjectCwd } from './types.js';import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';import { executeAgentTask } from './agent-execute-core.js';+import { AGENT_HEALTH_WINDOW, summarizeAgentExecutions, type AgentExecutionSample } from './agent-health-metrics.js';import { pheromoneAgentEligibility } from './swarm-tools.js';// Storage paths@@ -44,6 +45,7 @@ interface AgentRecord {/** ADR-148 — concrete OpenRouter slug when provider='openrouter'. */openrouterModel?: string;lastResult?: Record<string, unknown>;+ executionHistory?: AgentExecutionSample[];/*** ACOW — path to this agent's per-agent Copy-On-Write memory branch* (agenticow), set only when the agent was spawned with `memoryBase`. On@@ -788,7 +790,7 @@ export const agentTools: MCPTool[] = [},{name: 'agent_health',- description: 'Compute an agent\'s rolling health score (0-1) from recent task success ratio + response-latency p50/p95 + error rate. Use when native Task tool is wrong because you\'re running a long-lived agent (autonomous loop / hive-mind worker / federation peer) and need to detect degradation before the breaker trips it. For one-shot Task invocations there is no history to score. Pair with hooks_post-task so the scores stay current.',+ description: 'Report measured agent_execute provider-call outcomes over the last 20 calls: API success-ratio health (0-1), error rate, and response-latency p50/p95. This does not measure task correctness. Agents with no observed calls have unknown health; registration is not proof of a running process. Native Task and hooks_post-task outcomes are not recorded here.',category: 'agent',inputSchema: {type: 'object',@@ -805,61 +807,84 @@ export const agentTools: MCPTool[] = [const store = loadAgentStore();const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');- const threshold = (input.threshold as number) || 0.5;+ const threshold = input.threshold === undefined ? 0.5 : input.threshold as number;+ if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {+ return { error: 'threshold must be a finite number between 0 and 1' };+ }+ const healthStatus = (health: number | null): 'healthy' | 'degraded' | 'unhealthy' | 'unknown' =>+ health === null ? 'unknown' : health >= threshold ? 'healthy' : health >= 0.3 ? 'degraded' : 'unhealthy';if (input.agentId) {const agent = store.agents[input.agentId as string];if (agent) {+ const metrics = summarizeAgentExecutions(agent.executionHistory);return {agentId: agent.agentId,- health: agent.health,+ ...metrics,+ healthStatus: healthStatus(metrics.health),status: agent.status,- healthy: agent.health >= threshold,+ healthy: metrics.health === null ? null : metrics.health >= threshold,taskCount: agent.taskCount,- uptime: Date.now() - new Date(agent.createdAt).getTime(),+ uptime: null,+ registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),+ windowSize: AGENT_HEALTH_WINDOW,+ source: 'agent_execute',};}return { agentId: input.agentId, error: 'Agent not found' };}- const healthyAgents = agents.filter(a => a.health >= threshold);- const degradedAgents = agents.filter(a => a.health >= 0.3 && a.health < threshold);- const unhealthyAgents = agents.filter(a => a.health < 0.3);- const avgHealth = agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 1;+ const observed = agents.map(agent => ({ agent, metrics: summarizeAgentExecutions(agent.executionHistory) }));+ const healthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'healthy');+ const degradedAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'degraded');+ const unhealthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'unhealthy');+ const measuredAgents = observed.filter(({ metrics }) => metrics.health !== null);+ const unknownCount = agents.length - measuredAgents.length;+ const avgHealth = measuredAgents.length > 0+ ? measuredAgents.reduce((sum, { metrics }) => sum + metrics.health!, 0) / measuredAgents.length+ : null;return {// CLI expected fields- agents: agents.map(a => {- const uptime = Date.now() - new Date(a.createdAt).getTime();+ agents: observed.map(({ agent, metrics }) => {return {- id: a.agentId,- type: a.agentType,- health: a.health >= threshold ? 'healthy' : (a.health >= 0.3 ? 'degraded' : 'unhealthy'),- uptime,- tasks: { active: a.taskCount > 0 ? 1 : 0, queued: 0, completed: a.taskCount, failed: 0 },- _note: 'Per-agent OS metrics not available — use system_metrics for real CPU/memory',+ id: agent.agentId,+ type: agent.agentType,+ health: healthStatus(metrics.health),+ score: metrics.health,+ sampleCount: metrics.sampleCount,+ errorRate: metrics.errorRate,+ latency: metrics.latency,+ errors: { count: metrics.failures },+ uptime: null,+ registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),+ tasks: { active: agent.status === 'busy' ? 1 : 0, queued: null, completed: metrics.successes, failed: metrics.failures },+ _note: `Provider-call outcomes and latency cover only the last ${AGENT_HEALTH_WINDOW} agent_execute calls; task correctness, process liveness and CPU/memory are not observed`,};}),overall: {healthy: healthyAgents.length,degraded: degradedAgents.length,unhealthy: unhealthyAgents.length,+ unknown: unknownCount,cpu: null,memory: null,_note: 'Per-agent CPU/memory not available — use system_metrics for real OS-level stats',- score: Math.round(avgHealth * 100),+ score: avgHealth === null ? null : Math.round(avgHealth * 100),issues: unhealthyAgents.length,},// Additional fieldstotal: agents.length,+ observedCount: measuredAgents.length,+ unknownCount,healthyCount: healthyAgents.length,unhealthyCount: unhealthyAgents.length,threshold,avgHealth,- unhealthyAgents: unhealthyAgents.map(a => ({- agentId: a.agentId,- health: a.health,- status: a.status,+ unhealthyAgents: unhealthyAgents.map(({ agent, metrics }) => ({+ agentId: agent.agentId,+ health: metrics.health,+ status: agent.status,})),};},