opensquid 0.5.395

package/dist/chat/adapters/slack.js

@@ -0,0 +1,172 @@
+/**
+ * Slack adapter — Socket Mode via @slack/socket-mode + @slack/web-api
+ * (v0.7c). Skips @slack/bolt to avoid dragging Express into opensquid's
+ * runtime tree.
+ *
+ * Two tokens required (Slack architectural decision, not opensquid's):
+ *   bot_token  — `xoxb-...` Bot User OAuth Token, used for Web API calls
+ *   app_token  — `xapp-...` App-Level Token with `connections:write`
+ *                scope, used for the Socket Mode WebSocket
+ *
+ * Connection: outbound WebSocket via Socket Mode. No public webhook
+ * URL, no signature verification, no 3-second response SLA scrimmage.
+ * Works behind any NAT.
+ *
+ * Setup gotchas (surface in install docs):
+ *   1. Two tokens are easy to swap — xoxb→WebClient, xapp→SocketModeClient.
+ *      Our validator rejects the wrong prefix at config-load time.
+ *   2. MUST `await ack()` within 3 seconds of every event even in
+ *      Socket Mode, or Slack retries. We ack first, dispatch second.
+ *   3. Event Subscriptions need to be configured in the Slack dashboard
+ *      separately from the Socket Mode toggle — easy to miss.
+ */
+import { ChatGatewayError, formatChannelId, } from "../gateway.js";
+export class SlackAdapter {
+    config;
+    platform = "slack";
+    web = null;
+    socket = null;
+    handlers = [];
+    botUsername = "";
+    botId = "";
+    constructor(config) {
+        this.config = config;
+        if (!config.bot_token?.trim()) {
+            throw new ChatGatewayError("slack adapter: bot_token is required", "set chat_connections.slack.bot_token (xoxb-...) in ~/.opensquid/config.json");
+        }
+        if (!config.app_token?.trim()) {
+            throw new ChatGatewayError("slack adapter: app_token is required for Socket Mode", "set chat_connections.slack.app_token (xapp-...) in ~/.opensquid/config.json");
+        }
+    }
+    async start() {
+        if (this.socket)
+            return;
+        let WebClient;
+        let SocketModeClient;
+        try {
+            const web = (await import("@slack/web-api"));
+            WebClient = web.WebClient;
+        }
+        catch (err) {
+            // v0.7 audit fix (M5): distinguish not-installed from installed-but-threw.
+            const code = err?.code;
+            if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+                throw new ChatGatewayError("slack adapter: '@slack/web-api' SDK not installed", "run `npm install @slack/web-api @slack/socket-mode` (or reinstall without --omit=optional)");
+            }
+            throw new ChatGatewayError(`slack adapter: '@slack/web-api' SDK failed to load: ${err instanceof Error ? err.message : String(err)}`, "the SDK is installed but threw on import — check node version compatibility");
+        }
+        try {
+            const sm = (await import("@slack/socket-mode"));
+            SocketModeClient = sm.SocketModeClient;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+                throw new ChatGatewayError("slack adapter: '@slack/socket-mode' SDK not installed", "run `npm install @slack/socket-mode`");
+            }
+            throw new ChatGatewayError(`slack adapter: '@slack/socket-mode' SDK failed to load: ${err instanceof Error ? err.message : String(err)}`, "the SDK is installed but threw on import — check node version compatibility");
+        }
+        this.web = new WebClient(this.config.bot_token);
+        const socket = new SocketModeClient({ appToken: this.config.app_token });
+        this.socket = socket;
+        // Probe identity + bot_token validity in one round-trip.
+        const me = await this.web.auth.test();
+        if (!me.ok) {
+            throw new ChatGatewayError("slack adapter: auth.test failed — bot_token may be revoked");
+        }
+        this.botUsername = me.user ?? "";
+        this.botId = me.user_id ?? me.bot_id ?? "";
+        socket.on("message", async ({ event, ack }) => {
+            // ack FIRST — Slack's 3-second retry clock is unforgiving even
+            // in Socket Mode. Drop the work into the handler stack after.
+            await ack();
+            // Filter out subtypes (channel_join, bot_message, message_changed,
+            // etc.) and our own messages.
+            if (event.subtype)
+                return;
+            if (event.bot_id)
+                return;
+            if (!event.text || !event.user || !event.channel)
+                return;
+            if (this.config.allowlist_user_ids &&
+                this.config.allowlist_user_ids.length > 0 &&
+                !this.config.allowlist_user_ids.includes(event.user)) {
+                return;
+            }
+            const normalized = {
+                id: event.ts ?? `${event.channel}-${Date.now()}`,
+                platform: "slack",
+                channel: formatChannelId("slack", event.channel),
+                sender: event.user,
+                senderId: event.user,
+                text: event.text,
+                receivedAt: event.ts ? new Date(Math.floor(Number(event.ts) * 1000)) : new Date(),
+                mentionsBot: this.botId ? event.text.includes(`<@${this.botId}>`) : false,
+            };
+            for (const h of this.handlers) {
+                try {
+                    await h(normalized);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // eslint-disable-next-line no-console
+                    console.error(`[slack adapter] handler error: ${msg}`);
+                }
+            }
+        });
+        await socket.start();
+    }
+    async shutdown() {
+        if (!this.socket)
+            return;
+        try {
+            await this.socket.disconnect();
+        }
+        catch {
+            // best-effort
+        }
+        this.socket = null;
+        this.web = null;
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    async send(message) {
+        if (!this.web) {
+            throw new ChatGatewayError("slack adapter: not started", "call gateway.start() before send()");
+        }
+        const channel = nativeChannelIdFromChannel(message.channel);
+        const sent = await this.web.chat.postMessage({
+            channel,
+            text: message.text,
+            thread_ts: message.replyTo,
+        });
+        if (!sent.ok || !sent.ts) {
+            throw new ChatGatewayError(`slack adapter: chat.postMessage failed for channel '${channel}'`);
+        }
+        return {
+            platform: "slack",
+            messageId: sent.ts,
+            deliveredAt: new Date(Math.floor(Number(sent.ts) * 1000)),
+        };
+    }
+    async identity() {
+        if (!this.web) {
+            throw new ChatGatewayError("slack adapter: not started");
+        }
+        return { username: this.botUsername, nativeId: this.botId };
+    }
+}
+// ---------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------
+function nativeChannelIdFromChannel(channel) {
+    const idx = channel.indexOf(":");
+    if (idx === -1) {
+        throw new ChatGatewayError(`malformed channel id '${channel}'`);
+    }
+    if (channel.slice(0, idx) !== "slack") {
+        throw new ChatGatewayError(`slack adapter received non-slack channel: '${channel}'`);
+    }
+    return channel.slice(idx + 1);
+}

