@kairyou/agent-tools 0.9.0 → 0.10.0

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/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.0",
   "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/",

package/scripts/install.mjs

@@ -57,6 +57,15 @@ const INSTALL_ROOT =
   process.env.AGENT_TOOLS_HOME || path.join(os.homedir(), ".agent-tools");
 const META_KEY = "_agentTools";
 const META_VERSION = 1;
+// Stamped into install-state.json so a later install can tell which release
+// wrote the current layout. Purely informational today.
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")).version || "";
+  } catch {
+    return "";
+  }
+})();
 // Everything copied into ~/.agent-tools is built output from dist/ (see
 // scripts/build.mjs); integrations/ holds the sources.
 const SOURCE = {
@@ -395,14 +404,13 @@ function removeFile(file, dryRun) {
   console.log(`  removed ${file}`);
 }
 
-function usageEntry() {
+function usageEntry({ silent = false } = {}) {
   return {
     hooks: [
       {
         type: "command",
-        command: nodeCmd(RUNTIME.codexUsageHook),
+        command: `${nodeCmd(RUNTIME.codexUsageHook)}${silent ? " --silent" : ""}`,
         timeout: 5,
-        statusMessage: "Refreshing API usage",
       },
     ],
   };
@@ -433,7 +441,7 @@ function applyProviderUsage(cfg, { remove }) {
     }
     cfg.hooks[event] = cfg.hooks[event] || [];
     cfg.hooks[event] = cfg.hooks[event].filter((entry) => !isOurProviderUsageEntry(entry));
-    cfg.hooks[event].push(usageEntry());
+    cfg.hooks[event].push(usageEntry({ silent: event === "UserPromptSubmit" }));
   }
   if (Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
 }
@@ -631,6 +639,7 @@ function managedSkillStatus(dest, identity) {
 
 function recordManagedSkill(dest, identity) {
   const state = readInstallState();
+  state.packageVersion = PACKAGE_VERSION;
   state.artifacts[skillManifestKey(dest)] = {
     path: fwd(path.resolve(dest)),
     ...identity,

package/scripts/publish.mjs

@@ -41,8 +41,12 @@ if (typeof PACKAGE_NAME !== "string" || PACKAGE_NAME.trim() === "") {
 }
 
 function runNpm(args, { capture = false, allowFailure = false } = {}) {
-  const npmExecPath = process.env.npm_execpath;
-  const command = npmExecPath ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+  // npm run sets npm_execpath. When invoked directly (`node scripts/...`), find
+  // the bundled npm-cli.js next to node — spawning npm.cmd fails on Node 22+.
+  // Version-manager layouts may not have it there, so fall back to PATH.
+  const bundledNpm = path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  const npmExecPath = process.env.npm_execpath || (fs.existsSync(bundledNpm) ? bundledNpm : undefined);
+  const command = npmExecPath ? process.execPath : "npm";
   const commandArgs = npmExecPath ? [npmExecPath, ...args] : args;
   const result = spawnSync(command, commandArgs, {
     cwd: ROOT,

package/scripts/release.mjs

@@ -78,12 +78,14 @@ function run(command, args, { label, onFailure } = {}) {
 }
 
 function runNpm(args) {
-  const npmExecPath = process.env.npm_execpath;
-  if (npmExecPath) {
-    run(process.execPath, [npmExecPath, ...args], { label: `npm ${args.join(" ")}` });
-  } else {
-    run(process.platform === "win32" ? "npm.cmd" : "npm", args);
-  }
+  // npm run sets npm_execpath. When invoked directly (`node scripts/...`), find
+  // the bundled npm-cli.js next to node — spawning npm.cmd fails on Node 22+.
+  // Version-manager layouts may not have it there, so fall back to PATH.
+  const bundledNpm = path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  const npmExecPath = process.env.npm_execpath || (fs.existsSync(bundledNpm) ? bundledNpm : undefined);
+  const command = npmExecPath ? process.execPath : "npm";
+  const commandArgs = npmExecPath ? [npmExecPath, ...args] : args;
+  run(command, commandArgs, { label: `npm ${args.join(" ")}` });
 }
 
 function printRecovery(commands) {