@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/feed/events.js

@@ -1,16 +1,3 @@
-/**
- * Centralized event logging for agents-cli.
- *
- * Structured JSONL audit logs at ~/.agents/.history/events/YYYY-MM-DD/events.jsonl with
- * lossless numbered gzip rotation at 10 MiB and bounded retention.
- *
- * 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';
@@ -20,17 +7,6 @@ import { ensureLockTarget, withFileLock, withFileLockAsync } from '../fs-atomic.
 import { getUserAgentsDir } from '../state.js';
 import { stampProvenance, resetEventProvenanceForTest } from '../event-provenance.js';
 import { recordSample } from '../perf/spool.js';
-/**
- * Perf warehouse write. SYNCHRONOUS by design (PHNX-3497): `recordSample` is an
- * `appendFileSync` that never opens SQLite (see perf/spool.ts), so calling it
- * directly costs one file append and lands the row before this function returns.
- * It MUST NOT be deferred behind a `void import().then(...)`: the `agent.run`
- * timer ends at the very tail of `agents run`, and the CLI process exits before
- * any deferred microtask runs — so a fire-and-forget spool write was silently
- * lost on every foreground run, leaving the PHNX-3468 startup-phase surface with
- * no data. (Hooks were unaffected only because their shim appends the spool line
- * synchronously in bash.)
- */
 function recordPerfTiming(payload) {
     try {
         const phases = payload.phases && Object.keys(payload.phases).length > 0 ? payload.phases : undefined;
@@ -48,15 +24,8 @@ function recordPerfTiming(payload) {
         });
     }
     catch {
-        // fail soft
     }
 }
-// ─── Constants ────────────────────────────────────────────────────────────────
-// Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
-// import itself must stay side-effect free. Tests may override the exact path.
-// AGENTS_EVENTS_PATH redirects the sink — a test seam like AGENTS_SECRETS_AGENT_DIR:
-// unlike _resetForTest it survives a bare reset AND propagates to CLI subprocesses
-// a test spawns, so fixture events can never land in the user's real log (#910).
 let _eventsPath;
 let _eventsPathOverride = false;
 let _legacyMigrationChecked = false;
