@phnx-labs/agents-cli 1.14.2 → 1.14.4

package/dist/lib/resources/subagents.js

@@ -0,0 +1,198 @@
+/**
+ * Subagents resource handler.
+ *
+ * Subagents are YAML files stored in subagents/ directories across layers.
+ * Format is the same for all agents. Resolution order: project > user > system.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getProjectAgentsDir, getUserSubagentsDir, getSystemSubagentsDir, getEnabledExtraRepos, } from '../state.js';
+/** Get layer directories for subagent resolution. */
+function getLayerDirs(cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const extraRepos = getEnabledExtraRepos();
+    return {
+        system: path.join(getSystemSubagentsDir()),
+        user: getUserSubagentsDir(),
+        project: projectDir ? path.join(projectDir, 'subagents') : null,
+        extra: extraRepos.map((e) => path.join(e.dir, 'subagents')),
+    };
+}
+/** Map source directory to layer name. */
+function dirToLayer(dir, dirs) {
+    if (dirs.project && dir.startsWith(dirs.project))
+        return 'project';
+    if (dir.startsWith(dirs.user))
+        return 'user';
+    return 'system';
+}
+/** Parse a subagent YAML file and return parsed item. */
+function parseSubagentYaml(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        return {
+            name: parsed.name || '',
+            description: parsed.description || '',
+            model: parsed.model,
+            color: parsed.color,
+            config: parsed.config,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract name from filename (removes .yaml/.yml extension). */
+function nameFromFile(filename) {
+    return filename.replace(/\.ya?ml$/, '');
+}
+export class SubagentsHandler {
+    kind = 'subagent';
+    /**
+     * List all subagents across layers, with higher layer winning on name conflict.
+     * Returns a union of all subagents, deduplicated by name.
+     */
+    listAll(_agent, cwd) {
+        const dirs = getLayerDirs(cwd);
+        const seen = new Set();
+        const results = [];
+        // Order: project > user > system > extra (extra comes last after system)
+        const layerDirs = [];
+        if (dirs.project && fs.existsSync(dirs.project)) {
+            layerDirs.push({ dir: dirs.project, layer: 'project' });
+        }
+        if (fs.existsSync(dirs.user)) {
+            layerDirs.push({ dir: dirs.user, layer: 'user' });
+        }
+        if (fs.existsSync(dirs.system)) {
+            layerDirs.push({ dir: dirs.system, layer: 'system' });
+        }
+        for (const extraDir of dirs.extra) {
+            if (fs.existsSync(extraDir)) {
+                layerDirs.push({ dir: extraDir, layer: 'system' });
+            }
+        }
+        for (const { dir, layer } of layerDirs) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                    continue;
+                if (entry.name.startsWith('.'))
+                    continue;
+                const name = nameFromFile(entry.name);
+                if (seen.has(name))
+                    continue;
+                const filePath = path.join(dir, entry.name);
+                const item = parseSubagentYaml(filePath);
+                if (!item)
+                    continue;
+                seen.add(name);
+                results.push({
+                    name,
+                    item,
+                    layer,
+                    path: filePath,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Resolve a single subagent by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(_agent, name, cwd) {
+        const dirs = getLayerDirs(cwd);
+        // Order: project > user > system > extra
+        const searchDirs = [];
+        if (dirs.project) {
+            searchDirs.push({ dir: dirs.project, layer: 'project' });
+        }
+        searchDirs.push({ dir: dirs.user, layer: 'user' });
+        searchDirs.push({ dir: dirs.system, layer: 'system' });
+        for (const extraDir of dirs.extra) {
+            searchDirs.push({ dir: extraDir, layer: 'system' });
+        }
+        for (const { dir, layer } of searchDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            // Try .yaml first, then .yml
+            for (const ext of ['.yaml', '.yml']) {
+                const filePath = path.join(dir, name + ext);
+                if (fs.existsSync(filePath)) {
+                    const item = parseSubagentYaml(filePath);
+                    if (item) {
+                        return {
+                            name,
+                            item,
+                            layer,
+                            path: filePath,
+                        };
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Sync resolved subagents to the agent's version home directory.
+     * Copies YAML files to the target directory.
+     */
+    sync(agent, versionHome, cwd) {
+        const targetDir = path.join(versionHome, this.targetDir(agent));
+        // Ensure target directory exists
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        // Clear existing subagents in target
+        try {
+            const existing = fs.readdirSync(targetDir);
+            for (const file of existing) {
+                if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                    fs.unlinkSync(path.join(targetDir, file));
+                }
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        // Copy all resolved subagents
+        const resolved = this.listAll(agent, cwd);
+        for (const { name, path: sourcePath } of resolved) {
+            const ext = sourcePath.endsWith('.yml') ? '.yml' : '.yaml';
+            const targetPath = path.join(targetDir, name + ext);
+            fs.copyFileSync(sourcePath, targetPath);
+        }
+    }
+    /**
+     * Get the file format this resource uses for a given agent.
+     * Subagents always use YAML format.
+     */
+    format(_agent) {
+        return 'yaml';
+    }
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(_agent) {
+        return 'subagents';
+    }
+}
+/** Singleton instance of the SubagentsHandler. */
+export const subagentsHandler = new SubagentsHandler();

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

@@ -0,0 +1,82 @@
+/**
+ * Unified resource system types.
+ *
+ * Resources merge from three layers: system → user → project
+ * - 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';
+export type Layer = 'system' | 'user' | 'project';
+export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent';
+/** A resolved resource with its origin layer. */
+export interface ResolvedItem<T> {
+    name: string;
+    item: T;
+    layer: Layer;
+    path: string;
+}
+/**
+ * Resource handler interface.
+ *
+ * Each resource type (commands, hooks, skills, etc.) implements this interface
+ * to provide consistent list/resolve/sync behavior across all agent types.
+ */
+export interface ResourceHandler<T> {
+    readonly kind: ResourceKind;
+    /**
+     * List all resources across layers, with higher layer winning on name conflict.
+     * Returns a union of all resources, deduplicated by name.
+     */
+    listAll(agent: AgentId, cwd?: string): ResolvedItem<T>[];
+    /**
+     * Resolve a single resource by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(agent: AgentId, name: string, cwd?: string): ResolvedItem<T> | null;
+    /**
+     * Sync resolved resources to the agent's version home directory.
+     * Copies/transforms resources as needed for the agent's expected format.
+     */
+    sync(agent: AgentId, versionHome: string, cwd?: string): void;
+    /**
+     * Get the file format this resource uses for a given agent.
+     */
+    format(agent: AgentId): 'md' | 'toml' | 'json' | 'yaml';
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(agent: AgentId): string;
+    /**
+     * For resources that modify config files (MCP, permissions),
+     * return the config file path. Returns null if not applicable.
+     */
+    configPath?(agent: AgentId, versionHome: string): string | null;
+    /**
+     * Compute content hash for a resource item (for change detection).
+     * Used by diff() to detect modifications without full content comparison.
+     * Optional — handlers that don't implement this fall back to full sync.
+     */
+    hash?(item: T): string;
+    /**
+     * Compare source layers vs synced target to detect drift.
+     * Returns list of resources that differ (added, modified, removed).
+     * Enables incremental sync and "X resources out of sync" status.
+     * Optional — handlers that don't implement this always report "unknown".
+     */
+    diff?(agent: AgentId, versionHome: string, cwd?: string): ResourceDiff[];
+}
+/** Result of comparing source vs target for a single resource. */
+export interface ResourceDiff {
+    name: string;
+    status: 'added' | 'modified' | 'removed';
+    sourceLayer: Layer | null;
+    sourceHash: string | null;
+    targetHash: string | null;
+}
+/** Helper to get layer directories for resource resolution. */
+export interface LayerDirs {
+    system: string;
+    user: string;
+    project: string | null;
+    extra: string[];
+}

package/dist/lib/resources/types.js

@@ -0,0 +1,8 @@
+/**
+ * Unified resource system types.
+ *
+ * Resources merge from three layers: system → user → project
+ * - Union: All resources from all layers are combined
+ * - Override on name conflict: Higher layer wins (project > user > system)
+ */
+export {};

package/dist/lib/resources.js

@@ -8,7 +8,7 @@ import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope } from './commands.js';
 import { listInstalledSkillsWithScope } from './skills.js';
 import { listInstalledHooksWithScope } from './hooks.js';
-import { listInstalledInstructionsWithScope } from './memory.js';
+import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';

package/dist/lib/rotate.d.ts

@@ -35,7 +35,14 @@ export declare const RUN_STRATEGIES: RunStrategy[];
 export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   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).
+ */
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;

package/dist/lib/rotate.js

@@ -11,6 +11,12 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getAgentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
+const ROTATE_DIR = 'helpers/rotate';
+function getRotateDir() {
+    const dir = path.join(getAgentsDir(), ROTATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 export const RUN_STRATEGIES = ['pinned', 'available', 'balanced'];
 /**
  * Return a run strategy when the input is valid, otherwise null.
@@ -47,11 +53,18 @@ export function getProjectRunStrategy(agent, startPath) {
     }
     return null;
 }
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   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).
+ */
 export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
     return getProjectRunStrategy(agent, startPath)
         ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
-        ?? 'pinned';
+        ?? 'available';
 }
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export function setGlobalRunStrategy(agent, strategy) {
@@ -279,7 +292,7 @@ export async function selectAvailableVersion(agent, preferredVersion) {
  * a torn write just means the next reader sees a stale timestamp (harmless).
  */
 function recordRotationPick(agent, version) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         fs.writeFileSync(stampPath, JSON.stringify({ version, ts: Date.now() }), 'utf-8');
     }
@@ -290,7 +303,7 @@ function recordRotationPick(agent, version) {
  * or stamp is older than 60 seconds (stale).
  */
 function readRotationStamp(agent) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         const raw = JSON.parse(fs.readFileSync(stampPath, 'utf-8'));
         if (Date.now() - raw.ts < 60_000)

package/dist/lib/rules/compile.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Rules file compilation -- resolving @-imports into a single flat file.
+ *
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
+ * need a pre-compiled rules file with all imports inlined. This module
+ * handles that expansion for both user-scope (writes into version home) and
+ * project-scope (writes into the workspace).
+ */
+import type { AgentId } from '../types.js';
+import { type RulesLayer } from './compose.js';
+/** Sidecar manifest recording source file hashes for staleness detection. */
+export interface CompileManifest {
+    compiledAt: string;
+    sources: {
+        path: string;
+        sha256: string;
+        mtime?: number;
+        size?: number;
+    }[];
+}
+/** Result of resolving @-imports in a rules file. */
+export interface ResolveResult {
+    /** Fully-inlined content. */
+    content: string;
+    /** Absolute paths of every file read during resolution (including the root). */
+    sources: string[];
+}
+/**
+ * Expand all `@path/to/file` imports in `content`, recursively up to
+ * MAX_DEPTH. Imports inside fenced code blocks and inline code spans are
+ * left alone, matching Claude Code's parser. Missing files are left as-is
+ * (silent skip), matching the documented behavior.
+ *
+ * Relative paths resolve against `baseDir`; absolute and tilde-prefixed
+ * paths resolve against the filesystem root / home directory.
+ */
+export declare function resolveImports(content: string, baseDir: string): ResolveResult;
+/** True if the agent's native runtime resolves `@path` imports in its rules file. */
+export declare function supportsRulesImports(agentId: AgentId): boolean;
+/**
+ * Fast staleness check. Returns true when:
+ *  - the compiled file or its manifest is missing
+ *  - any recorded source file is missing
+ *  - any recorded source's sha256 no longer matches
+ *
+ * For agents that support @-imports natively, always returns false — there's
+ * nothing to compile.
+ */
+export declare function isRulesStale(agentId: AgentId, version: string): boolean;
+/**
+ * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
+ * write the result into the version home, alongside a sidecar manifest that
+ * records source file hashes for staleness detection.
+ *
+ * Agents that natively resolve @-imports are skipped (no-op) — their sync
+ * uses the standard copyFileSync path in `syncResourcesToVersion`.
+ */
+export declare function compileRulesForAgent(agentId: AgentId, version: string): {
+    compiled: boolean;
+    compiledPath: string;
+    sources: number;
+};
+/**
+ * Recompile rules if stale. Safe to call on every agent invocation — the
+ * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
+ * true if a recompile happened, false otherwise.
+ */
+export declare function ensureRulesFresh(agentId: AgentId, version: string): boolean;
+export interface ProjectCompileResult {
+    /** True when cwd/AGENTS.md was newly written or rewritten. */
+    compiled: boolean;
+    /** Absolute path to cwd/AGENTS.md. Empty when no project rules dir was present. */
+    agentsPath: string;
+    /** Per-agent instruction filenames symlinked (or copied) to AGENTS.md. */
+    symlinks: string[];
+    /** Number of source files inlined (root + recursive @-imports). */
+    sources: number;
+    /** Per-agent files we left alone because the user wrote/owns them. */
+    skippedClobber: string[];
+}
+/**
+ * Compile project-scope rules into a workspace's root memory files so each
+ * agent's native loader picks them up.
+ *
+ * Composes rules from all available layers (project > user > extras > system)
+ * with project highest priority — so a project's `subrules/` and `rules.yaml`
+ * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
+ * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
+ * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
+ * cwd. The agent's own loader merges this project-level file with its
+ * user-level rules (in version home) at runtime.
+ *
+ * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
+ * authored it — leave it alone and report via `skippedClobber`. Same for any
+ * pre-existing per-agent file or symlink that doesn't already point at
+ * AGENTS.md.
+ *
+ * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
+ * calls — content equality short-circuits the write.
+ */
+export declare function compileRulesForProject(cwd: string, opts?: {
+    preset?: string;
+    layers?: RulesLayer[];
+}): ProjectCompileResult;