@mnemom/mnemom 0.17.2-next.2 → 0.17.2-next.4

package/dist/lib/goal-api.js

@@ -0,0 +1,113 @@
+/**
+ * The client for the gateway's implicit-goal control route (implicit-goal CLI, cli-telemetry
+ * §1.2 / §1.4; the route is gateway/src/goal-intent-control.ts):
+ *
+ *   GET  https://<gateway_host>/mnemom/goal/intent?conversation_id=…&thread=…
+ *   POST https://<gateway_host>/mnemom/goal/intent/pin    {conversation_id, thread, pinned}
+ *   POST https://<gateway_host>/mnemom/goal/intent/reset  {conversation_id, thread, statement?, requirements?}
+ *
+ * Auth is the SAME credential the launch used: `x-api-key` (the Anthropic key from
+ * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, and `x-mnemom-api-key` when the
+ * launch had a Mnemom key. The gateway hashes them exactly as a proxied request and only LOOKS
+ * UP the agent. Key material is never printed: errors carry the status, the gateway's error code
+ * and its message, nothing else.
+ *
+ * Pure apart from the injected `fetch`, so every arm is unit-tested.
+ */
+/**
+ * A thread id the gateway accepts (PLAN K3 plus `all` for reads, plus the `m.<sha16>` per-process
+ * main ids the gateway's goal-thread.ts THREAD_ID_RE also accepts). Validated locally so a typo
+ * never costs a round trip.
+ */
+export const GOAL_THREAD_RE = /^(?:main|all|(?:a|t|af|q|m)\.[A-Za-z0-9._:-]{1,80})$/;
+export function isValidGoalThread(thread) {
+    return GOAL_THREAD_RE.test(thread);
+}
+/** A non-2xx answer (status > 0) or a transport failure (status 0). Never carries key material. */
+export class GoalControlError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "GoalControlError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/** `https://<host>` for a bare host; a host that already names a scheme is kept (trailing / dropped). */
+export function gatewayOrigin(host) {
+    const h = host.trim().replace(/\/+$/, "");
+    return /^https?:\/\//i.test(h) ? h : `https://${h}`;
+}
+export const GOAL_CONTROL_PATH = "/mnemom/goal/intent";
+/** The route URL for one op (the show query carries the conversation id and thread). */
+export function goalControlUrl(record, op, thread = "main") {
+    const base = `${gatewayOrigin(record.gateway_host)}${GOAL_CONTROL_PATH}`;
+    if (op === "show") {
+        const q = new URLSearchParams({ conversation_id: record.conversation_id, thread });
+        return `${base}?${q.toString()}`;
+    }
+    return `${base}/${op}`;
+}
+/** The launch's identity headers (never logged). */
+export function goalControlHeaders(record, creds) {
+    const headers = {
+        "x-api-key": creds.anthropicKey,
+        "x-mnemom-agent": record.agent_slug,
+        accept: "application/json",
+    };
+    if (creds.mnemomKey)
+        headers["x-mnemom-api-key"] = creds.mnemomKey;
+    return headers;
+}
+/** `{error:{code,message}}` (the gateway's envelope) → its parts; anything else → nulls. */
+function errorParts(body) {
+    if (!body || typeof body !== "object")
+        return { code: null, message: null };
+    const e = body.error;
+    if (!e || typeof e !== "object")
+        return { code: null, message: null };
+    const { code, message } = e;
+    return {
+        code: typeof code === "string" ? code : null,
+        message: typeof message === "string" ? message : null,
+    };
+}
+/**
+ * Call the control route. Resolves with the parsed 2xx body; rejects with a GoalControlError
+ * (status 0 for a transport failure or a 2xx that is not JSON).
+ */
+export async function goalControlFetch(record, op, body, deps) {
+    const thread = body.thread ?? "main";
+    const url = goalControlUrl(record, op, thread);
+    const headers = goalControlHeaders(record, deps.creds);
+    const init = { method: op === "show" ? "GET" : "POST", headers };
+    if (op !== "show") {
+        headers["content-type"] = "application/json";
+        init.body = JSON.stringify({ conversation_id: record.conversation_id, ...body, thread });
+    }
+    let res;
+    try {
+        res = await deps.fetch(url, init);
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        throw new GoalControlError(0, null, `could not reach ${gatewayOrigin(record.gateway_host)}: ${why}`);
+    }
+    const text = await res.text().catch(() => "");
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    if (!res.ok) {
+        const { code, message } = errorParts(parsed);
+        throw new GoalControlError(res.status, code, message ?? `HTTP ${res.status}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new GoalControlError(0, null, `unexpected non-JSON response (HTTP ${res.status})`);
+    }
+    return parsed;
+}

package/dist/lib/launcher-config.d.ts

@@ -33,6 +33,12 @@ export interface LauncherConfig {
     goalMode?: GoalModeDefault;
     /** Context folding default (on when unset; `false` disables it for every launch). */
     context?: boolean;
+    /**
+     * Context-handoff default (EXPERIMENTAL, off when unset): `true` registers the `handoff`
+     * MCP tool and sends `CONTEXT_HANDOFF_ENABLED: "true"` in the per-session config header for
+     * every launch. Off means byte-identical to a launch with no MNE-7564 change at all.
+     */
+    contextHandoff?: boolean;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;

package/dist/lib/launcher-config.js

@@ -145,6 +145,14 @@ export const CONFIG_KEYS = [
             c.context = coerceBool("context", v);
         },
     },
+    {
+        key: "context_handoff",
+        describe: "EXPERIMENTAL: register the `handoff` MCP tool + tell the gateway CONTEXT_HANDOFF_ENABLED=true (off by default)",
+        get: (c) => c.contextHandoff,
+        set: (c, v) => {
+            c.contextHandoff = coerceBool("context_handoff", v);
+        },
+    },
     {
         key: "guardrails.max_turns",
         describe: "Contract guardrail: turn ceiling (positive integer)",
@@ -213,6 +221,8 @@ export function parseLauncherConfig(text) {
         cfg.goalMode = coerceGoalMode(str(raw.goal_mode) ?? "");
     if (raw.context !== undefined)
         cfg.context = coerceBool("context", str(raw.context) ?? "");
+    if (raw.context_handoff !== undefined)
+        cfg.contextHandoff = coerceBool("context_handoff", str(raw.context_handoff) ?? "");
     const g = raw.guardrails;
     if (g !== undefined) {
         if (typeof g !== "object" || g === null || Array.isArray(g)) {
@@ -273,6 +283,8 @@ export function serializeLauncherConfig(cfg) {
         doc.goal_mode = cfg.goalMode;
     if (cfg.context !== undefined)
         doc.context = cfg.context;
+    if (cfg.contextHandoff !== undefined)
+        doc.context_handoff = cfg.contextHandoff;
     const g = cfg.guardrails;
     if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
         const gr = {};
@@ -322,4 +334,7 @@ export function applyConfigToEnv(cfg, env = process.env) {
     if (cfg.context !== undefined && !(env.MNEMOM_AGENT_CONTEXT ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT = cfg.context ? "1" : "0";
     }
+    if (cfg.contextHandoff !== undefined && !(env.MNEMOM_AGENT_CONTEXT_HANDOFF ?? "").trim()) {
+        env.MNEMOM_AGENT_CONTEXT_HANDOFF = cfg.contextHandoff ? "1" : "0";
+    }
 }

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