@nanhara/hara 0.67.0 → 0.89.0

package/dist/gateway/matrix.js

@@ -0,0 +1,188 @@
+// Matrix adapter for `hara gateway` — client-server API with a /sync long-poll (built-in fetch, zero new dep;
+// no WebSocket). Mirrors the Telegram long-poll model and the Discord download-media/sendFile patterns. Creds
+// from HARA_MATRIX_HOMESERVER (e.g. https://matrix.org) + HARA_MATRIX_TOKEN (access token) + HARA_MATRIX_USER_ID
+// (the bot's own @user:server, for self-filtering). Same ChatAdapter shape as the others, so all cross-platform
+// gateway plumbing (send_file, system context, stuck-guard, image attach/describe) works unchanged.
+//
+// LIMITATION (v1): NO end-to-end encryption. Encrypted rooms (m.room.encrypted events) are skipped — only
+// plaintext rooms work. E2EE would need libolm + a crypto store (see hermes' matrix-nio adapter), which breaks
+// the zero-dep constraint. Invite this bot into UNENCRYPTED rooms only.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const isImage = (name, mime) => (mime?.startsWith("image/") ?? false) || /\.(png|jpe?g|gif|webp)$/i.test(name);
+const mimeFromExt = (name) => {
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+        mp4: "video/mp4", mp3: "audio/mpeg", ogg: "audio/ogg", pdf: "application/pdf", txt: "text/plain",
+    };
+    return map[ext] ?? "application/octet-stream";
+};
+/** Parse `mxc://server/mediaId` → its two parts (pure). null if not an mxc URL. */
+export function parseMxc(mxc) {
+    if (typeof mxc !== "string" || !mxc.startsWith("mxc://"))
+        return null;
+    const rest = mxc.slice(6); // strip "mxc://"
+    const slash = rest.indexOf("/");
+    if (slash < 0)
+        return null;
+    const server = rest.slice(0, slash);
+    const mediaId = rest.slice(slash + 1);
+    if (!server || !mediaId)
+        return null;
+    return { server, mediaId };
+}
+/** Extract an InboundMsg from a single Matrix timeline event (pure). Accepts m.room.message of msgtype m.text
+ *  (and friends carrying a body) plus m.image (→ marker text + the mxc url to download in start()). Ignores our
+ *  own messages and encrypted events. Returns the InboundMsg + the image's mxc url (null if none). null = skip. */
+export function parseMatrixEvent(event, selfUserId) {
+    if (!event || event.type !== "m.room.message")
+        return null; // encrypted (m.room.encrypted) / state events → skip
+    const sender = typeof event.sender === "string" ? event.sender : "";
+    const roomId = typeof event.__roomId === "string" ? event.__roomId : ""; // injected by start() (events carry no room id)
+    if (!sender || !roomId)
+        return null;
+    if (sender === selfUserId)
+        return null; // ignore our own messages
+    const content = event.content ?? {};
+    const msgtype = typeof content.msgtype === "string" ? content.msgtype : "";
+    const body = typeof content.body === "string" ? content.body : "";
+    let imageMxc = null;
+    let text = body;
+    if (msgtype === "m.image") {
+        imageMxc = typeof content.url === "string" && content.url.startsWith("mxc://") ? content.url : null;
+        text = body || "[图片]";
+    }
+    else if (!body) {
+        return null; // text-less non-image (sticker/location/reaction-as-message/etc.)
+    }
+    return {
+        msg: {
+            chatId: roomId,
+            userId: sender,
+            userName: sender,
+            text: text || "[图片]",
+        },
+        imageMxc,
+    };
+}
+/** Download a Matrix mxc:// media to a local path under ~/.hara/matrix/media (resolves via /_matrix/media/v3/download). */
+async function downloadMatrixMedia(homeserver, token, mxc) {
+    const parts = parseMxc(mxc);
+    if (!parts)
+        return null;
+    try {
+        const url = `${homeserver}/_matrix/media/v3/download/${encodeURIComponent(parts.server)}/${encodeURIComponent(parts.mediaId)}`;
+        const r = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+        if (!r.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "matrix", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `mx_${Date.now()}_${parts.mediaId.slice(-12)}`);
+        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function matrixAdapter(homeserver, token, selfUserId) {
+    const base = homeserver.replace(/\/+$/, ""); // trim trailing slashes
+    const auth = { Authorization: `Bearer ${token}` };
+    let txnSeq = Date.now(); // monotonically increasing txn id base (survives clock-ish across a process run)
+    const nextTxn = () => `hara${++txnSeq}`;
+    return {
+        name: "matrix",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                const txn = nextTxn();
+                await fetch(`${base}/_matrix/client/v3/rooms/${encodeURIComponent(String(chatId))}/send/m.room.message/${txn}`, {
+                    method: "PUT",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ msgtype: "m.text", body: part }),
+                }).catch(() => { });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            const name = basename(filePath);
+            const mime = mimeFromExt(name);
+            try {
+                // 1) upload bytes → content_uri (mxc://)
+                const up = await fetch(`${base}/_matrix/media/v3/upload?filename=${encodeURIComponent(name)}`, {
+                    method: "POST",
+                    headers: { ...auth, "content-type": mime },
+                    body: readFileSync(filePath),
+                });
+                if (!up.ok)
+                    return;
+                const j = (await up.json());
+                const mxc = j?.content_uri;
+                if (!mxc)
+                    return;
+                // 2) send a referencing m.room.message — m.image for images, m.file otherwise
+                const msgtype = isImage(name, mime) ? "m.image" : "m.file";
+                const txn = nextTxn();
+                await fetch(`${base}/_matrix/client/v3/rooms/${encodeURIComponent(String(chatId))}/send/m.room.message/${txn}`, {
+                    method: "PUT",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ msgtype, body: name, filename: name, url: mxc, info: { mimetype: mime } }),
+                }).catch(() => { });
+            }
+            catch {
+                /* upload/send failed — surfaced upstream as "no file delivered" */
+            }
+        },
+        async start(onMessage, signal) {
+            // Prime the cursor: a since-less, timeout=0 sync skips backlog so we only see messages from now on.
+            let since = "";
+            try {
+                const r = await fetch(`${base}/_matrix/client/v3/sync?timeout=0`, { headers: auth, signal });
+                if (r.ok) {
+                    const j = (await r.json());
+                    if (typeof j.next_batch === "string")
+                        since = j.next_batch;
+                }
+            }
+            catch {
+                if (signal.aborted)
+                    return;
+            }
+            while (!signal.aborted) {
+                try {
+                    const q = `timeout=30000${since ? `&since=${encodeURIComponent(since)}` : ""}`;
+                    const res = await fetch(`${base}/_matrix/client/v3/sync?${q}`, { headers: auth, signal });
+                    if (!res.ok) {
+                        await sleep(2000);
+                        continue;
+                    }
+                    const j = (await res.json());
+                    if (typeof j.next_batch === "string")
+                        since = j.next_batch;
+                    const join = j.rooms?.join ?? {};
+                    for (const [roomId, room] of Object.entries(join)) {
+                        for (const event of room?.timeline?.events ?? []) {
+                            event.__roomId = roomId; // events carry no room id in /sync — inject it for the pure parser
+                            const parsed = parseMatrixEvent(event, selfUserId);
+                            if (!parsed)
+                                continue;
+                            if (parsed.imageMxc) {
+                                const path = await downloadMatrixMedia(base, token, parsed.imageMxc);
+                                if (path)
+                                    parsed.msg.images = [path];
+                            }
+                            await onMessage(parsed.msg).catch(() => { });
+                        }
+                    }
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000); // network blip → back off + retry
+                }
+            }
+        },
+    };
+}

