@hystudio/dsh-quota-pill 0.2.6 → 0.2.11

package/src/providers.js

@@ -0,0 +1,112 @@
+/**
+ * Adapter keys ↔ DSH provider/model ids.
+ *
+ * Two different namespaces meet here:
+ *   · DSH names providers after the upstream or the user's provider config
+ *     (`grok`, `commandcode-goat`, `opendesign-go`, `deepseek-account`,
+ *     `opencode-go`), and models carry that id as their prefix;
+ *   · adapters in this package use short historical keys (`xai`, `commandcode`,
+ *     `opendesign`, `deepseek`, `opencode`).
+ *
+ * A missing alias is invisible in the worst way: the provider is configured and
+ * readable, but the catalog filter drops it before any adapter runs. Keep these
+ * maps in one place and test them against a real catalog shape.
+ */
+
+/** Which DSH model prefixes map to which adapter. */
+export const PREFIX_ALIASES = {
+  'kimi-coding': 'kimi',
+  kimi: 'kimi',
+  'opencode-go': 'opencode',
+  opencode: 'opencode',
+  commandcode: 'commandcode',
+  'command-code': 'commandcode',
+  'commandcode-goat': 'commandcode',
+  xai: 'xai',
+  grok: 'xai',
+  codex: 'codex',
+  antigravity: 'agy',
+  agy: 'agy',
+  deepseek: 'deepseek',
+  'deepseek-account': 'deepseek',
+  opendesign: 'opendesign',
+  'opendesign-go': 'opendesign',
+};
+
+/**
+ * Which DSH catalog ids count as "this adapter".
+ *
+ * DSH names providers after the upstream (`antigravity`, `deepseek-account`,
+ * `opencode-go`); the adapters use the short keys the pill has always used.
+ */
+export const CATALOG_ALIASES = {
+  agy: ['antigravity', 'agy'],
+  deepseek: ['deepseek-account', 'deepseek'],
+  opencode: ['opencode-go', 'opencode'],
+  kimi: ['kimi-coding', 'kimi'],
+  // DSH ids follow the upstream/provider config name, not the short adapter
+  // key. Missing one of these hides a provider the user actually configured:
+  // grok (xAI), commandcode-goat (Command Code), opendesign-go (Open Design).
+  xai: ['xai', 'grok'],
+  codex: ['codex'],
+  commandcode: ['commandcode', 'commandcode-goat', 'command-code'],
+  opendesign: ['opendesign', 'opendesign-go'],
+};
+
+/**
+ * Providers contributed by the user's own adapters (~/.dsh/quota-pill/adapters).
+ * Kept separate from the built-in maps so a package update can re-register them
+ * from disk without ever rewriting the user's files.
+ */
+export const USER_PREFIX_ALIASES = {};
+export const USER_CATALOG_ALIASES = {};
+export const USER_DISPLAY_NAMES = {};
+
+export function clearUserProviders() {
+  for (const key of Object.keys(USER_PREFIX_ALIASES)) delete USER_PREFIX_ALIASES[key];
+  for (const key of Object.keys(USER_CATALOG_ALIASES)) delete USER_CATALOG_ALIASES[key];
+  for (const key of Object.keys(USER_DISPLAY_NAMES)) delete USER_DISPLAY_NAMES[key];
+}
+
+/** Register one user adapter's ids/name. Called on every adapter-dir reload. */
+export function registerUserProvider({ provider, catalogIds = [], prefixes = [], displayName } = {}) {
+  if (!provider) return;
+  const key = String(provider);
+  const ids = new Set([key, ...(Array.isArray(catalogIds) ? catalogIds : []), ...(Array.isArray(prefixes) ? prefixes : [])]);
+  for (const id of ids) {
+    if (!id) continue;
+    USER_PREFIX_ALIASES[String(id).toLowerCase()] = key;
+  }
+  USER_CATALOG_ALIASES[key] = Array.from(new Set([key, ...(USER_CATALOG_ALIASES[key] || []), ...(Array.isArray(catalogIds) ? catalogIds : [])]));
+  if (displayName) USER_DISPLAY_NAMES[key] = String(displayName);
+}
+
+export function providerForModel(model) {
+  const m = String(model || '').toLowerCase();
+  const prefix = m.split('/')[0];
+  // User adapters win: their catalog id is exactly what DSH uses for the model
+  // prefix, and the user added the adapter specifically for it.
+  if (USER_PREFIX_ALIASES[prefix]) return USER_PREFIX_ALIASES[prefix];
+  if (PREFIX_ALIASES[prefix]) return PREFIX_ALIASES[prefix];
+  // Fuzzy fallbacks for models whose prefix is not the provider id.
+  if (m.includes('grok')) return 'xai';
+  if (m.includes('codex') || m.startsWith('gpt-')) return 'codex';
+  if (m.includes('gemini')) return 'agy';
+  if (m.startsWith('k3') || m.startsWith('kimi')) return 'kimi';
+  return '';
+}
+
+export function inCatalog(provider, ids) {
+  if (!ids) return true; // catalog unknown: do not hide anything
+  const names = [
+    ...(CATALOG_ALIASES[provider] || []),
+    ...(USER_CATALOG_ALIASES[provider] || []),
+  ];
+  if (!names.length) names.push(provider);
+  return names.some((n) => ids.includes(n));
+}
+
+/** Display name for user adapters (built-ins keep their server-side table). */
+export function userDisplayName(provider) {
+  return USER_DISPLAY_NAMES[provider] || null;
+}

