@nanhara/hara 0.70.0 → 0.95.2

package/dist/gateway/serve.js

@@ -0,0 +1,339 @@
+// `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 { pickPaneForReply, capturePane, injectTmux, outputDelta } from "./tmux-routes.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) };
+    }
+    if (platform === "wecom" || platform === "wework") {
+        const botId = process.env.HARA_WECOM_BOT_ID;
+        const secret = process.env.HARA_WECOM_SECRET;
+        if (!botId || !secret) {
+            console.error("hara gateway: set HARA_WECOM_BOT_ID + HARA_WECOM_SECRET (企业微信 admin console → AI Bot credentials) and HARA_GATEWAY_ALLOWED=<your wecom userid>. (HARA_WECOM_WS_URL overrides the gateway URL.)");
+            return null;
+        }
+        const { wecomAdapter } = await import("./wecom.js");
+        return { adapter: wecomAdapter(botId, secret, process.env.HARA_WECOM_WS_URL) };
+    }
+    if (platform === "signal") {
+        const rpcUrl = process.env.HARA_SIGNAL_RPC_URL;
+        const number = process.env.HARA_SIGNAL_NUMBER;
+        if (!rpcUrl || !number) {
+            console.error("hara gateway: set HARA_SIGNAL_RPC_URL (e.g. http://localhost:8080) + HARA_SIGNAL_NUMBER (the bot's registered phone, E.164) and HARA_GATEWAY_ALLOWED=<your signal number/uuid>. Requires a local signal-cli daemon: `signal-cli -a <number> daemon --http localhost:8080`.");
+            return null;
+        }
+        const { signalAdapter } = await import("./signal.js");
+        return { adapter: signalAdapter(rpcUrl, number), ownerId: number };
+    }
+    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;
+        }
+        // If a tmux session opted in (via `hara remote ask/bind`), this reply is its input → inject it into that
+        // pane, let it react, and reply with the session's NEW output (on-inbound relay — quiet + iLink-friendly:
+        // one reply per message, no continuous push). Owner-gated by the allowlist check above.
+        if (!parseCommand(m.text)) {
+            const pane = pickPaneForReply();
+            if (pane) {
+                console.error(`hara gateway: routed reply → tmux pane ${pane}`);
+                const before = capturePane(pane) ?? "";
+                injectTmux(pane, m.text);
+                // wait for the session's output to SETTLE (poll every 800ms; stable for ~1.6s → done; cap ~10s) so a
+                // slow response isn't missed and we don't capture mid-stream.
+                let after = "";
+                let stable = 0;
+                for (let i = 0; i < 12; i++) {
+                    await new Promise((r) => setTimeout(r, 800));
+                    const cur = capturePane(pane) ?? "";
+                    if (cur === after) {
+                        if (++stable >= 2)
+                            break;
+                    }
+                    else {
+                        stable = 0;
+                        after = cur;
+                    }
+                }
+                const delta = outputDelta(before, after).trim();
+                const body = delta ? (delta.length > 1500 ? "…\n" + delta.slice(-1500) : delta) : "(已注入,暂无新输出 — 发 ? 再看)";
+                await adapter.send(m.chatId, `🖥 ${pane}\n${body}`);
+                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/detach — stop injecting replies into bound tmux panes\n/help\nanything else = run hara here");
+            if (cmd.cmd === "detach") {
+                const { unbindBinds } = await import("./tmux-routes.js");
+                const n = unbindBinds();
+                return adapter.send(m.chatId, n ? `🔓 detached ${n} bound tmux pane(s) — replies go to hara again.` : "(no tmux panes were bound)");
+            }
+            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);
+}

package/dist/gateway/sessions.js

