dsh-grok-provider 0.1.0

package/dist/internal/responses-request.mjs

@@ -0,0 +1,246 @@
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const MAX_TEXT_LENGTH = 8 * 1024 * 1024
+const MAX_REQUEST_BYTES = 16 * 1024 * 1024
+const MAX_MESSAGES = 10_000
+const MAX_TOOLS = 128
+
+export class UnsupportedResponsesRequestError extends Error {
+  constructor() {
+    super("The Harness request contains content or options unsupported by Grok Responses")
+    this.name = "UnsupportedResponsesRequestError"
+  }
+}
+
+export function encodeResponsesRequest(options) {
+  if (
+    !isPlainObject(options) ||
+    options.provider !== "grok" ||
+    !isId(options.model) ||
+    !Array.isArray(options.messages) ||
+    options.messages.length > MAX_MESSAGES
+  ) {
+    throw new UnsupportedResponsesRequestError()
+  }
+  if (options.stop !== undefined && (!Array.isArray(options.stop) || options.stop.length > 0)) {
+    throw new UnsupportedResponsesRequestError()
+  }
+
+  const request = {
+    model: options.model,
+    input: encodeMessages(options.messages, options.model),
+    ...(options.system === undefined ? {} : { instructions: parseText(options.system) }),
+    ...(options.tools === undefined ? {} : { tools: encodeTools(options.tools) }),
+    ...(options.reasoningEffort === undefined
+      ? {}
+      : { reasoning: { effort: parseId(options.reasoningEffort) } }),
+    ...(options.temperature === undefined
+      ? {}
+      : { temperature: parseTemperature(options.temperature) }),
+    ...(options.maxTokens === undefined
+      ? {}
+      : { max_output_tokens: parseMaxTokens(options.maxTokens) }),
+    include: ["reasoning.encrypted_content"],
+    stream: true,
+    store: false,
+  }
+
+  let serialized
+  try {
+    serialized = JSON.stringify(request)
+  } catch {
+    throw new UnsupportedResponsesRequestError()
+  }
+  if (Buffer.byteLength(serialized, "utf8") > MAX_REQUEST_BYTES) {
+    throw new UnsupportedResponsesRequestError()
+  }
+  return request
+}
+
+function encodeMessages(messages, targetModel) {
+  const input = []
+  for (const message of messages) {
+    if (!isPlainObject(message) || !Array.isArray(message.content)) fail()
+    if (message.source?.kind === "tool") {
+      encodeToolResultMessage(message, input)
+      continue
+    }
+    if (message.role !== "user" && message.role !== "assistant" && message.role !== "system") fail()
+    encodeOrdinaryMessage(message, input, targetModel)
+  }
+  return input
+}
+
+function encodeOrdinaryMessage(message, input, targetModel) {
+  const replayBlocks = readReplayBlocks(message, targetModel)
+  let text = ""
+  const flushText = () => {
+    if (text.length === 0) return
+    input.push({ role: message.role, content: text })
+    text = ""
+  }
+
+  for (const [position, block] of message.content.entries()) {
+    if (!isPlainObject(block) || typeof block.type !== "string") fail()
+    if (block.type === "text") {
+      text += parseText(block.text)
+      if (text.length > MAX_TEXT_LENGTH) fail()
+      continue
+    }
+    if (block.type === "reasoning" && message.role === "assistant") {
+      const replay = replayBlocks?.[position]
+      if (isReasoningReplay(replay)) {
+        flushText()
+        input.push({
+          type: "reasoning",
+          id: replay.id,
+          encrypted_content: replay.encryptedContent,
+          summary: block.text.length === 0
+            ? []
+            : [{ type: "summary_text", text: parseText(block.text) }],
+        })
+      }
+      continue
+    }
+    if (block.type === "tool-call" && message.role === "assistant") {
+      flushText()
+      if (!isId(block.id) || !isId(block.name) || !isJsonObject(block.arguments)) fail()
+      input.push({
+        type: "function_call",
+        call_id: block.id,
+        name: block.name,
+        arguments: block.arguments,
+      })
+      continue
+    }
+    fail()
+  }
+  flushText()
+}
+
+function readReplayBlocks(message, targetModel) {
+  const source = message.source
+  if (
+    !isPlainObject(source) ||
+    source.kind !== "model" ||
+    source.provider !== "grok" ||
+    source.model !== targetModel ||
+    !isPlainObject(source.replayState) ||
+    !isPlainObject(source.replayState.response) ||
+    source.replayState.response.version !== 1 ||
+    !Array.isArray(source.replayState.blocks) ||
+    source.replayState.blocks.length !== message.content.length
+  ) return undefined
+  return source.replayState.blocks
+}
+
+function isReasoningReplay(value) {
+  return isPlainObject(value) &&
+    value.type === "reasoning" &&
+    isId(value.id) &&
+    typeof value.encryptedContent === "string" &&
+    value.encryptedContent.length > 0 &&
+    Buffer.byteLength(value.encryptedContent, "utf8") <= MAX_TEXT_LENGTH
+}
+
+function encodeToolResultMessage(message, input) {
+  if (
+    message.role !== "user" ||
+    message.content.length !== 1 ||
+    !isPlainObject(message.content[0]) ||
+    message.content[0].type !== "tool-result"
+  ) fail()
+  const result = message.content[0]
+  if (
+    !isId(message.source.callId) ||
+    result.toolCallId !== message.source.callId ||
+    !Array.isArray(result.content)
+  ) fail()
+
+  let output = ""
+  for (const block of result.content) {
+    if (!isPlainObject(block) || block.type !== "text") fail()
+    output += parseText(block.text)
+    if (output.length > MAX_TEXT_LENGTH) fail()
+  }
+  input.push({ type: "function_call_output", call_id: result.toolCallId, output })
+}
+
+function encodeTools(tools) {
+  if (!Array.isArray(tools) || tools.length > MAX_TOOLS) fail()
+  const names = new Set()
+  return tools.map((tool) => {
+    if (
+      !isPlainObject(tool) ||
+      !isId(tool.name) ||
+      names.has(tool.name) ||
+      typeof tool.description !== "string" ||
+      tool.description.length > 4096 ||
+      !isPlainObject(tool.parameters)
+    ) fail()
+    names.add(tool.name)
+    return {
+      type: "function",
+      name: tool.name,
+      description: tool.description,
+      parameters: cloneJsonObject(tool.parameters),
+    }
+  })
+}
+
+function cloneJsonObject(value) {
+  let serialized
+  let cloned
+  try {
+    serialized = JSON.stringify(value)
+    if (serialized === undefined || Buffer.byteLength(serialized, "utf8") > 1024 * 1024) fail()
+    cloned = JSON.parse(serialized)
+  } catch (error) {
+    if (error instanceof UnsupportedResponsesRequestError) throw error
+    fail()
+  }
+  if (!isPlainObject(cloned)) fail()
+  return cloned
+}
+
+function parseText(value) {
+  if (typeof value !== "string" || value.length > MAX_TEXT_LENGTH) fail()
+  return value
+}
+
+function parseId(value) {
+  if (!isId(value)) fail()
+  return value
+}
+
+function parseTemperature(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 2) fail()
+  return value
+}
+
+function parseMaxTokens(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) fail()
+  return value
+}
+
+function isJsonObject(value) {
+  if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > 2 * 1024 * 1024) return false
+  try {
+    return isPlainObject(JSON.parse(value))
+  } catch {
+    return false
+  }
+}
+
+function isId(value) {
+  return typeof value === "string" && ID_PATTERN.test(value)
+}
+
+function fail() {
+  throw new UnsupportedResponsesRequestError()
+}
+
+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/responses-sse.mjs

