dsh-grok-provider 0.1.0

package/dist/internal/auth-registry.mjs

@@ -0,0 +1,64 @@
+export class AuthModeUnavailableError extends Error {
+  constructor() {
+    super("The official Grok authentication source is unavailable")
+    this.name = "AuthModeUnavailableError"
+  }
+}
+
+export function createAuthRegistry({ createTransport }) {
+  if (typeof createTransport !== "function") {
+    throw new TypeError("A Grok transport factory is required")
+  }
+
+  let entry
+  let generation = 0
+
+  return Object.freeze({
+    install(source) {
+      if (!source || typeof source !== "object") throw new TypeError("Invalid Grok credential source")
+      const token = Object.freeze({})
+      const transport = createTransport(source)
+      if (!transport || typeof transport !== "object") throw new TypeError("Invalid Grok transport")
+      entry = { source, transport, token }
+      generation += 1
+      let disposed = false
+      return () => {
+        if (disposed) return
+        disposed = true
+        if (entry?.token === token) {
+          entry = undefined
+          generation += 1
+        }
+      }
+    },
+
+    invalidate() {
+      generation += 1
+    },
+
+    getGeneration() {
+      if (entry === undefined) throw new AuthModeUnavailableError()
+      return Object.freeze({ id: generation, transport: entry.transport })
+    },
+
+    async status() {
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const snapshot = entry
+        const snapshotGeneration = generation
+        let available = false
+        if (snapshot !== undefined && typeof snapshot.source.withAccessToken === "function") {
+          try {
+            await snapshot.source.withAccessToken(() => undefined)
+            available = true
+          } catch {
+            available = false
+          }
+        }
+        if (entry === snapshot && generation === snapshotGeneration) {
+          return Object.freeze({ generation: snapshotGeneration, available })
+        }
+      }
+      return Object.freeze({ generation, available: false })
+    },
+  })
+}

package/dist/internal/auth-rpc.mjs

