@cartanova/qgrid-cli 2.3.8 → 2.4.0

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

@@ -0,0 +1,179 @@
+# Decision Rationale
+
+Use this reference when the question is "why is qgrid designed this way?" or before changing an established runtime contract. Current code is the source of truth for behavior; repo docs are the source of truth for the decision trail.
+
+Do not copy these notes blindly into implementation. Use them to find the relevant docs, then inspect the current code and tests.
+
+## Contents
+
+- AI SDK provider boundary
+- Tool calling and request-log lifecycle
+- OpenAI/Codex runtime
+- Anthropic/Claude Code runtime
+- Token sync and quota thresholds
+- Request logs, metrics, and dashboard
+- CLI packaging and server boot
+- Image generation
+
+## AI SDK Provider Boundary
+
+Sources:
+
+- `docs/plans/2026-05-07-feat-qgrid-ai-sdk-provider-plan.md`
+- `docs/solutions/conventions/qgrid-provider-options-boundary.md`
+- `docs/plans/2026-05-26-refactor-ai-sdk-wrapper-correlation-boundary-plan.md`
+
+Key decisions:
+
+- `packages/ai-sdk` is the active public SDK. `packages/sdk` is deprecated and should be read only for legacy context.
+- 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.
+- `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.
+- The SDK should stay a thin adapter. Server APIs own request-log lifecycle, provider dispatch, structured-output emulation, and provider runtime details.
+
+## Tool Calling And Request-Log Lifecycle
+
+Sources:
+
+- `docs/plans/2026-05-07-feat-qgrid-ai-sdk-provider-plan.md`
+- `docs/plans/2026-05-20-feat-request-log-run-lifecycle-api-plan.md`
+- `docs/plans/2026-05-26-refactor-ai-sdk-wrapper-correlation-boundary-plan.md`
+- `docs/solutions/tooling-decisions/anthropic-structured-stream-keep-required-and-fail-honestly.md`
+
+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.
+- 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.
+- `runContext.requestLogId` is intentionally direct. qgrid SDK and server are in the same product boundary, so an opaque indirection was not worth the complexity.
+- Lifecycle endpoints remain public because `createQgridLogger` records non-qgrid AI SDK calls into qgrid logs without forcing those calls through the qgrid provider.
+- Structured-output failures should fail honestly. Especially on Claude Code, partial or invalid structured output must not be rescued into a fake success.
+
+## OpenAI/Codex Runtime
+
+Sources:
+
+- `docs/plans/2026-05-18-feat-codex-app-server-backend-pivot-plan.md`
+- `docs/plans/2026-05-30-feat-codex-builtin-tool-suppression-plan.md`
+- `docs/plans/2026-06-06-feat-codex-thread-reuse-prompt-cache-plan.md`
+- `docs/solutions/logic-errors/qgrid-prompt-cache-hit-rate-metric-miscalculation.md`
+
+Key decisions:
+
+- OpenAI uses Codex `app-server` directly over stdio, not `codex exec`. The app-server path gives qgrid OAuth login, persistent workers, and thread handles.
+- Workers are persistent and token-scoped. qgrid can spawn multiple workers per token, but each worker is single-flight for turns. This differs from Anthropic, which fresh-spawns per request.
+- qgrid unsets normal OpenAI API-key paths and logs in with ChatGPT/OAuth credentials. This keeps the runtime aligned with subscription-token pooling rather than API billing.
+- Built-in Codex tools, apps, skills, web search, shell, and large instruction blocks are suppressed. The primary reason is tool-call correctness: Codex built-ins can steal calls that qgrid expects to represent as emulated AI SDK tool calls. Token savings are secondary.
+- Thread reuse exists because Codex/OpenAI prompt cache keys are tied to the Codex conversation/thread. New `thread/start` calls miss cache even with identical prefixes.
+- Reuse must be explicit through a server-issued coordinate such as `threadCoord`. Do not use content hashes or hidden closures; same-looking prompts from different sessions can cross-contaminate.
+- Reuse fallback should be cold and correct. Invalid worker id, epoch mismatch, missing thread, busy worker timeout, or over-threshold token should not corrupt a conversation.
+- Cache and usage metrics use per-turn usage. For Codex, `tokenUsage.total` is conversation cumulative; request logs must use `tokenUsage.last`.
+- OpenAI/Codex cached tokens are included in `input_tokens`. Cache-hit denominator is `input_tokens`, not `input + cache_read + cache_creation`.
+
+## Anthropic/Claude Code Runtime
+
+Sources:
+
+- `docs/brainstorms/2026-06-16-anthropic-provider-revival-problem-definition.md`
+- `docs/plans/2026-06-24-001-refactor-anthropic-cold-only-routing-plan.md`
+- `docs/solutions/integration-issues/claude-cli-drops-assistant-role-in-stream-json.md`
+- `docs/solutions/tooling-decisions/anthropic-structured-stream-keep-required-and-fail-honestly.md`
+- `docs/plans/2026-06-23-001-feat-anthropic-1m-context-plan.md`
+- `docs/solutions/security-issues/claude-cli-anthropic-api-key-leak-audit.md`
+- `docs/solutions/security-issues/qgrid-cross-user-context-leak-via-claude-settings-sources.md`
+- `docs/solutions/integration-issues/claude-code-oauth-tokens-share-prompt-cache.md`
+
+Key decisions:
+
+- Anthropic is an internal Claude subscription OAuth path. The API-key provider was not pursued because it does not serve qgrid's subscription-pooling value.
+- Anthropic is cold-only. It does not use Codex-style thread reuse because Claude Code prompt cache is prefix-based and AI SDK consumers already send full message history for each step.
+- The shared `threadCoord` response shape may still appear for provider symmetry, but AI SDK storage/replay is disabled for `anthropic/*` models.
+- Claude Code `stream-json` drops structural assistant role replay in the outbound API payload. qgrid flattens prior history into text because structural role replay through the CLI is not reliable.
+- Claude Code `--json-schema` is not constrained native tool calling. It creates a `StructuredOutput` tool and validates after model generation. Keep schemas strict and fail on non-success subtypes or retry exhaustion.
+- `MAX_STRUCTURED_OUTPUT_RETRIES=1` means one attempt. Do not set it to 0 expecting "no retry but one attempt"; that can mean no useful attempt.
+- 1M context support is measured per model and is a mitigation, not a guarantee. It reduces compaction/hang frequency for huge prompts, but does not make every structured prompt reliable.
+- Spawn env must be whitelisted. Never pass inherited `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `ANTHROPIC_BASE_URL` unless intentionally building an API-key/proxy path.
+- `--setting-sources project` is required for shared-service isolation. User/local Claude settings can load hooks or memory and leak context across requests.
+- Claude Code OAuth prompt cache sharing across tokens in the same workspace is an observed cost behavior, not a product contract. Monitor it; do not promise it.
+
+## Token Sync And Quota Thresholds
+
+Sources:
+
+- `docs/plans/2026-05-02-feat-token-sync-via-pg-listen-notify-plan.md`
+- `docs/brainstorms/2026-06-30-token-quota-threshold-requirements.md`
+- `docs/plans/2026-06-30-001-feat-token-quota-threshold-plan.md`
+
+Key decisions:
+
+- Token changes propagate with PostgreSQL `LISTEN/NOTIFY` plus periodic reconcile. Reconcile is kept because notifications can be missed during disconnects.
+- Trigger setup is boot-time idempotent SQL, not a raw migration file, because the Sonamu migration directory is managed and raw files can conflict.
+- Trigger payloads stay small (`op`, `id`). Dispatchers reload token rows instead of trusting a large notification body.
+- The token subscriber disables statement/idle timeouts for `LISTEN` and uses reconnect backoff.
+- `quota_threshold` is a routing guardrail, not a load balancer. It prevents an individual token from crossing a configured utilization percentage; it does not equalize traffic.
+- Threshold values are nullable integers from 1 to 100. `0` is not valid; `100` means exclude only at full utilization.
+- Provider criteria differ by primary window: Anthropic uses `five_hour.utilization`; OpenAI uses `primary.usedPercent`.
+- Threshold gates are by token id, not token name. Names are display/logging labels and can change.
+- Lookup failure is fail-open with logs/metrics. Hard failure happens only when usage was read successfully and the token is over threshold.
+- OpenAI needs the gate in reuse, idle selection, and queue drain paths. A reusable but over-threshold worker must fall back cold to another eligible token when possible.
+
+## Request Logs, Metrics, And Dashboard
+
+Sources:
+
+- `docs/plans/2026-05-21-feat-qgrid-logger-telemetry-integration-plan.md`
+- `docs/brainstorms/2026-07-01-request-log-ttft-metric-requirements.md`
+- `docs/solutions/logic-errors/qgrid-prompt-cache-hit-rate-metric-miscalculation.md`
+- `docs/solutions/performance-issues/sonamu-findmany-aggregate-slowdown.md`
+- `docs/solutions/performance-issues/qgrid-request-logs-subset-and-distinct-query-optimization.md`
+
+Key decisions:
+
+- The dashboard/logging layer is a core qgrid value, not an incidental web UI. It lets operators see cost, cache, TTFT, token routing, tool steps, and project-level workloads.
+- `createQgridLogger` exists so teams can keep using native AI SDK providers while still recording those calls in qgrid request logs. It should not throw into user code.
+- Request-log TTFT is the first generate-step TTFT. It intentionally measures generation responsiveness, not queue time or full request latency.
+- Cache-hit metrics must be derived consistently from normalized provider accounting. Keep metric logic centralized when possible.
+- Request-log list queries should avoid large text/blob columns unless the UI needs them. The list view is for scanning, not payload archival.
+- Aggregate endpoints can intentionally duplicate filters in raw SQL instead of reusing `findMany`. Materializing full rows for aggregates was measured as too slow.
+- Project-name filters matter at scale. Encourage `QGRID_PROJECT_NAME` so dashboards can distinguish workloads without inspecting prompts.
+- Setup agents are part of the intended local qgrid workflow. They should ask for or add a project label during setup because retroactively untangling anonymous request logs is expensive once multiple projects or workflows share a qgrid server.
+
+## CLI Packaging And Server Boot
+
+Sources:
+
+- `docs/plans/2026-04-06-feat-package-split-sdk-cli-plan.md`
+- `docs/plans/2026-04-13-refactor-cli-bundle-rollback-plan.md`
+- `references/cli-env-and-server-boot.md`
+
+Key decisions:
+
+- CLI and SDK were split so AI consumers do not install Sonamu, database, and runtime-server dependencies just to call qgrid.
+- The CLI is a direct Node/bundle runner, not a Docker wrapper. Docker was removed to keep `npm i -g ...` plus `qgrid start` usable without local Docker setup.
+- CLI user-facing configuration is intentionally small: database connection, port, public callback URL, server URL, and project name. Bundle bootstrapping details are implementation internals.
+- The CLI checks runtime CLIs (`codex`, `claude`) because qgrid delegates provider execution to those local binaries.
+- The dashboard version should follow the CLI package version because the dashboard is shipped by the CLI bundle, not as an independently versioned web product.
+- qgrid skills ship with the CLI package, not a separate skills package. qgrid cannot be used with the AI SDK alone; a local qgrid CLI server is required, so CLI install is the right moment to sync `.agents/skills/qgrid` and `.claude/skills/qgrid` into the consuming project.
+
+## Image Generation
+
+Sources:
+
+- `docs/brainstorms/2026-07-05-qgrid-image-generation-requirements.md`
+- `docs/plans/2026-07-05-001-feat-codex-image-generation-plan.md`
+- `docs/brainstorms/2026-07-06-qgrid-image-persistence-requirements.md`
+- `docs/brainstorms/2026-07-06-codex-image-cost-estimate.md`
+
+Key decisions:
+
+- Image generation is OpenAI/Codex-only and request-level opt-in. It is essentially a Codex-hosted `image_generation` tool call, not qgrid directly calling the OpenAI Images API. Always-on image tools would change every turn's tool configuration and threaten prompt-cache stability.
+- It is non-stream only. Codex returns completed base64 image payloads, not useful image deltas.
+- Image turns are cold one-shot threads and are excluded from thread reuse. This prevents base64 payloads from entering reusable conversation state and cache prefixes.
+- qgrid performs preflight capability/model gates and postflight "image count must be greater than zero" checks. Codex can otherwise silently return text when image generation is unavailable or unused.
+- Returned images are inline base64 content parts for consumers and AI SDK `file` parts. qgrid does not promise aspect ratio, edits, or reference-image control on this path.
+- `imageGenerationOptions` currently supports quality and size. The worker instruction and request-log pricing assumption use `gpt-image-2`, with defaults `medium` and `1536x1024`.
+- qgrid does not manage generated images as durable assets through a `generated_images` table or object-storage layer. Current request logs can still contain inline image data URLs for inspection and synthetic `image_generation` tool-call steps.
+- Image cost is stored separately in `request_logs.image_cost_usd`; `request_logs.cost_usd` remains the Codex driver model token cost. Because Codex does not expose exact image tool usage, `image_cost_usd` is a price-table estimate and may be inaccurate.
+- Inspect current plans, tests, and implementation before changing behavior; the Codex tool surface can change underneath qgrid.

package/skills/qgrid/references/docs-workflow.md

@@ -0,0 +1,32 @@
+# Docs Workflow
+
+Use this reference for qgrid planning, diagnosis, and review workflow.
+
+The project workflow is documented in `docs/WORKFLOW.md`.
+
+## Standard flow
+
+1. Brainstorm and plan before substantial work.
+2. Store local docs under `docs/` using existing directories:
+   - `docs/brainstorms/`
+   - `docs/plans/`
+   - `docs/diagnosis/`
+   - `docs/solutions/`
+3. Use peer review for plans and docs when requested.
+4. Accept review feedback by default unless there is a concrete tradeoff-based reason not to.
+
+## Existing docs are context
+
+Before changing runtime-sensitive areas, search `docs/diagnosis`, `docs/solutions`, and recent `docs/plans` for prior decisions. qgrid has important historical decisions around:
+
+- Codex thread reuse and prompt cache.
+- Claude Code fresh spawn.
+- structured output strictness.
+- Anthropic usage categories.
+- request log cache hit metrics.
+- quota threshold routing.
+- token isolation and auth env leaks.
+
+Do not copy stale docs blindly. Use docs to identify decisions and then verify against current code.
+
+When a repo doc establishes or changes durable rationale for a qgrid feature, reflect the stable decision in `references/decision-rationale.md`. Keep the skill reference as a compact index of why the decision exists and where the source docs live; do not copy full plans or brainstorms into the skill.

package/skills/qgrid/references/openai-codex-runtime.md

@@ -0,0 +1,153 @@
+# OpenAI Codex Runtime
+
+Use this reference before changing OpenAI provider behavior, Codex worker lifecycle, thread reuse, cache behavior, OAuth refresh, image-generation gates, or quota routing.
+
+## Contents
+
+- Process model
+- Codex configuration
+- Initialization and auth
+- Thread and turn flow
+- Thread retention
+- Queue and routing
+- Usage and notifications
+- Streaming
+- Image generation status
+
+## Process model
+
+OpenAI tokens use persistent Codex app-server workers.
+
+- Dispatcher: `packages/api/src/utils/providers/openai/openai-dispatcher.ts`.
+- Worker: `packages/api/src/utils/providers/openai/codex-worker.ts`.
+- RPC client: `packages/api/src/utils/providers/openai/codex-rpc.ts`.
+- Process command: `codex app-server --listen stdio://`.
+- Workers per token: `QGRID_WORKERS_PER_TOKEN`, default 3, capped at 5.
+- Worker id: `tokenId * 10 + workerIndex`.
+- Worker home: `/tmp/qgrid-codex/${tokenId}-${workerIndex}` when `workerIndex` exists.
+- Worker cwd: `${CODEX_HOME}/cwd`.
+
+Workers are persistent. Turns are single-flight per worker (`busy` flag). When all eligible workers are busy, requests enter an in-memory queue.
+
+## Codex configuration
+
+qgrid writes a worker-local `config.toml` under `CODEX_HOME` before spawning Codex. The intent is to use Codex as a plain generation backend, not as a coding agent.
+
+Disabled by config:
+
+- web search
+- shell tool
+- tool search/suggest
+- multi-agent
+- image generation by default
+- apps/plugins
+- view_image
+- bundled skills/instructions
+- permissions/apps/environment instruction blocks
+
+Spawn env is intentionally small:
+
+- `PATH`
+- `TMPDIR`
+- `CODEX_HOME`
+- `CODEX_EXEC_SERVER_URL=none`
+
+Do not re-enable built-in Codex tools/instructions unless the user explicitly asks for agentic Codex behavior.
+
+## Initialization and auth
+
+Worker initialization:
+
+1. Spawn Codex app-server over stdio.
+2. Create `CodexRpcClient`.
+3. Send `initialize`.
+4. Login with ChatGPT/OAuth credentials.
+5. Bind Codex server-request `account/chatgptAuthTokens/refresh` to qgrid's token refresh handler.
+
+If Codex asks to refresh ChatGPT auth tokens, qgrid handles it through `handleChatgptAuthTokensRefresh(tokenId)`.
+
+## Thread and turn flow
+
+Cold path:
+
+1. `thread/start` with `ephemeral: true`.
+2. `baseInstructions` is a minimal assistant prompt.
+3. `developerInstructions` carries the qgrid system prompt.
+4. Optional `thread/inject_items` injects full history.
+5. `turn/start` runs current input.
+
+Reuse path:
+
+1. qgrid verifies the incoming `threadCoord`.
+2. Dispatcher reacquires the exact worker by `workerId`.
+3. It checks worker readiness, active status, epoch, thread presence, and quota threshold.
+4. It waits up to 5 seconds for that worker to become free.
+5. It calls `turn/start` on the existing thread with delta input only.
+
+Thread metadata is stored only inside the worker process. Worker restart increments `epoch` and clears thread metadata. Thread reuse must fall back cold if epoch or thread lookup fails.
+
+## Thread retention
+
+Worker thread metadata:
+
+- idle TTL: 10 minutes.
+- max threads per worker: 16.
+- cleanup is lazy before creating a new thread.
+
+There is no explicit close RPC for old ephemeral threads; qgrid removes them from the reuse map and stops routing turns to them.
+
+## Queue and routing
+
+OpenAI worker selection:
+
+- Prefer reuse worker when a valid reuse coordinate exists.
+- Otherwise select an idle ready active worker round-robin across eligible workers.
+- If no worker is free, enqueue.
+- Queue timeout: 60 seconds.
+- Max queue size: 50.
+
+Quota threshold:
+
+- `quota_threshold` is stored on tokens.
+- Dispatcher reads rate limits through a ready worker.
+- Rate limit reads are cached for 60 seconds.
+- Lookup failure is fail-open.
+- If all ready active tokens are over threshold, throw `QuotaThresholdExceededError`.
+
+## Usage and notifications
+
+Codex RPC notifications drive result collection:
+
+- `item/agentMessage/delta`: text deltas and TTFT.
+- `item/completed`: final text and image-generation results.
+- `thread/tokenUsage/updated`: token usage.
+- `turn/completed`: duration and terminal status.
+- `error`: terminal error.
+
+When using thread reuse, use `tokenUsage.last`, not `tokenUsage.total`, for request logs. `.total` is conversation cumulative and mixes previous turns, which corrupts per-request cache hit metrics.
+
+## Streaming
+
+Streaming uses the same worker/thread execution with callbacks:
+
+- `onThreadId` emits the thread id when a new thread is created.
+- `onTurnId` emits turn id after `turn/start`.
+- qgrid can interrupt OpenAI turns on SSE close by calling `turn/interrupt` across ready workers.
+
+## Image generation
+
+Image generation is OpenAI/Codex-only and implemented as an opt-in Codex `image_generation` tool call. It is not a direct OpenAI Images API call from qgrid.
+
+- It is opt-in through `imageGeneration`.
+- `imageGenerationOptions` carries quality/size hints and the cost-estimation basis.
+- It is non-stream only; streaming path rejects it.
+- It always uses a cold one-shot thread and does not issue a reusable coordinate.
+- It enables `features.image_generation` only on that thread; global config remains disabled.
+- It swaps the normal "text only" base instruction for an image-permitting instruction on that thread.
+- It gates on provider capability and model multimodality.
+- Failure kinds are `gate`, `not_called`, and `incomplete`.
+- Codex notifications expose image items through `item/started` and `item/completed`; qgrid treats non-empty base64 `result` as the completion signal, not the item `status` string.
+- Completed images are surfaced as qgrid `image` content parts and AI SDK `file` parts with `mediaType: "image/png"`.
+- qgrid uses `gpt-image-2` as the image-tool pricing/model assumption. Codex does not expose exact image tool token usage, so `image_cost_usd` is an estimate from the public price table, not exact billing.
+
+Before modifying this area, inspect latest docs/plans/brainstorms and current tests.

package/skills/qgrid/references/prompt-cache-and-usage.md

@@ -0,0 +1,101 @@
+# Prompt Cache And Usage
+
+Use this reference for `sessionKey`, `threadCoord`, prompt cache, request-log usage metrics, and cost accounting.
+
+## qgrid thread coordinates
+
+Client-facing `QgridThreadCoord`:
+
+```ts
+{
+  workerId: number;
+  threadId: string;
+  epoch: number;
+  systemHash: string;
+}
+```
+
+- Server issues this after a provider turn.
+- Client returns it through `runContext.threadCoord`.
+- AI SDK hides this behind `providerOptions.qgrid.sessionKey` for OpenAI models.
+- `systemHash` is the first 16 hex chars of SHA-256 over the system prompt.
+- Reuse is eligible only when incoming `systemHash` matches current system prompt.
+
+## AI SDK `sessionKey`
+
+`packages/ai-sdk/src/index.ts` stores `threadCoord` in a module-level map by `sessionKey` for 10 minutes.
+
+- OpenAI models: `sessionKey` can replay the stored coordinate.
+- Anthropic models: `reusableSessionKey` returns `undefined`, so the coordinate is not stored or replayed.
+- Tool-call loop run context and non-tool multi-turn context share the same `runContext` boundary.
+
+## OpenAI/Codex cache behavior
+
+Codex sets OpenAI prompt-cache affinity from the Codex conversation/thread id. qgrid originally got cache misses by creating a new thread for every request. Thread reuse fixes this by keeping the same Codex thread for a logical conversation.
+
+Cache hit requires:
+
+1. `QGRID_OPENAI_THREAD_REUSE` is not `"false"`.
+2. AI SDK sends a stable `sessionKey`.
+3. Server receives a `threadCoord`.
+4. `systemHash` matches.
+5. The target worker exists, is ready/active, has same `epoch`, and still has the thread.
+6. The worker becomes free within the reuse wait window.
+7. Prefix content remains stable.
+
+When reuse succeeds, qgrid sends only delta input to `turn/start`. When reuse fails, qgrid falls back to cold execution with full prompt plus history injection.
+
+Important cache breakers:
+
+- Different system prompt.
+- Worker restart or thread TTL eviction.
+- Schema/output format changes near the prefix. Codex places `outputSchema` in a prefix-sensitive area, so changing schemas turn-by-turn can break cache even on the same thread.
+- Image generation requests, which intentionally use cold one-shot threads and do not issue reuse coordinates.
+
+## Anthropic/Claude Code cache behavior
+
+Anthropic uses fresh Claude Code process spawn per request. qgrid does not replay Anthropic `sessionKey`.
+
+Prompt cache can still work when prefixes are stable, but:
+
+- Full history is replayed through stream-json after flattening.
+- Cache write/read can be eventually consistent; immediate next request is not guaranteed to hit.
+- Claude Code OAuth token cache behavior has provider-specific quirks documented in `docs/solutions`.
+- Avoid putting volatile schema text into the system prompt. qgrid uses `--json-schema` / `StructuredOutput` for structured output.
+
+## Usage normalization
+
+qgrid's standard usage meaning:
+
+- `input_tokens`: total input for this request, including cache read and cache creation input.
+- `cache_read_tokens`: cached input read.
+- `cache_creation_tokens`: input written to prompt cache.
+- `output_tokens`: output tokens.
+
+OpenAI/Codex already reports `inputTokens` as total input including cached input. Use Codex `tokenUsage.last` for per-request logs, not `tokenUsage.total`.
+
+Anthropic native usage categories are mutually exclusive:
+
+- `input_tokens`
+- `cache_creation_input_tokens`
+- `cache_read_input_tokens`
+
+qgrid normalizes Anthropic by summing those three into standard `inputTokens` and preserving cache read/write as subfields.
+
+## Cache hit rate
+
+For qgrid-standard usage, hit rate denominator is `input_tokens`, not `input_tokens + cache_read_tokens + cache_creation_tokens`.
+
+Do not double-count cache subfields. This was a real dashboard bug: OpenAI cache hit rates could be displayed near half their actual value when cache tokens were added to the denominator again.
+
+## Cost accounting
+
+`packages/api/src/utils/providers/common/model-cost.ts` contains model price fallback.
+
+- OpenAI cost normally uses qgrid's price table.
+- OpenAI image generation stores a separate `image_cost_usd` estimate. It assumes Codex's image tool is priced as `gpt-image-2` for the selected/default quality and size, because qgrid does not receive exact image tool usage from Codex.
+- Anthropic Claude Code may return `total_cost_usd`; qgrid prefers provider cost when present and positive.
+- Anthropic cache creation uses 5-minute cache write price in fallback tables.
+- OpenAI long-context surcharge applies to the whole request when input exceeds the model threshold, not just the excess tokens.
+
+When changing models or prices, verify against current official pricing before editing the table.

package/skills/qgrid/references/provider-runtime-differences.md

@@ -0,0 +1,54 @@
+# Provider Runtime Differences
+
+Use this reference when comparing OpenAI and Anthropic behavior, debugging provider-specific bugs, or reviewing cross-provider changes.
+
+| Topic | OpenAI via Codex | Anthropic via Claude Code |
+|---|---|---|
+| Process lifetime | Persistent `codex app-server` workers | Fresh `claude` process per request |
+| Worker pool | Token x `QGRID_WORKERS_PER_TOKEN`, default 3, max 5 | No workers; in-memory token pool only |
+| Worker id | `tokenId * 10 + workerIndex` | `tokenId` |
+| Epoch | Worker spawn counter; changes on restart | Always `0` |
+| Request concurrency | One turn per worker; queue when all eligible workers busy | Fresh process per request; token selection uses least-used RR |
+| Model routing | `openai/*`; qgrid strips provider prefix before provider call | `anthropic/*`; provider canonicalizes model and strips prefix/`[1m]` |
+| Prefix-less models | Fallback not implemented | Fallback not implemented |
+| Thread/session | Ephemeral Codex thread stored in worker memory | Fresh Claude `--session-id` per request |
+| `sessionKey` | AI SDK stores and replays `threadCoord` for thread reuse | AI SDK intentionally disables storage/replay |
+| Multi-turn | Reuse sends delta input to existing Codex thread; cold fallback injects full history | Fresh spawn receives flattened full history through stream-json |
+| Cache key | Codex conversation/thread id is prompt-cache affinity | Anthropic prefix cache via Claude Code; fresh spawn still can cache stable prefixes |
+| Built-in tools | Codex tools/apps/plugins/skills disabled by worker config | Claude tools disabled via `--tools ""`; `StructuredOutput` allowed only for schema |
+| AI SDK tools | Emulated via qgrid structured output schema, then mapped to AI SDK `tool-call` content | Same emulation path; not native Claude Code tools |
+| Structured output | Codex `outputSchema` passed to `turn/start`; schema changes can affect prefix cache | Claude `--json-schema` through `StructuredOutput` tool; strict schemas required |
+| Usage accounting | Codex usage already reports `inputTokens` including cached input | Native Anthropic categories are mutually exclusive; qgrid sums them into total input |
+| Cost source | qgrid model price fallback | Prefer Claude Code `total_cost_usd`, else qgrid price fallback |
+| Settings isolation | Per-worker `CODEX_HOME` and config.toml | Shared project cwd plus per-token `CLAUDE_CONFIG_DIR` |
+| Streaming close | Can interrupt Codex turn with `turn/interrupt` | Abort kills the fresh child process |
+| Image generation | In progress, OpenAI/Codex non-stream only | Explicitly unsupported |
+
+## Routing contract
+
+Provider routing happens in `packages/api/src/application/qgrid/qgrid.dispatcher.ts`.
+
+- `openai/<model>` routes to `OpenAIDispatcher`.
+- `anthropic/<model>` routes to `AnthropicDispatcher`.
+- models without provider prefix produce "Direct LLM API fallback not implemented".
+
+Do not silently route prefix-less Claude model names such as `claude-sonnet-4-6` to Anthropic. Tests intentionally guard against this.
+
+## Shared contracts
+
+Both providers return `GenerateResult` with:
+
+- `text`
+- `tokenName`
+- `usage`
+- `durationMs`
+- optional `ttftMs`
+- optional provider cost
+- canonical `model`
+- `threadCoord`
+
+`qgrid.dispatcher.ts` maps this into `QueryOutput`, applies tool-call emulation, calculates fallback cost, and issues a client-facing `QgridThreadCoord` by adding `systemHash`.
+
+Both providers receive strictified output schemas from `buildStrictOutputSchema`.
+
+Tool calling uses this shared strict-schema path. It is not native provider tool calling on either route.

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

@@ -0,0 +1,37 @@
+# Repo Map
+
+Use this map to orient qgrid work quickly.
+
+## Active packages
+
+- `packages/api`: Sonamu server, qgrid API frame, provider dispatchers, token/request-log models, migrations, OAuth, runtime integration.
+- `packages/ai-sdk`: active public AI SDK provider and logger integration. Prefer this for public SDK behavior and examples.
+- `packages/web`: dashboard UI. Usually depends on Sonamu-generated API clients and API model shape.
+- `packages/cli`: global `qgrid` command, bundled server boot, dependency checks, DB preflight, and qgrid Codex/Claude Code skill sync. The CLI package ships `skills/qgrid` and its `postinstall` links it into consuming projects.
+- `scripts` and `packages/api/scripts`: smoke tests, debug scripts, runtime probes.
+- `docs`: local planning, diagnosis, and solution history. `docs/WORKFLOW.md` is the collaboration convention.
+
+## Deprecated/context-only package
+
+- `packages/sdk`: deprecated. Read only for historical context or migration clues. Do not implement new features, docs, or examples against this package unless explicitly asked for legacy compatibility.
+
+## Runtime hot spots
+
+- Provider router: `packages/api/src/application/qgrid/qgrid.dispatcher.ts`.
+- Conversation/thread reuse: `packages/api/src/application/qgrid/conv-routing.ts`.
+- Query API and SSE stream: `packages/api/src/application/qgrid/qgrid.frame.ts`.
+- Request logging lifecycle: `packages/api/src/application/qgrid/qgrid-run-lifecycle.ts`.
+- Token LISTEN/NOTIFY sync: `packages/api/src/application/qgrid/token-subscriber.ts`.
+- Token trigger setup: `packages/api/src/application/qgrid/token-trigger-setup.ts`.
+- OpenAI Codex runtime: `packages/api/src/utils/providers/openai/*`.
+- Anthropic Claude Code runtime: `packages/api/src/utils/providers/anthropic/*`.
+- Cost/usage accounting: `packages/api/src/utils/providers/common/model-cost.ts`.
+- Tool-call emulation: `packages/api/src/application/qgrid/tool-emulation.ts`.
+
+## Web/Sonamu hot spots
+
+- Entity definitions: `packages/api/src/application/**/**.entity.json`.
+- API models/types: `packages/api/src/application/**/**.model.ts`, `*.types.ts`.
+- Generated API files: `packages/api/src/application/sonamu.generated*`, `packages/web/src/services` when present, generated route/client files.
+- Dashboard components: `packages/web/src/components/qgrid/*`.
+- Dashboard routes: `packages/web/src/routes/*`.

package/skills/qgrid/references/request-log-run-lifecycle.md

@@ -0,0 +1,76 @@
+# Request Log Run Lifecycle
+
+Use this reference when changing request logging, tool-call loop logging, telemetry logger integration, request log steps, or dashboard metrics.
+
+## Modes
+
+qgrid query supports `logMode`:
+
+- `auto`: save one request_log after a simple request succeeds.
+- `run`: create/update a run and append steps for multi-step/tool-call flows.
+- `none`: no automatic logging.
+
+If `logMode` is omitted, `qgrid.frame.ts` uses `run` when `isStep` is true and `auto` otherwise.
+
+## Query flow
+
+For `logMode: "run"`:
+
+1. `beforeQuery(args)` creates or extends a run.
+2. `QgridDispatcher.query` or `queryStream` executes the provider call.
+3. `afterQuery(...)` records result/step data and returns `runContext`.
+4. qgrid merges lifecycle `requestLogId` with provider `threadCoord`.
+5. Errors call `finishRunWithError`; stream close can call abort handling.
+
+For `auto`:
+
+- qgrid saves a single request log row after the provider returns.
+- It records token name, project name, model, prompts, response, usage, duration, TTFT, driver cost, image cost estimate, effort, history, status, tool-call count, and image-generation flag.
+- Image results are also appended as synthetic `image_generation` tool-call steps so the detail page can inspect the generated image and pricing assumption.
+
+## Tool-call loop
+
+The AI SDK provider tracks pending tool-call IDs. When the next AI SDK call contains all required tool results, it sends:
+
+- existing `runContext`
+- `toolResults`
+- `logMode: "run"`
+
+qgrid converts tool results into continuation input for providers. Cold fallback still includes a "continue using these results" text input.
+
+Tool calls are produced through qgrid structured-output emulation, not native provider tool calling. The request log lifecycle records the emulated generate step, pending tool-call step rows, tool results on follow-up, and the final generate step. For full semantics, read `tool-calling-and-multiturn.md`.
+
+## Usage fields
+
+Stored request log usage uses qgrid-standard semantics:
+
+- `input_tokens`: total input, including cache read/write.
+- `cache_read_tokens`: cached input read.
+- `cache_creation_tokens`: prompt cache write input.
+- `output_tokens`: output tokens.
+- `cost_usd`: integer micro-USD in DB; displayed USD is `cost_usd / 1_000_000`.
+- `image_cost_usd`: integer micro-USD estimate for Codex image generation output.
+- `image_cost_method`: string such as `assumed:gpt-image-2:medium:1536x1024:png`.
+
+OpenAI/Codex: use per-turn `.last` usage from `thread/tokenUsage/updated`.
+
+Anthropic: normalize native mutually exclusive categories by summing input + cache creation + cache read into total input.
+
+For image requests, keep `cost_usd` as the Codex driver model token cost. Image output cost is separate because qgrid observes Codex's `image_generation` result, not the OpenAI Images API usage object. Treat `image_cost_usd` as a price-table estimate that may be inaccurate if Codex changes its underlying image accounting.
+
+## Legacy normalization
+
+`RequestLogModel` normalizes legacy Anthropic rows where stored `input_tokens` may not include cache read/write. Keep this in mind when changing cost or display logic.
+
+## TTFT
+
+TTFT is tracked by wrapping first provider delta:
+
+- OpenAI: first `item/agentMessage/delta`.
+- Anthropic: first text or structured partial JSON delta.
+
+If missing, qgrid maps TTFT to `0` in `QueryOutput` and nullable/optional places as appropriate.
+
+## Logger integration
+
+`packages/ai-sdk/src/logger.ts` lets non-qgrid providers write logs into qgrid. It skips model provider `qgrid` to avoid double logging. Preserve stale-run cleanup because AI SDK telemetry may emit start without a final event on provider failures.