@cartanova/qgrid-cli 2.7.6 → 2.7.7

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/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>;

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

@@ -566,7 +566,8 @@ Content-Type: application/json
   "id": 0,
   "name": "NAME",
   "quotaThreshold": null,
-  "weight": 0
+  "weight": 0,
+  "keepaliveEnabled": false
 }
 
 ###

package/bundle/src/application/sonamu.generated.sso.ts

@@ -213,6 +213,7 @@ export const tokenSubsetQueries = {
       ord: "tokens.ord",
       quota_threshold: "tokens.quota_threshold",
       weight: "tokens.weight",
+      keepalive_enabled: "tokens.keepalive_enabled",
     });
   },
 };

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

@@ -299,6 +299,7 @@ export const TokenBaseSchema = z.object({
   ord: z.int(),
   quota_threshold: z.int().nullable(),
   weight: z.int(),
+  keepalive_enabled: z.boolean(),
 });
 export type TokenBaseSchema = z.infer<typeof TokenBaseSchema> & {
   readonly __hasDefault__: readonly [
@@ -307,6 +308,7 @@ export type TokenBaseSchema = z.infer<typeof TokenBaseSchema> & {
     "ord",
     "quota_threshold",
     "weight",
+    "keepalive_enabled",
     "id",
   ];
 };
@@ -558,6 +560,7 @@ export const TokenSubsetA = z.object({
   ord: z.int(),
   quota_threshold: z.int().nullable(),
   weight: z.int(),
+  keepalive_enabled: z.boolean(),
 });
 export type TokenSubsetA = z.infer<typeof TokenSubsetA>;
 export type TokenSubsetMapping = {

package/bundle/src/application/token/token.entity.json

@@ -26,6 +26,12 @@
       "type": "integer",
       "desc": "가중 라운드로빈 라우팅 가중치 (1..100)",
       "dbDefault": "1"
+    },
+    {
+      "name": "keepalive_enabled",
+      "type": "boolean",
+      "desc": "Anthropic 5시간 토큰 윈도우 keepalive 사용 여부",
+      "dbDefault": "false"
     }
   ],
   "indexes": [
@@ -46,7 +52,8 @@
       "active",
       "ord",
       "quota_threshold",
-      "weight"
+      "weight",
+      "keepalive_enabled"
     ]
   },
   "enums": {

package/bundle/src/application/token/token.model.test.ts

@@ -111,6 +111,35 @@ describe("TokenModel.updateFields", () => {
   });
 });
 
