@chorus-aidlc/chorus-openclaw-plugin 0.4.0 → 0.5.3

package/src/index.ts

@@ -1,107 +1,89 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type OpenClawPluginApi = any;
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
 
-import { chorusConfigSchema, type ChorusPluginConfig, validateConfigWithWarnings } from "./config.js";
+import { resolveConfig, validateConfigWithWarnings } from "./config.js";
+import { ensureChorusMcpServer } from "./mcp-registration.js";
 import { ChorusMcpClient } from "./mcp-client.js";
 import { ChorusSseListener } from "./sse-listener.js";
 import { ChorusEventRouter } from "./event-router.js";
-import { registerPmTools } from "./tools/pm-tools.js";
-import { registerDevTools } from "./tools/dev-tools.js";
-import { registerCommonTools } from "./tools/common-tools.js";
-import { registerAdminTools } from "./tools/admin-tools.js";
+import { createWake } from "./wake.js";
 import { registerChorusCommands } from "./commands.js";
 
 /**
- * Trigger the OpenClaw agent by posting a system event to the gateway's
- * /hooks/wake endpoint. This enqueues the text into the agent's prompt
- * and triggers an immediate heartbeat so the agent processes it right away.
+ * JSON-Schema config contract for the Chorus plugin.
+ *
+ * This mirrors the canonical `configSchema` in `openclaw.plugin.json`
+ * (the manifest is validated by the host BEFORE this code loads). Keep the two
+ * in sync: same property set, same `additionalProperties: false`.
  */
