@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/lib/overdue.js

@@ -12,9 +12,8 @@
  * `agents routines catchup` command that runs them on demand.
  */
 import { Cron } from 'croner';
-import * as os from 'os';
-import { spawn } from 'child_process';
 import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
+import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -77,50 +76,18 @@ export function detectOverdueJobs(now = new Date()) {
     return overdue;
 }
 /**
- * Fire a native desktop notification. Best-effort — failures (missing
- * `osascript`/`notify-send`, no display, headless box) are swallowed so a
- * notification attempt can never take the daemon down.
+ * Fire a branded desktop notification listing the overdue jobs. Routed through
+ * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
+ * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
+ * a missing notifier or absent display is swallowed and never crashes the daemon.
  */
-export function notifyDesktop(title, body) {
-    const platform = os.platform();
-    try {
-        if (platform === 'darwin') {
-            const safeTitle = title.replace(/"/g, '\\"');
-            const safeBody = body.replace(/"/g, '\\"');
-            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
-            // A missing binary surfaces as an async 'error' event, NOT a synchronous
-            // throw the try/catch would catch. Without a listener Node re-throws it as
-            // an uncaught exception and takes the whole daemon down. Swallow it — the
-            // notification is best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-        else if (platform === 'linux') {
-            const child = spawn('notify-send', [title, body], {
-                detached: true,
-                stdio: 'ignore',
-            });
-            // Headless Linux boxes have no `notify-send` (libnotify-bin); its ENOENT
-            // arrives as an async 'error' event, not a throw. Without this listener
-            // the daemon crashes on every overdue routine and systemd restart-loops it
-            // (which also tears down the browser IPC socket). Swallow — best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-    }
-    catch {
-        // Notification is best-effort; nothing to do.
-    }
-}
-/** Fire a native desktop notification listing the overdue jobs. Best-effort. */
 export function notifyOverdue(jobs) {
     if (jobs.length === 0)
         return;
-    const title = jobs.length === 1
-        ? `Routine overdue: ${jobs[0].name}`
-        : `${jobs.length} routines overdue`;
+    const title = jobs.length === 1 ? 'Routine overdue' : `${jobs.length} routines overdue`;
+    const subtitle = jobs.length === 1 ? jobs[0].name : undefined;
     const body = jobs.length === 1
         ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
         : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
-    notifyDesktop(title, body);
+    notifyDesktop({ title, subtitle, body, action: 'routines:list' });
 }

package/dist/lib/routine-notify.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Routine lifecycle desktop notifications (RUSH-2030).
+ *
+ * The daemon fires a branded notification when a scheduled routine starts and
+ * when it finishes (success or failure), routed through the MenubarHelper
+ * companion (notify-desktop.ts) so it carries the agents-cli mark.
+ *
+ * Anti-spam threshold (Acceptance Criteria #4 — "define a sensible threshold so
+ * users are not spammed"):
+ *   - Agent / workflow routines: notify on BOTH start and finish. These are the
+ *     runs whose output a user actually wants surfaced.
+ *   - Command routines (deterministic housekeeping — version checks, `git pull`,
+ *     notify shims that can fire every minute): notify only on FAILURE. A green
+ *     housekeeping run is noise; a broken one is worth a ping. No start ping.
+ *   - "Notable output" is folded into the single finish notification rather than
+ *     sent as a third message: on failure the error reason, on success the first
+ *     line of the run's report (the user-facing result) when the routine produced
+ *     one. One start + one finish per run — never a stream.
+ *
+ * The pure builders (`routineStartNotification` / `routineFinishNotification`)
+ * return `null` when the threshold says "don't notify", and are unit-tested; the
+ * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
+ */
+import type { JobConfig, RunMeta } from './routines.js';
+import { type DesktopNotification } from './menubar/notify-desktop.js';
+type RoutineKind = 'agent' | 'workflow' | 'command';
+/** Which flavor of routine a config/meta describes — drives the notify threshold. */
+export declare function routineKind(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
+/** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
+export declare function formatDuration(ms: number | undefined): string | null;
+/**
+ * First non-empty line of a run report, trimmed to a notification-sized snippet.
+ * This is the "notable output" surfaced on a successful finish — the routine's
+ * own user-facing result. Returns null for an empty/whitespace report so the
+ * caller falls back to a plain "Completed" body.
+ */
+export declare function notableSnippet(report: string | null | undefined, maxLen?: number): string | null;
+/**
+ * Notification for a routine START, or null when the threshold suppresses it
+ * (command-mode housekeeping). Clicking opens the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineStartNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>): DesktopNotification | null;
+/**
+ * Notification for a routine that failed to even START — `executeJobDetached`
+ * threw before the child was spawned, so no run record and no finish will ever
+ * exist. The daemon fires the START notification unconditionally, so this closes
+ * the "exactly one start + one finish" invariant: the orphaned start gets its
+ * matching failure banner (RUSH-2030). Unlike a green finish this is never
+ * suppressed — a broken start is worth a ping for every routine kind, including
+ * command housekeeping. Clicking opens the runs folder (~/.agents/.history/runs)
+ * since there is no run report to open.
+ */
+export declare function routineStartFailedNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>, error: string): DesktopNotification;
+/**
+ * Notification for a routine FINISH, or null when the threshold suppresses it
+ * (a successful command-mode housekeeping run). Success carries the report's
+ * first line when present (the notable output); failure carries the reason.
+ * Clicking opens the run report/log when one is available, else the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineFinishNotification(meta: Pick<RunMeta, 'jobName' | 'status' | 'exitCode' | 'errorMessage' | 'duration' | 'agent' | 'workflow' | 'command'>, opts?: {
+    report?: string | null;
+    artifactPath?: string | null;
+}): DesktopNotification | null;
+/** Daemon glue: fire the START notification for a triggered routine. Best-effort. */
+export declare function notifyRoutineStart(config: JobConfig): void;
+/**
+ * Daemon glue: fire the "failed to start" notification when a routine trigger
+ * threw before spawning a child. Pairs with the unconditional START ping so a
+ * pre-spawn failure never leaves an orphaned "Routine started". Best-effort.
+ */
+export declare function notifyRoutineStartFailed(config: JobConfig, error: string): void;
+/** Daemon glue: fire the FINISH notification for a completed run. Best-effort. */
+export declare function notifyRoutineFinish(meta: RunMeta): void;
+export {};

package/dist/lib/routine-notify.js

@@ -0,0 +1,190 @@
+/**
+ * Routine lifecycle desktop notifications (RUSH-2030).
+ *
+ * The daemon fires a branded notification when a scheduled routine starts and
+ * when it finishes (success or failure), routed through the MenubarHelper
+ * companion (notify-desktop.ts) so it carries the agents-cli mark.
+ *
+ * Anti-spam threshold (Acceptance Criteria #4 — "define a sensible threshold so
+ * users are not spammed"):
+ *   - Agent / workflow routines: notify on BOTH start and finish. These are the
+ *     runs whose output a user actually wants surfaced.
+ *   - Command routines (deterministic housekeeping — version checks, `git pull`,
+ *     notify shims that can fire every minute): notify only on FAILURE. A green
+ *     housekeeping run is noise; a broken one is worth a ping. No start ping.
+ *   - "Notable output" is folded into the single finish notification rather than
+ *     sent as a third message: on failure the error reason, on success the first
+ *     line of the run's report (the user-facing result) when the routine produced
+ *     one. One start + one finish per run — never a stream.
+ *
+ * The pure builders (`routineStartNotification` / `routineFinishNotification`)
+ * return `null` when the threshold says "don't notify", and are unit-tested; the
+ * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getRunDir } from './routines.js';
+import { notifyDesktop } from './menubar/notify-desktop.js';
+/** Which flavor of routine a config/meta describes — drives the notify threshold. */
+export function routineKind(r) {
+    if (r.command)
+        return 'command';
+    if (r.workflow)
+        return 'workflow';
+    return 'agent';
+}
+/** Human label for the routine body ("agent claude", "workflow deploy", "command"). */
+function routineLabel(r) {
+    if (r.command)
+        return 'command';
+    if (r.workflow)
+        return `workflow ${r.workflow}`;
+    return `agent ${r.agent ?? 'unknown'}`;
+}
+/** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
+export function formatDuration(ms) {
+    if (ms === undefined || !Number.isFinite(ms) || ms < 0)
+        return null;
+    const totalSec = Math.round(ms / 1000);
+    if (totalSec < 60)
+        return `${totalSec}s`;
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    if (min < 60)
+        return sec ? `${min}m ${sec}s` : `${min}m`;
+    const hr = Math.floor(min / 60);
+    const remMin = min % 60;
+    return remMin ? `${hr}h ${remMin}m` : `${hr}h`;
+}
+/**
+ * First non-empty line of a run report, trimmed to a notification-sized snippet.
+ * This is the "notable output" surfaced on a successful finish — the routine's
+ * own user-facing result. Returns null for an empty/whitespace report so the
+ * caller falls back to a plain "Completed" body.
+ */
+export function notableSnippet(report, maxLen = 140) {
+    if (!report)
+        return null;
+    const firstLine = report
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!firstLine)
+        return null;
+    return firstLine.length > maxLen ? `${firstLine.slice(0, maxLen - 1).trimEnd()}…` : firstLine;
+}
+/** Encode a click action that opens a file (report/log) in the default app. */
+function openAction(filePath) {
+    return filePath ? `open:${filePath}` : undefined;
+}
+/**
+ * Notification for a routine START, or null when the threshold suppresses it
+ * (command-mode housekeeping). Clicking opens the runs folder
+ * (~/.agents/.history/runs).
+ */
+export function routineStartNotification(config) {
+    if (routineKind(config) === 'command')
+        return null;
+    return {
+        title: 'Routine started',
+        subtitle: config.name,
+        body: `Running ${routineLabel(config)}`,
+        action: 'routines:list',
+    };
+}
+/**
+ * Notification for a routine that failed to even START — `executeJobDetached`
+ * threw before the child was spawned, so no run record and no finish will ever
+ * exist. The daemon fires the START notification unconditionally, so this closes
+ * the "exactly one start + one finish" invariant: the orphaned start gets its
+ * matching failure banner (RUSH-2030). Unlike a green finish this is never
+ * suppressed — a broken start is worth a ping for every routine kind, including
+ * command housekeeping. Clicking opens the runs folder (~/.agents/.history/runs)
+ * since there is no run report to open.
+ */
+export function routineStartFailedNotification(config, error) {
+    return {
+        title: 'Routine failed',
+        subtitle: config.name,
+        body: `Failed to start: ${error}`,
+        action: 'routines:list',
+    };
+}
+/**
+ * Notification for a routine FINISH, or null when the threshold suppresses it
+ * (a successful command-mode housekeeping run). Success carries the report's
+ * first line when present (the notable output); failure carries the reason.
+ * Clicking opens the run report/log when one is available, else the runs folder
+ * (~/.agents/.history/runs).
+ */
+export function routineFinishNotification(meta, opts = {}) {
+    const kind = routineKind(meta);
+    const ok = meta.status === 'completed';
+    if (kind === 'command' && ok)
+        return null; // green housekeeping is noise
+    const action = openAction(opts.artifactPath) ?? 'routines:list';
+    if (ok) {
+        const snippet = notableSnippet(opts.report);
+        const dur = formatDuration(meta.duration);
+        return {
+            title: 'Routine finished',
+            subtitle: meta.jobName,
+            body: snippet ?? (dur ? `Completed in ${dur}` : 'Completed'),
+            action,
+        };
+    }
+    // failed | timeout
+    const reason = meta.status === 'timeout'
+        ? 'Timed out'
+        : meta.errorMessage
+            ? meta.errorMessage
+            : `Exited with code ${meta.exitCode ?? '?'}`;
+    return {
+        title: 'Routine failed',
+        subtitle: meta.jobName,
+        body: reason,
+        action,
+    };
+}
+/** Read a finished run's report text + the best artifact to open on click. */
+function loadRunArtifacts(meta) {
+    try {
+        const runDir = getRunDir(meta.jobName, meta.runId);
+        const reportPath = path.join(runDir, 'report.md');
+        const stdoutPath = path.join(runDir, 'stdout.log');
+        let report = null;
+        let artifactPath = null;
+        if (fs.existsSync(reportPath)) {
+            report = fs.readFileSync(reportPath, 'utf-8');
+            artifactPath = reportPath;
+        }
+        else if (fs.existsSync(stdoutPath)) {
+            artifactPath = stdoutPath;
+        }
+        return { report, artifactPath };
+    }
+    catch {
+        return { report: null, artifactPath: null };
+    }
+}
+/** Daemon glue: fire the START notification for a triggered routine. Best-effort. */
+export function notifyRoutineStart(config) {
+    const n = routineStartNotification(config);
+    if (n)
+        notifyDesktop(n);
+}
+/**
+ * Daemon glue: fire the "failed to start" notification when a routine trigger
+ * threw before spawning a child. Pairs with the unconditional START ping so a
+ * pre-spawn failure never leaves an orphaned "Routine started". Best-effort.
+ */
+export function notifyRoutineStartFailed(config, error) {
+    notifyDesktop(routineStartFailedNotification(config, error));
+}
+/** Daemon glue: fire the FINISH notification for a completed run. Best-effort. */
+export function notifyRoutineFinish(meta) {
+    const { report, artifactPath } = loadRunArtifacts(meta);
+    const n = routineFinishNotification(meta, { report, artifactPath });
+    if (n)
+        notifyDesktop(n);
+}

package/dist/lib/routines-placement.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Runtime placement resolution for routines: local / host / fleet / cloud.
+ *
+ * The scheduler only decides *whether* this machine may fire the job
+ * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
+ * body runs* once it has been fired, using `hostStrategy`.
+ *
+ * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
+ * fire. Cross-device double-fire is prevented by requiring a `devices` firing
+ * pin for fleet/host/cloud strategies (applied at add/sync time).
+ */
+import type { JobConfig } from './routines.js';
+export type PlacementTarget = {
+    mode: 'local';
+} | {
+    mode: 'host';
+    host: string;
+} | {
+    mode: 'cloud';
+};
+/**
+ * Pick one online fleet device for `hostStrategy: fleet`.
+ *
+ * Preference order:
+ * 1. This machine, if online and eligible (avoids needless SSH)
+ * 2. First eligible online device by name (stable / deterministic)
+ *
+ * `config.devices` is the *firing* allowlist only (which daemon may fire the
+ * job). It is intentionally NOT used as an execution pool filter — otherwise
+ * the double-fire pin (`devices: [self]`) would collapse fleet placement to
+ * always-local. Control / offline / no-address devices are never chosen.
+ */
+export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>): string | null;
+/**
+ * Resolve where a fired job's body should execute.
+ * Throws a human-readable Error when placement cannot be satisfied.
+ */
+export declare function resolvePlacementTarget(config: JobConfig): PlacementTarget;

package/dist/lib/routines-placement.js

@@ -0,0 +1,79 @@
+/**
+ * Runtime placement resolution for routines: local / host / fleet / cloud.
+ *
+ * The scheduler only decides *whether* this machine may fire the job
+ * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
+ * body runs* once it has been fired, using `hostStrategy`.
+ *
+ * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
+ * fire. Cross-device double-fire is prevented by requiring a `devices` firing
+ * pin for fleet/host/cloud strategies (applied at add/sync time).
+ */
+import { resolveHostStrategy } from './routines.js';
+import { machineId, normalizeHost } from './machine-id.js';
+import { loadDevicesSync } from './devices/registry.js';
+import { planFleetTargets } from './devices/fleet.js';
+/**
+ * Pick one online fleet device for `hostStrategy: fleet`.
+ *
+ * Preference order:
+ * 1. This machine, if online and eligible (avoids needless SSH)
+ * 2. First eligible online device by name (stable / deterministic)
+ *
+ * `config.devices` is the *firing* allowlist only (which daemon may fire the
+ * job). It is intentionally NOT used as an execution pool filter — otherwise
+ * the double-fire pin (`devices: [self]`) would collapse fleet placement to
+ * always-local. Control / offline / no-address devices are never chosen.
+ */
+export function pickFleetDevice(_config) {
+    let reg;
+    try {
+        reg = loadDevicesSync();
+    }
+    catch {
+        return null;
+    }
+    const planned = planFleetTargets(reg);
+    const candidates = planned.filter((t) => !t.skip).map((t) => t.device.name);
+    if (candidates.length === 0) {
+        // No registry / nothing online: fall back to self so a single-box fleet
+        // without a registry entry still runs locally.
+        return machineId();
+    }
+    const self = machineId();
+    const selfMatch = candidates.find((n) => normalizeHost(n) === self);
+    if (selfMatch)
+        return selfMatch;
+    return [...candidates].sort((a, b) => a.localeCompare(b))[0] ?? null;
+}
+/**
+ * Resolve where a fired job's body should execute.
+ * Throws a human-readable Error when placement cannot be satisfied.
+ */
+export function resolvePlacementTarget(config) {
+    const strategy = resolveHostStrategy(config);
+    switch (strategy) {
+        case 'local':
+            return { mode: 'local' };
+        case 'host': {
+            if (!config.host || config.host.trim() === '') {
+                throw new Error(`Routine '${config.name}' has hostStrategy: host but no host: — set host: or --run-on`);
+            }
+            // host: pointing at this machine is local execution (no SSH loop).
+            if (normalizeHost(config.host) === machineId())
+                return { mode: 'local' };
+            return { mode: 'host', host: config.host };
+        }
+        case 'fleet': {
+            const picked = pickFleetDevice(config);
+            if (!picked) {
+                throw new Error(`Routine '${config.name}' hostStrategy: fleet — no eligible online device to place the run`);
+            }
+            if (normalizeHost(picked) === machineId())
+                return { mode: 'local' };
+            return { mode: 'host', host: picked };
+        }
+        case 'cloud':
+            return { mode: 'cloud' };
+    }
+}

package/dist/lib/routines-project.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project-level routine opt-in, source tracking, and user-layer sync.
+ *
+ * Project YAML under `<project>/.agents/routines/*.yml` is inspection-only by
+ * default (a cloned public repo must never auto-fire agent prompts). After an
+ * explicit opt-in, routines are materialised into `~/.agents/routines/` with
+ * `source:` provenance so the daemon — which only loads user + system layers —
+ * can fire them. `syncProjectRoutines` refreshes the user-layer copies when
+ * project YAML changes (also invoked on daemon SIGHUP).
+ */
+import { type JobSource } from './routines.js';
+/** Expand `~/…` and resolve to an absolute path. */
+export declare function expandProjectPath(p: string): string;
+/** Store paths home-relative when under $HOME so they travel across machines. */
+export declare function displayProjectPath(abs: string): string;
+/** Project roots currently opted into daemon firing (absolute paths). */
+export declare function listEnabledProjectRoots(): string[];
+/** True when this project root is on the opt-in allowlist. */
+export declare function isProjectRoutinesEnabled(projectRoot: string): boolean;
+/**
+ * True when the project's own `agents.yaml` opts into project routines:
+ * `routines: { enable: true }`. This is an additional source of opt-in that
+ * still requires the project to be present on disk; it does not auto-enable
+ * every clone — the project must declare it, and `sync` / `enable-project`
+ * still materialises consent into the user layer.
+ */
+export declare function projectAgentsYamlEnablesRoutines(projectRoot: string): boolean;
+/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
+export declare function resolveProjectRoot(cwd?: string): string | null;
+/**
+ * Opt a project root into daemon firing. Returns true when newly added,
+ * false when it was already enabled.
+ */
+export declare function enableProjectRoutines(projectRoot: string): boolean;
+/**
+ * Remove a project root from the opt-in allowlist. Optionally deletes the
+ * user-layer copies that were materialised from it.
+ */
+export declare function disableProjectRoutines(projectRoot: string, opts?: {
+    removeSynced?: boolean;
+}): {
+    removed: boolean;
+    deletedJobs: string[];
+};
+/** Git provenance for a project root (best-effort; never throws). */
+export declare function readProjectGitSource(projectRoot: string): Pick<JobSource, 'repo' | 'branch' | 'commit'>;
+/** List project routine YAML files (name + absolute path). */
+export declare function listProjectRoutineFiles(projectRoot: string): Array<{
+    name: string;
+    path: string;
+}>;
+export interface SyncProjectResult {
+    projectRoot: string;
+    synced: string[];
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    removed: string[];
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * Materialise one project's routines into the user layer.
+ * - Overwrites user copies that already carry matching `source.projectPath`
+ * - Never clobbers a hand-authored user routine (no source / different source)
+ * - Removes user copies from this project whose YAML disappeared
+ * - Auto-pins `devices` for host/fleet/cloud placement when unset
+ */
+export declare function syncProjectRoutines(projectRoot: string): SyncProjectResult;
+export interface SyncAllResult {
+    projects: SyncProjectResult[];
+    /** Project roots that were listed but missing on disk. */
+    missing: string[];
+}
+/**
+ * Sync every project root on the user allowlist (`meta.routines.projects`),
+ * plus any explicit `extraRoots`. Project `agents.yaml` `routines.enable`
+ * alone never opts a path in — enable-project is required.
+ */
+export declare function syncAllProjectRoutines(opts?: {
+    extraRoots?: string[];
+}): SyncAllResult;
+/**
+ * Discover project routines at cwd for the setup UX. Returns null when no
+ * project `.agents/routines` dir exists.
+ */
+export declare function discoverProjectRoutinesAt(cwd?: string): {
+    projectRoot: string;
+    files: Array<{
+        name: string;
+        path: string;
+    }>;
+    enabled: boolean;
+} | null;