dsh-multi-provider-usage 0.7.1 → 0.7.3

package/lib/index.js

@@ -698,7 +698,19 @@ function renderUsageText(data, lang) {
 		} else if (provider.meta?.balanceMissing === true) {
 			lines.push(zh ? "    订阅外充值余额: 无充值额度" : "    Top-up balance: no top-up credits");
 		} else if (typeof provider.meta?.balanceError === "string" && provider.meta.balanceError !== "") {
-			if (/no console credential/i.test(provider.meta.balanceError)) {
+			// Each fixable setup state names its fix explicitly; the regex
+			// fallback keeps older host payloads (which carry only the message)
+			// working.
+			const setup = typeof provider.meta.balanceSetup === "string" ? provider.meta.balanceSetup : "";
+			if (setup === "api-key") {
+				lines.push(zh
+					? "    订阅外充值余额: 本机是 API Key 登录，不含余额 — 运行 opencode auth login 并选择 OpenCode Console 账号"
+					: "    Top-up balance: the local login is an API key and carries no balance — run opencode auth login and choose the OpenCode Console account");
+			} else if (setup === "expired") {
+				lines.push(zh
+					? "    订阅外充值余额: 控制台登录已过期 — 重新运行 opencode auth login 后再刷新"
+					: "    Top-up balance: the console sign-in expired — run opencode auth login again and refresh");
+			} else if (/no console credential/i.test(provider.meta.balanceError)) {
 				lines.push(zh
 					? "    订阅外充值余额: 未配置 — 运行 opencode auth login 或设置 OPENCODE_CONSOLE_TOKEN"
 					: "    Top-up balance: not configured — run opencode auth login or set OPENCODE_CONSOLE_TOKEN");

package/lib/opencode-console.js

@@ -13,10 +13,18 @@
  * API key. This module resolves that token, in priority order:
  *
  *   1. a DSH credential ref (`opencodeConsoleApiKeyEnv`);
- *   2. OpenCode's `auth.json` (`~/.local/share/opencode/auth.json`, or
- *      `$XDG_DATA_HOME/opencode/auth.json`);
- *   3. OpenCode's local database (`opencode.db`, `credential` table), which is
- *      where current OpenCode releases keep the OAuth grant.
+ *   2. OpenCode's local database (`opencode.db`, `credential` table), which is
+ *      where current OpenCode releases keep the OAuth grant;
+ *   3. OpenCode's legacy `auth.json` (`~/.local/share/opencode/auth.json`, or
+ *      `$XDG_DATA_HOME/opencode/auth.json`).
+ *
+ * Older releases wrote `auth.json`; current releases migrated the grant into
+ * the database but often leave the old file behind. The database is therefore
+ * preferred, and every usable candidate is tried in turn: a stale
+ * `auth.json` token must not shadow the live database grant. API-key logins
+ * (`oc_sk_…`, method "API key (service account)") are reported as "not a
+ * console session" instead of being sent to the billing endpoint, which only
+ * answers 403 for them.
  *
  * Reading the local OpenCode store is optional and can be disabled with
  * `opencodeConsoleEnabled: false`. Values never leave the host process; the
@@ -25,9 +33,9 @@
  * and a runtime without it simply falls through to the auth file.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { isCredentialRefName, uniqueStrings } from "./util.js";
 
 /** Default credential ref for a manually supplied console token. */
@@ -35,12 +43,16 @@ export const DEFAULT_OPENCODE_CONSOLE_API_KEY_ENV = "OPENCODE_CONSOLE_TOKEN";
 /** Default OpenCode console origin. */
 export const DEFAULT_OPENCODE_CONSOLE_BASE_URL = "https://opencode.ai";
 
-/** A balance read failure with a stable code (no token in the message). */
+/**
+ * A balance read failure with a stable code (no token in the message).
+ * `status` carries the console HTTP status when there was one.
+ */
 export class ConsoleError extends Error {
-	constructor(code, message) {
+	constructor(code, message, status = null) {
 		super(message);
 		this.name = "ConsoleError";
 		this.code = code;
+		this.status = status;
 	}
 }
 
@@ -69,10 +81,47 @@ function expandHome(pathValue) {
 	return raw;
 }
 
+/**
+ * Normalize an `expires` value (OpenCode stores epoch milliseconds) to ms.
+ * Values below 10^10 are treated as seconds, defensively.
+ */
+function expiryMs(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+	return value < 10_000_000_000 ? value * 1000 : value;
+}
+
+/**
+ * Classify a stored token. Console OAuth access tokens are `st_…`; OpenCode
+ * service-account keys (the GO API-key login) are `oc_sk_…`. An explicit
+ * `type` wins; unknown shapes are treated as OAuth so a manually pasted
+ * console token still works.
+ */
+function tokenKind(token, type) {
+	const normalized = String(type ?? "").toLowerCase();
+	if (normalized === "key" || normalized === "api" || normalized === "api-key") return "api-key";
+	if (normalized === "oauth") return "oauth";
+	if (/^st_/.test(token)) return "oauth";
+	// Service-account keys (`oc_sk_…`) authenticate the API, not the console.
+	if (/^oc_sk_/.test(token)) return "api-key";
+	return "oauth";
+}
+
+/** Console metadata carried by an OpenCode credential grant. */
+function grantMetadata(entry) {
+	return {
+		orgId: typeof entry?.metadata?.orgID === "string" ? entry.metadata.orgID : "",
+		server: typeof entry?.metadata?.server === "string" ? entry.metadata.server : ""
+	};
+}
+
 /**
  * Read the console OAuth token from OpenCode's auth.json.
- * Only the `opencode` provider is a console grant; `opencode-go` is the GO API
- * key and returns 403 on the console billing endpoint.
+ * Only the `opencode` integration is a console grant; `opencode-go` is the GO
+ * API key and returns 403 on the console billing endpoint.
+ *
+ * Returns a candidate (with `kind`) or null. API-key entries are returned too,
+ * so the caller can explain that no console session exists instead of sending
+ * the key to an endpoint that only rejects it.
  */
 export function readOpencodeAuthJson(pathValue = "") {
 	const path = expandHome(pathValue) || defaultOpencodeAuthFile();
@@ -84,16 +133,26 @@ export function readOpencodeAuthJson(pathValue = "") {
 	}
 	const entry = parsed?.opencode;
 	if (entry === null || entry === undefined) return null;
-	const token = typeof entry === "string"
-		? entry
-		: typeof entry.access === "string" && entry.access.length > 0
-			? entry.access
-			: typeof entry.key === "string" && entry.key.length > 0 ? entry.key : null;
-	if (token === null) return null;
+	let token = null;
+	let type = null;
+	if (typeof entry === "string") {
+		token = entry.trim();
+	} else {
+		type = typeof entry.type === "string" ? entry.type : null;
+		if (typeof entry.access === "string" && entry.access.trim() !== "") {
+			token = entry.access.trim();
+		} else if (typeof entry.key === "string" && entry.key.trim() !== "") {
+			token = entry.key.trim();
+		}
+	}
+	if (token === null || token === "") return null;
+	const metadata = grantMetadata(entry);
 	return {
 		token,
-		orgId: typeof entry?.metadata?.orgID === "string" ? entry.metadata.orgID : "",
-		expires: typeof entry?.expires === "number" ? entry.expires : null,
+		kind: tokenKind(token, type),
+		orgId: metadata.orgId,
+		server: metadata.server,
+		expires: expiryMs(entry?.expires),
 		source: "opencode-auth-file",
 		path
 	};
@@ -113,14 +172,57 @@ function sqliteDatabase() {
 }
 
 /**
- * Read the console OAuth token from OpenCode's local SQLite database.
- * Returns null when node:sqlite is unavailable, the database is absent/locked,
- * or the schema does not contain an active `opencode` credential.
+ * The database file OpenCode uses.
+ *
+ * Explicit configuration wins; then `$OPENCODE_DB`; then the data directory's
+ * `opencode.db`, then a channel build (`opencode-beta.db`, `opencode-dev.db`,
+ * …). Current channels use the plain name, but a beta install stores a
+ * suffixed one and would otherwise look unauthenticated. A relative
+ * `$OPENCODE_DB` resolves against the search directory — the auth file's
+ * directory when `opencodeConsoleAuthFile` is set, else the data directory.
+ *
+ * @param {string} [pathValue] - explicit path (`opencodeConsoleDbFile`)
+ * @param {string} [fallbackDir] - directory to search when no path is set
  */
-export async function readOpencodeDbCredential(pathValue = "") {
-	const path = expandHome(pathValue) || defaultOpencodeDbFile();
+export function resolveOpencodeDbFile(pathValue = "", fallbackDir = "") {
+	const explicit = expandHome(pathValue);
+	if (explicit !== "") return explicit;
+	const dir = fallbackDir !== "" ? fallbackDir : opencodeDataDir();
+	const fromEnv = typeof process.env.OPENCODE_DB === "string" ? process.env.OPENCODE_DB.trim() : "";
+	if (fromEnv !== "" && fromEnv !== ":memory:") return isAbsolute(fromEnv) ? fromEnv : join(dir, fromEnv);
+	const preferred = join(dir, "opencode.db");
+	try {
+		statSync(preferred);
+		return preferred;
+	} catch {
+		// fall through to a channel build
+	}
+	try {
+		const found = readdirSync(dir)
+			.filter((name) => /^opencode(?:-[A-Za-z0-9._-]+)?\.db$/.test(name))
+			.map((name) => {
+				const path = join(dir, name);
+				return { path, at: statSync(path).mtimeMs };
+			})
+			.sort((a, b) => b.at - a.at);
+		if (found.length > 0) return found[0].path;
+	} catch {
+		// no data directory: the read below fails and falls through to auth.json
+	}
+	return preferred;
+}
+
+/**
+ * Read every console grant from OpenCode's local SQLite database.
+ * Returns [] when node:sqlite is unavailable, the database is absent/locked,
+ * or the schema does not contain an `opencode` credential.
+ *
+ * @returns {Promise<Array<{ token: string, kind: string, orgId: string, server: string, expires: number | null, source: string, path: string }>>}
+ */
+export async function readOpencodeDbCredentials(pathValue = "") {
+	const path = resolveOpencodeDbFile(pathValue);
 	const DatabaseSync = await sqliteDatabase();
-	if (DatabaseSync === null) return null;
+	if (DatabaseSync === null) return [];
 	let db;
 	try {
 		db = new DatabaseSync(path, { readOnly: true });
@@ -129,9 +231,28 @@ export async function readOpencodeDbCredential(pathValue = "") {
 		} catch {
 			// a busy timeout is best-effort; the query still gets one try
 		}
-		const rows = db.prepare(
-			"SELECT integration_id, value FROM credential WHERE active=1 AND integration_id IN ('opencode','opencode-go')"
-		).all();
+		// `active` and `time_created` were added over time; fall back to the
+		// plain table for very old databases. A query that runs is
+		// authoritative even when it returns no rows: an empty `active=1`
+		// result means logged out, not an old schema — the later queries
+		// drop the `active` filter and would resurrect a revoked grant.
+		const queries = [
+			"SELECT integration_id, value FROM credential WHERE active=1 AND integration_id='opencode' ORDER BY time_created DESC",
+			"SELECT integration_id, value FROM credential WHERE integration_id='opencode' ORDER BY time_created DESC",
+			"SELECT integration_id, value FROM credential WHERE integration_id='opencode'"
+		];
+		let rows = null;
+		for (const query of queries) {
+			try {
+				rows = db.prepare(query).all();
+				// the schema works; an empty result is the real answer
+				break;
+			} catch {
+				// try the next, older schema
+			}
+		}
+		if (rows === null) return [];
+		const credentials = [];
 		for (const row of rows) {
 			if (row?.integration_id !== "opencode" || typeof row.value !== "string") continue;
 			let grant;
@@ -140,20 +261,28 @@ export async function readOpencodeDbCredential(pathValue = "") {
 			} catch {
 				continue;
 			}
-			const token = typeof grant?.access === "string" && grant.access.length > 0
-				? grant.access
-				: typeof grant?.key === "string" && grant.key.length > 0 ? grant.key : null;
+			const type = typeof grant?.type === "string" ? grant.type : null;
+			let token = null;
+			if (typeof grant?.access === "string" && grant.access.trim() !== "") {
+				token = grant.access.trim();
+			} else if (typeof grant?.key === "string" && grant.key.trim() !== "") {
+				token = grant.key.trim();
+			}
 			if (token === null) continue;
-			return {
+			const metadata = grantMetadata(grant);
+			credentials.push({
 				token,
-				orgId: typeof grant?.metadata?.orgID === "string" ? grant.metadata.orgID : "",
-				expires: typeof grant?.expires === "number" ? grant.expires : null,
+				kind: tokenKind(token, type),
+				orgId: metadata.orgId,
+				server: metadata.server,
+				expires: expiryMs(grant?.expires),
 				source: "opencode-db",
 				path
-			};
+			});
 		}
+		return credentials;
 	} catch {
-		return null;
+		return [];
 	} finally {
 		try {
 			db?.close();
@@ -161,75 +290,119 @@ export async function readOpencodeDbCredential(pathValue = "") {
 			// closing an already-closed handle is harmless
 		}
 	}
-	return null;
+}
+
+/** First console grant from OpenCode's database (kept for compatibility). */
+export async function readOpencodeDbCredential(pathValue = "") {
+	const credentials = await readOpencodeDbCredentials(pathValue);
+	return credentials.find((credential) => credential.kind === "oauth") ?? credentials[0] ?? null;
 }
 
 /**
- * Resolve the console credential for a provider config.
+ * Every usable console credential for a provider config.
+ *
+ * The database comes before the legacy auth file on purpose: OpenCode writes
+ * rotated grants to the database, and an old auth.json token would otherwise
+ * produce a 401 and hide the live balance. Duplicate tokens are collapsed and
+ * OAuth sessions are returned separately from API-key logins.
  *
- * `apiKeyEnv` is tried first through DSH credentials; then the OpenCode auth
- * file and database. `orgId` from config overrides the metadata value.
  * @param {{
- *   config: { apiKeyEnv?: string, orgId?: string, authFile?: string, dbFile?: string },
+ *   config: { apiKeyEnv?: string, orgId?: string, authFile?: string, dbFile?: string, baseUrl?: string },
  *   resolveCredential: (refs: string[]) => Promise<{ ref: string, value: string } | null>,
  * }} input
+ * @returns {Promise<{
+ *   credentials: Array<{ token: string, kind: string, orgId: string, server: string, expires: number | null, source: string, path: string | null }>,
+ *   apiKey: { token: string, kind: string, orgId: string, server: string, expires: number | null, source: string, path: string | null } | null,
+ * }>}
  */
-export async function resolveOpencodeConsoleCredential(input) {
+export async function resolveOpencodeConsoleCredentials(input) {
 	const { config, resolveCredential } = input;
+	const explicitOrg = typeof config.orgId === "string" ? config.orgId.trim() : "";
+	const withOrg = (credential) => ({
+		...credential,
+		orgId: explicitOrg !== "" ? explicitOrg : credential.orgId
+	});
+
+	const candidates = [];
 	const refs = uniqueStrings([config.apiKeyEnv, DEFAULT_OPENCODE_CONSOLE_API_KEY_ENV]).filter(isCredentialRefName);
 	const credential = await resolveCredential(refs);
-	if (credential !== null) {
-		return {
-			token: credential.value,
-			orgId: typeof config.orgId === "string" ? config.orgId.trim() : "",
-			source: `credential:${credential.ref}`,
+	if (credential !== null && typeof credential.value === "string" && credential.value.trim() !== "") {
+		const token = credential.value.trim();
+		candidates.push(withOrg({
+			token,
+			kind: tokenKind(token, null),
+			orgId: "",
+			server: "",
 			expires: null,
+			source: `credential:${credential.ref}`,
 			path: null
-		};
+		}));
 	}
+
+	const authDir = typeof config.authFile === "string" && config.authFile.trim() !== ""
+		? dirname(expandHome(config.authFile))
+		: "";
+	const dbFile = resolveOpencodeDbFile(config.dbFile, authDir);
+	for (const stored of await readOpencodeDbCredentials(dbFile)) candidates.push(withOrg(stored));
+
 	const authFile = readOpencodeAuthJson(config.authFile);
-	if (authFile !== null) {
-		return {
-			...authFile,
-			orgId: typeof config.orgId === "string" && config.orgId.trim().length > 0 ? config.orgId.trim() : authFile.orgId
-		};
-	}
-	const dbFile = resolveDbPath(config);
-	const db = await readOpencodeDbCredential(dbFile);
-	if (db !== null) {
-		return {
-			...db,
-			orgId: typeof config.orgId === "string" && config.orgId.trim().length > 0 ? config.orgId.trim() : db.orgId
-		};
+	if (authFile !== null) candidates.push(withOrg(authFile));
+
+	const seen = new Set();
+	const unique = [];
+	for (const candidate of candidates) {
+		if (seen.has(candidate.token)) continue;
+		seen.add(candidate.token);
+		unique.push(candidate);
 	}
-	return null;
+	const credentials = unique.filter((candidate) => candidate.kind === "oauth");
+	const apiKey = unique.find((candidate) => candidate.kind !== "oauth") ?? null;
+	return { credentials, apiKey };
 }
 
-/** Derive the database path, preferring one next to an explicit auth file. */
-function resolveDbPath(config) {
-	const explicit = expandHome(config.dbFile);
-	if (explicit.length > 0) return explicit;
-	const authFile = expandHome(config.authFile);
-	if (authFile.length > 0) return join(dirname(authFile), "opencode.db");
-	return defaultOpencodeDbFile();
+/**
+ * Resolve the preferred console credential for a provider config.
+ * @param {{
+ *   config: { apiKeyEnv?: string, orgId?: string, authFile?: string, dbFile?: string, baseUrl?: string },
+ *   resolveCredential: (refs: string[]) => Promise<{ ref: string, value: string } | null>,
+ * }} input
+ */
+export async function resolveOpencodeConsoleCredential(input) {
+	const { credentials } = await resolveOpencodeConsoleCredentials(input);
+	return credentials[0] ?? null;
 }
 
 /**
  * Non-network detection report for the settings page.
- * @returns {Promise<{ enabled: boolean, configured: boolean, source: string | null, orgId: string | null, error: string | null }>}
+ * @returns {Promise<{ enabled: boolean, configured: boolean, source: string | null, orgId: string | null, error: string | null, reason: string | null, expired: boolean }>}
  */
 export async function opencodeConsoleStatus(input) {
 	const { config, resolveCredential } = input;
 	const enabled = config.enabled !== false;
-	if (!enabled) return { enabled: false, configured: false, source: null, orgId: null, error: null };
+	if (!enabled) return { enabled: false, configured: false, source: null, orgId: null, error: null, reason: null, expired: false };
 	try {
-		const credential = await resolveOpencodeConsoleCredential({ config, resolveCredential });
+		const resolved = await resolveOpencodeConsoleCredentials({ config, resolveCredential });
+		const credential = resolved.credentials[0] ?? null;
+		if (credential === null) {
+			return {
+				enabled: true,
+				configured: false,
+				source: null,
+				orgId: typeof config.orgId === "string" && config.orgId.trim() !== "" ? config.orgId.trim() : null,
+				error: null,
+				reason: resolved.apiKey === null ? null : "api-key",
+				expired: false
+			};
+		}
+		const expired = typeof credential.expires === "number" && credential.expires <= Date.now();
 		return {
 			enabled: true,
-			configured: credential !== null,
-			source: credential?.source ?? null,
-			orgId: credential?.orgId ?? (typeof config.orgId === "string" && config.orgId.trim().length > 0 ? config.orgId.trim() : null),
-			error: null
+			configured: true,
+			source: credential.source,
+			orgId: credential.orgId || (typeof config.orgId === "string" && config.orgId.trim() !== "" ? config.orgId.trim() : null),
+			error: null,
+			reason: expired ? "expired" : null,
+			expired
 		};
 	} catch (error) {
 		return {
@@ -237,7 +410,9 @@ export async function opencodeConsoleStatus(input) {
 			configured: false,
 			source: null,
 			orgId: null,
-			error: error instanceof Error ? error.message : String(error)
+			error: error instanceof Error ? error.message : String(error),
+			reason: null,
+			expired: false
 		};
 	}
 }
@@ -252,25 +427,29 @@ function finite(values) {
 }
 
 /**
- * Fetch the OpenCode console billing status and normalize the prepaid balance.
- *
- * `balanceMicroCents` and `availableMicroCents` are 1/100,000,000 USD.
- * @param {{
- *   config: { apiKeyEnv?: string, orgId?: string, authFile?: string, dbFile?: string, baseUrl?: string },
- *   resolveCredential: (refs: string[]) => Promise<{ ref: string, value: string } | null>,
- *   fetchImpl?: typeof fetch,
- * }} input
+ * The console origin for a credential: an explicit override wins, then the
+ * server recorded in the grant (`https://opencode.ai/console` or a
+ * self-hosted console), then the public default.
  */
-export async function readOpencodeBalance(input) {
-	const { config, resolveCredential, fetchImpl = fetch } = input;
-	const credential = await resolveOpencodeConsoleCredential({ config, resolveCredential });
-	if (credential === null) {
-		throw new ConsoleError(
-			"no-console-credential",
-			"OpenCode balance: no console credential (set OPENCODE_CONSOLE_TOKEN, or sign in with OpenCode)"
-		);
+function consoleBaseUrl(config, credential) {
+	const configured = typeof config.baseUrl === "string" ? config.baseUrl.trim().replace(/\/+$/, "") : "";
+	// The config carries the public default even when the user never touched it,
+	// so an explicit non-default override wins while the default still lets a
+	// self-hosted `metadata.server` grant pick its own origin.
+	if (configured !== "" && configured !== DEFAULT_OPENCODE_CONSOLE_BASE_URL) return configured;
+	const server = typeof credential.server === "string" && credential.server.trim() !== ""
+		? credential.server.trim()
+		: DEFAULT_OPENCODE_CONSOLE_BASE_URL;
+	try {
+		return new URL(server).origin;
+	} catch {
+		return DEFAULT_OPENCODE_CONSOLE_BASE_URL;
 	}
-	const baseUrl = String(config.baseUrl || DEFAULT_OPENCODE_CONSOLE_BASE_URL).replace(/\/+$/, "");
+}
+
+/** Fetch and normalize the billing status for one credential. */
+async function fetchOpencodeBalance(config, credential, fetchImpl) {
+	const baseUrl = consoleBaseUrl(config, credential);
 	const headers = {
 		Accept: "application/json",
 		Authorization: `Bearer ${credential.token}`
@@ -289,7 +468,14 @@ export async function readOpencodeBalance(input) {
 	}
 	if (!res.ok) {
 		const body = await res.text().catch(() => "");
-		throw new ConsoleError("http-error", `OpenCode balance ${res.status}: ${body.slice(0, 300)}`);
+		if (res.status === 401 || res.status === 403) {
+			throw new ConsoleError(
+				"console-unauthorized",
+				`OpenCode balance ${res.status}: the saved OpenCode Console session is expired or not a Console login — run \`opencode auth login\` again (or set OPENCODE_CONSOLE_TOKEN) [source: ${credential.source}]`,
+				res.status
+			);
+		}
+		throw new ConsoleError("http-error", `OpenCode balance ${res.status}: ${body.slice(0, 300)}`, res.status);
 	}
 	let payload;
 	try {
@@ -319,3 +505,52 @@ export async function readOpencodeBalance(input) {
 	};
 }
 
+/**
+ * Fetch the OpenCode console billing status and normalize the prepaid balance.
+ *
+ * `balanceMicroCents` and `availableMicroCents` are 1/100,000,000 USD.
+ *
+ * Every discovered OAuth session is tried (newest storage first); a stale
+ * legacy `auth.json` token therefore cannot hide a live database grant. At
+ * most four candidates are tried before the first authentication failure is
+ * reported. When only an API-key login exists, the error says so instead of
+ * forwarding the key to an endpoint that rejects it.
+ *
+ * @param {{
+ *   config: { apiKeyEnv?: string, orgId?: string, authFile?: string, dbFile?: string, baseUrl?: string },
+ *   resolveCredential: (refs: string[]) => Promise<{ ref: string, value: string } | null>,
+ *   fetchImpl?: typeof fetch,
+ * }} input
+ */
+export async function readOpencodeBalance(input) {
+	const { config, resolveCredential, fetchImpl = fetch } = input;
+	const { credentials, apiKey } = await resolveOpencodeConsoleCredentials({ config, resolveCredential });
+	if (credentials.length === 0) {
+		if (apiKey !== null) {
+			throw new ConsoleError(
+				"console-api-key",
+				"OpenCode balance: the local OpenCode login is an API key, not an OpenCode Console session — run `opencode auth login` and choose the OpenCode Console account (or set OPENCODE_CONSOLE_TOKEN)"
+			);
+		}
+		throw new ConsoleError(
+			"no-console-credential",
+			"OpenCode balance: no console credential (set OPENCODE_CONSOLE_TOKEN, or sign in with OpenCode)"
+		);
+	}
+	const failures = [];
+	for (const credential of credentials.slice(0, 4)) {
+		try {
+			return await fetchOpencodeBalance(config, credential, fetchImpl);
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			failures.push(failure);
+			const status = failure instanceof ConsoleError ? failure.status : null;
+			// Only an authentication failure is worth retrying on the next
+			// candidate. A network or schema failure is shared by all sources
+			// (and a retry would only multiply the wait).
+			if (status !== 401 && status !== 403) break;
+		}
+	}
+	const unauthorized = failures.find((failure) => failure instanceof ConsoleError && (failure.status === 401 || failure.status === 403));
+	throw unauthorized ?? failures[0];
+}

package/lib/opencode-session.js

@@ -78,7 +78,11 @@ export function patchFetch() {
 		const meta = sessionStore.getStore();
 		if (meta?.sessionId !== undefined) {
 			if (matchesBase(input, meta.base)) {
-				const headers = new Headers(init?.headers);
+				// When the caller passed a Request, its own headers are the base:
+				// per the fetch spec an `init.headers` would otherwise replace them
+				// wholesale and drop e.g. Authorization.
+				const base = init?.headers ?? (input !== null && typeof input === "object" && input.headers !== null && typeof input.headers === "object" ? input.headers : undefined);
+				const headers = new Headers(base);
 				if (!headers.has("x-opencode-session")) {
 					headers.set("x-opencode-session", String(meta.sessionId));
 					injectionCount += 1;

package/lib/providers.js

@@ -235,13 +235,26 @@ function startOpencodeBalance(consoleConfig, resolveCredential, fetchImpl) {
 		.catch((error) => ({ ok: false, error }));
 }
 
-/** Project a settled balance read into public result fields. */
+/**
+ * Project a settled balance read into public result fields.
+ *
+ * A failed read carries `balanceSetup` when the user can act on it (no console
+ * login, an API-key-only login, or an expired/revoked session); the widget
+ * turns that into a setup chip instead of a mute dash.
+ */
 function balanceFields(settled) {
-	if (settled === null) return { balance: null, balanceError: null };
-	if (settled.ok) return { balance: settled.balance, balanceError: null };
+	if (settled === null) return { balance: null, balanceError: null, balanceSetup: null };
+	if (settled.ok) return { balance: settled.balance, balanceError: null, balanceSetup: null };
+	const error = settled.error;
+	const code = error?.code;
 	return {
 		balance: null,
-		balanceError: settled.error instanceof Error ? settled.error.message : String(settled.error)
+		balanceError: error instanceof Error ? error.message : String(error),
+		balanceSetup: code === "no-console-credential"
+			? "no-credential"
+			: code === "console-api-key"
+				? "api-key"
+				: code === "console-unauthorized" ? "expired" : null
 	};
 }
 
@@ -253,7 +266,8 @@ function attachBalance(result, settled) {
 		balance: fields.balance,
 		meta: {
 			...(result.meta ?? {}),
-			...(fields.balanceError === null ? {} : { balanceError: fields.balanceError })
+			...(fields.balanceError === null ? {} : { balanceError: fields.balanceError }),
+			...(fields.balanceSetup === null ? {} : { balanceSetup: fields.balanceSetup })
 		}
 	};
 }
@@ -269,7 +283,11 @@ async function opencodeGoFailure(code, message, accountRef, probe, fallback, bal
 		account: { ref: accountRef, id: null, name: "" },
 		fallback,
 		balance: balance.balance,
-		meta: { opencodeGo: probe, ...(balance.balanceError === null ? {} : { balanceError: balance.balanceError }) }
+		meta: {
+			opencodeGo: probe,
+			...(balance.balanceError === null ? {} : { balanceError: balance.balanceError }),
+			...(balance.balanceSetup === null ? {} : { balanceSetup: balance.balanceSetup })
+		}
 	});
 }
 
@@ -899,4 +917,3 @@ export async function readGlm(input) {
 		account: { ref: credential.ref, id: null, name: "" }
 	});
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-multi-provider-usage",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "DSH (DeepSeek Harness) plugin: one collapsible sidebar widget for OpenCode GO, Command Code and GLM Code Plan quotas plus top-up balances, a periodic balance-change animation, automatic checkout and installed-package updates, same-origin usage proxies, a Plugins-panel settings page and a /provider-usage chat command (DSH 0.1.7+ and 0.2.0 compatible)",
   "type": "module",
   "main": "lib/index.js",