@cartanova/qgrid-cli 2.7.5 → 2.7.7

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

@@ -9,6 +9,7 @@ import { QueryInput } from "./qgrid.types";
 const {
   findOneMock,
   findManyMock,
+  findActiveByProviderAndNameMock,
   saveMock,
   updateFieldsMock,
   requestLogSaveMock,
@@ -30,6 +31,7 @@ const {
   return {
     findOneMock: vi.fn(),
     findManyMock: vi.fn(),
+    findActiveByProviderAndNameMock: vi.fn(),
     saveMock: vi.fn(),
     updateFieldsMock: vi.fn(),
     requestLogSaveMock: vi.fn(),
@@ -59,6 +61,7 @@ vi.mock("../token/token.model", () => ({
   TokenModel: {
     findOne: findOneMock,
     findMany: findManyMock,
+    findActiveByProviderAndName: findActiveByProviderAndNameMock,
     save: saveMock,
     updateFields: updateFieldsMock,
   },
@@ -108,6 +111,7 @@ const tokenEntry = {
   ord: 0,
   quota_threshold: null,
   weight: 1,
+  keepalive_enabled: false,
 };
 
 function deeplyNestedInputSchema(depth: number): unknown {
@@ -125,6 +129,7 @@ describe("QgridFrame.updateToken", () => {
     appendStepMock.mockReset();
     appendStepMock.mockResolvedValue(1);
     dispatcherQueryMock.mockReset();
+    findActiveByProviderAndNameMock.mockReset();
   });
 
   it("rejects quota thresholds outside bounds before updating", async () => {
@@ -160,6 +165,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);
 
@@ -180,6 +193,7 @@ describe("QgridFrame.query request logging", () => {
     assertNativeRunAdmissionMock.mockReset();
     finishRunWithErrorMock.mockReset();
     dispatcherQueryMock.mockReset();
+    findActiveByProviderAndNameMock.mockReset();
   });
 
   function queryOutput() {
@@ -234,6 +248,59 @@ describe("QgridFrame.query request logging", () => {
     expect(result.runContext).toEqual(queryOutput().runContext);
   });
 
+  it("tokenName 을 활성 토큰 id 로 해석해 지정 요청으로 전달한다", async () => {
+    findActiveByProviderAndNameMock.mockResolvedValueOnce({
+      ...tokenEntry,
+      id: 17,
+      name: "anthropic/tok-A",
+    });
+    dispatcherQueryMock.mockResolvedValueOnce(queryOutput());
+
+    await QgridFrame.query({
+      prompt: "hi",
+      model: "anthropic/claude-sonnet-4-6",
+      tokenName: "anthropic/tok-A",
+    });
+
+    expect(findActiveByProviderAndNameMock).toHaveBeenCalledWith(
+      "A",
+      "anthropic",
+      "anthropic/tok-A",
+    );
+    expect(dispatcherQueryMock).toHaveBeenCalledWith(
+      expect.objectContaining({ preferredTokenId: 17, requirePreferredToken: true }),
+      expect.any(AbortSignal),
+    );
+  });
+
+  it("tokenName 에 해당하는 활성 토큰이 없으면 대체 없이 실패한다", async () => {
+    findActiveByProviderAndNameMock.mockResolvedValueOnce(undefined);
+
+    await expect(
+      QgridFrame.query({
+        prompt: "hi",
+        model: "anthropic/claude-sonnet-4-6",
+        tokenName: "anthropic/missing",
+      }),
+    ).rejects.toThrow("Active token not found: anthropic/missing");
+
+    expect(dispatcherQueryMock).not.toHaveBeenCalled();
+    expect(beforeQueryMock).not.toHaveBeenCalled();
+  });
+
+  it("tokenName provider 와 model provider 가 다르면 조회 전에 실패한다", async () => {
+    await expect(
+      QgridFrame.query({
+        prompt: "hi",
+        model: "anthropic/claude-sonnet-4-6",
+        tokenName: "openai/tok-A",
+      }),
+    ).rejects.toThrow("Token provider does not match model provider");
+
+    expect(findActiveByProviderAndNameMock).not.toHaveBeenCalled();
+    expect(dispatcherQueryMock).not.toHaveBeenCalled();
+  });
+
   it("persists an immediate tools+schema structured answer as final JSON text", async () => {
     const output = {
       ...queryOutput(),

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

@@ -39,7 +39,11 @@ import {
   finishRunAborted,
   finishRunWithError,
 } from "./qgrid-run-lifecycle";
-import { buildAndValidateStrictOutputSchema, QgridDispatcher } from "./qgrid.dispatcher";
+import {
+  buildAndValidateStrictOutputSchema,
+  type InternalQueryInput,
+  QgridDispatcher,
+} from "./qgrid.dispatcher";
 import {
   type QueryInput,
   type AppendStepInput,
@@ -147,6 +151,27 @@ function rejectInvalidCallerSchemas(args: QueryInput): void {
   }
 }
 
+async function resolveTokenName(args: QueryInput): Promise<InternalQueryInput> {
+  if (!args.tokenName) return args;
+
+  const tokenProvider = args.tokenName.split("/", 1)[0];
+  const modelProvider = args.model?.split("/", 1)[0];
+  if (tokenProvider !== "anthropic" && tokenProvider !== "openai") {
+    throw new BadRequestException(`Invalid token name: ${args.tokenName}` as LocalizedString);
+  }
+  if (modelProvider !== tokenProvider) {
+    throw new BadRequestException(
+      "Token provider does not match model provider" as LocalizedString,
+    );
+  }
+
+  const token = await TokenModel.findActiveByProviderAndName("A", tokenProvider, args.tokenName);
+  if (!token) {
+    throw new BadRequestException(`Active token not found: ${args.tokenName}` as LocalizedString);
+  }
+  return { ...args, preferredTokenId: token.id, requirePreferredToken: true };
+}
+
 function createHttpDisconnectHandle(): {
   signal: AbortSignal;
   dispose: () => void;
@@ -199,29 +224,30 @@ class QgridFrameClass extends BaseFrameClass {
   async query(args: QueryInput): Promise<QueryOutput> {
     assertNativeRunAdmission();
     rejectInvalidCallerSchemas(args);
+    const resolvedArgs = await resolveTokenName(args);
     const disconnect = createHttpDisconnectHandle();
     try {
-      if (args.logger === false) {
-        return await QgridDispatcher.query(args, disconnect.signal);
+      if (resolvedArgs.logger === false) {
+        return await QgridDispatcher.query(resolvedArgs, disconnect.signal);
       }
 
-      const { requestLogId, stepIndex } = await beforeQuery(args);
+      const { requestLogId, stepIndex } = await beforeQuery(resolvedArgs);
       let result: QueryOutput;
       try {
-        result = await QgridDispatcher.query(args, disconnect.signal);
+        result = await QgridDispatcher.query(resolvedArgs, disconnect.signal);
       } catch (e) {
         if (disconnect.signal.aborted) {
-          await finishRunAborted(requestLogId, args);
+          await finishRunAborted(requestLogId, resolvedArgs);
         } else {
-          await finishRunWithError(requestLogId, (e as Error).message, args);
+          await finishRunWithError(requestLogId, (e as Error).message, resolvedArgs);
         }
         throw e;
       }
 
       try {
-        const lifecycle = await afterQuery(requestLogId, stepIndex, args, result);
+        const lifecycle = await afterQuery(requestLogId, stepIndex, resolvedArgs, result);
         if (disconnect.signal.aborted) {
-          await finishRunAborted(requestLogId, args);
+          await finishRunAborted(requestLogId, resolvedArgs);
         }
         // tool-call requestLogId와 provider threadCoord는 서로 독립적으로 유지한다.
         const threadCoord = result.runContext?.threadCoord;
@@ -233,9 +259,9 @@ class QgridFrameClass extends BaseFrameClass {
       } catch (e) {
         logger.error(`query afterQuery failed: ${(e as Error).message}`);
         if (disconnect.signal.aborted) {
-          await finishRunAborted(requestLogId, args);
+          await finishRunAborted(requestLogId, resolvedArgs);
         } else {
-          await finishRunWithError(requestLogId, (e as Error).message, args);
+          await finishRunWithError(requestLogId, (e as Error).message, resolvedArgs);
         }
         // provider 응답은 성공했으므로 로깅 장애가 생성 결과를 덮어쓰지 않는다.
         return result;
@@ -250,8 +276,9 @@ class QgridFrameClass extends BaseFrameClass {
     assertNativeRunAdmission();
     rejectImageGenerationStream(args);
     rejectInvalidCallerSchemas(args);
+    const resolvedArgs = await resolveTokenName(args);
     const streamId = crypto.randomUUID();
-    pendingStreams.set(streamId, args);
+    pendingStreams.set(streamId, resolvedArgs);
     const expiry = setTimeout(() => pendingStreams.delete(streamId), 30_000);
     expiry.unref?.();
     return { streamId };
@@ -478,6 +505,7 @@ class QgridFrameClass extends BaseFrameClass {
     name?: string,
     quotaThreshold?: number | null,
     weight?: number,
+    keepaliveEnabled?: boolean,
   ): Promise<{ updated: boolean }> {
     if (
       quotaThreshold !== undefined &&
@@ -498,6 +526,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);

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

@@ -114,6 +114,8 @@ export const QueryInput = z.looseObject({
   serviceTier: ServiceTier.optional(),
   history: z.string().optional(),
   projectName: z.string().optional(),
+  // 내부·대시보드 호출용 지정 주소. 공개 AI SDK provider options 에는 노출하지 않는다.
+  tokenName: z.string().optional(),
   // SDK-derived opaque affinity. It is intentionally distinct from the caller's sessionKey.
   cacheAffinityKey: z
     .string()

package/bundle/src/application/qgrid/token-subscriber.test.ts

@@ -104,6 +104,89 @@ describe("TokenSubscriber OpenAI notifications", () => {
     );
   });
 
+  it("Anthropic 토큰 변경 뒤 keepalive 대상 재예약을 알린다", async () => {
+    const anthropicDispatcher = { onTokenAdded: vi.fn() };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map(),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher,
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access", refreshToken: "refresh" },
+    });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "INSERT", id: 1 }));
+
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
+
+  it("Anthropic credentials 갱신은 keepalive 전체 재예약을 유발하지 않는다", async () => {
+    const previous = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "old", refreshToken: "refresh" },
+    };
+    const anthropicDispatcher = { onTokenUpdated: vi.fn() };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map([[previous.id, previous]]),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher,
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({
+      ...previous,
+      credentials: { accessToken: "new", refreshToken: "refresh" },
+    });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "UPDATE", id: previous.id }));
+
+    expect(anthropicDispatcher.onTokenUpdated).toHaveBeenCalledOnce();
+    expect(onTokensChanged).not.toHaveBeenCalled();
+  });
+
+  it("Anthropic active 전환은 keepalive 대상 재예약을 알린다", async () => {
+    const previous = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access", refreshToken: "refresh" },
+    };
+    const subscriber = new TokenSubscriber(
+      {} as never,
+      {
+        tokens: new Map([[previous.id, previous]]),
+        removeCache: vi.fn(),
+        upsertCache: vi.fn(),
+        replaceCache: vi.fn(),
+        openaiDispatcher: null,
+        anthropicDispatcher: { onTokenRemoved: vi.fn() },
+      } as never,
+    );
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findOneMock.mockResolvedValueOnce({ ...previous, active: false });
+
+    await subscriber.handleNotification(JSON.stringify({ op: "UPDATE", id: previous.id }));
+
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
+
   it("serializes token reloads so rapid weight updates cannot apply backward", async () => {
     let resolveFirst!: (value: ReturnType<typeof openaiToken>) => void;
     const firstRow = new Promise<ReturnType<typeof openaiToken>>((resolve) => {
@@ -188,4 +271,33 @@ describe("TokenSubscriber OpenAI notifications", () => {
       expect.objectContaining({ id: 2, quotaThreshold: 80, weight: 4 }),
     ]);
   });
+
+  it("reconcile 은 Anthropic 대상 집합이 바뀔 때만 keepalive 재예약을 알린다", async () => {
+    const currentAnthropic = {
+      ...openaiToken(true),
+      provider: "anthropic",
+      credentials: { accessToken: "access-a", refreshToken: "refresh-a" },
+    };
+    const dispatcher = {
+      tokens: new Map([[currentAnthropic.id, currentAnthropic]]),
+      replaceCache: vi.fn(),
+      openaiDispatcher: null,
+      anthropicDispatcher: { replaceTokens: vi.fn() },
+    };
+    const subscriber = new TokenSubscriber({} as never, dispatcher as never);
+    const onTokensChanged = vi.fn();
+    subscriber.setTokenChangeHandler(onTokensChanged);
+    findActiveMock
+      .mockResolvedValueOnce([currentAnthropic])
+      .mockResolvedValueOnce([
+        currentAnthropic,
+        { ...currentAnthropic, id: 3, name: "anthropic/tok-C" },
+      ]);
+
+    await subscriber.reconcile();
+    expect(onTokensChanged).not.toHaveBeenCalled();
+
+    await subscriber.reconcile();
+    expect(onTokensChanged).toHaveBeenCalledTimes(1);
+  });
 });

package/bundle/src/application/qgrid/token-subscriber.ts

@@ -26,12 +26,25 @@ export class TokenSubscriber {
   connectedAt: Date | null = null;
   lastReconcileAt: Date | null = null;
   private operationChain: Promise<void> = Promise.resolve();
+  private tokenChangeHandler: (() => void) | null = null;
 
   constructor(
     public connConfig: ClientConfig,
     public dispatcher: QgridDispatcherClass,
   ) {}
 
+  setTokenChangeHandler(handler: (() => void) | null): void {
+    this.tokenChangeHandler = handler;
+  }
+
+  private notifyTokensChanged(): void {
+    try {
+      this.tokenChangeHandler?.();
+    } catch (error) {
+      logger.warn(`token change handler failed: ${(error as Error).message}`);
+    }
+  }
+
   async start(): Promise<boolean> {
     this.shutdownRequested = false;
     this.ensureReconcileTimer();
@@ -157,6 +170,10 @@ export class TokenSubscriber {
 
   private async handleNotificationNow(payloadJson: string): Promise<void> {
     const payload = JSON.parse(payloadJson) as Payload;
+    const previousRow = this.tokenChangeHandler
+      ? this.dispatcher.tokens.get(payload.id)
+      : undefined;
+    const wasKeepaliveTarget = previousRow?.active === true && previousRow.provider === "anthropic";
     if (payload.op === "DELETE") {
       this.dispatcher.removeCache(payload.id);
       await this.dispatcher.openaiDispatcher
@@ -165,6 +182,7 @@ export class TokenSubscriber {
       // anthropic 토큰 이벤트는 동기(void) — provider 를 모르므로 무해하게 항상 제거 시도.
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → removed from cache`);
+      if (previousRow === undefined || wasKeepaliveTarget) this.notifyTokensChanged();
       return;
     }
     const row = await TokenModel.findOne("A", { id: payload.id });
@@ -175,6 +193,7 @@ export class TokenSubscriber {
         .catch((e) => logger.warn(`openai token remove failed: ${(e as Error).message}`));
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → missing, removed from cache`);
+      if (previousRow === undefined || wasKeepaliveTarget) this.notifyTokensChanged();
       return;
     }
 
@@ -236,6 +255,8 @@ export class TokenSubscriber {
       }
     }
     logger.info(`NOTIFY ${payload.op} id=${payload.id} (${row.name}) active=${row.active}`);
+    const isKeepaliveTarget = row.active && row.provider === "anthropic";
+    if (wasKeepaliveTarget !== isKeepaliveTarget) this.notifyTokensChanged();
   }
 
   async reconcile(): Promise<void> {
@@ -243,6 +264,13 @@ export class TokenSubscriber {
   }
 
   private async reconcileNow(): Promise<void> {
+    const previousAnthropicIds = this.tokenChangeHandler
+      ? new Set(
+          [...this.dispatcher.tokens.values()]
+            .filter((row) => row.active && row.provider === "anthropic")
+            .map((row) => row.id),
+        )
+      : null;
     const rows = await TokenModel.findActive("A");
     this.dispatcher.replaceCache(rows);
     // NOTIFY 유실 대비: AnthropicDispatcher 풀도 DB active anthropic 토큰 기준으로 재동기화.
@@ -270,6 +298,13 @@ export class TokenSubscriber {
       ?.replaceTokens(openaiRows)
       .catch((e) => logger.warn(`openai reconcile failed: ${(e as Error).message}`));
     this.lastReconcileAt = new Date();
+    if (
+      previousAnthropicIds &&
+      (previousAnthropicIds.size !== anthropicRows.length ||
+        anthropicRows.some((row) => !previousAnthropicIds.has(row.id)))
+    ) {
+      this.notifyTokensChanged();
+    }
   }
 
   private enqueueOperation(operation: () => Promise<void>): Promise<void> {

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();
 `;