@cartanova/qgrid-cli 2.3.8 → 2.4.0

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.

package/skills/qgrid/references/tool-calling-and-multiturn.md

@@ -0,0 +1,144 @@
+# Tool Calling And Multi-Turn
+
+Use this reference before changing qgrid tool calling, AI SDK multi-step behavior, tool-result follow-ups, or request-log tool steps.
+
+## Contents
+
+- High-level contract
+- Client flow
+- Server schema emulation
+- Provider-specific path
+- Applying emulated tool calls
+- Multi-step and multi-turn
+- Request logs
+
+## High-Level Contract
+
+qgrid supports the AI SDK `tools` interface, but it does not use native provider tool calling.
+
+- Users write normal AI SDK code with `generateText`, `streamText`, `tools`, `stopWhen`, and related AI SDK APIs.
+- The AI SDK owns client-side tool execution.
+- qgrid owns LLM turns and request logging.
+- qgrid turns AI SDK tools into a strict structured-output schema.
+- The model emits a structured object describing either a final answer or requested client-side tool calls.
+- qgrid maps that structured object back into AI SDK `tool-call` content.
+- The AI SDK executes the actual tool functions and calls qgrid again with tool results.
+
+Do not describe this as OpenAI native function calling, Claude native tool use, or Codex/Claude executing client tools. The tools are client-side AI SDK tools requested through structured-output emulation.
+
+## Client Flow
+
+`packages/ai-sdk/src/index.ts` implements AI SDK `LanguageModelV3`.
+
+When `options.tools` contains function tools:
+
+1. Filter function tools.
+2. Convert them with `toQgridTool`.
+3. Send `tools` in `/api/qgrid/query` or `/api/qgrid/prepareStream`.
+4. Set `logMode: "run"`.
+5. Do not send `jsonSchema` response format at the same time.
+
+When qgrid responds with `finishReason: "tool-calls"`:
+
+1. Map qgrid `content: [{ type: "tool-call" }]` to AI SDK tool-call content.
+2. Store `clientRun` with `runContext` and pending tool-call IDs.
+3. Return finish reason `{ unified: "tool-calls", raw: "tool_call" }`.
+
+On the next AI SDK call, if prompt history contains tool results for all pending IDs:
+
+1. Extract tool results from AI SDK history.
+2. Send previous `runContext`.
+3. Send `toolResults`.
+4. Keep `logMode: "run"`.
+
+If pending tool calls are not satisfied, qgrid warns and clears `clientRun` instead of attaching stale run context.
+
+## Server Schema Emulation
+
+`packages/api/src/application/qgrid/tool-emulation.ts` builds the tool-call schema.
+
+The schema shape is:
+
+```json
+{
+  "action": "answer | tool_call",
+  "answer": "string | null",
+  "toolCalls": [
+    {
+      "toolName": "one of the AI SDK tool names",
+      "args": "JSON string"
+    }
+  ]
+}
+```
+
+The schema explicitly tells the model:
+
+- use `tool_call` when client-side tool execution is needed;
+- use `answer` only for a final answer;
+- do not invoke listed tools as native Claude Code tools;
+- put tool arguments in `args` as a JSON string.
+
+`qgrid.dispatcher.ts` strictifies this schema through `buildStrictOutputSchema` before it reaches provider dispatchers.
+
+If tools and `jsonSchema` are both present, dispatcher rejects the request.
+
+## Provider-Specific Path
+
+OpenAI/Codex:
+
+- qgrid does not register AI SDK tools as Codex native tools.
+- Codex built-in tools are disabled in worker config.
+- qgrid sends the strict tool-call schema as `outputSchema` in `turn/start`.
+- Codex returns text matching the structured schema.
+- qgrid parses that text and maps it to qgrid `tool-call` content.
+
+Anthropic/Claude Code:
+
+- qgrid does not allow client tools as Claude Code native tools.
+- Claude is spawned with `--tools ""`.
+- When a schema exists, qgrid permits only `StructuredOutput` with `--allowed-tools StructuredOutput`.
+- qgrid passes the strict tool-call schema through `--json-schema`.
+- The stream adapter preserves `StructuredOutput` tool input as final structured text.
+- qgrid parses that text and maps it to qgrid `tool-call` content.
+
+In both providers, native provider tools are not the public abstraction. The public abstraction is AI SDK tools plus qgrid structured-output emulation.
+
+## Applying Emulated Tool Calls
+
+`applyToolCallEmulation` handles provider text:
+
+- No tools: return normal text content.
+- Tools present and JSON parse fails: warn and fall back to text with `finishReason: "stop"`.
+- `action: "tool_call"`: validate tool names, generate qgrid `toolCallId`, return `finishReason: "tool-calls"`.
+- `action: "answer"`: return final text with `finishReason: "stop"`.
+
+Unknown tool names throw.
+
+## Multi-Step And Multi-Turn
+
+AI SDK multi-step behavior is client-orchestrated:
+
+1. qgrid returns emulated tool calls.
+2. AI SDK executes tools locally.
+3. AI SDK calls qgrid again with tool results.
+4. qgrid asks the model to continue from those results.
+
+This is different from a provider-native tool loop. Neither Codex nor Claude Code executes the AI SDK tool functions.
+
+OpenAI/Codex follow-ups can reuse the same Codex thread when `runContext.threadCoord` remains valid. For tool-result follow-up turns, qgrid sends delta input containing tool result text to the existing thread; cold fallback injects full history.
+
+Anthropic follow-ups do not reuse Claude sessions. qgrid starts a fresh Claude process, replays flattened full history, and sends the tool-result continuation input.
+
+## Request Logs
+
+Tool runs use `logMode: "run"`.
+
+- `beforeQuery` creates or continues a request log run.
+- A generate step is recorded after every LLM turn.
+- When `finishReason` is `tool-calls`, qgrid appends pending tool-call step rows.
+- The follow-up request fills tool-call results or errors.
+- The final `stop` response aggregates step usage and finishes the run.
+- Stale runs with no follow-up are marked error after 30 minutes.
+
+Use `projectName` for tool-heavy workloads so request logs can be filtered by task/workflow and metrics remain interpretable.

