@cartanova/qgrid-cli 2.10.9 → 2.11.0

package/dist/cli.js

@@ -39,7 +39,7 @@ function runSelfUpdate(params, dependencies) {
 	try {
 		latest = latestVersion(packageName);
 	} catch (cause) {
-		warn(`Warning: failed to check for qgrid-cli updates: ${cause.message}`);
+		warn(`Warning: failed to check for qgrid-cli updates: ${cause instanceof Error ? cause.message : String(cause)}`);
 		warn(`Continuing with qgrid-cli ${currentVersion}.`);
 		return { kind: "continue" };
 	}
@@ -60,7 +60,8 @@ function runSelfUpdate(params, dependencies) {
 			return { kind: "continue" };
 		}
 	} catch (cause) {
-		warn(`Warning: failed to update qgrid-cli to ${latest}: ${cause.message}`);
+		const message = cause instanceof Error ? cause.message : String(cause);
+		warn(`Warning: failed to update qgrid-cli to ${latest}: ${message}`);
 		warn(`Continuing with qgrid-cli ${currentVersion}; fix the global ${packageManager} install.`);
 		return { kind: "continue" };
 	}
@@ -213,13 +214,12 @@ function ensureLatestRuntimeCliDependencies() {
 				installedOutput = commandVersion(dep.command);
 			}
 		} catch (e) {
-			console.warn(`Warning: failed to update ${dep.label}: ${e.message}`);
+			console.warn(`Warning: failed to update ${dep.label}: ${e instanceof Error ? e.message : String(e)}`);
 		}
 		if (!installedOutput) warnMissingRuntimeCliDependency(dep);
 	}
 }
