@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/hooks/cache.js

@@ -0,0 +1,242 @@
+/**
+ * Declarative hook caching + timing.
+ *
+ * Hooks that opt in via `cache:` in hooks.yaml get a generated bash shim
+ * (~/.agents/.cache/shims/hooks/<name>.sh) registered with the agent instead
+ * of the raw script path. The shim handles:
+ *
+ *   1. cache lookup — reads ~/.agents/.cache/state/hooks/<name>.<key>.out
+ *      and serves it if newer than ttl.
+ *   2. stale-while-revalidate — when prefetch=background, serves stale cache
+ *      and refreshes the cache file in a detached child.
+ *   3. timing — appends one JSONL line per fire to events-YYYY-MM-DD.jsonl.
+ *
+ * The shim is regenerated whenever the registrar runs; if its content doesn't
+ * change (idempotent), mtime is preserved. Stale shims for removed hooks are
+ * cleaned by the registrar's garbage collection (shims dir is in
+ * managedPrefixes).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHookCacheDir, getHookShimsDir, getLogsDir } from '../state.js';
+/**
+ * Parse a `cache:` value from hooks.yaml into the canonical config form.
+ * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
+ * Returns null if the value is missing or unparseable.
+ */
+export function parseCacheConfig(raw) {
+    if (raw == null)
+        return null;
+    if (typeof raw === 'string')
+        return parseShorthand(raw);
+    const ttlSec = parseDuration(raw.ttl);
+    if (ttlSec == null)
+        return null;
+    return {
+        ttl: ttlSec,
+        key: raw.key ?? 'global',
+        prefetch: raw.prefetch ?? 'none',
+    };
+}
+function parseShorthand(s) {
+    const trimmed = s.trim();
+    let prefetch = 'none';
+    let durationPart = trimmed;
+    if (trimmed.endsWith('-bg')) {
+        prefetch = 'background';
+        durationPart = trimmed.slice(0, -3);
+    }
+    const ttlSec = parseDuration(durationPart);
+    if (ttlSec == null)
+        return null;
+    return { ttl: ttlSec, key: 'global', prefetch };
+}
+/** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
+export function parseDuration(d) {
+    if (d == null)
+        return null;
+    if (typeof d === 'number')
+        return Number.isFinite(d) && d > 0 ? Math.floor(d) : null;
+    const m = d.trim().match(/^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs)?$/i);
+    if (!m)
+        return null;
+    const value = parseInt(m[1], 10);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    const unit = (m[2] || 's').toLowerCase();
+    if (unit.startsWith('h'))
+        return value * 3600;
+    if (unit.startsWith('m'))
+        return value * 60;
+    return value;
+}
+/** Absolute path of the generated shim for a hook name. */
+export function getHookShimPath(name) {
+    return path.join(getHookShimsDir(), `${name}.sh`);
+}
+/**
+ * Generate (or refresh) the shim script for a hook. Idempotent — only writes
+ * when the content differs from what's on disk. Returns the absolute shim path.
+ */
+export function generateHookShim(args) {
+    const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
+    const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
+    const logsDir = args.paths?.logsDir ?? getLogsDir();
+    const shimPath = path.join(shimsDir, `${args.name}.sh`);
+    const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
+    fs.mkdirSync(shimsDir, { recursive: true });
+    let existing = null;
+    if (fs.existsSync(shimPath)) {
+        try {
+            existing = fs.readFileSync(shimPath, 'utf-8');
+        }
+        catch { /* rewrite */ }
+    }
+    if (existing !== content) {
+        fs.writeFileSync(shimPath, content, { mode: 0o755 });
+    }
+    else {
+        // Ensure exec bit even when content unchanged (file mode can drift).
+        try {
+            fs.chmodSync(shimPath, 0o755);
+        }
+        catch { /* best effort */ }
+    }
+    return shimPath;
+}
+/**
+ * Render the bash shim. Bash 3.2-compatible (macOS default). Uses python3 for
+ * monotonic-ish nanosecond timing — already a hard dependency of other hooks
+ * in this repo (04-capture-session-start-metadata.sh does the same).
+ */
+function renderShim(name, scriptPath, cache, paths) {
+    const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
+    const key = cache.key ?? 'global';
+    const prefetch = cache.prefetch ?? 'none';
+    const { cacheDir, logsDir } = paths;
+    // sh-escape: wrap in single quotes, escape any embedded single quotes.
+    const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    return `#!/usr/bin/env bash
+# GENERATED by agents-cli. Do not edit — re-run \`agents hooks sync\` to refresh.
+# Hook: ${name}
+# Source: ${scriptPath}
+# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}
+set -u
+
+HOOK_NAME=${q(name)}
+SOURCE=${q(scriptPath)}
+CACHE_DIR=${q(cacheDir)}
+LOGS_DIR=${q(logsDir)}
+TTL=${ttl}
+PREFETCH=${q(prefetch)}
+KEY_MODE=${q(key)}
+
+mkdir -p "$CACHE_DIR" "$LOGS_DIR"
+
+# Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
+STDIN_PAYLOAD="$(cat || true)"
+
+# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
+# \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
+sha1_12() { python3 -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
+
+# Derive cache key suffix from KEY_MODE. All untrusted inputs (cwd, session_id,
+# project path) are hashed before going into the filename so a malicious stdin
+# payload can't write outside $CACHE_DIR via path traversal.
+cache_suffix=""
+case "$KEY_MODE" in
+  per-cwd)
+    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("cwd","") or "")
+except Exception: pass' 2>/dev/null || true)"
+    [ -z "$cwd_val" ] && cwd_val="$PWD"
+    cache_suffix=".$(printf '%s' "$cwd_val" | sha1_12)"
+    ;;
+  per-session)
+    sid_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("session_id","") or "")
+except Exception: pass' 2>/dev/null || true)"
+    # Hash + fall back to a sentinel so missing-session doesn't silently
+    # collapse to the same file as KEY_MODE=global.
+    [ -z "$sid_val" ] && sid_val="__nosession__"
+    cache_suffix=".$(printf '%s' "$sid_val" | sha1_12)"
+    ;;
+  per-project)
+    proj_val="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || echo "")"
+    [ -z "$proj_val" ] && proj_val="$PWD"
+    cache_suffix=".$(printf '%s' "$proj_val" | sha1_12)"
+    ;;
+  global|*)
+    cache_suffix=""
+    ;;
+esac
+CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
+
+# Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
+now_ns() { python3 -c 'import time; print(int(time.time()*1e9))'; }
+START_NS=$(now_ns)
+
+CACHE_STATUS=miss
+CACHE_AGE=-1
+EXIT=0
+
+if [ -f "$CACHE_FILE" ]; then
+  # python3 is already a hard dep (used for now_ns) and gives portable mtime
+  # without the macOS-vs-Linux \`stat\` flag divergence (-f %m vs -c %Y) that
+  # blew up under \`set -u\` when the wrong flag produced literal "%m".
+  mtime=$(python3 -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$CACHE_FILE" 2>/dev/null)
+  mtime=\${mtime:-0}
+  now_s=$(date +%s)
+  CACHE_AGE=$((now_s - mtime))
+  if [ "$CACHE_AGE" -ge 0 ] && [ "$CACHE_AGE" -lt "$TTL" ]; then
+    cat "$CACHE_FILE"
+    CACHE_STATUS=hit
+  fi
+fi
+
+if [ "$CACHE_STATUS" = miss ]; then
+  if [ -f "$CACHE_FILE" ] && [ "$PREFETCH" = background ]; then
+    # Stale-while-revalidate: serve stale immediately, refresh in detached child.
+    cat "$CACHE_FILE"
+    CACHE_STATUS=stale-prefetch
+    tmp="$CACHE_FILE.new.$$"
+    ( printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null && mv -f "$tmp" "$CACHE_FILE" || rm -f "$tmp" ) >/dev/null 2>&1 &
+    disown 2>/dev/null || true
+  else
+    # Synchronous fetch + cache.
+    tmp="$CACHE_FILE.new.$$"
+    if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp"; then
+      EXIT=0
+      cat "$tmp"
+      mv -f "$tmp" "$CACHE_FILE"
+    else
+      EXIT=$?
+      rm -f "$tmp"
+    fi
+  fi
+fi
+
+END_NS=$(now_ns)
+MS=$(( (END_NS - START_NS) / 1000000 ))
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
+  "$TS" "$HOOK_NAME" "$MS" "$CACHE_STATUS" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+
+exit "$EXIT"
+`;
+}
+/**
+ * Remove a hook's shim. Called by the registrar's garbage collection when a
+ * hook is renamed/deleted or has its `cache:` field removed.
+ */
+export function removeHookShim(name, shimsDir) {
+    const dir = shimsDir ?? getHookShimsDir();
+    const shimPath = path.join(dir, `${name}.sh`);
+    if (fs.existsSync(shimPath)) {
+        try {
+            fs.unlinkSync(shimPath);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/lib/hooks/profile.d.ts

@@ -0,0 +1,33 @@
+export interface HookProfileRow {
+    hook: string;
+    n: number;
+    p50Ms: number;
+    p99Ms: number;
+    meanMs: number;
+    maxMs: number;
+    cacheHitPct: number;
+    cacheStalePct: number;
+    cacheMissPct: number;
+    errorCount: number;
+}
+interface RawFireEvent {
+    event?: string;
+    hook?: string;
+    ms?: number;
+    cache?: 'hit' | 'miss' | 'stale-prefetch' | string;
+    exit?: number;
+}
+/**
+ * Load every `hook.fire` event from the last `days` daily log files.
+ * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
+ * the events log is multiplexed (version.switch, secrets.get, …).
+ */
+export declare function loadHookFireEvents(days?: number, logsDir?: string): RawFireEvent[];
+/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
+export declare function aggregateHookProfile(events: RawFireEvent[]): HookProfileRow[];
+/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
+export declare function formatMs(ms: number): string;
+/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
+export declare function formatCacheColumn(row: HookProfileRow): string;
+export declare const DEFAULT_SLOW_HOOK_WARN_MS = 2000;
+export {};

package/dist/lib/hooks/profile.js

@@ -0,0 +1,129 @@
+/**
+ * Hook profiling — reads `hook.fire` events from the daily JSONL logs that
+ * generated shims (see `cache.ts`) emit on every invocation, and aggregates
+ * per-hook timing + cache stats.
+ *
+ * Only hooks declared with `cache:` get instrumented today, because only those
+ * are wrapped by a generated shim. Hooks without `cache:` are not in the
+ * profile output — that's deliberate: opting into the primitive is what
+ * surfaces the data.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getLogsDir } from '../state.js';
+/**
+ * Load every `hook.fire` event from the last `days` daily log files.
+ * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
+ * the events log is multiplexed (version.switch, secrets.get, …).
+ */
+export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
+    if (!fs.existsSync(logsDir))
+        return [];
+    const today = new Date();
+    const events = [];
+    for (let i = 0; i < days; i++) {
+        const d = new Date(today);
+        d.setUTCDate(d.getUTCDate() - i);
+        const yyyy = d.getUTCFullYear();
+        const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+        const dd = String(d.getUTCDate()).padStart(2, '0');
+        const file = path.join(logsDir, `events-${yyyy}-${mm}-${dd}.jsonl`);
+        if (!fs.existsSync(file))
+            continue;
+        const raw = fs.readFileSync(file, 'utf-8');
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.event !== 'hook.fire')
+                continue;
+            if (typeof parsed.hook !== 'string')
+                continue;
+            if (typeof parsed.ms !== 'number')
+                continue;
+            events.push(parsed);
+        }
+    }
+    return events;
+}
+/** Percentile of a sorted-ascending array. p in [0,100]. Linear interpolation. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
+export function aggregateHookProfile(events) {
+    const byHook = new Map();
+    for (const e of events) {
+        if (!e.hook)
+            continue;
+        if (!byHook.has(e.hook))
+            byHook.set(e.hook, []);
+        byHook.get(e.hook).push(e);
+    }
+    const rows = [];
+    for (const [hook, evs] of byHook) {
+        const sortedMs = evs.map(e => e.ms).sort((a, b) => a - b);
+        const n = evs.length;
+        const sum = sortedMs.reduce((a, b) => a + b, 0);
+        const hits = evs.filter(e => e.cache === 'hit').length;
+        const stale = evs.filter(e => e.cache === 'stale-prefetch').length;
+        const misses = evs.filter(e => e.cache === 'miss').length;
+        const errors = evs.filter(e => typeof e.exit === 'number' && e.exit !== 0).length;
+        rows.push({
+            hook,
+            n,
+            p50Ms: Math.round(percentile(sortedMs, 50)),
+            p99Ms: Math.round(percentile(sortedMs, 99)),
+            meanMs: Math.round(sum / n),
+            maxMs: sortedMs[sortedMs.length - 1],
+            cacheHitPct: Math.round((hits / n) * 100),
+            cacheStalePct: Math.round((stale / n) * 100),
+            cacheMissPct: Math.round((misses / n) * 100),
+            errorCount: errors,
+        });
+    }
+    rows.sort((a, b) => b.p99Ms - a.p99Ms);
+    return rows;
+}
+/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
+export function formatMs(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 10_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    const mins = Math.floor(ms / 60_000);
+    const secs = Math.round((ms % 60_000) / 1000);
+    return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
+}
+/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
+export function formatCacheColumn(row) {
+    if (row.cacheHitPct + row.cacheStalePct + row.cacheMissPct === 0)
+        return 'n/a';
+    const parts = [];
+    if (row.cacheHitPct > 0)
+        parts.push(`hit:${row.cacheHitPct}%`);
+    if (row.cacheStalePct > 0)
+        parts.push(`stale:${row.cacheStalePct}%`);
+    if (row.cacheMissPct > 0)
+        parts.push(`miss:${row.cacheMissPct}%`);
+    return parts.join(' ');
+}
+export const DEFAULT_SLOW_HOOK_WARN_MS = 2000;

package/dist/lib/hooks.d.ts

@@ -124,16 +124,6 @@ export declare function listCentralHooks(): HookEntry[];
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export declare function parseHookManifest(): Record<string, ManifestHook>;
-/**
- * Register hooks as lifecycle events in an agent's config.
- * Reads hooks.yaml manifest, merges into the agent's config file(s).
- * Only manages hooks whose command paths are under ~/.agents/hooks/ or
- * ~/.agents-system/hooks/. Does not remove user-added hooks.
- *
- * @param agentsDirOverride - When provided, treats this single dir as the
- *   only managed hook root. Used by tests to inject a temp path. In normal
- *   operation, both user and system roots are consulted with user precedence.
- */
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];
     errors: string[];