@@ -0,0 +1,118 @@
+import { AuthDriverUnavailableError, AuthLoginBusyError } from "./auth-controller.mjs"
+
+export function createAuthRpcHandler({ controller, dashboard }) {
+  if (
+    !controller ||
+    typeof controller.status !== "function" ||
+    typeof controller.beginLogin !== "function" ||
+    typeof controller.cancel !== "function" ||
+    typeof controller.logout !== "function" ||
+    typeof dashboard !== "function"
+  ) throw new TypeError("Invalid Grok auth RPC controller")
+
+  return async function handleAuthRpc(endpoint, payload, signal) {
+    if (signal?.aborted) return cancelled()
+    try {
+      if (endpoint === "status") {
+        if (!hasExactKeys(payload, [])) return badRequest()
+        const status = serializable(await controller.status())
+        return ok({ kind: "status", status })
+      }
+      if (endpoint === "dashboard") {
+        if (!hasExactKeys(payload, [])) return badRequest()
+        return ok({ kind: "dashboard", dashboard: serializable(await dashboard({ signal })) })
+      }
+      if (endpoint === "login") {
+        if (!hasExactKeys(payload, [])) return badRequest()
+        const session = await controller.beginLogin()
+        const status = serializable(session.public)
+        return ok({ kind: "login-started", status, sessionId: status.sessionId })
+      }
+      if (endpoint === "cancel") {
+        const cancellation = parseCancelPayload(payload)
+        if (cancellation === undefined) return badRequest()
+        return ok({
+          kind: controller.cancel(cancellation.sessionId) ? "cancelled" : "not-running",
+          status: serializable(await controller.status()),
+        })
+      }
+      if (endpoint === "logout") {
+        if (!hasExactKeys(payload, [])) return badRequest()
+        const outcome = await controller.logout({ signal })
+        if (outcome.kind === "confirmation-required") {
+          return ok({
+            kind: "logout-confirmation-required",
+            confirmationId: outcome.confirmationId,
+            expiresAt: outcome.expiresAt,
+          })
+        }
+        return ok({ kind: `logout-${outcome.kind}`, status: serializable(await controller.status()) })
+      }
+      return badRequest()
+    } catch (error) {
+      if (error instanceof AuthLoginBusyError) {
+        return ok({ kind: "busy", status: serializable(await controller.status()) })
+      }
+      if (error instanceof AuthDriverUnavailableError) {
+        return ok({ kind: "unavailable", status: serializable(await controller.status()) })
+      }
+      return signal?.aborted ? cancelled() : internal()
+    }
+  }
+}
+
+function parseCancelPayload(payload) {
+  if (
+    !hasExactKeys(payload, ["sessionId"]) ||
+    typeof payload.sessionId !== "string" ||
+    payload.sessionId.length === 0 ||
+    payload.sessionId.length > 128
+  ) return undefined
+  return payload
+}
+
+function hasExactKeys(value, expected) {
+  if (!isPlainObject(value)) return false
+  const keys = Object.keys(value).sort()
+  const sorted = [...expected].sort()
+  return keys.length === sorted.length && keys.every((key, index) => key === sorted[index])
+}
+
+function serializable(value) {
+  const text = JSON.stringify(value)
+  if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > 64 * 1024) {
+    throw new TypeError("Invalid Grok auth RPC response")
+  }
+  return JSON.parse(text)
+}
+
+function ok(value) {
+  return { ok: true, value }
+}
+
+function badRequest() {
+  return {
+    ok: false,
+    error: { code: "bad-request", message: "Invalid Grok auth RPC request", details: { issues: [] } },
+  }
+}
+
+function cancelled() {
+  return {
+    ok: false,
+    error: { code: "cancelled", message: "The Grok auth operation was cancelled", details: {} },
+  }
+}
+
+function internal() {
+  return {
+    ok: false,
+    error: { code: "internal", message: "The Grok auth operation failed", details: {} },
+  }
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}

package/dist/internal/billing-summary.mjs

