@cartanova/qgrid-cli 2.7.6 → 2.7.9

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,
   },
 }));
@@ -111,6 +114,7 @@ const tokenEntry = {
   ord: 0,
   quota_threshold: null,
   weight: 1,
+  keepalive_enabled: false,
 };
 
 function deeplyNestedInputSchema(depth: number): unknown {
@@ -164,6 +168,14 @@ describe("QgridFrame.updateToken", () => {
     expect(updateFieldsMock).toHaveBeenCalledWith(1, { weight: 4 });
   });
 
+  it("updates only the supplied keepalive switch", async () => {
+    await expect(QgridFrame.updateToken(1, undefined, undefined, undefined, true)).resolves.toEqual({
+      updated: true,
+    });
+
+    expect(updateFieldsMock).toHaveBeenCalledWith(1, { keepalive_enabled: true });
+  });
+
   it("reports a missing token from the atomic update result", async () => {
     updateFieldsMock.mockResolvedValueOnce(0);
 
@@ -881,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 };
   }
@@ -505,6 +534,7 @@ class QgridFrameClass extends BaseFrameClass {
     name?: string,
     quotaThreshold?: number | null,
     weight?: number,
+    keepaliveEnabled?: boolean,
   ): Promise<{ updated: boolean }> {
     if (
       quotaThreshold !== undefined &&
@@ -525,6 +555,7 @@ class QgridFrameClass extends BaseFrameClass {
     if (name !== undefined) patch.name = name;
     if (quotaThreshold !== undefined) patch.quota_threshold = quotaThreshold;
     if (weight !== undefined) patch.weight = weight;
+    if (keepaliveEnabled !== undefined) patch.keepalive_enabled = keepaliveEnabled;
     if (Object.keys(patch).length === 0) return { updated: false };
 
     const updated = await TokenModel.updateFields(id, patch);
@@ -572,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) {
@@ -593,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 };
   }
 
@@ -628,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) {
@@ -638,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);
       }
@@ -662,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/qgrid/token-trigger-setup.test.ts

@@ -6,4 +6,10 @@ describe("tokens trigger setup", () => {
   it("leaves weight notifications to the versioned migration trigger", () => {
     expect(TOKENS_TRIGGER_SETUP_SQL).not.toContain("OLD.weight IS DISTINCT FROM NEW.weight");
   });
+
+  it("notifies subscribers when per-token keepalive membership changes", () => {
+    expect(TOKENS_TRIGGER_SETUP_SQL).toContain(
+      "OLD.keepalive_enabled IS DISTINCT FROM NEW.keepalive_enabled",
+    );
+  });
 });

package/bundle/src/application/qgrid/token-trigger-setup.ts

@@ -40,7 +40,8 @@ export const TOKENS_TRIGGER_SETUP_SQL = `
     OLD.credentials IS DISTINCT FROM NEW.credentials OR
     OLD.provider IS DISTINCT FROM NEW.provider OR
     OLD.name IS DISTINCT FROM NEW.name OR
-    OLD.quota_threshold IS DISTINCT FROM NEW.quota_threshold
+    OLD.quota_threshold IS DISTINCT FROM NEW.quota_threshold OR
+    OLD.keepalive_enabled IS DISTINCT FROM NEW.keepalive_enabled
   )
   EXECUTE FUNCTION public.tokens_notify();
 `;

package/bundle/src/application/qgrid/token-window-keepalive.test.ts

@@ -15,13 +15,19 @@ const FIVE_HOURS_MS = 5 * 60 * 60 * 1_000;
 
 function token(
   id: number,
-  overrides: Partial<{ name: string; provider: string; active: boolean }> = {},
+  overrides: Partial<{
+    name: string;
+    provider: string;
+    active: boolean;
+    keepalive_enabled: boolean;
+  }> = {},
 ) {
   return {
     id,
     name: `anthropic/token-${id}`,
     provider: "anthropic",
     active: true,
+    keepalive_enabled: true,
     ...overrides,
   };
 }
@@ -40,6 +46,7 @@ function deps(overrides: Partial<TokenWindowKeepaliveDeps> = {}): TokenWindowKee
     readUsage: vi.fn(async () => usage(new Date(NOW + FIVE_HOURS_MS).toISOString())),
     dispatch: vi.fn(async () => undefined),
     readSetting: () => "true",
+    isRunnerEnabled: () => true,
     now: () => Date.now(),
     setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
     clearTimer: (handle) => clearTimeout(handle),
@@ -108,7 +115,7 @@ describe("token window keepalive", () => {
     expect(dispatch).toHaveBeenCalledTimes(1);
   });
 
