@cartanova/qgrid-cli 2.3.4 → 2.3.6

package/bundle/dist/utils/providers/openai/openai-quota.js

@@ -0,0 +1,30 @@
+import "../../../_virtual/_rolldown/runtime.js";
+//#region src/utils/providers/openai/openai-quota.ts
+async function readOpenAIQuotaUsage(readRateLimits) {
+	try {
+		const { data, cachedAt } = await readRateLimits();
+		const rateLimits = data.rateLimits;
+		const primary = rateLimits?.primary;
+		if (!primary || typeof primary.usedPercent !== "number" || !Number.isFinite(primary.usedPercent)) return {
+			kind: "lookup_failed",
+			reason: "primary usedPercent unavailable"
+		};
+		return {
+			kind: "ok",
+			utilizationPct: primary.usedPercent,
+			cacheAgeMs: Math.max(Date.now() - cachedAt, 0),
+			windowDurationMins: primary.windowDurationMins,
+			resetsAt: primary.resetsAt,
+			limitId: rateLimits.limitId
+		};
+	} catch (e) {
+		return {
+			kind: "lookup_failed",
+			reason: e.message
+		};
+	}
+}
+//#endregion
+export { readOpenAIQuotaUsage };
+
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib3BlbmFpLXF1b3RhLmpzIiwibmFtZXMiOltdLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy91dGlscy9wcm92aWRlcnMvb3BlbmFpL29wZW5haS1xdW90YS50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyB0eXBlIEdldEFjY291bnRSYXRlTGltaXRzUmVzcG9uc2UgfSBmcm9tIFwiLi4vLi4vLi4vY29kZXgtcHJvdG9jb2wvdjIvR2V0QWNjb3VudFJhdGVMaW1pdHNSZXNwb25zZVwiO1xuXG5leHBvcnQgdHlwZSBPcGVuQUlSYXRlTGltaXRzV2l0aE1ldGEgPSB7XG4gIGRhdGE6IEdldEFjY291bnRSYXRlTGltaXRzUmVzcG9uc2U7XG4gIGNhY2hlZEF0OiBudW1iZXI7XG59O1xuXG5leHBvcnQgdHlwZSBPcGVuQUlRdW90YVVzYWdlUmVzdWx0ID1cbiAgfCB7XG4gICAgICBraW5kOiBcIm9rXCI7XG4gICAgICB1dGlsaXphdGlvblBjdDogbnVtYmVyO1xuICAgICAgY2FjaGVBZ2VNczogbnVtYmVyO1xuICAgICAgd2luZG93RHVyYXRpb25NaW5zOiBudW1iZXIgfCBudWxsO1xuICAgICAgcmVzZXRzQXQ6IG51bWJlciB8IG51bGw7XG4gICAgICBsaW1pdElkOiBzdHJpbmcgfCBudWxsO1xuICAgIH1cbiAgfCB7IGtpbmQ6IFwibG9va3VwX2ZhaWxlZFwiOyByZWFzb246IHN0cmluZyB9O1xuXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gcmVhZE9wZW5BSVF1b3RhVXNhZ2UoXG4gIHJlYWRSYXRlTGltaXRzOiAoKSA9PiBQcm9taXNlPE9wZW5BSVJhdGVMaW1pdHNXaXRoTWV0YT4sXG4pOiBQcm9taXNlPE9wZW5BSVF1b3RhVXNhZ2VSZXN1bHQ+IHtcbiAgdHJ5IHtcbiAgICBjb25zdCB7IGRhdGEsIGNhY2hlZEF0IH0gPSBhd2FpdCByZWFkUmF0ZUxpbWl0cygpO1xuICAgIGNvbnN0IHJhdGVMaW1pdHMgPSBkYXRhLnJhdGVMaW1pdHM7XG4gICAgY29uc3QgcHJpbWFyeSA9IHJhdGVMaW1pdHM/LnByaW1hcnk7XG5cbiAgICBpZiAoXG4gICAgICAhcHJpbWFyeSB8fFxuICAgICAgdHlwZW9mIHByaW1hcnkudXNlZFBlcmNlbnQgIT09IFwibnVtYmVyXCIgfHxcbiAgICAgICFOdW1iZXIuaXNGaW5pdGUocHJpbWFyeS51c2VkUGVyY2VudClcbiAgICApIHtcbiAgICAgIHJldHVybiB7IGtpbmQ6IFwibG9va3VwX2ZhaWxlZFwiLCByZWFzb246IFwicHJpbWFyeSB1c2VkUGVyY2VudCB1bmF2YWlsYWJsZVwiIH07XG4gICAgfVxuXG4gICAgcmV0dXJuIHtcbiAgICAgIGtpbmQ6IFwib2tcIixcbiAgICAgIHV0aWxpemF0aW9uUGN0OiBwcmltYXJ5LnVzZWRQZXJjZW50LFxuICAgICAgY2FjaGVBZ2VNczogTWF0aC5tYXgoRGF0ZS5ub3coKSAtIGNhY2hlZEF0LCAwKSxcbiAgICAgIHdpbmRvd0R1cmF0aW9uTWluczogcHJpbWFyeS53aW5kb3dEdXJhdGlvbk1pbnMsXG4gICAgICByZXNldHNBdDogcHJpbWFyeS5yZXNldHNBdCxcbiAgICAgIGxpbWl0SWQ6IHJhdGVMaW1pdHMubGltaXRJZCxcbiAgICB9O1xuICB9IGNhdGNoIChlKSB7XG4gICAgcmV0dXJuIHsga2luZDogXCJsb29rdXBfZmFpbGVkXCIsIHJlYXNvbjogKGUgYXMgRXJyb3IpLm1lc3NhZ2UgfTtcbiAgfVxufVxuIl0sIm1hcHBpbmdzIjoiOztBQWtCQSxlQUFzQixxQkFDcEIsZ0JBQ2lDO0FBQ2pDLEtBQUk7RUFDRixNQUFNLEVBQUUsTUFBTSxhQUFhLE1BQU0sZ0JBQWdCO0VBQ2pELE1BQU0sYUFBYSxLQUFLO0VBQ3hCLE1BQU0sVUFBVSxZQUFZO0FBRTVCLE1BQ0UsQ0FBQyxXQUNELE9BQU8sUUFBUSxnQkFBZ0IsWUFDL0IsQ0FBQyxPQUFPLFNBQVMsUUFBUSxZQUFZLENBRXJDLFFBQU87R0FBRSxNQUFNO0dBQWlCLFFBQVE7R0FBbUM7QUFHN0UsU0FBTztHQUNMLE1BQU07R0FDTixnQkFBZ0IsUUFBUTtHQUN4QixZQUFZLEtBQUssSUFBSSxLQUFLLEtBQUssR0FBRyxVQUFVLEVBQUU7R0FDOUMsb0JBQW9CLFFBQVE7R0FDNUIsVUFBVSxRQUFRO0dBQ2xCLFNBQVMsV0FBVztHQUNyQjtVQUNNLEdBQUc7QUFDVixTQUFPO0dBQUUsTUFBTTtHQUFpQixRQUFTLEVBQVk7R0FBUyJ9

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