@@ -0,0 +1,89 @@
+// Chat → working-dir + session mapping, so each chat is a continuous, resumable thread that can ROAM across
+// projects. Persisted at ~/.hara/gateway/chats.json. A chat has a current cwd (switchable via /cd) and a
+// session id scoped to that (chat, cwd) pair — so switching projects switches threads, and switching back
+// resumes the right one. /sessions then lists the current dir's threads (codex-style), while the chat itself
+// stays a single conversation front-end (hermes-style). The same model backs a future desktop app.
+// Sessions are stored by id in ~/.hara/sessions, so these are real sessions resumable via `hara -p … --resume`.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+const dir = () => join(homedir(), ".hara", "gateway");
+const file = () => join(dir(), "chats.json");
+const mapKey = (platform, chatId) => `${platform}:${chatId}`;
+function load() {
+    try {
+        return existsSync(file()) ? JSON.parse(readFileSync(file(), "utf8")) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function save(m) {
+    mkdirSync(dir(), { recursive: true });
+    writeFileSync(file(), JSON.stringify(m, null, 2));
+}
+/** A stable, short, dir-specific suffix so each (chat, cwd) pair gets its own session thread. */
+export function cwdTag(cwd) {
+    return createHash("sha256").update(cwd).digest("hex").slice(0, 6);
+}
+/** Derived session id for a (chat, cwd, fork): `<platform>-<chatId>-<cwdTag>[-fork]`. */
+function deriveId(platform, chatId, cwd, fork) {
+    return `${platform}-${chatId}-${cwdTag(cwd)}${fork ? `-${fork}` : ""}`;
+}
+/** Get (or initialize) the chat's context: current working dir + the session id it drives. `defaultCwd` (the
+ *  gateway's launch dir) is used only on first contact; a pre-cwd entry is migrated in place (keeps its id). */
+export function chatContext(platform, chatId, defaultCwd) {
+    const m = load();
+    const k = mapKey(platform, chatId);
+    const e = m[k];
+    if (!e) {
+        const fresh = { cwd: defaultCwd, sessionId: deriveId(platform, chatId, defaultCwd, 0), fork: 0 };
+        m[k] = fresh;
+        save(m);
+        return { cwd: fresh.cwd, sessionId: fresh.sessionId, voice: false };
+    }
+    if (!e.cwd) {
+        e.cwd = defaultCwd; // migrate an old (pre-cwd) entry, preserving its existing sessionId
+        save(m);
+    }
+    return { cwd: e.cwd, sessionId: e.sessionId, voice: !!e.voice };
+}
+/** `/voice` — toggle whether this chat's replies are spoken (TTS audio); returns the new state. */
+export function toggleVoice(platform, chatId) {
+    const m = load();
+    const k = mapKey(platform, chatId);
+    const e = m[k];
+    if (!e)
+        return false; // chatContext always runs first, so an entry exists; defensive no-op otherwise
+    e.voice = !e.voice;
+    save(m);
+    return !!e.voice;
+}
+/** `/cd <dir>` — switch the chat to a working dir; the session follows (its own per-project thread). */
+export function chatCd(platform, chatId, cwd) {
+    const m = load();
+    const sessionId = deriveId(platform, chatId, cwd, 0);
+    m[mapKey(platform, chatId)] = { cwd, sessionId, fork: 0 };
+    save(m);
+    return sessionId;
+}
+/** `/new` — fork a fresh thread for the chat's CURRENT dir (the old one is preserved). */
+export function newChatSession(platform, chatId, defaultCwd) {
+    const m = load();
+    const k = mapKey(platform, chatId);
+    const cur = m[k] ?? { cwd: defaultCwd, sessionId: "", fork: 0 };
+    const cwd = cur.cwd || defaultCwd;
+    const fork = (cur.fork ?? 0) + 1;
+    const sessionId = deriveId(platform, chatId, cwd, fork);
+    m[k] = { cwd, sessionId, fork };
+    save(m);
+    return sessionId;
+}
+/** `/resume <id>` — point the chat at a specific existing session, following its cwd so it runs in the right place. */
+export function setChatSession(platform, chatId, sessionId, cwd) {
+    const m = load();
+    const k = mapKey(platform, chatId);
+    m[k] = { cwd, sessionId, fork: m[k]?.fork ?? 0 };
+    save(m);
+}

package/dist/gateway/signal.js

@@ -0,0 +1,220 @@
+// Signal adapter for `hara gateway` — talks to a LOCAL signal-cli daemon running in HTTP/JSON-RPC mode
+// (built-in fetch, zero new dep; no WebSocket, no cloud API). The user installs signal-cli, registers/links the
+// bot's phone number, and runs `signal-cli -a <number> daemon --http localhost:8080`. Inbound is drained via the
+// JSON-RPC `receive` method on a long-poll loop (the robust zero-dep path — no SSE line-buffering quirks);
+// outbound + attachment fetch go through JSON-RPC `send`/`getAttachment`. Creds from HARA_SIGNAL_RPC_URL
+// (e.g. http://localhost:8080) + HARA_SIGNAL_NUMBER (the bot's registered phone, E.164). Same ChatAdapter shape
+// as the others, so all cross-platform gateway plumbing (send_file, system context, stuck-guard, image
+// attach/describe) works unchanged. Mirrors the Matrix long-poll model + the Discord download-media/sendFile
+// patterns, and the hermes signal.py protocol/redaction behavior.
+//
+// EXTERNAL DEPENDENCY: signal-cli is NOT bundled — it's a separate program the user installs and runs (it is the
+// only way to speak Signal's protocol; there is no official cloud API). The adapter just speaks HTTP/JSON-RPC to
+// the daemon the user has running. See setup notes at the bottom of this file.
+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));
+// E.164 phone numbers (+15551234567) anywhere in a string → +155****4567 (mirrors hermes' _redact_phone).
+const PHONE_RE = /\+[1-9]\d{6,14}/g;
+/** Redact phone numbers for logging. Keeps a 4/4 head+tail window; never logs the full E.164. (pure) */
+export function redactPhone(s) {
+    if (!s)
+        return "<none>";
+    return s.replace(PHONE_RE, (p) => (p.length <= 8 ? "****" : `${p.slice(0, 4)}****${p.slice(-4)}`));
+}
+const isImageExt = (ext) => /^\.(png|jpe?g|gif|webp)$/i.test(ext);
+/** Guess a file extension from an attachment's contentType / filename (signal-cli gives us both as hints). (pure) */
+export function attachmentExt(contentType, filename) {
+    const ct = (contentType ?? "").toLowerCase();
+    if (ct.startsWith("image/")) {
+        if (ct.includes("png"))
+            return ".png";
+        if (ct.includes("jpeg") || ct.includes("jpg"))
+            return ".jpg";
+        if (ct.includes("gif"))
+            return ".gif";
+        if (ct.includes("webp"))
+            return ".webp";
+    }
+    const fromName = (filename ?? "").toLowerCase().match(/\.(png|jpe?g|gif|webp|mp4|mp3|ogg|m4a|pdf|txt)$/);
+    if (fromName)
+        return fromName[0];
+    if (ct.startsWith("audio/"))
+        return ".ogg";
+    if (ct.startsWith("video/"))
+        return ".mp4";
+    return ".bin";
+}
+/** Sniff a file extension from magic bytes — fallback when signal-cli's base64 attachment lacks a contentType. (pure) */
+export function extFromBytes(data) {
+    if (data.length >= 4 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47)
+        return ".png";
+    if (data.length >= 2 && data[0] === 0xff && data[1] === 0xd8)
+        return ".jpg";
+    if (data.length >= 4 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x38)
+        return ".gif";
+    if (data.length >= 12 && data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 && data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50)
+        return ".webp";
+    return ".bin";
+}
+/** Parse one signal-cli envelope → InboundMsg + the image attachments to fetch (pure; the fetch/download happens in
+ *  start()). Mirrors hermes' _handle_envelope: unwraps the {envelope:{...}} shape, handles plain dataMessage + edits,
+ *  filters our own outbound + stories. Filtering of OUR OWN number is done here via `selfNumber`. Returns the msg +
+ *  the image attachment refs (only images — other media is ignored, like Telegram/Matrix). null = skip. */
+export function parseSignalMessage(raw, selfNumber) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const env = raw.envelope ?? raw; // signal-cli wraps payloads as { envelope: {...} }
+    // Stories / typing / receipts / sync echoes carry no inbound dataMessage → skip. Also skip our own outbound
+    // (syncMessage is the echo of what WE sent from another linked device — never treat it as user input).
+    if (env.syncMessage)
+        return null;
+    if (env.storyMessage)
+        return null;
+    if (env.typingMessage || env.receiptMessage)
+        return null;
+    const sender = env.sourceNumber || env.sourceUuid || env.source;
+    if (!sender)
+        return null;
+    if (selfNumber && (env.sourceNumber === selfNumber || env.source === selfNumber))
+        return null; // our own message
+    // editMessage carries its updated dataMessage nested inside (mirrors hermes).
+    const data = env.dataMessage ?? env.editMessage?.dataMessage;
+    if (!data || typeof data !== "object")
+        return null;
+    const group = data.groupInfo;
+    const groupId = group?.groupId;
+    const chatId = groupId ? `group:${groupId}` : String(sender);
+    const atts = Array.isArray(data.attachments) ? data.attachments : [];
+    const images = atts
+        .filter((a) => a?.id && (String(a.contentType ?? "").startsWith("image/") || isImageExt(attachmentExt(a?.contentType, a?.filename))))
+        .map((a) => ({ id: String(a.id), contentType: a?.contentType, filename: a?.filename }));
+    const text = typeof data.message === "string" ? data.message : "";
+    if (!text && images.length === 0)
+        return null; // no text + no image (reaction/sticker/other media) → skip
+    return {
+        msg: {
+            chatId,
+            userId: String(sender),
+            userName: env.sourceName || String(sender),
+            text: text || "[图片]",
+        },
+        images,
+    };
+}
+export function signalAdapter(rpcUrl, selfNumber) {
+    const base = rpcUrl.replace(/\/+$/, ""); // trim trailing slashes
+    let rpcSeq = 0;
+    /** One JSON-RPC 2.0 call to the signal-cli daemon. Returns `result` (any) or null on error. */
+    async function rpc(method, params, signal) {
+        const id = `${method}_${++rpcSeq}`;
+        try {
+            const res = await fetch(`${base}/api/v1/rpc`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", method, params, id }),
+                signal,
+            });
+            if (!res.ok)
+                return null;
+            const j = (await res.json());
+            if (j.error) {
+                console.error(`hara gateway[signal]: RPC ${method} error:`, redactPhone(JSON.stringify(j.error)));
+                return null;
+            }
+            return j.result ?? null;
+        }
+        catch (e) {
+            if (signal?.aborted)
+                return null;
+            return null;
+        }
+    }
+    /** Recipient/group routing shared by send + sendFile (mirrors hermes). */
+    const target = (chatId) => {
+        const id = String(chatId);
+        return id.startsWith("group:") ? { groupId: id.slice(6) } : { recipient: [id] };
+    };
+    /** Fetch a signal-cli attachment by id (base64 over JSON-RPC) → a local path under ~/.hara/signal/media. */
+    async function downloadAttachment(ref) {
+        try {
+            const result = await rpc("getAttachment", { account: selfNumber, id: ref.id });
+            // signal-cli returns either a raw base64 string or { data: "base64..." }
+            const b64 = typeof result === "string" ? result : result && typeof result === "object" ? result.data : null;
+            if (!b64 || typeof b64 !== "string")
+                return null;
+            const bytes = Buffer.from(b64, "base64");
+            let ext = attachmentExt(ref.contentType, ref.filename);
+            if (ext === ".bin")
+                ext = extFromBytes(bytes); // last-resort magic-byte sniff
+            const dir = join(homedir(), ".hara", "signal", "media");
+            mkdirSync(dir, { recursive: true });
+            const path = join(dir, `sig_${Date.now()}_${ref.id.slice(-12)}${ext}`);
+            writeFileSync(path, bytes);
+            return path;
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        name: "signal",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                await rpc("send", { account: selfNumber, message: part, ...target(chatId) });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // Signal has no separate photo/document endpoints — everything is an `attachments` path on `send`.
+            // signal-cli reads the file off the local disk by path, so we just hand it the path (no upload step).
+            await rpc("send", { account: selfNumber, message: "", attachments: [filePath], ...target(chatId) }).catch(() => { });
+            // (readFileSync/basename imported for parity with the other adapters' file plumbing; signal-cli reads by path.)
+            void readFileSync;
+            void basename;
+        },
+        async start(onMessage, signal) {
+            console.error(`hara gateway[signal]: polling signal-cli daemon at ${base} as ${redactPhone(selfNumber)} (ensure \`signal-cli -a <number> daemon --http\` is running).`);
+            while (!signal.aborted) {
+                try {
+                    // JSON-RPC `receive` drains all envelopes queued since the last call. timeout is the long-poll seconds
+                    // the daemon will hold the request open waiting for new messages (server-side block → low-latency, low-spin).
+                    const result = await rpc("receive", { account: selfNumber, timeout: 30 }, signal);
+                    const envelopes = Array.isArray(result) ? result : result ? [result] : [];
+                    for (const raw of envelopes) {
+                        const parsed = parseSignalMessage(raw, selfNumber);
+                        if (!parsed)
+                            continue;
+                        for (const ref of parsed.images) {
+                            const path = await downloadAttachment(ref);
+                            if (path)
+                                (parsed.msg.images ??= []).push(path);
+                        }
+                        await onMessage(parsed.msg).catch(() => { });
+                    }
+                    if (envelopes.length === 0)
+                        await sleep(500); // daemon returned immediately (no long-poll support) → gentle spin
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000); // daemon down / network blip → back off + retry (reconnect on drop)
+                }
+            }
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// signal-cli setup (the user does this once, OUTSIDE hara):
+//
+//   1. Install signal-cli           brew install signal-cli   (or download a release; needs a JRE)
+//   2. Register OR link the number  (a) register a NEW number:
+//                                       signal-cli -a +1555… register        # solve the captcha it prompts for
+//                                       signal-cli -a +1555… verify 123456    # the SMS code
+//                                   (b) OR link to an EXISTING phone as a secondary device:
+//                                       signal-cli link -n "hara"             # scan the QR from Signal app → Linked devices
+//   3. Run the HTTP/JSON-RPC daemon signal-cli -a +1555… daemon --http localhost:8080
+//   4. Point hara at it             HARA_SIGNAL_RPC_URL=http://localhost:8080  HARA_SIGNAL_NUMBER=+1555…
+//                                   hara gateway --platform signal
+// ─────────────────────────────────────────────────────────────────────────────