@chanlerdev/scorel 0.0.1 → 0.0.3

package/extensions/builtin/telegram/adapter.js

@@ -0,0 +1,259 @@
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const TELEGRAM_MESSAGE_LIMIT = 4096;
+
+export const createAdapter = ({ config = {} } = {}) => {
+  const directToken = optionalStringConfig(config.apiKey ?? config.botToken, "Telegram direct API key");
+  const tokenEnv = stringConfig(config.botTokenEnv, "SCOREL_TELEGRAM_BOT_TOKEN");
+  const token = directToken ?? process.env[tokenEnv];
+  if (!token) {
+    throw new Error(`${tokenEnv} is not set`);
+  }
+  return createTelegramAdapter({
+    token,
+    apiBaseUrl: stringConfig(config.apiBaseUrl, "https://api.telegram.org"),
+    pollIntervalMs: numberConfig(config.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS),
+    allowedChatIds: parseAllowedChatIds(config.allowedChatIds),
+    botUsername: typeof config.botUsername === "string" ? config.botUsername : undefined,
+  });
+};
+
+export const createTelegramAdapter = (options) => {
+  const state = {
+    running: false,
+    offset: undefined,
+    timer: undefined,
+    ctx: undefined,
+    botUsername: options.botUsername,
+  };
+
+  const request = async (method, body) => telegramRequest(options.apiBaseUrl, options.token, method, body);
+
+  const pollOnce = async () => {
+    if (!state.running || !state.ctx) {
+      return;
+    }
+    try {
+      if (!state.botUsername) {
+        const me = await request("getMe", {});
+        state.botUsername = typeof me?.username === "string" ? me.username : undefined;
+      }
+      const updates = await request("getUpdates", {
+        timeout: 0,
+        ...(state.offset !== undefined ? { offset: state.offset } : {}),
+      });
+      if (!Array.isArray(updates)) {
+        return;
+      }
+      for (const update of updates) {
+        if (typeof update?.update_id === "number") {
+          state.offset = update.update_id + 1;
+        }
+        const incoming = normalizeTelegramUpdate(update, {
+          botUsername: state.botUsername,
+          allowedChatIds: options.allowedChatIds ?? [],
+        });
+        if (!incoming) {
+          continue;
+        }
+        await state.ctx.onMessage(incoming);
+      }
+    } catch (cause) {
+      state.ctx.logger.error("telegram_poll_failed", { message: safeErrorMessage(cause) });
+    }
+  };
+
+  const scheduleNextPoll = () => {
+    if (!state.running) {
+      return;
+    }
+    state.timer = setTimeout(() => {
+      void pollOnce().finally(scheduleNextPoll);
+    }, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    state.timer.unref?.();
+  };
+
+  return {
+    async start(ctx) {
+      state.ctx = ctx;
+      state.running = true;
+      await pollOnce();
+      scheduleNextPoll();
+    },
+    async stop() {
+      state.running = false;
+      if (state.timer) {
+        clearTimeout(state.timer);
+        state.timer = undefined;
+      }
+    },
+    async sendMessage(target, message) {
+      rejectUnsupportedAttachments("Telegram", message);
+      const chatId = target?.data?.chatId;
+      if (chatId === undefined || chatId === null) {
+        throw new Error("telegram target is missing chatId");
+      }
+      for (const text of splitTelegramText(message.text)) {
+        await request("sendMessage", { chat_id: chatId, text });
+      }
+    },
+    async setTyping(target, typing) {
+      if (!typing) {
+        return;
+      }
+      const chatId = target?.data?.chatId;
+      if (chatId === undefined || chatId === null) {
+        return;
+      }
+      await request("sendChatAction", { chat_id: chatId, action: "typing" });
+    },
+  };
+};
+
+export const normalizeTelegramUpdate = (update, options = {}) => {
+  const message = update?.message;
+  if (!message || typeof message !== "object") {
+    return undefined;
+  }
+  if (typeof message.text !== "string" || message.text.trim().length === 0) {
+    return undefined;
+  }
+  const chat = message.chat;
+  if (!chat || typeof chat.id !== "number") {
+    return undefined;
+  }
+  const allowedChatIds = options.allowedChatIds ?? [];
+  if (allowedChatIds.length > 0 && !allowedChatIds.includes(String(chat.id))) {
+    return undefined;
+  }
+  const conversationType = telegramConversationType(chat.type);
+  const mentionedBot = isBotMentioned(message, options.botUsername);
+  if ((conversationType === "group" || conversationType === "supergroup") && !mentionedBot) {
+    return undefined;
+  }
+  return {
+    externalConversationId: `telegram:${conversationType}:${chat.id}`,
+    text: stripBotMention(message.text, options.botUsername),
+    conversationType,
+    senderDisplayName: senderDisplayName(message.from),
+    mentionedBot,
+    target: {
+      externalConversationId: `telegram:${conversationType}:${chat.id}`,
+      data: { chatId: chat.id },
+    },
+    data: {
+      messageId: message.message_id,
+      chatType: chat.type,
+    },
+  };
+};
+
+export const isBotMentioned = (message, botUsername) => {
+  const text = typeof message?.text === "string" ? message.text : "";
+  if (botUsername && new RegExp(`(^|\\s)@${escapeRegExp(botUsername)}\\b`, "i").test(text)) {
+    return true;
+  }
+  const replyUsername = message?.reply_to_message?.from?.username;
+  return Boolean(botUsername && typeof replyUsername === "string" && replyUsername.toLowerCase() === botUsername.toLowerCase());
+};
+
+export const splitTelegramText = (text) => {
+  const normalized = String(text).trim();
+  if (normalized.length <= TELEGRAM_MESSAGE_LIMIT) {
+    return [normalized];
+  }
+  const chunks = [];
+  for (let index = 0; index < normalized.length; index += TELEGRAM_MESSAGE_LIMIT) {
+    chunks.push(normalized.slice(index, index + TELEGRAM_MESSAGE_LIMIT));
+  }
+  return chunks;
+};
+
+export const parseAllowedChatIds = (value) => {
+  if (value === undefined || value === "") {
+    return [];
+  }
+  if (typeof value === "number") {
+    return [String(value)];
+  }
+  if (typeof value !== "string") {
+    throw new Error("allowedChatIds must be a comma-separated string");
+  }
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+};
+
+const telegramRequest = async (apiBaseUrl, token, method, body) => {
+  const response = await fetch(`${apiBaseUrl.replace(/\/+$/, "")}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => undefined);
+  if (!response.ok || payload?.ok !== true) {
+    throw new Error(`telegram ${method} failed: ${payload?.description ?? response.status}`);
+  }
+  return payload.result;
+};
+
+const telegramConversationType = (type) => {
+  if (type === "group" || type === "supergroup" || type === "private") {
+    return type;
+  }
+  return "group";
+};
+
+const senderDisplayName = (from) => {
+  if (!from || typeof from !== "object") {
+    return undefined;
+  }
+  return [from.first_name, from.last_name].filter((part) => typeof part === "string" && part.trim()).join(" ") ||
+    (typeof from.username === "string" ? from.username : undefined);
+};
+
+const stripBotMention = (text, botUsername) => {
+  if (!botUsername) {
+    return text.trim();
+  }
+  return text.replace(new RegExp(`(^|\\s)@${escapeRegExp(botUsername)}\\b`, "i"), " ").trim();
+};
+
+const stringConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error("Telegram 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) {
+    return fallback;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error("Telegram numeric config value must be non-negative");
+  }
+  return value;
+};
+
+const safeErrorMessage = (cause) => cause instanceof Error ? redactToken(cause.message) : redactToken(String(cause));
+
+export const redactToken = (value) => value.replace(/bot[0-9]+:[A-Za-z0-9_-]+/g, "bot[REDACTED]");
+
+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) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

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

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

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

@@ -0,0 +1,11 @@
+---
+description: Reply to the current Telegram conversation through SendChannelMessage.
+---
+
+# Telegram
+
+When a message comes from Telegram, use `SendChannelMessage` to reply to the current chat when a response is needed.
+
+In groups, assume the user mentioned or replied to the bot before the message reached Scorel. Keep replies concise and avoid exposing raw chat ids, user ids, bot tokens, or internal routing details.
+
+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/wechat/adapter.d.ts

@@ -0,0 +1,24 @@
+export type WeChatAdapterOptions = {
+  webhookUrl?: string;
+  callbackHost?: string;
+  callbackPort?: number;
+  callbackPath?: string;
+  callbackToken?: string;
+};
+
+export type WeChatTarget = {
+  externalConversationId: string;
+  data?: Record<string, unknown>;
+};
+
+export type WeChatAdapter = {
+  start(ctx: unknown): Promise<void>;
+  stop(): Promise<void>;
+  callbackUrl?(): string | undefined;
+  sendMessage(target: WeChatTarget, message: { text?: string; attachments?: Array<Record<string, unknown>> }): Promise<void>;
+};
+
+export function createAdapter(options?: { config?: Record<string, string | number | boolean> }): WeChatAdapter;
+export function createWeChatAdapter(options: WeChatAdapterOptions): WeChatAdapter;
+export function normalizeWeChatEvent(event: unknown): unknown;
+export function redactWeChatSecret(value: string): string;

package/extensions/builtin/wechat/adapter.js

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+
+export const createAdapter = ({ config = {} } = {}) => {
+  return createWeChatAdapter({
+    webhookUrl: optionalStringConfig(config.webhookUrl, "WeChat webhook URL"),
+    callbackHost: stringConfig(config.callbackHost, "127.0.0.1"),
+    callbackPort: numberConfig(config.callbackPort, undefined),
+    callbackPath: stringConfig(config.callbackPath, "/wechat/callback"),
+    callbackToken: optionalStringConfig(config.callbackToken, "WeChat callback token"),
+  });
+};
+
+export const createWeChatAdapter = (options) => {
+  if (!options.webhookUrl && !options.callbackToken) {
+    throw new Error("WeChat webhook URL or callback token is required");
+  }
+  let server;
+  let ctx;
+  let callbackPort;
+
+  return {
+    async start(startCtx) {
+      ctx = startCtx;
+      if (!options.callbackToken) {
+        ctx?.logger?.info("wechat_callback_not_configured", {});
+        return;
+      }
+      server = createServer((request, response) => {
+        void handleCallbackRequest(options, request, response, ctx).catch((cause) => {
+          ctx?.logger?.error("wechat_callback_failed", { message: redactWeChatSecret(safeErrorMessage(cause)) });
+          if (!response.headersSent) {
+            response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+          }
+          response.end("error");
+        });
+      });
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.once("listening", () => {
+          server.off("error", reject);
+          resolve();
+        });
+        server.listen(options.callbackPort ?? 0, options.callbackHost ?? "127.0.0.1");
+      });
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("WeChat callback server did not expose a TCP address");
+      }
+      callbackPort = address.port;
+      ctx?.logger?.info("wechat_callback_started", { url: callbackUrl(options, callbackPort) });
+    },
+    async stop() {
+      const closing = server;
+      server = undefined;
+      callbackPort = undefined;
+      if (closing) {
+        await new Promise((resolve, reject) => closing.close((error) => error ? reject(error) : resolve()));
+      }
+    },
+    callbackUrl() {
+      return callbackPort ? callbackUrl(options, callbackPort) : undefined;
+    },
+    async sendMessage(_target, message) {
+      rejectUnsupportedAttachments("WeChat", message);
+      if (!options.webhookUrl) {
+        throw new Error("WeChat outbound webhook URL is not configured");
+      }
+      const response = await fetch(options.webhookUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          msgtype: "text",
+          text: { content: String(message.text).trim() },
+        }),
+      });
+      const payload = await response.json().catch(() => undefined);
+      if (!response.ok || (payload?.errcode !== undefined && payload.errcode !== 0)) {
+        throw new Error(redactWeChatSecret(`wechat send failed: ${payload?.errmsg ?? response.status}`));
+      }
+    },
+  };
+};
+
+export const normalizeWeChatEvent = (event) => {
+  const text = typeof event?.Content === "string" ? event.Content.trim() : "";
+  if (!text || event?.MsgType !== "text") {
+    return undefined;
+  }
+  const openId = optionalEventString(event.FromUserName);
+  if (!openId) {
+    return undefined;
+  }
+  const messageId = optionalEventString(event.MsgId);
+  const externalConversationId = `wechat:official:${openId}`;
+  return {
+    externalConversationId,
+    text,
+    conversationType: "official",
+    mentionedBot: true,
+    target: {
+      externalConversationId,
+      data: { kind: "official", id: openId, ...(messageId ? { messageId } : {}) },
+    },
+    data: {
+      ...(messageId ? { messageId } : {}),
+    },
+  };
+};
+
+export const redactWeChatSecret = (value) =>
+  String(value)
+    .replace(/([?&]key=)[^&\s]+/g, "$1[REDACTED]")
+    .replace(/(callbackToken"\s*:\s*")[^"]+/g, "$1[REDACTED]");
+
+const handleCallbackRequest = async (options, request, response, ctx) => {
+  const url = new URL(request.url ?? "/", "http://127.0.0.1");
+  if (url.pathname !== (options.callbackPath ?? "/wechat/callback")) {
+    response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+    response.end("not found");
+    return;
+  }
+  const timestamp = url.searchParams.get("timestamp") ?? "";
+  const nonce = url.searchParams.get("nonce") ?? "";
+  const signature = url.searchParams.get("signature") ?? "";
+  if (!verifySignature(options.callbackToken, timestamp, nonce, signature)) {
+    response.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+    response.end("invalid signature");
+    return;
+  }
+  if (request.method === "GET") {
+    response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+    response.end(url.searchParams.get("echostr") ?? "");
+    return;
+  }
+  if (request.method !== "POST") {
+    response.writeHead(405, { "content-type": "text/plain; charset=utf-8" });
+    response.end("method not allowed");
+    return;
+  }
+  const event = parseWeChatXml(await readText(request));
+  const incoming = normalizeWeChatEvent(event);
+  if (incoming) {
+    await ctx?.onMessage(incoming);
+  }
+  response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+  response.end("success");
+};
+
+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 optionalStringConfig = (value, name) => {
+  if (value === undefined || value === "") {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string`);
+  }
+  return value.trim();
+};
+
+const stringConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error("WeChat config value must be a string");
+  }
+  return value.trim();
+};
+
+const numberConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    throw new Error("WeChat callback port must be a valid TCP port");
+  }
+  return parsed;
+};
+
+const callbackUrl = (options, port) =>
+  `http://${options.callbackHost ?? "127.0.0.1"}:${port}${options.callbackPath ?? "/wechat/callback"}`;
+
+const verifySignature = (token, timestamp, nonce, signature) => {
+  if (!token || !timestamp || !nonce || !signature) {
+    return false;
+  }
+  const expected = createHash("sha1").update([token, timestamp, nonce].sort().join("")).digest("hex");
+  return expected === signature;
+};
+
+const readText = async (request) => {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+const parseWeChatXml = (xml) => {
+  const result = {};
+  for (const key of ["ToUserName", "FromUserName", "CreateTime", "MsgType", "Content", "MsgId"]) {
+    const match = new RegExp(`<${key}>(?:<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>|([\\s\\S]*?))<\\/${key}>`).exec(xml);
+    if (match) {
+      result[key] = (match[1] ?? match[2] ?? "").trim();
+    }
+  }
+  return result;
+};
+
+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`);
+  }
+};

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

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

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

@@ -0,0 +1,9 @@
+# WeChat
+
+Use this skill when replying through the WeChat IM channel.
+
+- Treat WeChat replies as human chat, not as a delayed report.
+- Use `SendChannelMessage` for the current conversation; do not expose OpenID, webhook key, or raw platform routing ids.
+- Send a short acknowledgement before long work, then send concise progress or final results.
+- Prefer short paragraphs and concrete next actions.
+- Do not imply personal WeChat account automation; Scorel uses official WeChat or WeCom-style bot surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanlerdev/scorel",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Replayable, recoverable, remotely controllable AI Agent workspace.",
   "type": "module",
   "packageManager": "pnpm@11.1.2",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "extensions",
     "README.md",
     "docs/SHIP.md",
     "docs/ROADMAP.md",
@@ -31,11 +32,14 @@
     "check": "pnpm typecheck && pnpm test",
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "release": "node scripts/release.mjs",
+    "release-notes": "node scripts/release-notes.mjs",
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test",
     "verify:m8-relay": "node --import tsx scripts/verify-m8-relay-e2e.ts",
+    "verify:m9-gui": "node --import tsx scripts/verify-m9-gui-e2e.ts",
     "scorel": "node --import tsx apps/cli/src/index.ts",
-    "dev": "node --import tsx apps/cli/src/index.ts up"
+    "dev": "node --import tsx apps/cli/src/index.ts up",
+    "gui": "pnpm --filter @scorel/app-gui dev"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",