-async function wakeAgent(
-  gatewayUrl: string,
-  hooksToken: string,
-  text: string,
-  logger: { info: (msg: string) => void; warn: (msg: string) => void },
-) {
-  try {
-    const res = await fetch(`${gatewayUrl}/hooks/wake`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${hooksToken}`,
-      },
-      body: JSON.stringify({ text, mode: "now" }),
-    });
-    if (!res.ok) {
-      logger.warn(`Wake agent failed: HTTP ${res.status}`);
-    } else {
-      logger.info(`Agent woken: ${text.slice(0, 80)}...`);
-    }
-  } catch (err) {
-    logger.warn(`Wake agent error: ${err}`);
-  }
-}
+const CHORUS_JSON_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    chorusUrl: {
+      type: "string",
+      description: "Chorus server URL (e.g. https://chorus.example.com)",
+    },
+    apiKey: {
+      type: "string",
+      description: "Chorus API Key (cho_ prefix)",
+    },
+  },
+} as const;
 
-const plugin = {
+export default definePluginEntry({
   id: "chorus-openclaw-plugin",
   name: "Chorus",
   description:
-    "Chorus AI-DLC collaboration platform — SSE real-time events + MCP tool integration",
-  configSchema: chorusConfigSchema,
+    "Chorus AI-DLC collaboration platform — native MCP + SSE real-time events",
+  configSchema: {
+    jsonSchema: CHORUS_JSON_SCHEMA,
+    uiHints: { apiKey: { sensitive: true } },
+  },
 
   register(api: OpenClawPluginApi) {
-    const rawConfig = api.pluginConfig ?? {};
-    const config: ChorusPluginConfig = {
-      chorusUrl: rawConfig.chorusUrl || undefined,
-      apiKey: rawConfig.apiKey || undefined,
-      projectUuids: rawConfig.projectUuids ?? [],
-      autoStart: rawConfig.autoStart ?? true,
-    };
-    const logger = api.logger;
+    // 1. Discovery-mode guard: heavy runtime wiring (MCP connect, SSE socket,
+    //    config mutation) must run ONLY in "full" registration mode. In
+    //    discovery / cli-metadata / setup-* modes we declare nothing heavy.
+    if (api.registrationMode !== "full") return;
 
+    // 2. Resolve + validate config from the host-validated pluginConfig bag.
+    const config = resolveConfig(api.pluginConfig);
+    const logger = api.logger;
     if (!validateConfigWithWarnings(config, logger)) {
       return;
     }
 
-    // After validateConfigWithWarnings, chorusUrl and apiKey are guaranteed present
+    // After validateConfigWithWarnings, chorusUrl and apiKey are present.
     const chorusUrl = config.chorusUrl!;
     const apiKey = config.apiKey!;
 
-    // Resolve gateway URL and hooks token from OpenClaw config
-    const gatewayPort = api.config?.gateway?.port ?? 18789;
-    const gatewayUrl = `http://127.0.0.1:${gatewayPort}`;
-    const hooksToken = api.config?.hooks?.token ?? "";
+    logger.info(`Chorus plugin initializing — ${chorusUrl}`);
 
-    logger.info(
-      `Chorus plugin initializing — ${chorusUrl} (${config.projectUuids?.length || "all"} projects)`
+    // 3. Ensure the Chorus MCP server is registered with OpenClaw so the agent
+    //    gains native chorus__* tools (fire-and-log; real impl in sibling task).
+    void ensureChorusMcpServer(api, config).catch((err) =>
+      logger.error(`MCP registration failed: ${err}`),
     );
 
-    // --- MCP Client ---
-    const mcpClient = new ChorusMcpClient({
-      chorusUrl,
-      apiKey,
-      logger,
-    });
+    // 4. Slim MCP client for the plugin's own synchronous calls (checkin,
+    //    assignments, notifications back-fill).
+    const mcpClient = new ChorusMcpClient({ chorusUrl, apiKey, logger });
 
-    // --- Event Router ---
+    // 5. Event router. Wakes the agent in-process by running an embedded agent
+    //    turn via `api.runtime.agent.runEmbeddedAgent` (see wake.ts). `createWake`
+    //    resolves the main agent session + configured model on each wake and
+    //    gracefully DROPS (logs + returns) when it cannot run — it never throws,
+    //    so the SSE service stays alive even on a host that exposes no session.
     const eventRouter = new ChorusEventRouter({
       mcpClient,
-      config,
       logger,
-      triggerAgent: (message: string, _metadata?: Record<string, unknown>) => {
-        // Use /hooks/wake to enqueue a system event + trigger immediate heartbeat
-        if (hooksToken) {
-          wakeAgent(gatewayUrl, hooksToken, message, logger);
-        } else {
-          logger.warn(
-            `[Chorus] Cannot wake agent — gateway.auth.token not configured. Event: ${message.slice(0, 100)}`
-          );
-        }
-      },
+      wake: createWake(api, logger),
     });
 
-    // --- SSE Listener (background service) ---
+    // 6. Background SSE service. The SSE socket opens only inside start(), which
+    //    the host calls in full mode — keeping the heavy socket gated.
     let sseListener: ChorusSseListener | null = null;
-
     api.registerService({
       id: "chorus-sse",
       async start() {
@@ -111,7 +93,6 @@ const plugin = {
           logger,
           onEvent: (event) => eventRouter.dispatch(event),
           onReconnect: async () => {
-            // Back-fill missed notifications after reconnect
             try {
               const result = (await mcpClient.callTool("chorus_get_notifications", {
                 status: "unread",
@@ -134,15 +115,7 @@ const plugin = {
       },
     });
 
-    // --- Tools ---
-    registerPmTools(api, mcpClient);
-    registerDevTools(api, mcpClient);
-    registerCommonTools(api, mcpClient);
-    registerAdminTools(api, mcpClient);
-
-    // --- Commands ---
+    // 7. /chorus command (status | tasks | ideas | skills).
     registerChorusCommands(api, mcpClient, () => sseListener?.status ?? "disconnected");
   },
-};
-
-export default plugin;
+});

package/src/mcp-client.ts

@@ -1,3 +1,20 @@
+/**
+ * Plugin-INTERNAL MCP client.
+ *
+ * This is NOT how the agent gets Chorus tools — those are exposed natively by
+ * OpenClaw connecting to the `mcp.servers.chorus` entry written by
+ * `ensureChorusMcpServer` (see mcp-registration.ts). The plugin no longer
+ * hand-wraps any Chorus tool with `api.registerTool`.
+ *
+ * This client exists only for the plugin's OWN synchronous calls into Chorus:
+ *   - `/chorus` command: chorus_checkin, chorus_get_my_assignments,
+ *     chorus_get_available_ideas (see commands.ts)
+ *   - SSE reconnect back-fill: chorus_get_notifications (see index.ts)
+ *
+ * No agent-facing tool depends on it. Keep it a generic StreamableHTTP
+ * `callTool` client (lazy connect + 404 reconnect); do not grow it into a tool
+ * surface.
+ */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 

package/src/mcp-registration.ts

@@ -0,0 +1,142 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { ChorusPluginConfig } from "./config.js";
+
+/**
+ * Shape of the `mcp.servers.chorus` entry we write into OpenClaw config.
+ *
+ * Mirrors the relevant subset of OpenClaw's `McpServerConfig`
+ * (`../openclaw/src/config/types.mcp.ts:12`): a remote streamable-http MCP
+ * server reachable at `<chorusUrl>/api/mcp` with a Bearer auth header.
+ */
+interface ChorusMcpServerEntry {
+  url: string;
+  transport: "streamable-http";
+  headers: { Authorization: string };
+}
+
+/**
+ * Build the desired `mcp.servers.chorus` entry for the current config.
+ */
+function buildDesiredEntry(chorusUrl: string, apiKey: string): ChorusMcpServerEntry {
+  return {
+    url: new URL("/api/mcp", chorusUrl).toString(),
+    transport: "streamable-http",
+    headers: { Authorization: `Bearer ${apiKey}` },
+  };
+}
+
+/**
+ * Shallow-equal the fields that define the desired entry. We only compare the
+ * three load-bearing fields (url, transport, Authorization header) so an
+ * operator-added extra field — e.g. `connectionTimeoutMs` — does not force a
+ * rewrite-and-reload on every activation.
+ */
+function entryMatches(existing: unknown, desired: ChorusMcpServerEntry): boolean {
+  if (!existing || typeof existing !== "object") return false;
+  const e = existing as {
+    url?: unknown;
+    transport?: unknown;
+    headers?: { Authorization?: unknown } | undefined;
+  };
+  return (
+    e.url === desired.url &&
+    e.transport === desired.transport &&
+    e.headers?.Authorization === desired.headers.Authorization
+  );
+}
+
+/**
+ * Ensure the Chorus MCP server is registered with OpenClaw so the agent gains
+ * the native `chorus__*` tools.
+ *
+ * Writes (idempotently) an `mcp.servers.chorus` entry into the OpenClaw config
+ * via `api.runtime.config.mutateConfigFile` — a remote streamable-http MCP
+ * server with Bearer auth. OpenClaw then connects to the remote Chorus MCP
+ * server on (re)load and auto-exposes its tools under the `chorus__` prefix; we
+ * never re-declare those tools with `api.registerTool`.
+ *
+ * Behavior:
+ * - Missing `chorusUrl`/`apiKey`: do NOT write; warn naming the missing field(s).
+ * - Existing entry already equals the desired entry: return without writing
+ *   (idempotent — no config reload triggered).
+ * - Otherwise: `mutateConfigFile({ afterWrite: { mode: "auto" }, mutate })`,
+ *   mutating the draft in place (OpenClaw's `mutate` callback receives a
+ *   structuredClone draft and persists the in-place mutation).
+ * - Any rejection from `mutateConfigFile` (or the runtime API being absent) is
+ *   logged at error level and swallowed — registration failure must never crash
+ *   the gateway, so the SSE service and `/chorus` command still register.
+ */
+export async function ensureChorusMcpServer(
+  api: OpenClawPluginApi,
+  cfg: ChorusPluginConfig,
+): Promise<void> {
+  const logger = api.logger;
+
+  // 1. Required-config guard: do not write a half-formed entry.
+  const missing: string[] = [];
+  if (!cfg.chorusUrl) missing.push("chorusUrl");
+  if (!cfg.apiKey) missing.push("apiKey");
+  if (missing.length > 0) {
+    logger.warn(
+      `[Chorus] Skipping MCP server registration — missing required config: ${missing.join(", ")}`,
+    );
+    return;
+  }
+
+  const desired = buildDesiredEntry(cfg.chorusUrl!, cfg.apiKey!);
+
+  try {
+    // `api.runtime` is permissively typed via the SDK shim; narrow to the
+    // config surface we use (current() + mutateConfigFile). At runtime the host
+    // provides the real `PluginRuntimeCore.config` API
+    // (../openclaw/src/plugins/runtime/types-core.ts:145).
+    const runtimeConfig = (
+      api.runtime as
+        | {
+            config?: {
+              current?: () => { mcp?: { servers?: Record<string, unknown> } } | undefined;
+              mutateConfigFile?: (params: {
+                afterWrite: { mode: "auto" };
+                mutate: (draft: {
+                  mcp?: { servers?: Record<string, unknown> };
+                }) => void;
+              }) => Promise<unknown>;
+            };
+          }
+        | undefined
+    )?.config;
+
+    if (!runtimeConfig?.mutateConfigFile) {
+      logger.error(
+        "[Chorus] MCP server registration failed — runtime.config.mutateConfigFile is unavailable on this host",
+      );
+      return;
+    }
+
+    // 2. Idempotency: skip the write (and the reload it triggers) when the
+    //    existing entry already matches.
+    const existing = runtimeConfig.current?.()?.mcp?.servers?.chorus;
+    if (entryMatches(existing, desired)) {
+      logger.info("[Chorus] MCP server entry already up to date — no config change");
+      return;
+    }
+
+    // 3. Write the entry, mutating the draft in place.
+    await runtimeConfig.mutateConfigFile({
+      afterWrite: { mode: "auto" },
+      mutate: (draft) => {
+        const mcp = (draft.mcp ??= {});
+        const servers = (mcp.servers ??= {});
+        servers.chorus = desired;
+      },
+    });
+
+    logger.info(`[Chorus] Registered MCP server entry — ${desired.url}`);
+  } catch (err) {
+    // 4. Never crash the gateway: log at error level and continue so the SSE
+    //    service and /chorus command still register.
+    logger.error(
+      `[Chorus] MCP server registration failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/openclaw-sdk.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Ambient module shim for the OpenClaw 2026.5.x Plugin SDK.
+ *
+ * WHY THIS EXISTS:
+ * The plugin's runtime entry imports `definePluginEntry` from the subpath
+ * `openclaw/plugin-sdk/plugin-entry`. That subpath export only exists in the
+ * OpenClaw 2026.5.30 Plugin SDK. The `openclaw` package currently resolvable in
+ * this workspace's node_modules is an older build (2026.3.x) that does NOT
+ * export `./plugin-sdk/plugin-entry`, so `tsc` cannot resolve the import from
+ * the real package and would fail type-checking.
+ *
+ * Rather than bundle/install the full 2026.5.30 OpenClaw package just to satisfy
+ * `tsc --noEmit`, we declare a minimal ambient module with a permissive
+ * signature. At install/runtime the real host provides the actual SDK
+ * (the package.json `peerDependencies.openclaw` floor + the
+ * `openclaw.compat.pluginApi >=2026.5.30` gate enforce the version contract);
+ * this declaration is purely a compile-time bridge.
+ *
+ * The signature mirrors `definePluginEntry` from
+ * `../openclaw/src/plugin-sdk/plugin-entry.ts` (verified against OpenClaw
+ * 2026.5.30). `api` is typed `unknown`-ish via a permissive shape so the entry
+ * file stays readable without pulling in the full `OpenClawPluginApi` type
+ * graph. When the workspace upgrades to an `openclaw` build that exports
+ * `plugin-sdk/plugin-entry`, delete this shim and rely on the real types.
+ */
+declare module "openclaw/plugin-sdk/plugin-entry" {
+  /** Public registration modes surfaced to plugin `register(api)` calls. */
+  export type PluginRegistrationMode =
+    | "full"
+    | "discovery"
+    | "tool-discovery"
+    | "setup-only"
+    | "setup-runtime"
+    | "cli-metadata";
+
+  /** JSON-Schema / parser config contract accepted by plugin entries. */
+  export type OpenClawPluginConfigSchema = {
+    safeParse?: (value: unknown) => unknown;
+    parse?: (value: unknown) => unknown;
+    validate?: (value: unknown) => unknown;
+    uiHints?: Record<string, unknown>;
+    jsonSchema?: Record<string, unknown>;
+  };
+
+  /**
+   * Permissive subset of `OpenClawPluginApi` used by this plugin's entry.
+   *
+   * Only the members this plugin touches are typed; the index signature keeps
+   * the rest of the (large) host API accessible without importing it.
+   */
+  export type OpenClawPluginApi = {
+    registrationMode: PluginRegistrationMode;
+    pluginConfig?: Record<string, unknown>;
+    config?: Record<string, unknown> & {
+      gateway?: { port?: number };
+      hooks?: { token?: string };
+    };
+    logger: {
+      debug?: (message: string) => void;
+      info: (message: string) => void;
+      warn: (message: string) => void;
+      error: (message: string) => void;
+    };
+    registerService: (service: {
+      id: string;
+      start: (...args: unknown[]) => void | Promise<void>;
+      stop?: (...args: unknown[]) => void | Promise<void>;
+    }) => void;
+    registerCommand: (command: unknown) => void;
+    registerTool: (tool: unknown, opts?: unknown) => void;
+    runtime?: unknown;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+  };
+
+  export type DefinePluginEntryOptions = {
+    id: string;
+    name: string;
+    description: string;
+    configSchema?: OpenClawPluginConfigSchema | (() => OpenClawPluginConfigSchema);
+    register: (api: OpenClawPluginApi) => void;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+  };
+
+  export type DefinedPluginEntry = {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: OpenClawPluginConfigSchema;
+    register: (api: OpenClawPluginApi) => void;
+  };
+
+  export function definePluginEntry(options: DefinePluginEntryOptions): DefinedPluginEntry;
+}