@goodandready/dsh-subscriptions 0.6.71 → 0.6.72

package/lib/doctor.js

@@ -0,0 +1,163 @@
+/**
+ * Vendor Auth Doctor: Diagnose authentication, authorization, quota, and network errors
+ * into structured, human-understandable recommendations.
+ */
+
+export const DOCTOR_CODES = {
+  GEO_BLOCKED: 'GEO_BLOCKED',
+  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+  TOKEN_REVOKED: 'TOKEN_REVOKED',
+  MISSING_SCOPE: 'MISSING_SCOPE',
+  QUOTA_EXHAUSTED: 'QUOTA_EXHAUSTED',
+  RATE_LIMIT: 'RATE_LIMIT',
+  PROXY_ERROR: 'PROXY_ERROR',
+  UNKNOWN: 'UNKNOWN',
+}
+
+/**
+ * Classifies vendor errors and generates actionable recommendations.
+ * @param {any} err
+ * @param {string} [provider]
+ * @param {any} [_account]
+ * @returns {{ code: string, title: string, details: string, recommendation: string } | null}
+ */
+export function diagnoseVendorError(err, provider = '', _account = null) {
+  if (!err) return null
+
+  const msg = String(err.message || err.error || err || '').toLowerCase()
+  const code = String(err.code || err.status || err.statusCode || '').toUpperCase()
+  const p = String(provider || '').toLowerCase()
+
+  // 1. Geo-blocking / Cloudflare Firewall (403, 1020, region forbidden)
+  if (
+    msg.includes('country') ||
+    msg.includes('location') ||
+    msg.includes('region') ||
+    msg.includes('not supported in your country') ||
+    msg.includes('cloudflare') ||
+    msg.includes('cf-ray') ||
+    msg.includes('error 1020') ||
+    msg.includes('access denied') ||
+    (code === '403' && (msg.includes('forbidden') || msg.includes('blocked') || msg.includes('geoblock')))
+  ) {
+    return {
+      code: DOCTOR_CODES.GEO_BLOCKED,
+      title: 'Region or IP Blocked by Vendor Firewall',
+      details: `The vendor (${p || 'provider'}) returned a geo-restriction or Cloudflare block.`,
+      recommendation: 'Configure a dedicated SOCKS5 or HTTP proxy located in a supported region (US, EU, JP) in proxy settings.',
+    }
+  }
+
+  // 2. Token Expired / Session Expired
+  if (
+    msg.includes('token_expired') ||
+    msg.includes('jwt expired') ||
+    msg.includes('invalid_grant') ||
+    msg.includes('session expired') ||
+    msg.includes('refresh token expired') ||
+    msg.includes('token has expired') ||
+    msg.includes('login_required')
+  ) {
+    return {
+      code: DOCTOR_CODES.TOKEN_EXPIRED,
+      title: 'OAuth Access or Refresh Token Expired',
+      details: 'The stored OAuth credentials have expired and could not be refreshed automatically.',
+      recommendation: 'Click "Connect" or "Device Login" to re-authorize the account and establish a fresh session.',
+    }
+  }
+
+  // 3. Token Revoked / Bad Credentials
+  if (
+    msg.includes('token_revoked') ||
+    msg.includes('revoked') ||
+    msg.includes('account_deactivated') ||
+    msg.includes('invalid_token') ||
+    msg.includes('bad_credentials') ||
+    code === 'TOKEN_REVOKED' ||
+    (code === '401' && (msg.includes('unauthorized') || msg.includes('invalid api key') || msg.includes('incorrect api key')))
+  ) {
+    return {
+      code: DOCTOR_CODES.TOKEN_REVOKED,
+      title: 'Token Invalid or Revoked',
+      details: 'The vendor rejected the API key or OAuth token as invalid or revoked.',
+      recommendation: 'Re-issue a fresh session token, API key, or CLI credentials in the vendor dashboard and save it.',
+    }
+  }
+
+  // 4. Missing Scope / Permissions
+  if (
+    msg.includes('insufficient_scope') ||
+    msg.includes('missing_scope') ||
+    msg.includes('scope required') ||
+    msg.includes('permission_denied') ||
+    msg.includes('model_not_found') ||
+    msg.includes('not have access') ||
+    msg.includes('license_required')
+  ) {
+    return {
+      code: DOCTOR_CODES.MISSING_SCOPE,
+      title: 'Missing Scope or Model Permissions',
+      details: 'The account does not have sufficient entitlements or required scope permissions for this model.',
+      recommendation: 'Check your organization role or subscription tier to ensure permissions and access to requested models is granted.',
+    }
+  }
+
+  // 5. Quota Exhausted / Balance Zero
+  if (
+    msg.includes('insufficient_quota') ||
+    msg.includes('exceeded your current quota') ||
+    msg.includes('credit_balance_zero') ||
+    msg.includes('billing_not_active') ||
+    msg.includes('quota exceeded') ||
+    msg.includes('run out of credits') ||
+    code === 'QUOTA'
+  ) {
+    return {
+      code: DOCTOR_CODES.QUOTA_EXHAUSTED,
+      title: 'Subscription Quota or Credits Exhausted',
+      details: 'The account has consumed 100% of its current billing cycle or token usage quota.',
+      recommendation: 'Check your subscription billing dashboard or wait until the quota window resets.',
+    }
+  }
+
+  // 6. Rate Limit / 429
+  if (
+    code === '429' ||
+    code === 'RATE_LIMIT' ||
+    msg.includes('too many requests') ||
+    msg.includes('rate_limit') ||
+    msg.includes('rate limit')
+  ) {
+    return {
+      code: DOCTOR_CODES.RATE_LIMIT,
+      title: 'Temporary Rate Limit Reached',
+      details: 'The vendor is throttling requests (RPM/TPM limit reached) for this account.',
+      recommendation: 'Account is placed in temporary cooldown. Requests will automatically route to another account.',
+    }
+  }
+
+  // 7. Network / Proxy Connectivity
+  if (
+    msg.includes('econnrefused') ||
+    msg.includes('etimedout') ||
+    msg.includes('enotfound') ||
+    msg.includes('fetch failed') ||
+    msg.includes('socks') ||
+    code === 'ENOTFOUND' ||
+    code === 'ETIMEDOUT'
+  ) {
+    return {
+      code: DOCTOR_CODES.PROXY_ERROR,
+      title: 'Network or Proxy Connection Failure',
+      details: 'Failed to establish TCP/TLS connection with the provider API or configured proxy server.',
+      recommendation: 'Check server network access, DNS resolution, and verify the configured SOCKS/HTTP proxy is online.',
+    }
+  }
+
+  return {
+    code: DOCTOR_CODES.UNKNOWN,
+    title: 'Unexpected Vendor Error',
+    details: msg.slice(0, 200) || 'Unknown error occurred during vendor request.',
+    recommendation: 'Review vendor API status or re-check account credentials.',
+  }
+}