@@ -10,6 +10,10 @@ export type AnthropicUsageRaw = {
   five_hour?: { utilization: number | null; resets_at: string | null } | null;
   seven_day?: { utilization: number | null; resets_at: string | null } | null;
 };
+export type AnthropicUsageWithMeta = {
+  data: AnthropicUsageRaw;
+  cachedAt: number;
+};
 
 const logger = getLogger(["qgrid", "oauth"]);
 
@@ -140,14 +144,18 @@ export async function refreshAccessToken(refreshToken: string): Promise<OAuthTok
   };
 }
 
-const usageCache: Record<string, { data: AnthropicUsageRaw; cachedAt: number }> = {};
+const usageCache: Record<string, AnthropicUsageWithMeta> = {};
 const USAGE_API_CACHE_TTL = 60_000; // 1분
 
 export async function fetchUsage(accessToken: string): Promise<AnthropicUsageRaw> {
+  return (await fetchUsageWithMeta(accessToken)).data;
+}
+
+export async function fetchUsageWithMeta(accessToken: string): Promise<AnthropicUsageWithMeta> {
   const cacheKey = accessToken.slice(-10);
   const cached = usageCache[cacheKey];
   if (cached && Date.now() - cached.cachedAt < USAGE_API_CACHE_TTL) {
-    return cached.data;
+    return cached;
   }
 
   const res = await fetch("https://api.anthropic.com/api/oauth/usage", {
@@ -173,16 +181,18 @@ export async function fetchUsage(accessToken: string): Promise<AnthropicUsageRaw
     logger.warn(`${res.status}: ${errorMessage}`);
 
     // 이전 성공 캐시 있으면 유지
-    if (cached?.data && !cached.data.error) return cached.data;
+    if (cached?.data && !cached.data.error) return cached;
 
     // 실패도 캐시 (반복 호출 방지)
     const errorResult = { error: errorMessage };
-    usageCache[cacheKey] = { data: errorResult, cachedAt: Date.now() };
-    return errorResult;
+    const entry = { data: errorResult, cachedAt: Date.now() };
+    usageCache[cacheKey] = entry;
+    return entry;
   }
 
   const data = (await res.json()) as AnthropicUsageRaw;
   // cache invalidate
-  usageCache[cacheKey] = { data, cachedAt: Date.now() };
-  return data;
+  const entry = { data, cachedAt: Date.now() };
+  usageCache[cacheKey] = entry;
+  return entry;
 }

package/bundle/src/application/qgrid/qgrid-run-lifecycle.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { afterQuery } from "./qgrid-run-lifecycle";
+import { type QueryOutput } from "./qgrid.types";
+
+const { appendStepMock, aggregateStepUsageMock, finishRunMock } = vi.hoisted(() => ({
+  appendStepMock: vi.fn(),
+  aggregateStepUsageMock: vi.fn(),
+  finishRunMock: vi.fn(),
+}));
+
+vi.mock("../request-log/request-log.model", () => ({
+  RequestLogModel: {
+    appendStep: appendStepMock,
+    aggregateStepUsage: aggregateStepUsageMock,
+    finishRun: finishRunMock,
+  },
+}));
+
+function queryOutput(overrides: Partial<QueryOutput> = {}): QueryOutput {
+  return {
+    text: "hello",
+    content: [],
+    finishReason: "stop",
+    tokenName: "tok-A",
+    model: "gpt-5-codex",
+    usage: {
+      input_tokens: 5,
+      output_tokens: 7,
+      cache_creation_input_tokens: 0,
+      cache_read_input_tokens: 0,
+    },
+    durationMs: 120,
+    ttftMs: 39,
+    costUsd: 0.001,
+    ...overrides,
+  };
+}
+
+describe("qgrid run lifecycle TTFT", () => {
+  beforeEach(() => {
+    appendStepMock.mockReset();
+    aggregateStepUsageMock.mockReset();
+    aggregateStepUsageMock.mockResolvedValue({
+      input_tokens: 5,
+      output_tokens: 7,
+      cache_read_tokens: 0,
+      cache_creation_tokens: 0,
+      duration_ms: 120,
+    });
+    finishRunMock.mockReset();
+  });
+
+  it("appends generate step ttft_ms from QueryOutput", async () => {
+    await afterQuery(10, 2, { prompt: "hi" }, queryOutput({ ttftMs: 44 }));
+
+    expect(appendStepMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        step_index: 2,
+        type: "generate",
+        duration_ms: 120,
+        ttft_ms: 44,
+      }),
+    );
+  });
+
+  it("preserves generate step ttft_ms zero when no first-token timing is available", async () => {
+    await afterQuery(
+      10,
+      2,
+      { prompt: "hi" },
+      queryOutput({ finishReason: "tool-calls", ttftMs: 0 }),
+    );
+
+    expect(appendStepMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        ttft_ms: 0,
+      }),
+    );
+    expect(finishRunMock).not.toHaveBeenCalled();
+  });
+
+  it("does not pass ttft into finishRun params because the model derives the run value", async () => {
+    await afterQuery(10, 2, { prompt: "hi" }, queryOutput({ ttftMs: 44 }));
+
+    expect(finishRunMock).toHaveBeenCalledWith(
+      10,
+      expect.not.objectContaining({
+        ttft_ms: expect.anything(),
+        ttftMs: expect.anything(),
+      }),
+    );
+  });
+});

