@kairyou/agent-tools 0.9.0 → 0.10.1

package/integrations/usage/codex-hook.mjs

@@ -16,6 +16,7 @@ const LOG_PATH = path.join(AGENT_TOOLS_HOME, "logs", "usage-hook.log");
 const TIMEOUT_MS = Number(process.env.AGENT_TOOLS_USAGE_HOOK_TIMEOUT_MS || 4500);
 const MAX_LOG_BYTES = Number(process.env.AGENT_TOOLS_USAGE_HOOK_LOG_BYTES || 256 * 1024);
 const KEEP_LOG_BYTES = 128 * 1024;
+const SILENT = process.argv.includes("--silent");
 
 function hookOut(message) {
   const payload = { continue: true };
@@ -64,6 +65,10 @@ function failureMessage() {
   return `API usage hook failed; see ${LOG_PATH.replace(/\\/g, "/")}`;
 }
 
+function hookFailureOut() {
+  hookOut(SILENT ? "" : failureMessage());
+}
+
 function parseHookJson(stdout) {
   const text = stdout.trim();
   if (!text) return { continue: true };
@@ -73,17 +78,21 @@ function parseHookJson(stdout) {
 async function runUsageScript() {
   if (!fs.existsSync(USAGE_SCRIPT)) {
     logFailure({ reason: "missing usage script", usageScript: USAGE_SCRIPT });
-    hookOut(failureMessage());
+    hookFailureOut();
     return;
   }
 
   const result = await new Promise((resolve) => {
-    const child = spawn(process.execPath, [USAGE_SCRIPT, "hook", "--agent", "codex"], {
-      cwd: process.cwd(),
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"],
-      windowsHide: true,
-    });
+    const child = spawn(
+      process.execPath,
+      [USAGE_SCRIPT, "hook", "--agent", "codex", ...(SILENT ? ["--silent"] : [])],
+      {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      }
+    );
     let stdout = "";
     let stderr = "";
     let settled = false;
@@ -126,7 +135,7 @@ async function runUsageScript() {
       node: process.version,
       platform: `${process.platform} ${os.release()}`,
     });
-    hookOut(failureMessage());
+    hookFailureOut();
     return;
   }
 
@@ -141,7 +150,7 @@ async function runUsageScript() {
       stderr: preview(result.stderr),
       usageScript: USAGE_SCRIPT,
     });
-    hookOut(failureMessage());
+    hookFailureOut();
   }
 }
 
@@ -153,5 +162,5 @@ try {
     error: error?.stack || error?.message || String(error),
     usageScript: USAGE_SCRIPT,
   });
-  hookOut(failureMessage());
+  hookFailureOut();
 }

package/integrations/usage/core.mjs

@@ -7,11 +7,19 @@
 // Everything else lives in ./lib (config, urls, http, cache, format, context,
 // routes) and is bundled into dist/usage/core.mjs at build time.
 
-import { pathToFileURL } from "node:url";
-import { debugLog, usagePreset, snapshotTtlMs } from "./lib/config.mjs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import {
+  debugLog,
+  usagePreset,
+  HOOK_SNAPSHOT_MAX_AGE_MS,
+  REFRESH_INTERVAL_MS,
+} from "./lib/config.mjs";
 import { isOfficialBaseUrl } from "./lib/urls.mjs";
 import {
   readUsageSnapshot,
+  acquireUsageRefreshLease,
+  canRefreshUsage,
   rememberUsageRoute,
   rememberUsageSnapshot,
   rememberRefreshState,
@@ -20,7 +28,7 @@ import { orderedUsageRoutes } from "./lib/routes.mjs";
 import { usageContext, normalizeUsageContext } from "./lib/context.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];
@@ -28,6 +36,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;
@@ -111,30 +121,68 @@ export async function queryProviderUsage(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: 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;
 }
 
 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 };