@@ -0,0 +1,123 @@
+const MAX_EVENT_BYTES = 2 * 1024 * 1024
+const MAX_STREAM_BYTES = 128 * 1024 * 1024
+const MAX_EVENTS = 100_000
+
+export class InvalidResponsesSseError extends Error {
+  constructor() {
+    super("The Grok Responses event stream is invalid")
+    this.name = "InvalidResponsesSseError"
+  }
+}
+
+export async function* parseResponsesSse(source) {
+  if (source === null || source === undefined || typeof source[Symbol.asyncIterator] !== "function") {
+    throw new TypeError("Responses SSE source must be an async iterable")
+  }
+
+  const decoder = new TextDecoder("utf-8", { fatal: true })
+  let buffer = ""
+  let totalBytes = 0
+  let eventBytes = 0
+  let eventName
+  let dataLines = []
+  let eventCount = 0
+  let done = false
+
+  const dispatch = () => {
+    if (dataLines.length === 0) {
+      eventName = undefined
+      eventBytes = 0
+      return undefined
+    }
+    const data = dataLines.join("\n")
+    dataLines = []
+    eventBytes = 0
+    if (data === "[DONE]") {
+      if (eventName !== undefined) fail()
+      done = true
+      return undefined
+    }
+    if (done) fail()
+
+    let value
+    try {
+      value = JSON.parse(data)
+    } catch {
+      fail()
+    }
+    if (!isPlainObject(value) || typeof value.type !== "string") fail()
+    if (eventName !== undefined && eventName !== value.type) fail()
+    eventName = undefined
+    eventCount += 1
+    if (eventCount > MAX_EVENTS) fail()
+    return value
+  }
+
+  const consumeLine = (rawLine) => {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine
+    if (line === "") return dispatch()
+    if (line.startsWith(":")) return undefined
+    if (done) fail()
+
+    const colon = line.indexOf(":")
+    const field = colon === -1 ? line : line.slice(0, colon)
+    let value = colon === -1 ? "" : line.slice(colon + 1)
+    if (value.startsWith(" ")) value = value.slice(1)
+    eventBytes += Buffer.byteLength(line, "utf8") + 1
+    if (eventBytes > MAX_EVENT_BYTES) fail()
+
+    if (field === "event") {
+      if (eventName !== undefined || value.length === 0 || value.length > 256) fail()
+      eventName = value
+    } else if (field === "data") {
+      dataLines.push(value)
+    } else if (field !== "id") {
+      fail()
+    }
+    return undefined
+  }
+
+  try {
+    for await (const chunk of source) {
+      if (!(chunk instanceof Uint8Array)) fail()
+      totalBytes += chunk.byteLength
+      if (totalBytes > MAX_STREAM_BYTES) fail()
+      buffer += decoder.decode(chunk, { stream: true })
+      if (Buffer.byteLength(buffer, "utf8") > MAX_EVENT_BYTES) fail()
+
+      let newline
+      while ((newline = buffer.indexOf("\n")) !== -1) {
+        const value = consumeLine(buffer.slice(0, newline))
+        buffer = buffer.slice(newline + 1)
+        if (value !== undefined) yield value
+      }
+    }
+    buffer += decoder.decode()
+    if (buffer.length > 0) {
+      const value = consumeLine(buffer)
+      if (value !== undefined) yield value
+    }
+    if (dataLines.length > 0 || eventName !== undefined) {
+      const value = dispatch()
+      if (value !== undefined) yield value
+    }
+  } catch (error) {
+    if (error instanceof InvalidResponsesSseError || error instanceof TypeError) throw error
+    if (error?.name === "AbortError") throw error
+    throw new InvalidResponsesSseError()
+  } finally {
+    buffer = ""
+    dataLines = []
+    eventName = undefined
+  }
+}
+
+function fail() {
+  throw new InvalidResponsesSseError()
+}
+
+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/docs/01-product-requirements.md

