@cartanova/qgrid-cli 2.10.9 → 2.11.0

package/bundle/src/application/qgrid/conv-routing.ts

@@ -1,14 +1,21 @@
+import { createHash } from "node:crypto";
+
 /**
  * conv-routing — 대화 연속성(cache affinity) 좌표 검증/구성.
  *
  * 모든 turn은 현재 input과 전체 history를 전달한다.
- * OpenAI의 epoch=-1 좌표는 system/model hash와 opaque affinity를 검증한 뒤
+ * Direct provider(OpenAI, Grok)의 epoch=-1 좌표는 system/model hash와 opaque affinity를 검증한 뒤
  * token 선택과 prompt-cache 힌트로만 사용한다.
  */
-import { createHash } from "node:crypto";
+import { z } from "zod";
 
 import { type ReuseThreadCoord } from "../../utils/providers/common/provider-dispatcher";
-import { type JsonValue, type UserInput } from "../../utils/providers/common/provider-types";
+import {
+  jsonValueSchema,
+  type JsonValue,
+  type ProviderId,
+  type UserInput,
+} from "../../utils/providers/common/provider-types";
 import { type QgridThreadCoord, type QueryInput, type QgridToolResultInput } from "./qgrid.types";
 
 export function systemHash(system?: string, modelNamespace?: string): string {
@@ -23,8 +30,10 @@ function toolResultsToText(toolResults: QgridToolResultInput[]): string {
   const lines = toolResults.map((tr) => {
     const name = tr.toolName ? ` (${tr.toolName})` : "";
     const errMark = tr.isError ? " [error]" : "";
+
     return `Tool result for call ${tr.toolCallId}${name}${errMark}: ${tr.output}`;
   });
+
   return `${lines.join("\n")}\n\nNow continue answering the user's request using these results.`;
 }
 
@@ -40,22 +49,31 @@ export interface ConvDecision {
   preferredTokenId?: number;
 }
 
+// HTTPS direct transport 로 prompt_cache_key affinity 를 쓰는 provider.
+export type DirectProviderId = Extract<ProviderId, "openai" | "grok">;
+
 export interface ConvRoutingOptions {
-  directOpenAI?: boolean;
+  directProvider?: DirectProviderId;
+  // 보통 `<provider>/<model>`. 같은 system 이라도 provider/model 이 다르면 좌표를 공유하지 않는다.
   modelNamespace?: string;
 }
 
-// 입력과 전체 history를 구성하고, 검증된 OpenAI cache affinity만 부가한다.
+// 입력과 전체 history를 구성하고, 검증된 direct-provider cache affinity만 부가한다.
 export function decideConvRouting(
   input: QueryInput,
   options: ConvRoutingOptions = {},
 ): ConvDecision {
+  const directProvider = options.directProvider;
+
   const sysHash = systemHash(
     input.system,
-    options.directOpenAI ? (options.modelNamespace ?? input.model ?? "openai") : undefined,
+    directProvider === undefined
+      ? undefined
+      : (options.modelNamespace ?? input.model ?? directProvider),
   );
+
   const history: Array<JsonValue> | undefined = input.history
-    ? (JSON.parse(input.history) as Array<JsonValue>)
+    ? z.array(jsonValueSchema).parse(JSON.parse(input.history))
     : undefined;
 
   const coord = input.runContext?.threadCoord;
@@ -63,14 +81,15 @@ export function decideConvRouting(
   // 재사용 자격: 좌표 존재 + system 동일. sessionKey 격리 + systemHash 로 대화 동일성이
   // 보장되고, 공통 prefix 는 백엔드가 prompt_cache_key 고정으로 알아서 캐시한다.
   const directCoordEligible =
-    options.directOpenAI === true &&
+    directProvider !== undefined &&
     coord?.epoch === -1 &&
     coord.systemHash === sysHash &&
     input.cacheAffinityKey !== undefined &&
     coord.threadId === input.cacheAffinityKey;
+
   // affinity 를 요청하지 않은 one-shot 요청에 임의 키를 붙이면 transport 가 그 소켓을
   // affinity 소켓으로 오인해 재사용되지 않을 연결을 계속 붙들어 둔다 → 키를 비워 둔다.
-  const cacheKey = options.directOpenAI ? input.cacheAffinityKey : undefined;
+  const cacheKey = directProvider === undefined ? undefined : input.cacheAffinityKey;
 
   return {
     // tool follow-up도 실행 user 줄에 결과를 사용해 계속 답하라는 안내를 담는다.
@@ -87,19 +106,25 @@ function buildDeltaInput(input: QueryInput): Array<UserInput> {
   if (input.toolResults && input.toolResults.length > 0) {
     return [{ type: "text", text: toolResultsToText(input.toolResults), text_elements: [] }];
   }
+
   if (input.input && input.input.length > 0) {
     const hasText = input.input.some((part) => part.type === "text");
+
     const parts: Array<UserInput> = input.input.map((part) => {
       if (part.type === "text") {
         return { type: "text", text: part.text, text_elements: part.text_elements };
       }
+
       return { type: "image", url: part.url };
     });
+
     if (!hasText && input.prompt.length > 0) {
       return [{ type: "text", text: input.prompt, text_elements: [] }, ...parts];
     }
+
     return parts;
   }
+
   return [{ type: "text", text: input.prompt, text_elements: [] }];
 }
 
@@ -117,6 +142,7 @@ export function issueConvContext(
       systemHash: decision.systemHash,
     };
   }
+
   return {
     workerId: threadCoord.workerId,
     threadId: threadCoord.threadId,

package/bundle/src/application/qgrid/expired-token-reminder.ts

@@ -45,12 +45,16 @@ export function buildReminderContext(
   userMap: Map<string, string>,
 ): string {
   const showLabel = tokens.length > 1;
+
   const lines = tokens.map((token) => {
     const mention = mentionFor(token.name, userMap);
     const label = token.name ?? "unnamed";
+
     if (!showLabel) return mention;
+
     return mention ? `${mention} ${label}` : label;
   });
+
   return [...lines, "재로그인이 필요합니다"].filter(Boolean).join("\n");
 }
 
@@ -59,6 +63,7 @@ async function sendReminder(
   mode: "scheduled" | "manual",
 ): Promise<number> {
   const expired = await deps.findReauthRequired();
+
   if (expired.length === 0) return 0;
 
   const userMap = deps.getSlackUserMap();
@@ -72,6 +77,7 @@ async function sendReminder(
     urgent: mode === "manual",
     throwOnFailure: mode === "manual",
   });
+
   return expired.length;
 }
 
@@ -95,12 +101,14 @@ function scheduleExpiredTokenReminder(runNow: boolean, deps: ExpiredTokenReminde
   // 주기 값과 별개인 스위치다. 꺼도 주기는 남아 있어 다시 켤 때 고르던 값이 그대로다.
   if (deps.readSetting("slack.remindersEnabled", "SLACK_REMINDERS_ENABLED") === "false") {
     logger.info("expired token reminder disabled");
+
     return;
   }
 
   const minutes = Number(
     deps.readSetting("slack.expiryReminderMinutes", "SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES") ?? 0,
   );
+
   if (!Number.isFinite(minutes) || minutes <= 0) return;
 
   logger.info(
@@ -109,7 +117,7 @@ function scheduleExpiredTokenReminder(runNow: boolean, deps: ExpiredTokenReminde
 
   const run = () =>
     sendReminder(deps, "scheduled").catch((e) =>
-      logger.warn(`reminder failed: ${(e as Error).message}`),
+      logger.warn(`reminder failed: ${e instanceof Error ? e.message : String(e)}`),
     );
 
   if (runNow) void run();

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

@@ -4,6 +4,7 @@
 import { createHash, randomBytes } from "node:crypto";
 
 import { getLogger } from "@logtape/logtape";
+import { z } from "zod";
 
 export type AnthropicUsageRaw = {
   error?: string;
@@ -11,6 +12,35 @@ export type AnthropicUsageRaw = {
   seven_day?: { utilization: number | null; resets_at: string | null } | null;
   seven_day_overage_included?: { utilization: number | null; resets_at: string | null } | null;
 };
+
+const usageWindowSchema = z
+  .object({ utilization: z.number().nullable(), resets_at: z.string().nullable() })
+  .nullable()
+  .optional();
+
+const anthropicUsageRawSchema: z.ZodType<AnthropicUsageRaw> = z.looseObject({
+  error: z.string().optional(),
+  five_hour: usageWindowSchema,
+  seven_day: usageWindowSchema,
+  seven_day_overage_included: usageWindowSchema,
+});
+
+const tokenExchangeResponseSchema = z.object({
+  access_token: z.string(),
+  refresh_token: z.string(),
+  expires_in: z.number(),
+  scope: z.string(),
+  account: z.object({ uuid: z.string(), email_address: z.string() }).optional(),
+});
+
+// A refresh response may omit refresh_token; the caller then keeps the current one.
+const tokenRefreshResponseSchema = z.object({
+  access_token: z.string(),
+  refresh_token: z.string().optional(),
+  expires_in: z.number(),
+  scope: z.string(),
+});
+
 export type AnthropicUsageWithMeta = {
   data: AnthropicUsageRaw;
   cachedAt: number;
@@ -21,6 +51,7 @@ const logger = getLogger(["qgrid", "oauth"]);
 const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 const AUTHORIZE_URL = "https://claude.com/cai/oauth/authorize";
 const TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+
 // client 허용 목록에 있는 콘솔 콜백. 인증 후 콘솔 페이지가 `code#state`를 표시하고
 // 사용자가 붙여넣는 코드 플로우(Claude Code CLI와 동일)에 사용한다.
 export const CONSOLE_CALLBACK_URL = "https://console.anthropic.com/oauth/code/callback";
@@ -48,10 +79,17 @@ function base64URLEncode(buffer: Buffer): string {
   return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 
-export function generatePKCE(): { codeVerifier: string; codeChallenge: string; state: string } {
+export interface PKCEChallenge {
+  codeVerifier: string;
+  codeChallenge: string;
+  state: string;
+}
+
+export function generatePKCE(): PKCEChallenge {
   const codeVerifier = base64URLEncode(randomBytes(32));
   const codeChallenge = base64URLEncode(createHash("sha256").update(codeVerifier).digest());
   const state = base64URLEncode(randomBytes(32));
+
   return { codeVerifier, codeChallenge, state };
 }
 
@@ -65,6 +103,7 @@ export function buildAuthUrl(codeChallenge: string, state: string, redirectUri:
   url.searchParams.append("code_challenge", codeChallenge);
   url.searchParams.append("code_challenge_method", "S256");
   url.searchParams.append("state", state);
+
   return url.toString();
 }
 
@@ -95,18 +134,13 @@ export async function exchangeCodeForTokens(
       state,
     }),
   });
+
   if (!res.ok) {
     const text = await res.text();
     throw new Error(`Token exchange failed (${res.status}): ${text}`);
   }
 
-  const data = (await res.json()) as {
-    access_token: string;
-    refresh_token: string;
-    expires_in: number;
-    scope: string;
-    account?: { uuid: string; email_address: string };
-  };
+  const data = tokenExchangeResponseSchema.parse(await res.json());
 
   return {
     accessToken: data.access_token,
@@ -148,16 +182,13 @@ export async function refreshAccessToken(refreshToken: string): Promise<OAuthTok
       scope: REFRESH_SCOPES.join(" "),
     }),
   });
+
   if (!res.ok) {
     const text = await res.text();
     throw new RefreshFailedError(res.status, text);
   }
-  const data = (await res.json()) as {
-    access_token: string;
-    refresh_token: string;
-    expires_in: number;
-    scope: string;
-  };
+
+  const data = tokenRefreshResponseSchema.parse(await res.json());
 
   return {
     accessToken: data.access_token,
@@ -181,6 +212,7 @@ export async function fetchUsage(accessToken: string): Promise<AnthropicUsageRaw
 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;
   }
@@ -193,11 +225,13 @@ export async function fetchUsageWithMeta(accessToken: string): Promise<Anthropic
     },
     signal: AbortSignal.timeout(5000),
   });
+
   if (!res.ok) {
     const text = await res.text();
 
     // 파싱 시도해서 에러 메시지 추출
     let errorMessage = `Error ${res.status}`;
+
     try {
       const parsed = JSON.parse(text);
       errorMessage = parsed.error?.message ?? errorMessage;
@@ -214,12 +248,14 @@ export async function fetchUsageWithMeta(accessToken: string): Promise<Anthropic
     const errorResult = { error: errorMessage };
     const entry = { data: errorResult, cachedAt: Date.now() };
     usageCache[cacheKey] = entry;
+
     return entry;
   }
 
-  const data = (await res.json()) as AnthropicUsageRaw;
+  const data = anthropicUsageRawSchema.parse(await res.json());
   // cache invalidate
   const entry = { data, cachedAt: Date.now() };
   usageCache[cacheKey] = entry;
+
   return entry;
 }

package/bundle/src/application/qgrid/qgrid-image-generation.ts

@@ -42,6 +42,7 @@ export function resolveImageGenerationOptions(
   options: ImageGenerationOptions | undefined,
 ): ResolvedImageGenerationOptions {
   const size = options?.size;
+
   return {
     quality: options?.quality ?? DEFAULT_IMAGE_GENERATION_QUALITY,
     // Unknown/custom sizes use the default price, without changing output hints.
@@ -61,7 +62,9 @@ export function imageGenerationCostMethod(
   ) {
     return "estimated:gpt-image-2:reported-usage:public-prices:conservative";
   }
+
   const resolved = resolveImageGenerationOptions(options);
+
   return `assumed:${CODEX_IMAGE_GENERATION_MODEL}:${resolved.quality}:${resolved.size}:png`;
 }
 
@@ -71,8 +74,10 @@ export function estimateImageGenerationCostMicroUsd(
 ): number | null {
   const images = result.content.filter((item) => item.type === "image");
   const imageCount = images.length;
+
   if (imageCount === 0) return null;
   const usage = images.find((image) => image.generation?.usage)?.generation?.usage;
+
   if (usage) {
     // Response-level image usage is carried by its first image only.
     // Do not multiply it by output count or price it as the requested text driver.
@@ -82,15 +87,19 @@ export function estimateImageGenerationCostMicroUsd(
     // Use a consistent reported split; unknown input is conservatively priced as
     // images. Cache discounts and private subscription billing remain unknown.
     const details = usage.input_tokens_details;
+
     const textTokens =
       details && details.text_tokens + details.image_tokens <= usage.input_tokens
         ? details.text_tokens
         : 0;
+
     return Math.round(
       textTokens * 5 + (usage.input_tokens - textTokens) * 8 + usage.output_tokens * 30,
     );
   }
+
   const resolved = resolveImageGenerationOptions(options);
   const unitCost = IMAGE_OUTPUT_COST_MICRO_USD[resolved.quality][resolved.size];
+
   return imageCount * unitCost;
 }

package/bundle/src/application/qgrid/qgrid-response-format.ts

@@ -1,3 +1,4 @@
+import { type JsonValue } from "../../utils/providers/common/provider-types";
 import {
   CODEX_IMAGE_GENERATION_MODEL,
   resolveImageGenerationOptions,
@@ -26,7 +27,9 @@ export function formatResponseForLog(result: QueryOutput): string {
   return result.content
     .flatMap((item) => {
       if (item.type === "text") return [item.text];
+
       if (item.type === "image") return [formatImagePartForLog(item)];
+
       return [];
     })
     .filter((part) => part.length > 0)
@@ -39,6 +42,7 @@ export function getImageParts(result: QueryOutput): Extract<QgridContent, { type
 
 export function formatImagePartForLog(image: Extract<QgridContent, { type: "image" }>): string {
   const alt = escapeHtmlAttribute(image.revisedPrompt ?? "generated image");
+
   return `<img src="data:${image.mediaType ?? "image/png"};base64,${image.data}" alt="${alt}" />`;
 }
 
@@ -47,29 +51,38 @@ export function imageGenerationToolArgs(
   options: { includeInputImages?: boolean; generation?: ImageGenerationMetadata } = {},
 ): string {
   const resolved = resolveImageGenerationOptions(args.imageGenerationOptions);
+
   const inputImages =
     options.includeInputImages === false ? [] : extractInputImagesForToolArgs(args);
-  return JSON.stringify({
-    prompt: args.prompt,
-    ...(inputImages.length > 0 ? { inputImages } : {}),
-    driverModel: args.model ?? null,
-    tool: {
-      ...CODEX_IMAGE_GENERATION_TOOL_CONFIG,
-      ...(args.imageGenerationOptions?.outputFormat
-        ? { outputFormat: args.imageGenerationOptions.outputFormat }
-        : {}),
-    },
-    ...(args.imageGenerationOptions ? { requestedOptions: args.imageGenerationOptions } : {}),
-    ...(options.generation
-      ? { observedGeneration: options.generation }
-      : {
-          pricingAssumption: {
-            model: CODEX_IMAGE_GENERATION_MODEL,
-            quality: resolved.quality,
-            size: resolved.size,
-          },
-        }),
-  });
+
+  // Keys are assigned in their serialized order; request logs store this JSON text.
+  const toolArgs: Record<string, JsonValue> = {};
+  toolArgs.prompt = args.prompt;
+
+  if (inputImages.length > 0) toolArgs.inputImages = inputImages;
+  toolArgs.driverModel = args.model ?? null;
+  const tool: Record<string, JsonValue> = {};
+  Object.assign(tool, CODEX_IMAGE_GENERATION_TOOL_CONFIG);
+
+  if (args.imageGenerationOptions?.outputFormat) {
+    tool.outputFormat = args.imageGenerationOptions.outputFormat;
+  }
+
+  toolArgs.tool = tool;
+
+  if (args.imageGenerationOptions) toolArgs.requestedOptions = args.imageGenerationOptions;
+
+  if (options.generation) {
+    toolArgs.observedGeneration = options.generation;
+  } else {
+    toolArgs.pricingAssumption = {
+      model: CODEX_IMAGE_GENERATION_MODEL,
+      quality: resolved.quality,
+      size: resolved.size,
+    };
+  }
+
+  return JSON.stringify(toolArgs);
 }
 
 export function buildImageGenerationToolSteps(
@@ -101,16 +114,21 @@ export function buildImageGenerationToolSteps(
   }));
 }
 
-function extractInputImagesForToolArgs(args: QueryInput): Array<{
+type LoggedInputImage = {
   mediaType?: string;
   data?: string;
   url?: string;
   byteSize?: number;
-}> {
+};
+
+export function extractInputImagesForToolArgs(args: QueryInput): LoggedInputImage[] {
   const images = args.input?.filter((item) => item.type === "image") ?? [];
+
   return images.map((image) => {
     const dataUrl = parseDataUrl(image.url);
+
     if (!dataUrl) return { url: image.url };
+
     if (dataUrl.isBase64 && dataUrl.mediaType.toLowerCase().startsWith("image/")) {
       return {
         mediaType: dataUrl.mediaType,
@@ -118,11 +136,15 @@ function extractInputImagesForToolArgs(args: QueryInput): Array<{
         byteSize: base64ByteSize(dataUrl.data),
       };
     }
-    return {
+
+    const logged: LoggedInputImage = {
       mediaType: dataUrl.mediaType,
       url: `[data-url ${image.url.length} chars]`,
-      ...(dataUrl.isBase64 ? { byteSize: base64ByteSize(dataUrl.data) } : {}),
     };
+
+    if (dataUrl.isBase64) logged.byteSize = base64ByteSize(dataUrl.data);
+
+    return logged;
   });
 }
 
@@ -130,13 +152,16 @@ function parseDataUrl(
   value: string,
 ): { mediaType: string; data: string; isBase64: boolean } | null {
   const match = /^data:([^;,]+)((?:;[^,]*)*),(.*)$/is.exec(value);
+
   if (!match) return null;
   const params = match[2]!.toLowerCase().split(";").filter(Boolean);
+
   return { mediaType: match[1]!, data: match[3]!, isBase64: params.includes("base64") };
 }
 
 function base64ByteSize(value: string): number {
   const normalized = /\s/.test(value) ? value.replace(/\s/g, "") : value;
   const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+
   return Math.max(Math.floor((normalized.length * 3) / 4) - padding, 0);
 }

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

@@ -112,6 +112,25 @@ describe("qgrid run lifecycle start", () => {
     });
   });
 
+  it.each([undefined, "Caller system"])(
+    "logs the Anthropic schema instructions with system=%s",
+    async (system) => {
+      const jsonSchema = '{"type":"object","properties":{"answer":{"type":"string"}}}';
+      await beforeQuery({
+        prompt: "hi",
+        model: "anthropic/claude-opus-5-5",
+        system,
+        jsonSchema,
+      });
+
+      const saved = createRunMock.mock.calls[0]![0];
+      expect(saved.system_prompt).toContain("## Output Format");
+      expect(saved.system_prompt).toContain(`<output-json-schema>\n${jsonSchema}\n</output-json-schema>`);
+      if (system) expect(saved.system_prompt).toMatch(/^Caller system\n\n/);
+      expect(saved.json_schema).toBe(jsonSchema);
+    },
+  );
+
   it.each([
     ["openai/gpt-6-sol", "fast", "fast"],
     ["openai/gpt-6-sol", "flex", "flex"],
@@ -122,6 +141,20 @@ describe("qgrid run lifecycle start", () => {
     expect(createRunMock).toHaveBeenCalledWith(expect.objectContaining({ service_tier: expected }));
   });
 
+  it("logs current-turn input images on the run", async () => {
+    await beforeQuery({
+      prompt: "describe",
+      model: "openai/gpt-6-sol",
+      input: [
+        { type: "text", text: "describe", text_elements: [] },
+        { type: "image", url: "data:image/jpeg;base64,AQID" },
+      ],
+    });
+    expect(createRunMock).toHaveBeenCalledWith(expect.objectContaining({
+      input_images: [{ mediaType: "image/jpeg", data: "AQID", byteSize: 3 }],
+    }));
+  });
+
   it.each([false, true, undefined])("does not log ignored effort when thinking is %s", async (thinking) => {
     await beforeQuery({ prompt: "hi", model: "openai/gpt-6-sol", thinking, effort: "high" });
     expect(createRunMock).toHaveBeenCalledWith(expect.objectContaining({