@cartanova/qgrid-cli 2.7.7 → 2.7.9

package/bundle/src/application/qgrid/qgrid-oauth-redirect.test.ts

@@ -4,10 +4,18 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CONSOLE_CALLBACK_URL } from "./oauth";
 import { QgridFrame } from "./qgrid.frame";
 
-const { exchangeMock, openAIExchangeMock, tokenSaveMock, tokenDelMock, findByAccountMock, notifyMock } =
-  vi.hoisted(() => ({
+const {
+  exchangeMock,
+  openAIExchangeMock,
+  relayStartMock,
+  tokenSaveMock,
+  tokenDelMock,
+  findByAccountMock,
+  notifyMock,
+} = vi.hoisted(() => ({
   exchangeMock: vi.fn(),
   openAIExchangeMock: vi.fn(),
+  relayStartMock: vi.fn(async () => "http://localhost:1455/auth/callback"),
   tokenSaveMock: vi.fn(async () => [1]),
   tokenDelMock: vi.fn(async () => 1),
   findByAccountMock: vi.fn(async () => []),
@@ -40,6 +48,12 @@ vi.mock("../../utils/providers/openai/openai-oauth", async (importOriginal) => (
   exchangeOpenAICode: openAIExchangeMock,
 }));
 
+// The relay binds a real loopback port; these tests only assert which redirect URI is signed in.
+vi.mock("../../utils/providers/openai/openai-callback-relay", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../utils/providers/openai/openai-callback-relay")>()),
+  startOpenAICallbackRelay: relayStartMock,
+}));
+
 vi.mock("../token/token.model", () => ({
   TokenModel: {
     save: tokenSaveMock,
@@ -193,22 +207,36 @@ describe("QgridFrame direct OpenAI OAuth", () => {
     tokenDelMock.mockClear();
     findByAccountMock.mockClear().mockResolvedValue([]);
     notifyMock.mockClear();
+    relayStartMock.mockClear();
   });
 
-  it("uses the pinned loopback callback despite hostile forwarding headers", async () => {
+  it("uses manual code completion without opening a server relay on remote origins", async () => {
     mockHttpContext({ origin: "https://qgrid.example.com" });
 
     const result = await QgridFrame.oauthStartOpenAI("openai-token");
     const url = new URL(result.authUrl);
-    expect(result.mode).toBe("redirect");
+    expect(result.mode).toBe("code");
     expect(url.origin + url.pathname).toBe("https://auth.openai.com/oauth/authorize");
-    expect(url.searchParams.get("redirect_uri")).toBe("http://localhost:44900/auth/callback");
+    expect(url.searchParams.get("redirect_uri")).toBe("http://localhost:1455/auth/callback");
     expect(url.searchParams.get("state")).toBeTruthy();
     expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(relayStartMock).not.toHaveBeenCalled();
+  });
+
+  it("keeps the automatic callback relay for loopback origins", async () => {
+    mockHttpContext({ origin: "http://localhost:44900" });
+
+    const result = await QgridFrame.oauthStartOpenAI("openai-token");
+
+    expect(result.mode).toBe("redirect");
+    expect(authUrlParam(result.authUrl, "redirect_uri")).toBe(
+      "http://localhost:1455/auth/callback",
+    );
+    expect(relayStartMock).toHaveBeenCalledWith("http://localhost:44900", 5 * 60_000);
   });
 
   it("exchanges an OpenAI callback, replaces the duplicate account, and notifies", async () => {
-    mockHttpContext({ origin: "https://qgrid.example.com" });
+    mockHttpContext({ origin: "http://localhost:44900" });
     const { authUrl } = await QgridFrame.oauthStartOpenAI("openai-token");
     const state = authUrlParam(authUrl, "state")!;
     findByAccountMock.mockResolvedValueOnce([{ id: 9, active: true }] as never);
@@ -228,7 +256,7 @@ describe("QgridFrame direct OpenAI OAuth", () => {
     expect(openAIExchangeMock).toHaveBeenCalledWith(
       "the-code",
       expect.any(String),
-      "http://localhost:44900/auth/callback",
+      "http://localhost:1455/auth/callback",
     );
     expect(tokenDelMock).toHaveBeenCalledOnce();
     expect(tokenSaveMock).toHaveBeenCalledWith([
@@ -242,8 +270,43 @@ describe("QgridFrame direct OpenAI OAuth", () => {
     expect(reply.redirect).toHaveBeenCalledWith("/?oauth=success&name=openai-token");
   });
 
-  it("consumes OpenAI state before a failed exchange", async () => {
+  it("exchanges a pasted OpenAI callback URL for remote login", async () => {
     mockHttpContext({ origin: "https://qgrid.example.com" });
+    const { authUrl } = await QgridFrame.oauthStartOpenAI("remote-openai-token");
+    const state = authUrlParam(authUrl, "state")!;
+    openAIExchangeMock.mockResolvedValueOnce({
+      accessToken: "access",
+      refreshToken: "refresh",
+      idToken: "id",
+      accessTokenExpiresAt: 123,
+      idTokenExpiresAt: 456,
+      accountId: "account-1",
+      planType: "pro",
+    });
+
+    await expect(
+      QgridFrame.oauthComplete(
+        `http://localhost:1455/auth/callback?code=the-code&state=${state}`,
+      ),
+    ).resolves.toEqual({ added: true, name: "remote-openai-token" });
+
+    expect(openAIExchangeMock).toHaveBeenCalledWith(
+      "the-code",
+      expect.any(String),
+      "http://localhost:1455/auth/callback",
+    );
+    expect(tokenSaveMock).toHaveBeenCalledWith([
+      expect.objectContaining({
+        provider: "openai",
+        name: "remote-openai-token",
+        credentials: expect.objectContaining({ accountId: "account-1" }),
+      }),
+    ]);
+    expect(notifyMock).toHaveBeenCalledWith("remote-openai-token", "openai");
+  });
+
+  it("consumes OpenAI state before a failed exchange", async () => {
+    mockHttpContext({ origin: "http://localhost:44900" });
     const { authUrl } = await QgridFrame.oauthStartOpenAI("openai-token");
     const state = authUrlParam(authUrl, "state")!;
     openAIExchangeMock.mockRejectedValueOnce(new Error("exchange rejected"));

package/bundle/src/application/qgrid/qgrid.frame.test.ts

@@ -14,6 +14,7 @@ const {
   updateFieldsMock,
   requestLogSaveMock,
   requestLogCreateRunMock,
+  requestLogFinishRunMock,
   appendStepMock,
   dispatcherQueryMock,
   dispatcherQueryStreamMock,
@@ -36,6 +37,7 @@ const {
     updateFieldsMock: vi.fn(),
     requestLogSaveMock: vi.fn(),
     requestLogCreateRunMock: vi.fn(),
+    requestLogFinishRunMock: vi.fn(),
     appendStepMock: vi.fn(),
     dispatcherQueryMock: vi.fn(),
     dispatcherQueryStreamMock: vi.fn(),
@@ -53,6 +55,7 @@ vi.mock("../request-log/request-log.model", () => ({
   RequestLogModel: {
     save: requestLogSaveMock,
     createRun: requestLogCreateRunMock,
+    finishRun: requestLogFinishRunMock,
     appendStep: appendStepMock,
   },
 }));
@@ -890,6 +893,46 @@ describe("QgridFrame raw lifecycle API", () => {
       expect.not.objectContaining({ model_name: expect.anything() }),
     );
   });
+
+  it("passes optional structured metadata through the external createRun API", async () => {
+    requestLogCreateRunMock.mockReset().mockResolvedValue(82);
+    const jsonSchema = JSON.stringify({
+      type: "object",
+      properties: { answer: { type: "string" } },
+      required: ["answer"],
+    });
+
+    await QgridFrame.createRun({
+      userPrompt: "hi",
+      modelName: "google/gemini-3.5-flash-lite",
+      isStructured: true,
+      jsonSchema,
+    });
+
+    expect(requestLogCreateRunMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        is_structured: true,
+        json_schema: jsonSchema,
+      }),
+    );
+  });
+
+  it("passes optional response JSON validity through the external finishRun API", async () => {
+    requestLogFinishRunMock.mockReset().mockResolvedValue(undefined);
+
+    await QgridFrame.finishRun({
+      requestLogId: 82,
+      status: "succeeded",
+      response: '{"answer":"ok"}',
+      tokenName: "external",
+      responseJsonOk: true,
+    });
+
+    expect(requestLogFinishRunMock).toHaveBeenCalledWith(
+      82,
+      expect.objectContaining({ response_json_ok: true }),
+    );
+  });
 });
 
 describe("QgridFrame.queryStream request logging", () => {

package/bundle/src/application/qgrid/qgrid.frame.ts

@@ -12,6 +12,11 @@ import {
   getRefreshToken,
 } from "../../utils/providers/common/credentials";
 import { CallerSchemaValidationError } from "../../utils/providers/common/schema-validation";
+import {
+  OPENAI_CALLBACK_PORTS,
+  openAICallbackRedirectUri,
+  startOpenAICallbackRelay,
+} from "../../utils/providers/openai/openai-callback-relay";
 import {
   buildOpenAIAuthUrl,
   exchangeOpenAICode,
@@ -70,6 +75,7 @@ type PendingOAuth = {
 };
 const OAUTH_STATE_PREFIX = "oauth:state:";
 const OAUTH_STATE_TTL = "5m";
+const OAUTH_STATE_TTL_MS = 5 * 60_000;
 
 function unixSecondsToIso(seconds: number | null | undefined): string | null {
   return typeof seconds === "number" ? new Date(seconds * 1000).toISOString() : null;
@@ -101,9 +107,7 @@ async function deleteOAuthState(state: string): Promise<void> {
 
 const trustedLoopbackBase = () => `http://localhost:${process.env.PORT ?? "44900"}`;
 
-// Anthropic's remote/manual flow uses its fixed console callback. Headers may select between two
-// allowlisted URIs, but never contribute authority or path bytes to either URI.
-function resolveOAuthRedirect(): { redirectUri: string; mode: "redirect" | "code" } {
+function isRemoteOAuthRequest(): boolean {
   try {
     const { headers } = Sonamu.getContext();
     const origin = typeof headers.origin === "string" ? headers.origin : undefined;
@@ -112,13 +116,35 @@ function resolveOAuthRedirect(): { redirectUri: string; mode: "redirect" | "code
     const host = origin
       ? new URL(origin).hostname
       : new URL(`http://${rawHost ?? "localhost"}`).hostname;
-    if (!new Set(["localhost", "127.0.0.1", "::1", "[::1]"]).has(host)) {
-      return { redirectUri: CONSOLE_CALLBACK_URL, mode: "code" };
-    }
+    return !new Set(["localhost", "127.0.0.1", "::1", "[::1]"]).has(host);
   } catch {}
+  return false;
+}
+
+// Anthropic's remote/manual flow uses its fixed console callback. Headers may select between two
+// allowlisted URIs, but never contribute authority or path bytes to either URI.
+function resolveOAuthRedirect(): { redirectUri: string; mode: "redirect" | "code" } {
+  if (isRemoteOAuthRequest()) {
+    return { redirectUri: CONSOLE_CALLBACK_URL, mode: "code" };
+  }
   return { redirectUri: `${trustedLoopbackBase()}/callback`, mode: "redirect" };
 }
 
+function parsePastedOAuthResult(input: string): { code: string; state: string } | null {
+  const trimmed = input.trim();
+  try {
+    const callback = new URL(trimmed);
+    const code = callback.searchParams.get("code")?.trim() ?? "";
+    const state = callback.searchParams.get("state")?.trim() ?? "";
+    if (code && state) return { code, state };
+  } catch {}
+
+  const separatorAt = trimmed.indexOf("#");
+  const code = separatorAt > 0 ? trimmed.slice(0, separatorAt).trim() : "";
+  const state = separatorAt > 0 ? trimmed.slice(separatorAt + 1).trim() : "";
+  return code && state ? { code, state } : null;
+}
+
 function rejectImageGenerationStream(args: QueryInput): void {
   if (!args.imageGeneration) return;
   throw new BadRequestException(
@@ -401,6 +427,8 @@ class QgridFrameClass extends BaseFrameClass {
       project_name: input.projectName,
       system_prompt: input.systemPrompt,
       history: input.history ? JSON.parse(input.history) : undefined,
+      is_structured: input.isStructured,
+      json_schema: input.jsonSchema,
     });
     return { requestLogId };
   }
@@ -457,6 +485,7 @@ class QgridFrameClass extends BaseFrameClass {
       duration_ms: input.totalDurationMs,
       history: input.history ? JSON.parse(input.history) : undefined,
       error_message: input.errorMessage,
+      response_json_ok: input.responseJsonOk,
     });
     return { ok: true };
   }
@@ -574,18 +603,16 @@ class QgridFrameClass extends BaseFrameClass {
     return { authUrl, mode };
   }
 
-  // 코드 붙여넣기 플로우(원격 접속): 콘솔 콜백이 표시한 `code#state` 를 받아 교환한다.
+  // 원격 접속의 수동 완료: Anthropic `code#state` 또는 OpenAI callback URL을 받아 교환한다.
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async oauthComplete(pastedCode: string): Promise<{ added: boolean; name: string }> {
-    const trimmed = pastedCode.trim();
-    const separatorAt = trimmed.indexOf("#");
-    const code = separatorAt > 0 ? trimmed.slice(0, separatorAt) : "";
-    const state = separatorAt > 0 ? trimmed.slice(separatorAt + 1) : "";
-    if (!code || !state) {
+    const result = parsePastedOAuthResult(pastedCode);
+    if (!result) {
       throw new BadRequestException(
-        "expected the code shown after login, in code#state form" as LocalizedString,
+        "expected the callback URL or code shown after login, in code#state form" as LocalizedString,
       );
     }
+    const { code, state } = result;
 
     const pending = await getOAuthState(state);
     if (!pending) {
@@ -595,11 +622,12 @@ class QgridFrameClass extends BaseFrameClass {
     }
     await deleteOAuthState(state);
 
-    if (pending.provider !== "anthropic") {
-      throw new BadRequestException("login session is not for Anthropic" as LocalizedString);
+    if (pending.provider === "openai") {
+      await this.completeOpenAILogin(code, pending);
+    } else {
+      await this.completeAnthropicLogin(code, state, pending);
     }
 
-    await this.completeAnthropicLogin(code, state, pending);
     return { added: true, name: pending.name };
   }
 
@@ -630,6 +658,17 @@ class QgridFrameClass extends BaseFrameClass {
     notifyTokenAdded(pending.name, "anthropic");
   }
 
+  private async completeOpenAILogin(code: string, pending: PendingOAuth): Promise<void> {
+    const creds = await exchangeOpenAICode(code, pending.codeVerifier, pending.redirectUri);
+    await TokenModel.replaceByAccount("openai", creds.accountId, {
+      provider: "openai",
+      credentials: creds,
+      name: pending.name,
+    });
+    logger.info(`OpenAI token saved for ${pending.name}`);
+    notifyTokenAdded(pending.name, "openai");
+  }
+
   async handleOAuthCallback(code: string, state: string, reply: FastifyReply): Promise<void> {
     const pending = await getOAuthState(state);
     if (!pending) {
@@ -640,14 +679,7 @@ class QgridFrameClass extends BaseFrameClass {
 
     try {
       if (pending.provider === "openai") {
-        const creds = await exchangeOpenAICode(code, pending.codeVerifier, pending.redirectUri);
-        await TokenModel.replaceByAccount("openai", creds.accountId, {
-          provider: "openai",
-          credentials: creds,
-          name: pending.name,
-        });
-        logger.info(`OpenAI token saved for ${pending.name}`);
-        notifyTokenAdded(pending.name, "openai");
+        await this.completeOpenAILogin(code, pending);
       } else {
         await this.completeAnthropicLogin(code, state, pending);
       }
@@ -664,10 +696,24 @@ class QgridFrameClass extends BaseFrameClass {
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async oauthStartOpenAI(name: string): Promise<OAuthStartResult> {
     const { codeVerifier, codeChallenge, state } = generateOpenAIPKCE();
-    const redirectUri = `${trustedLoopbackBase()}/auth/callback`;
+    const mode = isRemoteOAuthRequest() ? "code" : "redirect";
+    let redirectUri: string;
+    if (mode === "code") {
+      // OpenAI accepts only the Codex CLI's registered loopback URI. On a remote dashboard the
+      // browser cannot reach the server's loopback, so the user pastes the resulting callback URL.
+      redirectUri = openAICallbackRedirectUri(OPENAI_CALLBACK_PORTS[0]);
+    } else {
+      try {
+        redirectUri = await startOpenAICallbackRelay(trustedLoopbackBase(), OAUTH_STATE_TTL_MS);
+      } catch {
+        throw new BadRequestException(
+          `OpenAI login needs local port ${OPENAI_CALLBACK_PORTS.join(" or ")} — close any running \`codex login\` and retry` as LocalizedString,
+        );
+      }
+    }
     const authUrl = buildOpenAIAuthUrl(codeChallenge, state, redirectUri);
     await setOAuthState(state, { codeVerifier, name, redirectUri, provider: "openai" });
-    return { authUrl, mode: "redirect" };
+    return { authUrl, mode };
   }
 
   @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"] })

package/bundle/src/application/qgrid/qgrid.types.ts

@@ -214,6 +214,8 @@ export const CreateRunInput = z.object({
   effort: z.string().optional(),
   projectName: z.string().optional(),
   history: z.string().optional(),
+  isStructured: z.boolean().optional(),
+  jsonSchema: z.string().nullable().optional(),
 });
 export type CreateRunInput = z.infer<typeof CreateRunInput>;
 
@@ -266,6 +268,7 @@ export const FinishRunInput = z.object({
   totalDurationMs: z.number().optional(),
   history: z.string().optional(),
   errorMessage: z.string().optional(),
+  responseJsonOk: z.boolean().optional(),
 });
 export type FinishRunInput = z.infer<typeof FinishRunInput>;
 
@@ -284,7 +287,7 @@ export type TokenStats = z.infer<typeof TokenStats>;
 export const OAuthStartResult = z.object({
   authUrl: z.string(),
   // redirect: 브라우저 자동 복귀(루프백 접속). code: 콘솔 콜백 + 코드 붙여넣기(원격 접속).
-  // OpenAI 경로는 고정 loopback 콜백의 직접 PKCE 라 항상 redirect 를 반환한다.
+  // OpenAI 원격 경로는 등록된 loopback callback URL 전체를 붙여넣는 code 모드를 쓴다.
   mode: z.enum(["redirect", "code"]),
 });
 export type OAuthStartResult = z.infer<typeof OAuthStartResult>;

package/bundle/src/application/request-log/request-log.model.test.ts

@@ -279,6 +279,27 @@ describe("RequestLogModel run lifecycle", () => {
     vi.restoreAllMocks();
   });
 
+  it("keeps legacy external runs unstructured when metadata is omitted", async () => {
+    const ubRegister = vi.fn();
+    const transaction = vi.fn(
+      async (cb: (trx: { ubUpsert: () => Promise<number[]> }) => Promise<number>) =>
+        cb({ ubUpsert: vi.fn(async () => [16]) }),
+    );
+    vi.spyOn(
+      RequestLogModel as unknown as {
+        getPuri: () => { ubRegister: typeof ubRegister; transaction: typeof transaction };
+      },
+      "getPuri",
+    ).mockReturnValue({ ubRegister, transaction });
+
+    await RequestLogModel.createRun({ user_prompt: "plain text" });
+
+    expect(ubRegister).toHaveBeenCalledWith(
+      "request_logs",
+      expect.objectContaining({ is_structured: false, json_schema: null }),
+    );
+  });
+
   it("stores the requested model and attached tools but no serving model when a run starts", async () => {
     const ubRegister = vi.fn();
     const transaction = vi.fn(
@@ -296,6 +317,8 @@ describe("RequestLogModel run lifecycle", () => {
       RequestLogModel.createRun({
         user_prompt: "hi",
         requested_model_name: "openai/gpt-5-codex",
+        is_structured: true,
+        json_schema: '{"type":"object"}',
         tools: [{ name: "getWeather", description: "Get weather", inputSchema: { type: "object" } }],
       }),
     ).resolves.toBe(17);
@@ -306,6 +329,8 @@ describe("RequestLogModel run lifecycle", () => {
         status: "running",
         requested_model_name: "openai/gpt-5-codex",
         model_name: null,
+        is_structured: true,
+        json_schema: '{"type":"object"}',
         tools: [{ name: "getWeather", description: "Get weather", inputSchema: { type: "object" } }],
       }),
     );

package/bundle/src/application/request-log/request-log.model.ts

@@ -483,6 +483,7 @@ class RequestLogModelClass extends BaseModelClass<
     history?: unknown;
     tools?: ToolDefinitions;
     is_image_generation?: boolean;
+    is_structured?: boolean;
     json_schema?: string | null;
   }): Promise<number> {
     const wdb = this.getPuri("w");
@@ -505,7 +506,8 @@ class RequestLogModelClass extends BaseModelClass<
       // 이미지 turn 식별(R13). run 경로(tools+image 조합)도 auto 경로와 동일하게 마킹.
       is_image_generation: params.is_image_generation ?? false,
       json_schema: params.json_schema ?? null,
-      is_structured: params.json_schema !== null && params.json_schema !== undefined,
+      is_structured:
+        params.is_structured ?? (params.json_schema !== null && params.json_schema !== undefined),
       ...(params.history !== undefined ? { history: params.history as { type: string }[] } : {}),
       ...(params.tools !== undefined ? { tools: params.tools } : {}),
     });

package/bundle/src/application/sonamu.generated.http

@@ -41,7 +41,8 @@ Content-Type: application/json
       "active": false,
       "ord": 0,
       "quota_threshold": null,
-      "weight": 1
+      "weight": 1,
+      "keepalive_enabled": false
     }
   ]
 }
@@ -437,7 +438,9 @@ Content-Type: application/json
     "modelName": "MODELNAME",
     "effort": "EFFORT",
     "projectName": "PROJECTNAME",
-    "history": "HISTORY"
+    "history": "HISTORY",
+    "isStructured": false,
+    "jsonSchema": null
   }
 }
 
@@ -501,7 +504,8 @@ Content-Type: application/json
     "costSource": "provider",
     "totalDurationMs": 0,
     "history": "HISTORY",
-    "errorMessage": "ERRORMESSAGE"
+    "errorMessage": "ERRORMESSAGE",
+    "responseJsonOk": false
   }
 }
 

package/bundle/src/sonamu.config.ts

@@ -25,6 +25,7 @@ import {
 import { loadSettings, setSettingChangeHandler } from "./application/setting/setting.store";
 import { handleServerError } from "./server-error-handler";
 import { AnthropicDispatcher } from "./utils/providers/anthropic/anthropic-dispatcher";
+import { stopOpenAICallbackRelay } from "./utils/providers/openai/openai-callback-relay";
 import { OpenAIDispatcher } from "./utils/providers/openai/openai-dispatcher";
 
 const host = process.env.HOST ?? "localhost";
@@ -241,6 +242,7 @@ export default defineConfig({
         const log = getLogger(["qgrid", "startup"]);
         stopExpiredTokenReminder();
         stopTokenWindowKeepalive();
+        stopOpenAICallbackRelay();
         setSettingChangeHandler(null);
         QgridDispatcher.subscriber?.setTokenChangeHandler(null);
         if (QgridDispatcher.openaiDispatcher) {

package/bundle/src/utils/providers/openai/openai-callback-relay.test.ts

@@ -0,0 +1,109 @@
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  OPENAI_CALLBACK_PATH,
+  OPENAI_CALLBACK_PORTS,
+  openAICallbackRedirectUri,
+  startOpenAICallbackRelay,
+  stopOpenAICallbackRelay,
+} from "./openai-callback-relay";
+
+const DASHBOARD = "http://localhost:44900";
+
+function freePort(): Promise<number> {
+  return new Promise((resolve) => {
+    const probe = http.createServer();
+    probe.listen(0, "127.0.0.1", () => {
+      const port = (probe.address() as AddressInfo).port;
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+function occupy(port: number): Promise<http.Server> {
+  return new Promise((resolve) => {
+    const server = http.createServer();
+    server.listen(port, "127.0.0.1", () => resolve(server));
+  });
+}
+
+function get(url: string): Promise<{ status: number; location?: string }> {
+  return new Promise((resolve, reject) => {
+    const request = http.get(url, (response) => {
+      response.resume();
+      resolve({
+        status: response.statusCode ?? 0,
+        ...(response.headers.location ? { location: response.headers.location } : {}),
+      });
+    });
+    request.on("error", reject);
+  });
+}
+
+describe("openai callback relay", () => {
+  const occupied: http.Server[] = [];
+
+  afterEach(async () => {
+    stopOpenAICallbackRelay();
+    await Promise.all(occupied.splice(0).map((s) => new Promise((r) => s.close(r))));
+  });
+
+  it("pins the redirect URI to the ports OpenAI registered for the Codex CLI client", () => {
+    expect(OPENAI_CALLBACK_PORTS).toEqual([1455, 1457]);
+    expect(openAICallbackRedirectUri(1455)).toBe("http://localhost:1455/auth/callback");
+  });
+
+  it("forwards only code and state to the qgrid callback route", async () => {
+    const port = await freePort();
+    const redirectUri = await startOpenAICallbackRelay(DASHBOARD, 60_000, [port]);
+    expect(redirectUri).toBe(`http://localhost:${port}${OPENAI_CALLBACK_PATH}`);
+
+    const result = await get(
+      `http://127.0.0.1:${port}${OPENAI_CALLBACK_PATH}?code=the-code&state=the-state&extra=x`,
+    );
+
+    expect(result.status).toBe(302);
+    expect(result.location).toBe(
+      `${DASHBOARD}${OPENAI_CALLBACK_PATH}?code=the-code&state=the-state`,
+    );
+  });
+
+  it("answers 404 on any other path", async () => {
+    const port = await freePort();
+    await startOpenAICallbackRelay(DASHBOARD, 60_000, [port]);
+
+    expect((await get(`http://127.0.0.1:${port}/callback?code=c&state=s`)).status).toBe(404);
+  });
+
+  it("falls back to the next registered port when the first is taken", async () => {
+    const taken = await freePort();
+    const fallback = await freePort();
+    occupied.push(await occupy(taken));
+
+    const redirectUri = await startOpenAICallbackRelay(DASHBOARD, 60_000, [taken, fallback]);
+
+    expect(redirectUri).toBe(`http://localhost:${fallback}${OPENAI_CALLBACK_PATH}`);
+  });
+
+  it("reuses the running listener for a second login", async () => {
+    const port = await freePort();
+    const first = await startOpenAICallbackRelay(DASHBOARD, 60_000, [port]);
+    const second = await startOpenAICallbackRelay(DASHBOARD, 60_000, [await freePort()]);
+
+    expect(second).toBe(first);
+  });
+
+  it("fails when every registered port is taken", async () => {
+    const a = await freePort();
+    const b = await freePort();
+    occupied.push(await occupy(a), await occupy(b));
+
+    await expect(startOpenAICallbackRelay(DASHBOARD, 60_000, [a, b])).rejects.toThrow(
+      /PORTS_UNAVAILABLE/,
+    );
+  });
+});
+