@cartanova/qgrid-cli 2.7.1 → 2.7.3

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

@@ -64,14 +64,8 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 
 | Env | Default | Meaning |
 |---|---:|---|
-| `QGRID_OPENAI_AUTOSCALE` | enabled | Set to `"false"` or `"0"` to disable demand expansion and scale-down, keeping capacity fixed at the minimum. Fixed-mode health maintenance still replaces missing or terminal workers. |
-| `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` | `1` | Steady-state minimum worker slots maintained for each active OpenAI token. Transient restarts keep their slot; terminal or missing slots are replaced. Clamped to 1..20. |
-| `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` | `3` when autoscaling | Maximum workers per active OpenAI token. It cannot be lower than the resolved minimum and is hard-capped at 20. When autoscaling is disabled, the maximum equals the minimum. |
-| `QGRID_OPENAI_SCALE_INTERVAL_MS` | `5000` | OpenAI pool health, idle-thread cleanup, and demand autoscaling evaluation interval. Clamped to 250..300000 ms. |
-| `QGRID_OPENAI_SCALE_DOWN_IDLE_MS` | `600000` | Idle time before an excess worker becomes eligible for scale-down. Clamped to 1000 ms..24 hours. |
-| `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. Clamped to 1..32 GiB; the upper bound is an operator-typo guard, not an OOM-safety guarantee. |
-| `QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB` | `20` | Refuse scale-up when current host available memory is below this value. Clamped to 0..64 GiB. |
-| `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
+| `QGRID_OPENAI_TRANSPORT` | `websocket` | OpenAI transport selector (`https` or `websocket`). Invalid values fail at dispatcher configuration time. This is the only OpenAI runtime knob; there is no concurrency cap. |
+| `QGRID_OPENAI_AUTOSCALE` / `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` / `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` / `QGRID_OPENAI_PERMITS_PER_TOKEN` | ignored | Removed. OpenAI requests run uncapped like Anthropic (stateless per-request execution); setting these has no effect. |
 | `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
@@ -90,11 +84,10 @@ On shutdown, it stops provider dispatchers and the token subscriber.
 
 ### Runtime settings
 
-Some env values are editable at runtime through the dashboard's Settings page, backed by the `settings` table (key-value). Resolution order is DB → env → code default: env stays as a fallback so a deploy that has not written any setting yet keeps working exactly as before. `loadSettings()` runs in `onStart` before the dispatchers are constructed, since the OpenAI pool reads its worker counts in its constructor.
+Some env values are editable at runtime through the dashboard's Settings page, backed by the `settings` table (key-value). Resolution order is DB → env → code default: env stays as a fallback so a deploy that has not written any setting yet keeps working exactly as before.
 
-- Editable: OpenAI autoscale and min/max workers per token, the worker memory guards, Slack delivery control (master switch, reminder on/off, reminder interval, quiet-hours window, weekend behaviour), and the Slack channel/user-map/bot-token. `SETTING_DEFS` in `setting.constant.ts` is the single definition — key, env name, type, bounds, and whether the change applies immediately or needs a restart. The `settings` table itself (`setting.entity.json`) only stores `(key, value)` strings; everything the UI needs to render and validate a key lives in that constant, not in the schema.
+- Editable: Slack delivery control (master switch, reminder on/off, reminder interval, quiet-hours window, weekend behaviour), and the Slack channel/user-map/bot-token. `SETTING_DEFS` in `setting.constant.ts` is the single definition — key, env name, type, bounds, and whether the change applies immediately or needs a restart. The `settings` table itself (`setting.entity.json`) only stores `(key, value)` strings; everything the UI needs to render and validate a key lives in that constant, not in the schema.
 - Not editable: anything needed before the server can read its own database (`QGRID_DB_*`, `HOST`, `PORT`, `NODE_ENV`). These are exposed read-only on the same page so an operator can confirm which environment they are looking at; the DB password is masked.
-- Worker settings are marked `restart` because `resolveOpenAIWorkerPoolConfig` is called once in the dispatcher constructor. Changing them writes to the DB but does not resize a running pool. `POST /api/setting/restartServer` is how those land without an SSH session.
 
 ### Restart from the dashboard
 
@@ -136,7 +129,7 @@ This allowlist preserves anonymous inference and logger database writes for SDK
 
 ### Readiness during startup
 
-HTTP listening opens before the dispatchers finish starting, so requests can arrive while a provider is still unavailable. On dev0 that window is 1–2 minutes: 25 OpenAI workers spawn at `SPAWN_INTERVAL_MS` apart, plus codex process init.
+HTTP listening opens before the dispatchers finish starting, so requests can arrive while a provider is still unavailable. OpenAI startup loads token metadata and creates no Codex child processes.
 
 - `QgridDispatcher.startupState` tracks each provider as `starting` → `ready` or `failed`. A request for an unready provider throws `ServiceUnavailableException` (503, with a `Retry-After` header) while starting, and `InternalServerErrorException` (500) once initialization has failed — retrying helps in the first case and never in the second. Both used to be `QuotaError`, which told callers their tokens were exhausted and gave them nothing to act on.
 - `GET /api/qgrid/health` reports `ready` plus per-provider state. A 200 alone does not mean requests will succeed; read `providers` for that.
@@ -145,4 +138,4 @@ HTTP listening opens before the dispatchers finish starting, so requests can arr
 ## OAuth callbacks
 
 - Anthropic OAuth: loopback dashboards use `/callback` on the qgrid server (base derived per request from `Origin`, falling back to `X-Forwarded-Host`/`Host`). Remote dashboards cannot use a public callback (client redirect-URI allowlist), so `oauthStart` returns `mode: "code"` with the console callback and the user pastes the shown `code#state` into the dashboard (`oauthComplete`). No env configuration either way; direct non-HTTP calls fall back to localhost and `PORT`.
