@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/monitors/config.js

@@ -0,0 +1,372 @@
+/**
+ * Monitor (event-triggered watcher) configuration, validation, and CRUD.
+ *
+ * A monitor is a routine whose trigger is a *watched source* instead of a
+ * *clock*. It watches a SOURCE, detects a CONDITION change, and fires an ACTION —
+ * reusing the routines daemon, dispatch engine, device model, and notify path.
+ *
+ * Monitors are YAML files in ~/.agents/monitors/. This module owns the on-disk
+ * shape (mirroring lib/routines.ts read/write helpers), hand-rolled validation
+ * (mirroring validateJob — no zod), and the device-owner eligibility gate.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getMonitorsDir, ensureAgentsDir } from '../state.js';
+import { safeJoin, isSafeSegmentName } from '../paths.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { ALL_AGENT_IDS } from '../agents.js';
+/** Default values applied to every monitor config when fields are omitted. */
+const MONITOR_DEFAULTS = {
+    enabled: true,
+};
+const SOURCE_TYPES = [
+    'command',
+    'poll',
+    'poll-http',
+    'webhook',
+    'ws',
+    'file',
+    'device',
+];
+const CONDITION_MODES = ['on-change', 'match', 'every'];
+const ACTION_TYPES = ['run', 'routine', 'notify', 'webhook-out'];
+/**
+ * Parse a human interval string (e.g. `30s`, `15m`, `8h`, `1d`, `1h30m`) into
+ * milliseconds. Unlike routines' parseTimeout, seconds are supported (polls tick
+ * in seconds). Returns null on empty/unparseable/zero input.
+ */
+export function parseInterval(interval) {
+    const match = interval.trim().match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
+    if (!match)
+        return null;
+    const weeks = parseInt(match[1] || '0', 10);
+    const days = parseInt(match[2] || '0', 10);
+    const hours = parseInt(match[3] || '0', 10);
+    const minutes = parseInt(match[4] || '0', 10);
+    const seconds = parseInt(match[5] || '0', 10);
+    const ms = ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+    return ms > 0 ? ms : null;
+}
+/**
+ * True when the monitor may evaluate + fire on this machine. Owner semantics:
+ * `device` (single owner, exactly-once) → only that machine; else `devices`
+ * (allowlist) → any listed machine; else unrestricted. Both sides normalize so
+ * `Yosemite-S0` and `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ */
+export function monitorRunsOnThisDevice(config) {
+    const self = machineId();
+    if (config.device)
+        return normalizeHost(config.device) === self;
+    if (config.devices && config.devices.length > 0) {
+        return config.devices.some((d) => normalizeHost(d) === self);
+    }
+    return true;
+}
+/** Count the populated source-payload fields to detect "two sources". */
+function populatedSourceFields(source) {
+    const fields = [
+        ['command', source.command],
+        ['url', source.url],
+        ['wsUrl', source.wsUrl],
+        ['path', source.path],
+        ['device', source.device],
+        ['webhook', source.webhook],
+    ];
+    return fields.filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k]) => k);
+}
+/** Which source-payload field each source type requires. */
+const SOURCE_TYPE_FIELD = {
+    command: 'command',
+    poll: 'command',
+    'poll-http': 'url',
+    webhook: 'webhook',
+    ws: 'wsUrl',
+    file: 'path',
+    device: 'device',
+};
+/** Count the populated action-payload fields to detect "two actions". */
+function populatedActionFields(action) {
+    const fields = [
+        ['agent', action.agent],
+        ['routine', action.routine],
+        ['url', action.url],
+    ];
+    return fields.filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k]) => k);
+}
+/**
+ * Validate a partial monitor config, returning a list of human-readable errors.
+ * Hand-rolled like validateJob (lib/routines.ts) — no zod. Rejects: no source,
+ * two sources, no action, two actions, match-mode without `match`, plus the
+ * per-type field/shape checks.
+ */
+export function validateMonitor(config) {
+    const errors = [];
+    if (!config.name || typeof config.name !== 'string') {
+        errors.push('name is required');
+    }
+    else if (!isSafeSegmentName(config.name)) {
+        errors.push(`invalid name ${JSON.stringify(config.name)}: must be a single path segment ` +
+            `(no '/', '\\\\', or null bytes, and not '.' or '..')`);
+    }
+    // ─── SOURCE ───────────────────────────────────────────────────────────────
+    const source = config.source;
+    if (!source || typeof source !== 'object') {
+        errors.push('a source is required (source: { type, ... })');
+    }
+    else {
+        if (!source.type || !SOURCE_TYPES.includes(source.type)) {
+            errors.push(`source.type must be one of: ${SOURCE_TYPES.join(', ')}`);
+        }
+        const populated = populatedSourceFields(source);
+        if (source.type && SOURCE_TYPES.includes(source.type)) {
+            const required = SOURCE_TYPE_FIELD[source.type];
+            // Two sources: any populated field that doesn't belong to this type.
+            const stray = populated.filter((f) => f !== required);
+            if (stray.length > 0) {
+                errors.push(`source has conflicting fields (${[required, ...stray].join(', ')}); specify exactly one source`);
+            }
+            if (!populated.includes(required)) {
+                errors.push(`source.type '${source.type}' requires source.${required}`);
+            }
+        }
+        else if (populated.length > 1) {
+            errors.push(`source has conflicting fields (${populated.join(', ')}); specify exactly one source`);
+        }
+        // Interval-bearing sources must carry a parseable interval.
+        if ((source.type === 'poll' || source.type === 'poll-http') && source.interval === undefined) {
+            errors.push(`source.type '${source.type}' requires source.interval (e.g. 30s, 15m, 8h)`);
+        }
+        if (source.interval !== undefined && parseInterval(source.interval) === null) {
+            errors.push(`source.interval must be like 30s, 15m, 8h, 1d (got ${JSON.stringify(source.interval)})`);
+        }
+        if (source.webhook !== undefined) {
+            const w = source.webhook;
+            if (!w || typeof w !== 'object') {
+                errors.push('source.webhook must be an object');
+            }
+            else if (w.source !== 'github' && w.source !== 'linear') {
+                errors.push("source.webhook.source must be 'github' or 'linear'");
+            }
+            else if (!w.event || typeof w.event !== 'string') {
+                errors.push('source.webhook.event is required');
+            }
+        }
+    }
+    // ─── CONDITION ──────────────────────────────────────────────────────────────
+    const condition = config.condition;
+    if (!condition || typeof condition !== 'object') {
+        errors.push('a condition is required (condition: { mode, ... })');
+    }
+    else {
+        if (!condition.mode || !CONDITION_MODES.includes(condition.mode)) {
+            errors.push(`condition.mode must be one of: ${CONDITION_MODES.join(', ')}`);
+        }
+        if (condition.mode === 'match') {
+            if (!condition.match || typeof condition.match !== 'string') {
+                errors.push("condition.mode 'match' requires condition.match (a regex)");
+            }
+        }
+        for (const key of ['match', 'dedupeKey']) {
+            const val = condition[key];
+            if (val !== undefined) {
+                if (typeof val !== 'string') {
+                    errors.push(`condition.${key} must be a regex string`);
+                }
+                else {
+                    try {
+                        new RegExp(val);
+                    }
+                    catch {
+                        errors.push(`condition.${key} is not a valid regular expression: ${JSON.stringify(val)}`);
+                    }
+                }
+            }
+        }
+    }
+    // ─── ACTION ─────────────────────────────────────────────────────────────────
+    const action = config.action;
+    if (!action || typeof action !== 'object') {
+        errors.push('an action is required (action: { type, ... })');
+    }
+    else {
+        if (!action.type || !ACTION_TYPES.includes(action.type)) {
+            errors.push(`action.type must be one of: ${ACTION_TYPES.join(', ')}`);
+        }
+        const populatedAct = populatedActionFields(action);
+        const requiredByType = {
+            run: 'agent',
+            routine: 'routine',
+            'webhook-out': 'url',
+        };
+        if (action.type && ACTION_TYPES.includes(action.type)) {
+            const required = requiredByType[action.type];
+            // Two actions: a populated field that belongs to a different action type.
+            const stray = populatedAct.filter((f) => f !== required);
+            if (stray.length > 0) {
+                errors.push(`action has conflicting fields (${[...(required ? [required] : []), ...stray].join(', ')}); specify exactly one action`);
+            }
+            if (required && !populatedAct.includes(required)) {
+                errors.push(`action.type '${action.type}' requires action.${required}`);
+            }
+        }
+        else if (populatedAct.length > 1) {
+            errors.push(`action has conflicting fields (${populatedAct.join(', ')}); specify exactly one action`);
+        }
+        if (action.type === 'run') {
+            if (action.agent && !ALL_AGENT_IDS.includes(action.agent)) {
+                errors.push(`action.agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
+            }
+            if (!action.prompt || typeof action.prompt !== 'string') {
+                errors.push("action.type 'run' requires action.prompt");
+            }
+            if (action.mode && !['plan', 'edit', 'auto', 'skip', 'full'].includes(action.mode)) {
+                errors.push("action.mode must be plan, edit, auto, or skip ('full' accepted as alias for skip)");
+            }
+            if (action.effort && !['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(action.effort)) {
+                errors.push('action.effort must be low, medium, high, xhigh, max, or auto');
+            }
+        }
+        if (action.type === 'webhook-out' && action.url) {
+            try {
+                // eslint-disable-next-line no-new
+                new URL(action.url);
+            }
+            catch {
+                errors.push(`action.url must be an absolute URL (got ${JSON.stringify(action.url)})`);
+            }
+        }
+    }
+    // ─── PLACEMENT ───────────────────────────────────────────────────────────────
+    if (config.device !== undefined && config.devices !== undefined) {
+        errors.push("device (single owner) and devices (allowlist) are mutually exclusive — pick one");
+    }
+    if (config.device !== undefined && (typeof config.device !== 'string' || config.device.trim() === '')) {
+        errors.push('device must be a non-empty device name');
+    }
+    if (config.devices !== undefined) {
+        if (!Array.isArray(config.devices)) {
+            errors.push('devices must be an array of device names');
+        }
+        else {
+            for (const d of config.devices) {
+                if (typeof d !== 'string' || d.trim() === '') {
+                    errors.push('each entry in devices must be a non-empty device name');
+                    break;
+                }
+            }
+        }
+    }
+    if (config.runOn !== undefined && (typeof config.runOn !== 'string' || config.runOn.trim() === '')) {
+        errors.push('runOn must be a non-empty machine name (a registered host, device, capability tag, or user@host)');
+    }
+    // ─── HYGIENE ─────────────────────────────────────────────────────────────────
+    if (config.rateLimit !== undefined) {
+        const rl = config.rateLimit;
+        if (!rl || typeof rl !== 'object' || typeof rl.max !== 'number' || rl.max <= 0) {
+            errors.push('rateLimit.max must be a positive number');
+        }
+        if (!rl || typeof rl.per !== 'string' || parseInterval(rl.per) === null) {
+            errors.push('rateLimit.per must be an interval like 1m, 1h, 1d');
+        }
+    }
+    return errors;
+}
+function readMonitorFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return {
+            ...MONITOR_DEFAULTS,
+            ...parsed,
+            name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** List all monitor configs in ~/.agents/monitors/. */
+export function listMonitors() {
+    ensureAgentsDir();
+    const dir = getMonitorsDir();
+    if (!fs.existsSync(dir))
+        return [];
+    const monitors = [];
+    const seen = new Set();
+    for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))) {
+        const monitor = readMonitorFile(path.join(dir, file));
+        if (!monitor || seen.has(monitor.name))
+            continue;
+        seen.add(monitor.name);
+        monitors.push(monitor);
+    }
+    return monitors;
+}
+/** Read a single monitor config by name. Returns null if not found or corrupt. */
+export function readMonitor(name) {
+    ensureAgentsDir();
+    const dir = getMonitorsDir();
+    for (const ext of ['.yml', '.yaml']) {
+        const filePath = safeJoin(dir, name + ext);
+        if (fs.existsSync(filePath))
+            return readMonitorFile(filePath);
+    }
+    return null;
+}
+/** Get the filesystem path of a monitor's YAML config, or null if not found. */
+export function getMonitorPath(name) {
+    const dir = getMonitorsDir();
+    for (const ext of ['.yml', '.yaml']) {
+        const filePath = safeJoin(dir, name + ext);
+        if (fs.existsSync(filePath))
+            return filePath;
+    }
+    return null;
+}
+/** Write a monitor config to disk atomically, omitting fields that match defaults. */
+export function writeMonitor(config) {
+    ensureAgentsDir();
+    const dir = getMonitorsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const ymlPath = safeJoin(dir, config.name + '.yml');
+    const yamlPath = safeJoin(dir, config.name + '.yaml');
+    if (fs.existsSync(ymlPath) && fs.existsSync(yamlPath)) {
+        throw new Error(`Monitor '${config.name}' has both .yml and .yaml files; resolve the ambiguity before editing.`);
+    }
+    const filePath = fs.existsSync(yamlPath) ? yamlPath : ymlPath;
+    const output = { ...config };
+    if (output.enabled === true)
+        delete output.enabled;
+    const devArr = output.devices;
+    if (!devArr || devArr.length === 0)
+        delete output.devices;
+    atomicWriteFileSync(filePath, yaml.stringify(output));
+}
+/** Delete a monitor config file by name. Returns true if the file existed. */
+export function deleteMonitor(name) {
+    const dir = getMonitorsDir();
+    for (const ext of ['.yml', '.yaml']) {
+        const filePath = safeJoin(dir, name + ext);
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+            return true;
+        }
+    }
+    return false;
+}
+/** Enable or disable a monitor by name. */
+export function setMonitorEnabled(name, enabled) {
+    const monitor = readMonitor(name);
+    if (!monitor)
+        throw new Error(`Monitor '${name}' not found`);
+    monitor.enabled = enabled;
+    writeMonitor(monitor);
+}
+/** Check whether a monitor with the given name exists on disk. */
+export function monitorExists(name) {
+    return readMonitor(name) !== null;
+}

package/dist/lib/monitors/dispatch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Monitor action dispatch.
+ *
+ * On a fire, the monitor feeds the event to an action. Every `run`/`routine`
+ * action goes through the *same* detached spawn cron and webhook fires use
+ * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
+ * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
+ * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ */
+import type { ActionConfig, MonitorConfig, MonitorEvent } from './config.js';
+/** Outcome of a dispatched action. */
+export interface DispatchResult {
+    kind: ActionConfig['type'];
+    ok: boolean;
+    /** Run id for `run`/`routine` actions dispatched through executeJobDetached. */
+    runId?: string;
+    error?: string;
+}
+/** Replace `{event}` in a prompt with the fired event summary. */
+export declare function injectEvent(prompt: string, event: MonitorEvent): string;
+/**
+ * Dispatch a monitor's action for a fired event. `run` synthesizes a JobConfig
+ * (event injected into the prompt, action fields mapped onto the routines shape,
+ * runOn → host placement) and calls executeJobDetached — the exact path routines
+ * use. `routine` fires an existing routine with the event injected. `notify` and
+ * `webhook-out` are terminal side-effects.
+ */
+export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent): Promise<DispatchResult>;

package/dist/lib/monitors/dispatch.js

@@ -0,0 +1,91 @@
+/**
+ * Monitor action dispatch.
+ *
+ * On a fire, the monitor feeds the event to an action. Every `run`/`routine`
+ * action goes through the *same* detached spawn cron and webhook fires use
+ * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
+ * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
+ * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { executeJobDetached } from '../runner.js';
+import { readJob } from '../routines.js';
+import { buildOpenClawNotifyArgs } from '../notify.js';
+const execFileAsync = promisify(execFile);
+/** Replace `{event}` in a prompt with the fired event summary. */
+export function injectEvent(prompt, event) {
+    return prompt.replace(/\{event\}/g, event.summary);
+}
+/**
+ * Dispatch a monitor's action for a fired event. `run` synthesizes a JobConfig
+ * (event injected into the prompt, action fields mapped onto the routines shape,
+ * runOn → host placement) and calls executeJobDetached — the exact path routines
+ * use. `routine` fires an existing routine with the event injected. `notify` and
+ * `webhook-out` are terminal side-effects.
+ */
+export async function dispatchAction(monitor, event) {
+    const action = monitor.action;
+    if (action.type === 'run') {
+        const job = {
+            name: monitor.name,
+            agent: action.agent,
+            mode: action.mode ?? 'auto',
+            effort: action.effort ?? 'auto',
+            timeout: action.timeout ?? '10m',
+            enabled: true,
+            prompt: injectEvent(action.prompt ?? '', event),
+            ...(monitor.variables ? { variables: monitor.variables } : {}),
+            ...(monitor.version ? { version: monitor.version } : {}),
+            ...(monitor.runOn ? { host: monitor.runOn } : {}),
+        };
+        try {
+            const meta = await executeJobDetached(job);
+            return { kind: 'run', ok: true, runId: meta.runId };
+        }
+        catch (err) {
+            return { kind: 'run', ok: false, error: err.message };
+        }
+    }
+    if (action.type === 'routine') {
+        const routine = action.routine ? readJob(action.routine) : null;
+        if (!routine) {
+            return { kind: 'routine', ok: false, error: `routine '${action.routine}' not found` };
+        }
+        // Inject the event into the routine's prompt so the fired routine sees it.
+        const fired = { ...routine, prompt: injectEvent(routine.prompt ?? '', event) };
+        try {
+            const meta = await executeJobDetached(fired);
+            return { kind: 'routine', ok: true, runId: meta.runId };
+        }
+        catch (err) {
+            return { kind: 'routine', ok: false, error: err.message };
+        }
+    }
+    if (action.type === 'notify') {
+        const args = buildOpenClawNotifyArgs(event.summary, {
+            channel: action.notifyChannel ?? 'telegram',
+        });
+        try {
+            await execFileAsync('openclaw', args);
+            return { kind: 'notify', ok: true };
+        }
+        catch (err) {
+            return { kind: 'notify', ok: false, error: err.message };
+        }
+    }
+    // webhook-out
+    if (!action.url)
+        return { kind: 'webhook-out', ok: false, error: 'action.url is required' };
+    try {
+        const res = await fetch(action.url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(event),
+        });
+        return { kind: 'webhook-out', ok: res.ok, ...(res.ok ? {} : { error: `HTTP ${res.status}` }) };
+    }
+    catch (err) {
+        return { kind: 'webhook-out', ok: false, error: err.message };
+    }
+}

package/dist/lib/monitors/engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type MonitorConfig, type MonitorEvent } from './config.js';
+import { type Observation } from './sources/index.js';
+/** The fire/no-fire decision for one observation, plus what to persist. */
+export interface FireDecision {
+    fire: boolean;
+    /** The value whose de-dupe signature is stored on persist. */
+    value: string;
+    /** The de-dupe key (regex) applied to the value, if any. */
+    dedupeKey?: string;
+    /** Persist `value` as the new baseline even when not firing (on-change baseline). */
+    persist: boolean;
+    /** The event to dispatch, present iff `fire`. */
+    event: MonitorEvent | null;
+}
+/**
+ * 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 declare function decideFire(monitor: MonitorConfig, observation: Observation): FireDecision;
+/** One evaluation of a monitor's source + condition, without side effects. Used by `test`. */
+export declare function evaluateMonitorOnce(monitor: MonitorConfig): Promise<{
+    observation: Observation | null;
+    decision: FireDecision | null;
+}>;
+type LogFn = (level: string, message: string) => void;
+/** The durable monitor engine. One instance per daemon. */
+export declare class MonitorEngine {
+    private logFn;
+    private timer;
+    private monitors;
+    private lastEval;
+    private ticking;
+    constructor(logFn?: LogFn);
+    /** Load owned+enabled monitors and start the tick loop. */
+    start(): void;
+    /** Reload monitor configs (SIGHUP). */
+    reload(): void;
+    /** Stop the tick loop. */
+    stop(): void;
+    private loadAll;
+    private intervalMs;
+    private isDue;
+    /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
+    tick(): Promise<void>;
+    private runMonitor;
+    private fire;
+}
+export {};