@hystudio/dsh-quota-pill 0.2.6 → 0.2.11

package/src/adapters-opendesign.js

@@ -1,42 +1,69 @@
 /**
  * Open Design (open-design.ai) — Cloud coding-plan allowance.
  *
- * Optional provider. Unlike the others it does **not** read an API key: the
- * allowance lives in the cloud console's own API and is authenticated with the
- * console's session cookie. Set it once:
+ * Two ways in, in order:
+ *
+ *   1. **Control key** (preferred): `vela_ctrl_…` from an Open Design account
+ *      sign-in. It is accepted by the Bearer-only control-plane endpoints
+ *      `/billing/preflight` and `/wallet/balance`, alongside
+ *      `x-vela-workspace-id`. This is the same credential the Open Design CLI
+ *      (`vela login`) and the magpie/OpenCode provider use.
+ *   2. **Console session cookie** (fallback): `__Secure-better-auth.session_token`
+ *      from the Cloud console; it can read the browser-session-only
+ *      `/billing/coding-plan-usage` route.
+ *
+ * Configure one of:
  *
  *   ~/.dsh/.credentials.yaml
  *     refs:
+ *       OPENDESIGN_CONTROL_KEY: vela_ctrl_…
+ *       OPENDESIGN_WORKSPACE_ID: br542…
+ *       # or
  *       OPENDESIGN_SESSION_COOKIE: <__Secure-better-auth.session_token value>
  *
- * To get that value: open https://open-design.ai/cloud/dashboard while signed in,
- * then in the browser's devtools read the `__Secure-better-auth.session_token`
- * cookie (it is HttpOnly, so `document.cookie` will not show it).
+ * The workspace id is optional when a control key is set: the adapter resolves
+ * it through `/workspaces/current`.
  *
  * Two traps, both verified:
  *   · The inference gateway at amr-link.open-design.ai/v1 has NO balance
  *     endpoint — it is a chat proxy only. Probing it for quota always 404s.
  *   · amr-api sits behind Cloudflare, which rejects Node's TLS fingerprint with
- *     `error code: 1010`. The request therefore goes through system curl.
- *     That is the same request over a different TLS stack, not an auth bypass.
+ *     `error code: 1010`. Requests therefore go through system curl. That is
+ *     the same request over a different TLS stack, not an auth bypass.
+ *
+ * The control-plane endpoint accepts only the control key; an inference
+ * `sk-amr-…` API key is a different credential and returns 401 here.
  */
-import { readRef } from './credentials.js';
+import { readRef, readFirstRef } from './credentials.js';
 import { getJsonViaCurl } from './http.js';
 
 const API = process.env.OPENDESIGN_API_BASE || 'https://amr-api.open-design.ai/api/v1';
+const ORIGIN = 'https://open-design.ai';
+const CONTROL_REFS = ['OPENDESIGN_CONTROL_KEY', 'VELA_CONTROL_KEY'];
+const WORKSPACE_REFS = ['OPENDESIGN_WORKSPACE_ID', 'VELA_WORKSPACE_ID', 'OPENDESIGN_WORKSPACE'];
+const COOKIE_REF = 'OPENDESIGN_SESSION_COOKIE';
 
 const round2 = (n) => Math.round(n * 100) / 100;
 