-- OpenAI OAuth is handled by Codex app-server's own callback flow and completed through qgrid's OpenAI OAuth APIs.
+- OpenAI OAuth uses qgrid's direct PKCE authorize/callback flow and direct token exchange.

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

@@ -30,7 +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.
+- 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. For non-stream calls, the qgrid SDK may derive its own request-scoped Undici header/body budget from that explicit qgrid value (`timeoutMs + 60s`), but must not mutate the global dispatcher or pretend the original AI SDK timeout number is available.
 - `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.
@@ -74,26 +74,18 @@ Key decisions:
   behavior, never to leaked envelope text. See
   `references/tool-calling-and-multiturn.md` (Streaming With Tools).
 
-## 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`
+## OpenAI Direct Codex Runtime
 
 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`.
+- OpenAI uses direct HTTPS `POST` to the private ChatGPT Codex Responses backend and decodes SSE. It does not spawn Codex child processes.
+- Direct PKCE OAuth, refresh, and `wham/usage` quota lookup replace delegated runtime calls. Generation and quota requests send Codex CLI identity headers.
+- Requests run uncapped, matching the Anthropic runtime: transport is a single HTTPS/WS request, so no local resource justifies a cap, and upstream limits are the backend's responses. The worker-era permit/queue layer was removed once this became clear.
+- Every turn sends full Responses-format history. A model-scoped opaque value derived from `sessionKey` is forwarded as `prompt_cache_key`; it is not a provider thread address.
+- `AbortSignal` cancellation covers queue wait, retry delay, and active HTTPS transport.
+- The transport interface is independent of HTTPS so a future WebSocket implementation can preserve dispatcher behavior.
+- The backend is private and unstable. Mocked protocol tests do not establish live provider compatibility.
+- OpenAI cached tokens are included in `input_tokens`. Cache-hit denominator is `input_tokens`, not `input + cache_read + cache_creation`.
 
 ## Anthropic/Claude Code Runtime
 
@@ -111,7 +103,7 @@ Sources:
 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.
+- Anthropic is cold-only. It does not use OpenAI `sessionKey` affinity 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.
 - **qgrid does not pass `--json-schema` to Claude Code (SON-532, 2026-08).** CC's mode is not
@@ -151,7 +143,7 @@ Key decisions:
 - 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.
+- OpenAI applies the gate during token selection. An affinity-preferred token over threshold must fall back to another eligible token when possible.
 
 ## Weighted Token Routing
 
@@ -165,8 +157,8 @@ Key decisions:
 - `tokens.weight` is a per-token integer from 1 to 100 defaulting to 1. It is a relative routing share for new requests, not an enable/disable switch. Weight 0 is invalid; disabling a token stays on `active`.
 - Both providers share one smooth weighted round-robin selector in the provider common layer. The selector knows only token ids, weights, and current scores. Dispatchers own quota, lifecycle, and worker availability, and pass in only the eligible token id set per selection. Do not teach the selector about credentials, workers, or queues.
 - The quota threshold gate runs before weighted selection. An over-threshold token receives no weighted assignment regardless of weight, and the schedule is computed from the remaining eligible tokens.
-- OpenAI thread reuse stays pinned to its original worker and neither reads nor mutates weighted-selector state. Cache affinity intentionally beats weight distribution; only cold requests are weighted.
-- OpenAI routing is work-conserving. A token whose workers are all busy is omitted from the current selection round instead of making requests wait for the heavy-weight token. Queue drain re-runs weighted selection for the head item; the previous released-worker shortcut was removed because it bypassed weighting.
+- OpenAI cache affinity prefers its prior token whenever that token remains eligible; otherwise routing uses weighted selection.
+- Busyness never excludes a token: with no concurrency cap there is no queue and no drain.
 - Candidate collection, selector mutation, and worker acquisition must run without an intervening `await`. A weighted score is consumed only when the dispatcher can commit the assignment synchronously; this is what keeps concurrent Anthropic selections spread correctly.
 - Selector scores reset when token topology or configured weights change. Temporary ineligibility from quota or busy workers only excludes the token from that selection's candidate set and does not reset schedule state.
 - Weight-change notification is owned by the versioned migration trigger (`tokens_weight_changed_upd`); the boot-time trigger setup SQL intentionally excludes `weight` from its WHEN clause, and a test pins this so exactly one trigger fires per weight-only change.
@@ -228,7 +220,7 @@ 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.
+- Image turns send full input directly and retain no provider conversation state. This prevents base64 payloads from entering reusable state.
 - 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. Reference images are accepted through AI SDK multimodal message parts only on the `imageGeneration` path, and are transported as JSON data URLs with SDK-side size guarding.
 - `imageGenerationOptions` currently supports quality and size. The worker instruction and request-log pricing assumption use `gpt-image-2`, with defaults `medium` and `1536x1024`.

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

@@ -19,7 +19,7 @@ The project workflow is documented in `docs/WORKFLOW.md`.
 
 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.
+- OpenAI full-history replay and opaque prompt-cache affinity.
 - Claude Code fresh spawn.
 - structured output strictness.
 - Anthropic usage categories.

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

@@ -1,184 +1,67 @@
-# OpenAI Codex Runtime
+# OpenAI Direct 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.
+Use this reference before changing OpenAI transport, concurrency, routing, prompt-cache affinity, OAuth, quota lookup, image generation, or cancellation.
 
-## Contents
+## Source files
 
-- Process model
-- Codex configuration
-- Initialization and auth
-- Thread and turn flow
-- Thread retention
-- Queue and routing
-- Usage and notifications
-- Streaming
-- Image generation
+- Dispatcher and token routing: `packages/api/src/utils/providers/openai/openai-dispatcher.ts`.
+- Direct client and transport interface: `openai-direct-client.ts`.
+- Request, identity headers, and normalized events: `openai-backend-protocol.ts`.
+- SSE decoding: `openai-sse.ts`.
+- Direct PKCE OAuth and refresh: `openai-oauth.ts`, `openai-refresh.ts`.
+- Direct quota lookup: `openai-quota.ts`.
+- Provider integration and history: `packages/api/src/application/qgrid/qgrid.dispatcher.ts`, `conv-routing.ts`.
 
-## Process model
+## Private backend boundary
 
-OpenAI tokens use persistent Codex app-server workers.
+OpenAI requests go directly to `https://chatgpt.com/backend-api/codex/responses` with an HTTPS `POST`. The response is an SSE stream. Qgrid sends the subscription bearer token, ChatGPT account id, content negotiation fields, and Codex CLI `originator` and `User-Agent` identity headers.
 
