@mnemom/mnemom 0.17.25 → 0.17.27

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

@@ -2,16 +2,47 @@
  * 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/routes.jsonl         every addressed routing the router made (sticky threads)
  *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/aliases/<handle>.json an operator-registered handle → session
  *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *   ~/.mnemom/slack/offsets/<session>.off how far into its inbox a session has read
+ *   ~/.mnemom/slack/pending.jsonl        messages held for a session that was not
+ *                                        listening (slack_aliases on): delivered when its
+ *                                        offset passes them, else reported undelivered
  *
- * 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.
+ * The router (one per operator machine) is the only writer of inboxes and routes;
+ * each session's listener is the only reader of its own inbox. No secret is
+ * stored here.
  */
-import { type PostRecord } from "./slack-route.js";
+import { type PostRecord, type StickyRoute } from "./slack-route.js";
 export declare function slackDir(): string;
+/** A sticky-thread route stops routing replies this long after it was made. */
+export declare const STICKY_TTL_MS: number;
+/**
+ * A message held for a session that was not listening is dropped (and its sender
+ * told it was not delivered) this long after it arrived.
+ */
+export declare const PENDING_TTL_MS: number;
 export declare function recordPost(p: PostRecord): void;
 export declare function readPosts(): PostRecord[];
+/** A routing the router made by address (mention/handle/alias), kept so the thread sticks. */
+export interface RouteRecord extends StickyRoute {
+    /** ISO time the routing was made; the record expires STICKY_TTL_MS later. */
+    at: string;
+}
+export declare function recordRoute(r: RouteRecord): void;
+/** Sticky routes still within their TTL at `now`, oldest first (capped like posts). */
+export declare function readRoutes(now?: number): RouteRecord[];
+/**
+ * The records that route thread replies: posts plus unexpired sticky routes. With
+ * `resolve`, each sticky route is re-resolved against who is live and which aliases
+ * exist now (reresolveRoutes), so a thread follows a restarted or replaced session.
+ */
+export declare function readThreadRecords(now?: number, resolve?: {
+    live: Iterable<string>;
+    aliases: Map<string, string>;
+}): PostRecord[];
 /**
  * The post `session` itself made at `ts` (optionally in `channel`), from the local
  * post index — the ownership check behind delete: a session may only remove its
@@ -26,13 +57,66 @@ export interface InboxMessage {
     user: string;
     user_name?: string;
     text: string;
-    /** How it was addressed: thread | mention | handle. */
+    /** How it was addressed: thread | mention | handle | alias. */
     via: string[];
+    /** The alias handle it was addressed to (the session may front for several). */
+    for?: string;
     /** The thread so far (parent + recent replies), when the message is a thread reply. */
     context?: string;
+    /**
+     * Set (ISO time) when the router held the message because the session was not
+     * listening. A held message older than PENDING_TTL_MS is never delivered: its
+     * sender was already told it was not.
+     */
+    queued_at?: string;
 }
+/** `messages` without the held ones that have expired (see InboxMessage.queued_at). */
+export declare function freshInbox(messages: InboxMessage[], now?: number): InboxMessage[];
 export declare function appendInbox(session: string, msg: InboxMessage): void;
 export declare function inboxPath(session: string): string;
