@kairyou/agent-tools 0.5.2 → 0.7.0

package/README.md

@@ -109,9 +109,9 @@ and never touch your edits or comments.
 For API relay / gateway setups: shows the relay's balance / quota inside the
 agent, so when you pay per use or have plan limits you always know how much you
 have spent and how much is left — without opening the gateway console.
-Works with the usage APIs of Sub2API, NewAPI/OneAPI-family panels (OneHub,
-DoneHub, Veloera, ...), and OpenRouter; compatibility can vary with a
-deployment's version and auth scheme.
+Works with API-key usage endpoints exposed by Sub2API, One API, New API, and
+OpenRouter. Compatibility depends on the gateway version and whether the
+corresponding usage endpoint is enabled.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude
@@ -140,14 +140,66 @@ endpoint and key — and tune `providerUsage` in `~/.agent-tools/config.jsonc`:
 ```jsonc
 {
   "providerUsage": {
-    "preset": "auto", // sub2api | new-api | veloera | openrouter | ...
-    "userId": "",     // some NewAPI/Veloera panels require your panel user id
-    "days": 30,       // spend window for the "30d" field (max 90)
+    "preset": "auto", // auto | sub2api | one-api | new-api | openrouter | <custom-route-id>
+    "days": 30,       // how many recent days of spend to count
     "debug": false    // true: log probes to ~/.agent-tools/logs/usage-debug.log
   }
 }
 ```
 
+Keep `preset` set to `auto` for automatic detection. Select a specific protocol
+only when you know which usage endpoint the gateway exposes; a configured
+custom route id is also accepted.
+
+#### Custom gateway routes
+
+For gateways the built-in probes cannot reach (e.g. cookie-authenticated
+relays), write your own route module and declare it in `providerUsage.routes`
+(paths resolve against `~/.agent-tools`). Declared routes are probed first;
+setting `"preset"` to a route id selects it directly.
+
+```jsonc
+{
+  "providerUsage": {
+    "routes": [
+      "custom/my-gateway.mjs",
+      "custom/another-gateway.mjs"
+    ],
+    "myGateway": { "username": "me", "password": "..." }
+  }
+}
+```
+
+```js
+// ~/.agent-tools/custom/my-gateway.mjs
+export const meta = { id: "my-gateway" }; // optional; id defaults to the file name
+
+export async function run(context, { requestJson, agentConfig }) {
+  // context: { baseUrl, key, providerName, provider, label }
+  const { myGateway = {} } = await agentConfig(); // the providerUsage object; custom keys welcome
+
+  // Tip: save the token to a file (e.g. under ~/.agent-tools/cache) and reuse
+  // it; log in again only when a query fails with it (e.g. 401), then save the
+  // new token.
+  const login = await fetch(`${context.baseUrl}/api/user/login`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ username: myGateway.username, password: myGateway.password }),
+  });
+  const session = await login.json();
+
+  // Plain fetch works too; custom headers: authorization, cookie, ...
+  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
+    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
+  });
+  return { text: `API | balance ¥${me?.data?.balance}` };
+}
+```
+
+`text` is a free-form string; return `{ text }` on success, throw to fall
+through to the next route (with `providerUsage.debug` enabled, failures are
+logged to `~/.agent-tools/logs/usage-debug.log`).
+
 Output examples:
 
 ```text

package/README.zh-CN.md

@@ -102,8 +102,8 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 
 面向使用 API 中转的场景: 在 agent 内直接显示中转网关的余额/额度, 按量付费或
 有套餐限额时, 随时知道花了多少, 还剩多少, 不用切出去登录网关后台.
-支持 Sub2API, NewAPI/OneAPI 系面板 (OneHub, DoneHub, Veloera 等)
-与 OpenRouter 的用量接口; 同类网关的部署版本和鉴权方式不同, 兼容性可能有差异.
+支持 Sub2API, One API, New API 与 OpenRouter 提供的 API Key 用量接口.
+具体兼容性取决于网关版本及其是否开放相应接口.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude
@@ -130,14 +130,62 @@ provider 的 `base_url` 和密钥; Claude Code: 读取 `ANTHROPIC_BASE_URL` 与
 ```jsonc
 {
   "providerUsage": {
-    "preset": "auto", // sub2api | new-api | veloera | openrouter | ...
-    "userId": "",     // 部分 NewAPI/Veloera 面板需要填面板用户 id
-    "days": 30,       // "30d" 字段的统计窗口(最大 90)
+    "preset": "auto", // auto | sub2api | one-api | new-api | openrouter | <自定义 route id>
+    "days": 30,       // 统计最近多少天的消耗
     "debug": false    // true: 探测过程写入 ~/.agent-tools/logs/usage-debug.log
   }
 }
 ```
 
+保持 `preset: "auto"` 即可自动探测. 只有明确知道网关开放的是哪种用量协议时,
+才指定相应的内置 preset 或已配置的自定义 route id.
+
+#### 自定义网关路由
+
+内置探测覆盖不到的网关(比如 cookie 认证的中转), 可以自己写路由模块并在
+`providerUsage.routes` 里声明(相对 `~/.agent-tools` 解析). 声明的路由优先
+探测; `"preset"` 填路由 id 可直接选中.
+
+```jsonc
+{
+  "providerUsage": {
+    "routes": [
+      "custom/my-gateway.mjs",
+      "custom/another-gateway.mjs"
+    ],
+    "myGateway": { "username": "me", "password": "..." }
+  }
+}
+```
+
+```js
+// ~/.agent-tools/custom/my-gateway.mjs
+export const meta = { id: "my-gateway" }; // 可选; id 缺省用文件名
+
+export async function run(context, { requestJson, agentConfig }) {
+  // context: { baseUrl, key, providerName, provider, label }
+  const { myGateway = {} } = await agentConfig(); // providerUsage 对象, 自定义键随意加
+
+  // 建议: 把 token 存到文件里(如 ~/.agent-tools/cache 下)重复使用,
+  // 用它查询失败(如 401)时才重新登录, 并把新 token 写回文件.
+  const login = await fetch(`${context.baseUrl}/api/user/login`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ username: myGateway.username, password: myGateway.password }),
+  });
+  const session = await login.json();
+
+  // 用 fetch 也行; 自定义 header: authorization, cookie 等.
+  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
+    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
+  });
+  return { text: `API | balance ¥${me?.data?.balance}` };
+}
+```
+
+`text` 是自由字符串; 成功返回 `{ text }`, 抛错则回落到下一条路由
+(开启 `providerUsage.debug` 后, 失败会记录到 `~/.agent-tools/logs/usage-debug.log`).
+
 显示效果示例:
 
 ```text