-- 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: autoscaling defaults to 1–3 workers per active token, with a hard cap of 20.
-- Worker id: `tokenId * 100 + workerIndex`.
-- Worker home: `/tmp/qgrid-codex/${tokenId}-${workerIndex}` when `workerIndex` exists.
-- Worker cwd: `${CODEX_HOME}/cwd`.
+This is a private ChatGPT backend, not a documented public API. Its URL, accepted fields, required headers, event shapes, quota response, and availability can change without notice. Unit tests use mocked HTTP/SSE fixtures. Do not describe those tests as live provider verification.
 
-Workers are persistent. Turns are single-flight per worker (`busy` flag). When all eligible workers are busy, requests enter an in-memory queue.
+`QGRID_OPENAI_TRANSPORT=https|websocket` selects the transport once when dispatcher configuration is resolved; WebSocket is the default and other values fail fast. WebSocket mode scheme-swaps the Responses HTTPS URL to `wss` and reuses one connection for sequential requests with the same prompt-cache affinity. Requests without cache affinity use one connection each. HTTPS remains available but does not preserve prompt-cache connection affinity. Qgrid does not replay ambiguous requests. Only a definitively rejected 401 handshake may refresh credentials and reconnect once.
 
-Autoscaling is enabled unless `QGRID_OPENAI_AUTOSCALE` is `"false"` or `"0"`. It evaluates the pool every 5 seconds by default, starts scale-down after 10 idle minutes, and refuses scale-up when either memory guard would be crossed:
+The active HTTPS/SSE request receives the composed caller/timeout signal. Qgrid never replays a POST after a transport, 429, or 5xx failure because acceptance is ambiguous. A 401 may refresh credentials and retry once because the backend rejected that attempt.
 
