@kairyou/agent-tools 0.8.0 → 0.10.0

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();
@@ -1261,6 +1308,7 @@ async function requestJson(url, options = {}) {
 }
 
 // integrations/usage/lib/format.mjs
+var ONE_API_HARD_LIMIT_SENTINEL_USD = 1e6;
 function pickNumber(obj, keys) {
   for (const key of keys) {
     const value = obj?.[key];
@@ -1344,21 +1392,39 @@ async function formatQuota(data) {
   const keys = Object.keys(root || {}).slice(0, 4).join(", ");
   return keys ? `received (${keys})` : `checked ${unit}`;
 }
-async function formatNewApiTokenLine(data) {
+function newApiTokenQuota(data) {
   const root = usageRoot(data);
   const unlimited = root?.unlimited_quota === true || root?.unlimitedQuota === true;
-  const quota = pickNumber(root, ["quota", "limit", "total_quota", "totalQuota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota", "used"]);
-  let remaining = pickNumber(root, ["remain_quota", "remainQuota", "remaining", "balance"]);
+  const quota = pickNumber(root, [
+    "quota",
+    "limit",
+    "total_quota",
+    "totalQuota",
+    "total_granted",
+    "totalGranted"
+  ]);
+  const used = pickNumber(root, ["used_quota", "usedQuota", "used", "total_used", "totalUsed"]);
+  let remaining = pickNumber(root, [
+    "remain_quota",
+    "remainQuota",
+    "remaining",
+    "balance",
+    "total_available",
+    "totalAvailable"
+  ]);
   if (remaining === void 0 && quota !== void 0 && used !== void 0) {
     remaining = Math.max(0, quota - used);
   }
+  return { unlimited, quota, used, remaining };
+}
+async function formatNewApiTokenLine(data) {
+  const { unlimited, quota, used, remaining } = newApiTokenQuota(data);
   if (!unlimited && quota === void 0 && used === void 0 && remaining === void 0) {
     throw new Error("NewAPI token usage payload has no quota fields");
   }
   const parts = [];
   if (unlimited) parts.push("unlimited");
-  if (remaining !== void 0) parts.push(`balance ${await formatNewApiQuota(remaining)}`);
+  if (!unlimited && remaining !== void 0) parts.push(`balance ${await formatNewApiQuota(remaining)}`);
   if (used !== void 0 && quota !== void 0) {
     parts.push(`used ${await formatNewApiQuota(used)}/${await formatNewApiQuota(quota)}`);
   } else if (used !== void 0) {
@@ -1384,8 +1450,51 @@ function formatOpenRouterLine(data) {
   return parts.join(" | ");
 }
 function formatOneApiBillingLine(limit, used) {
+  if (!hasSpendableOneApiLimit(limit)) return `used ${formatMoney(used)}`;
   return `balance ${formatMoney(Math.max(0, limit - used))} | used ${formatMoney(used)}/${formatMoney(limit)}`;
 }
+function hasSpendableOneApiLimit(limit) {
+  return Number.isFinite(limit) && limit >= 0 && limit < ONE_API_HARD_LIMIT_SENTINEL_USD;
+}
+function effectiveClaudeCodeHubWindow(root, suffix) {
+  const keyLimit = pickNumber(root, [`keyLimit${suffix}Usd`]);
+  if (keyLimit !== void 0 && keyLimit > 0) {
+    return { limit: keyLimit, used: pickNumber(root, [`keyCurrent${suffix}Usd`]) };
+  }
+  const userLimit = pickNumber(root, [`userLimit${suffix}Usd`]);
+  return {
+    limit: userLimit !== void 0 && userLimit > 0 ? userLimit : void 0,
+    used: pickNumber(root, [`userCurrent${suffix}Usd`])
+  };
+}
+function earliestDate(...values) {
+  return values.map((value) => ({ value, time: Date.parse(value) })).filter((entry) => entry.value && Number.isFinite(entry.time)).sort((left, right) => left.time - right.time)[0]?.value;
+}
+function formatClaudeCodeHubLine(data) {
+  const root = usageRoot(data);
+  const windows = [
+    ["5h", "5h"],
+    ["D", "Daily"],
+    ["W", "Weekly"],
+    ["M", "Monthly"],
+    ["T", "Total"]
+  ];
+  const parts = [];
+  for (const [label, suffix] of windows) {
+    const { limit, used } = effectiveClaudeCodeHubWindow(root, suffix);
+    if (limit !== void 0 && used !== void 0) {
+      parts.push(`${label} ${formatMoney(used)}/${formatMoney(limit)}`);
+    }
+  }
+  if (parts.length === 0) {
+    const totalUsed = pickNumber(root, ["keyCurrentTotalUsd", "userCurrentTotalUsd"]);
+    if (totalUsed !== void 0) parts.push(`used ${formatMoney(totalUsed)}`);
+  }
+  const expires = shortDate(earliestDate(root?.expiresAt, root?.userExpiresAt));
+  if (expires) parts.push(`Exp ${expires}`);
+  if (parts.length === 0) throw new Error("Claude Code Hub quota payload has no quota fields");
+  return parts.join(" | ");
+}
 function formatQuotaLimitedLine(root) {
   const quota = root?.quota || {};
   const limit = pickNumber(quota, ["limit", "quota"]);
@@ -1466,13 +1575,7 @@ async function fetchNewApiTokenUsage(context) {
     key: context.key,
     name: "New API token usage"
   });
-  const root = usageRoot(json);
-  const quota = pickNumber(root, ["quota", "limit", "total_quota", "totalQuota"]);
-  const used = pickNumber(root, ["used_quota", "usedQuota", "used"]);
-  let remaining = pickNumber(root, ["remain_quota", "remainQuota", "remaining", "balance"]);
-  if (remaining === void 0 && quota !== void 0 && used !== void 0) {
-    remaining = Math.max(0, quota - used);
-  }
+  const { quota, used, remaining } = newApiTokenQuota(json);
   const scale = await newApiQuotaScale();
   const quotaForWarning = scale ? quota / scale : quota;
   const usedForWarning = scale ? used / scale : used;
@@ -1506,13 +1609,16 @@ async function fetchOneApiBillingUsage(context) {
     throw new Error("One API billing payload has no quota fields");
   }
   const used = usageCents / 100;
+  const spendableLimit = hasSpendableOneApiLimit(limit);
   const normalized = {
-    mode: "quota_limited",
-    quota: {
-      limit,
-      used,
-      remaining: Math.max(0, limit - used)
-    },
+    mode: spendableLimit ? "quota_limited" : "unrestricted",
+    ...spendableLimit ? {
+      quota: {
+        limit,
+        used,
+        remaining: Math.max(0, limit - used)
+      }
+    } : { used },
     unit: "USD",
     source: "oneapi-billing",
     raw: { subscription, usage }
@@ -1524,6 +1630,19 @@ async function fetchOneApiBillingUsage(context) {
     normalized
   );
 }
+async function fetchClaudeCodeHubUsage(context) {
+  const base = cleanBaseUrl(context.baseUrl).replace(/\/api\/v1$/i, "").replace(/\/v1$/i, "");
+  const json = await requestJson(joinUrl(base, "/api/v1/me/quota"), {
+    key: context.key,
+    name: "Claude Code Hub quota"
+  });
+  return usageResult(
+    context,
+    "claude-code-hub",
+    formatClaudeCodeHubLine(json),
+    json
+  );
+}
 async function fetchOpenRouterUsage(context) {
   const base = cleanBaseUrl(context.baseUrl).includes("/api/v1") ? cleanBaseUrl(context.baseUrl) : joinUrl(serviceRoot(context.baseUrl), "/api/v1");
   const endpoints = [
@@ -1562,6 +1681,11 @@ var USAGE_ROUTES = {
     id: "openrouter",
     path: "/api/v1/key",
     run: fetchOpenRouterUsage
+  },
+  "claude-code-hub": {
+    id: "claude-code-hub",
+    path: "/api/v1/me/quota",
+    run: fetchClaudeCodeHubUsage
   }
 };
 var CUSTOM_ROUTE_HELPERS = { requestJson, agentConfig };
@@ -1605,11 +1729,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();
@@ -1617,7 +1741,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;
@@ -1634,12 +1758,15 @@ async function usageRouteIds(context) {
     "openai-compatible": ["v1-usage"],
     "new-api": ["newapi-token"],
     "one-api": ["oneapi-billing"],
-    "openrouter": ["openrouter"]
+    "one-hub": ["oneapi-billing"],
+    "done-hub": ["oneapi-billing"],
+    "openrouter": ["openrouter"],
+    "claude-code-hub": ["claude-code-hub"]
   };
   if (routes[preset]) return routes[preset];
   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"];
+  const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai") ? ["openrouter"] : ["v1-usage", "newapi-token", "oneapi-billing", "claude-code-hub"];
   return [.../* @__PURE__ */ new Set([...customIds, ...builtinIds])];
 }
 async function cachedUsageRoute(context, registry) {
@@ -1768,7 +1895,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];
@@ -1776,6 +1903,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;
@@ -1851,27 +1980,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.
+```