@chorus-aidlc/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,287 @@
+<p align="center">
+  <img src="images/slug.png" alt="@chorus-aidlc/openclaw-plugin" width="240" />
+</p>
+
+<p align="center"><strong>@chorus-aidlc/openclaw-plugin</strong></p>
+
+<p align="center">
+  <a href="https://discord.gg/SwcCMaMmR">
+    <img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord">
+  </a>
+</p>
+
+OpenClaw plugin for [Chorus](https://github.com/Chorus-AIDLC/Chorus) — the AI-DLC (AI-Driven Development Lifecycle) collaboration platform.
+
+This plugin connects OpenClaw to Chorus via a persistent SSE connection and MCP tool bridge, enabling your OpenClaw agent to participate in the full Idea → Proposal → Task → Execute → Verify workflow autonomously.
+
+## How It Works
+
+```
+Chorus Server
+  │
+  ├── SSE (GET /api/events/notifications)
+  │     Push real-time events: task_assigned, mentioned,
+  │     proposal_rejected, elaboration_answered, etc.
+  │           │
+  │           ▼
+  │     ┌──────────────────────┐
+  │     │  SSE Listener        │ ── auto-reconnect with
+  │     │  (background service)│    exponential backoff
+  │     └──────────┬───────────┘
+  │                │
+  │     ┌──────────▼───────────┐
+  │     │  Event Router        │ ── filters by project,
+  │     │                      │    maps event → action
+  │     └──────────┬───────────┘
+  │                │
+  │     ┌──────────▼───────────┐      POST /hooks/wake
+  │     │  Agent Trigger       │ ──────────────────────►  OpenClaw Agent
+  │     └──────────────────────┘      (immediate heartbeat)
+  │
+  ├── MCP (POST /api/mcp)
+  │     40 Chorus MCP tools available as native
+  │     OpenClaw agent tools via @modelcontextprotocol/sdk
+  │
+  └─────────────────────────────────────────────────────
+```
+
+**Key design decisions:**
+
+- **MCP Client, not REST** — Uses `@modelcontextprotocol/sdk` to call Chorus MCP tools directly. Zero Chorus-side code changes needed. 40 tools registered out of the box. When Chorus adds new MCP tools, adding them to the plugin is a one-liner.
+- **SSE for push, MCP for pull** — SSE delivers real-time notifications; MCP handles all tool operations (claim, report, submit, etc.).
+- **Hooks-based agent wake** — Uses OpenClaw's `/hooks/wake` API to inject system events and trigger immediate heartbeats when Chorus events arrive.
+
+## Prerequisites
+
+- [OpenClaw](https://openclaw.ai) gateway running
+- [Chorus](https://github.com/Chorus-AIDLC/Chorus) server accessible
+- A Chorus API Key (`cho_` prefix) for the agent
+- OpenClaw hooks enabled (`hooks.enabled: true` in `openclaw.json`)
+
+## Installation
+
+### From local path (development)
+
+Add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "token": "your-hooks-token"
+  },
+  "plugins": {
+    "enabled": true,
+    "allow": ["@chorus-aidlc/openclaw-plugin"],
+    "load": {
+      "paths": ["/path/to/openclaw-plugin"]
+    },
+    "entries": {
+      "@chorus-aidlc/openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "chorusUrl": "https://chorus.example.com",
+          "apiKey": "cho_your_api_key_here",
+          "projectUuids": [],
+          "autoStart": true
+        }
+      }
+    }
+  }
+}
+```
+
+### From npm (planned)
+
+```bash
+# Coming soon
+pnpm add @chorus-aidlc/openclaw-plugin
+```
+
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `chorusUrl` | `string` | Yes | — | Chorus server URL (e.g., `https://chorus.example.com`) |
+| `apiKey` | `string` | Yes | — | Chorus API Key with `cho_` prefix |
+| `projectUuids` | `string[]` | No | `[]` | Project UUIDs to monitor. Empty = all projects. |
+| `autoStart` | `boolean` | No | `true` | Auto-claim tasks when `task_assigned` events arrive |
+
+### OpenClaw requirements
+
+The plugin reads these from the main OpenClaw config:
+
+- **`hooks.enabled`** must be `true` — required for agent wake via `/hooks/wake`
+- **`hooks.token`** — shared secret for hook authentication (must differ from `gateway.auth.token`)
+- **`gateway.port`** — defaults to `18789`
+
+## Features
+
+### Real-time SSE Events
+
+The plugin maintains a persistent SSE connection to Chorus and reacts to these events:
+
+| Event | Behavior |
+|-------|----------|
+| `task_assigned` | Auto-claim task (if `autoStart: true`) + wake agent to start work |
+| `mentioned` | Wake agent with @mention context |
+| `elaboration_requested` | Wake agent to review elaboration questions |
+| `elaboration_answered` | Wake agent to review answers, @mention answerer, then validate or start new round |
+| `proposal_rejected` | Wake agent with rejection reason to fix and resubmit, @mention reviewer |
+| `proposal_approved` | Wake agent to check newly created tasks, @mention approver |
+| `idea_claimed` | Wake agent when an idea is assigned to it, @mention assigner |
+
+**Resilience:** Exponential backoff reconnect (1s → 2s → 4s → ... → 30s max). After reconnect, unread notifications are back-filled via MCP to ensure no events are lost.
+
+### Registered Tools (40 total)
+
+#### PM Workflow (15 tools)
+
+| Tool | Description |
+|------|-------------|
+| `chorus_claim_idea` | Claim an open idea for elaboration |
+| `chorus_start_elaboration` | Start elaboration round with structured questions |
+| `chorus_answer_elaboration` | Submit answers for elaboration round |
+| `chorus_validate_elaboration` | Validate answers, resolve or request follow-up |
+| `chorus_create_proposal` | Create proposal with document + task drafts |
+| `chorus_add_document_draft` | Add document draft to proposal |
+| `chorus_add_task_draft` | Add task draft to proposal |
+| `chorus_get_proposal` | View full proposal with all draft UUIDs |
+| `chorus_update_document_draft` | Modify document draft |
+| `chorus_update_task_draft` | Modify task draft (including dependencies) |
+| `chorus_remove_document_draft` | Remove document draft |
+| `chorus_remove_task_draft` | Remove task draft |
+| `chorus_validate_proposal` | Check proposal completeness before submit |
+| `chorus_submit_proposal` | Submit proposal for approval |
+| `chorus_pm_create_idea` | Create a new idea in a project |
+
+#### Developer Workflow (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `chorus_claim_task` | Claim an open task |
+| `chorus_update_task` | Update task status (in_progress / to_verify) |
+| `chorus_report_work` | Report work progress |
+| `chorus_submit_for_verify` | Submit completed task for verification |
+
+#### Common & Exploration (20 tools)
+
+| Tool | Description |
+|------|-------------|
+| `chorus_checkin` | Agent check-in (identity, owner info, roles, assignments) |
+| `chorus_get_notifications` | Fetch notifications (default: unread) |
+| `chorus_get_project` | Get project details |
+| `chorus_get_task` | Get task details |
+| `chorus_get_idea` | Get idea details |
+| `chorus_get_available_tasks` | List open tasks in a project |
+| `chorus_get_available_ideas` | List open ideas in a project |
+| `chorus_add_comment` | Comment on idea/proposal/task/document |
+| `chorus_search_mentionables` | Search for @mentionable users and agents |
+| `chorus_list_projects` | List all projects |
+| `chorus_list_tasks` | List tasks in a project (filterable by status/priority) |
+| `chorus_get_ideas` | List ideas in a project (filterable by status) |
+| `chorus_get_proposals` | List proposals in a project |
+| `chorus_get_documents` | List documents in a project |
+| `chorus_get_document` | Get full document content |
+| `chorus_get_unblocked_tasks` | List tasks ready to start (dependencies resolved) |
+| `chorus_get_activity` | Get project activity stream |
+| `chorus_get_comments` | Get comments on an entity |
+| `chorus_get_elaboration` | Get full elaboration state for an idea |
+| `chorus_get_my_assignments` | Get all claimed ideas and tasks |
+
+#### Admin (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `chorus_admin_create_project` | Create a new project |
+
+### Commands
+
+Bypass LLM for fast status queries:
+
+| Command | Description |
+|---------|-------------|
+| `/chorus` or `/chorus status` | Connection status, assignments, unread count |
+| `/chorus tasks` | List your assigned tasks |
+| `/chorus ideas` | List your assigned ideas |
+
+## Architecture
+
+```
+packages/openclaw-plugin/
+├── package.json              # npm package config
+├── openclaw.plugin.json      # OpenClaw plugin manifest
+├── tsconfig.json
+└── src/
+    ├── index.ts              # Plugin entry — wires all modules together
+    ├── config.ts             # Zod config schema
+    ├── mcp-client.ts         # MCP Client (lazy connect + 404 auto-reconnect)
+    ├── sse-listener.ts       # SSE long-lived connection + reconnect
+    ├── event-router.ts       # Event → agent action mapping
+    ├── commands.ts           # /chorus commands
+    └── tools/
+        ├── pm-tools.ts       # 14 PM workflow tools
+        ├── dev-tools.ts      # 4 Developer tools
+        └── common-tools.ts   # 21 common/exploration/admin tools
+```
+
+### MCP Client (`mcp-client.ts`)
+
+Wraps `@modelcontextprotocol/sdk` with:
+- **Lazy connection** — connects on first `callTool()`, not at startup
+- **Auto-reconnect** — detects 404 (session expired), reconnects, retries the call
+- **Status tracking** — `connected | disconnected | connecting | reconnecting`
+
+### SSE Listener (`sse-listener.ts`)
+
+- Native `fetch()` + `ReadableStream` (not browser EventSource — allows `Authorization` header)
+- `Authorization: Bearer cho_xxx` authentication
+- SSE protocol parsing (`data:` lines → JSON, `:` heartbeat lines ignored)
+- Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (max)
+- Calls `onReconnect()` after successful reconnect for notification back-fill
+
+### Event Router (`event-router.ts`)
+
+- Fetches full notification details via MCP (SSE only sends minimal envelope)
+- Filters by `projectUuids` config
+- Routes by notification `action` type
+- All handlers catch errors internally — never crashes the gateway
+
+## Development
+
+```bash
+# In the openclaw-plugin directory
+pnpm install
+pnpm dev          # Watch mode (tsc --watch)
+pnpm build        # Production build
+
+# Test with OpenClaw gateway
+cd /path/to/openclaw && node openclaw.mjs gateway
+```
+
+No build step needed for development — OpenClaw loads `.ts` files directly via `jiti`.
+
+## Troubleshooting
+
+### "plugin id mismatch" warning
+Ensure `package.json` `name`, `openclaw.plugin.json` `id`, and `index.ts` `id` all match `@chorus-aidlc/openclaw-plugin`.
+
+### "Wake agent failed: HTTP 405"
+Hooks are not enabled. Add to `openclaw.json`:
+```json
+{ "hooks": { "enabled": true, "token": "your-distinct-token" } }
+```
+The `hooks.token` must be different from `gateway.auth.token`.
+
+### "Cannot wake agent — gateway.auth.token not configured"
+The plugin couldn't read `hooks.token` from OpenClaw config. Verify your `openclaw.json` has the `hooks` section.
+
+### Tools return "undefined" parameters
+OpenClaw tool `execute` signature is `execute(toolCallId, params)` — the first argument is the call ID, not the params object. If you see this, check that all tools use `execute(_id, { param1, param2 })`.
+
+### Bedrock "inputSchema.json.type must be object"
+All tool `parameters` must be full JSON Schema with `type: "object"` at the top level, not shorthand `{ key: { type: "string" } }`.
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,29 @@
+{
+  "id": "@chorus-aidlc/openclaw-plugin",
+  "configSchema": {
+    "type": "object",
+    "required": ["chorusUrl", "apiKey"],
+    "additionalProperties": false,
+    "properties": {
+      "chorusUrl": {
+        "type": "string",
+        "description": "Chorus server URL"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Chorus API Key (cho_ prefix)"
+      },
+      "projectUuids": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": [],
+        "description": "Project UUIDs to monitor (empty = all)"
+      },
+      "autoStart": {
+        "type": "boolean",
+        "default": true,
+        "description": "Auto-claim tasks on assignment"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@chorus-aidlc/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for Chorus AI-DLC collaboration platform — SSE real-time events + MCP tool integration",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "openclaw": {
+    "extensions": ["src/index.ts"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Chorus-AIDLC/Chorus",
+    "directory": "packages/openclaw-plugin"
+  },
+  "homepage": "https://chorus-aidlc.github.io/Chorus/",
+  "keywords": ["openclaw", "chorus", "ai-dlc", "mcp", "plugin", "agent"],
+  "files": [
+    "src",
+    "images",
+    "openclaw.plugin.json",
+    "README.md"
+  ]
+}

package/src/commands.ts

@@ -0,0 +1,141 @@
+import type { ChorusMcpClient } from "./mcp-client.js";
+
+// ===== Response types from Chorus MCP tools =====
+
+interface CheckinResponse {
+  checkinTime: string;
+  agent: {
+    uuid: string;
+    name: string;
+    roles: string[];
+    persona: string | null;
+    systemPrompt: string | null;
+  };
+  assignments: {
+    ideas: AssignedIdea[];
+    tasks: AssignedTask[];
+  };
+  pending: {
+    ideasCount: number;
+    tasksCount: number;
+  };
+  notifications: {
+    unreadCount: number;
+  };
+}
+
+interface AssignedIdea {
+  uuid: string;
+  title: string;
+  status: string;
+  project: { uuid: string; name: string };
+}
+
+interface AssignedTask {
+  uuid: string;
+  title: string;
+  status: string;
+  priority: string;
+  project: { uuid: string; name: string };
+}
+
+interface AssignmentsResponse {
+  ideas: AssignedIdea[];
+  tasks: AssignedTask[];
+}
+
+// ===== Formatting helpers =====
+
+function formatStatus(checkin: CheckinResponse, connectionStatus: string): string {
+  const lines: string[] = [
+    `Connection: ${connectionStatus}`,
+    `Assignments: ${checkin.pending.ideasCount} ideas, ${checkin.pending.tasksCount} tasks`,
+    `Notifications: ${checkin.notifications.unreadCount} unread`,
+  ];
+  return lines.join("\n");
+}
+
+function formatTaskList(tasks: AssignedTask[]): string {
+  if (tasks.length === 0) {
+    return "No assigned tasks.";
+  }
+
+  const lines = tasks.map(
+    (t) => `[${t.status}] [${t.priority}] ${t.title}  (${t.project.name})`
+  );
+  return `Assigned tasks (${tasks.length}):\n${lines.join("\n")}`;
+}
+
+function formatIdeaList(ideas: AssignedIdea[]): string {
+  if (ideas.length === 0) {
+    return "No assigned ideas.";
+  }
+
+  const lines = ideas.map(
+    (i) => `[${i.status}] ${i.title}  (${i.project.name})`
+  );
+  return `Assigned ideas (${ideas.length}):\n${lines.join("\n")}`;
+}
+
+const HELP_TEXT = [
+  "Chorus commands:",
+  "  /chorus           Show connection status and summary",
+  "  /chorus status    Same as above",
+  "  /chorus tasks     List assigned tasks",
+  "  /chorus ideas     List assigned ideas",
+].join("\n");
+
+// ===== Registration =====
+
+export function registerChorusCommands(
+  api: any,
+  mcpClient: ChorusMcpClient,
+  getStatus: () => string
+): void {
+  api.registerCommand({
+    name: "chorus",
+    description: "Chorus plugin commands: status, tasks, ideas",
+    async handler(ctx: { args: string }) {
+      const sub = (ctx.args ?? "").trim().toLowerCase();
+
+      // /chorus or /chorus status
+      if (!sub || sub === "status") {
+        try {
+          const checkin = (await mcpClient.callTool("chorus_checkin", {})) as CheckinResponse;
+          return { text: formatStatus(checkin, getStatus()) };
+        } catch (err) {
+          return { text: `Failed to check in: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // /chorus tasks
+      if (sub === "tasks") {
+        try {
+          const data = (await mcpClient.callTool(
+            "chorus_get_my_assignments",
+            {}
+          )) as AssignmentsResponse;
+          return { text: formatTaskList(data.tasks) };
+        } catch (err) {
+          return { text: `Failed to fetch tasks: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // /chorus ideas
+      if (sub === "ideas") {
+        try {
+          const data = (await mcpClient.callTool(
+            "chorus_get_my_assignments",
+            {}
+          )) as AssignmentsResponse;
+          return { text: formatIdeaList(data.ideas) };
+        } catch (err) {
+          return { text: `Failed to fetch ideas: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // Unknown subcommand
+      return { text: HELP_TEXT };
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+export const chorusConfigSchema = z.object({
+  chorusUrl: z
+    .string()
+    .url()
+    .describe("Chorus server URL (e.g. https://chorus.example.com)"),
+  apiKey: z
+    .string()
+    .startsWith("cho_")
+    .describe("Chorus API Key (cho_ prefix)"),
+  projectUuids: z
+    .array(z.string().uuid())
+    .optional()
+    .default([])
+    .describe("Project UUIDs to monitor. Empty = all projects"),
+  autoStart: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Auto-claim and start work on task_assigned events"),
+});
+
+export type ChorusPluginConfig = z.infer<typeof chorusConfigSchema>;