@kairyou/agent-tools 0.9.0 → 0.10.1

package/dist/usage/core.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // integrations/usage/core.mjs
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
+import { spawn } from "node:child_process";
 
 // integrations/usage/lib/config.mjs
 import { readFile, writeFile, mkdir, open, stat } from "node:fs/promises";
@@ -875,9 +876,10 @@ var AUTH_PATH = join(CODEX_HOME, "auth.json");
 var CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
 var AGENT_CONFIG_PATH = join(AGENT_TOOLS_HOME, "config.jsonc");
 var DEBUG_PATH = join(AGENT_TOOLS_HOME, "logs", "usage-debug.log");
-var ROUTE_CACHE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-routes.json");
-var SNAPSHOT_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
-var REFRESH_STATE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
+var CACHE_DIR = join(AGENT_TOOLS_HOME, "cache");
+var ROUTE_CACHE_PATH = join(CACHE_DIR, "usage-routes.json");
+var SNAPSHOT_PATH = join(CACHE_DIR, "usage-snapshot.json");
+var REFRESH_STATE_PATH = join(CACHE_DIR, "usage-refresh-state.json");
 var DEFAULT_USAGE_DAYS = 30;
 var MAX_USAGE_DAYS = 90;
 var DEFAULT_NEW_API_QUOTA_SCALE = 5e5;
@@ -944,10 +946,8 @@ async function usagePreset() {
   const config = await agentConfig();
   return String(process.env.PROVIDER_USAGE_PRESET || config.preset || "auto").toLowerCase();
 }