package/lib/instructions.js

@@ -0,0 +1,138 @@
+export const INSTRUCTIONS = {
+  codex: {
+    title: "OpenAI / ChatGPT Codex",
+    stepsEn: [
+      "1. Log in via CLI on server: run \"codex login\" in terminal.",
+      "2. Click \"📥 From CLI\" to auto-import ~/.codex/auth.json.",
+      "3. Or click \"Device Login\" above and enter the code at auth.openai.com.",
+    ],
+    stepsZh: [
+      "1. 在服务器上通过 CLI 登录：在终端运行 \"codex login\"。",
+      "2. 点击 \"📥 从 CLI 导入\" 自动读取 ~/.codex/auth.json。",
+      "3. 或者点击上方的 \"设备码登录\" (Device Login) 并在 auth.openai.com 输入代码。",
+    ],
+    link: "https://chatgpt.com",
+  },
+  claude: {
+    title: "Claude Code",
+    stepsEn: [
+      "1. Run \"claude login\" in server console.",
+      "2. Click \"📥 From CLI\" — plugin will import ~/.claude/credentials.json.",
+      "3. Or paste your Session Token / API Key from Anthropic Console and click \"Save token\".",
+    ],
+    stepsZh: [
+      "1. 在服务器控制台运行 \"claude login\"。",
+      "2. 点击 \"📥 从 CLI 导入\" — 插件将自动导入 ~/.claude/credentials.json。",
+      "3. 或者从 Anthropic 控制台复制您的 Session Token 或 API Key 并点击 \"保存令牌\"。",
+    ],
+    link: "https://console.anthropic.com/settings/keys",
+  },
+  cursor: {
+    title: "Cursor IDE",
+    stepsEn: [
+      "1. Auto CLI: if Cursor is used on server, click \"📥 From CLI\" (reads from ~/.cursor/cli-config.json).",
+      "2. Manual: open Cursor Settings (Connect button or link below), copy your session token or API key.",
+      "3. Paste it into the input field and click \"Save token\".",
+    ],
+    stepsZh: [
+      "1. CLI 自动导入：若服务器安装了 Cursor，点击 \"📥 从 CLI 导入\" (读取自 ~/.cursor/cli-config.json)。",
+      "2. 手动导入：打开 Cursor 设置页面（点击连接或下方链接），复制 WorkOS 会话令牌或 API 密钥。",
+      "3. 将其粘贴到输入框中并点击 \"保存令牌\"。",
+    ],
+    link: "https://cursor.com/settings",
+  },
+  antigravity: {
+    title: "Google Antigravity / Gemini",
+    stepsEn: [
+      "1. Easiest way: click \"📥 From CLI\" — server already has active token in ~/.gemini/antigravity-cli/antigravity-oauth-token.",
+      "2. Clicking \"📥 From CLI\" instantly loads fresh credentials.",
+      "3. Manual: paste session JSON or OAuth tokens and click \"Save token\".",
+      "Note: \"Connect\" button requires custom Google client_id in plugin settings; use \"📥 From CLI\" for seamless login!",
+    ],
+    stepsZh: [
+      "1. 推荐方式：点击 \"📥 从 CLI 导入\" — 服务器已保存 ~/.gemini/antigravity-cli/antigravity-oauth-token 会话。",
+      "2. 点击 \"📥 从 CLI 导入\" 可即时加载最新的凭据与 refresh_token。",
+      "3. 手动输入：将会话 JSON 或 OAuth access_token/refresh_token 粘贴至输入框并保存。",
+      "注：\"连接\" 按钮需要自定义 Google OAuth Client ID，推荐直接使用 \"📥 从 CLI 导入\"！",
+    ],
+    link: "https://antigravity.google",
+  },
+  kimi: {
+    title: "Moonshot Kimi",
+    stepsEn: [
+      "1. Open Moonshot developer console (link below or click Connect).",
+      "2. Generate and copy your API Key (sk-...).",
+      "3. Paste it into the input field and click \"Save token\".",
+      "4. Or click \"📥 From CLI\" if ~/.kimi-code is configured.",
+    ],
+    stepsZh: [
+      "1. 打开 Moonshot 开发者控制台（点击下方链接或点击连接）。",
+      "2. 创建并复制您的 API 密钥 (sk-...)。",
+      "3. 将密钥粘贴到槽位输入框中并点击 \"保存令牌\"。",
+      "4. 如果配置了 Kimi Code CLI，也可点击 \"📥 从 CLI 导入\" (~/.kimi-code)。",
+    ],
+    link: "https://platform.moonshot.cn/console/api-keys",
+  },
+  glm: {
+    title: "Zhipu GLM (Z.AI)",
+    stepsEn: [
+      "1. Open Zhipu BigModel API Keys center (link below or click Connect).",
+      "2. Copy your GLM API Key.",
+      "3. Paste it into the input field and click \"Save token\".",
+      "4. Or click \"📥 From CLI\" if ZCode CLI is installed (~/.zcode).",
+    ],
+    stepsZh: [
+      "1. 打开智谱 AI 开放平台（点击下方链接或点击连接）。",
+      "2. 复制您的 GLM API 密钥。",
+      "3. 粘贴到输入框中并点击 \"保存令牌\"。",
+      "4. 若已安装 ZCode CLI (~/.zcode)，点击 \"📥 从 CLI 导入\" 即可自动导入。",
+    ],
+    link: "https://bigmodel.cn/usercenter/proj-mgmt/apikeys",
+  },
+  grok: {
+    title: "xAI Grok",
+    stepsEn: [
+      "1. Click \"Device Login\" (or \"Connect\") on the slot card.",
+      "2. A one-time code will appear on the card.",
+      "3. Open https://accounts.x.ai/oauth2/device, enter the code, and approve access for your xAI account.",
+      "4. The plugin automatically captures tokens and enables Grok models.",
+      "5. Or click \"📥 From CLI\" (~/.grok/auth.json) / paste an xAI API Key.",
+    ],
+    stepsZh: [
+      "1. 点击卡片上的 \"设备码登录\" (Device Login) 或 \"连接\"。",
+      "2. 界面将展示一次性设备授权码。",
+      "3. 打开 https://accounts.x.ai/oauth2/device，输入代码，并为您拥有 Grok 订阅的 xAI 账户授权。",
+      "4. 授权成功后，插件会自动捕获会话并激活 Grok 官方模型。",
+      "5. 或点击 \"📥 从 CLI 导入\" (~/.grok/auth.json) / 直接粘贴 xAI API 密钥。",
+    ],
+    link: "https://accounts.x.ai/oauth2/device",
+  },
+  kiro: {
+    title: "AWS Kiro",
+    stepsEn: [
+      "1. Click \"📥 From CLI\" to import from ~/.kiro/credentials.json.",
+      "2. Or paste KIRO_API_KEY and click \"Save token\".",
+    ],
+    stepsZh: [
+      "1. 点击 \"📥 从 CLI 导入\" 从 ~/.kiro/credentials.json 或 ~/.aws/sso 导入凭据。",
+      "2. 或直接粘贴 KIRO_API_KEY 并点击 \"保存令牌\"。",
+    ],
+    link: "https://aws.amazon.com",
+  },
+  copilot: {
+    title: "GitHub Copilot",
+    stepsEn: [
+      "1. Click \"Device Login\" (or \"Connect\") on the slot card.",
+      "2. A one-time code will appear on the card.",
+      "3. Open https://github.com/login/device, enter the code, and approve access for your GitHub account with Copilot subscription.",
+      "4. The plugin automatically captures tokens and enables Copilot models.",
+    ],
+    stepsZh: [
+      "1. 点击卡片上的 \"设备码登录\" (Device Login) 或 \"连接\"。",
+      "2. 界面将展示一次性设备授权码。",
+      "3. 在浏览器打开 https://github.com/login/device 输入代码，并为您拥有 Copilot 订阅的 GitHub 账户授权。",
+      "4. 授权成功后，插件会自动捕获会话并激活 GitHub Copilot 官方模型。",
+    ],
+    link: "https://github.com/login/device",
+  },
+}

