openclaw-remote 0.1.0

package/src/channel.ts

@@ -0,0 +1,544 @@
+/**
+ * Remote Channel Plugin for OpenClaw.
+ *
+ * Implements the ChannelPlugin interface following the Synology Chat pattern.
+ * Connects to a Remote project board via SSE for inbound events and
+ * posts comments for outbound messages.
+ */
+
+import {
+  DEFAULT_ACCOUNT_ID,
+  setAccountEnabledInConfigSection,
+  waitUntilAbort,
+  optionalStringEnum,
+} from "openclaw/plugin-sdk/compat";
+import { Type } from "@sinclair/typebox";
+import { listAccountIds, resolveAccount } from "./accounts.js";
+import { postComment, createTask, updateTask, listTasks, getHeartbeat } from "./client.js";
+import { connectRealtime } from "./realtime-listener.js";
+import { formatEvent } from "./event-formatter.js";
+import { getRemoteRuntime } from "./runtime.js";
+import type { RemoteAccount } from "./types.js";
+
+const CHANNEL_ID = "remote";
+
+export function createRemotePlugin() {
+  return {
+    id: CHANNEL_ID,
+
+    meta: {
+      id: CHANNEL_ID,
+      label: "Remote",
+      selectionLabel: "Remote (Project Board)",
+      detailLabel: "Remote (Project Board)",
+      docsPath: "/channels/remote",
+      blurb: "Connect agents to Remote project boards as team members",
+      order: 95,
+    },
+
+    capabilities: {
+      chatTypes: ["direct" as const, "group" as const],
+      media: false,
+      threads: true,
+      reactions: false,
+      edit: false,
+      unsend: false,
+      reply: false,
+      effects: false,
+      blockStreaming: false,
+    },
+
+    reload: { configPrefixes: [`channels.${CHANNEL_ID}`] },
+
+    config: {
+      listAccountIds: (cfg: any) => listAccountIds(cfg),
+
+      resolveAccount: (cfg: any, accountId?: string | null) => resolveAccount(cfg, accountId),
+
+      defaultAccountId: (_cfg: any) => DEFAULT_ACCOUNT_ID,
+
+      setAccountEnabled: ({ cfg, accountId, enabled }: any) => {
+        const channelConfig = cfg?.channels?.[CHANNEL_ID] ?? {};
+        if (accountId === DEFAULT_ACCOUNT_ID) {
+          return {
+            ...cfg,
+            channels: {
+              ...cfg.channels,
+              [CHANNEL_ID]: { ...channelConfig, enabled },
+            },
+          };
+        }
+        return setAccountEnabledInConfigSection({
+          cfg,
+          sectionKey: `channels.${CHANNEL_ID}`,
+          accountId,
+          enabled,
+        });
+      },
+    },
+
+    security: {
+      resolveDmPolicy: ({
+        cfg,
+        accountId,
+        account,
+      }: {
+        cfg: any;
+        accountId?: string | null;
+        account: RemoteAccount;
+      }) => {
+        const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+        const channelCfg = (cfg as any).channels?.remote;
+        const useAccountPath = Boolean(channelCfg?.accounts?.[resolvedAccountId]);
+        const basePath = useAccountPath
+          ? `channels.remote.accounts.${resolvedAccountId}.`
+          : "channels.remote.";
+        return {
+          policy: account.dmPolicy ?? "open",
+          allowFrom: account.allowedUserIds ?? [],
+          policyPath: `${basePath}dmPolicy`,
+          allowFromPath: basePath,
+          approveHint: "openclaw pairing approve remote <code>",
+          normalizeEntry: (raw: string) => raw.toLowerCase().trim(),
+        };
+      },
+      collectWarnings: ({ account }: { account: RemoteAccount }) => {
+        const warnings: string[] = [];
+        if (!account.baseUrl) {
+          warnings.push(
+            "- Remote: baseUrl is not configured. The plugin cannot connect to the Remote API.",
+          );
+        }
+        if (!account.apiKey) {
+          warnings.push(
+            "- Remote: apiKey is not configured. The plugin cannot authenticate with the Remote API.",
+          );
+        }
+        if (account.dmPolicy === "open") {
+          warnings.push(
+            '- Remote: dmPolicy="open" allows any board event to trigger agent actions. Consider "allowlist" for production use.',
+          );
+        }
+        return warnings;
+      },
+    },
+
+    messaging: {
+      normalizeTarget: (target: string) => {
+        const trimmed = target.trim();
+        if (!trimmed) return undefined;
+        return trimmed.replace(/^remote:/i, "").trim();
+      },
+      targetResolver: {
+        looksLikeId: (id: string) => {
+          const trimmed = id?.trim();
+          if (!trimmed) return false;
+          return /^remote:/i.test(trimmed) || /^[a-f0-9-]+$/i.test(trimmed);
+        },
+        hint: "<taskId>",
+      },
+    },
+
+    directory: {
+      self: async () => null,
+      listPeers: async () => [],
+      listGroups: async () => [],
+    },
+
+    outbound: {
+      deliveryMode: "gateway" as const,
+      textChunkLimit: 4000,
+
+      sendText: async ({ to, text, accountId, cfg }: any) => {
+        const account: RemoteAccount = resolveAccount(cfg ?? {}, accountId);
+
+        if (!account.baseUrl || !account.apiKey) {
+          throw new Error("Remote baseUrl or apiKey not configured");
+        }
+
+        // Parse the target: `remote:{taskId}` → extract taskId
+        const taskId = extractTaskId(to);
+        if (!taskId) {
+          throw new Error(`Invalid Remote target: ${to}. Expected format: remote:{taskId}`);
+        }
+
+        const result = await postComment(account, taskId, text);
+        if (!result.ok) {
+          throw new Error(`Failed to post comment to Remote: ${result.error}`);
+        }
+
+        const commentId = result.data.comment?.id ?? `rc-${Date.now()}`;
+        return { channel: CHANNEL_ID, messageId: commentId, chatId: `remote:${taskId}` };
+      },
+    },
+
+    gateway: {
+      startAccount: async (ctx: any) => {
+        const { cfg, accountId, log, abortSignal, channelRuntime } = ctx;
+        const account = resolveAccount(cfg, accountId);
+
+        if (!account.enabled) {
+          log?.info?.(`Remote account ${accountId} is disabled, skipping`);
+          return waitUntilAbort(abortSignal);
+        }
+
+        if (!account.baseUrl || !account.apiKey) {
+          log?.warn?.(
+            `Remote account ${accountId} not fully configured (missing baseUrl or apiKey)`,
+          );
+          return waitUntilAbort(abortSignal);
+        }
+
+        if (!account.supabaseUrl || !account.supabaseKey) {
+          log?.warn?.(
+            `Remote account ${accountId} missing supabaseUrl or supabaseKey — Realtime events disabled. Agent tools still work.`,
+          );
+        }
+
+        log?.info?.(
+          `Starting Remote channel (account: ${accountId}, url: ${account.baseUrl})`,
+        );
+
+        // Use channelRuntime from gateway context (preferred), fall back to stored runtime
+        const runtime = channelRuntime ?? getRemoteRuntime().channel;
+
+        // If Supabase config is present, connect via Realtime for live events
+        let realtimeHandle: { unsubscribe: () => Promise<void> } | null = null;
+
+        if (account.supabaseUrl && account.supabaseKey) {
+          try {
+            realtimeHandle = connectRealtime(
+              account,
+              async (event) => {
+                const formatted = formatEvent(event);
+                if (!formatted) return;
+
+                try {
+                  const rt = getRemoteRuntime();
+                  const currentCfg = await rt.config.loadConfig();
+
+                  const sessionKey = `remote:${account.accountId}:${formatted.taskId}`;
+
+                  const msgCtx = runtime.reply.finalizeInboundContext({
+                    Body: formatted.body,
+                    RawBody: formatted.body,
+                    CommandBody: formatted.body,
+                    From: `remote:${formatted.senderId ?? "board"}`,
+                    To: `remote:${account.accountId}`,
+                    SessionKey: sessionKey,
+                    AccountId: account.accountId,
+                    OriginatingChannel: CHANNEL_ID,
+                    OriginatingTo: `remote:${formatted.taskId}`,
+                    ChatType: formatted.isDirect ? "direct" : "group",
+                    SenderName: formatted.senderName ?? "Remote Board",
+                    SenderId: formatted.senderId ?? "board",
+                    Provider: CHANNEL_ID,
+                    Surface: CHANNEL_ID,
+                    ConversationLabel: formatted.taskTitle ?? `Task ${formatted.taskId}`,
+                    Timestamp: Date.now(),
+                  });
+
+                  await runtime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                    ctx: msgCtx,
+                    cfg: currentCfg,
+                    dispatcherOptions: {
+                      deliver: async (payload: { text?: string; mediaUrl?: string; isReasoning?: boolean }, _info) => {
+                        if (payload.isReasoning) return;
+                        const text = payload?.text;
+                        if (text) {
+                          await postComment(account, formatted.taskId, text);
+                        }
+                      },
+                      onReplyStart: () => {
+                        log?.info?.(`Agent reply started for task ${formatted.taskId}`);
+                      },
+                    },
+                  });
+                } catch (err) {
+                  log?.error?.(
+                    `Error dispatching Remote event: ${err instanceof Error ? err.message : String(err)}`,
+                  );
+                }
+              },
+              (err) => {
+                log?.warn?.(`Realtime error: ${err.message}`);
+              },
+              log,
+            );
+          } catch (err) {
+            log?.error?.(`Failed to connect Realtime: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+
+        // Keep alive until abort signal fires
+        await waitUntilAbort(abortSignal, async () => {
+          if (realtimeHandle) {
+            await realtimeHandle.unsubscribe();
+          }
+        });
+
+        log?.info?.(`Stopped Remote channel (account: ${accountId})`);
+      },
+
+      stopAccount: async (ctx: any) => {
+        ctx.log?.info?.(`Remote account ${ctx.accountId} stopped`);
+      },
+    },
+
+    agentTools: ((params: { cfg?: any }) => {
+      const cfg = params.cfg;
+
+      return [
+        // 1. remote_create_task
+        {
+          name: "remote_create_task",
+          label: "Create a new task on the Remote project board",
+          description:
+            "Create a new task on the Remote project board. Specify title, and optionally description, type (feature/task/bug), priority (low/medium/high/urgent), and assigned_role_id.",
+          parameters: Type.Object({
+            title: Type.String({ description: "Task title" }),
+            description: Type.Optional(Type.String({ description: "Task description" })),
+            type: optionalStringEnum(["feature", "task", "bug"] as const, {
+              description: "Task type: feature, task, or bug",
+            }),
+            priority: optionalStringEnum(["low", "medium", "high", "urgent"] as const, {
+              description: "Task priority: low, medium, high, or urgent",
+            }),
+            assigned_role_id: Type.Optional(
+              Type.String({ description: "Role ID to assign the task to" }),
+            ),
+          }),
+          execute: async (_toolCallId: string, args: any) => {
+            const account = resolveAccount(cfg ?? {});
+            const result = await createTask(account, {
+              title: args.title,
+              description: args.description,
+              type: args.type,
+              priority: args.priority,
+              assigned_role_id: args.assigned_role_id,
+            });
+
+            if (!result.ok) {
+              return {
+                content: [{ type: "text" as const, text: `❌ Failed to create task: ${result.error}` }],
+                details: { ok: false, error: result.error },
+              };
+            }
+
+            const task = result.data.task;
+            const text = [
+              `✅ Task created successfully!`,
+              `- **ID**: ${task.id}`,
+              `- **Title**: ${task.title}`,
+              `- **Type**: ${task.type}`,
+              `- **Priority**: ${task.priority}`,
+              `- **Status**: ${task.status}`,
+            ].join("\n");
+
+            return {
+              content: [{ type: "text" as const, text }],
+              details: { ok: true, task },
+            };
+          },
+        },
+
+        // 2. remote_update_task
+        {
+          name: "remote_update_task",
+          label: "Update a task on the Remote project board",
+          description:
+            "Update an existing task on the Remote project board. Specify the task_id and any fields to change: status (todo/in_progress/review/done), priority, assigned_to, title, or description.",
+          parameters: Type.Object({
+            task_id: Type.String({ description: "ID of the task to update" }),
+            status: optionalStringEnum(["todo", "in_progress", "review", "done"] as const, {
+              description: "New status: todo, in_progress, review, or done",
+            }),
+            priority: optionalStringEnum(["low", "medium", "high", "urgent"] as const, {
+              description: "New priority: low, medium, high, or urgent",
+            }),
+            assigned_to: Type.Optional(
+              Type.String({ description: "User or role to assign the task to" }),
+            ),
+            title: Type.Optional(Type.String({ description: "New task title" })),
+            description: Type.Optional(Type.String({ description: "New task description" })),
+          }),
+          execute: async (_toolCallId: string, args: any) => {
+            const account = resolveAccount(cfg ?? {});
+            const { task_id, ...updates } = args;
+
+            const result = await updateTask(account, task_id, updates);
+
+            if (!result.ok) {
+              return {
+                content: [{ type: "text" as const, text: `❌ Failed to update task: ${result.error}` }],
+                details: { ok: false, error: result.error },
+              };
+            }
+
+            const task = result.data.task;
+            const text = [
+              `✅ Task updated successfully!`,
+              `- **ID**: ${task.id}`,
+              `- **Title**: ${task.title}`,
+              `- **Status**: ${task.status}`,
+              `- **Priority**: ${task.priority}`,
+            ].join("\n");
+
+            return {
+              content: [{ type: "text" as const, text }],
+              details: { ok: true, task },
+            };
+          },
+        },
+
+        // 3. remote_list_tasks
+        {
+          name: "remote_list_tasks",
+          label: "List tasks on the Remote project board",
+          description:
+            "List tasks on the Remote project board. Optionally filter by status (todo/in_progress/review/done) and assigned_to (use 'me' for tasks assigned to the agent).",
+          parameters: Type.Object({
+            status: optionalStringEnum(["todo", "in_progress", "review", "done"] as const, {
+              description: "Filter by status: todo, in_progress, review, or done",
+            }),
+            assigned_to: Type.Optional(
+              Type.String({ description: "Filter by assignee. Use 'me' for self." }),
+            ),
+          }),
+          execute: async (_toolCallId: string, args: any) => {
+            const account = resolveAccount(cfg ?? {});
+            const result = await listTasks(account, {
+              status: args.status,
+              assigned_to: args.assigned_to,
+            });
+
+            if (!result.ok) {
+              return {
+                content: [{ type: "text" as const, text: `❌ Failed to list tasks: ${result.error}` }],
+                details: { ok: false, error: result.error },
+              };
+            }
+
+            const tasks = result.data.tasks;
+            if (tasks.length === 0) {
+              const filterDesc = [
+                args.status && `status=${args.status}`,
+                args.assigned_to && `assigned_to=${args.assigned_to}`,
+              ]
+                .filter(Boolean)
+                .join(", ");
+
+              return {
+                content: [
+                  {
+                    type: "text" as const,
+                    text: `📋 No tasks found${filterDesc ? ` (filters: ${filterDesc})` : ""}.`,
+                  },
+                ],
+                details: { ok: true, tasks: [] },
+              };
+            }
+
+            const lines = [`📋 **${tasks.length} task(s) found:**`, ""];
+            for (const task of tasks) {
+              const meta = [task.type, task.priority, task.status].filter(Boolean).join(", ");
+              lines.push(`- **${task.title}** [${meta}] (id: ${task.id})`);
+              if (task.description) {
+                const desc = task.description.length > 80
+                  ? task.description.slice(0, 80) + "…"
+                  : task.description;
+                lines.push(`  ${desc}`);
+              }
+            }
+
+            return {
+              content: [{ type: "text" as const, text: lines.join("\n") }],
+              details: { ok: true, tasks },
+            };
+          },
+        },
+
+        // 4. remote_board_health
+        {
+          name: "remote_board_health",
+          label: "Get board health stats from Remote",
+          description:
+            "Get board health and statistics from the Remote project board: pending tasks, in-progress tasks, unassigned tasks, recent activity, and your roles.",
+          parameters: Type.Object({}),
+          execute: async (_toolCallId: string, _args: any) => {
+            const account = resolveAccount(cfg ?? {});
+            const result = await getHeartbeat(account);
+
+            if (!result.ok) {
+              return {
+                content: [{ type: "text" as const, text: `❌ Failed to get board health: ${result.error}` }],
+                details: { ok: false, error: result.error },
+              };
+            }
+
+            const h = result.data;
+            const text = [
+              `📊 **Board Health Summary**`,
+              "",
+              `- **Pending tasks**: ${h.pending_tasks}`,
+              `- **In progress**: ${h.in_progress_tasks}`,
+              `- **Unassigned**: ${h.unassigned_tasks}`,
+              `- **Activity (24h)**: ${h.recent_activity_24h}`,
+              `- **My roles**: ${h.my_roles?.join(", ") || "none"}`,
+              `- **Checked at**: ${h.checked_at}`,
+            ].join("\n");
+
+            return {
+              content: [{ type: "text" as const, text }],
+              details: { ok: true, heartbeat: h },
+            };
+          },
+        },
+      ];
+    }) as any,
+
+    agentPrompt: {
+      messageToolHints: () => [
+        "",
+        "### Remote Project Board",
+        "You are connected to a Remote project board. Messages you receive are task events (new tasks, comments, status changes, assignments).",
+        "",
+        "**Replying**: When you reply to a task notification, your reply is posted as a comment on that task.",
+        "",
+        "**Available tools**:",
+        "- `remote_create_task` — Create a new task (specify title, type, priority, etc.)",
+        "- `remote_update_task` — Update a task (change status, priority, assignment, etc.)",
+        "- `remote_list_tasks` — List/filter tasks on the board",
+        "- `remote_board_health` — Get board health stats (pending, in-progress, unassigned counts)",
+        "",
+        "**Task lifecycle**: todo → in_progress → review → done",
+        "**Task types**: feature, task, bug",
+        "**Priorities**: low, medium, high, urgent",
+        "",
+        "**Best practices**:",
+        "- When assigned a task, acknowledge it and move to in_progress",
+        "- Use comments to communicate progress and blockers",
+        "- Move tasks to review when ready for review, done when complete",
+        "- Keep task descriptions and comments clear and actionable",
+      ],
+    },
+  };
+}
+
+/**
+ * Extract the task ID from a target string.
+ * Supports formats: "remote:{taskId}", "{taskId}"
+ */
+function extractTaskId(to: string): string | undefined {
+  if (!to) return undefined;
+  const trimmed = to.trim();
+
+  // Strip "remote:" prefix if present
+  const match = trimmed.match(/^remote:(.+)$/i);
+  if (match) return match[1];
+
+  // Bare task ID (UUID-like or other ID format)
+  if (trimmed.length > 0) return trimmed;
+
+  return undefined;
+}