Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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<AgentE
current.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.ts
new file mode 100644
index 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.ts
index 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 fields
total: 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,
})),
};
},