@phnx-labs/agents-cli 1.14.7 → 1.16.0

package/dist/lib/events.js

@@ -3,15 +3,35 @@
  *
  * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
+ *
+ * Features:
+ * - Rich metadata: hostname, platform, arch, pid, timezone
+ * - Timing helpers: measure operation duration automatically
+ * - Truncation: long inputs/outputs are trimmed with ellipsis
+ * - Permissions: logs dir is 0700, files are 0600 (owner-only)
+ * - Performance tracking: withTiming() wrapper for any async function
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 // ─── Constants ────────────────────────────────────────────────────────────────
-const USER_AGENTS_DIR = path.join(os.homedir(), '.agents');
-const LOGS_DIR = path.join(USER_AGENTS_DIR, 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry.
+const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 30;
+/** Default max length for truncated strings. */
+const DEFAULT_TRUNCATE_LENGTH = 500;
+/** Environment variable to disable event logging. */
+const DISABLE_ENV_VAR = 'AGENTS_DISABLE_EVENT_LOG';
+/** Check if audit logging is disabled via environment variable. */
+function isDisabled() {
+    const val = process.env[DISABLE_ENV_VAR];
+    return val === '1' || val === 'true';
+}
+/** Directory permissions (owner read/write/execute only). */
+const DIR_MODE = 0o700;
+/** File permissions (owner read/write only). */
+const FILE_MODE = 0o600;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function getTimezoneOffset() {
     const offset = new Date().getTimezoneOffset();
@@ -36,8 +56,48 @@ function getLogFilePath(date = new Date()) {
 }
 function ensureLogsDir() {
     if (!fs.existsSync(LOGS_DIR)) {
-        fs.mkdirSync(LOGS_DIR, { recursive: true });
+        fs.mkdirSync(LOGS_DIR, { recursive: true, mode: DIR_MODE });
+    }
+    else {
+        // Ensure permissions are correct on existing dir
+        try {
+            fs.chmodSync(LOGS_DIR, DIR_MODE);
+        }
+        catch {
+            // May fail if not owner
+        }
+    }
+}
+// ─── Truncation ───────────────────────────────────────────────────────────────
+/**
+ * Truncate a string to maxLength, adding ellipsis if truncated.
+ * Returns undefined for null/undefined input.
+ */
+export function truncate(str, maxLength = DEFAULT_TRUNCATE_LENGTH) {
+    if (str == null)
+        return undefined;
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Truncate all string values in a payload object.
+ */
+function truncatePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
+    const result = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (typeof value === 'string') {
+            result[key] = truncate(value, maxLength);
+        }
+        else if (Array.isArray(value)) {
+            // Truncate array to first 10 items, truncate each string item
+            result[key] = value.slice(0, 10).map(v => typeof v === 'string' ? truncate(v, maxLength) : v);
+        }
+        else {
+            result[key] = value;
+        }
     }
+    return result;
 }
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
@@ -47,6 +107,8 @@ function ensureLogsDir() {
  * @param payload - Event-specific data (agent, version, cwd, etc.)
  */
 export function emit(event, payload = {}) {
+    if (isDisabled())
+        return;
     try {
         ensureLogsDir();
         const record = {
@@ -57,11 +119,20 @@ export function emit(event, payload = {}) {
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
+            ppid: process.ppid,
             event,
-            ...payload,
+            ...truncatePayload(payload),
         };
         const line = JSON.stringify(record) + '\n';
-        fs.appendFileSync(getLogFilePath(), line);
+        const logPath = getLogFilePath();
+        fs.appendFileSync(logPath, line, { mode: FILE_MODE });
+        // Ensure file permissions (appendFileSync doesn't respect mode on existing files)
+        try {
+            fs.chmodSync(logPath, FILE_MODE);
+        }
+        catch {
+            // May fail if not owner
+        }
     }
     catch {
         // Silent failure - logging should never break the CLI
@@ -88,6 +159,166 @@ export function emitStart(startEvent, payload = {}) {
         });
     };
 }
+// ─── Timing Utilities ─────────────────────────────────────────────────────────
+/**
+ * Measure execution time of a synchronous function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = time('parse-config', () => parseConfig(path));
+ */
+export function time(label, fn, payload = {}) {
+    const start = Date.now();
+    try {
+        const result = fn();
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'success',
+        });
+        return result;
+    }
+    catch (err) {
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Measure execution time of an async function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = await timeAsync('fetch-data', () => fetchData(url));
+ */
+export async function timeAsync(label, fn, payload = {}) {
+    const start = Date.now();
+    try {
+        const result = await fn();
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'success',
+        });
+        return result;
+    }
+    catch (err) {
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Create a timing context for measuring multiple phases of an operation.
+ * Useful for tracking startup time vs execution time.
+ *
+ * @example
+ * const timer = createTimer('agent.run', { agent: 'claude' });
+ * // ... setup work ...
+ * timer.mark('startup'); // records startup time
+ * // ... main work ...
+ * timer.end({ exitCode: 0 }); // records total time and emits event
+ */
+export function createTimer(label, payload = {}) {
+    const start = Date.now();
+    const marks = {};
+    return {
+        mark(phase) {
+            const elapsed = Date.now() - start;
+            marks[phase] = elapsed;
+            return elapsed;
+        },
+        elapsed() {
+            return Date.now() - start;
+        },
+        end(endPayload = {}) {
+            const durationMs = Date.now() - start;
+            emit('perf.timing', {
+                ...payload,
+                ...endPayload,
+                label,
+                durationMs,
+                phases: marks,
+            });
+        },
+    };
+}
+/**
+ * Higher-order function that wraps an async function with timing.
+ * The wrapper emits start/end events automatically.
+ *
+ * @example
+ * const timedFetch = withTiming('fetch', fetchData, { service: 'api' });
+ * const result = await timedFetch(url);
+ */
+export function withTiming(label, fn, basePayload = {}) {
+    return async (...args) => {
+        const start = Date.now();
+        try {
+            const result = await fn(...args);
+            emit('perf.timing', {
+                ...basePayload,
+                label,
+                durationMs: Date.now() - start,
+                status: 'success',
+            });
+            return result;
+        }
+        catch (err) {
+            emit('perf.timing', {
+                ...basePayload,
+                label,
+                durationMs: Date.now() - start,
+                status: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+    };
+}
+// ─── Command Tracking ─────────────────────────────────────────────────────────
+/**
+ * Emit a command.start event with CLI args.
+ * Returns a done() function to emit command.end with duration.
+ *
+ * @example
+ * // At CLI entry point:
+ * const done = emitCommand('run', process.argv.slice(2));
+ * // ... execute command ...
+ * done({ exitCode: 0 });
+ */
+export function emitCommand(command, args = [], payload = {}) {
+    return emitStart('command.start', {
+        ...payload,
+        command,
+        args: args.slice(0, 20), // Limit args to first 20
+        cwd: process.cwd(),
+    });
+}
+// ─── Error Tracking ───────────────────────────────────────────────────────────
+/**
+ * Emit an error event with full details.
+ */
+export function emitError(err, payload = {}) {
+    const error = err instanceof Error ? err : new Error(err);
+    emit('error', {
+        ...payload,
+        error: error.message,
+        errorStack: truncate(error.stack, 1000),
+    });
+}
 // ─── Rotation ─────────────────────────────────────────────────────────────────
 /**
  * Remove log files older than the retention period.
@@ -140,7 +371,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, agent, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, agent, command, limit } = options;
     const results = [];
     if (!fs.existsSync(LOGS_DIR))
         return results;
@@ -167,6 +398,8 @@ export function query(options) {
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
+                if (command && record.command !== command)
+                    continue;
                 results.push(record);
                 if (limit && results.length >= limit) {
                     return results;
@@ -179,5 +412,30 @@ export function query(options) {
     }
     return results;
 }
+// ─── Stats ────────────────────────────────────────────────────────────────────
+/**
+ * Get performance stats for a specific label.
+ */
+export function getTimingStats(label, options = {}) {
+    const days = options.days ?? 7;
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - days);
+    const events = query({
+        startDate,
+        eventTypes: ['perf.timing'],
+    }).filter(e => e.label === label && typeof e.durationMs === 'number');
+    if (events.length === 0)
+        return null;
+    const durations = events.map(e => e.durationMs).sort((a, b) => a - b);
+    const sum = durations.reduce((a, b) => a + b, 0);
+    return {
+        count: durations.length,
+        avgMs: Math.round(sum / durations.length),
+        minMs: durations[0],
+        maxMs: durations[durations.length - 1],
+        p50Ms: durations[Math.floor(durations.length * 0.5)],
+        p95Ms: durations[Math.floor(durations.length * 0.95)],
+    };
+}
 // ─── Exports ──────────────────────────────────────────────────────────────────
 export const LOGS_PATH = LOGS_DIR;

package/dist/lib/exec.js

@@ -10,7 +10,7 @@ import * as path from 'path';
 import { parseTimeout } from './routines.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
-import { emitStart, maybeRotate } from './events.js';
+import { maybeRotate, createTimer, truncate } from './events.js';
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -305,13 +305,17 @@ async function spawnAgent(options) {
     const piped = !process.stdout.isTTY;
     const interactive = options.interactive === true || options.prompt === undefined;
     maybeRotate();
-    const done = emitStart('agent.run.start', {
+    const timer = createTimer('agent.run', {
         agent: options.agent,
         version: options.version,
         cwd: options.cwd || process.cwd(),
         mode: options.mode,
         model: options.model,
         interactive,
+        sessionId: options.sessionId,
+        prompt: truncate(options.prompt, 200),
+        command: executable,
+        args: args.slice(0, 10),
     });
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
@@ -327,6 +331,8 @@ async function spawnAgent(options) {
             env: buildExecEnv(options),
             shell: false,
         });
+        // Mark startup time (time from function call to process spawn)
+        timer.mark('startup');
         if (!interactive && piped && child.stdout) {
             child.stdout.pipe(process.stdout);
         }
@@ -343,23 +349,23 @@ async function spawnAgent(options) {
                 }
             });
         }
-        let timer;
+        let timeoutTimer;
         if (timeoutMs) {
-            timer = setTimeout(() => {
+            timeoutTimer = setTimeout(() => {
                 child.kill('SIGTERM');
                 setTimeout(() => child.kill('SIGKILL'), 5000);
             }, timeoutMs);
         }
         child.on('error', (err) => {
-            if (timer)
-                clearTimeout(timer);
-            done({ error: err.message, exitCode: -1 });
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            timer.end({ error: err.message, exitCode: -1, status: 'error' });
             reject(err);
         });
         child.on('close', (code) => {
-            if (timer)
-                clearTimeout(timer);
-            done({ exitCode: code ?? 0 });
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            timer.end({ exitCode: code ?? 0, status: code === 0 ? 'success' : 'failed' });
             resolve({ exitCode: code ?? 0, stderr: stderrBuffer });
         });
     });

package/dist/lib/hooks.d.ts

@@ -66,6 +66,7 @@ export declare function installHookToVersion(agent: AgentId, version: string, ho
 };
 /**
  * Remove a single hook (script + data file) from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/hooks/.
  */
 export declare function removeHookFromVersion(agent: AgentId, version: string, hookName: string): {
     success: boolean;
@@ -113,10 +114,11 @@ export declare function installHooksCentrally(source: string): Promise<{
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse hooks.yaml manifests. Reads BOTH system (~/.agents-system/hooks.yaml)
- * and user (~/.agents/hooks.yaml), merging with user-wins-on-key-collision
- * precedence. A user entry with `enabled: false` disables the system-shipped
- * hook of the same name without forking the system file.
+ * Parse hook manifests. Reads system hooks from ~/.agents-system/hooks.yaml
+ * (npm-shipped defaults) and user hooks from the `hooks:` section of
+ * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
+ * A user entry with `enabled: false` disables the system-shipped hook of
+ * the same name without forking the system file.
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
@@ -124,10 +126,12 @@ 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/.
- * Does not remove user-added hooks.
+ * Only manages hooks whose command paths are under ~/.agents/hooks/ or
+ * ~/.agents-system/hooks/. Does not remove user-added hooks.
  *
- * @param agentsDirOverride - Override the agents dir (used in tests to inject a temp path).
+ * @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[];