@cartanova/qgrid-cli 2.3.7 → 2.3.9

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,47 @@
+# Sonamu API And Web Flow
+
+Use this reference for dashboard/API changes.
+
+qgrid dashboard work is usually a Sonamu API/model/generated-client/web change, not an isolated React change.
+
+## Full path to inspect
+
+1. Entity and model definitions in `packages/api/src/application/**`.
+2. API frame/model methods decorated with `@api` or `@stream`.
+3. Generated Sonamu files such as `packages/api/src/application/sonamu.generated*`.
+4. Web API consumers and generated client/types.
+5. Dashboard routes/components in `packages/web/src/**`.
+
+## Common patterns
+
+- Entity fields live in `*.entity.json`.
+- Model methods live in `*.model.ts`.
+- API frame methods for qgrid live in `qgrid.frame.ts`.
+- i18n generated files may change when entity labels or static data change.
+- Web components under `packages/web/src/components/qgrid` consume generated API shapes.
+- The main dashboard sidebar version should stay synced to `packages/cli/package.json`. `packages/web/vite.config.ts` reads that package version and exposes it as `__QGRID_CLI_VERSION__`; `Sidebar.tsx` displays it.
+
+## Request log dashboard
+
+Request log changes usually touch:
+
+- `request-log.entity.json`
+- `request-log.model.ts`
+- `request-log.types.ts`
+- `request-log-step.*`
+- `qgrid-run-lifecycle.ts`
+- `RequestLogTable.tsx`
+- `routes/requests/show.tsx`
+
+Check list and detail views. Avoid loading large text columns in list views unless intentionally needed.
+
+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.
+
+## Verification
+
+After API shape changes:
+
+- Regenerate or inspect generated Sonamu files according to repo workflow.
+- Run targeted API tests.
+- Check web consumers compile against generated types.
+- Verify dashboard display for null/legacy values when changing stored request log fields.

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