package/src/server.js

@@ -19,14 +19,19 @@
  * Every response includes `cached` and `at` so the client can tell a live
  * reading from a cached one.
  */
+import fs from 'node:fs';
 import http from 'node:http';
 import { kimi, opencode, commandcode } from './adapters-apikey.js';
 import { xai, codex, agy } from './adapters-cliproxy.js';
 import { deepseek } from './adapters-deepseek.js';
 import { credentialSource, hasCliProxy, CLI_PROXY_DIR, CREDENTIALS_FILE } from './credentials.js';
-import { catalogProviderIds } from './catalog.js';
+import { loadUserAdapters, adapterContext, userAdaptersInfo } from './user-adapters.js';
+import { catalogProviderIds, forgetCatalog } from './catalog.js';
 import { opendesign } from './adapters-opendesign.js';
+import { providerForModel, inCatalog } from './providers.js';
 
+const PKG = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const VERSION = PKG.version;
 const PORT = Number(process.env.QUOTA_PILL_PORT || 8319);
 const HOST = process.env.QUOTA_PILL_HOST || '127.0.0.1';
 const CACHE_TTL_MS = Number(process.env.QUOTA_PILL_CACHE_TTL || 60) * 1000;
@@ -47,37 +52,33 @@ const DISPLAY_NAMES = {
   opendesign: 'Open Design',
 };
 
-/** Which DSH model prefixes map to which adapter. */
-const PREFIX_ALIASES = {
-  'kimi-coding': 'kimi',
-  kimi: 'kimi',
-  'opencode-go': 'opencode',
-  opencode: 'opencode',
-  commandcode: 'commandcode',
-  'command-code': 'commandcode',
-  xai: 'xai',
-  codex: 'codex',
-  antigravity: 'agy',
-  agy: 'agy',
-  deepseek: 'deepseek',
-  opendesign: 'opendesign',
-};
+/** Provider ids contributed by ~/.dsh/quota-pill/adapters (tracked to purge stale ones). */
+let userProviderNames = new Set();
+
+/**
+ * Reload user adapters from disk and sync them into the request-time registry.
+ * Cheap when the directory has not changed; force on ?fresh=1.
+ */
+async function refreshUserAdapters({ force = false } = {}) {
+  const info = await loadUserAdapters({ force });
+  const next = new Set(info.adapters.map((a) => a.provider));
+  for (const provider of userProviderNames) {
+    if (!next.has(provider)) {
+      delete ADAPTERS[provider];
+      delete DISPLAY_NAMES[provider];
+    }
+  }
+  for (const adapter of info.adapters) {
+    ADAPTERS[adapter.provider] = (model) => adapter.read(adapterContext(model));
+    DISPLAY_NAMES[adapter.provider] = adapter.displayName;
+  }
+  userProviderNames = next;
+  return info;
+}
 
 /** provider|model → { at, payload }. Keyed by model because readings differ per model. */
 const cache = new Map();
 