-  it("비활성 토큰과 Anthropic 이 아닌 토큰은 대상에서 제외한다", async () => {
+  it("비활성·비Anthropic·keepalive off 토큰은 대상에서 제외한다", async () => {
     const readUsage = vi.fn(async () => usage(new Date(NOW + FIVE_HOURS_MS).toISOString()));
     await startTokenWindowKeepalive(
       deps({
@@ -116,6 +123,7 @@ describe("token window keepalive", () => {
           token(1),
           token(2, { provider: "openai" }),
           token(3, { active: false }),
+          token(4, { keepalive_enabled: false }),
         ]),
         readUsage,
       }),
@@ -211,6 +219,19 @@ describe("token window keepalive", () => {
     expect(vi.getTimerCount()).toBe(0);
   });
 
+  it("이 인스턴스가 runner로 지정되지 않으면 전역 스위치와 무관하게 시작하지 않는다", async () => {
+    const testDeps = deps({
+      isRunnerEnabled: () => false,
+      readSetting: vi.fn(() => "true"),
+    });
+
+    await startTokenWindowKeepalive(testDeps);
+
+    expect(testDeps.findTokens).not.toHaveBeenCalled();
+    expect(testDeps.readSetting).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
   it("실행 중 스위치를 끄고 재예약하면 기존 타이머를 정리한다", async () => {
     const testDeps = deps();
     await startTokenWindowKeepalive(testDeps);

package/bundle/src/application/qgrid/token-window-keepalive.ts

@@ -1,5 +1,6 @@
 import { getLogger } from "@logtape/logtape";
 
+import { TOKEN_WINDOW_KEEPALIVE_RUNNER_ENV_KEY } from "../setting/setting.constant";
 import { getSetting } from "../setting/setting.store";
 import { TokenModel } from "../token/token.model";
 import { type InternalQueryInput } from "./qgrid.dispatcher";
@@ -17,13 +18,14 @@ export const POST_KEEPALIVE_USAGE_DELAY_MS = 61_000;
 export const KEEPALIVE_MODEL = "anthropic/claude-haiku-4-5";
 export const KEEPALIVE_PROJECT_NAME = "qgrid-token-window-keepalive";
 export const KEEPALIVE_SETTING_KEY = "qgrid.tokenWindowKeepaliveEnabled";
-export const KEEPALIVE_ENV_KEY = "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED";
+export const KEEPALIVE_ENV_KEY = TOKEN_WINDOW_KEEPALIVE_RUNNER_ENV_KEY;
 
 type KeepaliveToken = {
   id: number;
   name: string;
   provider: string;
   active: boolean;
+  keepalive_enabled: boolean;
 };
 
 type TimerHandle = ReturnType<typeof setTimeout>;
@@ -33,6 +35,7 @@ export type TokenWindowKeepaliveDeps = {
   readUsage: (tokenId: number) => Promise<UsageResponse>;
   dispatch: (input: InternalQueryInput) => Promise<unknown>;
   readSetting: typeof getSetting;
+  isRunnerEnabled: () => boolean;
   now: () => number;
   setTimer: (callback: () => void, delayMs: number) => TimerHandle;
   clearTimer: (handle: TimerHandle) => void;
@@ -43,6 +46,7 @@ const defaultDeps: TokenWindowKeepaliveDeps = {
   readUsage: (tokenId) => QgridFrame.usage(tokenId),
   dispatch: (input) => QgridFrame.query(input),
   readSetting: getSetting,
+  isRunnerEnabled: () => process.env[KEEPALIVE_ENV_KEY] === "true",
   now: () => Date.now(),
   setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
   clearTimer: (handle) => clearTimeout(handle),
@@ -191,7 +195,11 @@ export async function startTokenWindowKeepalive(
   deps: TokenWindowKeepaliveDeps = defaultDeps,
 ): Promise<void> {
   clearScheduledTimers();
-  if (deps.readSetting(KEEPALIVE_SETTING_KEY, KEEPALIVE_ENV_KEY) === "false") {
+  if (!deps.isRunnerEnabled()) {
+    logger.info("token window keepalive runner disabled for this instance");
+    return;
+  }
+  if (deps.readSetting(KEEPALIVE_SETTING_KEY) === "false") {
     logger.info("token window keepalive disabled");
     return;
   }
@@ -206,7 +214,9 @@ export async function startTokenWindowKeepalive(
   }
   if (generation !== expectedGeneration) return;
 
-  const targets = tokens.filter((token) => token.active && token.provider === "anthropic");
+  const targets = tokens.filter(
+    (token) => token.active && token.provider === "anthropic" && token.keepalive_enabled,
+  );
   const targetIds = new Set(targets.map((token) => token.id));
   for (const tokenId of fireGuards.keys()) {
     if (!targetIds.has(tokenId)) fireGuards.delete(tokenId);

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/setting/setting.constant.test.ts

@@ -76,11 +76,11 @@ describe("SETTING_DEFS", () => {
   it("token window keepalive 비상 스위치를 즉시 적용 설정으로 등록한다", () => {
     expect(findSettingDef("qgrid.tokenWindowKeepaliveEnabled")).toMatchObject({
       group: "qgrid",
-      envKey: "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED",
       kind: "boolean",
       applies: "immediate",
       fallback: "true",
     });
+    expect(findSettingDef("qgrid.tokenWindowKeepaliveEnabled")?.envKey).toBeUndefined();
   });
 
   it("키가 중복되지 않는다", () => {
@@ -90,7 +90,7 @@ describe("SETTING_DEFS", () => {
 
   it("env 키도 중복되지 않는다", () => {
     // 겹치면 한 env 를 두 설정이 서로 덮어쓴다.
-    const envKeys = SETTING_DEFS.map((d) => d.envKey);
+    const envKeys = SETTING_DEFS.flatMap((d) => (d.envKey ? [d.envKey] : []));
     expect(new Set(envKeys).size).toBe(envKeys.length);
   });
 

package/bundle/src/application/setting/setting.constant.ts

@@ -22,7 +22,7 @@ export type SettingGroup = "qgrid" | "slack" | "slackConnection";
 export type SettingDef = {
   key: string;
   group: SettingGroup;
-  envKey: string;
+  envKey?: string;
   label: string;
   kind: SettingKind;
   /** 적용 시점. 부팅 시 한 번만 읽히는 값은 재시작이 필요하다. */
@@ -39,16 +39,21 @@ export type SettingDef = {
   help?: string;
 };
 
+/**
+ * keepalive 스케줄러를 실제로 소유할 인스턴스만 켠다. Settings DB 값과 일부러 분리한다 —
+ * 같은 DB를 보는 개발자 로컬 인스턴스가 전역 설정을 읽고 함께 발사하면 중복 요청이 된다.
+ */
+export const TOKEN_WINDOW_KEEPALIVE_RUNNER_ENV_KEY = "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED";
+
 export const SETTING_DEFS: SettingDef[] = [
   {
     key: "qgrid.tokenWindowKeepaliveEnabled",
     fallback: "true",
     group: "qgrid",
-    envKey: "QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED",
     label: "토큰 윈도우 keepalive",
     kind: "boolean",
     applies: "immediate",
-    help: "끄면 활성 Anthropic 토큰의 5시간 윈도우 자동 유지 요청을 중단합니다",
+    help: "끄면 이 서버에서 선택한 Anthropic 토큰의 5시간 윈도우 자동 유지 요청을 중단합니다",
   },
   {
     key: "slack.enabled",

package/bundle/src/application/setting/setting.model.ts

@@ -16,7 +16,13 @@ import { detectSupervisor } from "../../utils/process-supervisor";
 import { armServerRestartExit, beginServerRestart } from "../../utils/server-restart";
 import { type SettingSubsetKey, type SettingSubsetMapping } from "../sonamu.generated";
 import { settingSubsetQueries, settingLoaderQueries } from "../sonamu.generated.sso";
-import { findSettingDef, maskSecret, SETTING_DEFS, validateSettingValue } from "./setting.constant";
+import {
+  findSettingDef,
+  maskSecret,
+  SETTING_DEFS,
+  TOKEN_WINDOW_KEEPALIVE_RUNNER_ENV_KEY,
+  validateSettingValue,
+} from "./setting.constant";
 import {
   getSetting,
   isStored,
@@ -252,7 +258,12 @@ class SettingModelClass extends BaseModelClass<
       };
     });
 
-    return { settings, runtime: this.runtimeInfo(), supervisor: detectSupervisor() };
+    return {
+      settings,
+      runtime: this.runtimeInfo(),
+      supervisor: detectSupervisor(),
+      keepaliveRunnerEnabled: process.env[TOKEN_WINDOW_KEEPALIVE_RUNNER_ENV_KEY] === "true",
+    };
   }
 
   private runtimeInfo(): RuntimeInfoItem[] {

package/bundle/src/application/setting/setting.store.ts

@@ -54,8 +54,8 @@ export async function loadSettings(persistence: SettingPersistence = SettingMode
 }
 
 /** DB → env 순. 둘 다 없으면 undefined 라 호출부의 기본값으로 떨어진다. */
-export function getSetting(key: string, envKey: string): string | undefined {
-  return cache?.get(key) ?? process.env[envKey];
+export function getSetting(key: string, envKey?: string): string | undefined {
+  return cache?.get(key) ?? (envKey ? process.env[envKey] : undefined);
 }
 
 /** 저장된 값인지 — 화면에서 출처를 구분해 보여준다. */

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

@@ -61,5 +61,7 @@ export const SettingsResponse = z.object({
   runtime: RuntimeInfoItem.array(),
   /** null 이면 재시작 버튼을 쓸 수 없다 — 종료해도 되살릴 주체가 없다. */
   supervisor: SupervisorKind.nullable(),
+  /** 이 인스턴스가 keepalive 스케줄러를 소유하도록 명시적으로 허용됐는지. */
+  keepaliveRunnerEnabled: z.boolean(),
 });
 export type SettingsResponse = z.infer<typeof SettingsResponse>;