@cartanova/qgrid-cli 2.7.4 → 2.7.6

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

@@ -329,6 +329,7 @@ Content-Type: application/json
     "serviceTier": "fast",
     "history": "HISTORY",
     "projectName": "PROJECTNAME",
+    "tokenName": "TOKENNAME",
     "cacheAffinityKey": "CACHEAFFINITYKEY",
     "logger": false,
     "runContext": {
@@ -390,6 +391,7 @@ Content-Type: application/json
     "serviceTier": "fast",
     "history": "HISTORY",
     "projectName": "PROJECTNAME",
+    "tokenName": "TOKENNAME",
     "cacheAffinityKey": "CACHEAFFINITYKEY",
     "logger": false,
     "runContext": {

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

@@ -28,7 +28,14 @@
       "dbDefault": "1"
     }
   ],
-  "indexes": [],
+  "indexes": [
+    {
+      "type": "unique",
+      "name": "tokens_provider_name_unique",
+      "columns": [{ "name": "provider" }, { "name": "name" }],
+      "using": "btree"
+    }
+  ],
   "subsets": {
     "A": [
       "id",

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

@@ -111,6 +111,43 @@ describe("TokenModel.updateFields", () => {
   });
 });
 
+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

@@ -146,6 +146,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];
+  }
+
   /**
    * 라우팅에서 빠진 토큰들. 세션 만료로 자동 비활성화된 것과 수동으로 끈 것이 섞여 있다 —
    * 둘 다 "재로그인하면 살아나는" 상태라 알림 대상으로는 같게 본다.

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/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 판정은 서로 독립이라 병렬로 — 직렬 대기는 콜드 캐시에서