@cartanova/qgrid-cli 2.10.10 → 2.11.0

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

@@ -8,7 +8,21 @@ import {
   type ImageGenerationMetadata,
   type ImageGenerationOptions,
   type QgridContent,
+  type ReasoningSummary,
+  type Verbosity,
 } from "../../../application/qgrid/qgrid.types";
+import {
+  type GrokImageEditRequest,
+  type GrokImageGenerateRequest,
+  type GrokImageResponse,
+  type GrokSpeechResult,
+  type GrokSttResponse,
+  type GrokTranscribeRequest,
+  type GrokTtsRequest,
+  type GrokVideoStart,
+  type GrokVideoStartRequest,
+  type GrokVideoStatus,
+} from "../grok/grok-types";
 import { type JsonValue, type TokenUsageBreakdown, type UserInput } from "./provider-types";
 
 // qgrid provider 내부 표준 usage. provider 전용 cache write 세부 필드는 여기서 확장해 보존한다.
@@ -16,8 +30,38 @@ export type ProviderTokenUsageBreakdown = TokenUsageBreakdown & {
   cacheCreationInputTokens?: number;
   cacheCreationInputTokens5m?: number;
   cacheCreationInputTokens1h?: number;
+  // Live context size reported by the provider (Grok `usage.context_details`), distinct from
+  // the cumulative input token count.
+  contextTokens?: number;
+};
+
+// Native provider tools. Function tools follow the Responses API shape; built-in tools are
+// executed server-side by the provider (Grok `web_search` / `x_search`).
+export type ProviderFunctionToolDefinition = {
+  type: "function";
+  name: string;
+  description?: string;
+  parameters: JsonValue;
+  strict?: boolean;
 };
 
