@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/versions.js

@@ -23,14 +23,16 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import * as TOML from 'smol-toml';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
-import { resolveResource } from './resources.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
+import { defaultPatterns, expandPatterns } from './resource-patterns.js';
+import { resolveResource, listResources } 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 { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.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';
+import { WORKFLOW_CAPABLE_AGENTS, listInstalledWorkflows, syncWorkflowToVersion } from './workflows.js';
 import { registerHooksToSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins, syncPluginToVersion, isPluginSynced, pluginSupportsAgent, cleanOrphanedPluginSkills } from './plugins.js';
@@ -62,6 +64,7 @@ export function getAvailableResources(cwd = process.cwd()) {
         permissions: [],
         subagents: [],
         plugins: [],
+        workflows: [],
         promptcuts: false,
     };
     const projectAgentsDir = getProjectAgentsDir(cwd);
@@ -189,13 +192,26 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.subagents = Array.from(subagentNames);
+    // Workflows (directories with WORKFLOW.md)
+    const workflowNames = new Set();
+    for (const { base } of resourceBases) {
+        const workflowsDir = path.join(base, 'workflows');
+        if (!fs.existsSync(workflowsDir))
+            continue;
+        const names = fs.readdirSync(workflowsDir, { withFileTypes: true })
+            .filter(d => d.isDirectory() && fs.existsSync(path.join(workflowsDir, d.name, 'WORKFLOW.md')))
+            .map(d => d.name);
+        for (const name of names) {
+            workflowNames.add(name);
+        }
+    }
+    result.workflows = Array.from(workflowNames);
     // Plugins (directories with .claude-plugin/plugin.json)
     const allPlugins = discoverPlugins();
     result.plugins = allPlugins.map(p => p.name);
-    // Promptcuts — single file at ~/.agents/promptcuts.yaml, not per-agent.
-    // Project-scoped .agents/promptcuts.yaml is intentionally not supported
-    // (user-global shortcuts only — they follow the user, not the repo).
-    result.promptcuts = fs.existsSync(getPromptcutsPath());
+    // Promptcuts — present if either layer exists. Reads merge user + system
+    // with user precedence (see readMergedPromptcuts); writes always go to user.
+    result.promptcuts = fs.existsSync(getUserPromptcutsPath()) || fs.existsSync(getPromptcutsPath());
     return result;
 }
 // Files/dirs that are never synced into a version home (OS metadata, local tooling).
@@ -251,6 +267,7 @@ export function getActuallySyncedResources(agent, version, options = {}) {
         permissions: [],
         subagents: [],
         plugins: [],
+        workflows: [],
         promptcuts: false,
     };
     // Commands - check what files exist in version home
@@ -449,6 +466,15 @@ export function getActuallySyncedResources(agent, version, options = {}) {
             }
         }
     }