+    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") {
+      // Explicit request: query directly instead of going through the
+      // background refresh throttle, which would print nothing.
+      const result = await queryAgentProviderUsage(cli.agent);
       textOut(result?.text || "");
     } else if (mode === "hook") {
-      // Hook mode fires on every prompt; serve a fresh snapshot when possible.
-      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/integrations/usage/lib/cache.mjs

@@ -1,9 +1,11 @@
 // On-disk state under ~/.agent-tools/cache: the last working route per
 // gateway, the latest usage snapshot, and refresh bookkeeping.
 
-import { writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { writeFile, mkdir, open, unlink, rename, stat, utimes } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
 import {
+  CACHE_DIR,
   ROUTE_CACHE_PATH,
   SNAPSHOT_PATH,
   REFRESH_STATE_PATH,
@@ -12,104 +14,184 @@ import {
 } from "./config.mjs";
 import { usageRouteCacheKey } from "./urls.mjs";
 
-const ROUTE_CACHE_VERSION = 1;
-const SNAPSHOT_VERSION = 1;
-const REFRESH_STATE_VERSION = 1;
+const CACHE_VERSION = 1;
+const WRITE_LOCK_PATH = join(CACHE_DIR, "usage-cache-write.lock");
 
-export async function readRouteCache() {
+// Every cache file is { version, <field>: { [gatewayKey]: entry } }.
+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]: {} };
   }
 }
 
-export async function rememberUsageRoute(context, route, result) {
+// Read-modify-write serialized across processes: the gateway refresh lock
+// covers only one relay, and skill/CLI queries hold no lock at all, so
+// concurrent writers would otherwise drop each other's entries. The temp file
+// plus rename keeps readers from ever seeing a half-written file.
+async function updateJsonCache(path, field, source, mutate) {
+  const release = await acquireWriteLock();
+  if (!release) {
+    // Losing one update is safer than an unlocked read-modify-write, which
+    // would drop the other gateways' entries. Caches refill on the next run.
+    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: new Date().toISOString(),
-    };
-    await mkdir(dirname(ROUTE_CACHE_PATH), { recursive: true });
-    await writeFile(ROUTE_CACHE_PATH, `${JSON.stringify(cache, null, 2)}\n`);
+    const cache = await readJsonCache(path, field);
+    mutate(cache[field]);
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(cache, null, 2)}\n`);
+    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 : {},
+export async function readRouteCache() {
+  return await readJsonCache(ROUTE_CACHE_PATH, "routes");
+}
+
+export 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: new Date().toISOString(),
     };
-  } catch {
-    return { version: SNAPSHOT_VERSION, items: {} };
-  }
+  });
 }
 
 export async function readUsageSnapshot(context) {
-  const cache = await readSnapshotCache();
+  const cache = await readJsonCache(SNAPSHOT_PATH, "items");
   return cache.items[usageRouteCacheKey(context.baseUrl)] || null;
 }
 
 export 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: new Date().toISOString(),
     };
-    await mkdir(dirname(SNAPSHOT_PATH), { recursive: true });
-    await writeFile(SNAPSHOT_PATH, `${JSON.stringify(cache, null, 2)}\n`);
-  } 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: {} };
-  }
+  });
 }
 
 export 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 mkdir(dirname(REFRESH_STATE_PATH), { recursive: true });
-    await writeFile(REFRESH_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`);
-  } catch (error) {
-    await debugLog({ source: "refresh-state", error: error.message });
+    items[key] = { ...(items[key] || {}), ...patch, baseUrl: context.baseUrl };
+  });
+}
+
+export 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;
+}
+
+// `wx` fails when the file exists, which makes creating it an atomic
+// cross-process lock. Returns a release function, or null when the lock is held.
+//
+// Best-effort, not a guarantee: the holder keeps touching the file so a live
+// holder is unlikely to be declared stale, but a suspended machine, a stalled
+// event loop, or a failing utimes can still make one miss its heartbeat. The
+// owner token on release covers most of what slips through — a takeover that
+// happens between reading the token and unlinking still isn't excluded, and a
+// stale holder's heartbeat can even touch the new owner's file, since utimes
+// works on the path rather than a handle. Good enough for a background usage
+// cache, where the worst case is one duplicated refresh that self-heals.
+async function tryLock(lockPath, staleMs, details = {}) {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const token = randomUUID();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        await handle.writeFile(
+          `${JSON.stringify({ token, pid: process.pid, ...details, startedAt: new Date().toISOString() })}\n`
+        );
+      } finally {
+        await handle.close();
+      }
+      const heartbeat = setInterval(() => {
+        const now = new Date();
+        utimes(lockPath, now, now).catch(() => {});
+      }, Math.max(50, Math.floor(staleMs / 3)));
+      heartbeat.unref(); // must never keep the process alive
+      return async () => {
+        clearInterval(heartbeat);
+        // If we were taken over anyway, the file belongs to someone else and
+        // must survive; this check is why a missed heartbeat is recoverable.
+        try {
+          const held = JSON.parse(await readTextIfExists(lockPath));
+          if (held?.token === token) await unlink(lockPath);
+        } catch {
+          // Unreadable or already gone: nothing of ours left to release.
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST" || attempt > 0) return null;
+      const age = await stat(lockPath).then(
+        ({ mtimeMs }) => Date.now() - mtimeMs,
+        () => Infinity // vanished under us: retry immediately
+      );
+      if (age <= staleMs) return null;
+      // Claim the stale lock by renaming it: rename is atomic, so only one
+      // process wins and nobody deletes a lock another just created.
+      try {
+        const claimed = `${lockPath}.${token}`;
+        await rename(lockPath, claimed);
+        await unlink(claimed).catch(() => {});
+      } catch {
+        return null; // another process claimed it first
+      }
+    }
   }
