@cartanova/qgrid-cli 2.3.5 → 2.3.7

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

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { readAnthropicQuotaUsage } from "./anthropic-quota";
+
+const { fetchUsageWithMetaMock } = vi.hoisted(() => ({
+  fetchUsageWithMetaMock: vi.fn(),
+}));
+
+vi.mock("../../../application/qgrid/oauth", () => ({
+  fetchUsageWithMeta: fetchUsageWithMetaMock,
+}));
+
+describe("readAnthropicQuotaUsage", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-30T12:00:05.000Z"));
+    fetchUsageWithMetaMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("uses API utilization as 0..100 percent", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 17, resets_at: null } },
+      cachedAt: Date.now() - 1_250,
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toEqual({
+      kind: "ok",
+      utilizationPct: 17,
+      cacheAgeMs: 1_250,
+    });
+  });
+
+  it("keeps low percent utilization unchanged", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 1, resets_at: null } },
+      cachedAt: Date.now() - 500,
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "ok",
+      utilizationPct: 1,
+      cacheAgeMs: 500,
+    });
+  });
+
+  it("treats utilization 0 as a successful lookup", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: 0, resets_at: null } },
+      cachedAt: Date.now(),
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "ok",
+      utilizationPct: 0,
+    });
+  });
+
+  it("converts API errors and rejected fetches into lookup_failed", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { error: "rate limit API unavailable" },
+      cachedAt: Date.now(),
+    });
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+      reason: "rate limit API unavailable",
+    });
+
+    fetchUsageWithMetaMock.mockRejectedValueOnce(new Error("timeout"));
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+      reason: "timeout",
+    });
+  });
+
+  it("treats missing five_hour utilization as lookup_failed", async () => {
+    fetchUsageWithMetaMock.mockResolvedValueOnce({
+      data: { five_hour: { utilization: null, resets_at: null } },
+      cachedAt: Date.now(),
+    });
+
+    await expect(readAnthropicQuotaUsage("access-token")).resolves.toMatchObject({
+      kind: "lookup_failed",
+    });
+  });
+});

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

@@ -0,0 +1,27 @@
+import { fetchUsageWithMeta } from "../../../application/qgrid/oauth";
+
+export type AnthropicQuotaUsageResult =
+  | { kind: "ok"; utilizationPct: number; cacheAgeMs: number }
+  | { kind: "lookup_failed"; reason: string };
+
+export async function readAnthropicQuotaUsage(
+  accessToken: string,
+): Promise<AnthropicQuotaUsageResult> {
+  try {
+    const { data, cachedAt } = await fetchUsageWithMeta(accessToken);
+    if (data.error) return { kind: "lookup_failed", reason: data.error };
+
+    const utilization = data.five_hour?.utilization;
+    if (typeof utilization !== "number" || !Number.isFinite(utilization)) {
+      return { kind: "lookup_failed", reason: "five_hour utilization unavailable" };
+    }
+
+    return {
+      kind: "ok",
+      utilizationPct: utilization,
+      cacheAgeMs: Math.max(Date.now() - cachedAt, 0),
+    };
+  } catch (e) {
+    return { kind: "lookup_failed", reason: (e as Error).message };
+  }
+}

package/bundle/src/utils/providers/anthropic/claude-session.ts

@@ -21,6 +21,7 @@ import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
 import { type TokenUsageBreakdown } from "../../../codex-protocol/v2/TokenUsageBreakdown";
 import { type UserInput } from "../../../codex-protocol/v2/UserInput";