-- estimated qgrid worker RSS: `0.71 + 0.157 * totalWorkerCount` GiB, limited to 16 GiB by default;
-- current host available memory at scale-up evaluation time, required to be at least 20 GiB by default.
+## Request and stream behavior
 
-All sizing and memory limits can be configured within the bounds listed in `cli-env-and-server-boot.md`.
+Every request sends `store: false`, `stream: true`, full Responses-format history, and `include: ["reasoning.encrypted_content"]`. Optional reasoning, verbosity, service tier, structured-output schema, image generation, and `prompt_cache_key` fields are added when requested.
 
-Pool health maintenance is separate from demand autoscaling:
+`normalizeOpenAISSE` handles chunk boundaries and converts private backend events into qgrid's normalized text, output-item, image, usage, completion, and error events. The HTTPS transport may retry a failure only before any visible event. It refreshes credentials once on a pre-event 401. Once output is visible, an error is returned rather than replaying a request that may already have produced output.
 
-- Every active token maintains the configured minimum worker slots even when demand autoscaling is disabled.
-- An initial all-worker spawn failure is retried by the periodic pool evaluation.
-- A transiently restarting worker keeps its slot so qgrid does not create a duplicate process or worker index.
-- After a worker exhausts its three restart attempts, it emits a one-shot terminal signal. The dispatcher removes that exact worker and repairs the token back to its configured minimum.
-- Minimum repair follows the same operator commitment as startup and is not blocked by the above-min memory guards. Demand expansion above the minimum still uses both guards.
-- A broken token's failed minimum repair does not block healthy tokens from scaling up or down.
+The caller's `AbortSignal` is passed through token selection (including a pending quota lookup) and `fetch`. Cancellation aborts active transport work.
 
-## Codex configuration
+## Token routing
 
