@swarp/cli 0.0.1

package/src/mcp-server/index.mjs

@@ -0,0 +1,259 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { DispatchClient } from './dispatch.mjs';
+import { loadConfig } from '../config.mjs';
+import { auditConfigs } from '../generator/audit.mjs';
+import { generateRunnerConfig } from '../generator/generate.mjs';
+
+export async function startMcpServer() {
+  const config = loadConfig('.swarp.json');
+  const client = new DispatchClient(config.router_url);
+
+  const server = new Server(
+    { name: 'swarp', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  const agentTools = [];
+  let agentList = [];
+
+  try {
+    const { agents } = await client.listAgents();
+    agentList = agents ?? [];
+    for (const agent of agentList) {
+      agentTools.push(buildAgentTool(agent));
+    }
+  } catch (err) {
+    console.error(`[swarp] Warning: could not reach router at ${config.router_url}: ${err.message}`);
+  }
+
+  const localTools = buildLocalTools(config);
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: [...agentTools, ...localTools] };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: toolArgs } = req.params;
+
+    const agent = agentList.find((a) => a.name === name);
+    if (agent) {
+      return handleAgentDispatch(client, agent.name, toolArgs);
+    }
+
+    if (name === 'swarm_audit') return handleAudit(config, toolArgs);
+    if (name === 'swarm_generate') return handleGenerate(config, toolArgs);
+    if (name === 'swarm_status') return handleStatus(client, toolArgs);
+    if (name === 'swarm_deploy') return handleDeploy(config, toolArgs);
+
+    return {
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+function buildAgentTool(agent) {
+  const modeNames = (agent.modes ?? []).map((m) => m.name);
+  return {
+    name: agent.name,
+    description: `Dispatch a task to the ${agent.name} agent (${agent.role ?? 'agent'}). Available modes: ${modeNames.join(', ') || 'any'}`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: {
+          type: 'string',
+          description: `Mode to run. One of: ${modeNames.join(', ') || 'any'}`,
+        },
+        params: {
+          type: 'object',
+          description: 'Mode-specific parameters as key-value pairs',
+          additionalProperties: { type: 'string' },
+        },
+        session_id: {
+          type: 'string',
+          description: 'Optional session ID to continue an existing conversation',
+        },
+      },
+      required: ['mode'],
+    },
+  };
+}
+
+function buildLocalTools(config) {
+  return [
+    {
+      name: 'swarm_audit',
+      description: 'Audit all agent.yaml files for schema errors and warnings',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          agents_dir: {
+            type: 'string',
+            description: 'Directory containing agent subdirectories (default: config agents_dir)',
+          },
+        },
+      },
+    },
+    {
+      name: 'swarm_generate',
+      description: 'Generate runner configs from agent.yaml files',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          agents_dir: {
+            type: 'string',
+            description: 'Directory containing agent subdirectories (default: config agents_dir)',
+          },
+        },
+      },
+    },
+    {
+      name: 'swarm_status',
+      description: 'Get live status of an agent or all agents via gRPC',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          agent: {
+            type: 'string',
+            description: 'Agent name (omit for all agents)',
+          },
+        },
+      },
+    },
+    {
+      name: 'swarm_deploy',
+      description: 'Deploy an agent sprite via the Sprites API. Requires SWARP_SPRITES_TOKEN.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          agent: {
+            type: 'string',
+            description: 'Agent name to deploy',
+          },
+        },
+        required: ['agent'],
+      },
+      annotations: {
+        destructiveHint: true,
+      },
+    },
+  ];
+}
+
+async function handleAgentDispatch(client, agentName, toolArgs) {
+  const { mode, params = {}, session_id: sessionId = '' } = toolArgs ?? {};
+  const events = [];
+
+  try {
+    for await (const event of client.dispatchTask(
+      agentName,
+      { structured: { mode, params } },
+      sessionId,
+    )) {
+      events.push(event);
+    }
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Dispatch error: ${err.message}` }],
+      isError: true,
+    };
+  }
+
+  const last = events.at(-1);
+  const text = last?.result?.summary ?? last?.text ?? '';
+  return { content: [{ type: 'text', text }] };
+}
+
+async function handleAudit(config, toolArgs) {
+  const agentsDir = toolArgs?.agents_dir ?? config.agents_dir ?? 'agents';
+  try {
+    const results = await auditConfigs(agentsDir);
+    const lines = [];
+    for (const result of results) {
+      lines.push(`=== ${result.agent} ===`);
+      for (const c of result.checks) {
+        const icon = c.status === 'pass' ? '\u2713' : c.status === 'fail' ? '\u2717' : '\u25cb';
+        lines.push(`  ${icon} [${c.severity.toUpperCase().slice(0, 3)}] ${c.name}: ${c.message}`);
+      }
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Audit error: ${err.message}` }], isError: true };
+  }
+}
+
+async function handleGenerate(config, toolArgs) {
+  const agentsDir = toolArgs?.agents_dir ?? config.agents_dir ?? 'agents';
+  try {
+    await generateRunnerConfig(agentsDir);
+    return { content: [{ type: 'text', text: `Runner configs generated for agents in ${agentsDir}` }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Generate error: ${err.message}` }], isError: true };
+  }
+}
+
+async function handleStatus(client, toolArgs) {
+  const { agent } = toolArgs ?? {};
+  try {
+    if (agent) {
+      const status = await client.getAgentStatus(agent);
+      return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+    }
+    const { agents } = await client.listAgents();
+    const lines = (agents ?? []).map(
+      (a) => `${a.name} (${a.online ? 'online' : 'offline'}) — ${a.modes?.length ?? 0} mode(s)`,
+    );
+    return { content: [{ type: 'text', text: lines.join('\n') || 'No agents registered' }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Status error: ${err.message}` }], isError: true };
+  }
+}
+
+async function handleDeploy(config, toolArgs) {
+  const token = process.env.SWARP_SPRITES_TOKEN;
+  if (!token) {
+    return {
+      content: [{ type: 'text', text: 'Error: SWARP_SPRITES_TOKEN env var is required for deploy' }],
+      isError: true,
+    };
+  }
+
+  const { agent: agentName } = toolArgs ?? {};
+  if (!agentName) {
+    return {
+      content: [{ type: 'text', text: 'Error: agent name is required' }],
+      isError: true,
+    };
+  }
+
+  try {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const { resolve, join } = await import('node:path');
+    const yaml = (await import('js-yaml')).default;
+    const { FlySpriteAdapter } = await import('../runtimes/fly-sprites.mjs');
+
+    const agentsDir = resolve(config.agents_dir ?? 'agents');
+    const yamlPath = join(agentsDir, agentName, 'agent.yaml');
+    if (!existsSync(yamlPath)) {
+      return {
+        content: [{ type: 'text', text: `Error: agent.yaml not found at ${yamlPath}` }],
+        isError: true,
+      };
+    }
+
+    const agentConfig = yaml.load(readFileSync(yamlPath, 'utf-8'));
+    const adapter = new FlySpriteAdapter(token);
+    await adapter.createAgent(agentName, agentConfig);
+    return { content: [{ type: 'text', text: `Deployed ${agentName}` }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Deploy error: ${err.message}` }], isError: true };
+  }
+}

package/src/runtimes/fly-sprites.mjs

@@ -0,0 +1,74 @@
+import { RuntimeAdapter } from './interface.mjs';
+
+const SPRITES_API_BASE = 'https://sprites.fly.io/v1';
+
+export class FlySpriteAdapter extends RuntimeAdapter {
+  constructor(token) {
+    if (!token) {
+      throw new Error('SWARP_SPRITES_TOKEN is required — never load it from .env');
+    }
+    super(token);
+  }
+
+  async createAgent(name, config) {
+    const res = await fetch(`${SPRITES_API_BASE}/sprites`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        name,
+        config: {
+          name: config.name,
+          version: config.version,
+          grpc_port: config.grpc_port ?? 50052,
+          router_url: config.router_url,
+          region: config.region,
+        },
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Sprites API error creating ${name}: ${res.status} ${body}`);
+    }
+
+    return res.json();
+  }
+
+  async destroyAgent(name) {
+    const res = await fetch(`${SPRITES_API_BASE}/sprites/${encodeURIComponent(name)}`, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+      },
+    });
+
+    if (!res.ok && res.status !== 404) {
+      const body = await res.text();
+      throw new Error(`Sprites API error destroying ${name}: ${res.status} ${body}`);
+    }
+
+    return { destroyed: true, name };
+  }
+
+  async getAgent(name) {
+    const res = await fetch(`${SPRITES_API_BASE}/sprites/${encodeURIComponent(name)}`, {
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+      },
+    });
+
+    if (res.status === 404) {
+      return null;
+    }
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Sprites API error getting ${name}: ${res.status} ${body}`);
+    }
+
+    return res.json();
+  }
+}

package/src/runtimes/interface.mjs

@@ -0,0 +1,20 @@
+export class RuntimeAdapter {
+  constructor(token) {
+    if (new.target === RuntimeAdapter) {
+      throw new Error('RuntimeAdapter is abstract — extend it with a concrete implementation');
+    }
+    this.token = token;
+  }
+
+  async createAgent(name, config) {
+    throw new Error('createAgent() must be implemented by subclass');
+  }
+
+  async destroyAgent(name) {
+    throw new Error('destroyAgent() must be implemented by subclass');
+  }
+
+  async getAgent(name) {
+    throw new Error('getAgent() must be implemented by subclass');
+  }
+}

package/src/skill/generate.mjs

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+/**
+ * Scans the agents directory, reads each agent.yaml, and generates
+ * a SKILL.md tailored to the user's actual agents and modes.
+ *
+ * @param {object} opts
+ * @param {string} opts.agentsDir - Absolute path to agents directory
+ * @param {string} opts.routerUrl - Router gRPC address
+ * @returns {string} Rendered SKILL.md content
+ */
+export function generateSkill({ agentsDir, routerUrl }) {
+  const agents = scanAgents(agentsDir);
+
+  let md = `# /swarp
+
+Use this skill when dispatching tasks to SWARP agents, checking agent status, or managing deployments.
+
+## Available Agents
+
+`;
+
+  if (agents.length === 0) {
+    md += `No agents found in \`${agentsDir}\`. Run \`npx @swarp/cli init\` to create one.\n`;
+  } else {
+    for (const agent of agents) {
+      md += `### \`${agent.name}\`\n\n`;
+      if (agent.modes.length > 0) {
+        md += '| Mode | Description | Model | Timeout |\n';
+        md += '|------|-------------|-------|--------|\n';
+        for (const mode of agent.modes) {
+          const desc = mode.description || '—';
+          const model = mode.model || 'default';
+          const timeout = mode.timeout_minutes ? `${mode.timeout_minutes}m` : '30m';
+          md += `| \`${mode.name}\` | ${desc} | ${model} | ${timeout} |\n`;
+        }
+        md += '\n';
+      }
+    }
+  }
+
+  md += `## MCP Tools
+
+The SWARP MCP server registers one tool per agent, plus management tools.
+
+### Agent tools (one per agent above)
+
+Each agent tool accepts:
+- \`mode\` (required): one of the modes listed above
+- \`params\` (optional): key-value pairs interpolated into the mode prompt
+- \`session_id\` (optional): resume an existing session
+
+Example:
+\`\`\`
+`;
+
+  if (agents.length > 0) {
+    const first = agents[0];
+    const firstMode = first.modes[0]?.name || 'implement';
+    md += `Use the \`${first.name}\` tool with mode "${firstMode}" and params.task = "Add error handling to the API"\n`;
+  } else {
+    md += `Use the \`agent-name\` tool with mode "implement" and params.task = "..."\n`;
+  }
+
+  md += `\`\`\`
+
+### Management tools
+
+| Tool | Description |
+|------|-------------|
+| \`swarm_status\` | Check if an agent is online |
+| \`swarm_audit\` | Validate all agent.yaml files |
+| \`swarm_generate\` | Regenerate runner configs |
+| \`swarm_deploy\` | Deploy an agent (destructive — confirm first) |
+
+## CLI
+
+\`\`\`bash
+npx @swarp/cli status             # All agents
+npx @swarp/cli status <agent>     # Specific agent
+npx @swarp/cli audit              # Validate configs
+npx @swarp/cli deploy <agent>     # Deploy one agent
+npx @swarp/cli deploy --all       # Deploy all
+npx @swarp/cli certs generate     # Generate mTLS keypairs
+\`\`\`
+
+## Configuration
+
+Router: \`${routerUrl}\`
+Agents directory: \`${path.relative(process.cwd(), agentsDir) || agentsDir}\`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| \`SWARP_SPRITES_TOKEN\` | For deploy | Fly Sprites API token |
+| \`SWARP_ROUTER_URL\` | For gRPC | Router address (overrides .swarp.json) |
+
+**Security:** \`SWARP_SPRITES_TOKEN\` must be set in the environment — never loaded from .env files.
+`;
+
+  return md;
+}
+
+/**
+ * Reads all agent.yaml files from the agents directory.
+ *
+ * @param {string} agentsDir
+ * @returns {Array<{name: string, modes: Array<{name: string, description?: string, model?: string, timeout_minutes?: number}>}>}
+ */
+function scanAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return [];
+
+  const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+  const agents = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const yamlPath = path.join(agentsDir, entry.name, 'agent.yaml');
+    if (!fs.existsSync(yamlPath)) continue;
+
+    try {
+      const config = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+      agents.push({
+        name: config.name || entry.name,
+        modes: (config.modes || []).map((m) => ({
+          name: m.name,
+          description: m.description,
+          model: m.model,
+          timeout_minutes: m.timeout_minutes,
+        })),
+      });
+    } catch {
+      // Skip malformed configs — swarm_audit will catch them
+    }
+  }
+
+  return agents.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/templates/agent.yaml

