crewswarm 0.8.1-beta

package/contrib/openclaw-plugin/README.md

@@ -0,0 +1,199 @@
+# CrewSwarm Plugin for OpenClaw
+
+Connects your OpenClaw agents to a local [CrewSwarm](https://github.com/crewswarm/crewswarm) multi-agent crew.
+
+Your OpenClaw agents gain three new tools — `crewswarm_dispatch`, `crewswarm_status`, and `crewswarm_agents` — plus a `/crewswarm` slash command and Gateway RPC methods. **No LLM credentials are shared** — only a single auth token.
+
+---
+
+## What it does
+
+| Surface | Description |
+|---|---|
+| `crewswarm_dispatch` | Agent tool — dispatch a task to any crew agent and block until done |
+| `crewswarm_status` | Agent tool — poll status of a task by `taskId` |
+| `crewswarm_agents` | Agent tool — list available agents |
+| `/crewswarm <agent> <task>` | Slash command from any channel |
+| `crewswarm.dispatch` | Gateway RPC |
+| `crewswarm.status` | Gateway RPC |
+| `crewswarm.agents` | Gateway RPC |
+
+---
+
+## Requirements
+
+- [CrewSwarm](https://github.com/crewswarm/crewswarm) running locally (`npm run restart-all`)
+- `crew-lead` reachable at `http://127.0.0.1:5010` (default)
+- Your RT auth token from `~/.crewswarm/config.json → rt.authToken`
+
+---
+
+## Install
+
+```bash
+# From the CrewSwarm repo root:
+openclaw plugins install ./contrib/openclaw-plugin
+```
+
+Or link for development (no copy, reflects edits immediately):
+
+```bash
+openclaw plugins install -l ./contrib/openclaw-plugin
+```
+
+Then restart the OpenClaw Gateway:
+
+```bash
+openclaw restart
+```
+
+---
+
+## Configure
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "crewswarm": {
+        "enabled": true,
+        "config": {
+          "url":   "http://127.0.0.1:5010",
+          "token": "<your RT auth token>"
+        }
+      }
+    }
+  }
+}
+```
+
+Find your token:
+
+```bash
+cat ~/.crewswarm/config.json | python3 -c "import json,sys; print(json.load(sys.stdin)['rt']['authToken'])"
+```
+
+Optional config:
+
+| Key | Default | Description |
+|---|---|---|
+| `url` | `http://127.0.0.1:5010` | crew-lead base URL |
+| `token` | *(required)* | RT auth token |
+| `pollIntervalMs` | `4000` | Status poll frequency |
+| `pollTimeoutMs` | `300000` | Max wait time (5 min) |
+
+---
+
+## Usage
+
+### From an OpenClaw agent conversation
+
+Your OpenClaw agent will automatically call `crewswarm_dispatch` when it makes sense:
+
+> "Use crew-coder to write a login endpoint with JWT auth"
+
+Or explicitly:
+
+> "Call crewswarm_dispatch with agent=crew-qa to audit my last change"
+
+### Slash command (any channel — Telegram, WhatsApp, etc.)
+
+```
+/crewswarm crew-coder write /tmp/hello.js — a 10-line express hello world
+/crewswarm crew-qa audit the last PR changes
+/crewswarm crew-pm create a roadmap for the auth feature
+/crewswarm                   ← lists available agents
+```
+
+### Gateway RPC (from scripts or other tools)
+
+```bash
+# Dispatch
+openclaw rpc crewswarm.dispatch '{"agent":"crew-copywriter","task":"Write a tagline for CrewSwarm"}'
+
+# Poll status
+openclaw rpc crewswarm.status '{"taskId":"<uuid>"}'
+
+# List agents
+openclaw rpc crewswarm.agents
+```
+
+### Direct HTTP (no OpenClaw needed)
+
+```bash
+TOKEN="<your RT token>"
+
+# List agents
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5010/api/agents
+
+# Dispatch
+curl -X POST http://127.0.0.1:5010/api/dispatch \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"agent":"crew-coder","task":"write hello.js"}'
+
+# Poll
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5010/api/status/<taskId>
+```
+
+---
+
+## Available agents (default crew)
+
+| Agent | Role |
+|---|---|
+| `crew-coder` | Full-stack coding |
+| `crew-coder-front` | Frontend specialist |
+| `crew-coder-back` | Backend specialist |
+| `crew-frontend` | UI/CSS polish |
+| `crew-qa` | Testing & audit |
+| `crew-fixer` | Bug fixing |
+| `crew-pm` | Planning & roadmaps |
+| `crew-security` | Security review |
+| `crew-copywriter` | Writing & docs |
+| `crew-github` | Git & PRs |
+| `crew-main` | General purpose |
+| `crew-mega` | Heavy reasoning tasks |
+| `crew-researcher` | Web research |
+| `crew-architect` | System design |
+| `crew-ml` | ML/data tasks |
+| `crew-orchestrator` | Wave orchestration |
+| `crew-seo` | SEO optimization |
+| `crew-loco` | Web search/fetch |
+| `crew-judge` | Task evaluation |
+| `crew-telegram` | Telegram integration |
+| `crew-whatsapp` | WhatsApp integration |
+
+---
+
+## How it works
+
+```
+OpenClaw agent
+  → crewswarm_dispatch tool call
+    → POST /api/dispatch (crew-lead HTTP, Bearer token)
+      → RT WebSocket bus (port 18889)
+        → target agent bridge (gateway-bridge.mjs)
+          → LLM call (Mistral / Cerebras / DeepSeek / etc.)
+          → tool execution (@@WRITE_FILE, @@RUN_CMD, etc.)
+        → task.done event back on RT bus
+      → crew-lead stores result
+    → GET /api/status/:taskId (polled every 4s)
+  ← result returned to OpenClaw agent
+```
+
+No LLM keys cross the boundary — CrewSwarm uses its own provider config. The only shared secret is the RT auth token.
+
+---
+
+## Troubleshooting
+
+**"crew-lead unreachable"** — run `npm run restart-all` in the CrewSwarm repo.
+
+**401 Unauthorized** — token mismatch. Re-copy from `~/.crewswarm/config.json → rt.authToken`.
+
+**Task never completes** — check `/tmp/crew-lead.log` and the bridge log in `/tmp/`.
+
+**Agent not found** — call `crewswarm_agents` to see the live agent list.

