@phnx-labs/agents-cli 1.22.15 → 1.22.17

package/dist/lib/staleness/writers/sources.js

@@ -10,7 +10,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, getCommandsDir, getSkillsDir, getHooksDir } from '../../state.js';
-import { safeJoin } from '../../paths.js';
+import { isSafeSegmentName, safeJoin } from '../../paths.js';
 /** Trusted source bases for content-like kinds. Project layer excluded. */
 export function trustedSourceBases() {
     return [
@@ -119,14 +119,100 @@ export function listPluginSkillNames(options = {}) {
     }
     return Array.from(names);
 }
-/** Find the trusted source file for a hook by name. */
+/**
+ * Subdirectories under hooks/ that are never group dirs.
+ * Must stay in lockstep with HOOK_GROUP_SKIP_DIRS in hooks.ts.
+ */
+const HOOK_GROUP_SKIP_DIRS = new Set(['node_modules', '.git', '.cache']);
+const HOOK_SCRIPT_EXTS = new Set([
+    '.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1', '.cmd', '.bat',
+]);
+function dirHasTopLevelScripts(groupDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(groupDir);
+    }
+    catch {
+        return false;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue;
+        const ext = path.extname(name).toLowerCase();
+        if (!HOOK_SCRIPT_EXTS.has(ext))
+            continue;
+        if (isLiveFile(path.join(groupDir, name)))
+            return true;
+    }
+    return false;
+}
+function findNestedHookFile(hooksRoot, basename) {
+    if (!isLiveDir(hooksRoot))
+        return null;
+    let entries;
+    try {
+        entries = fs.readdirSync(hooksRoot).sort();
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') || HOOK_GROUP_SKIP_DIRS.has(name))
+            continue;
+        const groupDir = path.join(hooksRoot, name);
+        if (!isLiveDir(groupDir))
+            continue;
+        // Only group dirs (those with scripts) contribute nested scripts.
+        if (!dirHasTopLevelScripts(groupDir))
+            continue;
+        const candidate = path.join(groupDir, basename);
+        if (isLiveFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Find the trusted source for a hook by name.
+ * - File basename (`04-session-identity.sh`) or relative path
+ *   (`session-starts/04-session-identity.sh`) → script file
+ * - Directory basename (`tests`) → directory bundle (fixtures-only etc.)
+ */
 export function resolveHookSource(name) {
-    const candidates = [
-        safeJoin(path.join(getUserAgentsDir(), 'hooks'), name),
-        safeJoin(getHooksDir(), name),
-        ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'hooks'), name)),
+    const roots = [
+        path.join(getUserAgentsDir(), 'hooks'),
+        getHooksDir(),
+        ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'hooks')),
     ];
-    return candidates.find(isLiveFile) ?? null;
+    const base = path.basename(name);
+    for (const hooksRoot of roots) {
+        // Exact relative path (top-level or group/name) — multi-segment needs
+        // path.join + containment, not safeJoin (single-segment only).
+        if (name.includes('/') || name.includes('\\')) {
+            const candidate = path.resolve(hooksRoot, name);
+            const rootResolved = path.resolve(hooksRoot);
+            if ((candidate === rootResolved || candidate.startsWith(rootResolved + path.sep)) &&
+                isLiveFile(candidate)) {
+                return candidate;
+            }
+        }
+        else if (isSafeSegmentName(name)) {
+            try {
+                const top = safeJoin(hooksRoot, name);
+                // File script first; then directory bundle (e.g. tests/ fixtures).
+                if (isLiveFile(top))
+                    return top;
+                if (isLiveDir(top) && !dirHasTopLevelScripts(top))
+                    return top;
+            }
+            catch {
+                /* invalid segment */
+            }
+        }
+        const nested = findNestedHookFile(hooksRoot, base);
+        if (nested)
+            return nested;
+    }
+    return null;
 }
 /** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
 export function trustedSkillRoots() {

package/dist/lib/startup/command-registry.d.ts

@@ -46,6 +46,7 @@ export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
+export declare const loadResume: ModuleLoader;
 export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;
@@ -104,6 +105,7 @@ export declare const loadShare: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
 export declare const loadWebhook: ModuleLoader;
 export declare const loadFunnel: ModuleLoader;
+export declare const loadHumans: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/lib/startup/command-registry.js

@@ -24,6 +24,7 @@ export const loadRoutines = async () => (await import('../../commands/routines.j
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
 export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadResume = async () => (await import('../../commands/resume.js')).registerResumeCommand;
 export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
@@ -82,6 +83,7 @@ export const loadShare = async () => (await import('../../commands/share.js')).r
 export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
 export const loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
 export const loadFunnel = async () => (await import('../../commands/funnel.js')).registerFunnelCommand;
+export const loadHumans = async () => (await import('../../commands/humans.js')).registerHumansCommands;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -93,6 +95,7 @@ export const loadFunnel = async () => (await import('../../commands/funnel.js'))
 // same SQLite stack, same post-help registration order as sessions.
 export const LAZY_COMMAND_NAMES = new Set([
     'sessions',
+    'resume',
     'roster',
     'teams',
     'cloud',
@@ -145,6 +148,7 @@ export const COMMAND_LOADERS = {
     monitors: [loadMonitors],
     projects: [loadProjects],
     run: [loadRun],
+    resume: [loadResume],
     fork: [loadFork],
     defaults: [loadDefaults],
     set: [loadSet],
@@ -221,4 +225,5 @@ export const COMMAND_LOADERS = {
     audit: [loadAudit],
     webhook: [loadWebhook],
     funnel: [loadFunnel],
+    humans: [loadHumans],
 };

package/dist/lib/state.d.ts

@@ -23,6 +23,8 @@
  * and leaves a back-compat symlink at the old path.
  */
 import type { Meta } from './types.js';
+/** Return the absolute path to the humans.yaml file. */
+export declare function getHumansFilePath(): string;
 /**
  * Header prepended to every agents.yaml the CLI writes (central and per-device
  * docs). Carries the yaml-language-server schema hint so editors validate the

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);
     }

package/dist/lib/types.d.ts

@@ -1002,6 +1002,58 @@ 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;
+    /** Provider-specific recipient (phone number, user id, address). */
+    to?: 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.15",
+  "version": "1.22.17",
   "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",