@@ -0,0 +1,105 @@
+const MAX_BILLING_BYTES = 256 * 1024
+
+export class InvalidBillingResponseError extends Error {
+  constructor() {
+    super("The Grok billing response is invalid or unsupported")
+    this.name = "InvalidBillingResponseError"
+  }
+}
+
+export function parseBillingSummary(raw) {
+  if (typeof raw !== "string" || Buffer.byteLength(raw, "utf8") > MAX_BILLING_BYTES) fail()
+  let value
+  try { value = JSON.parse(raw) } catch { fail() }
+  if (!isPlainObject(value) || (value.config !== null && !isPlainObject(value.config))) fail()
+  if (value.config === null) return Object.freeze({ state: "unavailable" })
+
+  const config = value.config
+  const period = parsePeriod(config)
+  const usedPercent = parseUsage(config, period)
+  return Object.freeze({
+    state: "ready",
+    ...(usedPercent === undefined ? {} : {
+      usedPercent,
+      remainingPercent: normalizePercent(100 - usedPercent),
+    }),
+    ...period,
+  })
+}
+
+function parseUsage(config, period) {
+  if (config.creditUsagePercent !== undefined) {
+    if (!isPercent(config.creditUsagePercent)) fail()
+    return config.creditUsagePercent
+  }
+  // GetGrokCreditsConfig is protobuf-backed. Its JSON projection omits the
+  // scalar zero value, while retaining the typed period that owns it.
+  if (
+    period.periodKind !== undefined
+    && period.periodStart !== undefined
+    && period.resetsAt !== undefined
+  ) return 0
+  if (config.monthlyLimit === undefined && config.used === undefined) return undefined
+  const limit = parseCent(config.monthlyLimit)
+  const used = parseCent(config.used)
+  if (limit <= 0 || used < 0 || used > limit) fail()
+  return normalizePercent((used / limit) * 100)
+}
+
+function parsePeriod(config) {
+  if (config.currentPeriod !== undefined) {
+    if (!isPlainObject(config.currentPeriod)) fail()
+    const current = config.currentPeriod
+    const periodKind = current.type === "USAGE_PERIOD_TYPE_WEEKLY" ? "weekly"
+      : current.type === "USAGE_PERIOD_TYPE_MONTHLY" ? "monthly" : undefined
+    if (current.type !== undefined && (
+      typeof current.type !== "string" || current.type.length === 0 || current.type.length > 128
+    )) fail()
+    const periodStart = parseOptionalDateTime(current.start)
+    const resetsAt = parseOptionalDateTime(current.end)
+    return {
+      ...(periodKind === undefined ? {} : { periodKind }),
+      ...(periodStart === undefined ? {} : { periodStart }),
+      ...(resetsAt === undefined ? {} : { resetsAt }),
+    }
+  }
+  const periodStart = parseOptionalDateTime(config.billingPeriodStart)
+  const resetsAt = parseOptionalDateTime(config.billingPeriodEnd)
+  if (periodStart === undefined && resetsAt === undefined) return {}
+  return {
+    periodKind: "monthly",
+    ...(periodStart === undefined ? {} : { periodStart }),
+    ...(resetsAt === undefined ? {} : { resetsAt }),
+  }
+}
+
+function parseCent(value) {
+  if (!isPlainObject(value) || !Number.isSafeInteger(value.val)) fail()
+  return value.val
+}
+
+function parseOptionalDateTime(value) {
+  if (value === undefined) return undefined
+  if (typeof value !== "string") fail()
+  const time = Date.parse(value)
+  if (!Number.isFinite(time)) fail()
+  return new Date(time).toISOString()
+}
+
+function normalizePercent(value) {
+  return Math.round(value * 100) / 100
+}
+
+function isPercent(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100
+}
+
+function fail() {
+  throw new InvalidBillingResponseError()
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}

package/dist/internal/credential-source.mjs

