@phnx-labs/agents-cli 1.20.4 → 1.20.5

package/dist/lib/refresh.js

@@ -0,0 +1,315 @@
+/**
+ * Materialization helpers — install manifest CLIs, register MCP servers,
+ * sync resources into installed version homes, register hooks, add shims to
+ * PATH, prompt for missing default versions, install declared host-CLIs.
+ *
+ * Used by `agents repo refresh` (user-facing) and any other caller that needs
+ * to re-derive local state from declared configuration. Does NOT do any git
+ * operations — that lives in `agents repo pull`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { select, confirm } from '@inquirer/prompts';
+import { capableAgents } from './capabilities.js';
+import { AGENTS, ALL_AGENT_IDS, getAllCliStates, registerMcpToTargets, agentLabel, } from './agents.js';
+import { readManifest, MANIFEST_FILENAME } from './manifest.js';
+import { getUserAgentsDir } from './state.js';
+import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
+import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
+import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './shims.js';
+import { parseHookManifest, registerHooksToSettings } from './hooks.js';
+import { isPromptCancelled } from '../commands/utils.js';
+/**
+ * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
+ * The new layout is `~/.agents/.system/promptcuts.yaml` at the repo root — the
+ * hook reads from a fixed path so it survives version upgrades. If the root
+ * file doesn't exist yet but an agent-scoped one does, hoist the first one found.
+ */
+function migratePromptcutsToRoot(agentsDir) {
+    const rootPath = path.join(agentsDir, 'promptcuts.yaml');
+    if (fs.existsSync(rootPath))
+        return;
+    const agentDirs = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+    for (const dir of agentDirs) {
+        const legacyPath = path.join(agentsDir, dir, 'promptcuts.yaml');
+        if (fs.existsSync(legacyPath)) {
+            try {
+                fs.renameSync(legacyPath, rootPath);
+                console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
+                return;
+            }
+            catch {
+                // Best-effort migration; hook still works if the user moves it manually.
+            }
+        }
+    }
+}
+/**
+ * Re-materialize local state from declared configuration: install CLI versions,
+ * register MCP servers, sync resources to version homes, register hooks, add
+ * shims to PATH, prompt for missing defaults, install declared host-CLIs.
+ *
+ * Idempotent — safe to run repeatedly. No network operations.
+ */
+export async function refresh(options = {}) {
+    const { agentFilter, skipPrompts = false, skipClis = false } = options;
+    const agentsDir = getUserAgentsDir();
+    migratePromptcutsToRoot(agentsDir);
+    const manifest = readManifest(agentsDir);
+    if (!manifest) {
+        console.log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
+    }
+    // 1. Install/upgrade CLI versions from agents.yaml
+    if (!skipClis && manifest?.agents) {
+        console.log(chalk.bold('\nCLI Versions:\n'));
+        const cliAgents = Object.keys(manifest.agents);
+        for (const agentId of cliAgents) {
+            if (agentFilter && agentId !== agentFilter)
+                continue;
+            const agent = AGENTS[agentId];
+            if (!agent)
+                continue;
+            const cliSpinner = ora(`Checking ${agentLabel(agent.id)}...`).start();
+            const versions = listInstalledVersions(agentId);
+            const targetVersion = manifest.agents[agentId] || 'latest';
+            const result = await installVersion(agentId, targetVersion, (msg) => { cliSpinner.text = msg; });
+            if (result.success) {
+                const isNew = versions.length === 0;
+                if (isNew) {
+                    cliSpinner.succeed(`Installed ${agentLabel(agent.id)}@${result.installedVersion}`);
+                }
+                else {
+                    cliSpinner.succeed(`${agentLabel(agent.id)}@${result.installedVersion}`);
+                }
+                ensureShimCurrent(agentId);
+            }
+            else {
+                cliSpinner.warn(`${agentLabel(agent.id)}: ${result.error}`);
+            }
+        }
+    }
+    // 2. Register MCP servers
+    if (manifest?.mcp && Object.keys(manifest.mcp).length > 0) {
+        console.log(chalk.bold('\nMCP Servers:\n'));
+        for (const [name, config] of Object.entries(manifest.mcp)) {
+            if (!config.command || config.transport === 'http')
+                continue;
+            const scopedAgents = (config.agents ? [...config.agents] : [...capableAgents('mcp')]).filter((id) => !agentFilter || id === agentFilter);
+            const scopedVersions = config.agentVersions
+                ? Object.fromEntries(Object.entries(config.agentVersions).filter(([agentId]) => !agentFilter || agentId === agentFilter))
+                : undefined;
+            const targets = resolveConfiguredAgentTargets(scopedAgents, scopedVersions, capableAgents('mcp'));
+            const results = await registerMcpToTargets(targets, name, config.command, config.scope || 'user', config.transport || 'stdio');
+            for (const result of results) {
+                if (result.success) {
+                    const label = result.version
+                        ? `${agentLabel(result.agentId)}@${result.version}`
+                        : agentLabel(result.agentId);
+                    console.log(`  ${chalk.green('+')} ${name} -> ${label}`);
+                }
+            }
+        }
+    }
+    // 3. Sync resources to default version homes
+    const cliStates = await getAllCliStates();
+    const agentsToSync = agentFilter ? [agentFilter] : ALL_AGENT_IDS;
+    const available = getAvailableResources();
+    for (const agentId of agentsToSync) {
+        if (!cliStates[agentId]?.installed && listInstalledVersions(agentId).length === 0)
+            continue;
+        const defaultVer = getGlobalDefault(agentId);
+        if (!defaultVer)
+            continue;
+        const actuallySynced = getActuallySyncedResources(agentId, defaultVer);
+        const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
+        const hasAnySynced = actuallySynced.commands.length > 0 ||
+            actuallySynced.skills.length > 0 ||
+            actuallySynced.hooks.length > 0 ||
+            actuallySynced.memory.length > 0 ||
+            actuallySynced.mcp.length > 0 ||
+            actuallySynced.permissions.length > 0 ||
+            actuallySynced.plugins.length > 0;
+        try {
+            let selection;
+            if (skipPrompts) {
+                if (!hasAnySynced || hasNewResources(newResources, agentId)) {
+                    selection = {
+                        commands: 'all', skills: 'all', hooks: 'all', memory: 'all',
+                        mcp: 'all', permissions: 'all', subagents: 'all', plugins: 'all',
+                    };
+                }
+            }
+            else if (!hasAnySynced) {
+                console.log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
+                const userSelection = await promptResourceSelection(agentId);
+                if (userSelection)
+                    selection = userSelection;
+            }
+            else if (hasNewResources(newResources, agentId, defaultVer)) {
+                console.log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
+                const userSelection = await promptNewResourceSelection(agentId, newResources, defaultVer);
+                if (userSelection)
+                    selection = userSelection;
+            }
+            if (selection && Object.keys(selection).length > 0) {
+                const syncResult = syncResourcesToVersion(agentId, defaultVer, selection);
+                const synced = [];
+                if (syncResult.commands)
+                    synced.push('commands');
+                if (syncResult.skills)
+                    synced.push('skills');
+                if (syncResult.hooks)
+                    synced.push('hooks');
+                if (syncResult.memory.length > 0)
+                    synced.push('memory');
+                if (syncResult.permissions)
+                    synced.push('permissions');
+                if (syncResult.mcp.length > 0)
+                    synced.push('mcp');
+                if (syncResult.plugins.length > 0)
+                    synced.push('plugins');
+                if (synced.length > 0) {
+                    console.log(chalk.green(`  Synced: ${synced.join(', ')}`));
+                }
+            }
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('Skipped resource selection'));
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    // 4. Register hooks as lifecycle events
+    const hookManifest = parseHookManifest();
+    if (Object.keys(hookManifest).length > 0) {
+        let hookRegistered = 0;
+        const hookAgents = new Set(capableAgents('hooks'));
+        for (const agentId of agentsToSync) {
+            if (!hookAgents.has(agentId))
+                continue;
+            const versions = listInstalledVersions(agentId);
+            const defaultVer = getGlobalDefault(agentId);
+            const targetVersions = defaultVer ? [defaultVer] : versions.slice(-1);
+            for (const ver of targetVersions) {
+                const home = getVersionHomePath(agentId, ver);
+                const result = registerHooksToSettings(agentId, home, hookManifest);
+                hookRegistered += result.registered.length;
+                for (const error of result.errors) {
+                    console.log(chalk.yellow(`  Hook warning: ${error}`));
+                }
+            }
+        }
+        if (hookRegistered > 0) {
+            console.log(chalk.green(`\nRegistered ${hookRegistered} hook lifecycle event(s)`));
+        }
+    }
+    // 5. Auto-add shims to PATH
+    if (!isShimsInPath()) {
+        const pathResult = addShimsToPath();
+        if (pathResult.success && !pathResult.alreadyPresent) {
+            console.log(chalk.green(`\nAdded shims to ~/${pathResult.rcFile}`));
+            console.log(chalk.gray('Restart your shell or run: source ~/' + pathResult.rcFile));
+        }
+        else if (!pathResult.success) {
+            console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));
+            console.log(chalk.gray(getPathSetupInstructions()));
+        }
+    }
+    // 6. Prompt for missing default versions
+    if (!skipPrompts) {
+        const agentsNeedingDefault = [];
+        for (const agentId of agentsToSync) {
+            const versions = listInstalledVersions(agentId);
+            if (versions.length > 0 && !getGlobalDefault(agentId)) {
+                agentsNeedingDefault.push(agentId);
+            }
+        }
+        const selectedVersions = [];
+        for (const agentId of agentsNeedingDefault) {
+            const versions = listInstalledVersions(agentId);
+            const agent = AGENTS[agentId];
+            const shouldSwitch = await select({
+                message: `${agentLabel(agent.id)} has no default version. Set one now?`,
+                choices: [
+                    { name: 'Yes, pick a version', value: 'pick' },
+                    { name: 'Skip for now', value: 'skip' },
+                ],
+            });
+            if (shouldSwitch === 'pick') {
+                const selectedVersion = await select({
+                    message: `Select ${agentLabel(agent.id)} version:`,
+                    choices: versions.map((v) => ({ name: v, value: v })),
+                });
+                selectedVersions.push({ agentId, version: selectedVersion });
+            }
+        }
+        for (const { agentId, version } of selectedVersions) {
+            const agent = AGENTS[agentId];
+            setGlobalDefault(agentId, version);
+            const symlinkResult = await switchConfigSymlink(agentId, version);
+            if (!symlinkResult.success) {
+                console.log(chalk.yellow(`Warning: ${symlinkResult.error}`));
+            }
+            else if (symlinkResult.backupPath) {
+                console.log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
+            }
+            switchHomeFileSymlinks(agentId, version);
+            console.log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
+        }
+    }
+    // 7. Install declared host-CLIs
+    try {
+        const { statuses, errors } = listCliStatus(process.cwd());
+        for (const err of errors) {
+            console.log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
+        }
+        const missing = statuses.filter((s) => !s.installed);
+        if (missing.length > 0) {
+            console.log(chalk.bold('\nDeclared CLIs missing from this host:'));
+            for (const s of missing) {
+                const method = selectInstallMethod(s.manifest);
+                const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+                console.log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+            }
+            console.log('');
+            if (!skipPrompts) {
+                const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
+                if (proceed) {
+                    for (const s of missing) {
+                        console.log(chalk.bold(`\n→ ${s.manifest.name}`));
+                        const result = installCli(s.manifest);
+                        if (result.error) {
+                            console.log(chalk.red(`  ${result.error}`));
+                            continue;
+                        }
+                        if (result.installed) {
+                            console.log(chalk.green(`  installed`));
+                            if (s.manifest.postInstall) {
+                                console.log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                            }
+                        }
+                        else {
+                            console.log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
+                        }
+                    }
+                }
+                else {
+                    console.log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                }
+            }
+            else {
+                console.log(chalk.gray(`Run 'agents cli install' to install them.`));
+            }
+        }
+    }
+    catch (err) {
+        if (!isPromptCancelled(err)) {
+            console.log(chalk.yellow(`CLI install skipped: ${err.message}`));
+        }
+    }
+}