package/skills/qgrid/references/verification-and-debugging.md

@@ -0,0 +1,193 @@
+# Verification And Debugging
+
+Use this reference to choose tests, smoke scripts, and first debugging targets for qgrid changes.
+
+## Contents
+
+- Package scripts
+- Targeted test matrix
+- Smoke scripts
+- Common error triage
+- Debugging rules
+
+## Package Scripts
+
+Root:
+
+- `pnpm check`: oxlint plus oxfmt check for the repo.
+- `pnpm build`: recursive package build.
+- `pnpm dev`: parallel package dev servers.
+
+API package `qgrid-api`:
+
+- `pnpm --filter qgrid-api test`: Vitest run.
+- `pnpm --filter qgrid-api test:watch`: standalone watch mode.
+- `pnpm --filter qgrid-api build`: Sonamu build.
+- `pnpm --filter qgrid-api sonamu`: run Sonamu CLI.
+
+AI SDK package `@cartanova/qgrid-ai-sdk`:
+
+- `pnpm --filter @cartanova/qgrid-ai-sdk test`.
+- `pnpm --filter @cartanova/qgrid-ai-sdk build`.
+- `pnpm --filter @cartanova/qgrid-ai-sdk e2e`.
+- `pnpm --filter @cartanova/qgrid-ai-sdk e2e:logger`.
+
+CLI package `@cartanova/qgrid-cli`:
+
+- `pnpm --filter @cartanova/qgrid-cli build`.
+- `pnpm --filter @cartanova/qgrid-cli bundle` builds the API first and copies the server bundle.
+
+Web package `qgrid-web`:
+
+- `pnpm --filter qgrid-web dev`.
+- `pnpm --filter qgrid-web preview`.
+
+`packages/sdk` is deprecated. Do not use its tests as active public-SDK verification unless explicitly doing legacy work.
+
+## Targeted Test Matrix
+
+Choose by affected area:
+
+| Area | Primary tests |
+|---|---|
+| AI SDK provider request/response mapping | `packages/ai-sdk/src/index.test.ts` |
+| AI SDK logger integration | `packages/ai-sdk/src/logger.test.ts` |
+| qgrid provider routing and strict schema | `packages/api/src/application/qgrid/qgrid.dispatcher.test.ts` |
+| conversation/thread reuse routing | `packages/api/src/application/qgrid/conv-routing.test.ts` |
+| tool-call emulation | `packages/api/src/application/qgrid/tool-emulation.test.ts` |
+| request-log run lifecycle | `packages/api/src/application/qgrid/qgrid-run-lifecycle.test.ts` |
+| qgrid frame API behavior | `packages/api/src/application/qgrid/qgrid.frame.test.ts` |
+| token subscriber and LISTEN/NOTIFY handling | `packages/api/src/application/qgrid/token-subscriber.test.ts` |
+| token defaults/validation | `packages/api/src/application/token/token.model.test.ts`, `token.types.test.ts` |
+| request log queries/legacy normalization | `packages/api/src/application/request-log/request-log.model.test.ts` |
+| OpenAI dispatcher routing/queue/quota/reuse | `packages/api/src/utils/providers/openai/openai-dispatcher.test.ts` |
+| OpenAI Codex worker RPC/turn behavior | `packages/api/src/utils/providers/openai/codex-worker.test.ts` |
+| OpenAI quota parser | `packages/api/src/utils/providers/openai/openai-quota.test.ts` |
+| Anthropic dispatcher token/quota/session behavior | `packages/api/src/utils/providers/anthropic/anthropic-dispatcher.test.ts` |
+| Anthropic Claude args/env/session isolation | `packages/api/src/utils/providers/anthropic/claude-session.test.ts` |
+| Anthropic stream-json parsing/structured output | `packages/api/src/utils/providers/anthropic/stream-json-adapter.test.ts` |
+| Anthropic model constants/1M suffix | `packages/api/src/utils/providers/anthropic/anthropic-constants.test.ts` |
+| Anthropic quota parser | `packages/api/src/utils/providers/anthropic/anthropic-quota.test.ts` |
+| shared cost accounting | `packages/api/src/utils/providers/common/model-cost.test.ts` |
+| TTFT tracker | `packages/api/src/utils/providers/common/ttft.test.ts` |
+
+Run focused Vitest files from the owning package when possible, then broaden if the change crosses package boundaries.
+
+## Smoke Scripts
+
+Smoke scripts assume a running qgrid server and real registered tokens. They can consume subscription quota; do not run them casually.
+
+OpenAI direct qgrid API:
+
+- `scripts/smoke-test-openai.ts`
+- Requires qgrid server and active OpenAI token.
+- Uses `QGRID_URL`, default `http://localhost:44900`.
+- Covers health, text generation, structured output, and qgrid-native tool-call content.
+
+Anthropic qgrid path:
+
+- `packages/api/scripts/smoke-test-anthropic.ts`
+- Requires active Anthropic OAuth token.
+- Uses `QGRID_URL`, `QGRID_ANTHROPIC_MODEL`, `QGRID_ANTHROPIC_MODELS`.
+- Optional flags include `--full`, `--legacy-full`, and `--structured-stream-probe`.
+
+AI SDK structured output:
+
+- `scripts/qgrid-structured-ai-sdk-smoke.ts`
+- Uses local `packages/ai-sdk/src/index`.
+- Env: `QGRID_URL`, `SMOKE_MODEL`, `SMOKE_CASES`, `SMOKE_REPEAT`.
+- Useful for streamObject/structured-output regressions.
+
+Image generation:
+
+- `packages/api/scripts/smoke-test-image-generation.ts`
+- Human-initiated only.
+- Requires active OpenAI token with image entitlement and applicable migration.
+- Env: `QGRID_URL`, `QGRID_OPENAI_MODEL`.
+- Not part of CI; it consumes ChatGPT subscription quota.
+
+Other scripts under `scripts/smoke-test-*` and `scripts/debug-*` are ad hoc probes. Read the script header and env vars before running.
+
+## Common Error Triage
+
+`NO_OPENAI_WORKERS`:
+
+- Check active OpenAI tokens, worker startup logs, Codex CLI availability, and `OpenAIDispatcher.readyWorkerCount`.
+- If tokens were recently changed, inspect `TokenSubscriber` status and reconcile behavior.
+
+`NO_ACTIVE_WORKERS`:
+
+- OpenAI workers exist but active tokens were deactivated.
+- Check token `active` state and token subscriber event handling.
+
+`SERVER_BUSY`:
+
+- OpenAI worker queue is full or a queued request timed out.
+- Check `QGRID_WORKERS_PER_TOKEN`, worker readiness, long-running turns, and queue pressure.
+
+`QuotaThresholdExceededError` or `quota_threshold gate: all_exceeded`:
+
+- All eligible tokens are above their `quota_threshold`.
+- Check token thresholds and provider usage/rate-limit APIs.
+- Lookup failures are fail-open, so all-exceeded means qgrid got usable over-threshold signals.
+
+`Direct LLM API fallback not implemented`:
+
+- Model likely lacks `openai/` or `anthropic/` prefix.
+- Do not silently route prefix-less Claude model names to Anthropic.
+
+`No anthropic tokens available`:
+
+- Anthropic token pool is empty.
+- Check active Anthropic tokens, subscriber reconcile, and token provider values.
+
+`Claude session closed without result`:
+
+- Claude child exited without a result line.
+- Check stderr suffix in the error, spawn args, OAuth token validity, `CLAUDE_CONFIG_DIR` isolation, and CLI version.
+
+`error_max_structured_output_retries`:
+
+- Claude Code structured output failed after retries.
+- Treat as a real error, not a recoverable partial result.
+- Check schema strictness and `stream-json-adapter` behavior.
+
+`qgrid: imageGeneration is not supported with streamText`:
+
+- Image generation is non-stream only. Use `generateText`.
+
+`image generation is not supported on the Anthropic route`:
+
+- Image generation is OpenAI/Codex-only.
+
+`imageGeneration was requested but the response contained no image`:
+
+- AI SDK version-skew guard. The client requested image generation, but the server returned text-only content. Check server version and the OpenAI image-generation path.
+
+OpenAI `ImageGenerationError` kinds:
+
+- `gate`: capability/model check failed before the turn.
+- `not_called`: model completed but did not call Codex `image_generation`.
+- `incomplete`: image tool was attempted but no completed base64 image was produced.
+
+`worker not ready`:
+
+- OpenAI Codex worker RPC is missing or not initialized.
+- Check worker spawn/login failures and restart logs.
+
+`OpenAI refresh failed`:
+
+- Inspect response body for refresh token death codes.
+- If refresh token rotated but DB save failed, treat the token as at risk and require re-registration.
+
+`re-login required`:
+
+- Anthropic usage refresh failed and qgrid could not recover with stored refresh token.
+
+## Debugging Rules
+
+- Start from the package-specific tests before running smoke scripts.
+- For provider issues, identify route by model prefix first.
+- For cache issues, inspect `threadCoord`, `systemHash`, provider route, and usage semantics before assuming provider cache failure.
+- For dashboard metric issues, verify qgrid-standard usage fields before changing UI formulas.
+- For Sonamu shape changes, verify API generated files and web consumers together.

