@phnx-labs/agents-cli 1.22.14 → 1.22.16

package/dist/lib/state.js

@@ -60,6 +60,10 @@ const LEGACY_SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
 const META_FILE = path.join(USER_AGENTS_DIR, 'agents.yaml');
 /** Legacy location — used only for one-shot migration in readMeta(). */
 const SYSTEM_META_FILE = path.join(SYSTEM_AGENTS_DIR, 'agents.yaml');
+/** Canonical path for the humans.yaml owner-identity/channel config. */
+const HUMANS_FILE = path.join(USER_AGENTS_DIR, 'humans.yaml');
+/** Return the absolute path to the humans.yaml file. */
+export function getHumansFilePath() { return process.env.AGENTS_HUMANS_FILE ?? HUMANS_FILE; }
 // ─── System resource dirs ─────────────────────────────────────────────────────
 const SYSTEM_COMMANDS_DIR = path.join(SYSTEM_AGENTS_DIR, 'commands');
 const SYSTEM_HOOKS_DIR = path.join(SYSTEM_AGENTS_DIR, 'hooks');
@@ -300,7 +304,7 @@ export function getResolvedRulesDir() { return SYSTEM_RULES_DIR; }
 /** Path to MCP server YAML configs — system repo. */
 export function getMcpDir() { return SYSTEM_MCP_DIR; }
 /** Path to permission group YAML files — system repo. */
-export function getPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
+export function getPermissionsDir() { return process.env.AGENTS_SYSTEM_PERMISSIONS_DIR ?? SYSTEM_PERMISSIONS_DIR; }
 /** Path to subagent definition directories — system repo. */
 export function getSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
 /** Path to ~/.agents/.system/hooks/promptcuts.yaml (system defaults). */
@@ -359,7 +363,7 @@ export function getUserHooksDir() { return USER_HOOKS_DIR; }
 export function getUserSkillsDir() { return USER_SKILLS_DIR; }
 export function getUserRulesDir() { return USER_RULES_DIR; }
 export function getUserMcpDir() { return USER_MCP_DIR; }
-export function getUserPermissionsDir() { return USER_PERMISSIONS_DIR; }
+export function getUserPermissionsDir() { return process.env.AGENTS_USER_PERMISSIONS_DIR ?? USER_PERMISSIONS_DIR; }
 export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
 export function getSystemWorkflowsDir() { return SYSTEM_WORKFLOWS_DIR; }
 export function getUserWorkflowsDir() { return USER_WORKFLOWS_DIR; }