package/dist/lib/resource-patterns.d.ts

@@ -2,7 +2,7 @@
  * Resource selection patterns for agents.yaml versions: entries.
  *
  * Pattern syntax: [!]source:name
- *   "system:*"     — all resources from ~/.agents-system/
+ *   "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

package/dist/lib/resource-patterns.js

@@ -2,7 +2,7 @@
  * Resource selection patterns for agents.yaml versions: entries.
  *
  * Pattern syntax: [!]source:name
- *   "system:*"     — all resources from ~/.agents-system/
+ *   "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

package/dist/lib/resources/commands.js

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { AGENTS } from '../agents.js';
+import { AGENTS, agentConfigDirName } from '../agents.js';
 import { markdownToToml } from '../convert.js';
 /**
  * Get the commands directory for a given layer root.
@@ -164,7 +164,7 @@ export class CommandsHandler {
     sync(agent, versionHome, cwd) {
         const agentConfig = AGENTS[agent];
         const targetFormat = this.format(agent);
-        const targetDir = path.join(versionHome, `.${agent}`, this.targetDir(agent));
+        const targetDir = path.join(versionHome, agentConfigDirName(agent), this.targetDir(agent));
         // Ensure target directory exists
         fs.mkdirSync(targetDir, { recursive: true });
         // Get all resolved commands

package/dist/lib/resources/hooks.d.ts

@@ -2,7 +2,7 @@
  * HooksHandler - ResourceHandler implementation for hooks.
  *
  * Hook declarations live in:
- *   - System: ~/.agents-system/hooks.yaml (npm-shipped defaults)
+ *   - System: ~/.agents/.system/hooks.yaml (npm-shipped defaults)
  *   - User:   `hooks:` section of ~/.agents/agents.yaml
  *   - Project: <project>/.agents/hooks.yaml
  *

package/dist/lib/resources/hooks.js

@@ -2,7 +2,7 @@
  * HooksHandler - ResourceHandler implementation for hooks.
  *
  * Hook declarations live in:
- *   - System: ~/.agents-system/hooks.yaml (npm-shipped defaults)
+ *   - System: ~/.agents/.system/hooks.yaml (npm-shipped defaults)
  *   - User:   `hooks:` section of ~/.agents/agents.yaml
  *   - Project: <project>/.agents/hooks.yaml
  *

package/dist/lib/resources/mcp.d.ts

@@ -2,7 +2,7 @@
  * MCP resource handler - lists, resolves, and syncs MCP server configs across layers.
  *
  * MCP servers are stored as YAML files in mcp/ directories:
- *   ~/.agents-system/mcp/   (system)
+ *   ~/.agents/.system/mcp/   (system)
  *   ~/.agents/mcp/          (user)
  *   .agents/mcp/            (project)
  *

package/dist/lib/resources/mcp.js

@@ -2,7 +2,7 @@
  * MCP resource handler - lists, resolves, and syncs MCP server configs across layers.
  *
  * MCP servers are stored as YAML files in mcp/ directories:
- *   ~/.agents-system/mcp/   (system)
+ *   ~/.agents/.system/mcp/   (system)
  *   ~/.agents/mcp/          (user)
  *   .agents/mcp/            (project)
  *
@@ -13,9 +13,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
+import { capableAgents } from '../capabilities.js';
 import { getSystemMcpDir, getUserMcpDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-/** Agents from resources/types.ts that support MCP. */