-function providerForModel(model) {
-  const m = String(model || '').toLowerCase();
-  const prefix = m.split('/')[0];
-  if (PREFIX_ALIASES[prefix]) return PREFIX_ALIASES[prefix];
-  // Fuzzy fallbacks for models whose prefix is not the provider id.
-  if (m.includes('grok')) return 'xai';
-  if (m.includes('codex') || m.startsWith('gpt-')) return 'codex';
-  if (m.includes('gemini')) return 'agy';
-  if (m.startsWith('k3') || m.startsWith('kimi')) return 'kimi';
-  return '';
-}
-
 async function readOne(provider, model, { fresh = false } = {}) {
   const fn = ADAPTERS[provider];
   if (!fn) return { kind: 'none', provider, error: `no adapter for '${provider}'` };
@@ -105,29 +106,6 @@ async function readOne(provider, model, { fresh = false } = {}) {
   return { ...payload, cached: false, at: now };
 }
 
-/**
- * Which DSH catalog ids count as "this adapter".
- *
- * DSH names providers after the upstream (`antigravity`, `deepseek-account`,
- * `opencode-go`); the adapters use the short keys the pill has always used.
- */
-const CATALOG_ALIASES = {
-  agy: ['antigravity', 'agy'],
-  deepseek: ['deepseek-account', 'deepseek'],
-  opencode: ['opencode-go', 'opencode'],
-  kimi: ['kimi-coding', 'kimi'],
-  xai: ['xai'],
-  codex: ['codex'],
-  commandcode: ['commandcode'],
-  opendesign: ['opendesign'],
-};
-
-function inCatalog(provider, ids) {
-  if (!ids) return true; // catalog unknown: do not hide anything
-  const names = CATALOG_ALIASES[provider] || [provider];
-  return names.some((n) => ids.includes(n));
-}
-
 /**
  * Every provider worth showing: present in DSH's catalog AND actually readable.
  *
@@ -141,6 +119,7 @@ function inCatalog(provider, ids) {
  * failure is information the user needs.
  */
 async function readAll({ fresh = false } = {}) {
+  await refreshUserAdapters({ force: fresh });
   const ids = await catalogProviderIds();
   const wanted = Object.keys(ADAPTERS).filter((p) => inCatalog(p, ids));
 
@@ -153,20 +132,48 @@ async function readAll({ fresh = false } = {}) {
 }
 
 /** What is configured and what is missing — powers the agent-driven setup. */
-function describeSetup() {
+/** Human-readable "what this provider still needs" for /setup and AGENTS.md. */
+function requiresText(src) {
+  if (src.requires) return String(src.requires);
+  if (src.kind === 'cli-proxy') return 'CLIProxyAPI + OAuth login';
+  if (src.kind === 'dsh-account') return 'DSH Platform sign-in (nothing to add)';
+  const refs = (src.refs && src.refs.length) ? src.refs : (src.ref ? [src.ref] : []);
+  if (!refs.length) return 'no credential source';
+  const named = refs.map((r) => `refs.${r}`).join(' or ');
+  if (src.kind === 'control-key') {
+    const ws = (src.workspaceRefs || []).map((r) => `refs.${r}`).join(' or ')
+      || 'an explicit workspace ref (optional: resolved from /workspaces/current)';
+    const cookie = src.cookieRef ? ` or console cookie refs.${src.cookieRef}` : '';
+    return `~/.dsh/.credentials.yaml → ${named} + ${ws}${cookie}`;
+  }
+  const suffix = src.kind === 'session-cookie' ? ' (console session cookie)' : '';
+  return `~/.dsh/.credentials.yaml → ${named}${suffix}`;
+}
+
+async function describeSetup(info) {
+  const catalog = await catalogProviderIds();
   const providers = Object.keys(ADAPTERS).map((p) => {
     const src = credentialSource(p);
     return {
       provider: p,
       name: DISPLAY_NAMES[p] || p,
-      requires: src.kind === 'cli-proxy' ? 'CLIProxyAPI + OAuth login' : `~/.dsh/.credentials.yaml → refs.${src.ref}`,
+      requires: requiresText(src),
+      inCatalog: catalog ? inCatalog(p, catalog) : null,
       credential: src,
     };
   });
+  const adapted = new Set(
+    catalog ? catalog.filter((id) => Object.keys(ADAPTERS).some((p) => inCatalog(p, [id]))) : [],
+  );
   return {
     ok: true,
+    version: VERSION,
+    catalog,
+    catalogSource: 'DSH session/modelCatalog',
+    unadaptedCatalog: catalog ? catalog.filter((id) => !adapted.has(id)) : [],
     credentialsFile: CREDENTIALS_FILE,
     cliProxy: { dir: CLI_PROXY_DIR, present: hasCliProxy() },
+    userAdapters: info ? { ...userAdaptersInfo(), errors: info.errors } : userAdaptersInfo(),
     providers,
   };
 }
@@ -187,22 +194,31 @@ const server = http.createServer(async (req, res) => {
 
   try {
     if (url.pathname === '/health') {
-      return json(res, 200, { ok: true, port: PORT, providers: Object.keys(ADAPTERS) });
+      await refreshUserAdapters({ force: fresh });
+      return json(res, 200, { ok: true, port: PORT, version: VERSION, providers: Object.keys(ADAPTERS) });
     }
     if (url.pathname === '/setup') {
-      return json(res, 200, describeSetup());
+      const userInfo = await refreshUserAdapters({ force: fresh });
+      if (fresh) forgetCatalog();
+      return json(res, 200, await describeSetup(userInfo));
     }
     if (url.pathname === '/quota/all') {
+      // The catalog is DSH's live provider list. A forced read is how a newly
+      // added provider appears without restarting the sidecar or waiting for
+      // the 120s TTL.
+      if (fresh) forgetCatalog();
       const all = await readAll({ fresh });
       return json(res, 200, all);
     }
     if (url.pathname === '/quota') {
       const model = url.searchParams.get('model') || '';
+      await refreshUserAdapters({ force: fresh });
       const provider = providerForModel(model);
       if (!provider) {
         return json(res, 200, {
           kind: 'none',
           provider: 'unknown',
+          displayName: 'Unknown provider',
           model,
           error: `no adapter matches model '${model}'`,
         });

package/src/user-adapters.js

@@ -0,0 +1,172 @@
+/**
+ * User-contributed provider adapters.
+ *
+ * The package only ships eight built-ins. A DSH user can add a provider the
+ * built-ins do not know (and an agent can do it for them) by dropping a module
+ * in:
+ *
+ *   ~/.dsh/quota-pill/adapters/<provider>.mjs
+ *
+ * That directory is OUTSIDE the npm package, so updating/reinstalling the plugin
+ * never overwrites it. The sidecar discovers it on every request (mtime check),
+ * so adding a file and pressing Refresh is enough — no restart.
+ *
+ * Contract (all exports optional except provider/read):
+ *
+ *   export const provider = 'myprovider';
+ *   export const catalogIds = ['myprovider-go'];   // DSH catalog/model ids
+ *   export const displayName = 'My Provider';
+ *   export const credential = { kind: 'api-key', refs: ['MYPROVIDER_API_KEY'] };
+ *   export async function read(ctx) {
+ *     // ctx.model, ctx.readRef, ctx.readFirstRef, ctx.getJson,
+ *     // ctx.getJsonViaCurl, ctx.postJsonViaCurl, ctx.env, ctx.dshHome
+ *     return { kind: 'subscription-quota', remainingPct: 42, window: '5h', ... };
+ *   }
+ *
+ * The result must use the same kinds as the built-in adapters
+ * (subscription-quota / payg / usage-only / none / probe-failed). Never invent
+ * a number: if the provider has no quota API, say so in `error`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  DSH_DIR,
+  readRef,
+  readFirstRef,
+  registerCredentialSource,
+  clearUserCredentialSources,
+} from './credentials.js';
+import { getJson, getJsonViaCurl, postJsonViaCurl } from './http.js';
+import { clearUserProviders, registerUserProvider } from './providers.js';
+
+export const USER_ADAPTER_DIR = process.env.QUOTA_PILL_USER_ADAPTER_DIR
+  || path.join(DSH_DIR, 'quota-pill', 'adapters');
+
+let current = { dir: USER_ADAPTER_DIR, adapters: [], errors: [], loadedAt: 0, signature: '' };
+
+function signatureOf(dir) {
+  let files = [];
+  try {
+    files = fs.readdirSync(dir)
+      .filter((f) => /\.(mjs|js)$/i.test(f) && !f.endsWith('.test.mjs'))
+      .sort();
+  } catch {
+    return { files: [], sig: dir + '|missing' };
+  }
+  const parts = [];
+  for (const f of files) {
+    try {
+      const s = fs.statSync(path.join(dir, f));
+      parts.push(f + ':' + s.mtimeMs + ':' + s.size);
+    } catch {
+      parts.push(f + ':missing');
+    }
+  }
+  return { files, sig: dir + '|' + parts.join('|') };
+}
+
+function normalizeCredential(raw, provider) {
+  if (raw && typeof raw === 'object') {
+    return {
+      kind: raw.kind || 'user-adapter',
+      refs: Array.isArray(raw.refs) ? raw.refs : (raw.ref ? [raw.ref] : []),
+      ref: raw.ref || (Array.isArray(raw.refs) ? raw.refs[0] : null) || null,
+      requires: raw.requires || null,
+      ...raw,
+    };
+  }
+  return {
+    kind: 'user-adapter',
+    refs: [],
+    ref: null,
+    requires: 'credentials defined by the user adapter ' + provider,
+  };
+}
+
+async function importAdapter(full, stat) {
+  // The mtime/size query busts Node's ESM cache, so editing an adapter and
+  // refreshing really reloads it instead of serving the first version.
+  const href = pathToFileURL(full).href + '?v=' + encodeURIComponent(stat.mtimeMs + '-' + stat.size);
+  const mod = await import(href);
+  const spec = (mod && mod.default && typeof mod.default === 'object') ? { ...mod.default, ...mod } : mod;
+  const fallback = path.basename(full, path.extname(full));
+  const provider = String(spec.provider || fallback).trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(provider)) {
+    throw new Error('invalid provider id: ' + JSON.stringify(provider));
+  }
+  if (typeof spec.read !== 'function') throw new Error('adapter must export an async read(ctx) function');
+  return {
+    provider,
+    read: spec.read,
+    displayName: spec.displayName ? String(spec.displayName) : provider,
+    catalogIds: Array.isArray(spec.catalogIds) ? spec.catalogIds.map(String).filter(Boolean) : [provider],
+    prefixes: Array.isArray(spec.prefixes) ? spec.prefixes.map(String).filter(Boolean) : [],
+    credential: normalizeCredential(spec.credential, provider),
+    file: full,
+  };
+}
+
+/** Load/reload user adapters. Cheap when the directory has not changed. */
+export async function loadUserAdapters({ force = false, dir = USER_ADAPTER_DIR } = {}) {
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    // read-only home: scan whatever exists, /setup will show the error
+  }
+  const { files, sig } = signatureOf(dir);
+  if (!force && sig === current.signature) return current;
+
+  // Rebuild registrations from scratch so a deleted file also unregisters its
+  // provider instead of leaving a stale adapter/mapping behind.
+  clearUserProviders();
+  clearUserCredentialSources();
+
+  const adapters = [];
+  const errors = [];
+  for (const file of files) {
+    const full = path.join(dir, file);
+    try {
+      const stat = fs.statSync(full);
+      const adapter = await importAdapter(full, stat);
+      adapters.push(adapter);
+      registerUserProvider(adapter);
+      registerCredentialSource(adapter.provider, adapter.credential);
+    } catch (e) {
+      errors.push({ file, error: String((e && e.message) || e) });
+    }
+  }
+
+  current = { dir, adapters, errors, loadedAt: Date.now(), signature: sig };
+  return current;
+}
+
+export function userAdapterProviders() {
+  return current.adapters.map((a) => a.provider);
+}
+
+export function userAdapterFor(provider) {
+  return current.adapters.find((a) => a.provider === provider) || null;
+}
+
+export function userAdaptersInfo() {
+  return {
+    dir: current.dir,
+    providers: current.adapters.map((a) => ({ provider: a.provider, displayName: a.displayName, file: a.file })),
+    errors: current.errors,
+  };
+}
+
+/** Context passed to a user adapter's read(ctx). */
+export function adapterContext(model) {
+  return {
+    model,
+    readRef,
+    readFirstRef,
+    getJson,
+    getJsonViaCurl,
+    postJsonViaCurl,
+    env: process.env,
+    dshHome: DSH_DIR,
+  };
+}