@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/subagents.js

@@ -1,7 +1,16 @@
+/**
+ * Subagent management -- discovery, installation, and format conversion.
+ *
+ * Subagents are named agent definitions in ~/.agents/subagents/, each a directory
+ * with an agent.md file (frontmatter + instructions). This module discovers them,
+ * transforms them into agent-native formats (Claude .mdc, OpenClaw YAML),
+ * and syncs them into version homes.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSubagentsDir } from './state.js';
+import { getSubagentsDir, getUserSubagentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 /**
  * Parse AGENT.md frontmatter to extract subagent metadata
  */
@@ -92,30 +101,35 @@ export function discoverSubagentsFromRepo(repoPath) {
  * List installed subagents from ~/.agents/subagents/
  */
 export function listInstalledSubagents() {
+    const seen = new Set();
     const subagents = [];
-    const subagentsDir = getSubagentsDir();
-    if (!fs.existsSync(subagentsDir)) {
-        return subagents;
-    }
-    for (const dir of fs.readdirSync(subagentsDir)) {
-        const dirPath = path.join(subagentsDir, dir);
-        if (!fs.statSync(dirPath).isDirectory())
+    // User dir first (wins on name collision), then system
+    for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
+        if (!fs.existsSync(subagentsDir))
             continue;
-        const agentMd = path.join(dirPath, 'AGENT.md');
-        if (!fs.existsSync(agentMd))
-            continue;
-        const frontmatter = parseSubagentFrontmatter(agentMd);
-        if (!frontmatter)
-            continue;
-        const files = fs.readdirSync(dirPath)
-            .filter(f => f.endsWith('.md'))
-            .sort();
-        subagents.push({
-            name: dir,
-            path: dirPath,
-            files,
-            frontmatter,
-        });
+        for (const dir of fs.readdirSync(subagentsDir)) {
+            const dirPath = path.join(subagentsDir, dir);
+            if (!fs.statSync(dirPath).isDirectory())
+                continue;
+            const agentMd = path.join(dirPath, 'AGENT.md');
+            if (!fs.existsSync(agentMd))
+                continue;
+            const frontmatter = parseSubagentFrontmatter(agentMd);
+            if (!frontmatter)
+                continue;
+            if (seen.has(dir))
+                continue;
+            seen.add(dir);
+            const files = fs.readdirSync(dirPath)
+                .filter(f => f.endsWith('.md'))
+                .sort();
+            subagents.push({
+                name: dir,
+                path: dirPath,
+                files,
+                frontmatter,
+            });
+        }
     }
     return subagents;
 }
@@ -123,35 +137,28 @@ export function listInstalledSubagents() {
  * Get a specific installed subagent
  */
 export function getInstalledSubagent(name) {
-    const subagentsDir = getSubagentsDir();
-    const dirPath = path.join(subagentsDir, name);
-    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
-        return null;
-    }
-    const agentMd = path.join(dirPath, 'AGENT.md');
-    if (!fs.existsSync(agentMd)) {
-        return null;
-    }
-    const frontmatter = parseSubagentFrontmatter(agentMd);
-    if (!frontmatter) {
-        return null;
+    // Check user dir first, then system
+    for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
+        const dirPath = path.join(subagentsDir, name);
+        if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+            continue;
+        const agentMd = path.join(dirPath, 'AGENT.md');
+        if (!fs.existsSync(agentMd))
+            continue;
+        const frontmatter = parseSubagentFrontmatter(agentMd);
+        if (!frontmatter)
+            continue;
+        const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.md')).sort();
+        return { name, path: dirPath, files, frontmatter };
     }
-    const files = fs.readdirSync(dirPath)
-        .filter(f => f.endsWith('.md'))
-        .sort();
-    return {
-        name,
-        path: dirPath,
-        files,
-        frontmatter,
-    };
+    return null;
 }
 /**
  * Install a subagent centrally to ~/.agents/subagents/{name}/
  */
 export function installSubagentCentrally(sourcePath, name) {
-    const subagentsDir = getSubagentsDir();
-    const targetDir = path.join(subagentsDir, name);
+    const subagentsDir = getUserSubagentsDir();
+    const targetDir = safeJoin(subagentsDir, name);
     try {
         // Ensure subagents directory exists
         if (!fs.existsSync(subagentsDir)) {
@@ -173,18 +180,19 @@ export function installSubagentCentrally(sourcePath, name) {
  * Remove an installed subagent
  */
 export function removeSubagent(name) {
-    const subagentsDir = getSubagentsDir();
-    const targetDir = path.join(subagentsDir, name);
-    if (!fs.existsSync(targetDir)) {
-        return { success: false, error: `Subagent '${name}' not found` };
-    }
-    try {
-        fs.rmSync(targetDir, { recursive: true });
-        return { success: true };
-    }
-    catch (err) {
-        return { success: false, error: String(err) };
+    for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
+        const candidate = safeJoin(subagentsDir, name);
+        if (fs.existsSync(candidate)) {
+            try {
+                fs.rmSync(candidate, { recursive: true });
+                return { success: true };
+            }
+            catch (err) {
+                return { success: false, error: String(err) };
+            }
+        }
     }
+    return { success: false, error: `Subagent '${name}' not found` };
 }
 /**
  * Transform a subagent directory into a single .md file for Claude
@@ -256,7 +264,7 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
         }
         try {
             const transformed = transformSubagentForClaude(subagentDir);
-            fs.writeFileSync(path.join(agentsDir, `${subagentName}.md`), transformed);
+            fs.writeFileSync(safeJoin(agentsDir, `${subagentName}.md`), transformed);
             return { success: true };
         }
         catch (err) {
@@ -265,7 +273,7 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
     }
     else if (agent === 'openclaw') {
         // OpenClaw: copy full directory
-        const targetDir = path.join(agentHome, '.openclaw', subagentName);
+        const targetDir = safeJoin(path.join(agentHome, '.openclaw'), subagentName);
         return syncSubagentToOpenclaw(subagentDir, targetDir);
     }
     else {
@@ -279,14 +287,14 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
 export function removeSubagentFromAgent(subagentName, agent, agentHome) {
     try {
         if (agent === 'claude') {
-            const targetPath = path.join(agentHome, '.claude', 'agents', `${subagentName}.md`);
+            const targetPath = safeJoin(path.join(agentHome, '.claude', 'agents'), `${subagentName}.md`);
             if (fs.existsSync(targetPath)) {
                 fs.unlinkSync(targetPath);
             }
             return { success: true };
         }
         else if (agent === 'openclaw') {
-            const targetDir = path.join(agentHome, '.openclaw', subagentName);
+            const targetDir = safeJoin(path.join(agentHome, '.openclaw'), subagentName);
             if (fs.existsSync(targetDir)) {
                 fs.rmSync(targetDir, { recursive: true });
             }
@@ -324,7 +332,7 @@ export function subagentContentMatches(installedDir, sourceDir) {
     }
     return true;
 }
-// Agents that support subagents
+/** Agents that support the subagent system (Claude via flattened .md, OpenClaw via directory copy). */
 export const SUBAGENT_CAPABLE_AGENTS = ['claude', 'openclaw'];
 /**
  * List subagents installed to a specific agent's home
@@ -399,4 +407,3 @@ export function listSubagentsForAgent(agentId, home) {
     }
     return subagents;
 }
-//# sourceMappingURL=subagents.js.map

package/dist/lib/sync-manifest.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Sync manifest — fast staleness guard for syncResourcesToVersion.
+ *
+ * Written after each full sync; read before the next to skip unconditional
+ * re-copies when nothing has changed. Two-tier check:
+ *   Tier 1 — stat mtime+size   ~0.01ms/file   (kernel VFS cache)
+ *   Tier 2 — sha256 on miss    ~0.1–0.5ms/file
+ *
+ * Env vars in MCP YAML are NOT substituted by agents-cli — ${VAR} is stored
+ * verbatim and passed as-is to `claude mcp add`. Value-only env var changes
+ * (YAML content unchanged) are not detected and are not in scope.
+ *
+ * Layering model:
+ *   First-wins (commands, skills, hooks, MCP, rules): manifest stores fingerprint
+ *   of the WINNING source (project > user > system > extra). A scope change
+ *   (e.g. project file added/removed) is detected via resolved-path mismatch.
+ *
+ *   Merged (permissions): all group files across all scopes contribute. Any
+ *   change in any scope file triggers re-sync.
+ *
+ * The manifest is written only after a full (unselected) sync and is only used
+ * as a guard for full syncs — partial/interactive syncs bypass it entirely.
+ */
+import type { AgentId } from './types.js';
+import type { AvailableResources } from './versions.js';
+declare const MANIFEST_VERSION: 1;
+/** Fingerprint of a single source file. */
+export interface Fingerprint {
+    path: string;
+    mtime: number;
+    size: number;
+    sha256: string;
+}
+/** A single-file resource (command, hook, MCP server YAML). */
+interface FileEntry {
+    source: Fingerprint;
+}
+/** A directory resource (skill). */
+interface DirEntry {
+    dirPath: string;
+    files: Fingerprint[];
+}
+/** Rules/memory: per-file first-wins fingerprints. */
+interface RulesEntry {
+    files: Record<string, FileEntry>;
+}
+/** Permissions: all group files across all scopes (merged). */
+interface PermEntry {
+    groups: Record<string, FileEntry>;
+    permissionSet: string | null;
+}
+export interface SyncManifest {
+    v: typeof MANIFEST_VERSION;
+    syncedAt: string;
+    commands: Record<string, FileEntry>;
+    skills: Record<string, DirEntry>;
+    hooks: Record<string, FileEntry>;
+    rules: RulesEntry;
+    mcp: Record<string, FileEntry>;
+    permissions: PermEntry;
+    subagents: Record<string, DirEntry>;
+}
+/** Load the manifest for a given agent+version. Returns null on miss or parse error. */
+export declare function loadSyncManifest(agent: AgentId, version: string): SyncManifest | null;
+/** Write the manifest atomically (tmp + rename). */
+export declare function saveSyncManifest(agent: AgentId, version: string, manifest: SyncManifest): void;
+/**
+ * Build a manifest by fingerprinting current source state.
+ * Call this after a successful full sync.
+ */
+export declare function buildManifest(agent: AgentId, version: string, available: AvailableResources, cwd: string): SyncManifest;
+/**
+ * Check if sources have changed since the manifest was written.
+ * Returns true (stale) at the first detected mismatch — no need to scan everything.
+ * Returns false (clean) only after all checks pass.
+ *
+ * For rules, also delegates to isMemoryStale() to catch @-import changes
+ * for agents that pre-compile their memory file.
+ */
+export declare function isSyncStale(manifest: SyncManifest, available: AvailableResources, agent: AgentId, version: string, cwd: string): boolean;
+export {};