@chanlerdev/scorel 0.0.1 → 0.0.3

package/docs/spec/ship/S0094-im-inbound-runtime.md

@@ -0,0 +1,67 @@
+# S0094: IM Inbound Runtime
+
+## Goal
+
+Make built-in QQ and WeChat IM integrations actually receive user messages at runtime and route them through the shared Scorel IM session bridge.
+
+## Scope
+
+- Implement QQ Bot inbound receive through the official WebSocket Gateway.
+- Implement WeChat inbound receive through an official HTTP callback surface for official-account style plaintext text messages.
+- Keep WeCom group robot webhook as an outbound-only sender because that official webhook surface does not deliver user messages back to Scorel.
+- Keep adapters platform-IO only. They call `ctx.onMessage(...)`; daemon session creation stays in the existing IM bridge.
+- Update GUI settings and docs so outbound webhook configuration is not presented as if it enables inbound WeChat chat.
+
+## Not In Scope
+
+- Consumer personal WeChat reverse engineering, browser automation, or Web WeChat scraping.
+- Hosted public ingress, TLS certificates, relay tunneling, or automatic public URL provisioning.
+- Full WeChat encrypted callback decrypt/encrypt support. Plaintext callback is the S0094 receive baseline.
+- QQ sharding beyond one local gateway connection.
+
+## Acceptance Criteria
+
+- QQ adapter `start(ctx)` fetches an access token, fetches `/gateway`, opens a WebSocket, identifies with `QQBot <access_token>`, sends heartbeats, and calls `ctx.onMessage(...)` for text dispatch events normalized by `normalizeQQEvent`.
+- QQ adapter `stop()` closes the WebSocket and heartbeat timer.
+- WeChat adapter starts a local HTTP callback server when callback config is present, responds to GET URL verification, accepts text POST callbacks, normalizes them, and calls `ctx.onMessage(...)`.
+- WeChat adapter can still send outbound text to a configured WeCom group robot webhook; if only webhook URL is configured, inbound is explicitly not started.
+- Tests cover QQ gateway identify/heartbeat/dispatch/stop and WeChat callback verification/message routing.
+
+## Test Requirements
+
+- Add focused adapter tests before implementation.
+- Run:
+
+```bash
+pnpm --filter @scorel/daemon test -- qq-adapter.test.ts wechat-adapter.test.ts
+pnpm typecheck
+pnpm test
+```
+
+## Impacted Files
+
+- `extensions/builtin/qq/adapter.js`
+- `extensions/builtin/qq/adapter.d.ts`
+- `extensions/builtin/wechat/adapter.js`
+- `extensions/builtin/wechat/adapter.d.ts`
+- `packages/daemon/src/qq-adapter.test.ts`
+- `packages/daemon/src/wechat-adapter.test.ts`
+- `apps/gui/src/renderer/settings/sections/ImSection.tsx`
+- `docs/spec/ship/S0091-built-in-qq-and-wechat-im-extensions.md`
+
+## Risks And Boundaries
+
+- QQ event delivery also depends on the bot's platform-side event subscriptions and permissions. Scorel can connect to the gateway, but QQ may still omit events that are not enabled for the bot.
+- WeChat callback receive requires a URL Tencent can reach. Local-only callback ports are useful for tunnels and tests, but are not publicly reachable by themselves.
+- WeCom group robot webhook remains outbound-only by official product design; Scorel must not imply that it can receive user chat through that webhook.
+
+## References
+
+- QQ Bot event delivery and WebSocket gateway: <https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html>
+- QQ Bot gateway URL API: <https://bot.q.qq.com/wiki/develop/api-v2/openapi/wss/url_get.html>
+- WeCom group robot outbound webhook: <https://developer.work.weixin.qq.com/document/path/91770>
+- WeChat official account callback verification and normal messages: <https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html>, <https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Receiving_standard_messages.html>
+
+## Status
+
+Done.

package/docs/spec/ship/S0095-gui-im-session-list-refresh.md

