@remnic/core 9.7.6 → 9.7.8

package/src/access-mcp-cancellation.test.ts

@@ -0,0 +1,405 @@
+import assert from "node:assert/strict";
+import { request as httpRequest } from "node:http";
+import test from "node:test";
+
+import { abortError } from "./abort-error.js";
+import { EngramAccessHttpServer } from "./access-http.js";
+import { EngramMcpServer } from "./access-mcp.js";
+import { EngramAccessService, type EngramAccessRecallRequest } from "./access-service.js";
+
+function deferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function waitFor<T>(promise: Promise<T>, timeoutMs = 1_000): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+      timer.unref?.();
+    }),
+  ]);
+}
+
+function mcpBody(
+  name: string,
+  args: Record<string, unknown> = { query: "slow recall" },
+): string {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name, arguments: args },
+  });
+}
+
+function sendMcp(port: number, name: string): {
+  client: ReturnType<typeof httpRequest>;
+  response: Promise<string>;
+} {
+  const response = deferred<string>();
+  const client = httpRequest({
+    host: "127.0.0.1",
+    port,
+    path: "/mcp",
+    method: "POST",
+    headers: {
+      authorization: "Bearer test-token",
+      "content-type": "application/json",
+    },
+  }, (res) => {
+    const chunks: Buffer[] = [];
+    res.on("data", (chunk: Buffer) => chunks.push(chunk));
+    res.on("end", () => response.resolve(Buffer.concat(chunks).toString("utf8")));
+    res.on("error", response.reject);
+  });
+  client.on("error", (error) => response.reject(error));
+  client.end(mcpBody(name));
+  return { client, response: response.promise };
+}
+
+test("MCP recall aborts in-flight work without writing a JSON-RPC error after disconnect", async () => {
+  const recallStarted = deferred<void>();
+  const recallSettled = deferred<void>();
+  const forceRelease = deferred<void>();
+  let observedSignal: AbortSignal | undefined;
+  let responseStarted = false;
+  const service = {
+    recall: async (input: EngramAccessRecallRequest) => {
+      observedSignal = input.abortSignal;
+      recallStarted.resolve();
+      try {
+        await Promise.race([
+          forceRelease.promise,
+          new Promise<void>((_resolve, reject) => {
+            input.abortSignal?.addEventListener("abort", () => reject(input.abortSignal?.reason), { once: true });
+          }),
+        ]);
+      } finally {
+        recallSettled.resolve();
+      }
+      return {} as never;
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+
+  try {
+    const client = httpRequest({
+      host: "127.0.0.1",
+      port: status.port,
+      path: "/mcp",
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+    }, (res) => {
+      responseStarted = true;
+      res.resume();
+    });
+    client.on("error", () => {});
+    client.end(mcpBody("remnic.recall"));
+
+    await waitFor(recallStarted.promise);
+    assert.ok(observedSignal, "the HTTP request signal must reach the MCP recall service");
+    client.destroy();
+
+    await waitFor(recallSettled.promise);
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(observedSignal.aborted, true);
+    assert.equal(observedSignal.reason?.name, "AbortError");
+    assert.equal(responseStarted, false, "a disconnected client must not receive a JSON-RPC error response");
+  } finally {
+    forceRelease.resolve();
+    await server.stop();
+  }
+});
+
+test("MCP recall_xray forwards the signal and preserves the original AbortError", async () => {
+  const controller = new AbortController();
+  const reason = abortError("caller disconnected");
+  let observedSignal: AbortSignal | undefined;
+  const service = {
+    recallXray: async (input: { abortSignal?: AbortSignal }) => {
+      observedSignal = input.abortSignal;
+      controller.abort(reason);
+      return { snapshotFound: false };
+    },
+  } as unknown as EngramAccessService;
+  const mcp = new EngramMcpServer(service);
+
+  await assert.rejects(
+    mcp.handleRequest(
+      {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "remnic.recall_xray", arguments: { query: "why" } },
+      },
+      { abortSignal: controller.signal },
+    ),
+    (error: unknown) => error === reason,
+  );
+  assert.equal(observedSignal, controller.signal);
+});
+
+test("MCP memory inspector forwards cancellation to its full recall", async () => {
+  const controller = new AbortController();
+  const reason = abortError("inspector caller disconnected");
+  let observedSignal: AbortSignal | undefined;
+  let actionConfidenceStarted = false;
+  const service = {
+    recallXray: async (input: { abortSignal?: AbortSignal }) => {
+      observedSignal = input.abortSignal;
+      controller.abort(reason);
+      throw input.abortSignal?.reason;
+    },
+    actionConfidence: async () => {
+      actionConfidenceStarted = true;
+      return {} as never;
+    },
+  } as unknown as EngramAccessService;
+  const mcp = new EngramMcpServer(service);
+
+  await assert.rejects(
+    mcp.handleRequest(
+      {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "remnic.chatgpt_memory_inspector",
+          arguments: { query: "inspect this" },
+        },
+      },
+      { abortSignal: controller.signal },
+    ),
+    (error: unknown) => error === reason,
+  );
+  assert.equal(observedSignal, controller.signal);
+  assert.equal(actionConfidenceStarted, false);
+});
+
+test("standalone MCP calls leave recall cancellation undefined", async () => {
+  let observedSignal: AbortSignal | undefined;
+  const service = {
+    recall: async (input: EngramAccessRecallRequest) => {
+      observedSignal = input.abortSignal;
+      return {} as never;
+    },
+  } as unknown as EngramAccessService;
+  const mcp = new EngramMcpServer(service);
+
+  const response = await mcp.handleRequest({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name: "remnic.recall", arguments: { query: "live" } },
+  });
+
+  assert.equal(observedSignal, undefined);
+  assert.equal((response?.result as { isError?: boolean } | undefined)?.isError, false);
+});
+
+test("an already-aborted MCP write never starts and preserves the AbortError", async () => {
+  const controller = new AbortController();
+  const reason = abortError("caller disconnected before dispatch");
+  let writeStarted = false;
+  const service = {
+    memoryStore: async () => {
+      writeStarted = true;
+      return {} as never;
+    },
+  } as unknown as EngramAccessService;
+  const mcp = new EngramMcpServer(service);
+  controller.abort(reason);
+
+  await assert.rejects(
+    mcp.handleRequest(
+      {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "remnic.memory_store",
+          arguments: { content: "must not be stored", category: "fact" },
+        },
+      },
+      { abortSignal: controller.signal },
+    ),
+    (error: unknown) => error === reason,
+  );
+  assert.equal(writeStarted, false);
+});
+
+test("MCP write quota is recorded after commit even when the client disconnects before completion", async () => {
+  const mutationCommitted = deferred<void>();
+  const releaseOperation = deferred<void>();
+  const operationSettled = deferred<void>();
+  const requestAborted = deferred<void>();
+  let responseStarted = false;
+  const service = {
+    memoryStore: async () => {
+      mutationCommitted.resolve();
+      try {
+        await releaseOperation.promise;
+      } finally {
+        operationSettled.resolve();
+      }
+      return {
+        schemaVersion: 1,
+        operation: "memory_store",
+        namespace: "default",
+        dryRun: false,
+        accepted: true,
+        queued: false,
+        status: "stored",
+        memoryId: "committed-memory",
+      };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const serverHost = server as unknown as {
+    mcpServer: EngramMcpServer;
+    writeRequestTimestamps: number[];
+  };
+  const originalHandleRequest = serverHost.mcpServer.handleRequest.bind(serverHost.mcpServer);
+  serverHost.mcpServer.handleRequest = async (request, options) => {
+    options?.abortSignal?.addEventListener("abort", () => requestAborted.resolve(), { once: true });
+    return originalHandleRequest(request, options);
+  };
+  const status = await server.start();
+
+  try {
+    const client = httpRequest({
+      host: "127.0.0.1",
+      port: status.port,
+      path: "/mcp",
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+    }, (res) => {
+      responseStarted = true;
+      res.resume();
+    });
+    client.on("error", () => {});
+    client.end(mcpBody("remnic.memory_store", {
+      content: "committed before disconnect",
+      category: "fact",
+    }));
+
+    await waitFor(mutationCommitted.promise);
+    client.destroy();
+    await waitFor(requestAborted.promise);
+    releaseOperation.resolve();
+
+    await waitFor(operationSettled.promise);
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(serverHost.writeRequestTimestamps.length, 1);
+    assert.equal(responseStarted, false, "the disconnected client must not receive the committed write response");
+  } finally {
+    releaseOperation.resolve();
+    await server.stop();
+  }
+});
+
+test("a disconnected MCP recall queued on the budget lock never starts and does not poison the lock", async () => {
+  const firstStarted = deferred<void>();
+  const releaseFirst = deferred<void>();
+  const secondQueued = deferred<void>();
+  const secondAborted = deferred<void>();
+  const secondSettled = deferred<void>();
+  let secondStarted = false;
+  let thirdStarted = false;
+  let callCount = 0;
+
+  const lockService = Object.create(EngramAccessService.prototype) as EngramAccessService;
+  const lockHost = lockService as unknown as {
+    budgetLocks: Map<string, Promise<void>>;
+    withBudgetLock<T>(
+      principal: string,
+      abortSignal: AbortSignal | undefined,
+      operation: () => Promise<T>,
+    ): Promise<T>;
+  };
+  lockHost.budgetLocks = new Map();
+
+  const service = {
+    recall: async (input: EngramAccessRecallRequest) => {
+      callCount += 1;
+      const call = callCount;
+      if (call === 2) {
+        input.abortSignal?.addEventListener("abort", () => secondAborted.resolve(), { once: true });
+        secondQueued.resolve();
+      }
+      try {
+        return await lockHost.withBudgetLock("principal", input.abortSignal, async () => {
+          if (call === 1) {
+            firstStarted.resolve();
+            await releaseFirst.promise;
+          } else if (call === 2) {
+            secondStarted = true;
+          } else {
+            thirdStarted = true;
+          }
+          return {} as never;
+        });
+      } finally {
+        if (call === 2) secondSettled.resolve();
+      }
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+
+  try {
+    const first = sendMcp(status.port, "remnic.recall");
+    await waitFor(firstStarted.promise);
+
+    const second = sendMcp(status.port, "remnic.recall");
+    second.response.catch(() => {});
+    await waitFor(secondQueued.promise);
+    second.client.destroy();
+    await waitFor(secondAborted.promise);
+    releaseFirst.resolve();
+
+    await waitFor(first.response);
+    await waitFor(secondSettled.promise);
+    assert.equal(secondStarted, false);
+
+    const third = sendMcp(status.port, "remnic.recall");
+    await waitFor(third.response);
+    assert.equal(thirdStarted, true);
+  } finally {
+    releaseFirst.resolve();
+    await server.stop();
+  }
+});

package/src/access-mcp.ts

@@ -40,6 +40,7 @@ import { expandTildePath } from "./utils/path.js";
 
 import { applyToolOutputSchemas } from "./access-mcp-output-schemas.js";
 import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
+import { abortError, isAbortError } from "./abort-error.js";
 type JsonRpcId = string | number | null;
 
 type JsonRpcRequest = {
@@ -49,6 +50,12 @@ type JsonRpcRequest = {
   params?: Record<string, unknown>;
 };
 
+function throwMcpAbort(signal: AbortSignal | undefined, message: string): void {
+  if (!signal?.aborted) return;
+  if (isAbortError(signal.reason)) throw signal.reason;
+  throw abortError(message);
+}
+
 type McpRequestOptions = {
   principalOverride?: string;
   namespaceOverride?: string;
@@ -67,6 +74,8 @@ type McpRequestOptions = {
    * the operation context so write handlers stamp it onto frontmatter.
    */
   sourceConnector?: string;
+  /** HTTP request lifetime; absent for the standalone stdio transport. */
+  abortSignal?: AbortSignal;
 };
 
 type McpTool = {
@@ -2645,6 +2654,10 @@ export class EngramMcpServer {
           ...(options?.namespaceOverride ? { namespace: options.namespaceOverride } : {}),
           ...(options?.sessionKeyOverride ? { sessionKey: options.sessionKeyOverride } : {}),
         };
+        // Abort before dispatch so a disconnected request never starts work.
+        // Once a mutating tool has returned, cancellation is deferred to the
+        // HTTP transport so it can account for the committed write first.
+        throwMcpAbort(options?.abortSignal, "MCP request aborted before operation start");
         const result = await this.callTool(
           name,
           argumentsObject,
@@ -2652,8 +2665,12 @@ export class EngramMcpServer {
           options?.sessionId,
           mcpScope,
           options?.enforceWriteQuota,
-          options?.sourceConnector
+          options?.sourceConnector,
+          options?.abortSignal,
         );
+        if (isReadOnlyToolName(name)) {
+          throwMcpAbort(options?.abortSignal, "MCP request aborted before response");
+        }
         return {
           jsonrpc: "2.0",
           id,
@@ -2664,6 +2681,9 @@ export class EngramMcpServer {
           },
         };
       } catch (err) {
+        // Cancellation is transport control flow, not a JSON-RPC tool error.
+        // Preserve the original AbortError so HTTP can silently end a dead socket.
+        if (isAbortError(err)) throw err;
         const message = err instanceof Error ? err.message : String(err);
         return {
           jsonrpc: "2.0",
@@ -2862,6 +2882,7 @@ export class EngramMcpServer {
     scope?: { namespace?: string; sessionKey?: string },
     enforceWriteQuota?: () => void | Promise<void>,
     sourceConnector?: string,
+    abortSignal?: AbortSignal,
   ): Promise<unknown> {
     const migrated = MCP_MIGRATED_OPERATIONS[toLegacyToolName(name)];
     if (!migrated) {
@@ -2941,7 +2962,9 @@ export class EngramMcpServer {
       const result = (await op.run(envelope, {
         service: this.service,
         authenticatedPrincipal: effectivePrincipal,
+        ...(abortSignal ? { abortSignal } : {}),
       })) as { result: unknown };
+      throwMcpAbort(abortSignal, "MCP recall aborted before postprocessing");
       const response = result.result as Record<string, unknown>;
       if (this.shouldEmitCitations(mcpSessionId)) {
         const citations = this.buildRecallCitations(response as unknown as EngramAccessRecallResponse);
@@ -2961,6 +2984,7 @@ export class EngramMcpServer {
       authenticatedPrincipal: effectivePrincipal,
       ...(enforceWriteQuota ? { hooks: { enforceWriteQuota } } : {}),
       ...(sourceConnector ? { sourceConnector } : {}),
+      ...(abortSignal ? { abortSignal } : {}),
     })) as { result: unknown };
     return output.result;
   }

package/src/access-operations-batch.ts

@@ -83,7 +83,7 @@ defineOperation({ name: "recall", description: "Semantic recall.", schema: stric
     if (input.tags !== undefined) { if (!Array.isArray(input.tags) || !input.tags.every((t) => typeof t === "string")) throw new EngramAccessInputError("tags must be an array of strings"); tags = input.tags; }
     let tagMatch: "any" | "all" | undefined;
     if (input.tagMatch !== undefined) { if (input.tagMatch !== "any" && input.tagMatch !== "all") throw new EngramAccessInputError("tagMatch must be one of: any, all"); tagMatch = input.tagMatch; }
-    const result = await ctx.service.recall({ query: typeof input.query === "string" ? input.query : "", sessionKey: optStr(input.sessionKey), authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), topK: optNum(input.topK), mode: optStr(input.mode) as RecallPlanMode | "auto" | undefined, includeDebug: input.includeDebug === true, disclosure, cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), asOf: optStr(input.asOf), ...(tags ? { tags } : {}), ...(tagMatch ? { tagMatch } : {}) });
+    const result = await ctx.service.recall({ query: typeof input.query === "string" ? input.query : "", sessionKey: optStr(input.sessionKey), authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), topK: optNum(input.topK), mode: optStr(input.mode) as RecallPlanMode | "auto" | undefined, includeDebug: input.includeDebug === true, disclosure, cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), asOf: optStr(input.asOf), ...(tags ? { tags } : {}), ...(tagMatch ? { tagMatch } : {}), ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) });
     return { result };
   },
 });
@@ -110,7 +110,7 @@ defineOperation({ name: "recall_xray", description: "X-ray recall.", schema: str
     let budget: number | undefined;
     if (input.budget !== undefined) { const p = typeof input.budget === "number" ? input.budget : typeof input.budget === "string" ? Number(input.budget) : undefined; if (p === undefined || !Number.isFinite(p) || p <= 0 || !Number.isInteger(p)) throw new EngramAccessInputError("recall_xray: budget expects a positive integer"); budget = p; }
     const dr = optStr(input.disclosure);
-    return { result: await ctx.service.recallXray({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), budget, authenticatedPrincipal: ctx.authenticatedPrincipal, ...(dr && dr !== "" ? { disclosure: dr as RecallDisclosure } : {}) }) };
+    return { result: await ctx.service.recallXray({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), budget, authenticatedPrincipal: ctx.authenticatedPrincipal, ...(dr && dr !== "" ? { disclosure: dr as RecallDisclosure } : {}), ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) }) };
   },
 });
 