package/contrib/openclaw-plugin/index.ts

@@ -0,0 +1,306 @@
+/**
+ * CrewSwarm plugin for OpenClaw
+ *
+ * Gives every OpenClaw agent access to a local CrewSwarm crew via:
+ *   • crewswarm_dispatch  — agent tool (call crew-coder, crew-qa, etc.)
+ *   • crewswarm_status    — agent tool (poll a previously dispatched task)
+ *   • crewswarm_agents    — agent tool (list available agents)
+ *   • /crewswarm          — slash command (dispatch from any channel)
+ *   • crewswarm.dispatch  — Gateway RPC
+ *   • crewswarm.status    — Gateway RPC
+ *   • crewswarm.agents    — Gateway RPC
+ *
+ * Config (plugins.entries.crewswarm.config):
+ *   url            — crew-lead base URL  (default: http://127.0.0.1:5010)
+ *   token          — RT auth token from ~/.crewswarm/config.json → rt.authToken
+ *   pollIntervalMs — status poll cadence (default: 4000)
+ *   pollTimeoutMs  — max wait for a result (default: 300000 = 5 min)
+ */
+
+interface CrewSwarmConfig {
+  url?: string;
+  token: string;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+}
+
+interface DispatchResult {
+  ok: boolean;
+  taskId?: string;
+  agent?: string;
+  error?: string;
+}
+
+interface StatusResult {
+  ok: boolean;
+  taskId: string;
+  status: "pending" | "done" | "unknown";
+  agent?: string;
+  result?: string;
+  elapsedMs?: number;
+  error?: string;
+}
+
+function getConfig(api: any): CrewSwarmConfig {
+  return api.config?.plugins?.entries?.crewswarm?.config ?? {};
+}
+
+function baseUrl(cfg: CrewSwarmConfig): string {
+  return (cfg.url ?? "http://127.0.0.1:5010").replace(/\/$/, "");
+}
+
+function authHeaders(cfg: CrewSwarmConfig): Record<string, string> {
+  return {
+    "content-type": "application/json",
+    authorization: `Bearer ${cfg.token}`,
+  };
+}
+
+async function apiDispatch(
+  base: string,
+  headers: Record<string, string>,
+  agent: string,
+  task: string,
+  verify?: string,
+  done?: string,
+): Promise<DispatchResult> {
+  try {
+    const body: Record<string, string> = { agent, task };
+    if (verify) body.verify = verify;
+    if (done) body.done = done;
+    const res = await fetch(`${base}/api/dispatch`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    });
+    return res.json() as Promise<DispatchResult>;
+  } catch (e: any) {
+    return { ok: false, error: `Network error: ${e.message}` };
+  }
+}
+
+async function apiStatus(
+  base: string,
+  headers: Record<string, string>,
+  taskId: string,
+): Promise<StatusResult> {
+  try {
+    const res = await fetch(`${base}/api/status/${taskId}`, { headers });
+    return res.json() as Promise<StatusResult>;
+  } catch (e: any) {
+    return { ok: false, taskId, status: "unknown", error: `Network error: ${e.message}` };
+  }
+}
+
+async function apiAgents(
+  base: string,
+  headers: Record<string, string>,
+): Promise<string[]> {
+  try {
+    const res = await fetch(`${base}/api/agents`, { headers });
+    const data = await res.json() as { ok: boolean; agents: string[] };
+    return data.agents ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Dispatch and wait for result, polling until done or timeout */
+async function dispatchAndWait(
+  api: any,
+  agent: string,
+  task: string,
+  verify?: string,
+  done?: string,
+): Promise<string> {
+  const cfg = getConfig(api);
+  if (!cfg.token) return "Error: no CrewSwarm token configured (plugins.entries.crewswarm.config.token)";
+
+  const base = baseUrl(cfg);
+  const headers = authHeaders(cfg);
+  const pollMs = cfg.pollIntervalMs ?? 4000;
+  const timeoutMs = cfg.pollTimeoutMs ?? 300_000;
+
+  const dispatch = await apiDispatch(base, headers, agent, task, verify, done);
+  if (!dispatch.ok || !dispatch.taskId) {
+    return `Error dispatching to ${agent}: ${dispatch.error ?? "unknown error"}`;
+  }
+
+  const taskId = dispatch.taskId;
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    const s = await apiStatus(base, headers, taskId);
+    if (s.status === "done") return s.result ?? "(no result)";
+    if (s.status === "unknown") return `Error: task ${taskId} not found`;
+  }
+
+  return `Timeout: ${agent} did not complete within ${timeoutMs / 1000}s (taskId: ${taskId})`;
+}
+
+export default function register(api: any) {
+  // ── Agent tools ───────────────────────────────────────────────────────────
+
+  api.registerTool({
+    name: "crewswarm_dispatch",
+    description:
+      "Dispatch a task to a CrewSwarm specialist agent and wait for the result. " +
+      "Use this to delegate coding, QA, writing, security review, or any other task " +
+      "to the appropriate crew member. The call blocks until the agent replies.",
+    parameters: {
+      type: "object",
+      properties: {
+        agent: {
+          type: "string",
+          description:
+            "Target agent id. Common values: crew-coder, crew-qa, crew-fixer, " +
+            "crew-pm, crew-security, crew-copywriter, crew-frontend, crew-coder-back. " +
+            "Call crewswarm_agents first if unsure.",
+        },
+        task: {
+          type: "string",
+          description: "Full task description for the agent.",
+        },
+        verify: {
+          type: "string",
+          description:
+            "Optional: how the agent should verify its output (e.g. 'curl returns 200').",
+        },
+        done: {
+          type: "string",
+          description:
+            "Optional: explicit done condition (e.g. 'file contains const express').",
+        },
+      },
+      required: ["agent", "task"],
+      additionalProperties: false,
+    },
+    handler: async ({ agent, task, verify, done }: {
+      agent: string; task: string; verify?: string; done?: string;
+    }) => {
+      return dispatchAndWait(api, agent, task, verify, done);
+    },
+  });
+
+  api.registerTool({
+    name: "crewswarm_status",
+    description:
+      "Poll the status of a previously dispatched CrewSwarm task by taskId. " +
+      "Returns pending, done (with result), or unknown.",
+    parameters: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "taskId returned by crewswarm_dispatch" },
+      },
+      required: ["taskId"],
+      additionalProperties: false,
+    },
+    handler: async ({ taskId }: { taskId: string }) => {
+      const cfg = getConfig(api);
+      if (!cfg.token) return "Error: no CrewSwarm token configured";
+      const s = await apiStatus(baseUrl(cfg), authHeaders(cfg), taskId);
+      if (s.status === "done") return `Done: ${s.result}`;
+      if (s.status === "pending") return `Pending (${s.elapsedMs ?? 0}ms elapsed)`;
+      return `Unknown task: ${taskId}`;
+    },
+  });
+
+  api.registerTool({
+    name: "crewswarm_agents",
+    description: "List all available CrewSwarm agents by id.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: async () => {
+      const cfg = getConfig(api);
+      if (!cfg.token) return "Error: no CrewSwarm token configured";
+      const agents = await apiAgents(baseUrl(cfg), authHeaders(cfg));
+      return agents.length
+        ? `Available agents:\n${agents.map((a) => `  • ${a}`).join("\n")}`
+        : "No agents found — is crew-lead running?";
+    },
+  });
+
+  // ── Slash command: /crewswarm <agent> <task> ──────────────────────────────
+
+  api.registerCommand({
+    name: "crewswarm",
+    description: "Dispatch a task to CrewSwarm. Usage: /crewswarm <agent> <task>",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const args = (ctx.args ?? "").trim();
+      if (!args) {
+        const cfg = getConfig(api);
+        const agents = await apiAgents(baseUrl(cfg), authHeaders(cfg));
+        return {
+          text: agents.length
+            ? `CrewSwarm agents: ${agents.join(", ")}\n\nUsage: /crewswarm <agent> <task>`
+            : "crew-lead not reachable. Is CrewSwarm running?",
+        };
+      }
+
+      const [agent, ...rest] = args.split(" ");
+      const task = rest.join(" ").trim();
+      if (!task) return { text: `Usage: /crewswarm <agent> <task>\nExample: /crewswarm crew-coder write hello.js` };
+
+      const result = await dispatchAndWait(api, agent, task);
+      return { text: `[${agent}]: ${result}` };
+    },
+  });
+
+  // ── Gateway RPC ───────────────────────────────────────────────────────────
+
+  api.registerGatewayMethod("crewswarm.dispatch", async ({ params, respond }: any) => {
+    const { agent, task, verify, done } = params ?? {};
+    if (!agent || !task) {
+      respond(false, { error: "agent and task are required" });
+      return;
+    }
+    const cfg = getConfig(api);
+    const dispatch = await apiDispatch(baseUrl(cfg), authHeaders(cfg), agent, task, verify, done);
+    respond(dispatch.ok, dispatch);
+  });
+
+  api.registerGatewayMethod("crewswarm.status", async ({ params, respond }: any) => {
+    const { taskId } = params ?? {};
+    if (!taskId) { respond(false, { error: "taskId required" }); return; }
+    const cfg = getConfig(api);
+    const s = await apiStatus(baseUrl(cfg), authHeaders(cfg), taskId);
+    respond(s.ok, s);
+  });
+
+  api.registerGatewayMethod("crewswarm.agents", async ({ respond }: any) => {
+    const cfg = getConfig(api);
+    const agents = await apiAgents(baseUrl(cfg), authHeaders(cfg));
+    respond(true, { agents });
+  });
+
+  // ── Background health check (logs warning on startup if unreachable) ──────
+
+  api.registerService({
+    id: "crewswarm-health",
+    start: async () => {
+      const cfg = getConfig(api);
+      if (!cfg.token) {
+        api.logger?.warn("[crewswarm] No token configured — set plugins.entries.crewswarm.config.token");
+        return;
+      }
+      try {
+        const res = await fetch(`${baseUrl(cfg)}/health`);
+        const data = await res.json() as { ok: boolean };
+        if (data.ok) {
+          api.logger?.info(`[crewswarm] Connected to crew-lead at ${baseUrl(cfg)}`);
+        } else {
+          api.logger?.warn(`[crewswarm] crew-lead health check returned not-ok`);
+        }
+      } catch {
+        api.logger?.warn(`[crewswarm] crew-lead unreachable at ${baseUrl(cfg)} — start CrewSwarm first`);
+      }
+    },
+    stop: () => {},
+  });
+}

