@cartanova/qgrid-cli 2.7.0 → 2.7.2

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,92 +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`.
-- Avoid putting volatile schema text into the system prompt. qgrid uses `--json-schema` / `StructuredOutput` for structured output.
+- 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 ""`; `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 |
+| 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 | 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`.
 

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

@@ -18,12 +18,12 @@ Use this map to orient qgrid work quickly.
 ## Runtime hot spots
 
 - Provider router: `packages/api/src/application/qgrid/qgrid.dispatcher.ts`.
-- Conversation/thread reuse: `packages/api/src/application/qgrid/conv-routing.ts`.
+- Full-history and prompt-cache-affinity routing: `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/*`.
+- OpenAI direct backend transport, OAuth, quota, and dispatcher: `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`.
 - Weighted token selection: `packages/api/src/utils/providers/common/smooth-weighted-round-robin.ts`.

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

@@ -74,7 +74,7 @@ Stored request log usage uses qgrid-standard semantics:
 - `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 uses per-turn `.last` usage from `thread/tokenUsage/updated`.
+OpenAI uses the completed Responses event's per-request usage fields.
 
 Anthropic normalizes native mutually exclusive categories by summing input + cache creation + cache read into total input. Prefer positive Claude Code `total_cost_usd`; otherwise calculate from the actual serving model and TTL split.
 
@@ -82,6 +82,16 @@ For image requests, keep `cost_usd` as the Codex driver model token cost. Image
 
 Reference images for image generation are not stored in `request_logs.user_prompt`; that field remains the text prompt. For inspection in the detail view, qgrid stores reference image metadata/base64 in the synthetic `image_generation` step's `tool_args.inputImages`. If Codex returns multiple image outputs, store `inputImages` only on the first synthetic image tool step so multi-output logs do not duplicate the same input payload on every output.
 
+## Structured output fields
+
+Structured output requests (those carrying a `jsonSchema`) persist three related fields:
+
+- `json_schema`: the raw JSON Schema text of the request contract. Stored at `createRun`, exposed only through the server-side `responseTypeTs` conversion API (compact `type` declaration + reconstructed zod expression); the detail subset does not carry the raw text.
+- `is_structured`: boolean written at `createRun` from `json_schema` presence. Exists so the list subset can distinguish structured vs plain rows without shipping schema text; it is denormalized, so any future path that writes `json_schema` must set it too.
+- `response_json_ok`: tri-state verdict written at the succeeded `finishRun`. `true`/`false` = structured response parsed/failed `JSON.parse`; `null` = non-structured request, error/aborted run, or a row written before the column existed. The list filter `response_json_broken` matches only explicit `false`.
+
+Reconstructed zod output cannot contain `refine`/`transform` logic — those are lost when the client serializes the schema. Rows written by servers older than 2.7.2 have all three fields empty/false/null.
+
 ## Legacy normalization
 
 `RequestLogModel` normalizes legacy Anthropic rows where stored `input_tokens` may not include cache read/write. Rows with `cost_source = NULL` are legacy and can be repriced from the current table; rows with a source retain their exact stored cost across price/promotion changes.
@@ -90,7 +100,7 @@ Reference images for image generation are not stored in `request_logs.user_promp
 
 TTFT is tracked by wrapping the first provider delta:
 
-- OpenAI: first `item/agentMessage/delta`.
+- OpenAI: first `response.output_text.delta` from the direct Responses stream.
 - Anthropic: first text or structured partial JSON delta.
 
 If missing, qgrid maps TTFT to `0` in `QueryOutput` and nullable/optional places as appropriate.

package/skills/qgrid/references/sonamu-api-web-flow.md

@@ -56,6 +56,10 @@ Provider-qualified ids widen `model_name` and `requested_model_name` from 50 to
 
 Image-generation request logs add `is_image_generation`, `image_cost_usd`, and `image_cost_method`. The list view displays driver plus image cost as the total cost cell; the detail view shows driver cost and image cost separately and renders generated image data URLs from response/tool-step content.
 
+Structured output visibility: the list has an `Fmt` column (`json` badge from `is_structured` vs `text`), a `broken` badge plus a `Broken JSON` checkbox filter driven by `response_json_ok = false`, and the detail page shows a dark Response Type panel (zod expression by default, `type` declaration via toggle) rendered server-side from the stored `json_schema`. Plain-text rows render no panel. Rows written by pre-2.7.2 servers show `text` and never match the broken filter.
+
+The monit tab's vitals strip shows per-provider in-flight counts, an in-flight sparkline, token chips with quota gauges (fed by the dispatcher's 60-second rate-limits cache; `resetsAt` arrives as ms epoch), and a 1-hour per-provider request/error/cache-hit stats line polled separately every 30 seconds.
+
 Reference input images for image generation render in the detail view under the user prompt from the first synthetic `image_generation` step's `tool_args.inputImages`. Keep the prompt itself text-only, redact large base64 in request JSON views, and avoid rendering duplicate input previews for multi-output image turns.
 
 ## Verification