+    // Workflows - check {versionHome}/workflows/ for synced workflow directories
+    if (WORKFLOW_CAPABLE_AGENTS.includes(agent)) {
+        const workflowsDir = path.join(versionHome, 'workflows');
+        if (fs.existsSync(workflowsDir)) {
+            result.workflows = fs.readdirSync(workflowsDir, { withFileTypes: true })
+                .filter(d => d.isDirectory() && fs.existsSync(path.join(workflowsDir, d.name, 'WORKFLOW.md')))
+                .map(d => d.name);
+        }
+    }
     return result;
 }
 /**
@@ -470,6 +496,7 @@ export function getNewResources(available, actuallySynced) {
         permissions: available.permissions.filter(p => !actuallySynced.permissions.includes(p)),
         subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s)),
         plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p)),
+        workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w)),
         // Promptcuts aren't version-scoped — the hook reads ~/.agents/promptcuts.yaml
         // directly, so there is never a "new" per-version state to reconcile.
         promptcuts: false,
@@ -486,6 +513,7 @@ export function hasNewResources(diff, agent, version) {
     const permsApply = agent ? supports(agent, 'allowlist', version).ok : true;
     const subagentsApply = agent ? SUBAGENT_CAPABLE_AGENTS.includes(agent) : true;
     const pluginsApply = agent ? supports(agent, 'plugins', version).ok : true;
+    const workflowsApply = agent ? WORKFLOW_CAPABLE_AGENTS.includes(agent) : true;
     return ((diff.commands.length > 0 && commandsApply) ||
         diff.skills.length > 0 ||
         (diff.hooks.length > 0 && hooksApply) ||
@@ -493,7 +521,8 @@ export function hasNewResources(diff, agent, version) {
         (diff.mcp.length > 0 && mcpApply) ||
         (diff.permissions.length > 0 && permsApply) ||
         (diff.subagents.length > 0 && subagentsApply) ||
-        (diff.plugins.length > 0 && pluginsApply));
+        (diff.plugins.length > 0 && pluginsApply) ||
+        (diff.workflows.length > 0 && workflowsApply));
 }
 /**
  * Build a summary string of new resources.
@@ -526,6 +555,9 @@ function buildNewResourcesSummary(newResources, agent) {
     if (newResources.plugins.length > 0 && PLUGINS_CAPABLE_AGENTS.includes(agent)) {
         parts.push(`${newResources.plugins.length} plugin${newResources.plugins.length === 1 ? '' : 's'}`);
     }
+    if (newResources.workflows.length > 0 && WORKFLOW_CAPABLE_AGENTS.includes(agent)) {
+        parts.push(`${newResources.workflows.length} workflow${newResources.workflows.length === 1 ? '' : 's'}`);
+    }
     return parts.join(', ');
 }
 /**
@@ -574,6 +606,8 @@ export async function promptNewResourceSelection(agent, newResources) {
             selection.subagents = newResources.subagents;
         if (newResources.plugins.length > 0 && PLUGINS_CAPABLE_AGENTS.includes(agent))
             selection.plugins = newResources.plugins;
+        if (newResources.workflows.length > 0 && WORKFLOW_CAPABLE_AGENTS.includes(agent))
+            selection.workflows = newResources.workflows;
         return selection;
     }
     // Select specific items for each category
@@ -651,6 +685,14 @@ export async function promptNewResourceSelection(agent, newResources) {
         if (selected.length > 0)
             selection.plugins = selected;
     }
+    if (newResources.workflows.length > 0 && WORKFLOW_CAPABLE_AGENTS.includes(agent)) {
+        const selected = await checkbox({
+            message: 'Select new workflows to sync:',
+            choices: newResources.workflows.map(w => ({ name: w, value: w, checked: true })),
+        });
+        if (selected.length > 0)
+            selection.workflows = selected;
+    }
     return selection;
 }
 /**
@@ -676,14 +718,14 @@ export async function promptResourceSelection(agent) {
     ];
     const availableCategories = categories.filter(c => c.available);
     if (availableCategories.length === 0) {
-        console.log(chalk.gray('No resources available in ~/.agents/'));
+        console.log(chalk.gray('No resources available to sync.'));
         return {};
     }
     // Step 1: Select categories (with "Select All" shortcut at the top)
     console.log();
     const SELECT_ALL_KEY = '__select_all__';
     const selectedCategories = await checkbox({
-        message: 'Which resources from ~/.agents/ would you like to sync?',
+        message: 'Which resources would you like to sync?',
         choices: [
             { name: chalk.bold('Select All (sync everything)'), value: SELECT_ALL_KEY, checked: false },
             ...availableCategories.map(c => ({
@@ -1189,7 +1231,7 @@ export function resolveVersionAliasLoose(agent, raw) {
  * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
  */
 export function getProjectVersion(agent, startPath) {
-    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
     let dir = path.resolve(startPath);
     while (dir !== path.dirname(dir)) {
         const manifestPath = path.join(dir, 'agents.yaml');
@@ -1400,7 +1442,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const versionHome = getVersionHomePath(agent, version);
     const agentDir = path.join(versionHome, `.${agent}`);
     fs.mkdirSync(agentDir, { recursive: true });
-    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [] };
+    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
     const cwd = options.cwd || process.cwd();
     const projectAgentsDir = options.projectDir || getProjectAgentsDir(cwd);
     const userAgentsDir = getUserAgentsDir();
@@ -1408,13 +1450,80 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // project/user/system repos win on name collisions.
     const extraRepos = getEnabledExtraRepos();
     const available = getAvailableResources(cwd);
+    // Write default resource selection patterns for this version (idempotent —
+    // only sets fields that aren't already present, preserving user edits).
+    {
+        const extraAliases = extraRepos.map(e => e.alias);
+        const allLayers = defaultPatterns(extraAliases);
+        const noProject = defaultPatterns(extraAliases, false);
+        ensureVersionResourcePatterns(agent, version, {
+            commands: allLayers,
+            skills: allLayers,
+            hooks: noProject, // hooks: no project layer (security)
+            subagents: noProject,
+            plugins: noProject,
+            workflows: noProject,
+            permissions: ['system:*'],
+            mcp: ['user:*'],
+        });
+    }
+    // If no explicit selection was passed, build one from the persisted resource
+    // patterns. This lets users customize agents.yaml to control which resources
+    // are synced (e.g. "skills: [system:brain-scan user:creative]").
+    // When patterns are the default (every layer wildcard), the expanded result
+    // equals the full available set — identical to the old behavior.
+    if (!selection) {
+        const vr = getVersionResources(agent, version);
+        if (vr) {
+            const patternSelection = {};
+            // Listable resource types: use listResources to get name→source maps.
+            const listableTypes = [
+                ['commands', 'commands'],
+                ['skills', 'skills'],
+                ['hooks', 'hooks'],
+                ['subagents', 'subagents'],
+            ];
+            for (const [type, kind] of listableTypes) {
+                const patterns = vr[type];
+                if (!Array.isArray(patterns) || patterns.length === 0)
+                    continue;
+                const sourceMap = new Map(listResources(kind, cwd).map(r => [r.name, r.source]));
+                patternSelection[type] = expandPatterns(patterns, sourceMap);
+            }
+            // permissions: all groups are 'system' source.
+            if (Array.isArray(vr.permissions) && vr.permissions.length > 0) {
+                const permMap = new Map(available.permissions.map(n => [n, 'system']));
+                patternSelection.permissions = expandPatterns(vr.permissions, permMap);
+            }
+            // mcp: all declared servers are 'user' source.
+            if (Array.isArray(vr.mcp) && vr.mcp.length > 0) {
+                const mcpMap = new Map(available.mcp.map(n => [n, 'user']));
+                patternSelection.mcp = expandPatterns(vr.mcp, mcpMap);
+            }
+            // plugins: treat all as 'user' source for now.
+            if (Array.isArray(vr.plugins) && vr.plugins.length > 0) {
+                const pluginMap = new Map(available.plugins.map(n => [n, 'user']));
+                patternSelection.plugins = expandPatterns(vr.plugins, pluginMap);
+            }
+            // workflows: treat all as 'user' source.
+            if (Array.isArray(vr.workflows) && vr.workflows.length > 0) {
+                const workflowMap = new Map(available.workflows.map(n => [n, 'user']));
+                patternSelection.workflows = expandPatterns(vr.workflows, workflowMap);
+            }
+            // memory is not pattern-controlled (rulesPreset handles it) — always sync.
+            patternSelection.memory = 'all';
+            if (Object.keys(patternSelection).length > 0) {
+                selection = patternSelection;
+            }
+        }
+    }
     // Fast guard: skip the entire sync when no selection is active and nothing
     // has changed since the last full sync. Drops steady-state cost from ~16s
     // (unconditional file copies) to ~2ms (stat calls + manifest read).
     if (!selection && !options.force) {
         const manifest = loadSyncManifest(agent, version);
         if (manifest && !isSyncStale(manifest, available, agent, version, cwd)) {
-            return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [] };
+            return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
         }
     }
     // Helper: remove a path (symlink or real) if it exists
