@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/onepassword.js

@@ -0,0 +1,186 @@
+/**
+ * 1Password CLI (op) integration for importing secrets from vaults.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+function runOp(args, input) {
+    const result = spawnSync('op', args, {
+        stdio: [input !== undefined ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+        input,
+    });
+    if (result.error) {
+        if (result.error.code === 'ENOENT') {
+            return { ok: false, error: '1Password CLI not found. Install: brew install 1password-cli' };
+        }
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        const stderr = result.stderr?.trim() || '';
+        if (stderr.includes('not signed in') || stderr.includes('sign in') || stderr.includes('no active session')) {
+            return { ok: false, error: 'Not signed in to 1Password. Run: op signin' };
+        }
+        return { ok: false, error: stderr || `op exited with code ${result.status}` };
+    }
+    return { ok: true, stdout: result.stdout };
+}
+export function assertOpAvailable() {
+    // `op account list` works with both CLI session tokens and the 1Password
+    // desktop biometric integration; `op whoami` fails on the latter.
+    const result = runOp(['account', 'list', '--format=json']);
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+}
+export function listVaults() {
+    const result = runOp(['vault', 'list', '--format=json']);
+    if (!result.ok)
+        throw new Error(result.error);
+    return JSON.parse(result.stdout);
+}
+export function listItems(vaultName) {
+    const result = runOp(['item', 'list', '--vault', vaultName, '--format=json']);
+    if (!result.ok) {
+        if (result.error.includes('vault') && result.error.includes('not found')) {
+            const vaults = listVaults();
+            const available = vaults.map((v) => v.name).join(', ');
+            throw new Error(`Vault '${vaultName}' not found. Available: ${available || '(none)'}`);
+        }
+        throw new Error(result.error);
+    }
+    const items = JSON.parse(result.stdout);
+    return items || [];
+}
+export function getItem(itemId, vaultName) {
+    const result = runOp(['item', 'get', itemId, '--vault', vaultName, '--format=json', '--reveal']);
+    if (!result.ok)
+        throw new Error(result.error);
+    return JSON.parse(result.stdout);
+}
+export function toEnvKey(title) {
+    return title
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .replace(/^(\d)/, '_$1');
+}
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+const IMPORTABLE_FIELD_TYPES = new Set([
+    'CONCEALED', 'concealed',
+    'STRING', 'string', 'text', 'TEXT',
+    'URL', 'url',
+]);
+const SKIP_FIELD_LABELS = new Set(['username', 'notesPlain', 'notes']);
+function pickBestField(fields) {
+    const dominated = fields.filter((f) => IMPORTABLE_FIELD_TYPES.has(f.type) &&
+        f.value &&
+        !SKIP_FIELD_LABELS.has(f.label?.toLowerCase() || ''));
+    if (dominated.length === 0)
+        return null;
+    // Prefer concealed fields (credentials/passwords)
+    const concealed = dominated.find((f) => f.type.toLowerCase() === 'concealed');
+    if (concealed)
+        return concealed;
+    // Then prefer fields labeled credential/password/secret/key/token
+    const secretLabels = ['credential', 'password', 'secret', 'key', 'token', 'api_key', 'apikey'];
+    const labeled = dominated.find((f) => secretLabels.includes(f.label?.toLowerCase() || ''));
+    if (labeled)
+        return labeled;
+    // Fall back to first importable field
+    return dominated[0];
+}
+export function extractSecrets(items, vaultName) {
+    const secrets = [];
+    const skipped = [];
+    for (const summary of items) {
+        let item;
+        try {
+            item = getItem(summary.id, vaultName);
+        }
+        catch (err) {
+            skipped.push({
+                itemTitle: summary.title,
+                fieldLabel: '*',
+                reason: err.message,
+            });
+            continue;
+        }
+        const field = pickBestField(item.fields || []);
+        if (!field) {
+            skipped.push({
+                itemTitle: item.title,
+                fieldLabel: '*',
+                reason: 'no importable fields',
+            });
+            continue;
+        }
+        if (field.value.includes('\n')) {
+            skipped.push({
+                itemTitle: item.title,
+                fieldLabel: field.label,
+                reason: 'contains newlines (keychain limitation)',
+            });
+            continue;
+        }
+        const envKey = toEnvKey(item.title);
+        secrets.push({
+            envKey,
+            itemTitle: item.title,
+            fieldLabel: field.label,
+            value: field.value,
+        });
+    }
+    return { secrets, skipped };
+}
+export function buildPasswordItemTemplate(title, value) {
+    return {
+        title,
+        category: 'PASSWORD',
+        tags: ['agents-cli'],
+        fields: [
+            { id: 'password', type: 'CONCEALED', purpose: 'PASSWORD', label: 'password', value },
+        ],
+    };
+}
+export function itemExistsByTitle(title, vaultName) {
+    const result = runOp(['item', 'get', title, '--vault', vaultName, '--format=json']);
+    if (result.ok)
+        return true;
+    if (/isn't an item|not found|no item found/i.test(result.error))
+        return false;
+    throw new Error(result.error);
+}
+export function deleteItemByTitle(title, vaultName) {
+    const result = runOp(['item', 'delete', title, '--vault', vaultName]);
+    if (!result.ok)
+        throw new Error(result.error);
+}
+export function createPasswordItem(title, value, vaultName) {
+    // op item create reads stdin templates only from a real pipe; spawnSync's
+    // input plumbing is detected as empty and op silently ignores the template.
+    // The supported alternative is --template <file>, which works reliably.
+    const template = JSON.stringify(buildPasswordItemTemplate(title, value));
+    const tmpFile = path.join(os.tmpdir(), `agents-op-tpl-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, template, { mode: 0o600 });
+    try {
+        const result = runOp(['item', 'create', '--template', tmpFile, '--vault', vaultName]);
+        if (!result.ok)
+            throw new Error(result.error);
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve base + name while preventing path-traversal attacks.
+ * Rejects path separators, null bytes, '.' and '..', and any resolved path
+ * that escapes the base directory. Dot-prefixed names like '.env.example'
+ * are allowed — actual traversal is caught by the containment check below.
+ * Allows spaces, unicode, and other common filename characters.
+ */
+export declare function safeJoin(base: string, name: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,20 @@
+import * as path from 'path';
+/**
+ * Resolve base + name while preventing path-traversal attacks.
+ * Rejects path separators, null bytes, '.' and '..', and any resolved path
+ * that escapes the base directory. Dot-prefixed names like '.env.example'
+ * are allowed — actual traversal is caught by the containment check below.
+ * Allows spaces, unicode, and other common filename characters.
+ */
+export function safeJoin(base, name) {
+    if (!name ||
+        name === '.' || name === '..' ||
+        /[\/\\\x00]/.test(name) ||
+        name.length > 255) {
+        throw new Error(`Invalid name: ${name}`);
+    }
+    const resolved = path.resolve(base, name);
+    if (!resolved.startsWith(path.resolve(base) + path.sep))
+        throw new Error(`Path escape: ${name}`);
+    return resolved;
+}

package/dist/lib/permissions.d.ts

@@ -1,9 +1,11 @@
 import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, OpenCodePermissions, CodexPermissions } from './types.js';
