@cartanova/qgrid-cli 2.5.2 → 2.5.4

package/skills/qgrid/references/anthropic-claude-code-runtime.md

@@ -10,6 +10,7 @@ Use this reference before changing Anthropic provider behavior, Claude Code spaw
 - Spawn args
 - Spawn env
 - Config isolation
+- Timeout and cancellation
 - Input adaptation
 - Output adaptation
 - Fable refusal fallback
@@ -84,6 +85,9 @@ Important details:
 - `--setting-sources project` plus seeded settings isolates user configuration.
 - `--system-prompt` or `--system-prompt-file` is always supplied. Omitting it would allow Claude Code default system prompt injection.
 - Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG`.
+- Final structured-output schemas are limited to 64 KiB UTF-8 because Claude Code receives each
+  schema as one `--json-schema` argv value. qgrid applies this check before request-log or stream
+  allocation and repeats it at dispatcher/session boundaries.
 - `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off for existing models. Fable 5 requires always-on adaptive thinking. Opus 5 defaults to adaptive thinking and rejects disabled thinking at `xhigh`/`max` effort. qgrid omits all three suppressors for both models and uses `effort` to control depth.
 
 ## Spawn env
@@ -118,6 +122,24 @@ Never pass `ANTHROPIC_API_KEY` or inherited auth env vars to child processes. OA
 
 This blocks user-scope Claude settings, hooks, memory, and token cross-contamination as much as the current Claude Code interface allows.
 
+## Timeout and cancellation
+
+Claude sessions default to a 240-second server-side process timeout. AI SDK callers can override it
+with `providerOptions.qgrid.timeoutMs`; the wire value is validated as a positive integer no greater
+than 30 minutes and is applied to both `generateText` and `streamText`.
+
+Do not substitute AI SDK's standard top-level `timeout` for this setting. AI SDK consumes that value
+as its overall client budget and exposes only the resulting `abortSignal` to custom providers. The
+two controls are complementary: `timeoutMs` limits the Claude process, while the AI SDK timeout also
+covers client/network overhead.
+
+Cancellation must reach the child process independently of the timer:
+
+- AI SDK aborts cancel the qgrid HTTP request.
+- Streaming SSE close aborts the provider execution.
+- Non-streaming request abort or incomplete response close aborts the provider execution.
+- Logged requests cancelled by disconnect finish as `aborted`, not `error`.
+
 ## Input adaptation
 
 qgrid sends Claude stdin as JSONL with `--input-format stream-json`.
@@ -134,7 +156,10 @@ This is not equivalent to persistent Claude session reuse. It is full-history re
 Claude stdout JSONL is parsed by `stream-json-adapter.ts`.
 
 - Text mode streams `text_delta`.
-- Structured mode streams `input_json_delta` and preserves `StructuredOutput` tool input as final text.
+- Structured mode streams `input_json_delta`. On a successful result, qgrid returns
+  `result.structured_output`, because earlier assistant `StructuredOutput` inputs may be attempts
+  that Claude Code rejected before an internal retry. The first tool input is retained only as a
+  diagnostic fallback when no successful final structured output is available.
 - `result` lines provide final text, usage, duration, cost, subtype, and terminal reason.
 - Non-success subtype, `is_error`, or `terminal_reason: model_error` is treated as an error.
 - Quota exhaustion is detected when text starts with `You've hit`.
@@ -192,6 +217,11 @@ qgrid pins this env var only when the call is **structured and streaming**. The
 
 Non-streaming structured calls therefore keep Claude Code's default retry budget. This matters because Claude models comply with structured output less reliably than OpenAI models: pinning retries to 1 turns a single rejected attempt into an immediate `error_max_structured_output_retries`. Measured on dev0 before the fix, `deti_production` on Opus 4.8 failed 39.6% of non-streaming structured calls for this reason.
 
+When a non-streaming retry succeeds, the result event's `structured_output` is the canonical
+schema-validated value. Do not let a previously captured assistant tool input override it. Preserve
+the first input only for non-success results such as `error_max_turns` or
+`error_max_structured_output_retries`, where it is useful diagnostic evidence.
+
 The other half of SON-495 is unchanged: any non-success subtype still sets `isError`, so a degenerate output after retries fails honestly instead of leaking partial data.
 
 ## 1M context

package/skills/qgrid/references/cli-env-and-server-boot.md

@@ -74,7 +74,7 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 | `QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB` | `16` | Refuse scale-up when estimated qgrid worker RSS would exceed this value. Estimate: `0.71 + 0.157 * totalWorkerCount` GiB. |
 | `QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB` | `20` | Refuse scale-up when current host available memory is below this value. |
 | `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
-| `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic calls | Claude Code structured-output retry count, clamped to at least 1 by qgrid. |
+| `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic streaming calls | Claude Code structured-output retry count for streaming only, clamped to at least 1 by qgrid. Non-streaming `generate` leaves the variable unset and uses Claude Code's default retry budget. |
 
 ## Server boot lifecycle
 

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

@@ -30,6 +30,7 @@ Key decisions:
 - qgrid's AI SDK provider follows the AI SDK `LanguageModelV3` contract. Generic usage belongs to AI SDK docs; qgrid-specific docs should focus on qgrid routing, logging, cache/session behavior, and `providerOptions.qgrid`.
 - qgrid-specific options live under `providerOptions.qgrid`, not under provider-specific namespaces such as `providerOptions.openai`. Consumers should not need to branch on Codex versus Claude internals.
 - AI SDK exposes the outer `providerOptions` as a generic JSON record. `QgridProviderOptions` intentionally types the nested `providerOptions.qgrid` value, and examples should apply `satisfies` there to restore qgrid-specific inference without replacing AI SDK's outer contract.
+- AI SDK's standard `timeout` owns the client-side total budget and reaches custom providers only as an `AbortSignal`. `providerOptions.qgrid.timeoutMs` separately owns the Anthropic server-side Claude process timer; keeping the two explicit avoids pretending the original AI SDK timeout number is available inside qgrid.
 - `projectName` is provider config/payload camelCase. `project_name` is the Sonamu/database request-log column. Prefer `QGRID_PROJECT_NAME` as the project-wide default so request logs and metrics remain filterable at volume.
 - `fallbackModels` may exist as a typed future option, but it is not a server wire contract until the server implements fallback routing. Do not forward it as behavior just because the type exists.
 - Fable 5 refusal fallback is an upstream Claude Code safety path to Opus 4.8, not qgrid's reserved `fallbackModels` feature or Claude Code's overload-only `--fallback-model` flag. qgrid observes and reports the actual route and provider cost; it must not retry again.
@@ -48,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`