@cartanova/qgrid-ai-sdk 2.3.7 → 2.3.9

package/README.ko.md

@@ -0,0 +1,303 @@
+# @cartanova/qgrid-ai-sdk
+
+[English](./README.md) · **한국어**
+
+AI SDK v6 custom `LanguageModelV3` provider for [qgrid](https://github.com/cartanova-ai/Qgrid).
+
+**기존 AI SDK 코드 변경 없이, `model` 한 줄만 바꾸면 구독 토큰 풀링(토큰 N개 × worker 병렬 처리) + request log 대시보드를 사용할 수 있습니다.**
+
+```diff
+ import { generateText } from "ai";
+-import { openai } from "@ai-sdk/openai";
++import { qgrid } from "@cartanova/qgrid-ai-sdk";
+
+ const { text } = await generateText({
+-  model: openai("gpt-5.4-mini"),
++  model: qgrid("openai/gpt-5.4-mini"),
+   prompt: "서울 날씨 알려줘",
+ });
+```
+
+이미 다른 provider(google, openai 등)를 직접 사용하고 있다면, **logger 옵션 한 줄**만 추가하면 에이전트의 매 step(generate, tool-call, reasoning)을 qgrid 대시보드에서 확인할 수 있습니다.
+
+```diff
+ const { text } = await generateText({
+   model: google("gemini-3-flash"),
+   prompt: "복잡한 질문",
++  experimental_telemetry: createQgridLogger({ serverUrl: "http://localhost:44900" }),
+ });
+```
+
+## 설치
+
+```bash
+pnpm add @cartanova/qgrid-ai-sdk
+```
+
+Peer dependencies: `ai@^6.0.0`, `@ai-sdk/provider@^3.0.0`
+
+## 빠른 시작
+
+```typescript
+import { generateText } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: "서울 날씨 알려줘",
+});
+```
+
+qgrid 서버(`http://localhost:44900`)가 실행 중이어야 합니다.
+
+## 사용법
+> 들어가기전에: 모든 클라이언트 사용법은 [AI-SDK](https://ai-sdk.dev/docs/ai-sdk-core)와 동일합니다.
+
+### 텍스트 생성
+
+```typescript
+import { generateText } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  system: "당신은 학술 논문 요약가입니다.",
+  prompt: paperText,
+});
+```
+
+### 구조화 응답 (Structured Output)
+> [AI-SDK structured output guide를 참조하세요](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data)
+
+```typescript
+import { generateText, Output } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+import { z } from "zod";
+
+const { output } = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  system: "논문 메타데이터를 추출해주세요.",
+  prompt: paperText,
+  output: Output.object({
+    schema: z.object({
+      title: z.string(),
+      authors: z.array(z.string()),
+      keyFindings: z.array(z.string()),
+    }),
+  }),
+});
+
+console.log(output.title, output.authors);
+```
+
+top-level이 `object`인 schema는 서버 structured output으로 전달되어 강제됩니다.
+top-level이 `object`가 아니면 (예: array) AI SDK 클라이언트 파싱으로 fallback되며 경고 로그가 출력됩니다.
+
+> **Anthropic 모델 주의:** OpenAI/codex structured output은 디코딩 단계에서 schema를 강제(constrained decoding)하므로 이 부류 실패가 거의 없지만, Claude Code의 `--json-schema`는 StructuredOutput tool + 사후 검증 방식이라 복잡한 schema는 모델이 준수하지 못할 수 있습니다. qgrid는 Claude Code의 내부 재시도를 기본 차단하고(`MAX_STRUCTURED_OUTPUT_RETRIES=1` = 1회 시도, 1 미만 값은 1로 클램프) 검증 실패 시 깨진 JSON 대신 명시적 에러를 반환합니다. 서버 환경변수로 값을 올려 재시도를 허용할 수 있지만, 재시도 시 누적되는 rejected 출력이 스트리밍 경로의 AI SDK 파싱을 깨뜨릴 수 있어 기본값 유지를 권장합니다.
+
+### 스트리밍
+
+```typescript
+import { streamText } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+
+const { textStream } = streamText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: "TypeScript의 장점을 설명해줘",
+});
+
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Tool Calling
+
+```typescript
+import { generateText, tool } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+import { z } from "zod";
+
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: "서울 날씨 알려줘",
+  tools: {
+    getWeather: tool({
+      description: "도시의 현재 날씨 조회",
+      parameters: z.object({ city: z.string() }),
+      execute: async ({ city }) => {
+        return { temperature: 22, condition: "맑음" };
+      },
+    }),
+  },
+});
+```
+
+tool-call은 qgrid 서버의 structured output emulation으로 동작합니다.
+AI SDK가 tool 실행을 관리하고, qgrid는 각 턴의 LLM 호출만 담당합니다.
+
+### Provider Options
+
+qgrid 전용 옵션은 전부 `providerOptions.qgrid` 네임스페이스로 전달합니다. (`providerOptions.openai`가 아닙니다)
+
+```typescript
+import { generateText } from "ai";
+import { qgrid, type QgridProviderOptions } from "@cartanova/qgrid-ai-sdk";
+
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "복잡한 문제를 분석해줘",
+  providerOptions: {
+    qgrid: {
+      effort: "high",
+      reasoningSummary: "concise",
+      verbosity: "medium",
+    } satisfies QgridProviderOptions,
+  },
+});
+```
+
+| 옵션 | 값 | 적용 범위 | 설명 |
+|---|---|---|---|
+| `sessionKey` | `string` | OpenAI 전용 | 멀티턴 대화 식별자. 같은 key는 같은 codex thread로 라우팅되어 prompt cache 적중 ([아래](#멀티턴-prompt-cache-sessionkey) 참조) |
+| `effort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` | 공통 | reasoning 모델의 추론 깊이. 기본값은 config의 `defaultEffort` (`"low"`) |
+| `verbosity` | `"low"` \| `"medium"` \| `"high"` | OpenAI 전용 | 응답 텍스트의 상세도 |
+| `reasoningSummary` | `"auto"` \| `"concise"` \| `"detailed"` \| `"none"` | OpenAI 전용 | 추론 요약 출력 방식 |
+| `serviceTier` | `string` | OpenAI 전용 | OpenAI/codex service tier |
+| `imageGeneration` | `boolean` | OpenAI 전용, non-stream | codex 내장 `image_generation` tool 활성화 ([아래](#image-generation) 참조) |
+| `imageGenerationOptions` | `{ quality?, size? }` | OpenAI 전용 | 이미지 품질/크기 힌트. `quality: "low" \| "medium" \| "high"`, `size: "1024x1024" \| "1024x1536" \| "1536x1024"` (기본: `medium` / `1536x1024`) |
+| `fallbackModels` | `string[]` | 예약 | 향후 서버 fallback routing용 예약 필드. 현재 동작하지 않음 |
+
+### 멀티턴 prompt cache (sessionKey)
+
+멀티턴 대화에서 `sessionKey`로 호출자의 도메인 ID(게임 세션 ID, 채팅방 ID 등) 하나만 넘기면, provider가 같은 대화를 같은 codex thread로 라우팅하여 prompt cache를 적중시킵니다. thread 좌표의 발급/보관/회송은 provider 내부에서 처리하므로 호출자는 key만 넘기면 됩니다.
+
+```typescript
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: nextTurnPrompt,
+  providerOptions: { qgrid: { sessionKey: "game-session-123" } },
+});
+```
+
+- thread는 idle 10분 후 만료됩니다. 만료되거나 worker가 재시작되면 자동으로 cold thread로 시작하므로 요청이 실패하지는 않습니다.
+- `anthropic/*` 모델에서는 무시됩니다 (Claude Code는 요청마다 fresh process를 띄우므로 thread reuse가 없음).
+- 서버에서 `QGRID_OPENAI_THREAD_REUSE=false`로 비활성화할 수 있습니다.
+
+### Image Generation
+
+OpenAI/codex 경로 전용, `generateText` 전용입니다. 해당 요청에만 codex 내장 `image_generation` tool을 켜고, 결과 이미지를 AI SDK `files`로 받습니다.
+
+```typescript
+const result = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "우주를 나는 고래 일러스트",
+  providerOptions: {
+    qgrid: {
+      imageGeneration: true,
+      imageGenerationOptions: { quality: "medium", size: "1536x1024" },
+    },
+  },
+});
+
+const image = result.files[0]; // mediaType: "image/png", base64
+```
+
+- `streamText`에서는 거부됩니다 (non-stream 전용).
+- 이미지 생성 요청은 항상 cold one-shot thread로 실행되며 thread reuse 대상에서 제외됩니다.
+- 이미지 비용은 `gpt-image-2` 공개 단가표 기반 **추정치**로 request log의 `image_cost_usd`에 별도 기록됩니다 (codex가 정확한 이미지 tool 사용량을 노출하지 않음).
+
+## Telemetry Logger
+
+qgrid provider가 아닌 모델(google, openai 직접 호출)에서도 같은 request log 대시보드를 사용하려면 `createQgridLogger`를 `experimental_telemetry`에 넣으면 됩니다.
+
+```typescript
+import { generateText } from "ai";
+import { google } from "@ai-sdk/google";
+import { createQgridLogger } from "@cartanova/qgrid-ai-sdk";
+
+const { text } = await generateText({
+  model: google("gemini-3-flash"),
+  prompt: "안녕하세요",
+  experimental_telemetry: createQgridLogger({
+    serverUrl: "http://localhost:44900",
+  }),
+});
+```
+
+병렬 호출, run 분리, telemetry 활성화 등은 자동 처리됩니다.
+
+### Logger 설정
+
+```typescript
+createQgridLogger({
+  serverUrl: string;           // qgrid 서버 주소 (필수)
+  projectName?: string;        // request_logs.project_name (기본: QGRID_PROJECT_NAME 환경변수)
+  tokenName?: string;          // request_logs.token_name (기본: "external")
+  staleRunTimeoutMs?: number;  // watchdog timeout (기본: 30분 또는 AI SDK timeout + 여유시간, 0으로 비활성화)
+  onLogError?: (error: Error) => void;  // 로깅 실패 콜백
+});
+```
+
+모든 설정은 optional (serverUrl 제외). 기본값이 있으므로 `serverUrl`만 넣으면 동작합니다.
+
+### qgrid provider와 함께 사용
+
+`qgrid()` provider는 자체 lifecycle이 있으므로 logger가 자동으로 suppress됩니다. 같은 코드에서 qgrid provider와 다른 provider를 섞어 써도 이중 기록되지 않습니다.
+
+## 지원 모델
+
+```typescript
+type QgridSupportedModel =
+  // OpenAI (based on codex app-server)
+  | "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
+  | "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"
+```
+
+## 설정
+
+```typescript
+qgrid(modelId, {
+  serverUrl?: string;      // qgrid 서버 주소 (기본: QGRID_URL 환경변수 또는 http://localhost:44900)
+  defaultEffort?: string;  // effort 기본값 (기본: "low")
+  projectName?: string;    // request_logs.project_name (기본: QGRID_PROJECT_NAME 환경변수)
+});
+```
+
+여러 프로젝트/워크플로우가 한 qgrid 서버를 공유한다면 `QGRID_PROJECT_NAME`을 설정하세요. 대시보드에서 request log를 프로젝트별로 필터링하고 토큰/비용/캐시 지표를 워크로드별로 비교할 수 있습니다. config `projectName`은 특정 호출자만 다른 이름을 써야 할 때의 override 용도입니다.
+
+## 환경변수
+
+| 변수 | 설명 | 기본값 |
+|---|---|---|
+| `QGRID_URL` | qgrid 서버 주소 | `http://localhost:44900` |
+| `QGRID_PROJECT_NAME` | request log 프로젝트 이름 (provider/logger 공통) | (없음) |
+
+## 주의사항
+
+- `temperature`, `maxOutputTokens` 등 sampling 파라미터는 CLI 런타임(OpenAI: codex app-server, Anthropic: Claude Code)이 지원하지 않아 무시됩니다.
+- Structured output은 top-level `object` schema만 서버에서 강제됩니다. top-level `array`는 클라이언트 파싱 fallback.
+- `tools`와 structured output schema는 서버에서 동시에 사용할 수 없습니다. tools가 있으면 schema는 서버로 전달되지 않고 최종 텍스트를 AI SDK가 클라이언트에서 파싱합니다.
+
+## 요구사항
+
+- Node.js >= 20
+- AI SDK v6 (`ai@^6.0.0`)
+- 실행 중인 qgrid 서버

package/README.md

@@ -1,8 +1,10 @@
 # @cartanova/qgrid-ai-sdk
 
+**English** · [한국어](./README.ko.md)
+
 AI SDK v6 custom `LanguageModelV3` provider for [qgrid](https://github.com/cartanova-ai/Qgrid).
 
-**기존 AI SDK 코드 변경 없이, `model` 한 줄만 바꾸면 qgrid를 통한 구독 토큰으로 N개(토큰개수) 병렬 풀링 + request log 대시보드를 사용가능**
+**Without changing your existing AI SDK code, swap a single `model` line to get subscription-token pooling (N tokens × parallel workers) + the request log dashboard.**
 
 ```diff
  import { generateText } from "ai";
@@ -12,21 +14,21 @@ AI SDK v6 custom `LanguageModelV3` provider for [qgrid](https://github.com/carta
  const { text } = await generateText({
 -  model: openai("gpt-5.4-mini"),
 +  model: qgrid("openai/gpt-5.4-mini"),
-   prompt: "서울 날씨 알려줘",
+   prompt: "What's the weather in Seoul?",
  });
 ```
 
-이미 다른 provider(google, openai 등)를 직접 사용하고 있다면, **logger 옵션 한 줄**만 추가하면 에이전트의 매 step(generate, tool-call, reasoning)을 qgrid 대시보드에서 확인할 수 있습니다.
+If you already use another provider (google, openai, ...) directly, add **a single logger line** to see every agent step (generate, tool-call, reasoning) in the qgrid dashboard.
 
 ```diff
  const { text } = await generateText({
    model: google("gemini-3-flash"),
-   prompt: "복잡한 질문",
+   prompt: "A complex question",
 +  experimental_telemetry: createQgridLogger({ serverUrl: "http://localhost:44900" }),
  });
 ```
 
-## 설치
+## Install
 
 ```bash
 pnpm add @cartanova/qgrid-ai-sdk
@@ -34,7 +36,7 @@ pnpm add @cartanova/qgrid-ai-sdk
 
 Peer dependencies: `ai@^6.0.0`, `@ai-sdk/provider@^3.0.0`
 
-## 빠른 시작
+## Quick start
 
 ```typescript
 import { generateText } from "ai";
@@ -42,16 +44,16 @@ import { qgrid } from "@cartanova/qgrid-ai-sdk";
 
 const { text } = await generateText({
   model: qgrid("openai/gpt-5.4-mini"),
-  prompt: "서울 날씨 알려줘",
+  prompt: "What's the weather in Seoul?",
 });
 ```
 
-qgrid 서버(`http://localhost:44900`)가 실행 중이어야 합니다.
+A qgrid server (`http://localhost:44900`) must be running.
 
-## 사용법
-> 들어가기전에: 모든 클라언트 사용법은 [AI-SDK](https://ai-sdk.dev/docs/ai-sdk-core)와 동일합니다.
+## Usage
+> Before you start: all client-side usage is identical to the [AI SDK](https://ai-sdk.dev/docs/ai-sdk-core).
 
-### 텍스트 생성
+### Text generation
 
 ```typescript
 import { generateText } from "ai";
@@ -59,13 +61,13 @@ import { qgrid } from "@cartanova/qgrid-ai-sdk";
 
 const { text } = await generateText({
   model: qgrid("openai/gpt-5.4-mini"),
-  system: "당신은 학술 논문 요약가입니다.",
+  system: "You are an academic paper summarizer.",
   prompt: paperText,
 });
 ```
 
-### 구조화 응답 (Structured Output)
-> [AI-SDK structured output guide를 참조하세요](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data)
+### Structured Output
+> See the [AI SDK structured output guide](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data)
 
 ```typescript
 import { generateText, Output } from "ai";
@@ -74,7 +76,7 @@ import { z } from "zod";
 
 const { output } = await generateText({
   model: qgrid("openai/gpt-5.4"),
-  system: "논문 메타데이터를 추출해주세요.",
+  system: "Extract the paper metadata.",
   prompt: paperText,
   output: Output.object({
     schema: z.object({
@@ -88,10 +90,12 @@ const { output } = await generateText({
 console.log(output.title, output.authors);
 ```
 
-top-level이 `object`인 schema는 OpenAI structured output으로 서버에 전달됩니다 (임의로 타입 지정 시 파싱 에러)
-top-level이 AI-SDK의 가이드를 따르지않으면 AI SDK 클라이언트 파싱으로 fallback되며 경고 로그가 출력됩니다.
+Schemas with a top-level `object` are forwarded to server-side structured output and enforced.
+If the top level is not an `object` (e.g. array), the AI SDK falls back to client-side parsing and a warning is logged.
+
+> **Note for Anthropic models:** OpenAI/codex structured output constrains decoding to the schema, so this class of failure is rare there. Claude Code's `--json-schema`, however, works as a StructuredOutput tool + post-hoc validation, so the model may fail to honor a complex schema. qgrid disables Claude Code's internal retries by default (`MAX_STRUCTURED_OUTPUT_RETRIES=1` = one attempt; values below 1 are clamped to 1) and returns an explicit error on validation failure instead of broken JSON. You can raise the server env var to allow retries, but rejected attempts accumulating on the streaming path can break AI SDK parsing, so keeping the default is recommended.
 
-### 스트리밍
+### Streaming
 
 ```typescript
 import { streamText } from "ai";
@@ -99,7 +103,7 @@ import { qgrid } from "@cartanova/qgrid-ai-sdk";
 
 const { textStream } = streamText({
   model: qgrid("openai/gpt-5.4-mini"),
-  prompt: "TypeScript의 장점을 설명해줘",
+  prompt: "Explain the benefits of TypeScript",
 });
 
 for await (const chunk of textStream) {
@@ -116,54 +120,96 @@ import { z } from "zod";
 
 const { text } = await generateText({
   model: qgrid("openai/gpt-5.4-mini"),
-  prompt: "서울 날씨 알려줘",
+  prompt: "What's the weather in Seoul?",
   tools: {
     getWeather: tool({
-      description: "도시의 현재 날씨 조회",
+      description: "Get the current weather for a city",
       parameters: z.object({ city: z.string() }),
       execute: async ({ city }) => {
-        return { temperature: 22, condition: "맑음" };
+        return { temperature: 22, condition: "sunny" };
       },
     }),
   },
 });
 ```
 
-tool-call은 qgrid 서버의 structured output emulation으로 동작합니다.
-AI SDK가 tool 실행을 관리하고, qgrid는 각 턴의 LLM 호출만 담당합니다.
+Tool calls work through the qgrid server's structured output emulation.
+The AI SDK manages tool execution; qgrid handles only each turn's LLM call.
 
 ### Provider Options
 
+All qgrid-specific options go under the `providerOptions.qgrid` namespace. (Not `providerOptions.openai`.)
+
 ```typescript
 import { generateText } from "ai";
 import { qgrid, type QgridProviderOptions } from "@cartanova/qgrid-ai-sdk";
 
-const providerOptions = {
-  openai: {
-    reasoningEffort: "high",
-    reasoningSummary: "concise",
-    textVerbosity: "medium",
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "Analyze this complex problem",
+  providerOptions: {
+    qgrid: {
+      effort: "high",
+      reasoningSummary: "concise",
+      verbosity: "medium",
+    } satisfies QgridProviderOptions,
   },
-} satisfies QgridProviderOptions;
+});
+```
+
+| Option | Values | Applies to | Description |
+|---|---|---|---|
+| `sessionKey` | `string` | OpenAI only | Multi-turn conversation identifier. The same key routes to the same codex thread for prompt-cache hits (see [below](#multi-turn-prompt-cache-sessionkey)) |
+| `effort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` | both providers | Reasoning depth. Defaults to the config's `defaultEffort` (`"low"`) |
+| `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 |
+| `imageGeneration` | `boolean` | OpenAI only, non-stream | Enables codex's built-in `image_generation` tool (see [below](#image-generation)) |
+| `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 server-side fallback routing. Not functional yet |
+
+### Multi-turn prompt cache (sessionKey)
 
+For multi-turn conversations, pass a single caller-side domain ID (game session ID, chat room ID, ...) as `sessionKey` and the provider routes the same conversation to the same codex thread, hitting the prompt cache. Thread coordinate issuance/storage/replay is handled inside the provider — the caller only passes the key.
+
+```typescript
 const { text } = await generateText({
-  model: qgrid("openai/gpt-5.4"),
-  prompt: "복잡한 문제를 분석해줘",
-  providerOptions,
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: nextTurnPrompt,
+  providerOptions: { qgrid: { sessionKey: "game-session-123" } },
 });
 ```
 
-| 옵션 | 값 | 설명 |
-|---|---|---|
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` | reasoning 모델의 추론 깊이 |
-| `reasoningSummary` | `"auto"` \| `"concise"` \| `"detailed"` \| `"none"` | 추론 요약 출력 방식 (Responses API 전용) |
-| `textVerbosity` | `"low"` \| `"medium"` \| `"high"` | 응답 텍스트의 상세도 |
+- Threads expire after 10 minutes idle. On expiry or worker restart, the request automatically starts a cold thread instead of failing.
+- Ignored for `anthropic/*` models (Claude Code spawns a fresh process per request, so there is no thread reuse).
+- Can be disabled server-side with `QGRID_OPENAI_THREAD_REUSE=false`.
+
+### Image Generation
+
+OpenAI/codex route only, `generateText` only. Enables codex's built-in `image_generation` tool for that single request and returns the image through the AI SDK `files`.
+
+```typescript
+const result = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "An illustration of a whale flying through space",
+  providerOptions: {
+    qgrid: {
+      imageGeneration: true,
+      imageGenerationOptions: { quality: "medium", size: "1536x1024" },
+    },
+  },
+});
 
-codex app-server가 지원하는 옵션만 포함되어 있습니다. `temperature`, `maxOutputTokens` 등은 codex가 무시합니다.
+const image = result.files[0]; // mediaType: "image/png", base64
+```
+
+- Rejected in `streamText` (non-stream only).
+- Image-generation requests always run on a cold one-shot thread and are excluded from thread reuse.
+- The image cost is an **estimate** based on the public `gpt-image-2` price table, recorded separately as `image_cost_usd` on the request log (codex does not expose exact image-tool usage).
 
 ## Telemetry Logger
 
-qgrid provider가 아닌 모델(google, openai 직접 호출)에서도 같은 request log 대시보드를 사용하려면 `createQgridLogger`를 `experimental_telemetry`에 넣으면 됩니다.
+To use the same request log dashboard with models that don't go through the qgrid provider (direct google/openai calls), pass `createQgridLogger` to `experimental_telemetry`.
 
 ```typescript
 import { generateText } from "ai";
@@ -172,34 +218,34 @@ import { createQgridLogger } from "@cartanova/qgrid-ai-sdk";
 
 const { text } = await generateText({
   model: google("gemini-3-flash"),
-  prompt: "안녕하세요",
+  prompt: "Hello",
   experimental_telemetry: createQgridLogger({
     serverUrl: "http://localhost:44900",
   }),
 });
 ```
 
-병렬 호출, run 분리, telemetry 활성화 등은 자동 처리됩니다.
+Parallel calls, run separation, and telemetry activation are handled automatically.
 
-### Logger 설정
+### Logger configuration
 
 ```typescript
 createQgridLogger({
-  serverUrl: string;           // qgrid 서버 주소 (필수)
-  projectName?: string;        // request_logs.project_name
-  tokenName?: string;          // request_logs.token_name (기본: "external")
-  staleRunTimeoutMs?: number;  // watchdog timeout (기본: 30분, 0으로 비활성화)
-  onLogError?: (error: Error) => void;  // 로깅 실패 콜백
+  serverUrl: string;           // qgrid server address (required)
+  projectName?: string;        // request_logs.project_name (default: QGRID_PROJECT_NAME env var)
+  tokenName?: string;          // request_logs.token_name (default: "external")
+  staleRunTimeoutMs?: number;  // watchdog timeout (default: 30 min, or the AI SDK timeout plus a grace period; 0 disables)
+  onLogError?: (error: Error) => void;  // logging-failure callback
 });
 ```
 
-모든 설정은 optional (serverUrl 제외). 기본값이 있으므로 `serverUrl`만 넣으면 동작합니다.
+Everything except `serverUrl` is optional. With defaults in place, passing only `serverUrl` works.
 
-### qgrid provider와 함께 사용
+### Using alongside the qgrid provider
 
-`qgrid()` provider는 자체 lifecycle이 있으므로 logger가 자동으로 suppress됩니다. 같은 코드에서 qgrid provider와 다른 provider를 섞어 써도 이중 기록되지 않습니다.
+The `qgrid()` provider has its own lifecycle, so the logger automatically suppresses itself for qgrid calls. Mixing the qgrid provider and other providers in the same code does not double-log.
 
-## 지원 모델
+## Supported models
 
 ```typescript
 type QgridSupportedModel =
@@ -216,6 +262,7 @@ type QgridSupportedModel =
   | "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"
@@ -224,28 +271,33 @@ type QgridSupportedModel =
   | "anthropic/claude-opus-4-8"
 ```
 
-## 설정
+## Configuration
 
 ```typescript
 qgrid(modelId, {
-  serverUrl?: string;      // qgrid 서버 주소 (기본: QGRID_URL 환경변수 또는 http://localhost:44900)
-  defaultEffort?: string;  // reasoningEffort 기본값 (기본: "low")
+  serverUrl?: string;      // qgrid server address (default: QGRID_URL env var, then http://localhost:44900)
+  defaultEffort?: string;  // default effort (default: "low")
+  projectName?: string;    // request_logs.project_name (default: QGRID_PROJECT_NAME env var)
 });
 ```
 
-## 환경변수
+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
 
-| 변수 | 설명 | 기본값 |
+| Variable | Description | Default |
 |---|---|---|
-| `QGRID_URL` | qgrid 서버 주소 | `http://localhost:44900` |
+| `QGRID_URL` | qgrid server address | `http://localhost:44900` |
+| `QGRID_PROJECT_NAME` | request log project name (provider and logger) | (empty) |
 
-## 주의사항
+## Notes
 
-- `temperature`, `maxOutputTokens` 등 sampling 파라미터는 codex app-server가 지원하지 않아 무시됩니다.
-- Structured output은 top-level `object` schema만 지원합니다. top-level `array`는 클라이언트 파싱 fallback.
+- Sampling parameters such as `temperature` and `maxOutputTokens` are ignored — the CLI runtimes (OpenAI: codex app-server, Anthropic: Claude Code) do not support them.
+- Structured output is server-enforced only for top-level `object` schemas. Top-level `array` falls back to client-side parsing.
+- `tools` and a structured output schema cannot be used together on the server. When tools are present, the schema is not forwarded and the AI SDK parses the final text client-side.
 
-## 요구사항
+## Requirements
 
 - Node.js >= 20
 - AI SDK v6 (`ai@^6.0.0`)
-- 실행 중인 qgrid 서버
+- A running qgrid server

package/dist/index.d.ts

@@ -29,6 +29,20 @@ type QgridProviderOptions = {
   serviceTier?: string;
   /** @todo 향후 qgrid 서버 fallback routing에 사용할 후보 모델 목록. */
   fallbackModels?: string[];