package/lib/routes/accounts.js

@@ -1,3 +1,4 @@
+import { diagnoseVendorError } from '../doctor.js'
 import { exportVault, importVault } from '../vault.js'
 import { normalizeSlots, vendorConfig } from '../accounts.js'
 import { getVendor } from '../vendors/index.js'
@@ -445,6 +446,77 @@ export function registerAccountsRoutes(ctx, state) {
     }),
   }), 'dsh-subscriptions: /import-token')
 
+  // Issue #541: Dynamic model catalog discovery & sync
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/accounts/sync-models',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      let payload = {}
+      try { payload = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}') } catch { /* ignore */ }
+      const provider = payload.provider
+      const index = payload.index || 1
+      if (!provider || !isProvider(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'invalid_provider', message: 'Invalid or missing provider' } })
+        return
+      }
+      const ref = oauthRef(provider, index)
+      const info = await store.describeRef(ref)
+      if (!info.configured) {
+        writeJson(res, 400, { ok: false, error: { code: 'not_configured', message: 'Account is not configured' } })
+        return
+      }
+      try {
+        let blob = await store.loadBlob(ref)
+        blob = await store.ensureFresh(provider, blob, ref)
+        const vendor = getVendor(provider)
+        const cfg = vendorConfig(provider, live())
+        const doFetch = (typeof state.fetchForRef === 'function' && state.fetchForRef(ref)) || fetch
+        let models = []
+        if (typeof vendor.listModels === 'function') {
+          const cat = await vendor.listModels(blob, cfg, doFetch)
+          if (Array.isArray(cat)) {
+            models = cat.map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+          } else if (cat && Array.isArray(cat.models)) {
+            models = cat.models.map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+          }
+        }
+        if (!models.length && vendor.defaults) {
+          models = (vendor.defaults().models || []).map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+        }
+        if (typeof store.rememberDynamicModels === 'function') {
+          store.rememberDynamicModels(ref, models)
+        }
+        writeJson(res, 200, {
+          ok: true,
+          provider,
+          index,
+          ref,
+          count: models.length,
+          models,
+        })
+      } catch (err) {
+        const doc = diagnoseVendorError(err, provider)
+        writeJson(res, 502, {
+          ok: false,
+          provider,
+          index,
+          ref,
+          doctor: doc,
+          error: { code: 'sync_failed', message: String(err && err.message || err) },
+        })
+      }
+    }),
+  }), 'dsh-subscriptions: /accounts/sync-models')
+
+
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',

