@remnic/core 9.3.768 → 9.3.769

package/src/access-mcp.ts

@@ -78,7 +78,79 @@ type McpResource = {
   _meta?: Record<string, unknown>;
 };
 
-const MCP_PROTOCOL_VERSION = "2024-11-05";
+/**
+ * Conservative allowlist of canonical MCP tool suffixes that are
+ * unambiguously read-only. Tools in this set are tagged with
+ * `annotations: { readOnlyHint: true }` so ChatGPT (and other MCP
+ * clients that honor the hint) can skip per-call confirmation.
+ *
+ * The list is suffix-based so it covers both the `remnic.*` and
+ * `engram.*` naming forms. Anything not on it stays unannotated:
+ * uncertainty is resolved as "might mutate".
+ *
+ * Excluded by construction: anything that writes, runs a pipeline,
+ * flushes, applies, records, imports, or destructively deletes.
+ */
+const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
+  recall: true,
+  recall_explain: true,
+  recall_tier_explain: true,
+  recall_xray: true,
+  briefing: true,
+  wearables_status: true,
+  transcript_day: true,
+  transcript_search: true,
+  transcript_memories: true,
+  action_confidence: true,
+  capsule_list: true,
+  procedural_stats: true,
+  memory_get: true,
+  memory_timeline: true,
+  entity_get: true,
+  review_queue_list: true,
+  lcm_search: true,
+  continuity_incident_list: true,
+  identity_anchor_get: true,
+  memory_identity: true,
+  memory_search: true,
+  memory_profile: true,
+  memory_entities_list: true,
+  memory_questions: true,
+  memory_last_recall: true,
+  memory_intent_debug: true,
+  memory_qmd_debug: true,
+  memory_graph_explain: true,
+  graph_snapshot: true,
+  review_list: true,
+  profiling_report: true,
+  peer_list: true,
+  peer_get: true,
+  peer_profile_get: true,
+  console_state: true,
+  dreams_status: true,
+  codegraph_list_projects: true,
+  codegraph_index_status: true,
+  codegraph_search_graph: true,
+  codegraph_trace_path: true,
+  codegraph_detect_changes: true,
+  codegraph_query_graph: true,
+  codegraph_get_schema: true,
+  codegraph_get_snippet: true,
+  codegraph_get_architecture: true,
+  codegraph_search_code: true,
+};
+
+/**
+ * MCP protocol versions this server understands, ordered newest → oldest.
+ * Exported so the HTTP transport can validate the `MCP-Protocol-Version`
+ * header and reject requests advertising an unknown version.
+ */
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+];
+const MCP_DEFAULT_PROTOCOL_VERSION: string = MCP_SUPPORTED_PROTOCOL_VERSIONS[0] ?? "2025-06-18";
 const LEGACY_MCP_PREFIX = "engram.";
 const CANONICAL_MCP_PREFIX = "remnic.";
 
@@ -87,13 +159,27 @@ function toCanonicalToolName(name: string): string {
     ? `${CANONICAL_MCP_PREFIX}${name.slice(LEGACY_MCP_PREFIX.length)}`
     : name;
 }
-
 function toLegacyToolName(name: string): string {
   return name.startsWith(CANONICAL_MCP_PREFIX)
     ? `${LEGACY_MCP_PREFIX}${name.slice(CANONICAL_MCP_PREFIX.length)}`
     : name;
 }
 
+/**
+ * Suffix-based allowlist matcher. Returns true for tools whose canonical
+ * suffix (after stripping `remnic.` or `engram.`) is in
+ * {@link MCP_READ_ONLY_TOOL_SUFFIXES}. Unprefixed names are treated as
+ * unannotated.
+ */
+function isReadOnlyToolName(name: string): boolean {
+  for (const prefix of [CANONICAL_MCP_PREFIX, LEGACY_MCP_PREFIX]) {
+    if (name.startsWith(prefix)) {
+      return MCP_READ_ONLY_TOOL_SUFFIXES[name.slice(prefix.length)] === true;
+    }
+  }
+  return false;
+}
+
 function withToolAliases(tool: McpTool, emitLegacyTools = true): McpTool[] {
   const canonicalName = toCanonicalToolName(tool.name);
   const canonicalTool = canonicalName === tool.name ? tool : { ...tool, name: canonicalName };
@@ -2342,6 +2428,17 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...chatTools];
     }
