@phnx-labs/agents-cli 1.14.3 → 1.14.5

package/dist/lib/resources/subagents.js

@@ -0,0 +1,198 @@
+/**
+ * Subagents resource handler.
+ *
+ * Subagents are YAML files stored in subagents/ directories across layers.
+ * Format is the same for all agents. Resolution order: project > user > system.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getProjectAgentsDir, getUserSubagentsDir, getSystemSubagentsDir, getEnabledExtraRepos, } from '../state.js';
+/** Get layer directories for subagent resolution. */
+function getLayerDirs(cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const extraRepos = getEnabledExtraRepos();
+    return {
+        system: path.join(getSystemSubagentsDir()),
+        user: getUserSubagentsDir(),
+        project: projectDir ? path.join(projectDir, 'subagents') : null,
+        extra: extraRepos.map((e) => path.join(e.dir, 'subagents')),
+    };
+}
+/** Map source directory to layer name. */
+function dirToLayer(dir, dirs) {
+    if (dirs.project && dir.startsWith(dirs.project))
+        return 'project';
+    if (dir.startsWith(dirs.user))
+        return 'user';
+    return 'system';
+}
+/** Parse a subagent YAML file and return parsed item. */
+function parseSubagentYaml(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        return {
+            name: parsed.name || '',
+            description: parsed.description || '',
+            model: parsed.model,
+            color: parsed.color,
+            config: parsed.config,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract name from filename (removes .yaml/.yml extension). */
+function nameFromFile(filename) {
+    return filename.replace(/\.ya?ml$/, '');
+}
+export class SubagentsHandler {
+    kind = 'subagent';
+    /**
+     * List all subagents across layers, with higher layer winning on name conflict.
+     * Returns a union of all subagents, deduplicated by name.
+     */
+    listAll(_agent, cwd) {
+        const dirs = getLayerDirs(cwd);
+        const seen = new Set();
+        const results = [];
+        // Order: project > user > system > extra (extra comes last after system)
+        const layerDirs = [];
+        if (dirs.project && fs.existsSync(dirs.project)) {
+            layerDirs.push({ dir: dirs.project, layer: 'project' });
+        }
+        if (fs.existsSync(dirs.user)) {
+            layerDirs.push({ dir: dirs.user, layer: 'user' });
+        }
+        if (fs.existsSync(dirs.system)) {
+            layerDirs.push({ dir: dirs.system, layer: 'system' });
+        }
+        for (const extraDir of dirs.extra) {
+            if (fs.existsSync(extraDir)) {
+                layerDirs.push({ dir: extraDir, layer: 'system' });
+            }
+        }
+        for (const { dir, layer } of layerDirs) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                    continue;
+                if (entry.name.startsWith('.'))
+                    continue;
+                const name = nameFromFile(entry.name);
+                if (seen.has(name))
+                    continue;
+                const filePath = path.join(dir, entry.name);
+                const item = parseSubagentYaml(filePath);
+                if (!item)
+                    continue;
+                seen.add(name);
+                results.push({
+                    name,
+                    item,
+                    layer,
+                    path: filePath,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Resolve a single subagent by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(_agent, name, cwd) {
+        const dirs = getLayerDirs(cwd);
+        // Order: project > user > system > extra
+        const searchDirs = [];
+        if (dirs.project) {
+            searchDirs.push({ dir: dirs.project, layer: 'project' });
+        }
+        searchDirs.push({ dir: dirs.user, layer: 'user' });
+        searchDirs.push({ dir: dirs.system, layer: 'system' });
+        for (const extraDir of dirs.extra) {
+            searchDirs.push({ dir: extraDir, layer: 'system' });
+        }
+        for (const { dir, layer } of searchDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            // Try .yaml first, then .yml
+            for (const ext of ['.yaml', '.yml']) {
+                const filePath = path.join(dir, name + ext);
+                if (fs.existsSync(filePath)) {
+                    const item = parseSubagentYaml(filePath);
+                    if (item) {
+                        return {
+                            name,
+                            item,
+                            layer,
+                            path: filePath,
+                        };
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Sync resolved subagents to the agent's version home directory.
+     * Copies YAML files to the target directory.
+     */
+    sync(agent, versionHome, cwd) {
+        const targetDir = path.join(versionHome, this.targetDir(agent));
+        // Ensure target directory exists
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        // Clear existing subagents in target
+        try {
+            const existing = fs.readdirSync(targetDir);
+            for (const file of existing) {
+                if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                    fs.unlinkSync(path.join(targetDir, file));
+                }
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        // Copy all resolved subagents
+        const resolved = this.listAll(agent, cwd);
+        for (const { name, path: sourcePath } of resolved) {
+            const ext = sourcePath.endsWith('.yml') ? '.yml' : '.yaml';
+            const targetPath = path.join(targetDir, name + ext);
+            fs.copyFileSync(sourcePath, targetPath);
+        }
+    }
+    /**
+     * Get the file format this resource uses for a given agent.
+     * Subagents always use YAML format.
+     */
+    format(_agent) {
+        return 'yaml';
+    }
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(_agent) {
+        return 'subagents';
+    }
+}
+/** Singleton instance of the SubagentsHandler. */
+export const subagentsHandler = new SubagentsHandler();

package/dist/lib/resources/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Unified resource system types.
+ *
+ * Resources merge from three layers: system → user → project
+ * - Union: All resources from all layers are combined
+ * - Override on name conflict: Higher layer wins (project > user > system)
+ */
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw';
+export type Layer = 'system' | 'user' | 'project';
+export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent';
+/** A resolved resource with its origin layer. */
+export interface ResolvedItem<T> {
+    name: string;
+    item: T;
+    layer: Layer;
+    path: string;
+}
+/**
+ * Resource handler interface.
+ *
+ * Each resource type (commands, hooks, skills, etc.) implements this interface
+ * to provide consistent list/resolve/sync behavior across all agent types.
+ */
+export interface ResourceHandler<T> {
+    readonly kind: ResourceKind;
+    /**
+     * List all resources across layers, with higher layer winning on name conflict.
+     * Returns a union of all resources, deduplicated by name.
+     */
+    listAll(agent: AgentId, cwd?: string): ResolvedItem<T>[];
+    /**
+     * Resolve a single resource by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(agent: AgentId, name: string, cwd?: string): ResolvedItem<T> | null;
+    /**
+     * Sync resolved resources to the agent's version home directory.
+     * Copies/transforms resources as needed for the agent's expected format.
+     */
+    sync(agent: AgentId, versionHome: string, cwd?: string): void;
+    /**
+     * Get the file format this resource uses for a given agent.
+     */
+    format(agent: AgentId): 'md' | 'toml' | 'json' | 'yaml';
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(agent: AgentId): string;
+    /**
+     * For resources that modify config files (MCP, permissions),
+     * return the config file path. Returns null if not applicable.
+     */
+    configPath?(agent: AgentId, versionHome: string): string | null;
+    /**
+     * Compute content hash for a resource item (for change detection).
+     * Used by diff() to detect modifications without full content comparison.
+     * Optional — handlers that don't implement this fall back to full sync.
+     */
+    hash?(item: T): string;
+    /**
+     * Compare source layers vs synced target to detect drift.
+     * Returns list of resources that differ (added, modified, removed).
+     * Enables incremental sync and "X resources out of sync" status.
+     * Optional — handlers that don't implement this always report "unknown".
+     */
+    diff?(agent: AgentId, versionHome: string, cwd?: string): ResourceDiff[];
+}
+/** Result of comparing source vs target for a single resource. */
+export interface ResourceDiff {
+    name: string;
+    status: 'added' | 'modified' | 'removed';
+    sourceLayer: Layer | null;
+    sourceHash: string | null;
+    targetHash: string | null;
+}
+/** Helper to get layer directories for resource resolution. */
+export interface LayerDirs {
+    system: string;
+    user: string;
+    project: string | null;
+    extra: string[];
+}

package/dist/lib/resources/types.js

@@ -0,0 +1,8 @@
+/**
+ * Unified resource system types.
+ *
+ * Resources merge from three layers: system → user → project
+ * - Union: All resources from all layers are combined
+ * - Override on name conflict: Higher layer wins (project > user > system)
+ */
+export {};

package/dist/lib/state.js

@@ -40,13 +40,13 @@ const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md')
 // User-level operational state
 const PACKAGES_DIR = path.join(USER_AGENTS_DIR, 'packages');
 const ROUTINES_DIR = path.join(USER_AGENTS_DIR, 'routines');
-const RUNS_DIR = path.join(USER_AGENTS_DIR, 'runs');
+const RUNS_DIR = path.join(ROUTINES_DIR, 'runs');
 const VERSIONS_DIR = path.join(USER_AGENTS_DIR, 'versions');
 const SHIMS_DIR = path.join(USER_AGENTS_DIR, 'shims');
-const BACKUPS_DIR = path.join(USER_AGENTS_DIR, 'backups');
+const BACKUPS_DIR = path.join(USER_AGENTS_DIR, '.backups');
 const PLUGINS_DIR = path.join(USER_AGENTS_DIR, 'plugins');
 const DRIVE_DIR = path.join(USER_AGENTS_DIR, 'drive');
-const TRASH_DIR = path.join(USER_AGENTS_DIR, 'trash');
+const TRASH_DIR = path.join(USER_AGENTS_DIR, '.trash');
 // ─── User resource dirs ───────────────────────────────────────────────────────
 const USER_COMMANDS_DIR = path.join(USER_AGENTS_DIR, 'commands');
 const USER_HOOKS_DIR = path.join(USER_AGENTS_DIR, 'hooks');
@@ -264,8 +264,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(DRIVE_DIR))
-        fs.mkdirSync(DRIVE_DIR, opts);
     try {
         fs.chmodSync(SYSTEM_AGENTS_DIR, 0o700);
     }

package/dist/lib/teams/registry.d.ts

@@ -3,6 +3,8 @@ export interface TeamMeta {
     created_at: string;
     description?: string;
     enable_worktrees?: boolean;
+    /** Shared worktree path for all teammates (mutually exclusive with enable_worktrees). */
+    use_worktree?: string;
 }
 /** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
@@ -16,6 +18,8 @@ export declare function loadTeams(): Promise<TeamRegistry>;
 export interface CreateTeamOptions {
     description?: string;
     enableWorktrees?: boolean;
+    /** Path to an existing worktree for all teammates to share. */
+    useWorktree?: string;
 }
 /** Create a new team. Throws if a team with the same name already exists. */
 export declare function createTeam(name: string, options?: CreateTeamOptions): Promise<TeamMeta>;

package/dist/lib/teams/registry.js

@@ -92,6 +92,9 @@ async function saveTeams(reg) {
 }
 /** Create a new team. Throws if a team with the same name already exists. */
 export async function createTeam(name, options) {
+    if (options?.enableWorktrees && options?.useWorktree) {
+        throw new Error('Cannot use both --enable-worktrees and --use-worktree. Pick one.');
+    }
     const p = await registryPath();
     return withRegistryLock(p, async () => {
         const reg = await loadTeams();
@@ -102,6 +105,7 @@ export async function createTeam(name, options) {
             created_at: new Date().toISOString(),
             ...(options?.description ? { description: options.description } : {}),
             ...(options?.enableWorktrees ? { enable_worktrees: true } : {}),
+            ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
         };
         reg[name] = meta;
         await saveTeams(reg);

package/dist/lib/versions.d.ts

@@ -54,8 +54,9 @@ export declare function getActuallySyncedResources(agent: AgentId, version: stri
 export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources): AvailableResources;
 /**
  * Check if there are any new resources to sync.
+ * When version is provided, uses version-specific capability checks.
  */
-export declare function hasNewResources(diff: AvailableResources, agent?: AgentId): boolean;
+export declare function hasNewResources(diff: AvailableResources, agent?: AgentId, version?: string): boolean;
 /**
  * Prompt user to select which NEW resources to sync.
  * Only shows resources that haven't been synced yet.

package/dist/lib/versions.js

@@ -27,7 +27,7 @@ import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, g
 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 { installMcpServers } from './mcp.js';
+import { installMcpServers, parseMcpServerConfig } from './mcp.js';
 import { markdownToToml } from './convert.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { listInstalledSubagents, transformSubagentForClaude, syncSubagentToOpenclaw, SUBAGENT_CAPABLE_AGENTS } from './subagents.js';
@@ -145,17 +145,18 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.memory = Array.from(presetNames);
-    // MCP servers (*.yaml files)
+    // MCP servers (*.yaml files) — use the `name:` field inside, not filename
     const mcpNames = new Set();
     for (const { base } of resourceBases) {
         const mcpDir = path.join(base, 'mcp');
         if (!fs.existsSync(mcpDir))
             continue;
-        const names = fs.readdirSync(mcpDir)
-            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
-            .map(f => f.replace(/\.(yaml|yml)$/, ''));
-        for (const name of names) {
-            mcpNames.add(name);
+        const files = fs.readdirSync(mcpDir)
+            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+        for (const file of files) {
+            const config = parseMcpServerConfig(path.join(mcpDir, file));
+            if (config?.name)
+                mcpNames.add(config.name);
         }
     }
     result.mcp = Array.from(mcpNames);
@@ -459,7 +460,11 @@ export function getNewResources(available, actuallySynced) {
         commands: available.commands.filter(c => !actuallySynced.commands.includes(c)),
         skills: available.skills.filter(s => !actuallySynced.skills.includes(s)),
         hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h)),
-        memory: available.memory.filter(m => !actuallySynced.memory.includes(m)),
+        // Memory/rules presets are mutually exclusive — only one can be active.
+        // If any preset is synced, don't report others as "new".
+        memory: actuallySynced.memory.length > 0
+            ? []
+            : available.memory.filter(m => !actuallySynced.memory.includes(m)),
         mcp: available.mcp.filter(m => !actuallySynced.mcp.includes(m)),
         permissions: available.permissions.filter(p => !actuallySynced.permissions.includes(p)),
         subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s)),
@@ -471,14 +476,15 @@ export function getNewResources(available, actuallySynced) {
 }
 /**
  * Check if there are any new resources to sync.
+ * When version is provided, uses version-specific capability checks.
  */
-export function hasNewResources(diff, agent) {
-    const commandsApply = agent ? COMMANDS_CAPABLE_AGENTS.includes(agent) : true;
-    const hooksApply = agent ? AGENTS[agent].supportsHooks : true;
-    const mcpApply = agent ? MCP_CAPABLE_AGENTS.includes(agent) : true;
-    const permsApply = agent ? PERMISSIONS_CAPABLE_AGENTS.includes(agent) : true;
+export function hasNewResources(diff, agent, version) {
+    const commandsApply = agent ? supports(agent, 'commands', version).ok : true;
+    const hooksApply = agent ? supports(agent, 'hooks', version).ok : true;
+    const mcpApply = agent ? supports(agent, 'mcp', version).ok : true;
+    const permsApply = agent ? supports(agent, 'allowlist', version).ok : true;
     const subagentsApply = agent ? SUBAGENT_CAPABLE_AGENTS.includes(agent) : true;
-    const pluginsApply = agent ? PLUGINS_CAPABLE_AGENTS.includes(agent) : true;
+    const pluginsApply = agent ? supports(agent, 'plugins', version).ok : true;
     return ((diff.commands.length > 0 && commandsApply) ||
         diff.skills.length > 0 ||
         (diff.hooks.length > 0 && hooksApply) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.14.3",
+  "version": "1.14.5",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,8 @@
   },
   "bin": {
     "agents": "dist/index.js",
-    "ag": "dist/index.js"
+    "ag": "dist/index.js",
+    "browser": "dist/browser.js"
   },
   "files": [
     "dist/**/*.js",