@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/plugins/opencode-go/oauth.mjs

@@ -0,0 +1,194 @@
+import { LlmError } from '@deepseek-ai/dsh-llm';
+
+// Signing in to OpenCode Go with an OpenCode console account instead of a pasted API key.
+//
+// The console speaks the OAuth device flow (RFC 8628) to the public client `opencode-cli`,
+// which is OpenCode's own CLI; DSCODE borrows that client id, so the consent page names the
+// OpenCode CLI. The access token does not work on the public `zen/go/v1` endpoint: the
+// console's `/api/config` names the account's own inference endpoint for `opencode-go`,
+// which takes the token as a bearer plus `x-opencode-org-id` (probed 2026-09).
+//
+// Refresh tokens rotate: every refresh returns a new one and voids the old. DSCODE therefore
+// keeps its own grant, separate from any OpenCode CLI login, and re-reads the store before
+// giving up on a refused refresh, because another DSCODE process may have rotated it first.
+
+export const CONSOLE_URL = 'https://opencode.ai/console';
+export const CLIENT_ID = 'opencode-cli';
+/** Credential reference holding the grant, as JSON, in the shared store. */
+export const GRANT_REF = 'OPENCODE_OAUTH';
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** Refresh once the access token has less than this left. */
+export const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+const GRANT_VERSION = 1;
+
+async function request(fetchImpl, url, { method = 'GET', body, token, orgID, signal } = {}) {
+  const response = await fetchImpl(url, {
+    method, signal, redirect: 'error',
+    headers: {
+      accept: 'application/json',
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+      ...(token !== undefined ? { authorization: `Bearer ${token}` } : {}),
+      ...(orgID !== undefined ? { 'x-org-id': orgID } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await response.text();
+  let json;
+  try { json = JSON.parse(text); } catch { json = undefined; }
+  return { status: response.status, ok: response.ok, json, text };
+}
+
+const describe = result => result.json?.error_description ?? result.json?.error ?? `HTTP ${result.status}`;
+
+/**
+ * Start a device login.
+ * @returns `{ deviceCode, userCode, url, intervalMs, expiresAt }`; `url` already carries the user code.
+ */
+export async function startDeviceLogin({ fetch: fetchImpl = globalThis.fetch, server = CONSOLE_URL, now = Date.now() } = {}) {
+  const result = await request(fetchImpl, `${server}/auth/device/code`, { method: 'POST', body: { client_id: CLIENT_ID } });
+  const device = result.json;
+  if (!result.ok || typeof device?.device_code !== 'string' || typeof device.user_code !== 'string') {
+    throw new Error(`OpenCode refused to start a login: ${describe(result)}`);
+  }
+  const url = new URL(device.verification_uri_complete ?? device.verification_uri ?? '/console/device', `${server}/`);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error('OpenCode returned an unusable verification URL');
+  return {
+    deviceCode: device.device_code,
+    userCode: device.user_code,
+    url: url.href,
+    intervalMs: Math.max(1, Number(device.interval) || 5) * 1000,
+    expiresAt: now + Math.max(1, Number(device.expires_in) || 600) * 1000,
+  };
+}
+
+/**
+ * Poll until the user approves, the code expires or `signal` aborts.
+ * @returns the token response (`access_token`, `refresh_token`, `expires_in`).
+ */
+export async function pollDeviceToken(device, { fetch: fetchImpl = globalThis.fetch, server = CONSOLE_URL, signal, sleep, now = () => Date.now() } = {}) {
+  const wait = sleep ?? (ms => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+  }));
+  let interval = device.intervalMs;
+  while (now() < device.expiresAt) {
+    await wait(interval);
+    signal?.throwIfAborted();
+    const result = await request(fetchImpl, `${server}/auth/device/token`, { method: 'POST', signal, body: { grant_type: DEVICE_GRANT, device_code: device.deviceCode, client_id: CLIENT_ID } });
+    if (typeof result.json?.access_token === 'string') return result.json;
+    const error = result.json?.error;
+    if (error === 'authorization_pending') continue;
+    if (error === 'slow_down') { interval += 5000; continue; }
+    // A transient gateway failure is not an answer; keep polling until the code expires.
+    if (result.status >= 500 || result.status === 429) continue;
+    throw new Error(error === 'expired_token' ? 'the login code expired before it was approved' : error === 'access_denied' ? 'the login was declined' : `OpenCode refused the login: ${describe(result)}`);
+  }
+  throw new Error('the login code expired before it was approved');
+}
+
+/**
+ * Turn a token response into a stored grant: the account, and the first organisation (by
+ * name) whose console config carries `opencode-go`, with the inference endpoint it names.
+ */
+export async function completeGrant(token, { fetch: fetchImpl = globalThis.fetch, server = CONSOLE_URL, now = Date.now() } = {}) {
+  const access = token.access_token;
+  const [user, orgs] = await Promise.all([
+    request(fetchImpl, `${server}/api/user`, { token: access }),
+    request(fetchImpl, `${server}/api/orgs`, { token: access }),
+  ]);
+  if (!user.ok || !orgs.ok || !Array.isArray(orgs.json)) throw new Error(`OpenCode did not return the account: ${describe(user.ok ? orgs : user)}`);
+  const sorted = orgs.json.filter(org => typeof org?.id === 'string')
+    .toSorted((a, b) => String(a.name).localeCompare(String(b.name)) || a.id.localeCompare(b.id));
+  for (const org of sorted) {
+    const config = await request(fetchImpl, `${server}/api/config`, { token: access, orgID: org.id });
+    const go = config.ok ? config.json?.config?.provider?.['opencode-go'] : undefined;
+    if (typeof go?.api !== 'string' || !URL.canParse(go.api)) continue;
+    return {
+      version: GRANT_VERSION,
+      access,
+      refresh: token.refresh_token,
+      expires: now + Math.max(0, Number(token.expires_in) || 0) * 1000,
+      server,
+      api: go.api.replace(/\/+$/, ''),
+      orgID: org.id,
+      ...(typeof org.name === 'string' ? { orgName: org.name } : {}),
+      ...(typeof user.json?.email === 'string' ? { email: user.json.email } : {}),
+    };
+  }
+  throw new Error('this OpenCode account has no organisation with an OpenCode Go subscription');
+}
+
+/** Exchange the grant's refresh token; the returned grant carries the rotated one. */
+export async function refreshGrant(grant, { fetch: fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  const result = await request(fetchImpl, `${grant.server ?? CONSOLE_URL}/auth/device/token`, { method: 'POST', body: { grant_type: 'refresh_token', refresh_token: grant.refresh, client_id: CLIENT_ID } });
+  if (typeof result.json?.access_token !== 'string') {
+    const error = new Error(`OpenCode refused to refresh the login: ${describe(result)}`);
+    error.invalidGrant = result.json?.error === 'invalid_grant';
+    throw error;
+  }
+  return {
+    ...grant,
+    access: result.json.access_token,
+    refresh: result.json.refresh_token ?? grant.refresh,
+    expires: now + Math.max(0, Number(result.json.expires_in) || 0) * 1000,
+  };
+}
+
+/** A stored grant, or undefined for anything that is not one. */
+export function parseGrant(value) {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  let grant;
+  try { grant = JSON.parse(value); } catch { return undefined; }
+  const valid = grant?.version === GRANT_VERSION && typeof grant.access === 'string' && typeof grant.refresh === 'string'
+    && Number.isFinite(grant.expires) && typeof grant.api === 'string' && URL.canParse(grant.api) && typeof grant.orgID === 'string';
+  return valid ? grant : undefined;
+}
+
+/** The account facts safe to show: no token ever leaves through here. */
+export function grantSummary(grant, now = Date.now()) {
+  return { email: grant.email, orgName: grant.orgName, expiresInDays: Math.max(0, Math.round((grant.expires - now) / 86400000)) };
+}
+
+/**
+ * The grant as request auth, refreshed when it is about to expire. One refresh runs at a
+ * time per process; a refused refresh re-reads the store, because another DSCODE process
+ * may already have rotated the token.
+ */
+export class GrantSession {
+  /** @param store - `{ read(): Promise<string|undefined>, write(value): Promise<void> }` over the shared store. */
+  constructor(store, { fetch, now = () => Date.now() } = {}) {
+    this.store = store;
+    this.fetch = fetch;
+    this.now = now;
+    this.pending = undefined;
+  }
+
+  async current() {
+    return parseGrant(await this.store.read());
+  }
+
+  /** Request auth from the stored grant, or undefined when there is none. */
+  async auth() {
+    let grant = await this.current();
+    if (grant === undefined) return undefined;
+    if (grant.expires - this.now() < REFRESH_MARGIN_MS) grant = await this.refresh(grant);
+    return { apiKey: grant.access, baseURL: grant.api, headers: { 'x-opencode-org-id': grant.orgID } };
+  }
+
+  refresh(grant) {
+    this.pending ??= (async () => {
+      try {
+        const next = await refreshGrant(grant, { ...(this.fetch ? { fetch: this.fetch } : {}), now: this.now() });
+        await this.store.write(JSON.stringify(next));
+        return next;
+      } catch (error) {
+        const stored = await this.current();
+        if (stored !== undefined && stored.refresh !== grant.refresh && stored.expires - this.now() >= REFRESH_MARGIN_MS) return stored;
+        throw new LlmError(`OpenCode Go login ${error.invalidGrant ? 'expired or was revoked' : 'could not be refreshed'}; run /opencode login again`, 'AUTH', { cause: error });
+      } finally {
+        this.pending = undefined;
+      }
+    })();
+    return this.pending;
+  }
+}

package/plugins/opencode-go/search.mjs

@@ -0,0 +1,86 @@
+import { WebError } from '@deepseek-ai/dsh-web';
+
+// Web search for OpenCode Go sessions. Go has no search endpoint of its own; OpenCode's
+// client searches through Exa's hosted MCP server, which answers without an API key, and
+// DSCODE does the same so a Go session needs no DeepSeek or OpenRouter key to search.
+// `EXA_API_KEY`, when set, moves the calls onto that Exa account.
+export const EXA_SEARCH_ID = 'exa';
+export const EXA_MCP_URL = 'https://mcp.exa.ai/mcp';
+const DEFAULT_MAX_RESULTS = 8;
+const CONTEXT_CHARACTERS = 10_000;
+const SNIPPET_CHARACTERS = 1_000;
+const TIMEOUT_MS = 25_000;
+
+/** The JSON-RPC result text of an MCP answer, sent as one JSON body or as SSE `data:` lines. */
+export function mcpText(body) {
+  const payloads = [body.trim(), ...body.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trim())];
+  for (const payload of payloads) {
+    if (!payload.startsWith('{')) continue;
+    let parsed;
+    try { parsed = JSON.parse(payload); } catch { continue; }
+    if (parsed?.error) throw new WebError(`Exa search failed: ${typeof parsed.error.message === 'string' ? parsed.error.message : 'unknown error'}`, 'WEB_PROVIDER_ERROR');
+    const text = parsed?.result?.content?.find(item => typeof item?.text === 'string' && item.text.length > 0)?.text;
+    if (text !== undefined) return text;
+  }
+  return undefined;
+}
+
+/**
+ * Sources from Exa's text answer: `Title:`/`URL:`/`Highlights:` records separated by `---`.
+ * Records without a URL are dropped, and repeated URLs keep their first record.
+ */
+export function exaSources(text) {
+  const seen = new Set(), sources = [];
+  for (const record of text.split(/\n-{3,}\n/)) {
+    const url = record.match(/^URL:\s*(\S+)/m)?.[1];
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    const title = record.match(/^Title:\s*(.+)$/m)?.[1]?.trim();
+    const cut = record.search(/^(?:Highlights|Text|Summary):/m);
+    const snippet = cut < 0 ? '' : record.slice(record.indexOf(':', cut) + 1).replace(/\n\.\.\.\n/g, '\n').trim().slice(0, SNIPPET_CHARACTERS);
+    sources.push({ url, ...(title ? { title } : {}), ...(snippet ? { snippet } : {}) });
+  }
+  return sources;
+}
+
+/** Exa's `web_search_exa` tool over its hosted MCP endpoint. */
+export class ExaSearchProvider {
+  id = EXA_SEARCH_ID;
+
+  /** @param resolveOptions - `{ resolveApiKey(), userAgent, fetch? }` for the next search. */
+  constructor(resolveOptions) {
+    this.resolveOptions = resolveOptions;
+  }
+
+  available() {
+    return true;
+  }
+
+  async search(request, signal) {
+    const options = this.resolveOptions();
+    // An unreadable key store falls back to the keyless endpoint rather than failing the search.
+    const apiKey = await Promise.resolve(options.resolveApiKey?.()).catch(() => undefined);
+    const url = new URL(EXA_MCP_URL);
+    if (apiKey) url.searchParams.set('exaApiKey', apiKey);
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    let response, body;
+    try {
+      response = await (options.fetch ?? globalThis.fetch)(url, {
+        method: 'POST', redirect: 'error', signal: combined,
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(options.userAgent ? { 'user-agent': options.userAgent } : {}) },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'web_search_exa', arguments: {
+          query: request.query, type: 'auto', numResults: request.maxResults ?? DEFAULT_MAX_RESULTS, livecrawl: 'fallback', contextMaxCharacters: CONTEXT_CHARACTERS,
+        } } }),
+      });
+      body = await response.text();
+    } catch (error) {
+      if (signal?.aborted) throw new WebError('Exa search was cancelled', 'WEB_ABORTED', { cause: error ?? signal.reason });
+      if (timeout.aborted) throw new WebError(`Exa search timed out after ${TIMEOUT_MS / 1000}s`, 'WEB_PROVIDER_ERROR', { cause: error });
+      throw new WebError(`Exa search request failed: ${error instanceof Error ? error.message : String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error });
+    }
+    if (!response.ok) throw new WebError(`Exa search failed (HTTP ${response.status}): ${body.slice(0, 200)}`, 'WEB_PROVIDER_ERROR');
+    const text = mcpText(body);
+    return { sources: text === undefined ? [] : exaSources(text), truncated: false };
+  }
+}

package/plugins/opencode-go/usage.mjs

@@ -0,0 +1,119 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// What the OpenCode Go subscription has used. Go caps usage per rolling five hours, per week
+// and per month; the account's inference service answers all three at `<root>/go/v1/usage`
+// (the console's own proxy maps the public `/zen/go/v1/usage` there), with the account token
+// and `x-opencode-org-id` — without the org header it answers 403. Each window carries a used
+// percentage, `ok` or `rate-limited`, and when it resets.
+//
+// The endpoint is the console's own, not documented: every field is optional, and a shape
+// change degrades to "usage unavailable", never to a wrong number. The status line runs in
+// the terminal process, so the snapshot is also kept in DSH_HOME, as the Grok window is.
+
+/** OpenCode's own clients poll no faster; one read a minute is plenty for a five-hour window. */
+export const GO_USAGE_TTL_MS = 60_000;
+export const WINDOWS = Object.freeze(['rolling', 'weekly', 'monthly']);
+const FILE = 'opencode-go-usage.json';
+const VERSION = 1;
+let state;
+let fetchedAt = 0;
+let pending;
+let disk;
+
+/** The usage URL beside an account's chat endpoint (`…/go/openai/v1` → `…/go/v1/usage`), or undefined. */
+export function usageURL(api) {
+  if (typeof api !== 'string' || !URL.canParse(api)) return undefined;
+  const url = new URL(api);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (!/\/openai\/v1$/.test(path)) return undefined;
+  url.pathname = path.replace(/\/openai\/v1$/, '/v1/usage');
+  return url.href;
+}
+
+/** The three windows from one usage body, each with `percent`, `limited` and `resetsAt` when present. */
+export function parseGoUsage(body) {
+  const usage = {};
+  for (const name of WINDOWS) {
+    const window = body?.usage?.[name];
+    if (window === null || typeof window !== 'object') continue;
+    const percent = Number(window.percent);
+    const resetsAt = typeof window.resetsAt === 'string' && Number.isFinite(Date.parse(window.resetsAt)) ? window.resetsAt : undefined;
+    usage[name] = {
+      ...(Number.isFinite(percent) ? { percent: Math.min(100, Math.max(0, percent)) } : {}),
+      ...(window.status === 'rate-limited' ? { limited: true } : {}),
+      ...(resetsAt ? { resetsAt } : {}),
+    };
+  }
+  return usage;
+}
+
+/** One read with request auth from the grant session; undefined when it cannot be read. */
+export async function fetchGoUsage(auth, { fetch: fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  const url = usageURL(auth?.baseURL);
+  if (url === undefined || typeof fetchImpl !== 'function') return undefined;
+  try {
+    const response = await fetchImpl(url, { headers: { authorization: `Bearer ${auth.apiKey}`, accept: 'application/json', ...auth.headers } });
+    if (!response.ok) return undefined;
+    const usage = parseGoUsage(await response.json());
+    return Object.keys(usage).length === 0 ? undefined : { ...usage, fetchedAt: now };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Refresh at most once per interval, one read in flight; the last good snapshot survives a failed read. */
+export async function currentGoUsage({ home, resolveAuth, fetch, now = Date.now() } = {}) {
+  if (state !== undefined && now - fetchedAt < GO_USAGE_TTL_MS) return state;
+  if (pending) return pending;
+  pending = (async () => {
+    const auth = await Promise.resolve(resolveAuth?.()).catch(() => undefined);
+    if (auth === undefined) return state;
+    const next = await fetchGoUsage(auth, { ...(fetch ? { fetch } : {}), now });
+    if (next !== undefined) {
+      state = next;
+      fetchedAt = now;
+      if (home !== undefined) writeGoUsage(home, next);
+    }
+    return state;
+  })().finally(() => { pending = undefined; });
+  return pending;
+}
+
+/** The snapshot the status line renders: this process's own, else the file another process wrote. */
+export function goUsageNow(home = process.env.DSH_HOME, now = Date.now()) {
+  if (state !== undefined) return state;
+  if (home === undefined) return undefined;
+  if (disk !== undefined && disk.home === home && now - disk.at < GO_USAGE_TTL_MS) return disk.value;
+  let value;
+  try {
+    const cached = JSON.parse(readFileSync(join(home, FILE), 'utf8'));
+    if (cached?.version === VERSION) value = cached;
+  } catch { /* no snapshot yet */ }
+  disk = { home, at: now, value };
+  return value;
+}
+
+/** Atomic write of one snapshot; a failure leaves the previous file alone. */
+export function writeGoUsage(home, snapshot) {
+  try {
+    mkdirSync(home, { recursive: true });
+    const path = join(home, FILE);
+    writeFileSync(`${path}.tmp`, JSON.stringify({ version: VERSION, ...snapshot }));
+    renameSync(`${path}.tmp`, path);
+  } catch { /* the status line keeps its previous state */ }
+}
+
+/** Forget the snapshot, here and on disk: after signing out the status line shows no usage. */
+export function clearGoUsage(home) {
+  setGoUsage(undefined, 0);
+  if (home !== undefined) rmSync(join(home, FILE), { force: true });
+}
+
+/** Replace the in-memory snapshot; for tests. */
+export function setGoUsage(next, at = Date.now()) {
+  state = next;
+  fetchedAt = at;
+  pending = undefined;
+  disk = undefined;
+}

package/plugins/opencode-go/version.mjs

@@ -0,0 +1,10 @@
+import { readFileSync } from 'node:fs';
+
+/** The DSCODE version third-party services see; the package root is two levels up in a checkout and in the bundle. */
+export function dscodeVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return undefined;
+  }
+}

package/plugins/opencode-go/wire.mjs

@@ -0,0 +1,73 @@
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { serializeMessages } from '../openrouter/wire.mjs';
+import { ultraRequest } from '../ultra/policy.mjs';
+
+// OpenCode Go chat completions on the wire. Go forwards request fields to each model's
+// upstream, which rejects OpenRouter's extensions (`reasoning: {effort}`, `provider`,
+// `session_id`), so the body keeps to the OpenAI fields every upstream accepts. The SSE
+// stream is OpenAI's too, so the OpenRouter translation reads it unchanged.
+
+export const PROVIDER = 'opencode-go';
+/** `replayState.response.kind` for responses this adapter produced. */
+export const REPLAY_KIND = 'dscode-opencode-go';
+export const LABEL = 'OpenCode Go';
+const WIRE = Object.freeze({ off: 'none', low: 'low', high: 'high', max: 'max', ultra: 'max' });
+// DeepSeek rejects a thinking-mode tool-call turn replayed without `reasoning_content`.
+const REASONING_CONTENT_MODELS = /^deepseek-/;
+const DIALECT = Object.freeze({ provider: PROVIDER, reasoningContent: model => REASONING_CONTENT_MODELS.test(model) });
+
+/**
+ * Reasoning controls a model offers through this route.
+ * @param entry - the model's catalog entry, if any.
+ * @returns `{ levels, defaultEffort, wire }`, or undefined when the catalog does not describe the model.
+ */
+export function modelReasoning(entry) {
+  if (!entry?.efforts?.length) return undefined;
+  const levels = [...entry.efforts];
+  return { levels, defaultEffort: levels.includes('high') ? 'high' : levels[0], wire: Object.fromEntries(levels.map(level => [level, WIRE[level]])) };
+}
+
+/** A title needs no deliberation: reasoning off when the model allows it, else its lowest level. */
+function titleEffort(reasoning) {
+  return reasoning.levels[0];
+}
+
+/**
+ * The chat-completions body for one harness request.
+ * @param options - harness request (images already prepared into `images`).
+ * @param context - `{ entry, images }`: the model's catalog entry and prepared request images.
+ */
+export function requestBody(options, { entry, images } = {}) {
+  const reasoning = modelReasoning(entry);
+  const effort = options.purpose === 'session-title' && reasoning ? titleEffort(reasoning) : options.reasoningEffort;
+  const wireEffort = effort === undefined ? undefined : reasoning?.wire[effort];
+  if (effort !== undefined && reasoning !== undefined && wireEffort === undefined) {
+    throw new LlmError(`${LABEL} model "${options.model}" does not offer reasoning effort "${effort}"`, 'UNSUPPORTED_REASONING_EFFORT');
+  }
+  const messages = ultraRequest(options, serializeMessages(options.messages, { model: options.model, system: options.system, images, dialect: { ...DIALECT, provider: options.provider ?? PROVIDER } }));
+  // Delegation tools are offered at every effort; workflow and ralph never are.
+  const tools = (options.tools ?? []).filter(tool => tool.name !== 'workflow' && tool.name !== 'ralph')
+    .map(tool => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } }));
+  return {
+    model: options.model,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+    ...(tools.length > 0 ? { tools } : {}),
+    ...(wireEffort !== undefined ? { reasoning_effort: wireEffort } : {}),
+    ...(options.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {}),
+    ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    ...(options.stop !== undefined ? { stop: options.stop } : {}),
+  };
+}
+
+/**
+ * A clearer message for Go's account-side refusals, or the gateway's own text.
+ * The DeepSeek rows need the workspace's Global region, a setting only the user can change.
+ */
+export function explainError(message) {
+  if (typeof message === 'string' && /requires Global regions/i.test(message)) {
+    return `${message} (OpenCode console → your workspace → Privacy → select Global)`;
+  }
+  return message;
+}