package/bundle/src/application/qgrid/qgrid-run-lifecycle.ts

@@ -85,6 +85,7 @@ export async function afterQuery(
     cache_read_tokens: result.usage.cache_read_input_tokens,
     cache_creation_tokens: result.usage.cache_creation_input_tokens,
     duration_ms: result.durationMs,
+    ttft_ms: result.ttftMs,
     finish_reason: result.finishReason,
   });
 

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

@@ -335,4 +335,20 @@ describe("QgridDispatcherClass", () => {
     expect(result.costUsd).toBe(0.123456);
     expect(result.usage.cache_creation_input_tokens).toBe(600);
   });
+
+  it("provider ttftMs 를 QueryOutput.ttftMs 로 매핑하고 누락 값은 0 으로 둔다", async () => {
+    const dispatcher = new QgridDispatcherClass();
+    const generate = vi
+      .fn()
+      .mockResolvedValueOnce(providerResult({ ttftMs: 37 }))
+      .mockResolvedValueOnce(providerResult());
+    dispatcher.openaiDispatcher = { generate } as never;
+
+    await expect(
+      dispatcher.query({ prompt: "hi", model: "openai/gpt-5.5" }),
+    ).resolves.toMatchObject({ ttftMs: 37 });
+    await expect(
+      dispatcher.query({ prompt: "hi", model: "openai/gpt-5.5" }),
+    ).resolves.toMatchObject({ ttftMs: 0 });
+  });
 });

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

