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

package/dist/lib/slack.js

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+import { SESSION_NAME_ENV } from "./agent.js";
+export const SLACK_TOKEN_ENV = "MNEMOM_SLACK_BOT_TOKEN";
+export const SLACK_TOKEN_STORE_KEY = "slack_bot_token";
+/** The app-level token (`xapp-…`, scope connections:write) the Socket Mode router needs. */
+export const SLACK_APP_TOKEN_ENV = "MNEMOM_SLACK_APP_TOKEN";
+export const SLACK_APP_TOKEN_STORE_KEY = "slack_app_token";
+const SLACK_API = "https://slack.com/api";
+/** Slack truncates `username` beyond 80 chars; keep ours inside that. */
+const MAX_USERNAME = 80;
+/** env > store; "" when neither is set. `kind` selects the bot or the app-level token. */
+export function resolveSlackToken(env, store, kind = "bot") {
+    const envKey = kind === "bot" ? SLACK_TOKEN_ENV : SLACK_APP_TOKEN_ENV;
+    const storeKey = kind === "bot" ? SLACK_TOKEN_STORE_KEY : SLACK_APP_TOKEN_STORE_KEY;
+    const fromEnv = (env[envKey] ?? "").trim();
+    if (fromEnv)
+        return { token: fromEnv, source: "env" };
+    const stored = store[storeKey];
+    if (typeof stored === "string" && stored.trim())
+        return { token: stored.trim(), source: "store" };
+    return { token: "", source: null };
+}
+/** The session's display name from the launcher, or undefined outside a launched session. */
+export function sessionPosterName(env) {
+    const name = (env[SESSION_NAME_ENV] ?? "").replace(/[\r\n]+/g, " ").trim();
+    return name ? name.slice(0, MAX_USERNAME) : undefined;
+}
+/** A bot token is `xoxb-…`; reject anything else before it reaches the store. */
+export function looksLikeBotToken(token) {
+    return /^xoxb-[A-Za-z0-9-]+$/.test(token.trim());
+}
+/** An app-level token is `xapp-…`. */
+export function looksLikeAppToken(token) {
+    return /^xapp-[A-Za-z0-9-]+$/.test(token.trim());
+}
+/**
+ * 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 function slackAppManifest(appName) {
+    const name = appName.trim().slice(0, 35) || "mnemom-agents";
+    return {
+        display_information: {
+            name,
+            description: "Governed Mnemom agent sessions — each posts under its own session name.",
+            background_color: "#1d1c1d",
+        },
+        features: { bot_user: { display_name: name, always_online: true } },
+        oauth_config: {
+            scopes: {
+                bot: [
+                    "chat:write",
+                    "chat:write.customize",
+                    "app_mentions:read",
+                    "channels:history",
+                    "groups:history",
+                    "channels:read",
+                    "channels:join",
+                    "users:read",
+                ],
+            },
+        },
+        settings: {
+            event_subscriptions: { bot_events: ["app_mention", "message.channels", "message.groups"] },
+            interactivity: { is_enabled: false },
+            org_deploy_enabled: false,
+            socket_mode_enabled: true,
+            token_rotation_enabled: false,
+        },
+    };
+}
+/**
+ * Methods that accept a JSON body. Slack's read methods (conversations.info,
+ * users.info, …) REJECT a JSON body with `invalid_arguments`, so every other
+ * method is sent form-encoded (objects/arrays JSON-stringified per field).
+ */
+const JSON_METHODS = new Set(["chat.postMessage", "chat.update", "chat.postEphemeral"]);
+/** The request body for `method` (pure; unit-tested). */
+export function encodeSlackBody(method, body) {
+    if (JSON_METHODS.has(method)) {
+        return { contentType: "application/json; charset=utf-8", payload: JSON.stringify(body) };
+    }
+    const form = new URLSearchParams();
+    for (const [k, v] of Object.entries(body)) {
+        if (v === undefined || v === null)
+            continue;
+        form.set(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+    }
+    return { contentType: "application/x-www-form-urlencoded", payload: form.toString() };
+}
+/** POST one Web API method (bearer auth). Throws only on transport/HTTP failure. */
+export async function slackCall(method, token, body, fetchImpl = fetch) {
+    const { contentType, payload } = encodeSlackBody(method, body);
+    const res = await fetchImpl(`${SLACK_API}/${method}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: payload,
+    });
+    if (!res.ok)
+        throw new Error(`Slack ${method}: HTTP ${res.status}`);
+    return (await res.json());
+}
+/** The chat.postMessage body for a post — pure, so the wire shape is unit-testable. */
+export function buildPostBody(input) {
+    const body = {
+        channel: input.channel.trim(),
+        text: input.text,
+        unfurl_links: false,
+    };
+    if (input.username)
+        body.username = input.username;
+    if (input.iconEmoji)
+        body.icon_emoji = normalizeEmoji(input.iconEmoji);
+    if (input.threadTs)
+        body.thread_ts = input.threadTs;
+    return body;
+}
+function normalizeEmoji(raw) {
+    // Index scan, not /^:+|:+$/ — that pattern backtracks polynomially on long ':' runs.
+    let v = raw.trim();
+    let a = 0;
+    let b = v.length;
+    while (a < b && v[a] === ":")
+        a++;
+    while (b > a && v[b - 1] === ":")
+        b--;
+    v = v.slice(a, b);
+    return `:${v}:`;
+}
+/** Post a message; throws a human-readable error on a Slack `ok:false`. */
+export async function postMessage(input, fetchImpl = fetch) {
+    const res = await slackCall("chat.postMessage", input.token, buildPostBody(input), fetchImpl);
+    if (!res.ok)
+        throw new Error(explainSlackError(res.error, input.channel));
+    return { channel: String(res.channel ?? input.channel), ts: String(res.ts ?? "") };
+}
+/** Map the Slack error codes a poster actually hits to the fix. */
+export function explainSlackError(code, channel) {
+    const where = channel ? ` ${channel}` : "";
+    switch (code) {
+        case "not_in_channel":
+            return `Slack: the bot is not in${where} — invite it there first (/invite @<app> in the channel).`;
+        case "channel_not_found":
+            return `Slack: channel${where} not found (or private and the bot is not a member).`;
+        case "is_archived":
+            return `Slack: channel${where} is archived.`;
+        case "missing_scope":
+            return "Slack: the bot token is missing a scope — the app needs chat:write and chat:write.customize.";
+        case "invalid_auth":
+        case "not_authed":
+        case "token_revoked":
+        case "account_inactive":
+            return `Slack: the bot token was rejected (${code}) — re-run \`mnemom agent slack login\`.`;
+        case "msg_too_long":
+            return "Slack: message too long.";
+        case "ratelimited":
+            return "Slack: rate limited — try again shortly.";
+        default:
+            return `Slack: ${code ?? "unknown error"}`;
+    }
+}

package/dist/mcp/handoff-server.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// mnemom-handoff — the stdio MCP server `mnemom agent` registers (behind the OFF-by-default
+// `context_handoff` setting, MNE-7564) exposing exactly ONE tool: `handoff(note)`.
+//
+// WHY .mjs, NOT .ts
+// This file must exist BYTE-IDENTICAL at the same relative path in both the source tree and
+// the built `dist/` tree, exactly like `rc-proxy.mjs` next to it: `commands/agent.ts`
+// resolves it relative to its OWN `import.meta.url`, which is the SOURCE path under `vitest`
+// (dev/test — no `tsc` has run) and the DIST path once installed. A `tsc`-compiled `.ts` file
+// only exists post-build, so it would be unresolvable in dev/test. Consequently this file is
+// self-contained (only Node builtins + global `fetch`, no local imports) — see
+// `scripts/copy-assets.mjs`, which copies it (and rc-proxy.mjs) verbatim into `dist/`.
+//
+// Deliberately hand-rolled rather than `@modelcontextprotocol/sdk`: MCP over stdio is
+// newline-delimited JSON-RPC 2.0, small enough to hand-roll for one tool in a CLI that
+// otherwise carries four small deps. Only `initialize`, `tools/list` and `tools/call` are
+// implemented — the whole surface Claude Code's MCP client needs for a stdio tool.
+//
+// Config rides on env vars the launcher sets via the `--mcp-config` file's `env` block
+// (`buildHandoffMcpConfig`, cli/src/lib/agent.ts) — never argv, so nothing here is visible to
+// `ps`. The Anthropic key itself is never IN that file, for any launch shape: the launcher hands
+// this process `MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME` naming a var this process already
+// inherits from its OWN parent env (every stdio MCP server inherits the full parent env —
+// verified experimentally for MNE-7564), and this process reads the key from THAT var at
+// request time instead. A terminal launch names `ANTHROPIC_CUSTOM_HEADERS` (parsed for its
+// `x-api-key:` line); Remote Control names a dedicated `MNEMOM_HANDOFF_KEY` its launcher sets
+// directly, since RC's child env strips every ANTHROPIC_* var (see `HandoffAnthropicKeySource`
+// in cli/src/lib/agent.ts for the full rationale). This process never logs either var's name or
+// value.
+
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+
+/** The gateway route this tool calls (gateway/src/context-handoff.ts, MNE-7563). */
+export const HANDOFF_PATH = "/mnemom/context/handoff";
+
+const TOOL_NAME = "handoff";
+
+const TOOL_DESCRIPTION =
+  "Hand off to your successor context. Call this at a natural stopping point in your own " +
+  "work, OR as soon as you see a '[mnemom context warning]' line from the gateway telling you " +
+  "the fold budget is nearly spent — that line means the gateway will fold on its own soon, so " +
+  "calling `handoff` first lets YOU choose what your successor reads. A good note is short and " +
+  "covers: the goal, what is already done, the next concrete action, and any open questions or " +
+  "blockers. The note is stored byte-exact and rendered to your successor verbatim — it is not " +
+  "summarized, so write it as you want it read.";
+
+const TOOL_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    note: {
+      type: "string",
+      description:
+        "Goal, what's done, the next action, and open questions — byte-exact to your successor.",
+    },
+  },
+  required: ["note"],
+  additionalProperties: false,
+};
+
+/** Required env vars the launcher always sets when it registers this server. */
+const REQUIRED_ENV = [
+  "MNEMOM_HANDOFF_GATEWAY_HOST",
+  "MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME",
+  "MNEMOM_HANDOFF_AGENT",
+  "MNEMOM_HANDOFF_CONVERSATION_ID",
+];
+
+/**
+ * Recover the Anthropic key from an env var NAME this process itself inherited from its parent
+ * (never a value written into the `--mcp-config` file). `ANTHROPIC_CUSTOM_HEADERS` is a
+ * multi-line header BLOCK (`buildCustomHeaders`, cli/src/lib/agent.ts) whose first line is
+ * `x-api-key: <key>` — extract just that. Any other name is treated as carrying the key value
+ * directly.
+ * @param {string} name
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string} the key, or "" if the named var is absent/unusable.
+ */
+function resolveKeyFromEnvName(name, env) {
+  const value = env[name] ?? "";
+  if (name === "ANTHROPIC_CUSTOM_HEADERS") {
+    const m = value.match(/^x-api-key:\s*(.+)$/im);
+    return m ? m[1].trim() : "";
+  }
+  return value.trim();
+}
+
+/**
+ * Read the tool's config from env. Throws (message never contains the key value) when a
+ * required var is missing, or when the named key-source var resolves to no usable key.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{gatewayHost: string, anthropicKey: string, agent: string, conversationId: string, sessionConfigB64?: string}}
+ */
+export function configFromEnv(env) {
+  const missing = REQUIRED_ENV.filter((k) => !(env[k] ?? "").trim());
+  if (missing.length) {
+    throw new Error(`mnemom-handoff: missing required env var(s): ${missing.join(", ")}`);
+  }
+  const keyEnvName = env.MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME.trim();
+  const anthropicKey = resolveKeyFromEnvName(keyEnvName, env);
+  if (!anthropicKey) {
+    throw new Error(
+      `mnemom-handoff: MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME names '${keyEnvName}', but this ` +
+        "process's own inherited environment has no usable value for it.",
+    );
+  }
+  return {
+    gatewayHost: env.MNEMOM_HANDOFF_GATEWAY_HOST.trim(),
+    anthropicKey,
+    agent: env.MNEMOM_HANDOFF_AGENT.trim(),
+    conversationId: env.MNEMOM_HANDOFF_CONVERSATION_ID.trim(),
+    sessionConfigB64: env.MNEMOM_HANDOFF_SESSION_CONFIG?.trim() || undefined,
+  };
+}
+
+/**
+ * Build the fetch call. Exported so a test can assert the wire shape without mocking fetch.
+ * @param {{gatewayHost: string, anthropicKey: string, agent: string, conversationId: string, sessionConfigB64?: string}} cfg
+ * @param {string} note
+ */
+export function buildHandoffRequest(cfg, note) {
+  const headers = {
+    "content-type": "application/json",
+    "x-api-key": cfg.anthropicKey,
+    "x-mnemom-agent": cfg.agent,
+  };
+  if (cfg.sessionConfigB64) headers["x-mnemom-session-config"] = cfg.sessionConfigB64;
+  return {
+    url: `${cfg.gatewayHost.replace(/\/+$/, "")}${HANDOFF_PATH}`,
+    init: {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ conversation_id: cfg.conversationId, note }),
+    },
+  };
+}
+
+/** Pull `{code, message}` out of the gateway's canonical error envelope; tolerant of anything else. */
+function extractGatewayError(body) {
+  if (!body || typeof body !== "object") return {};
+  const err = body.error;
+  if (!err || typeof err !== "object") return {};
+  return {
+    code: typeof err.code === "string" ? err.code : undefined,
+    message: typeof err.message === "string" ? err.message : undefined,
+  };
+}
+
+/**
+ * Call the route and render the result. NEVER throws: a network failure, a non-2xx status, or
+ * an unparseable body all come back as `{ok:false, message}` for the caller to surface as an
+ * MCP tool error — the tool must never crash the server or the session over a bad response.
+ * @param {{gatewayHost: string, anthropicKey: string, agent: string, conversationId: string, sessionConfigB64?: string}} cfg
+ * @param {string} note
+ * @param {typeof fetch} fetchImpl
+ */
+export async function callHandoff(cfg, note, fetchImpl) {
+  const { url, init } = buildHandoffRequest(cfg, note);
+  let res;
+  try {
+    res = await fetchImpl(url, init);
+  } catch (err) {
+    return {
+      ok: false,
+      message: `could not reach the gateway: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const text = await res.text().catch(() => "");
+  let body;
+  try {
+    body = text ? JSON.parse(text) : undefined;
+  } catch {
+    body = undefined;
+  }
+
+  if (!res.ok) {
+    const { code, message } = extractGatewayError(body);
+    const detail = message ?? (text || `HTTP ${res.status}`);
+    return {
+      ok: false,
+      message: `handoff request failed (${res.status}${code ? ` ${code}` : ""}): ${detail}`,
+    };
+  }
+
+  const parsed = body ?? {};
+  const pending = parsed.pending === true;
+  const level = typeof parsed.level === "string" ? parsed.level : "none";
+  const generation = typeof parsed.generation === "number" ? parsed.generation : 0;
+  const line = pending
+    ? `handoff queued (level: ${level}, generation ${generation}) — the gateway will fold at your next request`
+    : `handoff acknowledged (level: ${level}, generation ${generation}) — no fold scheduled`;
+  return { ok: true, line };
+}
+
+class MethodNotFoundError extends Error {}
+
+/** True for a JSON-RPC NOTIFICATION (no `id` key at all) — never gets a response. */
+function isNotification(msg) {
+  return !("id" in msg);
+}
+
+function textContent(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function errorContent(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/**
+ * Run the server against injected streams (tests use in-memory ones; `main()` wires real
+ * stdio). Handles one message per line; a line that isn't valid JSON, or errors while handling
+ * a request, is reported back as a JSON-RPC error for that message's id and never crashes the
+ * loop — one bad message must not take the whole tool down.
+ * @param {{input: NodeJS.ReadableStream, output: NodeJS.WritableStream, config: object, fetchImpl?: typeof fetch}} opts
+ */
+export function runHandoffServer(opts) {
+  const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+  const write = (msg) => {
+    opts.output.write(`${JSON.stringify(msg)}\n`);
+  };
+  const respond = (id, result) => {
+    if (id === undefined) return; // notification — no response
+    write({ jsonrpc: "2.0", id, result });
+  };
+  const respondError = (id, code, message) => {
+    if (id === undefined) return;
+    write({ jsonrpc: "2.0", id, error: { code, message } });
+  };
+
+  const rl = createInterface({ input: opts.input, terminal: false });
+
+  rl.on("line", (raw) => {
+    const line = raw.trim();
+    if (!line) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return; // not JSON-RPC we can respond to — drop it
+    }
+    const id = "id" in msg ? msg.id : undefined;
+    const method = typeof msg.method === "string" ? msg.method : "";
+
+    handle(method, msg.params, isNotification(msg))
+      .then((result) => respond(id, result))
+      .catch((err) => {
+        const code = err instanceof MethodNotFoundError ? -32601 : -32603;
+        respondError(id, code, err instanceof Error ? err.message : String(err));
+      });
+  });
+
+  async function handle(method, params, notification) {
+    switch (method) {
+      case "initialize":
+        return {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "mnemom-handoff", version: "1.0.0" },
+        };
+      case "notifications/initialized":
+        return undefined; // no-op; notification anyway (never responded to)
+      case "tools/list":
+        return {
+          tools: [
+            { name: TOOL_NAME, description: TOOL_DESCRIPTION, inputSchema: TOOL_INPUT_SCHEMA },
+          ],
+        };
+      case "tools/call":
+        return callTool(params);
+      case "ping":
+        return {};
+      default:
+        if (notification) return undefined;
+        throw new MethodNotFoundError(`unknown method '${method}'`);
+    }
+  }
+
+  async function callTool(params) {
+    const p = params ?? {};
+    if (p.name !== TOOL_NAME) {
+      return errorContent(`unknown tool '${String(p.name)}'`);
+    }
+    const args = p.arguments ?? {};
+    const note = args.note;
+    if (typeof note !== "string" || note.trim() === "") {
+      return errorContent("handoff requires a non-empty string `note` argument.");
+    }
+    const outcome = await callHandoff(opts.config, note, fetchImpl);
+    return outcome.ok ? textContent(outcome.line) : errorContent(outcome.message);
+  }
+
+  return {
+    close: () => rl.close(),
+  };
+}
+
+async function main() {
+  let config;
+  try {
+    config = configFromEnv(process.env);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+    return;
+  }
+  runHandoffServer({ input: process.stdin, output: process.stdout, config });
+}
+
+/**
+ * Only auto-start when run directly (`node handoff-server.mjs`), never on import (tests).
+ * `argv1`/`moduleUrl` default to the real `process.argv[1]`/`import.meta.url` at the call site
+ * (main()'s own check, below) but are accepted as params — like `configFromEnv(env)` above —
+ * so a test can drive every branch (no entry, an unconvertible entry, a real match/mismatch)
+ * without touching the real process's argv.
+ * @param {string | undefined} [argv1]
+ * @param {string} [moduleUrl]
+ */
+export function isMain(argv1 = process.argv[1], moduleUrl = import.meta.url) {
+  if (!argv1) return false;
+  try {
+    return pathToFileURL(argv1).href === moduleUrl;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  void main();
+}