@@ -0,0 +1,36 @@
+# S0095: GUI IM Session List Refresh
+
+## Goal
+
+Make GUI sidebars show IM sessions that are created in the background by Telegram, QQ, or WeChat inbound messages.
+
+## Scope
+
+- Notify GUI when the local Host creates a session, including IM sessions created in the background.
+- Refresh only the affected Project session list in response to that notification.
+- Keep IM session storage and Project binding unchanged.
+- Cover the selected/default IM workspace Project so background QQ/Telegram sessions appear without app restart.
+
+## Not In Scope
+
+- Changing where session JSONL files are stored.
+- Creating per-platform Projects.
+- Relay or hosted notification push for remote devices.
+
+## Acceptance Criteria
+
+- A GUI Project refreshes when the local Host reports a new session for that Project.
+- The refresh does not clear the active transcript.
+- Renderer test covers a background session appearing after initial load.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/renderer/app-session-preload.test.tsx
+pnpm typecheck
+pnpm test
+```
+
+## Status
+
+Done.

package/extensions/builtin/loopback/adapter.js

@@ -0,0 +1,13 @@
+export const createAdapter = () => {
+  const outbox = [];
+  return {
+    async start() {},
+    async stop() {},
+    async sendMessage(_target, message) {
+      outbox.push(message);
+    },
+    getOutbox() {
+      return [...outbox];
+    },
+  };
+};

package/extensions/builtin/loopback/scorel.extension.json

@@ -0,0 +1,7 @@
+{
+  "id": "loopback",
+  "kind": "im",
+  "displayName": "Loopback IM",
+  "adapter": "./adapter.js",
+  "skills": ["./skills"]
+}

package/extensions/builtin/loopback/skills/loopback/SKILL.md

@@ -0,0 +1,9 @@
+---
+description: Reply to the current loopback IM conversation with SendChannelMessage.
+---
+
+# Loopback IM
+
+When a message comes from the loopback IM channel, use `SendChannelMessage` to reply to the current conversation. Do not ask for raw channel ids.
+
+If work will take more than a brief moment, send a short acknowledgement first, then follow with concise progress or the final result.

package/extensions/builtin/qq/adapter.d.ts

@@ -0,0 +1,27 @@
+export type QQAdapterOptions = {
+  appId: string;
+  appSecret: string;
+  apiBaseUrl: string;
+  accessTokenUrl?: string;
+  gatewayUrl?: string;
+  botId?: string;
+  intents?: number;
+  heartbeatIntervalMs?: number;
+  dedupeTtlMs?: number;
+};
+
+export type QQTarget = {
+  externalConversationId: string;
+  data?: Record<string, unknown>;
+};
+
+export type QQAdapter = {
+  start(ctx: unknown): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(target: QQTarget, message: { text?: string; attachments?: Array<Record<string, unknown>> }): Promise<void>;
+};
+
+export function createAdapter(options?: { config?: Record<string, string | number | boolean> }): QQAdapter;
+export function createQQAdapter(options: QQAdapterOptions): QQAdapter;
+export function normalizeQQEvent(event: unknown, options?: { botId?: string }): unknown;
+export function redactQQSecret(value: string): string;

package/extensions/builtin/qq/adapter.js

@@ -0,0 +1,384 @@
+import WebSocket from "ws";
+
+const DEFAULT_QQ_API_BASE_URL = "https://api.sgroup.qq.com";
+const DEFAULT_QQ_ACCESS_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+const DEFAULT_QQ_INTENTS = (1 << 9) | (1 << 25) | (1 << 30);
+const DEFAULT_DEDUPE_TTL_MS = 5 * 60_000;
+
+export const createAdapter = ({ config = {} } = {}) => {
+  return createQQAdapter({
+    appId: requiredStringConfig(config.appId, "QQ App ID"),
+    appSecret: requiredStringConfig(config.appSecret, "QQ App Secret"),
+    apiBaseUrl: stringConfig(config.apiBaseUrl, DEFAULT_QQ_API_BASE_URL),
+    accessTokenUrl: stringConfig(config.accessTokenUrl, DEFAULT_QQ_ACCESS_TOKEN_URL),
+    gatewayUrl: stringConfig(config.gatewayUrl, ""),
+    botId: optionalStringConfig(config.botId, "QQ botId"),
+  });
+};
+
+export const createQQAdapter = (options) => {
+  let accessToken;
+  let accessTokenExpiresAt = 0;
+  let ctx;
+  let running = false;
+  let socket;
+  let heartbeatTimer;
+  let lastSequence = null;
+  let sessionId;
+  const recentMessageIds = new Map();
+
+  const getAccessToken = async () => {
+    const refreshAt = accessTokenExpiresAt - 60_000;
+    if (accessToken && Date.now() < refreshAt) {
+      return accessToken;
+    }
+    const response = await fetch(options.accessTokenUrl ?? DEFAULT_QQ_ACCESS_TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        appId: options.appId,
+        clientSecret: options.appSecret,
+      }),
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok || typeof payload?.access_token !== "string" || !payload.access_token.trim()) {
+      throw new Error(redactQQSecret(`qq access token failed: ${payload?.message ?? payload?.errmsg ?? response.status}`));
+    }
+    const expiresIn = Number(payload.expires_in);
+    accessToken = payload.access_token.trim();
+    accessTokenExpiresAt = Date.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn * 1000 : 7200_000);
+    return accessToken;
+  };
+
+  const fetchGatewayUrl = async (token) => {
+    const configured = typeof options.gatewayUrl === "string" && options.gatewayUrl.trim() ? options.gatewayUrl.trim() : undefined;
+    const response = await fetch(configured ?? `${options.apiBaseUrl.replace(/\/+$/, "")}/gateway`, {
+      method: "GET",
+      headers: { authorization: `QQBot ${token}` },
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok || typeof payload?.url !== "string" || !payload.url.trim()) {
+      throw new Error(redactQQSecret(`qq gateway failed: ${payload?.message ?? response.status}`));
+    }
+    return payload.url.trim();
+  };
+
+  const sendSocket = (payload) => {
+    if (socket?.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(payload));
+    }
+  };
+
+  const sendHeartbeat = () => {
+    sendSocket({ op: 1, d: lastSequence });
+  };
+
+  const clearHeartbeat = () => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = undefined;
+    }
+  };
+
+  const identify = async () => {
+    sendSocket({
+      op: 2,
+      d: {
+        token: `QQBot ${await getAccessToken()}`,
+        intents: numberConfig(options.intents, DEFAULT_QQ_INTENTS),
+        shard: Array.isArray(options.shard) ? options.shard : [0, 1],
+        properties: {
+          "$os": process.platform,
+          "$browser": "scorel",
+          "$device": "scorel",
+        },
+      },
+    });
+  };
+
+  const handleGatewayPayload = async (payload) => {
+    if (typeof payload?.s === "number") {
+      lastSequence = payload.s;
+    }
+    if (payload?.op === 10) {
+      const interval = numberConfig(options.heartbeatIntervalMs, Number(payload?.d?.heartbeat_interval) || 45_000);
+      clearHeartbeat();
+      sendHeartbeat();
+      heartbeatTimer = setInterval(sendHeartbeat, interval);
+      heartbeatTimer.unref?.();
+      await identify();
+      return;
+    }
+    if (payload?.op === 1) {
+      sendHeartbeat();
+      return;
+    }
+    if (payload?.op === 0) {
+      if (payload.t === "READY" && typeof payload.d?.session_id === "string") {
+        sessionId = payload.d.session_id;
+        return;
+      }
+      const incoming = normalizeQQEvent(payload.d, { botId: options.botId });
+      if (!incoming || isDuplicateMessage(incoming, recentMessageIds, numberConfig(options.dedupeTtlMs, DEFAULT_DEDUPE_TTL_MS))) {
+        return;
+      }
+      await ctx?.onMessage(incoming);
+      return;
+    }
+    if (payload?.op === 7 || payload?.op === 9) {
+      ctx?.logger?.error("qq_gateway_reconnect_required", { op: payload.op, sessionId });
+    }
+  };
+
+  return {
+    async start(startCtx) {
+      ctx = startCtx;
+      running = true;
+      const token = await getAccessToken();
+      const url = await fetchGatewayUrl(token);
+      await new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        socket = ws;
+        let settled = false;
+        const settle = (error) => {
+          if (settled) return;
+          settled = true;
+          error ? reject(error) : resolve();
+        };
+        ws.once("open", () => settle());
+        ws.once("error", (error) => {
+          ctx?.logger?.error("qq_gateway_error", { message: safeErrorMessage(error) });
+          settle(error);
+        });
+        ws.on("message", (data) => {
+          void handleGatewayPayload(parseGatewayMessage(data)).catch((cause) => {
+            ctx?.logger?.error("qq_gateway_message_failed", { message: redactQQSecret(safeErrorMessage(cause)) });
+          });
+        });
+        ws.on("close", () => {
+          clearHeartbeat();
+          if (running) {
+            ctx?.logger?.error("qq_gateway_closed", {});
+          }
+        });
+      });
+    },
+    async stop() {
+      running = false;
+      clearHeartbeat();
+      const closing = socket;
+      socket = undefined;
+      if (closing && closing.readyState !== WebSocket.CLOSED) {
+        await new Promise((resolve) => {
+          closing.once("close", () => resolve());
+          closing.close();
+          setTimeout(resolve, 250).unref?.();
+        });
+      }
+    },
+    async sendMessage(target, message) {
+      rejectUnsupportedAttachments("QQ", message);
+      const route = qqSendRoute(target);
+      await qqRequest(options, route, await getAccessToken(), {
+        msg_type: 0,
+        content: String(message.text).trim(),
+        ...(target?.data?.messageId ? { msg_id: target.data.messageId } : {}),
+        msg_seq: 1,
+      });
+    },
+  };
+};
+
+const parseGatewayMessage = (data) => {
+  const text = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+  return JSON.parse(text);
+};
+
+export const normalizeQQEvent = (event, options = {}) => {
+  const text = typeof event?.content === "string" ? event.content.trim() : "";
+  if (!text) {
+    return undefined;
+  }
+  const groupOpenId = optionalEventString(event.group_openid);
+  const userOpenId = optionalEventString(event.user_openid ?? event.author?.user_openid ?? event.author?.id);
+  const channelId = optionalEventString(event.channel_id);
+  const guildId = optionalEventString(event.guild_id);
+  const messageId = optionalEventString(event.id);
+  const mentionedBot = isQQBotMentioned(text, options.botId) || Boolean(groupOpenId || guildId);
+  if (groupOpenId) {
+    return qqIncoming({
+      kind: "group",
+      id: groupOpenId,
+      text: stripQQMention(text, options.botId),
+      senderDisplayName: senderDisplayName(event.author ?? event.member),
+      mentionedBot,
+      messageId,
+    });
+  }
+  if (userOpenId) {
+    return qqIncoming({
+      kind: "private",
+      id: userOpenId,
+      text,
+      senderDisplayName: senderDisplayName(event.author),
+      mentionedBot: false,
+      messageId,
+    });
+  }
+  if (channelId) {
+    return qqIncoming({
+      kind: "channel",
+      id: channelId,
+      text: stripQQMention(text, options.botId),
+      senderDisplayName: senderDisplayName(event.author ?? event.member),
+      mentionedBot,
+      messageId,
+      extraData: guildId ? { guildId } : {},
+    });
+  }
+  return undefined;
+};
+
+export const redactQQSecret = (value) =>
+  String(value)
+    .replace(/(clientSecret"\s*:\s*")[^"]+/g, "$1[REDACTED]")
+    .replace(/QQBot\s+[A-Za-z0-9._-]+/g, "QQBot [REDACTED]");
+
+const qqIncoming = ({ kind, id, text, senderDisplayName, mentionedBot, messageId, extraData = {} }) => {
+  const conversationType = kind === "private" ? "private" : kind;
+  const externalConversationId = `qq:${conversationType}:${id}`;
+  return {
+    externalConversationId,
+    text,
+    conversationType,
+    senderDisplayName,
+    mentionedBot,
+    target: {
+      externalConversationId,
+      data: { kind, id, ...(messageId ? { messageId } : {}), ...extraData },
+    },
+    data: {
+      ...(messageId ? { messageId } : {}),
+      ...extraData,
+    },
+  };
+};
+
+const qqSendRoute = (target) => {
+  const kind = target?.data?.kind;
+  const id = target?.data?.id;
+  if (typeof id !== "string" || !id) {
+    throw new Error("QQ target is missing id");
+  }
+  if (kind === "group") {
+    return `/v2/groups/${encodeURIComponent(id)}/messages`;
+  }
+  if (kind === "private") {
+    return `/v2/users/${encodeURIComponent(id)}/messages`;
+  }
+  if (kind === "channel") {
+    return `/channels/${encodeURIComponent(id)}/messages`;
+  }
+  throw new Error("QQ target kind must be group, private, or channel");
+};
+
+const qqRequest = async (options, route, accessToken, body) => {
+  const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}${route}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `QQBot ${accessToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => undefined);
+  if (!response.ok) {
+    throw new Error(redactQQSecret(`qq send failed: ${payload?.message ?? response.status}`));
+  }
+  return payload;
+};
+
+const isQQBotMentioned = (text, botId) =>
+  Boolean(botId && new RegExp(`<@!?${escapeRegExp(botId)}>`, "i").test(text));
+
+const stripQQMention = (text, botId) => {
+  if (!botId) {
+    return text.trim();
+  }
+  return text.replace(new RegExp(`<@!?${escapeRegExp(botId)}>`, "gi"), " ").trim();
+};
+
+const senderDisplayName = (value) => {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  return optionalEventString(value.username ?? value.nick ?? value.name);
+};
+
+const optionalEventString = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+
+const requiredStringConfig = (value, name) => {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${name} is required`);
+  }
+  return value.trim();
+};
+
+const stringConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error("QQ config value must be a string");
+  }
+  return value;
+};
+
+const optionalStringConfig = (value, name) => {
+  if (value === undefined || value === "") {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string`);
+  }
+  return value;
+};
+
+const numberConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error("QQ config value must be a positive number");
+  }
+  return parsed;
+};
+
+const isDuplicateMessage = (incoming, recentMessageIds, ttlMs) => {
+  const messageId = optionalEventString(incoming?.data?.messageId ?? incoming?.target?.data?.messageId);
+  if (!messageId) {
+    return false;
+  }
+  const now = Date.now();
+  for (const [id, expiresAt] of recentMessageIds) {
+    if (expiresAt <= now) {
+      recentMessageIds.delete(id);
+    }
+  }
+  if (recentMessageIds.has(messageId)) {
+    return true;
+  }
+  recentMessageIds.set(messageId, now + ttlMs);
+  return false;
+};
+
+const safeErrorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+
+const rejectUnsupportedAttachments = (platform, message) => {
+  if (Array.isArray(message.attachments) && message.attachments.length > 0) {
+    throw new Error(`${platform} attachment sending is not supported yet`);
+  }
+};
+
+const escapeRegExp = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/extensions/builtin/qq/scorel.extension.json