@@ -88,44 +57,21 @@ function eventsPath(date = new Date()) {
 function eventsDir(date = new Date()) {
     return path.dirname(eventsPath(date));
 }
-/**
- * The directory today's ledger is appended to. Exported for the tool-activity
- * collector, which watches it instead of re-running `agents computer sessions`
- * on a timer to notice a new `computer.action` (see `feed/tool-activity.ts`).
- */
 export function getEventsDir() {
     return eventsDir();
 }
-/** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
-/** Default total footprint for the active log plus gzip archives (50 MiB). */
 const DEFAULT_MAX_STORAGE_BYTES = 50 * 1024 * 1024;
-/** Cross-process marker used to avoid a full archive scan on every append. */
 const PRUNE_MARKER = '.last-prune';
-/** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
-/** Gzip rotation threshold in bytes (10 MB). */
 const GZIP_ROTATION_BYTES = 10 * 1024 * 1024;
-/** 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;
-/**
- * Every {@link EventType}, as a runtime-checkable table.
- *
- * Typed `Record<EventType, true>` on purpose: the object literal is
- * exhaustiveness-checked at COMPILE time, so adding a member to the union
- * without adding it here fails `tsc`. That is what keeps the runtime validator
- * (`isEventType`, used by `agents events emit` to reject an unknown kind from an
- * out-of-process producer) from silently drifting behind the union.
- */
 const EVENT_TYPE_TABLE = {
     'agent.run.start': true, 'agent.run.end': true, 'agent.spawn.start': true, 'agent.spawn.end': true,
     'run.dispatched': true,
@@ -157,19 +103,14 @@ const EVENT_TYPE_TABLE = {
     'factory.command': true, 'factory.action': true, 'factory.uri': true, 'factory.launch': true,
     'friction': true, 'error': true, 'warn': true, 'info': true, 'debug': true,
 };
-/** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
 export const EVENT_TYPES = Object.keys(EVENT_TYPE_TABLE);
 const EVENT_TYPE_SET = new Set(EVENT_TYPES);
-/** Runtime guard for an event kind arriving from outside this process. */
 export function isEventType(value) {
     return EVENT_TYPE_SET.has(value);
 }
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
     'run.dispatched',
-    // Sibling of run.dispatched, and the MORE reliable signal for a stuck /
-    // logged-out launch (it fires pre-spawn, before an agent can hang at a login
-    // screen and never finalize). Must surface under --level audit --include runs.
     'run.launch',
     'secrets.get', 'secrets.unlocked', 'secrets.create', 'secrets.import', 'secrets.export', 'secrets.view', 'secrets.lease-denied', 'secrets.lease-expire',
     'secrets.set', 'secrets.delete', 'secrets.rename',
@@ -180,14 +121,7 @@ const AUDIT_EVENTS = new Set([
     'mcp.add', 'mcp.remove', 'mcp.register',
     'rotation.resolved', 'rotation.unresolved',
     'session.start', 'session.end',
-    // Daemon lifecycle (always-on process start/stop/error is audit-relevant).
-    // browser.* / computer.action stay info — they are already on the event stream;
-    // elevating them to audit would flood the security lane (see events.test.ts).
     'daemon.start', 'daemon.stop', 'daemon.error',
-    // An external process reaching into the user's editor (the CLI's
-    // vscodium-agent backend driving `/spawn` / `/inject` / `/focus`) is a
-    // "who reached in from outside" fact, which is what the audit lane answers.
-    // The other factory.* kinds are ordinary info — a palette press is not audit.
     'factory.uri',
 ]);
 export function levelFor(event) {
@@ -199,7 +133,6 @@ export function levelFor(event) {
         return 'audit';
     return 'info';
 }
-// ─── Helpers ──────────────────────────────────────────────────────────────────
 function getTimezoneOffset() {
     const offset = new Date().getTimezoneOffset();
     const sign = offset <= 0 ? '+' : '-';
@@ -216,31 +149,19 @@ function getTimezoneName() {
     }
 }
 function ensureLogsDir() {
-    eventsPath(); // Resolve an explicit AGENTS_EVENTS_PATH before migration checks.
+    eventsPath();
     migrateLegacyEventLogs();
     if (!fs.existsSync(eventsDir())) {
         fs.mkdirSync(eventsDir(), { recursive: true, mode: DIR_MODE });
     }
     else {
-        // Ensure permissions are correct on existing dir
         try {
             fs.chmodSync(eventsDir(), DIR_MODE);
         }
         catch {
-            // May fail if not owner
         }
     }
 }
-/**
- * Move root-level and interim flat-history event families into dated directories.
- *
- * The common case is a whole-family rename into an empty destination. A
- * Each segment is assigned to the local calendar day of its filesystem mtime;
- * new writes are split by day at source. A partially completed migration keeps
- * the destination active file authoritative and assigns a fresh archive number,
- * so no record is overwritten or silently discarded. The legacy active-file
- * lock serializes this with older installed processes that still append there.
- */
 function migrateLegacyEventLogs(userDir = userAgentsDir()) {
     if (_eventsPathOverride || _legacyMigrationChecked)
         return 0;
@@ -314,24 +235,17 @@ function migrateLegacyEventLogs(userDir = userAgentsDir()) {
                         if (fs.existsSync(family.active) && fs.statSync(family.active).size === 0)
                             fs.unlinkSync(family.active);
                     }
-                    catch { /* an older process may have reopened it */ }
+                    catch { }
                 }
                 return moved;
             });
         });
     }
     catch {
-        // Audit logging must remain fail-soft. Files stay at the legacy path and a
-        // later process retries because this guard is process-local.
         _legacyMigrationChecked = false;
         return 0;
     }
 }
