@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/models.js

@@ -11,8 +11,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { getVersionDir } from './versions.js';
-import { getAgentsDir } from './state.js';
-const CACHE_PATH = path.join(getAgentsDir(), '.models-cache.json');
+import { getModelsCachePath } from './state.js';
+const CACHE_PATH = getModelsCachePath();
 /**
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.

package/dist/lib/permissions.d.ts

@@ -8,10 +8,6 @@ export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
  * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
  */
 export declare function convertDenyToCodexRules(deny: string[]): string | null;
-/**
- * Ensure central permissions directory exists.
- */
-export declare function ensurePermissionsDir(): void;
 /**
  * Parse a permission set from a YAML file.
  */
@@ -42,26 +38,26 @@ export declare function discoverPermissionGroups(): PermissionGroupInfo[];
  */
 export declare function getTotalPermissionRuleCount(): number;
 /**
- * A permission set recipe — names a set and lists which groups it composes.
- * Lives at ~/.agents/permissions/sets/<name>.yaml.
+ * A permission preset recipe — names a preset and lists which groups it composes.
+ * Lives at ~/.agents/permissions/presets/<name>.yaml.
  */
-export interface PermissionSetRecipe {
+export interface PermissionPresetRecipe {
     name: string;
     description?: string;
     includes: string[];
 }
 /** Env var that selects which set recipe to apply at sync time. */
-export declare const PERMISSION_SET_ENV_VAR = "AGENTS_PERMISSION_SET";
+export declare const PERMISSION_PRESET_ENV_VAR = "AGENTS_PERMISSION_PRESET";
 /**
- * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Read a permission preset recipe by name from ~/.agents/permissions/presets/.
  * Returns null if the recipe file is missing or malformed.
  */
-export declare function readPermissionSetRecipe(name: string): PermissionSetRecipe | null;
+export declare function readPermissionPresetRecipe(name: string): PermissionPresetRecipe | null;
 /**
- * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * Return the active permission preset name from AGENTS_PERMISSION_PRESET env var,
  * or null if unset. Caller decides the default behavior when null.
  */
-export declare function getActivePermissionSetName(): string | null;
+export declare function getActivePermissionPresetName(): string | null;
 /**
  * Build a PermissionSet from selected groups.
  * Concatenates allow/deny rules from each group.
@@ -76,10 +72,6 @@ export declare function buildPermissionsFromGroups(groupNames: string[]): Permis
  * same-named override.
  */
 export declare function listInstalledPermissions(): InstalledPermission[];
-/**
- * Get a specific permission set by name. Searches user dir first, then system.
- */
-export declare function getPermissionSet(name: string): InstalledPermission | null;
 /**
  * Install a permission set to user-level central storage.
  */
@@ -110,24 +102,6 @@ export declare function convertToOpenCodeFormat(set: PermissionSet): OpenCodePer
  * Codex uses coarse-grained modes, so we infer the best fit.
  */
 export declare function convertToCodexFormat(set: PermissionSet, cwd?: string): CodexPermissions;
-/**
- * Read Claude's current permissions from settings.json.
- */
-export declare function readClaudePermissions(scope?: 'user' | 'project', cwd?: string, options?: {
-    home?: string;
-}): ClaudePermissions | null;
-/**
- * Read OpenCode's current permissions from opencode.jsonc.
- */
-export declare function readOpenCodePermissions(scope?: 'user' | 'project', cwd?: string, options?: {
-    home?: string;
-}): OpenCodePermissions | null;
-/**
- * Read Codex's current permissions from config.toml.
- */
-export declare function readCodexPermissions(scope?: 'user' | 'project', cwd?: string, options?: {
-    home?: string;
-}): CodexPermissions | null;
 /**
  * Read agent permissions based on agent ID.
  */
@@ -141,27 +115,6 @@ export declare function applyClaudePermissions(set: PermissionSet, scope?: 'user
     success: boolean;
     error?: string;
 };
-/**
- * Apply a permission set to OpenCode's opencode.jsonc.
- */
-export declare function applyOpenCodePermissions(set: PermissionSet, scope?: 'user' | 'project', cwd?: string, merge?: boolean): {
-    success: boolean;
-    error?: string;
-};
-/**
- * Apply a permission set to Codex's config.toml.
- */
-export declare function applyCodexPermissions(set: PermissionSet, scope?: 'user' | 'project', cwd?: string, merge?: boolean): {
-    success: boolean;
-    error?: string;
-};
-/**
- * Apply a permission set to an agent (global config).
- */
-export declare function applyPermissionsToAgent(agentId: AgentId, set: PermissionSet, scope?: 'user' | 'project', cwd?: string, merge?: boolean): {
-    success: boolean;
-    error?: string;
-};
 /**
  * Apply a permission set to a specific version's home directory.
  * This writes to {versionHome}/.{agent}/settings.json (or equivalent).
@@ -182,22 +135,11 @@ export declare function openCodeToCanonical(perms: OpenCodePermissions): Permiss
  * Convert Codex permissions back to canonical format (approximation).
  */
 export declare function codexToCanonical(perms: CodexPermissions): PermissionSet;
-/**
- * Export agent's current permissions to canonical format.
- */
-export declare function exportAgentPermissions(agentId: AgentId, scope?: 'user' | 'project', cwd?: string): PermissionSet | null;
 /**
  * Export permissions from a specific config file path to canonical format.
  * Auto-detects agent type from file path/name.
  */
 export declare function exportPermissionsFromPath(filePath: string): PermissionSet | null;
-/**
- * Save a permission set to central storage.
- */
-export declare function savePermissionSet(set: PermissionSet): {
-    success: boolean;
-    error?: string;
-};
 /**
  * Get the default permission set from central storage.
  */

package/dist/lib/permissions.js

@@ -44,7 +44,7 @@ export function convertDenyToCodexRules(deny) {
 /**
  * Ensure central permissions directory exists.
  */
-export function ensurePermissionsDir() {
+function ensurePermissionsDir() {
     const dir = getUserPermissionsDir();
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
@@ -159,15 +159,15 @@ export function getTotalPermissionRuleCount() {
     return groups.reduce((sum, g) => sum + g.ruleCount, 0);
 }
 /** Env var that selects which set recipe to apply at sync time. */
-export const PERMISSION_SET_ENV_VAR = 'AGENTS_PERMISSION_SET';
+export const PERMISSION_PRESET_ENV_VAR = 'AGENTS_PERMISSION_PRESET';
 /**
- * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Read a permission preset recipe by name from ~/.agents/permissions/presets/.
  * Returns null if the recipe file is missing or malformed.
  */
-export function readPermissionSetRecipe(name) {
-    const setsDir = path.join(getPermissionsDir(), 'sets');
+export function readPermissionPresetRecipe(name) {
+    const presetsDir = path.join(getPermissionsDir(), 'presets');
     for (const ext of ['.yaml', '.yml']) {
-        const filePath = safeJoin(setsDir, name + ext);
+        const filePath = safeJoin(presetsDir, name + ext);
         if (!fs.existsSync(filePath))
             continue;
         try {
@@ -190,11 +190,11 @@ export function readPermissionSetRecipe(name) {
     return null;
 }
 /**
- * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * Return the active permission preset name from AGENTS_PERMISSION_PRESET env var,
  * or null if unset. Caller decides the default behavior when null.
  */
-export function getActivePermissionSetName() {
-    const v = process.env[PERMISSION_SET_ENV_VAR];
+export function getActivePermissionPresetName() {
+    const v = process.env[PERMISSION_PRESET_ENV_VAR];
     return v && v.trim() ? v.trim() : null;
 }
 /**
@@ -295,7 +295,7 @@ export function listInstalledPermissions() {
 /**
  * Get a specific permission set by name. Searches user dir first, then system.
  */
-export function getPermissionSet(name) {
+function getPermissionSet(name) {
     for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
         for (const ext of ['.yml', '.yaml']) {
             const filePath = safeJoin(dir, name + ext);
@@ -504,7 +504,7 @@ function stripJsonComments(content) {
 /**
  * Read Claude's current permissions from settings.json.
  */
-export function readClaudePermissions(scope = 'user', cwd, options) {
+function readClaudePermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = scope === 'user'
         ? path.join(home, '.claude', 'settings.json')
@@ -532,7 +532,7 @@ export function readClaudePermissions(scope = 'user', cwd, options) {
 /**
  * Read OpenCode's current permissions from opencode.jsonc.
  */
-export function readOpenCodePermissions(scope = 'user', cwd, options) {
+function readOpenCodePermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = scope === 'user'
         ? path.join(home, '.opencode', 'opencode.jsonc')
@@ -559,7 +559,7 @@ export function readOpenCodePermissions(scope = 'user', cwd, options) {
 /**
  * Read Codex's current permissions from config.toml.
  */
-export function readCodexPermissions(scope = 'user', cwd, options) {
+function readCodexPermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = scope === 'user'
         ? path.join(home, '.codex', 'config.toml')
@@ -649,7 +649,7 @@ export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
 /**
  * Apply a permission set to OpenCode's opencode.jsonc.
  */
-export function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
+function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
     const configDir = scope === 'user'
         ? path.join(HOME, '.opencode')
         : path.join(cwd || process.cwd(), '.opencode');
@@ -690,7 +690,7 @@ export function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true)
 /**
  * Apply a permission set to Codex's config.toml.
  */
-export function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
+function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
     const configDir = scope === 'user'
         ? path.join(HOME, '.codex')
         : path.join(cwd || process.cwd(), '.codex');
@@ -739,7 +739,7 @@ export function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
 /**
  * Apply a permission set to an agent (global config).
  */
-export function applyPermissionsToAgent(agentId, set, scope = 'user', cwd, merge = true) {
+function applyPermissionsToAgent(agentId, set, scope = 'user', cwd, merge = true) {
     switch (agentId) {
         case 'claude':
             return applyClaudePermissions(set, scope, cwd, merge);
@@ -912,7 +912,7 @@ export function codexToCanonical(perms) {
 /**
  * Export agent's current permissions to canonical format.
  */
-export function exportAgentPermissions(agentId, scope = 'user', cwd) {
+function exportAgentPermissions(agentId, scope = 'user', cwd) {
     const perms = readAgentPermissions(agentId, scope, cwd);
     if (!perms)
         return null;
@@ -1017,7 +1017,7 @@ export function exportPermissionsFromPath(filePath) {
 /**
  * Save a permission set to central storage.
  */
-export function savePermissionSet(set) {
+function savePermissionSet(set) {
     ensurePermissionsDir();
     const filePath = safeJoin(getUserPermissionsDir(), set.name + '.yml');
     try {

package/dist/lib/plugins.d.ts

@@ -1,16 +1,18 @@
 /**
  * Plugin discovery, validation, and syncing.
  *
- * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks, and
- * scripts under a single manifest (plugin.yaml). This module discovers plugins,
- * validates their manifests, and syncs their contents into agent version homes.
+ * Plugins are bundles in ~/.agents/.cache/plugins/ that package skills, hooks,
+ * commands, agents, bin scripts, MCP servers, and settings under a single
+ * manifest (plugin.json). This module discovers plugins, validates their
+ * manifests, and syncs their contents into agent version homes.
  */
 import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
 /**
- * Discover all plugins in ~/.agents/plugins/.
+ * Discover all plugins in ~/.agents/.cache/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
  */
 export declare function discoverPlugins(): DiscoveredPlugin[];
+export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest): DiscoveredPlugin;
 /**
  * Load a plugin manifest from a plugin directory.
  */
@@ -25,55 +27,123 @@ export declare function getPlugin(name: string): DiscoveredPlugin | null;
  * Otherwise defaults to all plugin-capable agents.
  */
 export declare function pluginSupportsAgent(plugin: DiscoveredPlugin, agent: AgentId): boolean;
+/** Discover command .md files inside a plugin's commands/ directory. */
+export declare function discoverPluginCommands(pluginRoot: string): string[];
+/** Discover agent definition .md files inside a plugin's agents/ directory. */
+export declare function discoverPluginAgentDefs(pluginRoot: string): string[];
+/** Discover executable files in a plugin's bin/ directory. */
+export declare function discoverPluginBin(pluginRoot: string): string[];
 /**
  * Expand plugin variables in a string.
  *
  * Variables:
- *   ${CLAUDE_PLUGIN_ROOT}  -> absolute path to plugin directory
- *   ${CLAUDE_PLUGIN_DATA}  -> per-version data directory for this plugin
+ *   ${CLAUDE_PLUGIN_ROOT}      -> absolute path to plugin directory
+ *   ${CLAUDE_PLUGIN_DATA}      -> per-version data directory for this plugin
+ *   ${user_config.<key>}       -> value from plugin's .user-config.json
  */
-export declare function expandPluginVars(str: string, pluginRoot: string, pluginName: string, agentId: AgentId, versionHome: string): string;
+export declare function expandPluginVars(str: string, pluginRoot: string, pluginName: string, agentId: AgentId, versionHome: string, userConfig?: Record<string, string>): string;
+/**
+ * Load persisted user config for a plugin from .user-config.json.
+ */
+export declare function loadUserConfig(pluginName: string): Record<string, string>;
+/**
+ * Persist user config for a plugin to .user-config.json.
+ */
+export declare function saveUserConfig(pluginName: string, config: Record<string, string>): void;
+/**
+ * Check plugin dependencies against installed plugins.
+ * Returns names of missing dependencies (warning only — not a hard error).
+ */
+export declare function checkPluginDependencies(manifest: PluginManifest): string[];
 /**
  * Sync a plugin to a specific agent version's home directory.
  *
  * For Claude:
- *   1. Copy plugin skills into version's skills dir (prefixed: pluginName:skillName)
- *   2. Read hooks/hooks.json, expand vars, merge into settings.json hooks
- *   3. Read settings.json, expand vars, merge permissions into settings.json
- *
- * For OpenClaw:
- *   1. Copy plugin skills into version's skills dir
+ *   1. Copy plugin skills into version's skills dir (prefixed: pluginName--skillName)
+ *   2. Copy plugin commands into version's commands dir (prefixed: pluginName--cmdName.md)
+ *   3. Copy plugin agent defs into version's agents dir (prefixed: pluginName--agentName.md)
+ *   4. Copy plugin bin/ into version home plugin-bin/<pluginName>/, note path in settings
+ *   5. Read hooks/hooks.json, expand vars, merge into settings.json hooks
+ *   6. Read .mcp.json, expand vars, merge mcpServers into settings.json
+ *   7. Read settings.json, merge non-permission keys non-destructively into settings.json
+ *   8. Read settings.json permissions, expand vars, merge into settings.json
  */
 export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): {
     success: boolean;
     skills: string[];
+    commands: string[];
+    agentDefs: string[];
+    bin: string[];
     hooks: string[];
     permissions: boolean;
+    mcp: boolean;
+    settings: boolean;
 };
 /**
  * Check if a plugin is synced to a version by inspecting the version home.
- * Checks multiple signals: skills directories, hook commands in settings.json,
- * and plugin permissions in settings.json.
+ * Checks skills, commands, agent defs, bin, hook commands, and permissions.
  */
 export declare function isPluginSynced(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): boolean;
 /**
  * Remove a plugin from a specific agent version's home directory.
- * Inverse of syncPluginToVersion:
- *   1. Delete synced skill directories (pluginName--*)
- *   2. Strip hook entries whose commands reference the plugin root
- *   3. Strip permission rules that reference the plugin root
+ * Inverse of syncPluginToVersion.
  *
- * Works whether or not the plugin source still exists on disk, because it
- * matches by the plugin's name and root path rather than re-reading manifests.
+ * Works whether or not the plugin source still exists on disk.
  */
 export declare function removePluginFromVersion(pluginName: string, pluginRoot: string, agent: AgentId, versionHome: string): {
     skills: string[];
+    commands: string[];
+    agentDefs: string[];
+    bin: string[];
     hooks: string[];
     permissions: number;
+    mcp: number;
 };
 /**
  * Remove orphaned plugin skill directories from a version home.
- * An orphan is a skill dir with the plugin prefix pattern (name--skill)
- * where the plugin no longer exists in ~/.agents/plugins/.
+ * Soft-deletes to ~/.agents/.trash/plugins/.
  */
-export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>): string[];
+export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
+export interface VersionPluginDiff {
+    agent: AgentId;
+    version: string;
+    orphans: string[];
+}
+export declare function diffVersionPlugins(agent: AgentId, version: string): VersionPluginDiff;
+export declare function iterPluginsCapableVersions(filter?: {
+    agent?: AgentId;
+    version?: string;
+}): Array<{
+    agent: AgentId;
+    version: string;
+}>;
+export declare function removePluginSkillFromVersion(agent: AgentId, version: string, skillName: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Parse an install spec of the form `name@source` or just `source`.
+ * Source can be a git URL or an absolute/relative local path.
+ */
+export declare function parseInstallSpec(spec: string): {
+    name: string | null;
+    source: string;
+};
+/**
+ * Install a plugin from a git URL or local path.
+ * Clones/copies to ~/.agents/.cache/plugins/<name>/.
+ * Returns the installed plugin name and root path.
+ */
+export declare function installPlugin(spec: string): Promise<{
+    name: string;
+    root: string;
+    isNew: boolean;
+}>;
+/**
+ * Update an installed plugin by re-pulling from its original source.
+ * Returns true if the update succeeded.
+ */
+export declare function updatePlugin(name: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;