@cartanova/qgrid-cli 2.5.3 → 2.5.4

package/skills/qgrid/references/decision-rationale.md

@@ -49,7 +49,16 @@ Sources:
 Key decisions:
 
 - qgrid tool calling is intentionally implemented through structured-output emulation, not native provider tool use. The provider call returns a structured action with tool calls; the AI SDK loop executes tools and sends follow-up turns.
-- Tools and `jsonSchema` are mutually exclusive at the qgrid dispatcher boundary because both need the provider structured-output slot.
+- Tools and `jsonSchema` share one provider structured-output slot by composing
+  an action envelope on every turn. Its final `answer` branch embeds the user's
+  schema; its `tool_call` branch carries emulated AI SDK calls. This keeps final
+  output constrained even when tools are available but never called.
+- Final output is identified by `action: "answer"`, not by tool presence or turn
+  count. Structured answers are serialized as JSON text for AI SDK
+  `Output.object` parsing, while tools-only callers retain their legacy string
+  answer and tolerant parse fallback.
+- AI SDK `toolChoice` remains outside qgrid's wire contract. Do not imply that
+  qgrid transports or enforces it.
 - Tool-call request logs are a multi-step run: create run, append generate/tool steps, then finish run. This makes AI SDK multi-step behavior visible in the dashboard instead of logging only one opaque completion.
 - Tool results update the existing `tool_call` step by `request_log_id + tool_call_id`. They are not logged as a second unrelated completion row.
 - The server infers single-turn completion versus an open tool run from context and finish reason. The removed caller-selected `logMode` contract must not be recreated.

package/skills/qgrid/references/repo-map.md

@@ -28,7 +28,8 @@ Use this map to orient qgrid work quickly.
 - Cost/usage accounting: `packages/api/src/utils/providers/common/model-cost.ts`.
 - Weighted token selection: `packages/api/src/utils/providers/common/smooth-weighted-round-robin.ts`.
 - Boot order and startup migrations: `packages/api/src/server-bootstrap.ts`, `packages/api/src/startup-migrations.ts`.
-- Tool-call emulation: `packages/api/src/application/qgrid/tool-emulation.ts`.
+- Tool-call schema composition: `packages/api/src/application/qgrid/tool-emulation-schema.ts`.
+- Tool-call response decoding: `packages/api/src/application/qgrid/tool-emulation.ts`.
 
 ## Web/Sonamu hot spots
 

package/skills/qgrid/references/tool-calling-and-multiturn.md

@@ -24,6 +24,11 @@ qgrid supports the AI SDK `tools` interface, but it does not use native provider
 - qgrid maps that structured object back into AI SDK `tool-call` content.
 - The AI SDK executes the actual tool functions and calls qgrid again with tool results.
 
+`generateText` and `streamText` default to `stepCountIs(1)`. When an executable
+tool can run before the final answer, callers must set a bounded `stopWhen`
+(for example `stepCountIs(3)`) or the AI SDK stops after the first tool-call
+step and cannot produce the final text or `Output.object` value.
+
 Do not describe this as OpenAI native function calling, Claude native tool use, or Codex/Claude executing client tools. The tools are client-side AI SDK tools requested through structured-output emulation.
 
 ## Client Flow
@@ -36,7 +41,9 @@ When `options.tools` contains function tools:
 2. Convert them with `toQgridTool`.
 3. Send `tools` in `/api/qgrid/query` or `/api/qgrid/prepareStream`.
 4. Forward the per-call `logger` switch when request logging is disabled.
-5. Do not send `jsonSchema` response format at the same time. The server infers whether the logged request becomes a multi-step run.
+5. When a top-level object response format is present, send `jsonSchema` alongside
+   `tools`. The server composes both schemas and infers whether the logged request
+   becomes a multi-step run.
 
 When qgrid responds with `finishReason: "tool-calls"`:
 
@@ -57,9 +64,10 @@ The registry is keyed per pending run so concurrent `generateText(...tools...)`
 
 ## Server Schema Emulation
 
-`packages/api/src/application/qgrid/tool-emulation.ts` builds the tool-call schema.
+`packages/api/src/application/qgrid/tool-emulation-schema.ts` builds the tool-call schema.
+`tool-emulation.ts` decodes the model's action envelope into qgrid answer/tool-call content.
 