@@ -0,0 +1,132 @@
+# agents/example/agent.yaml
+#
+# SWARP agent configuration — all fields shown with explanations.
+# Required fields: name, version, grpc_port, router_url, modes
+# All other fields are optional.
+
+# ── Identity ──────────────────────────────────────────────────────────────────
+
+# Unique agent name. Used as the key in the router registry and as the MCP tool
+# name exposed to Claude Code.
+name: example
+
+# Semantic version of this agent's configuration. The runner reports this
+# version to the router on registration and includes it in AgentEvent metadata.
+version: '1.0.0'
+
+# ── Network ───────────────────────────────────────────────────────────────────
+
+# gRPC port this runner listens on. Each agent on the same Fly Machine must
+# use a unique port. The router connects to this port for Dispatch calls.
+grpc_port: 50052
+
+# Address of the SWARP router. Use an env var reference so the value is not
+# hardcoded and can differ between local dev and production.
+router_url: '${SWARP_ROUTER_URL}'
+
+# ── Persona ───────────────────────────────────────────────────────────────────
+
+# persona sets the character of this agent. It is prepended to every prompt
+# as a system-level instruction before any mode-specific content.
+persona: |
+  You are example, a focused software engineer.
+  You write clean, tested, idiomatic code.
+  You ask clarifying questions before starting large tasks.
+  You never make up facts.
+
+# ── Preamble ──────────────────────────────────────────────────────────────────
+
+# preamble is injected after the persona and before the user's task. Use it
+# for project-specific conventions that every mode should know about.
+preamble: |
+  Project: monorepo (Bun + React + Supabase)
+  Branch policy: never push to main; always use feature branches.
+  Test runner: bun test
+  Linter: bun run lint
+
+# ── Modes ─────────────────────────────────────────────────────────────────────
+
+# A mode is a named capability of this agent. The router's classifier selects
+# a mode based on keywords in the incoming task description.
+#
+# Required per mode: name
+# Optional: description, model, max_turns, timeout_minutes, tools, skills, hooks, env
+modes:
+  - name: implement
+    description: 'Implement a feature or fix a bug from a spec'
+    # Model to use for this mode. Defaults to the runner's configured default.
+    model: claude-opus-4-5
+    # Maximum number of agentic turns before the runner halts the session.
+    max_turns: 40
+    # Session wall-clock timeout in minutes. The runner cancels the claude
+    # process when this expires.
+    timeout_minutes: 30
+    # tools lists MCP tool names this mode is allowed to call.
+    tools:
+      - Read
+      - Edit
+      - Write
+      - Bash
+      - Glob
+      - Grep
+    # skills lists slash-command skill names this mode loads on startup.
+    skills:
+      - superpowers:test-driven-development
+      - superpowers:systematic-debugging
+    # hooks are shell commands run before or after the session.
+    hooks:
+      pre_session:
+        - 'git fetch origin'
+      post_session:
+        - 'bun run lint'
+        - 'bun test'
+    # env injects key=value pairs into the runner's process environment.
+    # Secrets should use ${SECRET_NAME} references.
+    env:
+      NODE_ENV: development
+
+  - name: review
+    description: 'Review code and provide structured feedback'
+    model: claude-sonnet-4-5
+    max_turns: 20
+    timeout_minutes: 15
+    tools:
+      - Read
+      - Glob
+      - Grep
+    skills:
+      - superpowers:requesting-code-review
+
+  - name: debug
+    description: 'Diagnose and fix a failing test or runtime error'
+    model: claude-opus-4-5
+    max_turns: 30
+    timeout_minutes: 25
+    tools:
+      - Read
+      - Edit
+      - Write
+      - Bash
+      - Glob
+      - Grep
+    skills:
+      - superpowers:systematic-debugging
+      - superpowers:test-driven-development
+
+  - name: plan
+    description: 'Write an implementation plan for a feature or refactor'
+    model: claude-sonnet-4-5
+    max_turns: 15
+    timeout_minutes: 15
+    tools:
+      - Read
+      - Glob
+      - Grep
+    skills:
+      - superpowers:writing-plans
+
+# ── Env file ──────────────────────────────────────────────────────────────────
+
+# Path to a .env file loaded before any session starts. Relative to the agent
+# config file. Use this for secrets that differ between environments.
+# env_file: .env