@@ -256,6 +256,7 @@ function toEmulationResult(
       cache_read_input_tokens: result.usage.cachedInputTokens,
     },
     durationMs: result.durationMs,
+    ttftMs: result.ttftMs ?? 0,
     costUsd:
       result.costUsd !== undefined && result.costUsd > 0
         ? result.costUsd

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

@@ -0,0 +1,128 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { QgridFrame } from "./qgrid.frame";
+
+const { findOneMock, saveMock, requestLogSaveMock, dispatcherQueryMock } = vi.hoisted(() => ({
+  findOneMock: vi.fn(),
+  saveMock: vi.fn(),
+  requestLogSaveMock: vi.fn(),
+  dispatcherQueryMock: vi.fn(),
+}));
+
+vi.mock("../request-log/request-log.model", () => ({
+  MICRO_USD: 1_000_000,
+  RequestLogModel: {
+    save: requestLogSaveMock,
+  },
+}));
+
+vi.mock("../token/token.model", () => ({
+  TokenModel: {
+    findOne: findOneMock,
+    save: saveMock,
+  },
+}));
+
+vi.mock("./qgrid.dispatcher", () => ({
+  QgridDispatcher: {
+    query: dispatcherQueryMock,
+  },
+}));
+
+const tokenEntry = {
+  id: 1,
+  created_at: new Date("2026-06-30T00:00:00.000Z"),
+  provider: "anthropic",
+  credentials: {
+    accessToken: "sk-ant-oat01-test",
+    refreshToken: "sk-ant-ort01-test",
+    expiresAt: Date.now() + 3_600_000,
+    accountUuid: "acc-1",
+  },
+  name: "tok-A",
+  active: true,
+  ord: 0,
+  quota_threshold: null,
+};
+
+describe("QgridFrame.updateToken", () => {
+  beforeEach(() => {
+    findOneMock.mockReset();
+    saveMock.mockReset();
+    saveMock.mockResolvedValue([1]);
+    requestLogSaveMock.mockReset();
+    requestLogSaveMock.mockResolvedValue([1]);
+    dispatcherQueryMock.mockReset();
+  });
+
+  it("rejects quota thresholds outside TokenSaveParams bounds before saving", async () => {
+    findOneMock.mockResolvedValueOnce(tokenEntry);
+
+    await expect(QgridFrame.updateToken(1, "tok-A", 0)).rejects.toThrow(
+      "quotaThreshold must be an integer between 1 and 100, or null",
+    );
+
+    expect(saveMock).not.toHaveBeenCalled();
+  });
+
+  it("saves valid quota thresholds through the same schema used by token saves", async () => {
+    findOneMock.mockResolvedValueOnce(tokenEntry);
+
+    await expect(QgridFrame.updateToken(1, "tok-A", 80)).resolves.toEqual({ updated: true });
+
+    expect(saveMock).toHaveBeenCalledWith([
+      expect.objectContaining({
+        id: 1,
+        name: "tok-A",
+        quota_threshold: 80,
+      }),
+    ]);
+  });
+});
+
+describe("QgridFrame.query auto logging", () => {
+  beforeEach(() => {
+    requestLogSaveMock.mockReset();
+    requestLogSaveMock.mockResolvedValue([1]);
+    dispatcherQueryMock.mockReset();
+  });
+
+  function queryOutput(ttftMs: number) {
+    return {
+      text: "hello",
+      content: [{ type: "text", text: "hello" }],
+      finishReason: "stop",
+      tokenName: "tok-A",
+      model: "gpt-5-codex",
+      usage: {
+        input_tokens: 5,
+        output_tokens: 7,
+        cache_creation_input_tokens: 0,
+        cache_read_input_tokens: 0,
+      },
+      durationMs: 120,
+      ttftMs,
+      costUsd: 0.001,
+    };
+  }
+
+  it("persists auto request ttft_ms from QueryOutput", async () => {
+    dispatcherQueryMock.mockResolvedValueOnce(queryOutput(39));
+
+    await QgridFrame.query({ prompt: "hi", model: "openai/gpt-5-codex", logMode: "auto" });
+
+    expect(requestLogSaveMock).toHaveBeenCalledWith([
+      expect.objectContaining({ duration_ms: 120, ttft_ms: 39 }),
+    ]);
+  });
+
+  it("persists auto request ttft_ms zero when no first-token timing is available", async () => {
+    dispatcherQueryMock.mockResolvedValueOnce(queryOutput(0));
+
+    await QgridFrame.query({ prompt: "hi", model: "openai/gpt-5-codex", logMode: "auto" });
+
+    expect(requestLogSaveMock).toHaveBeenCalledWith([
+      expect.objectContaining({ ttft_ms: 0 }),
+    ]);
+  });
+});

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