package/dist/usage/core.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // integrations/usage/core.mjs
-import { pathToFileURL } from "node:url";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 // integrations/usage/lib/config.mjs
 import { readFile, writeFile, mkdir } from "node:fs/promises";
@@ -919,32 +919,16 @@ async function debugLog(event) {
 async function providerUsageDays() {
   const config = await agentConfig();
   const value = Number(process.env.PROVIDER_USAGE_DAYS || config.days || DEFAULT_USAGE_DAYS);
-  if (!Number.isInteger(value) || value <= 0 || value > MAX_USAGE_DAYS) return DEFAULT_USAGE_DAYS;
-  return value;
+  if (!Number.isInteger(value) || value <= 0) return DEFAULT_USAGE_DAYS;
+  return Math.min(value, MAX_USAGE_DAYS);
 }
 async function usagePreset() {
   const config = await agentConfig();
   return String(process.env.PROVIDER_USAGE_PRESET || config.preset || "auto").toLowerCase();
 }
-async function panelUserId() {
-  const config = await agentConfig();
-  const raw = process.env.PROVIDER_USAGE_USER_ID || config.userId || "";
-  const parsed = Number.parseInt(String(raw), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-async function panelUserHeaders() {
-  const userId = await panelUserId();
-  if (!userId) return {};
-  const value = String(userId);
-  return {
-    "New-API-User": value,
-    "Veloera-User": value,
-    "voapi-user": value,
-    "User-id": value,
-    "X-User-Id": value,
-    "Rix-Api-User": value,
-    "neo-api-user": value
-  };
+function snapshotTtlMs() {
+  const raw = Number(process.env.AGENT_TOOLS_USAGE_SNAPSHOT_TTL_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 6e4;
 }
 async function newApiQuotaScale() {
   const config = await agentConfig();
@@ -1041,6 +1025,10 @@ async function readSnapshotCache() {
     return { version: SNAPSHOT_VERSION, items: {} };
   }
 }
+async function readUsageSnapshot(context) {
+  const cache = await readSnapshotCache();
+  return cache.items[usageRouteCacheKey(context.baseUrl)] || null;
+}
 async function rememberUsageSnapshot(context, result) {
   if (!result?.text) return;
   try {
@@ -1089,6 +1077,11 @@ async function rememberRefreshState(context, patch) {
   }
 }
 
+// integrations/usage/lib/routes.mjs
+import { readdir } from "node:fs/promises";
+import { basename, extname, isAbsolute, join as join2 } from "node:path";
+import { pathToFileURL } from "node:url";
+
 // integrations/usage/lib/http.mjs
 import { createContext, runInContext } from "node:vm";
 var REQUEST_TIMEOUT_MS = 5e3;
@@ -1191,7 +1184,8 @@ function mergeSetCookiePairs(cookieHeader, setCookieHeaders) {
   }
   return merged;
 }
-async function requestJson(url, key, options = {}) {
+async function requestJson(url, options = {}) {
+  const { key = "", headers = {}, name = "usage" } = options;
   let cookieHeader = "";
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const controller = new AbortController();
@@ -1199,10 +1193,10 @@ async function requestJson(url, key, options = {}) {
     const response = await fetch(url, {
       headers: {
         accept: "application/json",
-        authorization: `Bearer ${options.authKey || key}`,
+        ...key ? { authorization: `Bearer ${key}` } : {},
         "user-agent": SHIELD_USER_AGENT,
         ...cookieHeader ? { cookie: cookieHeader } : {},
-        ...options.headers || {}
+        ...headers
       },
       signal: controller.signal
     });
@@ -1216,7 +1210,7 @@ async function requestJson(url, key, options = {}) {
         const contentType = response.headers.get("content-type") || "";
         const acwScV2 = isShieldChallenge(contentType, body) ? solveNewApiAcwScV2(body) : "";
         await debugLog({
-          source: options.name || "usage",
+          source: name,
           url,
           status: response.status,
           contentType,
@@ -1227,25 +1221,25 @@ async function requestJson(url, key, options = {}) {
           cookieHeader = upsertCookie(cookieHeader, "acw_sc__v2", acwScV2);
           continue;
         }
-        throw new Error(`${options.name || "usage"} returned non-JSON (${response.status})`);
+        throw new Error(`${name} returned non-JSON (${response.status})`);
       }
       if (!response.ok) {
         const message = json?.error?.message || json?.message || response.statusText;
         await debugLog({
-          source: options.name || "usage",
+          source: name,
           url,
           status: response.status,
           message,
           bodyPreview: shortPreview(body)
         });
-        throw new Error(`${options.name || "usage"} failed (${response.status} ${message})`);
+        throw new Error(`${name} failed (${response.status} ${message})`);
       }
       return json;
     } finally {
       clearTimeout(timeout);
     }
   }
-  throw new Error(`${options.name || "usage"} unavailable`);
+  throw new Error(`${name} unavailable`);
 }
 
 // integrations/usage/lib/format.mjs
@@ -1374,36 +1368,8 @@ function formatOpenRouterLine(label, data) {
   if (parts.length === 1) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
 }
-function panelQuotaScale(kind) {
-  return kind === "veloera" ? 1e6 : DEFAULT_NEW_API_QUOTA_SCALE;
-}
-function panelQuotaLooksRemaining(kind) {
-  return ["new-api", "anyrouter", "agentrouter", "done-hub", "donehub"].includes(kind);
-}
-async function formatPanelUserSelfLine(label, data, kind) {
-  const root = usageRoot(data);
-  const scale = panelQuotaScale(kind);
-  const quota = pickNumber(root, ["quota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota"]);
-  const todayIncome = pickNumber(root, ["today_income", "todayIncome"]);
-  const todayUsed = pickNumber(root, ["today_quota_consumption", "todayQuotaConsumption"]);
-  if (quota === void 0 && used === void 0) {
-    throw new Error("panel /api/user/self payload has no quota fields");
-  }
-  const quotaUsd = quota === void 0 ? void 0 : quota / scale;
-  const usedUsd = used === void 0 ? void 0 : used / scale;
-  const remainingUsd = panelQuotaLooksRemaining(kind) ? quotaUsd : quotaUsd === void 0 || usedUsd === void 0 ? quotaUsd : Math.max(0, quotaUsd - usedUsd);
-  const totalUsd = panelQuotaLooksRemaining(kind) ? quotaUsd === void 0 || usedUsd === void 0 ? quotaUsd : quotaUsd + usedUsd : quotaUsd;
-  const parts = usageParts();
-  if (remainingUsd !== void 0) parts.push(`balance ${formatMoney(remainingUsd)}`);
-  if (usedUsd !== void 0 && totalUsd !== void 0) {
-    parts.push(`used ${formatMoney(usedUsd)}/${formatMoney(totalUsd)}`);
-  } else if (usedUsd !== void 0) {
-    parts.push(`used ${formatMoney(usedUsd)}`);
-  }
-  if (todayUsed !== void 0) parts.push(`today ${formatMoney(todayUsed / scale)}`);
-  if (todayIncome !== void 0) parts.push(`income ${formatMoney(todayIncome / scale)}`);
-  return parts.join(" | ");
+function formatOneApiBillingLine(limit, used) {
+  return `API | balance ${formatMoney(Math.max(0, limit - used))} | used ${formatMoney(used)}/${formatMoney(limit)}`;
 }
 function formatQuotaLimitedLine(label, root) {
   const quota = root?.quota || {};
@@ -1473,15 +1439,17 @@ function usageResult(context, source, text, raw) {
   };
 }
 async function fetchV1Usage(context) {
-  const json = await requestJson(await subscriptionUrl(context.baseUrl), context.key, {
+  const json = await requestJson(await subscriptionUrl(context.baseUrl), {
+    key: context.key,
     name: "v1 usage"
   });
   if (!hasV1UsageFields(usageRoot(json))) throw new Error("v1 usage payload has no usage fields");
   return usageResult(context, "v1-usage", await formatQuota(context.label, json), json);
 }
 async function fetchNewApiTokenUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), context.key, {
-    name: "NewAPI token usage"
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), {
+    key: context.key,
+    name: "New API token usage"
   });
   const root = usageRoot(json);
   const quota = pickNumber(root, ["quota", "limit", "total_quota", "totalQuota"]);
@@ -1507,64 +1475,37 @@ async function fetchNewApiTokenUsage(context) {
   };
   return usageResult(context, "newapi-token", await formatNewApiTokenLine(context.label, json), normalized);
 }
-async function fetchPanelUserSelfUsage(context) {
-  const preset = await usagePreset();
-  const kind = preset === "auto" ? "new-api" : preset;
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/user/self"), context.key, {
-    name: "panel /api/user/self",
-    headers: await panelUserHeaders()
+async function fetchOneApiBillingUsage(context) {
+  const base = serviceRoot(context.baseUrl);
+  const subscription = await requestJson(joinUrl(base, "/v1/dashboard/billing/subscription"), {
+    key: context.key,
+    name: "One API billing subscription"
   });
-  const root = usageRoot(json);
-  if (pickNumber(root, ["quota"]) === void 0 && pickNumber(root, ["used_quota", "usedQuota"]) === void 0) {
-    await debugLog({
-      source: "panel /api/user/self",
-      payloadKeys: Object.keys(root || {}).slice(0, 20),
-      success: root?.success,
-      message: root?.message || root?.error?.message || ""
-    });
+  const usage = await requestJson(joinUrl(base, "/v1/dashboard/billing/usage"), {
+    key: context.key,
+    name: "One API billing usage"
+  });
+  const limit = pickNumber(subscription, ["hard_limit_usd", "hardLimitUsd"]);
+  const usageCents = pickNumber(usage, ["total_usage", "totalUsage"]);
+  if (limit === void 0 || usageCents === void 0) {
+    throw new Error("One API billing payload has no quota fields");
   }
-  const scale = panelQuotaScale(kind);
-  const quota = pickNumber(root, ["quota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota"]);
-  const remaining = panelQuotaLooksRemaining(kind) ? quota : quota === void 0 || used === void 0 ? quota : Math.max(0, quota - used);
-  const total = panelQuotaLooksRemaining(kind) ? quota === void 0 || used === void 0 ? quota : quota + used : quota;
+  const used = usageCents / 100;
   const normalized = {
     mode: "quota_limited",
     quota: {
-      limit: total === void 0 ? void 0 : total / scale,
-      used: used === void 0 ? void 0 : used / scale,
-      remaining: remaining === void 0 ? void 0 : remaining / scale
+      limit,
+      used,
+      remaining: Math.max(0, limit - used)
     },
     unit: "USD",
-    source: "panel-user-self",
-    raw: json
+    source: "oneapi-billing",
+    raw: { subscription, usage }
   };
   return usageResult(
     context,
-    "panel-user-self",
-    await formatPanelUserSelfLine(context.label, json, kind),
-    normalized
-  );
-}
-async function fetchSub2ApiAuthMeUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/v1/auth/me"), context.key, {
-    name: "Sub2API auth/me"
-  });
-  const root = usageRoot(json);
-  const balance = pickNumber(root, ["balance"]);
-  if (balance === void 0) throw new Error("Sub2API auth/me payload has no balance field");
-  const normalized = {
-    mode: "unrestricted",
-    planName: root?.username || root?.email || context.label || "Sub2API",
-    balance,
-    unit: "USD",
-    source: "sub2api-auth-me",
-    raw: json
-  };
-  return usageResult(
-    context,
-    "sub2api-auth-me",
-    `API | balance ${formatMoney(balance)}`,
+    "oneapi-billing",
+    formatOneApiBillingLine(limit, used),
     normalized
   );
 }
@@ -1577,7 +1518,7 @@ async function fetchOpenRouterUsage(context) {
   let lastError;
   for (const endpoint of endpoints) {
     try {
-      const json = await requestJson(endpoint.url, context.key, { name: endpoint.source });
+      const json = await requestJson(endpoint.url, { key: context.key, name: endpoint.source });
       return usageResult(context, endpoint.source, formatOpenRouterLine("OpenRouter", json), json);
     } catch (error) {
       lastError = error;
@@ -1592,20 +1533,15 @@ var USAGE_ROUTES = {
     path: "/v1/usage",
     run: fetchV1Usage
   },
-  "sub2api-auth-me": {
-    id: "sub2api-auth-me",
-    path: "/api/v1/auth/me",
-    run: fetchSub2ApiAuthMeUsage
-  },
   "newapi-token": {
     id: "newapi-token",
     path: "/api/usage/token/",
     run: fetchNewApiTokenUsage
   },
-  "panel-user-self": {
-    id: "panel-user-self",
-    path: "/api/user/self",
-    run: fetchPanelUserSelfUsage
+  "oneapi-billing": {
+    id: "oneapi-billing",
+    path: "/v1/dashboard/billing/subscription",
+    run: fetchOneApiBillingUsage
   },
   "openrouter": {
     id: "openrouter",
@@ -1613,44 +1549,102 @@ var USAGE_ROUTES = {
     run: fetchOpenRouterUsage
   }
 };
+var CUSTOM_ROUTE_HELPERS = { requestJson, agentConfig };
+var customRoutesPromise;
+function customRoutes() {
+  customRoutesPromise ||= loadCustomRoutes();
+  return customRoutesPromise;
+}
+async function loadRouteModule(file, spec) {
+  try {
+    const mod = await import(pathToFileURL(file).href);
+    if (typeof mod.run !== "function") {
+      throw new Error("missing `export async function run(context, helpers)`");
+    }
+    const id = String(mod.meta?.id || basename(file, extname(file)));
+    return {
+      id,
+      path: spec,
+      run: async (context) => {
+        const result = await mod.run(context, CUSTOM_ROUTE_HELPERS);
+        if (typeof result?.text !== "string" || !result.text) {
+          throw new Error(`custom route ${id} returned no text`);
+        }
+        return {
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          baseUrl: context.baseUrl,
+          provider: context.providerName,
+          source: id,
+          ...result
+        };
+      }
+    };
+  } catch (error) {
+    await debugLog({ source: "custom-route", file, error: error.message });
+    return null;
+  }
+}
+async function loadCustomRoutes() {
+  const routes = [];
+  const config = await agentConfig();
+  const specs = Array.isArray(config.routes) ? config.routes : [];
+  for (const spec of specs) {
+    if (typeof spec !== "string" || !spec.trim()) continue;
+    const file = isAbsolute(spec) ? spec : join2(AGENT_TOOLS_HOME, spec);
+    const route = await loadRouteModule(file, spec);
+    if (route) routes.push(route);
+  }
+  const packagedDir = join2(AGENT_TOOLS_HOME, "dist", "usage", "routes");
+  let packaged = [];
+  try {
+    packaged = (await readdir(packagedDir)).filter((n) => n.endsWith(".mjs")).sort();
+  } catch {
+    packaged = [];
+  }
+  for (const name of packaged) {
+    const route = await loadRouteModule(join2(packagedDir, name), `dist/usage/routes/${name}`);
+    if (route && !routes.some((existing) => existing.id === route.id)) routes.push(route);
+  }
+  return routes;
+}
+async function routeRegistry() {
+  const registry = { ...USAGE_ROUTES };
+  for (const route of await customRoutes()) registry[route.id] = route;
+  return registry;
+}
 async function usageRouteIds(context) {
   const preset = await usagePreset();
   const routes = {
-    "sub2api": ["v1-usage", "sub2api-auth-me"],
+    "sub2api": ["v1-usage"],
     "openai-compatible": ["v1-usage"],
-    "new-api": ["newapi-token", "panel-user-self"],
-    "one-api": ["newapi-token", "panel-user-self"],
-    "onehub": ["newapi-token", "panel-user-self"],
-    "one-hub": ["newapi-token", "panel-user-self"],
-    "donehub": ["newapi-token", "panel-user-self"],
-    "done-hub": ["newapi-token", "panel-user-self"],
-    "veloera": ["panel-user-self", "newapi-token"],
-    "anyrouter": ["newapi-token", "panel-user-self", "v1-usage"],
-    "agentrouter": ["newapi-token", "panel-user-self", "v1-usage"],
+    "new-api": ["newapi-token"],
+    "one-api": ["oneapi-billing"],
     "openrouter": ["openrouter"]
   };
   if (routes[preset]) return routes[preset];
-  if (preset !== "auto") return [];
-  if (hostIncludes(context.baseUrl, "openrouter.ai")) return ["openrouter"];
-  return ["v1-usage", "sub2api-auth-me", "newapi-token", "panel-user-self"];
+  if (preset !== "auto") return (await routeRegistry())[preset] ? [preset] : [];
+  const customIds = (await customRoutes()).map((route) => route.id);
+  const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai") ? ["openrouter"] : ["v1-usage", "newapi-token", "oneapi-billing"];
+  return [.../* @__PURE__ */ new Set([...customIds, ...builtinIds])];
 }
-async function cachedUsageRoute(context) {
+async function cachedUsageRoute(context, registry) {
   const cache = await readRouteCache();
   const key = usageRouteCacheKey(context.baseUrl);
   const route = cache.routes[key];
-  return route?.route && USAGE_ROUTES[route.route] ? route : null;
+  return route?.route && registry[route.route] ? route : null;
 }
 async function orderedUsageRoutes(context) {
+  const registry = await routeRegistry();
   const routeIds = await usageRouteIds(context);
-  const cached = await cachedUsageRoute(context);
-  if (!cached || !routeIds.includes(cached.route)) return routeIds.map((id) => USAGE_ROUTES[id]).filter(Boolean);
+  const cached = await cachedUsageRoute(context, registry);
+  if (!cached || !routeIds.includes(cached.route)) return routeIds.map((id) => registry[id]).filter(Boolean);
   await debugLog({
     source: "route-cache",
     key: usageRouteCacheKey(context.baseUrl),
     route: cached.route,
-    path: cached.path || USAGE_ROUTES[cached.route]?.path || ""
+    path: cached.path || registry[cached.route]?.path || ""
   });
-  return [cached.route, ...routeIds.filter((id) => id !== cached.route)].map((id) => USAGE_ROUTES[id]).filter(Boolean);
+  return [cached.route, ...routeIds.filter((id) => id !== cached.route)].map((id) => registry[id]).filter(Boolean);
 }
 
 // integrations/usage/lib/context.mjs
@@ -1844,11 +1838,14 @@ async function queryProviderUsage(input, options = {}) {
 async function refresh(agent = "codex") {
   return await queryAgentProviderUsage(agent);
 }
-async function queryAgentProviderUsage(agent = "codex") {
-  return await queryUsageContext(await usageContext(agent), {
-    agent,
-    rememberSnapshot: agent === "claude"
-  });
+async function queryAgentProviderUsage(agent = "codex", { maxAgeMs = 0 } = {}) {
+  const context = await usageContext(agent);
+  if (maxAgeMs > 0) {
+    const cached = await readUsageSnapshot(context);
+    const age = cached?.updatedAt ? Date.now() - Date.parse(cached.updatedAt) : Infinity;
+    if (cached?.text && age < maxAgeMs) return { ...cached, cached: true };
+  }
+  return await queryUsageContext(context, { agent, rememberSnapshot: true });
 }
 async function main() {
   try {
@@ -1858,7 +1855,7 @@ async function main() {
       const result = await refresh(cli.agent);
       textOut(result?.text || "");
     } else if (mode === "hook") {
-      const result = await refresh(cli.agent);
+      const result = await queryAgentProviderUsage(cli.agent, { maxAgeMs: snapshotTtlMs() });
       hookOut(result?.text || "");
     } else {
       throw new Error(`unknown mode: ${mode}`);
@@ -1867,7 +1864,7 @@ async function main() {
     failSoft("Provider usage unavailable", error);
   }
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL2(process.argv[1]).href) {
   await main();
 }
 export {

package/integrations/usage/core.mjs

@@ -8,9 +8,10 @@
 // routes) and is bundled into dist/usage/core.mjs at build time.
 
 import { pathToFileURL } from "node:url";
-import { debugLog, usagePreset } from "./lib/config.mjs";
+import { debugLog, usagePreset, snapshotTtlMs } from "./lib/config.mjs";
 import { isOfficialBaseUrl } from "./lib/urls.mjs";
 import {
+  readUsageSnapshot,
   rememberUsageRoute,
   rememberUsageSnapshot,
   rememberRefreshState,
@@ -113,11 +114,14 @@ async function refresh(agent = "codex") {
   return await queryAgentProviderUsage(agent);
 }
 
-export async function queryAgentProviderUsage(agent = "codex") {
-  return await queryUsageContext(await usageContext(agent), {
-    agent,
-    rememberSnapshot: agent === "claude",
-  });
+export async function queryAgentProviderUsage(agent = "codex", { maxAgeMs = 0 } = {}) {
+  const context = await usageContext(agent);
+  if (maxAgeMs > 0) {
+    const cached = await readUsageSnapshot(context);
+    const age = cached?.updatedAt ? Date.now() - Date.parse(cached.updatedAt) : Infinity;
+    if (cached?.text && age < maxAgeMs) return { ...cached, cached: true };
+  }
+  return await queryUsageContext(context, { agent, rememberSnapshot: true });
 }
 
 async function main() {
@@ -128,7 +132,8 @@ async function main() {
       const result = await refresh(cli.agent);
       textOut(result?.text || "");
     } else if (mode === "hook") {
-      const result = await refresh(cli.agent);
+      // Hook mode fires on every prompt; serve a fresh snapshot when possible.
+      const result = await queryAgentProviderUsage(cli.agent, { maxAgeMs: snapshotTtlMs() });
       hookOut(result?.text || "");
     } else {
       throw new Error(`unknown mode: ${mode}`);

package/integrations/usage/lib/cache.mjs

@@ -61,6 +61,11 @@ async function readSnapshotCache() {
   }
 }
 
+export async function readUsageSnapshot(context) {
+  const cache = await readSnapshotCache();
+  return cache.items[usageRouteCacheKey(context.baseUrl)] || null;
+}
+
 export async function rememberUsageSnapshot(context, result) {
   if (!result?.text) return;
   try {

package/integrations/usage/lib/config.mjs

@@ -61,8 +61,8 @@ export async function debugLog(event) {
 export async function providerUsageDays() {
   const config = await agentConfig();
   const value = Number(process.env.PROVIDER_USAGE_DAYS || config.days || DEFAULT_USAGE_DAYS);
-  if (!Number.isInteger(value) || value <= 0 || value > MAX_USAGE_DAYS) return DEFAULT_USAGE_DAYS;
-  return value;
+  if (!Number.isInteger(value) || value <= 0) return DEFAULT_USAGE_DAYS;
+  return Math.min(value, MAX_USAGE_DAYS);
 }
 
 export async function usagePreset() {
@@ -70,26 +70,12 @@ export async function usagePreset() {
   return String(process.env.PROVIDER_USAGE_PRESET || config.preset || "auto").toLowerCase();
 }
 
-export async function panelUserId() {
-  const config = await agentConfig();
-  const raw = process.env.PROVIDER_USAGE_USER_ID || config.userId || "";
-  const parsed = Number.parseInt(String(raw), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-
-export async function panelUserHeaders() {
-  const userId = await panelUserId();
-  if (!userId) return {};
-  const value = String(userId);
-  return {
-    "New-API-User": value,
-    "Veloera-User": value,
-    "voapi-user": value,
-    "User-id": value,
-    "X-User-Id": value,
-    "Rix-Api-User": value,
-    "neo-api-user": value,
-  };
+// Passive callers (the codex hook fires per prompt; several sessions may run
+// at once) reuse a fresh snapshot instead of hitting the gateway every time.
+// Same knob the statusline uses; 0 disables.
+export function snapshotTtlMs() {
+  const raw = Number(process.env.AGENT_TOOLS_USAGE_SNAPSHOT_TTL_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 60_000;
 }
 
 export async function newApiQuotaScale() {

package/integrations/usage/lib/format.mjs

@@ -1,6 +1,6 @@
 // Turns gateway payloads into the compact one-line usage message.
 
-import { newApiQuotaScale, providerUsageDays, DEFAULT_NEW_API_QUOTA_SCALE } from "./config.mjs";
+import { newApiQuotaScale, providerUsageDays } from "./config.mjs";
 
 export function pickNumber(obj, keys) {
   for (const key of keys) {
@@ -159,45 +159,8 @@ export function formatOpenRouterLine(label, data) {
   return parts.join(" | ");
 }
 
-export function panelQuotaScale(kind) {
-  return kind === "veloera" ? 1000000 : DEFAULT_NEW_API_QUOTA_SCALE;
-}
-
-export function panelQuotaLooksRemaining(kind) {
-  return ["new-api", "anyrouter", "agentrouter", "done-hub", "donehub"].includes(kind);
-}
-
-export async function formatPanelUserSelfLine(label, data, kind) {
-  const root = usageRoot(data);
-  const scale = panelQuotaScale(kind);
-  const quota = pickNumber(root, ["quota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota"]);
-  const todayIncome = pickNumber(root, ["today_income", "todayIncome"]);
-  const todayUsed = pickNumber(root, ["today_quota_consumption", "todayQuotaConsumption"]);
-
-  if (quota === undefined && used === undefined) {
-    throw new Error("panel /api/user/self payload has no quota fields");
-  }
-
-  const quotaUsd = quota === undefined ? undefined : quota / scale;
-  const usedUsd = used === undefined ? undefined : used / scale;
-  const remainingUsd = panelQuotaLooksRemaining(kind)
-    ? quotaUsd
-    : (quotaUsd === undefined || usedUsd === undefined ? quotaUsd : Math.max(0, quotaUsd - usedUsd));
-  const totalUsd = panelQuotaLooksRemaining(kind)
-    ? (quotaUsd === undefined || usedUsd === undefined ? quotaUsd : quotaUsd + usedUsd)
-    : quotaUsd;
-
-  const parts = usageParts();
-  if (remainingUsd !== undefined) parts.push(`balance ${formatMoney(remainingUsd)}`);
-  if (usedUsd !== undefined && totalUsd !== undefined) {
-    parts.push(`used ${formatMoney(usedUsd)}/${formatMoney(totalUsd)}`);
-  } else if (usedUsd !== undefined) {
-    parts.push(`used ${formatMoney(usedUsd)}`);
-  }
-  if (todayUsed !== undefined) parts.push(`today ${formatMoney(todayUsed / scale)}`);
-  if (todayIncome !== undefined) parts.push(`income ${formatMoney(todayIncome / scale)}`);
-  return parts.join(" | ");
+export function formatOneApiBillingLine(limit, used) {
+  return `API | balance ${formatMoney(Math.max(0, limit - used))} | used ${formatMoney(used)}/${formatMoney(limit)}`;
 }
 
 function formatQuotaLimitedLine(label, root) {

package/integrations/usage/lib/http.mjs

@@ -125,7 +125,8 @@ function mergeSetCookiePairs(cookieHeader, setCookieHeaders) {
   return merged;
 }
 
-export async function requestJson(url, key, options = {}) {
+export async function requestJson(url, options = {}) {
+  const { key = "", headers = {}, name = "usage" } = options;
   let cookieHeader = "";
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const controller = new AbortController();
@@ -133,10 +134,10 @@ export async function requestJson(url, key, options = {}) {
     const response = await fetch(url, {
       headers: {
         accept: "application/json",
-        authorization: `Bearer ${options.authKey || key}`,
+        ...(key ? { authorization: `Bearer ${key}` } : {}),
         "user-agent": SHIELD_USER_AGENT,
         ...(cookieHeader ? { cookie: cookieHeader } : {}),
-        ...(options.headers || {}),
+        ...headers,
       },
       signal: controller.signal,
     });
@@ -151,7 +152,7 @@ export async function requestJson(url, key, options = {}) {
         const contentType = response.headers.get("content-type") || "";
         const acwScV2 = isShieldChallenge(contentType, body) ? solveNewApiAcwScV2(body) : "";
         await debugLog({
-          source: options.name || "usage",
+          source: name,
           url,
           status: response.status,
           contentType,
@@ -162,19 +163,19 @@ export async function requestJson(url, key, options = {}) {
           cookieHeader = upsertCookie(cookieHeader, "acw_sc__v2", acwScV2);
           continue;
         }
-        throw new Error(`${options.name || "usage"} returned non-JSON (${response.status})`);
+        throw new Error(`${name} returned non-JSON (${response.status})`);
       }
 
       if (!response.ok) {
         const message = json?.error?.message || json?.message || response.statusText;
         await debugLog({
-          source: options.name || "usage",
+          source: name,
           url,
           status: response.status,
           message,
           bodyPreview: shortPreview(body),
         });
-        throw new Error(`${options.name || "usage"} failed (${response.status} ${message})`);
+        throw new Error(`${name} failed (${response.status} ${message})`);
       }
 
       return json;
@@ -182,5 +183,5 @@ export async function requestJson(url, key, options = {}) {
       clearTimeout(timeout);
     }
   }
-  throw new Error(`${options.name || "usage"} unavailable`);
+  throw new Error(`${name} unavailable`);
 }

package/integrations/usage/lib/routes.mjs

@@ -1,9 +1,13 @@
 // Known gateway usage endpoints and the probing order for a given context.
 
+import { readdir } from "node:fs/promises";
+import { basename, extname, isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { requestJson } from "./http.mjs";
 import {
+  AGENT_TOOLS_HOME,
+  agentConfig,
   usagePreset,
-  panelUserHeaders,
   newApiQuotaScale,
   providerUsageDays,
   debugLog,
@@ -17,15 +21,12 @@ import {
 } from "./urls.mjs";
 import {
   pickNumber,
-  formatMoney,
   usageRoot,
   hasV1UsageFields,
   formatQuota,
   formatNewApiTokenLine,
+  formatOneApiBillingLine,
   formatOpenRouterLine,
-  formatPanelUserSelfLine,
-  panelQuotaScale,
-  panelQuotaLooksRemaining,
 } from "./format.mjs";
 import { readRouteCache } from "./cache.mjs";
 
@@ -50,19 +51,20 @@ function usageResult(context, source, text, raw) {
 // OpenAI-style endpoint at /v1/usage. This is intentionally probed first for
 // generic non-OpenAI base URLs because it does not require a management token.
 async function fetchV1Usage(context) {
-  const json = await requestJson(await subscriptionUrl(context.baseUrl), context.key, {
+  const json = await requestJson(await subscriptionUrl(context.baseUrl), {
+    key: context.key,
     name: "v1 usage",
   });
   if (!hasV1UsageFields(usageRoot(json))) throw new Error("v1 usage payload has no usage fields");
   return usageResult(context, "v1-usage", await formatQuota(context.label, json), json);
 }
 
-// NewAPI / OneAPI family panels: use the current API key as Bearer auth and
-// query token usage from the service root rather than the /v1 OpenAI-compatible
-// path.
+// New API exposes a read-only usage endpoint authenticated by the same relay
+// API key used for model requests.
 async function fetchNewApiTokenUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), context.key, {
-    name: "NewAPI token usage",
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), {
+    key: context.key,
+    name: "New API token usage",
   });
   const root = usageRoot(json);
   const quota = pickNumber(root, ["quota", "limit", "total_quota", "totalQuota"]);
@@ -89,82 +91,46 @@ async function fetchNewApiTokenUsage(context) {
   return usageResult(context, "newapi-token", await formatNewApiTokenLine(context.label, json), normalized);
 }
 
-// NewAPI / OneAPI / OneHub / DoneHub / Veloera panel session endpoint, based on
-// Metapi's platform handling. This works when PROVIDER_USAGE_API_KEY is a panel
-// access/session token, or when the site accepts the API key for /api/user/self.
-async function fetchPanelUserSelfUsage(context) {
-  const preset = await usagePreset();
-  const kind = preset === "auto" ? "new-api" : preset;
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/user/self"), context.key, {
-    name: "panel /api/user/self",
-    headers: await panelUserHeaders(),
+// One API's legacy OpenAI billing endpoints use the same relay API key as
+// model requests. Subscription reports the total quota; usage reports cents.
+async function fetchOneApiBillingUsage(context) {
+  const base = serviceRoot(context.baseUrl);
+  const subscription = await requestJson(joinUrl(base, "/v1/dashboard/billing/subscription"), {
+    key: context.key,
+    name: "One API billing subscription",
   });
-  const root = usageRoot(json);
-  if (pickNumber(root, ["quota"]) === undefined && pickNumber(root, ["used_quota", "usedQuota"]) === undefined) {
-    await debugLog({
-      source: "panel /api/user/self",
-      payloadKeys: Object.keys(root || {}).slice(0, 20),
-      success: root?.success,
-      message: root?.message || root?.error?.message || "",
-    });
+  const usage = await requestJson(joinUrl(base, "/v1/dashboard/billing/usage"), {
+    key: context.key,
+    name: "One API billing usage",
+  });
+  const limit = pickNumber(subscription, ["hard_limit_usd", "hardLimitUsd"]);
+  const usageCents = pickNumber(usage, ["total_usage", "totalUsage"]);
+  if (limit === undefined || usageCents === undefined) {
+    throw new Error("One API billing payload has no quota fields");
   }
-  const scale = panelQuotaScale(kind);
-  const quota = pickNumber(root, ["quota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota"]);
-  const remaining = panelQuotaLooksRemaining(kind)
-    ? quota
-    : (quota === undefined || used === undefined ? quota : Math.max(0, quota - used));
-  const total = panelQuotaLooksRemaining(kind)
-    ? (quota === undefined || used === undefined ? quota : quota + used)
-    : quota;
+  const used = usageCents / 100;
   const normalized = {
     mode: "quota_limited",
     quota: {
-      limit: total === undefined ? undefined : total / scale,
-      used: used === undefined ? undefined : used / scale,
-      remaining: remaining === undefined ? undefined : remaining / scale,
+      limit,
+      used,
+      remaining: Math.max(0, limit - used),
     },
     unit: "USD",
-    source: "panel-user-self",
-    raw: json,
-  };
-  return usageResult(
-    context,
-    "panel-user-self",
-    await formatPanelUserSelfLine(context.label, json, kind),
-    normalized
-  );
-}
-
-// Sub2API exposes user balance as USD at /api/v1/auth/me. Newer deployments may
-// also expose richer subscription summaries through /v1/usage, so this route is
-// a fallback for deployments where /v1/usage is unavailable.
-async function fetchSub2ApiAuthMeUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/v1/auth/me"), context.key, {
-    name: "Sub2API auth/me",
-  });
-  const root = usageRoot(json);
-  const balance = pickNumber(root, ["balance"]);
-  if (balance === undefined) throw new Error("Sub2API auth/me payload has no balance field");
-  const normalized = {
-    mode: "unrestricted",
-    planName: root?.username || root?.email || context.label || "Sub2API",
-    balance,
-    unit: "USD",
-    source: "sub2api-auth-me",
-    raw: json,
+    source: "oneapi-billing",
+    raw: { subscription, usage },
   };
   return usageResult(
     context,
-    "sub2api-auth-me",
-    `API | balance ${formatMoney(balance)}`,
+    "oneapi-billing",
+    formatOneApiBillingLine(limit, used),
     normalized
   );
 }
 
 // OpenRouter exposes normal API-key usage at /api/v1/key. Some accounts also
 // expose credits at /api/v1/credits; keep this route isolated because
-// OpenRouter's base URL already includes /api/v1, unlike NewAPI/OneAPI.
+// OpenRouter's base URL already includes /api/v1, unlike New API.
 async function fetchOpenRouterUsage(context) {
   const base = cleanBaseUrl(context.baseUrl).includes("/api/v1")
     ? cleanBaseUrl(context.baseUrl)
@@ -176,7 +142,7 @@ async function fetchOpenRouterUsage(context) {
   let lastError;
   for (const endpoint of endpoints) {
     try {
-      const json = await requestJson(endpoint.url, context.key, { name: endpoint.source });
+      const json = await requestJson(endpoint.url, { key: context.key, name: endpoint.source });
       return usageResult(context, endpoint.source, formatOpenRouterLine("OpenRouter", json), json);
     } catch (error) {
       lastError = error;
@@ -192,20 +158,15 @@ const USAGE_ROUTES = {
     path: "/v1/usage",
     run: fetchV1Usage,
   },
-  "sub2api-auth-me": {
-    id: "sub2api-auth-me",
-    path: "/api/v1/auth/me",
-    run: fetchSub2ApiAuthMeUsage,
-  },
   "newapi-token": {
     id: "newapi-token",
     path: "/api/usage/token/",
     run: fetchNewApiTokenUsage,
   },
-  "panel-user-self": {
-    id: "panel-user-self",
-    path: "/api/user/self",
-    run: fetchPanelUserSelfUsage,
+  "oneapi-billing": {
+    id: "oneapi-billing",
+    path: "/v1/dashboard/billing/subscription",
+    run: fetchOneApiBillingUsage,
   },
   "openrouter": {
     id: "openrouter",
@@ -214,52 +175,129 @@ const USAGE_ROUTES = {
   },
 };
 
-// Presets are probe-order aliases over the routes above, not separate
-// protocols (e.g. anyrouter/agentrouter just try the NewAPI panel endpoints
-// and /v1/usage in a different order).
-// They do not provide panel session-cookie authentication; only endpoints that
-// accept the configured Bearer key can succeed.
+// User-authored gateway routes, declared in config.jsonc:
+//   "providerUsage": { "routes": ["custom/my-gateway.mjs"] }
+// Paths resolve against ~/.agent-tools. Each module exports
+// `export async function run(context, helpers)` plus an optional
+// `export const meta = { id }` (id defaults to the file name). Broken modules
+// are logged and skipped so a bad custom route cannot break the built-ins.
+const CUSTOM_ROUTE_HELPERS = { requestJson, agentConfig };
+
+let customRoutesPromise;
+function customRoutes() {
+  customRoutesPromise ||= loadCustomRoutes();
+  return customRoutesPromise;
+}
+
+async function loadRouteModule(file, spec) {
+  try {
+    const mod = await import(pathToFileURL(file).href);
+    if (typeof mod.run !== "function") {
+      throw new Error("missing `export async function run(context, helpers)`");
+    }
+    const id = String(mod.meta?.id || basename(file, extname(file)));
+    return {
+      id,
+      path: spec,
+      run: async (context) => {
+        const result = await mod.run(context, CUSTOM_ROUTE_HELPERS);
+        if (typeof result?.text !== "string" || !result.text) {
+          throw new Error(`custom route ${id} returned no text`);
+        }
+        return {
+          updatedAt: new Date().toISOString(),
+          baseUrl: context.baseUrl,
+          provider: context.providerName,
+          source: id,
+          ...result,
+        };
+      },
+    };
+  } catch (error) {
+    await debugLog({ source: "custom-route", file, error: error.message });
+    return null;
+  }
+}
+
+async function loadCustomRoutes() {
+  const routes = [];
+
+  // config-declared routes probe first, in config order.
+  const config = await agentConfig();
+  const specs = Array.isArray(config.routes) ? config.routes : [];
+  for (const spec of specs) {
+    if (typeof spec !== "string" || !spec.trim()) continue;
+    const file = isAbsolute(spec) ? spec : join(AGENT_TOOLS_HOME, spec);
+    const route = await loadRouteModule(file, spec);
+    if (route) routes.push(route);
+  }
+
+  // Repo-shipped routes: the installer replaces this directory from the
+  // package's dist/usage/routes on every install, so a fork can distribute
+  // gateways to everyone under git control. Config-declared ids win.
+  const packagedDir = join(AGENT_TOOLS_HOME, "dist", "usage", "routes");
+  let packaged = [];
+  try {
+    packaged = (await readdir(packagedDir)).filter((n) => n.endsWith(".mjs")).sort();
+  } catch {
+    packaged = [];
+  }
+  for (const name of packaged) {
+    const route = await loadRouteModule(join(packagedDir, name), `dist/usage/routes/${name}`);
+    if (route && !routes.some((existing) => existing.id === route.id)) routes.push(route);
+  }
+
+  return routes;
+}
+
+async function routeRegistry() {
+  const registry = { ...USAGE_ROUTES };
+  for (const route of await customRoutes()) registry[route.id] = route;
+  return registry;
+}
+
+// Presets select API-key usage protocols, not hosted gateway brands.
 async function usageRouteIds(context) {
   const preset = await usagePreset();
   const routes = {
-    "sub2api": ["v1-usage", "sub2api-auth-me"],
+    "sub2api": ["v1-usage"],
     "openai-compatible": ["v1-usage"],
-    "new-api": ["newapi-token", "panel-user-self"],
-    "one-api": ["newapi-token", "panel-user-self"],
-    "onehub": ["newapi-token", "panel-user-self"],
-    "one-hub": ["newapi-token", "panel-user-self"],
-    "donehub": ["newapi-token", "panel-user-self"],
-    "done-hub": ["newapi-token", "panel-user-self"],
-    "veloera": ["panel-user-self", "newapi-token"],
-    "anyrouter": ["newapi-token", "panel-user-self", "v1-usage"],
-    "agentrouter": ["newapi-token", "panel-user-self", "v1-usage"],
+    "new-api": ["newapi-token"],
+    "one-api": ["oneapi-billing"],
     "openrouter": ["openrouter"],
   };
   if (routes[preset]) return routes[preset];
 
-  if (preset !== "auto") return [];
-  if (hostIncludes(context.baseUrl, "openrouter.ai")) return ["openrouter"];
-  return ["v1-usage", "sub2api-auth-me", "newapi-token", "panel-user-self"];
+  // A preset naming a registered route id (built-in or custom) selects it.
+  if (preset !== "auto") return (await routeRegistry())[preset] ? [preset] : [];
+
+  // Declared custom routes probe first, in config order.
+  const customIds = (await customRoutes()).map((route) => route.id);
+  const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai")
+    ? ["openrouter"]
+    : ["v1-usage", "newapi-token", "oneapi-billing"];
+  return [...new Set([...customIds, ...builtinIds])];
 }
 
-async function cachedUsageRoute(context) {
+async function cachedUsageRoute(context, registry) {
   const cache = await readRouteCache();
   const key = usageRouteCacheKey(context.baseUrl);
   const route = cache.routes[key];
-  return route?.route && USAGE_ROUTES[route.route] ? route : null;
+  return route?.route && registry[route.route] ? route : null;
 }
 
 export async function orderedUsageRoutes(context) {
+  const registry = await routeRegistry();
   const routeIds = await usageRouteIds(context);
-  const cached = await cachedUsageRoute(context);
-  if (!cached || !routeIds.includes(cached.route)) return routeIds.map((id) => USAGE_ROUTES[id]).filter(Boolean);
+  const cached = await cachedUsageRoute(context, registry);
+  if (!cached || !routeIds.includes(cached.route)) return routeIds.map((id) => registry[id]).filter(Boolean);
   await debugLog({
     source: "route-cache",
     key: usageRouteCacheKey(context.baseUrl),
     route: cached.route,
-    path: cached.path || USAGE_ROUTES[cached.route]?.path || "",
+    path: cached.path || registry[cached.route]?.path || "",
   });
   return [cached.route, ...routeIds.filter((id) => id !== cached.route)]
-    .map((id) => USAGE_ROUTES[id])
+    .map((id) => registry[id])
     .filter(Boolean);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Reusable Agent Skills and installable integrations (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "engines": {

package/scripts/build.mjs

@@ -37,6 +37,15 @@ const TARGETS = {
   },
 };
 
+// Repo-shipped usage routes (a fork can commit integrations/usage/routes/*.mjs
+// to distribute custom gateways to everyone who installs). Absent upstream.
+const USAGE_ROUTES_DIR = path.join(ROOT, "integrations", "usage", "routes");
+if (fs.existsSync(USAGE_ROUTES_DIR)) {
+  for (const file of fs.readdirSync(USAGE_ROUTES_DIR).filter((n) => n.endsWith(".mjs"))) {
+    TARGETS.usage.entryPoints[`routes/${file.slice(0, -4)}`] = path.join(USAGE_ROUTES_DIR, file);
+  }
+}
+
 for (const [name, { entryPoints, external = [] }] of Object.entries(TARGETS)) {
   const outDir = path.join(DIST, name);
   const stage = path.join(DIST, `.${name}-build-${process.pid}-${Date.now()}`);

package/scripts/install.mjs

@@ -242,6 +242,26 @@ function installRuntimeAssets(opts) {
   }
   console.log(`runtime: ${INSTALL_ROOT}`);
   for (const [src, dest, options] of files) copyRuntimeFile(src, dest, opts.dryRun, options);
+  if (wants(opts, "usage")) syncUsageRoutesDir(opts.dryRun);
+}
+
+// Repo-shipped usage routes are replaced wholesale so routes removed from the
+// repo do not linger (a stale file would still be loaded).
+const SOURCE_USAGE_ROUTES_DIR = path.join(REPO_ROOT, "dist", "usage", "routes");
+const RUNTIME_USAGE_ROUTES_DIR = path.join(INSTALL_ROOT, "dist", "usage", "routes");
+
+function syncUsageRoutesDir(dryRun) {
+  const hasSource = fs.existsSync(SOURCE_USAGE_ROUTES_DIR);
+  if (dryRun) {
+    if (hasSource) {
+      console.log(`  [dry-run] would copy ${SOURCE_USAGE_ROUTES_DIR} -> ${RUNTIME_USAGE_ROUTES_DIR}`);
+    } else if (fs.existsSync(RUNTIME_USAGE_ROUTES_DIR)) {
+      console.log(`  [dry-run] would remove ${RUNTIME_USAGE_ROUTES_DIR}`);
+    }
+    return;
+  }
+  fs.rmSync(RUNTIME_USAGE_ROUTES_DIR, { recursive: true, force: true });
+  if (hasSource) fs.cpSync(SOURCE_USAGE_ROUTES_DIR, RUNTIME_USAGE_ROUTES_DIR, { recursive: true });
 }
 
 function parseArgs(argv) {