@toddzheng024/dscode-bundle 0.7.13 → 0.7.14

package/cordis.patch.yml

@@ -820,10 +820,14 @@
 
 
 - id: credentials
-  name: "@toddzheng024/dscode-bundle/credentials"
+  disabled: true
 - insert:
+    - id: dscode-credentials
+      name: "@toddzheng024/dscode-bundle/credentials"
     - id: dscode-openrouter
       name: "@toddzheng024/dscode-bundle/openrouter"
+    - id: dscode-grok
+      name: "@toddzheng024/dscode-bundle/grok"
     - id: dscode-auto-review
       name: "@toddzheng024/dscode-bundle/auto-review"
       config:

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.13",
+  "version": "0.7.14",
   "type": "module",
   "license": "MIT",
   "author": "Todd Zheng",
@@ -11,7 +11,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/qiz029/dscode"
+    "url": "https://github.com/qiz029/dscode.git"
   },
   "name": "@toddzheng024/dscode-bundle",
   "description": "DSCODE coding harness: minimal persistent shell, Ultra subagents, auto review, Chrome, computer use and session telemetry.",
@@ -55,6 +55,7 @@
     "./auto-review": "./plugins/auto-review/index.mjs",
     "./session-metrics": "./plugins/session-metrics/index.mjs",
     "./openrouter": "./plugins/openrouter/index.mjs",
