@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/lib/routines-project.js

@@ -0,0 +1,349 @@
+/**
+ * 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 * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { execFileSync } from 'child_process';
+import { getProjectAgentsDir, getProjectRoutinesDir, readMeta, updateMeta, ensureAgentsDir, } from './state.js';
+import { readJob, writeJob, deleteJob, listJobs, validateJob, resolveHostStrategy, placementRequiresFiringPin, } from './routines.js';
+import { parseOwnerRepoFromRemote } from './registry.js';
+import { machineId } from './machine-id.js';
+import { isSafeSegmentName } from './paths.js';
+/** Expand `~/…` and resolve to an absolute path. */
+export function expandProjectPath(p) {
+    const trimmed = p.trim();
+    if (trimmed.startsWith('~/') || trimmed === '~') {
+        return path.resolve(trimmed.replace(/^~(?=$|[/\\])/, os.homedir()));
+    }
+    return path.resolve(trimmed);
+}
+/** Store paths home-relative when under $HOME so they travel across machines. */
+export function displayProjectPath(abs) {
+    const home = os.homedir();
+    const resolved = path.resolve(abs);
+    if (resolved === home)
+        return '~';
+    if (resolved.startsWith(home + path.sep)) {
+        return '~' + resolved.slice(home.length);
+    }
+    return resolved;
+}
+/** Project roots currently opted into daemon firing (absolute paths). */
+export function listEnabledProjectRoots() {
+    const meta = readMeta();
+    const raw = meta.routines?.projects ?? [];
+    const out = [];
+    const seen = new Set();
+    for (const p of raw) {
+        if (typeof p !== 'string' || p.trim() === '')
+            continue;
+        const abs = expandProjectPath(p);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        out.push(abs);
+    }
+    return out;
+}
+/** True when this project root is on the opt-in allowlist. */
+export function isProjectRoutinesEnabled(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    return listEnabledProjectRoots().some((p) => p === abs);
+}
+/**
+ * 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 function projectAgentsYamlEnablesRoutines(projectRoot) {
+    const agentsYaml = path.join(expandProjectPath(projectRoot), 'agents.yaml');
+    if (!fs.existsSync(agentsYaml))
+        return false;
+    try {
+        const parsed = yaml.parse(fs.readFileSync(agentsYaml, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return false;
+        const routines = parsed.routines;
+        if (!routines || typeof routines !== 'object')
+            return false;
+        return routines.enable === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
+export function resolveProjectRoot(cwd = process.cwd()) {
+    const agentsDir = getProjectAgentsDir(cwd);
+    if (!agentsDir)
+        return null;
+    return path.dirname(agentsDir);
+}
+/**
+ * Opt a project root into daemon firing. Returns true when newly added,
+ * false when it was already enabled.
+ */
+export function enableProjectRoutines(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    const stored = displayProjectPath(abs);
+    let added = false;
+    updateMeta((meta) => {
+        const projects = [...(meta.routines?.projects ?? [])];
+        const already = projects.some((p) => expandProjectPath(p) === abs);
+        if (already)
+            return meta;
+        projects.push(stored);
+        added = true;
+        return {
+            ...meta,
+            routines: {
+                ...(meta.routines ?? {}),
+                projects,
+            },
+        };
+    });
+    return added;
+}
+/**
+ * Remove a project root from the opt-in allowlist. Optionally deletes the
+ * user-layer copies that were materialised from it.
+ */
+export function disableProjectRoutines(projectRoot, opts = {}) {
+    const abs = expandProjectPath(projectRoot);
+    let removed = false;
+    updateMeta((meta) => {
+        const projects = meta.routines?.projects ?? [];
+        const next = projects.filter((p) => expandProjectPath(p) !== abs);
+        if (next.length === projects.length)
+            return meta;
+        removed = true;
+        return {
+            ...meta,
+            routines: {
+                ...(meta.routines ?? {}),
+                projects: next,
+            },
+        };
+    });
+    const deletedJobs = [];
+    if (opts.removeSynced) {
+        for (const job of listJobs()) {
+            if (job.source?.kind === 'project' && expandProjectPath(job.source.projectPath) === abs) {
+                if (deleteJob(job.name))
+                    deletedJobs.push(job.name);
+            }
+        }
+    }
+    return { removed, deletedJobs };
+}
+/** Git provenance for a project root (best-effort; never throws). */
+export function readProjectGitSource(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    const out = {};
+    try {
+        const remote = execFileSync('git', ['-C', abs, 'remote', 'get-url', 'origin'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        const repo = parseOwnerRepoFromRemote(remote);
+        if (repo)
+            out.repo = repo;
+    }
+    catch { /* no origin */ }
+    try {
+        out.branch = execFileSync('git', ['-C', abs, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        if (out.branch === 'HEAD')
+            delete out.branch; // detached
+    }
+    catch { /* not a git repo */ }
+    try {
+        out.commit = execFileSync('git', ['-C', abs, 'rev-parse', '--short', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+    }
+    catch { /* ignore */ }
+    return out;
+}
+/** List project routine YAML files (name + absolute path). */
+export function listProjectRoutineFiles(projectRoot) {
+    const routinesDir = getProjectRoutinesDir(expandProjectPath(projectRoot));
+    if (!routinesDir || !fs.existsSync(routinesDir))
+        return [];
+    return fs.readdirSync(routinesDir)
+        .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+        .map((f) => ({
+        name: f.replace(/\.ya?ml$/, ''),
+        path: path.join(routinesDir, f),
+    }))
+        .filter((e) => isSafeSegmentName(e.name));
+}
+function readProjectJobFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
+            return null;
+        return {
+            mode: 'auto',
+            effort: 'auto',
+            timeout: '10m',
+            enabled: true,
+            ...parsed,
+            name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function syncProjectRoutines(projectRoot) {
+    ensureAgentsDir();
+    const abs = expandProjectPath(projectRoot);
+    const git = readProjectGitSource(abs);
+    const source = {
+        kind: 'project',
+        projectPath: abs,
+        ...(git.repo ? { repo: git.repo } : {}),
+        ...(git.branch ? { branch: git.branch } : {}),
+        ...(git.commit ? { commit: git.commit } : {}),
+    };
+    const result = {
+        projectRoot: abs,
+        synced: [],
+        skipped: [],
+        removed: [],
+        errors: [],
+    };
+    const files = listProjectRoutineFiles(abs);
+    const seenNames = new Set();
+    for (const file of files) {
+        seenNames.add(file.name);
+        const job = readProjectJobFile(file.path);
+        if (!job) {
+            result.errors.push({ name: file.name, error: 'unreadable or invalid YAML' });
+            continue;
+        }
+        const existing = readJob(file.name);
+        if (existing) {
+            const existingSource = existing.source;
+            const fromThisProject = existingSource?.kind === 'project'
+                && expandProjectPath(existingSource.projectPath) === abs;
+            if (!fromThisProject) {
+                result.skipped.push({
+                    name: file.name,
+                    reason: existingSource
+                        ? `user-layer routine already exists from another source (${existingSource.projectPath})`
+                        : 'user-layer routine already exists (hand-authored); not overwriting without source match',
+                });
+                continue;
+            }
+            // Preserve user-layer devices pin when project YAML omits it (same overlay
+            // semantics as listJobs project discovery).
+            if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
+                job.devices = existing.devices;
+            }
+        }
+        // Placement that leaves the firing machine must pin devices to avoid
+        // every fleet daemon dispatching once.
+        const strategy = resolveHostStrategy(job);
+        if (placementRequiresFiringPin(strategy) && (!job.devices || job.devices.length === 0)) {
+            job.devices = [machineId()];
+        }
+        // Surface repo for list/display when project has a GitHub origin.
+        if (git.repo && !job.repo)
+            job.repo = git.repo;
+        job.source = source;
+        job.name = file.name;
+        const errors = validateJob(job);
+        if (errors.length > 0) {
+            result.errors.push({ name: file.name, error: errors.join('; ') });
+            continue;
+        }
+        try {
+            writeJob(job);
+            result.synced.push(file.name);
+        }
+        catch (err) {
+            result.errors.push({ name: file.name, error: err.message });
+        }
+    }
+    // Drop user-layer copies from this project that no longer exist in project YAML.
+    for (const job of listJobs()) {
+        if (job.source?.kind !== 'project')
+            continue;
+        if (expandProjectPath(job.source.projectPath) !== abs)
+            continue;
+        if (seenNames.has(job.name))
+            continue;
+        if (deleteJob(job.name))
+            result.removed.push(job.name);
+    }
+    return result;
+}
+/**
+ * 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 function syncAllProjectRoutines(opts = {}) {
+    const roots = new Set(listEnabledProjectRoots());
+    for (const r of opts.extraRoots ?? [])
+        roots.add(expandProjectPath(r));
+    const projects = [];
+    const missing = [];
+    for (const root of roots) {
+        if (!fs.existsSync(root)) {
+            missing.push(root);
+            continue;
+        }
+        projects.push(syncProjectRoutines(root));
+    }
+    return { projects, missing };
+}
+/**
+ * Discover project routines at cwd for the setup UX. Returns null when no
+ * project `.agents/routines` dir exists.
+ */
+export function discoverProjectRoutinesAt(cwd = process.cwd()) {
+    const projectRoot = resolveProjectRoot(cwd);
+    if (!projectRoot)
+        return null;
+    const routinesDir = getProjectRoutinesDir(projectRoot);
+    if (!routinesDir || !fs.existsSync(routinesDir))
+        return null;
+    const files = listProjectRoutineFiles(projectRoot);
+    if (files.length === 0)
+        return null;
+    return {
+        projectRoot,
+        files,
+        enabled: isProjectRoutinesEnabled(projectRoot) || projectAgentsYamlEnablesRoutines(projectRoot),
+    };
+}

package/dist/lib/routines.d.ts

@@ -14,6 +14,29 @@ export interface JobAllowConfig {
     sites?: string[];
     dirs?: string[];
 }
+/**
+ * Where a routine's job body executes when the daemon fires it.
+ * Distinct from `devices` (which daemon may *fire*) and from the CLI `--host`
+ * remote-management passthrough (manage routines *on* another machine).
+ */
+export type HostStrategy = 'local' | 'host' | 'fleet' | 'cloud';
+export declare const HOST_STRATEGIES: readonly HostStrategy[];
+/**
+ * Provenance for a routine that was materialised from a project
+ * (`.agents/routines/*.yml` synced into the user layer after opt-in).
+ */
+export interface JobSource {
+    /** Always `project` today; reserved for future layers. */
+    kind: 'project';
+    /** Absolute path to the project root that owns the YAML. */
+    projectPath: string;
+    /** GitHub `owner/repo` when the project has a GitHub origin remote. */
+    repo?: string;
+    /** Branch at last sync (when known). */
+    branch?: string;
+    /** Short commit SHA at last sync (when known). */
+    commit?: string;
+}
 /** GitHub webhook events a routine can be triggered by. */
 export type GithubTriggerEvent = 'pull_request' | 'push' | 'issue_comment' | 'workflow_run';
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
@@ -102,10 +125,33 @@ export interface JobConfig {
      * `host` says where the dispatched run EXECUTES. CLI flag: `--run-on`
      * (`--host` on routines commands already means "manage routines on that
      * machine" via the remote passthrough).
+     *
+     * When `hostStrategy` is set, it owns placement semantics; `host` is then
+     * only required for `hostStrategy: host` (or when strategy is inferred from
+     * a bare `host:` field for back-compat).
      */
     host?: string;
+    /**
+     * Where the job body should run when the daemon fires it.
+     * - `local`  — on the firing machine (default / current behavior)
+     * - `host`   — on the named `host` over SSH (maps to `--run-on`)
+     * - `fleet`  — pick one online registered device per run (no cross-device
+     *              double-fire; the firing pin stays on `devices`)
+     * - `cloud`  — dispatch via the agent's native cloud provider
+     *
+     * CLI flag: `--placement` (not `--host`, which is the remote-management
+     * passthrough). Omitted strategy falls back to `host` when `host:` is set,
+     * otherwise `local`.
+     */
+    hostStrategy?: HostStrategy;
     /** Working directory on the host for `host:`-placed runs. */
     remoteCwd?: string;
+    /**
+     * Provenance for routines materialised from a project
+     * (`<project>/.agents/routines/*.yml` → user-layer copy after opt-in).
+     * Absent for hand-authored user/system routines.
+     */
+    source?: JobSource;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -166,6 +212,10 @@ export interface RunMeta {
     /** The host-task sidecar id backing a `host:` run; the daemon monitor
      *  finalizes the run by reconciling it against the remote `.exit`. */
     hostTaskId?: string;
+    /** Cloud provider task id when `hostStrategy: cloud` dispatched the run. */
+    cloudTaskId?: string;
+    /** Cloud provider id when the run was cloud-dispatched. */
+    cloudProvider?: string;
 }
 /**
  * Finalize a run record with a terminal status, computing `duration` from
@@ -184,6 +234,24 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * catchup/overdue, manual run) gates on this.
  */
 export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/**
+ * Resolve the effective host strategy for a job.
+ * Bare `host:` without an explicit strategy implies `host` (back-compat with
+ * pre-hostStrategy YAML). Otherwise default to `local`.
+ */
+export declare function resolveHostStrategy(config: Pick<JobConfig, 'hostStrategy' | 'host'>): HostStrategy;
+/**
+ * Parse a CLI `--placement` value into a HostStrategy, or null when empty.
+ * Throws a human-readable Error for unknown values.
+ */
+export declare function parseHostStrategy(raw: string | undefined | null): HostStrategy | null;
+/**
+ * Strategies that dispatch the job body off the firing machine. Without a
+ * `devices` pin every daemon in the fleet would fire and each would dispatch
+ * once — N× duplicate runs. Callers pin to this machine when the user did not
+ * set an explicit allowlist.
+ */
+export declare function placementRequiresFiringPin(strategy: HostStrategy): boolean;
 /** Human presentation of a device-affinity mismatch for commands and runner. */
 export interface JobEligibilityResult {
     /** Full human message, e.g. "Job 'NAME' can only run on: a, b". */

package/dist/lib/routines.js

@@ -15,6 +15,7 @@ import { safeJoin, isSafeSegmentName } from './paths.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
+export const HOST_STRATEGIES = ['local', 'host', 'fleet', 'cloud'];
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
     'pull_request',
@@ -84,6 +85,39 @@ export function jobRunsOnThisDevice(config) {
     const self = machineId();
     return config.devices.some((d) => normalizeHost(d) === self);
 }
+/**
+ * Resolve the effective host strategy for a job.
+ * Bare `host:` without an explicit strategy implies `host` (back-compat with
+ * pre-hostStrategy YAML). Otherwise default to `local`.
+ */
+export function resolveHostStrategy(config) {
+    if (config.hostStrategy)
+        return config.hostStrategy;
+    if (config.host)
+        return 'host';
+    return 'local';
+}
+/**
+ * Parse a CLI `--placement` value into a HostStrategy, or null when empty.
+ * Throws a human-readable Error for unknown values.
+ */
+export function parseHostStrategy(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return null;
+    const v = raw.trim().toLowerCase();
+    if (HOST_STRATEGIES.includes(v))
+        return v;
+    throw new Error(`Invalid placement '${raw}'. Use one of: ${HOST_STRATEGIES.join(', ')}`);
+}
+/**
+ * Strategies that dispatch the job body off the firing machine. Without a
+ * `devices` pin every daemon in the fleet would fire and each would dispatch
+ * once — N× duplicate runs. Callers pin to this machine when the user did not
+ * set an explicit allowlist.
+ */
+export function placementRequiresFiringPin(strategy) {
+    return strategy === 'host' || strategy === 'fleet' || strategy === 'cloud';
+}
 /**
  * Return null when the job may run here; otherwise return a structured,
  * human-friendly eligibility failure. Centralizes the message/suggestion
@@ -419,24 +453,48 @@ export function validateJob(config) {
     if (config.device !== undefined) {
         errors.push('singular "device" key is no longer supported — replace with devices: [<name>] (an array)');
     }
+    if (config.hostStrategy !== undefined) {
+        if (!HOST_STRATEGIES.includes(config.hostStrategy)) {
+            errors.push(`hostStrategy must be one of: ${HOST_STRATEGIES.join(', ')}`);
+        }
+    }
+    const strategy = resolveHostStrategy(config);
     if (config.host !== undefined) {
         if (typeof config.host !== 'string' || config.host.trim() === '') {
             errors.push('host must be a non-empty machine name (a registered host, device, capability tag, or user@host)');
         }
-        // v1: the workflow bundle and the loop driver (with its signal files) live
-        // on the firing machine — neither can cross SSH to the target yet.
+    }
+    if (strategy === 'host' && (!config.host || config.host.trim() === '')) {
+        errors.push("hostStrategy: host requires host: (set via --run-on or host: in YAML)");
+    }
+    // Remote placement (host/fleet/cloud) can't carry workflow/loop/command yet —
+    // those live on the firing machine.
+    if (strategy === 'host' || strategy === 'fleet' || strategy === 'cloud') {
         if (config.workflow) {
-            errors.push("host: can't be combined with workflow: yet (the bundle lives on the firing machine) — run the workflow locally or convert it to a plain prompt");
+            errors.push(`${strategy} placement can't be combined with workflow: yet — run the workflow locally or convert it to a plain prompt`);
         }
         if (config.loop) {
-            errors.push("host: can't be combined with loop: yet (the loop driver and its signal files live on the firing machine)");
+            errors.push(`${strategy} placement can't be combined with loop: yet (the loop driver and its signal files live on the firing machine)`);
         }
         if (config.command) {
-            errors.push("host: can't be combined with command: yet (a plain shell command has no agent to place remotely) — run it locally, or convert it to a prompt");
+            errors.push(`${strategy} placement can't be combined with command: yet (a plain shell command has no agent to place remotely)`);
         }
     }
-    if (config.remoteCwd !== undefined && config.host === undefined) {
-        errors.push('remoteCwd only applies to host:-placed routines — set host: too, or drop it');
+    if (config.remoteCwd !== undefined && strategy !== 'host' && strategy !== 'fleet') {
+        errors.push('remoteCwd only applies to host/fleet-placed routines — set hostStrategy: host|fleet, or drop it');
+    }
+    if (config.source !== undefined) {
+        if (!config.source || typeof config.source !== 'object') {
+            errors.push('source must be an object');
+        }
+        else {
+            if (config.source.kind !== 'project') {
+                errors.push("source.kind must be 'project'");
+            }
+            if (typeof config.source.projectPath !== 'string' || config.source.projectPath.trim() === '') {
+                errors.push('source.projectPath must be a non-empty absolute path');
+            }
+        }
     }
     if (config.devices !== undefined) {
         if (!Array.isArray(config.devices)) {
@@ -451,6 +509,15 @@ export function validateJob(config) {
             }
         }
     }
+    // Off-box placement without a devices pin fires on every fleet daemon and
+    // each dispatches once (RUSH-1980). Enforce the pin at validation so hand
+    // edits and devices --clear cannot re-open the hole.
+    if (placementRequiresFiringPin(strategy)) {
+        if (!config.devices || config.devices.length === 0) {
+            errors.push(`hostStrategy: ${strategy} requires devices: [<name>] to pin which daemon may fire ` +
+                '(otherwise every fleet daemon dispatches once). Pin to one machine, e.g. devices: [this-host]');
+        }
+    }
     return errors;
 }
 /** Validate a job trigger block, returning a list of human-readable errors. */

package/dist/lib/runner.d.ts

@@ -77,9 +77,19 @@ export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, ag
  * failover across healthy same-agent accounts (RUSH-1016).
  */
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
+/**
+ * Optional lifecycle callbacks for a detached routine run. The daemon passes an
+ * `onFinish` that fires the branded finish/output notification (RUSH-2030) — it
+ * runs from the in-process settle() when the child exits, the only seam that
+ * observes the live running→terminal transition (the monitor tick would already
+ * see a finalized record and skip it). Never let a hook throw into finalization.
+ */
+export interface RoutineHooks {
+    /** Called once with the finalized meta when the run reaches a terminal state. */
+    onFinish?: (meta: RunMeta) => void;
+}
 /** Spawn a job as a detached process and return immediately with run metadata. */
-/** Spawn a job as a detached process and return immediately with run metadata. */
-export declare function executeJobDetached(config: JobConfig): Promise<RunMeta>;
+export declare function executeJobDetached(config: JobConfig, hooks?: RoutineHooks): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
 /** Scan all runs marked "running" and finalize any whose process has exited. */