-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.
+Execution is stateless per request, the same model as the Anthropic runtime: select a token, send the request. There is no concurrency cap, no permit, and no queue — transport is a single HTTPS/WS request, so nothing local is scarce, and upstream limits surface as backend responses (429 etc.), which qgrid does not retry.
 
-Disabled by config:
+Selection picks among active, quota-eligible tokens: a cache-affinity-preferred token is used when eligible; otherwise smooth weighted round-robin (token weights set relative share; affinity hits do not advance weighted state). If every active token is over its quota threshold, the request fails with `QuotaThresholdExceededError`; with no active tokens it fails with `NO_OPENAI_WORKERS`.
 
-- 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
+Quota lookup failures fail open. A successful lookup over a token's configured threshold excludes that token until the cached usage is refreshed.
 
-Spawn env is intentionally small:
+## Full-history replay and cache affinity
 
-- `PATH`
-- `TMPDIR`
-- `CODEX_HOME`
-- `CODEX_EXEC_SERVER_URL=none`
+Qgrid no longer retains an OpenAI provider thread. It sends the full conversation history on every turn. The AI SDK derives a model-scoped opaque value from `sessionKey`; the server validates and forwards it as `prompt_cache_key`.
 
-Do not re-enable built-in Codex tools/instructions unless the user explicitly asks for agentic Codex behavior.
+The legacy `threadCoord` and `runContext` shape remains for compatibility, but it carries cache affinity rather than a process or provider-thread address. Do not infer worker lifetime, thread presence, or delta-only replay from `workerId`, `threadId`, or `epoch`.
 
-## Initialization and auth
+Stable affinity can improve provider prompt-cache reuse only when the serialized prefix remains stable. System prompt, tool/schema framing, message order, and model changes can still prevent a cache hit. Image generation sends full input and retains no provider conversation state.
 
-Worker initialization:
+## OAuth, identity, refresh, and quota
 
-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.
+OpenAI browser login is implemented directly with authorization-code PKCE:
 
-If Codex asks to refresh ChatGPT auth tokens, qgrid handles it through `handleChatgptAuthTokensRefresh(tokenId)`.
+1. Generate verifier, SHA-256 challenge, and state.
+2. Build the OpenAI authorize URL with Codex CLI-compatible client, scope, originator, and simplified-flow fields.
+3. Validate pending state on callback.
+4. Exchange the code directly at `https://auth.openai.com/oauth/token`.
+5. Parse account id and plan claims, then store access, refresh, and id tokens.
 
-## Thread and turn flow
+Refresh posts the stored refresh token directly to the token endpoint, deduplicates concurrent refreshes, and persists rotated credentials. Generation sends Codex CLI identity headers built by `buildCodexIdentityHeaders`.
 
-Cold path:
+Quota is fetched directly from `https://chatgpt.com/backend-api/wham/usage` with the same identity headers. Qgrid normalizes the primary usage window and caches it for 60 seconds. This private response format has the same stability warning as the Responses endpoint.
 
-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.
+## Usage and images
 
-Reuse path:
+OpenAI usage reports total input, cached input, output, reasoning, and total tokens for the request. Preserve cached input as a subset of input; do not add it to input again when computing cache-hit rate.
 
