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): persist the name given to agent spawn (#4300) (#4301)

kevin44ac18676287
diff --git a/v3/@claude-flow/cli/__tests__/agent-spawn-name-4300.test.ts b/v3/@claude-flow/cli/__tests__/agent-spawn-name-4300.test.ts
new file mode 100644
index 0000000000..6e74f53ce2
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/agent-spawn-name-4300.test.ts
@@ -0,0 +1,78 @@
+/**
+ * Regression guard for ruvnet/ruflo#4300 — `agent spawn --name` was echoed
+ * by the CLI but never persisted: the CLI sent the name only as
+ * `metadata.name`, and the `agent_spawn` handler never read it, so the
+ * AgentRecord in `.claude-flow/agents/store.json` had no `name` and
+ * ruflo-console could only label agents by type.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { agentTools } from '../src/mcp-tools/agent-tools.js';
+
+const tool = (name: string) => {
+ const t = agentTools.find(t => t.name === name);
+ if (!t) throw new Error(`MCP tool not registered: ${name}`);
+ return t;
+};
+
+function readStoredAgents(dir: string): Record<string, { name?: string; agentType: string }> {
+ const raw = JSON.parse(readFileSync(join(dir, '.claude-flow', 'agents', 'store.json'), 'utf8'));
+ return raw.agents;
+}
+
+describe('#4300 — agent_spawn persists the agent name', () => {
+ let dir: string;
+ let prevCwd: string | undefined;
+
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'ruflo-4300-'));
+ prevCwd = process.env.CLAUDE_FLOW_CWD;
+ process.env.CLAUDE_FLOW_CWD = dir;
+ });
+
+ afterEach(() => {
+ if (prevCwd === undefined) delete process.env.CLAUDE_FLOW_CWD;
+ else process.env.CLAUDE_FLOW_CWD = prevCwd;
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('stores a top-level name and reports it from agent_list and agent_status', async () => {
+ const spawned = await tool('agent_spawn').handler({
+ agentType: 'coordinator',
+ name: 'game-director',
+ }) as { success: boolean; agentId: string; name?: string };
+
+ expect(spawned.success).toBe(true);
+ expect(spawned.name).toBe('game-director');
+ expect(readStoredAgents(dir)[spawned.agentId].name).toBe('game-director');
+
+ const list = await tool('agent_list').handler({}) as { agents: Array<{ agentId: string; name?: string }> };
+ expect(list.agents.find(a => a.agentId === spawned.agentId)?.name).toBe('game-director');
+
+ const status = await tool('agent_status').handler({ agentId: spawned.agentId }) as { name?: string };
+ expect(status.name).toBe('game-director');
+ });
+
+ it('falls back to metadata.name, which older CLI builds send', async () => {
+ const spawned = await tool('agent_spawn').handler({
+ agentType: 'architect',
+ metadata: { name: 'technical-director', capabilities: [] },
+ }) as { success: boolean; agentId: string };
+
+ expect(spawned.success).toBe(true);
+ expect(readStoredAgents(dir)[spawned.agentId].name).toBe('technical-director');
+ });
+
+ it('leaves name off the record when none is given', async () => {
+ const spawned = await tool('agent_spawn').handler({ agentType: 'coder' }) as { agentId: string };
+ expect(readStoredAgents(dir)[spawned.agentId]).not.toHaveProperty('name');
+ });
+
+ it('rejects a non-string name', async () => {
+ const spawned = await tool('agent_spawn').handler({ agentType: 'coder', name: 42 }) as { success: boolean; error?: string };
+ expect(spawned.success).toBe(false);
+ expect(spawned.error).toMatch(/name must be a string/);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/agent.ts b/v3/@claude-flow/cli/src/commands/agent.ts
index b0ae163eb7..f391aeddb2 100644
--- a/v3/@claude-flow/cli/src/commands/agent.ts
+++ b/v3/@claude-flow/cli/src/commands/agent.ts
@@ -154,6 +154,7 @@ const spawnCommand: Command = {
}>('agent_spawn', {
agentType,
id: agentName,
+ name: agentName,
config: {
provider: ctx.flags.provider || 'anthropic',
model: ctx.flags.model,
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 7037dbecc8..0d7ebd5e2c 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts
@@ -30,6 +30,8 @@ type ClaudeModel = 'haiku' | 'sonnet' | 'opus' | 'opus-4.7' | 'inherit';
interface AgentRecord {
agentId: string;
agentType: string;
+ /** #4300 — display name given at spawn (`agent spawn --name`). */
+ name?: string;
status: 'idle' | 'busy' | 'terminated';
health: number;
taskCount: number;
@@ -288,6 +290,7 @@ export const agentTools: MCPTool[] = [
properties: {
agentType: { type: 'string', description: 'Type of agent to spawn' },
agentId: { type: 'string', description: 'Optional custom agent ID' },
+ name: { type: 'string', description: 'Optional display name for the agent (shown by agent_list, agent_status and ruflo-console)' },
// #2085 — accept swarmId so spawned agents register in the
// swarm.agents array that swarm_status reports. Omit to register
// with the most-recently-created swarm.
@@ -314,6 +317,18 @@ export const agentTools: MCPTool[] = [
const agentId = (input.agentId as string) || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
const agentType = input.agentType as string;
+ // #4300 — older callers (including `agent spawn` before this fix) send
+ // the name only as metadata.name.
+ const metadata = input.metadata as Record<string, unknown> | undefined;
+ const rawName = input.name ?? metadata?.name;
+ let name: string | undefined;
+ if (rawName !== undefined && rawName !== '') {
+ const vName = validateText(rawName, 'name', 200);
+ if (!vName.valid) {
+ return { success: false, error: `Input validation failed: ${vName.error}` };
+ }
+ name = vName.sanitized;
+ }
const config = (input.config as Record<string, unknown>) || {};
// Add explicit model to config if provided
@@ -345,6 +360,7 @@ export const agentTools: MCPTool[] = [
const agent: AgentRecord = {
agentId,
agentType,
+ ...(name ? { name } : {}),
status: 'idle',
health: 1.0,
taskCount: 0,
@@ -434,6 +450,7 @@ export const agentTools: MCPTool[] = [
success: true,
agentId,
agentType: agent.agentType,
+ ...(agent.name ? { name: agent.name } : {}),
model: agent.model,
modelRoutedBy: routingResult.routedBy,
...(routingResult.modelId ? { modelId: routingResult.modelId } : {}),
@@ -592,6 +609,7 @@ export const agentTools: MCPTool[] = [
return {
agentId: agent.agentId,
agentType: agent.agentType,
+ ...(agent.name ? { name: agent.name } : {}),
status: agent.status,
health: agent.health,
taskCount: agent.taskCount,
@@ -648,6 +666,7 @@ export const agentTools: MCPTool[] = [
agents: agents.map(a => ({
agentId: a.agentId,
agentType: a.agentType,
+ ...(a.name ? { name: a.name } : {}),
status: a.status,
health: a.health,
taskCount: a.taskCount,