@@ -1500,9 +1609,6 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             syncedCommands.push(cmd);
         }
         result.commands = syncedCommands.length > 0;
-        if (syncedCommands.length > 0) {
-            recordVersionResources(agent, version, 'commands', syncedCommands);
-        }
     }
     // Sync skills (skip if agent natively reads ~/.agents/skills/)
     if (agentConfig.nativeAgentsSkillsDir) {
@@ -1531,9 +1637,6 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 syncedSkills.push(skill);
             }
             result.skills = syncedSkills.length > 0;
-            if (syncedSkills.length > 0) {
-                recordVersionResources(agent, version, 'skills', syncedSkills);
-            }
         }
     }
     // Sync hooks (if agent supports them at this version)
@@ -1599,9 +1702,6 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                     }
                 }
                 result.hooks = syncedHooks.length > 0;
-                if (syncedHooks.length > 0) {
-                    recordVersionResources(agent, version, 'hooks', syncedHooks);
-                }
                 // Register hooks into agent-native settings.json/hooks.json. Gemini
                 // shipped hooks in 0.26.0; gate already passed above so this is safe.
                 if (agent === 'claude' || agent === 'codex' || agent === 'gemini') {
@@ -1630,8 +1730,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             removePath(destFile);
             fs.writeFileSync(destFile, composed.content);
             result.memory.push(targetName);
-            // Track which preset materialized — surfaces in `agents rules list`.
-            recordVersionResources(agent, version, 'memory', [composed.preset]);
+            // rulesPreset is tracked separately via setActiveRulesPreset.
         }
         catch (err) {
             // No rules.yaml yet, or a typo'd preset name. Don't fail the whole sync —
@@ -1641,39 +1740,39 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     // Apply permissions (if agent supports them).
     // Groups live in ~/.agents/permissions/groups/. Optional recipes in
-    // ~/.agents/permissions/sets/<name>.yaml pick a subset via `includes:`.
-    // If AGENTS_PERMISSION_SET is set, we resolve that recipe and use its
+    // ~/.agents/permissions/presets/<name>.yaml pick a subset via `includes:`.
+    // If AGENTS_PERMISSION_PRESET is set, we resolve that recipe and use its
     // includes list as the group filter (intersected with groups on disk).
     const permissionGroups = discoverPermissionGroups();
     const allGroupNames = permissionGroups.map(g => g.name);
-    const activeSetName = getActivePermissionSetName();
-    let setFilteredGroups = null;
-    if (activeSetName) {
-        const recipe = readPermissionSetRecipe(activeSetName);
+    const activePresetName = getActivePermissionPresetName();
+    let presetFilteredGroups = null;
+    if (activePresetName) {
+        const recipe = readPermissionPresetRecipe(activePresetName);
         if (recipe) {
             const available = new Set(allGroupNames);
-            setFilteredGroups = recipe.includes.filter(g => available.has(g));
+            presetFilteredGroups = recipe.includes.filter(g => available.has(g));
         }
         else {
-            console.warn(`${PERMISSION_SET_ENV_VAR}=${activeSetName} but no recipe at ~/.agents/permissions/sets/${activeSetName}.yaml — falling back to all groups`);
+            console.warn(`${PERMISSION_PRESET_ENV_VAR}=${activePresetName} but no recipe at ~/.agents/permissions/presets/${activePresetName}.yaml — falling back to all groups`);
         }
     }
     let permsToSync;
     if (selection) {
         permsToSync = resolveSelection(selection.permissions, allGroupNames);
-        // If a set recipe is active, the recipe's includes list always wins —
+        // If a preset recipe is active, the recipe's includes list always wins —
         // even when the caller passed an explicit array via selection. Without
         // this intersection, `agents add`'s buildAutomaticSelection would pass
         // every group name discovered on disk (including 99-deny), bypassing
         // the sandbox filter.
-        if (setFilteredGroups) {
-            const filterSet = new Set(setFilteredGroups);
+        if (presetFilteredGroups) {
+            const filterSet = new Set(presetFilteredGroups);
             permsToSync = permsToSync.filter(g => filterSet.has(g));
         }
     }
     else {
         permsToSync = PERMISSIONS_CAPABLE_AGENTS.includes(agent)
-            ? (setFilteredGroups ?? allGroupNames)
+            ? (presetFilteredGroups ?? allGroupNames)
             : [];
     }
     if (permsToSync.length > 0 && PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {
@@ -1682,9 +1781,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         if (builtPerms.allow.length > 0 || (builtPerms.deny && builtPerms.deny.length > 0)) {
             const permResult = applyPermsToVersion(agent, builtPerms, versionHome, true);
             result.permissions = permResult.success;
-            if (permResult.success) {
-                recordVersionResources(agent, version, 'permissions', permsToSync);
-            }
+            // permissions patterns already written via ensureVersionResourcePatterns above.
         }
     }
     // Install MCP servers (if agent supports them)
@@ -1696,9 +1793,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (mcpToSync.length > 0 && MCP_CAPABLE_AGENTS.includes(agent)) {
         const mcpResult = installMcpServers(agent, version, versionHome, mcpToSync, { cwd });
         result.mcp = mcpResult.applied;
-        if (mcpResult.applied.length > 0) {
-            recordVersionResources(agent, version, 'mcp', mcpResult.applied);
-        }
+        // mcp patterns already written via ensureVersionResourcePatterns above.
     }
     // Sync subagents (claude and openclaw only)
     const subagentsToSync = selection
@@ -1731,9 +1826,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
             catch { /* resource sync failed for this item */ }
         }
-        if (result.subagents.length > 0) {
-            recordVersionResources(agent, version, 'subagents', result.subagents);
-        }
+        // subagent patterns already written via ensureVersionResourcePatterns above.
     }
     // Sync plugins (claude and openclaw)
     const pluginsToSync = selection
@@ -1754,9 +1847,27 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 result.plugins.push(name);
             }
         }
