@mnemom/mnemom 0.17.2-next.3 → 0.17.2-next.5

package/dist/lib/slack-launch.js

@@ -0,0 +1,42 @@
+/**
+ * lib/slack-launch.ts — what `mnemom agent --slack` adds to a launch.
+ *
+ * Writes a one-server MCP config for this session's channel server
+ * (`mnemom agent slack listen`, lib/slack-channel.ts), makes sure the
+ * per-operator router is running, and returns the CLI args that load it as a
+ * Claude Code channel. A custom (non-allowlisted) channel server loads only via
+ * `--dangerously-load-development-channels`, which shows a confirmation dialog;
+ * orgs on Team/Enterprise must also enable `channelsEnabled` in managed settings.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SESSION_NAME_ENV } from "./agent.js";
+import { ensureRouter } from "./slack-router.js";
+import { slackDir } from "./slack-state.js";
+import { normSession } from "./slack-route.js";
+export const SLACK_CHANNEL_SERVER = "mnemom-slack";
+/** The MCP config document for `session` (pure; unit-tested). */
+export function slackMcpConfig(session, cli) {
+    return {
+        mcpServers: {
+            [SLACK_CHANNEL_SERVER]: {
+                command: cli[0],
+                args: [...cli.slice(1), "agent", "slack", "listen"],
+                env: { [SESSION_NAME_ENV]: session },
+            },
+        },
+    };
+}
+/** The args that load the channel server for `session`; starts the router. */
+export function slackChannelArgs(session, cli = [process.execPath, process.argv[1] ?? "mnemom"]) {
+    mkdirSync(slackDir(), { recursive: true, mode: 0o700 });
+    const path = join(slackDir(), `mcp-${normSession(session)}.json`);
+    writeFileSync(path, JSON.stringify(slackMcpConfig(session, cli), null, 2), { mode: 0o600 });
+    ensureRouter(cli);
+    return [
+        "--mcp-config",
+        path,
+        "--dangerously-load-development-channels",
+        `server:${SLACK_CHANNEL_SERVER}`,
+    ];
+}

package/dist/lib/slack-route.d.ts

@@ -0,0 +1,58 @@
+/**
+ * lib/slack-route.ts — who a Slack message is addressed to (pure; no I/O).
+ *
+ * Every governed session posts through ONE per-operator Slack app, so a message
+ * arriving on that app's Socket Mode connection has to be routed to the session(s)
+ * it addresses. A session is not a Slack user and cannot be @mentioned natively,
+ * so three conventions stand in for a mention (all may apply to one message; the
+ * result is the de-duplicated union):
+ *
+ *   1. THREAD REPLY — a reply in a thread whose parent (or any earlier reply) a
+ *      session posted routes to that session. The post index records each post.
+ *   2. APP MENTION + NAME — `<@APPBOT> pv2-lead: …` (a real mention of the app)
+ *      routes to the session named by the first word after the mention.
+ *   3. PLAIN HANDLE — `@pv2-lead …` typed as text routes to that session when it
+ *      is a known live session (plain text is not a Slack mention, so it is only
+ *      honoured for names we recognise, to avoid routing stray `@words`).
+ *
+ * The app's own posts (bot_id set) are never routed — sessions do not hear
+ * themselves or each other through the router.
+ */
+export interface SlackMessageEvent {
+    type?: string;
+    subtype?: string;
+    channel?: string;
+    user?: string;
+    bot_id?: string;
+    text?: string;
+    ts?: string;
+    thread_ts?: string;
+}
+/** One post a session made: `ts` in `channel`, plus the thread it was in (if any). */
+export interface PostRecord {
+    session: string;
+    channel: string;
+    ts: string;
+    thread_ts?: string;
+}
+/** channel → thread root ts → sessions that posted in that thread. */
+export type ThreadIndex = Map<string, Map<string, Set<string>>>;
+export declare function buildThreadIndex(posts: Iterable<PostRecord>): ThreadIndex;
+/** Normalise a session name for comparison (same shape the launcher emits). */
+export declare function normSession(raw: string): string;
+/**
+ * The sessions `ev` is addressed to. `liveSessions` are the names with a running
+ * listener; `botUserId` is the app's bot user (from auth.test). Returns [] for
+ * events that address no one (or that the app itself posted).
+ */
+export declare function routeMessage(ev: SlackMessageEvent, ctx: {
+    botUserId: string;
+    liveSessions: Iterable<string>;
+    threads: ThreadIndex;
+}): string[];
+/**
+ * The text a session receives: the app mention, and a live session name right
+ * after it, are stripped so the model reads the instruction, not the routing.
+ * A word after the mention that is NOT a live session is kept (it is content).
+ */
+export declare function stripAddressing(text: string, botUserId: string, liveSessions: Iterable<string>): string;

