@stagewhisper/stagewhisper 0.9.0

package/README.md

@@ -0,0 +1,86 @@
+# @stagewhisper/stagewhisper
+
+OpenClaw channel plugin that turns StageWhisper live call moments into assistant tasks.
+
+## What it does
+
+During a live StageWhisper call, the system detects actionable moments (follow-ups, research requests, scheduling needs) and packages them as structured tasks. This plugin receives those tasks via the StageWhisper relay and injects them into OpenClaw as channel messages, allowing your AI assistant to start working while the call is still happening.
+
+## Setup
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @stagewhisper/stagewhisper
+```
+
+Or install from a local path during development:
+
+```bash
+openclaw plugins install /path/to/integrations/openclaw-stagewhisper-channel
+```
+
+### 2. Generate a pairing code in StageWhisper
+
+Open StageWhisper desktop → Settings → Assistant → Generate pairing code.
+
+### 3. Complete pairing
+
+```bash
+openclaw stagewhisper pair --code <PAIRING_CODE> --api-url https://api.stagewhisper.io
+```
+
+Follow the printed instructions to apply config, then restart:
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Verify the connection
+
+```bash
+openclaw stagewhisper status
+```
+
+## Development
+
+```bash
+cd integrations/openclaw-stagewhisper-channel
+pnpm install
+pnpm test
+pnpm typecheck
+```
+
+### Local install for testing
+
+```bash
+openclaw plugins install $(pwd)
+```
+
+## Configuration
+
+The plugin reads from `channels.stagewhisper` or `plugins.entries.stagewhisper.config`:
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `apiBaseUrl` | Yes | StageWhisper backend URL |
+| `integrationId` | Yes | Integration ID from pairing |
+| `relayToken` | Yes | Relay token from pairing |
+| `label` | No | Display label (default: "StageWhisper") |
+
+## Architecture
+
+```
+StageWhisper Desktop → StageWhisper Backend (relay) → This Plugin → OpenClaw Assistant
+                                                    ← Reply path ←
+```
+
+The plugin runs a background service that:
+1. Connects to the StageWhisper relay stream (SSE)
+2. Receives queued assistant tasks
+3. Injects them as channel messages into OpenClaw
+4. Posts assistant replies back to StageWhisper
+
+## License
+
+MIT

package/api.ts

@@ -0,0 +1,4 @@
+export { stagewhisperPlugin, resolveAccount } from "./src/channel.js";
+export { StageWhisperClient } from "./src/client.js";
+export type { TaskPayload, PairCompleteResponse } from "./src/client.js";
+export type { StageWhisperAccount } from "./src/channel.js";

package/index.ts

@@ -0,0 +1,77 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { stagewhisperPlugin } from "./src/channel.js";
+import { setRuntime } from "./src/runtime.js";
+import { createRelayService } from "./src/service.js";
+
+export default definePluginEntry({
+  id: "stagewhisper",
+  name: "StageWhisper",
+  description: "Turn live call moments into assistant tasks via StageWhisper",
+  register(api) {
+    api.registerChannel({ plugin: stagewhisperPlugin });
+
+    const service = createRelayService(api);
+
+    api.registerCli(({ program }) => {
+      const sw = program
+        .command("stagewhisper")
+        .description("StageWhisper integration");
+
+      sw.command("pair")
+        .description("Pair with StageWhisper using a pairing code from the desktop app")
+        .requiredOption("--code <code>", "Pairing code from Settings → Assistant")
+        .requiredOption("--api-url <url>", "StageWhisper backend URL (e.g. https://api.stagewhisper.io)")
+        .option("--label <label>", "Label for this OpenClaw host", "OpenClaw")
+        .action(
+          async (opts: { code: string; apiUrl: string; label?: string }) => {
+            const { StageWhisperClient } = await import("./src/client.js");
+            const client = new StageWhisperClient(opts.apiUrl, "", "");
+            try {
+              const result = await client.completePairing(
+                opts.code,
+                opts.label ?? "OpenClaw",
+              );
+
+              console.log(`\n✓ Paired with StageWhisper (${result.label})\n`);
+              console.log("  Apply the config:\n");
+              console.log(`  openclaw config set plugins.entries.stagewhisper.config.apiBaseUrl ${JSON.stringify(opts.apiUrl)}`);
+              console.log(`  openclaw config set plugins.entries.stagewhisper.config.integrationId ${JSON.stringify(result.integration_id)}`);
+              console.log(`  openclaw config set plugins.entries.stagewhisper.config.relayToken ${JSON.stringify(result.relay_token)}`);
+              console.log(`  openclaw config set plugins.entries.stagewhisper.config.label ${JSON.stringify(result.label)}`);
+              console.log("\n  Then restart OpenClaw to activate the relay:\n");
+              console.log("  openclaw gateway restart\n");
+            } catch (err) {
+              console.error(`\n✗ Pairing failed: ${err}\n`);
+              process.exit(1);
+            }
+          },
+        );
+
+      sw.command("status")
+        .description("Show StageWhisper relay connection status")
+        .action(() => {
+          const relayState = service.getState();
+          const cfg = api.pluginConfig as Record<string, string> | undefined;
+          const configured = !!(cfg?.["integrationId"] && cfg?.["relayToken"]);
+
+          if (!configured) {
+            console.log("\nStageWhisper: not paired\n");
+            console.log("  Run: openclaw stagewhisper pair --code <CODE> --api-url <URL>\n");
+            console.log("  Get the pairing code from StageWhisper desktop: Settings → Assistant → Generate Pairing Code\n");
+            return;
+          }
+
+          console.log(`\nStageWhisper relay:`);
+          console.log(`  Connected: ${relayState.connected}`);
+          console.log(`  Last heartbeat: ${relayState.lastHeartbeat?.toISOString() ?? "never"}`);
+          console.log(`  Reconnect attempts: ${relayState.reconnectAttempts}`);
+          console.log(`  Backend: ${cfg?.["apiBaseUrl"] ?? "(unset)"}\n`);
+        });
+    });
+
+    if (api.registrationMode !== "full") return;
+
+    setRuntime(api.runtime);
+    api.registerService(service);
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,49 @@
+{
+  "id": "stagewhisper",
+  "name": "StageWhisper",
+  "description": "Turn live call moments into assistant tasks via StageWhisper",
+  "version": "0.9.0",
+  "channels": [
+    "stagewhisper"
+  ],
+  "skills": [
+    "skills/stagewhisper-assistant"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiBaseUrl": {
+        "type": "string",
+        "description": "StageWhisper backend URL (e.g. https://api.stagewhisper.io)",
+        "default": ""
+      },
+      "integrationId": {
+        "type": "string",
+        "description": "Integration ID returned after pairing",
+        "default": ""
+      },
+      "relayToken": {
+        "type": "string",
+        "description": "Relay token returned after pairing",
+        "default": ""
+      },
+      "label": {
+        "type": "string",
+        "description": "Human-readable label for this connection",
+        "default": "OpenClaw"
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "relayToken": {
+      "label": "Relay token",
+      "sensitive": true
+    },
+    "apiBaseUrl": {
+      "label": "StageWhisper URL",
+      "placeholder": "https://api.stagewhisper.io"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stagewhisper/stagewhisper",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "OpenClaw channel plugin that connects StageWhisper live calls to your AI assistant",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "setup-entry.ts",
+    "api.ts",
+    "src",
+    "openclaw.plugin.json",
+    "skills"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "stagewhisper",
+      "label": "StageWhisper",
+      "blurb": "Turn live call moments into assistant tasks"
+    }
+  },
+  "devDependencies": {
+    "openclaw": "2026.3.23",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  }
+}

package/setup-entry.ts

@@ -0,0 +1,4 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+import { stagewhisperPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(stagewhisperPlugin);

package/skills/stagewhisper-assistant/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: StageWhisper Assistant
+description: Handle tasks that arrive from StageWhisper live calls
+---
+
+You are receiving messages from the StageWhisper channel. Each message represents a task that was created during a live call because the speaker said or implied that follow-up work is needed.
+
+## What you know about StageWhisper tasks
+
+Each task arrives with:
+- A title summarizing what needs to happen
+- The explicit ask from the call
+- Transcript context showing what was said
+- Signal and tone summaries when available
+- The playbook label (sales, support, interview, etc.)
+
+## How to respond
+
+- Start working immediately. The caller may still be on the call.
+- Keep replies short and concrete. Summarize what you did and what the result is.
+- If a task is ambiguous, do the safe version and note what you assumed.
+- If a task requires access you don't have, say so clearly in one sentence rather than attempting workarounds.
+- Call out blockers early. "I can't access that CRM" is better than silence.
+
+## Task types you may see
+
+- **research**: Look up information (competitor pricing, candidate profiles, case references)
+- **draft**: Write a follow-up email, summary, or note
+- **schedule**: Create calendar holds or propose meeting times
+- **lookup**: Find internal documents, tickets, or records
+- **notify**: Send a message or update to a specific person or channel
+
+## What not to do
+
+- Do not ask clarifying questions back through the channel. The caller is in a live meeting.
+- Do not run shell commands or make system changes unless the task explicitly asks for it.
+- Do not restate the entire task back. Just do the work and report the result.

package/src/channel.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { StageWhisperClient } from "./client.js";
+
+describe("StageWhisperClient", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("completePairing", () => {
+    it("sends pairing code and returns credentials", async () => {
+      const mockResponse = {
+        integration_id: "int-123",
+        relay_token: "tok-abc",
+        label: "StageWhisper (openclaw)",
+      };
+
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: true,
+          json: () => Promise.resolve(mockResponse),
+        }),
+      );
+
+      const client = new StageWhisperClient("https://sw.test", "", "");
+      const result = await client.completePairing("ABC123", "MyHost");
+
+      expect(fetch).toHaveBeenCalledWith(
+        "https://sw.test/api/v1/openclaw/pair/complete",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({
+            pairing_code: "ABC123",
+            host_label: "MyHost",
+          }),
+        }),
+      );
+
+      expect(result.integration_id).toBe("int-123");
+      expect(result.relay_token).toBe("tok-abc");
+    });
+
+    it("throws on failure", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: false,
+          status: 400,
+          text: () => Promise.resolve("Invalid code"),
+        }),
+      );
+
+      const client = new StageWhisperClient("https://sw.test", "", "");
+      await expect(client.completePairing("BAD", "Host")).rejects.toThrow(
+        "Pairing failed (400)",
+      );
+    });
+  });
+
+  describe("postReply", () => {
+    it("sends reply content to the correct endpoint", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: true,
+          json: () => Promise.resolve({ ok: true }),
+        }),
+      );
+
+      const client = new StageWhisperClient(
+        "https://sw.test",
+        "int-1",
+        "tok-1",
+      );
+      await client.postReply("task-42", "Here is the answer", "msg-99");
+
+      expect(fetch).toHaveBeenCalledWith(
+        "https://sw.test/api/v1/openclaw/tasks/task-42/reply",
+        expect.objectContaining({
+          method: "POST",
+          headers: expect.objectContaining({
+            Authorization: "Bearer tok-1",
+          }),
+          body: JSON.stringify({
+            content: "Here is the answer",
+            remote_message_id: "msg-99",
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("updateTaskStatus", () => {
+    it("sends status update", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: true,
+          json: () => Promise.resolve({ ok: true }),
+        }),
+      );
+
+      const client = new StageWhisperClient(
+        "https://sw.test",
+        "int-1",
+        "tok-1",
+      );
+      await client.updateTaskStatus("task-42", "running", "remote-77");
+
+      expect(fetch).toHaveBeenCalledWith(
+        "https://sw.test/api/v1/openclaw/tasks/task-42/status",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({
+            status: "running",
+            remote_task_id: "remote-77",
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("heartbeat", () => {
+    it("sends heartbeat and returns response", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: true,
+          json: () => Promise.resolve({ ok: true }),
+        }),
+      );
+
+      const client = new StageWhisperClient(
+        "https://sw.test",
+        "int-1",
+        "tok-1",
+      );
+      const result = await client.heartbeat();
+
+      expect(result.ok).toBe(true);
+      expect(fetch).toHaveBeenCalledWith(
+        "https://sw.test/api/v1/openclaw/integrations/int-1/heartbeat",
+        expect.objectContaining({
+          method: "POST",
+          headers: expect.objectContaining({
+            Authorization: "Bearer tok-1",
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("streamUrl", () => {
+    it("builds correct stream URL", () => {
+      const client = new StageWhisperClient(
+        "https://sw.test/",
+        "int-1",
+        "tok-1",
+      );
+      expect(client.streamUrl()).toBe(
+        "https://sw.test/api/v1/openclaw/integrations/int-1/stream",
+      );
+    });
+  });
+});
+
+describe("config resolution", () => {
+  it("resolveAccount extracts config from channels.stagewhisper", async () => {
+    const { stagewhisperPlugin } = await import("./channel.js");
+
+    const cfg = {
+      channels: {
+        stagewhisper: {
+          apiBaseUrl: "https://sw.test",
+          integrationId: "int-1",
+          relayToken: "tok-1",
+          label: "My SW",
+        },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").OpenClawConfig;
+
+    const base = stagewhisperPlugin.base;
+    if (base?.setup?.resolveAccount) {
+      const account = base.setup.resolveAccount(cfg);
+      expect(account.apiBaseUrl).toBe("https://sw.test");
+      expect(account.integrationId).toBe("int-1");
+      expect(account.relayToken).toBe("tok-1");
+      expect(account.label).toBe("My SW");
+    }
+  });
+
+  it("resolveAccount throws when config is missing", async () => {
+    const { stagewhisperPlugin } = await import("./channel.js");
+
+    const cfg = { channels: {} } as unknown as import("openclaw/plugin-sdk/core").OpenClawConfig;
+    const base = stagewhisperPlugin.base;
+    if (base?.setup?.resolveAccount) {
+      expect(() => base.setup.resolveAccount(cfg)).toThrow("apiBaseUrl is required");
+    }
+  });
+});

package/src/channel.ts

@@ -0,0 +1,165 @@
+import {
+  createChatChannelPlugin,
+  createChannelPluginBase,
+  DEFAULT_ACCOUNT_ID,
+} from "openclaw/plugin-sdk/core";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { StageWhisperClient } from "./client.js";
+
+export type StageWhisperAccount = {
+  accountId: string | null;
+  apiBaseUrl: string;
+  integrationId: string;
+  relayToken: string;
+  label: string;
+};
+
+function getChannelSection(cfg: OpenClawConfig): Record<string, unknown> {
+  const channels = cfg.channels as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  return channels?.["stagewhisper"] ?? {};
+}
+
+export function resolveAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): StageWhisperAccount {
+  const section = getChannelSection(cfg);
+  const pluginCfg = (cfg as Record<string, unknown>)?.["plugins"] as
+    | Record<string, unknown>
+    | undefined;
+  const entries = pluginCfg?.["entries"] as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  const swConfig = entries?.["stagewhisper"]?.["config"] as
+    | Record<string, unknown>
+    | undefined;
+
+  const apiBaseUrl =
+    (section["apiBaseUrl"] as string) ??
+    (swConfig?.["apiBaseUrl"] as string) ??
+    "";
+  const integrationId =
+    (section["integrationId"] as string) ??
+    (swConfig?.["integrationId"] as string) ??
+    "";
+  const relayToken =
+    (section["relayToken"] as string) ??
+    (swConfig?.["relayToken"] as string) ??
+    "";
+  const label =
+    (section["label"] as string) ??
+    (swConfig?.["label"] as string) ??
+    "StageWhisper";
+
+  if (!apiBaseUrl) throw new Error("stagewhisper: apiBaseUrl is required");
+  if (!integrationId)
+    throw new Error("stagewhisper: integrationId is required");
+  if (!relayToken) throw new Error("stagewhisper: relayToken is required");
+
+  return {
+    accountId: accountId ?? null,
+    apiBaseUrl,
+    integrationId,
+    relayToken,
+    label,
+  };
+}
+
+const base = createChannelPluginBase<StageWhisperAccount>({
+  id: "stagewhisper",
+  capabilities: {
+    chatTypes: ["direct"],
+  },
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount,
+    inspectAccount(cfg: OpenClawConfig) {
+      try {
+        const account = resolveAccount(cfg);
+        return {
+          enabled: true,
+          configured: true,
+          label: account.label,
+          apiBaseUrl: account.apiBaseUrl,
+        };
+      } catch {
+        return {
+          enabled: false,
+          configured: false,
+          tokenStatus: "missing",
+        };
+      }
+    },
+  },
+  setup: {
+    applyAccountConfig({ cfg, input }) {
+      const channels = (cfg.channels ?? {}) as Record<
+        string,
+        Record<string, unknown>
+      >;
+      const section = { ...(channels["stagewhisper"] ?? {}) };
+      const raw = input as unknown as Record<string, string>;
+
+      if (raw["apiBaseUrl"]) section["apiBaseUrl"] = raw["apiBaseUrl"];
+      if (raw["integrationId"])
+        section["integrationId"] = raw["integrationId"];
+      if (raw["relayToken"]) section["relayToken"] = raw["relayToken"];
+      if (raw["label"]) section["label"] = raw["label"];
+
+      return {
+        ...cfg,
+        channels: { ...channels, stagewhisper: section },
+      } as OpenClawConfig;
+    },
+  },
+});
+
+export const stagewhisperPlugin = createChatChannelPlugin<StageWhisperAccount>(
+  {
+    base: base as unknown as Parameters<typeof createChatChannelPlugin<StageWhisperAccount>>[0]["base"],
+
+    security: {
+      dm: {
+        channelKey: "stagewhisper",
+        resolvePolicy: () => "closed",
+        resolveAllowFrom: () => [],
+        defaultPolicy: "closed",
+      },
+    },
+
+    pairing: {
+      text: {
+        idLabel: "StageWhisper pairing code",
+        message: "Run this command to complete pairing:",
+        notify: async () => {},
+      },
+    },
+
+    threading: { topLevelReplyToMode: "reply" },
+
+    outbound: {
+      base: { deliveryMode: "direct" },
+      attachedResults: {
+        channel: "stagewhisper",
+        sendText: async (ctx) => {
+          const account = resolveAccount(ctx.cfg, ctx.accountId);
+          const client = new StageWhisperClient(
+            account.apiBaseUrl,
+            account.integrationId,
+            account.relayToken,
+          );
+
+          const taskId = ctx.threadId as string | undefined;
+          if (!taskId) {
+            return { messageId: `sw-noop-${Date.now()}`, ok: true };
+          }
+
+          await client.postReply(taskId, ctx.text);
+          return { messageId: `sw-reply-${taskId}-${Date.now()}`, ok: true };
+        },
+      },
+    },
+  },
+);

package/src/client.ts

@@ -0,0 +1,121 @@
+export type TaskPayload = {
+  id: string;
+  session_id: string;
+  title: string;
+  request_text: string;
+  action_type: string;
+  status: string;
+  evidence_payload: Record<string, unknown> | null;
+  created_at: string;
+};
+
+export type PairCompleteResponse = {
+  integration_id: string;
+  relay_token: string;
+  label: string;
+};
+
+export type HeartbeatResponse = {
+  ok: boolean;
+};
+
+export class StageWhisperClient {
+  private baseUrl: string;
+  private integrationId: string;
+  private relayToken: string;
+
+  constructor(baseUrl: string, integrationId: string, relayToken: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.integrationId = integrationId;
+    this.relayToken = relayToken;
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.relayToken}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async completePairing(
+    pairingCode: string,
+    hostLabel: string,
+  ): Promise<PairCompleteResponse> {
+    const res = await fetch(`${this.baseUrl}/api/v1/openclaw/pair/complete`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        pairing_code: pairingCode,
+        host_label: hostLabel,
+      }),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Pairing failed (${res.status}): ${text}`);
+    }
+    return res.json();
+  }
+
+  async updateTaskStatus(
+    taskId: string,
+    status: string,
+    remoteTaskId?: string,
+  ): Promise<void> {
+    const body: Record<string, unknown> = { status };
+    if (remoteTaskId) body.remote_task_id = remoteTaskId;
+
+    const res = await fetch(
+      `${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/status`,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(body),
+      },
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Status update failed (${res.status}): ${text}`);
+    }
+  }
+
+  async postReply(taskId: string, content: string, remoteMessageId?: string): Promise<void> {
+    const body: Record<string, unknown> = { content };
+    if (remoteMessageId) body.remote_message_id = remoteMessageId;
+
+    const res = await fetch(
+      `${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/reply`,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(body),
+      },
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Reply failed (${res.status}): ${text}`);
+    }
+  }
+
+  async heartbeat(): Promise<HeartbeatResponse> {
+    const res = await fetch(
+      `${this.baseUrl}/api/v1/openclaw/integrations/${this.integrationId}/heartbeat`,
+      {
+        method: "POST",
+        headers: this.headers(),
+      },
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Heartbeat failed (${res.status}): ${text}`);
+    }
+    return res.json();
+  }
+
+  streamUrl(): string {
+    return `${this.baseUrl}/api/v1/openclaw/integrations/${this.integrationId}/stream`;
+  }
+
+  streamHeaders(): Record<string, string> {
+    return { Authorization: `Bearer ${this.relayToken}` };
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,6 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+
+export const { setRuntime, getRuntime } = createPluginRuntimeStore<PluginRuntime>(
+  "StageWhisper plugin runtime not initialized",
+);

package/src/service.ts

@@ -0,0 +1,261 @@
+import type {
+  OpenClawPluginApi,
+  OpenClawPluginServiceContext,
+} from "openclaw/plugin-sdk/core";
+import { buildAgentSessionKey } from "openclaw/plugin-sdk/core";
+import { StageWhisperClient } from "./client.js";
+import type { TaskPayload } from "./client.js";
+import type { StageWhisperAccount } from "./channel.js";
+import { resolveAccount } from "./channel.js";
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+
+type ServiceState = {
+  running: boolean;
+  connected: boolean;
+  lastHeartbeat: Date | null;
+  reconnectAttempts: number;
+};
+
+export function createRelayService(api: OpenClawPluginApi) {
+  const state: ServiceState = {
+    running: false,
+    connected: false,
+    lastHeartbeat: null,
+    reconnectAttempts: 0,
+  };
+
+  let abortController: AbortController | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  function resolveServiceAccount(): StageWhisperAccount {
+    try {
+      return resolveAccount(api.config);
+    } catch {
+      const pluginCfg = api.pluginConfig as Record<string, unknown>;
+      return {
+        accountId: null,
+        apiBaseUrl: (pluginCfg["apiBaseUrl"] as string) ?? "",
+        integrationId: (pluginCfg["integrationId"] as string) ?? "",
+        relayToken: (pluginCfg["relayToken"] as string) ?? "",
+        label: (pluginCfg["label"] as string) ?? "StageWhisper",
+      };
+    }
+  }
+
+  function buildTaskMessage(task: TaskPayload): string {
+    const lines: string[] = [];
+    lines.push(`**${task.title}**`);
+    lines.push("");
+    lines.push(task.request_text);
+
+    if (task.evidence_payload) {
+      const evidence = task.evidence_payload;
+      if (evidence["transcript_excerpt"]) {
+        lines.push("");
+        lines.push(`Context: ${evidence["transcript_excerpt"]}`);
+      }
+      if (evidence["signal_summary"]) {
+        lines.push(`Signal: ${evidence["signal_summary"]}`);
+      }
+      if (evidence["tone_summary"]) {
+        lines.push(`Tone: ${evidence["tone_summary"]}`);
+      }
+      if (evidence["playbook_label"]) {
+        lines.push(`Playbook: ${evidence["playbook_label"]}`);
+      }
+    }
+
+    lines.push("");
+    lines.push(`Action type: ${task.action_type}`);
+    lines.push(`StageWhisper task: ${task.id}`);
+    lines.push(`Session: ${task.session_id}`);
+
+    return lines.join("\n");
+  }
+
+  async function handleTask(
+    task: TaskPayload,
+    client: StageWhisperClient,
+  ): Promise<void> {
+    api.logger.info(`Received task: ${task.title} (${task.id})`);
+
+    try {
+      await client.updateTaskStatus(task.id, "delivered");
+    } catch (err) {
+      api.logger.warn(`Failed to mark task as delivered: ${err}`);
+    }
+
+    const messageContent = buildTaskMessage(task);
+
+    try {
+      const sessionKey = buildAgentSessionKey({
+        agentId: "default",
+        channel: "stagewhisper",
+        peer: { kind: "direct", id: `sw-session-${task.session_id}` },
+      });
+
+      const result = await api.runtime.subagent.run({
+        sessionKey,
+        message: messageContent,
+        deliver: true,
+      });
+
+      api.logger.info(
+        `Task ${task.id} dispatched to agent session (runId: ${result.runId})`,
+      );
+      await client.updateTaskStatus(task.id, "running");
+    } catch (err) {
+      api.logger.error(`Failed to dispatch task to agent: ${err}`);
+      await client.updateTaskStatus(task.id, "failed").catch(() => {});
+    }
+  }
+
+  async function connectStream(account: StageWhisperAccount): Promise<void> {
+    const client = new StageWhisperClient(
+      account.apiBaseUrl,
+      account.integrationId,
+      account.relayToken,
+    );
+
+    abortController = new AbortController();
+
+    const res = await fetch(client.streamUrl(), {
+      headers: client.streamHeaders(),
+      signal: abortController.signal,
+    });
+
+    if (!res.ok) {
+      throw new Error(`Stream connection failed (${res.status})`);
+    }
+
+    if (!res.body) {
+      throw new Error("Stream response has no body");
+    }
+
+    state.connected = true;
+    state.reconnectAttempts = 0;
+    api.logger.info("Connected to StageWhisper relay stream");
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (state.running) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const jsonStr = line.slice(6).trim();
+          if (!jsonStr) continue;
+
+          try {
+            const task = JSON.parse(jsonStr) as TaskPayload;
+            await handleTask(task, client);
+          } catch (parseErr) {
+            api.logger.warn(`Failed to parse stream event: ${parseErr}`);
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+      state.connected = false;
+    }
+  }
+
+  function backoffMs(): number {
+    const ms = Math.min(
+      RECONNECT_BASE_MS * Math.pow(2, state.reconnectAttempts),
+      RECONNECT_MAX_MS,
+    );
+    return ms + Math.random() * 1000;
+  }
+
+  async function runLoop(account: StageWhisperAccount): Promise<void> {
+    while (state.running) {
+      try {
+        await connectStream(account);
+      } catch (err) {
+        if (!state.running) break;
+        state.reconnectAttempts++;
+        const delay = backoffMs();
+        api.logger.warn(
+          `Stream disconnected (attempt ${state.reconnectAttempts}), reconnecting in ${Math.round(delay)}ms: ${err}`,
+        );
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+
+  function startHeartbeat(account: StageWhisperAccount): void {
+    const client = new StageWhisperClient(
+      account.apiBaseUrl,
+      account.integrationId,
+      account.relayToken,
+    );
+
+    heartbeatTimer = setInterval(async () => {
+      try {
+        await client.heartbeat();
+        state.lastHeartbeat = new Date();
+      } catch (err) {
+        api.logger.warn(`Heartbeat failed: ${err}`);
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  return {
+    id: "stagewhisper-relay",
+
+    async start(_ctx: OpenClawPluginServiceContext): Promise<void> {
+      const account = resolveServiceAccount();
+      if (
+        !account.apiBaseUrl ||
+        !account.integrationId ||
+        !account.relayToken
+      ) {
+        api.logger.info(
+          "StageWhisper not paired. Run: openclaw stagewhisper pair --code <CODE> --api-url <URL>",
+        );
+        api.logger.info(
+          "Get the pairing code from StageWhisper desktop: Settings → Assistant → Generate Pairing Code",
+        );
+        return;
+      }
+
+      state.running = true;
+      startHeartbeat(account);
+      runLoop(account).catch((err) => {
+        api.logger.error(`Relay service crashed: ${err}`);
+      });
+      api.logger.info(
+        `StageWhisper relay service started for ${account.label}`,
+      );
+    },
+
+    async stop(_ctx: OpenClawPluginServiceContext): Promise<void> {
+      state.running = false;
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      if (abortController) {
+        abortController.abort();
+        abortController = null;
+      }
+      api.logger.info("StageWhisper relay service stopped");
+    },
+
+    getState(): ServiceState {
+      return { ...state };
+    },
+  };
+}