@egoai/platform 0.1.0

package/src/chat.ts

@@ -0,0 +1,373 @@
+/**
+ * Platform chat interface.
+ *
+ * Mirrors the Telegram channel pattern: each platform user gets a stable
+ * session key derived from their user ID, and the plugin handles routing so
+ * the caller doesn't need to know openclaw's internal key format.
+ *
+ * Session key format: agent:{agentId}:platform:direct:{userId}
+ *
+ * RPC methods exposed to the platform (intercepted in PLUGIN_HANDLERS):
+ *   platform.chat.send    — send a message on behalf of a user
+ *   platform.chat.history — fetch conversation history for a user
+ *   platform.chat.abort   — abort an in-flight run for a user
+ *   platform.chat.reset   — reset (clear) a user's session
+ *   platform.session.resolve — return the computed session key
+ */
+
+import { randomUUID } from "node:crypto";
+import type { OpenClawConfig, PluginLogger } from "openclaw/plugin-sdk";
+import { dispatchReplyWithBufferedBlockDispatcher } from "openclaw/plugin-sdk/reply-runtime";
+import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
+import type {
+  RpcRequest,
+  RpcResponse,
+  PlatformChatSendParams,
+  PlatformChatSendStreamParams,
+  PlatformChatHistoryParams,
+  PlatformChatAbortParams,
+  PlatformChatResetParams,
+  PlatformSessionResolveParams,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Session key
+// ---------------------------------------------------------------------------
+
+const VALID_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const INVALID_CHARS_RE = /[^a-z0-9_-]+/g;
+const LEADING_TRAILING_DASH_RE = /^-+|-+$/g;
+
+function normalizeId(value: string | null | undefined): string {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return "";
+  if (VALID_ID_RE.test(trimmed)) return trimmed.toLowerCase();
+  return (
+    trimmed
+      .toLowerCase()
+      .replace(INVALID_CHARS_RE, "-")
+      .replace(LEADING_TRAILING_DASH_RE, "")
+      .slice(0, 64) || ""
+  );
+}
+
+/**
+ * Build the openclaw session key for a platform user.
+ * Mirrors buildAgentPeerSessionKey with dmScope="per-channel-peer".
+ *
+ * Format: agent:{agentId}:platform:direct:{userId}
+ */
+export function buildPlatformSessionKey(
+  agentId: string | null | undefined,
+  userId: string,
+): string {
+  const agent = normalizeId(agentId) || "main";
+  const user = normalizeId(userId) || "unknown";
+  return `agent:${agent}:platform:direct:${user}`;
+}
+
+// ---------------------------------------------------------------------------
+// Gateway forwarder type
+// ---------------------------------------------------------------------------
+
+/** Send an RPC request to the gateway and return its payload or throw on error. */
+export type GatewayForwarder = (
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+// ---------------------------------------------------------------------------
+// Handler context
+// ---------------------------------------------------------------------------
+
+export type ChatHandlerContext = {
+  forwardToGateway: GatewayForwarder;
+  cfg: OpenClawConfig;
+  logger?: PluginLogger;
+  /**
+   * Send a raw frame to the platform WS (used for streaming notifications).
+   * Called with `{ type: "notif", method, params }` frames during streaming.
+   */
+  sendToPlatform?: (frame: unknown) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ok(frame: RpcRequest, payload: unknown): RpcResponse {
+  return { type: "res", id: frame.id, ok: true, payload };
+}
+
+function fail(frame: RpcRequest, message: string): RpcResponse {
+  return { type: "res", id: frame.id, ok: false, error: { message } };
+}
+
+function requireString(params: Record<string, unknown>, key: string): string | null {
+  const v = params[key];
+  if (typeof v !== "string" || !v.trim()) return null;
+  return v.trim();
+}
+
+// ---------------------------------------------------------------------------
+// platform.chat.send
+// ---------------------------------------------------------------------------
+
+export async function handlePlatformChatSend(
+  frame: RpcRequest,
+  ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformChatSendParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.chat.send: userId is required");
+  const message = requireString(p as Record<string, unknown>, "message");
+  if (!message) return fail(frame, "platform.chat.send: message is required");
+
+  const agentId = normalizeId(p.agentId) || "main";
+  const sessionKey = buildPlatformSessionKey(p.agentId, userId);
+  const runId = p.runId ?? randomUUID();
+  const streamId = p.streamId ?? null;
+
+  ctx.logger?.info(
+    `platform: chat.send sessionKey=${sessionKey} runId=${runId}${streamId ? ` streamId=${streamId}` : ""}`,
+  );
+
+  const pipeline = createChannelReplyPipeline({
+    cfg: ctx.cfg,
+    agentId,
+    channel: "platform",
+    accountId: userId,
+  });
+
+  const textParts: string[] = [];
+
+  try {
+    await dispatchReplyWithBufferedBlockDispatcher({
+      cfg: ctx.cfg,
+      ctx: {
+        Body: message,
+        From: userId,
+        To: agentId,
+        SessionKey: sessionKey,
+        AccountId: userId,
+      },
+      dispatcherOptions: {
+        ...pipeline,
+        deliver: async (payload) => {
+          if (payload.text && !payload.isReasoning && !payload.isError) {
+            textParts.push(payload.text);
+            if (streamId && ctx.sendToPlatform) {
+              ctx.sendToPlatform({
+                type: "notif",
+                method: "platform.chat.chunk",
+                params: { streamId, text: payload.text },
+              });
+            }
+          }
+        },
+      },
+      replyOptions: { runId },
+    });
+  } catch (err) {
+    return fail(frame, `platform.chat.send: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return ok(frame, { text: textParts.join(""), runId });
+}
+
+// ---------------------------------------------------------------------------
+// platform.chat.send.stream
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire-and-forget streaming variant of platform.chat.send.
+ *
+ * Returns immediately with { runId, streamId }.  As the agent replies, the
+ * plugin pushes notification frames to the platform:
+ *   { type: "notif", method: "platform.chat.chunk", params: { streamId, text } }
+ *   { type: "notif", method: "platform.chat.done",  params: { streamId, runId } }
+ *   { type: "notif", method: "platform.chat.error", params: { streamId, error } }
+ */
+export async function handlePlatformChatSendStream(
+  frame: RpcRequest,
+  ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformChatSendStreamParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.chat.send.stream: userId is required");
+  const message = requireString(p as Record<string, unknown>, "message");
+  if (!message) return fail(frame, "platform.chat.send.stream: message is required");
+
+  const agentId = normalizeId(p.agentId) || "main";
+  const threadId = requireString(p as Record<string, unknown>, "threadId") ?? null;
+  const baseSessionKey = buildPlatformSessionKey(p.agentId, userId);
+  const sessionKey = threadId ? `${baseSessionKey}:thread:${threadId}` : baseSessionKey;
+  const runId = p.runId ?? randomUUID();
+  const streamId = randomUUID();
+
+  ctx.logger?.info(
+    `platform: chat.send.stream sessionKey=${sessionKey} runId=${runId} streamId=${streamId}${threadId ? ` threadId=${threadId}` : ""}`,
+  );
+
+  const pipeline = createChannelReplyPipeline({
+    cfg: ctx.cfg,
+    agentId,
+    channel: "platform",
+    accountId: userId,
+  });
+
+  // Fire and forget — return the streamId immediately so the caller can
+  // subscribe to notifications before chunks start arriving.
+  // onPartialReply fires per-token as the LLM streams; deliver fires once per
+  // completed block (too coarse for real-time output).
+  dispatchReplyWithBufferedBlockDispatcher({
+    cfg: ctx.cfg,
+    ctx: {
+      Body: message,
+      From: userId,
+      To: agentId,
+      SessionKey: sessionKey,
+      AccountId: userId,
+      // Surface/Provider identifies the channel for ACP dispatch and session tracking.
+      Surface: "platform",
+      // OriginatingChannel/To enable ACP reply routing back to this caller.
+      OriginatingChannel: "platform",
+      OriginatingTo: userId,
+      // MessageThreadId drives thread-scoped ACP session routing.
+      ...(threadId ? { MessageThreadId: threadId } : {}),
+    },
+    dispatcherOptions: {
+      ...pipeline,
+      deliver: async (_payload) => {
+        // Block-level delivery — not used for streaming; onPartialReply handles it.
+      },
+    },
+    replyOptions: {
+      runId,
+      onPartialReply: (() => {
+        let prevLen = 0;
+        return (payload) => {
+          if (payload.text && !payload.isReasoning && !payload.isError) {
+            const delta = payload.text.slice(prevLen);
+            prevLen = payload.text.length;
+            if (delta) {
+              ctx.sendToPlatform?.({
+                type: "notif",
+                method: "platform.chat.chunk",
+                params: { streamId, text: delta },
+              });
+            }
+          }
+        };
+      })(),
+    },
+  }).then(() => {
+    ctx.sendToPlatform?.({
+      type: "notif",
+      method: "platform.chat.done",
+      params: { streamId, runId },
+    });
+  }).catch((err: unknown) => {
+    ctx.sendToPlatform?.({
+      type: "notif",
+      method: "platform.chat.error",
+      params: { streamId, error: err instanceof Error ? err.message : String(err) },
+    });
+  });
+
+  return ok(frame, { runId, streamId });
+}
+
+// ---------------------------------------------------------------------------
+// platform.chat.history
+// ---------------------------------------------------------------------------
+
+export async function handlePlatformChatHistory(
+  frame: RpcRequest,
+  ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformChatHistoryParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.chat.history: userId is required");
+
+  const sessionKey = buildPlatformSessionKey(p.agentId, userId);
+  ctx.logger?.info(`platform: chat.history sessionKey=${sessionKey}`);
+
+  const gatewayParams: Record<string, unknown> = { sessionKey };
+  if (typeof p.limit === "number") gatewayParams.limit = p.limit;
+
+  try {
+    const payload = await ctx.forwardToGateway("chat.history", gatewayParams);
+    return ok(frame, payload);
+  } catch (err) {
+    return fail(frame, `platform.chat.history: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// platform.chat.abort
+// ---------------------------------------------------------------------------
+
+export async function handlePlatformChatAbort(
+  frame: RpcRequest,
+  ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformChatAbortParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.chat.abort: userId is required");
+
+  const sessionKey = buildPlatformSessionKey(p.agentId, userId);
+  ctx.logger?.info(`platform: chat.abort sessionKey=${sessionKey}`);
+
+  const gatewayParams: Record<string, unknown> = { sessionKey };
+  if (p.runId) gatewayParams.runId = p.runId;
+
+  try {
+    const payload = await ctx.forwardToGateway("chat.abort", gatewayParams);
+    return ok(frame, payload);
+  } catch (err) {
+    return fail(frame, `platform.chat.abort: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// platform.chat.reset
+// ---------------------------------------------------------------------------
+
+export async function handlePlatformChatReset(
+  frame: RpcRequest,
+  ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformChatResetParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.chat.reset: userId is required");
+
+  const sessionKey = buildPlatformSessionKey(p.agentId, userId);
+  ctx.logger?.info(`platform: chat.reset sessionKey=${sessionKey}`);
+
+  try {
+    const payload = await ctx.forwardToGateway("sessions.reset", {
+      key: sessionKey,
+      reason: "reset",
+    });
+    return ok(frame, payload);
+  } catch (err) {
+    return fail(frame, `platform.chat.reset: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// platform.session.resolve
+// ---------------------------------------------------------------------------
+
+export async function handlePlatformSessionResolve(
+  frame: RpcRequest,
+  _ctx: ChatHandlerContext,
+): Promise<RpcResponse> {
+  const p = frame.params as Partial<PlatformSessionResolveParams>;
+  const userId = requireString(p as Record<string, unknown>, "userId");
+  if (!userId) return fail(frame, "platform.session.resolve: userId is required");
+
+  const sessionKey = buildPlatformSessionKey(p.agentId, userId);
+  return ok(frame, { sessionKey });
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+/**
+ * Typed config resolver for the platform channel plugin.
+ *
+ * The gateway token is NOT stored in config — the plugin reads it from the
+ * running gateway context and pushes it to platform over the pre-handshake.
+ */
+
+export type PlatformAccount = {
+  accountId: string;
+  enabled: boolean;
+  /** true when platformUrl is set */
+  configured: boolean;
+  platformUrl: string;
+  platformKey?: string;
+};
+
+export function resolveAccount(cfg: OpenClawConfig, accountId?: string): PlatformAccount {
+  if (accountId && accountId !== "platform") {
+    console.warn(`platform: unexpected accountId "${accountId}", only "platform" is supported`);
+  }
+  const platform = cfg.channels?.platform ?? {};
+  const platformUrl = typeof platform.platformUrl === "string" ? platform.platformUrl.trim() : "ws://localhost:8000/openclaw/channel";
+
+  return {
+    accountId: "platform",
+    enabled: platform.enabled === true,
+    configured: platformUrl.length > 0,
+    platformUrl,
+    platformKey: typeof platform.platformKey === "string" ? platform.platformKey || undefined : undefined,
+  };
+}
+
+/**
+ * Inspect account status without materializing secrets.
+ * Used by the gateway dashboard and health checks.
+ */
+export function inspectAccount(cfg: OpenClawConfig, _accountId?: string | null): {
+  enabled: boolean;
+  configured: boolean;
+  tokenStatus: "available" | "missing";
+} {
+  const platform = cfg.channels?.platform ?? {};
+  const platformUrl = typeof platform.platformUrl === "string" && platform.platformUrl.trim().length > 0;
+  const hasPlatformKey = typeof platform.platformKey === "string" && platform.platformKey.length > 0;
+
+  return {
+    enabled: platform.enabled === true,
+    configured: platformUrl,
+    tokenStatus: hasPlatformKey ? "available" : "missing",
+  };
+}
+
+/**
+ * Resolve the gateway token from the running gateway config or environment.
+ * The plugin pushes this to platform so it can complete the standard handshake.
+ */
+export function resolveGatewayToken(cfg: OpenClawConfig): string {
+  // Prefer environment variable, fall back to config
+  const envToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+  if (envToken) return envToken;
+
+  const token = cfg.gateway?.auth?.token;
+  if (typeof token === "string" && token.length > 0) return token;
+
+  throw new Error(
+    "platform: cannot resolve gateway token — set OPENCLAW_GATEWAY_TOKEN or configure gateway.auth.token",
+  );
+}
+
+/**
+ * Resolve the gateway's local WS URL for the loopback relay connection.
+ * The plugin connects here and relays frames to/from platform.
+ */
+export function resolveGatewayUrl(cfg: OpenClawConfig): string {
+  const port = cfg.gateway?.port ?? 18789;
+  return `ws://127.0.0.1:${port}`;
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Platform — OpenClaw channel plugin for real-time AI voice conversations.
+ *
+ * Connects an OpenClaw agent to the Platform voice platform, enabling the agent
+ * to participate in live voice calls with embodied characters. The gateway
+ * initiates the connection to Platform and maintains a persistent session
+ * for RPC communication.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { PlatformChannel } from "./channel.js";
+import { triggerReconnect, getConnectionStatus } from "./monitor.js";
+import { resolveAccount } from "./config.js";
+import {
+  handleBeforePromptBuild,
+  handleMessageReceived,
+  handleMessageSent,
+  handleAgentEnd,
+  handleSessionEnd,
+} from "./brain.js";
+
+export default function register(api: OpenClawPluginApi) {
+  api.registerChannel({ plugin: PlatformChannel });
+
+  // --- Brain (Mnemo) hooks ---
+  // RAG context injection: keyword-match brain/index.md, prepend relevant wiki pages
+  api.on("before_prompt_build", (event, ctx) => {
+    return handleBeforePromptBuild(event, ctx, api.logger);
+  });
+
+  // Per-turn conversation logging: buffer user message, then log on agent response
+  api.on("message_received", (event, ctx) => {
+    handleMessageReceived(event, ctx, api.logger);
+  });
+
+  api.on("message_sent", (event, ctx) => {
+    handleMessageSent(event, ctx, api.logger);
+  });
+
+  // Per-turn capture via agent_end (fires for TUI, unlike message_sent)
+  api.on("agent_end", (event, ctx) => {
+    handleAgentEnd(event, ctx, api.logger);
+  });
+
+  // Session-end: log to log.md and queue for extraction
+  api.on("session_end", (event, ctx) => {
+    handleSessionEnd(event, ctx, api.logger);
+  });
+
+  api.registerCommand({
+    name: "platform-pair",
+    description: "Show instructions for pairing OpenClaw with Platform",
+    handler: () => ({
+      text: [
+        "To pair OpenClaw with platform:",
+        "",
+        "1. Follow the setup instructions at https://platform.md",
+        "2. Register an account on Platform and add OpenClaw as a connection",
+        "3. Add OpenClaw and follow instructions to install pairing token in OpenClaw",
+        "",
+        "Once configured, restart the gateway and use /platform-status to verify the connection.",
+      ].join("\n"),
+    }),
+  });
+
+  api.registerCommand({
+    name: "platform-reconnect",
+    description: "Skip the retry delay and reconnect to Platform immediately",
+    handler: () => {
+      const triggered = triggerReconnect();
+      return triggered
+        ? { text: "platform: reconnecting now." }
+        : { text: "platform: no pending retry — already connected or not running." };
+    },
+  });
+
+  api.registerCommand({
+    name: "platform-status",
+    description: "Show Platform connection status and current configuration",
+    handler: (ctx) => {
+      const status = getConnectionStatus();
+      const account = resolveAccount(ctx.config);
+
+      const lines: string[] = ["**Platform Status**"];
+
+      // Connection state
+      switch (status.state) {
+        case "connected":
+          lines.push("Connection: connected");
+          break;
+        case "connecting":
+          lines.push("Connection: connecting…");
+          break;
+        case "retrying": {
+          const secsLeft = Math.max(0, Math.round((status.retryingAt - Date.now()) / 1000));
+          lines.push(`Connection: retrying in ${secsLeft}s`);
+          lines.push(`Last error: ${status.lastError}`);
+          break;
+        }
+        case "disconnected":
+          lines.push("Connection: disconnected");
+          break;
+      }
+
+      // Config
+      lines.push("");
+      lines.push("**Config**");
+      lines.push(`Enabled: ${account.enabled}`);
+      lines.push(`Platform URL: ${account.platformUrl || "(not set)"}`);
+      lines.push(`Pairing token: ${account.platformKey ? "set" : "missing"}`);
+
+      return { text: lines.join("\n") };
+    },
+  });
+
+  api.logger.info("platform: channel registered");
+}