@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/lib/migrate/datapack.mjs

@@ -8,11 +8,19 @@
  * confirmation of the default-fallback case. This module owns the lookup.
  *
  * Wire model: the MCP server routes by `datapack_id` parameter, not URL host.
- * `datapack_list` returns the user's visible packs; we resolve here, then the
- * orchestrator threads `datapack_id` into every subsequent `tools/call`.
+ * We resolve here, then the orchestrator threads `datapack_id` into every
+ * subsequent `tools/call`.
+ *
+ * Lookups go through `datapack_search(name=...)` and `datapack_describe`, so
+ * they cost the same for an account with 1M datapacks as for one with two.
+ * A server whose tools/list has no `datapack_search` predates it; there we
+ * fall back to scanning `datapack_list`, which is fine for the account sizes
+ * such a server can serve.
  */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const DEFAULT_DATAPACK_NAME = "meko_default_datapack";
+const NIL_CONVERSATION_ID = "00000000-0000-0000-0000-000000000000";
+const SUGGESTION_LIMIT = 10;
 
 export function isUuid(value) {
   return typeof value === "string" && UUID_RE.test(value);
@@ -50,7 +58,8 @@ export function parseDatapackList(text) {
  * Resolve the destination datapack for a migration.
  *
  * @param {object} opts
- * @param {{callTool: Function}} opts.client    Connected McpClient.
+ * @param {{callTool: Function, listTools?: Function}} opts.client
+ *                                              Connected McpClient.
  * @param {string|null} opts.requested          Raw `--datapack` value (UUID or
  *                                              name) or null for default.
  * @returns {Promise<{
@@ -68,20 +77,239 @@ export function parseDatapackList(text) {
  *   - `server-fallback`: requested=null and no default row found in the list;
  *     we let the server's own fallback chain handle it (id stays null).
  *
- * `defaultId` is the id of the `meko_default_datapack` row if visible — surfaced
- * even when `requested` is non-null so the caller can detect "user named the
- * default explicitly" and reuse the same on-disk state file.
+ * `defaultId` is the id of the `meko_default_datapack` row if visible, so the
+ * caller can detect "user named the default explicitly" and reuse the same
+ * on-disk state file. With `datapack_search`, an explicit `requested` whose
+ * datapack has another name gets `defaultId: null` without a lookup: its id
+ * can't match the default's, and skipping the lookup keeps a failure there
+ * from failing the request.
  *
  * Failure cases (`ok: false`):
- *   - `datapack_list` call failed (auth, network, server error).
- *   - response body wasn't a recognizable datapack list.
- *   - explicit override didn't match any row.
+ *   - the lookup call failed (auth, network, server error).
+ *   - response body wasn't recognizable.
+ *   - explicit override didn't match any visible datapack.
  */
 export async function resolveDestinationDatapack(opts) {
   const { client, requested } = opts;
+  if (await hasTool(client, "datapack_search")) {
+    return resolveWithSearch(client, requested);
+  }
+  return resolveWithListScan(client, requested);
+}
+
+/**
+ * Whether the server lists `name`. A client without `listTools` (a test
+ * double) or a failed tools/list reads as "no", which selects the
+ * `datapack_list` scan every server supports.
+ */
+async function hasTool(client, name) {
+  if (typeof client.listTools !== "function") return false;
+  try {
+    const names = await client.listTools();
+    return Array.isArray(names) && names.includes(name);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse a `datapack_search` response body into its rows, or return
+ * `{error}` naming what went wrong. Rows are summary rows (no credentials),
+ * but the body is still never echoed.
+ *
+ * @param {{ok: boolean, text?: string, error?: object}} res
+ * @returns {{rows: Array} | {error: string}}
+ */
+export function parseDatapackSearch(res) {
+  if (!res.ok) return { error: res.error?.message ?? "unknown" };
+  let body;
+  try {
+    body = JSON.parse(res.text ?? "");
+  } catch {
+    return { error: "unrecognized response shape" };
+  }
+  if (body && typeof body === "object" && typeof body.error === "string") {
+    const detail = typeof body.detail === "string" ? ` (${body.detail})` : "";
+    return { error: `${body.error}${detail}` };
+  }
+  if (!body || !Array.isArray(body.datapacks)) {
+    return { error: "unrecognized response shape" };
+  }
+  const rows = body.datapacks.filter(
+    (e) => e && typeof e === "object" && typeof e.datapack_id === "string",
+  );
+  return { rows };
+}
+
+function search(client, args) {
+  return client.callTool("datapack_search", {
+    conversation_id: NIL_CONVERSATION_ID,
+    ...args,
+  });
+}
+
+/**
+ * The row named exactly `name`. An owned row is requested first, with
+ * `grant: "owner"`, so a page of newer shared copies of the same name
+ * cannot hide it. If the caller owns none, the first exact match of any
+ * grant is used.
+ */
+async function findByName(client, name) {
+  const owned = parseDatapackSearch(
+    await search(client, { name, grant: "owner", limit: 100 }),
+  );
+  if (owned.error) return owned;
+  const ownedHit = owned.rows.find(
+    (d) => d.datapack_name === name && d.grant === "owner",
+  );
+  if (ownedHit) return { row: ownedHit };
+
+  const found = parseDatapackSearch(await search(client, { name, limit: 100 }));
+  if (found.error) return found;
+  const exact = found.rows.filter((d) => d.datapack_name === name);
+  return { row: exact[0] ?? null };
+}
+
+async function resolveWithSearch(client, requested) {
+  if (!requested) {
+    const def = await findByName(client, DEFAULT_DATAPACK_NAME);
+    if (def.error) {
+      return {
+        ok: false,
+        message: `datapack_search failed: ${def.error}. Cannot resolve --datapack.`,
+      };
+    }
+    const defaultRow = def.row;
+    if (defaultRow) {
+      return {
+        ok: true,
+        id: defaultRow.datapack_id,
+        name: defaultRow.datapack_name,
+        source: "default",
+        defaultId: defaultRow.datapack_id,
+      };
+    }
+    return { ok: true, id: null, name: null, source: "server-fallback", defaultId: null };
+  }
+
+  const found = await resolveRequested(client, requested);
+  if (!found.ok) return found;
+  const def = await defaultIdFor(client, requested, found.row);
+  if (def.error) {
+    return {
+      ok: false,
+      message:
+        `datapack_search failed: ${def.error}. Cannot tell whether --datapack ` +
+        `${requested} is your default datapack.`,
+    };
+  }
+  return {
+    ok: true,
+    id: found.row.datapack_id,
+    name: found.row.datapack_name ?? null,
+    source: found.source,
+    defaultId: def.id,
+  };
+}
+
+/**
+ * The id of the caller's `meko_default_datapack`, or null, for comparing with
+ * an explicitly requested datapack. A row with any other name can't be the
+ * default, so the lookup runs only when the requested datapack carries the
+ * default's name or its name is unknown. That keeps a failure in a lookup the
+ * request doesn't need from failing the request.
+ *
+ * @returns {Promise<{id: string|null} | {error: string}>}
+ */
+async function defaultIdFor(client, requested, row) {
+  const name = row.datapack_name;
+  if (typeof name === "string" && name !== DEFAULT_DATAPACK_NAME) {
+    return { id: null };
+  }
+  // findByName already resolved the default's name, owner first.
+  if (requested === DEFAULT_DATAPACK_NAME) return { id: row.datapack_id };
+  const def = await findByName(client, DEFAULT_DATAPACK_NAME);
+  if (def.error) return def;
+  return { id: def.row?.datapack_id ?? null };
+}
+
+/**
+ * Resolve an explicit `--datapack` to `{ok: true, row, source}`, or to the
+ * `{ok: false, message}` the caller returns as is.
+ */
+async function resolveRequested(client, requested) {
+  if (isUuid(requested)) {
+    const res = await client.callTool("datapack_describe", {
+      datapack_id: requested,
+      conversation_id: NIL_CONVERSATION_ID,
+    });
+    const hit = parseDescribe(res);
+    if (hit.error) {
+      return {
+        ok: false,
+        message:
+          `--datapack ${requested}: no datapack with that id is visible to ` +
+          `this API key (${hit.error}).`,
+      };
+    }
+    return { ok: true, row: hit.row, source: "flag-id" };
+  }
+
+  const byName = await findByName(client, requested);
+  if (byName.error) {
+    return {
+      ok: false,
+      message: `datapack_search failed: ${byName.error}. Cannot resolve --datapack.`,
+    };
+  }
+  if (!byName.row) {
+    const similar = parseDatapackSearch(
+      await search(client, { query: requested, limit: SUGGESTION_LIMIT }),
+    );
+    if (similar.error) {
+      return {
+        ok: false,
+        message: `datapack_search failed: ${similar.error}. Cannot resolve --datapack.`,
+      };
+    }
+    const hint = similar.rows.length
+      ? `Similar names: ${formatNames(similar.rows)}.`
+      : "No datapack name contains that text.";
+    return {
+      ok: false,
+      message:
+        `--datapack ${JSON.stringify(requested)}: no datapack with that name. ` +
+        hint,
+    };
+  }
+  return { ok: true, row: byName.row, source: "flag-name" };
+}
+
+/**
+ * Parse a `datapack_describe` body into `{row}` or `{error}`. Only the id
+ * and name are read; the body is never echoed.
+ */
+function parseDescribe(res) {
+  if (!res.ok) return { error: res.error?.message ?? "unknown" };
+  let body;
+  try {
+    body = JSON.parse(res.text ?? "");
+  } catch {
+    return { error: "unrecognized response shape" };
+  }
+  if (body && typeof body === "object" && typeof body.error === "string") {
+    return { error: body.error };
+  }
+  if (!body || typeof body.datapack_id !== "string") {
+    return { error: "unrecognized response shape" };
+  }
+  return { row: body };
+}
+
+async function resolveWithListScan(client, requested) {
   const res = await client.callTool("datapack_list", {
     scope: "read",
-    conversation_id: "00000000-0000-0000-0000-000000000000",
+    conversation_id: NIL_CONVERSATION_ID,
   });
   if (!res.ok) {
     return {
@@ -101,7 +329,7 @@ export async function resolveDestinationDatapack(opts) {
     };
   }
 
-  const defaultRow = list.find((d) => d.datapack_name === DEFAULT_DATAPACK_NAME);
+  const defaultRow = namedRow(list, DEFAULT_DATAPACK_NAME);
   const defaultId = defaultRow?.datapack_id ?? null;
 
   if (!requested) {
@@ -136,7 +364,7 @@ export async function resolveDestinationDatapack(opts) {
     };
   }
 
-  const hit = list.find((d) => d.datapack_name === requested);
+  const hit = namedRow(list, requested);
   if (!hit) {
     return {
       ok: false,
@@ -154,14 +382,24 @@ export async function resolveDestinationDatapack(opts) {
   };
 }
 
+function namedRow(list, name) {
+  const exact = list.filter((d) => d.datapack_name === name);
+  return exact.find((d) => d.grant === "owner") ?? exact[0] ?? null;
+}
+
 /**
  * Format a one-line "Available: a, b, c" hint. Names only — never ids,
  * because the underlying response can carry credentials.
  */
 function formatAvailable(list) {
-  const names = list
+  const names = formatNames(list);
+  if (!names) return "(no datapacks visible to this API key.)";
+  return `Available: ${names}.`;
+}
+
+function formatNames(list) {
+  return list
     .map((d) => d.datapack_name)
-    .filter((n) => typeof n === "string" && n.length > 0);
-  if (names.length === 0) return "(no datapacks visible to this API key.)";
-  return `Available: ${names.join(", ")}.`;
+    .filter((n) => typeof n === "string" && n.length > 0)
+    .join(", ");
 }

package/lib/migrate/id.mjs

@@ -3,6 +3,8 @@
  */
 
 import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 /**
@@ -44,7 +46,7 @@ export const COMMON_BUCKET_AGENT_ID = "meko_agent";
 
 const AGENT_ID_MAX_LEN = 64;
 const KNOWN_LOOSE_CLIENTS = new Set(["claude-desktop", "claude_desktop"]);
-const KNOWN_CODING_CLIENTS = new Set(["claude_code", "cursor", "codex", "kiro"]);
+const KNOWN_CODING_CLIENTS = new Set(["claude_code", "cursor", "codex", "kiro", "opencode"]);
 
 /**
  * Sanitize a project segment: lowercase, collapse non-`[a-z0-9-]` to `-`,
@@ -61,21 +63,125 @@ function sanitizeProjectSegment(segment) {
   return collapsed.slice(0, AGENT_ID_MAX_LEN);
 }
 
+/**
+ * The user's home directory, read fresh so tests (and shells that re-point
+ * `$HOME`) see the current value rather than a module-load snapshot.
+ *
+ * @returns {string|null}
+ */
+function homeBoundary() {
+  const fromEnv = (process.env.HOME || "").trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  try {
+    const h = os.homedir();
+    return h ? path.resolve(h) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk parents of `cwd` looking for a `.git` entry (directory for a normal
+ * checkout, file for a submodule or linked worktree). Returns the absolute
+ * repo-root path, or `null` if none is found.
+ *
+ * The walk stops at `$HOME`: a directory under home that is not itself in a
+ * repo must NOT inherit home's repo-ness. Users who keep dotfiles under git
+ * would otherwise see every scratch directory collapse into
+ * `claude_code:<username>` — the same cross-project merge MEKO-590 exists to
+ * prevent, one level up. `$HOME` itself is still a valid repo root, so a
+ * session run directly in a git-tracked home resolves normally.
+ *
+ * Sync + best-effort: any I/O error at a level just skips that level. The
+ * caller treats `null` as "outside a repo" and falls back to the bare client
+ * name, per the MEKO-590 contract.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function resolveRepoRoot(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  let dir;
+  try {
+    dir = path.resolve(cwd);
+  } catch {
+    return null;
+  }
+  const start = dir;
+  const home = homeBoundary();
+  let prev = null;
+  while (dir && dir !== prev) {
+    // A directory below a git-tracked home must not inherit home's `.git`.
+    if (home && dir === home && dir !== start) return null;
+    try {
+      fs.statSync(path.join(dir, ".git"));
+      return dir;
+    } catch {
+      // no .git here; keep walking
+    }
+    // Check home itself for `.git`, then stop. This lets a git-tracked home
+    // resolve as a repo root without allowing a non-git home to inherit a
+    // `.git` from /Users, /home, or /.
+    if (home && dir === home) return null;
+    prev = dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Repo root for a cwd that is HISTORICAL rather than live — a path recorded
+ * in an old transcript, or reverse-derived from a `~/.claude/projects/<slug>`
+ * directory name. Such a path may no longer exist (repo deleted, moved, or
+ * renamed) while its transcripts survive, so a filesystem walk is not a
+ * usable oracle.
+ *
+ * Walks first, so a repo still on disk gets the correct root. When the walk
+ * finds nothing, treats the recorded path's own basename as the project
+ * segment instead of reporting "outside a repo". That keeps each historical
+ * project in its own bucket: collapsing them all into a bare `claude_code`
+ * would re-create, inside the migrator, exactly the cross-repo merge
+ * MEKO-590 fixes in the hook.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function repoRootForHistoricalCwd(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  const live = resolveRepoRoot(cwd);
+  if (live) return live;
+  try {
+    return path.resolve(cwd);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Derive an `agent_id` for a Meko write.
  *
- * Contract:
+ * Contract (MEKO-590):
  *   - `envOverride` (typically `MEKO_AGENT_ID`) wins if non-empty.
  *   - Loose clients (Claude Desktop) → bare `claude_desktop`; no schema.
- *   - Coding clients (Claude Code, Cursor, Codex, Kiro) → `<client>:<repo-basename>`.
- *     Outside a repo (basename is empty/`.`/`/`) → bare client name to
- *     keep coding-agent traffic out of the common bucket.
+ *   - Coding clients (Claude Code, Cursor, Codex, Kiro, OpenCode) →
+ *     `<client>:<repo-basename>`, resolved by walking parents of `cwd`
+ *     for a `.git` entry. The basename is lowercased and non-`[a-z0-9-]`
+ *     runs collapse to `-`. Outside a repo (no `.git` in any ancestor,
+ *     or basename sanitizes to empty) → bare client name, so sibling
+ *     directories named `docs` / `webapp` / `src` across unrelated repos
+ *     cannot silently collapse into one agent_id.
  *   - Anything else → `meko_agent` (the common cross-project bucket).
  *
+ * The `repoRoot` opt lets callers bypass the filesystem walk when they
+ * already know the repo root (or, for Cursor's flat project-name model,
+ * want to treat a supplied name as the basename directly). Passing
+ * `repoRoot: null` explicitly is an assertion of "outside a repo".
+ *
  * @param {object} opts
  * @param {string} [opts.client]       e.g. "claude_code", "cursor", "codex", "kiro", "claude-desktop"
  * @param {string} [opts.cwd]          Absolute working directory, for coding clients
  * @param {string} [opts.envOverride]  Raw value of `MEKO_AGENT_ID`, if set
+ * @param {string|null} [opts.repoRoot] Pre-resolved repo root; bypasses the FS walk when set
  * @returns {string}
  */
 export function deriveAgentId(opts = {}) {
@@ -86,13 +192,45 @@ export function deriveAgentId(opts = {}) {
   if (KNOWN_LOOSE_CLIENTS.has(client)) return "claude_desktop";
   if (!KNOWN_CODING_CLIENTS.has(client)) return COMMON_BUCKET_AGENT_ID;
 
-  const rawBase = opts.cwd ? path.basename(opts.cwd) : "";
-  if (!rawBase || rawBase === "." || rawBase === "/") return client;
-  const project = sanitizeProjectSegment(rawBase);
+  const repoRoot = Object.prototype.hasOwnProperty.call(opts, "repoRoot")
+    ? opts.repoRoot
+    : resolveRepoRoot(opts.cwd);
+  if (!repoRoot) return client;
+  const project = sanitizeProjectSegment(path.basename(repoRoot));
   if (!project) return client;
   return `${client}:${project}`;
 }
 
+/**
+ * Derive the coding-agent id used before MEKO-590: from the cwd's leaf
+ * basename without a repo-root walk. Persisted migrator state and datapack
+ * pin filenames may still use this value, so callers use it as a compatibility
+ * alias while new sessions use `deriveAgentId`.
+ *
+ * @param {object} opts
+ * @param {string} [opts.client]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.envOverride]
+ * @returns {string}
+ */
+export function deriveLegacyAgentId(opts = {}) {
+  const override = (opts.envOverride ?? "").trim();
+  if (override) return override;
+
+  const client = (opts.client ?? "").trim();
+  if (KNOWN_LOOSE_CLIENTS.has(client)) return "claude_desktop";
+  if (!KNOWN_CODING_CLIENTS.has(client)) return COMMON_BUCKET_AGENT_ID;
+
+  let rawBase = "";
+  try {
+    rawBase = opts.cwd ? path.basename(opts.cwd) : "";
+  } catch {
+    return client;
+  }
+  const project = sanitizeProjectSegment(rawBase);
+  return project ? `${client}:${project}` : client;
+}
+
 /**
  * Back-compat alias. New code should call `deriveAgentId(...)`.
  */
@@ -101,14 +239,23 @@ export const AGENT_ID = COMMON_BUCKET_AGENT_ID;
 /**
  * @param {string} [cwd] Absolute project cwd. Required for project-scope
  *   writes; omit for user-scope writes (returns the common bucket).
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ * @param {object} [opts]
+ * @param {boolean} [opts.historical] Treat `cwd` as a recorded path.
  * @returns {string}
  */
-export function agentIdForClaude(cwd) {
+export function agentIdForClaude(cwd, opts = {}) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "claude_code",
     cwd,
     envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
   });
 }
 
@@ -122,13 +269,19 @@ export const CLAUDE_CODE_USER_AGENT_ID = COMMON_BUCKET_AGENT_ID;
 /**
  * @param {string} [cwd] Absolute project cwd (or basename — Cursor's projects
  *   live under a flat `~/.cursor/projects/<name>/`). Omit for user-scope.
+ *
+ * Cursor's persisted transcripts store a flat project name rather than a
+ * full absolute cwd, so we treat the supplied value as the repo basename
+ * directly (via `repoRoot`) instead of walking the filesystem for a `.git`
+ * that isn't there.
+ *
  * @returns {string}
  */
 export function agentIdForCursor(cwd) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "cursor",
-    cwd,
+    repoRoot: cwd,
     envOverride: process.env.MEKO_AGENT_ID,
   });
 }
@@ -137,24 +290,53 @@ export function agentIdForCursor(cwd) {
  * @param {string} [cwd] Absolute project cwd of the Codex session (from the
  *   rollout's `session_meta.payload.cwd`). Omit for user-scope writes
  *   (returns the common bucket).
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ * @param {object} [opts]
+ * @param {boolean} [opts.historical] Treat `cwd` as a recorded path.
  * @returns {string}
  */
-export function agentIdForCodex(cwd) {
+export function agentIdForCodex(cwd, opts = {}) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "codex",
     cwd,
     envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
   });
 }
 
-/** Derive the project-scoped owner used by Kiro hook capture. */
-export function agentIdForKiro(cwd) {
+/**
+ * Derive the project-scoped owner used by Kiro hook capture.
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ */
+export function agentIdForKiro(cwd, opts = {}) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "kiro",
     cwd,
     envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
+  });
+}
+
+/** Derive the project-scoped owner used by OpenCode capture and migration. */
+export function agentIdForOpenCode(cwd, opts = {}) {
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "opencode",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
   });
 }
 

package/lib/migrate/mcp-client.mjs

@@ -79,6 +79,40 @@ export class McpClient {
     }
   }
 
+  /**
+   * Names of the tools the server lists over the open session. Throws when
+   * the request fails, so callers can decide how to degrade.
+   *
+   * @param {{timeoutMs?: number}} [opts]
+   * @returns {Promise<string[]>}
+   */
+  async listTools(opts = {}) {
+    await this._acquire();
+    try {
+      const res = await jsonRpcRequest(
+        this.url,
+        { jsonrpc: "2.0", id: this._reqId++, method: "tools/list", params: {} },
+        this.apiKey,
+        this.sessionId,
+        { timeoutMs: opts.timeoutMs ?? this.timeoutMs },
+      );
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        const e = new Error(`tools/list returned HTTP ${res.statusCode}`);
+        e.statusCode = res.statusCode;
+        throw e;
+      }
+      const parsed = JSON.parse(res.body);
+      if (parsed.error) {
+        throw new Error(`tools/list error: ${parsed.error.message ?? "unknown"}`);
+      }
+      const tools = parsed.result?.tools;
+      if (!Array.isArray(tools)) throw new Error("tools/list returned no tools array");
+      return tools.map((t) => t?.name).filter((n) => typeof n === "string");
+    } finally {
+      this._release();
+    }
+  }
+
   async _callWithRetry(name, args, opts) {
     const maxRetries = opts.maxRetries ?? 3;
     let lastErr = null;
@@ -93,7 +127,31 @@ export class McpClient {
         lastErr = err;
         const code = err.statusCode;
         if (code === 401 || code === 403) {
-          // Auth is fatal; surface immediately.
+          // Auth errors are never worth retrying: the same credential will
+          // be rejected again. Whether they're fatal depends on the caller.
+          //
+          // A fire-and-forget call is one whose loss the run can absorb
+          // (conversation_add_message, memory_add). A token that expires
+          // partway through a multi-hour migration used to kill the whole
+          // run from inside one such call; now the call is dropped, the skip
+          // is recorded, and the run finishes with the gap visible.
+          //
+          // The initial auth probe is `connect()`, which does not come
+          // through here, so a bad key still aborts before any work starts.
+          if (opts.fireAndForget) {
+            this.log.warn?.("mcp_skipped_auth", {
+              tool: name,
+              statusCode: code,
+              error: err.message,
+            });
+            return {
+              ok: false,
+              skipped: true,
+              authSkipped: true,
+              statusCode: code,
+              error: { message: err.message },
+            };
+          }
           throw err;
         }
         if (attempt < maxRetries) {