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

package/dist/lib/agent.js

@@ -50,6 +50,18 @@ export function resolveAnthropicDoor(env = process.env) {
 export function isProdGateway(env = process.env) {
     return resolveGatewayHost(env) === PROD_GATEWAY_HOST;
 }
+/**
+ * The gateway origin the `handoff` MCP tool's own `POST /mnemom/context/handoff` must hit —
+ * always the SAME cell the launched session's own `/v1/messages` traffic goes to. Derived from
+ * the already-resolved Anthropic `door` (scheme+host only, via `new URL(...).origin`) rather
+ * than `resolveGatewayHost` directly, because `MNEMOM_AGENT_ANTHROPIC_GATEWAY` can override the
+ * door to a DIFFERENT host than `MNEMOM_AGENT_GATEWAY`/the default (e.g. a test cell) — reading
+ * `resolveGatewayHost` here would silently send handoff calls to prod (or vice versa) while the
+ * session's model traffic went elsewhere (MNE-7564 review).
+ */
+export function resolveHandoffGatewayHost(door) {
+    return new URL(door).origin;
+}
 /**
  * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
  * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
@@ -195,6 +207,15 @@ export const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
 export const SESSION_CONFIG_HEADER = "x-mnemom-session-config";
 /** The gateway env key that gates context folding (allow-listed for per-session overlay). */
 export const CONTEXT_RUNTIME_KEY = "CONTEXT_RUNTIME_ENABLED";
+/**
+ * The gateway env key that gates the whole context-handoff capability (level lines +
+ * `/mnemom/context/handoff` route + the digest note section) for a single session
+ * (MNE-7561..7565). Off by default on the gateway; turned on ONLY when this launch's
+ * `contextHandoff` setting is true (see `resolveContextHandoff`), which also registers the
+ * `handoff` MCP tool (MNE-7564) — a session never gets the tool without the header, or the
+ * header without the tool.
+ */
+export const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
 const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
 /**
  * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
@@ -393,16 +414,76 @@ export function resolveContextFold(opts) {
     return !(raw === "0" || raw === "false" || raw === "off" || raw === "no");
 }
 /**
- * The `x-mnemom-session-config` value that turns context folding OFF, or
- * `undefined` when folding is ON (the default — nothing is sent, the gateway's
- * own default stands). base64url so it survives the gateway's inbound strip.
+ * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
+ * nothing to override (the gateway's own defaults stand — the common case). Two
+ * independent overlays, both OFF by default (folding is ON by default so only its OFF
+ * state is ever sent; handoff is OFF by default so only its ON state is ever sent):
+ *   - `fold: false` → `CONTEXT_RUNTIME_ENABLED: "false"` (`--no-context`).
+ *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
+ *     setting) — the SAME header the `handoff` MCP tool's own call to
+ *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
+ *     per request (see `commands/agent.ts` handoff MCP wiring).
+ * base64url so it survives the gateway's inbound strip.
  */
-export function buildSessionConfigB64(fold) {
-    if (fold)
+export function buildSessionConfigB64(opts) {
+    const config = {};
+    if (!opts.fold)
+        config[CONTEXT_RUNTIME_KEY] = "false";
+    if (opts.contextHandoff)
+        config[CONTEXT_HANDOFF_KEY] = "true";
+    if (Object.keys(config).length === 0)
         return undefined;
-    const payload = JSON.stringify({ v: 1, config: { [CONTEXT_RUNTIME_KEY]: "false" } });
+    const payload = JSON.stringify({ v: 1, config });
     return Buffer.from(payload, "utf8").toString("base64url");
 }
+/**
+ * Is the `handoff` MCP tool + `CONTEXT_HANDOFF_ENABLED` session-config header ON for
+ * this launch? OFF by default (operator directive, curation 2026-09-25): an absent flag
+ * and an absent `context_handoff` setting are both "off", matching `resolveContextFold`'s
+ * shape but the opposite default. Precedence: an explicit `--context-handoff`/
+ * `--no-context-handoff` flag wins, else `MNEMOM_AGENT_CONTEXT_HANDOFF` (which
+ * `applyConfigToEnv` sets from the `context_handoff` config key), else OFF.
+ */
+export function resolveContextHandoff(opts) {
+    if (opts.contextHandoff !== undefined)
+        return opts.contextHandoff;
+    const raw = (opts.env?.MNEMOM_AGENT_CONTEXT_HANDOFF ?? "").trim().toLowerCase();
+    if (raw === "")
+        return false;
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+/** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
+export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
+/**
+ * The name of the non-`ANTHROPIC_*` env var `spawnRcCli` (commands/agent.ts) adds to Claude
+ * Code's Remote Control child env, carrying the real Anthropic key, ONLY when context handoff is
+ * on. `spawnRcCli` strips every `ANTHROPIC_*` auth var (including `ANTHROPIC_CUSTOM_HEADERS`) so
+ * the RC gate sees a clean first-party-OAuth setup, but that gate only inspects the recognized
+ * `ANTHROPIC_*` base-url/key/socket family — a custom-named var rides through ungated, exactly
+ * like `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` already do for the proxy. The handoff server inherits
+ * it the same way it inherits `ANTHROPIC_CUSTOM_HEADERS` under the terminal shape.
+ */
+export const HANDOFF_RC_KEY_ENV_NAME = "MNEMOM_HANDOFF_KEY";
+/** The `--mcp-config` document registering exactly the `handoff` tool. Pure — no I/O. */
+export function buildHandoffMcpConfig(p) {
+    const env = {
+        MNEMOM_HANDOFF_GATEWAY_HOST: p.gatewayHost,
+        MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME: p.anthropicKeySource.envName,
+        MNEMOM_HANDOFF_AGENT: p.agent,
+        MNEMOM_HANDOFF_CONVERSATION_ID: p.conversationId,
+    };
+    if (p.sessionConfigB64)
+        env.MNEMOM_HANDOFF_SESSION_CONFIG = p.sessionConfigB64;
+    return {
+        mcpServers: {
+            [HANDOFF_MCP_SERVER_NAME]: { command: p.nodeBin, args: [p.serverScript], env },
+        },
+    };
+}
+/** `JSON.stringify(buildHandoffMcpConfig(p))` — the exact bytes written to the config file. */
+export function buildHandoffMcpConfigJson(p) {
+    return JSON.stringify(buildHandoffMcpConfig(p));
+}
 /**
  * Is this launch implicit-mode? Precedence, highest wins:
  *   1. an explicit flag — `--implicit` (true) or `--no-implicit` (false);

package/dist/lib/goal-api.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+import type { SessionRecord } from "./agent-ledger.js";
+export type GoalOp = "show" | "pin" | "reset";
+/**
+ * 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 declare const GOAL_THREAD_RE: RegExp;
+export declare function isValidGoalThread(thread: string): boolean;
+/** The ledger fields the control call needs. */
+export type GoalControlRecord = Pick<SessionRecord, "gateway_host" | "agent_slug" | "conversation_id">;
+export interface GoalControlCreds {
+    /** The Anthropic key the launch sent as `x-api-key`. */
+    anthropicKey: string;
+    /** The Mnemom key, only when the launch sent `x-mnemom-api-key`. */
+    mnemomKey?: string | null;
+}
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface GoalControlDeps {
+    fetch: FetchLike;
+    creds: GoalControlCreds;
+}
+export interface GoalShowBodyInput {
+    thread?: string;
+}
+export interface GoalPinBodyInput {
+    thread?: string;
+    pinned: boolean;
+}
+export interface GoalResetBodyInput {
+    thread?: string;
+    statement?: string;
+    requirements?: string[];
+}
+export interface GoalPinned {
+    at: string;
+    revision: number;
+    by: "cli";
+}
+export interface GoalHistoryEntry {
+    revision: number;
+    hash: string;
+    class: string;
+    ops: number;
+    at: string;
+    source: string | null;
+}
+export interface GoalIntentView {
+    intent_id: string;
+    revision: number;
+    contract_hash: string;
+    statement: string;
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    pinned: GoalPinned | null;
+    pending_count: number;
+    history: GoalHistoryEntry[];
+    revisions_10m: number;
+    gates_10m: number;
+    updated_at: string;
+}
+export interface GoalVerdictView {
+    verdict: string;
+    turn: number;
+    at: string;
+    superseded: boolean;
+}
+export interface GoalThreadRow {
+    thread: string;
+    role: string;
+    revision: number;
+    statement: string | null;
+    pinned: boolean;
+}
+/** `GET /mnemom/goal/intent` (cli-telemetry §1.2 plus the `thread` echo and `last_revision`). */
+export interface GoalShowResponse {
+    conversation_id: string;
+    thread: string;
+    mode: "implicit" | "sealed" | "none";
+    sealed_hash?: string;
+    intent: GoalIntentView | null;
+    verdict: GoalVerdictView | null;
+    last_revision: number;
+    threads?: GoalThreadRow[];
+}
+export interface GoalPinResponse {
+    conversation_id: string;
+    thread: string;
+    pinned: GoalPinned | null;
+    revision: number;
+}
+export interface GoalResetResponse {
+    conversation_id: string;
+    thread: string;
+    reset: true;
+    revision: number;
+    prior_revision: number;
+    intent: GoalIntentView | null;
+    verdict_superseded: boolean;
+}
+/** A non-2xx answer (status > 0) or a transport failure (status 0). Never carries key material. */
+export declare class GoalControlError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(status: number, code: string | null, message: string);
+}
+/** `https://<host>` for a bare host; a host that already names a scheme is kept (trailing / dropped). */
+export declare function gatewayOrigin(host: string): string;
+export declare const GOAL_CONTROL_PATH = "/mnemom/goal/intent";
+/** The route URL for one op (the show query carries the conversation id and thread). */
+export declare function goalControlUrl(record: GoalControlRecord, op: GoalOp, thread?: string): string;
+/** The launch's identity headers (never logged). */
+export declare function goalControlHeaders(record: GoalControlRecord, creds: GoalControlCreds): Record<string, string>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "show", body: GoalShowBodyInput, deps: GoalControlDeps): Promise<GoalShowResponse>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "pin", body: GoalPinBodyInput, deps: GoalControlDeps): Promise<GoalPinResponse>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "reset", body: GoalResetBodyInput, deps: GoalControlDeps): Promise<GoalResetResponse>;

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