package/contrib/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "crewswarm",
+  "name": "CrewSwarm",
+  "description": "Dispatch tasks to a local CrewSwarm multi-agent crew from any OpenClaw agent. Adds the crewswarm_dispatch tool, /crewswarm slash command, and Gateway RPC methods.",
+  "version": "0.1.0",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "url": {
+        "type": "string",
+        "default": "http://127.0.0.1:5010",
+        "description": "Base URL of the CrewSwarm crew-lead HTTP server"
+      },
+      "token": {
+        "type": "string",
+        "description": "RT auth token from ~/.crewswarm/config.json → rt.authToken"
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "default": 4000,
+        "description": "How often (ms) to poll /api/status when waiting for a task result"
+      },
+      "pollTimeoutMs": {
+        "type": "number",
+        "default": 300000,
+        "description": "Max time (ms) to wait for a dispatched task before giving up"
+      }
+    },
+    "required": ["token"]
+  },
+  "uiHints": {
+    "url":            { "label": "crew-lead URL",   "placeholder": "http://127.0.0.1:5010" },
+    "token":          { "label": "RT Auth Token",   "sensitive": true },
+    "pollIntervalMs": { "label": "Poll interval (ms)" },
+    "pollTimeoutMs":  { "label": "Task timeout (ms)" }
+  }
+}

