@cartanova/qgrid-cli 2.10.9 → 2.11.0

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

@@ -8,20 +8,32 @@ import { createFenceStripTransform } from "../../utils/providers/anthropic/fence
 import { getAccessToken } from "../../utils/providers/common/credentials";
 import { calculateCostUsd } from "../../utils/providers/common/model-cost";
 import {
+  type GenerateRequest,
   type GenerateResult,
+  type GenerateStreamCallbacks,
+  type MediaDispatcher,
+  type ProviderDispatcher,
   type StreamCallbacks,
+  type VoiceDispatcher,
 } from "../../utils/providers/common/provider-dispatcher";
-import { type JsonValue } from "../../utils/providers/common/provider-types";
+import {
+  isJsonObject,
+  isProviderId,
+  type JsonValue,
+  type ProviderId,
+} from "../../utils/providers/common/provider-types";
 import {
   parseAndValidateCallerSchemas,
   serializeAndValidateDispatchSchema,
 } from "../../utils/providers/common/schema-validation";
 import { strictify } from "../../utils/providers/common/strictifier";
+import { type GrokTokenStateSnapshot } from "../../utils/providers/grok/grok-dispatcher";
 import {
   ImageGenerationError,
   type OpenAIDispatcher,
 } from "../../utils/providers/openai/openai-dispatcher";
 import { type TokenSubsetA } from "../sonamu.generated";