package/skills/qgrid/references/token-auth-quota-lifecycle.md

@@ -20,7 +20,7 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - Anthropic OAuth utilities and usage API: `packages/api/src/application/qgrid/oauth.ts`.
 - Token DB trigger setup: `packages/api/src/application/qgrid/token-trigger-setup.ts`.
 - Token subscriber: `packages/api/src/application/qgrid/token-subscriber.ts`.
-- OpenAI refresh/quota: `packages/api/src/utils/providers/openai/openai-refresh.ts`, `openai-quota.ts`.
+- OpenAI direct OAuth/refresh/quota: `packages/api/src/utils/providers/openai/openai-oauth.ts`, `openai-refresh.ts`, `openai-quota.ts`.
 - Anthropic quota: `packages/api/src/utils/providers/anthropic/anthropic-quota.ts`.
 - Provider token event handlers: `openai-dispatcher.ts`, `anthropic-dispatcher.ts`.
 
@@ -116,36 +116,27 @@ Usage/quota:
 
 ## OpenAI OAuth And Refresh Flow
 
-OpenAI OAuth is delegated to Codex app-server.
+OpenAI OAuth is implemented directly with authorization-code PKCE.
 
 Browser registration:
 
-1. `oauthStartOpenAI(name)` calls `OpenAIDispatcher.startBrowserLogin(name)`.
-2. Dispatcher creates a temporary `CodexAppServerWorker`.
-3. Worker spawns `codex app-server` and calls `account/login/start` with `type: "chatgpt"`.
-4. qgrid returns Codex's `authUrl`.
-5. In the background, dispatcher waits for `account/login/completed`.
-6. Worker reads managed credentials from its `auth.json`.
-7. Existing OpenAI tokens with the same `accountId` are deleted.
-8. qgrid saves a new `provider: "openai"` token.
-9. Temporary worker is killed; pending browser login times out after 5 minutes.
-
-Worker login:
-
-- Normal OpenAI workers call `account/login/start` with `type: "chatgptAuthTokens"`, `accessToken`, `chatgptAccountId`, and optional `chatgptPlanType`.
+1. `oauthStartOpenAI(name)` generates verifier, SHA-256 challenge, and state.
+2. qgrid stores pending state and builds the OpenAI authorize URL with Codex CLI-compatible client, scope, simplified-flow, and originator fields.
+3. The callback validates state and exchanges the code directly at `https://auth.openai.com/oauth/token`.
+4. qgrid parses account id and plan claims from the returned JWTs.
+5. Existing OpenAI tokens with the same `accountId` are deleted.
+6. qgrid saves the access, refresh, and id tokens as a new `provider: "openai"` token.
 
 Refresh:
 
-- Codex can send server-request `account/chatgptAuthTokens/refresh`.
-- qgrid handles it through `handleChatgptAuthTokensRefresh(tokenId)`.
+- qgrid posts the stored refresh token directly to the OpenAI token endpoint through `handleChatgptAuthTokensRefresh(tokenId)`.
 - Refresh is deduplicated per token with an in-flight promise.
 - Refresh has a 5-second minimum interval; too-soon calls read current DB credentials.
 - Refresh token rotation is saved immediately. If DB save fails after rotation, treat it as token-death risk because the old refresh token may already be invalid.
 
 Usage/quota:
 
-- OpenAI quota threshold uses Codex `account/rateLimits/read`.
-- qgrid reads rate limits through a ready worker.
+- OpenAI quota threshold uses direct `GET https://chatgpt.com/backend-api/wham/usage` with Codex CLI identity headers.
 - Rate limit data is cached for 60 seconds.
 - Threshold uses primary `usedPercent`.
 - Usage lookup failure is fail-open for routing.
@@ -192,12 +183,11 @@ Anthropic row changes:
 
 ## Provider Runtime Consequences
 
-OpenAI token changes can create, update, deactivate, or kill persistent Codex workers.
+OpenAI token changes create, update, deactivate, or remove in-memory credential metadata.
 
-- In-place OpenAI worker update is allowed only when account id and plan type match.
-- Otherwise workers are killed and respawned.
-- Weight-only changes never respawn workers; they update token metadata and reset the weighted selector's scores.
-- If no ready active OpenAI workers remain, queued OpenAI requests are rejected.
+- Weight-only changes update token metadata and reset the weighted selector's scores.
+- Credential changes replace the direct client's credentials without spawning a process.
+- If no active OpenAI tokens remain, queued OpenAI requests are rejected.
 
 Anthropic token changes only affect the in-memory token pool because every request fresh-spawns Claude Code.