@@ -2,9 +2,10 @@ import crypto from "node:crypto";
 
 import { getLogger } from "@logtape/logtape";
 import { type FastifyReply } from "fastify";
-import { api, BaseFrameClass, Sonamu, stream } from "sonamu";
+import { api, BadRequestException, BaseFrameClass, Sonamu, stream } from "sonamu";
 import { getCacheManagerRef } from "sonamu/cache";
 
+import { type LocalizedString } from "../../i18n/sd.generated";
 import {
   getAccessToken,
   getExpiresAt,
@@ -13,7 +14,11 @@ import {
 import { MICRO_USD, RequestLogModel } from "../request-log/request-log.model";
 import { type TokenSubsetA } from "../sonamu.generated";
 import { TokenModel } from "../token/token.model";
-import { TokenCredentials } from "../token/token.types";
+import {
+  TokenCredentials,
+  TokenSaveParams,
+  type TokenSaveParams as TokenSaveParamsType,
+} from "../token/token.types";
 import {
   type AnthropicUsageRaw,
   buildAuthUrl,
@@ -49,6 +54,10 @@ type PendingOAuth = { codeVerifier: string; name: string; redirectUri: string };
 const OAUTH_STATE_PREFIX = "oauth:state:";
 const OAUTH_STATE_TTL = "5m";
 
+function unixSecondsToIso(seconds: number | null | undefined): string | null {
+  return typeof seconds === "number" ? new Date(seconds * 1000).toISOString() : null;
+}
+
 async function setOAuthState(state: string, data: PendingOAuth): Promise<void> {
   const cache = getCacheManagerRef();
   if (!cache) throw new Error("CacheManager not initialized");
@@ -142,6 +151,7 @@ class QgridFrameClass extends BaseFrameClass {
         cache_read_tokens: result.usage.cache_read_input_tokens,
         cache_creation_tokens: result.usage.cache_creation_input_tokens,
         duration_ms: result.durationMs,
+        ttft_ms: result.ttftMs,
         cost_usd: result.costUsd !== null ? Math.round(result.costUsd * MICRO_USD) : null,
         effort: args.effort ?? null,
         // malformed history가 와도 성공한 턴(특히 stream sse.end())을 깨지 않도록 방어.
@@ -296,6 +306,7 @@ class QgridFrameClass extends BaseFrameClass {
       cache_read_tokens: input.cacheReadTokens,
       cache_creation_tokens: input.cacheCreationTokens,
       duration_ms: input.durationMs,
+      ttft_ms: input.ttftMs ?? null,
       finish_reason: input.finishReason,
       reasoning_text: input.reasoningText,
       reasoning_tokens: input.reasoningTokens,
@@ -359,18 +370,33 @@ class QgridFrameClass extends BaseFrameClass {
   }
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
-  async updateToken(id: number, name?: string): Promise<{ updated: boolean }> {
+  async updateToken(
+    id: number,
+    name?: string,
+    quotaThreshold?: number | null,
+  ): Promise<{ updated: boolean }> {
     const entry = await TokenModel.findOne("A", { id });
     if (!entry) return { updated: false };
 
-    await TokenModel.save([
-      {
-        id: entry.id,
-        provider: entry.provider,
-        credentials: entry.credentials,
-        name: name !== undefined ? name : entry.name,
-      },
-    ]);
+    const patch: TokenSaveParamsType = {
+      id: entry.id,
+      provider: entry.provider,
+      credentials: entry.credentials,
+      name: name !== undefined ? name : entry.name,
+    };
+    if (quotaThreshold !== undefined) {
+      patch.quota_threshold = quotaThreshold;
+    }
+
+    const parsed = TokenSaveParams.safeParse(patch);
+    if (!parsed.success) {
+      throw new BadRequestException(
+        "quotaThreshold must be an integer between 1 and 100, or null" as LocalizedString,
+        { zodError: parsed.error },
+      );
+    }
+
+    await TokenModel.save([parsed.data]);
     return { updated: true };
   }
 
@@ -513,25 +539,20 @@ class QgridFrameClass extends BaseFrameClass {
 
     if (entry.provider === "openai") {
       try {
-        const raw = (await QgridDispatcher.openaiDispatcher?.getRateLimits(entry.name)) as {
-          rateLimits?: {
-            primary?: { usedPercent: number; windowDurationMins: number; resetsAt: number };
-            secondary?: { usedPercent: number; windowDurationMins: number; resetsAt: number };
-          };
-        };
-        const rl = raw?.rateLimits;
+        const raw = await QgridDispatcher.openaiDispatcher?.getRateLimitsByTokenId(entry.id);
+        const rl = raw?.data.rateLimits;
         return {
           provider: "openai",
           fiveHour: rl?.primary
             ? {
                 utilization: rl.primary.usedPercent,
-                resetsAt: new Date(rl.primary.resetsAt * 1000).toISOString(),
+                resetsAt: unixSecondsToIso(rl.primary.resetsAt),
               }
             : null,
           sevenDay: rl?.secondary
             ? {
                 utilization: rl.secondary.usedPercent,
-                resetsAt: new Date(rl.secondary.resetsAt * 1000).toISOString(),
+                resetsAt: unixSecondsToIso(rl.secondary.resetsAt),
               }
             : null,
         };

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

@@ -102,6 +102,7 @@ export const QueryOutput = z.object({
     cache_read_input_tokens: z.number(),
   }),
   durationMs: z.number(),
+  ttftMs: z.number(),
   costUsd: z.number(),
   runContext: QgridRunContext.optional(),
 });
@@ -128,6 +129,7 @@ export const StreamEvents = z.object({
       cache_read_input_tokens: z.number(),
     }),
     durationMs: z.number(),
+    ttftMs: z.number(),
     costUsd: z.number(),
     content: z.array(QgridContent),
     runContext: QgridRunContext.optional(),
@@ -157,6 +159,7 @@ export const AppendStepInput = z.object({
   cacheReadTokens: z.number().optional(),
   cacheCreationTokens: z.number().optional(),
   durationMs: z.number().optional(),
+  ttftMs: z.number().nullable().optional(),
   finishReason: z.string().optional(),
   reasoningText: z.string().optional(),
   reasoningTokens: z.number().optional(),
@@ -250,6 +253,9 @@ export type HealthResponse = z.infer<typeof HealthResponse>;
 export class QuotaError extends Error {
   readonly code = "QUOTA_EXHAUSTED" as const;
 }
+export class QuotaThresholdExceededError extends Error {
+  readonly code = "QUOTA_THRESHOLD_EXCEEDED" as const;
+}
 export class TimeoutError extends Error {
   readonly code = "TIMEOUT" as const;
 }

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

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { TokenSubscriber } from "./token-subscriber";
+
+const { findOneMock, findActiveMock } = vi.hoisted(() => ({
+  findOneMock: vi.fn(),
+  findActiveMock: vi.fn(),
+}));
+
+vi.mock("../token/token.model", () => ({
+  TokenModel: {
+    findOne: findOneMock,
+    findActive: findActiveMock,
+  },
+}));
+
+function openaiToken(active = true) {
+  return {
+    id: 1,
+    provider: "openai",
+    active,
+    name: "tok-A",
+    credentials: { accessToken: "access", accountId: "account" },
+    quota_threshold: 80,
+  };
+}
+
+function subscriberWith(openaiDispatcher: Record<string, unknown>) {
+  return new TokenSubscriber(
+    {} as never,
+    {
+      removeCache: vi.fn(),
+      upsertCache: vi.fn(),
+      replaceCache: vi.fn(),
+      openaiDispatcher,
+      anthropicDispatcher: null,
+    } as never,
+  );
+}
+
+async function flushPromises(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe("TokenSubscriber OpenAI notifications", () => {
+  beforeEach(() => {
+    findOneMock.mockReset();
+    findActiveMock.mockReset();
+  });
+
+  it("updates OpenAI token metadata before activating workers", async () => {
+    const calls: string[] = [];
+    const openaiDispatcher = {
+      onTokenUpdated: vi.fn(async () => {
+        calls.push("updated");
+      }),
+      onTokenActivated: vi.fn(() => {
+        calls.push("activated");
+      }),
+    };
+    const subscriber = subscriberWith(openaiDispatcher);
+    findOneMock.mockResolvedValueOnce(openaiToken(true));
+
+    await subscriber.handleNotification(JSON.stringify({ op: "UPDATE", id: 1 }));
+    await flushPromises();
+
+    expect(calls).toEqual(["updated", "activated"]);
+    expect(openaiDispatcher.onTokenUpdated).toHaveBeenCalledWith(
+      1,
+      "tok-A",
+      { accessToken: "access", accountId: "account" },
+      80,
+    );
+  });
+
+  it("does not spawn workers for inactive OpenAI inserts", async () => {
+    const openaiDispatcher = {
+      onTokenAdded: vi.fn(async () => {}),
+      onTokenDeactivated: vi.fn(),
+    };
+    const subscriber = subscriberWith(openaiDispatcher);
+    findOneMock.mockResolvedValueOnce(openaiToken(false));
+
+    await subscriber.handleNotification(JSON.stringify({ op: "INSERT", id: 1 }));
+
+    expect(openaiDispatcher.onTokenAdded).not.toHaveBeenCalled();
+    expect(openaiDispatcher.onTokenDeactivated).toHaveBeenCalledWith(1);
+  });
+});

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

@@ -177,17 +177,20 @@ export class TokenSubscriber {
 
     if (row.provider === "openai") {
       const creds = row.credentials as Record<string, unknown>;
-      if (payload.op === "INSERT") {
-        this.dispatcher.openaiDispatcher
-          ?.onTokenAdded(payload.id, row.name, creds as OpenAICredentials)
+      const openaiDispatcher = this.dispatcher.openaiDispatcher;
+      if (payload.op === "INSERT" && row.active) {
+        openaiDispatcher
+          ?.onTokenAdded(payload.id, row.name, creds as OpenAICredentials, row.quota_threshold)
           .catch((e) => logger.warn(`openai worker spawn failed: ${(e as Error).message}`));
       } else if (row.active) {
-        this.dispatcher.openaiDispatcher?.onTokenActivated(payload.id);
-        this.dispatcher.openaiDispatcher
-          ?.onTokenUpdated(payload.id, row.name, creds as OpenAICredentials)
-          .catch((e) => logger.warn(`openai worker update failed: ${(e as Error).message}`));
+        if (openaiDispatcher) {
+          openaiDispatcher
+            .onTokenUpdated(payload.id, row.name, creds as OpenAICredentials, row.quota_threshold)
+            .then(() => openaiDispatcher.onTokenActivated(payload.id))
+            .catch((e) => logger.warn(`openai worker update failed: ${(e as Error).message}`));
+        }
       } else {
-        this.dispatcher.openaiDispatcher?.onTokenDeactivated(payload.id);
+        openaiDispatcher?.onTokenDeactivated(payload.id);
       }
     } else if (row.provider === "anthropic") {
       // anthropic 토큰 이벤트는 동기(void). worker 가 없고 풀(Map)만 관리하므로 단순:
@@ -195,9 +198,19 @@ export class TokenSubscriber {
       //  (별도 activate/deactivate 콜백이 없어 active 토글을 add/remove 로 매핑.)
       const creds = row.credentials as AnthropicCredentials;
       if (payload.op === "INSERT" && row.active) {
-        this.dispatcher.anthropicDispatcher?.onTokenAdded(payload.id, row.name, creds);
+        this.dispatcher.anthropicDispatcher?.onTokenAdded(
+          payload.id,
+          row.name,
+          creds,
+          row.quota_threshold,
+        );
       } else if (row.active) {
-        this.dispatcher.anthropicDispatcher?.onTokenUpdated(payload.id, row.name, creds);
+        this.dispatcher.anthropicDispatcher?.onTokenUpdated(
+          payload.id,
+          row.name,
+          creds,
+          row.quota_threshold,
+        );
       } else {
         // inactive 면 INSERT 든 UPDATE 든 풀에 넣지 않는다.
         this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
@@ -213,8 +226,24 @@ export class TokenSubscriber {
     // (rows 는 active 만 — inactive/삭제된 토큰은 여기 없으므로 replaceTokens 가 풀에서 제거한다.)
     const anthropicRows = rows
       .filter((r) => r.provider === "anthropic")
-      .map((r) => ({ id: r.id, name: r.name, credentials: r.credentials as AnthropicCredentials }));
+      .map((r) => ({
+        id: r.id,
+        name: r.name,
+        credentials: r.credentials as AnthropicCredentials,
+        quotaThreshold: r.quota_threshold,
+      }));
     this.dispatcher.anthropicDispatcher?.replaceTokens(anthropicRows);
+    const openaiRows = rows
+      .filter((r) => r.provider === "openai")
+      .map((r) => ({
+        id: r.id,
+        name: r.name,
+        credentials: r.credentials as OpenAICredentials,
+        quotaThreshold: r.quota_threshold,
+      }));
+    await this.dispatcher.openaiDispatcher
+      ?.replaceTokens(openaiRows)
+      .catch((e) => logger.warn(`openai reconcile failed: ${(e as Error).message}`));
     this.lastReconcileAt = new Date();
   }
 }