@@ -0,0 +1,7 @@
+{
+  "id": "qq",
+  "kind": "im",
+  "displayName": "QQ Bot",
+  "adapter": "./adapter.js",
+  "skills": ["./skills"]
+}

package/extensions/builtin/qq/skills/qq/SKILL.md

@@ -0,0 +1,9 @@
+# QQ Bot
+
+Use this skill when replying through the QQ Bot IM channel.
+
+- Treat QQ messages as short conversational turns.
+- In groups, assume the user intentionally mentioned the bot when the channel context says `mentioned_bot: true`.
+- Reply with `SendChannelMessage` to the current conversation instead of exposing raw QQ ids.
+- If work will take more than a brief moment, send a short acknowledgement first, then follow with progress or the final result.
+- Keep replies concise and avoid dumping internal tool logs unless the user asked for technical detail.

package/extensions/builtin/telegram/adapter.d.ts

@@ -0,0 +1,43 @@
+export type TelegramAdapterOptions = {
+  token: string;
+  apiBaseUrl: string;
+  pollIntervalMs?: number;
+  allowedChatIds?: string[];
+  botUsername?: string;
+};
+
+export type TelegramIncomingMessage = {
+  externalConversationId: string;
+  text: string;
+  conversationType?: string;
+  senderDisplayName?: string;
+  mentionedBot?: boolean;
+  target?: TelegramTarget;
+  data?: Record<string, unknown>;
+};
+
+export type TelegramTarget = {
+  externalConversationId: string;
+  data?: Record<string, unknown>;
+};
+
+export type TelegramAdapter = {
+  start(ctx: {
+    onMessage(message: TelegramIncomingMessage): Promise<void>;
+    logger: {
+      info(message: string, data?: Record<string, unknown>): void;
+      error(message: string, data?: Record<string, unknown>): void;
+    };
+  }): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(target: TelegramTarget, message: { text?: string; attachments?: Array<Record<string, unknown>> }): Promise<void>;
+  setTyping?(target: TelegramTarget, typing: boolean): Promise<void>;
+};
+
+export function createAdapter(options?: { config?: Record<string, string | number | boolean> }): TelegramAdapter;
+export function createTelegramAdapter(options: TelegramAdapterOptions): TelegramAdapter;
+export function normalizeTelegramUpdate(update: unknown, options?: { botUsername?: string; allowedChatIds?: string[] }): unknown;
+export function isBotMentioned(message: unknown, botUsername?: string): boolean;
+export function splitTelegramText(text: string): string[];
+export function parseAllowedChatIds(value: unknown): string[];
+export function redactToken(value: string): string;