+    "./grok": "./plugins/grok/index.mjs",
     "./tui-tools": "./plugins/tui-tools/index.mjs"
   },
   "dependencies": {

package/plugins/code-review/index.mjs

@@ -79,8 +79,11 @@ export function describeAttempt(tokens, assembler, finish) {
 }
 
 export function reviewRoute(fallback, env = process.env) {
-  // A verdict needs little deliberation: start at the lightest level the model offers.
-  const effort = typeof env.DSCODE_REVIEW_EFFORT === 'string' && env.DSCODE_REVIEW_EFFORT.trim() ? env.DSCODE_REVIEW_EFFORT.trim() : 'minimal';
+  // A verdict needs no deliberation, and a thinking reviewer spends the whole deadline
+  // reasoning before it writes one line: ask for thinking off, the only level that turns
+  // it off. A model without that level keeps its own default, because `chooseEffort`
+  // returns no effort at all when the wanted level is outside its standard levels.
+  const effort = typeof env.DSCODE_REVIEW_EFFORT === 'string' && env.DSCODE_REVIEW_EFFORT.trim() ? env.DSCODE_REVIEW_EFFORT.trim() : 'off';
   const wanted = typeof env.DSCODE_REVIEW_MODEL === 'string' ? env.DSCODE_REVIEW_MODEL.trim() : '';
   if (!wanted) return { route: fallback, effort };
   const at = wanted.indexOf('/');

package/plugins/compaction/threshold.mjs

@@ -16,6 +16,18 @@ export function thresholdForCacheRatio(ratio) {
   return rounded < 0.1 ? 0.9 : rounded < 0.5 ? 0.8 : 0.6;
 }
 
+/**
+ * How far below the priced threshold a background prefetch starts, as a share of
+ * the context window: at the default 80% threshold the prefetch mark is 70%.
+ */
+export const PREFETCH_LEAD_RATIO = 0.1;
+
+/** Token mark where a background prefetch starts; an unknown window leaves the threshold itself. */
+export function prefetchThresholdTokens(thresholdTokens, contextWindow, leadRatio = PREFETCH_LEAD_RATIO) {
+  if (!Number.isFinite(thresholdTokens) || !Number.isInteger(contextWindow) || contextWindow <= 0) return thresholdTokens;
+  return Math.max(0, thresholdTokens - Math.floor(contextWindow * leadRatio));
+}
+
 /** The route's threshold ratio, waiting for the OpenRouter listing when it has not loaded yet. */
 export async function pricedThresholdRatio(provider, model, now = Date.now()) {
   if (provider === 'openrouter') await ensureOpenRouterModels({ home: process.env.DSH_HOME, now });

package/plugins/credentials/index.mjs

@@ -4,6 +4,7 @@ import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local';
 import { Context, Service } from '@deepseek-ai/cordis';
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
 import { PROVIDERS } from '../providers/catalog.mjs';
+import { GROK_TOKEN_REF, grokAuthState } from '../grok/auth.mjs';
 
 // The `/provider` keys (DeepSeek, OpenRouter and its management key) live in the shared store.
 const SHARED = new Set(PROVIDERS.flatMap(provider => [provider.credentialRef, provider.managementRef].filter(Boolean)));
@@ -28,6 +29,12 @@ export default class DscodeCredentials extends LocalCredentialProvider {
     yield* super[Service.init]();
   }
   async resolve(ref) {
+    // dscode: the Grok subscription rail is the official CLI login, read-only. DSCODE never
+    // writes that file: the CLI owns refresh-token rotation, and two writers log the other out.
+    if (ref === GROK_TOKEN_REF) {
+      const state = grokAuthState();
+      return state.kind === 'ready' ? { value: state.credential.token, source: 'file' } : undefined;
+    }
     if (SHARED.has(ref)) {
       const stored = await this.shared.resolve(ref);
       if (stored?.source === 'env' || stored?.source === 'file') return stored;
@@ -35,6 +42,10 @@ export default class DscodeCredentials extends LocalCredentialProvider {
     return super.resolve(ref);
   }
   async describe(ref) {
+    if (ref === GROK_TOKEN_REF) {
+      const state = grokAuthState();
+      return state.kind === 'ready' ? { configured: true, source: 'file', writable: false } : { configured: false, writable: false };
+    }
     if (SHARED.has(ref)) {
       const facts = await this.shared.describe(ref);
       if (facts.source === 'env' || facts.source === 'file') return facts;
@@ -42,6 +53,8 @@ export default class DscodeCredentials extends LocalCredentialProvider {
     return super.describe(ref);
   }
   set(ref, value) {
+    // The CLI file is not a DSCODE store: saving here would go somewhere nothing reads.
+    if (ref === GROK_TOKEN_REF) throw new Error('GROK_CLI_TOKEN comes from ~/.grok/auth.json; run grok login instead');
     return SHARED.has(ref) ? this.shared.set(ref, value) : super.set(ref, value);
   }
   async unset(ref) {

package/plugins/grok/adapter.mjs

@@ -0,0 +1,114 @@
+import { LlmAdapter, LlmError, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { grokModel, listGrokModels } from "./models.mjs";
+import { PROVIDER, effortInfo, errorCode, errorMessage, requestBody, retryAfterMs, sseData, translate } from "./wire.mjs";
+
+export { PROVIDER };
+/** Context assumed for a model the catalog does not size. */
+export const DEFAULT_CONTEXT_WINDOW = 131072;
+/** Output cap materialized when a caller names none. */
+export const DEFAULT_OUTPUT_CAP = 131072;
+
+function modelInfo(provider, id, entry) {
+  return { provider, id, name: entry?.name ?? id, inputModalities: ["text"] };
+}
+
+/**
+ * xAI chat completions as a harness adapter: the subscription rail of the official grok
+ * CLI, over the model catalog that rail publishes. The connection facts and the token
+ * resolve per request, so a fresh `grok login` reaches the next call without a restart.
+ */
+export class GrokAdapter extends LlmAdapter {
+  /** @param config - `options()`, `ensureModels()`, `resolveToken()`, optional `fetch`. */
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+
+  providerInfo(provider) {
+    return { id: provider, name: "Grok" };
+  }
+
+  providerRetryPolicy() {
+    return this.config.options().retryPolicy;
+  }
+
+  /** Models that can drive an agent: the catalog the subscription rail filtered for this account. */
+  async listModels(provider) {
+    await this.config.ensureModels();
+    return listGrokModels().map(([id, entry]) => modelInfo(provider, id, entry));
+  }
+
+  async resolveModel(provider, model) {
+    await this.config.ensureModels();
+    const entry = grokModel(model);
+    const efforts = entry?.efforts ?? [];
+    return {
+      ...modelInfo(provider, model, entry),
+      context: { contextWindow: entry?.contextWindow ?? DEFAULT_CONTEXT_WINDOW },
+      ...entry?.maxOutput === undefined ? {} : { defaultMaxTokens: Math.min(entry.maxOutput, DEFAULT_OUTPUT_CAP) },
+      ...efforts.length === 0 ? {} : { reasoning: {
+        efforts: efforts.map(id => ({ ...effortInfo(id), id: ReasoningEffortId(id) })),
+        ...entry?.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(entry.defaultEffort) },
+      } },
+    };
+  }
+
+  async *stream(options) {
+    const connection = this.config.options();
+    const idle = new AbortController(), consumer = new AbortController();
+    let timer;
+    const pulse = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => idle.abort(new Error("Grok stream idle")), connection.streamIdleTimeoutMs);
+      timer.unref?.();
+    };
+    const signal = AbortSignal.any([idle.signal, consumer.signal, ...options.signal ? [options.signal] : []]);
+    try {
+      const token = await this.config.resolveToken();
+      await this.config.ensureModels();
+      const entry = grokModel(options.model);
+      const body = requestBody(options, { entry });
+      pulse();
+      const fetchImpl = this.config.fetch ?? globalThis.fetch;
+      let response;
+      try {
+        response = await fetchImpl(connection.baseURL + "/chat/completions", {
+          method: "POST",
+          headers: { authorization: "Bearer " + token, "content-type": "application/json", accept: "text/event-stream" },
+          body: JSON.stringify(body),
+          signal,
+        });
+      } catch (error) {
+        if (signal.aborted) throw error;
+        throw new LlmError(`Grok request to ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
+      }
+      if (!response.ok || !response.headers.get("content-type")?.includes("text/event-stream")) {
+        const raw = await response.text();
+        let error;
+        try { error = JSON.parse(raw)?.error; } catch { /* not JSON */ }
+        if (response.ok && error === undefined) throw new LlmError(`Grok returned a non-stream response: ${raw.slice(0, 120)}`, "MALFORMED_RESPONSE");
+        const delay = retryAfterMs(response.headers.get("retry-after"));
+        const status = response.ok ? Number.isInteger(error?.code) ? error.code : undefined : response.status;
+        throw new LlmError(errorMessage(error, `Grok API error (HTTP ${response.status})`), errorCode(response.ok ? undefined : response.status, error), {
+          cause: new Error(raw.length > 0 ? raw : `Grok HTTP ${response.status}`),
+          ...status === undefined ? {} : { status },
+          ...delay === undefined ? {} : { providerRetryAfterMs: delay },
+        });
+      }
+      if (!response.body) throw new LlmError("Grok returned no response body", "EMPTY_RESPONSE");
+      for await (const chunk of translate(sseData(response.body, pulse), { model: options.model })) {
+        clearTimeout(timer);
+        yield chunk;
+        pulse();
+      }
+    } catch (error) {
+      if (idle.signal.aborted && !options.signal?.aborted) throw new LlmError(`Grok stream idle timeout after ${connection.streamIdleTimeoutMs}ms`, "TIMEOUT", { cause: error });
+      if (options.signal?.aborted) throw new LlmError("Grok request aborted by caller", "ABORTED", { cause: error });
+      if (error instanceof LlmError) throw error;
+      throw new LlmError(`Grok API stream from ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
+    } finally {
+      clearTimeout(timer);
+      consumer.abort("Grok stream consumer stopped");
+    }
+  }
+}

package/plugins/grok/auth.mjs

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// dscode: the Grok subscription rail authenticates with the OAuth credentials the
+// official `grok` CLI stores after `grok login`. DSCODE reads that file and never writes
+// it: the CLI owns token rotation, and a refresh token rotated by a second writer would
+// log the CLI out (the same trap the Hub token rotation sets). An expired token is
+// reported with the command that fixes it, never silently refreshed.
+
+/** The file the grok CLI writes: one entry per issuer/client, keyed `https://auth.x.ai::<client id>`. */
+export const GROK_AUTH_PATH = join(homedir(), ".grok", "auth.json");
+/** Credential ref the `/provider` machinery reads; resolved read-only from the CLI file. */
+export const GROK_TOKEN_REF = "GROK_CLI_TOKEN";
+
+/** Decode a JWT payload without verifying: only `exp`/`sub` are read, and xAI validates the token. */
+function jwtClaims(token) {
+  try {
+    return JSON.parse(Buffer.from(String(token).split(".")[1], "base64").toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One CLI credential from a parsed auth file: the first issuer entry, whose access token
+ * is `key`. Unknown shapes answer undefined instead of throwing.
+ * @returns `{ token, refreshToken?, userId?, expiresAt?, issuer?, clientId? }`, or undefined.
+ */
+export function parseGrokAuth(value) {
+  if (value === null || typeof value !== "object") return undefined;
+  for (const [name, entry] of Object.entries(value)) {
+    if (entry === null || typeof entry !== "object") continue;
+    if (typeof entry.key !== "string" || entry.key.length === 0) continue;
+    const claims = jwtClaims(entry.key);
+    const expiresAt = Number.isFinite(claims?.exp) ? claims.exp * 1000 : Date.parse(entry.expires_at ?? "");
+    return {
+      token: entry.key,
+      ...typeof entry.refresh_token === "string" && entry.refresh_token.length > 0 ? { refreshToken: entry.refresh_token } : {},
+      ...typeof entry.user_id === "string" && entry.user_id.length > 0 ? { userId: entry.user_id } : typeof claims?.sub === "string" ? { userId: claims.sub } : {},
+      ...Number.isFinite(expiresAt) ? { expiresAt } : {},
+      ...name.includes("::") ? { issuer: name.split("::")[0], clientId: name.split("::")[1] } : {},
+    };
+  }
+  return undefined;
+}
+
+/**
+ * The local Grok login as one fact set, with no I/O of its own beyond the injected read.
+ * @returns `{ kind: "ready"|"expired"|"missing"|"malformed", credential? }`; a missing file
+ *   means the user never ran `grok login`, a malformed one means the CLI changed its shape.
+ */
+export function grokAuthState({ now = Date.now(), read = () => readFileSync(GROK_AUTH_PATH, "utf8") } = {}) {
+  let raw;
+  try {
+    raw = read();
+  } catch {
+    return { kind: "missing" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "malformed" };
+  }
+  const credential = parseGrokAuth(parsed);
+  if (credential === undefined) return { kind: "malformed" };
+  if (credential.expiresAt !== undefined && credential.expiresAt <= now) return { kind: "expired", credential };
+  return { kind: "ready", credential };
+}
+
+/** Minutes until the access token expires, or undefined when the file carries no expiry. */
+export function minutesLeft(credential, now = Date.now()) {
+  if (credential?.expiresAt === undefined) return undefined;
+  return Math.max(0, Math.round((credential.expiresAt - now) / 60000));
+}

package/plugins/grok/billing.mjs

@@ -0,0 +1,146 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// dscode: what the Grok subscription left, and when it resets. The CLI proxy answers two
+// payloads on the same credential the models come from: /settings names the tier, and
+// /billing?format=credits carries the weekly window plus the used percentage. The
+// percentage is optional (the server omits it when a period has no usage), so the status
+// line has three states: a number, no usage recorded yet, and unreadable.
+//
+// This is the undocumented rail the official CLI itself reads; every field is optional and
+// a shape change must degrade to "usage unavailable", never to a crash or a wrong number.
+
+export const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+export const GROK_SETTINGS_URL = "https://cli-chat-proxy.grok.com/v1/settings";
+/** The CLI re-reads its subscription every 60s (`subscription_watch_interval_secs`); so does DSCODE. */
+export const GROK_SUBSCRIPTION_TTL_MS = 60_000;
+const FILE = "grok-subscription.json";
+const VERSION = 1;
+let state;
+let fetchedAt = 0;
+let pending;
+let disk;
+
+const finite = value => Number.isFinite(Number(value)) ? Number(value) : undefined;
+const percent = value => {
+  const number = finite(value);
+  return number === undefined ? undefined : Math.min(100, Math.max(0, number));
+};
+const stamp = value => typeof value === "string" && value.length > 0 ? value : undefined;
+
+/**
+ * The weekly credit window from one `/billing?format=credits` body.
+ * @returns `{ usedPercent?, periodStart?, periodEnd?, periodType?, onDemandCap?, onDemandUsed?,
+ *   prepaidBalance?, unified? }` with unknown fields left out.
+ */
+export function parseGrokCredits(body) {
+  const config = body?.config ?? {};
+  const period = config.currentPeriod ?? {};
+  const used = percent(config.creditUsagePercent);
+  const onDemandCap = finite(config.onDemandCap?.val);
+  const onDemandUsed = finite(config.onDemandUsed?.val);
+  const prepaid = finite(config.prepaidBalance?.val);
+  const periodEnd = stamp(period.end) ?? stamp(config.billingPeriodEnd);
+  const periodStart = stamp(period.start) ?? stamp(config.billingPeriodStart);
+  return {
+    ...used === undefined ? {} : { usedPercent: used },
+    ...periodStart === undefined ? {} : { periodStart },
+    ...periodEnd === undefined ? {} : { periodEnd },
+    ...stamp(period.type) === undefined ? {} : { periodType: stamp(period.type) },
+    ...onDemandCap === undefined ? {} : { onDemandCap },
+    ...onDemandUsed === undefined ? {} : { onDemandUsed },
+    ...prepaid === undefined ? {} : { prepaidBalance: prepaid },
+    ...config.isUnifiedBillingUser === true ? { unified: true } : {},
+  };
+}
+
+/** The plan facts from one `/settings` body: the tier label and the access gate. */
+export function parseGrokSettings(body) {
+  const tier = stamp(body?.subscription_tier_display);
+  const gate = stamp(body?.gate_message);
+  const gateUrl = stamp(body?.gate_url);
+  return {
+    ...tier === undefined ? {} : { tier },
+    ...stamp(body?.default_model) === undefined ? {} : { defaultModel: stamp(body.default_model) },
+    ...body?.allow_access === false ? { blocked: true } : {},
+    ...gate === undefined ? {} : { gateMessage: gate },
+    ...gateUrl === undefined ? {} : { gateUrl },
+  };
+}
+
+/** Both reads at once; either half may fail without losing the other. */
+export async function fetchGrokSubscription({ token, userId, version = "1.0.34", fetch: fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  if (typeof fetchImpl !== "function") return undefined;
+  const headers = { authorization: "Bearer " + token, accept: "application/json", "x-xai-token-auth": "xai-grok-cli", "x-authenticateresponse": "authenticate-response", "x-grok-client-version": version, ...userId === undefined ? {} : { "x-userid": userId } };
+  const read = async url => {
+    try {
+      const response = await fetchImpl(url, { headers });
+      return response.ok ? await response.json() : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  const [credits, settings] = await Promise.all([read(GROK_BILLING_URL), read(GROK_SETTINGS_URL)]);
+  if (credits === undefined && settings === undefined) return undefined;
+  return { ...parseGrokSettings(settings), ...parseGrokCredits(credits), fetchedAt: now };
+}
+
+/** The state the status line renders: cached for one refresh interval, one request in flight. */
+export async function currentGrokSubscription({ home, ...options } = {}) {
+  if (state !== undefined && Date.now() - fetchedAt < GROK_SUBSCRIPTION_TTL_MS) return state;
+  if (pending) return pending;
+  pending = (async () => {
+    const next = await fetchGrokSubscription(options);
+    if (next !== undefined) {
+      state = next;
+      fetchedAt = next.fetchedAt ?? Date.now();
+      if (home !== undefined) writeGrokSubscription(home, next);
+    }
+    return state;
+  })().finally(() => { pending = undefined; });
+  return pending;
+}
+
+/** The last written subscription state, or undefined before the first successful read. */
+export function readGrokSubscription(home) {
+  try {
+    const cached = JSON.parse(readFileSync(join(home, FILE), "utf8"));
+    return cached?.version === VERSION && typeof cached === "object" ? cached : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Atomic write of one state snapshot; a failure leaves the previous file alone. */
+export function writeGrokSubscription(home, snapshot) {
+  try {
+    mkdirSync(home, { recursive: true });
+    const path = join(home, FILE);
+    writeFileSync(path + ".tmp", JSON.stringify({ version: VERSION, ...snapshot }));
+    renameSync(path + ".tmp", path);
+  } catch { /* the status line simply keeps its previous state */ }
+}
+
+/** Replace the in-memory state; for tests. */
+export function setGrokSubscription(next, at = Date.now()) {
+  state = next;
+  fetchedAt = at;
+  pending = undefined;
+  disk = undefined;
+}
+
+/**
+ * The cached state without waiting for a fetch; the view uses this during a render. The live
+ * process wins, then the state file the panel already reads, so a footer drawn before the
+ * first refresh — or one drawn while the network is down — still shows the last window
+ * instead of falling back to a bare tier name. One file read per refresh window keeps the
+ * render path off the disk.
+ */
+export function grokSubscriptionNow(home = process.env.DSH_HOME) {
+  if (state !== undefined) return state;
+  if (home === undefined) return undefined;
+  if (disk !== undefined && disk.home === home && Date.now() - disk.at < GROK_SUBSCRIPTION_TTL_MS) return disk.value;
+  const value = readGrokSubscription(home);
+  disk = { home, at: Date.now(), value };
+  return value;
+}

package/plugins/grok/index.mjs

@@ -0,0 +1,118 @@
+import z from "@deepseek-ai/schemastery";
+import { RetryPolicySchema, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { GrokAdapter, PROVIDER } from "./adapter.mjs";
+import { ensureGrokModels } from "./models.mjs";
+import { GROK_SUBSCRIPTION_TTL_MS, currentGrokSubscription } from "./billing.mjs";
+import { GROK_TOKEN_REF, grokAuthState } from "./auth.mjs";
+
+// dscode: the `grok` route — the SuperGrok / X Premium+ subscription the official grok CLI
+// already signed in for, driven through xAI chat completions. The token is read (never
+// written) from the CLI credential file, the catalog and the weekly credit window come from
+// the same CLI proxy the official client uses, and the status line reads the cached window
+// instead of a dollar balance: a subscription has credits, not a bill.
+export const name = "dscode-grok";
+export const inject = ["llm"];
+const NS = "llm-grok";
+const DEFAULT_BASE_URL = "https://api.x.ai/v1";
+/** The client version the CLI proxy is asked with; xAI refuses requests without one. */
+const DEFAULT_CLIENT_VERSION = "1.0.34";
+
+export const Config = z.object({
+  apiKeyEnv: z.string().role("credential-ref").default(GROK_TOKEN_REF),
+  baseURL: z.string().default(DEFAULT_BASE_URL),
+  clientVersion: z.string().default(DEFAULT_CLIENT_VERSION),
+  streamIdleTimeoutMs: z.number().min(1).default(300000),
+  retryPolicy: RetryPolicySchema,
+});
+
+/** Validated connection facts from one config snapshot. */
+export function resolveOptions(config = {}) {
+  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? 300000;
+  if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0) throw new Error(name + ": streamIdleTimeoutMs must be a positive number");
+  const baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  if (!URL.canParse(baseURL)) throw new Error(name + ": baseURL must be a URL");
+  return {
+    apiKeyEnv: credentialRef(config.apiKeyEnv || GROK_TOKEN_REF),
+    baseURL,
+    clientVersion: config.clientVersion || DEFAULT_CLIENT_VERSION,
+    streamIdleTimeoutMs,
+    retryPolicy: resolveRetryPolicy(config.retryPolicy, name + ": retryPolicy"),
+  };
+}
+
+/** The message a missing or expired CLI login deserves: the fix is a command, not a paste. */
+export function loginHint(state) {
+  if (state.kind === 'missing') return name + ': no local grok login found; run "grok login" (DSCODE reads ~/.grok/auth.json read-only)';
+  if (state.kind === 'expired') return name + ': the local grok login expired; run "grok login" again (DSCODE never rotates that token)';
+  return name + ': the local grok login file was not readable; run "grok login" again';
+}
+
+export function apply(ctx, config = {}) {
+  let current = () => config, lastRaw, lastGood;
+  const options = () => {
+    const raw = current();
+    if (raw === lastRaw && lastGood !== undefined) return lastGood;
+    try {
+      lastGood = resolveOptions(raw);
+      lastRaw = raw;
+      return lastGood;
+    } catch (error) {
+      if (lastGood === undefined) throw error;
+      lastRaw = raw;
+      ctx.logger.error(name + ": keeping the last good configuration after an invalid settings section");
+      return lastGood;
+    }
+  };
+  options();
+  const home = process.env.DSH_HOME;
+  /** The credential the route calls with, or undefined: the catalog must load without a login. */
+  const resolveTokenSafe = async () => {
+    const ref = options().apiKeyEnv;
+    const credentials = ctx.get("credentials");
+    try {
+      const stored = credentials === undefined ? launchEnvironmentOf(ctx).get(ref)?.value : (await credentials.resolve(ref))?.value;
+      if (stored !== undefined && stored.length > 0) return stored;
+    } catch { /* fall through to the local login state for a better message */ }
+    const state = grokAuthState();
+    return state.kind === "ready" ? state.credential.token : undefined;
+  };
+  const resolveToken = async () => {
+    const token = await resolveTokenSafe();
+    if (token !== undefined) return token;
+    throw new Error(loginHint(grokAuthState()));
+  };
+  const ensureModels = async () => {
+    const token = await resolveTokenSafe();
+    if (token === undefined) return;
+    await ensureGrokModels({ home, token, version: options().clientVersion });
+  };
+  const adapter = new GrokAdapter({ options, ensureModels, resolveToken });
+  ctx.llm.registerConfigurableProviders([{ provider: PROVIDER, displayName: "Grok", settingsNs: NS, settingsPath: [] }]);
+  const registration = ctx.llm.registerAdapter([PROVIDER], adapter);
+  let registeredPolicy = JSON.stringify(options().retryPolicy);
+  ctx.inject(["settings"], settingsCtx => {
+    settingsCtx.settings.installSection(ctx, NS, Config, config, {
+      setSource: source => { current = source; },
+      onChange: () => {
+        const policy = JSON.stringify(options().retryPolicy);
+        if (policy === registeredPolicy) return;
+        registration.replace([PROVIDER]);
+        registeredPolicy = policy;
+      },
+    });
+  });
+  // Warm the catalog and the weekly window for a user who already ran `grok login`, then keep
+  // the window fresh at the interval the official CLI itself watches (subscription_watch_interval_secs).
+  const refresh = async () => {
+    const state = grokAuthState();
+    if (state.kind !== "ready") return;
+    await ensureGrokModels({ home, token: state.credential.token, version: options().clientVersion });
+    await currentGrokSubscription({ home, token: state.credential.token, userId: state.credential.userId, version: options().clientVersion });
+  };
+  void refresh().catch(() => {});
+  const timer = setInterval(() => { void refresh().catch(() => {}); }, GROK_SUBSCRIPTION_TTL_MS);
+  timer.unref?.();
+  ctx.effect(() => () => clearInterval(timer));
+}