@@ -0,0 +1,205 @@
+# Token Auth Quota Lifecycle
+
+Use this reference before changing token storage, OAuth flows, token activation, token subscriber behavior, quota thresholds, usage APIs, or provider token routing.
+
+## Contents
+
+- Source files
+- Token table contract
+- Token APIs
+- Anthropic OAuth flow
+- OpenAI OAuth and refresh flow
+- Token sync and reconcile
+- Provider runtime consequences
+- Quota threshold semantics
+
+## Source Files
+
+- Token model/types: `packages/api/src/application/token/token.model.ts`, `token.types.ts`, `token.entity.json`.
+- qgrid API frame and OAuth endpoints: `packages/api/src/application/qgrid/qgrid.frame.ts`.
+- 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`.
+- Anthropic quota: `packages/api/src/utils/providers/anthropic/anthropic-quota.ts`.
+- Provider token event handlers: `openai-dispatcher.ts`, `anthropic-dispatcher.ts`.
+
+## Token Table Contract
+
+`tokens` stores:
+
+- `provider`: provider string such as `openai` or `anthropic`.
+- `credentials`: JSONB credentials.
+- `name`: display/logging name.
+- `active`: whether provider dispatchers may use it.
+- `ord`: dashboard ordering.
+- `quota_threshold`: nullable integer percentage, validated as 1..100 when present.
+
+On creation, `TokenModel.save` applies default `quota_threshold = 80` unless `id` or `quota_threshold` is already provided.
+
+OpenAI credentials:
+
+```ts
+{
+  accessToken: string;
+  refreshToken: string;
+  idToken?: string;
+  accessTokenExpiresAt: number;
+  idTokenExpiresAt?: number;
+  accountId: string;
+  planType?: string;
+}
+```
+
+Anthropic credentials:
+
+```ts
+{
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  accountUuid: string;
+}
+```
+
+Duplicate account replacement is account-identifier based:
+
+- OpenAI: `credentials.accountId`.
+- Anthropic: `credentials.accountUuid`.
+
+## Token APIs
+
+`QgridFrame` exposes token APIs:
+
+- `addToken(provider, credentials, name)`: saves a token directly.
+- `updateToken(id, name?, quotaThreshold?)`: updates name and/or quota threshold, preserving provider/credentials.
+- `removeToken(id)`: deletes token row.
+- `toggleToken(id)`: flips `active`.
+- `stats()`: reports dispatcher cache stats.
+- `health()`: reports active token cache count and subscriber status.
+- `usage(tokenId?)`: returns provider usage/rate-limit summary.
+
+When updating a token, preserve existing provider and credentials unless intentionally rotating credentials.
+
+## Anthropic OAuth Flow
+
+Anthropic OAuth is implemented directly in qgrid.
+
+1. `oauthStart(name)` generates PKCE verifier/challenge/state.
+2. qgrid builds the Claude OAuth authorize URL with Claude Code-like scopes.
+3. Pending state is cached under `oauth:state:<state>` for 5 minutes.
+4. `/callback` calls `handleOAuthCallback(code, state, reply)`.
+5. qgrid exchanges the code for tokens.
+6. Existing Anthropic tokens with the same `accountUuid` are deleted.
+7. qgrid saves a new `provider: "anthropic"` token.
+
+`QGRID_PUBLIC_BASE_URL` controls the public callback base. If unset, callback defaults to `http://localhost:${PORT}/callback`.
+
+Refresh:
+
+- `refreshToken(token)` uses the stored refresh token and `refreshAccessToken`.
+- Refreshed credentials are saved back through `TokenModel.save`.
+- `usage()` refreshes expired Anthropic access tokens before usage lookup when a refresh token exists.
+- `AnthropicDispatcher` also preemptively refreshes when expiration is within 60 seconds.
+
+Usage/quota:
+
+- Usage API is `https://api.anthropic.com/api/oauth/usage`.
+- qgrid caches Anthropic usage by access-token suffix for 60 seconds.
+- Quota threshold uses `five_hour.utilization`.
+- Usage lookup failure is fail-open for routing.
+
+## OpenAI OAuth And Refresh Flow
+
+OpenAI OAuth is delegated to Codex app-server.
+
+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`.
+
+Refresh:
+
+- Codex can send server-request `account/chatgptAuthTokens/refresh`.
+- qgrid handles it 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.
+- Rate limit data is cached for 60 seconds.
+- Threshold uses primary `usedPercent`.
+- Usage lookup failure is fail-open for routing.
+
+## Token Sync And Reconcile
+
+On server start, qgrid creates PostgreSQL triggers for `tokens_changed`.
+
+Triggers notify on:
+
+- INSERT
+- DELETE
+- UPDATE when `active`, `credentials`, `provider`, `name`, or `quota_threshold` changes.
+
+`TokenSubscriber`:
+
+- connects to PostgreSQL and `LISTEN`s on `tokens_changed`;
+- reconnects with jittered exponential backoff up to 30 seconds;
+- runs periodic reconcile every 10 minutes because LISTEN/NOTIFY can miss changes while disconnected;
+- replaces dispatcher cache from `TokenModel.findActive("A")`.
+
+On DELETE or missing row:
+
+- remove from `QgridDispatcher.tokens`;
+- call OpenAI `onTokenRemoved`;
+- call Anthropic `onTokenRemoved`.
+
+OpenAI row changes:
+
+- active INSERT: `onTokenAdded` spawns workers.
+- active UPDATE: `onTokenUpdated`, then `onTokenActivated`.
+- inactive row: `onTokenDeactivated`.
+- reconcile uses `replaceTokens`, which removes absent tokens, updates existing tokens, adds new tokens, and activates rows present in active DB set.
+
+Anthropic row changes:
+
+- active INSERT: add to in-memory pool.
+- active UPDATE: update in-memory pool.
+- inactive row: remove from pool.
+- reconcile uses active Anthropic rows to replace the in-memory pool.
+
+## Provider Runtime Consequences
+
+OpenAI token changes can create, update, deactivate, or kill persistent Codex workers.
+
+- In-place OpenAI worker update is allowed only when account id and plan type match.
+- Otherwise workers are killed and respawned.
+- If no ready active OpenAI workers remain, queued OpenAI requests are rejected.
+
+Anthropic token changes only affect the in-memory token pool because every request fresh-spawns Claude Code.
+
+## Quota Threshold Semantics
+
+`quota_threshold` is a routing gate, not a hard external-provider guarantee.
+
+- Null means no threshold gate.
+- Lookup failure is fail-open.
+- Individual over-threshold tokens are excluded from selection.
+- If all ready/eligible tokens are over threshold, qgrid throws `QuotaThresholdExceededError`.
+- Log messages use `quota_threshold gate` with reasons such as `over_threshold`, `lookup_fail_open`, and `all_exceeded`.
+
+OpenAI queue items keep an `excludedTokenIds` set so a token found over threshold for a request is not immediately reselected for that same queued request.