@@ -0,0 +1,168 @@
+const CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828"
+const EXPIRY_SKEW_MS = 5 * 60 * 1000
+
+export const GROK_CLI_1_0_5_AUTH_CONTRACT = Object.freeze({
+  authMode: "oidc",
+  clientId: CLIENT_ID,
+  issuer: "https://auth.x.ai",
+  scope: `https://auth.x.ai::${CLIENT_ID}`,
+})
+
+export class UnsupportedCredentialError extends Error {
+  constructor() {
+    super("The Grok credential does not match the supported authentication contract")
+    this.name = "UnsupportedCredentialError"
+  }
+}
+
+export class CredentialFileTooLargeError extends Error {
+  constructor() {
+    super("The Grok credential file exceeds the 64 KiB limit")
+    this.name = "CredentialFileTooLargeError"
+  }
+}
+
+class CredentialRefreshRequiredError extends Error {}
+
+export function createCredentialSource({ contract, load, now, refresh }) {
+  if (
+    !contract ||
+    typeof load !== "function" ||
+    typeof now !== "function" ||
+    (refresh !== undefined && typeof refresh !== "function")
+  ) {
+    throw new TypeError("Invalid credential source dependencies")
+  }
+  let activeRefresh
+
+  const refreshOnce = async () => {
+    if (activeRefresh === undefined) {
+      activeRefresh = Promise.resolve().then(refresh).finally(() => {
+        activeRefresh = undefined
+      })
+    }
+    return activeRefresh
+  }
+
+  return Object.freeze({
+    async withAccessToken(operation) {
+      if (typeof operation !== "function") {
+        throw new TypeError("Access-token operation must be a function")
+      }
+
+      let raw
+      let rawText
+      let parsed
+      let accessToken
+      let metadata
+      let refreshAttempted = false
+
+      try {
+        while (accessToken === undefined) {
+          try {
+            raw = await load()
+            if (utf8ByteLength(raw) > 64 * 1024) {
+              throw new CredentialFileTooLargeError()
+            }
+            rawText = decodeUtf8(raw)
+            parsed = JSON.parse(rawText)
+
+            if (!isPlainObject(parsed)) throw new UnsupportedCredentialError()
+
+            const entries = Object.entries(parsed)
+            if (entries.length !== 1 || entries[0][0] !== contract.scope) {
+              throw new UnsupportedCredentialError()
+            }
+
+            const record = entries[0][1]
+            if (
+              !isPlainObject(record) ||
+              record.auth_mode !== contract.authMode ||
+              record.oidc_issuer !== contract.issuer ||
+              record.oidc_client_id !== contract.clientId ||
+              typeof record.key !== "string" ||
+              record.key.length === 0 ||
+              !isDateTime(record.expires_at)
+            ) {
+              throw new UnsupportedCredentialError()
+            }
+            const currentTime = now()
+            if (!(currentTime instanceof Date) || !Number.isFinite(currentTime.getTime())) {
+              throw new TypeError("Invalid credential source clock")
+            }
+            if (!isFutureDateTime(record.expires_at, currentTime)) throw new CredentialRefreshRequiredError()
+
+            accessToken = record.key
+            metadata = Object.freeze({
+              ...(isHeaderValue(record.user_id) ? { userId: record.user_id } : {}),
+            })
+          } catch (error) {
+            if (
+              error instanceof CredentialRefreshRequiredError &&
+              refresh !== undefined &&
+              !refreshAttempted
+            ) {
+              refreshAttempted = true
+              try {
+                await refreshOnce()
+              } catch {
+                throw new UnsupportedCredentialError()
+              }
+              raw = undefined
+              rawText = undefined
+              parsed = undefined
+              continue
+            }
+            if (
+              error instanceof UnsupportedCredentialError ||
+              error instanceof CredentialFileTooLargeError ||
+              error instanceof TypeError
+            ) {
+              throw error
+            }
+            throw new UnsupportedCredentialError()
+          }
+        }
+
+        return await operation(accessToken, metadata)
+      } finally {
+        metadata = undefined
+        accessToken = undefined
+        parsed = undefined
+        rawText = undefined
+        raw = undefined
+      }
+    },
+  })
+}
+
+function isHeaderValue(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 16 * 1024 && !/[\r\n\0]/u.test(value)
+}
+
+function utf8ByteLength(value) {
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8")
+  if (value instanceof Uint8Array) return value.byteLength
+  throw new TypeError("Credential loader must return a string or Uint8Array")
+}
+
+function decodeUtf8(value) {
+  if (typeof value === "string") return value
+  return new TextDecoder("utf-8", { fatal: true }).decode(value)
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function isFutureDateTime(value, now) {
+  if (typeof value !== "string") return false
+  const expiresAt = Date.parse(value)
+  return Number.isFinite(expiresAt) && expiresAt - now.getTime() > EXPIRY_SKEW_MS
+}
+
+function isDateTime(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value))
+}

package/dist/internal/grok-adapter.mjs

