@kairyou/agent-tools 0.5.0 → 0.6.0

package/README.md

@@ -101,8 +101,8 @@ Here `5h` and `w` are Claude's rolling usage windows; `⟳` is the reset countdo
 When a compatible API relay is active, the statusline also appends provider usage.
 
 To choose what appears, edit `statusline.fields` in
-`~/.agent-tools/config.jsonc`. The installer may add new default keys on update;
-it preserves top-of-file comments and existing values.
+`~/.agent-tools/config.jsonc`. Installer updates only add missing default keys
+and never touch your edits or comments.
 
 ### Provider usage
 
@@ -148,6 +148,55 @@ endpoint and key — and tune `providerUsage` in `~/.agent-tools/config.jsonc`:
 }
 ```
 
+#### 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

@@ -96,7 +96,7 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 使用兼容的 API 中转时, statusline 还会追加 provider usage.
 
 如需控制显示项, 修改 `~/.agent-tools/config.jsonc` 里的
-`statusline.fields`. 安装器更新时可能补充新的默认键; 文件顶部注释和已有值会保留.
+`statusline.fields`. 安装器更新时只会补充缺失的默认键, 不会动你的修改和注释.
 
 ### Provider usage
 
@@ -138,6 +138,52 @@ provider 的 `base_url` 和密钥; Claude Code: 读取 `ANTHROPIC_BASE_URL` 与
 }
 ```
 
+#### 自定义网关路由
+
+内置探测覆盖不到的网关(比如 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";
@@ -946,6 +946,10 @@ async function panelUserHeaders() {
     "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();
   const scale = Number(config.newApiQuotaScale || DEFAULT_NEW_API_QUOTA_SCALE);
@@ -1041,6 +1045,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 +1097,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 +1204,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 +1213,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 +1230,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 +1241,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
@@ -1473,14 +1487,16 @@ 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, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), {
+    key: context.key,
     name: "NewAPI token usage"
   });
   const root = usageRoot(json);
@@ -1510,7 +1526,8 @@ async function fetchNewApiTokenUsage(context) {
 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, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/user/self"), {
+    key: context.key,
     name: "panel /api/user/self",
     headers: await panelUserHeaders()
   });
@@ -1547,7 +1564,8 @@ async function fetchPanelUserSelfUsage(context) {
   );
 }
 async function fetchSub2ApiAuthMeUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/v1/auth/me"), context.key, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/v1/auth/me"), {
+    key: context.key,
     name: "Sub2API auth/me"
   });
   const root = usageRoot(json);
@@ -1577,7 +1595,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;
@@ -1613,6 +1631,69 @@ 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 = {
@@ -1630,27 +1711,29 @@ async function usageRouteIds(context) {
     "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", "sub2api-auth-me", "newapi-token", "panel-user-self"];
+  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 +1927,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 +1944,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 +1953,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

@@ -92,6 +92,14 @@ export async function panelUserHeaders() {
   };
 }
 
+// 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() {
   const config = await agentConfig();
   const scale = Number(config.newApiQuotaScale || DEFAULT_NEW_API_QUOTA_SCALE);

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,7 +1,12 @@
 // 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,
@@ -50,7 +55,8 @@ 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");
@@ -61,7 +67,8 @@ async function fetchV1Usage(context) {
 // query token usage from the service root rather than the /v1 OpenAI-compatible
 // path.
 async function fetchNewApiTokenUsage(context) {
-  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), context.key, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/usage/token/"), {
+    key: context.key,
     name: "NewAPI token usage",
   });
   const root = usageRoot(json);
@@ -95,7 +102,8 @@ async function fetchNewApiTokenUsage(context) {
 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, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/user/self"), {
+    key: context.key,
     name: "panel /api/user/self",
     headers: await panelUserHeaders(),
   });
@@ -140,7 +148,8 @@ async function fetchPanelUserSelfUsage(context) {
 // 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, {
+  const json = await requestJson(joinUrl(serviceRoot(context.baseUrl), "/api/v1/auth/me"), {
+    key: context.key,
     name: "Sub2API auth/me",
   });
   const root = usageRoot(json);
@@ -176,7 +185,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;
@@ -214,6 +223,87 @@ const USAGE_ROUTES = {
   },
 };
 
+// User-authored gateway routes, declared in config.jsonc:
+//   "providerUsage": { "routes": ["custom/anyrouter.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 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).
@@ -237,29 +327,36 @@ async function usageRouteIds(context) {
   };
   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", "sub2api-auth-me", "newapi-token", "panel-user-self"];
+  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.0",
+  "version": "0.6.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

