@phnx-labs/agents-cli 1.16.0 → 1.17.1

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.
  */
@@ -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 });
@@ -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,57 +27,81 @@ 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.
  * Soft-deletes to ~/.agents/.trash/plugins/.
- * An orphan is a skill dir with the plugin prefix pattern (name--skill)
- * where the plugin no longer exists in ~/.agents/plugins/.
  */
 export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
 export interface VersionPluginDiff {
@@ -83,14 +109,7 @@ export interface VersionPluginDiff {
     version: string;
     orphans: string[];
 }
-/**
- * Compare a version home's plugin skills against discovered plugins.
- * Returns orphan plugin skill names (pattern: pluginName--skillName).
- */
 export declare function diffVersionPlugins(agent: AgentId, version: string): VersionPluginDiff;
-/**
- * Iterate all (agent, version) pairs that support plugins and are installed.
- */
 export declare function iterPluginsCapableVersions(filter?: {
     agent?: AgentId;
     version?: string;
@@ -98,11 +117,33 @@ export declare function iterPluginsCapableVersions(filter?: {
     agent: AgentId;
     version: string;
 }>;
-/**
- * Remove a single orphan plugin skill from a version home.
- * Soft-deletes to ~/.agents/.trash/plugins/.
- */
 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;
+}>;