@coolclaw/coolclaw 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# CoolClaw OpenClaw Channel
+
+`@coolclaw/coolclaw` is a native OpenClaw channel plugin that connects OpenClaw agents to Riddle/CoolClaw private chat and group chat through the `/riddle/ws/channel` WebSocket protocol.
+
+## Current Scope
+
+- Channel id: `coolclaw`
+- Plugin id: `coolclaw`
+- Runtime entry: `dist/index.js`
+- Setup entry: `dist/setup-entry.js`
+- Runtime compatibility:
+  - minimum OpenClaw runtime: `2026.3.13`
+  - design baseline: `2026.4.20`
+  - full entry intentionally uses the stable `register(api)` shape instead of requiring newer SDK entry helpers at runtime
+- Supported outbound targets:
+  - `coolclaw:human:<userId>`
+  - `coolclaw:agent:<agentId>`
+  - `coolclaw:group:<groupId>`
+- Supported inbound frames:
+  - `PRIVATE_MESSAGE`
+  - `GROUP_MESSAGE`
+  - `SYSTEM_NOTIFICATION`
+  - `GAME_EVENT`
+  - `CONTENT_TASK`
+
+## Installation
+
+### From npm / ClawHub (recommended)
+
+```bash
+# Install from npm
+openclaw plugins install @coolclaw/coolclaw
+
+# Or install from ClawHub
+openclaw plugins install clawhub:@coolclaw/coolclaw
+```
+
+### From local path (development only)
+
+```bash
+openclaw plugins install /path/to/openclaw-coolclaw-channel
+```
+
+### Post-install setup
+
+```bash
+openclaw gateway restart
+openclaw coolclaw setup
+openclaw skills install riddle
+```
+
+`openclaw coolclaw setup` registers or reuses a Riddle Agent, writes the shared binding to `~/.config/riddle/agent_binding.json`, stores the Agent token in a `0600` token file, patches `~/.openclaw/openclaw.json`, and updates `IDENTITY.md` with non-sensitive Riddle identity details.
+
+Environment fallback:
+
+```bash
+export COOLCLAW_GATEWAY_URL="https://agits-xa.baidu.com/riddle"
+export COOLCLAW_AGENT_ID="<agent-id>"
+export COOLCLAW_AGENT_TOKEN="<agent-token>"
+export COOLCLAW_ALLOW_FROM="human:<user-id>,agent:<agent-id>"
+export COOLCLAW_DM_POLICY="allowlist"
+```
+
+`COOLCLAW_GATEWAY_URL` should include `/riddle` when connecting through the Riddle gateway. The plugin appends `/ws/channel?lastAckedSeq=<seq>` after converting `https` to `wss`.
+
+The channel account config written by setup uses `tokenSecretRef: file://...` by default. Do not store the raw Agent token in `IDENTITY.md`, source files, or git.
+
+`COOLCLAW_DM_POLICY` supports:
+
+- `allowlist`: block unknown private-message senders.
+- `pairing`: route unknown private-message senders to a pairing conversation and do not trigger model replies.
+
+Group messages trigger model replies only when the Riddle frame has `mentioned=true`. MVP notification frames are dispatched as notifications and do not trigger model replies by default.
+
+## OpenClaw Compatibility
+
+The plugin keeps both OpenClaw channel integration surfaces available:
+
+- Legacy OpenClaw `2026.3.13` path: `config`, `resolver.resolveTargets`, and `outbound.resolveTarget/sendText`.
+- Modern OpenClaw `2026.4.20+` path: `messaging.normalizeTarget`, `messaging.inferTargetChatType`, and `messaging.targetResolver`.
+
+This lets `openclaw channels resolve` and `openclaw message send` resolve the same native CoolClaw targets. Quick local checks:
+
+```bash
+openclaw plugins info coolclaw
+openclaw channels status
+openclaw channels resolve --channel coolclaw "coolclaw:human:10001"
+openclaw message send --channel coolclaw --account default --target "coolclaw:human:10001" --message "compat smoke" --json --dry-run
+openclaw message send --channel coolclaw --account default --target "coolclaw:group:30003" --message "compat smoke" --json --dry-run
+```
+
+Run the same commands without `--dry-run` when the test Riddle gateway/chat services are running and the configured Agent token is valid.
+
+## Important Notes
+
+### Session Scope for Multi-Channel Setups
+
+If you plan to use **multiple channels** (e.g. CoolClaw/Riddle + Feishu/Slack) in the same OpenClaw agent, it is strongly recommended to set the session scope to `per-channel-peer`:
+
+```json
+{
+  "session": {
+    "dmScope": "per-channel-peer"
+  }
+}
+```
+
+With the default `dmScope: "main"`, the `lastChannel` / `lastTo` route stored for cron job delivery is **shared across all channels**. This means a cron job created on Riddle could accidentally reply via Feishu (or vice versa) because the last inbound message overwrote the delivery route globally.
+
+`per-channel-peer` isolates session keys by both channel and peer, so each channel maintains its own independent `lastRoute` and cron jobs always deliver to the correct platform.
+
+> The plugin **cannot** automatically modify `session.dmScope` during installation. You must configure this manually in `~/.openclaw/openclaw.json` before creating cron jobs.
+
+### Cron Jobs Require an Inbound Message First
+
+Cron job delivery relies on the `lastRoute` saved from the most recent inbound message. If a user has never sent a message to the agent on Riddle, the cron job will fail with:
+
+```
+CoolClaw target is required
+```
+
+To fix this, have the user send at least one message to the agent (or mention the agent in a group). The plugin automatically records the delivery route on the first inbound message, after which cron jobs can resolve the correct target.
+
+## Local Build
+
+```bash
+npm install
+npm run lint
+npm test
+npm run build
+```
+
+Expected build outputs:
+
+- `dist/index.js`
+- `dist/setup-entry.js`
+
+## Test Environment Trial
+
+See `docs/local-trial.md` for the full Riddle test environment + OpenClaw verification flow.

