@aigentic/claude-flow 3.7.0-alpha.69

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js

@@ -0,0 +1,716 @@
+/**
+ * Agent MCP Tools for CLI
+ *
+ * Tool definitions for agent lifecycle management with file persistence.
+ * Includes model routing integration for intelligent model selection.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectCwd } from './types.js';
+import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';
+import { executeAgentTask } from './agent-execute-core.js';
+// Storage paths
+const STORAGE_DIR = '.claude-flow';
+const AGENT_DIR = 'agents';
+const AGENT_FILE = 'store.json';
+// #1916: hive-mind_spawn writes its workers to `.claude-flow/agents.json`
+// (a *different* file from the canonical `.claude-flow/agents/store.json`
+// used here). agent_status / agent_list / agent_logs merge that store so a
+// hive-spawned worker is resolvable instead of returning `not_found`.
+const HIVE_AGENT_FILE = 'agents.json';
+function getAgentDir() {
+    return join(getProjectCwd(), STORAGE_DIR, AGENT_DIR);
+}
+function getAgentPath() {
+    return join(getAgentDir(), AGENT_FILE);
+}
+function ensureAgentDir() {
+    const dir = getAgentDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function loadAgentStore() {
+    try {
+        const path = getAgentPath();
+        if (existsSync(path)) {
+            const data = readFileSync(path, 'utf-8');
+            return JSON.parse(data);
+        }
+    }
+    catch {
+        // Return empty store on error
+    }
+    return { agents: {}, version: '3.0.0' };
+}
+function saveAgentStore(store) {
+    ensureAgentDir();
+    writeFileSync(getAgentPath(), JSON.stringify(store, null, 2), 'utf-8');
+}
+// #1916: read hive-mind-spawned workers from `.claude-flow/agents.json`.
+function getHiveAgentPath() {
+    return join(getProjectCwd(), STORAGE_DIR, HIVE_AGENT_FILE);
+}
+function loadHiveAgents() {
+    try {
+        const path = getHiveAgentPath();
+        if (existsSync(path)) {
+            const data = JSON.parse(readFileSync(path, 'utf-8'));
+            if (data && typeof data.agents === 'object' && data.agents) {
+                return data.agents;
+            }
+        }
+    }
+    catch {
+        // Ignore — hive store is optional/best-effort.
+    }
+    return {};
+}
+/**
+ * #1916: merged view of every tracked agent — the canonical agent store
+ * plus hive-mind-spawned workers. On an id collision the canonical record
+ * wins (it carries model-routing + lastResult that the hive store omits).
+ */
+function loadAllAgents() {
+    return { ...loadHiveAgents(), ...loadAgentStore().agents };
+}
+// Default model mappings for agent types (can be overridden)
+const AGENT_TYPE_MODEL_DEFAULTS = {
+    // Complex agents → opus
+    'architect': 'opus',
+    'security-architect': 'opus',
+    'system-architect': 'opus',
+    'core-architect': 'opus',
+    // Medium complexity → sonnet
+    'coder': 'sonnet',
+    'reviewer': 'sonnet',
+    'researcher': 'sonnet',
+    'tester': 'sonnet',
+    'analyst': 'sonnet',
+    // Simple/fast agents → haiku
+    'formatter': 'haiku',
+    'linter': 'haiku',
+    'documenter': 'haiku',
+};
+// Lazy-loaded model router
+let modelRouterInstance = null;
+async function getModelRouter() {
+    if (!modelRouterInstance) {
+        try {
+            const { getModelRouter } = await import('../ruvector/model-router.js');
+            modelRouterInstance = getModelRouter();
+        }
+        catch (e) {
+            // Log but don't fail - model router is optional
+            console.error('[agent-tools] Model router load failed:', e.message);
+        }
+    }
+    return modelRouterInstance;
+}
+/**
+ * Determine model for agent based on (ADR-026 3-tier routing):
+ * 1. Explicit model in config
+ * 2. Enhanced task-based routing with Agent Booster AST (if task provided)
+ * 3. Agent type defaults
+ * 4. Fallback to sonnet
+ */
+async function determineAgentModel(agentType, config, task) {
+    // 1. Explicit model in config
+    if (config.model && ['haiku', 'sonnet', 'opus', 'inherit'].includes(config.model)) {
+        return { model: config.model, routedBy: 'explicit' };
+    }
+    // 2. Enhanced task-based routing with Agent Booster AST
+    if (task) {
+        try {
+            // Try enhanced router first (includes Agent Booster detection)
+            const { getEnhancedModelRouter } = await import('../ruvector/enhanced-model-router.js');
+            const enhancedRouter = getEnhancedModelRouter();
+            const routeResult = await enhancedRouter.route(task, { filePath: config.filePath });
+            if (routeResult.tier === 1 && routeResult.canSkipLLM) {
+                // Agent Booster can handle this task
+                return {
+                    model: 'haiku', // Use haiku as fallback if AB fails
+                    routedBy: 'agent-booster',
+                    canSkipLLM: true,
+                    agentBoosterIntent: routeResult.agentBoosterIntent?.type,
+                    tier: 1,
+                };
+            }
+            return {
+                model: routeResult.model,
+                routedBy: 'router',
+                tier: routeResult.tier,
+            };
+        }
+        catch {
+            // Enhanced router not available, try basic router
+            const router = await getModelRouter();
+            if (router) {
+                try {
+                    const result = await router.route(task);
+                    return { model: result.model, routedBy: 'router' };
+                }
+                catch {
+                    // Fall through to defaults on router error
+                }
+            }
+        }
+    }
+    // 3. Agent type defaults
+    const defaultModel = AGENT_TYPE_MODEL_DEFAULTS[agentType];
+    if (defaultModel) {
+        return { model: defaultModel, routedBy: 'default' };
+    }
+    // 4. Fallback to sonnet (balanced)
+    return { model: 'sonnet', routedBy: 'default' };
+}
+export const agentTools = [
+    {
+        name: 'agent_spawn',
+        description: 'Spawn a Ruflo-tracked agent with cost attribution + memory persistence + swarm coordination. Use when native Task tool is wrong because you need (a) cost tracking per agent in the cost-tracking namespace, (b) cross-session learning via the patterns namespace, or (c) coordination with other agents in a swarm topology (hierarchical / mesh / consensus). For one-shot subtasks with no learning loop, native Task is fine. Pair with hooks_route to pick the right model first.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentType: { type: 'string', description: 'Type of agent to spawn' },
+                agentId: { type: 'string', description: 'Optional custom agent ID' },
+                config: { type: 'object', description: 'Agent configuration' },
+                domain: { type: 'string', description: 'Agent domain' },
+                model: {
+                    type: 'string',
+                    enum: ['haiku', 'sonnet', 'opus', 'inherit'],
+                    description: 'Claude model to use (haiku=fast/cheap, sonnet=balanced, opus=most capable)'
+                },
+                task: { type: 'string', description: 'Task description for intelligent model routing' },
+            },
+            required: ['agentType'],
+        },
+        handler: async (input) => {
+            // Validate user-provided input (#1425: wire security validators to runtime)
+            const validation = await validateAgentSpawn(input);
+            if (!validation.valid) {
+                return { success: false, error: `Input validation failed: ${validation.errors.join('; ')}` };
+            }
+            const store = loadAgentStore();
+            const agentId = input.agentId || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const agentType = input.agentType;
+            const config = input.config || {};
+            // Add explicit model to config if provided
+            if (input.model) {
+                config.model = input.model;
+            }
+            // Get task from either top-level or config (CLI passes it in config.task)
+            const task = input.task || config.task || undefined;
+            // Determine model using ADR-026 3-tier routing logic
+            const routingResult = await determineAgentModel(agentType, config, task);
+            const agent = {
+                agentId,
+                agentType,
+                status: 'idle',
+                health: 1.0,
+                taskCount: 0,
+                config,
+                createdAt: new Date().toISOString(),
+                domain: input.domain,
+                model: routingResult.model,
+                modelRoutedBy: routingResult.routedBy,
+            };
+            store.agents[agentId] = agent;
+            saveAgentStore(store);
+            // Record agent in graph database (ADR-087, best-effort)
+            try {
+                const { addNode } = await import('../ruvector/graph-backend.js');
+                await addNode({ id: agentId, type: 'agent', name: agentType });
+            }
+            catch { /* graph-node not available */ }
+            // Include Agent Booster routing info if applicable
+            const response = {
+                success: true,
+                agentId,
+                agentType: agent.agentType,
+                model: agent.model,
+                modelRoutedBy: routingResult.routedBy,
+                status: 'registered',
+                createdAt: agent.createdAt,
+                note: 'Agent registered for coordination. Three execution paths: ' +
+                    '(1) call agent_execute(agentId, prompt) — direct LLM call via Anthropic Messages API (requires ANTHROPIC_API_KEY); ' +
+                    '(2) Claude Code Task tool — spawns a real subagent; ' +
+                    '(3) claude -p — headless background instance.',
+            };
+            // Add Agent Booster info if task can skip LLM
+            if (routingResult.canSkipLLM) {
+                response.canSkipLLM = true;
+                response.agentBoosterIntent = routingResult.agentBoosterIntent;
+                response.tier = routingResult.tier;
+                response.note = `Agent Booster can handle "${routingResult.agentBoosterIntent}" - use agent_booster_edit_file MCP tool`;
+            }
+            else if (routingResult.tier) {
+                response.tier = routingResult.tier;
+            }
+            return response;
+        },
+    },
+    {
+        // ADR-095 G1: real LLM execution via the agent registry. Previously
+        // agent_spawn registered metadata but nothing dispatched work to a
+        // provider — the wire between AnthropicProvider and the agent
+        // registry was missing, as the April audit (@roman-rr) called out.
+        // agent_execute closes that wire by reading the agent's configured
+        // model, calling the Anthropic Messages API directly via fetch, and
+        // updating the agent record with lastResult / taskCount / status.
+        // No mock — actual HTTP request to api.anthropic.com.
+        name: 'agent_execute',
+        description: 'Run a task on a previously-spawned agent_spawn record via the Anthropic Messages API with that agent\'s configured model. Use when native Task tool is wrong because (a) you need the spawned agent\'s persistent config (model, instructions, cost-tracking attribution) to apply to this turn, (b) the result needs to feed back into the agent\'s lifecycle (taskCount, lastResult, swarm-coordinated state), or (c) you want explicit model routing via the spawn record\'s `model` field instead of inheriting. For one-shot Claude prompts without a tracked agent, native Task is fine. Requires ANTHROPIC_API_KEY in env.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of the spawned agent' },
+                prompt: { type: 'string', description: 'Task / prompt for the agent to execute' },
+                systemPrompt: { type: 'string', description: 'Optional system prompt (overrides agent default)' },
+                maxTokens: { type: 'number', description: 'Max output tokens (default 1024)' },
+                temperature: { type: 'number', description: 'Sampling temperature 0..1 (default 0.7)' },
+            },
+            required: ['agentId', 'prompt'],
+        },
+        handler: async (input) => {
+            const vId = validateIdentifier(input.agentId, 'agentId');
+            if (!vId.valid)
+                return { success: false, error: `Input validation failed: ${vId.error}` };
+            const vP = validateText(input.prompt, 'prompt');
+            if (!vP.valid)
+                return { success: false, error: `Input validation failed: ${vP.error}` };
+            // Delegate to the shared core (also used by the workflow runtime).
+            return executeAgentTask({
+                agentId: input.agentId,
+                prompt: input.prompt,
+                systemPrompt: input.systemPrompt,
+                maxTokens: input.maxTokens,
+                temperature: input.temperature,
+                timeoutMs: input.timeoutMs,
+            });
+        },
+    },
+    {
+        name: 'agent_terminate',
+        description: 'Remove a Ruflo-tracked agent from the registry and free its swarm slot. Use when you need to (a) clean up a spawned agent so its cost-tracking row finalizes, (b) reclaim a swarm-topology slot for another agent, or (c) end a stuck agent without restarting the whole swarm. For one-shot Task tool invocations that already self-terminate, this tool is not needed. Pair with agent_list first to confirm the agentId.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of agent to terminate' },
+                force: { type: 'boolean', description: 'Force immediate termination' },
+            },
+            required: ['agentId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.agentId, 'agentId');
+            if (!v.valid)
+                return { success: false, error: `Input validation failed: ${v.error}` };
+            const store = loadAgentStore();
+            const agentId = input.agentId;
+            if (store.agents[agentId]) {
+                store.agents[agentId].status = 'terminated';
+                saveAgentStore(store);
+                return {
+                    success: true,
+                    agentId,
+                    terminated: true,
+                    terminatedAt: new Date().toISOString(),
+                };
+            }
+            return {
+                success: false,
+                agentId,
+                error: 'Agent not found',
+            };
+        },
+    },
+    {
+        name: 'agent_status',
+        description: 'Read the lifecycle state of a single tracked agent: idle/running/stopped, current taskCount, lastResult, model, health score. Use when native Task tool is wrong because you need agent-level state (status across turns, accumulated taskCount, last error, swarm coordination) rather than a one-shot response. For inspecting a Task you just ran, native Task output is fine. Pair with agent_list to find the agentId first.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of agent' },
+            },
+            required: ['agentId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.agentId, 'agentId');
+            if (!v.valid)
+                return { agentId: input.agentId, status: 'not_found', error: `Input validation failed: ${v.error}` };
+            const agentId = input.agentId;
+            const agent = loadAllAgents()[agentId]; // #1916: includes hive-mind-spawned workers
+            if (agent) {
+                return {
+                    agentId: agent.agentId,
+                    agentType: agent.agentType,
+                    status: agent.status,
+                    health: agent.health,
+                    taskCount: agent.taskCount,
+                    createdAt: agent.createdAt,
+                    domain: agent.domain,
+                    lastResult: agent.lastResult || null,
+                };
+            }
+            return {
+                agentId,
+                status: 'not_found',
+                error: 'Agent not found',
+            };
+        },
+    },
+    {
+        name: 'agent_list',
+        description: 'List every Ruflo-tracked agent in the registry with its type, model, status, and taskCount. Use when native Task tool is wrong because you need to see the swarm-wide agent inventory across turns (which agents exist, their roles, their cost-tracking handles) rather than spawn a new one-shot Task. Filter by status/domain/agentType if needed. For starting a fresh single-shot subagent, native Task is fine.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', description: 'Filter by status' },
+                domain: { type: 'string', description: 'Filter by domain' },
+                includeTerminated: { type: 'boolean', description: 'Include terminated agents' },
+            },
+        },
+        handler: async (input) => {
+            if (input.status) {
+                const v = validateIdentifier(input.status, 'status');
+                if (!v.valid)
+                    return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+            }
+            if (input.domain) {
+                const v = validateIdentifier(input.domain, 'domain');
+                if (!v.valid)
+                    return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+            }
+            let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
+            // Filter by status
+            if (input.status) {
+                agents = agents.filter(a => a.status === input.status);
+            }
+            else if (!input.includeTerminated) {
+                agents = agents.filter(a => a.status !== 'terminated');
+            }
+            // Filter by domain
+            if (input.domain) {
+                agents = agents.filter(a => a.domain === input.domain);
+            }
+            return {
+                agents: agents.map(a => ({
+                    agentId: a.agentId,
+                    agentType: a.agentType,
+                    status: a.status,
+                    health: a.health,
+                    taskCount: a.taskCount,
+                    createdAt: a.createdAt,
+                    domain: a.domain,
+                })),
+                total: agents.length,
+                filters: {
+                    status: input.status,
+                    domain: input.domain,
+                    includeTerminated: input.includeTerminated,
+                },
+            };
+        },
+    },
+    {
+        name: 'agent_pool',
+        description: 'Manage a fixed-size warm pool of pre-spawned agents to skip cold-start cost on bursty workloads. Use when native Task is wrong because (a) you have a queue of similar tasks and want to amortize spawn latency, (b) cost-tracking wants stable agentIds across requests, or (c) swarm topology requires a known agent count at all times. For one-shot work, just call agent_spawn or native Task. Pool sizes and warm/idle thresholds are set per-pool.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['status', 'scale', 'drain', 'fill'], description: 'Pool action' },
+                targetSize: { type: 'number', description: 'Target pool size (for scale action)' },
+                agentType: { type: 'string', description: 'Agent type filter' },
+            },
+            required: ['action'],
+        },
+        handler: async (input) => {
+            if (input.agentType) {
+                const v = validateIdentifier(input.agentType, 'agentType');
+                if (!v.valid)
+                    return { action: input.action, error: `Input validation failed: ${v.error}` };
+            }
+            const store = loadAgentStore();
+            const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
+            const action = input.action || 'status'; // Default to status
+            if (action === 'status') {
+                const byType = {};
+                const byStatus = {};
+                for (const agent of agents) {
+                    byType[agent.agentType] = (byType[agent.agentType] || 0) + 1;
+                    byStatus[agent.status] = (byStatus[agent.status] || 0) + 1;
+                }
+                const idleAgents = agents.filter(a => a.status === 'idle').length;
+                const busyAgents = agents.filter(a => a.status === 'busy').length;
+                const utilization = agents.length > 0 ? busyAgents / agents.length : 0;
+                return {
+                    action,
+                    // CLI expected fields
+                    poolId: 'agent-pool-default',
+                    currentSize: agents.length,
+                    minSize: input.min || 0,
+                    maxSize: input.max || 100,
+                    autoScale: input.autoScale ?? false,
+                    utilization,
+                    agents: agents.map(a => ({
+                        id: a.agentId,
+                        type: a.agentType,
+                        status: a.status,
+                    })),
+                    // Additional fields
+                    id: 'agent-pool-default',
+                    size: agents.length,
+                    totalAgents: agents.length,
+                    byType,
+                    byStatus,
+                    avgHealth: agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 0,
+                };
+            }
+            if (action === 'scale') {
+                const targetSize = input.targetSize || 5;
+                const agentType = input.agentType || 'worker';
+                const currentSize = agents.filter(a => a.agentType === agentType).length;
+                const delta = targetSize - currentSize;
+                const added = [];
+                const removed = [];
+                if (delta > 0) {
+                    for (let i = 0; i < delta; i++) {
+                        const agentId = `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                        store.agents[agentId] = {
+                            agentId,
+                            agentType,
+                            status: 'idle',
+                            health: 1.0,
+                            taskCount: 0,
+                            config: {},
+                            createdAt: new Date().toISOString(),
+                        };
+                        added.push(agentId);
+                    }
+                }
+                else if (delta < 0) {
+                    const toRemove = agents.filter(a => a.agentType === agentType && a.status === 'idle').slice(0, -delta);
+                    for (const agent of toRemove) {
+                        store.agents[agent.agentId].status = 'terminated';
+                        removed.push(agent.agentId);
+                    }
+                }
+                saveAgentStore(store);
+                return {
+                    action,
+                    agentType,
+                    previousSize: currentSize,
+                    targetSize,
+                    newSize: currentSize + delta,
+                    added,
+                    removed,
+                };
+            }
+            if (action === 'drain') {
+                const agentType = input.agentType;
+                let drained = 0;
+                for (const agent of agents) {
+                    if (!agentType || agent.agentType === agentType) {
+                        if (agent.status === 'idle') {
+                            store.agents[agent.agentId].status = 'terminated';
+                            drained++;
+                        }
+                    }
+                }
+                saveAgentStore(store);
+                return {
+                    action,
+                    agentType: agentType || 'all',
+                    drained,
+                    remaining: agents.length - drained,
+                };
+            }
+            return { action, error: 'Unknown action' };
+        },
+    },
+    {
+        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.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'Specific agent ID (optional)' },
+                threshold: { type: 'number', description: 'Health threshold (0-1)' },
+            },
+        },
+        handler: async (input) => {
+            if (input.agentId) {
+                const v = validateIdentifier(input.agentId, 'agentId');
+                if (!v.valid)
+                    return { agentId: input.agentId, error: `Input validation failed: ${v.error}` };
+            }
+            const store = loadAgentStore();
+            const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
+            const threshold = input.threshold || 0.5;
+            if (input.agentId) {
+                const agent = store.agents[input.agentId];
+                if (agent) {
+                    return {
+                        agentId: agent.agentId,
+                        health: agent.health,
+                        status: agent.status,
+                        healthy: agent.health >= threshold,
+                        taskCount: agent.taskCount,
+                        uptime: Date.now() - new Date(agent.createdAt).getTime(),
+                    };
+                }
+                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;
+            return {
+                // CLI expected fields
+                agents: agents.map(a => {
+                    const uptime = Date.now() - new Date(a.createdAt).getTime();
+                    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',
+                    };
+                }),
+                overall: {
+                    healthy: healthyAgents.length,
+                    degraded: degradedAgents.length,
+                    unhealthy: unhealthyAgents.length,
+                    cpu: null,
+                    memory: null,
+                    _note: 'Per-agent CPU/memory not available — use system_metrics for real OS-level stats',
+                    score: Math.round(avgHealth * 100),
+                    issues: unhealthyAgents.length,
+                },
+                // Additional fields
+                total: agents.length,
+                healthyCount: healthyAgents.length,
+                unhealthyCount: unhealthyAgents.length,
+                threshold,
+                avgHealth,
+                unhealthyAgents: unhealthyAgents.map(a => ({
+                    agentId: a.agentId,
+                    health: a.health,
+                    status: a.status,
+                })),
+            };
+        },
+    },
+    {
+        name: 'agent_update',
+        description: 'Mutate a tracked agent\'s config (model, instructions, status, health) without re-spawning. Use when native Task tool is wrong because the agent already has accumulated state (taskCount, swarm membership, cost-tracking attribution) and you only need to tweak one field — for example, promoting an idle agent to running on a new task, or rotating its model from haiku to sonnet mid-loop. For a brand-new subagent, agent_spawn (or native Task) is the right call.',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of agent' },
+                status: { type: 'string', description: 'New status' },
+                health: { type: 'number', description: 'Health value (0-1)' },
+                taskCount: { type: 'number', description: 'Task count' },
+                config: { type: 'object', description: 'Config updates' },
+            },
+            required: ['agentId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.agentId, 'agentId');
+            if (!v.valid)
+                return { success: false, agentId: input.agentId, error: `Input validation failed: ${v.error}` };
+            if (input.status) {
+                const vs = validateIdentifier(input.status, 'status');
+                if (!vs.valid)
+                    return { success: false, agentId: input.agentId, error: `Input validation failed: ${vs.error}` };
+            }
+            const store = loadAgentStore();
+            const agentId = input.agentId;
+            const agent = store.agents[agentId];
+            if (agent) {
+                if (input.status)
+                    agent.status = input.status;
+                if (typeof input.health === 'number')
+                    agent.health = input.health;
+                if (typeof input.taskCount === 'number')
+                    agent.taskCount = input.taskCount;
+                if (input.config) {
+                    agent.config = { ...agent.config, ...input.config };
+                }
+                saveAgentStore(store);
+                return {
+                    success: true,
+                    agentId,
+                    updated: true,
+                    agent: {
+                        agentId: agent.agentId,
+                        status: agent.status,
+                        health: agent.health,
+                        taskCount: agent.taskCount,
+                    },
+                };
+            }
+            return {
+                success: false,
+                agentId,
+                error: 'Agent not found',
+            };
+        },
+    },
+    {
+        // #1916 — the `ruflo agent logs <id>` CLI subcommand and the guidance
+        // surface both reference an `agent_logs` MCP tool that was never
+        // registered, so it errored with `MCP tool not found: agent_logs`.
+        // This is the registered handler. Note: agents don't yet keep a
+        // structured per-agent activity log (that lands with hive worker
+        // execution wiring — see #1916), so for now we surface the agent's
+        // last task result as a single synthetic entry, or an explicit empty
+        // response. The shape matches what the CLI `logs` subcommand expects:
+        // `{ agentId, entries: [{timestamp,level,message,context?}], total }`.
+        name: 'agent_logs',
+        description: 'Return recorded activity-log entries for a tracked agent (idle/running history, last task result). Use when native Task tool is wrong because you need the agent\'s log across turns (what it did, last error/result, swarm context) rather than a one-shot Task transcript. For a Task you just ran, native Task output is fine. Pair with agent_list to find the agentId. (Hive-mind-spawned workers are resolved here too.) Today this returns the last task result as a synthetic entry — full per-agent activity logs land with hive worker execution wiring (ruvnet/ruflo#1916).',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of agent' },
+                tail: { type: 'number', description: 'Max recent entries to return (default 50)' },
+                level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'], description: 'Minimum log level (currently advisory — entries are synthetic)' },
+                since: { type: 'string', description: 'Show logs since, e.g. "1h" / "30m" (currently advisory)' },
+            },
+            required: ['agentId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.agentId, 'agentId');
+            if (!v.valid)
+                return { agentId: input.agentId, entries: [], total: 0, error: `Input validation failed: ${v.error}` };
+            const agentId = input.agentId;
+            const agent = loadAllAgents()[agentId]; // #1916: includes hive-mind-spawned workers
+            if (!agent) {
+                return { agentId, entries: [], total: 0, error: 'Agent not found' };
+            }
+            const entries = [];
+            entries.push({ timestamp: agent.createdAt, level: 'info', message: `agent created (type=${agent.agentType}, status=${agent.status})` });
+            if (agent.lastResult) {
+                entries.push({ timestamp: agent.createdAt, level: 'info', message: 'last task result', context: agent.lastResult });
+            }
+            const tail = typeof input.tail === 'number' && input.tail > 0 ? Math.floor(input.tail) : 50;
+            const sliced = entries.slice(-tail);
+            return {
+                agentId: agent.agentId,
+                entries: sliced,
+                total: entries.length,
+                note: 'per-agent activity logging is not yet wired; entries are synthetic (ruvnet/ruflo#1916)',
+            };
+        },
+    },
+];
+//# sourceMappingURL=agent-tools.js.map