+/** Agents that support the permissions subsystem. */
 export declare const PERMISSIONS_CAPABLE_AGENTS: AgentId[];
+/** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 /**
  * Convert canonical deny rules to Codex Starlark .rules format.
- * E.g. "Bash(git reset:*)" → prefix_rule(pattern=["git", "reset"], decision="forbidden")
+ * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
  */
 export declare function convertDenyToCodexRules(deny: string[]): string | null;
 /**
@@ -39,6 +41,27 @@ export declare function discoverPermissionGroups(): PermissionGroupInfo[];
  * Get total rule count across all permission groups.
  */
 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.
+ */
+export interface PermissionSetRecipe {
+    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";
+/**
+ * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Returns null if the recipe file is missing or malformed.
+ */
+export declare function readPermissionSetRecipe(name: string): PermissionSetRecipe | null;
+/**
+ * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * or null if unset. Caller decides the default behavior when null.
+ */
+export declare function getActivePermissionSetName(): string | null;
 /**
  * Build a PermissionSet from selected groups.
  * Concatenates allow/deny rules from each group.
@@ -201,4 +224,3 @@ export declare function saveDefaultPermissionSet(set: PermissionSet): {
     success: boolean;
     error?: string;
 };
-//# sourceMappingURL=permissions.d.ts.map

package/dist/lib/permissions.js

@@ -1,17 +1,27 @@
+/**
+ * Permission management for AI coding agents.
+ *
+ * Provides a canonical permission format (PermissionSet with allow/deny rules)
+ * and converters to/from each agent's native format (Claude settings.json,
+ * OpenCode opencode.jsonc, Codex config.toml + .rules). Handles discovery,
+ * installation, removal, and merging of permission groups stored in
+ * ~/.agents/permissions/groups/.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-import { getPermissionsDir, ensureAgentsDir } from './state.js';
+import { getPermissionsDir, getUserPermissionsDir, ensureAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 const HOME = os.homedir();
-// Agents that support permissions
+/** Agents that support the permissions subsystem. */
 export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode'];
-// Codex .rules file name for deny permissions
+/** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
 /**
  * Convert canonical deny rules to Codex Starlark .rules format.
- * E.g. "Bash(git reset:*)" → prefix_rule(pattern=["git", "reset"], decision="forbidden")
+ * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
  */
 export function convertDenyToCodexRules(deny) {
     const rules = [];
@@ -24,7 +34,7 @@ export function convertDenyToCodexRules(deny) {
         if (!command)
             continue;
         const parts = command.split(/\s+/);
-        const patternStr = parts.map(p => `"${p}"`).join(', ');
+        const patternStr = parts.map(p => JSON.stringify(p)).join(', ');
         rules.push(`prefix_rule(\n    pattern = [${patternStr}],\n    decision = "forbidden",\n)`);
     }
     if (rules.length === 0)
@@ -35,7 +45,7 @@ export function convertDenyToCodexRules(deny) {
  * Ensure central permissions directory exists.
  */
 export function ensurePermissionsDir() {
-    const dir = getPermissionsDir();
+    const dir = getUserPermissionsDir();
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
@@ -108,38 +118,37 @@ export function discoverPermissionsFromRepo(repoPath) {
  * Returns groups with their rule counts.
  */
 export function discoverPermissionGroups() {
-    const groupsDir = path.join(getPermissionsDir(), 'groups');
-    if (!fs.existsSync(groupsDir)) {
-        return [];
-    }
+    const seen = new Set();
     const groups = [];
-    try {
-        const entries = fs.readdirSync(groupsDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
-                continue;
-            const filePath = path.join(groupsDir, entry.name);
-            const name = entry.name.replace(/\.(yaml|yml)$/, '');
-            // Count rules in this group
-            let ruleCount = 0;
-            try {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                // Count lines that look like permission entries (start with - " after optional whitespace)
-                const matches = content.match(/^\s*-\s*"/gm);
-                ruleCount = matches ? matches.length : 0;
-            }
-            catch {
-                // Skip files we can't read
+    // Search user dir first, then system (user wins on name collision)
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const groupsDir = path.join(baseDir, 'groups');
+        if (!fs.existsSync(groupsDir))
+            continue;
+        try {
+            const entries = fs.readdirSync(groupsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
+                    continue;
+                const name = entry.name.replace(/\.(yaml|yml)$/, '');
+                if (seen.has(name))
+                    continue;
+                seen.add(name);
+                const filePath = path.join(groupsDir, entry.name);
+                let ruleCount = 0;
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const matches = content.match(/^\s*-\s*"/gm);
+                    ruleCount = matches ? matches.length : 0;
+                }
+                catch { /* Skip files we can't read */ }
+                groups.push({ name, ruleCount, path: filePath });
             }
-            groups.push({ name, ruleCount, path: filePath });
         }
+        catch { /* Skip inaccessible directory */ }
     }
-    catch {
-        // Skip inaccessible directory
-    }
-    // Sort by name (which sorts by numeric prefix)
     return groups.sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
@@ -149,6 +158,45 @@ export function getTotalPermissionRuleCount() {
     const groups = discoverPermissionGroups();
     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';
+/**
+ * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Returns null if the recipe file is missing or malformed.
+ */
+export function readPermissionSetRecipe(name) {
+    const setsDir = path.join(getPermissionsDir(), 'sets');
+    for (const ext of ['.yaml', '.yml']) {
+        const filePath = safeJoin(setsDir, name + ext);
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const parsed = yaml.parse(content);
+            if (!parsed || typeof parsed !== 'object')
+                return null;
+            if (!Array.isArray(parsed.includes))
+                return null;
+            return {
+                name: parsed.name || name,
+                description: parsed.description,
+                includes: parsed.includes.filter((v) => typeof v === 'string'),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * or null if unset. Caller decides the default behavior when null.
+ */
+export function getActivePermissionSetName() {
+    const v = process.env[PERMISSION_SET_ENV_VAR];
+    return v && v.trim() ? v.trim() : null;
+}
 /**
  * Build a PermissionSet from selected groups.
  * Concatenates allow/deny rules from each group.
@@ -157,18 +205,25 @@ export function getTotalPermissionRuleCount() {
  * permission files often contain unescaped nested quotes that break YAML.
  */
 export function buildPermissionsFromGroups(groupNames) {
-    const groupsDir = path.join(getPermissionsDir(), 'groups');
     const allAllow = [];
     const allDeny = [];
     for (const groupName of groupNames) {
-        // Try both .yaml and .yml extensions
-        let filePath = path.join(groupsDir, `${groupName}.yaml`);
-        if (!fs.existsSync(filePath)) {
-            filePath = path.join(groupsDir, `${groupName}.yml`);
+        // Search user dir first, then system dir
+        let filePath = null;
+        for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+            const groupsDir = path.join(baseDir, 'groups');
+            for (const ext of ['.yaml', '.yml']) {
+                const candidate = safeJoin(groupsDir, `${groupName}${ext}`);
+                if (fs.existsSync(candidate)) {
+                    filePath = candidate;
+                    break;
+                }
+            }
+            if (filePath)
+                break;
         }
-        if (!fs.existsSync(filePath)) {
+        if (!filePath)
             continue;
-        }
         try {
             const content = fs.readFileSync(filePath, 'utf-8');
             // Extract rules using line-by-line regex (more robust than YAML parsing)
@@ -241,7 +296,7 @@ export function listInstalledPermissions() {
 export function getPermissionSet(name) {
     const dir = getPermissionsDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(dir, name + ext);
+        const filePath = safeJoin(dir, name + ext);
         if (fs.existsSync(filePath)) {
             const set = parsePermissionSet(filePath);
             if (set) {
@@ -260,7 +315,7 @@ export function installPermissionSet(sourcePath, name) {
     if (!set) {
         return { success: false, error: 'Invalid permission file' };
     }
-    const targetPath = path.join(getPermissionsDir(), name + '.yml');
+    const targetPath = safeJoin(getPermissionsDir(), name + '.yml');
     try {
         fs.copyFileSync(sourcePath, targetPath);
         return { success: true };
@@ -275,7 +330,7 @@ export function installPermissionSet(sourcePath, name) {
 export function removePermissionSet(name) {
     const dir = getPermissionsDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(dir, name + ext);
+        const filePath = safeJoin(dir, name + ext);
         if (fs.existsSync(filePath)) {
             try {
                 fs.unlinkSync(filePath);
@@ -316,6 +371,8 @@ function parseCanonicalPattern(permission) {
         return null;
     return { tool: match[1].toLowerCase(), pattern: match[2] };
 }
+/** Blanket-Bash canonical forms that mean "allow any bash command". */
+const BLANKET_BASH_FORMS = new Set(['Bash', 'Bash(*)', 'Bash(**)']);
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
@@ -324,6 +381,12 @@ export function convertToOpenCodeFormat(set) {
     const bashPermissions = {};
     // Process allow list
     for (const perm of set.allow) {
+        if (BLANKET_BASH_FORMS.has(perm)) {
+            // Bare "Bash" has no parens so parseCanonicalPattern returns null;
+            // normalize all three blanket forms to "*".
+            bashPermissions['*'] = 'allow';
+            continue;
+        }
         const parsed = parseCanonicalPattern(perm);
         if (parsed && parsed.tool === 'bash') {
             bashPermissions[parsed.pattern] = 'allow';
@@ -350,10 +413,16 @@ export function convertToOpenCodeFormat(set) {
  */
 export function convertToCodexFormat(set, cwd) {
     const result = {};
-    // Check for broad bash permissions -> suggest full-auto
+    // Check for broad bash permissions -> suggest full-auto.
+    // Treat the bare blanket form "Bash" the same as "Bash(*)" / "Bash(**)";
+    // parseCanonicalPattern requires parens so "Bash" alone wouldn't match
+    // otherwise — the difference determines whether a pod runs unattended
+    // (approval_policy: 'never') or stalls on interactive approvals.
     const hasBroadBash = set.allow.some((p) => {
+        if (BLANKET_BASH_FORMS.has(p))
+            return true;
         const parsed = parseCanonicalPattern(p);
-        return parsed && parsed.tool === 'bash' && (parsed.pattern === '*' || parsed.pattern === '**');
+        return parsed !== null && parsed.tool === 'bash' && (parsed.pattern === '*' || parsed.pattern === '**');
     });
     if (hasBroadBash) {
         result.approval_policy = 'never';
@@ -946,7 +1015,7 @@ export function exportPermissionsFromPath(filePath) {
  */
 export function savePermissionSet(set) {
     ensurePermissionsDir();
-    const filePath = path.join(getPermissionsDir(), set.name + '.yml');
+    const filePath = safeJoin(getUserPermissionsDir(), set.name + '.yml');
     try {
         const content = yaml.stringify({
             name: set.name,
@@ -961,6 +1030,7 @@ export function savePermissionSet(set) {
         return { success: false, error: err.message };
     }
 }
+/** Name used for the default permission set in central storage. */
 const DEFAULT_PERMISSION_SET_NAME = 'default';
 /**
  * Get the default permission set from central storage.
@@ -1019,4 +1089,3 @@ export function saveDefaultPermissionSet(set) {
     set.name = DEFAULT_PERMISSION_SET_NAME;
     return savePermissionSet(set);
 }
-//# sourceMappingURL=permissions.js.map

package/dist/lib/picker.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Interactive fuzzy-filter picker built on @inquirer/core.
+ *
+ * Provides a searchable, paginated list UI with optional preview pane
+ * for selecting items in the terminal. Used by session picker, command
+ * picker, and other interactive selection flows.
+ */
+/** Configuration for the interactive picker prompt. */
 export interface PickerConfig<T> {
     message: string;
     items: T[];
@@ -10,8 +18,9 @@ export interface PickerConfig<T> {
     emptyMessage?: string;
     enterHint?: string;
 }
+/** The result returned when the user selects an item. */
 export interface PickedItem<T> {
     item: T;
 }
+/** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;
-//# sourceMappingURL=picker.d.ts.map

package/dist/lib/picker.js

@@ -1,5 +1,20 @@
+/**
+ * Interactive fuzzy-filter picker built on @inquirer/core.
+ *
+ * Provides a searchable, paginated list UI with optional preview pane
+ * for selecting items in the terminal. Used by session picker, command
+ * picker, and other interactive selection flows.
+ */
+/**
+ * Custom inquirer prompt for searchable, scrollable selection lists.
+ *
+ * Extends @inquirer/core to support type-ahead filtering, column-aligned
+ * display, and keyboard navigation. Used by sessions, teams, and other
+ * interactive pickers throughout the CLI.
+ */
 import { createPrompt, useState, useKeypress, useEffect, useMemo, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, } from '@inquirer/core';
 import chalk from 'chalk';
+/** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export function itemPicker(config) {
     const prompt = createPrompt((cfg, done) => {
         const theme = makeTheme({});
@@ -92,4 +107,3 @@ export function itemPicker(config) {
     });
     return prompt(config);
 }
-//# sourceMappingURL=picker.js.map

package/dist/lib/plugins.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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.
+ */
 import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
 /**
  * Discover all plugins in ~/.agents/plugins/.
@@ -70,4 +77,3 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
  * where the plugin no longer exists in ~/.agents/plugins/.
  */
 export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>): string[];
-//# sourceMappingURL=plugins.d.ts.map

package/dist/lib/plugins.js

@@ -1,3 +1,10 @@
+/**
+ * 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.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getPluginsDir } from './state.js';
@@ -46,6 +53,9 @@ export function loadPluginManifest(pluginRoot) {
         const parsed = JSON.parse(content);
         if (!parsed.name || !parsed.version)
             return null;
+        if (/[/\\]/.test(parsed.name) || parsed.name.includes('..') || parsed.name.includes('\0')) {
+            return null;
+        }
         return parsed;
     }
     catch {
@@ -546,4 +556,3 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames)
     }
     return removed;
 }
-//# sourceMappingURL=plugins.js.map

package/dist/lib/profiles-presets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in profile presets for popular model providers.
+ *
+ * Each preset bundles a host CLI, API base URL, default model, and provider
+ * name so users can `agents profiles add kimi` without manual configuration.
+ */
+import type { AgentId } from './types.js';
+/** A pre-configured profile template for a model provider. */
+export interface Preset {
+    name: string;
+    description: string;
+    provider: string;
+    host: AgentId;
+    env: Record<string, string>;
+    authEnvVar: string;
+    signupUrl?: string;
+}
+export declare const PRESETS: Preset[];
+/** Look up a preset by name (case-sensitive). */
+export declare function getPreset(name: string): Preset | undefined;
+/** Return a copy of all available presets. */
+export declare function listPresets(): Preset[];
+/** Return the unique set of provider names across all presets. */
+export declare function listProviders(): string[];