-        if (result.plugins.length > 0) {
-            recordVersionResources(agent, version, 'plugins', result.plugins);
+        // plugin patterns already written via ensureVersionResourcePatterns above.
+    }
+    // Sync workflows (claude only)
+    const workflowsToSync = selection
+        ? resolveSelection(selection.workflows, available.workflows)
+        : (WORKFLOW_CAPABLE_AGENTS.includes(agent) ? available.workflows : []);
+    if (workflowsToSync.length > 0 && WORKFLOW_CAPABLE_AGENTS.includes(agent)) {
+        const allWorkflows = listInstalledWorkflows();
+        for (const name of workflowsToSync) {
+            const workflow = allWorkflows.get(name);
+            if (!workflow)
+                continue;
+            try {
+                const syncResult = syncWorkflowToVersion(workflow.path, name, agent, versionHome);
+                if (syncResult.success) {
+                    result.workflows.push(name);
+                }
+            }
+            catch { /* resource sync failed for this item */ }
         }
+        // workflow patterns already written via ensureVersionResourcePatterns above.
     }
     // Write manifest after a successful full sync so the next launch can skip this work.
     if (!selection) {

package/dist/lib/workflows.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Workflow management library.
+ *
+ * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
+ * They optionally contain subagents/, skills/, and plugins/ subdirectories that
+ * are composed at runtime by `agents run <workflow>`.
+ */
+import type { AgentId } from './types.js';
+/** Agents that support running workflows via `agents run`. */
+export declare const WORKFLOW_CAPABLE_AGENTS: AgentId[];
+/** Parsed WORKFLOW.md frontmatter. */
+export interface WorkflowFrontmatter {
+    name: string;
+    description: string;
+    model?: string;
+    tools?: string[];
+    skills?: string[];
+    mcpServers?: string[];
+    allowedAgents?: string[];
+}
+/** A workflow found during repo discovery. */
+export interface DiscoveredWorkflow {
+    name: string;
+    path: string;
+    frontmatter: WorkflowFrontmatter;
+    subagentCount: number;
+}
+/** A workflow in central storage (~/.agents/workflows/ or ~/.agents-system/workflows/). */
+export interface InstalledWorkflow {
+    name: string;
+    path: string;
+    frontmatter: WorkflowFrontmatter;
+    subagentCount: number;
+}
+/** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
+export declare function parseWorkflowFrontmatter(workflowDir: string): WorkflowFrontmatter | null;
+/** Count subagent .md files in a workflow's subagents/ directory. */
+export declare function countWorkflowSubagents(workflowDir: string): number;
+/**
+ * Discover all workflow directories (those containing WORKFLOW.md) in a local path.
+ * Checks if the path itself is a workflow, then scans a top-level workflows/ subdirectory,
+ * then falls back to scanning all immediate subdirectories.
+ */
+export declare function discoverWorkflowsFromRepo(repoPath: string): DiscoveredWorkflow[];
+/**
+ * List all workflows in central storage.
+ * User layer (~/.agents/workflows/) wins over system (~/.agents-system/workflows/).
+ */
+export declare function listInstalledWorkflows(): Map<string, InstalledWorkflow>;
+/** Copy a workflow directory into user central storage (~/.agents/workflows/<name>/). */
+export declare function installWorkflowCentrally(sourcePath: string, name: string): {
+    success: boolean;
+    error?: string;
+};
+/** Move a workflow from user central storage to trash. */
+export declare function removeWorkflow(name: string): {
+    success: boolean;
+    error?: string;
+};
+/** List workflow names synced into a specific agent version home (at {versionHome}/workflows/). */
+export declare function listWorkflowsForAgent(_agent: AgentId, versionHome: string): string[];
+/** Copy a workflow directory into a version home at {versionHome}/workflows/<name>/. */
+export declare function syncWorkflowToVersion(workflowPath: string, name: string, _agent: AgentId, versionHome: string): {
+    success: boolean;
+    error?: string;
+};
+/** Remove a workflow from a specific agent version home. */
+export declare function removeWorkflowFromVersion(agent: AgentId, version: string, name: string): {
+    success: boolean;
+    error?: string;
+};
+/** Iterate all installed (agent, version) pairs that support workflows. */
+export declare function iterWorkflowsCapableVersions(filter?: {
+    agent?: AgentId;
+    version?: string;
+}): Array<{
+    agent: AgentId;
+    version: string;
+}>;