+export type ProviderBuiltinToolDefinition = { type: "web_search" } | { type: "x_search" };
+
+export type ToolDefinition = ProviderFunctionToolDefinition | ProviderBuiltinToolDefinition;
+
+// A native function call returned by the provider (not the qgrid tool-emulation envelope).
+export interface ProviderToolCall {
+  toolCallId: string;
+  toolName: string;
+  // Raw JSON argument string as returned by the provider.
+  input: string;
+}
+
+export interface XaiProviderMetadata {
+  costInUsdTicks?: number;
+  contextWindow?: number;
+}
+
 // 공개 thread 좌표의 provider 결과 부분. 이름은 호환성을 위해 유지한다.
 export interface ReuseThreadCoord {
   workerId: number;
@@ -58,8 +102,8 @@ export interface GenerateRequest {
   stopAfterOutputMessage?: (text: string, phase?: string) => boolean;
   effort?: string;
   thinking?: boolean;
-  verbosity?: string;
-  reasoningSummary?: string;
+  verbosity?: Verbosity;
+  reasoningSummary?: ReasoningSummary;
   serviceTier?: string;
   // provider 실행 제한(ms). Queue selection 이후의 active provider request 전체에 적용한다.
   timeoutMs?: number;
@@ -78,6 +122,11 @@ export interface GenerateRequest {
   // 이 플래그가 있으면 OpenAI prompt-cache affinity 라우팅을 건너뛴다.
   imageGeneration?: boolean | "auto";
   imageGenerationOptions?: ImageGenerationOptions;
+  // Opaque provider namespaces (for example `providerOptions.xai`). Each dispatcher validates its
+  // own namespace; other providers ignore it.
+  providerOptions?: { [key: string]: JsonValue | undefined };
+  // Native tools for providers that accept them on the wire (Grok).
+  tools?: ToolDefinition[];
 }
 
 export interface GenerateResult {
@@ -97,6 +146,11 @@ export interface GenerateResult {
   threadCoord: ReuseThreadCoord;
   // 이미지 turn 에서만 채워짐(OpenAI 경로). 완성 이미지가 없으면 undefined.
   images?: GeneratedImage[];
+  // Origin of costUsd; "provider" when the provider reported the cost itself.
+  costSource?: CostSource;
+  providerMetadata?: { xai?: XaiProviderMetadata };
+  // Native function calls returned by providers that accept `GenerateRequest.tools`.
+  toolCalls?: ProviderToolCall[];
 }
 
 // 스트림 콜백 컨테이너. 계층별로 onComplete payload 만 다르고, 스트림 이벤트 shape 는 동일하다.
@@ -117,3 +171,45 @@ export interface ProviderDispatcher {
   start(): Promise<void>;
   stop(): Promise<void>;
 }
+
+// Token selection hints for media/voice requests. There is no cache affinity; a caller may still
+// pin an exact token.
+export interface MediaTokenSelection {
+  preferredTokenId?: number;
+  requirePreferredToken?: boolean;
+}
+
+export interface MediaDispatchResult<T> {
+  result: T;
+  tokenId: number;
+  tokenName: string;
+}
+
+// Optional capability: image and video generation. Video polling always goes to the token that
+// started the job.
+export interface MediaDispatcher {
+  generateImages(
+    request: GrokImageGenerateRequest & MediaTokenSelection,
+  ): Promise<MediaDispatchResult<GrokImageResponse>>;
+  editImages(
+    request: GrokImageEditRequest & MediaTokenSelection,
+  ): Promise<MediaDispatchResult<GrokImageResponse>>;
+  startVideo(
+    request: GrokVideoStartRequest & MediaTokenSelection,
+  ): Promise<MediaDispatchResult<GrokVideoStart>>;
+  getVideo(
+    tokenId: number,
+    requestId: string,
+    signal?: AbortSignal,
+  ): Promise<MediaDispatchResult<GrokVideoStatus>>;
+}
+
+// Optional capability: speech-to-text and text-to-speech.
+export interface VoiceDispatcher {
+  transcribe(
+    request: GrokTranscribeRequest & MediaTokenSelection,
+  ): Promise<MediaDispatchResult<GrokSttResponse>>;
+  speak(
+    request: GrokTtsRequest & { signal?: AbortSignal } & MediaTokenSelection,
+  ): Promise<MediaDispatchResult<GrokSpeechResult>>;
+}

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

@@ -1,11 +1,54 @@
-export type JsonValue =
+import { z } from "zod";
+
+// qgrid provider route prefix (`<provider>/<model>`). 새 provider 는 여기에만 추가한다.
+export const PROVIDER_IDS = ["openai", "anthropic", "grok"] as const;
+
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+
+export function isProviderId(value: string | undefined): value is ProviderId {
+  return PROVIDER_IDS.some((id) => id === value);
+}
+
+export type JsonValue = number | string | boolean | JsonValue[] | JsonObject | null;
+
+export interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+
+/** JsonValue accepted read-only, for callers that pass `as const` or frozen JSON. */
+export type ReadonlyJsonValue =
   | number
   | string
   | boolean
-  | JsonValue[]
-  | { [key: string]: JsonValue | undefined }
+  | readonly ReadonlyJsonValue[]
+  | ReadonlyJsonObject
   | null;
 
+export interface ReadonlyJsonObject {
+  readonly [key: string]: ReadonlyJsonValue | undefined;
+}
+
+/** Decodes parsed JSON text (for example `JSON.parse` output) into `JsonValue`. */
+export const jsonValueSchema: z.ZodType<JsonValue> = z.json();
+
+// Shallow: accepts any non-null, non-array object, including null-prototype objects.
+const anyJsonObject = z.looseObject({});
+
+/** Narrows an already-decoded JSON value to its object member. */
+export function isJsonObject(value: JsonValue | undefined): value is JsonObject {
+  return anyJsonObject.safeParse(value).success;
+}
+
+/** The string member of a decoded JSON value, or undefined for any other member. */
+export function jsonString(value: JsonValue | undefined): string | undefined {
+  return z.string().safeParse(value).data;
+}
+
+/** The number member of a decoded JSON value, or undefined for any other member. */
+export function jsonNumber(value: JsonValue | undefined): number | undefined {
+  return z.number().safeParse(value).data;
+}
+
 export type UserInput =
   | { type: "text"; text: string; text_elements: TextElement[] }
   | { type: "image"; url: string }

package/bundle/src/utils/providers/common/schema-validation.test.ts

@@ -2,6 +2,7 @@ import { Buffer } from "node:buffer";
 
 import { describe, expect, it, vi } from "vitest";
 
+import { type JsonObject } from "./provider-types";
 import {
   ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES,
   CALLER_SCHEMA_LIMITS,
@@ -116,7 +117,10 @@ describe("caller schema validation", () => {
   });
 
   it("rejects non-serializable direct dispatch schemas", () => {
-    expect(() => serializeAndValidateDispatchSchema(() => {}, "anthropic")).toThrow(
+    const cyclic: JsonObject = { type: "object" };
+    cyclic.self = cyclic;
+
+    expect(() => serializeAndValidateDispatchSchema(cyclic, "anthropic")).toThrow(
       "dispatch schema must be JSON-serializable",
     );
   });

package/bundle/src/utils/providers/common/schema-validation.ts

@@ -1,6 +1,8 @@
 import { Buffer } from "node:buffer";
 
-import { type JsonValue } from "./provider-types";
+import { z } from "zod";
+
+import { isJsonObject, type JsonValue } from "./provider-types";
 
 /**
  * Caller-provided schemas are serialized, copied, and recursively normalized before dispatch.
@@ -43,38 +45,45 @@ export function parseAndValidateCallerSchemas(input: CallerSchemasInput): JsonVa
     nodes: 0,
     schemas: 0,
   };
+
   let outputSchema: JsonValue | undefined;
 
   if (input.jsonSchema !== undefined) {
     addUtf8Bytes(Buffer.byteLength(input.jsonSchema, "utf8"), "jsonSchema", state);
 
-    let parsed: unknown;
+    let parsed: JsonValue;
+
     try {
+      // JSON.parse without a reviver yields only JSON values.
       parsed = JSON.parse(input.jsonSchema);
     } catch {
       throw new CallerSchemaValidationError("jsonSchema must contain valid JSON");
     }
 
-    if (!isRecord(parsed) || parsed.type !== "object") {
+    if (!isJsonObject(parsed) || parsed.type !== "object") {
       throw new CallerSchemaValidationError('jsonSchema top-level type must be "object"');
     }
 
-    addComplexity(parsed, "jsonSchema", state);
+    complexityWalk("jsonSchema", state, false).parse(parsed);
     state.schemas += 1;
-    outputSchema = parsed as JsonValue;
+    outputSchema = parsed;
   }
 
   for (const [index, tool] of (input.tools ?? []).entries()) {
     addToolMetadataUtf8Bytes(tool, index, state);
 
     const path = `tools[${index}].inputSchema`;
-    addComplexity(tool.inputSchema, path, state, true);
+    complexityWalk(path, state, true).parse(tool.inputSchema);
 
-    const serialized = stringifyJsonOrThrow(tool.inputSchema, path);
+    const serialized = callerJsonText.safeParse(tool.inputSchema);
+
+    if (!serialized.success) {
+      throw new CallerSchemaValidationError(`${path} must be JSON-serializable`);
+    }
 
     // buildToolCallSchema embeds this serialization inside another JSON string. Charge the
     // escaped outer-string representation before that composed description is materialized.
-    addUtf8Bytes(jsonStringContentUtf8ByteUpperBound(serialized), path, state);
+    addUtf8Bytes(jsonStringContentUtf8ByteUpperBound(serialized.data), path, state);
     state.schemas += 1;
   }
 
@@ -82,7 +91,7 @@ export function parseAndValidateCallerSchemas(input: CallerSchemasInput): JsonVa
 }
 
 export function serializeAndValidateDispatchSchema(
-  schema: unknown,
+  schema: JsonValue | undefined,
   provider?: string,
 ): string | undefined {
   if (schema === undefined) return undefined;
@@ -90,11 +99,13 @@ export function serializeAndValidateDispatchSchema(
   const serialized = stringifyJsonOrThrow(schema, "dispatch schema");
 
   const byteLength = Buffer.byteLength(serialized, "utf8");
+
   if (byteLength > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
     throw new CallerSchemaValidationError(
       `dispatch schema exceeds UTF-8 byte limit of ${CALLER_SCHEMA_LIMITS.maxUtf8Bytes}`,
     );
   }
+
   if (provider === "anthropic") {
     assertAnthropicSchemaArgvSize(serialized);
   }
@@ -110,21 +121,47 @@ export function assertAnthropicSchemaArgvSize(jsonSchema: string): void {
   }
 }
 
-function stringifyJsonOrThrow(value: unknown, subject: string): string {
+/**
+ * Decodes an opaque caller value (QgridTool.inputSchema is z.unknown() at the API boundary) into
+ * its JSON text. Cycles, BigInt, and values with no JSON form (bare undefined, functions) fail.
+ */
+const callerJsonText = z.unknown().transform((value, context): string => {
   let serialized: string | undefined;
+
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    serialized = undefined;
+  }
+
+  if (serialized === undefined) {
+    context.addIssue({ code: "custom", message: "value is not JSON-serializable" });
+
+    return z.NEVER;
+  }
+
+  return serialized;
+});
+
+function stringifyJsonOrThrow(value: JsonValue, subject: string): string {
+  let serialized: string | undefined;
+
   try {
     serialized = JSON.stringify(value);
   } catch {
     throw new CallerSchemaValidationError(`${subject} must be JSON-serializable`);
   }
+
   if (serialized === undefined) {
     throw new CallerSchemaValidationError(`${subject} must be JSON-serializable`);
   }
+
   return serialized;
 }
 
 function addUtf8Bytes(byteLength: number, path: string, state: ComplexityState): void {
   state.utf8Bytes += byteLength;
+
   if (state.utf8Bytes > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
     throwLimitError(path, "UTF-8 byte", CALLER_SCHEMA_LIMITS.maxUtf8Bytes, state);
   }
@@ -162,6 +199,7 @@ function addToolMetadataUtf8Bytes(
     jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_NAME_SEPARATOR) +
     jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_INPUT_SCHEMA_PREFIX) +
     (index === 0 ? 0 : jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_ENTRY_SEPARATOR) + 1);
+
   addUtf8Bytes(framingBytes, toolPath, state);
 }
 
@@ -181,12 +219,15 @@ function jsonStringContentUtf8ByteUpperBound(value: string): number {
       bytes += 2;
       continue;
     }
+
     if (codeUnit <= 0x1f) {
       bytes += 6;
       continue;
     }
+
     if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
       const nextCodeUnit = value.charCodeAt(index + 1);
+
       if (nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff) {
         bytes += 4;
         index += 1;
@@ -194,8 +235,10 @@ function jsonStringContentUtf8ByteUpperBound(value: string): number {
         // Well-formed JSON.stringify escapes lone surrogates as `\uXXXX`.
         bytes += 6;
       }
+
       continue;
     }
+
     if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
       bytes += 6;
       continue;
@@ -207,60 +250,87 @@ function jsonStringContentUtf8ByteUpperBound(value: string): number {
   return bytes;
 }
 
-function addComplexity(
-  root: unknown,
-  path: string,
-  state: ComplexityState,
-  precheckUtf8Bytes = false,
-): void {
-  const rawUtf8Bytes = { value: 0 };
-  if (precheckUtf8Bytes && typeof root === "string") {
-    addRawUtf8LowerBound(root, path, state, rawUtf8Bytes);
-  }
-  addNode(path, state);
-  if (root === null || typeof root !== "object") return;
+/**
+ * Bounded, iterative walk over a caller schema, run before anything materializes its
+ * serialization. Values are read one at a time, in key order, so a limit stops the walk before
+ * later values (including getters) are touched. That rules out decoding each value with a schema
+ * first; nodes are classified by identity instead: Object(value) === value holds exactly for
+ * objects, arrays, and functions.
+ */
+function complexityWalk(path: string, state: ComplexityState, precheckUtf8Bytes: boolean) {
+  return z.unknown().transform((root): void => {
+    const rawUtf8Bytes = { value: 0 };
+
+    if (precheckUtf8Bytes && isPrimitiveText(root)) {
+      addRawUtf8LowerBound(root, path, state, rawUtf8Bytes);
+    }
+
+    addNode(path, state);
+
+    if (root === null || root === undefined || Object(root) !== root) return;
+
+    const rootObject: object = Object(root);
+    const stack: Array<{ value: object; depth: number }> = [{ value: rootObject, depth: 0 }];
+
+    while (stack.length > 0) {
+      const current = stack.pop()!;
 
-  const stack: Array<{ value: Record<string, unknown> | unknown[]; depth: number }> = [
-    { value: root as Record<string, unknown> | unknown[], depth: 0 },
-  ];
+      if (Array.isArray(current.value)) {
+        for (let index = 0; index < current.value.length; index += 1) {
+          const depth = current.depth + 1;
+          assertDepthWithinLimit(depth, path);
+          addNode(path, state);
+
+          const child: unknown = current.value[index];
+
+          if (precheckUtf8Bytes && isPrimitiveText(child)) {
+            addRawUtf8LowerBound(child, path, state, rawUtf8Bytes);
+          }
+
+          if (child !== null && child !== undefined && Object(child) === child) {
+            stack.push({ value: Object(child), depth });
+          }
+        }
+
+        continue;
+      }
+
+      for (const key in current.value) {
+        if (!Object.hasOwn(current.value, key)) continue;
+
+        if (precheckUtf8Bytes) {
+          addRawUtf8LowerBound(key, path, state, rawUtf8Bytes);
+        }
 
-  while (stack.length > 0) {
-    const current = stack.pop()!;
-    if (Array.isArray(current.value)) {
-      for (let index = 0; index < current.value.length; index += 1) {
         const depth = current.depth + 1;
         assertDepthWithinLimit(depth, path);
         addNode(path, state);
 
-        const child = current.value[index];
-        if (precheckUtf8Bytes && typeof child === "string") {
+        // Same read as current.value[key] for an own property: data value, or the getter's result.
+        const descriptor = Object.getOwnPropertyDescriptor(current.value, key);
+
+        const child: unknown = descriptor?.get
+          ? descriptor.get.call(current.value)
+          : descriptor?.value;
+
+        if (precheckUtf8Bytes && isPrimitiveText(child)) {
           addRawUtf8LowerBound(child, path, state, rawUtf8Bytes);
         }
-        if (child !== null && typeof child === "object") {
-          stack.push({ value: child as Record<string, unknown> | unknown[], depth });
+
+        if (child !== null && child !== undefined && Object(child) === child) {
+          stack.push({ value: Object(child), depth });
         }
       }
-      continue;
     }
+  });
+}
 
-    for (const key in current.value) {
-      if (!Object.hasOwn(current.value, key)) continue;
-      if (precheckUtf8Bytes) {
-        addRawUtf8LowerBound(key, path, state, rawUtf8Bytes);
-      }
-      const depth = current.depth + 1;
-      assertDepthWithinLimit(depth, path);
-      addNode(path, state);
-
-      const child = current.value[key];
-      if (precheckUtf8Bytes && typeof child === "string") {
-        addRawUtf8LowerBound(child, path, state, rawUtf8Bytes);
-      }
-      if (child !== null && typeof child === "object") {
-        stack.push({ value: child as Record<string, unknown> | unknown[], depth });
-      }
-    }
-  }
+/**
+ * String test for the bounded walk. A failed zod parse builds a ZodError (which serializes the
+ * input), so the walk uses identity: a primitive whose String() form is itself is a string.
+ */
+function isPrimitiveText(value: unknown): value is string {
+  return Object(value) !== value && String(value) === value;
 }
 
 function addRawUtf8LowerBound(
@@ -270,6 +340,7 @@ function addRawUtf8LowerBound(
   rawUtf8Bytes: { value: number },
 ): void {
   rawUtf8Bytes.value += Buffer.byteLength(value, "utf8");
+
   if (state.utf8Bytes + rawUtf8Bytes.value > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
     throwLimitError(path, "UTF-8 byte", CALLER_SCHEMA_LIMITS.maxUtf8Bytes, state);
   }
@@ -285,6 +356,7 @@ function assertDepthWithinLimit(depth: number, path: string): void {
 
 function addNode(path: string, state: ComplexityState): void {
   state.nodes += 1;
+
   if (state.nodes > CALLER_SCHEMA_LIMITS.maxNodes) {
     throwLimitError(path, "node", CALLER_SCHEMA_LIMITS.maxNodes, state);
   }
@@ -302,7 +374,3 @@ function throwLimitError(
       : `caller schemas exceed aggregate ${kind} limit of ${limit}`,
   );
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}

package/bundle/src/utils/providers/common/smooth-weighted-round-robin.ts

@@ -6,6 +6,7 @@ export class SmoothWeightedRoundRobin {
     if (!Number.isInteger(weight) || weight < 1 || weight > 100) {
       throw new RangeError("weight must be an integer between 1 and 100");
     }
+
     if (this.weights.get(tokenId) === weight) return;
     this.weights.set(tokenId, weight);
     this.resetScores();
@@ -25,6 +26,7 @@ export class SmoothWeightedRoundRobin {
     const candidates = [...eligibleTokenIds]
       .filter((tokenId) => this.weights.has(tokenId))
       .toSorted((a, b) => a - b);
+
     if (candidates.length === 0) return null;
 
     let selected = candidates[0]!;
@@ -36,6 +38,7 @@ export class SmoothWeightedRoundRobin {
       totalWeight += weight;
       const score = (this.currentScores.get(tokenId) ?? 0) + weight;
       this.currentScores.set(tokenId, score);
+
       if (score > selectedScore) {
         selected = tokenId;
         selectedScore = score;
@@ -43,6 +46,7 @@ export class SmoothWeightedRoundRobin {
     });
 
     this.currentScores.set(selected, selectedScore - totalWeight);
+
     return selected;
   }
 }