package/dist/chat/adapters/slack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.js","sourceRoot":"","sources":["../../../src.legacy/chat/adapters/slack.ts"],"names":[],"mappings":"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"}

package/dist/chat/adapters/slack.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { ChatGatewayError } from "../gateway.js";
+import { SlackAdapter } from "./slack.js";
+describe("SlackAdapter constructor", () => {
+    it("rejects empty bot_token", () => {
+        expect(() => new SlackAdapter({ bot_token: "", app_token: "xapp-1-2-3" })).toThrow(ChatGatewayError);
+    });
+    it("rejects empty app_token", () => {
+        expect(() => new SlackAdapter({ bot_token: "xoxb-1-2-3", app_token: "" })).toThrow(ChatGatewayError);
+    });
+    it("rejects whitespace-only tokens", () => {
+        expect(() => new SlackAdapter({ bot_token: "   ", app_token: "xapp-1-2-3" })).toThrow();
+        expect(() => new SlackAdapter({ bot_token: "xoxb-1-2-3", app_token: "   " })).toThrow();
+    });
+    it("accepts both real-shaped tokens", () => {
+        const a = new SlackAdapter({
+            bot_token: "xoxb-123-456-abc",
+            app_token: "xapp-1-A1B2-xyz",
+        });
+        expect(a.platform).toBe("slack");
+    });
+    it("send before start() throws", async () => {
+        const a = new SlackAdapter({ bot_token: "xoxb-x", app_token: "xapp-x" });
+        await expect(a.send({ channel: "slack:C012345", text: "hi" })).rejects.toThrow(/not started/);
+    });
+    it("identity before start() throws", async () => {
+        const a = new SlackAdapter({ bot_token: "xoxb-x", app_token: "xapp-x" });
+        await expect(a.identity()).rejects.toThrow(/not started/);
+    });
+});