package/lib/routes/status.js

@@ -1,3 +1,5 @@
+import { diagnoseVendorError } from '../doctor.js'
+import { INSTRUCTIONS } from '../instructions.js'
 import {
   getModelReasoningCapabilities,
   setSessionReasoning,
@@ -505,9 +507,13 @@ export function registerStatusRoutes(ctx, state) {
         blob = await store.loadBlob(ref)
         blob = await store.ensureFresh(provider, blob, ref)
       } catch (e) {
-        const latencyMs = Date.now() - t0
+        const latencyMs = Math.max(1, Date.now() - t0)
+        const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+        if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+        const docVerdict = diagnoseVendorError(e, provider, blob)
+        if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, docVerdict)
         history.add({ provider, ref, path: "/smoke", status: 401, ms: latencyMs })
-        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, error: { code: 'auth_failed', message: String(e && e.message || e) } })
+        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, latencyGrade, doctor: docVerdict, error: { code: 'auth_failed', message: String(e && e.message || e) } })
         return
       }
 
@@ -525,7 +531,10 @@ export function registerStatusRoutes(ctx, state) {
         }
         try {
           await vendor.check(blob, vendorConfig(provider, live()), probeFetch)
-          const latencyMs = Date.now() - t0
+          const latencyMs = Math.max(1, Date.now() - t0)
+          const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+          if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+          if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, null)
           history.add({ provider, ref, path: "/smoke", status: 200, ms: latencyMs })
           writeJson(res, 200, {
             ok: true,
@@ -533,6 +542,7 @@ export function registerStatusRoutes(ctx, state) {
             index,
             ref,
             latencyMs,
+            latencyGrade,
             label: pmL(blob.label),
             email: pmE(blob.email),
             quota: capturedQuota || info.quota || null,
@@ -540,7 +550,11 @@ export function registerStatusRoutes(ctx, state) {
           })
           return
         } catch (e) {
-          const latencyMs = Date.now() - t0
+          const latencyMs = Math.max(1, Date.now() - t0)
+          const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+          if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+          const docVerdict = diagnoseVendorError(e, provider, blob)
+          if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, docVerdict)
           history.add({ provider, ref, path: "/smoke", status: 502, ms: latencyMs })
           writeJson(res, 502, {
             ok: false,
@@ -548,13 +562,18 @@ export function registerStatusRoutes(ctx, state) {
             index,
             ref,
             latencyMs,
+            latencyGrade,
+            doctor: docVerdict,
             error: { code: e && e.code ? e.code : 'VENDOR', message: String(e && e.message || e).slice(0, 300) },
           })
           return
         }
       }
 