@@ -674,8 +678,6 @@ export function ensureAgentsDir() {
         fs.mkdirSync(PACKAGES_DIR, opts);
     if (!fs.existsSync(ROUTINES_DIR))
         fs.mkdirSync(ROUTINES_DIR, opts);
-    if (!fs.existsSync(WEBHOOKS_DIR))
-        fs.mkdirSync(WEBHOOKS_DIR, opts);
     if (!fs.existsSync(RUNS_DIR))
         fs.mkdirSync(RUNS_DIR, opts);
     if (!fs.existsSync(VERSIONS_DIR))
@@ -694,8 +696,6 @@ export function ensureAgentsDir() {
         fs.mkdirSync(SYSTEM_PERMISSIONS_DIR, opts);
     if (!fs.existsSync(SYSTEM_SUBAGENTS_DIR))
         fs.mkdirSync(SYSTEM_SUBAGENTS_DIR, opts);
-    if (!fs.existsSync(SYSTEM_WEBHOOKS_DIR))
-        fs.mkdirSync(SYSTEM_WEBHOOKS_DIR, opts);
     try {
         fs.chmodSync(SYSTEM_AGENTS_DIR, 0o700);
     }
@@ -812,6 +812,7 @@ const META_KEY_SCOPE = {
     versions: 'device',
     defaultBrowserProfile: 'device',
     deviceConfig: 'device',
+    deviceRoutines: 'device',
     // Central — synced via agents.yaml.
     run: 'central',
     model: 'central',
@@ -909,7 +910,7 @@ function serializeCentral(central) {
     return isEmpty ? META_HEADER : doc.toString({ collectionStyle: 'block' });
 }
 function writeMetaUnlocked(meta) {
-    const { agents, isolatedAgents, versions, defaultBrowserProfile, deviceConfig, ...central } = meta;
+    const { agents, isolatedAgents, versions, defaultBrowserProfile, deviceConfig, deviceRoutines, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const devicePath = getDeviceMetaPath();
@@ -923,7 +924,8 @@ function writeMetaUnlocked(meta) {
     // Device-scope config (`maxAgents`, `schedulerEnabled`, …) is per-machine, so it
     // rides the device doc under `config:` — never the central doc that syncs.
     const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
-    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser || hasDeviceConfig) {
+    const hasDeviceRoutines = Array.isArray(deviceRoutines);
+    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser || hasDeviceConfig || hasDeviceRoutines) {
         // Device-local doc carries `agents:` pins, `defaultBrowserProfile:`, and the
         // device-scope `config:` — all per-machine and must never land in central
         // agents.yaml (which syncs).
@@ -936,6 +938,8 @@ function writeMetaUnlocked(meta) {
             deviceDoc.defaultBrowserProfile = defaultBrowserProfile;
         if (hasDeviceConfig)
             deviceDoc.config = deviceConfig;
+        if (hasDeviceRoutines)
+            deviceDoc.routines = deviceRoutines;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         writeIfChanged(devicePath, META_HEADER + yaml.stringify(deviceDoc));
     }
@@ -971,8 +975,12 @@ function writeMetaUnlocked(meta) {
 function overlayMachineLocal(meta) {
     const devicePath = getDeviceMetaPath();
     if (fs.existsSync(devicePath)) {
+        let dm = null;
         try {
-            const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+            dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+        }
+        catch { /* preserve the existing tolerance for malformed legacy device YAML */ }
+        if (dm) {
             if (dm?.agents)
                 meta.agents = { ...meta.agents, ...dm.agents };
             if (dm?.isolatedAgents)
@@ -981,8 +989,13 @@ function overlayMachineLocal(meta) {
                 meta.defaultBrowserProfile = dm.defaultBrowserProfile;
             if (dm?.config)
                 meta.deviceConfig = dm.config;
+            if (dm && Object.prototype.hasOwnProperty.call(dm, 'routines')) {
+                if (!Array.isArray(dm.routines) || dm.routines.some((name) => typeof name !== 'string')) {
+                    throw new Error(`Device config corrupted at ${devicePath}: routines must be a string list.`);
+                }
+                meta.deviceRoutines = dm.routines;
+            }
         }
-        catch { /* ignore malformed device file */ }
     }
     const vrPath = getVersionResourcesPath();
     if (fs.existsSync(vrPath)) {

package/dist/lib/types.d.ts

@@ -511,10 +511,16 @@ export interface RegistrySearchResult {
 }
 /** A package that has been resolved from a registry and is ready to install. */
 export interface ResolvedPackage {
-    type: 'mcp' | 'skill' | 'git';
+    /** `plugin` is Phase 5 packaging: `agents install plugin:<spec>` → plugins install. */
+    type: 'mcp' | 'skill' | 'git' | 'plugin';
     source: string;
     mcpEntry?: McpServerEntry;
     skillEntry?: SkillEntry;
+    /**
+     * Plugin install spec (`name@url`, path, or bare source) when `type === 'plugin'`.
+     * Same grammar as `agents plugins install <spec>`.
+     */
+    pluginSpec?: string;
 }
 /** Categories of resources that can be synced into an agent version home. */
 export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
@@ -937,6 +943,13 @@ export interface Meta {
      * device-config registry (`maxAgents`, `schedulerEnabled`, `notes`). Per-machine by design — unset = today's behavior.
      */
     deviceConfig?: Record<string, unknown>;
+    /**
+     * Routine names enabled on this machine. In memory this stays distinct from
+     * portable user config; state.ts writes it as top-level `routines:` in
+     * `~/.agents/devices/<machine>/agents.yaml`. Presence in the list is the whole
+     * activation state: absent means disabled on this device.
+     */
+    deviceRoutines?: string[];
     /**
      * Agent-host registry keyed by host name (`agents hosts`). Portable user
      * config synced with `agents repo push/pull`. For `ssh-config` hosts this is
@@ -989,6 +1002,56 @@ export interface Meta {
         projects?: string[];
     };
 }
+/** A single delivery channel entry in humans.yaml. */
+export interface HumanChannel {
+    /** Canonical channel identifier (e.g. "imessage", "call"). */
+    id: string;
+    /** Provider transport (e.g. "rush", "twilio"). */
+    transport: string;
+    /** If true the channel is watched for incoming messages. */
+    watch?: boolean;
+    /** Shell command to invoke (for call channels). */
+    cmd?: string;
+    /** Credentials bundle name (`agents secrets`). */
+    creds?: string;
+    /** Whether the channel is intrusive (e.g. voice call). */
+    intrusive?: boolean;
+}
+/** Severity-to-channel-list escalation policy in humans.yaml. */
+export interface HumanPolicy {
+    low?: string[];
+    normal?: string[];
+    critical?: string[];
+}
+/** Owner identity and contact configuration in humans.yaml. */
+export interface HumanOwner {
+    /** Display name. */
+    name?: string;
+    /** IANA timezone string (e.g. "America/Los_Angeles"). */
+    timezone?: string;
+    /** Quiet hours as "HH:MM-HH:MM" in local time. */
+    quiet_hours?: string;
+    /** Default notification severity when unspecified. */
+    default_severity?: 'low' | 'normal' | 'critical';
+    /** Short-form channel config for `agents send --to owner` (channel + recipient). */
+    notify?: {
+        channel: string;
+        to: string;
+    };
+    /** Full delivery-channel definitions. */
+    channels?: HumanChannel[];
+    /** Severity-to-channel escalation policy. */
+    policy?: HumanPolicy;
+}
+/**
+ * Versioned humans.yaml config — owner identity, channels, and notification
+ * policy. Written to ~/.agents/humans.yaml by `migrateHumans()`.
+ */
+export interface HumansConfig {
+    /** Schema version. Always 1. */
+    version: 1;
+    owner?: HumanOwner;
+}
 /** Persisted agent-host entry in agents.yaml (overlay or inline). */
 export interface HostEntry {
     /** `ssh-config`: reach via the bare name (ssh resolves). `inline`: use address/user below. */

package/dist/lib/versions.js

@@ -185,15 +185,24 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.skills = filterNamesForActiveResourceProfile('skills', Array.from(skillNames), sourceMapFromResources('skills', cwd));
-    // Hooks. A hook is either a directory bundle or an actual script file: known
-    // script extension, OR executable bit on a file with a non-data extension.
-    // Auxiliary content like `README.md` (docs) or `promptcuts.yaml` (data read
-    // directly by the expand-promptcuts script) lives in hooks/ but is not a
-    // hook. Older sync runs chmod 0o755'd everything they copied, so an exec bit
-    // alone can no longer be trusted as the signal.
+    // Hooks:
+    //   - top-level script files
+    //   - one-level *group* dirs that contain top-level scripts (session-starts/*.sh)
+    //     → each script is its own hook resource (install name = basename)
+    //   - other directories (e.g. tests/ with fixtures only) → directory bundles,
+    //     copied wholesale as one resource (pre-existing layout)
+    // Auxiliary content like README.md / promptcuts.yaml is not a hook. Older sync
+    // runs chmod 0o755'd everything, so an exec bit alone is not the signal.
     const NON_SCRIPT_EXTS = new Set(['.md', '.markdown', '.rst', '.txt', '.yaml', '.yml', '.json', '.toml', '.ini', '.conf']);
     const SCRIPT_EXTS = new Set(['.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1']);
+    const HOOK_GROUP_SKIP = new Set(['node_modules', '.git', '.cache']);
     const hookNames = new Set();
+    const isHookScriptName = (fileName, mode) => {
+        const ext = path.extname(fileName).toLowerCase();
+        if (SCRIPT_EXTS.has(ext))
+            return true;
+        return (mode & 0o111) !== 0 && !NON_SCRIPT_EXTS.has(ext);
+    };
     for (const { base } of resourceBases) {
         const hooksDir = path.join(base, 'hooks');
         if (!fs.existsSync(hooksDir))
@@ -202,22 +211,47 @@ export function getAvailableResources(cwd = process.cwd()) {
             if (name.startsWith('.'))
                 continue;
             try {
-                const stat = fs.lstatSync(path.join(hooksDir, name));
+                const full = path.join(hooksDir, name);
+                const stat = fs.lstatSync(full);
                 if (stat.isSymbolicLink())
                     continue;
-                if (stat.isDirectory()) {
-                    hookNames.add(name);
+                if (stat.isFile()) {
+                    if (isHookScriptName(name, stat.mode))
+                        hookNames.add(name);
                     continue;
                 }
-                if (!stat.isFile())
+                if (!stat.isDirectory() || HOOK_GROUP_SKIP.has(name))
                     continue;
-                const ext = path.extname(name).toLowerCase();
-                if (SCRIPT_EXTS.has(ext)) {
-                    hookNames.add(name);
+                // Group vs bundle: if the dir has any top-level script files, expand
+                // them; otherwise treat the whole dir as one hook resource.
+                let nestedNames;
+                try {
+                    nestedNames = fs.readdirSync(full);
+                }
+                catch {
                     continue;
                 }
-                if ((stat.mode & 0o111) !== 0 && !NON_SCRIPT_EXTS.has(ext))
+                const scripts = [];
+                for (const nested of nestedNames) {
+                    if (nested.startsWith('.'))
+                        continue;
+                    try {
+                        const nfull = path.join(full, nested);
+                        const nstat = fs.lstatSync(nfull);
+                        if (nstat.isSymbolicLink() || !nstat.isFile())
+                            continue;
+                        if (isHookScriptName(nested, nstat.mode))
+                            scripts.push(nested);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (scripts.length > 0) {
+                    for (const s of scripts)
+                        hookNames.add(s);
+                }
+                else {
                     hookNames.add(name);
+                }
             }
             catch { /* ignore unreadable */ }
         }

package/dist/lib/watchdog/rotate.d.ts

@@ -166,7 +166,7 @@ export declare function isWatchdogRotateEnabled(): boolean;
  * Persist `watchdog.rotate: on|off`. Called by the `agents watchdog rotate
  * on|off` subcommand (commands/watchdog.ts) — the rotate-only switch the
  * Factory migration uses so a user who opted out of autoRotate keeps nudging
- * (rather than `agents watchdog disable`, which kills the whole watchdog).
+ * (rather than `agents watchdog off`, which disables the whole watchdog here).
  */
 export declare function setWatchdogRotateEnabled(on: boolean): void;
 export interface RotateGateResult {

package/dist/lib/watchdog/rotate.js

@@ -291,7 +291,7 @@ export function isWatchdogRotateEnabled() {
  * Persist `watchdog.rotate: on|off`. Called by the `agents watchdog rotate
  * on|off` subcommand (commands/watchdog.ts) — the rotate-only switch the
  * Factory migration uses so a user who opted out of autoRotate keeps nudging
- * (rather than `agents watchdog disable`, which kills the whole watchdog).
+ * (rather than `agents watchdog off`, which disables the whole watchdog here).
  */
 export function setWatchdogRotateEnabled(on) {
     const meta = readMeta();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.14",
+  "version": "1.22.16",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",

package/dist/lib/watchdog/routine.d.ts

@@ -1,44 +0,0 @@
-/**
- * The watchdog, expressed as a routine.
- *
- * The always-on watchdog is not a bespoke subsystem — it is a plain `command`
- * routine the daemon's existing scheduler fires: `agents watchdog --nudge`, once
- * every couple of minutes. Enabling / disabling the watchdog is enabling /
- * disabling that routine, so there is ONE durable, inspectable concept
- * (`agents routines list` shows it; the scheduler catches it up if the daemon was
- * down) instead of a private sentinel file and a hand-rolled `--watch` loop.
- *
- * A `command` routine — not `agent`/`workflow` — because the tick is deterministic
- * housekeeping: no LLM, no auth, no sandbox. Each fire runs ONE bounded tick (the
- * cron is the loop), so the daemon's per-fire model fits without a long-lived
- * process.
- */
-import { type JobConfig } from '../routines.js';
-/** The routine name. `agents routines list` / `readJob` key on this. */
-export declare const WATCHDOG_ROUTINE_NAME = "watchdog";
-/**
- * Fire every 2 minutes. Mirrors the extension's 120s tick, and is well inside the
- * 5m stall threshold and 20m nudge cooldown, so a stall is noticed promptly
- * without the daemon spawning a tick more often than the cooldown can matter.
- */
-export declare const WATCHDOG_ROUTINE_SCHEDULE = "*/2 * * * *";
-/** The plain shell each fire runs: one bounded, deterministic nudge tick. */
-export declare const WATCHDOG_ROUTINE_COMMAND = "agents watchdog --nudge";
-/**
- * Build the watchdog routine config. Pure — touches no disk. `mode`/`effort`/
- * `timeout` are required by JobConfig but ignored for `command` routines;
- * writeJob() drops the default ('auto'/'10m') values so the on-disk file stays
- * to the point (name + schedule + command + enabled).
- */
-export declare function buildWatchdogRoutine(enabled: boolean): JobConfig;
-/** Is the watchdog routine present on disk (user or system layer)? */
-export declare function watchdogRoutineExists(): boolean;
-/** Is the watchdog routine present AND enabled? */
-export declare function isWatchdogRoutineEnabled(): boolean;
-/**
- * Ensure the watchdog routine exists with the requested enabled state, preserving
- * any user edits. Absent → create it; present → only flip `enabled` (never clobber
- * a schedule or command the user tuned). Idempotent: calling it twice with the
- * same state is a no-op after the first.
- */
-export declare function ensureWatchdogRoutine(enabled: boolean): void;

package/dist/lib/watchdog/routine.js

@@ -1,69 +0,0 @@
-/**
- * The watchdog, expressed as a routine.
- *
- * The always-on watchdog is not a bespoke subsystem — it is a plain `command`
- * routine the daemon's existing scheduler fires: `agents watchdog --nudge`, once
- * every couple of minutes. Enabling / disabling the watchdog is enabling /
- * disabling that routine, so there is ONE durable, inspectable concept
- * (`agents routines list` shows it; the scheduler catches it up if the daemon was
- * down) instead of a private sentinel file and a hand-rolled `--watch` loop.
- *
- * A `command` routine — not `agent`/`workflow` — because the tick is deterministic
- * housekeeping: no LLM, no auth, no sandbox. Each fire runs ONE bounded tick (the
- * cron is the loop), so the daemon's per-fire model fits without a long-lived
- * process.
- */
-import { readJob, writeJob, setJobEnabled } from '../routines.js';
-/** The routine name. `agents routines list` / `readJob` key on this. */
-export const WATCHDOG_ROUTINE_NAME = 'watchdog';
-/**
- * Fire every 2 minutes. Mirrors the extension's 120s tick, and is well inside the
- * 5m stall threshold and 20m nudge cooldown, so a stall is noticed promptly
- * without the daemon spawning a tick more often than the cooldown can matter.
- */
-export const WATCHDOG_ROUTINE_SCHEDULE = '*/2 * * * *';
-/** The plain shell each fire runs: one bounded, deterministic nudge tick. */
-export const WATCHDOG_ROUTINE_COMMAND = 'agents watchdog --nudge';
-/**
- * Build the watchdog routine config. Pure — touches no disk. `mode`/`effort`/
- * `timeout` are required by JobConfig but ignored for `command` routines;
- * writeJob() drops the default ('auto'/'10m') values so the on-disk file stays
- * to the point (name + schedule + command + enabled).
- */
-export function buildWatchdogRoutine(enabled) {
-    return {
-        name: WATCHDOG_ROUTINE_NAME,
-        schedule: WATCHDOG_ROUTINE_SCHEDULE,
-        command: WATCHDOG_ROUTINE_COMMAND,
-        enabled,
-        mode: 'auto',
-        effort: 'auto',
-        timeout: '10m',
-        prompt: '',
-    };
-}
-/** Is the watchdog routine present on disk (user or system layer)? */
-export function watchdogRoutineExists() {
-    return readJob(WATCHDOG_ROUTINE_NAME) !== null;
-}
-/** Is the watchdog routine present AND enabled? */
-export function isWatchdogRoutineEnabled() {
-    const job = readJob(WATCHDOG_ROUTINE_NAME);
-    return job !== null && job.enabled === true;
-}
-/**
- * Ensure the watchdog routine exists with the requested enabled state, preserving
- * any user edits. Absent → create it; present → only flip `enabled` (never clobber
- * a schedule or command the user tuned). Idempotent: calling it twice with the
- * same state is a no-op after the first.
- */
-export function ensureWatchdogRoutine(enabled) {
-    const existing = readJob(WATCHDOG_ROUTINE_NAME);
-    if (existing === null) {
-        writeJob(buildWatchdogRoutine(enabled));
-        return;
-    }
-    if (existing.enabled !== enabled) {
-        setJobEnabled(WATCHDOG_ROUTINE_NAME, enabled);
-    }
-}