-function headers(cookie) {
+/** Headers both control-plane reads need. */
+function controlHeaders(workspaceId) {
+  return {
+    'x-vela-workspace-id': workspaceId,
+    Origin: ORIGIN,
+    Referer: ORIGIN + '/',
+  };
+}
+
+function cookieHeaders(cookie) {
   return {
     Cookie: '__Secure-better-auth.session_token=' + cookie,
-    Origin: 'https://open-design.ai',
-    Referer: 'https://open-design.ai/',
+    Origin: ORIGIN,
+    Referer: ORIGIN + '/',
   };
 }
 
 /** Window label from its length: 18000s is the 5h cap, 604800s the weekly one. */
-function windowKey(seconds) {
+export function windowKey(seconds) {
   const s = Number(seconds) || 0;
   if (s > 0 && s <= 6 * 3600) return '5h';
   if (s > 0 && s <= 8 * 86400) return 'weekly';
@@ -45,50 +72,151 @@ function windowKey(seconds) {
 }
 
 /**
- * The workspace id is discoverable, so the user only supplies a cookie.
- * `/workspaces/current` already resolves to the default workspace.
+ * The workspace whose allowance is shown. A control key can resolve its own
+ * active workspace; an explicit ref wins when the account has more than one.
  */
-async function currentWorkspace(cookie) {
-  const res = await getJsonViaCurl(`${API}/workspaces/current`, { headers: headers(cookie) });
+async function workspaceForControl(controlKey) {
+  const configured = readFirstRef(WORKSPACE_REFS);
+  if (configured) return { id: configured };
+  const res = await getJsonViaCurl(API + '/workspaces/current', {
+    token: controlKey,
+    headers: { Origin: ORIGIN, Referer: ORIGIN + '/' },
+  });
   if (!res.ok) return { error: res.error };
-  const id = res.data && res.data.workspaceId;
-  return id ? { id } : { error: 'no workspaceId in response' };
+  const body = res.data || {};
+  const id = body.activeWorkspaceId || body.workspaceId;
+  return id ? { id } : { error: 'no activeWorkspaceId in /workspaces/current' };
 }
 
-export async function opendesign() {
-  const cookie = readRef('OPENDESIGN_SESSION_COOKIE');
-  if (!cookie) {
+/**
+ * Turn the control-plane preflight's `codingPlan.windows` into the pill's
+ * window rows. The preflight reports **used** credits; the pill renders
+ * **remaining** percent, so the conversion happens once here.
+ */
+export function preflightWindows(body) {
+  const plan = body && body.codingPlan;
+  const out = [];
+  for (const w of (plan && plan.windows) || []) {
+    const limit = Number(w.limitCredits);
+    const used = Number(w.usedCredits);
+    if (!Number.isFinite(limit) || limit <= 0 || !Number.isFinite(used)) continue;
+    const remain = Math.max(0, limit - used);
+    out.push({
+      key: windowKey(w.durationSeconds),
+      remainPct: round2((remain / limit) * 100),
+      resetAt: w.resetsAt || null,
+      credits: { remain: round2(remain), total: round2(limit), unit: 'credits' },
+    });
+  }
+  return out;
+}
+
+/** Shared result shape for both credential paths (and the tests). */
+export function shapeReading({ windows, balanceUsd, tier = null, source }) {
+  if (windows.length) {
+    const tight = windows.reduce((a, b) => (a.remainPct <= b.remainPct ? a : b));
+    const ORDER = { '5h': 0, weekly: 1, monthly: 2, 'credits-all': 3 };
+    windows.sort((a, b) => (ORDER[a.key] ?? 9) - (ORDER[b.key] ?? 9));
+    const products = {};
+    for (const w of windows) products[w.key] = round2(100 - w.remainPct);
     return {
-      kind: 'none',
+      kind: 'subscription-quota',
       provider: 'opendesign',
-      error: 'no OPENDESIGN_SESSION_COOKIE in ~/.dsh/.credentials.yaml',
-      setup: {
-        kind: 'session-cookie',
-        ref: 'OPENDESIGN_SESSION_COOKIE',
-        hint: 'Copy the __Secure-better-auth.session_token cookie from the Open Design cloud dashboard.',
-      },
+      account: tier || null,
+      remainingPct: tight.remainPct,
+      usedPct: round2(100 - tight.remainPct),
+      window: tight.key,
+      resetAt: tight.resetAt,
+      products,
+      windows,
+      raw: { source, tier },
     };
   }
 
-  const ws = await currentWorkspace(cookie);
+  const balance = Number(balanceUsd);
+  if (Number.isFinite(balance)) {
+    return {
+      kind: 'payg',
+      provider: 'opendesign',
+      account: tier || null,
+      note: 'wallet balance $' + balance.toFixed(2),
+      remainingPct: null,
+      usedPct: null,
+      credits: { remain: round2(balance), total: null, unit: 'USD' },
+      raw: { source, tier },
+    };
+  }
+
+  return {
+    kind: 'none',
+    provider: 'opendesign',
+    error: source + ' returned no allowance windows and no wallet balance',
+  };
+}
+
+/** Control key: Bearer-only `/billing/preflight` plus the wallet balance. */
+async function readWithControl(controlKey) {
+  const ws = await workspaceForControl(controlKey);
   if (ws.error) {
     return {
       kind: 'probe-failed',
       provider: 'opendesign',
-      error: `workspace lookup failed: ${ws.error}`,
+      error: 'workspace lookup failed: ' + ws.error,
+      hint: 'A Control Key (vela_ctrl_…) is required; an inference sk-amr-… key cannot read the control plane.',
+    };
+  }
+
+  const res = await getJsonViaCurl(
+    API + '/workspaces/' + encodeURIComponent(ws.id) + '/billing/preflight',
+    { token: controlKey, headers: controlHeaders(ws.id), timeoutMs: 25000 },
+  );
+  if (!res.ok) {
+    const denied = res.status === 401 || res.status === 403;
+    return {
+      kind: 'probe-failed',
+      provider: 'opendesign',
+      error: 'billing/preflight failed: ' + res.error,
+      hint: denied
+        ? 'The Control Key is invalid, expired, or not allowed to read this workspace.'
+        : undefined,
+    };
+  }
+
+  const body = res.data || {};
+  const plan = body.codingPlan || null;
+  return shapeReading({
+    windows: preflightWindows(body),
+    balanceUsd: body.balanceUsd ?? (plan && plan.balanceUsd),
+    tier: (plan && (plan.tier || plan.membershipTier)) || body.tier || null,
+    source: 'billing/preflight (control key)',
+  });
+}
+
+/** Console session cookie: browser-session-only `/billing/coding-plan-usage`. */
+async function readWithCookie(cookie) {
+  const wsRes = await getJsonViaCurl(API + '/workspaces/current', { headers: cookieHeaders(cookie) });
+  if (!wsRes.ok) {
+    return {
+      kind: 'probe-failed',
+      provider: 'opendesign',
+      error: 'workspace lookup failed: ' + wsRes.error,
       hint: 'The console session cookie has probably expired — copy a fresh one.',
     };
   }
+  const id = (wsRes.data && (wsRes.data.activeWorkspaceId || wsRes.data.workspaceId));
+  if (!id) {
+    return { kind: 'probe-failed', provider: 'opendesign', error: 'no workspaceId in /workspaces/current' };
+  }
 
   const res = await getJsonViaCurl(
-    `${API}/workspaces/${ws.id}/billing/coding-plan-usage`,
-    { headers: headers(cookie), timeoutMs: 25000 },
+    API + '/workspaces/' + encodeURIComponent(id) + '/billing/coding-plan-usage',
+    { headers: cookieHeaders(cookie), timeoutMs: 25000 },
   );
   if (!res.ok) {
     return {
       kind: 'probe-failed',
       provider: 'opendesign',
-      error: `coding-plan-usage failed: ${res.error}`,
+      error: 'coding-plan-usage failed: ' + res.error,
       hint: res.error && res.error.includes('40')
         ? 'The console session cookie has probably expired — copy a fresh one.'
         : undefined,
@@ -108,34 +236,48 @@ export async function opendesign() {
       credits: { remain: round2(remain), total: round2(limit), unit: 'credits' },
     });
   }
+  return shapeReading({
+    windows,
+    balanceUsd: body.balanceUsd,
+    tier: body.tier || null,
+    source: 'coding-plan-usage (console session)',
+  });
+}
 
-  if (!windows.length) {
-    return {
-      kind: 'none',
-      provider: 'opendesign',
-      error: `coding-plan-usage returned no windows (tier ${body.tier || 'unknown'})`,
-    };
+export async function opendesign() {
+  const controlKey = readFirstRef(CONTROL_REFS);
+  const cookie = readRef(COOKIE_REF);
+
+  let controlResult = null;
+  if (controlKey) {
+    controlResult = await readWithControl(controlKey);
+    if (controlResult.kind === 'subscription-quota' || controlResult.kind === 'payg') {
+      return controlResult;
+    }
   }
 
-  // The tightest window is what blocks the next request, but the list itself
-  // stays in canonical order (5h before weekly) so rows match every other
-  // provider instead of reshuffling as the numbers move.
-  const tight = windows.reduce((a, b) => (a.remainPct <= b.remainPct ? a : b));
-  const ORDER = { '5h': 0, weekly: 1, monthly: 2, 'credits-all': 3 };
-  windows.sort((a, b) => (ORDER[a.key] ?? 9) - (ORDER[b.key] ?? 9));
-  const products = {};
-  for (const w of windows) products[w.key] = round2(100 - w.remainPct);
+  if (cookie) {
+    const cookieResult = await readWithCookie(cookie);
+    if (cookieResult.kind === 'subscription-quota' || cookieResult.kind === 'payg') {
+      return cookieResult;
+    }
+    return controlResult || cookieResult;
+  }
+
+  if (controlResult) return controlResult;
 
   return {
-    kind: 'subscription-quota',
+    kind: 'none',
     provider: 'opendesign',
-    account: body.tier || null,
-    remainingPct: tight.remainPct,
-    usedPct: round2(100 - tight.remainPct),
-    window: tight.key,
-    resetAt: tight.resetAt,
-    products,
-    windows,
-    raw: { source: 'coding-plan-usage (console session)', tier: body.tier },
+    error: 'no OPENDESIGN_CONTROL_KEY (or VELA_CONTROL_KEY) and no OPENDESIGN_SESSION_COOKIE in ~/.dsh/.credentials.yaml',
+    setup: {
+      kind: 'control-key',
+      ref: 'OPENDESIGN_CONTROL_KEY',
+      refs: CONTROL_REFS,
+      workspaceRefs: WORKSPACE_REFS,
+      cookieRef: COOKIE_REF,
+      hint: 'Add the Control Key from an Open Design account sign-in (vela_ctrl_…); '
+        + 'a console session cookie also works as a fallback.',
+    },
   };
 }

package/src/autostart.js

@@ -0,0 +1,64 @@
+/**
+ * Start the sidecar as soon as the DSH host plugin loads.
+ *
+ * The pill is useless without the sidecar, and asking a fresh user to install a
+ * launchd/systemd unit before they see any quota is the opposite of out-of-box.
+ * The host half therefore spawns the bundled server when nothing is listening
+ * on the port.
+ *
+ * - If a sidecar is already running (launchd, systemd, a previous DSH launch),
+ *   the port check makes this a no-op instead of a duplicate.
+ * - The child is detached so it survives a DSH window reload and can serve the
+ *   next launch too. QUOTA_PILL_NO_AUTOSTART=1 opts out (service managers).
+ * - Electron's executable is not Node; ELECTRON_RUN_AS_NODE=1 turns it into one.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_PORT = 8319;
+const SERVER = fileURLToPath(new URL('../bin/quota-pill-server.js', import.meta.url));
+
+export function sidecarPort() {
+  const port = Number(process.env.QUOTA_PILL_PORT || DEFAULT_PORT);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_PORT;
+}
+
+/** True when something (healthy or not) is already listening. */
+export function isPortOpen(port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    // A port that accepts TCP but never speaks still means "do not start a
+    // second copy"; the health endpoint is the client's job.
+    socket.setTimeout(timeoutMs, () => done(true));
+  });
+}
+
+export async function ensureSidecar({ port = sidecarPort(), server = SERVER, env = process.env } = {}) {
+  if (env.QUOTA_PILL_NO_AUTOSTART === '1' || env.QUOTA_PILL_NO_AUTOSTART === 'true') return null;
+  if (!fs.existsSync(server)) return null;
+  if (await isPortOpen(port)) return null;
+
+  const childEnv = { ...env, QUOTA_PILL_PORT: String(port) };
+  if (process.versions.electron && !childEnv.ELECTRON_RUN_AS_NODE) {
+    childEnv.ELECTRON_RUN_AS_NODE = '1';
+  }
+  const child = spawn(process.execPath, [server], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    env: childEnv,
+  });
+  child.unref();
+  return child;
+}

package/src/credentials.js

@@ -82,14 +82,33 @@ function unquote(v) {
   return v;
 }
 
+/** Pick the first present, non-empty ref from an ordered list. */
+export function pickFirstRef(refs, names) {
+  for (const name of names || []) {
+    const v = refs && refs[name];
+    if (typeof v === 'string' && v) return v;
+  }
+  return null;
+}
+
 /** Read one DSH credential ref. Returns null when absent. */
 export function readRef(name) {
+  return readFirstRef([name]);
+}
+
+/**
+ * Read the first of several acceptable credential refs.
+ *
+ * DSH names a provider's key after its configured `apiKeyEnv` (for example
+ * `COMMANDCODE_GOAT_API_KEY`), while older docs and other setups used the
+ * short provider name. Accepting both keeps a key the user already has
+ * visible instead of reporting the provider as unconfigured.
+ */
+export function readFirstRef(names) {
   try {
     const text = fs.readFileSync(CREDENTIALS_FILE, 'utf8');
     const doc = parseCredentialsYaml(text);
-    const refs = doc.refs || {};
-    const v = refs[name];
-    return typeof v === 'string' && v ? v : null;
+    return pickFirstRef(doc.refs || {}, names);
   } catch {
     return null;
   }
@@ -149,17 +168,49 @@ export function hasCliProxy() {
   }
 }
 
+/** Credential sources contributed by user adapters, keyed by provider id. */
+const userCredentialSources = new Map();
+
+export function registerCredentialSource(provider, source) {
+  if (provider && source) userCredentialSources.set(String(provider), source);
+}
+
+export function clearUserCredentialSources() {
+  userCredentialSources.clear();
+}
+
 /** Where a given provider's credentials come from, for the setup docs / AGENTS.md. */
 export function credentialSource(provider) {
+  const fromAdapter = userCredentialSources.get(provider);
+  if (fromAdapter) return fromAdapter;
   if (provider === 'xai' || provider === 'codex' || provider === 'agy') {
-    return { kind: 'cli-proxy', dir: CLI_PROXY_DIR, ref: null };
+    return { kind: 'cli-proxy', dir: CLI_PROXY_DIR, ref: null, refs: [] };
+  }
+  if (provider === 'deepseek') {
+    // The official account is read through DSH's own Platform sign-in; there is
+    // no credential the user can add to this file.
+    return { kind: 'dsh-account', dir: null, ref: null, refs: [] };
+  }
+  if (provider === 'opendesign') {
+    // The quota control plane authenticates with a Control Key (vela_ctrl_…);
+    // a console session cookie is a fallback. The inference sk-amr-… key is a
+    // different credential and cannot read it.
+    return {
+      kind: 'control-key',
+      dir: null,
+      ref: 'OPENDESIGN_CONTROL_KEY',
+      refs: ['OPENDESIGN_CONTROL_KEY', 'VELA_CONTROL_KEY'],
+      workspaceRefs: ['OPENDESIGN_WORKSPACE_ID', 'VELA_WORKSPACE_ID'],
+      cookieRef: 'OPENDESIGN_SESSION_COOKIE',
+    };
   }
-  const refByProvider = {
-    kimi: 'KIMI_CODING_API_KEY',
-    commandcode: 'COMMANDCODE_API_KEY',
-    opencode: 'OPENCODE_GO_API_KEY',
+  const refsByProvider = {
+    kimi: ['KIMI_CODING_API_KEY'],
+    commandcode: ['COMMANDCODE_API_KEY', 'COMMANDCODE_GOAT_API_KEY'],
+    opencode: ['OPENCODE_GO_API_KEY'],
   };
-  return { kind: 'api-key', dir: null, ref: refByProvider[provider] || null };
+  const refs = refsByProvider[provider] || [];
+  return { kind: 'api-key', dir: null, ref: refs[0] || null, refs };
 }
 
 /**

package/src/http.js

@@ -67,6 +67,51 @@ export function getJsonViaCurl(url, { token, headers = {}, timeoutMs = DEFAULT_T
   });
 }
 
+/** POST JSON through the system curl (device authorization, control-plane calls). */
+export function postJsonViaCurl(url, body, { token, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const args = [
+    '-sS',
+    '--max-time', String(Math.ceil(timeoutMs / 1000)),
+    '-H', 'Accept: application/json',
+    '-H', 'Content-Type: application/json',
+    '-w', '\n%{http_code}',
+  ];
+  if (!proxyUrl()) args.push('--noproxy', '*');
+  if (token) args.push('-H', 'Authorization: Bearer ' + token);
+  if (proxyUrl()) args.push('--proxy', proxyUrl());
+  for (const [k, v] of Object.entries(headers)) {
+    if (v != null && v !== '') args.push('-H', `${k}: ${v}`);
+  }
+  args.push('--data', JSON.stringify(body ?? {}));
+  args.push(url);
+
+  return new Promise((resolve) => {
+    execFile('curl', args, { maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+      if (err && !stdout) {
+        resolve({ ok: false, error: String(err.message || err) });
+        return;
+      }
+      const text = String(stdout || '');
+      const cut = text.lastIndexOf('\n');
+      if (cut < 0) {
+        resolve({ ok: false, error: 'empty response' });
+        return;
+      }
+      const responseBody = text.slice(0, cut);
+      const status = Number(text.slice(cut + 1).trim());
+      if (status < 200 || status >= 300) {
+        resolve({ ok: false, status, error: `http ${status}: ${responseBody.slice(0, 160)}` });
+        return;
+      }
+      try {
+        resolve({ ok: true, status, data: JSON.parse(responseBody) });
+      } catch {
+        resolve({ ok: false, status, error: 'unparsable json: ' + responseBody.slice(0, 120) });
+      }
+    });
+  });
+}
+
 /** GET JSON with fetch. Cheaper; fine for upstreams without TLS fingerprinting. */
 export async function getJson(url, { token, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const controller = new AbortController();

package/src/opendesign-auth.js

@@ -0,0 +1,95 @@
+/**
+ * Open Design account sign-in — the device authorization `vela login` runs.
+ *
+ * The control plane (https://amr-api.open-design.ai) issues two keys:
+ *   · control key (`vela_ctrl_…`) — plan, wallet, Design Plan allowance
+ *   · runtime key (`sk-amr-…`)   — model requests at amr-link
+ *
+ * The quota pill only needs the control key. The CLI flow is:
+ *   POST /api/v1/cli/device-authorizations      → deviceId, deviceSecret, code, activation URL
+ *   user approves the URL in a signed-in browser
+ *   POST /api/v1/cli/device-authorizations/:id/token { deviceSecret } → the keys
+ */
+import os from 'node:os';
+import { getJsonViaCurl, postJsonViaCurl } from './http.js';
+
+export const CONTROL_ORIGIN = 'https://amr-api.open-design.ai';
+export const CONTROL_API = CONTROL_ORIGIN + '/api/v1';
+const CLI_VERSION = '0.1.4';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function headers(extra = {}) {
+  return { Origin: 'https://open-design.ai', Referer: 'https://open-design.ai/', ...extra };
+}
+
+export async function startDevice() {
+  const res = await postJsonViaCurl(CONTROL_API + '/cli/device-authorizations', {
+    cliVersion: CLI_VERSION,
+    host: os.hostname() || 'dsh',
+    profile: 'prod',
+  }, { headers: headers() });
+  if (!res.ok) throw new Error('device authorization failed: ' + res.error);
+  const d = res.data || {};
+  if (!d.deviceId || !d.deviceSecret) {
+    throw new Error('device authorization response is missing deviceId/deviceSecret');
+  }
+  return {
+    deviceId: String(d.deviceId),
+    deviceSecret: String(d.deviceSecret),
+    userCode: d.userCode ? String(d.userCode) : '',
+    activationUrl: d.activationUrl ? String(d.activationUrl) : '',
+    intervalSeconds: Number(d.pollIntervalSeconds) > 0 ? Number(d.pollIntervalSeconds) : 2,
+    expiresAt: Date.parse(d.expiresAt || '') || Date.now() + 10 * 60_000,
+  };
+}
+
+export async function waitForDevice(device, { onPending } = {}) {
+  for (;;) {
+    if (Date.now() > device.expiresAt) {
+      throw new Error('the device code expired before it was approved');
+    }
+    await sleep((device.intervalSeconds || 2) * 1000);
+    const res = await postJsonViaCurl(
+      CONTROL_API + '/cli/device-authorizations/' + encodeURIComponent(device.deviceId) + '/token',
+      { deviceSecret: device.deviceSecret },
+      { headers: headers() },
+    );
+    if (res.ok && res.data && res.data.controlKey && res.data.runtimeKey) {
+      return {
+        controlKey: String(res.data.controlKey),
+        runtimeKey: String(res.data.runtimeKey),
+        email: res.data.user && res.data.user.email ? String(res.data.user.email) : null,
+      };
+    }
+    const status = String((res.data && res.data.status) || '').toLowerCase();
+    if (status === 'expired' || status === 'denied' || status === 'cancelled' || status === 'canceled' || status === 'rejected') {
+      throw new Error('the device authorization was ' + status);
+    }
+    if (res.status === 401 && /invalid_device_secret/.test(String((res.data && res.data.error) || ''))) {
+      throw new Error('the device code is no longer valid');
+    }
+    if (onPending) onPending(status || 'pending');
+  }
+}
+
+/** The workspace whose allowance is shown. Explicit ref wins; otherwise ask. */
+export async function workspaceOf(controlKey) {
+  const res = await getJsonViaCurl(CONTROL_API + '/workspaces/current', {
+    token: controlKey,
+    headers: headers(),
+  });
+  if (!res.ok) throw new Error('workspace lookup failed: ' + res.error);
+  const body = res.data || {};
+  const id = body.activeWorkspaceId || body.workspaceId;
+  if (!id) throw new Error('the account has no active workspace');
+  return String(id);
+}
+
+/** Run the full device login. `onDevice` receives the URL/code to show the user. */
+export async function loginOpenDesign({ onDevice, onPending } = {}) {
+  const device = await startDevice();
+  if (onDevice) onDevice(device);
+  const keys = await waitForDevice(device, { onPending });
+  const workspaceId = await workspaceOf(keys.controlKey);
+  return { ...keys, workspaceId };
+}