-      const latencyMs = Date.now() - t0
+      const latencyMs = Math.max(1, Date.now() - t0)
+      const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+      if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+      if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, null)
       history.add({ provider, ref, path: "/smoke", status: 200, ms: latencyMs })
       writeJson(res, 200, {
         ok: true,
@@ -562,6 +581,7 @@ export function registerStatusRoutes(ctx, state) {
         index,
         ref,
         latencyMs,
+        latencyGrade,
         label: pmL(blob.label),
         email: pmE(blob.email),
         quota: info.quota || null,
@@ -569,6 +589,80 @@ export function registerStatusRoutes(ctx, state) {
     }),
   }), 'dsh-subscriptions: /smoke')
 
+  // Issue #542: Latency RTT ping test endpoint
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/ping',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      let payload = {}
+      try { payload = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}') } catch { /* ignore ping payload */ }
+      const provider = payload.provider
+      const index = payload.index || 1
+      if (!provider || !isProvider(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'invalid_provider', message: 'Provider required' } })
+        return
+      }
+      const ref = oauthRef(provider, index)
+      const info = await store.describeRef(ref)
+      if (!info.configured) {
+        writeJson(res, 400, { ok: false, error: { code: 'not_configured', message: 'Account is not configured' } })
+        return
+      }
+      const t0 = Date.now()
+      let latencyMs = 0
+      let latencyGrade = 'good'
+      try {
+        const blob = await store.loadBlob(ref)
+        const vendor = getVendor(provider)
+        const cfg = vendorConfig(provider, live())
+        const doFetch = (typeof fetchForRef === 'function' && fetchForRef(ref)) || fetch
+        if (typeof vendor.check === 'function') {
+          await vendor.check(blob, cfg, doFetch)
+        } else if (typeof vendor.listModels === 'function') {
+          await vendor.listModels(blob, cfg, doFetch)
+        }
+        latencyMs = Math.max(1, Date.now() - t0)
+        latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+        if (typeof store.rememberPing === 'function') store.rememberPing(ref, { latencyMs, latencyGrade })
+        if (typeof store.rememberDoctorVerdict === 'function') store.rememberDoctorVerdict(ref, null)
+        writeJson(res, 200, { ok: true, provider, index, ref, latencyMs, latencyGrade })
+      } catch (err) {
+        latencyMs = Math.max(1, Date.now() - t0)
+        latencyGrade = 'poor'
+        const doc = diagnoseVendorError(err, provider)
+        if (typeof store.rememberPing === 'function') store.rememberPing(ref, { latencyMs, latencyGrade })
+        if (typeof store.rememberDoctorVerdict === 'function') store.rememberDoctorVerdict(ref, doc)
+        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, latencyGrade, doctor: doc, error: { message: String(err && err.message || err) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /ping')
+
+  // Issue #540: Dynamic vendor instructions API
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/instructions',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      writeJson(res, 200, { ok: true, instructions: INSTRUCTIONS })
+    }),
+  }), 'dsh-subscriptions: /instructions')
+
+
   // #351: Quota and session alerts API
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-subscriptions",
-  "version": "0.6.71",
+  "version": "0.6.72",
   "description": "Use ChatGPT Codex, Claude, Grok, Antigravity, Kimi, GLM, Cursor, Kiro, Copilot, Qwen, ERNIE, Spark, JetBrains, Perplexity, Replit, and Cody subscriptions as DeepSeek Harness LLM providers via OAuth.",
   "license": "MIT",
   "type": "module",