package/contrib/openclaw-plugin/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "crewswarm-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin — dispatch tasks to a local CrewSwarm multi-agent crew",
+  "keywords": ["openclaw", "crewswarm", "multi-agent", "ai", "orchestration"],
+  "homepage": "https://github.com/CrewSwarm/CrewSwarm",
+  "bugs": "https://github.com/CrewSwarm/CrewSwarm/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CrewSwarm/CrewSwarm.git",
+    "directory": "contrib/openclaw-plugin"
+  },
+  "license": "MIT",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "skills": ["./skills/crewswarm"]
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/contrib/openclaw-plugin/skills/crewswarm/SKILL.md

@@ -0,0 +1,88 @@
+# CrewSwarm Dispatch Skill
+
+## When to use this skill
+
+Use CrewSwarm tools when the user asks you to **build, write, test, review, fix, or ship something** that would benefit from a specialist agent — especially multi-step work that crosses disciplines (code + tests + docs, or frontend + backend + QA).
+
+**Trigger phrases:**
+- "build / write / create / implement [feature]"
+- "test / audit / review [code or PR]"
+- "fix [bug]"
+- "write docs / a README / a spec for..."
+- "dispatch crew-coder / crew-qa / crew-pm to..."
+- "have the crew handle..."
+
+## Available tools
+
+- `crewswarm_agents` — list all available agents (call this first if unsure)
+- `crewswarm_dispatch` — send a task to a specialist and wait for the result
+- `crewswarm_status` — poll a running task by taskId
+
+## How to use
+
+### Step 1 — pick the right agent
+
+| Task type | Agent |
+|---|---|
+| Write or edit code (general) | `crew-coder` |
+| Frontend / UI / CSS | `crew-coder-front` or `crew-frontend` |
+| Backend / API / DB | `crew-coder-back` |
+| Write tests, audit, QA | `crew-qa` |
+| Fix a bug or error | `crew-fixer` |
+| Plan a feature or roadmap | `crew-pm` |
+| Security review | `crew-security` |
+| Write docs, copy, README | `crew-copywriter` |
+| Git / PR operations | `crew-github` |
+| Heavy reasoning / complex tasks | `crew-mega` |
+| Web research | `crew-researcher` |
+| System architecture / design | `crew-architect` |
+| ML / data tasks | `crew-ml` |
+| SEO optimization | `crew-seo` |
+| Task evaluation / judging | `crew-judge` |
+| General / orchestration | `crew-main` |
+
+If you're unsure, call `crewswarm_agents` first to see the live list.
+
+### Step 2 — dispatch with a clear task
+
+Write the task as a precise, self-contained instruction. Include:
+- **What** to produce (file path, function name, endpoint, etc.)
+- **How** to verify it worked (optional `verify` field)
+- **Done condition** (optional `done` field)
+
+Good example:
+```
+agent: "crew-coder"
+task: "Write /src/api/auth.ts — a JWT login endpoint using jose. Accept email+password, validate against users array, return httpOnly cookie."
+verify: "curl -X POST http://localhost:3000/login returns Set-Cookie header"
+done: "File exists and contains createSigner from jose"
+```
+
+### Step 3 — wait and relay
+
+`crewswarm_dispatch` blocks until the agent finishes (up to 5 minutes). The result includes the agent's full output including any files written, commands run, and verification results. Relay the relevant parts to the user.
+
+## Chaining agents
+
+For complex work, dispatch sequentially — use the result of one agent as context for the next:
+
+```
+1. crewswarm_dispatch crew-pm  → "Create a task plan for user auth feature"
+2. crewswarm_dispatch crew-coder → "Implement: [result from step 1]"
+3. crewswarm_dispatch crew-qa  → "Test: [result from step 2]"
+```
+
+## Slash command alternative
+
+Users can also dispatch directly from any channel:
+```
+/crewswarm crew-coder write /tmp/hello.js — a 10-line express hello world
+/crewswarm crew-qa audit the last PR
+/crewswarm              ← lists available agents
+```
+
+## When NOT to use CrewSwarm
+
+- Simple one-liner answers or explanations — handle directly
+- Tasks you can complete yourself without writing files or running code
+- If CrewSwarm is not running (`crewswarm_agents` returns empty or errors)