-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 runs from the dispatcher's periodic health evaluation and also lazily before creating a new thread.
-
-Eviction is two-sided. Removing a thread from the reuse map only stops qgrid from routing turns to it; the thread itself stays resident inside the codex process. Codex auto-unloads a thread from memory only when it has zero subscribers and has been idle for 30 minutes (`THREAD_UNLOADING_DELAY`, hardcoded upstream), and `thread/start` auto-registers the creating connection as a permanent subscriber. So on every eviction (TTL sweep or LRU cap) qgrid also sends fire-and-forget `thread/unsubscribe`, which arms that 30-minute unload. Image one-shot threads never enter the reuse map, so they are unsubscribed immediately after their turn completes or fails.
-
-Periodic cleanup scans only ready, idle workers. It must never unsubscribe from a busy worker because turn notifications would stop reaching qgrid and the request could hang. Reusable thread `lastUsedAt` is refreshed when a turn finishes, so a long-running turn receives a full idle TTL after completion. The periodic pass keeps up to 16 threads; the pre-create lazy pass reserves one slot so the newly created thread still leaves the worker at no more than 16.
-
-Once `thread/start` returns, `createThread` owns cleanup until history injection and reuse-map registration finish. Any failure during that partial-creation window removes tentative metadata and immediately unsubscribes the thread. Otherwise neither turn cleanup nor the lazy sweep can see it, and repeated failed cold-history requests accumulate permanently subscribed threads.
-
-Do not send turns to an unsubscribed thread: its notifications no longer reach qgrid's connection, so the turn would hang until timeout. Map removal must always precede or accompany unsubscribe.
-
-`thread/archive` is not usable here: it requires a rollout file and ephemeral threads have none ("no rollout found"). Without unsubscribe, worker RSS grows without bound (measured ~2 MiB resident per 512 KB injected history; dev0 incident reached ~1.28 GB per worker in two days).
-
-## Queue and routing
-
-OpenAI worker selection:
-
-- Prefer reuse worker when a valid reuse coordinate exists. Successful reuse bypasses weighted selection and does not read or mutate its state.
-- Otherwise cold selection is two-level: group quota-eligible ready active workers by token, keep only tokens with at least one idle worker, choose the token with the shared smooth weighted round-robin selector (`providers/common/smooth-weighted-round-robin.ts`, driven by `tokens.weight`), then rotate a per-token worker cursor inside the chosen token.
-- Selection is work-conserving: a token whose workers are all busy is omitted from that selection round, so an idle lower-weight token receives the request immediately instead of waiting for the heavy token.
-- If no eligible worker is idle, enqueue. Queue drain re-runs the same weighted cold selection; it must not hand the queue head to the worker that happened to finish first.
-- If active token metadata exists but every worker is starting, restarting, or otherwise unavailable, enqueue instead of returning `NO_OPENAI_WORKERS`. Queue admission immediately requests both a drain and pool evaluation so a recovered worker cannot lose its wake-up.
-- Return `NO_OPENAI_WORKERS` immediately only when there is no active OpenAI token candidate. A zero-ready recovery request still uses the normal 60-second queue timeout.
-- Queue timeout: 60 seconds.
-- Max queue size: 50.
-
-Scale-down uses one pool-wide quiet clock, not per-worker timers. With an empty queue and no new request for `scaleDownIdleMs`, each evaluation removes at most one highest-index idle excess worker per token. Busy workers are never removed, and repeated evaluations stop exactly at the configured `minWorkersPerToken`.
-
-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.
-- AI SDK reference images are accepted only on this image-generation path. They arrive as qgrid `input` image data URLs and should be compressed/resized by callers before JSON transport.
-- 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.
-- Codex may return multiple completed image outputs. qgrid maps each one to a separate image content part and a synthetic `image_generation` request-log tool step.
-
-Before modifying this area, inspect latest docs/plans/brainstorms and current tests.
+Image generation is opt-in and non-stream at the AI SDK interface. The backend still delivers its response through SSE. Returned base64 images become AI SDK PNG file parts. Recorded image cost remains an estimate based on qgrid's configured public image price table because this route does not expose exact image-tool billing.

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

@@ -1,10 +1,10 @@
 # Prompt Cache And Usage
 
-Use this reference for `sessionKey`, `threadCoord`, prompt cache, request-log usage metrics, and cost accounting.
+Use this reference for `sessionKey`, opaque cache affinity, request-log usage metrics, and cost accounting.
 
-## qgrid thread coordinates
+## OpenAI affinity coordinates
 
-Client-facing `QgridThreadCoord`:
+The public compatibility shape remains `QgridThreadCoord`:
 
 ```ts
 {
@@ -15,95 +15,59 @@ Client-facing `QgridThreadCoord`:
 }
 ```
 