package/dist/lib/slack-route.js

@@ -0,0 +1,99 @@
+/**
+ * lib/slack-route.ts — who a Slack message is addressed to (pure; no I/O).
+ *
+ * Every governed session posts through ONE per-operator Slack app, so a message
+ * arriving on that app's Socket Mode connection has to be routed to the session(s)
+ * it addresses. A session is not a Slack user and cannot be @mentioned natively,
+ * so three conventions stand in for a mention (all may apply to one message; the
+ * result is the de-duplicated union):
+ *
+ *   1. THREAD REPLY — a reply in a thread whose parent (or any earlier reply) a
+ *      session posted routes to that session. The post index records each post.
+ *   2. APP MENTION + NAME — `<@APPBOT> pv2-lead: …` (a real mention of the app)
+ *      routes to the session named by the first word after the mention.
+ *   3. PLAIN HANDLE — `@pv2-lead …` typed as text routes to that session when it
+ *      is a known live session (plain text is not a Slack mention, so it is only
+ *      honoured for names we recognise, to avoid routing stray `@words`).
+ *
+ * The app's own posts (bot_id set) are never routed — sessions do not hear
+ * themselves or each other through the router.
+ */
+export function buildThreadIndex(posts) {
+    const idx = new Map();
+    for (const p of posts) {
+        let byRoot = idx.get(p.channel);
+        if (!byRoot)
+            idx.set(p.channel, (byRoot = new Map()));
+        // Index the post's own ts as well as the thread it asked for: Slack posts a
+        // reply to a deleted parent at the top level, and a reply under THAT post
+        // must still reach the session that wrote it.
+        for (const root of new Set([p.ts, p.thread_ts].filter(Boolean))) {
+            let sessions = byRoot.get(root);
+            if (!sessions)
+                byRoot.set(root, (sessions = new Set()));
+            sessions.add(p.session);
+        }
+    }
+    return idx;
+}
+/** Normalise a session name for comparison (same shape the launcher emits). */
+export function normSession(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+const HANDLE_RE = /(?:^|[\s(])@([a-z0-9][a-z0-9-]*[a-z0-9])(?=$|[\s,.:;!?)])/gi;
+/**
+ * The sessions `ev` is addressed to. `liveSessions` are the names with a running
+ * listener; `botUserId` is the app's bot user (from auth.test). Returns [] for
+ * events that address no one (or that the app itself posted).
+ */
+export function routeMessage(ev, ctx) {
+    if (ev.bot_id || !ev.user || !ev.channel || !ev.ts)
+        return [];
+    if (ev.subtype && ev.subtype !== "thread_broadcast" && ev.subtype !== "file_share")
+        return [];
+    const live = new Map();
+    for (const s of ctx.liveSessions)
+        live.set(normSession(s), s);
+    const out = new Set();
+    const text = ev.text ?? "";
+    // 1. thread reply
+    if (ev.thread_ts && ev.thread_ts !== ev.ts) {
+        for (const s of ctx.threads.get(ev.channel)?.get(ev.thread_ts) ?? [])
+            out.add(s);
+    }
+    // 2. <@BOT> name…
+    const mention = `<@${ctx.botUserId}>`;
+    let at = text.indexOf(mention);
+    while (at !== -1) {
+        const after = text.slice(at + mention.length).match(/^[\s,:]*@?([A-Za-z0-9][A-Za-z0-9-]*)/);
+        if (after) {
+            const hit = live.get(normSession(after[1]));
+            if (hit)
+                out.add(hit);
+        }
+        at = text.indexOf(mention, at + mention.length);
+    }
+    // 3. plain @handle for a known live session
+    for (const m of text.matchAll(HANDLE_RE)) {
+        const hit = live.get(normSession(m[1]));
+        if (hit)
+            out.add(hit);
+    }
+    return [...out];
+}
+/**
+ * The text a session receives: the app mention, and a live session name right
+ * after it, are stripped so the model reads the instruction, not the routing.
+ * A word after the mention that is NOT a live session is kept (it is content).
+ */
+export function stripAddressing(text, botUserId, liveSessions) {
+    const live = new Set([...liveSessions].map(normSession));
+    const re = new RegExp(`<@${botUserId}>[\\s,:]*(?:@?([A-Za-z0-9][A-Za-z0-9-]*)[\\s,:]*)?`, "g");
+    return text
+        .replace(re, (_whole, name) => name && !live.has(normSession(name)) ? `${name} ` : "")
+        .replace(/[ \t]{2,}/g, " ")
+        .trim();
+}

package/dist/lib/slack-router.d.ts

@@ -0,0 +1,34 @@
+/**
+ * lib/slack-router.ts — the per-operator Socket Mode router.
+ *
+ * ONE process per operator machine holds the app's Socket Mode connection
+ * (Slack hands each event to exactly one of an app's open connections, so a
+ * connection per session would silently drop messages). For every channel
+ * message it asks lib/slack-route.ts who is addressed and appends the message to
+ * each addressed session's inbox (lib/slack-state.ts); each session's listener
+ * delivers from there. The router never writes to a session, never runs a tool,
+ * and holds no state beyond an in-memory user-name cache.
+ */
+import { type FetchLike } from "./slack.js";
+/** The running router's pid, or null. */
+export declare function routerPid(): number | null;
+/**
+ * Start the router detached if none is running. `argv` is how to re-invoke this
+ * CLI (node + script path). Returns the pid (existing or new).
+ */
+export declare function ensureRouter(argv?: string[]): number;
+/** Run the router until the process is killed. Reconnects on disconnect. */
+export declare function runRouter(opts: {
+    botToken: string;
+    appToken: string;
+    /** Slack member ids allowed to reach a session; everyone else is dropped. */
+    allow: string[];
+    log?: (line: string) => void;
+    fetchImpl?: FetchLike;
+}): Promise<never>;
+/** For `status`: whether a pid file points at a live router. */
+export declare function routerStatus(): {
+    running: boolean;
+    pid: number | null;
+    pidFile: string;
+};

package/dist/lib/slack-router.js

@@ -0,0 +1,185 @@
+/**
+ * lib/slack-router.ts — the per-operator Socket Mode router.
+ *
+ * ONE process per operator machine holds the app's Socket Mode connection
+ * (Slack hands each event to exactly one of an app's open connections, so a
+ * connection per session would silently drop messages). For every channel
+ * message it asks lib/slack-route.ts who is addressed and appends the message to
+ * each addressed session's inbox (lib/slack-state.ts); each session's listener
+ * delivers from there. The router never writes to a session, never runs a tool,
+ * and holds no state beyond an in-memory user-name cache.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { slackCall } from "./slack.js";
+import { buildThreadIndex, routeMessage, stripAddressing, } from "./slack-route.js";
+import { appendInbox, liveSessions, readPosts, slackDir } from "./slack-state.js";
+const routerPidFile = () => join(slackDir(), "router.pid");
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** The running router's pid, or null. */
+export function routerPid() {
+    try {
+        const pid = Number(readFileSync(routerPidFile(), "utf8").trim());
+        return Number.isInteger(pid) && pid > 0 && pidAlive(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Start the router detached if none is running. `argv` is how to re-invoke this
+ * CLI (node + script path). Returns the pid (existing or new).
+ */
+export function ensureRouter(argv = [process.execPath, process.argv[1] ?? "mnemom"]) {
+    const existing = routerPid();
+    if (existing)
+        return existing;
+    const child = spawn(argv[0], [...argv.slice(1), "agent", "slack", "router"], {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+    });
+    child.unref();
+    return child.pid ?? 0;
+}
+/** Run the router until the process is killed. Reconnects on disconnect. */
+export async function runRouter(opts) {
+    const log = opts.log ?? ((l) => console.error(`[slack-router] ${l}`));
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const WS = globalThis.WebSocket;
+    if (!WS)
+        throw new Error("the Slack router needs Node 22+ (global WebSocket).");
+    const auth = await slackCall("auth.test", opts.botToken, {}, fetchImpl);
+    if (!auth.ok)
+        throw new Error(`Slack auth.test failed: ${auth.error}`);
+    const botUserId = String(auth.user_id);
+    const other = routerPid();
+    if (other && other !== process.pid)
+        throw new Error(`a router is already running (pid ${other}).`);
+    mkdirSync(slackDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(routerPidFile(), String(process.pid), { mode: 0o600 });
+    const names = new Map();
+    const userName = async (id) => {
+        if (names.has(id))
+            return names.get(id);
+        try {
+            const r = await slackCall("users.info", opts.botToken, { user: id }, fetchImpl);
+            const u = r.user;
+            const n = u?.profile?.display_name || u?.profile?.real_name || u?.name;
+            if (n)
+                names.set(id, n);
+            return n;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // app_mention and message.channels both fire for a mention — handle each ts once.
+    const seen = new Set();
+    const handle = async (ev) => {
+        const key = `${ev.channel}:${ev.ts}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        if (seen.size > 2000)
+            seen.delete(seen.values().next().value);
+        // Sender gate: Slack text becomes model input, so only allowlisted members
+        // may reach a session. An empty allowlist delivers nothing.
+        if (!ev.user || !opts.allow.includes(ev.user))
+            return;
+        const live = liveSessions();
+        const threads = buildThreadIndex(readPosts());
+        const targets = routeMessage(ev, { botUserId, liveSessions: live, threads });
+        if (!targets.length) {
+            if (ev.text?.includes(`<@${botUserId}>`) && !ev.bot_id) {
+                const hint = live.length
+                    ? `No live session matched. Address one as \`@<app> <session>: …\` — live now: ${live.map((s) => `\`${s}\``).join(", ")}.`
+                    : "No agent session is listening right now.";
+                await slackCall("chat.postMessage", opts.botToken, { channel: ev.channel, thread_ts: ev.thread_ts ?? ev.ts, text: hint }, fetchImpl).catch(() => undefined);
+            }
+            return;
+        }
+        const { channel, ts, user } = ev;
+        if (!channel || !ts || !user)
+            return; // routeMessage already requires all three
+        const inThread = ev.thread_ts && ev.thread_ts !== ev.ts ? threads.get(channel)?.get(ev.thread_ts) : undefined;
+        const user_name = await userName(user);
+        const text = stripAddressing(ev.text ?? "", botUserId, live);
+        for (const session of targets) {
+            const via = [];
+            if (inThread?.has(session))
+                via.push("thread");
+            if ((ev.text ?? "").includes(`<@${botUserId}>`))
+                via.push("mention");
+            if (!via.length)
+                via.push("handle");
+            appendInbox(session, {
+                channel: channel,
+                ts: ts,
+                thread_ts: ev.thread_ts,
+                user: user,
+                user_name,
+                text,
+                via,
+            });
+            log(`routed ${ev.channel}/${ev.ts} → ${session} (${via.join("+")})`);
+        }
+    };
+    for (;;) {
+        try {
+            const open = await slackCall("apps.connections.open", opts.appToken, {}, fetchImpl);
+            if (!open.ok)
+                throw new Error(`apps.connections.open: ${open.error}`);
+            await new Promise((resolve) => {
+                const ws = new WS(String(open.url));
+                ws.onmessage = (m) => {
+                    let env;
+                    try {
+                        env = JSON.parse(String(m.data));
+                    }
+                    catch {
+                        return;
+                    }
+                    if (env.envelope_id)
+                        ws.send(JSON.stringify({ envelope_id: env.envelope_id }));
+                    if (env.type === "disconnect") {
+                        log(`disconnect requested (${env.reason ?? "?"}); reconnecting`);
+                        ws.close();
+                        return;
+                    }
+                    const ev = env.payload?.event;
+                    if (env.type === "events_api" &&
+                        ev &&
+                        (ev.type === "message" || ev.type === "app_mention")) {
+                        handle(ev).catch((e) => log(`handle failed: ${e instanceof Error ? e.message : e}`));
+                    }
+                };
+                ws.onopen = () => log(`connected as <@${botUserId}>`);
+                ws.onclose = () => resolve();
+                ws.onerror = () => ws.close();
+            });
+        }
+        catch (e) {
+            log(`connection error: ${e instanceof Error ? e.message : e}`);
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+}
+/** For `status`: whether a pid file points at a live router. */
+export function routerStatus() {
+    const pid = routerPid();
+    return {
+        running: pid !== null,
+        pid,
+        pidFile: existsSync(routerPidFile()) ? routerPidFile() : "",
+    };
+}

package/dist/lib/slack-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * lib/slack-state.ts — the local, per-operator state behind `mnemom agent slack`.
+ *
+ *   ~/.mnemom/slack/posts.jsonl          every post a session made (routes thread replies)
+ *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *
+ * The router (one per operator machine) is the only writer of inboxes; each
+ * session's listener is the only reader of its own. No secret is stored here.
+ */
+import { type PostRecord } from "./slack-route.js";
+export declare function slackDir(): string;
+export declare function recordPost(p: PostRecord): void;
+export declare function readPosts(): PostRecord[];
+/** A message as delivered to a session. */
+export interface InboxMessage {
+    channel: string;
+    ts: string;
+    thread_ts?: string;
+    user: string;
+    user_name?: string;
+    text: string;
+    /** How it was addressed: thread | mention | handle. */
+    via: string[];
+}
+export declare function appendInbox(session: string, msg: InboxMessage): void;
+export declare function inboxPath(session: string): string;
+/** Messages appended after byte `offset`, and the new offset. */
+export declare function readInboxFrom(session: string, offset: number): {
+    messages: InboxMessage[];
+    offset: number;
+};
+export declare function registerLive(session: string, pid?: number): void;
+export declare function unregisterLive(session: string): void;
+/** Sessions with a running listener; stale entries (dead pid) are pruned. */
+export declare function liveSessions(): string[];

package/dist/lib/slack-state.js

@@ -0,0 +1,119 @@
+/**
+ * lib/slack-state.ts — the local, per-operator state behind `mnemom agent slack`.
+ *
+ *   ~/.mnemom/slack/posts.jsonl          every post a session made (routes thread replies)
+ *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *
+ * The router (one per operator machine) is the only writer of inboxes; each
+ * session's listener is the only reader of its own. No secret is stored here.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { MNEMOM_DIR } from "./config.js";
+import { normSession } from "./slack-route.js";
+export function slackDir() {
+    return join(MNEMOM_DIR, "slack");
+}
+const postsFile = () => join(slackDir(), "posts.jsonl");
+const liveDir = () => join(slackDir(), "live");
+const inboxDir = () => join(slackDir(), "inbox");
+/** Only the most recent posts matter for thread routing; cap what we read. */
+const MAX_POSTS = 5000;
+function ensure(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+function readJsonl(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // a torn line from a concurrent append is skipped, never fatal
+        }
+    }
+    return out;
+}
+export function recordPost(p) {
+    ensure(slackDir());
+    appendFileSync(postsFile(), JSON.stringify(p) + "\n", { mode: 0o600 });
+}
+export function readPosts() {
+    return readJsonl(postsFile()).slice(-MAX_POSTS);
+}
+const fileFor = (session) => `${normSession(session)}`;
+export function appendInbox(session, msg) {
+    ensure(inboxDir());
+    appendFileSync(join(inboxDir(), `${fileFor(session)}.jsonl`), JSON.stringify(msg) + "\n", {
+        mode: 0o600,
+    });
+}
+export function inboxPath(session) {
+    return join(inboxDir(), `${fileFor(session)}.jsonl`);
+}
+/** Messages appended after byte `offset`, and the new offset. */
+export function readInboxFrom(session, offset) {
+    const path = inboxPath(session);
+    if (!existsSync(path))
+        return { messages: [], offset: 0 };
+    const buf = readFileSync(path);
+    if (buf.length < offset)
+        offset = 0; // truncated/rotated
+    const chunk = buf.subarray(offset).toString("utf8");
+    const end = chunk.lastIndexOf("\n") + 1; // leave a partial trailing line for next read
+    const messages = [];
+    for (const line of chunk.slice(0, end).split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            messages.push(JSON.parse(line));
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return { messages, offset: offset + Buffer.byteLength(chunk.slice(0, end)) };
+}
+export function registerLive(session, pid = process.pid) {
+    ensure(liveDir());
+    writeFileSync(join(liveDir(), `${fileFor(session)}.json`), JSON.stringify({ session, pid, since: new Date().toISOString() }), { mode: 0o600 });
+}
+export function unregisterLive(session) {
+    rmSync(join(liveDir(), `${fileFor(session)}.json`), { force: true });
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Sessions with a running listener; stale entries (dead pid) are pruned. */
+export function liveSessions() {
+    if (!existsSync(liveDir()))
+        return [];
+    const out = [];
+    for (const f of readdirSync(liveDir())) {
+        if (!f.endsWith(".json"))
+            continue;
+        const path = join(liveDir(), f);
+        try {
+            const rec = JSON.parse(readFileSync(path, "utf8"));
+            if (rec.session && typeof rec.pid === "number" && pidAlive(rec.pid))
+                out.push(rec.session);
+            else
+                rmSync(path, { force: true });
+        }
+        catch {
+            rmSync(path, { force: true });
+        }
+    }
+    return out;
+}

package/dist/lib/slack.d.ts

@@ -0,0 +1,69 @@
+/**
+ * lib/slack.ts — the Slack Web API seam behind `mnemom agent slack`.
+ *
+ * One shared Slack app (bot token, scopes `chat:write` + `chat:write.customize`)
+ * posts on behalf of every governed session; `chat:write.customize` lets each post
+ * carry the session's own display name (MNEMOM_AGENT_SESSION_NAME, set by the
+ * launcher in the child CLI's env) so a channel reads as N named agents, not one bot.
+ *
+ * Where the bot may post is governed in Slack itself: it can only post to channels
+ * it has been /invited to (`not_in_channel` otherwise).
+ *
+ * The token resolves env (MNEMOM_SLACK_BOT_TOKEN) > the launcher's secret store
+ * (~/.mnemom/launcher.json `slack_bot_token`). It is deliberately NEVER exported
+ * into the child CLI's environment, so it does not sit in the model's context.
+ */
+export declare const SLACK_TOKEN_ENV = "MNEMOM_SLACK_BOT_TOKEN";
+export declare const SLACK_TOKEN_STORE_KEY = "slack_bot_token";
+/** The app-level token (`xapp-…`, scope connections:write) the Socket Mode router needs. */
+export declare const SLACK_APP_TOKEN_ENV = "MNEMOM_SLACK_APP_TOKEN";
+export declare const SLACK_APP_TOKEN_STORE_KEY = "slack_app_token";
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface SlackResponse {
+    ok: boolean;
+    error?: string;
+    [k: string]: unknown;
+}
+/** env > store; "" when neither is set. `kind` selects the bot or the app-level token. */
+export declare function resolveSlackToken(env: NodeJS.ProcessEnv, store: Record<string, unknown>, kind?: "bot" | "app"): {
+    token: string;
+    source: "env" | "store" | null;
+};
+/** The session's display name from the launcher, or undefined outside a launched session. */
+export declare function sessionPosterName(env: NodeJS.ProcessEnv): string | undefined;
+/** A bot token is `xoxb-…`; reject anything else before it reaches the store. */
+export declare function looksLikeBotToken(token: string): boolean;
+/** An app-level token is `xapp-…`. */
+export declare function looksLikeAppToken(token: string): boolean;
+/**
+ * The Slack app manifest an operator pastes at api.slack.com/apps → "From a
+ * manifest". One app per operator: Socket Mode delivers each event to ONE of an
+ * app's open connections, so a single router per app is what makes routing lossless.
+ * The app-level token (connections:write) cannot be minted by a manifest — the
+ * operator generates it under Basic Information → App-Level Tokens.
+ */
+export declare function slackAppManifest(appName: string): Record<string, unknown>;
+/** The request body for `method` (pure; unit-tested). */
+export declare function encodeSlackBody(method: string, body: Record<string, unknown>): {
+    contentType: string;
+    payload: string;
+};
+/** POST one Web API method (bearer auth). Throws only on transport/HTTP failure. */
+export declare function slackCall(method: string, token: string, body: Record<string, unknown>, fetchImpl?: FetchLike): Promise<SlackResponse>;
+export interface PostInput {
+    token: string;
+    channel: string;
+    text: string;
+    username?: string;
+    iconEmoji?: string;
+    threadTs?: string;
+}
+/** The chat.postMessage body for a post — pure, so the wire shape is unit-testable. */
+export declare function buildPostBody(input: PostInput): Record<string, unknown>;
+/** Post a message; throws a human-readable error on a Slack `ok:false`. */
+export declare function postMessage(input: PostInput, fetchImpl?: FetchLike): Promise<{
+    channel: string;
+    ts: string;
+}>;
+/** Map the Slack error codes a poster actually hits to the fix. */
+export declare function explainSlackError(code: string | undefined, channel?: string): string;