-const MCP_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode', 'openclaw', 'antigravity', 'grok'];
 /**
  * Parse an MCP YAML file into an McpItem.
  */
@@ -414,7 +413,7 @@ function syncToOpenClawConfig(configPath, items) {
 export const McpHandler = {
     kind: 'mcp',
     listAll(agent, cwd) {
-        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+        if (!capableAgents('mcp').includes(agent)) {
             return [];
         }
         const results = new Map();
@@ -435,7 +434,7 @@ export const McpHandler = {
         return Array.from(results.values());
     },
     resolve(agent, name, cwd) {
-        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+        if (!capableAgents('mcp').includes(agent)) {
             return null;
         }
         const layerDirs = getLayerDirs(cwd);
@@ -469,7 +468,7 @@ export const McpHandler = {
         return null;
     },
     sync(agent, versionHome, cwd) {
-        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+        if (!capableAgents('mcp').includes(agent)) {
             return;
         }
         const items = this.listAll(agent, cwd);

package/dist/lib/resources/permissions.js

@@ -9,7 +9,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getSystemAgentsDir, getUserAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { parsePermissionSet, applyPermissionsToVersion, mergePermissionSets, PERMISSIONS_CAPABLE_AGENTS, } from '../permissions.js';
+import { parsePermissionSet, applyPermissionsToVersion, mergePermissionSets, } from '../permissions.js';
+import { isCapable } from '../capabilities.js';
 /**
  * Get the permissions directory for a given layer root.
  */
@@ -66,6 +67,8 @@ function getAgentConfigPath(agent, versionHome) {
             return path.join(versionHome, '.codex', 'config.toml');
         case 'opencode':
             return path.join(versionHome, '.opencode', 'opencode.jsonc');
+        case 'kimi':
+            return path.join(versionHome, '.kimi-code', 'config.toml');
         default:
             return null;
     }
@@ -143,7 +146,7 @@ export const PermissionsHandler = {
      */
     sync(agent, versionHome, cwd) {
         // Only sync to agents that support permissions
-        if (!PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {
+        if (!isCapable(agent, 'allowlist')) {
             return;
         }
         const resolved = this.listAll(agent, cwd);

package/dist/lib/resources/rules.js

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getSystemRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+import { agentConfigDirName } from '../agents.js';
 const SUBRULES_DIR = 'subrules';
 const SUBRULES_README = 'README.md';
 /**
@@ -131,7 +132,7 @@ export const RulesHandler = {
         // Rules sync is handled by the compose module and syncResourcesToVersion.
         // This method ensures the agent config directory exists.
         // The actual composition and write happens in versions.ts via composeRulesFromState().
-        const targetDir = path.join(versionHome, `.${agent}`);
+        const targetDir = path.join(versionHome, agentConfigDirName(agent));
         if (!fs.existsSync(targetDir)) {
             fs.mkdirSync(targetDir, { recursive: true });
         }
@@ -141,6 +142,6 @@ export const RulesHandler = {
     },
     targetDir(agent) {
         // Rules don't have a target subdirectory - they're written to the instructions file
-        return `.${agent}`;
+        return agentConfigDirName(agent);
     },
 };

package/dist/lib/resources/skills.js

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getSystemSkillsDir, getUserSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+import { agentConfigDirName } from '../agents.js';
 /** Default provider uses the real state module. */
 const defaultProvider = {
     getSystemSkillsDir,
@@ -200,7 +201,7 @@ export function createSkillsHandler(provider = defaultProvider) {
             return null;
         },
         sync(agent, versionHome, cwd) {
-            const targetDir = path.join(versionHome, `.${agent}`, 'skills');
+            const targetDir = path.join(versionHome, agentConfigDirName(agent), 'skills');
             // Ensure target directory exists
             if (!fs.existsSync(targetDir)) {
                 fs.mkdirSync(targetDir, { recursive: true });
@@ -230,7 +231,7 @@ export function createSkillsHandler(provider = defaultProvider) {
             return 'md';
         },
         targetDir(agent) {
-            return `.${agent}/skills`;
+            return `${agentConfigDirName(agent)}/skills`;
         },
     };
 }

package/dist/lib/resources/types.d.ts

@@ -5,7 +5,7 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'antigravity' | 'grok';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'antigravity' | 'grok' | 'kimi';
 export type Layer = 'system' | 'user' | 'project';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow';
 /** A resolved resource with its origin layer. */

package/dist/lib/resources.js

@@ -12,7 +12,7 @@ import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { WorkflowsHandler } from './resources/workflows.js';
-import { WORKFLOW_CAPABLE_AGENTS } from './workflows.js';
+import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
@@ -163,7 +163,7 @@ export function getAgentResources(agentId, options = {}) {
     }
     // Workflows (claude only)
     const workflows = [];
-    if (WORKFLOW_CAPABLE_AGENTS.includes(agentId)) {
+    if (isCapable(agentId, 'workflows')) {
         for (const w of WorkflowsHandler.listAll(agentId, cwd)) {
             workflows.push({ name: w.name, path: w.path, scope: w.layer === 'project' ? 'project' : 'user' });
         }

package/dist/lib/rotate.d.ts

@@ -38,7 +38,7 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 /**
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
- *   2. ~/.agents-system/agents.yaml
+ *   2. ~/.agents/.system/agents.yaml
  *   3. default: `available` (use the pinned default version when healthy,
  *      otherwise fall through to a healthy account so a single rate-limited
  *      account doesn't block the run).

package/dist/lib/rotate.js

@@ -55,7 +55,7 @@ export function getProjectRunStrategy(agent, startPath) {
 /**
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
- *   2. ~/.agents-system/agents.yaml
+ *   2. ~/.agents/.system/agents.yaml
  *   3. default: `available` (use the pinned default version when healthy,
  *      otherwise fall through to a healthy account so a single rate-limited
  *      account doesn't block the run).

package/dist/lib/routines.d.ts

@@ -32,6 +32,7 @@ export interface JobConfig {
     config?: Record<string, unknown>;
     version?: string;
     runOnce?: boolean;
+    endAt?: string;
 }
 /** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
@@ -45,10 +46,19 @@ export interface RunMeta {
     completedAt: string | null;
     exitCode: number | null;
 }
-/** List all job configs from ~/.agents/routines/. */
-export declare function listJobs(): JobConfig[];
-/** Read a single job config by name. Returns null if not found. */
-export declare function readJob(name: string): JobConfig | null;
+/**
+ * List all job configs, scanning project > user routine dirs.
+ * Project routines (`<project>/.agents/routines/`) shadow user routines of the
+ * same name. Project discovery is opt-in via `cwd`; the daemon (which calls
+ * `listJobs()` with no argument) only sees user routines.
+ */
+export declare function listJobs(cwd?: string): JobConfig[];
+/**
+ * Read a single job config by name, checking project > user.
+ * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
+ * only resolve user routines.
+ */
+export declare function readJob(name: string, cwd?: string): JobConfig | null;
 /** Write a job config to disk, omitting fields that match defaults. */
 export declare function writeJob(config: JobConfig): void;
 /** Delete a job config file by name. Returns true if the file existed. */
@@ -57,6 +67,8 @@ export declare function deleteJob(name: string): boolean;
 export declare function setJobEnabled(name: string, enabled: boolean): void;
 /** Validate a partial job config, returning a list of human-readable errors. */
 export declare function validateJob(config: Partial<JobConfig>): string[];
+/** True when a job's endAt has already elapsed. False when endAt is unset or in the future. */
+export declare function isPastEndAt(config: Pick<JobConfig, 'endAt'>, now?: Date): boolean;
 /** Expand built-in and user-defined template variables in a job's prompt string. */
 export declare function resolveJobPrompt(config: JobConfig): string;
 /** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.