openclaw-remote 0.1.0

package/src/client.ts

@@ -0,0 +1,226 @@
+/**
+ * HTTP client for the Remote API.
+ * All functions use standard fetch() with Bearer auth.
+ */
+
+import type {
+  RemoteAccount,
+  RemoteTask,
+  RemoteComment,
+  RemoteHeartbeat,
+  RemoteActivity,
+  ApiResult,
+} from "./types.js";
+
+/** Build standard headers for Remote API requests. */
+function buildHeaders(account: RemoteAccount): Record<string, string> {
+  return {
+    Authorization: `Bearer ${account.apiKey}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+}
+
+/** Build the full URL for a given API path. */
+function buildUrl(account: RemoteAccount, path: string): string {
+  return `${account.baseUrl}${path}`;
+}
+
+/** Safe JSON fetch wrapper with error handling. */
+async function apiFetch<T>(
+  url: string,
+  options: RequestInit,
+): Promise<ApiResult<T>> {
+  try {
+    const res = await fetch(url, { ...options, signal: AbortSignal.timeout(30_000) });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      return {
+        ok: false,
+        error: `HTTP ${res.status}: ${res.statusText}${body ? ` — ${body.slice(0, 200)}` : ""}`,
+      };
+    }
+
+    const data = (await res.json()) as T;
+    return { ok: true, data };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/**
+ * Post a comment on a task.
+ */
+export async function postComment(
+  account: RemoteAccount,
+  taskId: string,
+  content: string,
+): Promise<ApiResult<{ comment: RemoteComment }>> {
+  return apiFetch<{ comment: RemoteComment }>(
+    buildUrl(account, `/api/v1/tasks/${encodeURIComponent(taskId)}/comments`),
+    {
+      method: "POST",
+      headers: buildHeaders(account),
+      body: JSON.stringify({ content }),
+    },
+  );
+}
+
+/**
+ * Create a new task.
+ */
+export async function createTask(
+  account: RemoteAccount,
+  task: {
+    title: string;
+    description?: string;
+    type?: string;
+    priority?: string;
+    assigned_role_id?: string;
+    epic_id?: string;
+  },
+): Promise<ApiResult<{ task: RemoteTask }>> {
+  return apiFetch<{ task: RemoteTask }>(
+    buildUrl(account, "/api/v1/tasks"),
+    {
+      method: "POST",
+      headers: buildHeaders(account),
+      body: JSON.stringify(task),
+    },
+  );
+}
+
+/**
+ * Update an existing task.
+ */
+export async function updateTask(
+  account: RemoteAccount,
+  taskId: string,
+  updates: {
+    status?: string;
+    priority?: string;
+    assigned_to?: string;
+    title?: string;
+    description?: string;
+    ping?: boolean;
+  },
+): Promise<ApiResult<{ task: RemoteTask }>> {
+  return apiFetch<{ task: RemoteTask }>(
+    buildUrl(account, `/api/v1/tasks/${encodeURIComponent(taskId)}`),
+    {
+      method: "PATCH",
+      headers: buildHeaders(account),
+      body: JSON.stringify(updates),
+    },
+  );
+}
+
+/**
+ * List tasks with optional filters.
+ */
+export async function listTasks(
+  account: RemoteAccount,
+  filters?: { status?: string; assigned_to?: string },
+): Promise<ApiResult<{ tasks: RemoteTask[] }>> {
+  const params = new URLSearchParams();
+  if (filters?.status) params.set("status", filters.status);
+  if (filters?.assigned_to) params.set("assigned_to", filters.assigned_to);
+
+  const qs = params.toString();
+  const path = `/api/v1/tasks${qs ? `?${qs}` : ""}`;
+
+  return apiFetch<{ tasks: RemoteTask[] }>(
+    buildUrl(account, path),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}
+
+/**
+ * Get a single task with comments.
+ */
+export async function getTask(
+  account: RemoteAccount,
+  taskId: string,
+): Promise<ApiResult<{ task: RemoteTask }>> {
+  return apiFetch<{ task: RemoteTask }>(
+    buildUrl(account, `/api/v1/tasks/${encodeURIComponent(taskId)}`),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}
+
+/**
+ * Get board health / heartbeat.
+ */
+export async function getHeartbeat(
+  account: RemoteAccount,
+): Promise<ApiResult<RemoteHeartbeat>> {
+  return apiFetch<RemoteHeartbeat>(
+    buildUrl(account, "/api/v1/heartbeat"),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}
+
+/**
+ * Get activity feed.
+ */
+export async function getActivity(
+  account: RemoteAccount,
+  since?: string,
+  limit?: number,
+): Promise<ApiResult<{ activity: RemoteActivity[] }>> {
+  const params = new URLSearchParams();
+  if (since) params.set("since", since);
+  if (limit != null) params.set("limit", String(limit));
+
+  const qs = params.toString();
+  const path = `/api/v1/activity${qs ? `?${qs}` : ""}`;
+
+  return apiFetch<{ activity: RemoteActivity[] }>(
+    buildUrl(account, path),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}
+
+/**
+ * Get project info.
+ */
+export async function getProject(
+  account: RemoteAccount,
+): Promise<ApiResult<any>> {
+  return apiFetch<any>(
+    buildUrl(account, "/api/v1/project"),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}
+
+/**
+ * Get roles.
+ */
+export async function getRoles(
+  account: RemoteAccount,
+): Promise<ApiResult<any>> {
+  return apiFetch<any>(
+    buildUrl(account, "/api/v1/roles"),
+    {
+      method: "GET",
+      headers: buildHeaders(account),
+    },
+  );
+}

package/src/event-formatter.ts

@@ -0,0 +1,166 @@
+/**
+ * Transform raw SSE events into human-readable messages for the agent.
+ */
+
+import type { RemoteEvent } from "./types.js";
+
+export interface FormattedEvent {
+  /** Human-readable message body */
+  body: string;
+  /** Task ID associated with this event */
+  taskId: string;
+  /** Sender name (if identifiable) */
+  senderName?: string;
+  /** Sender ID (if identifiable) */
+  senderId?: string;
+  /** Task title for conversation label */
+  taskTitle?: string;
+  /** Whether this event is a direct/assigned event or board-wide */
+  isDirect: boolean;
+}
+
+/**
+ * Format a Remote SSE event into a human-readable message.
+ */
+export function formatEvent(event: RemoteEvent): FormattedEvent | null {
+  switch (event.type) {
+    case "task.created":
+      return formatTaskCreated(event);
+    case "task.updated":
+      return formatTaskUpdated(event);
+    case "task.commented":
+      return formatTaskCommented(event);
+    case "task.assigned":
+      return formatTaskAssigned(event);
+    default:
+      return formatGenericEvent(event);
+  }
+}
+
+function formatTaskCreated(event: RemoteEvent): FormattedEvent | null {
+  const task = event.task;
+  if (!task) return null;
+
+  const meta = [task.type, task.priority].filter(Boolean).join(", ");
+  let body = `📋 New task created: **${task.title}**`;
+  if (meta) body += ` [${meta}]`;
+  if (task.description) body += `\n${task.description}`;
+  body += `\n\n[task:${task.id}]`;
+
+  return {
+    body,
+    taskId: task.id,
+    taskTitle: task.title,
+    isDirect: false,
+  };
+}
+
+function formatTaskUpdated(event: RemoteEvent): FormattedEvent | null {
+  const task = event.task;
+  if (!task) return null;
+
+  const changes = event.changes;
+  
+  // Assignment change — treat as a direct assignment event
+  if (changes?.field === "assigned_role_id" || changes?.field === "assigned_to_agent" || changes?.field === "assigned_profile_id") {
+    if (changes.to && changes.to !== "null" && changes.to !== "") {
+      let body = `👤 You've been assigned: **${task.title}**`;
+      if (task.description) body += `\n\n${task.description}`;
+      body += `\n\nPriority: ${task.priority || "medium"} | Type: ${task.type || "task"}`;
+      body += `\n\nAcknowledge this task, move it to in_progress using remote_update_task, and share your plan.`;
+      body += `\n\n[task:${task.id}]`;
+
+      return {
+        body,
+        taskId: task.id,
+        taskTitle: task.title,
+        isDirect: true,
+      };
+    }
+    // Unassignment — skip silently
+    return null;
+  }
+
+  // Status change
+  if (changes?.field === "status") {
+    let body = `🔄 Task **${task.title}** moved to **${changes.to}**`;
+    body += `\n\n[task:${task.id}]`;
+    return {
+      body,
+      taskId: task.id,
+      taskTitle: task.title,
+      isDirect: false,
+    };
+  }
+
+  // Generic update
+  let body = `🔄 Task updated: **${task.title}**`;
+  if (changes) {
+    body += ` — ${changes.field} changed from "${changes.from}" to "${changes.to}"`;
+  }
+  body += `\n\n[task:${task.id}]`;
+
+  return {
+    body,
+    taskId: task.id,
+    taskTitle: task.title,
+    isDirect: false,
+  };
+}
+
+function formatTaskCommented(event: RemoteEvent): FormattedEvent | null {
+  const comment = event.comment;
+  const taskId = event.task_id ?? event.task?.id;
+  if (!comment || !taskId) return null;
+
+  const taskTitle = event.task?.title ?? `Task ${taskId}`;
+  let body = `💬 ${comment.author_name} commented on **${taskTitle}**:\n${comment.content}`;
+  body += `\n\n[task:${taskId}]`;
+
+  return {
+    body,
+    taskId,
+    senderName: comment.author_name,
+    senderId: comment.author_id,
+    taskTitle,
+    isDirect: false,
+  };
+}
+
+function formatTaskAssigned(event: RemoteEvent): FormattedEvent | null {
+  const task = event.task;
+  const assignee = event.assigned_to;
+  if (!task) return null;
+
+  let body = `👤 Task **${task.title}** assigned`;
+  if (assignee) {
+    body += ` to ${assignee.name} (${assignee.role})`;
+  }
+  body += `\n\n[task:${task.id}]`;
+
+  return {
+    body,
+    taskId: task.id,
+    senderName: assignee?.name,
+    taskTitle: task.title,
+    // Assigned events are direct — the agent is likely the assignee
+    isDirect: true,
+  };
+}
+
+function formatGenericEvent(event: RemoteEvent): FormattedEvent | null {
+  const task = event.task;
+  const taskId = event.task_id ?? task?.id;
+  if (!taskId) return null;
+
+  const taskTitle = task?.title ?? `Task ${taskId}`;
+  let body = `🔔 Remote event (${event.type}): **${taskTitle}**`;
+  body += `\n\n[task:${taskId}]`;
+
+  return {
+    body,
+    taskId,
+    taskTitle,
+    isDirect: false,
+  };
+}