-function snapshotTtlMs() {
-  const raw = Number(process.env.AGENT_TOOLS_USAGE_SNAPSHOT_TTL_MS);
-  return Number.isFinite(raw) && raw >= 0 ? raw : 6e4;
-}
+var HOOK_SNAPSHOT_MAX_AGE_MS = 10 * 6e4;
+var REFRESH_INTERVAL_MS = 6e4;
 async function newApiQuotaScale() {
   const config = await agentConfig();
   const scale = Number(config.newApiQuotaScale || DEFAULT_NEW_API_QUOTA_SCALE);
@@ -995,114 +995,161 @@ function hostIncludes(baseUrl, value) {
 }
 
 // integrations/usage/lib/cache.mjs
-import { writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
-import { dirname as dirname2 } from "node:path";
-var ROUTE_CACHE_VERSION = 1;
-var SNAPSHOT_VERSION = 1;
-var REFRESH_STATE_VERSION = 1;
-async function readRouteCache() {
+import { writeFile as writeFile2, mkdir as mkdir2, open as open2, unlink, rename, stat as stat2, utimes } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname as dirname2, join as join2 } from "node:path";
+var CACHE_VERSION = 1;
+var WRITE_LOCK_PATH = join2(CACHE_DIR, "usage-cache-write.lock");
+async function readJsonCache(path, field) {
   try {
-    const raw = await readTextIfExists(ROUTE_CACHE_PATH);
-    if (!raw.trim()) return { version: ROUTE_CACHE_VERSION, routes: {} };
-    const parsed = JSON.parse(raw);
+    const raw = await readTextIfExists(path);
+    const entries = raw.trim() ? JSON.parse(raw)?.[field] : null;
     return {
-      version: ROUTE_CACHE_VERSION,
-      routes: parsed?.routes && typeof parsed.routes === "object" ? parsed.routes : {}
+      version: CACHE_VERSION,
+      [field]: entries && typeof entries === "object" ? entries : {}
     };
   } catch {
-    return { version: ROUTE_CACHE_VERSION, routes: {} };
+    return { version: CACHE_VERSION, [field]: {} };
   }
 }
-async function rememberUsageRoute(context, route, result) {
+async function updateJsonCache(path, field, source, mutate) {
+  const release = await acquireWriteLock();
+  if (!release) {
+    await debugLog({ source, skipped: "cache write lock unavailable" });
+    return;
+  }
   try {
-    const cache = await readRouteCache();
-    const key = usageRouteCacheKey(context.baseUrl);
-    cache.routes[key] = {
-      route: route.id,
-      path: route.path,
-      source: result.source,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    await mkdir2(dirname2(ROUTE_CACHE_PATH), { recursive: true });
-    await writeFile2(ROUTE_CACHE_PATH, `${JSON.stringify(cache, null, 2)}
+    const cache = await readJsonCache(path, field);
+    mutate(cache[field]);
+    await mkdir2(dirname2(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile2(temp, `${JSON.stringify(cache, null, 2)}
 `);
+    await rename(temp, path);
   } catch (error) {
-    await debugLog({ source: "route-cache", error: error.message });
+    await debugLog({ source, error: error.message });
+  } finally {
+    await release();
   }
 }
-async function readSnapshotCache() {
-  try {
-    const raw = await readTextIfExists(SNAPSHOT_PATH);
-    if (!raw.trim()) return { version: SNAPSHOT_VERSION, items: {} };
-    const parsed = JSON.parse(raw);
-    return {
-      version: SNAPSHOT_VERSION,
-      items: parsed?.items && typeof parsed.items === "object" ? parsed.items : {}
+async function readRouteCache() {
+  return await readJsonCache(ROUTE_CACHE_PATH, "routes");
+}
+async function rememberUsageRoute(context, route, result) {
+  await updateJsonCache(ROUTE_CACHE_PATH, "routes", "route-cache", (routes) => {
+    routes[usageRouteCacheKey(context.baseUrl)] = {
+      route: route.id,
+      path: route.path,
+      source: result.source,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-  } catch {
-    return { version: SNAPSHOT_VERSION, items: {} };
-  }
+  });
 }
 async function readUsageSnapshot(context) {
-  const cache = await readSnapshotCache();
+  const cache = await readJsonCache(SNAPSHOT_PATH, "items");
   return cache.items[usageRouteCacheKey(context.baseUrl)] || null;
 }
 async function rememberUsageSnapshot(context, result) {
   if (!result?.text) return;
-  try {
-    const cache = await readSnapshotCache();
-    const key = usageRouteCacheKey(context.baseUrl);
-    cache.items[key] = {
+  await updateJsonCache(SNAPSHOT_PATH, "items", "snapshot-cache", (items) => {
+    items[usageRouteCacheKey(context.baseUrl)] = {
       text: result.text,
       source: result.source,
       baseUrl: context.baseUrl,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    await mkdir2(dirname2(SNAPSHOT_PATH), { recursive: true });
-    await writeFile2(SNAPSHOT_PATH, `${JSON.stringify(cache, null, 2)}
-`);
-  } catch (error) {
-    await debugLog({ source: "snapshot-cache", error: error.message });
-  }
-}
-async function readRefreshState() {
-  try {
-    const raw = await readTextIfExists(REFRESH_STATE_PATH);
-    if (!raw.trim()) return { version: REFRESH_STATE_VERSION, items: {} };
-    const parsed = JSON.parse(raw);
-    return {
-      version: REFRESH_STATE_VERSION,
-      items: parsed?.items && typeof parsed.items === "object" ? parsed.items : {}
-    };
-  } catch {
-    return { version: REFRESH_STATE_VERSION, items: {} };
-  }
+  });
 }
 async function rememberRefreshState(context, patch) {
-  try {
-    const state = await readRefreshState();
+  await updateJsonCache(REFRESH_STATE_PATH, "items", "refresh-state", (items) => {
     const key = usageRouteCacheKey(context.baseUrl);
-    state.items[key] = {
-      ...state.items[key] || {},
-      ...patch,
-      baseUrl: context.baseUrl
-    };
-    await mkdir2(dirname2(REFRESH_STATE_PATH), { recursive: true });
-    await writeFile2(REFRESH_STATE_PATH, `${JSON.stringify(state, null, 2)}
-`);
-  } catch (error) {
-    await debugLog({ source: "refresh-state", error: error.message });
+    items[key] = { ...items[key] || {}, ...patch, baseUrl: context.baseUrl };
+  });
+}
+async function canRefreshUsage(context, minIntervalMs) {
+  if (minIntervalMs <= 0) return true;
+  const state = await readJsonCache(REFRESH_STATE_PATH, "items");
+  const item = state.items[usageRouteCacheKey(context.baseUrl)] || {};
+  const latest = Math.max(
+    ...[item.lastStartedAt, item.lastSuccessAt, item.lastFailureAt].map((value) => Date.parse(value || "")).filter(Number.isFinite),
+    0
+  );
+  return latest === 0 || Date.now() - latest >= minIntervalMs;
+}
+async function tryLock(lockPath, staleMs, details = {}) {
+  await mkdir2(dirname2(lockPath), { recursive: true });
+  const token = randomUUID();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await open2(lockPath, "wx");
+      try {
+        await handle.writeFile(
+          `${JSON.stringify({ token, pid: process.pid, ...details, startedAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`
+        );
+      } finally {
+        await handle.close();
+      }
+      const heartbeat = setInterval(() => {
+        const now = /* @__PURE__ */ new Date();
+        utimes(lockPath, now, now).catch(() => {
+        });
+      }, Math.max(50, Math.floor(staleMs / 3)));
+      heartbeat.unref();
+      return async () => {
+        clearInterval(heartbeat);
+        try {
+          const held = JSON.parse(await readTextIfExists(lockPath));
+          if (held?.token === token) await unlink(lockPath);
+        } catch {
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST" || attempt > 0) return null;
+      const age = await stat2(lockPath).then(
+        ({ mtimeMs }) => Date.now() - mtimeMs,
+        () => Infinity
+        // vanished under us: retry immediately
+      );
+      if (age <= staleMs) return null;
+      try {
+        const claimed = `${lockPath}.${token}`;
+        await rename(lockPath, claimed);
+        await unlink(claimed).catch(() => {
+        });
+      } catch {
+        return null;
+      }
+    }
   }
+  return null;
+}
+function refreshLockPath(context) {
+  const key = usageRouteCacheKey(context.baseUrl);
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return join2(CACHE_DIR, `usage-refresh-${hash}.lock`);
+}
+async function acquireUsageRefreshLease(context, leaseMs = 6e4) {
+  return await tryLock(refreshLockPath(context), leaseMs, { baseUrl: context.baseUrl });
+}
+async function acquireWriteLock({ timeoutMs = 500, staleMs = 5e3 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const release = await tryLock(WRITE_LOCK_PATH, staleMs);
+    if (release) return release;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  } while (Date.now() < deadline);
+  return null;
 }
 
 // integrations/usage/lib/routes.mjs
 import { readdir } from "node:fs/promises";
-import { basename, extname, isAbsolute, join as join2 } from "node:path";
+import { basename, extname, isAbsolute, join as join3 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // integrations/usage/lib/http.mjs
 import { createContext, runInContext } from "node:vm";
-var REQUEST_TIMEOUT_MS = 5e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var SHIELD_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36";
 function shortPreview(text) {
   return String(text || "").replace(/\s+/g, " ").trim().slice(0, 220);
@@ -1203,7 +1250,7 @@ function mergeSetCookiePairs(cookieHeader, setCookieHeaders) {
   return merged;
 }
 async function requestJson(url, options = {}) {
-  const { key = "", headers = {}, name = "usage", timeoutMs = REQUEST_TIMEOUT_MS } = options;
+  const { key = "", headers = {}, name = "usage", timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = options;
   let cookieHeader = "";
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const controller = new AbortController();
@@ -1262,6 +1309,14 @@ async function requestJson(url, options = {}) {
 
 // integrations/usage/lib/format.mjs
 var ONE_API_HARD_LIMIT_SENTINEL_USD = 1e6;
+var RESET_TIME_FIELDS = Object.freeze({
+  // Sub2API rate-limit entries returned alongside quota usage.
+  SUB2API_RATE_LIMIT: "reset_at",
+  // Sub2API /v1/usage response: subscription weekly-window anchor.
+  SUB2API_SUBSCRIPTION_WEEKLY_START: "weekly_window_start",
+  // OpenRouter /api/v1/key response: absolute key-limit reset.
+  OPENROUTER_KEY_LIMIT: "limit_reset"
+});
 function pickNumber(obj, keys) {
   for (const key of keys) {
     const value = obj?.[key];
@@ -1290,6 +1345,39 @@ function shortDate(value) {
   const match = String(value).match(/^(\d{4})-(\d{2})-(\d{2})/);
   return match ? `${match[2]}-${match[3]}` : "";
 }
+function timestampMs(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1e3 : value;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function compactDurationUntil(value) {
+  const resetMs = timestampMs(value);
+  if (resetMs === void 0) return "";
+  const remainingMs = resetMs - Date.now();
+  if (remainingMs <= 0) return "";
+  let seconds = Math.floor(remainingMs / 1e3);
+  if (seconds <= 0) return "0m";
+  const days = Math.floor(seconds / 86400);
+  seconds %= 86400;
+  const hours = Math.floor(seconds / 3600);
+  seconds %= 3600;
+  const minutes = Math.floor(seconds / 60);
+  if (days) return `${days}d${hours}h`;
+  if (hours) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+function rateLimitResetAt(entry) {
+  const value = entry?.[RESET_TIME_FIELDS.SUB2API_RATE_LIMIT];
+  return timestampMs(value) === void 0 ? void 0 : value;
+}
+function weeklyResetAt(subscription) {
+  const startMs = timestampMs(
+    subscription?.[RESET_TIME_FIELDS.SUB2API_SUBSCRIPTION_WEEKLY_START]
+  );
+  return startMs === void 0 ? void 0 : startMs + 7 * 86400 * 1e3;
+}
 function hasSubscriptionLimits(root) {
   const sub = root?.subscription || {};
   return [
@@ -1390,7 +1478,7 @@ function formatOpenRouterLine(data) {
   const limit = pickNumber(root, ["limit", "limit_remaining", "total_credits"]);
   const remaining = pickNumber(root, ["limit_remaining", "remaining_credits"]);
   const used = pickNumber(root, ["usage", "total_usage", "spend"]);
-  const reset = root?.limit_reset || root?.reset_at ? shortDate(root.limit_reset || root.reset_at) : "";
+  const reset = compactDurationUntil(root?.[RESET_TIME_FIELDS.OPENROUTER_KEY_LIMIT]);
   const parts = [];
   if (remaining !== void 0) parts.push(`balance ${formatMoney(remaining)}`);
   if (used !== void 0 && limit !== void 0 && limit !== remaining) {
@@ -1398,7 +1486,7 @@ function formatOpenRouterLine(data) {
   } else if (used !== void 0) {
     parts.push(`used ${formatMoney(used)}`);
   }
-  if (reset) parts.push(`Reset ${reset}`);
+  if (reset) parts.push(`\u27F3${reset}`);
   if (parts.length === 0) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
 }
@@ -1464,7 +1552,8 @@ function formatQuotaLimitedLine(root) {
       const window = entry?.window;
       const rateLimit = pickNumber(entry, ["limit"]);
       const rateUsed = pickNumber(entry, ["used"]);
-      return window && rateLimit !== void 0 && rateUsed !== void 0 ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}` : "";
+      const reset = compactDurationUntil(rateLimitResetAt(entry));
+      return window && rateLimit !== void 0 && rateUsed !== void 0 ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}${reset ? ` \u27F3${reset}` : ""}` : "";
     }).filter(Boolean);
     if (rateParts.length > 0) parts.push(rateParts.join(", "));
   }
@@ -1491,9 +1580,12 @@ function formatUsageLine(root) {
   const monthlyLimit = pickNumber(sub, ["monthly_limit_usd"]);
   const monthlyUsage = pickNumber(sub, ["monthly_usage_usd"]);
   const expires = shortDate(sub.expires_at);
+  const weeklyReset = compactDurationUntil(weeklyResetAt(sub));
   const parts = [];
   if (dailyLimit > 0 && dailyUsage !== void 0) parts.push(`D ${formatMoney(dailyUsage)}/${formatMoney(dailyLimit)}`);
-  if (weeklyLimit > 0 && weeklyUsage !== void 0) parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}`);
+  if (weeklyLimit > 0 && weeklyUsage !== void 0) {
+    parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}${weeklyReset ? ` \u27F3${weeklyReset}` : ""}`);
+  }
   if (monthlyLimit > 0 && monthlyUsage !== void 0) parts.push(`M ${formatMoney(monthlyUsage)}/${formatMoney(monthlyLimit)}`);
   if (expires) parts.push(`Exp ${expires}`);
   return parts.join(" | ");
@@ -1682,11 +1774,11 @@ async function loadCustomRoutes() {
   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 file = isAbsolute(spec) ? spec : join3(AGENT_TOOLS_HOME, spec);
     const route = await loadRouteModule(file, spec);
     if (route) routes.push(route);
   }
-  const packagedDir = join2(AGENT_TOOLS_HOME, "dist", "usage", "routes");
+  const packagedDir = join3(AGENT_TOOLS_HOME, "dist", "usage", "routes");
   let packaged = [];
   try {
     packaged = (await readdir(packagedDir)).filter((n) => n.endsWith(".mjs")).sort();
@@ -1694,7 +1786,7 @@ async function loadCustomRoutes() {
     packaged = [];
   }
   for (const name of packaged) {
-    const route = await loadRouteModule(join2(packagedDir, name), `dist/usage/routes/${name}`);
+    const route = await loadRouteModule(join3(packagedDir, name), `dist/usage/routes/${name}`);
     if (route && !routes.some((existing) => existing.id === route.id)) routes.push(route);
   }
   return routes;
@@ -1848,7 +1940,7 @@ function normalizeUsageContext(input) {
 
 // integrations/usage/core.mjs
 function parseArgs(argv) {
-  const opts = { mode: "hook", agent: "codex" };
+  const opts = { mode: "hook", agent: "codex", silent: false };
   let modeSet = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -1856,6 +1948,8 @@ function parseArgs(argv) {
       opts.agent = argv[++i];
     } else if (arg.startsWith("--agent=")) {
       opts.agent = arg.slice("--agent=".length);
+    } else if (arg === "--silent") {
+      opts.silent = true;
     } else if (!arg.startsWith("-") && !modeSet) {
       opts.mode = arg;
       modeSet = true;
@@ -1931,27 +2025,59 @@ async function queryProviderUsage(input, options = {}) {
   return await queryUsageContext(normalizeUsageContext(input), options);
 }
 async function refresh(agent = "codex") {
-  return await queryAgentProviderUsage(agent);
+  const context = await usageContext(agent);
+  const release = await acquireUsageRefreshLease(context);
+  if (!release) return { skipped: true, text: "" };
+  try {
+    if (!await canRefreshUsage(context, REFRESH_INTERVAL_MS)) return { skipped: true, text: "" };
+    await rememberRefreshState(context, { lastStartedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    return await queryUsageContext(context, { agent, rememberSnapshot: true });
+  } finally {
+    await release();
+  }
+}
+async function cachedUsage(context) {
+  const cached = await readUsageSnapshot(context);
+  const ageMs = cached?.updatedAt ? Date.now() - Date.parse(cached.updatedAt) : Infinity;
+  return cached?.text && Number.isFinite(ageMs) ? { ...cached, ageMs } : null;
 }
 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 };
+    const cached = await cachedUsage(context);
+    if (cached && cached.ageMs < maxAgeMs) return { ...cached, cached: true };
   }
   return await queryUsageContext(context, { agent, rememberSnapshot: true });
 }
+function scheduleRefresh(agent) {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "refresh", "--agent", agent], {
+    cwd: process.cwd(),
+    env: process.env,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+async function hook(agent, { silent = false } = {}) {
+  const context = await usageContext(agent);
+  const cached = await cachedUsage(context);
+  if ((!cached || cached.ageMs >= REFRESH_INTERVAL_MS) && await canRefreshUsage(context, REFRESH_INTERVAL_MS)) {
+    scheduleRefresh(agent);
+  }
+  hookOut(silent ? "" : cached && cached.ageMs < HOOK_SNAPSHOT_MAX_AGE_MS ? cached.text : "");
+}
 async function main() {
   try {
     if (mode === "refresh") {
       await refresh(cli.agent);
-    } else if (mode === "print" || mode === "print-or-refresh") {
-      const result = await refresh(cli.agent);
+    } else if (mode === "print") {
+      const result = await queryAgentProviderUsage(cli.agent);
       textOut(result?.text || "");
     } else if (mode === "hook") {
-      const result = await queryAgentProviderUsage(cli.agent, { maxAgeMs: snapshotTtlMs() });
-      hookOut(result?.text || "");
+      await hook(cli.agent, { silent: cli.silent });
     } else {
       throw new Error(`unknown mode: ${mode}`);
     }

package/docs/en/custom-gateway-routes.md

@@ -0,0 +1,53 @@
+# Custom gateway routes
+
+Advanced guide for [provider usage](../../README.md#provider-usage): write your own
+usage probe for relays the built-in presets cannot reach (e.g. cookie-authenticated
+gateways) without modifying package code.
+
+## Declare a route
+
+Write a route module and list 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": "..." }
+  }
+}
+```
+
+## Route module API
+
+```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
+
+  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();
+
+  // requestJson parses JSON and throws on non-2xx responses; pass custom
+  // authorization or cookie headers here when needed.
+  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
+    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
+  });
+  return { text: `balance ¥${me?.data?.balance}` };
+}
+```
+
+`text` is a free-form string; return `{ text }` on success, throw to fall through
+to the next route. Enable `providerUsage.debug` to log probe failures to
+`~/.agent-tools/logs/usage-debug.log`.

package/docs/en/repository-structure.md

@@ -0,0 +1,20 @@
+# Repository structure
+
+```text
+agent-tools/
+├── .claude-plugin/    # Claude Code/plugin ecosystem manifest.
+├── .codex-plugin/     # Codex plugin manifest.
+├── integrations/      # Installable capabilities, one directory each.
+│   ├── statusline/    # Agent status line: branch, model, usage.
+│   ├── usage/         # Provider balance / quota display.
+│   └── vision/        # Cross-model image understanding.
+├── skills/            # Reusable Agent Skills.
+│   ├── workflow/      # Workflow-oriented skills.
+│   │   ├── at-commit/   # Conventional Commit message skill.
+│   │   ├── at-review/   # Review changes for bugs and regressions.
+│   │   └── at-simplify/ # Reduce complexity and duplication in changes.
+│   └── integrations/  # Skills that integrate external systems.
+│       └── at-zentao/   # ZenTao bug/task fixing workflow.
+├── docs/              # Advanced guides and contributor reference.
+└── scripts/           # Install, sync, validation, and maintenance scripts.
+```

package/docs/zh-CN/custom-gateway-routes.md

@@ -0,0 +1,47 @@
+# 自定义网关路由
+
+[Provider usage](../../README.zh-CN.md#provider-usage) 的高级指南: 为内置 preset 覆盖不到的中转(比如 cookie 认证的网关)编写自己的用量探测, 无需修改包内代码.
+
+## 声明路由
+
+编写路由模块, 并在 `providerUsage.routes` 里声明(相对 `~/.agent-tools` 解析). 声明的路由优先探测; `"preset"` 填路由 id 可直接选中.
+
+```jsonc
+{
+  "providerUsage": {
+    "routes": [
+      "custom/my-gateway.mjs",
+      "custom/another-gateway.mjs"
+    ],
+    "myGateway": { "username": "me", "password": "..." }
+  }
+}
+```
+
+## 路由模块 API
+
+```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 对象, 自定义键随意加
+
+  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();
+
+  // requestJson 会解析 JSON, 并在非 2xx 响应时抛错; 需要时可在这里传入
+  // authorization、cookie 等自定义认证 header.
+  const me = await requestJson(`${context.baseUrl}/api/user/self`, {
+    headers: { authorization: `Bearer ${session?.data?.accessToken}` },
+  });
+  return { text: `balance ¥${me?.data?.balance}` };
+}
+```
+
+`text` 是自由字符串; 成功返回 `{ text }`, 抛错则回落到下一条路由. 开启 `providerUsage.debug` 后, 探测失败会记录到 `~/.agent-tools/logs/usage-debug.log`.

package/docs/zh-CN/repository-structure.md

@@ -0,0 +1,20 @@
+# 仓库结构
+
+```text
+agent-tools/
+├── .claude-plugin/    # Claude Code/plugin 生态的 manifest.
+├── .codex-plugin/     # Codex plugin manifest.
+├── integrations/      # 可安装的 capability, 一个一目录.
+│   ├── statusline/    # Agent 状态栏: 分支, 模型, 用量.
+│   ├── usage/         # Provider 余额/额度显示.
+│   └── vision/        # 跨模型识图.
+├── skills/            # 可复用的 Agent Skills.
+│   ├── workflow/      # 工作流类 skills.
+│   │   ├── at-commit/   # 生成 Conventional Commits message.
+│   │   ├── at-review/   # 审查改动中的 bug 与回归风险.
+│   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
+│   └── integrations/  # 对接外部系统的 skills.
+│       └── at-zentao/   # 禅道 bug/task 修复工作流.
+├── docs/              # 高级指南和贡献者参考.
+└── scripts/           # 安装, 同步, 校验和仓库维护脚本.
+```