@remnic/core 10.0.84 → 10.0.86

package/src/access-http.test.ts

@@ -13,8 +13,8 @@ import {
 import { peerManifestRevision } from "./reconcile/manifest.js";
 import {
   EngramAccessInputError,
+  EngramAccessService,
   type EngramAccessRecallRequest,
-  type EngramAccessService,
   type EngramAccessBriefingRequest,
 } from "./access-service.js";
 import {
@@ -815,6 +815,48 @@ test("HTTP coding-context endpoint accepts projectTag shorthand", async () => {
   }
 });
 
+test("HTTP observe answers 503 buffer_admission_refused when durable capture hits the entry cap", async () => {
+  const refusal = new Error("buffer at session-entry cap");
+  refusal.name = "ReplayAdmissionRefusedError";
+  // SAFETY: this fixture drives only the observe route; the remaining service members are unreachable.
+  const service = Object.assign({} as EngramAccessService, {
+    observe: async () => {
+      throw refusal;
+    },
+  });
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/observe`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          sessionKey: "capacity-test-session",
+          messages: [{ role: "user", content: "retry me" }],
+        }),
+      },
+    );
+    assert.equal(response.status, 503, "admission backpressure is retryable, not a server fault");
+    assert.deepEqual(await response.json(), {
+      error: "buffer at session-entry cap",
+      code: "buffer_admission_refused",
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP briefing endpoint dispatches through the briefing operation", async () => {
   const calls: unknown[] = [];
   const service = {
@@ -2996,11 +3038,11 @@ test("HTTP scoped-token namespace allow-list is enforced on every namespace rout
       "scoped memory_get: the allowed namespace reaches the service",
     );
 
-    // ── a non-namespace-scoped route is unaffected by namespace scoping ──
+    // ── a global-store route is fleet-wide: a namespace-scoped token is denied (issue #3225 B3) ──
     assert.equal(
       (await request("scoped-ns-a", "/engram/v1/peers")).status,
-      200,
-      "a non-namespace-scoped route must be unaffected",
+      403,
+      "peer routes touch global stores, so a namespace-scoped token is denied",
     );
 
     // ── unrestricted token: omitting namespace still reaches the default tenant ──
@@ -6515,3 +6557,206 @@ test("a budget above the backend cap still gets the rows it asked for", async ()
     "the excluded hit was replaced, not subtracted",
   );
 });
+
+/**
+ * Prototype-backed service stub for the write-quota tests: the constructor's
+ * surface getters read only `orchestrator.config`, and each test overrides the
+ * single member its route dispatches.
+ */
+function quotaStubService(): EngramAccessService {
+  // SAFETY: the prototype supplies the untouched service surface; each quota test overrides only the member its route dispatches.
+  const service = Object.create(EngramAccessService.prototype) as EngramAccessService;
+  // SAFETY: startup reads only orchestrator.config from the service; an empty config keeps every surface flag false.
+  Reflect.set(service, "orchestrator", { config: {} });
+  return service;
+}
+
+test("concurrent distinct-payload writes cannot overshoot the write quota (issue #3225 C4)", async () => {
+  // Checking hasCapacity before the operation and calling record after it
+  // left a window where N in-flight writes all pass against the same
+  // committed count. Admission must reserve a slot, so only LIMIT of TOTAL
+  // overlapping writes proceed and the rest get 429.
+  const LIMIT = 2;
+  const TOTAL = 6;
+  let dispatches = 0;
+  const firstDispatched = Promise.withResolvers<void>();
+  const releaseWrites = Promise.withResolvers<void>();
+  const service = quotaStubService();
+  service.capsuleExport = async (request) => {
+    dispatches += 1;
+    if (dispatches === 1) firstDispatched.resolve();
+    await releaseWrites.promise;
+    // SAFETY: the route serializes this stub result into the HTTP response; the test asserts statuses, not this shape.
+    return { ok: true, name: request.name } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: LIMIT,
+  });
+  const status = await server.start();
+  const post = (index: number) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/capsules/export`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name: `quota-race-${index}` }),
+    });
+  try {
+    const first = post(0);
+    await firstDispatched.promise;
+    const rest = Array.from({ length: TOTAL - 1 }, (_, index) => post(index + 1));
+    // The first write is admitted and held open inside the service, so every
+    // other request must run its admission check against an unrecorded
+    // window. Loopback arrival needs a bounded grace; the overlap cannot be
+    // driven deterministically because admission is server-internal.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    releaseWrites.resolve();
+    const responses = await Promise.all([first, ...rest]);
+    const statuses = responses.map((response) => response.status).sort((a, b) => a - b);
+    assert.deepEqual(
+      statuses,
+      [...Array<number>(LIMIT).fill(200), ...Array<number>(TOTAL - LIMIT).fill(429)],
+      `expected exactly ${LIMIT} admitted writes and ${TOTAL - LIMIT} rejections, got ${JSON.stringify(statuses)}`,
+    );
+  } finally {
+    releaseWrites.resolve();
+    await server.stop();
+  }
+});
+
+test("a failed write releases its reserved quota slot (issue #3225 C4)", async () => {
+  let calls = 0;
+  const service = quotaStubService();
+  service.capsuleExport = async (request) => {
+    calls += 1;
+    if (calls === 1) throw new Error("export backend failed");
+    // SAFETY: the route serializes this stub result into the HTTP response; the test asserts statuses, not this shape.
+    return { ok: true, name: request.name } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (name: string) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/capsules/export`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name }),
+    });
+  try {
+    // The first export fails in the backend; the slot it reserved at
+    // admission must be released, so the retry is admitted and only then
+    // does the window fill.
+    assert.equal((await post("quota-fail-1")).status, 500);
+    assert.equal((await post("quota-fail-2")).status, 200);
+    assert.equal((await post("quota-fail-3")).status, 429);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("a replayed observe never 429s and never consumes a second quota slot (issue #1434, #3225 C4)", async () => {
+  const stored = new Map<string, { sessionKey: string }>();
+  let hookCalls = 0;
+  const service = quotaStubService();
+  service.observe = async (request, hooks) => {
+    const key = request.idempotencyKey?.trim();
+    const cached = key ? stored.get(key) : undefined;
+    if (cached) {
+      // SAFETY: the route only forwards this result into the HTTP response and reads its dryRun/idempotencyReplay flags.
+      return { ...cached, idempotencyReplay: true } as never;
+    }
+    // Mirror the real service contract: the quota hook fires exactly once,
+    // immediately before an actual write commits, never on a replay.
+    await hooks?.enforceWriteQuota?.();
+    hookCalls += 1;
+    const response = { sessionKey: request.sessionKey };
+    stored.set(key ?? "", response);
+    // SAFETY: the route only forwards this result into the HTTP response and reads its dryRun/idempotencyReplay flags.
+    return response as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (idempotencyKey: string) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/observe`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        sessionKey: "quota-replay",
+        messages: [{ role: "user", content: "hello" }],
+        idempotencyKey,
+      }),
+    });
+  try {
+    assert.equal((await post("quota-replay-1")).status, 202);
+    const replay = await post("quota-replay-1");
+    assert.equal(replay.status, 202);
+    // SAFETY: our own server serialized this body; the test reads only the idempotencyReplay flag.
+    const replayBody = (await replay.json()) as { idempotencyReplay?: boolean };
+    assert.equal(replayBody.idempotencyReplay, true);
+    assert.equal(hookCalls, 1, "the replay must not re-run the quota hook");
+    // The window still holds exactly the first write's slot: a different
+    // payload is rejected, proving the replay consumed nothing.
+    assert.equal((await post("quota-replay-2")).status, 429);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("a dreams dry run neither 429s nor consumes quota at a full window (#3225 C4)", async () => {
+  const service = quotaStubService();
+  service.dreamsRun = async (options) => {
+    // SAFETY: the route serializes this stub result into the HTTP response and reads its dryRun flag.
+    return { phase: options.phase, dryRun: options.dryRun === true } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (body: Record<string, boolean>) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/dreams/run`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ phase: "lightSleep", ...body }),
+    });
+  try {
+    assert.equal((await post({})).status, 200);
+    // The window is full; the dry run must pass and leave the count alone.
+    const dry = await post({ dryRun: true });
+    assert.equal(dry.status, 200);
+    // SAFETY: our own server serialized this body; the test reads only the dryRun flag.
+    const dryBody = (await dry.json()) as { dryRun?: boolean };
+    assert.equal(dryBody.dryRun, true);
+    assert.equal((await post({})).status, 429);
+  } finally {
+    await server.stop();
+  }
+});

package/src/access-http.ts

@@ -417,6 +417,11 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
   private readonly resourceMetadataUrl?: string;
   private readonly externalRequestHandler?: SupportPassportExternalRequestHandler;
   private readonly writeLimiter: WriteRateLimiter;
+  // Reservations taken by ensureWriteRateLimitAvailable and not yet committed
+  // by recordWriteRateLimitHit, keyed by request. The per-request release in
+  // the connection callback covers every early return and error path, so a
+  // failed or exempt write never leaks its slot (issue #3225 C4).
+  private readonly pendingWriteQuotas = new WeakMap<IncomingMessage, WriteRateLimitReservation>();
   private readonly mcpServer: EngramMcpServer;
   private server: Server | null = null;
   private boundPort = 0;
@@ -544,6 +549,13 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
             });
             return;
           }
+          if (err.name === "ReplayAdmissionRefusedError") {
+            // Durable-capture backpressure (#3251/#1908): the request was
+            // never accepted — the buffer is at entry capacity. Retryable,
+            // not a server fault (503, not 500).
+            this.respondJson(res, 503, { error: err.message, code: "buffer_admission_refused" });
+            return;
+          }
           if (res.headersSent) {
             res.destroy(err as Error);
             return;
@@ -556,6 +568,9 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
         }).finally(() => {
           req.off("aborted", abortDisconnectedRequest);
           res.off("close", abortDisconnectedRequest);
+          // A counted write that failed or was exempt (dry run, replay) must
+          // not hold its reserved slot past the request (issue #3225 C4).
+          this.releasePendingWriteQuota(req);
         });
       });
     });
@@ -2739,26 +2754,38 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
     //   DELETE /engram/v1/peers/:id?forget=true — destructive full purge (issue #679 completion)
     //   GET    /engram/v1/peers/:id/profile  — get peer profile
     if (req.method === "GET" && pathname === "/engram/v1/peers") {
-      this.enforceTokenOp("peer_list"); // boundary dispatch (issue #1525)
-      const result = await this.service.peerList();
-      this.respondJson(res, 200, result);
+      const op = getOperation("peer_list"); // boundary dispatch (issue #1525)
+      if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_list");
+      // SAFETY: the registered peer_list handler returns { result } from the service.
+      const output = (await op.run({}, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        sourceConnector: this.resolveConnector(req),
+      })) as { result: unknown };
+      this.respondJson(res, 200, output.result);
       return;
     }
 
     const peerProfileMatch = /^\/engram\/v1\/peers\/([^/]+)\/profile$/.exec(pathname);
     if (peerProfileMatch) {
-      this.enforceTokenOp("peer_profile_get"); // boundary dispatch (issue #1525)
       if (req.method !== "GET") {
         this.respondJson(res, 405, { error: "method_not_allowed", code: "method_not_allowed" });
         return;
       }
+      const op = getOperation("peer_profile_get"); // boundary dispatch (issue #1525)
+      if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_profile_get");
       const peerId = decodePeerIdSegment(peerProfileMatch[1] ?? "");
-      const result = await this.service.peerProfileGet(peerId);
-      if (!result.found) {
+      // SAFETY: the registered peer_profile_get handler returns { result } from the service.
+      const output = (await op.run({ id: peerId }, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        sourceConnector: this.resolveConnector(req),
+      })) as { result: { found: boolean } };
+      if (!output.result.found) {
         this.respondJson(res, 404, { error: "peer_profile_not_found", code: "peer_profile_not_found" });
         return;
       }
-      this.respondJson(res, 200, result);
+      this.respondJson(res, 200, output.result);
       return;
     }
 
@@ -2767,47 +2794,49 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       const peerId = decodePeerIdSegment(peerIdMatch[1] ?? "");
 
       if (req.method === "GET") {
-        this.enforceTokenOp("peer_get"); // boundary dispatch (issue #1525)
-        const result = await this.service.peerGet(peerId);
-        if (!result.found) {
+        const op = getOperation("peer_get"); // boundary dispatch (issue #1525)
+        if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_get");
+        // SAFETY: the registered peer_get handler returns { result } with a found flag.
+        const output = (await op.run({ id: peerId }, {
+          service: this.service,
+          authenticatedPrincipal: this.resolveRequestPrincipal(req),
+          sourceConnector: this.resolveConnector(req),
+        })) as { result: { found: boolean } };
+        if (!output.result.found) {
           this.respondJson(res, 404, { error: "peer_not_found", code: "peer_not_found" });
           return;
         }
-        this.respondJson(res, 200, result);
+        this.respondJson(res, 200, output.result);
         return;
       }
 
       if (req.method === "PUT") {
-        this.enforceTokenOp("peer_set"); // boundary dispatch (issue #1525)
         const body = await this.readJsonBody(req) as Record<string, unknown>;
-        // Reject malformed types up front rather than silently dropping them
-        // to undefined and letting peerSet fall back to defaults
-        // (CLAUDE.md rule 51: no silent defaults on bad input).
-        if ("kind" in body && body.kind !== undefined && typeof body.kind !== "string") {
-          throw new EngramAccessInputError("kind must be a string when provided");
-        }
-        if (
-          "displayName" in body &&
-          body.displayName !== undefined &&
-          typeof body.displayName !== "string"
-        ) {
-          throw new EngramAccessInputError("displayName must be a string when provided");
-        }
-        if ("notes" in body && body.notes !== undefined && typeof body.notes !== "string") {
-          throw new EngramAccessInputError("notes must be a string when provided");
+        const op = getOperation("peer_set"); // boundary dispatch (issue #1525)
+        if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_set");
+        // The operation schema strips nulls as "absent", so an explicit null
+        // must fail here or the peer would register with default fields.
+        for (const field of ["kind", "displayName", "notes"]) {
+          if (body[field] === null) throw new EngramAccessInputError(`${field} must be a string when provided`);
         }
-        const result = await this.service.peerSet({
+        // Raw body fields: the operation schema rejects malformed types with an
+        // input error instead of silently defaulting them (rule 51).
+        // SAFETY: the registered peer_set handler returns { result } with the upsert outcome.
+        const output = (await op.run({
           id: peerId,
-          kind: typeof body.kind === "string" ? body.kind : undefined,
-          displayName: typeof body.displayName === "string" ? body.displayName : undefined,
-          notes: typeof body.notes === "string" ? body.notes : undefined,
-        });
-        this.respondJson(res, result.created ? 201 : 200, result);
+          kind: body.kind,
+          displayName: body.displayName,
+          notes: body.notes,
+        }, {
+          service: this.service,
+          authenticatedPrincipal: this.resolveRequestPrincipal(req),
+          sourceConnector: this.resolveConnector(req),
+        })) as { result: { created: boolean } };
+        this.respondJson(res, output.result.created ? 201 : 200, output.result);
         return;
       }
 
       if (req.method === "DELETE") {
-        this.enforceTokenOp("peer_delete"); // boundary dispatch (issue #1525)
         // `?forget=true` triggers the destructive full-purge path (issue #679
         // completion). The caller must also pass `confirm=yes` in the request
         // body; absent confirmation yields 400. Plain DELETE (no ?forget) keeps
@@ -2824,12 +2853,26 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
             });
             return;
           }
-          const result = await this.service.peerForget(peerId, { confirm: "yes" });
-          this.respondJson(res, 200, result);
+          const op = getOperation("peer_forget"); // boundary dispatch (issue #1525)
+          if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_forget");
+          // SAFETY: the registered peer_forget handler returns { result } with the purge outcome.
+          const output = (await op.run({ id: peerId, confirm: "yes" }, {
+            service: this.service,
+            authenticatedPrincipal: this.resolveRequestPrincipal(req),
+            sourceConnector: this.resolveConnector(req),
+          })) as { result: unknown };
+          this.respondJson(res, 200, output.result);
           return;
         }
-        const result = await this.service.peerDelete(peerId);
-        this.respondJson(res, 200, result);
+        const op = getOperation("peer_delete"); // boundary dispatch (issue #1525)
+        if (!op) throw new EngramAccessInputError("access-boundary: operation not registered: peer_delete");
+        // SAFETY: the registered peer_delete handler returns { result } with the delete outcome.
+        const output = (await op.run({ id: peerId }, {
+          service: this.service,
+          authenticatedPrincipal: this.resolveRequestPrincipal(req),
+          sourceConnector: this.resolveConnector(req),
+        })) as { result: unknown };
+        this.respondJson(res, 200, output.result);
         return;
       }
 
@@ -3931,16 +3974,48 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
     return 200;
   }
 
+  /**
+   * Admit a quota-counted write by RESERVING a limiter slot for the request
+   * (issue #3225 C4). A bare hasCapacity check admits N concurrent requests
+   * against the same committed count; the reservation holds in-flight
+   * capacity until the write commits at recordWriteRateLimitHit or the
+   * request ends. Idempotent per request, so a quota hook that fires after
+   * an earlier reservation is a no-op.
+   */
   protected ensureWriteRateLimitAvailable(req?: IncomingMessage): void {
-    if (!this.writeLimiter.hasCapacity(this.principalForRateLimit(req))) {
+    if (!req) {
+      if (!this.writeLimiter.hasCapacity()) {
+        throw new HttpError(429, "write_rate_limited", "write_rate_limited");
+      }
+      return;
+    }
+    if (this.pendingWriteQuotas.has(req)) return;
+    const reservation = this.writeLimiter.reserve(this.principalForRateLimit(req));
+    if (!reservation) {
       throw new HttpError(429, "write_rate_limited", "write_rate_limited");
     }
+    this.pendingWriteQuotas.set(req, reservation);
   }
 
+  /** Commit a counted write at the durable boundary; consumes the request's reservation. */
   protected recordWriteRateLimitHit(req?: IncomingMessage): void {
+    const pending = req ? this.pendingWriteQuotas.get(req) : undefined;
+    if (pending && req) {
+      this.pendingWriteQuotas.delete(req);
+      pending.commit();
+      return;
+    }
     this.writeLimiter.record(this.principalForRateLimit(req));
   }
 
+  /** Release an uncommitted reservation after a rejection, failure, or exempt outcome. */
+  private releasePendingWriteQuota(req: IncomingMessage): void {
+    const pending = this.pendingWriteQuotas.get(req);
+    if (!pending) return;
+    this.pendingWriteQuotas.delete(req);
+    pending.release();
+  }
+
   protected reserveWriteRateLimitSlot(req?: IncomingMessage): WriteRateLimitReservation {
     const reservation = this.writeLimiter.reserve(this.principalForRateLimit(req));
     if (!reservation) {

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

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MCP_STDIO_MAX_FRAME_BYTES, McpFrameReader } from "./access-mcp-frames.js";
+
+function frame(body: string): Buffer {
+  return Buffer.from(`Content-Length: ${Buffer.byteLength(body, "utf-8")}\r\n\r\n${body}`, "utf-8");
+}
+
+test("a frame that arrives in two reads is returned once, without re-reading the partial buffer", () => {
+  const reader = new McpFrameReader();
+  const whole = frame('{"id":1}');
+  reader.push(whole.subarray(0, 10));
+  assert.equal(reader.next(), null);
+  assert.equal(reader.hasUnread(), false);
+
+  reader.push(whole.subarray(10));
+  assert.equal(reader.hasUnread(), true);
+  assert.deepEqual(reader.next(), { kind: "body", text: '{"id":1}' });
+  assert.equal(reader.next(), null);
+});
+
+test("bytes that arrive after the reader stopped on an empty buffer are unread", () => {
+  const reader = new McpFrameReader();
+  reader.push(frame("first"));
+  assert.deepEqual(reader.next(), { kind: "body", text: "first" });
+  assert.equal(reader.next(), null);
+  assert.equal(reader.hasUnread(), false);
+
+  reader.push(frame("second"));
+  assert.equal(reader.hasUnread(), true);
+  assert.deepEqual(reader.next(), { kind: "body", text: "second" });
+});
+
+test("the body of an oversized frame is dropped across reads and the next frame is read", () => {
+  const reader = new McpFrameReader();
+  const declared = MCP_STDIO_MAX_FRAME_BYTES + 5;
+  reader.push(Buffer.from(`Content-Length: ${declared}\r\n\r\n${"A".repeat(100)}`, "utf-8"));
+  assert.deepEqual(reader.next(), { kind: "too-large" });
+  assert.equal(reader.next(), null);
+
+  reader.push(Buffer.from("B".repeat(declared - 100), "utf-8"));
+  assert.equal(reader.hasUnread(), false);
+
+  reader.push(frame("after"));
+  assert.deepEqual(reader.next(), { kind: "body", text: "after" });
+});

package/src/access-mcp-frames.ts

@@ -0,0 +1,74 @@
+/**
+ * Content-Length framing for the MCP stdio transport.
+ *
+ * `push` appends raw bytes. `next` returns one frame at a time and `null` when
+ * the buffered bytes hold no complete frame yet. The header and the body are
+ * each bounded to MCP_STDIO_MAX_FRAME_BYTES, which matches the HTTP access
+ * default `maxBodyBytes`, so a peer cannot grow the buffer without limit.
+ */
+export const MCP_STDIO_MAX_FRAME_BYTES = 131072;
+
+export type McpFrame = { kind: "body"; text: string } | { kind: "too-large" };
+
+const TOO_LARGE: McpFrame = { kind: "too-large" };
+
+export class McpFrameReader {
+  private buffer = Buffer.alloc(0);
+  /** Body bytes of a refused oversized frame that have not arrived yet. */
+  private skipBytes = 0;
+  /** Buffer length when `next` last stopped on an incomplete frame. */
+  private waitingBytes = 0;
+
+  push(chunk: Buffer): void {
+    const dropped = Math.min(this.skipBytes, chunk.length);
+    this.skipBytes -= dropped;
+    const kept = chunk.subarray(dropped);
+    if (kept.length > 0) this.buffer = Buffer.concat([this.buffer, kept]);
+  }
+
+  /** True when bytes arrived after `next` last examined the buffer. */
+  hasUnread(): boolean {
+    return this.buffer.length > this.waitingBytes;
+  }
+
+  next(): McpFrame | null {
+    this.waitingBytes = 0;
+    const headerEnd = this.buffer.indexOf("\r\n\r\n");
+    if (headerEnd < 0) {
+      if (this.buffer.length <= MCP_STDIO_MAX_FRAME_BYTES) return this.wait();
+      return this.discardBuffer();
+    }
+    if (headerEnd > MCP_STDIO_MAX_FRAME_BYTES) return this.discardBuffer();
+
+    const headers = this.buffer.subarray(0, headerEnd).toString("utf-8").split("\r\n");
+    const lengthHeader = headers.find((line) => line.toLowerCase().startsWith("content-length:"));
+    const contentLength = lengthHeader ? Number.parseInt(lengthHeader.split(":")[1]?.trim() ?? "0", 10) : NaN;
+    if (!Number.isFinite(contentLength) || contentLength < 0) {
+      this.buffer = Buffer.alloc(0);
+      return null;
+    }
+
+    const bodyStart = headerEnd + 4;
+    if (contentLength > MCP_STDIO_MAX_FRAME_BYTES) {
+      const rest = this.buffer.subarray(bodyStart);
+      this.skipBytes = Math.max(0, contentLength - rest.length);
+      this.buffer = rest.subarray(Math.min(contentLength, rest.length));
+      return TOO_LARGE;
+    }
+    const bodyEnd = bodyStart + contentLength;
+    if (this.buffer.length < bodyEnd) return this.wait();
+    const text = this.buffer.subarray(bodyStart, bodyEnd).toString("utf-8");
+    this.buffer = this.buffer.subarray(bodyEnd);
+    return { kind: "body", text };
+  }
+
+  private wait(): null {
+    this.waitingBytes = this.buffer.length;
+    return null;
+  }
+
+  private discardBuffer(): McpFrame {
+    this.buffer = Buffer.alloc(0);
+    return TOO_LARGE;
+  }
+}