@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/lib/event-families.js

@@ -0,0 +1,159 @@
+/**
+ * Event stream families — sessions-style --include / --exclude for the unified
+ * event reader. One vocabulary maps onto existing filters (includeActivity,
+ * eventTypes, level) so the engine stays single-path.
+ */
+export const EVENT_FAMILIES = [
+    'ops',
+    'activity',
+    'commands',
+    'runs',
+    'security',
+];
+const FAMILY_SET = new Set(EVENT_FAMILIES);
+export function isEventFamily(value) {
+    return FAMILY_SET.has(value);
+}
+/**
+ * Parse a comma-separated family list. Throws on unknown names or empty list
+ * after split (same discipline as sessions role lists).
+ */
+export function parseFamilyList(raw, flagName) {
+    const parts = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0) {
+        throw new Error(`${flagName} requires at least one family: ${EVENT_FAMILIES.join(', ')}`);
+    }
+    const out = [];
+    for (const p of parts) {
+        if (!isEventFamily(p)) {
+            throw new Error(`Unknown family ${JSON.stringify(p)} in ${flagName}. Use: ${EVENT_FAMILIES.join(', ')}`);
+        }
+        if (!out.includes(p))
+            out.push(p);
+    }
+    return out;
+}
+/** Command-churn event kinds. */
+export const COMMAND_EVENT_TYPES = ['command.start', 'command.end'];
+/** Run-dispatch outcome kinds (replaces the separate audit/log.jsonl product). */
+export const RUN_EVENT_TYPES = ['run.dispatched', 'agent.run.end'];
+/**
+ * Fold family include/exclude into a UnifiedQuery.
+ * Precedence: family narrows sources/types; field filters (module, event, …)
+ * still apply on top.
+ *
+ * --include and --exclude are mutually exclusive at the CLI layer; this
+ * function accepts only one of includeFamilies / excludeFamilies.
+ */
+export function applyFamilies(q) {
+    const include = q.includeFamilies;
+    const exclude = q.excludeFamilies;
+    if (include?.length && exclude?.length) {
+        throw new Error('--include and --exclude are mutually exclusive');
+    }
+    if (!include?.length && !exclude?.length)
+        return q;
+    if (include?.length)
+        return applyInclude(q, include);
+    return applyExclude(q, exclude);
+}
+function applyInclude(q, families) {
+    const has = (f) => families.includes(f);
+    const typeSets = [];
+    let level = q.level;
+    let includeActivity = false;
+    let forceModule;
+    // Source selection — multi-family include is a UNION of each family's rows.
+    if (has('activity'))
+        includeActivity = true;
+    if (has('ops') || has('commands') || has('runs') || has('security')) {
+        // ops path open (includeActivity stays true when activity is also listed)
+    }
+    else if (has('activity')) {
+        // activity-only
+        forceModule = q.module ?? 'activity';
+        includeActivity = true;
+    }
+    // Default when include lists only type-scoping / ops / security: activity off
+    // unless activity is listed.
+    if (!has('activity') && (has('ops') || has('commands') || has('runs') || has('security'))) {
+        includeActivity = false;
+    }
+    // include ops + activity explicitly
+    if (has('ops') && has('activity'))
+        includeActivity = true;
+    if (has('commands'))
+        typeSets.push([...COMMAND_EVENT_TYPES]);
+    if (has('runs'))
+        typeSets.push([...RUN_EVENT_TYPES]);
+    if (has('security')) {
+        if (!level)
+            level = 'audit';
+        // security without activity stays ops-only
+        if (!has('activity'))
+            includeActivity = false;
+    }
+    // Type-scoped families (commands / runs) only restrict eventTypes when no
+    // broader ops-side family is in the include list. ops and security already
+    // cover those kinds; AND-ing a type filter would shrink the union (e.g.
+    // --include security,runs would drop secrets.get and keep only run.dispatched).
+    const broadOps = has('ops') || has('security');
+    let eventTypes = q.eventTypes ? [...q.eventTypes] : undefined;
+    if (typeSets.length > 0 && !broadOps) {
+        const union = new Set();
+        for (const set of typeSets)
+            for (const t of set)
+                union.add(t);
+        if (eventTypes?.length) {
+            // Intersect with --event; empty means no match (never silently widen).
+            const allowed = new Set(eventTypes);
+            eventTypes = [...union].filter((t) => allowed.has(t));
+        }
+        else {
+            eventTypes = [...union];
+        }
+    }
+    return {
+        ...q,
+        includeActivity,
+        ...(forceModule != null ? { module: forceModule } : {}),
+        ...(level ? { level } : {}),
+        ...(eventTypes ? { eventTypes } : {}),
+    };
+}
+function applyExclude(q, families) {
+    const has = (f) => families.includes(f);
+    let includeActivity = q.includeActivity !== false;
+    const excludeEventTypes = [...(q.excludeEventTypes ?? [])];
+    let excludeLevel = q.excludeLevel;
+    let forceModule;
+    // Exclude ops first (→ activity-only), then activity (may clear the reopen).
+    // --exclude ops,activity must not re-open activity after both sources are out.
+    if (has('ops')) {
+        forceModule = q.module ?? 'activity';
+        includeActivity = true;
+    }
+    if (has('activity'))
+        includeActivity = false;
+    if (has('commands')) {
+        for (const t of COMMAND_EVENT_TYPES) {
+            if (!excludeEventTypes.includes(t))
+                excludeEventTypes.push(t);
+        }
+    }
+    if (has('runs')) {
+        for (const t of RUN_EVENT_TYPES) {
+            if (!excludeEventTypes.includes(t))
+                excludeEventTypes.push(t);
+        }
+    }
+    if (has('security'))
+        excludeLevel = 'audit';
+    return {
+        ...q,
+        includeActivity,
+        ...(forceModule != null ? { module: forceModule } : {}),
+        ...(excludeEventTypes.length ? { excludeEventTypes } : {}),
+        ...(excludeLevel ? { excludeLevel } : {}),
+    };
+}