-- 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.
+These names are legacy. On the direct OpenAI route, the coordinate does not identify a worker process or provider thread. The AI SDK derives a model-scoped opaque SHA-256 value from `sessionKey`, stores the compatibility coordinate briefly, and returns it through `runContext`. The server validates the opaque value and forwards it as `prompt_cache_key`.
 
-## AI SDK `sessionKey`
+Anthropic models do not store or replay this coordinate.
 
-`packages/ai-sdk/src/index.ts` stores `threadCoord` in a module-level map by `sessionKey` for 10 minutes.
+## Full-history replay and cache behavior
 
-- 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 receives the complete Responses-format conversation history on every request. There is no delta-only turn, process pinning, thread retention, or provider-thread expiry.
 
-## OpenAI/Codex cache behavior
+A cache hit can occur when both the opaque affinity key and serialized prefix stay stable. Important cache breakers include:
 
-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.
+- a different model or system prompt;
+- changed tool or output-schema framing;
+- changed message order or normalization;
+- provider-side cache expiry or policy changes;
+- private-backend protocol changes.
 
-Cache hit requires:
+Affinity is a hint, not a cache-hit guarantee. The direct endpoint is a private ChatGPT backend and can change without notice. Mocked tests verify qgrid's key derivation and request mapping, not live provider cache behavior.
 
-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.
+New requests use smooth weighted routing across quota-eligible tokens. A compatible coordinate prefers its prior token whenever that token stays eligible, preserving the same opaque affinity key and full history.
 
-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.
+## Anthropic cache behavior
 
-Reuse is decided before weighted token routing and stays pinned to its original worker: a successful reuse neither consumes nor advances the weighted schedule. Cache affinity intentionally beats weight distribution; only cold requests are weighted.
-
-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`.
+Anthropic uses a fresh Claude Code process 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`.
-- Since SON-532, qgrid appends the schema/tool-envelope contract to the end of the system
-  prompt (no `--json-schema`). A stable schema keeps the system prefix stable and cacheable
-  across requests; a schema that changes per request invalidates the prefix cache from the
-  contract onward. Keep caller schemas deterministic (no timestamps or per-request IDs inside).
+- full history is replayed through stream-json after flattening;
+- cache write/read can be eventually consistent;
+- Claude Code OAuth token cache behavior has provider-specific quirks documented in `docs/solutions`;
+- schema/tool-envelope text is appended to the system prompt, so changing it changes the cacheable prefix.
 
 ## Usage normalization
 
-qgrid's standard usage meaning:
+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.
+- `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:
+OpenAI Responses usage already reports input as total input including cached input. Anthropic's native input, cache creation, and cache read categories are mutually exclusive, so qgrid sums them into standard total input while preserving cache subfields.
 
-- `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.
+Cache-hit rate uses `input_tokens` as its denominator. Do not add cache subfields again.
 
 ## Cost accounting
 