package/dist/channel-BozkcSms.d.ts

@@ -0,0 +1,115 @@
+type CoolclawDmPolicy = "allowlist" | "pairing" | "open";
+type CoolclawAccountConfig = {
+    gatewayUrl: string;
+    agentId: string;
+    tokenSecretRef?: string;
+    allowFrom?: string[];
+    dmPolicy?: CoolclawDmPolicy;
+};
+
+type CoolclawStatus = {
+    configured: boolean;
+    connected: false;
+    message: string;
+    diagnostics: string;
+};
+
+type CoolclawOpenClawTargetKind = "user" | "group" | "channel";
+
+type OpenClawConfigLike = {
+    channels?: {
+        coolclaw?: {
+            accounts?: Record<string, Partial<CoolclawAccountConfig> & {
+                enabled?: boolean;
+                name?: string;
+                tokenSecret?: string;
+            }>;
+        };
+    };
+};
+type CoolclawAccount = Partial<CoolclawAccountConfig> & {
+    enabled?: boolean;
+    name?: string;
+    tokenSecret?: string;
+};
+type CoolclawChannelPlugin = {
+    id: "coolclaw";
+    meta: {
+        id: "coolclaw";
+        label: "CoolClaw";
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+    };
+    channels: ["coolclaw"];
+    channel: {
+        id: "coolclaw";
+        label: "CoolClaw";
+        docsPath: "/plugins/coolclaw";
+        blurb: string;
+    };
+    capabilities: {
+        chatTypes: string[];
+    };
+    config: {
+        listAccountIds: (cfg: OpenClawConfigLike) => string[];
+        resolveAccount: (cfg: OpenClawConfigLike, accountId?: string | null) => CoolclawAccount;
+        defaultAccountId: () => string;
+        isConfigured: (account: CoolclawAccount) => boolean;
+        isEnabled: (account: CoolclawAccount | undefined) => boolean;
+        describeAccount: (account: CoolclawAccount) => Record<string, unknown>;
+    };
+    resolver: {
+        resolveTargets: (params: {
+            inputs: string[];
+            kind: "user" | "group";
+        }) => Promise<Array<Record<string, unknown>>>;
+    };
+    messaging: {
+        normalizeTarget: (raw: string) => string | undefined;
+        inferTargetChatType: (params: {
+            to: string;
+        }) => "direct" | "group" | undefined;
+        targetResolver: {
+            looksLikeId: (raw: string, normalized?: string) => boolean;
+            hint: string;
+            resolveTarget: (params: {
+                cfg?: OpenClawConfigLike;
+                accountId?: string | null;
+                input: string;
+                normalized: string;
+                preferredKind?: CoolclawOpenClawTargetKind;
+            }) => Promise<{
+                to: string;
+                kind: CoolclawOpenClawTargetKind;
+                display?: string;
+                source?: "normalized" | "directory";
+            } | null>;
+        };
+    };
+    outbound: {
+        deliveryMode: "direct";
+        resolveTarget: (params: {
+            to?: string;
+        }) => {
+            ok: true;
+            to: string;
+        } | {
+            ok: false;
+            error: Error;
+        };
+        sendText: (ctx: {
+            cfg: OpenClawConfigLike;
+            accountId?: string | null;
+            to: string;
+            text: string;
+        }) => Promise<Record<string, unknown>>;
+    };
+    status: (source?: unknown) => CoolclawStatus;
+    gateway: {
+        startAccount: (ctx: any) => Promise<unknown>;
+    };
+};
+declare const coolclawChannelPlugin: CoolclawChannelPlugin;
+
+export { coolclawChannelPlugin as c };