package/dist/gateway/mattermost.js

@@ -0,0 +1,206 @@
+// Mattermost adapter for `hara gateway` — connects to a self-hosted (or cloud) Mattermost over the v4
+// WebSocket (Node's native global WebSocket, zero new dep on Node ≥ 22) for inbound events, and the v4 REST
+// API for outbound. Server from HARA_MATTERMOST_URL, token (bot or personal-access) from HARA_MATTERMOST_TOKEN;
+// allow users via HARA_GATEWAY_ALLOWED (Mattermost user ids). Same ChatAdapter shape as Telegram/Discord, so all
+// the cross-platform gateway plumbing (send_file, in-chat system context, stuck-guard, image attach/describe)
+// works unchanged. Auth is a WS "authentication_challenge" rather than an HTTP header.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const WSImpl = globalThis.WebSocket;
+const sleep = (ms, signal) => new Promise((r) => {
+    if (signal?.aborted)
+        return r();
+    const t = setTimeout(r, ms);
+    signal?.addEventListener?.("abort", () => { clearTimeout(t); r(); }, { once: true });
+});
+const isImage = (name, mime) => (mime?.startsWith("image/") ?? false) || /\.(png|jpe?g|gif|webp)$/i.test(name);
+/** Strip a trailing slash and any `/api/v4` suffix so we can rebuild paths cleanly (pure). */
+function normalizeBase(raw) {
+    return raw.trim().replace(/\/+$/, "").replace(/\/api\/v4$/i, "");
+}
+/** http(s):// base → wss(s):// websocket endpoint (pure). */
+function wsUrlFromBase(base) {
+    return normalizeBase(base).replace(/^http/i, "ws") + "/api/v4/websocket";
+}
+async function downloadMattermostFile(base, token, fileId, name) {
+    try {
+        const r = await fetch(`${normalizeBase(base)}/api/v4/files/${encodeURIComponent(fileId)}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!r.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "mattermost", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `mm_${Date.now()}_${basename(name) || "file.bin"}`);
+        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse a Mattermost "posted" event's post → InboundMsg + its image file ids (pure; download happens in
+ *  start()). The post is the already-parsed object (the event's data.post is a JSON string the caller decodes).
+ *  null = ignore (own post / system post / empty). */
+export function parseMattermostPost(post, selfUserId) {
+    if (!post?.channel_id || !post?.user_id)
+        return null;
+    if (post.user_id === selfUserId)
+        return null; // ignore our own posts
+    if (post.type)
+        return null; // system post (join/leave/etc.) — type "" is a normal user post
+    const fileIds = Array.isArray(post.file_ids) ? post.file_ids.map((f) => String(f)) : [];
+    // file_ids alone don't tell us the mime; the caller resolves per-file. Here we surface them all and let the
+    // download step filter to images. To stay pure we pass them through as candidate image ids.
+    const imageFileIds = fileIds;
+    const text = String(post.message ?? "");
+    if (!text && !imageFileIds.length)
+        return null;
+    return {
+        msg: {
+            chatId: String(post.channel_id),
+            userId: String(post.user_id),
+            userName: String(post.user_id), // enriched by start() from the event's sender_name when available
+            text: text || "[图片]",
+        },
+        imageFileIds,
+    };
+}
+export function mattermostAdapter(serverUrl, token) {
+    const base = normalizeBase(serverUrl);
+    const api = `${base}/api/v4`;
+    const auth = { Authorization: `Bearer ${token}` };
+    return {
+        name: "mattermost",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                await fetch(`${api}/posts`, {
+                    method: "POST",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ channel_id: chatId, message: part }),
+                }).catch(() => { });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // upload the file (multipart) → get a file_id, then create a post referencing it
+            const form = new FormData();
+            form.append("channel_id", String(chatId));
+            form.append("files", new Blob([readFileSync(filePath)]), basename(filePath));
+            const up = await fetch(`${api}/files`, { method: "POST", headers: auth, body: form }).catch(() => null);
+            if (!up || !up.ok)
+                return;
+            const j = (await up.json().catch(() => null));
+            const fileId = j?.file_infos?.[0]?.id;
+            if (!fileId)
+                return;
+            await fetch(`${api}/posts`, {
+                method: "POST",
+                headers: { ...auth, "content-type": "application/json" },
+                body: JSON.stringify({ channel_id: chatId, message: "", file_ids: [fileId] }),
+            }).catch(() => { });
+        },
+        async start(onMessage, signal) {
+            if (!WSImpl) {
+                console.error("hara gateway: Mattermost needs Node ≥ 22 (global WebSocket). Upgrade Node.");
+                return;
+            }
+            while (!signal.aborted) {
+                await connectOnce(base, token, onMessage, signal);
+                if (!signal.aborted)
+                    await sleep(3000, signal); // reconnect backoff
+            }
+        },
+    };
+}
+/** One WS connection: send authentication_challenge, then dispatch "posted" events. Resolves on close/abort;
+ *  the caller reconnects. v1 keeps it simple — fresh auth each time, no resume. The bot's own user id is
+ *  resolved via GET /users/me so we can drop our own echoes. */
+function connectOnce(base, token, onMessage, signal) {
+    return new Promise((resolve) => {
+        const ws = new WSImpl(wsUrlFromBase(base));
+        let seq = 1;
+        let selfId = "";
+        const stop = () => {
+            signal.removeEventListener("abort", stop);
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing */
+            }
+            resolve();
+        };
+        signal.addEventListener("abort", stop, { once: true });
+        ws.addEventListener("close", () => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        });
+        ws.addEventListener("error", () => { });
+        ws.addEventListener("open", async () => {
+            // resolve our own user id first so parseMattermostPost can ignore our echoes
+            try {
+                const me = await fetch(`${base}/api/v4/users/me`, { headers: { Authorization: `Bearer ${token}` } });
+                if (me.ok)
+                    selfId = String(((await me.json())?.id) ?? "");
+            }
+            catch {
+                /* best-effort; without it we just won't filter our own posts */
+            }
+            try {
+                ws.send(JSON.stringify({ seq: seq++, action: "authentication_challenge", data: { token } }));
+            }
+            catch {
+                /* socket gone */
+            }
+        });
+        ws.addEventListener("message", async (ev) => {
+            let p;
+            try {
+                p = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            if (p.event !== "posted")
+                return;
+            let post;
+            try {
+                post = JSON.parse(String(p.data?.post ?? ""));
+            }
+            catch {
+                return;
+            }
+            const parsed = parseMattermostPost(post, selfId);
+            if (!parsed)
+                return;
+            // enrich the display name from the event payload when the server includes it
+            const senderName = String(p.data?.sender_name ?? "").replace(/^@/, "");
+            if (senderName)
+                parsed.msg.userName = senderName;
+            for (const fid of parsed.imageFileIds) {
+                // resolve the file's mime/name, then download only images so the agent can SEE them
+                let name = "image";
+                let mime = "";
+                try {
+                    const info = await fetch(`${base}/api/v4/files/${encodeURIComponent(fid)}/info`, { headers: { Authorization: `Bearer ${token}` } });
+                    if (info.ok) {
+                        const ij = (await info.json());
+                        name = String(ij?.name ?? name);
+                        mime = String(ij?.mime_type ?? "");
+                    }
+                }
+                catch {
+                    /* fall back to extension sniff below */
+                }
+                if (!isImage(name, mime))
+                    continue;
+                const path = await downloadMattermostFile(base, token, fid, name);
+                if (path)
+                    (parsed.msg.images ??= []).push(path);
+            }
+            await onMessage(parsed.msg).catch(() => { });
+        });
+    });
+}

package/dist/gateway/serve.js

@@ -0,0 +1,282 @@
+// `hara gateway` — an opt-in long-running daemon that lets you drive your LOCAL hara from a chat app
+// (Telegram now; WeChat-iLink / Feishu via the same ChatAdapter next). Each inbound message → a fresh `hara`
+// subprocess (the cron pattern) on that chat's session → the reply is sent back. This is hara's first
+// persistent process; it is never required by the core CLI.
+import { spawn } from "node:child_process";
+import { telegramAdapter } from "./telegram.js";
+import { chatContext, chatCd, newChatSession, setChatSession, toggleVoice } from "./sessions.js";
+import { synthesize } from "./tts.js";
+import { selfArgv } from "../cron/runner.js";
+import { listSessions, resolveSessionId, loadSession } from "../session/store.js";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, rmSync } from "node:fs";
+/** Parse a leading slash-command from a chat message (pure). null if it isn't one. */
+export function parseCommand(text) {
+    const m = /^\/([a-z]+)\b\s*([\s\S]*)$/i.exec(text.trim());
+    return m ? { cmd: m[1].toLowerCase(), arg: m[2].trim() } : null;
+}
+/** Whether a user may drive the gateway. Empty allowlist = nobody (safe default — never wide-open). */
+export function isAllowed(userId, allowlist) {
+    return allowlist.size > 0 && allowlist.has(String(userId));
+}
+/** Strip hara's CLI chrome from captured `-p` output so a chat reply is just the answer: MCP status lines
+ *  (`mcp: …`) and the token-usage footer (`… · ↑N ↓N tok`). Colors are off when piped, so no ANSI to strip. */
+export function cleanReply(raw) {
+    return raw
+        .split("\n")
+        .filter((ln) => !/^\s*mcp: /.test(ln) && !/·\s*↑\d+\s*↓\d+\s*tok\s*$/.test(ln))
+        .join("\n")
+        .trim();
+}
+let outboxSeq = 0;
+/** Run hara headlessly on a chat's session. Returns its cleaned text reply plus any files the agent queued
+ *  via send_file. The gateway env (HARA_GATEWAY + a per-message outbox file) is what makes send_file and the
+ *  in-chat system context active in the subprocess; the daemon delivers the queued files after it exits. */
+function runHara(text, sessionId, cwd, platform, images) {
+    const outbox = join(tmpdir(), `hara-outbox-${process.pid}-${Date.now()}-${outboxSeq++}.txt`);
+    return new Promise((res) => {
+        const self = selfArgv();
+        const child = spawn(self[0], [...self.slice(1), "-p", text, "--approval", "full-auto", "--resume", sessionId], {
+            cwd,
+            env: {
+                ...process.env,
+                HARA_GATEWAY: platform,
+                HARA_GATEWAY_OUTBOX: outbox,
+                ...(images?.length ? { HARA_GATEWAY_IMAGES: images.join("\n") } : {}),
+            },
+        });
+        let out = "";
+        const cap = (d) => {
+            out = (out + d.toString()).slice(-12000);
+        };
+        child.stdout.on("data", cap);
+        child.stderr.on("data", cap);
+        const finish = (reply) => {
+            let files = [];
+            try {
+                if (existsSync(outbox)) {
+                    files = readFileSync(outbox, "utf8").split("\n").map((s) => s.trim()).filter(Boolean);
+                    rmSync(outbox, { force: true });
+                }
+            }
+            catch {
+                /* outbox is best-effort; a missing/unreadable file just means nothing to send */
+            }
+            res({ reply, files });
+        };
+        child.on("error", (e) => finish(`(error: ${e.message})`));
+        child.on("close", () => finish(cleanReply(out) || "(no output)"));
+    });
+}
+/** Re-exported so `hara gateway --platform weixin --login` can run the QR flow. */
+export { weixinLogin } from "./weixin.js";
+async function buildAdapter(platform) {
+    if (platform === "weixin") {
+        const { loadWeixinCreds, weixinAdapter } = await import("./weixin.js");
+        const creds = loadWeixinCreds();
+        if (!creds) {
+            console.error("hara gateway: no WeChat login found. Run `hara gateway --platform weixin --login` first.");
+            return null;
+        }
+        // The iLink user_id is whoever scanned the QR — the bot owner. Auto-allow them so there's no wxid dance.
+        return { adapter: weixinAdapter(creds), ownerId: creds.user_id || undefined };
+    }
+    if (platform === "discord") {
+        const token = process.env.HARA_DISCORD_TOKEN;
+        if (!token) {
+            console.error("hara gateway: set HARA_DISCORD_TOKEN (Discord bot token) and HARA_GATEWAY_ALLOWED=<your discord user id>. Enable the Message Content Intent on the bot.");
+            return null;
+        }
+        const { discordAdapter } = await import("./discord.js");
+        return { adapter: discordAdapter(token) };
+    }
+    if (platform === "feishu" || platform === "lark") {
+        const appId = process.env.HARA_FEISHU_APP_ID;
+        const appSecret = process.env.HARA_FEISHU_APP_SECRET;
+        if (!appId || !appSecret) {
+            console.error("hara gateway: set HARA_FEISHU_APP_ID + HARA_FEISHU_APP_SECRET (Feishu app console) and HARA_GATEWAY_ALLOWED=<your open_id>. (HARA_FEISHU_DOMAIN=lark for larksuite.com.)");
+            return null;
+        }
+        const { feishuAdapter } = await import("./feishu.js");
+        return { adapter: feishuAdapter(appId, appSecret) };
+    }
+    if (platform === "slack") {
+        const appToken = process.env.HARA_SLACK_APP_TOKEN;
+        const botToken = process.env.HARA_SLACK_BOT_TOKEN;
+        if (!appToken || !botToken) {
+            console.error("hara gateway: set HARA_SLACK_APP_TOKEN (xapp-, Socket Mode app-level token w/ connections:write) + HARA_SLACK_BOT_TOKEN (xoxb-, bot token w/ chat:write,files:write,files:read,*:history) and HARA_GATEWAY_ALLOWED=<your slack user id>.");
+            return null;
+        }
+        const { slackAdapter } = await import("./slack.js");
+        return { adapter: slackAdapter(appToken, botToken) };
+    }
+    if (platform === "mattermost") {
+        const url = process.env.HARA_MATTERMOST_URL;
+        const token = process.env.HARA_MATTERMOST_TOKEN;
+        if (!url || !token) {
+            console.error("hara gateway: set HARA_MATTERMOST_URL (e.g. https://mm.example.com) + HARA_MATTERMOST_TOKEN (bot or personal-access token) and HARA_GATEWAY_ALLOWED=<your mattermost user id>.");
+            return null;
+        }
+        const { mattermostAdapter } = await import("./mattermost.js");
+        return { adapter: mattermostAdapter(url, token) };
+    }
+    if (platform === "matrix") {
+        const homeserver = process.env.HARA_MATRIX_HOMESERVER;
+        const token = process.env.HARA_MATRIX_TOKEN;
+        const userId = process.env.HARA_MATRIX_USER_ID;
+        if (!homeserver || !token || !userId) {
+            console.error("hara gateway: set HARA_MATRIX_HOMESERVER (e.g. https://matrix.org), HARA_MATRIX_TOKEN (access token), HARA_MATRIX_USER_ID (@bot:server) and HARA_GATEWAY_ALLOWED=<@you:server>. Unencrypted rooms only (no E2EE in v1).");
+            return null;
+        }
+        const { matrixAdapter } = await import("./matrix.js");
+        return { adapter: matrixAdapter(homeserver, token, userId), ownerId: userId };
+    }
+    if (platform === "dingtalk" || platform === "ding") {
+        const clientId = process.env.HARA_DINGTALK_CLIENT_ID;
+        const clientSecret = process.env.HARA_DINGTALK_CLIENT_SECRET;
+        if (!clientId || !clientSecret) {
+            console.error("hara gateway: set HARA_DINGTALK_CLIENT_ID + HARA_DINGTALK_CLIENT_SECRET (钉钉开放平台 app AppKey/AppSecret, Stream mode enabled on the bot) and HARA_GATEWAY_ALLOWED=<your senderStaffId>.");
+            return null;
+        }
+        const { dingtalkAdapter } = await import("./dingtalk.js");
+        return { adapter: dingtalkAdapter(clientId, clientSecret) };
+    }
+    const token = process.env.HARA_TELEGRAM_TOKEN;
+    if (!token) {
+        console.error("hara gateway: set HARA_TELEGRAM_TOKEN (from @BotFather) and HARA_GATEWAY_ALLOWED=<your telegram user id>.");
+        return null;
+    }
+    return { adapter: telegramAdapter(token) };
+}
+/** Allowlist = the env ids ∪ the bot owner (on WeChat, whoever scanned the QR is always allowed). */
+export function resolveAllowlist(envValue, ownerId) {
+    const set = new Set((envValue ?? "").split(",").map((s) => s.trim()).filter(Boolean));
+    if (ownerId)
+        set.add(ownerId);
+    return set;
+}
+/** The gateway's default workspace when no --cwd is given: a dedicated safe home under ~/.hara (like Hermes'
+ *  ~/.hermes), NOT the launch dir — so a full-auto chat bot never lands on a real repo by accident. */
+export function defaultWorkspace() {
+    const dir = join(homedir(), ".hara", "workspace");
+    mkdirSync(dir, { recursive: true });
+    const agents = join(dir, "AGENTS.md");
+    if (!existsSync(agents)) {
+        writeFileSync(agents, "# hara chat workspace\n\nDefault working directory for `hara gateway` (Telegram/WeChat). Each message runs here with `--approval full-auto`. A safe scratch — pass `--cwd <dir>` to point the gateway at a real project instead.\n");
+    }
+    return dir;
+}
+export async function runGateway(opts) {
+    const platform = opts.platform || "telegram";
+    const cwd = opts.cwd ?? defaultWorkspace(); // dir-free default: hara's own ~/.hara/workspace, like Hermes' ~/.hermes
+    const built = await buildAdapter(platform);
+    if (!built)
+        process.exit(1);
+    const { adapter, ownerId } = built;
+    const allowlist = resolveAllowlist(process.env.HARA_GATEWAY_ALLOWED, ownerId);
+    if (allowlist.size === 0) {
+        const hint = platform === "weixin" ? "your WeChat id" : "your Telegram user id (DM @userinfobot)";
+        console.error(`hara gateway: ⚠ HARA_GATEWAY_ALLOWED is empty — nobody is allowed. Set it to ${hint}.`);
+    }
+    else if (ownerId) {
+        console.error(`hara gateway: bot owner auto-allowed (${ownerId}).`);
+    }
+    const ac = new AbortController();
+    process.on("SIGINT", () => ac.abort());
+    process.on("SIGTERM", () => ac.abort());
+    console.error(`hara gateway: ${adapter.name} up · cwd=${cwd} · ${allowlist.size} allowed user(s) · Ctrl-C to stop`);
+    await adapter.start(async (m) => {
+        if (!isAllowed(m.userId, allowlist)) {
+            console.error(`hara gateway: ✗ message from ${m.userId} — not in allowlist. Add it to HARA_GATEWAY_ALLOWED to authorize.`);
+            await adapter.send(m.chatId, "⛔ not authorized.");
+            return;
+        }
+        const ctx = chatContext(adapter.name, m.chatId, cwd); // this chat's current { cwd, sessionId }
+        const cmd = parseCommand(m.text);
+        if (cmd) {
+            if (cmd.cmd === "help")
+                return adapter.send(m.chatId, "commands:\n/pwd · /cd <dir> — project\n/sessions · /new · /resume <id> — threads\n/voice · /say <text> — speech · /send <path> — send a file\n/help\nanything else = run hara here");
+            if (cmd.cmd === "pwd")
+                return adapter.send(m.chatId, `📂 ${ctx.cwd}\n🧵 ${ctx.sessionId.slice(-18)}`);
+            if (cmd.cmd === "cd" || cmd.cmd === "project") {
+                if (!cmd.arg)
+                    return adapter.send(m.chatId, `📂 ${ctx.cwd}\nusage: /cd <dir> (absolute, ~, or relative to here)`);
+                const target = resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir()));
+                if (!existsSync(target) || !statSync(target).isDirectory())
+                    return adapter.send(m.chatId, `✗ not a directory: ${target}`);
+                const sid = chatCd(adapter.name, m.chatId, target);
+                return adapter.send(m.chatId, `📂 now in ${target}\n🧵 ${sid.slice(-18)} · /sessions lists this dir's threads`);
+            }
+            if (cmd.cmd === "new")
+                return adapter.send(m.chatId, `✨ new thread: ${newChatSession(adapter.name, m.chatId, cwd).slice(-18)}`);
+            if (cmd.cmd === "sessions") {
+                const list = listSessions(ctx.cwd).slice(0, 10).map((x) => `${x.id.slice(-18)}  ${x.title || "(untitled)"}`).join("\n");
+                return adapter.send(m.chatId, `📂 ${ctx.cwd}\n${list || "(no threads in this dir yet)"}`);
+            }
+            if (cmd.cmd === "resume") {
+                const id = resolveSessionId(cmd.arg);
+                if (!id)
+                    return adapter.send(m.chatId, `no session '${cmd.arg}'`);
+                const target = loadSession(id)?.meta.cwd || ctx.cwd; // follow the session's own dir so it runs in the right place
+                setChatSession(adapter.name, m.chatId, id, target);
+                return adapter.send(m.chatId, `↩ resumed ${id.slice(-18)}\n📂 ${target}`);
+            }
+            if (cmd.cmd === "voice") {
+                if (!adapter.sendFile)
+                    return adapter.send(m.chatId, "this platform can't send voice yet.");
+                const on = toggleVoice(adapter.name, m.chatId);
+                return adapter.send(m.chatId, on ? "🔊 voice replies ON — I'll speak each reply too." : "🔇 voice replies OFF.");
+            }
+            if (cmd.cmd === "say") {
+                if (!adapter.sendFile)
+                    return adapter.send(m.chatId, "this platform can't send voice yet.");
+                if (!cmd.arg)
+                    return adapter.send(m.chatId, "usage: /say <text to speak>");
+                const audio = await synthesize(cmd.arg);
+                if (!audio)
+                    return adapter.send(m.chatId, "✗ TTS failed (check HARA_TTS_* config).");
+                await adapter.sendFile(m.chatId, audio);
+                rmSync(audio, { force: true });
+                return;
+            }
+            if (cmd.cmd === "send") {
+                if (!adapter.sendFile)
+                    return adapter.send(m.chatId, "this platform can't send files yet.");
+                const p = cmd.arg ? resolve(ctx.cwd, cmd.arg.replace(/^~(?=\/|$)/, homedir())) : "";
+                if (!p || !existsSync(p) || !statSync(p).isFile())
+                    return adapter.send(m.chatId, `✗ not a file: ${p || "(none)"}\nusage: /send <path> (abs, ~, or relative to current dir)`);
+                await adapter.sendFile(m.chatId, p);
+                return;
+            }
+            // any other slash word → treat as a normal task
+        }
+        await adapter.send(m.chatId, "⟳ working…");
+        const { reply, files } = await runHara(m.text, ctx.sessionId, ctx.cwd, adapter.name, m.images);
+        const hasReply = reply && reply !== "(no output)";
+        if (hasReply)
+            await adapter.send(m.chatId, reply);
+        else if (files.length)
+            await adapter.send(m.chatId, "📎");
+        // Deliver any files the agent queued via send_file (images inline, others as attachments).
+        for (const f of files) {
+            if (!adapter.sendFile) {
+                await adapter.send(m.chatId, "(this platform can't send files yet)");
+                break;
+            }
+            try {
+                await adapter.sendFile(m.chatId, f);
+            }
+            catch (e) {
+                await adapter.send(m.chatId, `✗ couldn't send ${f}: ${e.message}`);
+            }
+        }
+        if (hasReply && ctx.voice && adapter.sendFile) {
+            const audio = await synthesize(reply);
+            if (audio) {
+                await adapter.sendFile(m.chatId, audio);
+                rmSync(audio, { force: true });
+            }
+        }
+    }, ac.signal);
+}