@nanhara/hara 0.70.0 → 0.89.0

package/dist/gateway/slack.js

@@ -0,0 +1,190 @@
+// Slack adapter for `hara gateway` — uses Socket Mode so the local daemon connects OUT over Node's native
+// global WebSocket (zero new dep on Node ≥ 22): apps.connections.open (app-level token, xapp-) hands back a
+// wss:// URL → we connect, ACK every envelope, and turn message events into InboundMsg. Outbound is the Web
+// API (bot token, xoxb-). Same ChatAdapter shape as Discord/Telegram, so all cross-platform gateway plumbing
+// (send_file, in-chat system context, stuck-guard, image attach/describe) works unchanged. Two tokens are
+// required because Socket Mode (xapp-) and the Web API (xoxb-) are separate auth scopes.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const WEB = "https://slack.com/api";
+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);
+/** Call a Slack Web API method with a token (form-encoded, the most widely-accepted shape). Returns the parsed
+ *  JSON; callers check `.ok`. Never throws — a failed call resolves to `{ ok: false }`. */
+async function slackApi(method, token, body) {
+    try {
+        const r = await fetch(`${WEB}/${method}`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "content-type": "application/json; charset=utf-8" },
+            body: JSON.stringify(body),
+        });
+        return await r.json();
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Slack file url_private is gated — it needs the BOT token as a Bearer header (a plain GET returns the login
+ *  page HTML, not the bytes). Download into ~/.hara/slack/media so the agent can SEE it. */
+async function downloadSlackFile(url, name, botToken) {
+    try {
+        const r = await fetch(url, { headers: { Authorization: `Bearer ${botToken}` } });
+        if (!r.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "slack", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `sl_${Date.now()}_${basename(name) || "file.bin"}`);
+        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse a Slack Events API `event` (the inner `payload.event`) → InboundMsg + its image file refs (pure;
+ *  download happens in start()). null = ignore (not a user message / our own / an edit/delete subtype / empty).
+ *  Mirrors discord.ts's parseDiscordMessage so it's unit-testable without the network. */
+export function parseSlackEvent(event, selfId) {
+    if (event?.type !== "message")
+        return null;
+    if (event.bot_id || (selfId && event.user === selfId))
+        return null; // ignore bots + our own messages
+    // message_changed / message_deleted / channel_join … carry no fresh user text we want to act on
+    if (event.subtype && event.subtype !== "file_share")
+        return null;
+    if (!event.channel || !event.user)
+        return null;
+    const files = Array.isArray(event.files) ? event.files : [];
+    const imageUrls = files
+        .filter((f) => isImage(String(f?.name ?? ""), f?.mimetype))
+        .map((f) => ({ url: String(f?.url_private_download || f?.url_private || ""), name: String(f?.name ?? "image") }))
+        .filter((f) => f.url);
+    const text = String(event.text ?? "");
+    if (!text && !imageUrls.length)
+        return null;
+    return {
+        msg: {
+            chatId: String(event.channel),
+            userId: String(event.user),
+            userName: String(event.user), // Slack events carry only the id; users.info would resolve a name (skipped for zero extra calls)
+            text: text || "[图片]",
+        },
+        imageUrls,
+    };
+}
+export function slackAdapter(appToken, botToken) {
+    return {
+        name: "slack",
+        async send(chatId, text) {
+            // Slack hard-caps a message at 40k chars; 3500 keeps us clear of mrkdwn expansion + block limits.
+            for (const part of chunkText(text || "(empty)", 3500)) {
+                await slackApi("chat.postMessage", botToken, { channel: chatId, text: part });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // 3-step external-upload flow (getUploadURLExternal → PUT bytes → completeUploadExternal): the current,
+            // non-deprecated path that works with just files:write (the old files.upload can 404/missing_scope).
+            try {
+                const bytes = readFileSync(filePath);
+                const name = basename(filePath);
+                const url = await slackApi("files.getUploadURLExternal", botToken, { filename: name, length: bytes.length });
+                if (!url?.ok || !url.upload_url || !url.file_id)
+                    return;
+                const up = await fetch(url.upload_url, { method: "POST", body: new Blob([bytes]) }); // presigned URL: no auth header
+                if (!up.ok)
+                    return;
+                await slackApi("files.completeUploadExternal", botToken, { files: [{ id: url.file_id, title: name }], channel_id: String(chatId) });
+            }
+            catch {
+                /* upload/send failed — surfaced upstream as "no file delivered" */
+            }
+        },
+        async start(onMessage, signal) {
+            if (!WSImpl) {
+                console.error("hara gateway: Slack needs Node ≥ 22 (global WebSocket). Upgrade Node.");
+                return;
+            }
+            // Resolve our own bot user id once so parseSlackEvent can drop our own messages (echo-loop guard).
+            const auth = await slackApi("auth.test", botToken, {});
+            const selfId = String(auth?.user_id ?? "");
+            while (!signal.aborted) {
+                const wss = await openSocketUrl(appToken);
+                if (wss)
+                    await connectOnce(wss, botToken, selfId, onMessage, signal);
+                if (!signal.aborted)
+                    await sleep(3000, signal); // reconnect backoff (and re-open: each URL is single-use)
+            }
+        },
+    };
+}
+/** Ask Slack for a fresh single-use Socket Mode wss:// URL (app-level token). null on failure → caller backs off. */
+async function openSocketUrl(appToken) {
+    const j = await slackApi("apps.connections.open", appToken, {});
+    return j?.ok && typeof j.url === "string" ? j.url : null;
+}
+/** One Socket Mode connection: receive envelopes, ACK each by echoing its envelope_id, and dispatch message
+ *  events. Resolves on close/disconnect/abort; the caller re-opens a new URL and reconnects. v1 keeps it simple —
+ *  no buffered-payload backpressure (the daemon spawns one hara per message anyway). */
+function connectOnce(url, botToken, selfId, onMessage, signal) {
+    return new Promise((resolve) => {
+        const ws = new WSImpl(url);
+        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("message", async (ev) => {
+            let p;
+            try {
+                p = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            // ACK first — Slack redelivers (and eventually disconnects the socket) for any envelope we don't ack in ~3s.
+            if (p.envelope_id) {
+                try {
+                    ws.send(JSON.stringify({ envelope_id: p.envelope_id }));
+                }
+                catch {
+                    /* socket gone */
+                }
+            }
+            if (p.type === "disconnect") {
+                stop(); // server is rotating us off (refresh / too_many_connections) → drop and let the caller reconnect
+                return;
+            }
+            if (p.type === "events_api") {
+                const parsed = parseSlackEvent(p.payload?.event, selfId);
+                if (parsed) {
+                    for (const im of parsed.imageUrls) {
+                        const path = await downloadSlackFile(im.url, im.name, botToken);
+                        if (path)
+                            (parsed.msg.images ??= []).push(path);
+                    }
+                    await onMessage(parsed.msg).catch(() => { });
+                }
+            }
+            // type "hello" (connection established) and slash_commands/interactive envelopes: acked above, nothing else to do.
+        });
+    });
+}

package/dist/gateway/telegram.js

@@ -0,0 +1,115 @@
+// Telegram adapter for `hara gateway` — long-poll getUpdates + sendMessage over the Bot API (built-in
+// fetch, zero new dep). Token from HARA_TELEGRAM_TOKEN. The generic `ChatAdapter` shape is what WeChat(iLink)
+// / Feishu plug into next.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+const API = "https://api.telegram.org";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Extract an InboundMsg from a Telegram getUpdates result item (pure). Accepts text and photo messages
+ *  (photo → caption or a "[图片]" marker; the image itself is downloaded in start()). null otherwise. */
+export function parseTelegramUpdate(u) {
+    const m = u?.message;
+    if (!m || !m.chat?.id)
+        return null;
+    const text = typeof m.text === "string" ? m.text : typeof m.caption === "string" ? m.caption : "";
+    const hasPhoto = Array.isArray(m.photo) && m.photo.length > 0;
+    if (!text && !hasPhoto)
+        return null; // not text or a photo (sticker/location/etc.)
+    return {
+        chatId: m.chat.id,
+        userId: m.from?.id ?? 0,
+        userName: m.from?.username || m.from?.first_name || String(m.from?.id ?? ""),
+        text: text || "[图片]",
+    };
+}
+/** The largest photo's file_id (Telegram sends `photo` as an ascending size array) (pure). null if none. */
+export function photoFileId(u) {
+    const photo = u?.message?.photo;
+    return Array.isArray(photo) && photo.length ? (photo[photo.length - 1]?.file_id ?? null) : null;
+}
+/** Download a Telegram file by file_id → a local path under ~/.hara/telegram/media (getFile then the file CDN). */
+async function downloadTelegramFile(base, token, fileId) {
+    try {
+        const r = await fetch(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`);
+        const j = (await r.json());
+        const fp = j?.result?.file_path;
+        if (!fp)
+            return null;
+        const dl = await fetch(`${API}/file/bot${token}/${fp}`);
+        if (!dl.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "telegram", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `tg_${Date.now()}_${basename(fp)}`);
+        writeFileSync(path, Buffer.from(await dl.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** Split text into chunks ≤ max (Telegram caps a message at 4096 chars) (pure). */
+export function chunkText(text, max = 4000) {
+    if (text.length <= max)
+        return [text];
+    const out = [];
+    for (let i = 0; i < text.length; i += max)
+        out.push(text.slice(i, i + max));
+    return out;
+}
+export function telegramAdapter(token) {
+    const base = `${API}/bot${token}`;
+    return {
+        name: "telegram",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)")) {
+                await fetch(`${base}/sendMessage`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ chat_id: chatId, text: part }),
+                }).catch(() => { });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // images → sendPhoto (inline preview); everything else → sendDocument (keeps the filename)
+            const name = basename(filePath);
+            const isImg = /\.(png|jpe?g|gif|webp)$/i.test(name);
+            const form = new FormData();
+            form.append("chat_id", String(chatId));
+            form.append(isImg ? "photo" : "document", new Blob([readFileSync(filePath)]), name);
+            await fetch(`${base}/${isImg ? "sendPhoto" : "sendDocument"}`, { method: "POST", body: form }).catch(() => { });
+        },
+        async start(onMessage, signal) {
+            let offset = 0;
+            while (!signal.aborted) {
+                try {
+                    const res = await fetch(`${base}/getUpdates?timeout=30&offset=${offset}`, { signal });
+                    if (!res.ok) {
+                        await sleep(2000);
+                        continue;
+                    }
+                    const j = (await res.json());
+                    for (const u of j.result ?? []) {
+                        offset = Math.max(offset, (u.update_id ?? 0) + 1);
+                        const msg = parseTelegramUpdate(u);
+                        if (!msg)
+                            continue;
+                        const fid = photoFileId(u); // a photo message → download it so the agent can SEE it
+                        if (fid) {
+                            const path = await downloadTelegramFile(base, token, fid);
+                            if (path)
+                                msg.images = [path];
+                        }
+                        await onMessage(msg).catch(() => { });
+                    }
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000); // network blip → back off + retry
+                }
+            }
+        },
+    };
+}

package/dist/gateway/tts.js

@@ -0,0 +1,100 @@
+// Pluggable text-to-speech for the chat gateway's voice replies. Mirrors the video project's provider design:
+// a config-driven registry, nothing vendor-hardcoded, both API and local. Selected by env:
+//   HARA_TTS_PROVIDER = say | openai | cmd   (default: say)
+//   HARA_TTS_VOICE / HARA_TTS_MODEL / HARA_TTS_BASE_URL / HARA_TTS_API_KEY / HARA_TTS_CMD
+// Providers:
+//   say    — local macOS `say` (zero-config default; fast, ~0.5s; Chinese voices e.g. Tingting) → m4a
+//   openai — any OpenAI-compatible /audio/speech endpoint (point BASE_URL at Aliyun DashScope or a local
+//            TTS server); reuses the existing `openai` dep, no new dependency
+//   cmd    — a configurable local command (point it at VoxCPM or any local TTS); the text is piped on stdin,
+//            `{out}` in the command is replaced with the output path
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+/** Read TTS settings from the environment (fully configurable — nothing hardcoded). */
+export function ttsConfigFromEnv(env = process.env) {
+    return {
+        provider: (env.HARA_TTS_PROVIDER || "say").trim(),
+        voice: (env.HARA_TTS_VOICE || "").trim(),
+        model: (env.HARA_TTS_MODEL || "").trim(),
+        baseURL: (env.HARA_TTS_BASE_URL || "").trim(),
+        apiKey: (env.HARA_TTS_API_KEY || "").trim(),
+        cmd: (env.HARA_TTS_CMD || "").trim(),
+    };
+}
+/** Normalize a reply for speech: collapse whitespace, drop code fences, cap length (long audio is unwanted). */
+export function ttsCleanText(text, max = 1200) {
+    return text
+        .replace(/```[\s\S]*?```/g, " (code omitted) ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, max);
+}
+function run(cmd, args, stdin) {
+    return new Promise((resolve) => {
+        const c = spawn(cmd, args, { stdio: [stdin != null ? "pipe" : "ignore", "ignore", "ignore"] });
+        c.on("error", () => resolve(false));
+        c.on("close", (code) => resolve(code === 0));
+        if (stdin != null)
+            c.stdin?.end(stdin);
+    });
+}
+// local: macOS `say` → m4a (AAC). Zero config; HARA_TTS_VOICE picks the voice (default Tingting / zh).
+async function sayTts(text, out, cfg) {
+    return run("say", ["-v", cfg.voice || "Tingting", "-o", out, "--file-format", "m4af", "--data-format", "aac", text]);
+}
+// API: OpenAI-compatible /audio/speech. Works against OpenAI, Aliyun DashScope (compatible-mode), or a local
+// server exposing the same shape — set HARA_TTS_BASE_URL + HARA_TTS_API_KEY + HARA_TTS_MODEL + HARA_TTS_VOICE.
+async function openaiTts(text, out, cfg) {
+    if (!cfg.apiKey && !cfg.baseURL)
+        return false; // not configured → unavailable
+    const { default: OpenAI } = (await import("openai"));
+    const client = new OpenAI({ baseURL: cfg.baseURL || undefined, apiKey: cfg.apiKey || "x" });
+    const res = await client.audio.speech.create({ model: cfg.model || "tts-1", voice: cfg.voice || "alloy", input: text });
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!buf.length)
+        return false;
+    writeFileSync(out, buf);
+    return true;
+}
+// local: a configurable command (e.g. VoxCPM). `{out}` → output path; the text is piped on stdin.
+async function cmdTts(text, out, cfg) {
+    if (!cfg.cmd)
+        return false;
+    return run("sh", ["-c", cfg.cmd.replace(/\{out\}/g, out)], text);
+}
+const PROVIDERS = {
+    say: sayTts,
+    openai: openaiTts,
+    cmd: cmdTts,
+};
+const EXT = { say: "m4a", openai: "mp3", cmd: "wav" };
+/** Synthesize `text` to a temp audio file; returns its path, or null on failure. Falls back to local `say`
+ *  if a configured provider fails (so a misconfigured API never silently kills voice replies). */
+export async function synthesize(text, cfg = ttsConfigFromEnv()) {
+    const clean = ttsCleanText(text);
+    if (!clean)
+        return null;
+    const provider = PROVIDERS[cfg.provider] ? cfg.provider : "say";
+    const out = join(tmpdir(), `hara-tts-${randomUUID().slice(0, 8)}.${EXT[provider] || "wav"}`);
+    try {
+        if (await PROVIDERS[provider](clean, out, cfg))
+            return out;
+    }
+    catch (e) {
+        console.error(`tts(${provider}): ${e?.message ?? e}`);
+    }
+    if (provider !== "say") {
+        try {
+            const o2 = join(tmpdir(), `hara-tts-${randomUUID().slice(0, 8)}.m4a`);
+            if (await sayTts(clean, o2, cfg))
+                return o2; // graceful fallback to local
+        }
+        catch {
+            /* give up */
+        }
+    }
+    return null;
+}