@cartanova/qgrid-ai-sdk 2.5.3 → 2.5.4

package/README.ko.md

@@ -93,7 +93,7 @@ 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 파싱을 깨뜨릴 수 있어 기본값 유지를 권장합니다.
+> **Anthropic 모델 주의:** OpenAI/codex structured output은 디코딩 단계에서 schema를 강제(constrained decoding)하므로 이 부류 실패가 거의 없지만, Claude Code의 `--json-schema`는 `StructuredOutput` tool + 사후 검증 방식이라 복잡한 schema는 모델이 준수하지 못할 수 있습니다. qgrid는 structured streaming에만 `MAX_STRUCTURED_OUTPUT_RETRIES=1`을 주입해 1회 시도로 제한합니다(1 미만 값은 1로 클램프). non-stream `generate`에는 이 override를 주입하지 않고 Claude Code의 기본 retry 예산을 사용합니다. 각 경로의 시도 이후 검증이 실패하면 깨진 JSON 대신 명시적 에러를 반환합니다.
 
 ### 스트리밍
 
@@ -114,7 +114,7 @@ for await (const chunk of textStream) {
 ### Tool Calling
 
 ```typescript
-import { generateText, tool } from "ai";
+import { generateText, stepCountIs, tool } from "ai";
 import { qgrid } from "@cartanova/qgrid-ai-sdk";
 import { z } from "zod";
 
@@ -124,17 +124,54 @@ const { text } = await generateText({
   tools: {
     getWeather: tool({
       description: "도시의 현재 날씨 조회",
-      parameters: z.object({ city: z.string() }),
+      inputSchema: z.object({ city: z.string() }),
       execute: async ({ city }) => {
         return { temperature: 22, condition: "맑음" };
       },
     }),
   },
+  stopWhen: stepCountIs(3),
 });
 ```
 
 tool-call은 qgrid 서버의 structured output emulation으로 동작합니다.
 AI SDK가 tool 실행을 관리하고, qgrid는 각 턴의 LLM 호출만 담당합니다.
+실행 가능한 tool을 쓸 때는 제한이 있는 `stopWhen`을 지정해야 AI SDK가
+tool-call 턴 뒤에도 계속 진행해 모델의 최종 응답을 받습니다.
+
+`tools`와 `Output.object`를 함께 사용할 수도 있습니다.
+
+```typescript
+import { generateText, Output, stepCountIs, tool } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+import { z } from "zod";
+
+const { output } = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "서울 날씨를 조회해서 예보를 반환해줘.",
+  tools: {
+    getWeather: tool({
+      description: "도시의 현재 날씨 조회",
+      inputSchema: z.object({ city: z.string() }),
+      execute: async ({ city }) => ({ city, temperature: 22 }),
+    }),
+  },
+  stopWhen: stepCountIs(3),
+  output: Output.object({
+    schema: z.object({
+      city: z.string(),
+      summary: z.string(),
+    }),
+  }),
+});
+```
+
+qgrid 2.5.4는 모든 모델 턴에 합성된 action envelope를 강제합니다. tool-call
+턴은 AI SDK tool call로 유지되고, 마지막 `answer`는 사용자 schema로 강제된 뒤
+`output`으로 반환됩니다. 제한이 있는 `stopWhen`을 지정하지 않으면 AI SDK가
+기본 첫 번째 step에서 멈춰 최종 structured output을 만들 수 없습니다. qgrid server
+2.5.4와 `@cartanova/qgrid-ai-sdk` 2.5.4가 모두 필요합니다. AI SDK의
+`toolChoice`는 현재 전송하거나 강제하지 않으며 tool 선택은 모델이 결정합니다.
 
 ### Provider Options
 
@@ -369,7 +406,30 @@ qgrid(modelId, {
 
 - `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가 클라이언트에서 파싱합니다.
+- `tools`와 `Output.object`를 함께 사용하려면 qgrid server와 AI SDK가 모두 2.5.4 이상이어야 합니다.
+- AI SDK/Zod가 Draft-7 `items: [...]`로 만드는 위치 기반 tuple은 지원되는
+  positive schema 위치에서 OpenAI 호출 전에 정규화되고 위치별 제약이
+  강제됩니다. tuple tail이 생략되면 고정 길이로 해석하며,
+  `additionalItems: true`로 명시한 무제한 tail은 HTTP 400으로 거부합니다.
+  negative, conditional 등 안전하게 정규화할 수 없는 위치의 tuple도 의미가
+  바뀌는 변환 대신 HTTP 400으로 거부합니다. definition은 전역 정규화되므로
+  해당 위치에서 참조하는 경우도 같은 이유로 거부합니다. Anthropic 위치 기반
+  tuple schema는 Claude Code가 위치 의미를 보존할 수 없어 HTTP 400으로
+  거부됩니다. tuple node는 `type: "array"`를 명시해야 하며 nullable tuple은
+  array/null `anyOf`로 표현합니다.
+- structured schema에서는 문서 root 또는 `$defs`/`definitions` entry root만
+  연속으로 가리키는 로컬 root-relative JSON Pointer `$ref`를 허용합니다.
+  property, tuple 내부, conditional, literal 값을 가리키는 ref는 정규화 중
+  target이 이동하거나 다시 작성될 수 있어 HTTP 400으로 거부합니다. resource
+  ID, anchor, 외부 ref, dynamic ref, recursive ref도 허용하지 않습니다.
+- output/tool schema serialization, tool 이름, 설명, JSON escaping,
+  composition framing은 합산 UTF-8 512 KiB 전처리 한도를 공유합니다.
+  schema 값에는 별도로 합산 20,000 node와 schema별 최대 깊이 128 한도가
+  적용됩니다. 잘못되거나 한도를 넘는 입력은 provider 실행 전에 HTTP 400으로
+  실패합니다.
+- Anthropic 경로에서는 최종 합성 schema가 Claude Code 전송의 안전한 단일 argv
+  한도인 64 KiB도 넘지 않아야 합니다.
+- AI SDK의 `toolChoice`는 현재 qgrid에서 지원하지 않습니다.
 
 ## 요구사항
 

package/README.md

@@ -93,7 +93,7 @@ console.log(output.title, output.authors);
 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.
+> **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 plus post-hoc validation, so the model may fail to honor a complex schema. For structured streaming only, qgrid sets `MAX_STRUCTURED_OUTPUT_RETRIES=1` (one attempt; values below 1 are clamped to 1) to bound stream latency. Non-streaming `generate` leaves that override unset and uses Claude Code's default retry budget. Validation failures after the applicable attempts return an explicit error instead of broken JSON.
 
 ### Streaming
 
@@ -114,7 +114,7 @@ for await (const chunk of textStream) {
 ### Tool Calling
 
 ```typescript
-import { generateText, tool } from "ai";
+import { generateText, stepCountIs, tool } from "ai";
 import { qgrid } from "@cartanova/qgrid-ai-sdk";
 import { z } from "zod";
 
@@ -124,17 +124,55 @@ const { text } = await generateText({
   tools: {
     getWeather: tool({
       description: "Get the current weather for a city",
-      parameters: z.object({ city: z.string() }),
+      inputSchema: z.object({ city: z.string() }),
       execute: async ({ city }) => {
         return { temperature: 22, condition: "sunny" };
       },
     }),
   },
+  stopWhen: stepCountIs(3),
 });
 ```
 
 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.
+Executable tools require a bounded `stopWhen` so the AI SDK continues after a
+tool-call step and asks the model for the final response.
+
+Tools can be combined with `Output.object`:
+
+```typescript
+import { generateText, Output, stepCountIs, tool } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+import { z } from "zod";
+
+const { output } = await generateText({
+  model: qgrid("openai/gpt-5.4"),
+  prompt: "Look up Seoul's weather and return a forecast.",
+  tools: {
+    getWeather: tool({
+      description: "Get the current weather for a city",
+      inputSchema: z.object({ city: z.string() }),
+      execute: async ({ city }) => ({ city, temperature: 22 }),
+    }),
+  },
+  stopWhen: stepCountIs(3),
+  output: Output.object({
+    schema: z.object({
+      city: z.string(),
+      summary: z.string(),
+    }),
+  }),
+});
+```
+
+qgrid 2.5.4 constrains every model turn with a composed action envelope. Tool-call
+turns remain AI SDK tool calls, while the final `answer` is constrained by the
+user schema and returned as `output`. Keep a bounded `stopWhen`; otherwise AI SDK
+stops after its default first step and cannot produce the final structured output.
+This requires both qgrid server 2.5.4 and `@cartanova/qgrid-ai-sdk` 2.5.4. AI SDK
+`toolChoice` is not currently transported or enforced; tool selection remains
+model-driven.
 
 ### Provider Options
 
@@ -370,7 +408,33 @@ If multiple projects/workflows share one qgrid server, set `QGRID_PROJECT_NAME`.
 
 - 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.
+- Combining `tools` with `Output.object` requires qgrid server and AI SDK 2.5.4 or later.
+- AI SDK/Zod positional tuples emitted as Draft-7 `items: [...]` are normalized
+  in supported positive schema positions before OpenAI dispatch and their
+  positional constraints are enforced. An omitted tuple tail is treated as
+  fixed-length; an explicitly unrestricted `additionalItems: true` tail is
+  rejected with HTTP 400. Tuples in negative, conditional, or otherwise
+  non-normalizable schema positions are also rejected instead of being
+  rewritten with changed semantics. References from those positions are
+  rejected for the same reason because definitions are normalized globally.
+  Anthropic positional tuple schemas are rejected with HTTP 400 because Claude
+  Code cannot preserve their positional semantics. Tuple nodes must explicitly
+  declare `type: "array"`; express nullable tuples with an `anyOf` array/null
+  branch.
+- Structured schemas accept only local root-relative JSON Pointer `$ref` values
+  targeting the document root or a chain of `$defs`/`definitions` entry roots.
+  References into properties, tuple internals, conditionals, or literal values
+  fail with HTTP 400 because normalization can move or rewrite those targets.
+  Resource IDs, anchors, external refs, dynamic refs, and recursive refs are
+  also rejected.
+- Output/tool schema serialization, tool names, descriptions, JSON escaping,
+  and composition framing share an aggregate 512 KiB UTF-8 preprocessing
+  budget. Schema values also share a 20,000-node budget and have a maximum
+  depth of 128 per schema. Invalid or over-budget inputs fail with HTTP 400
+  before provider execution.
+- On Anthropic routes, the final composed schema must also fit the 64 KiB safe
+  single-argument budget used by the Claude Code transport.
+- AI SDK `toolChoice` is not currently supported by qgrid.
 
 ## Requirements
 

package/dist/index.js

@@ -2,7 +2,7 @@
 const QGRID_PROVIDER_NAME = "qgrid";
 const THREAD_COORD_TTL_MS = 10 * 6e4;
 const TEXT_STREAM_ID_PREFIX = "text";
-const TOP_LEVEL_SCHEMA_WARNING = "OpenAI structured output requires \"object\". Falling back to client-side parsing.";
+const TOP_LEVEL_SCHEMA_WARNING = "qgrid server-enforced structured output requires \"object\". Falling back to client-side parsing.";
 const PENDING_TOOL_RESULTS_WARNING = "[qgrid] tool results did not match any pending qgrid run; sending request without runContext";
 //#endregion
 //#region src/utils.ts
@@ -678,6 +678,16 @@ function warnDroppedImages(droppedImageCount) {
 	if (droppedImageCount <= 0) return;
 	console.warn(`[qgrid] ${droppedImageCount} image message part(s) were ignored because providerOptions.qgrid.imageGeneration is not enabled.`);
 }
+function serializeObjectResponseFormat(responseFormat) {
+	const rawSchema = responseFormat?.type === "json" ? responseFormat.schema : void 0;
+	if (rawSchema === void 0) return void 0;
+	const schemaType = rawSchema.type;
+	if (schemaType !== "object") {
+		console.warn(`[qgrid] responseFormat.schema top-level type is "${schemaType ?? "unknown"}". ${TOP_LEVEL_SCHEMA_WARNING}`);
+		return;
+	}
+	return JSON.stringify(rawSchema);
+}
 function getThreadCoord(sessionKey) {
 	const entry = threadCoordStore.get(sessionKey);
 	if (!entry) return void 0;
@@ -788,10 +798,7 @@ function qgrid(modelId, config) {
 			if (imageGeneration) assertImageInputFitsJsonTransport(imageUrls);
 			const sessionKey = qgridOptions.sessionKey;
 			const reuseSessionKey = reusableSessionKey(modelId, sessionKey);
-			const rawSchema = options.responseFormat?.type === "json" ? options.responseFormat.schema : void 0;
-			const schemaType = rawSchema ? rawSchema.type : void 0;
-			if (rawSchema && !hasTools && schemaType !== "object") console.warn(`[qgrid] responseFormat.schema top-level type is "${schemaType ?? "unknown"}". ${TOP_LEVEL_SCHEMA_WARNING}`);
-			const jsonSchema = !hasTools && rawSchema && schemaType === "object" ? JSON.stringify(rawSchema) : void 0;
+			const jsonSchema = serializeObjectResponseFormat(options.responseFormat);
 			let runContext;
 			let toolResultsPayload;
 			const matchedClientRun = matchClientRun(options.prompt);
@@ -889,8 +896,7 @@ function qgrid(modelId, config) {
 			warnDroppedImages(droppedImageCount);
 			const sessionKey = qgridOptions.sessionKey;
 			const reuseSessionKey = reusableSessionKey(modelId, sessionKey);
-			const rawSchema = options.responseFormat?.type === "json" ? options.responseFormat.schema : void 0;
-			const jsonSchema = !hasTools && rawSchema && rawSchema.type === "object" ? JSON.stringify(rawSchema) : void 0;
+			const jsonSchema = serializeObjectResponseFormat(options.responseFormat);
 			let runContext;
 			let toolResultsPayload;
 			const matchedClientRun = matchClientRun(options.prompt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-ai-sdk",
-  "version": "2.5.3",
+  "version": "2.5.4",
   "description": "AI SDK LanguageModelV3 provider for qgrid",
   "repository": {
     "type": "git",
@@ -24,7 +24,8 @@
     "ai": "^6.0.190",
     "tsdown": "^0.22.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "zod": "4.4.3"
   },
   "peerDependencies": {
     "@ai-sdk/provider": "^3.0.0",
@@ -34,6 +35,7 @@
     "build": "tsdown",
     "test": "vitest run",
     "e2e": "tsx e2e/e2e.ts",
+    "e2e:tools-output": "tsx e2e/tools-structured-output.ts",
     "e2e:logger": "tsx e2e/e2e-logger.ts"
   }
 }