+/** The inbox's size in bytes (0 when absent): the offset just past its last message. */
+export declare function inboxSize(session: string): number;
+/** How far into its inbox `session` has read (0 when it never saved an offset). */
+export declare function readOffset(session: string): number;
+/** `session` has read its inbox up to byte `offset`. */
+export declare function writeOffset(session: string, offset: number): void;
+/** True when `session` has saved an offset at all (it has read its inbox before). */
+export declare function hasOffset(session: string): boolean;
+/** A held message: where it came from, and the inbox offset just past it. */
+export interface PendingRecord {
+    session: string;
+    channel: string;
+    ts: string;
+    /** The thread to answer in (the message's own ts when it was not in a thread). */
+    thread_ts: string;
+    user: string;
+    /** Inbox byte offset where the held message starts. */
+    start: number;
+    /** Inbox byte offset just past the held message: read once the offset reaches it. */
+    end: number;
+    /** ISO time it was held. */
+    at: string;
+}
+export declare function recordPending(p: PendingRecord): void;
+export declare function readPending(): PendingRecord[];
+/**
+ * Where `session`'s listener must start reading to deliver what is held for it:
+ * the start of its earliest held message it has not read, or undefined when
+ * nothing unread is held (the listener then starts at the end of its inbox and
+ * reads nothing). Cost: a read of pending.jsonl, which is absent with aliases off.
+ */
+export declare function heldFrom(session: string): number | undefined;
+/**
+ * Settle the held messages at `now`: one whose session has read past it is
+ * delivered; one older than PENDING_TTL_MS that is still unread is expired; the
+ * rest stay held. Rewrites pending.jsonl with the ones still held. The router is
+ * the only caller (and the only writer of pending.jsonl).
+ */
+export declare function settlePending(now?: number): {
+    delivered: PendingRecord[];
+    expired: PendingRecord[];
+    held: PendingRecord[];
+};
 /** Messages appended after byte `offset`, and the new offset. */
 export declare function readInboxFrom(session: string, offset: number): {
     messages: InboxMessage[];
@@ -40,5 +124,22 @@ export declare function readInboxFrom(session: string, offset: number): {
 };
 export declare function registerLive(session: string, pid?: number): void;
 export declare function unregisterLive(session: string): void;
+export interface AliasRecord {
+    handle: string;
+    session: string;
+    since: string;
+}
+/**
+ * Register `handle` → `session` (idempotent; re-running with the same pair keeps the
+ * first `since`). The session need not be live: an alias is how a handle reaches a
+ * session that is launched later or restarts.
+ */
+export declare function setAlias(handle: string, session: string): AliasRecord;
+/** Remove `handle`; true when something was removed. */
+export declare function removeAlias(handle: string): boolean;
+/** Every registered alias, by handle (sorted). Corrupt files are ignored, not fatal. */
+export declare function listAliases(): AliasRecord[];
+/** normalised handle → session, the shape routeHits takes. */
+export declare function readAliases(): Map<string, string>;
 /** Sessions with a running listener; stale entries (dead pid) are pruned. */
 export declare function liveSessions(): string[];

package/dist/lib/slack-state.js

@@ -2,24 +2,42 @@
  * 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/routes.jsonl         every addressed routing the router made (sticky threads)
  *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/aliases/<handle>.json an operator-registered handle → session
  *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *   ~/.mnemom/slack/offsets/<session>.off how far into its inbox a session has read
+ *   ~/.mnemom/slack/pending.jsonl        messages held for a session that was not
+ *                                        listening (slack_aliases on): delivered when its
+ *                                        offset passes them, else reported undelivered
  *
- * 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.
+ * The router (one per operator machine) is the only writer of inboxes and routes;
+ * each session's listener is the only reader of its own inbox. No secret is
+ * stored here.
  */
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { MNEMOM_DIR } from "./config.js";
-import { normSession } from "./slack-route.js";
+import { normHandle, normSession, reresolveRoutes, } from "./slack-route.js";
 export function slackDir() {
     return join(MNEMOM_DIR, "slack");
 }
 const postsFile = () => join(slackDir(), "posts.jsonl");
+const routesFile = () => join(slackDir(), "routes.jsonl");
 const liveDir = () => join(slackDir(), "live");
+const aliasDir = () => join(slackDir(), "aliases");
 const inboxDir = () => join(slackDir(), "inbox");
+const offsetDir = () => join(slackDir(), "offsets");
+const pendingFile = () => join(slackDir(), "pending.jsonl");
 /** Only the most recent posts matter for thread routing; cap what we read. */
 const MAX_POSTS = 5000;
+/** A sticky-thread route stops routing replies this long after it was made. */
+export const STICKY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * A message held for a session that was not listening is dropped (and its sender
+ * told it was not delivered) this long after it arrived.
+ */
+export const PENDING_TTL_MS = 60 * 60 * 1000;
 function ensure(dir) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
@@ -46,6 +64,31 @@ export function recordPost(p) {
 export function readPosts() {
     return readJsonl(postsFile()).slice(-MAX_POSTS);
 }
+export function recordRoute(r) {
+    ensure(slackDir());
+    appendFileSync(routesFile(), JSON.stringify(r) + "\n", { mode: 0o600 });
+}
+/** Sticky routes still within their TTL at `now`, oldest first (capped like posts). */
+export function readRoutes(now = Date.now()) {
+    return readJsonl(routesFile())
+        .filter((r) => {
+        const at = Date.parse(r.at);
+        return Number.isFinite(at) && now - at <= STICKY_TTL_MS && now >= at;
+    })
+        .slice(-MAX_POSTS);
+}
+/**
+ * The records that route thread replies: posts plus unexpired sticky routes. With
+ * `resolve`, each sticky route is re-resolved against who is live and which aliases
+ * exist now (reresolveRoutes), so a thread follows a restarted or replaced session.
+ */
+export function readThreadRecords(now = Date.now(), resolve) {
+    const routes = readRoutes(now);
+    return [
+        ...readPosts(),
+        ...(resolve ? reresolveRoutes(routes, resolve.live, resolve.aliases) : routes),
+    ];
+}
 /**
  * The post `session` itself made at `ts` (optionally in `channel`), from the local
  * post index — the ownership check behind delete: a session may only remove its
@@ -57,6 +100,15 @@ export function findOwnPost(session, ts, channel) {
         .reverse()
         .find((p) => p.ts === ts && normSession(p.session) === me && (!channel || p.channel === channel));
 }
+/** `messages` without the held ones that have expired (see InboxMessage.queued_at). */
+export function freshInbox(messages, now = Date.now()) {
+    return messages.filter((m) => {
+        if (!m.queued_at)
+            return true;
+        const at = Date.parse(m.queued_at);
+        return Number.isFinite(at) && now - at <= PENDING_TTL_MS;
+    });
+}
 const fileFor = (session) => `${normSession(session)}`;
 export function appendInbox(session, msg) {
     ensure(inboxDir());
@@ -67,15 +119,117 @@ export function appendInbox(session, msg) {
 export function inboxPath(session) {
     return join(inboxDir(), `${fileFor(session)}.jsonl`);
 }
+/** The inbox's size in bytes (0 when absent): the offset just past its last message. */
+export function inboxSize(session) {
+    try {
+        return statSync(inboxPath(session)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+// Normalised like the inbox file name, so a session name can never escape offsets/.
+const offsetFile = (session) => join(offsetDir(), `${fileFor(session)}.off`);
+/** How far into its inbox `session` has read (0 when it never saved an offset). */
+export function readOffset(session) {
+    try {
+        return Number(readFileSync(offsetFile(session), "utf8")) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** `session` has read its inbox up to byte `offset`. */
+export function writeOffset(session, offset) {
+    ensure(offsetDir());
+    writeFileSync(offsetFile(session), String(offset), { mode: 0o600 });
+}
+/** True when `session` has saved an offset at all (it has read its inbox before). */
+export function hasOffset(session) {
+    return existsSync(offsetFile(session));
+}
+export function recordPending(p) {
+    ensure(slackDir());
+    appendFileSync(pendingFile(), JSON.stringify(p) + "\n", { mode: 0o600 });
+}
+export function readPending() {
+    return readJsonl(pendingFile());
+}
+/**
+ * Where `session`'s listener must start reading to deliver what is held for it:
+ * the start of its earliest held message it has not read, or undefined when
+ * nothing unread is held (the listener then starts at the end of its inbox and
+ * reads nothing). Cost: a read of pending.jsonl, which is absent with aliases off.
+ */
+export function heldFrom(session) {
+    if (!existsSync(pendingFile()))
+        return undefined;
+    const me = normSession(session);
+    const read = readOffset(session);
+    const size = inboxSize(session);
+    let from;
+    for (const p of readPending()) {
+        if (normSession(p.session) !== me || !(p.end > read) || p.end > size)
+            continue;
+        const s = Number.isFinite(p.start) ? Math.max(p.start, read) : read;
+        from = from === undefined ? s : Math.min(from, s);
+    }
+    return from;
+}
+/**
+ * Settle the held messages at `now`: one whose session has read past it is
+ * delivered; one older than PENDING_TTL_MS that is still unread is expired; the
+ * rest stay held. Rewrites pending.jsonl with the ones still held. The router is
+ * the only caller (and the only writer of pending.jsonl).
+ */
+export function settlePending(now = Date.now()) {
+    const delivered = [];
+    const expired = [];
+    const held = [];
+    const all = readPending();
+    if (!all.length)
+        return { delivered, expired, held };
+    for (const p of all) {
+        const at = Date.parse(p.at);
+        if (readOffset(p.session) >= p.end)
+            delivered.push(p);
+        else if (!Number.isFinite(at) || now - at > PENDING_TTL_MS)
+            expired.push(p);
+        else
+            held.push(p);
+    }
+    writeFileSync(pendingFile(), held.map((p) => JSON.stringify(p) + "\n").join(""), {
+        mode: 0o600,
+    });
+    return { delivered, expired, held };
+}
 /** 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");
+    // Open, don't check-then-open: the router appends concurrently. Read only the
+    // bytes after `offset`, never the whole history.
+    let fd;
+    try {
+        fd = openSync(inboxPath(session), "r");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { messages: [], offset: 0 };
+        throw e;
+    }
+    let chunk;
+    try {
+        const size = fstatSync(fd).size;
+        if (size < offset)
+            offset = 0; // truncated/rotated
+        const buf = Buffer.alloc(size - offset);
+        // One positional read. A short read (the file shrank under us) is safe: the
+        // offset only advances past complete lines, so the rest is read next poll.
+        const got = buf.length ? readSync(fd, buf, 0, buf.length, offset) : 0;
+        chunk = buf.subarray(0, got).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
     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")) {
@@ -106,6 +260,71 @@ function pidAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/**
+ * Register `handle` → `session` (idempotent; re-running with the same pair keeps the
+ * first `since`). The session need not be live: an alias is how a handle reaches a
+ * session that is launched later or restarts.
+ */
+export function setAlias(handle, session) {
+    const h = normHandle(handle);
+    const s = session.trim();
+    if (!h)
+        throw new Error(`alias: '${handle}' is not a usable handle (letters, digits, dashes).`);
+    if (!normSession(s))
+        throw new Error(`alias: '${session}' is not a usable session name.`);
+    ensure(aliasDir());
+    const path = join(aliasDir(), `${h}.json`);
+    const prev = readAlias(path);
+    const rec = {
+        handle: h,
+        session: s,
+        since: prev && prev.session === s ? prev.since : new Date().toISOString(),
+    };
+    writeFileSync(path, JSON.stringify(rec), { mode: 0o600 });
+    return rec;
+}
+/** Remove `handle`; true when something was removed. */
+export function removeAlias(handle) {
+    const h = normHandle(handle);
+    if (!h)
+        return false;
+    const path = join(aliasDir(), `${h}.json`);
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+function readAlias(path) {
+    try {
+        const rec = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof rec.handle === "string" && typeof rec.session === "string" && rec.session) {
+            return { handle: rec.handle, session: rec.session, since: String(rec.since ?? "") };
+        }
+    }
+    catch {
+        /* corrupt → absent */
+    }
+    return undefined;
+}
+/** Every registered alias, by handle (sorted). Corrupt files are ignored, not fatal. */
+export function listAliases() {
+    if (!existsSync(aliasDir()))
+        return [];
+    const out = [];
+    for (const f of readdirSync(aliasDir()).sort()) {
+        if (!f.endsWith(".json"))
+            continue;
+        const rec = readAlias(join(aliasDir(), f));
+        // The file name is the normalised handle; a record whose handle disagrees is ignored.
+        if (rec && `${normHandle(rec.handle)}.json` === f)
+            out.push(rec);
+    }
+    return out;
+}
+/** normalised handle → session, the shape routeHits takes. */
+export function readAliases() {
+    return new Map(listAliases().map((a) => [normHandle(a.handle), a.session]));
+}
 /** Sessions with a running listener; stale entries (dead pid) are pruned. */
 export function liveSessions() {
     if (!existsSync(liveDir()))

package/dist/lib/subscription-login.d.ts

@@ -57,10 +57,19 @@ export interface MnemomKeyDeps {
     say(line: string): void;
 }
 /**
- * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
- * key, else mint one (gateway scope only) and store it. The key is never printed.
+ * The Mnemom key this machine already has — MNEMOM_AGENT_MNEMOM_KEY, else the stored key — or
+ * undefined. NEVER mints. An unpinned api-key launch sends it (`x-mnemom-api-key`) alongside its
+ * Anthropic key when there is one, so the gateway can serve the key owner's claimed agent of that
+ * name instead of a fresh one per rotated Anthropic key; with none it launches exactly as before.
  */
-export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps): Promise<string>;
+export declare function readMnemomKey(deps: Pick<MnemomKeyDeps, "env" | "readStored">): string | undefined;
+/**
+ * The Mnemom key a subscription launch (or a pinned launch, which the gateway honours only with
+ * a verified Mnemom key) sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored key, else mint one
+ * (gateway scope only) and store it. The key is never printed. `purpose` names why in the
+ * one-line notes ("subscription login" by default).
+ */
+export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps, purpose?: string): Promise<string>;
 /**
  * Remote Control on a subscription login is open to accounts entitled to Remote Control
  * (internal Mnemom accounts): the RC proxy then forwards the user's own OAuth bearer to the

package/dist/lib/subscription-login.js

@@ -72,30 +72,42 @@ export function resolveAgentAuth(flag, env) {
     return fromEnv ? coerceAgentAuth(fromEnv) : "api-key";
 }
 /**
- * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
- * key, else mint one (gateway scope only) and store it. The key is never printed.
+ * The Mnemom key this machine already has — MNEMOM_AGENT_MNEMOM_KEY, else the stored key — or
+ * undefined. NEVER mints. An unpinned api-key launch sends it (`x-mnemom-api-key`) alongside its
+ * Anthropic key when there is one, so the gateway can serve the key owner's claimed agent of that
+ * name instead of a fresh one per rotated Anthropic key; with none it launches exactly as before.
  */
-export async function resolveSubscriptionMnemomKey(deps) {
+export function readMnemomKey(deps) {
     const fromEnv = headerSafe(deps.env[MNEMOM_KEY_ENV] ?? "");
     if (fromEnv)
         return fromEnv;
     const stored = headerSafe(deps.readStored() ?? "");
-    if (stored)
-        return stored;
+    return stored || undefined;
+}
+/**
+ * The Mnemom key a subscription launch (or a pinned launch, which the gateway honours only with
+ * a verified Mnemom key) sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored key, else mint one
+ * (gateway scope only) and store it. The key is never printed. `purpose` names why in the
+ * one-line notes ("subscription login" by default).
+ */
+export async function resolveSubscriptionMnemomKey(deps, purpose = "subscription login") {
+    const existing = readMnemomKey(deps);
+    if (existing)
+        return existing;
     let minted;
     try {
         minted = headerSafe(await deps.mint());
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`mnemom agent: subscription login needs a Mnemom API key and minting one failed (${msg}).\n` +
+        throw new Error(`mnemom agent: ${purpose} needs a Mnemom API key and minting one failed (${msg}).\n` +
             `  Create one with \`mnemom api-key create --name mnemom-agent --scopes gateway\` and set ${MNEMOM_KEY_ENV}.`, { cause: err });
     }
     if (!minted)
         throw new Error("mnemom agent: the API returned an empty Mnemom key.");
     try {
         deps.store(minted);
-        deps.say("mnemom agent: minted a gateway-only Mnemom API key for subscription login (saved to ~/.mnemom/launcher.json, 0600).");
+        deps.say(`mnemom agent: minted a gateway-only Mnemom API key for ${purpose} (saved to ~/.mnemom/launcher.json, 0600).`);
     }
     catch {
         deps.say("mnemom agent: minted a gateway-only Mnemom API key for this launch but could not save it — the next launch mints another.");

package/dist/mcp/handoff-server.mjs

@@ -85,11 +85,31 @@ function resolveKeyFromEnvName(name, env) {
   return value.trim();
 }
 
+/** A full Mnemom agent id (mirrors AGENT_ID_RE in cli/src/lib/agent.ts). */
+const AGENT_ID_RE = /^mnm-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * The Mnemom key the launch's own requests carry, when it has one: the `x-mnemom-api-key:` line
+ * of the inherited `ANTHROPIC_CUSTOM_HEADERS` (terminal), else the dedicated
+ * `MNEMOM_HANDOFF_MNEMOM_KEY` the Remote Control launcher sets. "" when there is none. A pinned
+ * call needs it: the gateway honours `x-mnemom-agent-id` only with a verified Mnemom key.
+ * @param {string} keyEnvName
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function resolveMnemomKey(keyEnvName, env) {
+  if (keyEnvName === "ANTHROPIC_CUSTOM_HEADERS") {
+    const m = (env.ANTHROPIC_CUSTOM_HEADERS ?? "").match(/^x-mnemom-api-key:\s*(.+)$/im);
+    return m ? m[1].trim() : "";
+  }
+  return (env.MNEMOM_HANDOFF_MNEMOM_KEY ?? "").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}}
+ * @returns {{gatewayHost: string, anthropicKey: string, mnemomKey?: string, agent: string, agentId?: string, conversationId: string, sessionConfigB64?: string}}
  */
 export function configFromEnv(env) {
   const missing = REQUIRED_ENV.filter((k) => !(env[k] ?? "").trim());
@@ -104,10 +124,16 @@ export function configFromEnv(env) {
         "process's own inherited environment has no usable value for it.",
     );
   }
+  const agentId = (env.MNEMOM_HANDOFF_AGENT_ID ?? "").trim().toLowerCase();
+  if (agentId && !AGENT_ID_RE.test(agentId)) {
+    throw new Error("mnemom-handoff: MNEMOM_HANDOFF_AGENT_ID is not a full mnm-<uuid> agent id.");
+  }
   return {
     gatewayHost: env.MNEMOM_HANDOFF_GATEWAY_HOST.trim(),
     anthropicKey,
+    mnemomKey: resolveMnemomKey(keyEnvName, env) || undefined,
     agent: env.MNEMOM_HANDOFF_AGENT.trim(),
+    agentId: agentId || undefined,
     conversationId: env.MNEMOM_HANDOFF_CONVERSATION_ID.trim(),
     sessionConfigB64: env.MNEMOM_HANDOFF_SESSION_CONFIG?.trim() || undefined,
   };
@@ -115,7 +141,7 @@ export function configFromEnv(env) {
 
 /**
  * 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 {{gatewayHost: string, anthropicKey: string, mnemomKey?: string, agent: string, agentId?: string, conversationId: string, sessionConfigB64?: string}} cfg
  * @param {string} note
  */
 export function buildHandoffRequest(cfg, note) {
@@ -124,6 +150,8 @@ export function buildHandoffRequest(cfg, note) {
     "x-api-key": cfg.anthropicKey,
     "x-mnemom-agent": cfg.agent,
   };
+  if (cfg.mnemomKey) headers["x-mnemom-api-key"] = cfg.mnemomKey;
+  if (cfg.agentId) headers["x-mnemom-agent-id"] = cfg.agentId;
   if (cfg.sessionConfigB64) headers["x-mnemom-session-config"] = cfg.sessionConfigB64;
   return {
     url: `${cfg.gatewayHost.replace(/\/+$/, "")}${HANDOFF_PATH}`,
@@ -150,7 +178,7 @@ function extractGatewayError(body) {
  * 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 {{gatewayHost: string, anthropicKey: string, mnemomKey?: string, agent: string, agentId?: string, conversationId: string, sessionConfigB64?: string}} cfg
  * @param {string} note
  * @param {typeof fetch} fetchImpl
  */

package/dist/rc-proxy.mjs

@@ -62,6 +62,9 @@
 // CONFIG (env, none secret)
 //   MNEMOM_AGENT_RC_DOOR              gateway door URL (required), e.g. https://gateway.mnemom.ai/anthropic
 //   MNEMOM_AGENT_RC_AGENT             x-mnemom-agent value (required)
+//   MNEMOM_AGENT_RC_AGENT_ID          x-mnemom-agent-id value (optional; a full mnm-<uuid> pin — the
+//                                  gateway then serves exactly that agent or refuses; needs the
+//                                  Mnemom key on stdin line 2)
 //   MNEMOM_AGENT_RC_CONVERSATION_ID   x-mnemom-conversation-id value (required)
 //   MNEMOM_AGENT_RC_CONTRACT_B64      base64 contract for x-mnemom-contract (optional)
 //   MNEMOM_AGENT_RC_GOAL_MODE         x-mnemom-goal-mode value (optional; `--implicit` — no contract,
@@ -111,6 +114,12 @@ try {
 }
 if (GATEWAY.protocol !== "https:") die("MNEMOM_AGENT_RC_DOOR must be https");
 const AGENT = env.MNEMOM_AGENT_RC_AGENT || die("MNEMOM_AGENT_RC_AGENT is required");
+const AGENT_ID = (env.MNEMOM_AGENT_RC_AGENT_ID || "").trim().toLowerCase();
+if (
+  AGENT_ID &&
+  !/^mnm-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(AGENT_ID)
+)
+  die("MNEMOM_AGENT_RC_AGENT_ID must be a full mnm-<uuid> agent id");
 const CONV =
   env.MNEMOM_AGENT_RC_CONVERSATION_ID || die("MNEMOM_AGENT_RC_CONVERSATION_ID is required");
 const CONTRACT_B64 = env.MNEMOM_AGENT_RC_CONTRACT_B64 || "";
@@ -168,6 +177,8 @@ try {
 } catch {
   die("expected three lines of secrets on stdin (anthropic, mnemom, openai)");
 }
+if (AGENT_ID && !secrets.mnemom)
+  die("a pinned agent (MNEMOM_AGENT_RC_AGENT_ID) needs the Mnemom key (stdin line 2)");
 if (SUBSCRIPTION) {
   if (!secrets.mnemom) die("subscription login needs the Mnemom key (stdin line 2)");
 } else if (!secrets.anthropic) die("the Anthropic key (stdin line 1) is empty");
@@ -519,6 +530,9 @@ function handle(req, res, viaPlain) {
       headers["x-api-key"] = secrets.anthropic;
     }
     headers["x-mnemom-agent"] = AGENT;
+    // The pin is this proxy's to state: a client-supplied one is dropped, like x-mnemom-turn.
+    delete headers["x-mnemom-agent-id"];
+    if (AGENT_ID) headers["x-mnemom-agent-id"] = AGENT_ID;
     headers["x-mnemom-conversation-id"] = CONV;
     if (secrets.mnemom) headers["x-mnemom-api-key"] = secrets.mnemom;
     if (PROVIDER) headers["x-mnemom-provider"] = PROVIDER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.25",
+  "version": "0.17.27",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {