dsh-grok-subscription 0.1.3 → 0.1.13

package/lib/index.js

@@ -8,6 +8,7 @@ var CREDENTIAL_REF_NAME = "GROK_BUILD_ACCESS_TOKEN";
 var PROXY_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
 var RESPONSES_URL = "https://cli-chat-proxy.grok.com/v1/responses";
 var MODELS_V2_URL = "https://cli-chat-proxy.grok.com/v1/models-v2";
+var BILLING_CREDITS_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
 var TOKEN_AUTH_HEADER = "X-XAI-Token-Auth";
 var TOKEN_AUTH_VALUE = "xai-grok-cli";
 var CLIENT_IDENTIFIER_HEADER = "x-grok-client-identifier";
@@ -19,11 +20,16 @@ var SESSION_AUTH_MODES = Object.freeze(["oidc", "external", "web_login", "grok"]
 var API_KEY_AUTH_MODES = Object.freeze(["api_key"]);
 var AUTH_FILE_MAX_BYTES = 1048576;
 var CATALOG_TIMEOUT_MS = 15e3;
+var USAGE_TIMEOUT_MS = 8e3;
+var STORE_TOKEN_TIMEOUT_MS = 5e3;
 var STREAM_IDLE_TIMEOUT_MS = 10 * 60 * 1e3;
 var MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
 var REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048;
 var REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
 var FALLBACK_MODEL_IDS = Object.freeze(["grok-4.7", "grok-4.6", "grok-4.5"]);
+var IMPORT_TIMEOUT_MS = 2500;
+var CREDENTIALS_IO_TIMEOUT_MS = 1500;
+var RPC_HANDLER_TIMEOUT_MS = 8e3;
 
 // src/session.js
 import { existsSync as existsSync2 } from "node:fs";
@@ -401,273 +407,312 @@ async function loadCatalog(accessToken, options = {}) {
   }
 }
 
-// src/session.js
-function resolveGrokBin(env = process.env, exists = existsSync2) {
-  if (typeof env.DSH_GROK_BIN === "string" && env.DSH_GROK_BIN.trim()) return env.DSH_GROK_BIN.trim();
-  const local = join2(grokHome(env), "bin", "grok");
-  if (exists(local)) return local;
-  return "grok";
+// src/usage.js
+var USAGE_SOURCE = "billing-credits-undocumented";
+var SHANGHAI_TZ = "Asia/Shanghai";
+function unavailable(reason) {
+  return Object.freeze({
+    status: "unavailable",
+    reason: typeof reason === "string" && reason.trim() ? reason.trim() : "Usage unavailable",
+    experimental: true,
+    source: USAGE_SOURCE
+  });
 }
-function grokCliAvailable(env = process.env, exists = existsSync2) {
-  const bin = resolveGrokBin(env, exists);
-  if (bin.includes("/") || bin.includes("\\")) return exists(bin);
-  const delimiter = process.platform === "win32" ? ";" : ":";
-  return String(env.PATH ?? "").split(delimiter).some((dir) => dir && exists(join2(dir, bin)));
+function asFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  if (value && typeof value === "object" && !Array.isArray(value) && "val" in value) {
+    return asFiniteNumber(value.val);
+  }
+  return void 0;
 }
-function spawnGrokLogin(options = {}) {
-  const spawnFn = options.spawn ?? spawn;
-  const bin = resolveGrokBin(options.env, options.exists);
-  const args = options.device ? ["login", "--device-auth"] : ["login"];
-  return new Promise((resolve, reject) => {
-    const child = spawnFn(bin, args, {
-      stdio: options.stdio ?? "inherit",
-      env: options.env ?? process.env
-    });
-    child.on("error", (error) => {
-      reject(new Error(`Could not start grok CLI (${bin})`, { cause: error }));
-    });
-    child.on("exit", (code, signal) => {
-      if (code === 0) resolve({ ok: true, code });
-      else reject(new Error(signal ? `grok login terminated by ${signal}` : `grok login exited with code ${code ?? "unknown"}`));
-    });
-  });
+function asFinitePercent(value) {
+  return asFiniteNumber(value);
+}
+function asIsoString(value) {
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  const trimmed = value.trim();
+  const ms = Date.parse(trimmed);
+  if (!Number.isFinite(ms)) return void 0;
+  return new Date(ms).toISOString();
 }
-async function credentialRefOf() {
+function formatShanghai(iso) {
+  if (!iso) return void 0;
   try {
-    const mod = await import("@deepseek-ai/dsh-credentials");
-    if (typeof mod.credentialRef === "function") return mod.credentialRef(CREDENTIAL_REF_NAME);
+    return new Intl.DateTimeFormat("zh-CN", {
+      timeZone: SHANGHAI_TZ,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false
+    }).format(new Date(iso));
   } catch {
+    return void 0;
   }
-  return CREDENTIAL_REF_NAME;
 }
-function createSessionService({ credentials, logger, onCatalogChange } = {}) {
-  let catalog = { models: [], source: "signed-out", error: void 0 };
-  let lastPublic = publicSessionView(void 0);
-  const notifyCatalogChange = () => {
-    try {
-      onCatalogChange?.();
-    } catch (error) {
-      logger?.warn?.(
-        "Grok subscription catalog change notify failed: %s",
-        error instanceof Error ? error.message : "unknown"
-      );
-    }
-  };
-  const readStoredToken = async () => {
-    if (!credentials?.resolve) return void 0;
-    const hit = await credentials.resolve(await credentialRefOf());
-    const value = hit?.value;
-    return typeof value === "string" && value.length > 0 ? value : void 0;
-  };
-  const storeToken = async (token) => {
-    if (!credentials?.set) throw new Error("DSH credentials service is unavailable");
-    await credentials.set(await credentialRefOf(), token);
-  };
-  const clearToken = async () => {
-    if (!credentials?.unset) return;
-    await credentials.unset(await credentialRefOf());
-  };
-  const pull = async () => {
-    const parsed = readGrokAuthSession();
-    if (!parsed.session) {
-      catalog = { models: [], source: "signed-out", error: void 0 };
-      lastPublic = publicSessionView(void 0);
-      await clearToken();
-      const message = parsed.reason === "api-key-only" ? "Found an API-key entry only. Sign in with SuperGrok / X Premium via grok login." : "No Grok Build subscription session in auth.json. Run grok login first.";
-      notifyCatalogChange();
-      return { ok: false, error: message, account: lastPublic, catalog };
-    }
-    await storeToken(parsed.session.accessToken);
-    lastPublic = publicSessionView(parsed.session);
-    catalog = await loadCatalog(parsed.session.accessToken);
-    notifyCatalogChange();
-    return { ok: true, account: lastPublic, catalog };
-  };
-  const status = async () => {
-    let token;
-    try {
-      token = await readStoredToken();
-    } catch (error) {
-      logger?.warn?.("could not resolve Grok subscription credential: %s", error instanceof Error ? error.message : "unknown");
-      token = void 0;
-    }
-    if (!token) {
-      lastPublic = publicSessionView(void 0);
-      catalog = { models: [], source: "signed-out", error: void 0 };
-      return { account: lastPublic, catalog, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
-    }
-    if (lastPublic.signedIn !== true) {
-      try {
-        const parsed = readGrokAuthSession();
-        if (parsed.session) lastPublic = publicSessionView(parsed.session);
-        else lastPublic = Object.freeze({ signedIn: true, maskedAccount: "\u2022\u2022\u2022\u2022", authMode: "oidc", source: "dsh-credentials" });
-      } catch {
-        lastPublic = Object.freeze({ signedIn: true, maskedAccount: "\u2022\u2022\u2022\u2022", authMode: "oidc", source: "dsh-credentials" });
-      }
-    }
-    return { account: lastPublic, catalog, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
-  };
-  const refreshCatalog = async () => {
-    const token = await readStoredToken();
-    if (!token) {
-      catalog = { models: [], source: "signed-out", error: void 0 };
-      notifyCatalogChange();
-      return catalog;
-    }
-    catalog = await loadCatalog(token);
-    notifyCatalogChange();
-    return catalog;
-  };
-  const login = async (options) => {
-    await spawnGrokLogin(options);
-    return pull();
-  };
-  const logout = async () => {
-    await clearToken();
-    catalog = { models: [], source: "signed-out", error: void 0 };
-    lastPublic = publicSessionView(void 0);
-    notifyCatalogChange();
-    return { ok: true, account: lastPublic, catalog };
-  };
-  return {
-    pull,
-    status,
-    refreshCatalog,
-    login,
-    logout,
-    currentToken: readStoredToken,
-    models: () => catalog.models,
-    catalog: () => catalog,
-    publicAccount: () => lastPublic
-  };
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-
-// src/rpc-contract.js
-var RPC_ENDPOINTS = Object.freeze([
-  "status",
-  "login/cli",
-  "login/device",
-  "pull",
-  "logout",
-  "catalog/refresh"
-]);
-function publicResult(value) {
-  return { ok: true, value };
+function topLevelKeys(body) {
+  return Object.keys(body).filter((key) => typeof key === "string").slice(0, 24);
 }
-function publicError(error, fallback = "Grok subscription request failed") {
-  const message = error instanceof Error ? error.message : fallback;
-  return { ok: false, error: { code: "internal", message, details: { issues: [] } } };
+function missingPercentReason(body) {
+  const keys = topLevelKeys(body);
+  if (keys.length === 0) {
+    return "Missing creditUsagePercent (empty object)";
+  }
+  return `Missing creditUsagePercent (keys: ${keys.join(",")})`;
 }
-
-// src/rpc.js
-function stripSecrets(value) {
-  if (!value || typeof value !== "object") return value;
-  const next = { ...value };
-  delete next.accessToken;
-  delete next.token;
-  delete next.refresh;
-  delete next.refresh_token;
-  delete next.key;
-  if (next.catalog) {
-    next.catalog = {
-      source: next.catalog.source,
-      error: next.catalog.error,
-      models: Array.isArray(next.catalog.models) ? next.catalog.models.map((model) => ({
-        id: model.id,
-        name: model.name,
-        contextWindow: model.contextWindow,
-        reasoning: model.reasoning,
-        source: model.source
-      })) : []
-    };
+function firstDefined(...values) {
+  for (const value of values) {
+    if (value !== void 0 && value !== null) return value;
   }
-  if (next.account) {
-    next.account = {
-      signedIn: next.account.signedIn === true,
-      maskedAccount: next.account.maskedAccount,
-      authMode: next.account.authMode,
-      expiresAt: next.account.expiresAt,
-      source: next.account.source
-    };
+  return void 0;
+}
+function readPercentCandidate(node) {
+  if (!isPlainObject(node)) return void 0;
+  return asFinitePercent(firstDefined(
+    node.creditUsagePercent,
+    node.usedPercent,
+    node.usagePercent,
+    node.percentUsed,
+    node.used_percent,
+    node.usage_percent
+  ));
+}
+function resolveUsedPercent(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  const usage = isPlainObject(body.usage) ? body.usage : void 0;
+  const credits = isPlainObject(body.credits) ? body.credits : void 0;
+  const direct = firstDefined(
+    readPercentCandidate(body),
+    readPercentCandidate(config),
+    readPercentCandidate(usage),
+    readPercentCandidate(credits),
+    asFinitePercent(credits?.usedPercent)
+  );
+  if (direct !== void 0) return direct;
+  const used = firstDefined(
+    asFiniteNumber(body.used),
+    asFiniteNumber(body.includedUsed),
+    asFiniteNumber(body.totalUsed),
+    asFiniteNumber(config?.includedUsed),
+    asFiniteNumber(config?.totalUsed),
+    asFiniteNumber(usage?.used),
+    asFiniteNumber(credits?.used)
+  );
+  const total = firstDefined(
+    asFiniteNumber(body.total),
+    asFiniteNumber(body.monthlyLimit),
+    asFiniteNumber(config?.monthlyLimit),
+    asFiniteNumber(usage?.total),
+    asFiniteNumber(credits?.total),
+    asFiniteNumber(credits?.limit)
+  );
+  if (used !== void 0 && total !== void 0 && total > 0) {
+    return used / total * 100;
   }
-  return next;
+  return void 0;
 }
-function createRpcHandler(session) {
-  return async function handle(endpoint, _payload, _signal) {
-    try {
-      if (endpoint === "status") return publicResult(stripSecrets(await session.status()));
-      if (endpoint === "pull") return publicResult(stripSecrets(await session.pull()));
-      if (endpoint === "logout") return publicResult(stripSecrets(await session.logout()));
-      if (endpoint === "catalog/refresh") {
-        const catalog = await session.refreshCatalog();
-        return publicResult(stripSecrets({ catalog, account: session.publicAccount() }));
-      }
-      if (endpoint === "login/cli") return publicResult(stripSecrets(await session.login({ device: false })));
-      if (endpoint === "login/device") return publicResult(stripSecrets(await session.login({ device: true })));
-      return publicError(new Error(`Unknown Grok subscription RPC: ${endpoint}`));
-    } catch (error) {
-      return publicError(error);
-    }
-  };
+function resolvePeriodBounds(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  const period = firstDefined(
+    isPlainObject(config?.currentPeriod) ? config.currentPeriod : void 0,
+    isPlainObject(body.currentPeriod) ? body.currentPeriod : void 0,
+    isPlainObject(body.period) ? body.period : void 0
+  );
+  const start = firstDefined(
+    period ? asIsoString(period.start) : void 0,
+    asIsoString(config?.billingPeriodStart),
+    asIsoString(body.billingPeriodStart),
+    asIsoString(body.periodStart),
+    asIsoString(body.resetStart)
+  );
+  const end = firstDefined(
+    period ? asIsoString(period.end) : void 0,
+    asIsoString(config?.billingPeriodEnd),
+    asIsoString(body.billingPeriodEnd),
+    asIsoString(body.periodEnd),
+    asIsoString(body.resetAt),
+    asIsoString(body.reset_at)
+  );
+  return { start, end };
 }
-
-// src/transport.js
-function parseEnvelope(body, method) {
-  if (!body || typeof body !== "object") return void 0;
-  if (body.method !== method) return void 0;
-  return {
-    rpcId: body.rpcId,
-    payload: body.payload
-  };
+function resolveProductUsage(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  return firstDefined(
+    Array.isArray(body.productUsage) ? body.productUsage : void 0,
+    Array.isArray(config?.productUsage) ? config.productUsage : void 0,
+    Array.isArray(body.products) ? body.products : void 0
+  );
 }
-function registerSubscriptionTransport(connection, handler) {
-  const disposers = [];
+function sanitizeProductUsage(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const rows = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const name2 = typeof item.name === "string" && item.name.trim() ? item.name.trim() : typeof item.product === "string" && item.product.trim() ? item.product.trim() : typeof item.id === "string" && item.id.trim() ? item.id.trim() : void 0;
+    const usedPercent = asFinitePercent(firstDefined(
+      item.creditUsagePercent,
+      item.usedPercent,
+      item.usagePercent,
+      item.percentUsed,
+      item.used_percent
+    ));
+    if (!name2 && usedPercent === void 0) continue;
+    rows.push(Object.freeze({
+      ...name2 ? { name: name2 } : {},
+      ...usedPercent !== void 0 ? { usedPercent } : {}
+    }));
+  }
+  return rows.length ? Object.freeze(rows) : void 0;
+}
+function parseBillingCredits(body) {
+  if (body === null || body === void 0) {
+    return unavailable("Empty billing response");
+  }
+  if (typeof body !== "object" || Array.isArray(body)) {
+    return unavailable("Unexpected billing response shape");
+  }
+  const usedPercent = resolveUsedPercent(body);
+  if (usedPercent === void 0) {
+    return unavailable(missingPercentReason(body));
+  }
+  const { start: periodStart, end: periodEnd } = resolvePeriodBounds(body);
+  const productUsage = sanitizeProductUsage(resolveProductUsage(body));
+  const remainingPercent = Math.max(0, 100 - usedPercent);
+  return Object.freeze({
+    status: "ok",
+    experimental: true,
+    source: USAGE_SOURCE,
+    usedPercent,
+    remainingPercent,
+    ...periodStart ? { periodStart, periodStartLocal: formatShanghai(periodStart) } : {},
+    ...periodEnd ? { periodEnd, periodEndLocal: formatShanghai(periodEnd) } : {},
+    ...productUsage ? { productUsage } : {}
+  });
+}
+function parseBillingCreditsJson(text) {
+  if (typeof text !== "string") return unavailable("Non-text billing response");
+  if (!text.trim()) return unavailable("Empty billing response");
+  let body;
   try {
-    for (const endpoint of RPC_ENDPOINTS) {
-      const method = `grok-subscription/${endpoint}`;
-      if (typeof connection?.fetch?.register !== "function") {
-        throw new Error("DSH connection.fetch.register is unavailable");
-      }
-      disposers.push(connection.fetch.register({
-        path: `/api/${method}`,
-        methods: ["POST"],
-        requestBody: "buffered",
-        async fetch(request) {
-          if (request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
-            return new Response("content type must be application/json", { status: 415 });
-          }
-          let body;
-          try {
-            body = await request.json();
-          } catch {
-            return new Response("invalid JSON", { status: 400 });
-          }
-          const envelope = parseEnvelope(body, method);
-          if (!envelope) return new Response("invalid RPC envelope", { status: 400 });
-          let result;
-          try {
-            request.signal?.throwIfAborted?.();
-            result = await handler(endpoint, envelope.payload, request.signal);
-          } catch {
-            result = { ok: false, error: { code: "internal", message: "Grok subscription request failed", details: { issues: [] } } };
-          }
-          return Response.json({ type: "server-response", rpcId: envelope.rpcId, result });
-        }
-      }));
+    body = JSON.parse(text);
+  } catch {
+    return unavailable("Invalid JSON from billing API");
+  }
+  return parseBillingCredits(body);
+}
+async function fetchBillingUsageOnce(accessToken, options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    return unavailable("Fetch unavailable");
+  }
+  let response;
+  try {
+    const signal = options.signal ?? AbortSignal.timeout(options.timeoutMs ?? USAGE_TIMEOUT_MS);
+    response = await fetchImpl(BILLING_CREDITS_URL, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        ...buildProxyHeaders(accessToken, options)
+      },
+      redirect: "error",
+      signal
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "network error";
+    if (/abort|timeout/i.test(message)) return unavailable("Billing request timed out");
+    return unavailable("Billing network error");
+  }
+  if (response.status === 401 || response.status === 403) {
+    return unavailable(`Billing unauthorized (HTTP ${response.status})`);
+  }
+  if (!response.ok) {
+    return unavailable(`Billing HTTP ${response.status}`);
+  }
+  const rawContentType = typeof response.headers?.get === "function" ? response.headers.get("content-type") ?? "" : "";
+  const contentType = String(rawContentType).split(";")[0].trim();
+  const contentTypeLower = contentType.toLowerCase();
+  const looksJson = !contentTypeLower || contentTypeLower.includes("json") || contentTypeLower === "text/plain";
+  let text;
+  try {
+    text = await response.text();
+  } catch {
+    return unavailable("Could not read billing body");
+  }
+  if (!looksJson) {
+    const parsedAnyway = parseBillingCreditsJson(text);
+    if (parsedAnyway.status === "ok") {
+      return Object.freeze({
+        ...parsedAnyway,
+        fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
     }
+    return unavailable(`Non-JSON billing Content-Type: ${contentType || "unknown"}`);
+  }
+  const parsed = parseBillingCreditsJson(text);
+  if (parsed.status === "ok") {
+    return Object.freeze({
+      ...parsed,
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return parsed;
+}
+async function fetchBillingUsage(accessToken, options = {}) {
+  if (typeof accessToken !== "string" || accessToken.length === 0) {
+    return unavailable("Not signed in");
+  }
+  const timeoutMs = options.timeoutMs ?? USAGE_TIMEOUT_MS;
+  let timer;
+  try {
+    const result = await Promise.race([
+      fetchBillingUsageOnce(accessToken, options),
+      new Promise((resolve) => {
+        timer = setTimeout(
+          () => resolve(unavailable("Billing request timed out")),
+          timeoutMs
+        );
+      })
+    ]);
+    return result;
   } catch (error) {
-    for (const dispose of disposers.reverse()) dispose?.();
-    throw error;
+    const message = error instanceof Error ? error.message : "network error";
+    if (/abort|timeout/i.test(message)) return unavailable("Billing request timed out");
+    return unavailable("Billing network error");
+  } finally {
+    if (timer) clearTimeout(timer);
   }
-  return () => {
-    for (const dispose of disposers.reverse()) dispose?.();
-  };
 }
 
 // src/adapter.js
-async function optionalImport(specifier) {
+function withImportTimeout(promise, ms, message) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), ms);
+    })
+  ]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+async function optionalImport(specifier, options = {}) {
+  const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : IMPORT_TIMEOUT_MS;
+  const importFn = typeof options.importFn === "function" ? options.importFn : (id) => import(id);
   try {
-    return await import(specifier);
+    return await withImportTimeout(
+      Promise.resolve(importFn(specifier)),
+      timeoutMs,
+      `Import timed out after ${timeoutMs}ms: ${specifier}`
+    );
   } catch {
     return void 0;
   }
@@ -987,37 +1032,48 @@ function withEncryptedReasoningInclude(api) {
     streamSimple: (model, context, options) => api.streamSimple(model, context, inject2(options))
   };
 }
-async function createGrokBuildAdapter(session) {
-  const [piAi, dshPi, dshLlm] = await Promise.all([
-    optionalImport("@earendil-works/pi-ai"),
-    optionalImport("@deepseek-ai/dsh-llm-pi-ai"),
-    optionalImport("@deepseek-ai/dsh-llm")
-  ]);
-  const duck = createDuckAdapter(session);
-  const asHostAdapter = (candidate) => {
-    if (!dshLlm?.LlmAdapter || candidate instanceof dshLlm.LlmAdapter) return candidate;
-    class GrokBuildAdapter extends dshLlm.LlmAdapter {
-      providerInfo(provider) {
-        return candidate.providerInfo(provider);
-      }
-      providerRetryPolicy(provider) {
-        return candidate.providerRetryPolicy(provider);
-      }
-      listModels(provider) {
-        return candidate.listModels(provider);
-      }
-      resolveModel(provider, model, signal) {
-        return candidate.resolveModel(provider, model, signal);
-      }
-      prepareCall(provider, model, signal) {
-        return candidate.prepareCall(provider, model, signal);
-      }
-      stream(options) {
-        return candidate.stream(options);
-      }
+function wrapAsHostAdapter(candidate, dshLlm) {
+  if (!dshLlm?.LlmAdapter || candidate instanceof dshLlm.LlmAdapter) return candidate;
+  class GrokBuildAdapter extends dshLlm.LlmAdapter {
+    providerInfo(provider) {
+      return candidate.providerInfo(provider);
+    }
+    providerRetryPolicy(provider) {
+      return candidate.providerRetryPolicy(provider);
+    }
+    listModels(provider) {
+      return candidate.listModels(provider);
+    }
+    resolveModel(provider, model, signal) {
+      return candidate.resolveModel(provider, model, signal);
+    }
+    prepareCall(provider, model, signal) {
+      return candidate.prepareCall(provider, model, signal);
     }
-    return new GrokBuildAdapter();
+    stream(options) {
+      return candidate.stream(options);
+    }
+  }
+  return new GrokBuildAdapter();
+}
+function createGrokBuildAdapterSync(session, options = {}) {
+  const duck = createDuckAdapter(session);
+  const dshLlm = options.dshLlm;
+  return {
+    adapter: wrapAsHostAdapter(duck, dshLlm),
+    kind: "custom-mvp",
+    note: "Registered a sync duck Responses adapter; pi-ai upgrade may follow in the background."
   };
+}
+async function createGrokBuildAdapter(session, options = {}) {
+  const importOpts = options.importOptions ?? {};
+  const [piAi, dshPi, dshLlm] = await Promise.all([
+    optionalImport("@earendil-works/pi-ai", importOpts),
+    optionalImport("@deepseek-ai/dsh-llm-pi-ai", importOpts),
+    optionalImport("@deepseek-ai/dsh-llm", importOpts)
+  ]);
+  const duck = createDuckAdapter(session);
+  const asHostAdapter = (candidate) => wrapAsHostAdapter(candidate, dshLlm);
   if (!piAi?.createProvider || !dshPi?.PiAiAdapter) {
     return {
       adapter: asHostAdapter(duck),
@@ -1027,8 +1083,8 @@ async function createGrokBuildAdapter(session) {
   }
   let responsesApi;
   try {
-    const lazy = await import("@earendil-works/pi-ai/api/openai-responses.lazy");
-    responsesApi = typeof lazy.openAIResponsesApi === "function" ? lazy.openAIResponsesApi() : void 0;
+    const lazy = await optionalImport("@earendil-works/pi-ai/api/openai-responses.lazy", importOpts);
+    responsesApi = typeof lazy?.openAIResponsesApi === "function" ? lazy.openAIResponsesApi() : void 0;
   } catch {
     responsesApi = void 0;
   }
@@ -1120,10 +1176,513 @@ async function createGrokBuildAdapter(session) {
   };
 }
 
+// src/session.js
+function resolveGrokBin(env = process.env, exists = existsSync2) {
+  if (typeof env.DSH_GROK_BIN === "string" && env.DSH_GROK_BIN.trim()) return env.DSH_GROK_BIN.trim();
+  const local = join2(grokHome(env), "bin", "grok");
+  if (exists(local)) return local;
+  return "grok";
+}
+function grokCliAvailable(env = process.env, exists = existsSync2) {
+  const bin = resolveGrokBin(env, exists);
+  if (bin.includes("/") || bin.includes("\\")) return exists(bin);
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  return String(env.PATH ?? "").split(delimiter).some((dir) => dir && exists(join2(dir, bin)));
+}
+function spawnGrokLogin(options = {}) {
+  const spawnFn = options.spawn ?? spawn;
+  const bin = resolveGrokBin(options.env, options.exists);
+  const args = options.device ? ["login", "--device-auth"] : ["login"];
+  return new Promise((resolve, reject) => {
+    const child = spawnFn(bin, args, {
+      stdio: options.stdio ?? "inherit",
+      env: options.env ?? process.env
+    });
+    child.on("error", (error) => {
+      reject(new Error(`Could not start grok CLI (${bin})`, { cause: error }));
+    });
+    child.on("exit", (code, signal) => {
+      if (code === 0) resolve({ ok: true, code });
+      else reject(new Error(signal ? `grok login terminated by ${signal}` : `grok login exited with code ${code ?? "unknown"}`));
+    });
+  });
+}
+async function defaultCredentialRefOf() {
+  try {
+    const mod = await optionalImport("@deepseek-ai/dsh-credentials");
+    if (typeof mod?.credentialRef === "function") return mod.credentialRef(CREDENTIAL_REF_NAME);
+  } catch {
+  }
+  return CREDENTIAL_REF_NAME;
+}
+function scheduleDeferred(run) {
+  if (typeof setImmediate === "function") setImmediate(run);
+  else queueMicrotask(run);
+}
+function withTimeout(promise, ms, message, options = {}) {
+  let timer;
+  const shouldUnref = options.unref !== false;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), ms);
+      if (shouldUnref && typeof timer?.unref === "function") timer.unref();
+    })
+  ]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+function createSessionService({
+  credentials,
+  logger,
+  onCatalogChange,
+  fetchBillingUsage: fetchBilling = fetchBillingUsage,
+  loadCatalog: loadCatalogFn = loadCatalog,
+  readAuth = readGrokAuthSession,
+  storeTokenTimeoutMs = STORE_TOKEN_TIMEOUT_MS,
+  credentialsIoTimeoutMs = CREDENTIALS_IO_TIMEOUT_MS,
+  credentialRefOf = defaultCredentialRefOf
+} = {}) {
+  let catalog = { models: [], source: "signed-out", error: void 0 };
+  let lastPublic = publicSessionView(void 0);
+  let lastUsage = unavailable("Not fetched yet");
+  let memoryAccessToken;
+  let memorySessionTouched = false;
+  const resolveTimeoutMs = () => {
+    return typeof storeTokenTimeoutMs === "number" && storeTokenTimeoutMs > 0 ? storeTokenTimeoutMs : STORE_TOKEN_TIMEOUT_MS;
+  };
+  const resolveIoTimeoutMs = () => {
+    return typeof credentialsIoTimeoutMs === "number" && credentialsIoTimeoutMs > 0 ? credentialsIoTimeoutMs : CREDENTIALS_IO_TIMEOUT_MS;
+  };
+  const notifyCatalogChange = () => {
+    scheduleDeferred(() => {
+      try {
+        onCatalogChange?.();
+      } catch (error) {
+        logger?.warn?.(
+          "Grok subscription catalog change notify failed: %s",
+          error instanceof Error ? error.message : "unknown"
+        );
+      }
+    });
+  };
+  const readStoredToken = async () => {
+    if (typeof memoryAccessToken === "string" && memoryAccessToken.length > 0) {
+      return memoryAccessToken;
+    }
+    if (memorySessionTouched) return void 0;
+    if (!credentials?.resolve) return void 0;
+    const timeoutMs = resolveIoTimeoutMs();
+    try {
+      const hit = await withTimeout(
+        (async () => {
+          const ref = await credentialRefOf();
+          return credentials.resolve(ref);
+        })(),
+        timeoutMs,
+        `Resolving Grok credential timed out after ${timeoutMs}ms`
+      );
+      const value = hit?.value;
+      return typeof value === "string" && value.length > 0 ? value : void 0;
+    } catch (error) {
+      logger?.warn?.(
+        "Grok subscription credential resolve failed: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+      return void 0;
+    }
+  };
+  const persistToken = async (token) => {
+    if (!credentials?.set) throw new Error("DSH credentials service is unavailable");
+    const timeoutMs = resolveTimeoutMs();
+    await withTimeout(
+      (async () => {
+        const ref = await credentialRefOf();
+        await credentials.set(ref, token);
+      })(),
+      timeoutMs,
+      `Storing Grok credential timed out after ${timeoutMs}ms`
+    );
+  };
+  const clearToken = async () => {
+    if (!credentials?.unset) return;
+    const timeoutMs = resolveTimeoutMs();
+    await withTimeout(
+      (async () => {
+        const ref = await credentialRefOf();
+        await credentials.unset(ref);
+      })(),
+      timeoutMs,
+      `Clearing Grok credential timed out after ${timeoutMs}ms`
+    );
+  };
+  const refreshUsage = async () => {
+    const token = await readStoredToken();
+    if (!token) {
+      lastUsage = unavailable("Not signed in");
+      return lastUsage;
+    }
+    try {
+      lastUsage = await fetchBilling(token);
+    } catch (error) {
+      logger?.warn?.(
+        "Grok subscription usage fetch failed: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+      lastUsage = unavailable("Usage fetch failed");
+    }
+    return lastUsage;
+  };
+  const refreshCatalog = async () => {
+    const token = await readStoredToken();
+    if (!token) {
+      catalog = { models: [], source: "signed-out", error: void 0 };
+      notifyCatalogChange();
+      return catalog;
+    }
+    catalog = await loadCatalogFn(token);
+    notifyCatalogChange();
+    return catalog;
+  };
+  const kickBackgroundUsageRefresh = () => {
+    void refreshUsage().catch((error) => {
+      logger?.warn?.(
+        "Grok subscription background usage refresh failed: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+    });
+  };
+  const kickBackgroundCatalogRefresh = () => {
+    void refreshCatalog().catch((error) => {
+      logger?.warn?.(
+        "Grok subscription background catalog refresh failed: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+    });
+  };
+  const pull = async () => {
+    const parsed = readAuth();
+    if (!parsed.session) {
+      memoryAccessToken = void 0;
+      memorySessionTouched = true;
+      catalog = { models: [], source: "signed-out", error: void 0 };
+      lastPublic = publicSessionView(void 0);
+      lastUsage = unavailable("Not signed in");
+      scheduleDeferred(() => {
+        void clearToken().catch((error) => {
+          logger?.warn?.(
+            "Grok subscription deferred credential clear failed: %s",
+            error instanceof Error ? error.message : "unknown"
+          );
+        });
+      });
+      const message = parsed.reason === "api-key-only" ? "Found an API-key entry only. Sign in with SuperGrok / X Premium via grok login." : "No Grok Build subscription session in auth.json. Run grok login first.";
+      notifyCatalogChange();
+      return { ok: false, error: message, account: lastPublic, catalog, usage: lastUsage };
+    }
+    const accessToken = parsed.session.accessToken;
+    memoryAccessToken = accessToken;
+    memorySessionTouched = true;
+    lastPublic = publicSessionView(parsed.session);
+    scheduleDeferred(() => {
+      void persistToken(accessToken).catch((error) => {
+        logger?.warn?.(
+          "Grok subscription deferred credential persist failed: %s",
+          error instanceof Error ? error.message : "unknown"
+        );
+      });
+    });
+    notifyCatalogChange();
+    kickBackgroundCatalogRefresh();
+    kickBackgroundUsageRefresh();
+    return { ok: true, account: lastPublic, catalog, usage: lastUsage };
+  };
+  const status = async () => {
+    if (typeof memoryAccessToken === "string" && memoryAccessToken.length > 0 || lastPublic.signedIn === true) {
+      return { account: lastPublic, catalog, usage: lastUsage, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
+    }
+    try {
+      const parsed = readAuth();
+      if (parsed.session) {
+        memoryAccessToken = parsed.session.accessToken;
+        memorySessionTouched = true;
+        lastPublic = publicSessionView(parsed.session);
+        return { account: lastPublic, catalog, usage: lastUsage, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
+      }
+    } catch (error) {
+      logger?.warn?.(
+        "Grok subscription auth.json read failed during status: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+    }
+    let token;
+    try {
+      token = await readStoredToken();
+    } catch (error) {
+      logger?.warn?.("could not resolve Grok subscription credential: %s", error instanceof Error ? error.message : "unknown");
+      token = void 0;
+    }
+    if (!token) {
+      lastPublic = publicSessionView(void 0);
+      catalog = { models: [], source: "signed-out", error: void 0 };
+      lastUsage = unavailable("Not signed in");
+      return { account: lastPublic, catalog, usage: lastUsage, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
+    }
+    memoryAccessToken = token;
+    lastPublic = Object.freeze({ signedIn: true, maskedAccount: "\u2022\u2022\u2022\u2022", authMode: "oidc", source: "dsh-credentials" });
+    return { account: lastPublic, catalog, usage: lastUsage, cliAvailable: grokCliAvailable(), authPath: authJsonPath() };
+  };
+  const login = async (options) => {
+    await spawnGrokLogin(options);
+    return pull();
+  };
+  const logout = async () => {
+    memoryAccessToken = void 0;
+    memorySessionTouched = true;
+    await clearToken().catch((error) => {
+      logger?.warn?.(
+        "Grok subscription credential clear failed: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+    });
+    catalog = { models: [], source: "signed-out", error: void 0 };
+    lastPublic = publicSessionView(void 0);
+    lastUsage = unavailable("Not signed in");
+    notifyCatalogChange();
+    return { ok: true, account: lastPublic, catalog, usage: lastUsage };
+  };
+  return {
+    pull,
+    status,
+    refreshCatalog,
+    refreshUsage,
+    login,
+    logout,
+    currentToken: readStoredToken,
+    models: () => catalog.models,
+    catalog: () => catalog,
+    usage: () => lastUsage,
+    publicAccount: () => lastPublic
+  };
+}
+
+// src/rpc-contract.js
+var RPC_ENDPOINTS = Object.freeze([
+  "status",
+  "login/cli",
+  "login/device",
+  "pull",
+  "logout",
+  "catalog/refresh",
+  "usage",
+  "usage/refresh"
+]);
+function publicResult(value) {
+  return { ok: true, value };
+}
+function publicError(error, fallback = "Grok subscription request failed") {
+  const message = error instanceof Error ? error.message : fallback;
+  return { ok: false, error: { code: "internal", message, details: { issues: [] } } };
+}
+
+// src/rpc.js
+function stripSecrets(value) {
+  if (!value || typeof value !== "object") return value;
+  const next = { ...value };
+  delete next.accessToken;
+  delete next.token;
+  delete next.refresh;
+  delete next.refresh_token;
+  delete next.key;
+  if (next.catalog) {
+    next.catalog = {
+      source: next.catalog.source,
+      error: next.catalog.error,
+      models: Array.isArray(next.catalog.models) ? next.catalog.models.map((model) => ({
+        id: model.id,
+        name: model.name,
+        contextWindow: model.contextWindow,
+        reasoning: model.reasoning,
+        source: model.source
+      })) : []
+    };
+  }
+  if (next.account) {
+    next.account = {
+      signedIn: next.account.signedIn === true,
+      maskedAccount: next.account.maskedAccount,
+      authMode: next.account.authMode,
+      expiresAt: next.account.expiresAt,
+      source: next.account.source
+    };
+  }
+  if (next.usage) {
+    next.usage = sanitizeUsage(next.usage);
+  }
+  return next;
+}
+function sanitizeUsage(usage) {
+  if (!usage || typeof usage !== "object") {
+    return { status: "unavailable", reason: "Usage unavailable", experimental: true, source: "billing-credits-undocumented" };
+  }
+  const out = {
+    status: usage.status === "ok" ? "ok" : "unavailable",
+    experimental: true,
+    source: typeof usage.source === "string" ? usage.source : "billing-credits-undocumented"
+  };
+  if (out.status !== "ok") {
+    out.reason = typeof usage.reason === "string" ? usage.reason : "Usage unavailable";
+    return out;
+  }
+  if (typeof usage.usedPercent === "number" && Number.isFinite(usage.usedPercent)) out.usedPercent = usage.usedPercent;
+  if (typeof usage.remainingPercent === "number" && Number.isFinite(usage.remainingPercent)) out.remainingPercent = usage.remainingPercent;
+  if (typeof usage.periodStart === "string") out.periodStart = usage.periodStart;
+  if (typeof usage.periodStartLocal === "string") out.periodStartLocal = usage.periodStartLocal;
+  if (typeof usage.periodEnd === "string") out.periodEnd = usage.periodEnd;
+  if (typeof usage.periodEndLocal === "string") out.periodEndLocal = usage.periodEndLocal;
+  if (typeof usage.fetchedAt === "string") out.fetchedAt = usage.fetchedAt;
+  if (Array.isArray(usage.productUsage)) {
+    out.productUsage = usage.productUsage.filter((row) => row && typeof row === "object").map((row) => ({
+      ...typeof row.name === "string" ? { name: row.name } : {},
+      ...typeof row.usedPercent === "number" && Number.isFinite(row.usedPercent) ? { usedPercent: row.usedPercent } : {}
+    }));
+  }
+  return out;
+}
+async function dispatch(session, endpoint) {
+  if (endpoint === "status") return publicResult(stripSecrets(await session.status()));
+  if (endpoint === "pull") return publicResult(stripSecrets(await session.pull()));
+  if (endpoint === "logout") return publicResult(stripSecrets(await session.logout()));
+  if (endpoint === "catalog/refresh") {
+    const catalog = await session.refreshCatalog();
+    return publicResult(stripSecrets({ catalog, account: session.publicAccount(), usage: session.usage?.() }));
+  }
+  if (endpoint === "usage") {
+    return publicResult(stripSecrets({ usage: session.usage?.() ?? { status: "unavailable", reason: "Usage unavailable", experimental: true } }));
+  }
+  if (endpoint === "usage/refresh") {
+    const usage = await session.refreshUsage();
+    return publicResult(stripSecrets({ usage, account: session.publicAccount() }));
+  }
+  if (endpoint === "login/cli") return publicResult(stripSecrets(await session.login({ device: false })));
+  if (endpoint === "login/device") return publicResult(stripSecrets(await session.login({ device: true })));
+  return publicError(new Error(`Unknown Grok subscription RPC: ${endpoint}`));
+}
+function createRpcHandler(session, options = {}) {
+  const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : RPC_HANDLER_TIMEOUT_MS;
+  return async function handle(endpoint, _payload, _signal) {
+    try {
+      return await withTimeout(
+        dispatch(session, endpoint),
+        timeoutMs,
+        `Grok subscription RPC "${endpoint}" timed out after ${timeoutMs}ms`,
+        { unref: false }
+      );
+    } catch (error) {
+      return publicError(error);
+    }
+  };
+}
+
+// src/transport.js
+function parseEnvelope(body, method) {
+  if (!body || typeof body !== "object") return void 0;
+  if (body.method !== method) return void 0;
+  return {
+    rpcId: body.rpcId,
+    payload: body.payload
+  };
+}
+var cachedClientRequestSchema;
+var schemaLoadStarted = false;
+function kickSchemaLoad() {
+  if (schemaLoadStarted) return;
+  schemaLoadStarted = true;
+  void optionalImport("@deepseek-ai/dsh-client-connection").then((mod) => {
+    if (mod?.clientRequestSchema && typeof mod.clientRequestSchema.safeParse === "function") {
+      cachedClientRequestSchema = mod.clientRequestSchema;
+    }
+  }).catch(() => {
+  });
+}
+function resolveEnvelope(body, method) {
+  const schema = cachedClientRequestSchema;
+  if (schema) {
+    const envelope = schema.safeParse(body);
+    if (!envelope.success || envelope.data.method !== method) return void 0;
+    return { rpcId: envelope.data.rpcId, payload: envelope.data.payload };
+  }
+  return parseEnvelope(body, method);
+}
+function registerSubscriptionTransport(connection, handler) {
+  kickSchemaLoad();
+  const disposers = [];
+  try {
+    for (const endpoint of RPC_ENDPOINTS) {
+      const method = `grok-subscription/${endpoint}`;
+      if (typeof connection?.fetch?.register !== "function") {
+        throw new Error("DSH connection.fetch.register is unavailable");
+      }
+      disposers.push(connection.fetch.register({
+        path: `/api/${method}`,
+        methods: ["POST"],
+        requestBody: "buffered",
+        async fetch(request) {
+          if (request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+            return new Response("content type must be application/json", { status: 415 });
+          }
+          let body;
+          try {
+            body = await request.json();
+          } catch {
+            return new Response("invalid JSON", { status: 400 });
+          }
+          if (!cachedClientRequestSchema) {
+            try {
+              const mod = await optionalImport("@deepseek-ai/dsh-client-connection");
+              if (mod?.clientRequestSchema && typeof mod.clientRequestSchema.safeParse === "function") {
+                cachedClientRequestSchema = mod.clientRequestSchema;
+              }
+            } catch {
+            }
+          }
+          const envelope = resolveEnvelope(body, method);
+          if (!envelope) return new Response("invalid RPC envelope", { status: 400 });
+          let result;
+          try {
+            request.signal?.throwIfAborted?.();
+            result = await handler(endpoint, envelope.payload, request.signal);
+          } catch {
+            result = { ok: false, error: { code: "internal", message: "Grok subscription request failed", details: { issues: [] } } };
+          }
+          return Response.json({ type: "server-response", rpcId: envelope.rpcId, result });
+        }
+      }));
+    }
+  } catch (error) {
+    for (const dispose of disposers.reverse()) dispose?.();
+    throw error;
+  }
+  return () => {
+    for (const dispose of disposers.reverse()) dispose?.();
+  };
+}
+
 // src/index.js
 var name = CORDIS_ID;
-var inject = ["llm", "credentials", "settings", "web"];
-function apply(ctx) {
+var inject = ["llm", "web"];
+function scheduleDeferred2(run) {
+  if (typeof setImmediate === "function") setImmediate(run);
+  else queueMicrotask(run);
+}
+function softService(ctx, key) {
+  try {
+    if (typeof ctx.get === "function") return ctx.get(key) ?? void 0;
+  } catch {
+  }
+  return void 0;
+}
+function apply(ctx, options = {}) {
   let active = true;
   if (typeof ctx.effect === "function") {
     ctx.effect(
@@ -1134,60 +1693,103 @@ function apply(ctx) {
     );
   }
   const notifyCatalogChange = () => {
-    if (!active) return;
-    try {
-      ctx.emit("llm/adapters-updated");
-    } catch (error) {
-      ctx.logger?.warn?.("an llm/adapters-updated listener failed");
-      ctx.logger?.warn?.(error);
-    }
+    scheduleDeferred2(() => {
+      if (!active) return;
+      try {
+        ctx.emit("llm/adapters-updated");
+      } catch (error) {
+        ctx.logger?.warn?.("an llm/adapters-updated listener failed");
+        ctx.logger?.warn?.(error);
+      }
+    });
   };
+  const credentials = softService(ctx, "credentials");
   const session = createSessionService({
-    credentials: ctx.credentials,
+    credentials,
     logger: ctx.logger,
     onCatalogChange: notifyCatalogChange
   });
   const handler = createRpcHandler(session);
-  void boot(ctx, session, notifyCatalogChange);
+  const createSync = options.createSync ?? createGrokBuildAdapterSync;
+  try {
+    const created = createSync(session);
+    if (created.note) ctx.logger?.debug?.(created.note);
+    ctx.llm.registerAdapter([PROVIDER_ID], created.adapter);
+    notifyCatalogChange();
+  } catch (error) {
+    ctx.logger?.warn?.(
+      "Grok subscription duck adapter failed to register: %s",
+      error instanceof Error ? error.message : "unknown"
+    );
+  }
+  const defer = options.defer ?? scheduleDeferred2;
+  defer(() => {
+    void deferredBoot(ctx, session, notifyCatalogChange, options);
+  });
   ctx.inject(["connection"], (connectionContext) => connectionContext.effect(
     () => registerSubscriptionTransport(connectionContext.connection, handler),
     "grok-subscription: host-only account RPC"
   ));
 }
-async function boot(ctx, session, notifyCatalogChange) {
-  await tryRegisterSettings(ctx);
+async function deferredBoot(ctx, session, notifyCatalogChange, options = {}) {
+  if (!options.skipSettings) {
+    await tryRegisterSettings(ctx);
+  }
   try {
-    await session.pull();
+    ctx.llm.registerConfigurableProviders?.([{
+      provider: PROVIDER_ID,
+      displayName: DISPLAY_NAME,
+      settingsNs: SETTINGS_NAMESPACE,
+      settingsPath: []
+    }]);
   } catch (error) {
-    ctx.logger?.debug?.("Grok subscription startup pull skipped: %s", error instanceof Error ? error.message : "unknown");
+    ctx.logger?.debug?.(
+      "Grok subscription provider directory skipped: %s",
+      error instanceof Error ? error.message : "unknown"
+    );
   }
+  if (!options.skipPull) {
+    void session.pull().catch((error) => {
+      ctx.logger?.debug?.(
+        "Grok subscription startup pull skipped: %s",
+        error instanceof Error ? error.message : "unknown"
+      );
+    });
+  }
+  if (options.skipUpgrade) return;
+  const createAsync = options.createAsync ?? createGrokBuildAdapter;
   try {
-    const created = await createGrokBuildAdapter(session);
-    if (created.note) ctx.logger?.warn?.(created.note);
-    ctx.llm.registerAdapter([PROVIDER_ID], created.adapter);
-    try {
-      ctx.llm.registerConfigurableProviders?.([{
-        provider: PROVIDER_ID,
-        displayName: DISPLAY_NAME,
-        settingsNs: SETTINGS_NAMESPACE,
-        settingsPath: []
-      }]);
-    } catch (error) {
-      ctx.logger?.debug?.("Grok subscription provider directory skipped: %s", error instanceof Error ? error.message : "unknown");
+    const created = await createAsync(session);
+    if (created.kind === "pi-ai") {
+      if (created.note) ctx.logger?.warn?.(created.note);
+      ctx.llm.registerAdapter([PROVIDER_ID], created.adapter);
+      notifyCatalogChange?.();
+    } else if (created.note) {
+      ctx.logger?.debug?.(created.note);
     }
-    notifyCatalogChange?.();
   } catch (error) {
-    ctx.logger?.warn?.("Grok subscription adapter failed to start: %s", error instanceof Error ? error.message : "unknown");
+    ctx.logger?.warn?.(
+      "Grok subscription adapter upgrade failed: %s",
+      error instanceof Error ? error.message : "unknown"
+    );
   }
 }
 async function tryRegisterSettings(ctx) {
-  if (typeof ctx.settings?.register !== "function") return;
+  const settings = softService(ctx, "settings");
+  if (typeof settings?.register !== "function") return;
   try {
-    const mod = await import("@deepseek-ai/schemastery");
+    const mod = await optionalImport("@deepseek-ai/schemastery");
+    if (!mod) {
+      ctx.logger?.debug?.("Grok subscription settings namespace skipped: schemastery unavailable or timed out");
+      return;
+    }
     const z = mod.default ?? mod;
-    ctx.settings.register(SETTINGS_NAMESPACE, z.object({}));
+    settings.register(SETTINGS_NAMESPACE, z.object({}));
   } catch (error) {
-    ctx.logger?.debug?.("Grok subscription settings namespace skipped: %s", error instanceof Error ? error.message : "unknown");
+    ctx.logger?.debug?.(
+      "Grok subscription settings namespace skipped: %s",
+      error instanceof Error ? error.message : "unknown"
+    );
   }
 }
 export {
@@ -1195,6 +1797,9 @@ export {
   DISPLAY_NAME_ZH,
   PROVIDER_ID,
   apply,
+  deferredBoot,
   inject,
-  name
+  name,
+  scheduleDeferred2 as scheduleDeferred,
+  softService
 };