refactor(api): move the per-request keepalive frame into a helper (#17825)

changelog.d/maintenance/17825-keepalive-frame-helper.md

@@ -0,0 +1 @@
+- **refactor(api):** move the per-request Responses keepalive frame into a helper so `/v1/responses` stays under the cognitive-complexity ratchet after #18197 (#17825)

src/app/api/v1/responses/route.ts

@@ -104,6 +104,15 @@ export async function withCodexPreferredModel(
  * POST /v1/responses - OpenAI Responses API format
  * Handled by the unified chat handler (openai-responses format auto-detected).
  */
+// #17825: per-request complete frame (stable id, request-time created_at, request model).
+function buildRequestKeepaliveFrame(body: { model?: unknown } | null | undefined) {
+  const model = body?.model;
+  return buildResponsesInProgressFrame({
+    id: buildKeepaliveResponseId(),
+    model: typeof model === "string" ? model : undefined,
+  });
+}
+
 async function postHandler(request: any) {
   // Defense-in-depth: the authz proxy (src/proxy.ts) is the primary gate, but
   // its matcher can miss path variants (e.g. uppercase /V1/ aliases), so the
@@ -229,11 +238,7 @@ async function postHandler(request: any) {
         admission.lease,
         { signal: streamSignal }
       );
-      // #17825: per-request complete frame (stable id, request-time created_at, request model).
-      const keepaliveFrame = buildResponsesInProgressFrame({
-        id: buildKeepaliveResponseId(),
-        model: typeof resolvedBody?.model === "string" ? resolvedBody.model : undefined,
-      });
+      const keepaliveFrame = buildRequestKeepaliveFrame(resolvedBody);
       return await withEarlyStreamKeepalive(handlerResponse, {
         signal: streamSignal,
         thresholdMs,

tests/unit/responses-route-early-keepalive-wiring.test.ts

@@ -30,6 +30,15 @@ test("Responses route wires dual-cadence neutral keepalives", () => {
   assert.doesNotMatch(routeSource, /RESPONSES_STARTUP_THINKING_FRAME/);
 });
 
+test("Responses route builds one keepalive frame per request from the request model (#17825)", () => {
+  assert.match(routeSource, /const keepaliveFrame = buildRequestKeepaliveFrame\(resolvedBody\);/);
+  assert.match(
+    routeSource,
+    /function buildRequestKeepaliveFrame\([\s\S]*?id: buildKeepaliveResponseId\(\),[\s\S]*?typeof model === "string" \? model : undefined/,
+    "each request gets a fresh keepalive id and its own model, never a shared constant frame"
+  );
+});
+
 test("Responses route applies heavyweight admission through the SSE lifecycle", () => {
   assert.match(routeSource, /admitChatRequest\(request,/);
   assert.match(routeSource, /admitChatStructure\(parsedBody, admission\.lease,/);