@@ -102,40 +102,6 @@ function nodeCmd(absScript) {
   return `node "${fwd(absScript)}"`;
 }
 
-function stripJsonComments(input) {
-  let out = "";
-  let inString = false;
-  let escaped = false;
-  for (let i = 0; i < input.length; i++) {
-    const ch = input[i];
-    const next = input[i + 1];
-    if (inString) {
-      out += ch;
-      escaped = ch === "\\" ? !escaped : false;
-      if (ch === "\"" && !escaped) inString = false;
-      continue;
-    }
-    if (ch === "\"") {
-      inString = true;
-      out += ch;
-      continue;
-    }
-    if (ch === "/" && next === "/") {
-      while (i < input.length && input[i] !== "\n") i++;
-      out += "\n";
-      continue;
-    }
-    if (ch === "/" && next === "*") {
-      i += 2;
-      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
-      i++;
-      continue;
-    }
-    out += ch;
-  }
-  return out;
-}
-
 function readJsonc(file) {
   if (!fs.existsSync(file)) return {};
   const raw = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");
@@ -146,31 +112,6 @@ function readJsonc(file) {
   return parsed ?? {};
 }
 
-function headerComments(text) {
-  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
-  const header = [];
-  for (const line of lines) {
-    if (/^\s*(?:\/\/.*)?$/.test(line)) {
-      header.push(line);
-      continue;
-    }
-    break;
-  }
-  return header.length ? header.join("\n").replace(/\s+$/, "") + "\n" : "";
-}
-
-function mergeDefaults(target, defaults) {
-  if (Array.isArray(defaults)) return target === undefined ? defaults : target;
-  if (!defaults || typeof defaults !== "object") {
-    return target === undefined ? defaults : target;
-  }
-  const out = target && typeof target === "object" && !Array.isArray(target) ? { ...target } : {};
-  for (const [key, value] of Object.entries(defaults)) {
-    out[key] = mergeDefaults(out[key], value);
-  }
-  return out;
-}
-
 function writeText(file, text, dryRun) {
   if (dryRun) {
     console.log(`  [dry-run] would write ${file}:`);
@@ -215,23 +156,46 @@ function updateOpenCodeTuiConfig(file, { remove, dryRun }) {
   writeText(file, updated, dryRun);
 }
 
+// Keys present in defaults but absent in current, as jsonc-parser edit paths.
+function missingDefaultPaths(current, defaults, basePath = []) {
+  const out = [];
+  for (const [key, value] of Object.entries(defaults)) {
+    const existing = current?.[key];
+    if (existing === undefined) {
+      out.push({ path: [...basePath, key], value });
+    } else if (
+      value && typeof value === "object" && !Array.isArray(value) &&
+      existing && typeof existing === "object" && !Array.isArray(existing)
+    ) {
+      out.push(...missingDefaultPaths(existing, value, [...basePath, key]));
+    }
+  }
+  return out;
+}
+
+// Updates only add missing default keys via surgical jsonc-parser edits, so
+// the user's comments, formatting, and key order survive installer updates.
 function mergeJsoncFile(src, dest, dryRun) {
-  const defaults = readJsonc(src);
-  const defaultHeader = headerComments(fs.readFileSync(src, "utf8"));
-  if (!fs.existsSync(dest)) {
+  if (!fs.existsSync(dest) || !fs.readFileSync(dest, "utf8").trim()) {
     writeText(dest, fs.readFileSync(src, "utf8"), dryRun);
     return;
   }
+  const defaults = readJsonc(src);
   const currentText = fs.readFileSync(dest, "utf8");
-  const current = readJsonc(dest);
-  const merged = mergeDefaults(current, defaults);
-  const currentHeader = headerComments(currentText) || defaultHeader;
-  const mergedText = currentHeader + JSON.stringify(merged, null, 2) + "\n";
-  if (stripJsonComments(currentText).trim() === JSON.stringify(merged, null, 2)) {
+  const additions = missingDefaultPaths(readJsonc(dest), defaults);
+  if (additions.length === 0) {
     console.log(`  kept existing ${dest}`);
     return;
   }
-  writeText(dest, mergedText, dryRun);
+  const eol = currentText.includes("\r\n") ? "\r\n" : "\n";
+  let updated = currentText;
+  for (const { path: keyPath, value } of additions) {
+    const edits = modify(updated, keyPath, value, {
+      formattingOptions: { insertSpaces: true, tabSize: 2, eol },
+    });
+    updated = applyEdits(updated, edits);
+  }
+  writeText(dest, updated, dryRun);
 }
 
 function copyRuntimeFile(src, dest, dryRun, options = {}) {
@@ -278,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) {