@@ -0,0 +1,160 @@
+import { parseModelCatalogResponse } from "./model-catalog.mjs"
+import { createResponsesEventDecoder } from "./responses-codec.mjs"
+import { encodeResponsesRequest } from "./responses-request.mjs"
+import { parseResponsesSse } from "./responses-sse.mjs"
+
+export class GrokAdapterError extends Error {
+  constructor() {
+    super("The requested Grok model or adapter generation is unavailable")
+    this.name = "GrokAdapterError"
+  }
+}
+
+export function createGrokAdapter({ getGeneration, mapError = (error) => error }) {
+  if (typeof getGeneration !== "function") {
+    throw new TypeError("A Grok adapter generation source is required")
+  }
+  if (typeof mapError !== "function") throw new TypeError("Invalid Grok adapter error mapper")
+
+  const captureGeneration = () => {
+    const generation = getGeneration()
+    if (
+      !isPlainObject(generation) ||
+      !generation.transport ||
+      typeof generation.transport.listModels !== "function" ||
+      typeof generation.transport.streamResponses !== "function"
+    ) {
+      throw new GrokAdapterError()
+    }
+    return generation
+  }
+
+  const resolveWithGeneration = async (generation, provider, model, signal) => {
+    try {
+      requireProvider(provider)
+      if (typeof model !== "string" || model.length === 0) throw new GrokAdapterError()
+      const entries = await discover(generation, provider, signal)
+      const match = entries.find((entry) => entry.resolvedModelInfo.id === model)
+      if (match === undefined) throw new GrokAdapterError()
+      return match.resolvedModelInfo
+    } catch (error) {
+      throw mapError(error)
+    }
+  }
+
+  return Object.freeze({
+    providerInfo(provider) {
+      requireProvider(provider)
+      return Object.freeze({ id: "grok", name: "Grok Build" })
+    },
+
+    providerRetryPolicy(provider) {
+      requireProvider(provider)
+      return undefined
+    },
+
+    async listModels(provider) {
+      try {
+        requireProvider(provider)
+        const entries = await discover(captureGeneration(), provider)
+        return Object.freeze(entries.map((entry) => entry.resolvedModelInfo))
+      } catch (error) {
+        throw mapError(error)
+      }
+    },
+
+    async resolveModel(provider, model, signal) {
+      return resolveWithGeneration(captureGeneration(), provider, model, signal)
+    },
+
+    async prepareCall(provider, model, signal) {
+      const generation = captureGeneration()
+      const resolvedModel = await resolveWithGeneration(generation, provider, model, signal)
+      return Object.freeze({
+        model: resolvedModel,
+        stream(options) {
+          try {
+            validatePreparedOptions(options, resolvedModel)
+            return streamWithGeneration(generation, options, mapError)
+          } catch (error) {
+            throw mapError(error)
+          }
+        },
+      })
+    },
+
+    stream(options) {
+      try {
+        return streamWithGeneration(captureGeneration(), options, mapError)
+      } catch (error) {
+        throw mapError(error)
+      }
+    },
+  })
+}
+
+async function discover(generation, provider, signal) {
+  const raw = await generation.transport.listModels({ signal })
+  return parseModelCatalogResponse(raw, { provider }).map((entry) => Object.freeze({
+    backend: entry.backend,
+    resolvedModelInfo: freezeModel(entry.resolvedModelInfo),
+  }))
+}
+
+async function* streamWithGeneration(generation, options, mapError) {
+  try {
+    requireProvider(options?.provider)
+    const request = encodeResponsesRequest(options)
+    const decoder = createResponsesEventDecoder()
+    for await (const event of parseResponsesSse(
+      generation.transport.streamResponses(request, { signal: options.signal }),
+    )) {
+      for (const chunk of decoder.push(event)) yield chunk
+    }
+    decoder.finish()
+  } catch (error) {
+    throw mapError(error)
+  }
+}
+
+function validatePreparedOptions(options, resolvedModel) {
+  if (!isPlainObject(options) || options.provider !== "grok" || options.model !== resolvedModel.id) {
+    throw new GrokAdapterError()
+  }
+  if (options.reasoningEffort !== undefined) {
+    const efforts = resolvedModel.reasoning?.efforts
+    if (!Array.isArray(efforts) || !efforts.some((effort) => effort.id === options.reasoningEffort)) {
+      throw new GrokAdapterError()
+    }
+  }
+}
+
+function freezeModel(model) {
+  const frozen = {
+    ...model,
+    inputModalities: model.inputModalities === undefined
+      ? undefined
+      : Object.freeze([...model.inputModalities]),
+    context: model.context === undefined ? undefined : Object.freeze({ ...model.context }),
+    reasoning: model.reasoning === undefined
+      ? undefined
+      : Object.freeze({
+        ...model.reasoning,
+        efforts: Object.freeze(model.reasoning.efforts.map((effort) => Object.freeze({ ...effort }))),
+      }),
+  }
+  if (frozen.inputModalities === undefined) delete frozen.inputModalities
+  if (frozen.context === undefined) delete frozen.context
+  if (frozen.reasoning === undefined) delete frozen.reasoning
+  return Object.freeze(frozen)
+}
+
+function requireProvider(provider) {
+  if (provider !== "grok") throw new GrokAdapterError()
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}