-// ─── Redaction ────────────────────────────────────────────────────────────────
-/**
- * Replace a prompt string with length + short SHA so we can correlate runs
- * without persisting the raw text. Returns the fields to spread into a payload.
- */
 export function redactPrompt(prompt) {
     if (prompt == null)
         return {};
@@ -353,10 +267,6 @@ function promptMarker(value) {
     const { prompt_length, prompt_sha256 } = redactPrompt(value);
     return `[REDACTED prompt length=${prompt_length} sha256=${prompt_sha256}]`;
 }
-/**
- * Mask argv entries that look like tokens or secret paths. Preserves structure
- * for debugging but drops the sensitive substring.
- */
 export function redactArgs(args) {
     if (!args)
         return undefined;
@@ -414,11 +324,6 @@ export function redactArgs(args) {
     }
     return result;
 }
-// ─── 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;
@@ -426,9 +331,6 @@ export function truncate(str, maxLength = DEFAULT_TRUNCATE_LENGTH) {
         return str;
     return str.slice(0, maxLength - 3) + '...';
 }
-/**
- * Truncate all string values in a payload object.
- */
 function sanitizeNested(value, key, maxLength) {
     if (SENSITIVE_PAYLOAD_KEY.test(key))
         return '[REDACTED]';
@@ -475,7 +377,6 @@ const TERMINAL_CALLERS = {
     ag: 'antigravity',
     gk: 'grok',
 };
-/** Identify the environment that invoked agents-cli, not the source callsite. */
 export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.stdout.isTTY)) {
     const session = env.AGENT_SESSION_ID?.slice(0, 8) || undefined;
     if (env.CLAUDECODE === '1')
@@ -487,20 +388,6 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
     }
     return { kind: stdoutIsTTY ? 'terminal' : 'script' };
 }
