first working version

Author: steookk

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.js
+*.d.ts
+*.js.map
+*.d.ts.map
+!scripts/*.ts
+.env

CLAUDE.md

@@ -0,0 +1,147 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Type-check the plugin (no emit)
+npm run type-check          # tsc --noEmit
+
+# Run individual test scripts (no build step needed — tsx runs TS directly)
+npx tsx scripts/generate-bot-token.ts
+npx tsx scripts/discover-channels.ts
+npx tsx scripts/test-client.ts
+npx tsx scripts/test-roundtrip.ts
+npx tsx scripts/test-thread.ts
+
+# Restart the gateway after code changes
+openclaw gateway restart
+```
+
+There is no build step for the plugin itself. OpenClaw loads it directly from TypeScript source via `tsx`. The `scripts/` directory is excluded from `tsconfig.json`; scripts are run standalone with `npx tsx`.
+
+The `openclaw/plugin-sdk` import alias resolves to `../openclaw/dist/plugin-sdk/plugin-sdk/index.d.ts`. If that file is missing, rebuild it:
+
+```bash
+cd ../openclaw && tsc -p tsconfig.plugin-sdk.dts.json
+```
+
+## Architecture
+
+### Plugin registration
+
+`index.ts` is the plugin entry point. It exports a default object conforming to `OpenClawPluginDefinition`: the `register(api)` method stores the framework runtime singleton (`setStreamChatRuntime`) and calls `api.registerChannel({ plugin: streamchatPlugin })`.
+
+The OpenClaw framework discovers the plugin via `plugins.load.paths` in `~/.openclaw/openclaw.json`, looks for `openclaw.plugin.json` in the directory, then loads the extension listed in `package.json#openclaw.extensions`.
+
+**Config wiring gotchas:**
+- The `plugins.entries` key must equal the manifest `id` field (`"streamchat"`), not the package name (`@wunderchat/openclaw-channel-streamchat`) or directory name. Using the wrong key causes a `plugin not found` validation error at startup.
+- `PluginEntryConfig` only accepts `{ enabled, config }`. Any other field (e.g. `source`) will be rejected with `Unrecognized key`.
+- Config validation runs before plugin loading, so `plugins.load.paths` and `plugins.entries` must both be correct before the gateway will start.
+- There will always be a harmless cosmetic warning: `plugin id mismatch (manifest uses "streamchat", entry hints "openclaw-channel-streamchat")`. This is because the directory name differs from the manifest id and can be ignored.
+
+### Source module map
+
+| File | Responsibility |
+|---|---|
+| `src/channel.ts` | Main plugin export (`streamchatPlugin`). Contains `handleStreamChatMessage` (inbound dispatch) and the `ChannelPlugin` adapter implementations: `config`, `outbound`, `gateway`, `status`. |
+| `src/stream-chat-runtime.ts` | `StreamChatClientRuntime` — wraps the `stream-chat` SDK. Connects as bot user (`allowServerSideConnect: true` is required for Node.js server contexts), queries + watches channels on startup, auto-watches channels added later via `notification.added_to_channel`. |
+| `src/streaming.ts` | `StreamingHandler` — manages the AI streaming lifecycle per run: creates placeholder message → sends `ai_indicator` events → calls `partialUpdateMessage` on throttled chunks → finalizes on completion. |
+| `src/run-context.ts` | `RunContextMap` — binds an OpenClaw `runId` (UUID generated per inbound message) to delivery routing state: `channelId`, `threadParentId`, `responseMessageId`. TTL of 5 min. |
+| `src/envelope.ts` | `buildEnvelope` — wraps the raw message text in `[Thread]` / `[Replying to]` XML-like tags so the LLM receives thread and quote context in the single-session model. |
+| `src/types.ts` | `StreamChatChannelConfig`, `ResolvedAccount`, `RunContext`, `EnvelopeResult` interfaces, plus config helper functions (`getStreamChatConfig`, `resolveStreamChatAccount`). |
+| `src/config-schema.ts` | Zod schema for `channels.streamchat.*` config. Uses `z.lazy()` for the recursive `accounts` sub-map (multi-account support). |
+| `src/runtime.ts` | Module-level singleton accessor (`getStreamChatRuntime` / `setStreamChatRuntime`) for the `PluginRuntime` injected by OpenClaw at registration time. |
+| `src/stream-chat.d.ts` | Module augmentation adding `generating?: boolean` and `ai_generated?: boolean` to `CustomMessageData`. |
+| `src/utils.ts` | `truncate` and `safeAsync` helpers. |
+
+### Inbound flow
+
+```
+message.new (WebSocket)
+  → handleStreamChatMessage
+      → skip if event.user.id === botUserId  (own messages)
+      → skip if message.ai_generated === true (own placeholder/streamed messages)
+      → resolveAgentRoute   (peer kind: "channel", id: channelId)
+      → buildEnvelope       (wraps text with thread/reply context tags)
+      → finalizeInboundContext
+      → recordInboundSession
+      → dispatchReplyWithBufferedBlockDispatcher
+          deliver(payload, info) called per block:
+            info.kind === "tool"  → onRunProgress (EXTERNAL_SOURCES indicator)
+            text chunk            → onRunStarted (first) + onTextChunk
+          after dispatcher returns:
+            → onRunCompleted (final partialUpdateMessage + ai_indicator.clear)
+```
+
+The `ai_generated: true` check is critical — without it the bot would trigger on its own empty placeholder message created by `onRunStarted`, causing an infinite loop.
+
+### Event mapping
+
+How each signal from the OpenClaw pipeline translates into Stream Chat API calls or channel events:
+
+| Trigger | Stream Chat action | Notes |
+|---|---|---|
+| Inbound message received | `channel.sendReaction(msgId, { type: "eyes" })` | Ack reaction, fire-and-forget |
+| First `deliver` text block | `channel.sendMessage({ text: "", ai_generated: true })` | Creates the bot's placeholder message |
+| First `deliver` text block | `channel.sendEvent({ type: "ai_indicator.update", ai_state: "AI_STATE_THINKING" })` | Immediately followed by GENERATING below |
+| First text chunk processed | `channel.sendEvent({ type: "ai_indicator.update", ai_state: "AI_STATE_GENERATING" })` | Transitions from THINKING on the very first `onTextChunk` call |
+| Text chunk — throttled flush | `client.partialUpdateMessage(msgId, { set: { text, generating: true } })` | Odd chunks 1,3,5,7; then every N (default 15). Chained via `lastUpdatePromise` to avoid out-of-order updates |
+| `deliver` with `info.kind === "tool"` | `channel.sendEvent({ type: "ai_indicator.update", ai_state: "AI_STATE_EXTERNAL_SOURCES" })` | Only emitted once per run (de-duplicated by `indicatorState`); only if streaming has already started |
+| Dispatcher resolves (run complete) | `client.partialUpdateMessage(msgId, { set: { text, generating: false } })` | Final flush, waits for any in-flight partial updates first |
+| Dispatcher resolves (run complete) | `channel.sendEvent({ type: "ai_indicator.clear" })` | Clears the indicator bubble |
+| Dispatcher resolves (run complete) | `channel.deleteReaction(inboundMsgId, "eyes")` → `channel.sendReaction(inboundMsgId, { type: "white_check_mark" })` | Reaction swap on the original user message |
+| `deliver` with `payload.isError` | `client.partialUpdateMessage(msgId, { set: { text: "…\n\nError: …", generating: false } })` | Appends error to any partial text already accumulated |
+| `deliver` with `payload.isError` | `channel.sendEvent({ type: "ai_indicator.update", ai_state: "AI_STATE_ERROR" })` | Leaves the error indicator visible (no `ai_indicator.clear`) |
+| `ai_indicator.stop` from client | `client.partialUpdateMessage(msgId, { set: { generating: false } })` | Clears the generating flag without touching the accumulated text |
+| `ai_indicator.stop` from client | `channel.sendEvent({ type: "ai_indicator.clear" })` | |
+
+The `ai_indicator` events are sent via `safeSendEvent`, which retries up to 5 times on 429/5xx with exponential backoff (100 ms base, doubles each attempt) and swallows the error rather than aborting delivery if all retries fail.
+
+### Outbound streaming lifecycle
+
+Each agent run that produces text goes through these steps in `StreamingHandler`:
+
+1. `onRunStarted` — `channel.sendMessage({ text: "", ai_generated: true })` → `ai_indicator.update(AI_STATE_THINKING)`
+2. `onTextChunk` — accumulates text, switches indicator to `AI_STATE_GENERATING` on first chunk, calls `client.partialUpdateMessage({ set: { text, generating: true } })` throttled (early burst: odd chunks < 8; then every Nth chunk, default N=15)
+3. `onRunCompleted` — waits for in-flight partial updates, sends final `partialUpdateMessage({ generating: false })`, sends `ai_indicator.clear`
+
+Force-stop (`ai_indicator.stop` from client) calls `onForceStop`, which clears `generating` without overwriting the accumulated text.
+
+### Session model
+
+Each Stream Chat channel maps to exactly one OpenClaw session:
+
+```
+agent:<agentId>:streamchat:channel:<channelId>
+```
+
+This is achieved by passing `peer: { kind: "channel", id: channelId }` to `resolveAgentRoute`. The "channel" peer kind bypasses the `dmScope` logic and always builds per-channel keys. Do not use `peer.kind: "direct"` — with the framework default of `dmScope: "main"`, all direct-peer messages collapse into a single shared session (`agent:main:main`), so all channels would share one conversation context.
+
+All messages in a channel — main feed and threads — go to the same session. Thread context is injected into the prompt via `buildEnvelope` wrappers, not via separate sessions. This preserves cross-thread LLM context.
+
+### Multi-account support
+
+Config supports a flat default account or named sub-accounts:
+
+```jsonc
+"channels": {
+  "streamchat": {
+    "apiKey": "...",         // default account
+    "accounts": {
+      "workspace-b": { "apiKey": "..." }  // named account
+    }
+  }
+}
+```
+
+`resolveStreamChatAccount(cfg, accountId)` merges the named account config over the base config. Each account gets its own `StreamChatClientRuntime`, `RunContextMap`, and `StreamingHandler` instance (created in `gateway.startAccount`).
+
+## Key design decisions
+
+- **Bot token in config, secret is not.** The API secret is only used in `scripts/generate-bot-token.ts` to mint a JWT. Only the resulting token is stored in `openclaw.json`.
+- **`deliver` callback vs. completion signal.** `dispatchReplyWithBufferedBlockDispatcher` signals completion by resolving its promise, not by passing an `isComplete` flag. The `info.kind` parameter (`"tool" | "block" | "final"`) distinguishes delivery type. `onRunCompleted` is called after the dispatcher awaits. The `ReplyPayload` type has `text` and `isError` as the only relevant fields — there is no `markdown`, `isComplete`, or `toolName` field, despite what seems intuitive.
+- **Partial updates are chained via `lastUpdatePromise`.** Each `partialUpdateMessage` is `.then()`-chained onto the previous one to avoid out-of-order message text.
+- **`safeSendEvent` swallows errors.** Indicator events are best-effort; a failed `ai_indicator` update must not abort message delivery. Retries: 5 attempts, exponential backoff starting at 100 ms, only on 429/5xx.
+- **`seenThreads` is process-scoped.** The `Set<string>` tracking "first message in thread" lives at module level, so it persists across gateway reloads until the process restarts. This is intentional — it avoids re-sending parent context for active threads after a config reload.

README.md

@@ -0,0 +1,178 @@
+# @wunderchat/openclaw-channel-streamchat
+
+OpenClaw channel plugin for [Stream Chat](https://getstream.io/chat/). Connects as a bot user via WebSocket, normalizes inbound messages into OpenClaw envelope format, and delivers agent responses using Stream Chat's AI streaming pattern (`partialUpdateMessage` + `ai_indicator` events).
+
+## Prerequisites
+
+- OpenClaw `>= 2026.2.13`
+- A Stream Chat application (API key + secret from the [Stream Dashboard](https://dashboard.getstream.io/))
+- Node.js `>= 20`
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+cd openclaw-channel-streamchat
+npm install
+```
+
+### 2. Generate a bot token
+
+The plugin connects to Stream Chat as a regular user (the bot). You need a JWT for that user, generated from your API secret. The secret is only used here — it is **not** stored in the plugin config.
+
+Create a `.env` file in the plugin root:
+
+```env
+STREAM_API_KEY=your_api_key
+STREAM_API_SECRET=your_api_secret
+BOT_USER_ID=chatgpt
+```
+
+Then run:
+
+```bash
+npx tsx scripts/generate-bot-token.ts
+```
+
+This prints the bot JWT. Copy it for the next step.
+
+### 3. Configure OpenClaw
+
+Add the channel config and plugin entry to your `~/.openclaw/openclaw.json`:
+
+```jsonc
+{
+  // Add the channel configuration
+  "channels": {
+    "streamchat": {
+      "enabled": true,
+      "apiKey": "your_api_key",
+      "botUserId": "chatgpt",
+      "botUserToken": "<token from step 2>",
+      // Optional:
+      "ackReaction": "eyes",           // reaction added when message is received (default: "eyes")
+      "doneReaction": "white_check_mark", // reaction swapped in when response is done (default: "white_check_mark")
+      "streamingThrottle": 15          // partial-update every Nth chunk (default: 15)
+    }
+  },
+
+  // Register the plugin
+  "plugins": {
+    "load": {
+      "paths": [
+        "/absolute/path/to/openclaw-channel-streamchat"
+      ]
+    },
+    "entries": {
+      "streamchat": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### 4. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+The plugin will connect to Stream Chat, watch all channels where the bot is a member, and start processing messages.
+
+## Testing
+
+All test scripts live in `scripts/` and can be run with `npx tsx`. They load credentials from `.env` or use environment variables.
+
+### Discover channels
+
+Lists all channels the test user belongs to:
+
+```bash
+npx tsx scripts/discover-channels.ts
+```
+
+Override the defaults with environment variables:
+
+```bash
+STREAM_API_KEY=... USER_ID=myuser USER_TOKEN=... npx tsx scripts/discover-channels.ts
+```
+
+### Interactive test client
+
+Connects as a test user, watches a channel, and lets you send messages interactively while printing incoming bot responses and AI indicator events:
+
+```bash
+# Auto-discover channels and use the first one
+npx tsx scripts/test-client.ts
+
+# Specify a channel
+npx tsx scripts/test-client.ts myChannelId
+
+# Send a single message
+npx tsx scripts/test-client.ts myChannelId "Hello bot"
+```
+
+Commands inside the interactive client:
+
+| Command | Description |
+|---------|-------------|
+| `/thread <parentId> <text>` | Send a thread reply |
+| `/quote <messageId> <text>` | Send a quoted reply |
+| `/quit` | Disconnect and exit |
+
+Override the test user with environment variables:
+
+```bash
+STREAM_API_KEY=... TEST_USER_ID=myuser TEST_USER_TOKEN=... npx tsx scripts/test-client.ts
+```
+
+### Automated round-trip test
+
+Sends a message and waits for the bot to respond, verifying the full streaming lifecycle (placeholder message, AI indicators, partial updates, final update):
+
+```bash
+npx tsx scripts/test-roundtrip.ts
+```
+
+Expected output:
+
+```
+[NEW MSG][chatgpt] [AI]: (no text)        # empty placeholder
+[AI INDICATOR] AI_STATE_THINKING           # thinking indicator
+[AI INDICATOR] AI_STATE_GENERATING         # generating indicator
+[STREAMING] 2 + 2 = 4.                    # partial update
+[FINAL] 2 + 2 = 4.                        # final update (generating: false)
+[AI INDICATOR] cleared                     # indicator cleared
+
+✓ Round-trip test PASSED — got bot response.
+```
+
+### Thread test
+
+Sends a parent message, waits for the bot's response, then sends a thread reply and verifies the bot responds inside the thread:
+
+```bash
+npx tsx scripts/test-thread.ts
+```
+
+## How it works
+
+**Inbound flow:**
+1. Bot receives `message.new` event via WebSocket
+2. Plugin filters out bot's own messages and AI-generated messages
+3. Builds an envelope with thread/reply context wrappers (`[Thread]`, `[Replying]`)
+4. Dispatches to the OpenClaw agent pipeline
+
+**Outbound flow (streaming):**
+1. Creates an empty placeholder message with `ai_generated: true`
+2. Sends `ai_indicator.update` with `AI_STATE_THINKING`
+3. On first text chunk, switches to `AI_STATE_GENERATING`
+4. Progressively updates the message via `partialUpdateMessage` with `generating: true`
+5. On completion, sends final update with `generating: false` and clears the indicator
+
+**Thread handling:**
+- Thread replies include `parent_id` so the bot's response routes to the correct thread
+- First message in a thread includes the parent message text for context
+- Quoted replies are wrapped in `[Replying to ...]` envelopes

index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { streamchatPlugin } from "./src/channel.js";
+import { setStreamChatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "streamchat",
+  name: "Stream Chat",
+  description: "Stream Chat messaging channel for OpenClaw",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi): void {
+    setStreamChatRuntime(api.runtime);
+    api.registerChannel({ plugin: streamchatPlugin });
+  },
+};
+
+export default plugin;

openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "streamchat",
+  "channels": ["streamchat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}