@pi-archimedes/mcp 2.3.0

package/src/metadata-cache.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ServerDef, ServerCacheEntry } from "./types.js";
+import { CACHE_VERSION, CACHE_MAX_AGE_MS } from "./types.js";
+
+const {
+  computeServerHash,
+  loadMetadataCache,
+  saveServerCache,
+  isServerCacheValid,
+  getCachedTools,
+  getCachedPrompts,
+  recordServerOutcome,
+  setCachePathForTest,
+} = await import("./metadata-cache.js");
+
+let tempDir: string;
+let cachePath: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "mcp-cache-test-"));
+  cachePath = join(tempDir, "mcp-cache.json");
+  setCachePathForTest(cachePath);
+});
+
+afterEach(() => {
+  setCachePathForTest(null);
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+const baseStdioDef: ServerDef = {
+  type: "stdio",
+  command: "node",
+  args: ["--experimental", "server.js"],
+  env: { API_KEY: "abc" },
+  cwd: "/tmp/work",
+  protocolVersion: "2025-03-26",
+  includeTools: ["a", "b"],
+  excludeTools: ["c"],
+  exposeResources: true,
+};
+
+const baseHttpDef: ServerDef = {
+  type: "http",
+  url: "https://example.com/mcp",
+  auth: { token: "tok" },
+  headers: { "X-Api": "1" },
+  bearerTokenEnv: "BEARER_TOKEN",
+  protocolVersion: "2025-03-26",
+};
+
+describe("computeServerHash", () => {
+  it("is stable across key order (stdio)", () => {
+    const reordered: ServerDef = {
+      exposeResources: true,
+      env: { API_KEY: "abc" },
+      type: "stdio",
+      command: "node",
+      includeTools: ["a", "b"],
+      protocolVersion: "2025-03-26",
+      args: ["--experimental", "server.js"],
+      cwd: "/tmp/work",
+      excludeTools: ["c"],
+    };
+    expect(computeServerHash(reordered)).toBe(computeServerHash(baseStdioDef));
+  });
+
+  it("is stable across key order (http, nested object key order)", () => {
+    const reordered: ServerDef = {
+      bearerTokenEnv: "BEARER_TOKEN",
+      url: "https://example.com/mcp",
+      type: "http",
+      headers: { "X-Api": "1" },
+      protocolVersion: "2025-03-26",
+      auth: { token: "tok" },
+    };
+    expect(computeServerHash(reordered)).toBe(computeServerHash(baseHttpDef));
+  });
+
+  it("changes when command changes", () => {
+    const changed: ServerDef = { ...baseStdioDef, command: "python3" };
+    expect(computeServerHash(changed)).not.toBe(computeServerHash(baseStdioDef));
+  });
+
+  it("changes when url changes (http)", () => {
+    const changed: ServerDef = { ...baseHttpDef, url: "https://other.com/mcp" };
+    expect(computeServerHash(changed)).not.toBe(computeServerHash(baseHttpDef));
+  });
+
+  it("does NOT change for runtime settings", () => {
+    const withRuntime: ServerDef = {
+      ...baseStdioDef,
+      lifecycle: "lazy-keep-alive",
+      idleTimeout: 0,
+      requestTimeoutMs: 5000,
+      directTools: true,
+      toolPrefix: "none",
+      debug: true,
+    };
+    expect(computeServerHash(withRuntime)).toBe(computeServerHash(baseStdioDef));
+  });
+
+  it("does NOT change for registration-only / inert fields (protocolVersion, includeTools, excludeTools, exposeResources)", () => {
+    const changed: ServerDef = {
+      ...baseStdioDef,
+      protocolVersion: "2025-06-18",
+      includeTools: ["z"],
+      excludeTools: ["w", "x"],
+      exposeResources: false,
+    };
+    expect(computeServerHash(changed)).toBe(computeServerHash(baseStdioDef));
+  });
+
+  it("changes when headers change (http)", () => {
+    const changed: ServerDef = { ...baseHttpDef, headers: { "X-Api": "2" } };
+    expect(computeServerHash(changed)).not.toBe(computeServerHash(baseHttpDef));
+  });
+
+  it("changes when bearerTokenEnv changes (http)", () => {
+    const changed: ServerDef = { ...baseHttpDef, bearerTokenEnv: "OTHER_TOKEN" };
+    expect(computeServerHash(changed)).not.toBe(computeServerHash(baseHttpDef));
+  });
+
+  it("returns a 64-char hex sha-256 digest", () => {
+    expect(computeServerHash(baseStdioDef)).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+function validEntry(def: ServerDef): ServerCacheEntry {
+  return {
+    configHash: computeServerHash(def),
+    tools: [{ name: "t1", inputSchema: {} }],
+    resources: [],
+    cachedAt: Date.now(),
+  };
+}
+
+describe("isServerCacheValid", () => {
+  it("is true for a matching, fresh entry", () => {
+    expect(isServerCacheValid(baseStdioDef, validEntry(baseStdioDef))).toBe(true);
+  });
+
+  it("is false for an undefined entry", () => {
+    expect(isServerCacheValid(baseStdioDef, undefined)).toBe(false);
+  });
+
+  it("is false on hash mismatch (config changed)", () => {
+    const changed: ServerDef = { ...baseStdioDef, command: "python3" };
+    expect(isServerCacheValid(changed, validEntry(baseStdioDef))).toBe(false);
+  });
+
+  it("is false when older than CACHE_MAX_AGE_MS", () => {
+    const stale: ServerCacheEntry = {
+      ...validEntry(baseStdioDef),
+      cachedAt: Date.now() - CACHE_MAX_AGE_MS - 1000,
+    };
+    expect(isServerCacheValid(baseStdioDef, stale)).toBe(false);
+  });
+
+  it("is true just under CACHE_MAX_AGE_MS", () => {
+    const fresh: ServerCacheEntry = {
+      ...validEntry(baseStdioDef),
+      cachedAt: Date.now() - CACHE_MAX_AGE_MS + 60_000,
+    };
+    expect(isServerCacheValid(baseStdioDef, fresh)).toBe(true);
+  });
+});
+
+describe("loadMetadataCache", () => {
+  it("returns empty structure when file is missing", () => {
+    expect(loadMetadataCache()).toEqual({ version: CACHE_VERSION, servers: {} });
+  });
+
+  it("returns empty structure on corrupt JSON", () => {
+    writeFileSync(cachePath, "{not json", "utf-8");
+    expect(loadMetadataCache()).toEqual({ version: CACHE_VERSION, servers: {} });
+  });
+
+  it("returns empty structure on version mismatch", () => {
+    writeFileSync(
+      cachePath,
+      JSON.stringify({ version: 999, servers: { a: validEntry(baseStdioDef) } }),
+      "utf-8",
+    );
+    expect(loadMetadataCache()).toEqual({ version: CACHE_VERSION, servers: {} });
+  });
+});
+
+describe("saveServerCache + loadMetadataCache round-trip", () => {
+  it("persists a server entry with computed hash and timestamp", () => {
+    saveServerCache("srv1", baseStdioDef, {
+      tools: [{ name: "t1", description: "d", inputSchema: { type: "object" } }],
+      resources: [],
+      prompts: [],
+    });
+    const cache = loadMetadataCache();
+    const entry = cache.servers["srv1"];
+    expect(entry).toBeDefined();
+    expect(entry?.configHash).toBe(computeServerHash(baseStdioDef));
+    expect(entry?.cachedAt).toBeGreaterThan(Date.now() - 5000);
+    expect(entry?.tools).toEqual([{ name: "t1", description: "d", inputSchema: { type: "object" } }]);
+  });
+
+  it("merges without clobbering other servers (read-merge-write)", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [] });
+    saveServerCache("srv2", baseHttpDef, { tools: [], resources: [], prompts: [] });
+    const cache = loadMetadataCache();
+    expect(Object.keys(cache.servers).sort()).toEqual(["srv1", "srv2"]);
+  });
+
+  it("writes atomically (no leftover tmp file)", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [] });
+    expect(existsSync(cachePath)).toBe(true);
+    expect(existsSync(join(tempDir, "mcp-cache.json.tmp"))).toBe(false);
+    // File content must be valid JSON (not a partial write)
+    expect(() => JSON.parse(readFileSync(cachePath, "utf-8"))).not.toThrow();
+  });
+});
+
+describe("getCachedPrompts", () => {
+  it("returns cached prompts for a valid entry", () => {
+    const prompts = [{ name: "p1", description: "d" }];
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts });
+    expect(getCachedPrompts("srv1", baseStdioDef)).toEqual(prompts);
+  });
+
+  it("returns undefined when the entry is stale (hash mismatch)", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [{ name: "p1" }] });
+    const changed: ServerDef = { ...baseStdioDef, command: "python3" };
+    expect(getCachedPrompts("srv1", changed)).toBeUndefined();
+  });
+
+  it("returns undefined when the entry has no prompts", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [] });
+    expect(getCachedPrompts("srv1", baseStdioDef)).toBeUndefined();
+  });
+
+  it("returns undefined when the server is not in the cache", () => {
+    expect(getCachedPrompts("missing", baseStdioDef)).toBeUndefined();
+  });
+});
+
+describe("recordServerOutcome (ADR 0004)", () => {
+  it("persists an outcome with a timestamp and the error text", () => {
+    const before = Date.now();
+    recordServerOutcome("srv1", "needs-auth", "unauthorized");
+    const entry = loadMetadataCache().serverStatuses?.["srv1"];
+    expect(entry).toEqual({ status: "needs-auth", error: "unauthorized", at: expect.any(Number) });
+    expect(entry!.at).toBeGreaterThanOrEqual(before);
+    expect(entry!.at).toBeLessThanOrEqual(Date.now() + 1);
+  });
+
+  it("stores no error field when none is given (exactOptionalPropertyTypes-safe)", () => {
+    recordServerOutcome("srv1", "connected");
+    const entry = loadMetadataCache().serverStatuses?.["srv1"];
+    expect(entry).toEqual({ status: "connected", at: expect.any(Number) });
+    expect("error" in (entry ?? {})).toBe(false);
+  });
+
+  it("keeps other servers' outcomes on re-record (read-merge-write)", () => {
+    recordServerOutcome("srv1", "connected");
+    recordServerOutcome("srv2", "error", "boom");
+    const statuses = loadMetadataCache().serverStatuses ?? {};
+    expect(statuses["srv1"]?.status).toBe("connected");
+    expect(statuses["srv2"]?.status).toBe("error");
+  });
+
+  it("is idempotent per server (last write wins)", () => {
+    recordServerOutcome("srv1", "connected");
+    recordServerOutcome("srv1", "error", "ECONNREFUSED");
+    expect(loadMetadataCache().serverStatuses?.["srv1"]?.status).toBe("error");
+  });
+});
+
+describe("serverStatuses round-trip (ADR 0004 data-loss trap)", () => {
+  it("saveServerCache preserves a previously recorded outcome", () => {
+    recordServerOutcome("srv1", "needs-auth", "unauthorized");
+    saveServerCache("srv1", baseStdioDef, { tools: [{ name: "t1", inputSchema: {} }], resources: [] });
+    const cache = loadMetadataCache();
+    expect(cache.serverStatuses?.["srv1"]?.status).toBe("needs-auth");
+    expect(cache.servers["srv1"]).toBeDefined();
+  });
+
+  it("recordServerOutcome preserves previously saved server entries", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [{ name: "t1", inputSchema: {} }], resources: [] });
+    recordServerOutcome("srv1", "connected");
+    expect(getCachedTools("srv1", baseStdioDef)).toEqual([{ name: "t1", inputSchema: {} }]);
+  });
+
+  it("both fields survive alternating save/record cycles", () => {
+    recordServerOutcome("srv1", "error", "one");
+    saveServerCache("srv2", baseHttpDef, { tools: [], resources: [] });
+    recordServerOutcome("srv2", "needs-auth");
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [] });
+    const cache = loadMetadataCache();
+    expect(cache.serverStatuses?.["srv1"]?.status).toBe("error");
+    expect(cache.serverStatuses?.["srv2"]?.status).toBe("needs-auth");
+    expect(Object.keys(cache.servers).sort()).toEqual(["srv1", "srv2"]);
+  });
+
+  it("loads serverStatuses from a hand-written file (backwards-compatible load)", () => {
+    writeFileSync(
+      cachePath,
+      JSON.stringify({
+        version: CACHE_VERSION,
+        servers: {},
+        serverStatuses: { srv1: { status: "needs-auth", at: Date.now() - 60_000 } },
+      }),
+      "utf-8",
+    );
+    expect(loadMetadataCache().serverStatuses?.["srv1"]?.status).toBe("needs-auth");
+  });
+
+  it("still loads a legacy file without serverStatuses", () => {
+    writeFileSync(cachePath, JSON.stringify({ version: CACHE_VERSION, servers: {} }), "utf-8");
+    const cache = loadMetadataCache();
+    expect(cache).toEqual({ version: CACHE_VERSION, servers: {} });
+    expect(cache.serverStatuses).toBeUndefined();
+  });
+
+  it("drops malformed individual entries instead of crashing", () => {
+    writeFileSync(
+      cachePath,
+      JSON.stringify({
+        version: CACHE_VERSION,
+        servers: {},
+        serverStatuses: {
+          good: { status: "connected", at: 123 },
+          badStatus: { status: "bogus", at: 123 },
+          noAt: { status: "connected" },
+        },
+      }),
+      "utf-8",
+    );
+    expect(Object.keys(loadMetadataCache().serverStatuses ?? {})).toEqual(["good"]);
+  });
+});
+
+describe("getCachedTools", () => {
+  it("returns cached tools for a valid entry", () => {
+    const tools = [{ name: "t1", description: "d", inputSchema: {} }];
+    saveServerCache("srv1", baseStdioDef, { tools, resources: [], prompts: [] });
+    expect(getCachedTools("srv1", baseStdioDef)).toEqual(tools);
+  });
+
+  it("returns undefined when the entry is stale (hash mismatch)", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [] });
+    const changed: ServerDef = { ...baseStdioDef, command: "python3" };
+    expect(getCachedTools("srv1", changed)).toBeUndefined();
+  });
+
+  it("returns undefined when the entry is older than CACHE_MAX_AGE_MS", () => {
+    saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [] });
+    // Age the entry directly on disk
+    const cache = loadMetadataCache();
+    const entry = cache.servers["srv1"];
+    if (entry) entry.cachedAt = Date.now() - CACHE_MAX_AGE_MS - 1;
+    writeFileSync(cachePath, JSON.stringify(cache), "utf-8");
+    expect(getCachedTools("srv1", baseStdioDef)).toBeUndefined();
+  });
+
+  it("returns undefined when the server is not in the cache", () => {
+    expect(getCachedTools("missing", baseStdioDef)).toBeUndefined();
+  });
+});
+
+describe("cache path override", () => {
+  it("honors the MCP_CACHE_PATH env var when no test path is set", () => {
+    const envPath = join(tempDir, "env-cache.json");
+    setCachePathForTest(null);
+    process.env.MCP_CACHE_PATH = envPath;
+    try {
+      saveServerCache("srv1", baseStdioDef, { tools: [], resources: [], prompts: [] });
+      expect(readFileSync(envPath, "utf-8")).toContain("srv1");
+      expect(getCachedTools("srv1", baseStdioDef)).toEqual([]);
+    } finally {
+      delete process.env.MCP_CACHE_PATH;
+      setCachePathForTest(cachePath);
+    }
+  });
+});

