@phnx-labs/agents-cli 1.15.0 → 1.16.0

package/dist/lib/subagents.js

@@ -9,7 +9,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSubagentsDir, getUserSubagentsDir } from './state.js';
+import { getSubagentsDir, getUserSubagentsDir, getTrashSubagentsDir } from './state.js';
+import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { safeJoin } from './paths.js';
 /**
  * Parse AGENT.md frontmatter to extract subagent metadata
@@ -407,3 +408,99 @@ export function listSubagentsForAgent(agentId, home) {
     }
     return subagents;
 }
+// Agents that support subagents
+const SUBAGENTS_CAPABLE_AGENTS = ['claude', 'openclaw'];
+/**
+ * Compare a version home's subagents against discovered subagents.
+ * Returns orphan subagent names.
+ */
+export function diffVersionSubagents(agent, version) {
+    const versionHome = getVersionHomePath(agent, version);
+    const orphans = [];
+    // Get all discovered subagent names
+    const discovered = new Set();
+    for (const dir of [getSubagentsDir(), getUserSubagentsDir()]) {
+        if (fs.existsSync(dir)) {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    discovered.add(entry.name);
+                }
+            }
+        }
+    }
+    // Check what's installed
+    if (agent === 'claude') {
+        const agentsDir = path.join(versionHome, '.claude', 'agents');
+        if (fs.existsSync(agentsDir)) {
+            for (const file of fs.readdirSync(agentsDir)) {
+                if (!file.endsWith('.md'))
+                    continue;
+                const name = path.basename(file, '.md');
+                if (!discovered.has(name)) {
+                    orphans.push(name);
+                }
+            }
+        }
+    }
+    else if (agent === 'openclaw') {
+        const openclawDir = path.join(versionHome, '.openclaw');
+        if (fs.existsSync(openclawDir)) {
+            for (const entry of fs.readdirSync(openclawDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                if (!discovered.has(entry.name)) {
+                    orphans.push(entry.name);
+                }
+            }
+        }
+    }
+    return { agent, version, orphans: orphans.sort() };
+}
+/**
+ * Iterate all (agent, version) pairs that support subagents and are installed.
+ */
+export function iterSubagentsCapableVersions(filter) {
+    const pairs = [];
+    const agents = filter?.agent ? [filter.agent] : SUBAGENTS_CAPABLE_AGENTS;
+    for (const agent of agents) {
+        if (!SUBAGENTS_CAPABLE_AGENTS.includes(agent))
+            continue;
+        const versions = listInstalledVersions(agent);
+        for (const version of versions) {
+            if (filter?.version && filter.version !== version)
+                continue;
+            pairs.push({ agent, version });
+        }
+    }
+    return pairs;
+}
+/**
+ * Remove a single subagent from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/subagents/.
+ */
+export function removeSubagentFromVersion(agent, version, subagentName) {
+    const versionHome = getVersionHomePath(agent, version);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const trashDir = path.join(getTrashSubagentsDir(), agent, version, subagentName);
+    try {
+        if (agent === 'claude') {
+            const targetPath = path.join(versionHome, '.claude', 'agents', `${subagentName}.md`);
+            if (fs.existsSync(targetPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.md.${stamp}`));
+            }
+        }
+        else if (agent === 'openclaw') {
+            const targetDir = path.join(versionHome, '.openclaw', subagentName);
+            if (fs.existsSync(targetDir)) {
+                const trashDest = path.join(trashDir, stamp);
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetDir, trashDest);
+            }
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}

package/dist/lib/sync-manifest.d.ts

@@ -47,7 +47,7 @@ interface RulesEntry {
 /** Permissions: all group files across all scopes (merged). */
 interface PermEntry {
     groups: Record<string, FileEntry>;
-    permissionSet: string | null;
+    permissionPreset: string | null;
 }
 export interface SyncManifest {
     v: typeof MANIFEST_VERSION;

package/dist/lib/sync-manifest.js

@@ -28,7 +28,7 @@ import { getVersionsDir, getProjectAgentsDir, getUserAgentsDir, getSkillsDir, ge
 import { resolveResource } from './resources.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { isRulesStale } from './rules/compile.js';
-import { getActivePermissionSetName } from './permissions.js';
+import { getActivePermissionPresetName } from './permissions.js';
 import { listInstalledSubagents } from './subagents.js';
 import { safeJoin } from './paths.js';
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -341,7 +341,7 @@ export function buildManifest(agent, version, available, cwd) {
         mcp,
         permissions: {
             groups: permGroups,
-            permissionSet: getActivePermissionSetName(),
+            permissionPreset: getActivePermissionPresetName(),
         },
         subagents,
     };
@@ -420,7 +420,7 @@ export function isSyncStale(manifest, available, agent, version, cwd) {
             return true;
     }
     // ── Permissions ───────────────────────────────────────────────────────────
-    if (manifest.permissions.permissionSet !== getActivePermissionSetName())
+    if (manifest.permissions.permissionPreset !== getActivePermissionPresetName())
         return true;
     const currentGroups = collectPermissionGroupFiles();
     if (nameSetDiffers(Object.keys(manifest.permissions.groups), Object.keys(currentGroups)))

package/dist/lib/teams/persistence.js

@@ -13,7 +13,7 @@ import { homedir, tmpdir } from 'os';
 import { constants as fsConstants } from 'fs';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getUserAgentsDir } from '../state.js';
+import { getTeamsDir, getTeamsAgentsDir } from '../state.js';
 /**
  * Atomic JSON write: writes to a sibling tmp file then renames over the
  * target. rename(2) is atomic on POSIX, so a crashed/interrupted write
@@ -62,8 +62,9 @@ async function withConfigLock(p, fn) {
 }
 // All supported teammate agent types
 const ALL_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode'];
-// Teams data lives under ~/.agents/teams/
-const TEAMS_DIR = path.join(getUserAgentsDir(), 'teams');
+// Teams config + registry live under ~/.agents/teams/ (definitions);
+// per-run agent execution dirs live under ~/.agents/.history/teams/agents/.
+const TEAMS_DIR = getTeamsDir();
 // Legacy paths (for migration)
 const LEGACY_CONFIG_DIR = path.join(homedir(), '.agents');
 // Legacy migration from pre-OSS brand; safe to remove after 2026-07
@@ -100,8 +101,17 @@ export async function resolveBaseDir() {
     throw new Error('Unable to determine a writable data directory for teams');
 }
 async function resolveAgentsPath() {
-    const base = await resolveBaseDir();
-    return path.join(base, 'agents');
+    const historyAgents = getTeamsAgentsDir();
+    if (await ensureWritableDir(historyAgents)) {
+        return historyAgents;
+    }
+    // Last-resort temp fallback so dispatch keeps working when ~/.agents is unwritable.
+    const tmpAgents = path.join(TMP_FALLBACK_DIR, 'agents');
+    if (await ensureWritableDir(tmpAgents)) {
+        console.warn(`[agents teams] Falling back to temp agents dir at ${tmpAgents}`);
+        return tmpAgents;
+    }
+    throw new Error('Unable to determine a writable agents directory');
 }
 async function resolveConfigPath() {
     await fs.mkdir(TEAMS_DIR, { recursive: true });

package/dist/lib/teams/registry.js

@@ -10,9 +10,9 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getUserAgentsDir } from '../state.js';
+import { getTeamsDir } from '../state.js';
 async function registryPath() {
-    return path.join(getUserAgentsDir(), 'teams', 'registry.json');
+    return path.join(getTeamsDir(), 'registry.json');
 }
 /**
  * Atomic JSON write: writes to a unique sibling tmp file then renames over

package/dist/lib/types.d.ts

@@ -186,9 +186,9 @@ export interface RepoInfo {
     lastSync: string;
 }
 /** Canonical system repo cloned into ~/.agents-system/. */
-export declare const DEFAULT_SYSTEM_REPO = "gh:muqsitnawaz/.agents-system";
-/** Mirror system repo (phnx-labs) — will become the default once fully released. */
-export declare const MIRROR_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
+export declare const DEFAULT_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
+/** Legacy system repo — kept so existing installs still recognize their origin. */
+export declare const MIRROR_SYSTEM_REPO = "gh:muqsitnawaz/.agents-system";
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export declare function systemRepoSlug(repo?: string): string;
 /** Kind of package that can be searched and installed from a registry. */
@@ -378,6 +378,35 @@ export interface Meta {
      * once. Tracked so a user `registry remove` won't silently re-seed.
      */
     seededPresets?: string[];
+    /**
+     * Hook manifest entries keyed by hook name. Folded into agents.yaml so the
+     * user has a single file to sync. Each entry shape matches ManifestHook
+     * (script, events, timeout, matches, enabled).
+     */
+    hooks?: Record<string, ManifestHook>;
+    /**
+     * Browser profile definitions keyed by profile name. Portable user config
+     * that syncs with `agents repo push/pull`. Runtime state (chrome-data, pids)
+     * lives separately in ~/.agents/.cache/browser/<profile>/.
+     */
+    browser?: Record<string, BrowserProfileConfig>;
+}
+/** Browser profile definition stored in agents.yaml. */
+export interface BrowserProfileConfig {
+    description?: string;
+    browser: 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+    binary?: string;
+    electron?: boolean;
+    endpoints: string[];
+    chrome?: {
+        headless?: boolean;
+        args?: string[];
+    };
+    secrets?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */
 export interface SyncOptions {

package/dist/lib/types.js

@@ -6,9 +6,9 @@
  * formats for each supported agent.
  */
 /** Canonical system repo cloned into ~/.agents-system/. */
-export const DEFAULT_SYSTEM_REPO = 'gh:muqsitnawaz/.agents-system';
-/** Mirror system repo (phnx-labs) — will become the default once fully released. */
-export const MIRROR_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
+export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
+/** Legacy system repo — kept so existing installs still recognize their origin. */
+export const MIRROR_SYSTEM_REPO = 'gh:muqsitnawaz/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {
     return repo.replace(/^gh:/, '').replace(/\.git$/, '');

package/dist/lib/usage.js

@@ -16,7 +16,7 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
 import { getKeychainToken, setKeychainToken, deleteKeychainToken, } from './secrets/index.js';
-import { getAgentsDir } from './state.js';
+import { getCacheDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -31,7 +31,7 @@ const CLAUDE_SCOPES = [
     'user:file_upload',
 ];
 const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
-const getClaudeUsageCachePath = () => path.join(getAgentsDir(), 'cache', 'claude-usage.json');
+const getClaudeUsageCachePath = () => path.join(getCacheDir(), 'claude-usage.json');
 const CACHED_CLAUDE_USAGE_SOURCE_LABEL = 'last seen live account data';
 const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;

package/dist/lib/versions.js

@@ -23,10 +23,10 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import * as TOML from 'smol-toml';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
 import { resolveResource } from './resources.js';
 import { AGENTS, getAccountEmail, MCP_CAPABLE_AGENTS, COMMANDS_CAPABLE_AGENTS, getMcpConfigPathForHome, parseMcpConfig, resolveAgentName, formatAgentError } from './agents.js';
-import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionSetName, readPermissionSetRecipe, PERMISSION_SET_ENV_VAR } from './permissions.js';
+import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { installMcpServers, parseMcpServerConfig } from './mcp.js';
 import { markdownToToml } from './convert.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
@@ -192,10 +192,9 @@ export function getAvailableResources(cwd = process.cwd()) {
     // Plugins (directories with .claude-plugin/plugin.json)
     const allPlugins = discoverPlugins();
     result.plugins = allPlugins.map(p => p.name);
-    // Promptcuts — single file at ~/.agents/promptcuts.yaml, not per-agent.
-    // Project-scoped .agents/promptcuts.yaml is intentionally not supported
-    // (user-global shortcuts only — they follow the user, not the repo).
-    result.promptcuts = fs.existsSync(getPromptcutsPath());
+    // Promptcuts — present if either layer exists. Reads merge user + system
+    // with user precedence (see readMergedPromptcuts); writes always go to user.
+    result.promptcuts = fs.existsSync(getUserPromptcutsPath()) || fs.existsSync(getPromptcutsPath());
     return result;
 }
 // Files/dirs that are never synced into a version home (OS metadata, local tooling).
@@ -676,14 +675,14 @@ export async function promptResourceSelection(agent) {
     ];
     const availableCategories = categories.filter(c => c.available);
     if (availableCategories.length === 0) {
-        console.log(chalk.gray('No resources available in ~/.agents/'));
+        console.log(chalk.gray('No resources available to sync.'));
         return {};
     }
     // Step 1: Select categories (with "Select All" shortcut at the top)
     console.log();
     const SELECT_ALL_KEY = '__select_all__';
     const selectedCategories = await checkbox({
-        message: 'Which resources from ~/.agents/ would you like to sync?',
+        message: 'Which resources would you like to sync?',
         choices: [
             { name: chalk.bold('Select All (sync everything)'), value: SELECT_ALL_KEY, checked: false },
             ...availableCategories.map(c => ({
@@ -1189,7 +1188,7 @@ export function resolveVersionAliasLoose(agent, raw) {
  * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
  */
 export function getProjectVersion(agent, startPath) {
-    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
     let dir = path.resolve(startPath);
     while (dir !== path.dirname(dir)) {
         const manifestPath = path.join(dir, 'agents.yaml');
@@ -1641,39 +1640,39 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     // Apply permissions (if agent supports them).
     // Groups live in ~/.agents/permissions/groups/. Optional recipes in
-    // ~/.agents/permissions/sets/<name>.yaml pick a subset via `includes:`.
-    // If AGENTS_PERMISSION_SET is set, we resolve that recipe and use its
+    // ~/.agents/permissions/presets/<name>.yaml pick a subset via `includes:`.
+    // If AGENTS_PERMISSION_PRESET is set, we resolve that recipe and use its
     // includes list as the group filter (intersected with groups on disk).
     const permissionGroups = discoverPermissionGroups();
     const allGroupNames = permissionGroups.map(g => g.name);
-    const activeSetName = getActivePermissionSetName();
-    let setFilteredGroups = null;
-    if (activeSetName) {
-        const recipe = readPermissionSetRecipe(activeSetName);
+    const activePresetName = getActivePermissionPresetName();
+    let presetFilteredGroups = null;
+    if (activePresetName) {
+        const recipe = readPermissionPresetRecipe(activePresetName);
         if (recipe) {
             const available = new Set(allGroupNames);
-            setFilteredGroups = recipe.includes.filter(g => available.has(g));
+            presetFilteredGroups = recipe.includes.filter(g => available.has(g));
         }
         else {
-            console.warn(`${PERMISSION_SET_ENV_VAR}=${activeSetName} but no recipe at ~/.agents/permissions/sets/${activeSetName}.yaml — falling back to all groups`);
+            console.warn(`${PERMISSION_PRESET_ENV_VAR}=${activePresetName} but no recipe at ~/.agents/permissions/presets/${activePresetName}.yaml — falling back to all groups`);
         }
     }
     let permsToSync;
     if (selection) {
         permsToSync = resolveSelection(selection.permissions, allGroupNames);
-        // If a set recipe is active, the recipe's includes list always wins —
+        // If a preset recipe is active, the recipe's includes list always wins —
         // even when the caller passed an explicit array via selection. Without
         // this intersection, `agents add`'s buildAutomaticSelection would pass
         // every group name discovered on disk (including 99-deny), bypassing
         // the sandbox filter.
-        if (setFilteredGroups) {
-            const filterSet = new Set(setFilteredGroups);
+        if (presetFilteredGroups) {
+            const filterSet = new Set(presetFilteredGroups);
             permsToSync = permsToSync.filter(g => filterSet.has(g));
         }
     }
     else {
         permsToSync = PERMISSIONS_CAPABLE_AGENTS.includes(agent)
-            ? (setFilteredGroups ?? allGroupNames)
+            ? (presetFilteredGroups ?? allGroupNames)
             : [];
     }
     if (permsToSync.length > 0 && PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",

package/scripts/postinstall.js

@@ -20,7 +20,7 @@ if (!isGlobalInstall) {
   fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
   console.log(`
 agents-cli installed locally.
-To complete setup, run: npx agents init
+To complete setup, run: npx agents setup
 `);
   process.exit(0);
 }