+  return null;
+}
+
+// One lock per gateway, keyed like the route and snapshot caches, so
+// refreshing one relay never blocks another.
+function refreshLockPath(context) {
+  const key = usageRouteCacheKey(context.baseUrl);
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return join(CACHE_DIR, `usage-refresh-${hash}.lock`);
+}
+
+// The holder keeps its lock warm, so this window mostly decides how soon a
+// crashed refresh is reclaimed rather than how long a slow one may run.
+export async function acquireUsageRefreshLease(context, leaseMs = 60_000) {
+  return await tryLock(refreshLockPath(context), leaseMs, { baseUrl: context.baseUrl });
+}
+
+// Writers wait briefly for each other; null means "skip this write" so a cache
+// update never blocks a background refresh.
+async function acquireWriteLock({ timeoutMs = 500, staleMs = 5_000 } = {}) {
+  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;
 }

package/integrations/usage/lib/config.mjs

@@ -13,9 +13,10 @@ export const AUTH_PATH = join(CODEX_HOME, "auth.json");
 export const CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
 export const AGENT_CONFIG_PATH = join(AGENT_TOOLS_HOME, "config.jsonc");
 export const DEBUG_PATH = join(AGENT_TOOLS_HOME, "logs", "usage-debug.log");
-export const ROUTE_CACHE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-routes.json");
-export const SNAPSHOT_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
-export const REFRESH_STATE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
+export const CACHE_DIR = join(AGENT_TOOLS_HOME, "cache");
+export const ROUTE_CACHE_PATH = join(CACHE_DIR, "usage-routes.json");
+export const SNAPSHOT_PATH = join(CACHE_DIR, "usage-snapshot.json");
+export const REFRESH_STATE_PATH = join(CACHE_DIR, "usage-refresh-state.json");
 export const DEFAULT_USAGE_DAYS = 30;
 export const MAX_USAGE_DAYS = 90;
 export const DEFAULT_NEW_API_QUOTA_SCALE = 500000;
@@ -91,13 +92,13 @@ export async function usagePreset() {
   return String(process.env.PROVIDER_USAGE_PRESET || config.preset || "auto").toLowerCase();
 }
 