@@ -0,0 +1,128 @@
+# 产品需求
+
+## 1. 产品定义
+
+提供一个原创的 DeepSeek Harness LLM Provider，使 Harness 能把 Grok Build 当作模型后端使用，同时保留 Harness 自己的会话、权限、工具和附件边界。
+
+冻结的 npm 身份：
+
+- 包名：`dsh-grok-provider`
+- 首个精确版本：`0.1.0`
+- Provider ID：`grok`
+- 当前真机模型快照：`grok-4.6`、`grok-4.5`；生产目录动态发现账号可用的全部模型
+
+项目选择无需 scope 所有权的唯一名称，避免把脚手架和 credential owner 绑定到尚未确认的 `@yukiryou` scope。该名称在 2026-08-25 查询时未公开发布；发布前仍必须重新检查占用状态。
+
+## 2. P0 用户目标
+
+- 在 Harness `0.1.1-rc.2` 中安装精确 npm 版本后出现 Grok Provider，并动态列出当前账号通过 Grok Build 可用的全部模型。
+- macOS 和 Windows 用户使用相同的插件包，不需要平台专属脚本。
+- 用户可从 Harness 发起官方 CLI 浏览器登录；插件能识别登录中、成功、取消、失败、凭据过期和未登录状态。
+- 首版只接受与发布绑定 CLI 版本的 xAI 第一方 OIDC schema 相符的候选。CLI 有效配置若选择外部 auth provider、企业 OIDC、API key 或无法判定的凭据结构，插件必须显示“不受支持的认证配置”并拒绝由本插件把该 token 发给 xAI CLI Chat Proxy；这不把未签名 metadata 宣称成来源证明。
+- 支持多轮文本对话、reasoning 增量、流式文本、工具调用、usage 和明确 finish 原因。
+- Harness 中止请求时，网络流和解析器都能及时终止。
+- 热更新设置或重新认证不会让同一调用混用两组路由或凭据。
+- 凭据不进入 renderer、RPC、settings、workspace、本插件日志、错误详情、诊断包或 npm tarball；官方 CLI 自身的日志、网络与遥测属于独立 vendor boundary。
+- 本插件拥有并注入 Bearer 的推理请求只到固定 xAI origin，任何 3xx 都失败；官方 CLI 登录网络是独立信任边界。
+- 发布物在 macOS arm64 的受管安装、重启和真实聊天 smoke test 中通过；Windows x64 首次真机验证在 `0.1.0` 发布后执行，验证前必须明确标注为“代码支持、真机未验证”。
+
+## 3. P0 安全负需求
+
+首版明确禁止：
+
+- 复制、提取或反编译第三方/xAI 官方 CLI 的 OAuth Client ID，或接受用户提供任意 client ID。
+- 保存 client secret，或把官方 access/refresh token 复制到 Harness credentials、settings、环境、日志、workspace 或 renderer。
+- 由插件直接启动 shell、PowerShell、`cmd /c start`、`open`、`xdg-open` 或任意 URL opener；本约束不伪装成对官方 CLI 内部行为的保证。
+- 通过 renderer/RPC 接收任意可执行路径、命令、参数、环境变量或 cwd；唯一允许的进程入口是 Host 内部验证后的官方 `grok`，参数只能来自闭合命令表。
+- 接受用户、模型、远端响应或 marketplace 配置提供的 `baseURL`。
+- 跟随重定向发送 Authorization。
+- 把 Authorization、Cookie 或 Referer 带到图片、附件或远端返回的 URL。
+- 将远端错误 body、请求 headers、完整 SSE 事件或凭据文件内容原样返回 UI。
+- 在安装期间运行 `preinstall`、`install` 或 `postinstall`。
+
+## 4. `0.1.0` 范围
+
+### 账户与模型概览
+
+- Web 设置页以账户状态卡、额度卡、模型能力卡的层级展示信息，并适配窄屏单列布局。
+- 登录后展示官方 billing 返回的真实使用百分比和额度周期结束时间；数据缺失时明确显示不可用，不猜测。
+- 展示账号动态可见的全部模型，以及上下文窗口、推理档位、文本/流式/tool capability。
+- 首版不提供模型隐藏开关；Harness 模型选择器继续显示账号可见的全部模型。
+- 页面支持手动刷新；额度与模型不写入插件配置或 workspace。
+
+包含：
+
+- 通过固定 `/v1/models` 动态发现的全部账号可用 Grok Build 模型；当前真实快照为 `grok-4.6` 与 `grok-4.5`。
+- 文本输入与输出。
+- reasoning 增量（远端协议实际支持时）。
+- Harness 定义的工具调用增量。
+- 流式 usage、finish、超时、取消与稳定错误码。
+- 只读官方 Grok CLI 会话凭据。
+- Host 侧官方 CLI 登录桥：`login`、`cancel`、`status`、`logout`。
+- Web 设置页：认证状态、“使用 Grok 登录”、取消、退出、安装说明和隐私说明。
+- TUI 闭合命令：`/grok status`、`login`、`cancel`、`logout`；Web 与 TUI 共用同一认证协调器。
+
+不包含：
+
+- 插件自管 OAuth、device flow、authorization-code callback、任意 URL opener、client ID 或 client secret。
+- xAI API Key 模式。
+- Grok ACP 或 `grok -p` headless 代理。
+- 厂商侧 Web Search、X Search、远程抓取。
+- 图片生成、图片 URL 下载或文件落盘。
+- 图片输入；后续版本只有在 Harness attachment 限额与协议兼容测试完成后再考虑。
+- 自定义 endpoint、企业 OIDC、自定义代理或多账号。
+- 自动安装或更新 Grok CLI。
+- 在远程 Web/headless 主机自动打开浏览器或无人值守登录的承诺。
+- Linux 的发布承诺；实现应避免无谓的平台绑定，但首版只验收 macOS 与 Windows。
+
+## 5. 用户流程
+
+### 首次使用
+
+1. 用户从 xAI 官方渠道安装与本机架构匹配的 Grok Build CLI。
+2. 用户在 Web 设置页点击“使用 Grok 登录”，或在 TUI 输入 `/grok login`。
+3. Host 从官方默认目录解析并对 `grok`/`grok.exe` 做路径、owner 和版本约束，通过 Harness `ctx.subprocess` 用固定 argv `[constrainedExecutable, "login", "--oauth"]` 启动它；该 seam 不做 shell 解释。
+4. 在受支持的标准配置下，官方 CLI 打开系统浏览器、处理 OAuth/loopback callback，并管理自己的共享凭据；它可能先清除旧会话并在成功后同步 managed config。
+5. 插件只向 UI 返回 `starting`、`running`、`succeeded`、`cancelled`、`failed` 等可观察闭合状态；不猜测“浏览器已打开”，也不回传原始 stdout/stderr、授权 URL 或 token。
+6. 登录进程以成功、失败、取消或超时结算后，插件都先等待受管树、失效缓存并重新检查凭据；只有唯一、非歧义且符合绑定 CLI 版本第一方 OIDC schema 的记录才能把当前 credential 状态标成 `valid`，其他模式失败关闭。登录尝试 outcome 与当前 credential 状态分开显示。
+7. 插件刷新固定 `/v1/models` 目录，用户选择当前账号可用模型并开始对话。
+
+### 凭据过期
+
+1. 官方 CLI 凭据过期或进入固定 skew 时，插件只对完全匹配的官方 OIDC record 启动一次 single-flight、30 秒有界的 `grok models`，由 CLI 自行刷新其凭据；随后重新读取并校验。刷新失败、CLI capability 缺失或 record 仍无效时以 LLM `AUTH` 失败，不循环、不降级。
+2. 首个 401 使内存中的 lease 失效；已经发送的 POST 不自动重放。
+3. 设置页显示“重新登录”；下一次明确用户动作才启动官方 CLI 浏览器登录。
+4. 插件不删除、不修改官方 `auth.json`。
+
+### 退出
+
+Web 的“退出”或 TUI `/grok logout` 先中止本插件所有在途 Grok 请求并推进认证 generation，再由 Host 以同样的受限方式执行官方 `grok logout`，最后清除插件内存缓存。较早请求不得在退出后重新填充旧 token。插件不直接删除或修改其他应用的凭据文件。
+
+## 6. 隐私与可观察性
+
+- 提示词、工具参数、附件、搜索词默认不写日志。
+- 普通日志只允许 endpoint ID、状态码、耗时、字节计数、插件错误码和随机 diagnostic ID；Harness RPC correlation 由 carrier 内部所有。
+- 设置页明确说明提示词与工具结果会发送给 xAI Grok Build 服务。
+- 插件只能保证自己不声明厂商侧搜索工具，不能保证服务商内部永不检索；此残余行为需依据 xAI 当时文档披露。
+
+## 7. 成功指标
+
+- 受管市场安装结果为 `artifact-verified`。
+- macOS arm64 和 Windows x64 的自动测试通过。macOS x64 不在当前官方 CLI 支持矩阵，也不属于 `0.1.0` 承诺。
+- `0.1.0` 发布前至少一台真实 macOS arm64 设备完成安装、登录、流式对话、工具调用、中止、重启与重新认证 smoke。
+- `0.1.0` 发布后在一台真实 Windows x64 设备对 Registry 中的精确 `0.1.0` 执行首次安装、登录、流式对话、工具调用、中止、重启与重新认证 smoke；该项是发布后跟进，不回溯阻断已经完成的首次发布。
+- `0.1.1` 及后续版本不把重复真机 smoke 设为常规发版门禁；由 macOS/Windows CI、契约测试、干净安装和精确 tarball 校验承接。认证、官方 CLI、Harness subprocess 或平台安全边界变化时安排定向真机复核，但除非当次发布另行声明，不作为强制门禁。
+- canary secret 扫描确认日志、RPC、错误、临时文件和打包产物无泄漏。
+- 协议测试确认第二个测试 origin 永远收不到 Authorization。
+
+## 8. 发布阻断项
+
+任一条件不满足都不得发布：
+
+- xAI 官方文档或官方答复不允许第三方本地 adapter 使用官方会话凭据调用 CLI Chat Proxy。
+- 服务条款或官方答复不允许独立插件使用该路径。
+- 任一真实发现模型的基础流无法映射，或声明支持的工具调用无法无损映射到 Harness。
+- 凭据只能通过不安全的 renderer、RPC 或明文复制方式获得。
+- 官方 CLI 凭据筛选无法阻止 schema 不符 token 进入固定 Proxy。
+- macOS arm64 发布前验收失败；或自动化 Windows x64 平台测试失败。
+- GitHub repository 或 provenance 发布链未确定，或冻结包名在发布前被他人占用。

