@cartanova/qgrid-cli 2.7.5 → 2.7.7

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

@@ -111,6 +111,72 @@ 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();
+  });
+
+  it("active·provider·name 세 조건으로 단일 토큰을 조회한다", async () => {
+    const where = vi.fn();
+    const qb = { where };
+    const row = { id: 7, active: true, ...baseToken };
+    vi.spyOn(
+      TokenModel as unknown as { getSubsetQueries: (subset: "A") => { qb: typeof qb } },
+      "getSubsetQueries",
+    ).mockReturnValue({ qb });
+    const executeSubsetQuery = vi
+      .spyOn(
+        TokenModel as unknown as {
+          executeSubsetQuery: (input: unknown) => Promise<{ rows: typeof row[] }>;
+        },
+        "executeSubsetQuery",
+      )
+      .mockResolvedValue({ rows: [row] });
+
+    await expect(
+      TokenModel.findActiveByProviderAndName("A", "anthropic", "anthropic/tok-A"),
+    ).resolves.toBe(row);
+
+    expect(where.mock.calls).toEqual([
+      ["tokens.active", true],
+      ["tokens.provider", "anthropic"],
+      ["tokens.name", "anthropic/tok-A"],
+    ]);
+    expect(executeSubsetQuery).toHaveBeenCalledWith(
+      expect.objectContaining({ subset: "A", qb, params: { num: 1, page: 1 } }),
+    );
+  });
+});
+
 describe("TokenModel.deactivateIfActive", () => {
   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 {
@@ -146,6 +147,26 @@ class TokenModelClass extends BaseModelClass<
     return result.rows;
   }
 
+  async findActiveByProviderAndName<T extends TokenSubsetKey>(
+    subset: T,
+    provider: string,
+    name: string,
+  ): Promise<TokenSubsetMapping[T] | undefined> {
+    const { qb } = this.getSubsetQueries(subset);
+    qb.where("tokens.active", true);
+    qb.where("tokens.provider", provider);
+    qb.where("tokens.name", name);
+    const enhancers = this.createEnhancers({ A: (row) => ({ ...row }) });
+    const result = await this.executeSubsetQuery({
+      subset,
+      qb,
+      params: { num: 1, page: 1 },
+      enhancers,
+      debug: false,
+    });
+    return result.rows[0];
+  }
+
   /**
    * 라우팅에서 빠진 토큰들. 세션 만료로 자동 비활성화된 것과 수동으로 끈 것이 섞여 있다 —
    * 둘 다 "재로그인하면 살아나는" 상태라 알림 대상으로는 같게 본다.
@@ -215,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(
@@ -224,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/20260819102011_alter_tokens_alter1.ts

@@ -0,0 +1,13 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw(
+    `CREATE UNIQUE INDEX tokens_provider_name_unique ON tokens USING btree(provider ASC NULLS LAST, name ASC NULLS LAST) NULLS DISTINCT;`,
+  );
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    table.dropIndex(["provider", "name"], "tokens_provider_name_unique");
+  });
+}

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/sonamu.config.ts

@@ -17,6 +17,11 @@ import { QgridDispatcher } from "./application/qgrid/qgrid.dispatcher";
 import { QgridFrame } from "./application/qgrid/qgrid.frame";
 import { TokenSubscriber } from "./application/qgrid/token-subscriber";
 import { ensureTokensTrigger } from "./application/qgrid/token-trigger-setup";
+import {
+  rescheduleTokenWindowKeepalive,
+  startTokenWindowKeepalive,
+  stopTokenWindowKeepalive,
+} from "./application/qgrid/token-window-keepalive";
 import { loadSettings, setSettingChangeHandler } from "./application/setting/setting.store";
 import { handleServerError } from "./server-error-handler";
 import { AnthropicDispatcher } from "./utils/providers/anthropic/anthropic-dispatcher";
@@ -176,6 +181,9 @@ export default defineConfig({
           if (key === "slack.expiryReminderMinutes" || key === "slack.remindersEnabled") {
             rescheduleExpiredTokenReminder();
           }
+          if (key === "qgrid.tokenWindowKeepaliveEnabled") {
+            void rescheduleTokenWindowKeepalive();
+          }
         });
 
         let triggerReady = true;
@@ -213,7 +221,11 @@ export default defineConfig({
           log.warn(`anthropic dispatcher failed: ${(e as Error).message}`);
         }
 
+        subscriber.setTokenChangeHandler(() => {
+          void rescheduleTokenWindowKeepalive();
+        });
         startExpiredTokenReminder();
+        void startTokenWindowKeepalive();
 
         const anthropicCount = QgridDispatcher.anthropicDispatcher?.tokenCount ?? 0;
         const openaiCount = QgridDispatcher.openaiDispatcher?.tokenCount ?? 0;
@@ -228,7 +240,9 @@ export default defineConfig({
       onShutdown: async () => {
         const log = getLogger(["qgrid", "startup"]);
         stopExpiredTokenReminder();
+        stopTokenWindowKeepalive();
         setSettingChangeHandler(null);
+        QgridDispatcher.subscriber?.setTokenChangeHandler(null);
         if (QgridDispatcher.openaiDispatcher) {
           await QgridDispatcher.openaiDispatcher.stop();
         }

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.test.ts

@@ -249,6 +249,52 @@ describe("AnthropicDispatcher", () => {
     expect(readAnthropicQuotaUsageMock).not.toHaveBeenCalled();
   });
 
+  it("preferredTokenId 가 있으면 가중 선택과 무관하게 그 토큰을 고른다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 10);
+    d.onTokenAdded(2, "tok-B", creds(), null, 1);
+
+    const result = await d.generate(baseReq({ preferredTokenId: 2 }));
+
+    expect(result.tokenName).toBe("tok-B");
+  });
+
+  it("preferredTokenId 가 풀에 없으면 다른 토큰으로 대체하지 않는다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+
+    await expect(d.generate(baseReq({ preferredTokenId: 99 }))).rejects.toThrow(
+      "Preferred anthropic token 99 is not available",
+    );
+    expect(runClaudeSessionMock).not.toHaveBeenCalled();
+  });
+
+  it("지정 토큰이 threshold 를 넘으면 eligible 토큰으로 대체하지 않는다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+    d.onTokenAdded(2, "tok-B", creds(), 80, 1);
+    readAnthropicQuotaUsageMock.mockResolvedValueOnce(quotaOk(80));
+
+    const error = await d.generate(baseReq({ preferredTokenId: 2 })).catch((e) => e);
+
+    expect(error).toBeInstanceOf(QuotaThresholdExceededError);
+    expect(error.message).toBe(
+      "All anthropic tokens exceeded quota threshold: tok-B (threshold 80%)",
+    );
+    expect(readAnthropicQuotaUsageMock).toHaveBeenCalledTimes(1);
+    expect(runClaudeSessionMock).not.toHaveBeenCalled();
+  });
+
+  it("지정 선택은 다음 비지정 요청의 가중 선택 상태를 소비하지 않는다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+    d.onTokenAdded(2, "tok-B", creds(), null, 2);
+
+    expect((await d.generate(baseReq())).tokenName).toBe("tok-B");
+    expect((await d.generate(baseReq({ preferredTokenId: 2 }))).tokenName).toBe("tok-B");
+    expect((await d.generate(baseReq())).tokenName).toBe("tok-A");
+  });
+
   it("recomputes weighted selection from quota-eligible tokens", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds(), 80, 10);

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -161,9 +161,16 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     this.weightedSelector.removeToken(id);
   }
 
-  // quota 통과 후보만으로 요청마다 smooth weighted round-robin 선택한다.
-  private async selectToken(): Promise<PooledToken | null> {
-    const rows = [...this.tokenPool.values()];
+  // 지정 요청은 해당 토큰만 quota 판정하고 weighted 상태를 건드리지 않는다.
+  // 미지정 요청만 quota 통과 후보로 smooth weighted round-robin 을 진행한다.
+  private async selectToken(preferredTokenId?: number): Promise<PooledToken | null> {
+    const preferred =
+      preferredTokenId === undefined ? undefined : this.tokenPool.get(preferredTokenId);
+    if (preferredTokenId !== undefined && !preferred) {
+      throw new Error(`Preferred anthropic token ${preferredTokenId} is not available`);
+    }
+
+    const rows = preferred ? [preferred] : [...this.tokenPool.values()];
     if (rows.length === 0) return null;
     const { eligible, overThresholdTokens } = await this.filterEligibleTokens(rows);
     if (eligible.length === 0) {
@@ -179,6 +186,8 @@ export class AnthropicDispatcher implements ProviderDispatcher {
       );
     }
 
+    if (preferred) return preferred;
+
     const selectedId = this.weightedSelector.select(new Set(eligible.map((token) => token.id)));
     if (selectedId === null) return null;
     return this.tokenPool.get(selectedId) ?? null;
@@ -305,7 +314,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     const model = canonicalAnthropicModel(req.model);
     const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
 
-    const token = await this.selectToken();
+    const token = await this.selectToken(req.preferredTokenId);
     if (!token) throw new Error("No anthropic tokens available");
 
     const exec = async (): Promise<GenerateResult> => {

package/bundle/src/utils/providers/common/provider-dispatcher.ts

@@ -64,6 +64,8 @@ export interface GenerateRequest {
   // and prompt-cache routing without relying on a process-local worker/thread.
   promptCacheKey?: string;
   preferredTokenId?: number;
+  // 사람이 지정한 exact target. Cache affinity 선호와 달리 부적격 시 다른 토큰으로 대체하지 않는다.
+  requirePreferredToken?: boolean;
   // 재사용 좌표 + delta input. 둘은 한 쌍 — 검증 통과 시에만 설정한다.
   // dispatcher 가 worker/thread 생존을 재검증해 성공하면 reuseInput(delta)을, 실패하면
   // coldInput + coldHistory 로 폴백한다(전체 history 로 문맥 복구).

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

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 
+import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
 import { type GenerateRequest } from "../common/provider-dispatcher";
 import {
   type OpenAINormalizedEvent,
@@ -178,6 +179,35 @@ describe("OpenAIDispatcher direct runtime", () => {
     expect((await d.generate(request())).tokenName).toBe("two");
   });
 
+  it("required preferred token 이 없으면 다른 토큰으로 대체하지 않는다", async () => {
+    const d = dispatcher(() => events({ type: "completed", responseId: "r" }));
+    await d.onTokenAdded(1, "one", credentials);
+
+    await expect(
+      d.generate(request({ preferredTokenId: 99, requirePreferredToken: true })),
+    ).rejects.toThrow("Preferred openai token 99 is not available");
+  });
+
+  it("required preferred token 이 threshold 를 넘으면 eligible 토큰으로 대체하지 않는다", async () => {
+    const d = new OpenAIDispatcher(config(), {
+      clientFactory: () => ({ responses: () => events({ type: "completed", responseId: "r" }) }),
+      fetch: async () =>
+        new Response(
+          JSON.stringify({ rate_limits: { primary_window: { used_percent: 90 } } }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        ),
+    });
+    await d.onTokenAdded(1, "one", credentials, null);
+    await d.onTokenAdded(2, "two", { ...credentials, accountId: "acct2" }, 80);
+
+    const error = await d
+      .generate(request({ preferredTokenId: 2, requirePreferredToken: true }))
+      .catch((caught) => caught);
+
+    expect(error).toBeInstanceOf(QuotaThresholdExceededError);
+    expect(error.message).toContain("two (threshold 80%)");
+  });
+
   it("runs concurrent requests without queueing and tracks in-flight counts", async () => {
     const releases: Array<() => void> = [];
     const d = dispatcher(() => ({

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

@@ -272,7 +272,11 @@ export class OpenAIDispatcher implements ProviderDispatcher {
   ): Promise<GenerateResult> {
     const signal = activeSignal(req.abortSignal, req.timeoutMs);
     if (signal.aborted) throw abortError(signal);
-    const selection = await this.selectToken(req.preferredTokenId, signal);
+    const selection = await this.selectToken(
+      req.preferredTokenId,
+      req.requirePreferredToken ?? false,
+      signal,
+    );
     this.inFlightCount++;
     try {
       if (signal.aborted) throw abortError(signal);
@@ -420,6 +424,7 @@ export class OpenAIDispatcher implements ProviderDispatcher {
    */
   private async selectToken(
     preferredTokenId: number | undefined,
+    requirePreferredToken: boolean,
     signal: AbortSignal,
   ): Promise<TokenSelection> {
     if (preferredTokenId !== undefined) {
@@ -427,6 +432,17 @@ export class OpenAIDispatcher implements ProviderDispatcher {
       if (preferred?.active && (await this.isQuotaEligible(preferredTokenId, preferred, signal))) {
         return { tokenId: preferredTokenId, metadata: preferred };
       }
+      if (requirePreferredToken) {
+        if (!preferred?.active) {
+          throw new Error(`Preferred openai token ${preferredTokenId} is not available`);
+        }
+        const threshold = preferred.quotaThreshold;
+        if (threshold !== null && threshold !== undefined) {
+          throw new QuotaThresholdExceededError(
+            quotaMessage([{ name: preferred.name, threshold }]),
+          );
+        }
+      }
     }
 
     // 토큰별 quota 판정은 서로 독립이라 병렬로 — 직렬 대기는 콜드 캐시에서

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),
   };
 }