package/bundle/dist/migrations/20260705140615_alter_request_log_steps_alter1.js

@@ -1,14 +0,0 @@
-import "../_virtual/_rolldown/runtime.js";
-//#region src/migrations/20260705140615_alter_request_log_steps_alter1.ts
-async function up(knex) {
-	await knex.raw(`CREATE INDEX request_log_steps_request_log_id_index ON request_log_steps USING btree(request_log_id ASC NULLS LAST);`);
-}
-async function down(knex) {
-	await knex.schema.alterTable("request_log_steps", (table) => {
-		table.dropIndex(["request_log_id"], "request_log_steps_request_log_id_index");
-	});
-}
-//#endregion
-export { down, up };
-
-//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMjAyNjA3MDUxNDA2MTVfYWx0ZXJfcmVxdWVzdF9sb2dfc3RlcHNfYWx0ZXIxLmpzIiwibmFtZXMiOltdLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9taWdyYXRpb25zLzIwMjYwNzA1MTQwNjE1X2FsdGVyX3JlcXVlc3RfbG9nX3N0ZXBzX2FsdGVyMS50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyB0eXBlIEtuZXggfSBmcm9tIFwia25leFwiO1xuXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gdXAoa25leDogS25leCk6IFByb21pc2U8dm9pZD4ge1xuICBhd2FpdCBrbmV4LnJhdyhcbiAgICBgQ1JFQVRFIElOREVYIHJlcXVlc3RfbG9nX3N0ZXBzX3JlcXVlc3RfbG9nX2lkX2luZGV4IE9OIHJlcXVlc3RfbG9nX3N0ZXBzIFVTSU5HIGJ0cmVlKHJlcXVlc3RfbG9nX2lkIEFTQyBOVUxMUyBMQVNUKTtgLFxuICApO1xufVxuXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gZG93bihrbmV4OiBLbmV4KTogUHJvbWlzZTx2b2lkPiB7XG4gIGF3YWl0IGtuZXguc2NoZW1hLmFsdGVyVGFibGUoXCJyZXF1ZXN0X2xvZ19zdGVwc1wiLCAodGFibGUpID0+IHtcbiAgICB0YWJsZS5kcm9wSW5kZXgoW1wicmVxdWVzdF9sb2dfaWRcIl0sIFwicmVxdWVzdF9sb2dfc3RlcHNfcmVxdWVzdF9sb2dfaWRfaW5kZXhcIik7XG4gIH0pO1xufVxuIl0sIm1hcHBpbmdzIjoiOztBQUVBLGVBQXNCLEdBQUcsTUFBMkI7QUFDbEQsT0FBTSxLQUFLLElBQ1QsdUhBQ0Q7O0FBR0gsZUFBc0IsS0FBSyxNQUEyQjtBQUNwRCxPQUFNLEtBQUssT0FBTyxXQUFXLHNCQUFzQixVQUFVO0FBQzNELFFBQU0sVUFBVSxDQUFDLGlCQUFpQixFQUFFLHlDQUF5QztHQUM3RSJ9

package/bundle/src/migrations/20260705140615_alter_request_log_steps_alter1.ts

@@ -1,13 +0,0 @@
-import { type Knex } from "knex";
-
-export async function up(knex: Knex): Promise<void> {
-  await knex.raw(
-    `CREATE INDEX request_log_steps_request_log_id_index ON request_log_steps USING btree(request_log_id ASC NULLS LAST);`,
-  );
-}
-
-export async function down(knex: Knex): Promise<void> {
-  await knex.schema.alterTable("request_log_steps", (table) => {
-    table.dropIndex(["request_log_id"], "request_log_steps_request_log_id_index");
-  });
-}