+    // Apply `readOnlyHint` annotations to the conservative read-only
+    // allowlist. Done as a final pass so every spread (chat, codegraph,
+    // coding_*, correction, etc.) inherits the annotation without
+    // scattering the same logic across every `withToolAliases` call site.
+    // Suffix-based matching covers both the `remnic.*` and `engram.*`
+    // naming forms emitted by `withToolAliases`.
+    this.tools = this.tools.map((tool) =>
+      isReadOnlyToolName(tool.name) && tool.annotations?.readOnlyHint !== true
+        ? { ...tool, annotations: { ...(tool.annotations ?? {}), readOnlyHint: true } }
+        : tool,
+    );
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */
@@ -2369,6 +2466,24 @@ export class EngramMcpServer {
     }
     if (method === "initialize") {
       const params = request.params ?? {};
+      // MCP initialize REQUIRES params.protocolVersion (string). Reject a
+      // missing/mistyped field with JSON-RPC invalid params instead of
+      // silently negotiating (repo rule: never reinterpret invalid input).
+      // An unsupported-but-well-formed version gets the spec-mandated
+      // counter-offer below instead: the server answers with the newest
+      // version it supports and the client decides whether to proceed.
+      if (typeof params.protocolVersion !== "string" || params.protocolVersion.length === 0) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message:
+              "initialize requires params.protocolVersion (string); " +
+              `supported versions: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`,
+          },
+        };
+      }
       const rawClientInfo = params.clientInfo as { name?: string; version?: string } | undefined;
       // Generate a server-side session ID for this MCP session.
       // The caller should send this back as Mcp-Session-Id on subsequent requests.