-// ─── Core API ─────────────────────────────────────────────────────────────────
-/**
- * Emit a structured event to the append-only audit log.
- *
- * @param event - The event type
- * @param payload - Event-specific data (agent, version, cwd, etc.)
- * @param overrides - Envelope fields the CALLER owns rather than the writer.
- *   Only `ts` today: a batched out-of-process producer (`agents events emit`)
- *   records when each event HAPPENED, but flushes them together later, so
- *   stamping write-time would collapse a whole batch onto the flush instant and
- *   corrupt every `--since` boundary. `ts` stays in RESERVED_META_KEYS so a
- *   *payload* still cannot inject it — this explicit channel is the only way in.
- */
-/** Build the JSONL line + target path for an event, or null when logging is disabled. Shared by {@link emit} and {@link emitAsync}. */
 function prepareEventWrite(event, payload, overrides) {
     if (isDisabled())
         return null;
@@ -508,7 +395,6 @@ function prepareEventWrite(event, payload, overrides) {
     const caller = detectCaller();
     const safePayload = sanitizePayload(payload);
     const record = {
-        // Provenance floor first: env-sourced defaults an explicit payload overrides.
         ...stampProvenance(),
         ...safePayload,
         ts: overrides.ts ?? new Date().toISOString(),
@@ -530,7 +416,6 @@ function prepareEventWrite(event, payload, overrides) {
     ensureLockTarget(logPath, '', DIR_MODE);
     return { logPath, line, isNew };
 }
-/** The under-lock append + chmod + rotate/prune. Tiny local writes (µs), safe inside either the sync or async lock. */
 function appendEventLocked(logPath, line, isNew) {
     fs.appendFileSync(logPath, line, { mode: FILE_MODE });
     if (isNew || logPath !== _chmoddedPath) {
@@ -539,7 +424,6 @@ function appendEventLocked(logPath, line, isNew) {
             fs.chmodSync(logPath, FILE_MODE);
         }
         catch {
-            // May fail if not owner
         }
     }
     const rotated = maybeGzipRotateLocked(logPath);
@@ -553,18 +437,8 @@ export function emit(event, payload = {}, overrides = {}) {
         withFileLock(prepared.logPath, () => appendEventLocked(prepared.logPath, prepared.line, prepared.isNew));
     }
     catch {
-        // Silent failure - logging should never break the CLI
     }
 }
-/**
- * Async, non-blocking counterpart of {@link emit} for callers on the daemon's
- * shared event loop (PHNX-3695). `emit` acquires the event-log lock with
- * `withFileLock` → `sleepSync` (`Atomics.wait`), which HALTS the loop for up to
- * 30s under contention (a peer appending to the same log). `emitAsync` acquires
- * it with `withFileLockAsync`, so the loop keeps turning. The under-lock body is
- * identical (a µs-scale append + a rare rotate). Best-effort like `emit`: never
- * throws; a caller on a tick fires it and moves on.
- */
 export async function emitAsync(event, payload = {}, overrides = {}) {
     try {
         const prepared = prepareEventWrite(event, payload, overrides);
@@ -573,20 +447,9 @@ export async function emitAsync(event, payload = {}, overrides = {}) {
         await withFileLockAsync(prepared.logPath, () => appendEventLocked(prepared.logPath, prepared.line, prepared.isNew));
     }
     catch {
-        // Silent failure - logging should never break the CLI
     }
 }
-/** Last log path this process chmod'd — avoids a redundant chmod per append. */
 let _chmoddedPath;
-/**
- * Convenience wrapper for timed operations.
- * Returns a function to call when the operation completes.
- *
- * @example
- * const done = emitStart('agent.run.start', { agent: 'claude' });
- * // ... do work ...
- * done({ exitCode: 0 }); // emits agent.run.end with durationMs
- */
 export function emitStart(startEvent, payload = {}) {
     const startTime = Date.now();
     emit(startEvent, payload);
@@ -608,22 +471,9 @@ function routineEndPayload(meta) {
 export function emitRoutineEnd(meta) {
     emit('routine.end', routineEndPayload(meta));
 }
-/**
- * Async, non-blocking `routine.end` for the daemon heartbeat tick (PHNX-3695):
- * the reaper (`reapExitedRunningJobs`) runs on the shared event loop, so it emits
- * through {@link emitAsync} rather than the `sleepSync`-locked {@link emit}.
- */
 export async function emitRoutineEndAsync(meta) {
     await emitAsync('routine.end', routineEndPayload(meta));
 }
-// ─── 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 {
@@ -667,17 +517,6 @@ export function time(label, fn, payload = {}) {
         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 = {};
@@ -712,31 +551,14 @@ export function createTimer(label, payload = {}) {
         },
     };
 }
-// ─── 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
+        args: args.slice(0, 20),
         cwd: process.cwd(),
     });
 }
-/**
- * Emit a friction event — a structured, point-of-use record of a failure or
- * block the CLI just hit. `surface` is the subsystem (teams, browser, secrets,
- * guard, …); `failureId` is a stable slug that lets the nightly routine group
- * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
- */
 export function emitFriction(surface, failureId, payload = {}) {
     emit('friction', {
         ...payload,
@@ -744,8 +566,6 @@ export function emitFriction(surface, failureId, payload = {}) {
         failureId,
     });
 }
-// ─── Gzip rotation ──────────────────────────────────────────────────────────
-/** Rotate the active file while its append lock is held. */
 function maybeGzipRotateLocked(logPath) {
     const stat = fs.statSync(logPath);
     if (stat.size < GZIP_ROTATION_BYTES)
@@ -770,7 +590,7 @@ function maybeGzipRotateLocked(logPath) {
         try {
             fs.unlinkSync(tmpArchive);
         }
-        catch { /* best-effort cleanup */ }
+        catch { }
         throw err;
     }
 }
@@ -788,7 +608,7 @@ function listEventLogFiles() {
                 size: stat.size,
             });
         }
-        catch { /* file may rotate while an unlocked reader enumerates */ }
+        catch { }
     };
     const addDirectory = (dir) => {
         let names = [];
@@ -850,7 +670,7 @@ function removeEmptyDayDirectories() {
             if (fs.readdirSync(dir).length === 0)
                 fs.rmdirSync(dir);
         }
-        catch { /* best effort */ }
+        catch { }
     }
 }
 function finalizePastDayLogs() {
@@ -877,7 +697,7 @@ function finalizePastDayLogs() {
                 fs.unlinkSync(file.path);
             });
         }