-function normalizePort(port) {
-	const value = String(port);
+function normalizePort(value) {
 	const numeric = Number(value);
 	if (!/^\d+$/.test(value) || numeric < 1 || numeric > 65535) {
 		console.error(`Invalid port: ${value}`);
@@ -303,10 +303,10 @@ program.name("qgrid").version(pkg.version).description("Qgrid — LLM subscripti
 		await client.connect();
 		await client.end();
 	} catch (e) {
-		const err = e;
+		const message = e instanceof Error ? e.message : String(e);
 		console.error(`Error: Cannot connect to PostgreSQL at ${dbHost}:${dbPort}/${dbName}`);
-		console.error(`error:  ${err.message}`);
-		if (err.message.includes("timeout expired")) console.error(`cannot connect to the database server. Please check if the database is running and accessible.`);
+		console.error(`error:  ${message}`);
+		if (message.includes("timeout expired")) console.error(`cannot connect to the database server. Please check if the database is running and accessible.`);
 		console.error(`\nProvide DB connection via --db flag or QGRID_DB_* env vars:`);
 		console.error(`  qgrid --db postgres://user:password@host:port/dbname`);
 		process.exit(1);
@@ -314,7 +314,7 @@ program.name("qgrid").version(pkg.version).description("Qgrid — LLM subscripti
 	try {
 		await import(serverEntry);
 	} catch (e) {
-		console.error("Failed to start server:", e.stack ?? e.message);
+		console.error("Failed to start server:", e instanceof Error ? e.stack ?? e.message : e);
 		process.exit(1);
 	}
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.10.9",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"
@@ -20,20 +20,15 @@
     "@ai-sdk/anthropic": "^3.0.0",
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/provider-utils": "^4.0.0",
-    "@anthropic-ai/sdk": "^0.81.0",
     "@better-auth/core": "~1.6.0",
     "@better-auth/passkey": "~1.6.0",
     "@better-auth/sso": "~1.6.0",
     "@logtape/logtape": "2.0.0",
     "@logtape/pretty": "2.0.0",
-    "@logtape/redaction": "2.0.0",
-    "@oxc-project/runtime": "^0.79.0",
+    "@oxc-project/runtime": "^0.79.1",
     "ai": "^6.0.1",
-    "bcrypt": "^6.0.0",
     "better-auth": "~1.6.0",
-    "chalk": "^4.1.2",
     "commander": "^13.0.0",
-    "date-fns": "^4.1.0",
     "dotenv": "^16",
     "fastify": "^4",
     "ioredis": "^5.8.2",
@@ -41,16 +36,14 @@
     "knex": "^3.2.9",
     "pg": "^8.16.3",
     "pngjs": "^7.0.0",
-    "radashi": "^12.2.0",
-    "sonamu": "0.10.3",
-    "typescript": "6.0.3",
+    "sonamu": "0.11.16",
+    "typescript": "7.1.0-dev.20260831.1",
     "ws": "8.20.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "25.0.7",
     "@types/pg": "^8.20.0",
-    "@types/ws": "8.18.1",
     "semver": "^7.7.4",
     "tsdown": "^0.22.3",
     "yaml": "^2.8.2"

package/postinstall.mjs

@@ -28,6 +28,7 @@ function findProjectRoot(startDir) {
     }
 
     const parent = path.dirname(current);
+
     if (parent === current) return packageJsonRoot ?? path.resolve(startDir);
     current = parent;
   }
@@ -35,15 +36,19 @@ function findProjectRoot(startDir) {
 
 function defaultProjectRoot() {
   if (process.env.QGRID_SKILLS_CWD) return findProjectRoot(process.env.QGRID_SKILLS_CWD);
+
   if (process.env.INIT_CWD) return findProjectRoot(process.env.INIT_CWD);
 
   const cwd = process.cwd();
+
   if (cwd.includes(`${path.sep}node_modules${path.sep}`)) return null;
+
   return findProjectRoot(cwd);
 }
 
 function isInside(parentDir, childDir) {
   const relative = path.relative(path.resolve(parentDir), path.resolve(childDir));
+
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
@@ -55,9 +60,11 @@ function defaultTargets() {
     const codexHome = process.env.CODEX_HOME
       ? path.resolve(process.env.CODEX_HOME)
       : path.join(os.homedir(), ".codex");
+
     const claudeHome = process.env.CLAUDE_HOME
       ? path.resolve(process.env.CLAUDE_HOME)
       : path.join(os.homedir(), ".claude");
+
     return [
       { label: "Codex", target: path.join(codexHome, "skills", "qgrid"), useSymlink: false },
       { label: "Claude Code", target: path.join(claudeHome, "skills", "qgrid"), useSymlink: false },
@@ -65,10 +72,13 @@ function defaultTargets() {
   }
 
   const projectRoot = defaultProjectRoot();
+
   if (!projectRoot) return null;
   const isInstalledPackage = packageDir.split(path.sep).includes("node_modules");
+
   if (!isInstalledPackage && isInside(projectRoot, sourceSkillsDir)) {
     console.log("qgrid skill sync skipped: running inside qgrid repository.");
+
     return [];
   }
 
@@ -89,6 +99,7 @@ function defaultTargets() {
 async function syncSkill({ label, target, useSymlink }) {
   if (!existsSync(path.join(sourceSkillsDir, "SKILL.md"))) {
     console.log("qgrid skill source not found in qgrid CLI package.");
+
     return;
   }
 
@@ -99,6 +110,7 @@ async function syncSkill({ label, target, useSymlink }) {
     try {
       await symlink(sourceSkillsDir, target, "dir");
       console.log(`qgrid skill linked for ${label}: ${target}`);
+
       return;
     } catch (error) {
       console.log(

package/skills/qgrid/SKILL.md

@@ -21,6 +21,7 @@ Before changing code, identify the affected path:
 - OpenAI direct transport, permits, routing, cache affinity, OAuth, or quota behavior: read `references/openai-codex-runtime.md`.
 - Adding an OpenAI model, its pricing, or reasoning levels: follow the model-addition checklist in `references/openai-codex-runtime.md`.
 - Anthropic models or Claude Code spawn/stream-json behavior: read `references/anthropic-claude-code-runtime.md`.
+- Grok fingerprinting, OAuth, quota routing, media, voice, or retry behavior: read `references/grok-runtime.md`.
 - Token registration, OAuth, token sync, active/inactive behavior, quota thresholds, or weighted token routing: read `references/token-auth-quota-lifecycle.md`.
 - Provider comparisons, routing, or cross-provider bugs: read `references/provider-runtime-differences.md`.
 - Tool calling, AI SDK multi-step loops, or tool-call request logs: read `references/tool-calling-and-multiturn.md`.

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

@@ -66,6 +66,8 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 |---|---:|---|
 | `QGRID_OPENAI_TRANSPORT` | `websocket` | OpenAI transport selector (`https` or `websocket`). Invalid values fail at dispatcher configuration time. This is the only OpenAI runtime knob; there is no concurrency cap. |
 | `QGRID_OPENAI_AUTOSCALE` / `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` / `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` / `QGRID_OPENAI_PERMITS_PER_TOKEN` | ignored | Removed. OpenAI requests run uncapped like Anthropic (stateless per-request execution); setting these has no effect. |
+| `QGRID_GROK_MAX_INFLIGHT_PER_TOKEN` | unset (uncapped) | Optional positive-integer per-account Grok cap. Accounts at the cap are excluded from selection rather than queued. Invalid values are ignored with a warning (`packages/api/src/utils/providers/grok/grok-dispatcher.ts`). |
+| `QGRID_GROK_LIVE_TOKEN_ID` | unset | Reserved token-row selector for opt-in Grok live tests. Keep it unset in CI and ordinary server runs. The live-test gate is specified in `docs/plans/2026-10-16-grok-provider-integration-plan.md` §7; no current server runtime behavior reads it. |
 | `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED` | off | Marks this instance as the Anthropic 5-hour window keepalive runner (2.8.0, `ea7feb3`). Only the literal `true` enables it; set it on exactly one instance per shared DB so developer instances do not fire duplicates. Two more gates apply: the global setting `qgrid.tokenWindowKeepaliveEnabled` (`false` turns everything off; changing it reschedules immediately) and the per-token `tokens.keepalive_enabled` flag (default `false`, dashboard settings-panel toggle). In 2.7.6 this env was a default-on global switch with no per-token opt-in. |
 | `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic streaming calls | Claude Code structured-output retry count for streaming only, clamped to at least 1 by qgrid. Non-streaming `generate` leaves the variable unset and uses Claude Code's default retry budget. |
 
@@ -81,7 +83,8 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
    1. Ensures PostgreSQL `tokens_changed` triggers.
    2. Starts `TokenSubscriber` for LISTEN/NOTIFY plus periodic reconcile.
    3. Starts `OpenAIDispatcher` and `AnthropicDispatcher`.
-   4. Logs server URL and provider readiness counts.
+   4. Constructs `GrokRefreshCoordinator`, `GrokMediaClient`, and `GrokVoiceClient`, injects them into `GrokDispatcher`, starts it, then reconciles Grok tokens (`packages/api/src/sonamu.config.ts`).
+   5. Logs server URL and provider readiness counts.
 
 On shutdown, it stops provider dispatchers and the token subscriber.
 

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

@@ -10,6 +10,7 @@ Do not copy these notes blindly into implementation. Use them to find the releva
 - Tool calling and request-log lifecycle
 - OpenAI/Codex runtime
 - Anthropic/Claude Code runtime
+- Grok (xAI subscription) runtime
 - Token sync and quota thresholds
 - Weighted token routing
 - Request logs, metrics, and dashboard
@@ -133,6 +134,28 @@ Key decisions:
 - `--setting-sources project` is required for shared-service isolation. User/local Claude settings can load hooks or memory and leak context across requests.
 - Claude Code OAuth prompt cache sharing across tokens in the same workspace is an observed cost behavior, not a product contract. Monitor it; do not promise it.
 
+## Grok (xAI Subscription) Runtime
+
+Sources:
+
+- `docs/plans/2026-10-16-grok-provider-integration-plan.md`
+- `docs/diagnosis/2026-10-16-grok-live-probe.md`
+- `packages/api/src/utils/providers/grok/*`
+- `packages/api/src/application/qgrid/qgrid.dispatcher.ts`
+
+Key decisions:
+
+- **D1 — accepted terms risk:** The user accepted the risk of using an xAI subscription token from a non-official client and authorized the bounded live probe. This is recorded acceptance, not a claim that xAI permits every deployment.
+- **D2 — reproduce grok-build:** Qgrid sends the full installed grok-build fingerprint. `GROK_BUILD_VERSION` is a source pin, not an environment override; changing it requires a new installed-binary capture, golden fixture, build id, and fingerprint test.
+- **D3 — subscription OAuth only:** Grok tokens must be `at+jwt` OAuth credentials issued by `auth.x.ai`. Raw xAI API keys are outside qgrid's subscription-pooling purpose.
+- **D4 — URL video delivery:** Return the upstream `api.x.ai` video URL in the AI SDK URL result. Qgrid does not download, proxy, or persist video bytes.
+- **D5 — no new workspace package:** Grok runtime code lives under `packages/api/src/utils/providers/grok/`; SDK adapters stay in `packages/ai-sdk/src/`.
+- **D6 — exclude on-demand billing:** An account with `/settings.on_demand_enabled = true` is ineligible. There is no per-token override because the exclusion closes accidental paid usage.
+- **D7 — shared weighted routing:** Grok uses the common `SmoothWeightedRoundRobin` with `tokens.weight`, after quota, on-demand, cooldown, entitlement, and optional in-flight gates.
+- **D8 — preserve tool emulation:** Grok remains on qgrid's shared strict action-envelope tool contract. The provider can emit native function calls, but qgrid callers continue to receive the same emulated AI SDK multi-step lifecycle as the other routes.
+
+Current implementation evidence is in `grok-constants.ts`, `grok-dispatcher.ts`, `grok-oauth.ts`, `grok-media-client.ts`, `packages/api/src/application/qgrid/qgrid.frame.ts`, and `qgrid.dispatcher.ts`. See `references/grok-runtime.md` for operational details and unverified gaps.
+
 ## Token Sync And Quota Thresholds
 
 Sources:
@@ -237,7 +260,7 @@ Key decisions:
 - qgrid performs preflight capability/model gates. Raw `imageGeneration: true` requires an image; `"auto"` allows normal text replies but still rejects attempted image generation without a completed image. Public `generateImage` requires one direct Images output per provider call; AI SDK batches requests for `n` outputs.
 - Raw returned images are inline base64 content parts. The image SDK maps them to AI SDK `image`/`images` and takes references through standard `prompt: { text, images }`, with JSON data URL size guarding and HTTPS reference URL support. The language SDK forwards user-message images to `openai/` models as image input (image→text) and drops other image parts with an AI SDK `unsupported` warning.
 - Raw/server `imageGenerationOptions` supports quality, size, and background. The public image SDK uses flat `QgridImageProviderOptions` and standard top-level `size`. The subscription backend can ignore size and quality hints. Put desired ratios in the prompt, report observed output settings, and never silently resize. Reported image usage is priced at public token rates; without it, use the requested quality/size table with a default-size price for auto/custom hints. Preserve observed settings separately from pricing assumptions. No background-removal fallback is allowed.
-- qgrid does not manage generated or reference images as durable assets through a `generated_images` table or object-storage layer. Current request logs can still contain inline image data URLs for inspection and synthetic `image_generation` tool-call steps; reference input images live in the first synthetic step's `tool_args.inputImages`.
+- qgrid does not manage generated or reference images as durable assets through a `generated_images` table or object-storage layer. Current request logs can still contain inline image data URLs for inspection and synthetic `image_generation` tool-call steps; current-turn input images (image→text and image references) live in `request_logs.input_images`; older image-generation logs keep them only in the first synthetic step's `tool_args.inputImages`.
 - Image cost is stored separately in `request_logs.image_cost_usd`; `request_logs.cost_usd` remains the Codex driver model token cost. Image costs use reported image usage at public token rates, or per-image quality/size estimates when usage is absent. Auto/custom sizes fall back to the 1536x1024 price; omitted quality uses medium. Rows and totals display combined costs as dollar amounts without Cost labels, without Known/Estimated labels or pricing disclaimers. Existing stored null costs are not backfilled; `totalCost.unknownImageCostCount` remains for API compatibility.
 - Inspect current plans, tests, and implementation before changing behavior; the Codex tool surface can change underneath qgrid.
 

package/skills/qgrid/references/grok-runtime.md

@@ -0,0 +1,89 @@
+# Grok Direct Runtime
+
+Use this reference before changing Grok chat transport, fingerprinting, OAuth, quota routing, media, voice, cost accounting, or retry behavior.
+
+## Source files
+
+- Fingerprint constants and headers: `packages/api/src/utils/providers/grok/grok-constants.ts`, `grok-headers.ts`.
+- Chat protocol, transport, models, and dispatch: `grok-backend-protocol.ts`, `grok-direct-client.ts`, `grok-models.ts`, `grok-dispatcher.ts`.
+- OAuth, refresh, billing, and settings: `grok-oauth.ts`, `grok-refresh.ts`, `grok-quota.ts`.
+- Image/video and voice clients: `grok-media-client.ts`, `grok-voice-client.ts`.
+- API limits and endpoints: `packages/api/src/application/qgrid/qgrid.types.ts`, `qgrid.frame.ts`.
+- Probe evidence and design decisions: `docs/diagnosis/2026-10-16-grok-live-probe.md`, `docs/plans/2026-10-16-grok-provider-integration-plan.md`.
+
+## Hosts and fingerprint
+
+Grok uses the same xAI subscription OAuth bearer on two hosts, but the header families are not interchangeable (`grok-constants.ts`, `grok-headers.ts`):
+
+| Host | Operations | Identity headers |
+| --- | --- | --- |
+| `https://cli-chat-proxy.grok.com/v1` | `/responses`, `/settings`, `/models`, `/billing`, `/user` | `grok-shell/1.0.60 (<os>; <arch>)`, client version and identifier, client mode, and the proxy auth headers. `/responses` also sends the captured `x-grok-*` conversation headers, trace context, loop guards, and zstd encoding. |
+| `https://api.x.ai/v1` | image generation/editing, video start/status, STT, TTS | Media uses `xai-grok-build/1.0.60`; voice uses the shell user agent. Both send the client version and identifier, but never the proxy auth trio. |
+
+D2 requires the installed grok-build fingerprint. `GROK_BUILD_VERSION` is pinned to `1.0.60` and `GROK_BUILD_COMMIT` to build `01a8e1c591c0`; the golden request came from the installed binary, not the older public source (`grok-constants.ts`, `grok-headers.test.ts`, `docs/diagnosis/2026-10-16-grok-live-probe.md`).
+
+Handle the pin like OpenAI's `CODEX_CLI_VERSION`: keep it as a source constant with no runtime override. To bump it:
+
+1. Edit `GROK_BUILD_VERSION` in `grok-constants.ts`.
+2. Run the newly installed grok-build binary through an intercepting proxy and re-capture the redacted golden request fixture.
+3. Update `GROK_BUILD_COMMIT` with that binary's build id.
+4. Run `grok-headers.test.ts` and the golden fingerprint test before release.
+
+The proxy treats the client version as a floor. The 2026-10-16 probe saw `/settings.min_client_version = 1.0.13`; a lower client received HTTP 426. The dispatcher trips a chat-only fast gate for 10 minutes and reports the bump routine (`docs/diagnosis/2026-10-16-grok-live-probe.md`, `grok-dispatcher.ts`).
+
+## OAuth, credentials, and refresh
+
+Grok login uses OIDC discovery under `https://auth.x.ai`, public client id `b1a00492-073a-47ea-816f-4c329264a828`, S256 PKCE, `referrer=grok-build`, and these frozen scopes: `openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write` (`grok-constants.ts`, `grok-oauth.ts`).
+
+Browser login uses a random `127.0.0.1` callback and accepts either the full callback URL or a pasted bare code. Qgrid exposes this as code-paste completion because it does not serve the random callback. Device login uses `/oauth2/device/code`, polls `/oauth2/token` at the returned interval, and adds five seconds after `slow_down` (`grok-oauth.ts`, `packages/api/src/application/qgrid/qgrid.frame.ts`).
+
+Stored credentials contain OAuth access/refresh tokens, RFC 3339 expiry, issuer, client id, scopes, `userId`, stable session/agent ids, and an optional tier. Registration accepts only an `at+jwt` issued by `auth.x.ai`; the post-login `/user` lookup resolves the account (`grok-types.ts`, `grok-oauth.ts`). `userId` is the token identity key, so signing in again replaces the prior row for the same account while preserving token settings (`packages/api/src/application/token/token.model.ts`).
+
+Refresh starts 300 seconds plus stable 0–60 second per-account jitter before expiry, coalesces concurrent refreshes, persists before publishing credentials, and retains the old refresh token when xAI does not rotate it. Only `invalid_grant` and `invalid_client` require a new login; network errors, 429, 5xx, and unknown OAuth errors remain transient. An upstream 401 permits one forced refresh and one same-token retry (`grok-refresh.ts`, `grok-dispatcher.ts`).
+
+## Quota, billing, and token selection
+
+`/billing?format=credits` is camelCase: qgrid reads `config.creditUsagePercent`, `config.currentPeriod`, and `config.prepaidBalance.val`. The observed period was seven days anchored at subscription start. Results are cached for 60 seconds; lookup failure fails open (`grok-quota.ts`, `grok-dispatcher.ts`, `docs/diagnosis/2026-10-16-grok-live-probe.md`).
+
+D6 excludes accounts when `/settings.on_demand_enabled` is `true`; `null`, `false`, or absence allows routing. Billing does not carry this field. D7 selects eligible accounts through the shared `SmoothWeightedRoundRobin`, using `tokens.weight`; a valid cache-affinity token remains preferred. `QGRID_GROK_MAX_INFLIGHT_PER_TOKEN` optionally excludes accounts at the cap, while omission leaves Grok uncapped (`grok-quota.ts`, `grok-dispatcher.ts`, `packages/api/src/utils/providers/common/smooth-weighted-round-robin.ts`).
+
+## Failure and failover rules
+
+The dispatcher implements the plan §5.4 state machine (`grok-backend-protocol.ts`, `grok-direct-client.ts`, `grok-dispatcher.ts`, `grok-media-client.ts`):
+
+| Condition | State and retry behavior |
+| --- | --- |
+| 429 with `Retry-After` | Set a request-class cooldown, capped at 120 seconds; fail over within the hop budget. If every candidate is cooling down, wait once for at most 30 seconds, then return a rate-limit error. |
+| 429 exhaustion | Block the request class until the billing period ends, or one hour when the end is unavailable; invalidate billing and fail over. |
+| 403 | Chat fails permanently without refresh or failover. Public API sets a one-hour entitlement block for that request class and may fail over once. |
+| HTTP 426 | Trip the chat-only version gate. Media and voice remain available. |
+| 401 | Refresh once and retry the same account; a second 401 marks it for re-authentication and may fail over. |
+| `x-should-retry: false` | Return the error without retry or failover. |
+| Chat 5xx/connect/idle failure | Fail over only before any event was forwarded and before upstream execution was observed. |
+| Media/voice transport failure | Fail over only for a classified pre-send connection failure. Never replay a sent POST or a timeout that may have executed upstream. |
+
+## Chat, tools, usage, and cost
+
+Chat sends complete Responses-format history over HTTPS/SSE. It preserves image data/HTTPS inputs, strict structured output, prompt-cache affinity, reasoning effort, and the fixed include/store fields captured from grok-build. A stream succeeds only after `response.completed` (`grok-backend-protocol.ts`, `grok-direct-client.ts`, `grok-dispatcher.ts`, `docs/diagnosis/2026-10-16-grok-live-probe.md`).
+
+D8 keeps qgrid's shared structured-output tool emulation: caller tools become the strict action envelope, the AI SDK executes returned tool calls, and a follow-up turn replays results. Do not replace this with Grok-native function execution without reopening the cross-provider contract (`packages/api/src/application/qgrid/qgrid.dispatcher.ts`, `tool-emulation.ts`, `tool-emulation-schema.ts`).
+
+Provider `cost_in_usd_ticks` is authoritative, including zero; one tick is `1e-10` USD. If ticks are absent, qgrid uses catalog-seeded language/image prices and marks `costSource: "pricing_table"`; reported ticks use `costSource: "provider"` (`grok-dispatcher.ts`, `packages/api/src/utils/providers/common/model-cost.ts`, `docs/diagnosis/2026-10-16-grok-live-probe.md`).
+
+## Media and voice
+
+Qgrid exposes image generation/editing, asynchronous video start/status, transcription, and speech through `api.x.ai`. Reference images select `/images/edits`; video uses `/videos/generations` and `/videos/{request_id}`; voice uses multipart `/stt` and JSON `/tts` (`grok-media-client.ts`, `grok-voice-client.ts`, `packages/api/src/application/qgrid/qgrid.frame.ts`).
+
+Inline audio, each inline image, and the aggregate inline images in one request are capped at 7 MiB decoded. The server maps Fastify's oversized-body error to HTTP 413 (`packages/api/src/application/qgrid/qgrid.types.ts`, `qgrid.frame.ts`).
+
+Video starts return a random 128-bit in-memory job handle. Handles expire after 24 hours, polling stays pinned to the starting token, and `projectName` must match the owner supplied at start. D4 returns the upstream `api.x.ai` video URL unchanged; qgrid does not fetch, proxy, or store the bytes (`qgrid.frame.ts`, `grok-media-client.ts`, `packages/ai-sdk/README.md`).
+
+**ZDR and video.** xAI refuses `POST /v1/videos/generations` for Zero Data Retention accounts with HTTP 400 `invalid_request`: "Zero Data Retention teams must provide output.upload_url for video generation." The dispatcher therefore keeps a per-token `zdr` state and excludes `zdr === true` tokens from video only; chat, image, STT, and TTS still route. The primary signal is `codingDataRetentionOptOut` on `GET /user?include=subscription`, re-read on the 60 s prefetch with settings; `x-zero-data-retention: true` on a chat-proxy response confirms it, but its absence never clears it. Unknown state, or a failed `/user` read with no prior value, routes (fail open). If a video start still gets the ZDR 400, the token is marked ZDR, video is entitlement-blocked for an hour, and the start fails over under the media rules. With no eligible video token the caller gets `GrokZdrVideoUnavailableError` (HTTP 503) naming the tokens; usage exposes `zdrVideoExcluded`. Both signals were inferred from one account (plan §11). grok-build's remedy, a user-owned S3 presigned `output.upload_url`, is not implemented (`grok-dispatcher.ts`, `grok-quota.ts`).
+
+## Known gaps and residual risks
+
+- **Verified 2026-10-16:** video generation succeeded through the SDK once the account's data-retention opt-out was off (8 s H.264 mp4 on vidgen.x.ai, $0.64; plan section 11). ZDR accounts are refused upstream and are excluded from the video class (see ZDR and video).
+- Node/undici adds headers such as `accept-language` and `sec-fetch-mode` that the captured reqwest client did not send. Transport fingerprinting remains residual risk 10; D1/D2 do not authorize anti-detection work (`docs/plans/2026-10-16-grok-provider-integration-plan.md`, risk 10).
+- **Unverified:** The capture pins chat header order. Media header order has not been verified through an installed-binary capture (`grok-headers.ts`, `docs/diagnosis/2026-10-16-grok-live-probe.md`).
+- **Observed 2026-10-16, not represented in the catalog fixture:** `grok-composer` ids silently remapped to `grok-4.5-build`. Treat the returned serving model as authoritative; the captured catalog itself lists only the four documented model ids (`docs/diagnosis/2026-10-16-grok-live-probe.md`, `grok-models.ts`).
+- `QGRID_GROK_LIVE_TOKEN_ID` is reserved by the plan for opt-in live tests and must stay unset in ordinary/CI runs; no current server runtime behavior depends on it (`docs/plans/2026-10-16-grok-provider-integration-plan.md`, §7).

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

@@ -1,31 +1,31 @@
 # 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 | 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 |
-| Effort vocabulary | Codex catalog levels `low`..`ultra` (Astra, GPT-6 Sol, GPT-5.6 Sol/Terra through `ultra`; GPT-6/5.6 Luna through `max`); public-API `none`/`minimal` absent | Claude Code `--effort` levels `low`..`max`; per-model caps handled by Claude Code |
-| Unsupported effort | Server drops it silently before the request (`resolveOpenAIEffort`), backend default applies | Server drops it silently (`resolveAnthropicEffort`), qgrid default `low` applies |
-| 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-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 |
+Use this reference when comparing OpenAI, Anthropic, and Grok behavior, debugging provider-specific bugs, or reviewing cross-provider changes. Sources: `packages/api/src/utils/providers/{openai,anthropic,grok}/*`, `packages/api/src/application/qgrid/qgrid.dispatcher.ts`, and `references/grok-runtime.md`.
+
+| Topic | OpenAI via Codex | Anthropic via Claude Code | Grok via grok-build fingerprint |
+|---|---|---|---|
+| Process lifetime | No child process; direct HTTPS/SSE or WebSocket request | Fresh `claude` process per request | No child process; direct HTTPS/SSE request |
+| Worker pool | None; in-memory token pool only | None; in-memory token pool only | None; in-memory token/account pool only |
+| Worker id | Legacy coordinate field carries token id | `tokenId` | Legacy coordinate field carries token id |
+| Epoch | Legacy compatibility value; not a process generation | Always `0` | `-1`; not a process generation |
+| Request concurrency | Uncapped; stateless request per call | Uncapped; fresh process per request | Uncapped by default; optional `QGRID_GROK_MAX_INFLIGHT_PER_TOKEN` excludes accounts at the cap |
+| Token selection | Smooth weighted RR over quota-eligible tokens; valid affinity may prefer its token | Smooth weighted RR over quota-eligible tokens per request | Smooth weighted RR after quota, on-demand, cooldown, entitlement, and capacity gates; valid affinity may prefer its token |
+| Model routing | `openai/*`; qgrid strips provider prefix before provider call | `anthropic/*`; provider canonicalizes model and strips prefix/`[1m]` | `grok/*`; qgrid strips the provider prefix and validates against the seeded/live catalog |
+| Prefix-less models | Fallback not implemented | Fallback not implemented | Fallback not implemented |
+| Effort vocabulary | Codex catalog levels `low`..`ultra` | Claude Code `--effort` levels `low`..`max` | Catalog levels `low`, `medium`, `high`, `xhigh`; thinking-off is unverified and rejected |
+| Unsupported effort | Server drops it before the request; backend default applies | Server drops it; qgrid default `low` applies | Server drops it; catalog default applies |
+| Thread/session | No provider thread retained | Fresh Claude `--session-id` per request | No provider thread retained; stable account session/agent ids are fingerprint headers |
+| `sessionKey` | AI SDK derives and replays opaque `prompt_cache_key` affinity | AI SDK intentionally disables storage/replay | AI SDK derives and replays account-affine `prompt_cache_key` coordinates |
+| Multi-turn | Full Responses-format history is sent on every request | Fresh spawn receives flattened full history through stream-json | Full Responses-format history is sent on every request |
+| Cache key | Opaque model-scoped affinity key plus stable serialized prefix | Anthropic prefix cache via Claude Code | Opaque model-scoped affinity key, also used to derive Grok conversation ids |
+| Built-in tools | Direct request includes only requested qgrid tools/options | Claude tools disabled via `--tools ""` | Captured proxy supports `web_search`/`x_search`, but qgrid's public tool path remains the shared emulation contract |
+| AI SDK tools | Emulated via qgrid structured output schema | Emulated via prompt envelope; not native Claude Code tools | Emulated via the strict qgrid action envelope (D8), not provider-executed function tools |
+| Structured output | Strict JSON schema is sent in the direct Responses request | Schema is prompt text; consumer validation owns correctness | Strict JSON schema is sent in the direct Responses request |
+| Usage accounting | Input includes cached input | Native categories are summed into total input | Responses reports cached/reasoning/context tokens and `cost_in_usd_ticks` |
+| Cost source | qgrid model price fallback | Prefer Claude Code `total_cost_usd`, else qgrid fallback | Provider ticks are authoritative; catalog-seeded fallback when ticks are absent |
+| Settings isolation | Per-token credentials in memory | Shared project cwd plus per-token `CLAUDE_CONFIG_DIR` | Per-token OAuth credentials and stable ids in memory |
+| Streaming close | `AbortSignal` cancels selection or active transport | Abort kills the fresh child process | `AbortSignal` cancels selection or active SSE; success requires `response.completed` |
+| Media/voice | OpenAI image routes only | Explicitly unsupported | Image generation/editing, async video URL jobs, STT, and TTS on `api.x.ai` |
 
 ## Routing contract
 
@@ -33,13 +33,14 @@ Provider routing happens in `packages/api/src/application/qgrid/qgrid.dispatcher
 
 - `openai/<model>` routes to `OpenAIDispatcher`.
 - `anthropic/<model>` routes to `AnthropicDispatcher`.
+- `grok/<model>` routes to `GrokDispatcher`.
 - 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:
+All three providers return `GenerateResult` with:
 
 - `text`
 - `tokenName`
@@ -52,6 +53,6 @@ Both providers return `GenerateResult` with:
 
 `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`.
+OpenAI and Grok receive strictified output schemas from `buildStrictOutputSchema`; Anthropic receives the original schema as prompt text.
 
-Tool calling uses this shared strict-schema path. It is not native provider tool calling on either route.
+Tool calling uses qgrid's shared action-envelope path. It is not native provider tool execution on any public route (`packages/api/src/application/qgrid/qgrid.dispatcher.ts`, `tool-emulation.ts`).

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

@@ -25,6 +25,7 @@ Use this map to orient qgrid work quickly.
 - Token trigger setup: `packages/api/src/application/qgrid/token-trigger-setup.ts`.
 - OpenAI direct backend transport, OAuth, quota, and dispatcher: `packages/api/src/utils/providers/openai/*`.
 - Anthropic Claude Code runtime: `packages/api/src/utils/providers/anthropic/*`.
+- Grok chat fingerprint/transport, OAuth/refresh, quota/models, dispatcher, media, and voice: `packages/api/src/utils/providers/grok/{grok-constants.ts,grok-headers.ts,grok-backend-protocol.ts,grok-direct-client.ts,grok-oauth.ts,grok-refresh.ts,grok-quota.ts,grok-models.ts,grok-dispatcher.ts,grok-media-client.ts,grok-voice-client.ts,grok-types.ts}`. See `packages/cli/skills/qgrid/references/grok-runtime.md`.
 - 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`.
 - Boot order and startup migrations: `packages/api/src/server-bootstrap.ts`, `packages/api/src/startup-migrations.ts`.
@@ -38,3 +39,12 @@ Use this map to orient qgrid work quickly.
 - 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/*`.
+
+## Grok SDK and API surfaces
+
+- Public AI SDK language/options integration: `packages/ai-sdk/src/index.ts`, `index.types.ts`, `grok-options.ts`.
+- Grok image/video/transcription/speech adapters: `packages/ai-sdk/src/image-model.ts`, `video-model.ts`, `transcription-model.ts`, `speech-model.ts`.
+- Grok OAuth, media, voice, limits, and video job handles: `packages/api/src/application/qgrid/qgrid.frame.ts`, `qgrid.types.ts`.
+- Grok dispatcher construction and lifecycle: `packages/api/src/sonamu.config.ts`.
+
+These paths are documented by `packages/ai-sdk/README.md` and `packages/cli/skills/qgrid/references/grok-runtime.md`.

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

@@ -98,7 +98,7 @@ For `imageGeneration: "auto"`, set `is_image_generation` only when returned cont
 
 If the auto image stage fails or is cancelled after the chat driver has completed, preserve the completed driver result as internal failure metadata. The frame converts it with the same usage/pricing mapper used on success; terminal logging writes one generate step before aggregating the run and retains the actual/requested model and token. The parent remains `error` or `aborted` with the original error message. Do not write a completed image step, invent an image cost, expose failure metadata in the HTTP error, or record this step again on success. A driver that never completed and a direct image-only call have no completed chat usage to retain. `logger: false` still creates no logs. Log-writing failures must not replace the original generation failure.
 
-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.
+Input images are not stored in `request_logs.user_prompt`; that field remains the text prompt. `beforeQuery` stores the current turn's `args.input` images on the run as `request_logs.input_images` (`{ mediaType, data, byteSize }` or `{ url }`), for text and image runs alike. Earlier-turn images in `history` stay in `request_logs.history`. 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
 

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

@@ -78,7 +78,7 @@ Chat model presets: the model `<select>` lists the served subset of `QgridSuppor
 
 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.
+Current-turn input images render in the detail view under the user prompt from `request_logs.input_images` (subset `A` only, not the list subset). Logs created before that column fall back to 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

@@ -9,6 +9,7 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - Token APIs
 - Anthropic OAuth flow
 - OpenAI OAuth and refresh flow
+- Grok OAuth, refresh, and quota flow
 - Token sync and reconcile
 - Provider runtime consequences
 - Quota threshold semantics
@@ -24,7 +25,8 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - Token subscriber: `packages/api/src/application/qgrid/token-subscriber.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`.
+- Grok OAuth/refresh/quota: `packages/api/src/utils/providers/grok/grok-oauth.ts`, `grok-refresh.ts`, `grok-quota.ts`.
+- Provider token event handlers: `openai-dispatcher.ts`, `anthropic-dispatcher.ts`, `grok-dispatcher.ts`.
 
 ## Token Table Contract
 
@@ -71,10 +73,29 @@ Anthropic credentials:
 }
 ```
 
-Duplicate account replacement is account-identifier based:
+Grok credentials (`packages/api/src/utils/providers/grok/grok-types.ts`):
+
+```ts
+{
+  authMode: "oauth";
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: string;
+  issuer: "https://auth.x.ai";
+  clientId: string;
+  scopes: string[];
+  userId: string;
+  sessionId: string;
+  agentId: string;
+  subscriptionTier?: string;
+}
+```
+
+Duplicate account replacement is account-identifier based (`packages/api/src/application/token/token.model.ts`):
 
 - OpenAI: `credentials.accountId`.
 - Anthropic: `credentials.accountUuid`.
+- Grok: `credentials.userId`.
 
 ## Token APIs
 
@@ -152,6 +173,26 @@ Usage/quota:
 - Threshold uses primary `usedPercent`.
 - Usage lookup failure is fail-open for routing.
 
+## Grok OAuth, Refresh, And Quota Flow
+
+Grok supports two OAuth entry paths (`grok-oauth.ts`, `packages/api/src/application/qgrid/qgrid.frame.ts`):
+
+1. Browser PKCE uses xAI OIDC discovery, a random `127.0.0.1` callback, the grok-build client id/scopes/referrer, and code-paste completion from either a full callback URL or bare code.
+2. Device code starts at `auth.x.ai/oauth2/device/code` and polls the token endpoint at the returned interval; `slow_down` adds five seconds.
+
+The resulting access token must be an `at+jwt` issued by `auth.x.ai`. Qgrid confirms identity through `/user?include=subscription` and stores `userId` as the account identity key (`grok-oauth.ts`, `grok-types.ts`, `token.model.ts`).
+
+Refresh starts 300 seconds plus stable 0–60 second jitter before expiry, is single-flight per token, keeps the previous refresh token when xAI does not rotate it, and persists rotated credentials before exposing them. `invalid_grant` and `invalid_client` require re-login; other failures remain transient. A generation 401 permits one forced refresh and same-token retry (`grok-refresh.ts`, `grok-dispatcher.ts`).
+
+Quota and spending controls use two proxy reads (`grok-quota.ts`, `grok-dispatcher.ts`):
+
+| Read | Routing fields | Cache/failure policy |
+|---|---|---|
+| `/billing?format=credits` | camelCase `config.creditUsagePercent`, weekly `currentPeriod`, prepaid balance | 60-second cache; lookup failure fails open |
+| `/settings` | `on_demand_enabled`, minimum client version, feature/tier flags | 60-second cache; `true` excludes the account under D6; lookup failure fails open |
+
+The observed weekly billing window begins at subscription start, not a calendar boundary (`docs/diagnosis/2026-10-16-grok-live-probe.md`). Quota exhaustion blocks only the affected request class until period end (one-hour fallback); a fresh below-threshold billing read clears blocks (`grok-dispatcher.ts`).
+
 ## Token Sync And Reconcile
 
 On server start, qgrid creates PostgreSQL triggers for `tokens_changed`.
@@ -176,7 +217,8 @@ On DELETE or missing row:
 
 - remove from `QgridDispatcher.tokens`;
 - call OpenAI `onTokenRemoved`;
-- call Anthropic `onTokenRemoved`.
+- call Anthropic `onTokenRemoved`;
+- call Grok `onTokenRemoved`.
 
 OpenAI row changes:
 
@@ -192,6 +234,12 @@ Anthropic row changes:
 - inactive row: remove from pool.
 - reconcile uses active Anthropic rows to replace the in-memory pool.
 
+Grok row changes (`packages/api/src/application/qgrid/token-subscriber.ts`, `grok-dispatcher.ts`):
+
+- active INSERT/UPDATE: validate credentials and upsert account metadata plus selector weight.
+- inactive or deleted row: remove it from the in-memory pool and weighted selector.
+- reconcile uses active Grok rows to replace the in-memory pool.
+
 ## Provider Runtime Consequences
 
 OpenAI token changes create, update, deactivate, or remove in-memory credential metadata.
@@ -202,6 +250,8 @@ OpenAI token changes create, update, deactivate, or remove in-memory credential
 
 Anthropic token changes only affect the in-memory token pool because every request fresh-spawns Claude Code.
 
+Grok token changes update the in-memory OAuth credentials, quota/settings cache generation, and weighted selector. Grok has no child process; media and chat reserve the selected account for the request (`grok-dispatcher.ts`).
+
 ## Auth-Dead Detection And Token Registration
 
 When a refresh fails in a way that only re-login can fix, qgrid removes the token from routing instead of letting every subsequent request 401.
@@ -232,6 +282,9 @@ When a refresh fails in a way that only re-login can fix, qgrid removes the toke
   `recovered` once a later quota check falls below the threshold. Metadata generations prevent an
   in-flight lookup from restoring a block after a threshold or lifecycle change. The state is not
   persisted across server restarts.
+- Grok also keeps threshold and exhaustion blocks in memory. Its exhaustion block is request-class
+  scoped, and `/settings.on_demand_enabled = true` independently excludes the entire account
+  (`packages/api/src/utils/providers/grok/grok-dispatcher.ts`).
 - 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`.