@@ -2391,7 +2506,9 @@ export class EngramMcpServer {
         jsonrpc: "2.0",
         id,
         result: {
-          protocolVersion: MCP_PROTOCOL_VERSION,
+          protocolVersion: MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(params.protocolVersion)
+            ? params.protocolVersion
+            : MCP_DEFAULT_PROTOCOL_VERSION,
           capabilities: {
             tools: {},
             resources: {},

package/src/index.ts

@@ -977,11 +977,14 @@ export {
 // ---------------------------------------------------------------------------
 
 export {
+  buildTokenEntry,
+  commitTokenEntry,
   generateToken,
   listTokens,
   revokeToken,
   getAllValidTokens,
   getAllValidTokensCached,
+  getAllValidTokenEntriesCached,
   resolveConnectorFromToken,
   loadTokenStore,
   saveTokenStore,

package/src/tokens.test.ts

@@ -8,6 +8,7 @@ import {
   buildTokenEntry,
   commitTokenEntry,
   generateToken,
+  getAllValidTokenEntriesCached,
   getAllValidTokensCached,
   loadTokenStore,
   revokeToken,
@@ -208,3 +209,60 @@ test("generateToken uses a recognizable prefix for the omp connector", async ()
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("generateToken uses a recognizable prefix for the chatgpt connector", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    const entry = generateToken("chatgpt", tokensPath);
+    assert.equal(entry.connector, "chatgpt");
+    assert.ok(
+      entry.token.startsWith("remnic_cg_"),
+      `expected remnic_cg_ prefix, got ${entry.token}`,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("commitTokenEntry replaces the prior chatgpt entry so re-linking rotates the token", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    const first = generateToken("chatgpt", tokensPath);
+    commitTokenEntry(first, tokensPath);
+    const second = generateToken("chatgpt", tokensPath);
+    commitTokenEntry(second, tokensPath);
+    assert.notEqual(first.token, second.token, "re-linking must mint a new token");
+    const store = loadTokenStore(tokensPath);
+    const chatgptEntries = store.tokens.filter((t) => t.connector === "chatgpt");
+    assert.equal(chatgptEntries.length, 1, "only one chatgpt entry survives the rotate");
+    assert.equal(chatgptEntries[0]?.token, second.token, "the new token is the surviving one");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("entries snapshot is coherent with validation: mint and revoke take effect immediately", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    // Warm the cache so a stale snapshot WOULD be observable if mutation
+    // failed to invalidate it.
+    assert.deepEqual([...getAllValidTokenEntriesCached(tokensPath)], []);
+
+    // Mint-then-use: the fresh token resolves with its connector in the
+    // SAME snapshot call that validates it — no window where the token is
+    // valid but its identity is unknown.
+    const minted = generateToken("chatgpt", tokensPath);
+    const afterMint = getAllValidTokenEntriesCached(tokensPath);
+    const found = afterMint.find((entry) => entry.token === minted.token);
+    assert.ok(found, "freshly minted token must appear immediately");
+    assert.equal(found.connector, "chatgpt");
+    assert.deepEqual(getAllValidTokensCached(tokensPath), [minted.token]);
+
+    // Revoke-then-use: the token disappears from the snapshot immediately.
+    assert.equal(revokeToken("chatgpt", tokensPath), true);
+    assert.deepEqual([...getAllValidTokenEntriesCached(tokensPath)], []);
+    assert.deepEqual(getAllValidTokensCached(tokensPath), []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/tokens.ts

@@ -36,6 +36,7 @@ const TOKEN_PREFIXES: Record<string, string> = {
   "windsurf": "remnic_ws_",
   "amp": "remnic_am_",
   "generic-mcp": "remnic_gm_",
+  "chatgpt": "remnic_cg_",
 };
 
 function defaultTokensPath(): string {
@@ -260,26 +261,36 @@ export function getAllValidTokens(tokensPath?: string): string[] {
   return loadTokenStore(tokensPath).tokens.map((t) => t.token);
 }
 
-// Cached token loader to avoid synchronous disk I/O on every HTTP request.
-// Re-reads tokens.json at most once per TTL interval (default 5s).
+// Cached token-entry snapshot to avoid synchronous disk I/O on every HTTP
+// request. Re-reads tokens.json at most once per TTL interval (default 5s).
+// There is deliberately exactly ONE cache: validation (token strings) and
+// identity (connector ids) are derived from the SAME snapshot, so a token
+// can never validate against a fresher snapshot than the one that resolves
+// its connector. saveTokenStore() invalidates on every mutation, so a
+// freshly minted or revoked token is coherent immediately.
 const TOKEN_CACHE_TTL_MS = 5_000;
-let _cachedTokens: string[] = [];
+let _cachedEntries: TokenEntry[] = [];
 let _cachedAt = 0;
 let _cachedPath: string | undefined;
 
 function invalidateTokenCache(): void {
-  _cachedTokens = [];
+  _cachedEntries = [];
   _cachedAt = 0;
   _cachedPath = undefined;
 }
 
-export function getAllValidTokensCached(tokensPath?: string): string[] {
+/** Cached token-entry snapshot ({token, connector} pairs). */
+export function getAllValidTokenEntriesCached(tokensPath?: string): readonly TokenEntry[] {
   const now = Date.now();
-  if (now - _cachedAt < TOKEN_CACHE_TTL_MS && tokensPath === _cachedPath) return _cachedTokens;
-  _cachedTokens = getAllValidTokens(tokensPath);
+  if (now - _cachedAt < TOKEN_CACHE_TTL_MS && tokensPath === _cachedPath) return _cachedEntries;
+  _cachedEntries = loadTokenStore(tokensPath).tokens;
   _cachedAt = now;
   _cachedPath = tokensPath;
-  return _cachedTokens;
+  return _cachedEntries;
+}
+
+export function getAllValidTokensCached(tokensPath?: string): string[] {
+  return getAllValidTokenEntriesCached(tokensPath).map((entry) => entry.token);
 }
 
 export function resolveConnectorFromToken(token: string, tokensPath?: string): string | undefined {