-The schema shape is:
+The tools-only schema shape is:
 
 ```json
 {
@@ -83,7 +91,13 @@ The schema explicitly tells the model:
 
 `qgrid.dispatcher.ts` strictifies this schema through `buildStrictOutputSchema` before it reaches provider dispatchers.
 
-If tools and `jsonSchema` are both present, dispatcher rejects the request.
+When tools and a user `jsonSchema` are both present, the dispatcher builds the
+same outer envelope on every turn, but replaces `answer: string | null` with
+`answer: <user schema> | null`. The user schema is namespaced under
+`$defs.__qgrid_user_output`, including rebased local JSON pointers, before the
+whole envelope is strictified. This prevents tool availability from disabling
+the final structured-output constraint, including when the model answers without
+calling a tool.
 
 ## Provider-Specific Path
 
@@ -111,9 +125,14 @@ In both providers, native provider tools are not the public abstraction. The pub
 `applyToolCallEmulation` handles provider text:
 
 - No tools: return normal text content.
-- Tools present and JSON parse fails: warn and fall back to text with `finishReason: "stop"`.
+- Tools-only mode and JSON parse failure: preserve the legacy warning and text
+  fallback with `finishReason: "stop"`.
+- Tools plus a user schema and malformed or incoherent envelope: return an
+  explicit structured-output error; do not rescue it as successful text.
 - `action: "tool_call"`: validate tool names, generate qgrid `toolCallId`, return `finishReason: "tool-calls"`.
-- `action: "answer"`: return final text with `finishReason: "stop"`.
+- `action: "answer"` in tools-only mode: return the string answer as final text.
+- `action: "answer"` with a user schema: JSON-serialize the structured `answer`
+  as final text so AI SDK can parse and validate `Output.object`.
 
 Unknown tool names throw.
 
@@ -128,6 +147,14 @@ AI SDK multi-step behavior is client-orchestrated:
 
 This is different from a provider-native tool loop. Neither Codex nor Claude Code executes the AI SDK tool functions.
 
+The composed schema is reapplied to tool-result follow-up turns. Final output is
+identified by `action: "answer"` rather than by whether a tool happened to be
+available or called. AI SDK `toolChoice` is not transported or enforced by
+qgrid; the model selects between the envelope's answer and tool-call actions.
+
+The combined contract requires qgrid server 2.5.4 and
+`@cartanova/qgrid-ai-sdk` 2.5.4.
+
 OpenAI/Codex follow-ups can reuse the same Codex thread when `runContext.threadCoord` remains valid. For tool-result follow-up turns, qgrid sends delta input containing tool result text to the existing thread; cold fallback injects full history.
 
 Anthropic follow-ups do not reuse Claude sessions. qgrid starts a fresh Claude process, replays flattened full history, and sends the tool-result continuation input.

package/skills/qgrid/references/verification-and-debugging.md

@@ -30,6 +30,7 @@ AI SDK package `@cartanova/qgrid-ai-sdk`:
 - `pnpm --filter @cartanova/qgrid-ai-sdk test`.
 - `pnpm --filter @cartanova/qgrid-ai-sdk build`.
 - `pnpm --filter @cartanova/qgrid-ai-sdk e2e`.
+- `pnpm --filter @cartanova/qgrid-ai-sdk e2e:tools-output`.
 - `pnpm --filter @cartanova/qgrid-ai-sdk e2e:logger`.
 
 CLI package `@cartanova/qgrid-cli`:
@@ -54,7 +55,7 @@ Choose by affected area:
 | AI SDK logger integration | `packages/ai-sdk/src/logger.test.ts` |
 | qgrid provider routing and strict schema | `packages/api/src/application/qgrid/qgrid.dispatcher.test.ts` |
 | conversation/thread reuse routing | `packages/api/src/application/qgrid/conv-routing.test.ts` |
-| tool-call emulation | `packages/api/src/application/qgrid/tool-emulation.test.ts` |
+| tool-call emulation | `packages/api/src/application/qgrid/tool-emulation.test.ts`, `tool-emulation-schema.test.ts` |
 | request-log run lifecycle | `packages/api/src/application/qgrid/qgrid-run-lifecycle.test.ts` |
 | qgrid frame API behavior | `packages/api/src/application/qgrid/qgrid.frame.test.ts` |
 | token subscriber and LISTEN/NOTIFY handling | `packages/api/src/application/qgrid/token-subscriber.test.ts` |
@@ -101,6 +102,20 @@ AI SDK structured output:
 - Env: `QGRID_URL`, `SMOKE_MODEL`, `SMOKE_CASES`, `SMOKE_REPEAT`.
 - Uses AI SDK 6 `streamText` with `Output.object`; useful for structured-output regressions.
 
+AI SDK tools plus structured output:
+
+- `packages/ai-sdk/e2e/tools-structured-output.ts`
+- This is the public-path release acceptance matrix: `qgrid()` HTTP/SSE,
+  `generateText`/`streamText`, OpenAI/Anthropic, direct final answers, and one
+  client-tool result followed by `Output.object`.
+- It consumes real provider quota and requires the explicit
+  `QGRID_REAL_PROVIDER_ACCEPTANCE=1` opt-in.
+- Uses `QGRID_URL`, `QGRID_ACCEPTANCE_OPENAI_MODEL`, and
+  `QGRID_ACCEPTANCE_ANTHROPIC_MODEL`. OpenAI direct-final coverage defaults to
+  10 generate plus 10 stream attempts and can be changed with
+  `QGRID_ACCEPTANCE_OPENAI_DIRECT_REPEATS_PER_MODE`. Request logs use the stable
+  project name `qgrid-ai-sdk-tools-output-acceptance`.
+
 Image generation:
 
 - `packages/api/scripts/smoke-test-image-generation.ts`