-        catch { /* retry on the next prune */ }
+        catch { }
     }
 }
 function pruneEventLogsLocked(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
@@ -893,7 +713,7 @@ function pruneEventLogsLocked(retentionDays = DEFAULT_RETENTION_DAYS, maxStorage
             result.removedByAge++;
             result.bytesReclaimed += file.size;
         }
-        catch { /* another process may already have removed it */ }
+        catch { }
     }
     files = listEventLogFiles();
     let totalBytes = files.reduce((sum, file) => sum + file.size, 0);
@@ -909,12 +729,11 @@ function pruneEventLogsLocked(retentionDays = DEFAULT_RETENTION_DAYS, maxStorage
             result.removedBySize++;
             result.bytesReclaimed += file.size;
         }
-        catch { /* another process may already have removed it */ }
+        catch { }
     }
     removeEmptyDayDirectories();
     return result;
 }
-/** Apply age retention and the total-size ceiling immediately. */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
     try {
         ensureLogsDir();
@@ -926,7 +745,6 @@ export function rotate(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes =
         return { removedByAge: 0, removedBySize: 0, bytesReclaimed: 0 };
     }
 }
-/** Prune daily across processes, and immediately after a size rotation. */
 function maybePruneLocked(force) {
     const marker = path.join(eventsRoot(), PRUNE_MARKER);
     const oneDayMs = 24 * 60 * 60 * 1000;
@@ -946,19 +764,12 @@ function maybePruneLocked(force) {
     try {
         fs.writeFileSync(marker, '', { mode: FILE_MODE });
     }
-    catch { /* retry next append */ }
+    catch { }
 }
-// ─── Query ────────────────────────────────────────────────────────────────────
-/**
- * Read events from log files within a date range.
- *
- * @param options - Query options
- * @returns Array of event records
- */
 export function query(options) {
     const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, bundle, limit } = options;
     const results = [];
-    eventsPath(); // Resolve AGENTS_EVENTS_PATH before deciding whether to migrate.
+    eventsPath();
     migrateLegacyEventLogs();
     const files = listEventLogFiles().sort((a, b) => Number(b.currentActive) - Number(a.currentActive) || b.mtimeMs - a.mtimeMs || b.path.localeCompare(a.path));
     const startMs = startDate?.getTime();
@@ -1000,9 +811,6 @@ export function query(options) {
                     continue;
                 if (module && record.module !== module)
                     continue;
-                // Filter bundle in the SAME scan, before the limit cutoff — a post-filter
-                // on the already-capped result silently drops matching-bundle records that
-                // fell outside the newest-`limit` window (a data-loss bug for an audit query).
                 if (bundle && record.bundle !== bundle)
                     continue;
                 results.push(record);
@@ -1011,17 +819,11 @@ export function query(options) {
                 }
             }
             catch {
-                // Skip malformed lines
             }
         }
     }
     return results;
 }
-/**
- * Scan event logs once for a set of session IDs and return browser/computer
- * usage flags for each. O(files) instead of O(N × files) — safe to call
- * outside a SQLite write transaction.
- */
 export function queryToolUsageForSessions(sessionIds) {
     const result = new Map();
     if (sessionIds.size === 0)
@@ -1034,7 +836,7 @@ export function queryToolUsageForSessions(sessionIds) {
     eventsPath();
     migrateLegacyEventLogs();
     const files = listEventLogFiles().sort((a, b) => Number(b.currentActive) - Number(a.currentActive) || b.mtimeMs - a.mtimeMs || b.path.localeCompare(a.path));
-    let remaining = sessionIds.size * 2; // each session needs up to 2 flags set
+    let remaining = sessionIds.size * 2;
     for (const file of files) {
         if (remaining <= 0)
             break;
@@ -1069,7 +871,6 @@ export function queryToolUsageForSessions(sessionIds) {
                 }
             }
             catch {
-                // skip malformed lines
             }
         }
     }
@@ -1103,7 +904,7 @@ export function stats(options = {}) {
         fileCount = files.length;
         totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     }
-    catch { /* skip */ }
+    catch { }
     return {
         totalEvents: records.length,
         byLevel,
@@ -1115,7 +916,6 @@ export function stats(options = {}) {
         totalBytes,
     };
 }
-// ─── Exports ──────────────────────────────────────────────────────────────────
 export function getLogsPath() {
     return eventsPath();
 }