+import { createTtftTracker } from "../common/ttft";
 import {
   ANTHROPIC_CLAUDE_CWD,
   anthropicConfigDir,
@@ -111,6 +112,7 @@ export interface ClaudeSessionRequest {
 export interface ClaudeSessionResult extends ClaudeStreamResult {
   sessionId: string;
   workerId: number;
+  ttftMs: number | null;
 }
 
 // per-token CLAUDE_CONFIG_DIR 보장(격리). 경로 규칙은 anthropicConfigDir(순수 함수)이 소유 —
@@ -305,6 +307,8 @@ export function runClaudeSession(
       let settled = false;
       let buffer = "";
       const streamState: ClaudeStreamJsonState = {};
+      const ttftTracker = createTtftTracker();
+      const onTrackedDelta = ttftTracker.wrapDelta(onDelta);
       // bounded stderr 버퍼(최근 ~4KB만 유지 — 무한 누적 방지).
       let stderrBuf = "";
       const STDERR_CAP = 4096;
@@ -339,7 +343,7 @@ export function runClaudeSession(
         clearTimeout(timer);
         cleanupAbort?.();
         cleanupSpawnFiles();
-        resolve({ ...result, sessionId, workerId });
+        resolve({ ...result, sessionId, workerId, ttftMs: ttftTracker.value() });
       };
 
       const onAbort = () => {
@@ -360,7 +364,7 @@ export function runClaudeSession(
         const lines = buffer.split("\n");
         buffer = lines.pop() ?? "";
         for (const line of lines) {
-          const result = handleStreamJsonLine(line, onDelta, {
+          const result = handleStreamJsonLine(line, onTrackedDelta, {
             structuredOutput: useStructured,
             state: streamState,
           });
@@ -389,6 +393,7 @@ export function runClaudeSession(
       });
 
       // stdin 으로 입력 JSONL 흘리고 닫는다.
+      ttftTracker.markStart();
       child.stdin?.write(stdinPayload);
       child.stdin?.end();
     });

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

@@ -49,6 +49,7 @@ export interface GenerateResult {
   tokenName: string;
   usage: ProviderTokenUsageBreakdown;
   durationMs: number;
+  ttftMs?: number | null;
   // Provider 가 직접 산출한 비용. Anthropic Claude Code 는 total_cost_usd 를 주므로 이 값을
   // 우선 사용하고, 없으면 상위가 모델별 가격표로 계산한다.
   costUsd?: number;

package/bundle/src/utils/providers/common/ttft.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+import { createTtftTracker } from "./ttft";
+
+describe("createTtftTracker", () => {
+  it("records the first delta once relative to the marked start", () => {
+    let now = 100;
+    const tracker = createTtftTracker(() => now);
+    const deltas: string[] = [];
+    const onDelta = tracker.wrapDelta((text) => deltas.push(text));
+
+    tracker.markStart();
+    now = 135;
+    onDelta("a");
+    now = 200;
+    onDelta("b");
+
+    expect(tracker.value()).toBe(35);
+    expect(deltas).toEqual(["a", "b"]);
+  });
+
+  it("keeps null when no delta is recorded", () => {
+    const tracker = createTtftTracker(() => 100);
+
+    tracker.markStart();
+
+    expect(tracker.value()).toBeNull();
+  });
+
+  it("does not treat a delta before start as zero", () => {
+    const tracker = createTtftTracker(() => 100);
+
+    tracker.recordFirstDelta();
+
+    expect(tracker.value()).toBeNull();
+  });
+});

package/bundle/src/utils/providers/common/ttft.ts

@@ -0,0 +1,26 @@
+export function createTtftTracker(now: () => number = Date.now): {
+  markStart: () => void;
+  recordFirstDelta: () => void;
+  value: () => number | null;
+  wrapDelta: (onDelta: (text: string) => void) => (text: string) => void;
+} {
+  let startedAt: number | null = null;
+  let ttftMs: number | null = null;
+
+  const recordFirstDelta = () => {
+    if (startedAt === null || ttftMs !== null) return;
+    ttftMs = Math.max(0, now() - startedAt);
+  };
+
+  return {
+    markStart: () => {
+      startedAt = now();
+    },
+    recordFirstDelta,
+    value: () => ttftMs,
+    wrapDelta: (onDelta) => (text) => {
+      recordFirstDelta();
+      onDelta(text);
+    },
+  };
+}

package/bundle/src/utils/providers/openai/codex-worker.test.ts

@@ -53,6 +53,41 @@ function createWorkerWithRequestSpy() {
   return { worker, request };
 }
 
+function createWorkerWithNotificationRpc(
+  onRequest: (
+    method: string,
+    params: unknown,
+    handlers: Map<string, (params: never) => void>,
+  ) => Promise<unknown>,
+) {
+  const worker = new CodexAppServerWorker({
+    tokenId: 1,
+    tokenName: "token",
+    accessToken: "access",
+    accountId: "account",
+  });
+  const handlers = new Map<string, (params: never) => void>();
+  const request = vi.fn((method: string, params?: unknown) => onRequest(method, params, handlers));
+  const rpc = {
+    request,
+    onNotification(method: string, handler: (params: never) => void) {
+      handlers.set(method, handler);
+    },
+  };
+  (
+    worker as unknown as {
+      rpc: typeof rpc;
+      ready: boolean;
+    }
+  ).rpc = rpc;
+  (
+    worker as unknown as {
+      ready: boolean;
+    }
+  ).ready = true;
+  return { worker, request, handlers };
+}
+
 describe("CodexAppServerWorker active turn cleanup", () => {
   it("rejects a non-streaming turn when the worker process exits", async () => {
     const { worker } = createWorkerWithFakeRpc();
@@ -101,6 +136,119 @@ describe("CodexAppServerWorker active turn cleanup", () => {
   });
 });
 
+describe("CodexAppServerWorker TTFT", () => {
+  it("captures fast non-stream deltas registered before turn/start completes", async () => {
+    let now = 1_000;
+    const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => now);
+    const { worker } = createWorkerWithNotificationRpc(async (method, _params, handlers) => {
+      if (method === "thread/start") {
+        return { thread: { id: "thread-1" }, model: "gpt-test" };
+      }
+      if (method === "turn/start") {
+        now = 1_025;
+        handlers.get("item/agentMessage/delta")?.({
+          threadId: "thread-1",
+          delta: "h",
+        } as never);
+        now = 1_050;
+        handlers.get("item/agentMessage/delta")?.({
+          threadId: "thread-1",
+          delta: "i",
+        } as never);
+        handlers.get("turn/completed")?.({
+          threadId: "thread-1",
+          turn: { status: "completed", durationMs: 90 },
+        } as never);
+        return { turn: { id: "turn-1" } };
+      }
+      throw new Error(`unexpected request: ${method}`);
+    });
+
+    try {
+      const result = await worker.executeTurn({
+        input: [{ type: "text", text: "hi", text_elements: [] }],
+      });
+
+      expect(result.text).toBe("hi");
+      expect(result.ttftMs).toBe(25);
+    } finally {
+      nowSpy.mockRestore();
+    }
+  });
+
+  it("keeps non-stream ttft null when no delta arrives", async () => {
+    const { worker } = createWorkerWithNotificationRpc(async (method, _params, handlers) => {
+      if (method === "thread/start") {
+        return { thread: { id: "thread-1" }, model: "gpt-test" };
+      }
+      if (method === "turn/start") {
+        handlers.get("turn/completed")?.({
+          threadId: "thread-1",
+          turn: { status: "completed", durationMs: 90 },
+        } as never);
+        return { turn: { id: "turn-1" } };
+      }
+      throw new Error(`unexpected request: ${method}`);
+    });
+
+    const result = await worker.executeTurn({
+      input: [{ type: "text", text: "hi", text_elements: [] }],
+    });
+
+    expect(result.ttftMs).toBeNull();
+  });
+
+  it("captures stream ttft from the first delta only", async () => {
+    let now = 2_000;
+    const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => now);
+    const { worker } = createWorkerWithNotificationRpc(async (method, _params, handlers) => {
+      if (method === "thread/start") {
+        return { thread: { id: "thread-1" }, model: "gpt-test" };
+      }
+      if (method === "turn/start") {
+        now = 2_030;
+        handlers.get("item/agentMessage/delta")?.({
+          threadId: "thread-1",
+          delta: "a",
+        } as never);
+        now = 2_080;
+        handlers.get("item/agentMessage/delta")?.({
+          threadId: "thread-1",
+          delta: "b",
+        } as never);
+        handlers.get("turn/completed")?.({
+          threadId: "thread-1",
+          turn: { status: "completed", durationMs: 120 },
+        } as never);
+        return { turn: { id: "turn-1" } };
+      }
+      throw new Error(`unexpected request: ${method}`);
+    });
+    const callbacks: StreamCallbacks = {
+      onDelta: vi.fn(),
+      onComplete: vi.fn(),
+      onError: vi.fn(),
+    };
+
+    try {
+      await worker.executeTurnStream(
+        {
+          input: [{ type: "text", text: "hi", text_elements: [] }],
+        },
+        callbacks,
+      );
+
+      expect(callbacks.onDelta).toHaveBeenCalledWith("a");
+      expect(callbacks.onDelta).toHaveBeenCalledWith("b");
+      expect(callbacks.onComplete).toHaveBeenCalledWith(
+        expect.objectContaining({ text: "ab", ttftMs: 30 }),
+      );
+    } finally {
+      nowSpy.mockRestore();
+    }
+  });
+});
+
 describe("CodexAppServerWorker prompt prefix", () => {
   it("uses the same base instructions with and without an output schema", async () => {
     type WorkerInternals = {

package/bundle/src/utils/providers/openai/codex-worker.ts

@@ -10,6 +10,7 @@ import { type TokenUsageBreakdown } from "../../../codex-protocol/v2/TokenUsageB
 import { type TurnStartParams } from "../../../codex-protocol/v2/TurnStartParams";
 import { type TurnStartResponse } from "../../../codex-protocol/v2/TurnStartResponse";
 import { type StreamCallbacks as CommonStreamCallbacks } from "../common/provider-dispatcher";
+import { createTtftTracker } from "../common/ttft";
 import { CodexRpcClient } from "./codex-rpc";
 
 const logger = getLogger(["qgrid", "codex-worker"]);
@@ -44,6 +45,7 @@ export interface TurnResult {
   text: string;
   usage: TokenUsageBreakdown;
   durationMs: number;
+  ttftMs: number | null;
   model: string;
 }
 
@@ -387,8 +389,17 @@ export class CodexAppServerWorker {
     } else {
       ({ threadId, model } = await this.createThread(req));
     }
-    await this.startTurnOnThread(threadId, req);
-    const result = await this.consumeTurnNotifications(threadId, model);
+    const ttftTracker = createTtftTracker();
+    const resultPromise = this.consumeTurnNotifications(threadId, model, ttftTracker);
+    try {
+      ttftTracker.markStart();
+      await this.startTurnOnThread(threadId, req);
+    } catch (e) {
+      this.failActiveTurn(e as Error);
+      await resultPromise.catch(() => {});
+      throw e;
+    }
+    const result = await resultPromise;
     return { ...result, threadId };
   }
 
@@ -405,10 +416,20 @@ export class CodexAppServerWorker {
     } else {
       ({ threadId, model } = await this.createThread(req));
     }
-    const { turnId } = await this.startTurnOnThread(threadId, req);
     cb.onThreadId?.(threadId);
+    const ttftTracker = createTtftTracker();
+    const resultPromise = this.consumeStreamNotifications(threadId, model, cb, ttftTracker);
+    let turnId: string;
+    try {
+      ttftTracker.markStart();
+      ({ turnId } = await this.startTurnOnThread(threadId, req));
+    } catch (e) {
+      this.failActiveTurn(e as Error);
+      await resultPromise.catch(() => {});
+      throw e;
+    }
     cb.onTurnId?.(turnId);
-    await this.consumeStreamNotifications(threadId, model, cb);
+    await resultPromise;
     return { threadId };
   }
 
@@ -456,7 +477,11 @@ export class CodexAppServerWorker {
     abort?.(error);
   }
 
-  private consumeTurnNotifications(threadId: string, model: string): Promise<TurnResult> {
+  private consumeTurnNotifications(
+    threadId: string,
+    model: string,
+    ttftTracker = createTtftTracker(),
+  ): Promise<TurnResult> {
     return new Promise<TurnResult>((resolve, reject) => {
       let settled = false;
       let abort: ActiveTurnAbort;
@@ -510,6 +535,12 @@ export class CodexAppServerWorker {
         if (p.item.type === "agentMessage") text = p.item.text;
       });
 
+      this.rpc!.onNotification("item/agentMessage/delta", (p) => {
+        if (p.threadId !== threadId) return;
+        ttftTracker.recordFirstDelta();
+        text += p.delta;
+      });
+
       this.rpc!.onNotification("thread/tokenUsage/updated", (p) => {
         if (p.threadId !== threadId) return;
         // thread 재사용 시 .total 은 대화 전체 누적이라, cold 였던 이전 turn 까지 섞여
@@ -521,8 +552,11 @@ export class CodexAppServerWorker {
       this.rpc!.onNotification("turn/completed", (p) => {
         if (p.threadId !== threadId) return;
         durationMs = p.turn.durationMs ?? 0;
-        if (p.turn.status === "completed") finishWithResult({ text, usage, durationMs, model });
-        else finishWithError(new Error(`turn failed: ${JSON.stringify(p.turn.error)}`));
+        if (p.turn.status === "completed") {
+          finishWithResult({ text, usage, durationMs, ttftMs: ttftTracker.value(), model });
+        } else {
+          finishWithError(new Error(`turn failed: ${JSON.stringify(p.turn.error)}`));
+        }
       });
 
       this.rpc!.onNotification("error", (p) => {
@@ -538,6 +572,7 @@ export class CodexAppServerWorker {
     threadId: string,
     model: string,
     cb: StreamCallbacks,
+    ttftTracker = createTtftTracker(),
   ): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       let settled = false;
@@ -590,6 +625,7 @@ export class CodexAppServerWorker {
 
       this.rpc!.onNotification("item/agentMessage/delta", (p) => {
         if (p.threadId !== threadId) return;
+        ttftTracker.recordFirstDelta();
         text += p.delta;
         cb.onDelta(p.delta);
       });
@@ -610,7 +646,13 @@ export class CodexAppServerWorker {
       this.rpc!.onNotification("turn/completed", (p) => {
         if (p.threadId !== threadId) return;
         if (p.turn.status === "completed") {
-          finishWithComplete({ text, usage, durationMs: p.turn.durationMs ?? 0, model });
+          finishWithComplete({
+            text,
+            usage,
+            durationMs: p.turn.durationMs ?? 0,
+            ttftMs: ttftTracker.value(),
+            model,
+          });
         } else {
           finishWithError(new Error(`turn ${p.turn.status}: ${JSON.stringify(p.turn.error)}`));
         }