@cartanova/qgrid-ai-sdk 2.7.9 → 2.8.0

package/README.ko.md

@@ -201,6 +201,7 @@ 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"`) |
@@ -212,6 +213,18 @@ const { text } = await generateText({
 | `imageGenerationOptions` | `{ quality?, size? }` | OpenAI 전용 | 이미지 품질/크기 힌트. `quality: "low" \| "medium" \| "high"`, `size: "1024x1024" \| "1024x1536" \| "1536x1024"` (기본: `medium` / `1536x1024`) |
 | `fallbackModels` | `string[]` | 예약 | 향후 qgrid 서버 fallback routing용 예약 필드. 현재 동작하지 않으며 Claude Code의 Fable refusal fallback과 무관 |
 
+```typescript
+await generateText({
+  model: qgrid("anthropic/claude-fable-5"),
+  prompt,
+  providerOptions: {
+    qgrid: { tokenName: "anthropic/yds" } satisfies QgridProviderOptions,
+  },
+});
+```
+
+`tokenName`은 `streamText`에서도 같은 방식으로 동작합니다.
+
 AI SDK 최상위 `timeout`은 전체 클라이언트 제한시간이며 custom provider 실행 전에
 `AbortSignal`로 변환됩니다. 따라서 그 숫자 자체는 qgrid에 전달되지 않습니다. qgrid 서버의
 Claude Code 프로세스 제한시간을 바꾸려면 `providerOptions.qgrid.timeoutMs`를 사용하세요.

package/README.md

@@ -210,6 +210,7 @@ const { text } = await generateText({
 
 | Option | Values | Applies to | Description |
 |---|---|---|---|
+| `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"`) |
@@ -221,6 +222,18 @@ const { text } = await generateText({
 | `imageGenerationOptions` | `{ quality?, size? }` | OpenAI only | Image quality/size hints. `quality: "low" \| "medium" \| "high"`, `size: "1024x1024" \| "1024x1536" \| "1536x1024"` (defaults: `medium` / `1536x1024`) |
 | `fallbackModels` | `string[]` | reserved | Reserved for future qgrid server-side fallback routing. Not functional yet and unrelated to Claude Code's Fable refusal fallback |
 
+```typescript
+await generateText({
+  model: qgrid("anthropic/claude-fable-5"),
+  prompt,
+  providerOptions: {
+    qgrid: { tokenName: "anthropic/yds" } satisfies QgridProviderOptions,
+  },
+});
+```
+
+`tokenName` works the same way with `streamText`.
+
 AI SDK's top-level `timeout` remains the overall client-side budget and is converted to an
 `AbortSignal` before the custom provider runs. It does not expose the numeric timeout to qgrid.
 Use `providerOptions.qgrid.timeoutMs` when the qgrid server's Claude Code process needs a different

package/dist/index.d.ts

@@ -12,6 +12,10 @@ type QgridProviderConfig = {
  * providerOptions.qgrid 로 전달한다.
  */
 type QgridProviderOptions = {
+  /**
+   * 이 요청을 처리할 활성 qgrid 토큰 이름. provider prefix를 포함해야 하며 다른 토큰으로 fallback하지 않는다.
+   */
+  tokenName?: string;
   /**
    * qgrid request log 저장 여부. 기본값은 true.
    * false여도 client tool 실행과 multi-step 연결은 계속 동작한다.

package/dist/index.js

@@ -1075,7 +1075,9 @@ function qgridProviderMetadata(data) {
 	} };
 }
 function getQgridProviderOptions(options) {
-	return options.providerOptions?.qgrid ?? {};
+	const qgridOptions = options.providerOptions?.qgrid ?? {};
+	if (qgridOptions.tokenName !== void 0 && qgridOptions.tokenName.trim() === "") throw new Error("qgrid: tokenName must not be empty");
+	return qgridOptions;
 }
 function toAiSdkUsage(usage) {
 	const cacheRead = usage.cache_read_input_tokens;
@@ -1150,6 +1152,7 @@ function qgrid(modelId, config) {
 			const serviceTier = qgridOptions.serviceTier;
 			const timeoutMs = qgridOptions.timeoutMs;
 			const logger = qgridOptions.logger;
+			const tokenName = qgridOptions.tokenName;
 			const imageGenerationOptions = qgridOptions.imageGenerationOptions;
 			if (imageGeneration) assertImageInputFitsJsonTransport(imageUrls);
 			const sessionKey = qgridOptions.sessionKey;
@@ -1184,6 +1187,7 @@ function qgrid(modelId, config) {
 					...projectName ? { projectName } : {},
 					...cacheAffinityKey ? { cacheAffinityKey } : {},
 					...logger === false ? { logger: false } : {},
+					...tokenName ? { tokenName } : {},
 					...runContext ? { runContext } : {},
 					...toolResultsPayload ? { toolResults: toolResultsPayload } : {},
 					...imageGeneration ? { imageGeneration } : {},
@@ -1254,6 +1258,7 @@ function qgrid(modelId, config) {
 			const serviceTier = qgridOptions.serviceTier;
 			const timeoutMs = qgridOptions.timeoutMs;
 			const logger = qgridOptions.logger;
+			const tokenName = qgridOptions.tokenName;
 			if (qgridOptions.imageGeneration) throw new Error("qgrid: imageGeneration is not supported with streamText — use generateText instead.");
 			const { prompt, system, history, droppedImageCount } = extractPromptAndHistory(options.prompt, { includeImages: false });
 			warnDroppedImages(droppedImageCount);
@@ -1287,6 +1292,7 @@ function qgrid(modelId, config) {
 					...projectName ? { projectName } : {},
 					...cacheAffinityKey ? { cacheAffinityKey } : {},
 					...logger === false ? { logger: false } : {},
+					...tokenName ? { tokenName } : {},
 					...runContext ? { runContext } : {},
 					...toolResultsPayload ? { toolResults: toolResultsPayload } : {}
 				} }),

package/package.json

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