@cartanova/qgrid-ai-sdk 2.9.1 → 2.9.2

package/README.ko.md

@@ -204,7 +204,8 @@ const { text } = await generateText({
 | `tokenName` | provider prefix를 포함한 토큰 이름 | 공통 | `anthropic/yds`처럼 활성 토큰 하나를 엄격히 지정. prefix는 model provider와 같아야 하며 빈 값·누락·inactive·quota 초과 시 다른 토큰으로 fallback하지 않음 |
 | `logger` | `boolean` | 공통 | qgrid request log 저장 여부. 기본값은 `true`. `false`로 설정해도 client tool 실행과 multi-step 연결은 계속 동작 |
 | `sessionKey` | `string` | OpenAI 전용 | 전체 history 재전송 시 불투명 prompt-cache affinity를 파생하는 멀티턴 대화 식별자 ([아래](#멀티턴-prompt-cache-sessionkey) 참조) |
-| `effort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | 공통 (지원 값은 모델별 상이, 예: `"max"`는 GPT-5.6+) | reasoning 모델의 추론 깊이. 기본값은 config의 `defaultEffort` (`"low"`) |
+| `effort` | OpenAI: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` \| `"ultra"` | OpenAI 전용 (`QgridOpenAIProviderOptions`) | ChatGPT 구독 Codex 경로의 reasoning 깊이. `"max"`/`"ultra"`는 GPT-5.6 계열만 지원하며, 모델이 지원하지 않는 값은 서버가 조용히 무시하고 백엔드 기본값을 적용. 공개 OpenAI API의 `"none"`/`"minimal"`은 이 경로에 없음 |
+| `effort` | Anthropic: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | Anthropic 전용 (`QgridAnthropicProviderOptions`) | Claude Code `--effort` 허용값. 집합 밖의 값은 서버가 조용히 무시하고 qgrid 기본(`"low"`)을 적용. 모델별 상한(예: Sonnet 4.6은 `"xhigh"` 없음)은 Claude Code가 처리 |
 | `verbosity` | `"low"` \| `"medium"` \| `"high"` | OpenAI 전용 | 응답 텍스트의 상세도 |
 | `reasoningSummary` | `"auto"` \| `"concise"` \| `"detailed"` \| `"none"` | OpenAI 전용 | 추론 요약 출력 방식 |
 | `serviceTier` | `string` | OpenAI 전용 | OpenAI/codex service tier |
@@ -414,11 +415,13 @@ Claude Code는 Fable의 safety refusal을 다른 Opus 모델로 자동 재시도
 ```typescript
 qgrid(modelId, {
   serverUrl?: string;      // qgrid 서버 주소 (기본: QGRID_URL 환경변수 또는 http://localhost:44900)
-  defaultEffort?: string;  // effort 기본값 (기본: "low")
+  defaultEffort?: ...;     // effort 기본값 (기본: "low"). 모델 ID prefix에 따라 provider 어휘로 타입 검사
   projectName?: string;    // request_logs.project_name (기본: QGRID_PROJECT_NAME 환경변수)
 });
 ```
 
+`qgrid()`는 모델 ID prefix로 오버로드되어 `openai/*`에는 `QgridOpenAIEffort`, `anthropic/*`에는 `QgridAnthropicEffort`가 `defaultEffort` 타입으로 적용됩니다. `providerOptions.qgrid`는 AI SDK 타입이 모델과 연결해 주지 않으므로 `QgridProviderOptions`는 `QgridOpenAIProviderOptions | QgridAnthropicProviderOptions`의 union이며, provider를 아는 호출자는 provider별 타입에 `satisfies`를 쓰는 편이 정확합니다.
+
 여러 프로젝트/워크플로우가 한 qgrid 서버를 공유한다면 `QGRID_PROJECT_NAME`을 설정하세요. 대시보드에서 request log를 프로젝트별로 필터링하고 토큰/비용/캐시 지표를 워크로드별로 비교할 수 있습니다. config `projectName`은 특정 호출자만 다른 이름을 써야 할 때의 override 용도입니다.
 
 ## 환경변수

package/README.md

@@ -213,7 +213,8 @@ const { text } = await generateText({
 | `tokenName` | provider-prefixed token name | both providers | Strictly targets one active token, such as `anthropic/yds`. The prefix must match the model provider; empty, missing, inactive, or over-threshold targets fail without fallback |
 | `logger` | `boolean` | both providers | qgrid request logging. Defaults to `true`; `false` disables request-log persistence for this generation without disabling client tools or multi-step continuation |
 | `sessionKey` | `string` | OpenAI only | Multi-turn conversation identifier used to derive opaque prompt-cache affinity while replaying full history (see [below](#multi-turn-prompt-cache-sessionkey)) |
-| `effort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | both providers (supported values are model-dependent, e.g. `"max"` is GPT-5.6+) | Reasoning depth. Defaults to the config's `defaultEffort` (`"low"`) |
+| `effort` | OpenAI: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` \| `"ultra"` | OpenAI only (`QgridOpenAIProviderOptions`) | Reasoning depth on the ChatGPT-subscription Codex route. `"max"`/`"ultra"` exist on GPT-5.6 models only; a value the model does not support is silently ignored by the server and the backend default applies. The public OpenAI API's `"none"`/`"minimal"` do not exist on this route |
+| `effort` | Anthropic: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | Anthropic only (`QgridAnthropicProviderOptions`) | Claude Code `--effort` levels. Values outside this set are silently ignored and qgrid's default (`"low"`) applies; per-model limits (for example no `"xhigh"` on Sonnet 4.6) are handled by Claude Code |
 | `verbosity` | `"low"` \| `"medium"` \| `"high"` | OpenAI only | Response text verbosity |
 | `reasoningSummary` | `"auto"` \| `"concise"` \| `"detailed"` \| `"none"` | OpenAI only | Reasoning summary output mode |
 | `serviceTier` | `string` | OpenAI only | OpenAI/codex service tier |
@@ -424,11 +425,13 @@ Claude Code may automatically retry a Fable safety refusal on another Opus model
 ```typescript
 qgrid(modelId, {
   serverUrl?: string;      // qgrid server address (default: QGRID_URL env var, then http://localhost:44900)
-  defaultEffort?: string;  // default effort (default: "low")
+  defaultEffort?: ...;     // default effort (default: "low"); typed per provider from the model id prefix
   projectName?: string;    // request_logs.project_name (default: QGRID_PROJECT_NAME env var)
 });
 ```
 
+`qgrid()` is overloaded on the model id prefix, so `defaultEffort` accepts `QgridOpenAIEffort` for `openai/*` models and `QgridAnthropicEffort` for `anthropic/*` models. `providerOptions.qgrid` cannot be linked to the model by the AI SDK types, so `QgridProviderOptions` is the union of `QgridOpenAIProviderOptions` and `QgridAnthropicProviderOptions`; use the provider-specific type with `satisfies` when you know the provider.
+
 If multiple projects/workflows share one qgrid server, set `QGRID_PROJECT_NAME`. It lets you filter request logs by project in the dashboard and compare token/cost/cache metrics per workload. The config-level `projectName` is an override for callers that need a different label.
 
 ## Environment variables

package/dist/index.d.ts

@@ -1,17 +1,33 @@
 import { LanguageModelV3 } from "@ai-sdk/provider";
 import { TelemetrySettings } from "ai";
 //#region src/index.types.d.ts
-type QgridProviderConfig = {
+/**
+ * OpenAI 경로(ChatGPT 구독 Codex 백엔드)의 reasoning effort. 백엔드 모델 카탈로그의
+ * supported_reasoning_levels 합집합이며, 공개 OpenAI API 의 `none`/`minimal` 은 이 경로에 없다.
+ * `max`/`ultra` 는 GPT-5.6 계열만 받고, 모델이 지원하지 않는 값은 서버가 조용히 무시한다.
+ */
+type QgridOpenAIEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+/**
+ * Anthropic 경로(Claude Code `--effort`)의 reasoning effort. 모델별 상한(예: Sonnet 4.6 은 `xhigh`
+ * 없음)은 Claude Code 가 처리하고, 이 집합 밖의 값은 서버가 조용히 무시한다.
+ */
+type QgridAnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";
+type QgridOpenAIModel = Extract<QgridSupportedModel, `openai/${string}`>;
+type QgridAnthropicModel = Extract<QgridSupportedModel, `anthropic/${string}`>;
+type QgridCommonProviderConfig = {
   serverUrl?: string;
-  defaultEffort?: string;
   /** request_logs.project_name. default: process.env.QGRID_PROJECT_NAME */
   projectName?: string;
 };
-/**
- * qgrid provider options.
- * providerOptions.qgrid 로 전달한다.
- */
-type QgridProviderOptions = {
+type QgridOpenAIProviderConfig = QgridCommonProviderConfig & {
+  defaultEffort?: QgridOpenAIEffort;
+};
+type QgridAnthropicProviderConfig = QgridCommonProviderConfig & {
+  defaultEffort?: QgridAnthropicEffort;
+};
+/** `qgrid()` 는 모델 ID prefix 로 오버로드되므로 보통 provider 별 타입이 추론된다. */
+type QgridProviderConfig = QgridOpenAIProviderConfig | QgridAnthropicProviderConfig;
+type QgridCommonProviderOptions = {
   /**
    * 이 요청을 처리할 활성 qgrid 토큰 이름. provider prefix를 포함해야 하며 다른 토큰으로 fallback하지 않는다.
    */
@@ -21,34 +37,30 @@ type QgridProviderOptions = {
    * false여도 client tool 실행과 multi-step 연결은 계속 동작한다.
    */
   logger?: boolean;
+  /**
+   * @todo 향후 qgrid 서버 fallback routing에 사용할 후보 모델 목록.
+   * Claude Code가 처리하는 Fable safety-refusal fallback과는 무관하다.
+   */
+  fallbackModels?: string[];
+};
+/** `providerOptions.qgrid` — OpenAI(Codex) 모델용. */
+type QgridOpenAIProviderOptions = QgridCommonProviderOptions & {
   /**
    * 멀티턴 프롬프트 캐시 어피니티용 대화 식별자, 호출자가 자기 도메인 ID(예: 게임 세션 ID) 하나만 넘기면
    * provider가 model+sessionKey에서 opaque cache affinity를 결정적으로 파생해 회송한다.
    * 원문 sessionKey는 서버에 전송하지 않으며 좌표는 model+sessionKey 별로 격리된다.
    */
   sessionKey?: string;
-  /** reasoning 모델의 추론 깊이. 기본값은 qgrid config의 defaultEffort. */
-  effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  /** 응답 텍스트의 상세도. OpenAI route에서만 적용된다. */
+  /** reasoning 깊이. 기본값은 qgrid config의 defaultEffort. 모델이 지원하지 않는 값은 서버가 무시한다. */
+  effort?: QgridOpenAIEffort;
+  /** 응답 텍스트의 상세도. */
   verbosity?: "low" | "medium" | "high";
-  /** reasoning 모델의 추론 요약 출력 방식. OpenAI route에서만 적용된다. */
+  /** reasoning 요약 출력 방식. */
   reasoningSummary?: "auto" | "concise" | "detailed" | "none";
-  /** OpenAI service tier. OpenAI route에서만 적용된다. */
+  /** Codex service tier. */
   serviceTier?: string;
   /**
-   * qgrid 서버의 provider 실행 제한(ms). Anthropic 경로에서는 Claude Code 프로세스 타이머로
-   * 사용되며, SDK의 non-stream 요청별 HTTP headers/body timeout은 이 값보다 60초 길게 설정된다.
-   * AI SDK 표준 timeout은 provider에 숫자를 전달하지 않고 abortSignal로 변환되므로, 서버 측
-   * 제한을 바꾸려면 이 옵션을 사용한다. 양의 정수만 허용하며 최대 30분, 기본 240초다.
-   */
-  timeoutMs?: number;
-  /**
-   * @todo 향후 qgrid 서버 fallback routing에 사용할 후보 모델 목록.
-   * Claude Code가 처리하는 Fable 5 safety-refusal fallback과는 무관하다.
-   */
-  fallbackModels?: string[];
-  /**
-   * OpenAI Responses image_generation tool 을 켠다. OpenAI route + non-stream 전용.
+   * OpenAI Responses image_generation tool 을 켠다. non-stream 전용.
    * generateText 결과의 files 로 이미지를 받는다. streaming(streamText)에서는 거부된다.
    */
   imageGeneration?: boolean;
@@ -62,6 +74,24 @@ type QgridProviderOptions = {
     size?: "1024x1024" | "1024x1536" | "1536x1024";
   };
 };
+/** `providerOptions.qgrid` — Anthropic(Claude Code) 모델용. */
+type QgridAnthropicProviderOptions = QgridCommonProviderOptions & {
+  /** reasoning 깊이. 기본값은 qgrid config의 defaultEffort. 집합 밖의 값은 서버가 무시한다. */
+  effort?: QgridAnthropicEffort;
+  /**
+   * qgrid 서버의 provider 실행 제한(ms). Claude Code 프로세스 타이머로 사용되며, SDK의 non-stream
+   * 요청별 HTTP headers/body timeout은 이 값보다 60초 길게 설정된다. AI SDK 표준 timeout은
+   * provider에 숫자를 전달하지 않고 abortSignal로 변환되므로, 서버 측 제한을 바꾸려면 이 옵션을
+   * 사용한다. 양의 정수만 허용하며 최대 30분, 기본 240초다.
+   */
+  timeoutMs?: number;
+};
+/**
+ * `providerOptions.qgrid` 의 공용 타입. AI SDK 의 providerOptions 는 모델과 연결되지 않은 JSON
+ * 레코드라 여기서는 두 provider 타입의 union 이다. provider 를 아는 호출자는
+ * `QgridOpenAIProviderOptions` / `QgridAnthropicProviderOptions` 를 직접 쓰는 편이 정확하다.
+ */
+type QgridProviderOptions = QgridOpenAIProviderOptions | QgridAnthropicProviderOptions;
 type QgridSupportedModel = "openai/gpt-5.6-sol" | "openai/gpt-5.6-terra" | "openai/gpt-5.6-luna" | "openai/gpt-5.5" | "openai/gpt-5.4" | "openai/gpt-5.2" | "openai/gpt-5.4-mini" | "openai/gpt-5.3-codex" | "openai/gpt-5.3-codex-spark" | "anthropic/claude-fable-5-1" | "anthropic/claude-fable-5" | "anthropic/claude-haiku-4-5" | "anthropic/claude-sonnet-4" | "anthropic/claude-sonnet-4-5" | "anthropic/claude-sonnet-4-6" | "anthropic/claude-sonnet-4-7" | "anthropic/claude-sonnet-5" | "anthropic/claude-opus-4" | "anthropic/claude-opus-4-1" | "anthropic/claude-opus-4-5" | "anthropic/claude-opus-4-6" | "anthropic/claude-opus-4-7" | "anthropic/claude-opus-4-8" | "anthropic/claude-opus-5";
 type QgridLoggerConfig = {
   /** qgrid 서버 주소. default: process.env.QGRID_URL, 없으면 기본값은 "http://localhost:44900" */
@@ -95,6 +125,7 @@ type QgridLoggerConfig = {
 declare function createQgridLogger(config?: QgridLoggerConfig): TelemetrySettings;
 //#endregion
 //#region src/index.d.ts
-declare function qgrid(modelId: QgridSupportedModel, config?: QgridProviderConfig): LanguageModelV3;
+declare function qgrid(modelId: QgridOpenAIModel, config?: QgridOpenAIProviderConfig): LanguageModelV3;
+declare function qgrid(modelId: QgridAnthropicModel, config?: QgridAnthropicProviderConfig): LanguageModelV3;
 //#endregion
-export { type QgridLoggerConfig, type QgridProviderOptions, type QgridSupportedModel, createQgridLogger, qgrid as default, qgrid };
+export { type QgridAnthropicEffort, type QgridAnthropicModel, type QgridAnthropicProviderConfig, type QgridAnthropicProviderOptions, type QgridLoggerConfig, type QgridOpenAIEffort, type QgridOpenAIModel, type QgridOpenAIProviderConfig, type QgridOpenAIProviderOptions, type QgridProviderConfig, type QgridProviderOptions, type QgridSupportedModel, createQgridLogger, qgrid as default, qgrid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-ai-sdk",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "description": "AI SDK LanguageModelV3 provider for qgrid",
   "repository": {
     "type": "git",