package/dist/chat/adapters/telegram.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Telegram adapter — long-polling via the official Bot API (v0.7a).
+ *
+ * SDK: `grammy` (modern, TS-first, actively maintained — recommended
+ * over `telegraf` which is frozen at v4.16 from Feb 2024 and over
+ * `node-telegram-bot-api` which is untyped).
+ *
+ * Connection: long-polling via `bot.start()` — no public webhook URL
+ * required. The bot opens an outbound HTTPS connection to
+ * `api.telegram.org` and polls for updates. Works behind any NAT.
+ *
+ * Why `grammy` is loaded via dynamic import: opensquid declares all
+ * three chat SDKs as optionalDependencies. Users with no Telegram
+ * config (and possibly `npm --omit=optional`) shouldn't pay the install
+ * cost. The dynamic import only runs in `start()` when this adapter
+ * is actually being activated — and produces a clear "install grammy"
+ * error if the dep is missing.
+ *
+ * Gotcha: only ONE polling consumer per token at a time. A second
+ * opensquid process with the same token will collide with 409 Conflict.
+ * Surface that error clearly on start.
+ */
+import { type ChatAdapter, type MessageHandler, type OutboundMessage, type SendResult } from "../gateway.js";
+import type { TelegramConfig } from "../config.js";
+export declare class TelegramAdapter implements ChatAdapter {
+    private readonly config;
+    readonly platform: "telegram";
+    private bot;
+    private handlers;
+    private botUsername;
+    private botId;
+    private startPromise;
+    /**
+     * 0.7.4 (#147): true when the long-poll lost to a 409 Conflict
+     * (another consumer holds the token — typically the Claude Code
+     * `plugin:telegram` bun bot). Outbound sendMessage still works via
+     * HTTPS, only inbound is dead. A periodic retry attempts to reclaim.
+     */
+    private outboundOnly;
+    /** 0.7.4 (#147): handle for the periodic long-poll retry timer. */
+    private retryTimer;
+    /** Retry cadence — long enough that flapping doesn't burn API quota. */
+    private static readonly RETRY_INTERVAL_MS;
+    /**
+     * 0.5.90 (TG.3): chat_ids for which we've already logged an allowlist
+     * drop this process. The adapter silently drops messages from non-
+     * allowlisted chats (correct policy — never echo policy decisions back
+     * to the sender), but operators need a one-time-per-chat log line so
+     * they can diagnose "why isn't my message routing?" without reading
+     * source. Tracked as a Set keyed by chatIdStr; resets on restart.
+     */
+    private allowlistDropLogged;
+    constructor(config: TelegramConfig);
+    start(): Promise<void>;
+    /**
+     * 0.7.4 (#147): handle a rejection from `bot.start()`. Extracted
+     * from inline catch handler so tests can simulate 409 without
+     * needing a live grammy + colliding bot. EXPORTED VIA PROTECTED for
+     * test-only direct invocation; not part of the public adapter API.
+     */
+    handleStartRejection(err: unknown): void;
+    /**
+     * 0.7.4 (#147): test-only seed — install a fake bot reference + mark
+     * outbound-only so tests can verify isOutboundOnly() + retry timer
+     * without spinning up grammy. Must be called before any
+     * handleStartRejection in test context.
+     */
+    _testSeed(fakeBot: any): void;
+    /**
+     * 0.7.4 (#147): test-only — clear the retry timer so tests don't
+     * leak intervals after a 409 simulation.
+     */
+    _testClearRetryTimer(): void;
+    /**
+     * 0.7.4 (#147): periodically retry the long-poll while in outbound-
+     * only mode. If the competing consumer disconnects, we reclaim
+     * inbound transparently.
+     */
+    private scheduleRetry;
+    private tryReclaim;
+    shutdown(): Promise<void>;
+    /**
+     * 0.7.4 (#147): introspection accessor for tests + the
+     * `chat_daemon_status` MCP tool to surface "outbound-only" state to
+     * operators trying to diagnose "where did my message go?"
+     */
+    isOutboundOnly(): boolean;
+    onMessage(handler: MessageHandler): void;
+    send(message: OutboundMessage): Promise<SendResult>;
+    /**
+     * v0.7.2 — Create a forum topic in a supergroup. Requires the bot
+     * to be admin with "Manage Topics" permission and the supergroup to
+     * have Topics enabled in settings. Returns the topic's
+     * `message_thread_id` for storage in chat-routing.json.
+     */
+    createTopic(chatId: string, name: string, options?: {
+        iconColor?: number;
+        iconCustomEmojiId?: string;
+    }): Promise<{
+        message_thread_id: number;
+        name: string;
+    }>;
+    identity(): Promise<{
+        username: string;
+        nativeId: string;
+    }>;
+}
+/**
+ * Parse a Telegram channel id (with optional embedded forum-topic
+ * thread id) into its native chat_id + message_thread_id parts.
+ *
+ * Wire format (canonical, mirrors `chat_poll_inbox` output):
+ * - `telegram:<chat_id>`              → general topic, no thread
+ * - `telegram:<chat_id>:<thread_id>`  → forum topic (supergroup with
+ *                                       Topics enabled)
+ *
+ * Examples:
+ * - `telegram:-1001234567890`      → `{ chatId: "-1001234567890" }`
+ * - `telegram:-1001234567890:15`   → `{ chatId: "-1001234567890",
+ *                                       threadId: "15" }`
+ * - `telegram:8075471258`          → `{ chatId: "8075471258" }` (DM)
+ *
+ * Why the parser lives in the adapter (not in `gateway.ts`): Slack uses
+ * a different colon-in-native-id convention (`slack:C012345:1234.5678`
+ * where the trailing segment is `thread_ts`, an opaque part of the
+ * native id). Telegram's `<chat_id>:<thread_id>` semantic is
+ * platform-specific and shouldn't leak into the cross-platform
+ * `nativeIdFromChannel` helper.
+ *
+ * Exported for unit testing.
+ */
+export declare function parseTelegramChannel(channel: string): {
+    chatId: string;
+    threadId?: string;
+};
+/**
+ * Detect whether a message text contains an @-mention of this bot, or
+ * uses one of telegram's bot_command entities pointing at the bot
+ * (`/cmd@my_bot`).
+ *
+ * Exported for unit testing.
+ */
+export declare function detectBotMention(text: string, entities: Array<{
+    type: string;
+    offset: number;
+    length: number;
+}> | undefined, botUsername: string): boolean;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/chat/adapters/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../../src.legacy/chat/adapters/telegram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,WAAW,EAGhB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EAEhB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA0CnD,qBAAa,eAAgB,YAAW,WAAW;IA6BrC,OAAO,CAAC,QAAQ,CAAC,MAAM;IA5BnC,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;IAExC,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,YAAY,CAA8B;IAClD;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAS;IAC7B,mEAAmE;IACnE,OAAO,CAAC,UAAU,CAA+B;IACjD,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IACnD;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB,CAAqB;gBAEnB,MAAM,EAAE,cAAc;IAS7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4F5B;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAmBxC;;;;;OAKG;IAEH,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAI7B;;;OAGG;IACH,oBAAoB,IAAI,IAAI;IAO5B;;;;OAIG;IACH,OAAO,CAAC,aAAa;YAOP,UAAU;IA2ClB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB/B;;;;OAIG;IACH,cAAc,IAAI,OAAO;IAIzB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIlC,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BzD;;;;;OAKG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/D,OAAO,CAAC;QAAE,iBAAiB,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAejD,QAAQ,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAMlE;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAqCA;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,EAC7E,WAAW,EAAE,MAAM,GAClB,OAAO,CAWT"}