@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/monitors/remote.js

@@ -1,30 +1,6 @@
-/**
- * Fleet-wide monitor lookup — "is any box already watching this?"
- *
- * A monitor's identity is its ARGUMENTS, not its name or its device. Agents
- * create monitors per work item, so the same shape runs many times over with
- * different arguments (PR #2517 vs #2600) and those must all coexist. The case
- * that must NOT happen is two agents, on two different machines, creating a
- * watcher with the SAME arguments — one work item, two triggers.
- *
- * A local-only check cannot see that: each box reads its own `monitors/` dir and
- * neither sees the other. So the duplicate guard asks the fleet, reusing the
- * same cross-machine fan-out `sessions --active` and `fleet status` already run
- * (`lib/remote-agents-json.ts`).
- *
- * Deliberately NOT solved by syncing `monitors/*.yml` through the DotAgents repo:
- * an agent's per-PR watcher is running state, not config, and syncing would push
- * every one of them onto every box — the accumulation this guard exists to stop.
- */
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
 import { monitorFingerprint } from './fingerprint.js';
-/** Recursion guard: a peer answering the fan-out must not fan out again. */
 export const NO_MONITOR_FANOUT_ENV = 'AGENTS_MONITORS_LOCAL';
-/**
- * Parse a peer's `monitors list --json`. Defensive against version skew: a peer
- * on an older CLI may emit a different shape or no JSON at all, and one bad peer
- * must never blank the guard for the rest of the fleet.
- */
 export function parseRemoteMonitors(stdout, machine) {
     let parsed;
     try {
@@ -33,9 +9,6 @@ export function parseRemoteMonitors(stdout, machine) {
     catch {
         return [];
     }
-    // `monitors list --json` writes a BARE array (stdoutJson -> JSON.stringify of
-    // monitors.map(...)); it has never wrapped. Guarding an envelope shape that has
-    // never existed would be a fallback for an imaginary bug.
     if (!Array.isArray(parsed))
         return [];
     const rows = parsed;
@@ -44,8 +17,6 @@ export function parseRemoteMonitors(stdout, machine) {
         if (!row || typeof row !== 'object' || Array.isArray(row))
             continue;
         const m = row;
-        // Without source+condition+action there is no identity to compare, so the
-        // row cannot participate in the duplicate check either way.
         if (!m.name || !m.source || !m.condition || !m.action)
             continue;
         const display = {
@@ -66,17 +37,6 @@ export function parseRemoteMonitors(stdout, machine) {
     }
     return out;
 }
-/**
- * Every monitor on every other registered device. Never throws: an unreachable
- * fleet degrades to an empty list plus the names we could not consult, and the
- * caller decides what to say about them.
- *
- * When {@link GatherFleetMonitorsOptions.againstFingerprint} is provided, a peer
- * returning that fingerprint is a definitive clash: the remaining peers are
- * SIGTERM'd immediately rather than burning the rest of the timeout budget.
- * Absence of a clash still waits for the full fleet, because uniqueness is only
- * knowable once every peer has answered.
- */
 export async function gatherFleetMonitors(options = {}) {
     try {
         const result = await gatherRemoteAgentsJson({
@@ -98,8 +58,6 @@ export async function gatherFleetMonitors(options = {}) {
         };
     }
     catch {
-        // Could not consult the fleet at all. Reported as such by the caller, never
-        // as an absence of duplicates.
         return { monitors: [], skipped: [], discoveryFailed: true };
     }
 }

package/dist/lib/monitors/sources/command.d.ts

@@ -1,11 +1,4 @@
-/**
- * Command / poll source evaluator.
- *
- * Runs a shell command; its stdout is the observation. `poll` re-runs the same
- * command on an interval — the evaluation is identical, so poll.ts delegates
- * here. No agent, no sandbox: a plain `/bin/sh -c` (or `cmd /c` on Windows).
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** Run the source command and return its combined stdout as the observation. */
-export declare function evaluate(source: MonitorSource): Promise<Observation | null>;
+export declare const POLL_TIMEOUT_MS = 60000;
+export declare function evaluate(source: MonitorSource, timeoutMs?: number): Promise<Observation | null>;

package/dist/lib/monitors/sources/command.js

@@ -1,41 +1,20 @@
-/**
- * Command / poll source evaluator.
- *
- * Runs a shell command; its stdout is the observation. `poll` re-runs the same
- * command on an interval — the evaluation is identical, so poll.ts delegates
- * here. No agent, no sandbox: a plain `/bin/sh -c` (or `cmd /c` on Windows).
- */
-import { execFile } from 'child_process';
+import { execFileBounded } from '../../exec-bounded.js';
 import { classifyPollFailure } from './failure.js';
-const DEFAULT_TIMEOUT_MS = 60_000;
-/** Run the source command and return its combined stdout as the observation. */
-export function evaluate(source) {
+export const POLL_TIMEOUT_MS = 60_000;
+export async function evaluate(source, timeoutMs = POLL_TIMEOUT_MS) {
     const command = source.command;
     if (!command)
-        return Promise.resolve(null);
+        return null;
     const [bin, args] = process.platform === 'win32'
         ? ['cmd', ['/c', command]]
         : ['/bin/sh', ['-c', command]];
-    return new Promise((resolve) => {
-        execFile(bin, args, { encoding: 'utf-8', timeout: DEFAULT_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
-            const exitCode = err && typeof err.code === 'number'
-                ? err.code
-                : err
-                    ? 1
-                    : 0;
-            // Surface stderr when stdout is empty.
-            const raw = (stdout && stdout.length > 0 ? stdout : stderr ?? '').replace(/\s+$/, '');
-            // A poll that failed to OBSERVE — non-zero exit, or a transport/auth/
-            // rate-limit error shape in its output (which a piped `gh … | jq`
-            // swallows the exit code of) — is not a new value. Flag it so the engine
-            // skips it instead of reading empty→error→empty as two value changes and
-            // dispatching an agent on a dead premise (PHNX-3510).
-            const failureReason = classifyPollFailure({ exitCode, text: raw });
-            resolve({
-                raw,
-                meta: { exitCode },
-                ...(failureReason ? { failed: true, failureReason } : {}),
-            });
-        });
-    });
+    const { stdout, stderr, code, timedOut } = await execFileBounded(bin, args, { timeoutMs, maxBuffer: 8 * 1024 * 1024 });
+    const exitCode = code ?? 1;
+    const raw = (stdout.length > 0 ? stdout : stderr).replace(/\s+$/, '');
+    const failureReason = timedOut ? `timed out after ${timeoutMs / 1000}s` : classifyPollFailure({ exitCode, text: raw });
+    return {
+        raw,
+        meta: { exitCode },
+        ...(failureReason ? { failed: true, failureReason } : {}),
+    };
 }

package/dist/lib/monitors/sources/device.d.ts

@@ -1,13 +1,3 @@
-/**
- * Device source evaluator.
- *
- * A fleet device becomes the watched source. Reuses the real load/health probe
- * (lib/devices/health.ts) — the first scheduler consumer of it — so a monitor can
- * fire "when a box goes loaded / unreachable". The observation is
- * `<reachable>\t<headroom>` plus the full DeviceStats in meta, so an on-change
- * monitor fires on a headroom-bucket flip and a match monitor can match `loaded`.
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** Probe the device and return reachability + headroom bucket as the observation. */
 export declare function evaluate(source: MonitorSource): Promise<Observation | null>;

package/dist/lib/monitors/sources/device.js

@@ -1,16 +1,6 @@
-/**
- * Device source evaluator.
- *
- * A fleet device becomes the watched source. Reuses the real load/health probe
- * (lib/devices/health.ts) — the first scheduler consumer of it — so a monitor can
- * fire "when a box goes loaded / unreachable". The observation is
- * `<reachable>\t<headroom>` plus the full DeviceStats in meta, so an on-change
- * monitor fires on a headroom-bucket flip and a match monitor can match `loaded`.
- */
 import { loadDevices } from '../../devices/registry.js';
 import { probeDeviceStats, probeLocalStats, headroom } from '../../devices/health.js';
 import { machineId, normalizeHost } from '../../machine-id.js';
-/** Probe the device and return reachability + headroom bucket as the observation. */
 export async function evaluate(source) {
     const name = source.device;
     if (!name)
@@ -18,10 +8,6 @@ export async function evaluate(source) {
     const registry = await loadDevices();
     const wanted = normalizeHost(name);
     const entry = Object.entries(registry).find(([k]) => normalizeHost(k) === wanted);
-    // An unregistered / removed device must NOT silently fall back to the local
-    // machine's stats — that would watch the wrong box under the requested name
-    // (the "no fallback logic" convention). `add` validates --watch-device up
-    // front, so this catches the device-removed-after-creation case at eval time.
     if (!entry) {
         return {
             raw: `error\tdevice not registered: ${name}`,

package/dist/lib/monitors/sources/failure.d.ts

@@ -1,31 +1,4 @@
-/**
- * Poll-failure classifier (PHNX-3510).
- *
- * A poll that FAILS to observe — the command exited non-zero, or its output
- * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
- * not a new value. Reading it as a value is the defect this closes: a
- * `gh pr list … | jq` monitor whose gh half intermittently prints
- * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
- * `[on-change]` monitor read that as two value changes and dispatched a full
- * agent run on a premise that was false.
- *
- * The exit code alone is not enough: when gh is piped into jq the shell's exit
- * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
- * observation. The text patterns catch exactly that case. They stay tightly
- * scoped to unambiguous failure shapes so a legitimate observation whose content
- * merely mentions "timeout" is never misread as a failure.
- */
-/** The failure reason matched in a poll's output text, or null when it looks clean. */
 export declare function matchFailureText(text: string): string | null;
-/**
- * Classify one poll snapshot. Returns a short failure reason when the snapshot is
- * an observation failure (non-zero exit, or a failure-shaped output), else null —
- * in which case the snapshot is a genuine value the condition may diff.
- *
- * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
- * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
- * failure regardless of output shape.
- */
 export declare function classifyPollFailure(input: {
     exitCode?: number;
     text: string;

package/dist/lib/monitors/sources/failure.js

@@ -1,20 +1,3 @@
-/**
- * Poll-failure classifier (PHNX-3510).
- *
- * A poll that FAILS to observe — the command exited non-zero, or its output
- * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
- * not a new value. Reading it as a value is the defect this closes: a
- * `gh pr list … | jq` monitor whose gh half intermittently prints
- * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
- * `[on-change]` monitor read that as two value changes and dispatched a full
- * agent run on a premise that was false.
- *
- * The exit code alone is not enough: when gh is piped into jq the shell's exit
- * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
- * observation. The text patterns catch exactly that case. They stay tightly
- * scoped to unambiguous failure shapes so a legitimate observation whose content
- * merely mentions "timeout" is never misread as a failure.
- */
 const FAILURE_TEXT_PATTERNS = [
     { re: /\bAPI rate limit (?:already )?exceeded\b/i, reason: 'API rate limit exceeded' },
     { re: /\bsecondary rate limit\b/i, reason: 'secondary rate limit' },
@@ -25,7 +8,6 @@ const FAILURE_TEXT_PATTERNS = [
     { re: /\bconnection (?:refused|reset|timed out)\b/i, reason: 'connection error' },
     { re: /\bnetwork is unreachable\b/i, reason: 'network unreachable' },
 ];
-/** The failure reason matched in a poll's output text, or null when it looks clean. */
 export function matchFailureText(text) {
     for (const { re, reason } of FAILURE_TEXT_PATTERNS) {
         if (re.test(text))
@@ -33,15 +15,6 @@ export function matchFailureText(text) {
     }
     return null;
 }
-/**
- * Classify one poll snapshot. Returns a short failure reason when the snapshot is
- * an observation failure (non-zero exit, or a failure-shaped output), else null —
- * in which case the snapshot is a genuine value the condition may diff.
- *
- * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
- * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
- * failure regardless of output shape.
- */
 export function classifyPollFailure(input) {
     const textReason = matchFailureText(input.text);
     const badExit = typeof input.exitCode === 'number' && input.exitCode !== 0;

package/dist/lib/monitors/sources/file.d.ts

@@ -1,14 +1,4 @@
-/**
- * File source evaluator.
- *
- * The observation is the file's content (bounded) plus mtime/size in meta, so an
- * on-change monitor fires on any edit. For a directory, the observation is a
- * sorted listing with per-entry mtime/size. Push-follow reuses followFile
- * (lib/log-follow.ts) — the same cross-platform tail the routines log viewer uses.
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** Snapshot the file (or directory) as the observation. */
 export declare function evaluate(source: MonitorSource): Promise<Observation | null>;
-/** Push-follow the file, emitting each appended chunk as an observation. */
 export declare function subscribe(source: MonitorSource, onObs: (obs: Observation) => void): () => void;

package/dist/lib/monitors/sources/file.js

@@ -1,16 +1,7 @@
-/**
- * File source evaluator.
- *
- * The observation is the file's content (bounded) plus mtime/size in meta, so an
- * on-change monitor fires on any edit. For a directory, the observation is a
- * sorted listing with per-entry mtime/size. Push-follow reuses followFile
- * (lib/log-follow.ts) — the same cross-platform tail the routines log viewer uses.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { followFile } from '../../log-follow.js';
 const MAX_CONTENT = 256 * 1024;
-/** Snapshot the file (or directory) as the observation. */
 export function evaluate(source) {
     const filePath = source.path;
     if (!filePath)
@@ -44,11 +35,9 @@ export function evaluate(source) {
         });
     }
     catch (err) {
-        // Absent file is a real observation (it may have just been deleted/created).
         return Promise.resolve({ raw: `missing: ${err.message}`, meta: { kind: 'missing' } });
     }
 }
-/** Push-follow the file, emitting each appended chunk as an observation. */
 export function subscribe(source, onObs) {
     const filePath = source.path;
     if (!filePath)

package/dist/lib/monitors/sources/http.d.ts

@@ -1,10 +1,3 @@
-/**
- * Poll-http source evaluator.
- *
- * GETs the URL; the observation is `<status>\n<body>` so a status flip OR a body
- * change both register as a diff. Uses the built-in fetch (Node 22+).
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** GET the source URL and return status + body as the observation. */
 export declare function evaluate(source: MonitorSource): Promise<Observation | null>;

package/dist/lib/monitors/sources/http.js

@@ -1,12 +1,5 @@
-/**
- * Poll-http source evaluator.
- *
- * GETs the URL; the observation is `<status>\n<body>` so a status flip OR a body
- * change both register as a diff. Uses the built-in fetch (Node 22+).
- */
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_BODY = 1024 * 1024;
-/** GET the source URL and return status + body as the observation. */
 export async function evaluate(source) {
     const url = source.url;
     if (!url)
@@ -24,8 +17,6 @@ export async function evaluate(source) {
         };
     }
     catch (err) {
-        // A network failure is itself a real observation (the endpoint went down);
-        // surface it so an on-change monitor can fire on reachability flips.
         return { raw: `error: ${err.message}`, meta: { status: 0, ok: false } };
     }
     finally {

package/dist/lib/monitors/sources/index.d.ts

@@ -1,14 +1,5 @@
-/**
- * Source-evaluator registry: source.type → evaluator.
- *
- * The engine looks up the evaluator by type and calls its poll-model `evaluate`.
- * Push-based sources (ws, webhook) return null from `evaluate` and deliver
- * observations through their `subscribe` instead.
- */
 import type { MonitorSourceType, MonitorSource } from '../config.js';
 import type { Observation, SourceEvaluator } from './types.js';
 export type { Observation, SourceEvaluator, SourceSubscriber } from './types.js';
-/** Poll-model evaluator per source type. */
 export declare const SOURCE_EVALUATORS: Record<MonitorSourceType, SourceEvaluator>;
-/** Evaluate one source snapshot. Returns null when the source is push-only or has nothing new. */
 export declare function evaluateSource(source: MonitorSource): Promise<Observation | null>;

package/dist/lib/monitors/sources/index.js

@@ -1,10 +1,3 @@
-/**
- * Source-evaluator registry: source.type → evaluator.
- *
- * The engine looks up the evaluator by type and calls its poll-model `evaluate`.
- * Push-based sources (ws, webhook) return null from `evaluate` and deliver
- * observations through their `subscribe` instead.
- */
 import * as command from './command.js';
 import * as poll from './poll.js';
 import * as http from './http.js';
@@ -12,7 +5,6 @@ import * as file from './file.js';
 import * as device from './device.js';
 import * as ws from './ws.js';
 import * as webhook from './webhook.js';
-/** Poll-model evaluator per source type. */
 export const SOURCE_EVALUATORS = {
     command: command.evaluate,
     poll: poll.evaluate,
@@ -22,7 +14,6 @@ export const SOURCE_EVALUATORS = {
     ws: ws.evaluate,
     webhook: webhook.evaluate,
 };
-/** Evaluate one source snapshot. Returns null when the source is push-only or has nothing new. */
 export function evaluateSource(source) {
     const evaluator = SOURCE_EVALUATORS[source.type];
     if (!evaluator)

package/dist/lib/monitors/sources/poll.d.ts

@@ -1,9 +1 @@
-/**
- * Poll source evaluator.
- *
- * `poll` re-runs a shell command on an interval and diffs the output. The
- * evaluation is identical to the `command` source — the difference is only the
- * scheduling cadence (source.interval), which the engine owns — so this
- * delegates to command.ts rather than duplicating the shell-run.
- */
 export { evaluate } from './command.js';

package/dist/lib/monitors/sources/poll.js

@@ -1,9 +1 @@
-/**
- * Poll source evaluator.
- *
- * `poll` re-runs a shell command on an interval and diffs the output. The
- * evaluation is identical to the `command` source — the difference is only the
- * scheduling cadence (source.interval), which the engine owns — so this
- * delegates to command.ts rather than duplicating the shell-run.
- */
 export { evaluate } from './command.js';

package/dist/lib/monitors/sources/types.d.ts

@@ -1,27 +1,9 @@
-/**
- * Shared source-evaluator contract.
- *
- * Every source module exports `evaluate(source)` (the poll model — one snapshot,
- * or null when nothing is observable this tick / the source is push-only) and,
- * where push-based (ws, file-follow), a `subscribe(source, onObs)` returning an
- * unsubscribe fn.
- */
 import type { MonitorSource } from '../config.js';
-/** One observation of a source: the raw text plus optional structured metadata. */
 export interface Observation {
     raw: string;
     meta?: Record<string, unknown>;
-    /**
-     * The source flagged this snapshot as an OBSERVATION FAILURE (a poll that
-     * exited non-zero or emitted a transport/auth/rate-limit error), not a value.
-     * The engine skips it: no fire, watched-state untouched, counted as a failed
-     * check for drought health (PHNX-3510).
-     */
     failed?: boolean;
-    /** Short human reason for `failed`, surfaced in drought health and `test`. */
     failureReason?: string;
 }
-/** Poll-model evaluator: return one observation, or null when none is available. */
 export type SourceEvaluator = (source: MonitorSource) => Promise<Observation | null>;
-/** Push-model subscriber: call onObs on each frame; return an unsubscribe fn. */
 export type SourceSubscriber = (source: MonitorSource, onObs: (obs: Observation) => void) => () => void;

package/dist/lib/monitors/sources/types.js

@@ -1,9 +1 @@
-/**
- * Shared source-evaluator contract.
- *
- * Every source module exports `evaluate(source)` (the poll model — one snapshot,
- * or null when nothing is observable this tick / the source is push-only) and,
- * where push-based (ws, file-follow), a `subscribe(source, onObs)` returning an
- * unsubscribe fn.
- */
 export {};

package/dist/lib/monitors/sources/webhook.d.ts

@@ -1,10 +1,3 @@
-/**
- * Webhook source evaluator.
- *
- * Webhooks are push-based (an inbound signed HTTP delivery), so the poll-model
- * `evaluate` returns null.
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** Push-only: nothing to snapshot on a poll tick. */
 export declare function evaluate(_source: MonitorSource): Promise<Observation | null>;

package/dist/lib/monitors/sources/webhook.js

@@ -1,10 +1,3 @@
-/**
- * Webhook source evaluator.
- *
- * Webhooks are push-based (an inbound signed HTTP delivery), so the poll-model
- * `evaluate` returns null.
- */
-/** Push-only: nothing to snapshot on a poll tick. */
 export function evaluate(_source) {
     return Promise.resolve(null);
 }

package/dist/lib/monitors/sources/ws.d.ts

@@ -1,14 +1,4 @@
-/**
- * WebSocket source evaluator.
- *
- * ws is push-based: each frame is an observation. The poll-model `evaluate`
- * returns null (there is nothing to snapshot on a tick); real observations arrive
- * through `subscribe`, which opens a persistent client (the same `ws` client
- * lib/browser/cdp.ts uses — not the platform undici WebSocket).
- */
 import type { MonitorSource } from '../config.js';
 import type { Observation } from './types.js';
-/** Push-only: nothing to snapshot on a poll tick. */
 export declare function evaluate(_source: MonitorSource): Promise<Observation | null>;
-/** Open a persistent WebSocket; emit each received frame as an observation. */
 export declare function subscribe(source: MonitorSource, onObs: (obs: Observation) => void): () => void;

package/dist/lib/monitors/sources/ws.js

@@ -1,17 +1,7 @@
-/**
- * WebSocket source evaluator.
- *
- * ws is push-based: each frame is an observation. The poll-model `evaluate`
- * returns null (there is nothing to snapshot on a tick); real observations arrive
- * through `subscribe`, which opens a persistent client (the same `ws` client
- * lib/browser/cdp.ts uses — not the platform undici WebSocket).
- */
 import WSWebSocket from 'ws';
-/** Push-only: nothing to snapshot on a poll tick. */
 export function evaluate(_source) {
     return Promise.resolve(null);
 }
-/** Open a persistent WebSocket; emit each received frame as an observation. */
 export function subscribe(source, onObs) {
     const url = source.wsUrl;
     if (!url)
@@ -25,13 +15,13 @@ export function subscribe(source, onObs) {
         socket.onmessage = (ev) => onObs({ raw: String(ev.data), meta: { kind: 'frame' } });
         socket.onclose = () => {
             if (!closed)
-                setTimeout(connect, 5_000); // reconnect on drop
+                setTimeout(connect, 5_000);
         };
         socket.onerror = () => {
             try {
                 socket?.close();
             }
-            catch { /* already closing */ }
+            catch { }
         };
     };
     connect();
@@ -40,6 +30,6 @@ export function subscribe(source, onObs) {
         try {
             socket?.close();
         }
-        catch { /* already closed */ }
+        catch { }
     };
 }