@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/monitors/engine.js

@@ -0,0 +1,201 @@
+/**
+ * Monitor evaluate/fire loop.
+ *
+ * Modeled on the routines daemon: a single MonitorEngine lives inside runDaemon()
+ * beside the cron JobScheduler. On each tick it evaluates every enabled monitor
+ * that is DUE and owned by this device, applies the condition through the native
+ * state-diff store, and on a fire dispatches the action, writes a fire record, and
+ * updates state. A per-monitor rate limit auto-pauses a firehose.
+ *
+ * v1 covers the poll model (command, poll, poll-http, file, device). Push sources
+ * (ws, webhook) return null from `evaluate` — they deliver through `subscribe` /
+ * the webhook receiver, wired in a follow-up; the engine treats them as inert.
+ */
+import { listMonitors, monitorRunsOnThisDevice, parseInterval, setMonitorEnabled, } from './config.js';
+import { evaluateSource } from './sources/index.js';
+import { hasChanged, readState, writeState, recordFireTime, writeFireRecord, } from './state.js';
+import { dispatchAction } from './dispatch.js';
+/** How often the engine wakes to check which monitors are due. */
+const TICK_MS = 5_000;
+/** Default evaluation cadence for sources that carry no explicit interval. */
+const DEFAULT_INTERVAL_MS = 60_000;
+function truncateSummary(text) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length > 240 ? oneLine.slice(0, 240) + '…' : oneLine;
+}
+function buildEvent(monitor, summary, payload) {
+    return { monitorName: monitor.name, firedAt: new Date().toISOString(), summary, payload };
+}
+/**
+ * Apply a monitor's condition to an observation. Pure (reads state, never
+ * writes), so both the tick loop and the `test` dry-run share it.
+ */
+export function decideFire(monitor, observation) {
+    const cond = monitor.condition;
+    const raw = observation.raw;
+    const payload = observation.meta ?? {};
+    const dedupeKey = cond.dedupeKey;
+    if (cond.mode === 'every') {
+        return {
+            fire: true,
+            value: raw,
+            dedupeKey,
+            persist: false,
+            event: buildEvent(monitor, truncateSummary(raw), payload),
+        };
+    }
+    if (cond.mode === 'match') {
+        let matched = null;
+        try {
+            matched = new RegExp(cond.match ?? '').exec(raw);
+        }
+        catch {
+            matched = null;
+        }
+        if (!matched) {
+            return { fire: false, value: raw, dedupeKey, persist: false, event: null };
+        }
+        const matchedValue = matched[0];
+        const changed = hasChanged(monitor.name, matchedValue, dedupeKey);
+        return {
+            fire: changed,
+            value: matchedValue,
+            dedupeKey,
+            persist: changed,
+            event: changed ? buildEvent(monitor, truncateSummary(matchedValue), payload) : null,
+        };
+    }
+    // on-change (default): the first observation establishes a silent baseline;
+    // thereafter fire when the de-dupe signature differs from last-seen.
+    const prior = readState(monitor.name);
+    if (!prior) {
+        return { fire: false, value: raw, dedupeKey, persist: true, event: null };
+    }
+    const changed = hasChanged(monitor.name, raw, dedupeKey);
+    return {
+        fire: changed,
+        value: raw,
+        dedupeKey,
+        persist: changed,
+        event: changed ? buildEvent(monitor, truncateSummary(raw), payload) : null,
+    };
+}
+/** One evaluation of a monitor's source + condition, without side effects. Used by `test`. */
+export async function evaluateMonitorOnce(monitor) {
+    const observation = await evaluateSource(monitor.source);
+    if (!observation)
+        return { observation: null, decision: null };
+    return { observation, decision: decideFire(monitor, observation) };
+}
+/** The durable monitor engine. One instance per daemon. */
+export class MonitorEngine {
+    logFn;
+    timer = null;
+    monitors = [];
+    lastEval = new Map();
+    ticking = false;
+    constructor(logFn = () => { }) {
+        this.logFn = logFn;
+    }
+    /** Load owned+enabled monitors and start the tick loop. */
+    start() {
+        this.loadAll();
+        this.logFn('INFO', `Monitor engine started (${this.monitors.length} monitor(s) on this device)`);
+        this.timer = setInterval(() => void this.tick(), TICK_MS);
+    }
+    /** Reload monitor configs (SIGHUP). */
+    reload() {
+        this.loadAll();
+        this.logFn('INFO', `Monitor engine reloaded (${this.monitors.length} monitor(s) on this device)`);
+    }
+    /** Stop the tick loop. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    loadAll() {
+        this.monitors = listMonitors().filter((m) => m.enabled && monitorRunsOnThisDevice(m));
+    }
+    intervalMs(monitor) {
+        if (monitor.source.interval)
+            return parseInterval(monitor.source.interval) ?? DEFAULT_INTERVAL_MS;
+        return DEFAULT_INTERVAL_MS;
+    }
+    isDue(monitor, now) {
+        const last = this.lastEval.get(monitor.name) ?? 0;
+        return now - last >= this.intervalMs(monitor);
+    }
+    /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
+    async tick() {
+        if (this.ticking)
+            return;
+        this.ticking = true;
+        try {
+            const now = Date.now();
+            for (const monitor of this.monitors) {
+                if (!this.isDue(monitor, now))
+                    continue;
+                this.lastEval.set(monitor.name, now);
+                await this.runMonitor(monitor);
+            }
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    async runMonitor(monitor) {
+        try {
+            const { observation, decision } = await evaluateMonitorOnce(monitor);
+            if (!observation || !decision)
+                return;
+            if (decision.fire && decision.event) {
+                await this.fire(monitor, decision, decision.event);
+            }
+            else if (decision.persist) {
+                // Silent baseline / no-change: record the value so we don't re-fire.
+                writeState(monitor.name, decision.value, decision.dedupeKey);
+            }
+        }
+        catch (err) {
+            this.logFn('ERROR', `monitor '${monitor.name}' evaluation failed: ${err.message}`);
+        }
+    }
+    async fire(monitor, decision, event) {
+        const now = Date.now();
+        let fireTimes;
+        // Firehose guard: auto-pause a monitor that exceeds its rate limit.
+        if (monitor.rateLimit) {
+            const windowMs = parseInterval(monitor.rateLimit.per) ?? 60_000;
+            fireTimes = recordFireTime(monitor.name, now, windowMs);
+            if (fireTimes.length > monitor.rateLimit.max) {
+                writeState(monitor.name, decision.value, decision.dedupeKey, { lastFiredAt: event.firedAt, fireTimes });
+                try {
+                    setMonitorEnabled(monitor.name, false);
+                }
+                catch { /* best-effort pause */ }
+                this.logFn('WARN', `monitor '${monitor.name}' exceeded rate limit (${monitor.rateLimit.max}/${monitor.rateLimit.per}) — auto-paused`);
+                this.loadAll();
+                return;
+            }
+        }
+        let result;
+        try {
+            result = await dispatchAction(monitor, event);
+        }
+        catch (err) {
+            result = { kind: monitor.action.type, ok: false, error: err.message };
+        }
+        writeFireRecord(event, {
+            ...(result.runId ? { runId: result.runId } : {}),
+            action: result.kind,
+            ok: result.ok,
+            ...(result.error ? { error: result.error } : {}),
+        });
+        writeState(monitor.name, decision.value, decision.dedupeKey, { lastFiredAt: event.firedAt, fireTimes });
+        this.logFn(result.ok ? 'INFO' : 'ERROR', `monitor '${monitor.name}' fired → ${result.kind}` +
+            (result.runId ? ` (run: ${result.runId})` : '') +
+            (result.ok ? '' : ` FAILED: ${result.error}`));
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 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>;

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