+  /**
+   * codex 내장 image_generation tool 을 켠다. OpenAI/codex route + non-stream 전용.
+   * generateText 결과의 files 로 이미지를 받는다. streaming(streamText)에서는 거부된다.
+   */
+  imageGeneration?: boolean;
+  /**
+   * Image generation hint and cost-estimation basis. The image model is fixed
+   * to gpt-image-2; qgrid accepts supported quality/size pairs from OpenAI's
+   * public calculator table.
+   */
+  imageGenerationOptions?: {
+    quality?: "low" | "medium" | "high";
+    size?: "1024x1024" | "1024x1536" | "1536x1024";
+  };
 };
 /**
  * codex thread 좌표

package/dist/index.js

@@ -528,6 +528,8 @@ function qgrid(modelId, config) {
 			const verbosity = qgridOptions.verbosity;
 			const reasoningSummary = qgridOptions.reasoningSummary;
 			const serviceTier = qgridOptions.serviceTier;
+			const imageGeneration = qgridOptions.imageGeneration;
+			const imageGenerationOptions = qgridOptions.imageGenerationOptions;
 			const sessionKey = qgridOptions.sessionKey;
 			const reuseSessionKey = reusableSessionKey(modelId, sessionKey);
 			const rawSchema = options.responseFormat?.type === "json" ? options.responseFormat.schema : void 0;
@@ -572,7 +574,9 @@ function qgrid(modelId, config) {
 					...projectName ? { projectName } : {},
 					...logMode ? { logMode } : {},
 					...runContext ? { runContext } : {},
-					...toolResultsPayload ? { toolResults: toolResultsPayload } : {}
+					...toolResultsPayload ? { toolResults: toolResultsPayload } : {},
+					...imageGeneration ? { imageGeneration } : {},
+					...imageGenerationOptions ? { imageGenerationOptions } : {}
 				} }),
 				signal: options.abortSignal
 			}).then(async (res) => {
@@ -592,7 +596,12 @@ function qgrid(modelId, config) {
 					type: "text",
 					text: item.text
 				});
-				else content.push({
+				else if (item.type === "image") content.push({
+					type: "file",
+					mediaType: "image/png",
+					data: item.data
+				});
+				else if (item.type === "tool-call") content.push({
 					type: "tool-call",
 					toolCallId: item.toolCallId,
 					toolName: item.toolName,
@@ -606,6 +615,7 @@ function qgrid(modelId, config) {
 				type: "text",
 				text: data.text
 			});
+			if (imageGeneration && !content.some((c) => c.type === "file")) throw new Error("qgrid: imageGeneration was requested but the response contained no image — the server may be an older version that does not support image generation.");
 			if (data.runContext && finishReason.unified === "tool-calls") clientRun = {
 				runContext: data.runContext,
 				pendingToolCallIds: new Set(content.filter((c) => c.type === "tool-call").map((c) => c.toolCallId))
@@ -635,6 +645,7 @@ function qgrid(modelId, config) {
 			const verbosity = qgridOptions.verbosity;
 			const reasoningSummary = qgridOptions.reasoningSummary;
 			const serviceTier = qgridOptions.serviceTier;
+			if (qgridOptions.imageGeneration) throw new Error("qgrid: imageGeneration is not supported with streamText — use generateText instead.");
 			const sessionKey = qgridOptions.sessionKey;
 			const reuseSessionKey = reusableSessionKey(modelId, sessionKey);
 			const rawSchema = options.responseFormat?.type === "json" ? options.responseFormat.schema : void 0;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@cartanova/qgrid-ai-sdk",
-  "version": "2.3.7",
+  "version": "2.3.9",
   "description": "AI SDK LanguageModelV3 provider for qgrid",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.ko.md"
   ],
   "type": "module",
   "main": "dist/index.js",