package/dist/lib/event-stream.d.ts

@@ -12,11 +12,16 @@
  * single READ surface that merges them; nothing here writes.
  */
 import { type EventRecord, type EventType, type EventLevel } from './events.js';
+import { type EventFamily } from './event-families.js';
 export interface UnifiedQuery {
     startDate?: Date;
     endDate?: Date;
     eventTypes?: EventType[];
+    /** Drop these event kinds after read (used by --exclude commands / runs). */
+    excludeEventTypes?: EventType[];
     level?: EventLevel;
+    /** Drop this level (used by --exclude security). */
+    excludeLevel?: EventLevel;
     agent?: string;
     /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
     sessionId?: string;
@@ -31,6 +36,9 @@ export interface UnifiedQuery {
     includeActivity?: boolean;
     /** Override the activity dir (tests). */
     activityRoot?: string;
+    /** Sessions-style family filters (resolved via applyFamilies). */
+    includeFamilies?: EventFamily[];
+    excludeFamilies?: EventFamily[];
 }
 /**
  * Read a unified, newest-first event stream. Operational events come from
@@ -40,4 +48,4 @@ export interface UnifiedQuery {
  * eventTypes for activity, eventTypes/module/bundle for ops — so the top-N is
  * exact for those filters).
  */
-export declare function readUnifiedEvents(q?: UnifiedQuery): EventRecord[];
+export declare function readUnifiedEvents(raw?: UnifiedQuery): EventRecord[];

package/dist/lib/event-stream.js

@@ -13,6 +13,7 @@
  */
 import { query, levelFor } from './events.js';
 import { readActivityAsEventRecords } from './activity.js';
+import { applyFamilies } from './event-families.js';
 /** Apply the same filters query() applies, to an activity-derived record. */
 function matches(r, q) {
     const ms = Date.parse(r.ts);
@@ -25,7 +26,12 @@ function matches(r, q) {
         return false;
     if (q.eventTypes && !q.eventTypes.includes(r.event))
         return false;
-    if (q.level && (r.level ?? levelFor(r.event)) !== q.level)
+    if (q.excludeEventTypes?.includes(r.event))
+        return false;
+    const lvl = r.level ?? levelFor(r.event);
+    if (q.level && lvl !== q.level)
+        return false;
+    if (q.excludeLevel && lvl === q.excludeLevel)
         return false;
     if (q.agent && r.agent !== q.agent)
         return false;
@@ -50,9 +56,18 @@ function matches(r, q) {
  * eventTypes for activity, eventTypes/module/bundle for ops — so the top-N is
  * exact for those filters).
  */
-export function readUnifiedEvents(q = {}) {
+export function readUnifiedEvents(raw = {}) {
+    const q = applyFamilies(raw);
     // `bundle` is filtered inside query()'s scan (before its limit cutoff) so a
     // matching-bundle record older than the newest-`limit` window is not dropped.
+    // Over-fetch when we will post-filter excludeEventTypes / excludeLevel so the
+    // top-N is still meaningful after drops.
+    const needsPost = Boolean(q.excludeEventTypes?.length || q.excludeLevel);
+    const fetchLimit = q.limit === undefined
+        ? undefined
+        : needsPost
+            ? Math.min(q.limit * 4, q.limit + 500)
+            : q.limit;
     const ops = query({
         startDate: q.startDate,
         endDate: q.endDate,
@@ -64,14 +79,16 @@ export function readUnifiedEvents(q = {}) {
         command: q.command,
         module: q.module,
         bundle: q.bundle,
-        limit: q.limit,
-    });
-    if (q.includeActivity === false)
-        return ops;
+        limit: fetchLimit,
+    }).filter((r) => matches(r, q));
+    if (q.includeActivity === false) {
+        return typeof q.limit === 'number' ? ops.slice(0, q.limit) : ops;
+    }
     // Activity events always stamp module: 'activity'. A non-activity module
     // filter can never match them — skip the activity scan entirely.
-    if (q.module != null && q.module !== 'activity')
-        return ops;
+    if (q.module != null && q.module !== 'activity') {
+        return typeof q.limit === 'number' ? ops.slice(0, q.limit) : ops;
+    }
     // Push eventTypes into the activity reader so `limit` is applied AFTER the
     // event-type filter (readRecentActivity already does this for `events`).
     // Without this, a rare match older than the newest-`limit` window of routine
@@ -80,7 +97,7 @@ export function readUnifiedEvents(q = {}) {
     // run via matches() for fields activity.ts does not pre-filter.
     const acts = readActivityAsEventRecords({
         sinceMs: q.startDate?.getTime(),
-        limit: q.limit,
+        limit: fetchLimit,
         root: q.activityRoot,
         events: q.eventTypes,
     }).filter((r) => matches(r, q));

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'run.dispatched' | 'daemon.start' | 'daemon.stop' | 'daemon.error' | 'daemon.info' | 'routine.start' | 'routine.end' | 'watchdog.action' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
 export declare const EVENT_TYPES: readonly EventType[];
 /** Runtime guard for an event kind arriving from outside this process. */
@@ -135,6 +135,14 @@ export declare function emit(event: EventType, payload?: EventPayload, overrides
  * done({ exitCode: 0 }); // emits agent.run.end with durationMs
  */
 export declare function emitStart(startEvent: EventType, payload?: EventPayload): (endPayload?: EventPayload) => void;
+export declare function emitRoutineEnd(meta: {
+    jobName: string;
+    runId?: string;
+    status: string;
+    duration?: number;
+    exitCode?: number | null;
+    detail?: string;
+}): void;
 /**
  * Measure execution time of a synchronous function.
  * Emits a perf.timing event with the duration.

package/dist/lib/events.js

@@ -109,6 +109,10 @@ const FILE_MODE = 0o600;
  */
 const EVENT_TYPE_TABLE = {
     'agent.run.start': true, 'agent.run.end': true, 'agent.spawn.start': true, 'agent.spawn.end': true,
+    'run.dispatched': true,
+    'daemon.start': true, 'daemon.stop': true, 'daemon.error': true, 'daemon.info': true,
+    'routine.start': true, 'routine.end': true,
+    'watchdog.action': true,
     'version.install': true, 'version.switch': true, 'version.remove': true,
     'skill.install': true, 'skill.remove': true,
     'browser.launch': true, 'browser.close': true, 'browser.navigate': true, 'browser.screenshot': true,
@@ -141,6 +145,7 @@ export function isEventType(value) {
 }
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
+    'run.dispatched',
     'secrets.get', 'secrets.unlocked', 'secrets.create', 'secrets.import', 'secrets.export', 'secrets.view', 'secrets.lease-denied', 'secrets.lease-expire',
     'secrets.set', 'secrets.delete', 'secrets.rename',
     'teams.create', 'teams.add', 'teams.start', 'teams.complete', 'teams.disband',
@@ -150,6 +155,10 @@ const AUDIT_EVENTS = new Set([
     'mcp.add', 'mcp.remove', 'mcp.register',
     'rotation.resolved',
     '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.
@@ -528,15 +537,21 @@ let _chmoddedPath;
 export function emitStart(startEvent, payload = {}) {
     const startTime = Date.now();
     emit(startEvent, payload);
-    const endEvent = startEvent.replace('.start', '.end');
     return (endPayload = {}) => {
-        emit(endEvent, {
-            ...payload,
-            ...endPayload,
-            durationMs: Date.now() - startTime,
-        });
+        emit(startEvent.replace('.start', '.end'), { ...payload, ...endPayload, durationMs: Date.now() - startTime });
     };
 }
+export function emitRoutineEnd(meta) {
+    emit('routine.end', {
+        module: 'routine',
+        name: meta.jobName,
+        status: meta.status,
+        ...(meta.runId ? { runId: meta.runId } : {}),
+        ...(meta.duration != null ? { durationMs: meta.duration } : {}),
+        ...(meta.exitCode != null ? { exitCode: meta.exitCode } : {}),
+        ...(meta.detail ? { detail: meta.detail } : {}),
+    });
+}
 // ─── Timing Utilities ─────────────────────────────────────────────────────────
 /**
  * Measure execution time of a synchronous function.

package/dist/lib/exec.d.ts

@@ -353,6 +353,29 @@ export declare function execShimPassthrough(agent: AgentId, rawArgs: string[], c
  * `[detached]` with no explanation.
  */
 export declare function shouldRecapDeadPane(status: number | undefined, interactive: boolean): boolean;
+/**
+ * The exit code a tmux-wrapped run resolves with (RUSH-2185 / EXEC-23b).
+ *
+ * Three inputs, one rule: report success ONLY for an outcome tmux actually told
+ * us about. A clean user detach (`knownAlive`) is 0; a dead pane reports the
+ * status tmux read off it; everything else — pane unreadable because the server
+ * or session went away, or dead with no status — is UNKNOWN and resolves to
+ * {@link UNKNOWN_OUTCOME_EXIT_CODE}, never 0.
+ *
+ * Why this is not `status ?? 0`: an interactive run whose tmux server died mid-
+ * work landed on exactly those unknown branches and returned 0, so `agents run`
+ * printed a failure banner while handing its caller a success code. The same
+ * "1 if unknown" rule already governs the `--host` follow path
+ * (`docs/specifications.md` §Agent execution, exit-code table).
+ *
+ * @param pane       What `paneExitStatus` read back for the agent pane.
+ * @param knownAlive Positive proof the pane is still alive (see
+ *                   {@link isPaneKnownAliveFromQueryResult}) — a clean detach.
+ */
+export declare function tmuxRunExitCode(pane: {
+    dead: boolean;
+    status?: number;
+}, knownAlive: boolean): number;
 /**
  * True only when a `display-message #{pane_dead}` tmux query explicitly returned
  * "0" (pane alive). Used to distinguish "pane alive" from "query failed" in
@@ -439,6 +462,13 @@ export declare function writeTmuxEnvFile(env: NodeJS.ProcessEnv, filePath: strin
 export declare function formatPaneTail(raw: string, maxLines?: number): string;
 /** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export declare const BUDGET_KILL_EXIT_CODE = 7;
+/**
+ * Exit code a tmux-wrapped run resolves with when tmux cannot tell us how the
+ * agent finished — the pane is unreadable, or it is dead with no reported status
+ * (EXEC-23b). Never 0: an unknown outcome reported as success is how a run killed
+ * mid-work gets counted as a clean finish by whatever scripted it.
+ */
+export declare const UNKNOWN_OUTCOME_EXIT_CODE = 1;
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
  * because providers phrase these differently -- Anthropic uses "5-hour limit"