@@ -0,0 +1,31 @@
+/**
+ * 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';
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Run the source command and return its combined stdout as the observation. */
+export function evaluate(source) {
+    const command = source.command;
+    if (!command)
+        return Promise.resolve(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;
+            // A non-zero exit is still a real observation (the diff might be exactly
+            // "command started failing"); surface stderr when stdout is empty.
+            const raw = (stdout && stdout.length > 0 ? stdout : stderr ?? '').replace(/\s+$/, '');
+            resolve({ raw, meta: { exitCode } });
+        });
+    });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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

@@ -0,0 +1,35 @@
+/**
+ * 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)
+        return null;
+    const registry = await loadDevices();
+    const wanted = normalizeHost(name);
+    const entry = Object.entries(registry).find(([k]) => normalizeHost(k) === wanted);
+    const stats = entry && normalizeHost(entry[0]) !== machineId()
+        ? await probeDeviceStats(entry[1])
+        : await probeLocalStats(name);
+    const bucket = headroom(stats);
+    return {
+        raw: `${stats.reachable ? 'reachable' : 'unreachable'}\t${bucket}`,
+        meta: {
+            reachable: stats.reachable,
+            headroom: bucket,
+            loadPercent: stats.loadPercent,
+            memPercent: stats.memPercent,
+            ncpu: stats.ncpu,
+        },
+    };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,57 @@
+/**
+ * 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)
+        return Promise.resolve(null);
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.isDirectory()) {
+            const entries = fs
+                .readdirSync(filePath, { withFileTypes: true })
+                .map((e) => {
+                try {
+                    const s = fs.statSync(path.join(filePath, e.name));
+                    return `${e.name}\t${s.size}\t${Math.round(s.mtimeMs)}`;
+                }
+                catch {
+                    return `${e.name}\t?`;
+                }
+            })
+                .sort();
+            return Promise.resolve({
+                raw: entries.join('\n'),
+                meta: { kind: 'directory', count: entries.length },
+            });
+        }
+        let content = fs.readFileSync(filePath, 'utf-8');
+        if (content.length > MAX_CONTENT)
+            content = content.slice(content.length - MAX_CONTENT);
+        return Promise.resolve({
+            raw: content,
+            meta: { kind: 'file', size: stat.size, mtimeMs: Math.round(stat.mtimeMs) },
+        });
+    }
+    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)
+        return () => { };
+    return followFile(filePath, (text) => onObs({ raw: text, meta: { kind: 'append' } }), { fromEnd: true });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * 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

@@ -0,0 +1,34 @@
+/**
+ * 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)
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+        let body = await res.text();
+        if (body.length > MAX_BODY)
+            body = body.slice(0, MAX_BODY);
+        return {
+            raw: `${res.status}\n${body}`,
+            meta: { status: res.status, ok: res.ok },
+        };
+    }
+    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 {
+        clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,31 @@
+/**
+ * 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';
+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,
+    'poll-http': http.evaluate,
+    file: file.evaluate,
+    device: device.evaluate,
+    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)
+        return Promise.resolve(null);
+    return evaluator(source);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,18 @@
+/**
+ * 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>;
+}
+/** 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

@@ -0,0 +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.
+ */
+export {};

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