-`packages/api/src/utils/providers/common/model-cost.ts` contains model price fallback.
+`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 responses can split cache creation into `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`; preserve that split and price each TTL separately.
-- Claude Code automatically requests 1-hour cache TTL for subscription OAuth and 5-minute TTL for API-key or usage-credit paths. Only legacy responses without a TTL breakdown use the subscription path's 1-hour rate as qgrid's fallback.
-- Persist per-step `cost_usd`, `cost_source`, and the 5m/1h split. New request logs use that exact stored cost; only legacy rows with no `cost_source` are repriced from the current table.
-- When Fable refuses and Claude Code serves Opus, prefer Claude Code's positive `total_cost_usd`. Persist Fable as the requested model and Opus as the serving model instead of pricing the combined turn as Fable.
-- 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.
+- OpenAI image generation stores a separate `image_cost_usd` estimate because the direct private route does not expose exact image-tool billing.
+- Anthropic prefers a positive Claude Code `total_cost_usd`; otherwise qgrid uses its price table.
+- Preserve Anthropic's five-minute and one-hour cache-creation token split and price each TTL separately.
+- Persist per-step cost, source, and cache-write split. Only legacy rows without a source are repriced.
+- OpenAI long-context surcharge applies to the whole request when input exceeds the configured threshold.
+
+When changing models or prices, verify against current official pricing before editing the table. Do not attribute the configured OpenAI context or cost behavior to the removed app-server runtime.

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

@@ -4,26 +4,26 @@ Use this reference when comparing OpenAI and Anthropic behavior, debugging provi
 
 | Topic | OpenAI via Codex | Anthropic via Claude Code |
 |---|---|---|
-| Process lifetime | Persistent `codex app-server` workers | Fresh `claude` process per request |
-| Worker pool | Autoscaling pool per token, default 1–3 and hard-capped at 20 | No workers; in-memory token pool only |
-| Worker id | `tokenId * 100 + 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 | Smooth weighted RR picks a quota-eligible token with an idle worker, then a per-token worker cursor; reuse bypasses weights | Smooth weighted RR over quota-eligible tokens per request |
+| Process lifetime | No child process; direct HTTPS/SSE request | Fresh `claude` process per request |
+| Worker pool | None; in-memory token pool only | None; in-memory token pool only |
+| Worker id | Legacy coordinate field carries token id | `tokenId` |
+| Epoch | Legacy compatibility value; not a process generation | Always `0` |
+| Request concurrency | Uncapped; stateless HTTPS/WS request per call | Uncapped; fresh process per request |
+| Token selection | Smooth weighted RR over quota-eligible tokens; valid affinity may prefer its token | Smooth weighted RR over quota-eligible tokens per request |
 | 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 ""` on every call |
+| Thread/session | No provider thread retained | Fresh Claude `--session-id` per request |
+| `sessionKey` | AI SDK derives and replays opaque `prompt_cache_key` affinity | AI SDK intentionally disables storage/replay |
+| Multi-turn | Full Responses-format history is sent on every request | Fresh spawn receives flattened full history through stream-json |
+| Cache key | Opaque model-scoped affinity key plus stable serialized prefix | Anthropic prefix cache via Claude Code; fresh spawn still can cache stable prefixes |
+| Built-in tools | Direct Responses request includes only requested qgrid tools/options | Claude tools disabled via `--tools ""` on every call |
 | AI SDK tools | Emulated via qgrid structured output schema, then mapped to AI SDK `tool-call` content | Emulated via envelope contract rendered as prompt text (SON-532); reply parsed by `parseEnvelope`; not native Claude Code tools |
-| Structured output | Codex `outputSchema` passed to `turn/start` (strictified, constrained decoding); schema changes can affect prefix cache | Schema delivered as prompt text appended to the system prompt (no `--json-schema`, no strictify); server strips fences; validation is the consumer's |
-| Usage accounting | Codex usage already reports `inputTokens` including cached input | Native Anthropic categories are mutually exclusive; qgrid sums them into total input |
+| Structured output | Strict JSON schema is sent in the direct Responses request; schema changes can affect prefix cache | Schema delivered as prompt text appended to the system prompt (no `--json-schema`, no strictify); server strips fences; validation is the consumer's |
+| Usage accounting | Responses usage reports input 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 | Implemented as an opt-in Codex `image_generation` tool path; non-stream only | Explicitly unsupported |
+| Settings isolation | Per-token credentials in memory | Shared project cwd plus per-token `CLAUDE_CONFIG_DIR` |
+| Streaming close | `AbortSignal` cancels queue wait, retry delay, or `fetch` | Abort kills the fresh child process |
+| Image generation | Implemented as an opt-in direct Responses `image_generation` tool path; non-stream only | Explicitly unsupported |
 
 ## Routing contract
 
@@ -48,7 +48,7 @@ Both providers return `GenerateResult` with:
 - 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`.
+`qgrid.dispatcher.ts` maps this into `QueryOutput`, applies tool-call emulation, calculates fallback cost, and keeps the legacy `QgridThreadCoord` response shape for opaque OpenAI cache affinity.
 
 Both providers receive strictified output schemas from `buildStrictOutputSchema`.