+describe("TokenModel.replaceByAccount", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("re-login으로 row가 교체돼도 기존 keepalive 선택을 보존한다", async () => {
+    vi.spyOn(TokenModel, "findByAccountIdentifier").mockResolvedValue([
+      {
+        id: 1,
+        created_at: new Date(),
+        active: true,
+        ord: 0,
+        quota_threshold: 80,
+        weight: 1,
+        keepalive_enabled: true,
+        ...baseToken,
+      },
+    ]);
+    vi.spyOn(TokenModel, "del").mockResolvedValue(1);
+    const save = vi.spyOn(TokenModel, "save").mockResolvedValue([2]);
+
+    await TokenModel.replaceByAccount("anthropic", "acc-1", baseToken);
+
+    expect(save).toHaveBeenCalledWith([
+      expect.objectContaining({ keepalive_enabled: true }),
+    ]);
+  });
+});
+
 describe("TokenModel.findActiveByProviderAndName", () => {
   afterEach(() => {
     vi.restoreAllMocks();

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

@@ -23,6 +23,7 @@ export type TokenUpdateFields = {
   name?: string;
   quota_threshold?: number | null;
   weight?: number;
+  keepalive_enabled?: boolean;
 };
 
 function applyCreateDefaults(sp: TokenSaveParams): TokenSaveParams {
@@ -235,8 +236,12 @@ class TokenModelClass extends BaseModelClass<
     accountId: string | undefined,
     saveParams: TokenSaveParams,
   ): Promise<void> {
+    let keepaliveEnabled = saveParams.keepalive_enabled;
     if (accountId) {
       const oldEntries = await this.findByAccountIdentifier("A", provider, accountId);
+      if (keepaliveEnabled === undefined && oldEntries.length > 0) {
+        keepaliveEnabled = oldEntries.some((entry) => entry.keepalive_enabled);
+      }
       if (oldEntries.length > 0) await this.del(oldEntries.map((o) => o.id));
     } else {
       logger.warn(
@@ -244,7 +249,11 @@ class TokenModelClass extends BaseModelClass<
       );
     }
 
-    await this.save([saveParams]);
+    await this.save([
+      keepaliveEnabled === undefined
+        ? saveParams
+        : { ...saveParams, keepalive_enabled: keepaliveEnabled },
+    ]);
   }
 
   /**

package/bundle/src/application/token/token.types.test.ts

@@ -42,4 +42,14 @@ describe("TokenSaveParams", () => {
       expect(() => TokenSaveParams.parse({ ...baseToken, weight })).toThrow();
     }
   });
+
+  it("keeps per-token keepalive opt-in optional and accepts booleans", () => {
+    expect(TokenSaveParams.parse(baseToken)).not.toHaveProperty("keepalive_enabled");
+    expect(
+      TokenSaveParams.parse({ ...baseToken, keepalive_enabled: true }).keepalive_enabled,
+    ).toBe(true);
+    expect(() =>
+      TokenSaveParams.parse({ ...baseToken, keepalive_enabled: "true" }),
+    ).toThrow();
+  });
 });

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

@@ -41,6 +41,7 @@ export const TokenSaveParams = TokenBaseSchema.partial({
   ord: true,
   quota_threshold: true,
   weight: true,
+  keepalive_enabled: true,
 }).extend({
   quota_threshold: TokenQuotaThreshold.optional(),
   weight: TokenWeight.optional(),

package/bundle/src/i18n/sd.generated.ts

@@ -320,6 +320,7 @@ const entityLabels = {
   "entity.Token.ord": "정렬 순서",
   "entity.Token.quota_threshold": "quota 사용률 임계치(%). null이면 미설정",
   "entity.Token.weight": "가중 라운드로빈 라우팅 가중치 (1..100)",
+  "entity.Token.keepalive_enabled": "Anthropic 5시간 토큰 윈도우 keepalive 사용 여부",
   "enum.TokenOrderBy.id-desc": "ID최신순",
   "enum.TokenOrderBy.ord-asc": "순서순",
   "enum.TokenSearchField.id": "ID",

package/bundle/src/migrations/20260820153531_alter_tokens_add1_alter1.ts

@@ -0,0 +1,15 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // add
+    table.boolean("keepalive_enabled").notNullable().defaultTo(knex.raw("false"));
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // rollback - add
+    table.dropColumns("keepalive_enabled");
+  });
+}

package/bundle/src/utils/providers/openai/openai-quota.test.ts

@@ -147,6 +147,37 @@ describe("readOpenAIQuotaUsage", () => {
     });
   });
 
+  it("converts the current WHAM limit_window_seconds duration to minutes", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () =>
+      new Response(
+        JSON.stringify({
+          rate_limit: {
+            primary_window: {
+              used_percent: 21,
+              limit_window_seconds: 604_800,
+              reset_at: 123,
+            },
+          },
+        }),
+        { status: 200 },
+      ),
+    );
+
+    await expect(
+      readOpenAIQuotaUsage({
+        credentials: { accessToken: "access", accountId: "acct" },
+        fetch: fetchMock,
+      }),
+    ).resolves.toMatchObject({
+      kind: "ok",
+      raw: {
+        rateLimits: {
+          primary: { usedPercent: 21, windowDurationMins: 10_080, resetsAt: 123 },
+        },
+      },
+    });
+  });
+
   it("fails open for direct HTTP failures", async () => {
     await expect(
       readOpenAIQuotaUsage({

package/bundle/src/utils/providers/openai/openai-quota.ts

@@ -47,11 +47,17 @@ function windowFrom(value: unknown) {
   const source = value as Record<string, unknown>;
   const usedPercent = Number(source.usedPercent ?? source.used_percent);
   if (!Number.isFinite(usedPercent)) return null;
-  const duration = source.windowDurationMins ?? source.window_minutes;
+  const durationMins = source.windowDurationMins ?? source.window_minutes;
+  const durationSeconds = source.limitWindowSeconds ?? source.limit_window_seconds;
   const resets = source.resetsAt ?? source.reset_at;
   return {
     usedPercent,
-    windowDurationMins: duration === null || duration === undefined ? null : Number(duration),
+    windowDurationMins:
+      durationMins !== null && durationMins !== undefined
+        ? Number(durationMins)
+        : durationSeconds !== null && durationSeconds !== undefined
+          ? Number(durationSeconds) / 60
+          : null,
     resetsAt: resets === null || resets === undefined ? null : Number(resets),
   };
 }