+import { type TokenCredentials } from "../token/token.types";
 import { decideConvRouting, issueConvContext } from "./conv-routing";
 import {
   maskToken,
@@ -41,6 +53,61 @@ export type InternalQueryInput = QueryInput & {
   requirePreferredToken?: boolean;
 };
 
+// qgrid 상위가 provider 에 요구하는 실행 계약. 스트리밍은 공통 ProviderDispatcher 에 아직 없어서
+// 여기서 합친다.
+export type StreamingProviderDispatcher = ProviderDispatcher & {
+  generateStream(req: GenerateRequest, cb: GenerateStreamCallbacks): Promise<void>;
+};
+
+// TokenSubscriber 가 grok row 를 전달하는 계약. credentials 는 DB JSONB 원본이며 dispatcher 가
+// 자체 스키마로 검증한다.
+export type GrokTokenRow = {
+  id: number;
+  name: string;
+  credentials: TokenCredentials;
+  quotaThreshold: number | null;
+  weight: number;
+};
+
+export interface GrokTokenSink {
+  onTokenAdded(
+    id: number,
+    name: string,
+    credentials: TokenCredentials,
+    quotaThreshold: number | null,
+    weight: number,
+  ): void | Promise<void>;
+  onTokenUpdated(
+    id: number,
+    name: string,
+    credentials: TokenCredentials,
+    quotaThreshold: number | null,
+    weight: number,
+  ): void | Promise<void>;
+  onTokenRemoved(id: number): void | Promise<void>;
+  replaceTokens(rows: GrokTokenRow[]): void | Promise<void>;
+}
+
+/** Observability the concrete Grok dispatcher exposes beyond routing. */
+export interface GrokTokenStateSource {
+  tokenStates(): GrokTokenStateSnapshot[];
+}
+
+/** Media, voice, and token-state reporting are optional capabilities of a Grok dispatcher. */
+export type GrokProviderDispatcher = StreamingProviderDispatcher &
+  GrokTokenSink &
+  Partial<MediaDispatcher & VoiceDispatcher & GrokTokenStateSource>;
+
+export type QgridDispatcherOptions = {
+  grokDispatcher?: GrokProviderDispatcher | null;
+};
+
+const PROVIDER_LABELS: Record<ProviderId, string> = {
+  openai: "OpenAI",
+  anthropic: "Anthropic",
+  grok: "Grok",
+};
+
 export class QgridDispatcherClass {
   tokens = new Map<number, TokenSubsetA>();
 
@@ -49,23 +116,76 @@ export class QgridDispatcherClass {
   requestCounts = new Map<string, number>();
 
   subscriber: TokenSubscriber | null = null;
-  openaiDispatcher: OpenAIDispatcher | null = null;
-  anthropicDispatcher: AnthropicDispatcher | null = null;
+
+  // provider route prefix → 실행 dispatcher. 등록되지 않은 provider 는 not-ready 로 응답한다.
+  readonly dispatchers = new Map<ProviderId, StreamingProviderDispatcher>();
+  #openaiDispatcher: OpenAIDispatcher | null = null;
+  #anthropicDispatcher: AnthropicDispatcher | null = null;
+  #grokDispatcher: GrokProviderDispatcher | null = null;
 
   // HTTP가 dispatcher보다 먼저 열리므로 초기화 중과 초기화 실패를 구분한다.
-  startupState: Record<"openai" | "anthropic", ProviderStartupState> = {
+  // grok 은 bootstrap 이 붙기 전까지 상태가 없으며, 없으면 기동 중으로 본다.
+  startupState: Record<"openai" | "anthropic", ProviderStartupState> &
+    Partial<Record<"grok", ProviderStartupState>> = {
     openai: "starting",
     anthropic: "starting",
   };
 
+  constructor(options: QgridDispatcherOptions = {}) {
+    if (options.grokDispatcher) this.grokDispatcher = options.grokDispatcher;
+  }
+
+  get openaiDispatcher(): OpenAIDispatcher | null {
+    return this.#openaiDispatcher;
+  }
+
+  set openaiDispatcher(dispatcher: OpenAIDispatcher | null) {
+    this.#openaiDispatcher = dispatcher;
+    this.register("openai", dispatcher);
+  }
+
+  get anthropicDispatcher(): AnthropicDispatcher | null {
+    return this.#anthropicDispatcher;
+  }
+
+  set anthropicDispatcher(dispatcher: AnthropicDispatcher | null) {
+    this.#anthropicDispatcher = dispatcher;
+    this.register("anthropic", dispatcher);
+  }
+
+  get grokDispatcher(): GrokProviderDispatcher | null {
+    return this.#grokDispatcher;
+  }
+
+  set grokDispatcher(dispatcher: GrokProviderDispatcher | null) {
+    this.#grokDispatcher = dispatcher;
+    this.register("grok", dispatcher);
+  }
+
+  register(provider: ProviderId, dispatcher: StreamingProviderDispatcher | null): void {
+    if (dispatcher) this.dispatchers.set(provider, dispatcher);
+    else this.dispatchers.delete(provider);
+  }
+
   // 초기화 중에는 503 + Retry-After, 초기화 실패에는 500을 반환한다.
-  notReadyError(provider: "openai" | "anthropic"): Error {
-    const label = provider === "openai" ? "OpenAI" : "Anthropic";
+  notReadyError(provider: ProviderId): Error {
+    const label = PROVIDER_LABELS[provider];
+
     return this.startupState[provider] === "failed"
       ? new InternalServerErrorException(SD("qgrid.dispatcherFailed")(label))
       : new ServiceUnavailableException(SD("qgrid.dispatcherStarting")(label));
   }
 
+  // prefix 없는/미지원 prefix 는 기존대로 ProcessError, 지원 provider 의 미등록은 not-ready.
+  resolveDispatcher(input: QueryInput, provider: string | undefined): ResolvedDispatcher {
+    if (!isProviderId(provider)) throw directLlmApiFallbackNotImplemented(input);
+    const dispatcher = this.dispatchers.get(provider);
+
+    if (!dispatcher) throw this.notReadyError(provider);
+
+    return { provider, dispatcher };
+  }
+
   recordCompleted(provider: string, tokenName: string): void {
     const key = `${provider}\0${tokenName}`;
     this.requestCounts.set(key, (this.requestCounts.get(key) ?? 0) + 1);
@@ -88,55 +208,12 @@ export class QgridDispatcherClass {
     const route = parseProviderRoute(input.model);
     const outputSchema = buildAndValidateStrictOutputSchema(input, route.provider);
     const answerKind = input.jsonSchema ? ("json" as const) : ("text" as const);
+    const { provider, dispatcher } = this.resolveDispatcher(input, route.provider);
 
-    if (route.provider === "openai") {
-      if (!this.openaiDispatcher) throw this.notReadyError("openai");
-
-      const decision = decideConvRouting(input, {
-        directOpenAI: true,
-        modelNamespace: `openai/${route.model}`,
-      });
-      const result = await this.openaiDispatcher.generate({
-        model: route.model,
-        systemPrompt: input.system,
-        outputSchema,
-        stopAfterOutputMessage: input.tools?.length
-          ? (text, phase) => isToolCallEnvelope(text, input.tools!, answerKind, phase)
-          : undefined,
-        thinking: input.thinking,
-        effort: input.thinking === false ? undefined : input.effort,
-        verbosity: input.verbosity,
-        reasoningSummary: input.reasoningSummary,
-        serviceTier: input.serviceTier,
-        timeoutMs: input.timeout,
-        coldInput: decision.coldInput,
-        coldHistory: decision.coldHistory,
-        promptCacheKey: input.imageGeneration ? undefined : decision.promptCacheKey,
-        preferredTokenId:
-          input.preferredTokenId ?? (input.imageGeneration ? undefined : decision.preferredTokenId),
-        requirePreferredToken: input.requirePreferredToken,
-        abortSignal,
-        imageGeneration: input.imageGeneration,
-        imageGenerationOptions: input.imageGenerationOptions,
-      });
-      this.recordCompleted("openai", result.tokenName);
-
-      // 이미지 요청은 cold-only(R8)라 재사용 좌표를 발급하지 않는다. 좌표를 실으면
-      // sessionKey 소비자의 warm 좌표를 죽은 좌표로 덮어써 다음 텍스트 turn 이 cold 로 떨어진다.
-      const coord = input.imageGeneration
-        ? undefined
-        : issueConvContext(result.threadCoord, decision, result.threadCoord.workerId);
-
-      return applyToolCallEmulation(toEmulationResult(result, input.serviceTier), input.tools, {
-        threadCoord: coord,
-        images: result.images,
-        answerKind,
-      });
-    } else if (route.provider === "anthropic") {
-      if (!this.anthropicDispatcher) throw this.notReadyError("anthropic");
-
+    if (provider === "anthropic") {
       const decision = decideConvRouting(input);
-      const result = await this.anthropicDispatcher.generate({
+
+      const result = await dispatcher.generate({
         model: input.model,
         systemPrompt: composeSystemWithSchemaContract(input.system, input),
         thinking: input.thinking,
@@ -149,7 +226,8 @@ export class QgridDispatcherClass {
         imageGeneration: input.imageGeneration,
         imageGenerationOptions: input.imageGenerationOptions,
       });
-      this.recordCompleted("anthropic", result.tokenName);
+
+      this.recordCompleted(provider, result.tokenName);
 
       return applyToolCallEmulation(toEmulationResult(result), input.tools, {
         threadCoord: issueConvContext(result.threadCoord, decision),
@@ -157,7 +235,33 @@ export class QgridDispatcherClass {
       });
     }
 
-    throw directLlmApiFallbackNotImplemented(input);
+    const decision = decideConvRouting(input, {
+      directProvider: provider,
+      modelNamespace: `${provider}/${route.model}`,
+    });
+
+    const result = await dispatcher.generate({
+      ...buildDirectRequest(input, route.model, outputSchema, answerKind, abortSignal),
+      promptCacheKey: input.imageGeneration ? undefined : decision.promptCacheKey,
+      preferredTokenId:
+        input.preferredTokenId ?? (input.imageGeneration ? undefined : decision.preferredTokenId),
+      coldInput: decision.coldInput,
+      coldHistory: decision.coldHistory,
+    });
+
+    this.recordCompleted(provider, result.tokenName);
+
+    // 이미지 요청은 cold-only(R8)라 재사용 좌표를 발급하지 않는다. 좌표를 실으면
+    // sessionKey 소비자의 warm 좌표를 죽은 좌표로 덮어써 다음 텍스트 turn 이 cold 로 떨어진다.
+    const coord = input.imageGeneration
+      ? undefined
+      : issueConvContext(result.threadCoord, decision, result.threadCoord.workerId);
+
+    return applyToolCallEmulation(toEmulationResult(result, input.serviceTier), input.tools, {
+      threadCoord: coord,
+      images: result.images,
+      answerKind,
+    });
   }
 
   async queryStream(
@@ -168,77 +272,23 @@ export class QgridDispatcherClass {
     const route = parseProviderRoute(input.model);
     const outputSchema = buildAndValidateStrictOutputSchema(input, route.provider);
     const answerKind = input.jsonSchema ? ("json" as const) : ("text" as const);
+    const { provider, dispatcher } = this.resolveDispatcher(input, route.provider);
 
-    if (route.provider === "openai") {
-      if (!this.openaiDispatcher) throw this.notReadyError("openai");
-
-      const decision = decideConvRouting(input, {
-        directOpenAI: true,
-        modelNamespace: `openai/${route.model}`,
-      });
-      await this.openaiDispatcher.generateStream(
-        {
-          model: route.model,
-          systemPrompt: input.system,
-          outputSchema,
-          stopAfterOutputMessage: input.tools?.length
-            ? (text, phase) => isToolCallEnvelope(text, input.tools!, answerKind, phase)
-            : undefined,
-          thinking: input.thinking,
-          effort: input.thinking === false ? undefined : input.effort,
-          verbosity: input.verbosity,
-          reasoningSummary: input.reasoningSummary,
-          serviceTier: input.serviceTier,
-          timeoutMs: input.timeout,
-          coldInput: decision.coldInput,
-          coldHistory: decision.coldHistory,
-          promptCacheKey: decision.promptCacheKey,
-          preferredTokenId: input.preferredTokenId ?? decision.preferredTokenId,
-          requirePreferredToken: input.requirePreferredToken,
-          abortSignal,
-          imageGeneration: input.imageGeneration,
-          imageGenerationOptions: input.imageGenerationOptions,
-        },
-        {
-          onDelta: cb.onDelta,
-          onThreadId: cb.onThreadId,
-          onTurnId: cb.onTurnId,
-          onComplete: (turnResult) => {
-            this.recordCompleted("openai", turnResult.tokenName);
-            cb.onComplete(
-              applyToolCallEmulation(
-                toEmulationResult(turnResult, input.serviceTier),
-                input.tools,
-                {
-                  threadCoord: issueConvContext(
-                    turnResult.threadCoord,
-                    decision,
-                    turnResult.threadCoord.workerId,
-                  ),
-                  answerKind,
-                },
-              ),
-            );
-          },
-          onError: cb.onError,
-        },
-      );
-      return;
-    } else if (route.provider === "anthropic") {
-      if (!this.anthropicDispatcher) throw this.notReadyError("anthropic");
-
+    if (provider === "anthropic") {
       // 구조화 응답은 최종 텍스트와 델타 모두 코드펜스를 제거한다.
       const hasSchemaContract = input.jsonSchema !== undefined || Boolean(input.tools?.length);
       const fenceStrip = hasSchemaContract ? createFenceStripTransform() : undefined;
+
       const emitDelta = fenceStrip
         ? (text: string) => {
             const safe = fenceStrip.push(text);
+
             if (safe) cb.onDelta(safe);
           }
         : cb.onDelta;
 
       const decision = decideConvRouting(input);
-      await this.anthropicDispatcher.generateStream(
+      await dispatcher.generateStream(
         {
           model: input.model,
           systemPrompt: composeSystemWithSchemaContract(input.system, input),
@@ -256,9 +306,10 @@ export class QgridDispatcherClass {
           onDelta: emitDelta,
           onThreadId: cb.onThreadId,
           onComplete: (turnResult) => {
-            this.recordCompleted("anthropic", turnResult.tokenName);
+            this.recordCompleted(provider, turnResult.tokenName);
             // 닫는 펜스 판정 때문에 보류한 텍스트를 완료 전에 방출한다.
             const rest = fenceStrip?.flush();
+
             if (rest) cb.onDelta(rest);
 
             const issuedCoord = issueConvContext(turnResult.threadCoord, decision);
@@ -272,20 +323,98 @@ export class QgridDispatcherClass {
           onError: cb.onError,
         },
       );
+
       return;
     }
 
-    throw directLlmApiFallbackNotImplemented(input);
+    const decision = decideConvRouting(input, {
+      directProvider: provider,
+      modelNamespace: `${provider}/${route.model}`,
+    });
+
+    await dispatcher.generateStream(
+      {
+        ...buildDirectRequest(input, route.model, outputSchema, answerKind, abortSignal),
+        promptCacheKey: decision.promptCacheKey,
+        preferredTokenId: input.preferredTokenId ?? decision.preferredTokenId,
+        coldInput: decision.coldInput,
+        coldHistory: decision.coldHistory,
+      },
+      {
+        onDelta: cb.onDelta,
+        onThreadId: cb.onThreadId,
+        onTurnId: cb.onTurnId,
+        onComplete: (turnResult) => {
+          this.recordCompleted(provider, turnResult.tokenName);
+          cb.onComplete(
+            applyToolCallEmulation(toEmulationResult(turnResult, input.serviceTier), input.tools, {
+              threadCoord: issueConvContext(
+                turnResult.threadCoord,
+                decision,
+                turnResult.threadCoord.workerId,
+              ),
+              answerKind,
+            }),
+          );
+        },
+        onError: cb.onError,
+      },
+    );
   }
 }
 
-function parseProviderRoute(model: string | undefined): { provider?: string; model: string } {
+// Direct provider(OpenAI, Grok) 공통 요청 필드. cache affinity 필드는 stream 여부에 따라 호출부가 채운다.
+function buildDirectRequest(
+  input: InternalQueryInput,
+  model: string,
+  outputSchema: JsonValue | undefined,
+  answerKind: "json" | "text",
+  abortSignal: AbortSignal | undefined,
+): Omit<GenerateRequest, "coldInput" | "coldHistory" | "promptCacheKey" | "preferredTokenId"> {
+  const request: Omit<
+    GenerateRequest,
+    "coldInput" | "coldHistory" | "promptCacheKey" | "preferredTokenId"
+  > = {
+    model,
+    systemPrompt: input.system,
+    outputSchema,
+    stopAfterOutputMessage: input.tools?.length
+      ? (text, phase) => isToolCallEnvelope(text, input.tools!, answerKind, phase)
+      : undefined,
+    thinking: input.thinking,
+    effort: input.thinking === false ? undefined : input.effort,
+    verbosity: input.verbosity,
+    reasoningSummary: input.reasoningSummary,
+    serviceTier: input.serviceTier,
+    timeoutMs: input.timeout,
+    requirePreferredToken: input.requirePreferredToken,
+    abortSignal,
+    imageGeneration: input.imageGeneration,
+    imageGenerationOptions: input.imageGenerationOptions,
+  };
+
+  // Opaque namespaces; the Grok dispatcher reads `xai`, OpenAI ignores it.
+  if (input.providerOptions?.xai) {
+    request.providerOptions = { xai: { ...input.providerOptions.xai } };
+  }
+
+  return request;
+}
+
+interface ProviderRoute {
+  provider?: string;
+  model: string;
+}
+
+function parseProviderRoute(model: string | undefined): ProviderRoute {
   if (!model?.includes("/")) {
     return { model: model ?? "" };
   }
 
   const [provider, routedModel] = model.split("/", 2);
+
   if (!provider || !routedModel) throw new ProcessError("unknown model");
+
   return { provider, model: routedModel };
 }
 
@@ -301,9 +430,10 @@ export function buildStrictOutputSchema(
 ): JsonValue | undefined {
   const outputSchema = buildRawOutputSchema(input);
 
-  return outputSchema
-    ? (strictify(outputSchema as Parameters<typeof strictify>[0], { provider }) as JsonValue)
-    : undefined;
+  if (!outputSchema) return undefined;
+
+  // Boolean and other non-object schemas have nothing to tighten and pass through unchanged.
+  return isJsonObject(outputSchema) ? strictify(outputSchema, { provider }) : outputSchema;
 }
 
 export function buildAndValidateStrictOutputSchema(
@@ -314,11 +444,13 @@ export function buildAndValidateStrictOutputSchema(
   // Anthropic은 원본 스키마를 검증한 뒤 프롬프트로 전달하고, 응답 검증은 소비자에 맡긴다.
   if (provider === "anthropic") {
     parseAndValidateCallerSchemas(input);
+
     return undefined;
   }
 
   const outputSchema = buildStrictOutputSchema(input, provider);
   serializeAndValidateDispatchSchema(outputSchema, provider);
+
   return outputSchema;
 }
 
@@ -333,11 +465,12 @@ function buildRawOutputSchema(
 }
 
 export function completedDriverFromImageFailure(
-  error: unknown,
+  cause: unknown,
   serviceTier?: string,
 ): QueryOutput | undefined {
-  if (!(error instanceof ImageGenerationError) || !error.completedDriver) return undefined;
-  return applyToolCallEmulation(toEmulationResult(error.completedDriver, serviceTier), undefined, {
+  if (!(cause instanceof ImageGenerationError) || !cause.completedDriver) return undefined;
+
+  return applyToolCallEmulation(toEmulationResult(cause.completedDriver, serviceTier), undefined, {
     answerKind: "text",
   });
 }
@@ -347,8 +480,12 @@ function toEmulationResult(
   result: GenerateResult,
   serviceTier?: string,
 ): Omit<QueryOutput, "content" | "finishReason" | "runContext"> {
-  const hasProviderCost = result.costUsd !== undefined && result.costUsd > 0;
-  return {
+  // A provider that labels its own cost (Grok ticks) is authoritative even at 0; otherwise only a
+  // positive provider cost (Claude Code total_cost_usd) wins over the price table.
+  const hasProviderCost =
+    result.costUsd !== undefined && (result.costSource === "provider" || result.costUsd > 0);
+
+  const emulationResult: Omit<QueryOutput, "content" | "finishReason" | "runContext"> = {
     text: result.text,
     tokenName: result.tokenName,
     model: result.model,
@@ -379,8 +516,19 @@ function toEmulationResult(
           },
           serviceTier,
         ),
-    costSource: hasProviderCost ? "provider" : "pricing_table",
+    costSource: hasProviderCost ? (result.costSource ?? "provider") : "pricing_table",
   };
+
+  if (result.providerMetadata?.xai) {
+    emulationResult.providerMetadata = { xai: result.providerMetadata.xai };
+  }
+
+  return emulationResult;
 }
 
 export const QgridDispatcher = new QgridDispatcherClass();
+
+interface ResolvedDispatcher {
+  provider: ProviderId;
+  dispatcher: StreamingProviderDispatcher;
+}