package/src/metadata-cache.ts

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ServerDef, MetadataCache, ServerCacheEntry, CachedTool, ServerOutcomeRecord } from "./types.js";
+import { CACHE_VERSION, CACHE_MAX_AGE_MS } from "./types.js";
+import type { ServerStatus } from "./server-client.js";
+
+/** Test override — null means "use MCP_CACHE_PATH env var or the default path" */
+let testCachePath: string | null = null;
+
+/**
+ * Override the cache file path (for tests). Pass null to reset.
+ * Tests must use this so the real ~/.pi/agent/mcp-cache.json is never touched.
+ */
+export function setCachePathForTest(path: string | null): void {
+  testCachePath = path;
+}
+
+/** Default cache location: ~/.pi/agent/mcp-cache.json (MCP_CACHE_PATH overrides) */
+function cachePath(): string {
+  if (testCachePath) return testCachePath;
+  const env = process.env.MCP_CACHE_PATH;
+  if (env) return env;
+  return join(getAgentDir(), "mcp-cache.json");
+}
+
+/**
+ * Project a ServerDef to only the identity-affecting fields — the fields
+ * that change WHAT the server is (connection + auth), not HOW it is managed.
+ * ServerDef is a discriminated union — narrow via "command" in def / "url" in def
+ * before accessing transport-specific fields. Runtime settings (lifecycle,
+ * idleTimeout, debug, directTools, toolPrefix, requestTimeoutMs, disabled)
+ * are deliberately excluded: changing them must not invalidate the cache.
+ * Likewise excluded: protocolVersion (documented inert), exposeResources
+ * (not yet implemented), and includeTools/excludeTools (they only filter
+ * DIRECT-tool registration, never the cached tool list) — toggling any of
+ * those must not invalidate the cache or trigger a client close+replace.
+ */
+function projectIdentity(def: ServerDef): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if ("command" in def) {
+    out.command = def.command;
+    if (def.args !== undefined) out.args = def.args;
+    if (def.env !== undefined) out.env = def.env;
+    if (def.cwd !== undefined) out.cwd = def.cwd;
+  }
+  if ("url" in def) {
+    out.url = def.url;
+    if (def.auth !== undefined) out.auth = def.auth;
+    if (def.headers !== undefined) out.headers = def.headers;
+    if (def.bearerTokenEnv !== undefined) out.bearerTokenEnv = def.bearerTokenEnv;
+  }
+  return out;
+}
+
+/** Deterministic JSON: object keys sorted recursively, undefined values dropped */
+function stableStringify(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const parts = Object.keys(obj)
+      .sort()
+      .filter((k) => obj[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  // string / number / boolean
+  return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * SHA-256 hex digest over the identity-affecting fields only, stable-stringified
+ * (sorted keys) so key order in the config file does not change the hash.
+ */
+export function computeServerHash(def: ServerDef): string {
+  return createHash("sha256")
+    .update(stableStringify(projectIdentity(def)))
+    .digest("hex");
+}
+
+function emptyCache(): MetadataCache {
+  return { version: CACHE_VERSION, servers: {} };
+}
+
+function isServerOutcomeRecord(v: unknown): v is ServerOutcomeRecord {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return (
+    (o.status === "connected" || o.status === "needs-auth" || o.status === "error") &&
+    typeof o.at === "number" &&
+    (o.error === undefined || typeof o.error === "string")
+  );
+}
+
+/** Keep only well-formed outcome entries; a garbage field must not sink the whole cache. */
+function sanitizeServerStatuses(raw: unknown): Record<string, ServerOutcomeRecord> | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const kept: Record<string, ServerOutcomeRecord> = {};
+  for (const [name, v] of Object.entries(raw)) {
+    if (isServerOutcomeRecord(v)) kept[name] = v;
+  }
+  return Object.keys(kept).length > 0 ? kept : undefined;
+}
+
+/** Load the metadata cache; returns an empty valid structure on missing/corrupt file or version mismatch. */
+export function loadMetadataCache(): MetadataCache {
+  const path = cachePath();
+  if (!existsSync(path)) return emptyCache();
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    if (typeof raw !== "object" || raw === null) return emptyCache();
+    const obj = raw as { version?: unknown; servers?: unknown; [key: string]: unknown };
+    if (
+      obj.version !== CACHE_VERSION ||
+      typeof obj.servers !== "object" ||
+      obj.servers === null ||
+      Array.isArray(obj.servers)
+    ) {
+      return emptyCache();
+    }
+    const cache: MetadataCache = {
+      version: CACHE_VERSION,
+      servers: obj.servers as Record<string, ServerCacheEntry>,
+    };
+    // ADR 0004 round-trip: preserve the persisted connection outcomes. The
+    // pre-fix reconstruction dropped this field, so every saveServerCache
+    // rewrite silently erased it (the data-loss trap).
+    const statuses = sanitizeServerStatuses(obj.serverStatuses);
+    if (statuses !== undefined) cache.serverStatuses = statuses;
+    return cache;
+  } catch {
+    return emptyCache();
+  }
+}
+
+/** Atomic write: tmp file + rename in the same directory. */
+function writeCacheFile(cache: MetadataCache): void {
+  const path = cachePath();
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cache, null, 2), "utf-8");
+  renameSync(tmp, path);
+}
+
+/**
+ * Read-merge-write: merge one server's entry into the on-disk cache.
+ * Any `serverStatuses` present in the on-disk file survive the rewrite
+ * (ADR 0004 round-trip — the load+save paths must never drop each other's
+ * field). Atomic via tmp file + rename in the same directory.
+ */
+export function saveServerCache(
+  serverName: string,
+  def: ServerDef,
+  entry: Omit<ServerCacheEntry, "configHash" | "cachedAt">,
+): void {
+  const cache = loadMetadataCache();
+  cache.servers = {
+    ...cache.servers,
+    [serverName]: {
+      ...entry,
+      configHash: computeServerHash(def),
+      cachedAt: Date.now(),
+    },
+  };
+  writeCacheFile(cache);
+}
+
+/**
+ * The SINGLE recorder for persisted connection outcomes (ADR 0004).
+ * Every connection settle point (session_start background probe, on-demand
+ * connect, reconnect) calls this — never touches the cache file directly,
+ * so the write path stays in one place. Best-effort: a cache write failure
+ * must never break the settle itself (same convention as saveServerCache).
+ */
+export function recordServerOutcome(
+  serverName: string,
+  status: ServerOutcomeRecord["status"],
+  error?: string,
+): void {
+  try {
+    const cache = loadMetadataCache();
+    const entry: ServerOutcomeRecord = { status, at: Date.now() };
+    // Status lines are single-line; multi-line errors keep their first line
+    const firstLine = error?.split("\n")[0]?.trim();
+    if (firstLine !== undefined && firstLine.length > 0) entry.error = firstLine;
+    cache.serverStatuses = { ...(cache.serverStatuses ?? {}), [serverName]: entry };
+    writeCacheFile(cache);
+  } catch (e) {
+    console.warn(
+      `[archimedes/mcp] Failed to record outcome for "${serverName}": ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}
+
+/**
+ * Settle-point convenience: map a finished ServerClient onto its recorded
+ * outcome. A client that is "disconnected"/"connecting" has no verified
+ * outcome (e.g. a generation-fenced connect that resolved empty) — nothing
+ * is recorded for those.
+ */
+export function recordClientOutcome(client: { name: string; status: ServerStatus; error: string | null }): void {
+  if (client.status !== "connected" && client.status !== "needs-auth" && client.status !== "error") return;
+  recordServerOutcome(client.name, client.status, client.error ?? undefined);
+}
+
+/** True if the cache entry exists, its config hash matches, and it is not older than CACHE_MAX_AGE_MS */
+export function isServerCacheValid(def: ServerDef, entry: ServerCacheEntry | undefined): boolean {
+  if (!entry) return false;
+  if (entry.configHash !== computeServerHash(def)) return false;
+  return Date.now() - entry.cachedAt <= CACHE_MAX_AGE_MS;
+}
+
+/** Get cached tools for a server if the cache is valid for the current def, else undefined */
+export function getCachedTools(serverName: string, def: ServerDef): CachedTool[] | undefined {
+  const entry = loadMetadataCache().servers[serverName];
+  if (!entry || !isServerCacheValid(def, entry)) return undefined;
+  return entry.tools;
+}
+
+/** Get cached prompts for a server if the cache is valid for the current def, else undefined */
+export function getCachedPrompts(
+  serverName: string,
+  def: ServerDef,
+): Array<{ name: string; description?: string }> | undefined {
+  const entry = loadMetadataCache().servers[serverName];
+  if (!entry || !isServerCacheValid(def, entry)) return undefined;
+  return entry.prompts;
+}