package/docs/02-architecture-options.md

@@ -0,0 +1,180 @@
+# 架构候选与推荐路线
+
+## 1. 评价标准
+
+候选路线按以下优先级评价：
+
+1. xAI 官方支持证据与服务条款风险。
+2. 凭据暴露面和可审计性。
+3. Harness LLM 流、reasoning 与工具调用的语义完整性。
+4. macOS 与 Windows 一致性。
+5. 依赖体积、供应链与受管市场可安装性。
+6. 用户体验与维护成本。
+
+## 2. 候选比较
+
+| 路线 | 认证所有者 | Harness 语义 | 跨平台 | 主要风险 | 决策 |
+|---|---|---:|---:|---|---|
+| A. 插件自管 device OAuth + 固定 Proxy | 插件 | 高 | 高 | Client ID 授权、令牌存储、刷新状态机 | ADR-0005 拒绝进入 `0.1.0` |
+| B. Harness 发起官方 CLI 登录 + 固定 Proxy | xAI CLI | 高 | 高 | 依赖官方 CLI；子进程生命周期；上游文件格式变化 | **采用** |
+| C. `grok -p` Headless | xAI CLI | 低 | 高 | prompt 展平、每次进程开销、工具与会话语义不完整 | 拒绝 Provider 路线 |
+| D. `grok agent stdio` ACP | xAI CLI | 低 | 高 | agent 套 agent，权限、工具、会话边界重复 | 拒绝 Provider 路线 |
+| E. xAI Console API Key | 插件/用户 | 高 | 高 | 独立计费，未必提供 Grok Build 订阅模型 | 后续独立模式 |
+
+## 3. 推荐路线 B（官方 CLI 单路径）
+
+### 数据流
+
+```text
+Harness renderer
+  │ 仅状态 DTO / 模型选择
+  ▼
+Harness Host
+  ├─ GrokAdapter
+  │    ├─ 动态账号模型目录
+  │    ├─ prepareCall generation
+  │    └─ Harness chunk 流
+  ├─ OfficialSessionCredentialSource
+  │    └─ 只读 xAI 官方 auth.json
+  ├─ OfficialGrokLoginBridge
+  │    └─ 仅 ctx.subprocess.spawn([<constrained grok>, login --oauth|logout])
+  ├─ PinnedGrokTransport
+  │    └─ 仅 cli-chat-proxy.grok.com
+  └─ ProviderWireCodec
+       ├─ ResponsesCodec（当前真实模型）
+       └─ 其他 Grok 声明 backend 只有在协议与真机门禁通过后启用
+
+xAI 官方 Grok Build CLI
+  ├─ 标准配置：打开系统浏览器、OAuth、loopback callback、凭据写入
+  └─ 用户/企业有效配置：也可能选择外部 auth command 或企业 OIDC
+```
+
+### 深模块边界
+
+#### `GrokAdapter`
+
+对 Harness 暴露一个小而稳定的 Provider 接口，内部隐藏认证文件、HTTP headers、SSE 方言和重试细节。它拥有：
+
+- `providerInfo` 与 retry policy。
+- 动态、认证 generation 隔离的账号模型目录；不从模型名猜能力。
+- `prepareCall()` 的 generation 快照。
+- 输入验证、工具 schema 转换和 Harness chunk 顺序。
+
+#### `OfficialSessionCredentialSource`
+
+它只提供“为一次 Host 请求取得当前 access token”的能力，不把文件路径、JSON、token 或 refresh token暴露给调用方。设计约束：
+
+- 路径只来自 Host 的 OS home 或 Host 启动时已有的 `GROK_HOME` 环境，不接受 UI/RPC 参数。
+- 文件必须是普通文件，大小不超过 64 KiB；拒绝 symlink、reparse point、目录和设备文件。
+- JSON 严格解析，只读取官方身份 key；未知结构返回 `AUTH_FORMAT_UNSUPPORTED`。
+- 只接受唯一、无歧义、与发布绑定 CLI 版本的 xAI 生产 OIDC schema 相符的记录：`auth_mode`、issuer、client ID、scope、expiry 与 token 都必须通过闭合关系；external、API key、web-login、企业 issuer、legacy scope 和多记录全部拒绝。
+- 这些字段是官方 CLI 写入的本地未签名 metadata，只能作为失败关闭的兼容性筛选，不能作为 token 第一方来源的密码学证明。
+- token 仅在 Host 内存短暂缓存，按文件元数据变化和 401 失效。
+- 永不直接写入、执行 OAuth refresh grant、迁移或删除官方凭据；过期时可启动固定的官方 `grok models` 命令，由 CLI 在自己的信任边界内刷新并写回，插件随后重新校验 snapshot。
+
+#### `OfficialGrokLoginBridge`
+
+为 Web 设置页和 TUI 提供与 `dsh-codex` 类似的“在 Harness 内发起登录”体验，但不接管 OAuth：
+
+- 从 Host 启动时冻结的绝对 `GROK_HOME` 派生候选：macOS 默认 `~/.grok/bin/grok`；Windows 默认 `%USERPROFILE%\\.grok\\bin\\grok.exe`。不使用 `GROK_BIN_DIR`、PATH、workspace，也不接受 RPC/UI 传路径。
+- macOS 官方安装会使用 symlink；必须 `realpath` 后确认目标位于同一 `~/.grok` 根下、是当前用户拥有的普通可执行文件。Windows 拒绝 reparse point 和非普通文件。
+- 只使用 Harness 公开 `ctx.subprocess.resolveExecutable()` 与 `ctx.subprocess.spawn()`；不直接 import `node:child_process`，也不把 `@deepseek-ai/dsh-subprocess-local` 打进插件。
+- 先执行固定 argv `[constrainedExecutable, "--version"]`，在 10 秒和 16 KiB 输出上限内验证版本格式，并要求版本属于发布时冻结的有限精确 allowlist；未经测试的更高版本也失败关闭。
+- 登录只允许 `[constrainedExecutable, "login", "--oauth"]`；退出只允许 `[constrainedExecutable, "logout"]`。不拼接字符串、不显式启动 shell、不接受额外参数。
+- `cwd` 使用受控的 Grok home，不使用用户 workspace；stdin 关闭，stdout/stderr 分别限制 64 KiB。
+- 同时只允许一个登录事务；默认 5 分钟超时，支持取消与插件卸载清理。终止通过 Harness seam 对整棵进程树执行，Windows 与 macOS 行为由 Runtime 实现并在真实设备验证。
+- 官方 CLI 自己打开浏览器并监听 callback。插件只映射进程状态，绝不把原始输出、授权 URL、state、code 或 token 送入 renderer。
+- `grok login --oauth` 成功退出后再读取凭据；进程退出码为 0 但凭据无效时仍判定失败。
+- `--oauth` 只固定 loopback transport，并不会绕过 CLI 的 external provider、devbox、OIDC、系统 managed config 或 MDM。检测到已知的 external/enterprise 环境覆盖时应在 spawn 前失败；即便未检测到，官方 CLI 及其有效配置仍是用户管理的信任边界，登录后的凭据门禁是最终防线。
+- 首版只支持 Harness Host 与浏览器处于同一 macOS/Windows 桌面会话；远程 Web/headless 不假装成功，也不把 Host 的登录误报成客户端登录。
+
+公开 Host API 只接受闭合动作：
+
+```ts
+type AuthAction = "status" | "login" | "cancel" | "logout"
+```
+
+它不是通用命令执行器，也不是通用 URL opener。
+
+#### `PinnedGrokTransport`
+
+调用方传 endpoint ID，不传 URL：
+
+```ts
+type EndpointId = "models" | "responses" | "chat-completions" | "messages"
+```
+
+生产映射编译期固定到：
+
+```text
+models           -> GET  https://cli-chat-proxy.grok.com/v1/models
+responses        -> POST https://cli-chat-proxy.grok.com/v1/responses
+chat-completions -> POST https://cli-chat-proxy.grok.com/v1/chat/completions
+messages         -> POST https://cli-chat-proxy.grok.com/v1/messages
+```
+
+只有目录返回的闭合 `api_backend` 才能选择对应 endpoint；调用方不能直接传 URL。2026-08-26 的 `grok-4.6` 与 `grok-4.5` 都声明 `responses`。若真实账号目录出现尚未通过 codec 与真机测试的 backend，则“支持全部模型”门禁失败并阻断发布，不能静默隐藏该模型。
+
+Transport 独占 Authorization 注入，强制 `redirect: "error"`、HTTPS、固定 origin/path、超时、取消和响应上限。测试通过构造时注入本地 transport，不在生产配置中暴露 base URL。
+
+#### `ProviderWireCodec`
+
+负责按 backend 把经过 schema 验证的远端增量转换为 Harness。当前 Responses 流已真实观察到 `response.created`、reasoning summary、output item/content part、output text 和 `response.completed`；所有 event 都必须经过闭合状态机后才转换为：
+
+- `block-start`
+- `text-delta` / `reasoning-delta`
+- `tool-call-delta`
+- `block-end`
+- `usage`
+- `finish`
+
+`usage` 必须在 `finish` 前，`finish` 后不得再输出；截断或空成功响应必须产生稳定错误，不得假装成功。
+
+### 登录的两层保证
+
+- 插件可保证：renderer 无通用命令能力；传给 Harness seam 的 argv、cwd、stdio、环境覆盖与期限闭合；该 seam 不解释 shell；取消/卸载终止受管进程树；不符合绑定生产 OIDC schema 的凭据不会被本插件发往固定 Proxy。
+- 插件不能保证：官方 CLI 不依据受信配置执行内部 shell、外部 helper、devbox 或企业 OIDC；也不能从未签名 `auth.json` metadata 密码学证明 token 的签发者。
+
+因此推荐路线的前提是接受“官方 Grok CLI + 它的有效配置”为本地信任边界。若产品要求端到端绝不运行 shell，当前上游没有可验证的 builtin-only/no-config 参数，本路线必须阻断，等待上游能力或改用获得 xAI 授权的自有 OAuth client。
+
+## 4. 已拒绝的自管 OAuth 责任
+
+自行 OAuth 会同时引入以下责任；ADR-0005 决定 `0.1.0` 不承担它们：
+
+- 取得明确授权的公共 OAuth Client ID，而不是复制官方 CLI 或第三方 Client ID。
+- RFC 8628 device code、固定 verification URI、polling、取消、过期和重放防御。
+- Harness credential grant record 的明文落盘边界与未来 keychain provider 迁移。
+- refresh token 轮换、并发 single-flight、注销和恢复。
+- 需要自行承担跨平台安全存储、刷新与账户切换，而 Harness 的子进程 seam 只能解决官方 CLI 生命周期，不能替代这些认证责任。
+
+当前单一路径把这些责任留给官方 CLI。ADR-0003 仅作为已被取代的历史设计保留，发布包不包含对应实现。
+
+## 5. 为什么不用 Headless
+
+xAI 官方把 Headless 描述为简单脚本集成；示例会把消息压成 prompt，并运行一个完整 Grok agent 进程。作为 Harness LLM Provider，它无法可靠保证：
+
+- 系统、用户、助手消息的原始角色边界。
+- Harness tool schema 与增量 tool calls。
+- Harness 自己的权限 UI 是唯一工具授权来源。
+- 同一流的 usage、finish、abort 和 retry 语义。
+
+因此 Headless 适合单独的“调用 Grok agent”功能，不适合本项目的 LLM adapter。
+
+## 6. 为什么不用 ACP
+
+ACP 面向 IDE 与 agent client，包含自己的 session、tools、permission 和 MCP 生命周期。把 ACP agent 包进 Harness LLM Provider 会形成两层 agent loop，让用户难以判断哪一层执行工具、保存会话和做权限确认。首版保持模型层集成，不引入 ACP。
+
+## 7. API Key 备选
+
+xAI Console API Key 是更传统的官方 API 路线，但通常是独立 API 计费，并不能自动等价于 Grok Build 订阅额度或模型目录。若未来需要，应作为明确命名的第二种认证模式，并使用 `api.x.ai` 的官方 API 文档；不能在失败时静默从订阅会话切换到可能计费的 API Key。
+
+## 8. 首个开发验证
+
+方案获批后的第一项工作不是大规模编码，而是一个受控协议 spike：
+
+1. 使用用户自己的官方 CLI 登录会话。
+2. 验证在受支持的标准 Grok 配置下，从 Web/TUI 触发 `grok login --oauth` 后，macOS 与 Windows 都由官方 CLI 打开系统浏览器；取消、超时和卸载会终止并等待 Harness seam 可观察的受管进程树；Windows 不出现额外 shell/console 闪窗。
+3. 分别验证标准配置、external auth、企业 OIDC、环境覆盖与多记录 auth 文件；只允许与绑定版本生产 OIDC schema 相符的候选进入 transport，并记录官方 CLI 仍可能在内部执行配置命令这一残余风险。
+4. 对固定 Chat Proxy 验证多轮消息、流式文本、reasoning、工具 schema、增量 tool call、usage、finish、401 和中止。
+5. 只记录脱敏后的字段名称、类型和状态，不保存 prompt、token、完整响应或账号信息。
+6. 若工具调用不能无损映射，或凭据筛选不足以维持固定 Proxy 边界，停止实现并回到本 ADR；不得用 prompt 拼接或 ACP 偷换路线。