package/src/realtime-listener.ts

@@ -0,0 +1,117 @@
+/**
+ * Supabase Realtime listener for Remote board events.
+ *
+ * Subscribes to Postgres changes on task_comments (INSERT) only.
+ * All task lifecycle events (assigned, status changed, created) are
+ * delivered as system comments by the Remote server actions, so a
+ * single task_comments subscription covers everything.
+ *
+ * Replaces the old SSE + relay architecture with a direct subscription.
+ * Scales well: 1 WebSocket per agent regardless of event volume.
+ */
+
+import { createClient, type RealtimeChannel, type SupabaseClient } from "@supabase/supabase-js";
+import type { RemoteAccount, RemoteEvent } from "./types.js";
+
+export type RealtimeEventCallback = (event: RemoteEvent) => void;
+export type RealtimeErrorCallback = (error: Error) => void;
+
+interface RealtimeListenerHandle {
+  unsubscribe: () => Promise<void>;
+}
+
+/**
+ * Connect to Supabase Realtime and listen for board changes.
+ *
+ * Subscribes to:
+ * - task_comments (INSERT) → all events (human comments + system notifications)
+ *
+ * Returns a handle to unsubscribe cleanly.
+ */
+export function connectRealtime(
+  account: RemoteAccount,
+  onEvent: RealtimeEventCallback,
+  onError: RealtimeErrorCallback,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void },
+): RealtimeListenerHandle {
+  const { supabaseUrl, supabaseKey } = account;
+
+  if (!supabaseUrl || !supabaseKey) {
+    throw new Error("Supabase URL and key are required for Realtime listener. Set supabaseUrl and supabaseKey in channels.remote config.");
+  }
+
+  log?.info?.(`Connecting to Supabase Realtime: ${supabaseUrl}`);
+
+  const supabase: SupabaseClient = createClient(supabaseUrl, supabaseKey, {
+    realtime: {
+      params: { eventsPerSecond: 10 },
+    },
+  });
+
+  const channelName = `remote-${account.accountId}-${Date.now()}`;
+
+  const channel: RealtimeChannel = supabase
+    .channel(channelName)
+
+    // Listen for new comments (human comments + system notification comments)
+    .on(
+      "postgres_changes",
+      {
+        event: "INSERT",
+        schema: "public",
+        table: "task_comments",
+      },
+      (payload) => {
+        try {
+          const row = payload.new as any;
+
+          // Echo suppression: skip comments authored by agents (agent_author_id set, no human author_id).
+          // System notifications have both null — they pass through.
+          // Human comments have author_id set — they pass through.
+          if (row.agent_author_id && !row.author_id) {
+            log?.info?.(`Skipping agent-authored comment on task ${row.task_id} (echo suppression)`);
+            return;
+          }
+
+          const event: RemoteEvent = {
+            type: "task.commented",
+            task_id: row.task_id,
+            comment: {
+              id: row.id,
+              content: row.body || row.content || "",
+              author_name: row.author_name || "System",
+              author_id: row.author_id || "",
+              created_at: row.created_at,
+            },
+          };
+
+          log?.info?.(`Realtime: new comment on task ${row.task_id}`);
+          onEvent(event);
+        } catch (err) {
+          log?.warn?.(`Failed to process comment event: ${err}`);
+        }
+      },
+    );
+
+  // Subscribe and handle status
+  channel.subscribe((status, err) => {
+    if (status === "SUBSCRIBED") {
+      log?.info?.("Supabase Realtime connected and subscribed.");
+    } else if (status === "CHANNEL_ERROR") {
+      log?.error?.(`Realtime channel error: ${err?.message || "unknown"}`);
+      onError(new Error(`Realtime channel error: ${err?.message || "unknown"}`));
+    } else if (status === "TIMED_OUT") {
+      log?.warn?.("Realtime subscription timed out, will auto-retry...");
+    } else if (status === "CLOSED") {
+      log?.info?.("Realtime channel closed.");
+    }
+  });
+
+  return {
+    unsubscribe: async () => {
+      log?.info?.("Unsubscribing from Supabase Realtime...");
+      await supabase.removeChannel(channel);
+      log?.info?.("Realtime listener shut down cleanly.");
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,9 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
+import type { PluginRuntime } from "openclaw/plugin-sdk/compat";
+
+const { setRuntime: setRemoteRuntime, getRuntime: getRemoteRuntime } =
+  createPluginRuntimeStore<PluginRuntime>(
+    "Remote runtime not initialized - plugin not registered",
+  );
+
+export { getRemoteRuntime, setRemoteRuntime };

package/src/sse-listener.ts

@@ -0,0 +1,164 @@
+/**
+ * SSE connection manager for Remote API events.
+ *
+ * Connects to GET /api/v1/events with streaming response body.
+ * Parses SSE data: lines into RemoteEvent objects.
+ * Auto-reconnects with exponential backoff on disconnect.
+ */
+
+import type { RemoteAccount, RemoteEvent } from "./types.js";
+
+const MIN_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+const BACKOFF_FACTOR = 2;
+
+export type SSEEventCallback = (event: RemoteEvent) => void;
+export type SSEErrorCallback = (error: Error) => void;
+
+/**
+ * Connect to the Remote SSE events stream.
+ *
+ * Returns a promise that resolves when the connection is cleanly closed
+ * (via abortSignal). Auto-reconnects on errors/disconnects until aborted.
+ */
+export async function connectSSE(
+  account: RemoteAccount,
+  onEvent: SSEEventCallback,
+  onError: SSEErrorCallback,
+  abortSignal?: AbortSignal,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void },
+): Promise<void> {
+  let reconnectMs = MIN_RECONNECT_MS;
+
+  while (!abortSignal?.aborted) {
+    try {
+      await connectOnce(account, onEvent, abortSignal, log);
+      // If connectOnce resolves without error, the stream ended cleanly.
+      // Reset backoff on successful connection that lasted a while.
+      reconnectMs = MIN_RECONNECT_MS;
+    } catch (err) {
+      if (abortSignal?.aborted) break;
+
+      const message = err instanceof Error ? err.message : String(err);
+      log?.warn?.(`SSE connection error: ${message}. Reconnecting in ${reconnectMs}ms...`);
+      onError(err instanceof Error ? err : new Error(message));
+    }
+
+    if (abortSignal?.aborted) break;
+
+    // Wait before reconnecting
+    await sleep(reconnectMs, abortSignal);
+    reconnectMs = Math.min(reconnectMs * BACKOFF_FACTOR, MAX_RECONNECT_MS);
+  }
+
+  log?.info?.("SSE listener shut down cleanly.");
+}
+
+/**
+ * Single SSE connection attempt. Resolves when the stream ends.
+ * Throws on connection/parse errors.
+ */
+async function connectOnce(
+  account: RemoteAccount,
+  onEvent: SSEEventCallback,
+  abortSignal?: AbortSignal,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void },
+): Promise<void> {
+  const url = `${account.baseUrl}/api/v1/events`;
+  log?.info?.(`Connecting to SSE: ${url}`);
+
+  const res = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${account.apiKey}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+    },
+    signal: abortSignal,
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`SSE connection failed: HTTP ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+  }
+
+  if (!res.body) {
+    throw new Error("SSE response has no body stream");
+  }
+
+  log?.info?.("SSE connected successfully.");
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEventType = "";
+  let currentData = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Process complete lines
+      const lines = buffer.split("\n");
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (line.startsWith("event:")) {
+          currentEventType = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          // Append to current data (SSE allows multi-line data)
+          const dataContent = line.slice(5).trim();
+          currentData = currentData ? `${currentData}\n${dataContent}` : dataContent;
+        } else if (line.startsWith(":")) {
+          // SSE comment / keepalive — ignore
+        } else if (line.trim() === "") {
+          // Empty line = event boundary. Dispatch if we have data.
+          if (currentData) {
+            try {
+              const parsed = JSON.parse(currentData) as RemoteEvent;
+              // If the event type was specified via `event:` line, use it
+              if (currentEventType && !parsed.type) {
+                parsed.type = currentEventType;
+              }
+              onEvent(parsed);
+            } catch (parseErr) {
+              log?.warn?.(
+                `Failed to parse SSE data: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`,
+              );
+            }
+          }
+          // Reset for next event
+          currentEventType = "";
+          currentData = "";
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Sleep that respects an AbortSignal. */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+
+    const timer = setTimeout(resolve, ms);
+
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}