package/dist/internal/grok-command-handler.mjs

@@ -0,0 +1,62 @@
+import { parseGrokCommandInput } from "./grok-command.mjs"
+
+const USAGE = "Usage: /grok status|login|cancel|logout"
+
+export function createGrokCommandHandler({ controller }) {
+  if (
+    !controller ||
+    typeof controller.status !== "function" ||
+    typeof controller.beginLogin !== "function" ||
+    typeof controller.cancel !== "function" ||
+    typeof controller.logout !== "function"
+  ) throw new TypeError("Invalid Grok command controller")
+
+  return async function handleGrokCommand({ rawInput, signal } = {}) {
+    const command = parseGrokCommandInput(rawInput)
+    if (command === undefined) return error(USAGE)
+
+    try {
+      if (command.verb === "status") {
+        const status = await controller.status()
+        return success(`Grok official CLI auth: ${renderStatus(status)}`)
+      }
+      if (command.verb === "login") {
+        const session = await controller.beginLogin()
+        const outcome = await session.wait({ signal })
+        return outcome.kind === "succeeded"
+          ? success("Grok official CLI login succeeded")
+          : error(`Grok official CLI login ${outcome.kind}`)
+      }
+      if (command.verb === "cancel") {
+        const sessionId = (await controller.status()).session?.sessionId
+        return typeof sessionId === "string" && controller.cancel(sessionId)
+          ? success("Grok login cancellation requested")
+          : error("No Grok login is running")
+      }
+      if (command.verb === "logout") {
+        const outcome = await controller.logout({ signal })
+        return outcome.kind === "succeeded"
+          ? success("Grok official CLI logout succeeded")
+          : outcome.kind === "confirmation-required"
+            ? success("Repeat /grok logout within 30 seconds to confirm")
+            : error(`Grok official CLI logout ${outcome.kind}`)
+      }
+      return error(USAGE)
+    } catch {
+      return error("The Grok authentication operation failed")
+    }
+  }
+}
+
+function renderStatus(status) {
+  if (status.session?.state === "running") return "running"
+  return status.driver && status.available ? "ready" : "unavailable"
+}
+
+function success(text) {
+  return Object.freeze({ kind: "success", text })
+}
+
+function error(text) {
+  return Object.freeze({ kind: "error", text })
+}

package/dist/internal/grok-command.mjs

@@ -0,0 +1,17 @@
+const GRAMMAR = Object.freeze([
+  { pattern: /^\s+status$/u, build: () => ({ verb: "status" }) },
+  { pattern: /^\s+login$/u, build: () => ({ verb: "login" }) },
+  { pattern: /^\s+cancel$/u, build: () => ({ verb: "cancel" }) },
+  { pattern: /^\s+logout$/u, build: () => ({ verb: "logout" }) },
+])
+
+export function parseGrokCommandInput(rawInput) {
+  if (typeof rawInput !== "string" || rawInput.length > 256 || /[\r\n\0]/u.test(rawInput)) {
+    return undefined
+  }
+  for (const rule of GRAMMAR) {
+    const match = rule.pattern.exec(rawInput)
+    if (match !== null) return Object.freeze(rule.build(match))
+  }
+  return undefined
+}