@@ -0,0 +1,23 @@
+/**
+ * Webhook source evaluator.
+ *
+ * Webhooks are push-based (an inbound signed HTTP delivery), so the poll-model
+ * `evaluate` returns null. When a delivery arrives, the receiver matches it
+ * against monitors with `matchWebhook`, which reuses the github/linear matchers
+ * from lib/triggers/webhook.ts by projecting the monitor's webhook filters onto a
+ * synthesized JobConfig-shaped trigger.
+ */
+import { type IncomingWebhook } from '../../triggers/webhook.js';
+import type { JobTrigger } from '../../routines.js';
+import type { MonitorSource, MonitorConfig } 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>;
+/** Project a monitor's webhook source onto a JobTrigger for the shared matcher. */
+export declare function monitorTrigger(source: MonitorSource): JobTrigger | null;
+/**
+ * True when an incoming webhook matches this monitor's webhook source — reuses
+ * the routines matcher (lib/triggers/webhook.ts) so github/linear filter
+ * semantics stay in one place.
+ */
+export declare function matchWebhook(monitor: MonitorConfig, webhook: IncomingWebhook): boolean;

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

@@ -0,0 +1,47 @@
+/**
+ * Webhook source evaluator.
+ *
+ * Webhooks are push-based (an inbound signed HTTP delivery), so the poll-model
+ * `evaluate` returns null. When a delivery arrives, the receiver matches it
+ * against monitors with `matchWebhook`, which reuses the github/linear matchers
+ * from lib/triggers/webhook.ts by projecting the monitor's webhook filters onto a
+ * synthesized JobConfig-shaped trigger.
+ */
+import { jobMatchesWebhook } from '../../triggers/webhook.js';
+/** Push-only: nothing to snapshot on a poll tick. */
+export function evaluate(_source) {
+    return Promise.resolve(null);
+}
+/** Project a monitor's webhook source onto a JobTrigger for the shared matcher. */
+export function monitorTrigger(source) {
+    const w = source.webhook;
+    if (!w)
+        return null;
+    if (w.source === 'github') {
+        return {
+            type: 'github_event',
+            event: w.event,
+            ...(w.repo ? { repo: w.repo } : {}),
+            ...(w.branch ? { branch: w.branch } : {}),
+        };
+    }
+    return {
+        type: 'linear_event',
+        event: w.event,
+        ...(w.action ? { action: w.action } : {}),
+        ...(w.teamKey ? { teamKey: w.teamKey } : {}),
+        ...(w.label ? { label: w.label } : {}),
+    };
+}
+/**
+ * True when an incoming webhook matches this monitor's webhook source — reuses
+ * the routines matcher (lib/triggers/webhook.ts) so github/linear filter
+ * semantics stay in one place.
+ */
+export function matchWebhook(monitor, webhook) {
+    const trigger = monitorTrigger(monitor.source);
+    if (!trigger)
+        return false;
+    const shim = { name: monitor.name, trigger };
+    return jobMatchesWebhook(shim, webhook);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,45 @@
+/**
+ * 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)
+        return () => { };
+    let closed = false;
+    let socket = null;
+    const connect = () => {
+        if (closed)
+            return;
+        socket = new WSWebSocket(url, { maxPayload: 8 * 1024 * 1024 });
+        socket.onmessage = (ev) => onObs({ raw: String(ev.data), meta: { kind: 'frame' } });
+        socket.onclose = () => {
+            if (!closed)
+                setTimeout(connect, 5_000); // reconnect on drop
+        };
+        socket.onerror = () => {
+            try {
+                socket?.close();
+            }
+            catch { /* already closing */ }
+        };
+    };
+    connect();
+    return () => {
+        closed = true;
+        try {
+            socket?.close();
+        }
+        catch { /* already closed */ }
+    };
+}