@cartanova/qgrid-cli 2.10.10 → 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.10",
+  "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:

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/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`.