@spikelabs/lobster-shell-plugin 0.2.2

package/README.md

@@ -0,0 +1,80 @@
+# @spikelabs/lobster-shell-plugin
+
+Connect your OpenClaw agent to [Lobster Shell](https://www.lobstershell.ai) — give your bot a face, voice, and video presence.
+
+## Install
+
+```bash
+npm install @spikelabs/lobster-shell-plugin
+```
+
+OpenClaw discovers the plugin automatically via its `openclaw.plugin.json` manifest.
+
+## Setup
+
+1. Start your OpenClaw gateway
+2. Visit **http://localhost:18789/lobster/setup** in your browser
+3. Click **Connect to Lobster Shell**
+4. Sign in (or create an account) on lobstershell.ai
+5. You'll be redirected back — the setup page should show "Connected!"
+
+No API keys needed. The plugin uses OAuth 2.1 with PKCE to securely link your gateway to your Lobster Shell account.
+
+## How it works
+
+Once connected, the plugin:
+
+- **Relays messages** between your OpenClaw agent and the Lobster Shell avatar renderer via an Ably real-time bridge
+- **Publishes events** (`message_received`, `agent_thinking`, `agent_response`) so the avatar reacts in real time
+- **Supports Shell Live** — real-time voice/video conversations through LiveKit
+
+## Configuration
+
+The plugin works with zero configuration. Optional settings:
+
+| Variable | Default | Description |
+|---|---|---|
+| `OPENCLAW_GATEWAY_TOKEN` | `dev-token-1234` | Gateway WebSocket auth token (set this if you changed the default) |
+
+You can also override the cloud URL via the plugin config in OpenClaw if you're running a custom Lobster Shell instance:
+
+```json
+{
+  "pluginConfig": {
+    "lobster-shell": {
+      "cloudUrl": "https://your-custom-instance.com"
+    }
+  }
+}
+```
+
+## Diagnostics
+
+Use the `/lobster-status` command in your OpenClaw chat to check connection status:
+
+```
+/lobster-status
+```
+
+This shows plugin version, gateway port, cloud bridge status, and channel info.
+
+## Development
+
+```bash
+pnpm install
+pnpm build          # Build once
+pnpm dev            # Watch mode
+pnpm lint           # Type-check
+```
+
+To test with a local OpenClaw Docker container, copy the built plugin:
+
+```bash
+pnpm build
+cp dist/* .openclaw-dev/config/extensions/lobster-shell/dist/
+docker compose restart
+```
+
+## License
+
+MIT

package/dist/chunk-RNTMVHEF.js

@@ -0,0 +1,202 @@
+// src/oauth-flow.ts
+import { randomBytes, createHash } from "crypto";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+function generateCodeVerifier() {
+  return randomBytes(32).toString("base64url");
+}
+function generateCodeChallenge(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+var OAuthFlow = class {
+  stateDir;
+  cloudUrl;
+  logger;
+  constructor(opts) {
+    this.stateDir = opts.stateDir;
+    this.cloudUrl = opts.cloudUrl;
+    this.logger = opts.logger;
+  }
+  // -------------------------------------------------------------------------
+  // Persistence
+  // -------------------------------------------------------------------------
+  async loadAuth() {
+    try {
+      const raw = await readFile(join(this.stateDir, "auth.json"), "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async saveAuth(state) {
+    await mkdir(this.stateDir, { recursive: true });
+    await writeFile(join(this.stateDir, "auth.json"), JSON.stringify(state, null, 2));
+  }
+  async loadPending() {
+    try {
+      const raw = await readFile(join(this.stateDir, "pending-auth.json"), "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async savePending(pending) {
+    await mkdir(this.stateDir, { recursive: true });
+    await writeFile(join(this.stateDir, "pending-auth.json"), JSON.stringify(pending, null, 2));
+  }
+  // -------------------------------------------------------------------------
+  // Step 1: Discover OAuth metadata
+  // -------------------------------------------------------------------------
+  async discover() {
+    const url = `${this.cloudUrl}/.well-known/oauth-authorization-server`;
+    this.logger.info(`[lobster:oauth] Discovering OAuth metadata from ${url}`);
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`OAuth discovery failed: ${res.status}`);
+    return await res.json();
+  }
+  // -------------------------------------------------------------------------
+  // Step 2: Dynamic client registration
+  // -------------------------------------------------------------------------
+  async registerClient(registrationEndpoint, redirectUri) {
+    this.logger.info("[lobster:oauth] Registering OAuth client dynamically");
+    const res = await fetch(registrationEndpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_name: "Lobster Shell Plugin",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none"
+        // public client (PKCE)
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Client registration failed: ${res.status} ${body}`);
+    }
+    return await res.json();
+  }
+  // -------------------------------------------------------------------------
+  // Initiate flow (returns URL to redirect browser to)
+  // -------------------------------------------------------------------------
+  async initiateFlow(redirectUri) {
+    const metadata = await this.discover();
+    if (!metadata.registration_endpoint) {
+      throw new Error("OAuth server does not support dynamic client registration");
+    }
+    const { client_id } = await this.registerClient(metadata.registration_endpoint, redirectUri);
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = randomBytes(16).toString("hex");
+    await this.savePending({
+      state,
+      codeVerifier,
+      clientId: client_id,
+      tokenEndpoint: metadata.token_endpoint,
+      redirectUri
+    });
+    const authUrl = new URL(metadata.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", client_id);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", codeChallenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("scope", "profile");
+    this.logger.info("[lobster:oauth] Authorization URL generated");
+    return authUrl.toString();
+  }
+  // -------------------------------------------------------------------------
+  // Handle callback (exchange code for tokens, register gateway)
+  // -------------------------------------------------------------------------
+  async handleCallback(query, gatewayInfo) {
+    const { code, state } = query;
+    if (!code || !state) throw new Error("Missing code or state parameter");
+    const pending = await this.loadPending();
+    if (!pending || pending.state !== state) {
+      throw new Error("Invalid state parameter \u2014 possible CSRF");
+    }
+    this.logger.info("[lobster:oauth] Exchanging authorization code for tokens");
+    const tokenRes = await fetch(pending.tokenEndpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: pending.redirectUri,
+        client_id: pending.clientId,
+        code_verifier: pending.codeVerifier
+      })
+    });
+    if (!tokenRes.ok) {
+      const body = await tokenRes.text();
+      throw new Error(`Token exchange failed: ${tokenRes.status} ${body}`);
+    }
+    const tokens = await tokenRes.json();
+    this.logger.info("[lobster:oauth] Registering gateway with Spike cloud");
+    const registerRes = await fetch(`${this.cloudUrl}/api/gateways/register`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${tokens.access_token}`
+      },
+      body: JSON.stringify({ gatewayInfo })
+    });
+    if (!registerRes.ok) {
+      const body = await registerRes.text();
+      throw new Error(`Gateway registration failed: ${registerRes.status} ${body}`);
+    }
+    const registration = await registerRes.json();
+    const authState = {
+      clientId: pending.clientId,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1e3,
+      gatewayPublicId: registration.gatewayPublicId,
+      channelName: registration.channelName,
+      tenantToken: registration.tenantToken,
+      tenantTokenExpiresAt: registration.tenantTokenExpiresAt
+    };
+    await this.saveAuth(authState);
+    this.logger.info(
+      `[lobster:oauth] OAuth flow completed, gateway registered: ${registration.gatewayPublicId}`
+    );
+    return authState;
+  }
+  // -------------------------------------------------------------------------
+  // Refresh token
+  // -------------------------------------------------------------------------
+  async refreshAccessToken() {
+    const auth = await this.loadAuth();
+    if (!auth?.refreshToken) return null;
+    const metadata = await this.discover();
+    this.logger.info("[lobster:oauth] Refreshing access token");
+    const res = await fetch(metadata.token_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: auth.refreshToken,
+        client_id: auth.clientId
+      })
+    });
+    if (!res.ok) {
+      this.logger.warn(`[lobster:oauth] Token refresh failed: ${res.status}`);
+      return null;
+    }
+    const tokens = await res.json();
+    const updated = {
+      ...auth,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token ?? auth.refreshToken,
+      expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1e3
+    };
+    await this.saveAuth(updated);
+    return updated;
+  }
+};
+
+export {
+  OAuthFlow
+};

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * Minimal type declarations for the OpenClaw Plugin SDK.
+ * Aligned with openclaw/src/plugins/types.ts — only what we actually use.
+ * This avoids a dependency on the full openclaw package.
+ */
+
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type ChannelId = string;
+type ChannelMeta = {
+    id: ChannelId;
+    label: string;
+    selectionLabel: string;
+    docsPath: string;
+    blurb: string;
+    order?: number;
+    aliases?: string[];
+    detailLabel?: string;
+    systemImage?: string;
+};
+type ChannelCapabilities = {
+    chatTypes: Array<"direct" | "group" | "thread">;
+    media?: boolean;
+    polls?: boolean;
+    reactions?: boolean;
+    edit?: boolean;
+    threads?: boolean;
+};
+type ChannelConfigAdapter<ResolvedAccount = unknown> = {
+    listAccountIds: (cfg: unknown) => string[];
+    resolveAccount: (cfg: unknown, accountId?: string | null) => ResolvedAccount;
+};
+type ChannelOutboundContext = {
+    cfg: unknown;
+    to: string;
+    text: string;
+    mediaUrl?: string;
+    mediaLocalRoots?: readonly string[];
+    replyToId?: string | null;
+    threadId?: string | number | null;
+    accountId?: string | null;
+    silent?: boolean;
+};
+type OutboundDeliveryResult = {
+    ok: boolean;
+    messageId?: string;
+    error?: string;
+};
+type ChannelOutboundAdapter = {
+    deliveryMode: "direct" | "gateway" | "hybrid";
+    sendText?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+    sendMedia?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+};
+type ChannelPlugin = {
+    id: ChannelId;
+    meta: ChannelMeta;
+    capabilities: ChannelCapabilities;
+    config: ChannelConfigAdapter;
+    outbound?: ChannelOutboundAdapter;
+};
+type PluginServiceContext = {
+    config: unknown;
+    workspaceDir?: string;
+    stateDir: string;
+    logger: PluginLogger;
+};
+type PluginService = {
+    id: string;
+    start: (ctx: PluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
+};
+type PluginCommandContext = {
+    senderId?: string;
+    channel: string;
+    channelId?: string;
+    isAuthorizedSender: boolean;
+    args?: string;
+    commandBody: string;
+    config: unknown;
+    from?: string;
+    to?: string;
+    accountId?: string;
+};
+type PluginCommandResult = {
+    text?: string;
+    mediaUrl?: string;
+};
+type PluginCommandDefinition = {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
+};
+type PluginHookMessageContext = {
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+};
+type PluginHookMessageSentEvent = {
+    to: string;
+    content: string;
+    success: boolean;
+    error?: string;
+};
+type PluginHookMessageReceivedEvent = {
+    from: string;
+    content: string;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+};
+type PluginHookGatewayStartEvent = {
+    port: number;
+};
+type PluginHookGatewayContext = {
+    port?: number;
+};
+type PluginHookHandlerMap = {
+    message_sent: (event: PluginHookMessageSentEvent, ctx: PluginHookMessageContext) => Promise<void> | void;
+    message_received: (event: PluginHookMessageReceivedEvent, ctx: PluginHookMessageContext) => Promise<void> | void;
+    gateway_start: (event: PluginHookGatewayStartEvent, ctx: PluginHookGatewayContext) => Promise<void> | void;
+    gateway_stop: (event: {
+        reason?: string;
+    }, ctx: PluginHookGatewayContext) => Promise<void> | void;
+};
+type PluginHookName = keyof PluginHookHandlerMap;
+/**
+ * HTTP route handler receives raw Node.js IncomingMessage and ServerResponse.
+ * Return `true` (or void) if handled, `false` to pass to next route.
+ */
+type OpenClawPluginHttpRouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean | void> | boolean | void;
+type OpenClawPluginHttpRouteAuth = "gateway" | "plugin";
+type OpenClawPluginHttpRouteMatch = "exact" | "prefix";
+type OpenClawPluginHttpRouteParams = {
+    path: string;
+    handler: OpenClawPluginHttpRouteHandler;
+    /** "gateway" = gateway auth enforced; "plugin" = plugin handles its own auth */
+    auth: OpenClawPluginHttpRouteAuth;
+    match?: OpenClawPluginHttpRouteMatch;
+    replaceExisting?: boolean;
+};
+type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    source: string;
+    config: unknown;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerChannel: (plugin: ChannelPlugin) => void;
+    registerService: (service: PluginService) => void;
+    registerCommand: (command: PluginCommandDefinition) => void;
+    registerHttpRoute: (params: OpenClawPluginHttpRouteParams) => void;
+    registerHook: (events: string | string[], handler: (...args: unknown[]) => unknown, opts?: {
+        name?: string;
+        description?: string;
+    }) => void;
+    on: <K extends PluginHookName>(hookName: K, handler: PluginHookHandlerMap[K], opts?: {
+        priority?: number;
+    }) => void;
+};
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+type OpenClawPluginModule = OpenClawPluginDefinition | ((api: OpenClawPluginApi) => void | Promise<void>);
+
+/**
+ * @spikelabs/lobster-shell-plugin — Connect your OpenClaw agent to Lobster Shell cloud.
+ *
+ * This plugin registers:
+ *  - A "lobster-shell" channel so the agent can send responses to the avatar renderer
+ *  - Hooks on message_sent / message_received to relay events to the cloud bridge
+ *  - A background service that manages the Ably bridge to Lobster Shell
+ *  - HTTP routes for OAuth setup flow
+ *  - A /lobster-status command for quick diagnostics
+ */
+
+declare const plugin: OpenClawPluginModule;
+
+export { plugin as default };