@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/subagents.d.ts

@@ -81,3 +81,31 @@ export declare const SUBAGENT_CAPABLE_AGENTS: AgentId[];
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export declare function listSubagentsForAgent(agentId: AgentId, home: string): InstalledSubagent[];
+export interface VersionSubagentDiff {
+    agent: AgentId;
+    version: string;
+    orphans: string[];
+}
+/**
+ * Compare a version home's subagents against discovered subagents.
+ * Returns orphan subagent names.
+ */
+export declare function diffVersionSubagents(agent: AgentId, version: string): VersionSubagentDiff;
+/**
+ * Iterate all (agent, version) pairs that support subagents and are installed.
+ */
+export declare function iterSubagentsCapableVersions(filter?: {
+    agent?: AgentId;
+    version?: string;
+}): Array<{
+    agent: AgentId;
+    version: string;
+}>;
+/**
+ * Remove a single subagent from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/subagents/.
+ */
+export declare function removeSubagentFromVersion(agent: AgentId, version: string, subagentName: string): {
+    success: boolean;
+    error?: string;
+};

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. */
@@ -288,30 +288,49 @@ export interface ResolvedPackage {
     skillEntry?: SkillEntry;
 }
 /** Categories of resources that can be synced into an agent version home. */
-export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins';
-/** Map of resource names synced to a specific agent version, keyed by type. */
+export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
+/**
+ * A resource selection pattern stored in agents.yaml versions:
+ *   "system:*"      — all resources from ~/.agents-system/
+ *   "user:*"        — all resources from ~/.agents/
+ *   "rush:*"        — all resources from ~/.agents-rush/  (extra repo alias)
+ *   "project:*"     — all resources from .agents/ in the project root
+ *   "user:foo"      — specifically "foo" from ~/.agents/
+ *   "!user:temp"    — exclude "temp" from the user repo
+ */
+export type ResourcePattern = string;
+/** Sync specification for a specific agent@version, keyed by resource type. */
 export interface VersionResources {
-    commands?: string[];
-    skills?: string[];
-    hooks?: string[];
-    memory?: string[];
-    mcp?: string[];
-    permissions?: string[];
-    subagents?: string[];
-    plugins?: string[];
     /**
-     * Active rule preset for this agent@version. The composer reads layered
-     * `rules.yaml` files and emits this preset's subrules as the agent's
-     * single instruction file. Absent/null means the literal "default" preset.
+     * Active rule preset. Absent/null means "default".
      */
     rulesPreset?: string;
+    skills?: ResourcePattern[];
+    commands?: ResourcePattern[];
+    hooks?: ResourcePattern[];
+    subagents?: ResourcePattern[];
+    plugins?: ResourcePattern[];
+    workflows?: ResourcePattern[];
+    permissions?: ResourcePattern[];
+    mcp?: ResourcePattern[];
+}
+/** A userConfig field declared in a plugin manifest. */
+export interface PluginUserConfigField {
+    key: string;
+    description: string;
+    required?: boolean;
+    default?: string;
 }
-/** Manifest file (plugin.yaml) at the root of a plugin bundle. */
+/** Manifest file (plugin.json) at the root of a plugin bundle. */
 export interface PluginManifest {
     name: string;
     description: string;
     version: string;
     agents?: AgentId[];
+    /** Interactive config fields prompted at install time. Values stored in .user-config.json. */
+    userConfig?: PluginUserConfigField[];
+    /** Other plugin names this plugin depends on. Missing deps produce a warning. */
+    dependencies?: string[];
 }
 /** A plugin found on disk with its parsed manifest and resource inventory. */
 export interface DiscoveredPlugin {
@@ -321,6 +340,16 @@ export interface DiscoveredPlugin {
     skills: string[];
     hooks: string[];
     scripts: string[];
+    /** Slash-command .md files in the plugin's commands/ directory (names without extension). */
+    commands: string[];
+    /** Subagent .md files in the plugin's agents/ directory (names without extension). */
+    agentDefs: string[];
+    /** Executable files in the plugin's bin/ directory. */
+    bin: string[];
+    /** Whether the plugin root contains a .mcp.json file. */
+    hasMcp: boolean;
+    /** Whether the plugin root contains a settings.json with non-permission keys to merge. */
+    hasSettings: boolean;
 }
 /** Frontmatter fields parsed from a subagent's agent.md file. */
 export interface SubagentFrontmatter {
@@ -378,6 +407,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.d.ts

@@ -15,6 +15,7 @@ export interface ResourceSelection {
     permissions?: string[] | 'all';
     subagents?: string[] | 'all';
     plugins?: string[] | 'all';
+    workflows?: string[] | 'all';
 }
 /**
  * Available resources in ~/.agents/ for syncing.
@@ -33,6 +34,7 @@ export interface AvailableResources {
     permissions: string[];
     subagents: string[];
     plugins: string[];
+    workflows: string[];
     promptcuts: boolean;
 }
 /**
@@ -215,6 +217,7 @@ export interface SyncResult {
     mcp: string[];
     subagents: string[];
     plugins: string[];
+    workflows: string[];
 }
 /** Diff between central ~/.agents/ resources and what is synced to a version home. */
 export interface ResourceDiff {