-// 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;
-}
+// Timing follows the caller's shape, so it is fixed rather than configurable:
+// the hook never waits on the network (snapshot + background refresh), and
+// every other caller either runs detached or is an explicit user request.
+// Past this age a snapshot is too stale to show instead of nothing.
+export const HOOK_SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
+// Minimum gap between gateway queries, however many hooks fire.
+export const REFRESH_INTERVAL_MS = 60_000;
 
 export async function newApiQuotaScale() {
   const config = await agentConfig();

package/integrations/usage/lib/format.mjs

@@ -6,6 +6,15 @@ import { newApiQuotaScale, providerUsageDays } from "./config.mjs";
 
 const ONE_API_HARD_LIMIT_SENTINEL_USD = 1_000_000;
 
+const 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",
+});
+
 export function pickNumber(obj, keys) {
   for (const key of keys) {
     const value = obj?.[key];
@@ -40,6 +49,45 @@ function shortDate(value) {
   return match ? `${match[2]}-${match[3]}` : "";
 }
 
+function timestampMs(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1000 : value;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function compactDurationUntil(value) {
+  const resetMs = timestampMs(value);
+  if (resetMs === undefined) return "";
+
+  const remainingMs = resetMs - Date.now();
+  if (remainingMs <= 0) return "";
+
+  let seconds = Math.floor(remainingMs / 1000);
+  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) === undefined ? undefined : value;
+}
+
+function weeklyResetAt(subscription) {
+  const startMs = timestampMs(
+    subscription?.[RESET_TIME_FIELDS.SUB2API_SUBSCRIPTION_WEEKLY_START]
+  );
+  return startMs === undefined ? undefined : startMs + 7 * 86400 * 1000;
+}
+
 function hasSubscriptionLimits(root) {
   const sub = root?.subscription || {};
   return [
@@ -163,7 +211,7 @@ export 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 !== undefined) parts.push(`balance ${formatMoney(remaining)}`);
@@ -172,7 +220,7 @@ export function formatOpenRouterLine(data) {
   } else if (used !== undefined) {
     parts.push(`used ${formatMoney(used)}`);
   }
-  if (reset) parts.push(`Reset ${reset}`);
+  if (reset) parts.push(`⟳${reset}`);
 
   if (parts.length === 0) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
@@ -254,8 +302,9 @@ function formatQuotaLimitedLine(root) {
         const window = entry?.window;
         const rateLimit = pickNumber(entry, ["limit"]);
         const rateUsed = pickNumber(entry, ["used"]);
+        const reset = compactDurationUntil(rateLimitResetAt(entry));
         return window && rateLimit !== undefined && rateUsed !== undefined
-          ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}`
+          ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}${reset ? ` ⟳${reset}` : ""}`
           : "";
       })
       .filter(Boolean);
@@ -290,10 +339,13 @@ 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 !== undefined) parts.push(`D ${formatMoney(dailyUsage)}/${formatMoney(dailyLimit)}`);
-  if (weeklyLimit > 0 && weeklyUsage !== undefined) parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}`);
+  if (weeklyLimit > 0 && weeklyUsage !== undefined) {
+    parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}${weeklyReset ? ` ⟳${weeklyReset}` : ""}`);
+  }
   if (monthlyLimit > 0 && monthlyUsage !== undefined) parts.push(`M ${formatMoney(monthlyUsage)}/${formatMoney(monthlyLimit)}`);
   if (expires) parts.push(`Exp ${expires}`);
   return parts.join(" | ");

package/integrations/usage/lib/http.mjs

@@ -4,7 +4,10 @@
 import { createContext, runInContext } from "node:vm";
 import { debugLog } from "./config.mjs";
 
-const REQUEST_TIMEOUT_MS = 5000;
+// No user waits on this request: the hook reads a snapshot and refreshes in a
+// detached process, and skill/CLI queries are explicit. Custom routes can pass
+// their own timeoutMs.
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
 const 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";
@@ -126,7 +129,7 @@ function mergeSetCookiePairs(cookieHeader, setCookieHeaders) {
 }
 
 export 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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Reusable Agent Skills and installable integrations (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,7 @@
   },
   "files": [
     "config.default.jsonc",
+    "docs/",
     "dist/",
     "integrations/",
     "scripts/",