@nanhara/hara 0.70.0 → 0.89.0

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);
+}

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);
+}