openclaw-remote 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# @openclaw/remote
+
+Connect OpenClaw agents to **Remote** project boards as native team members.
+
+Agents receive real-time task events (new tasks, comments, status changes, assignments) via SSE and reply by posting comments — just like Telegram or Slack, but for a project board.
+
+## Install
+
+```bash
+openclaw plugins install @openclaw/remote
+```
+
+Or load locally during development:
+
+```bash
+openclaw plugins load ./projects/openclaw-remote
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json5
+{
+  channels: {
+    remote: {
+      accounts: {
+        default: {
+          enabled: true,
+          baseUrl: "https://your-remote-instance.com",
+          apiKey: "claw_your_agent_api_key"
+        }
+      }
+    }
+  }
+}
+```
+
+### Config Options
+
+| Field | Required | Description |
+|---|---|---|
+| `baseUrl` | ✅ | Remote instance URL (e.g., `https://remote.clawpack.io`) |
+| `apiKey` | ✅ | Agent's Bearer token (e.g., `claw_xxx`) |
+| `enabled` | | Enable/disable the account (default: `true`) |
+| `projectId` | | Optional: filter to a single project |
+| `dmPolicy` | | Access control: `open`, `allowlist`, `disabled` (default: `open`) |
+| `allowedUserIds` | | Comma-separated user IDs for allowlist mode |
+
+### Environment Variables
+
+For the default account, you can use env vars instead of config:
+
+- `REMOTE_BASE_URL` — Base URL of the Remote instance
+- `REMOTE_API_KEY` — Agent's API key
+- `REMOTE_ALLOWED_USER_IDS` — Comma-separated allowed user IDs
+
+## How It Works
+
+### Inbound (Remote → Agent)
+
+The plugin connects to Remote's SSE endpoint (`GET /api/v1/events`) with the agent's API key. Events arrive in real-time:
+
+- **task.created** → `📋 New task created: **Fix login redirect** [bug, high]`
+- **task.updated** → `🔄 Task updated: **Fix login redirect** — status changed from "todo" to "in_progress"`
+- **task.commented** → `💬 Hugo commented on **Fix login redirect**: the redirect should go to /dashboard`
+- **task.assigned** → `👤 Task **Fix login redirect** assigned to Agent (developer)`
+
+Each event is transformed into a human-readable message and dispatched to the agent as if it were a chat message.
+
+### Outbound (Agent → Remote)
+
+When the agent replies to a task notification, the reply is automatically posted as a comment on that task via `POST /api/v1/tasks/{taskId}/comments`.
+
+The routing uses the format `remote:{taskId}` — the plugin parses this to determine which task to comment on.
+
+## Agent Tools
+
+The plugin provides 4 agent tools for board-level actions:
+
+### `remote_create_task`
+
+Create a new task on the board.
+
+```
+Parameters:
+  title: string (required)
+  description?: string
+  type?: "feature" | "task" | "bug"
+  priority?: "low" | "medium" | "high" | "urgent"
+  assigned_role_id?: string
+```
+
+### `remote_update_task`
+
+Update an existing task's status, priority, or assignment.
+
+```
+Parameters:
+  task_id: string (required)
+  status?: "todo" | "in_progress" | "review" | "done"
+  priority?: "low" | "medium" | "high" | "urgent"
+  assigned_to?: string
+  title?: string
+  description?: string
+```
+
+### `remote_list_tasks`
+
+List and filter tasks on the board.
+
+```
+Parameters:
+  status?: "todo" | "in_progress" | "review" | "done"
+  assigned_to?: string (use "me" for self)
+```
+
+### `remote_board_health`
+
+Get board health statistics: pending tasks, in-progress count, unassigned tasks, recent activity.
+
+```
+Parameters: none
+```
+
+## Setting Up on Remote
+
+1. **Add the agent to your Remote project** — hire it as a team member with an appropriate role
+2. **Get the API key** — from Team Settings → API Keys, or generate one for the agent profile
+3. **Configure the plugin** — add the `baseUrl` and `apiKey` to your OpenClaw config
+4. **Start the gateway** — `openclaw gateway start`
+
+The agent will connect to the SSE stream and start receiving events immediately.
+
+## Task Lifecycle
+
+```
+todo → in_progress → review → done
+```
+
+## Architecture
+
+```
+Remote Board  ──SSE──→  Plugin  ──dispatch──→  Agent
+                                                  │
+Agent Reply   ←──POST──  Plugin  ←──sendText──────┘
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+import { createRemotePlugin } from "./src/channel.js";
+import { setRemoteRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "remote",
+  name: "Remote",
+  description: "Remote project board channel plugin for OpenClaw",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setRemoteRuntime(api.runtime);
+    api.registerChannel({ plugin: createRemotePlugin() });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "openclaw-remote",
+  "version": "0.1.0",
+  "description": "Remote project board channel plugin for OpenClaw",
+  "type": "module",
+  "main": "index.ts",
+  "files": ["index.ts", "src/", "package.json"],
+  "keywords": ["openclaw", "remote", "channel", "plugin", "agent"],
+  "license": "MIT",
+  "openclaw": {
+    "extensions": [
+      "index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "@supabase/supabase-js": "^2.99.1"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,80 @@
+/**
+ * Account resolution: reads config from channels.remote,
+ * merges per-account overrides, falls back to environment variables.
+ */
+
+import type { RemoteChannelConfig, RemoteAccount } from "./types.js";
+
+/** Extract the channel config from the full OpenClaw config object. */
+function getChannelConfig(cfg: any): RemoteChannelConfig | undefined {
+  return cfg?.channels?.remote;
+}
+
+/** Parse allowedUserIds from string or array to string[]. */
+function parseAllowedUserIds(raw: string | string[] | undefined): string[] {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.filter(Boolean);
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * List all configured account IDs for this channel.
+ * Returns ["default"] if there's a base config with apiKey, plus any named accounts.
+ */
+export function listAccountIds(cfg: any): string[] {
+  const channelCfg = getChannelConfig(cfg);
+  if (!channelCfg) return [];
+
+  const ids = new Set<string>();
+
+  // If base config has an apiKey or env var, there's a "default" account
+  const hasBaseKey = channelCfg.apiKey || process.env.REMOTE_API_KEY;
+  if (hasBaseKey) {
+    ids.add("default");
+  }
+
+  // Named accounts
+  if (channelCfg.accounts) {
+    for (const id of Object.keys(channelCfg.accounts)) {
+      ids.add(id);
+    }
+  }
+
+  return Array.from(ids);
+}
+
+/**
+ * Resolve a specific account by ID with full defaults applied.
+ * Falls back to env vars for the "default" account.
+ */
+export function resolveAccount(cfg: any, accountId?: string | null): RemoteAccount {
+  const channelCfg = getChannelConfig(cfg) ?? {};
+  const id = accountId || "default";
+
+  // Account-specific overrides (if named account exists)
+  const accountOverride = channelCfg.accounts?.[id] ?? {};
+
+  // Env var fallbacks (primarily for the "default" account)
+  const envBaseUrl = process.env.REMOTE_BASE_URL ?? "";
+  const envApiKey = process.env.REMOTE_API_KEY ?? "";
+  const envAllowedUserIds = process.env.REMOTE_ALLOWED_USER_IDS ?? "";
+
+  // Merge: account override > base channel config > env var
+  return {
+    accountId: id,
+    enabled: accountOverride.enabled ?? channelCfg.enabled ?? true,
+    baseUrl: (accountOverride.baseUrl ?? channelCfg.baseUrl ?? envBaseUrl).replace(/\/+$/, ""),
+    apiKey: accountOverride.apiKey ?? channelCfg.apiKey ?? envApiKey,
+    projectId: accountOverride.projectId ?? channelCfg.projectId,
+    supabaseUrl: accountOverride.supabaseUrl ?? channelCfg.supabaseUrl ?? process.env.REMOTE_SUPABASE_URL,
+    supabaseKey: accountOverride.supabaseKey ?? channelCfg.supabaseKey ?? process.env.REMOTE_SUPABASE_KEY,
+    dmPolicy: accountOverride.dmPolicy ?? channelCfg.dmPolicy ?? "open",
+    allowedUserIds: parseAllowedUserIds(
+      accountOverride.allowedUserIds ?? channelCfg.allowedUserIds ?? envAllowedUserIds,
+    ),
+    webhookPath: accountOverride.webhookPath ?? channelCfg.webhookPath,
+  };
+}