@@ -133,7 +133,7 @@ defineOperation({ name: "chatgpt_memory_inspector", description: "Memory inspect
     if (input.currentContextScopes !== undefined) ii.currentContextScopes = input.currentContextScopes as string[];
     if (input.allowUnverifiedPreview !== undefined) ii.allowUnverifiedPreview = input.allowUnverifiedPreview as boolean;
     const rsk = ii.sessionKey ?? (ctx.authenticatedPrincipal ? "remnic:chatgpt-memory-inspector:" + randomUUID() : undefined);
-    const xr = await ctx.service.recallXray({ query: ii.query, sessionKey: rsk, namespace: ii.namespace, currentContextScopes: ii.currentContextScopes, authenticatedPrincipal: ctx.authenticatedPrincipal, mode: "full", disclosure: "chunk", includeRecall: true });
+    const xr = await ctx.service.recallXray({ query: ii.query, sessionKey: rsk, namespace: ii.namespace, currentContextScopes: ii.currentContextScopes, authenticatedPrincipal: ctx.authenticatedPrincipal, mode: "full", disclosure: "chunk", includeRecall: true, ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) });
     const x = xr.snapshotFound === true ? (xr.snapshot ?? null) : null;
     const r = xr.recall ?? { query: ii.query, namespace: ii.namespace ?? x?.namespace ?? "global", context: "", count: 0, memoryIds: [], results: [], fallbackUsed: false, sourcesUsed: [], disclosure: "chunk" as const };
     const ac = await ctx.service.actionConfidence(buildChatGptMemoryInspectorActionRequest(ii, r, x));