@phnx-labs/agents-cli 1.18.1 → 1.18.2

package/dist/lib/teams/persistence.js

@@ -1,84 +1,19 @@
 /**
- * Teams configuration persistence.
+ * Teams data-directory resolution.
  *
- * Manages reading, writing, and migrating the teams config file
- * (~/.agents/teams/config.json) that stores per-agent-type settings
- * (command templates, enabled state, pinned models) and provider configs.
- * Also resolves the base data directory for teammate process storage.
+ * Resolves the base directory for teammate metadata + the per-team agents
+ * dir, with temp-dir fallbacks for unwritable homedirs. The teams subsystem
+ * does NOT carry its own agent-registry config — `agents teams` discovers
+ * agents through the same machinery as `agents view` (installed versions
+ * via `listInstalledVersions`) and invokes them through `agents run`.
  */
 import * as fs from 'fs/promises';
-import * as fsSync from 'fs';
 import * as path from 'path';
-import { homedir, tmpdir } from 'os';
+import { tmpdir } from 'os';
 import { constants as fsConstants } from 'fs';
-import { randomBytes } from 'crypto';
-import lockfile from 'proper-lockfile';
 import { getTeamsDir, getTeamsAgentsDir } from '../state.js';
-/**
- * Atomic JSON write: writes to a sibling tmp file then renames over the
- * target. rename(2) is atomic on POSIX, so a crashed/interrupted write
- * leaves the old config intact instead of leaving a half-written file the
- * next read will reject.
- */
-async function atomicWriteJson(p, data) {
-    await fs.mkdir(path.dirname(p), { recursive: true });
-    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
-    const body = JSON.stringify(data, null, 2);
-    await fs.writeFile(tmp, body);
-    try {
-        await fs.rename(tmp, p);
-    }
-    catch (err) {
-        await fs.unlink(tmp).catch(() => { });
-        throw err;
-    }
-}
-/**
- * Hold an exclusive cross-process lock on the config file while running
- * `fn`. proper-lockfile requires the target to exist, so we touch it
- * first. Stale locks auto-expire after 10s.
- */
-async function withConfigLock(p, fn) {
-    await fs.mkdir(path.dirname(p), { recursive: true });
-    if (!fsSync.existsSync(p)) {
-        try {
-            await fs.writeFile(p, '{}', { flag: 'wx' });
-        }
-        catch (err) {
-            if (err && err.code !== 'EEXIST')
-                throw err;
-        }
-    }
-    const release = await lockfile.lock(p, {
-        retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
-        stale: 10_000,
-    });
-    try {
-        return await fn();
-    }
-    finally {
-        await release();
-    }
-}
-// All supported teammate agent types
-const ALL_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode'];
-// Teams config + registry live under ~/.agents/teams/ (definitions);
-// per-run agent execution dirs live under ~/.agents/.history/teams/agents/.
 const TEAMS_DIR = getTeamsDir();
-// Legacy paths (for migration)
-const LEGACY_CONFIG_DIR = path.join(homedir(), '.agents');
-// Legacy migration from pre-OSS brand; safe to remove after 2026-07
-const LEGACY_BASE_DIR = path.join(homedir(), '.swarmify');
 const TMP_FALLBACK_DIR = path.join(tmpdir(), 'agents');
-async function pathExists(p) {
-    try {
-        await fs.access(p);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function ensureWritableDir(p) {
     try {
         await fs.mkdir(p, { recursive: true });
@@ -113,18 +48,7 @@ async function resolveAgentsPath() {
     }
     throw new Error('Unable to determine a writable agents directory');
 }
-async function resolveConfigPath() {
-    await fs.mkdir(TEAMS_DIR, { recursive: true });
-    return path.join(TEAMS_DIR, 'config.json');
-}
-async function resolveLegacyConfigPath() {
-    return path.join(LEGACY_CONFIG_DIR, 'config.json');
-}
-async function resolveLegacySwarmifyConfigPath() {
-    return path.join(LEGACY_BASE_DIR, 'agents', 'config.json');
-}
 let AGENTS_DIR = null;
-let CONFIG_PATH = null;
 /** Resolve and ensure the agents subdirectory exists under the teams base dir. */
 export async function resolveAgentsDir() {
     if (!AGENTS_DIR) {
@@ -133,249 +57,3 @@ export async function resolveAgentsDir() {
     await fs.mkdir(AGENTS_DIR, { recursive: true });
     return AGENTS_DIR;
 }
-async function ensureConfigPath() {
-    if (!CONFIG_PATH) {
-        CONFIG_PATH = await resolveConfigPath();
-    }
-    const dir = path.dirname(CONFIG_PATH);
-    await fs.mkdir(dir, { recursive: true });
-    return CONFIG_PATH;
-}
-// Get default agent configuration. `model` is null by default — the teammate
-// launcher omits --model and the agent's CLI picks its own default, which is
-// what "drop hardcoded model mapping" means in practice.
-function getDefaultAgentConfig(agentType) {
-    const defaults = {
-        claude: {
-            command: 'claude -p \'{prompt}\' --output-format stream-json --json',
-            enabled: true,
-            model: null,
-            provider: 'anthropic'
-        },
-        codex: {
-            command: 'codex exec --sandbox workspace-write \'{prompt}\' --json',
-            enabled: true,
-            model: null,
-            provider: 'openai'
-        },
-        gemini: {
-            command: 'gemini \'{prompt}\' --output-format stream-json',
-            enabled: true,
-            model: null,
-            provider: 'google'
-        },
-        cursor: {
-            command: 'cursor-agent -p --output-format stream-json \'{prompt}\'',
-            enabled: true,
-            model: null,
-            provider: 'custom'
-        },
-        opencode: {
-            command: 'opencode run --format json \'{prompt}\'',
-            enabled: true,
-            model: null,
-            provider: 'custom'
-        }
-    };
-    return defaults[agentType];
-}
-// Get default provider configuration
-function getDefaultProviderConfig() {
-    return {
-        anthropic: {
-            apiEndpoint: 'https://api.anthropic.com'
-        },
-        openai: {
-            apiEndpoint: 'https://api.openai.com/v1'
-        },
-        google: {
-            apiEndpoint: 'https://generativelanguage.googleapis.com/v1'
-        },
-        custom: {
-            apiEndpoint: null
-        }
-    };
-}
-// Get default full configuration
-function getDefaultSwarmConfig() {
-    const agents = {};
-    for (const agentType of ALL_AGENTS) {
-        agents[agentType] = getDefaultAgentConfig(agentType);
-    }
-    return {
-        agents,
-        providers: getDefaultProviderConfig()
-    };
-}
-// Try to read a config file as either SwarmConfig or legacy format
-async function tryReadLegacyConfig(configPath) {
-    try {
-        const data = await fs.readFile(configPath, 'utf-8');
-        const parsed = JSON.parse(data);
-        // New format: has agents object with nested configs. We detect it by any
-        // recognizable per-agent field (model, models, command, enabled) — the old
-        // 'models' field is still accepted so pre-existing configs load cleanly.
-        if (parsed.agents && typeof parsed.agents === 'object') {
-            const firstValue = Object.values(parsed.agents)[0];
-            if (firstValue && typeof firstValue === 'object') {
-                const obj = firstValue;
-                if ('model' in obj || 'models' in obj || 'command' in obj || 'enabled' in obj) {
-                    return parsed;
-                }
-            }
-        }
-        // Old format: { enabledAgents: string[] }
-        if (parsed.enabledAgents && Array.isArray(parsed.enabledAgents)) {
-            const defaultConfig = getDefaultSwarmConfig();
-            for (const agentType of parsed.enabledAgents) {
-                if (ALL_AGENTS.includes(agentType)) {
-                    defaultConfig.agents[agentType].enabled = true;
-                }
-            }
-            return defaultConfig;
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-// Migrate from legacy config locations
-async function migrateLegacyConfig() {
-    // Try ~/.agents/config.json first (most recent legacy location)
-    const legacyConfigPath = await resolveLegacyConfigPath();
-    let config = await tryReadLegacyConfig(legacyConfigPath);
-    // Try ~/.swarmify/agents/config.json (legacy pre-OSS brand path)
-    if (!config) {
-        const legacyBrandConfigPath = await resolveLegacySwarmifyConfigPath();
-        config = await tryReadLegacyConfig(legacyBrandConfigPath);
-    }
-    if (!config)
-        return null;
-    // Write migrated config to new location
-    const newConfigPath = await ensureConfigPath();
-    await fs.writeFile(newConfigPath, JSON.stringify(config, null, 2));
-    console.warn(`[agents] Migrated config to ${newConfigPath}`);
-    return config;
-}
-/** Read teams config from disk, migrating legacy formats if needed. Returns defaults when no config exists. */
-export async function readConfig() {
-    const configPath = await ensureConfigPath();
-    // Try to read new config first
-    try {
-        const data = await fs.readFile(configPath, 'utf-8');
-        const config = JSON.parse(data);
-        const enabledAgents = [];
-        const agentConfigs = {};
-        const providerConfigs = {};
-        // Parse agent configs
-        if (config.agents && typeof config.agents === 'object') {
-            for (const [agentKey, agentValue] of Object.entries(config.agents)) {
-                if (!ALL_AGENTS.includes(agentKey))
-                    continue;
-                const agentType = agentKey;
-                // Merge with defaults for missing fields
-                const defaultAgentConfig = getDefaultAgentConfig(agentType);
-                const mergedAgentConfig = {
-                    ...defaultAgentConfig,
-                    ...agentValue
-                };
-                if (mergedAgentConfig.enabled) {
-                    enabledAgents.push(agentType);
-                }
-                agentConfigs[agentType] = mergedAgentConfig;
-            }
-        }
-        // Fill in missing agents with defaults
-        for (const agentType of ALL_AGENTS) {
-            if (!agentConfigs[agentType]) {
-                agentConfigs[agentType] = getDefaultAgentConfig(agentType);
-            }
-        }
-        // Parse provider configs
-        if (config.providers && typeof config.providers === 'object') {
-            for (const [providerKey, providerValue] of Object.entries(config.providers)) {
-                const providerConfig = providerValue;
-                providerConfigs[providerKey] = providerConfig;
-            }
-        }
-        // Fill in missing providers with defaults
-        const defaultProviders = getDefaultProviderConfig();
-        for (const [providerKey, providerValue] of Object.entries(defaultProviders)) {
-            if (!providerConfigs[providerKey]) {
-                providerConfigs[providerKey] = providerValue;
-            }
-        }
-        return { enabledAgents, agentConfigs, providerConfigs, hasConfig: true };
-    }
-    catch {
-        // Config doesn't exist or is invalid, try migration
-        const migratedConfig = await migrateLegacyConfig();
-        if (migratedConfig) {
-            const enabledAgents = [];
-            const agentConfigs = {};
-            const providerConfigs = migratedConfig.providers;
-            for (const [agentKey, agentValue] of Object.entries(migratedConfig.agents)) {
-                const agentType = agentKey;
-                agentConfigs[agentType] = agentValue;
-                if (agentValue.enabled) {
-                    enabledAgents.push(agentType);
-                }
-            }
-            return { enabledAgents, agentConfigs, providerConfigs, hasConfig: true };
-        }
-        // No config and no legacy config, return defaults
-        const defaultConfig = getDefaultSwarmConfig();
-        const enabledAgents = [];
-        const agentConfigs = defaultConfig.agents;
-        const providerConfigs = defaultConfig.providers;
-        for (const [agentKey, agentValue] of Object.entries(defaultConfig.agents)) {
-            if (agentValue.enabled) {
-                enabledAgents.push(agentKey);
-            }
-        }
-        // Write default config to file
-        await fs.writeFile(configPath, JSON.stringify(defaultConfig, null, 2));
-        return { enabledAgents, agentConfigs, providerConfigs, hasConfig: false };
-    }
-}
-/** Write teams config to disk. */
-export async function writeConfig(config) {
-    const configPath = await ensureConfigPath();
-    await withConfigLock(configPath, async () => {
-        await atomicWriteJson(configPath, config);
-    });
-}
-/** Update the enabled/disabled status of a specific agent type in the config file. */
-export async function setAgentEnabled(agentType, enabled) {
-    const configPath = await ensureConfigPath();
-    await withConfigLock(configPath, async () => {
-        let parsed;
-        try {
-            const raw = await fs.readFile(configPath, 'utf-8');
-            parsed = JSON.parse(raw);
-        }
-        catch (err) {
-            // ENOENT: the lock held briefly above touched a placeholder, but a
-            // racing writer could still have produced an empty file. Fall back
-            // to defaults rather than wedge the call.
-            if (err && err.code === 'ENOENT') {
-                parsed = getDefaultSwarmConfig();
-            }
-            else if (err instanceof SyntaxError) {
-                throw new Error(`Teams config corrupted at ${configPath}: ${err.message}. Inspect and restore from backup.`);
-            }
-            else {
-                throw err;
-            }
-        }
-        if (!parsed.agents) {
-            parsed.agents = getDefaultSwarmConfig().agents;
-        }
-        if (!parsed.agents[agentType]) {
-            parsed.agents[agentType] = getDefaultAgentConfig(agentType);
-        }
-        parsed.agents[agentType].enabled = enabled;
-        await atomicWriteJson(configPath, parsed);
-    });
-}

package/dist/lib/teams/registry.js

@@ -1,18 +1,20 @@
 /**
  * Team registry.
  *
- * Manages the persistent registry of named teams stored in registry.json
- * under the teams data directory. Provides CRUD operations for team metadata
- * (creation timestamp and optional description).
+ * Manages the persistent registry of named teams stored at
+ * ~/.agents/.history/teams/registry.json. This is per-machine runtime
+ * state (timestamps + worktree paths that include absolute filesystem
+ * paths) and intentionally lives under .history/ so it's NOT pulled in
+ * by `agents repo push`.
  */
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getTeamsDir } from '../state.js';
+import { getTeamsRegistryPath } from '../state.js';
 async function registryPath() {
-    return path.join(getTeamsDir(), 'registry.json');
+    return getTeamsRegistryPath();
 }
 /**
  * Atomic JSON write: writes to a unique sibling tmp file then renames over

package/dist/lib/versions.js

@@ -37,7 +37,7 @@ import { registerHooksToSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins, syncPluginToVersion, isPluginSynced, pluginSupportsAgent, cleanOrphanedPluginSkills } from './plugins.js';
 import { composeRulesFromState } from './rules/compose.js';
-import { loadSyncManifest, saveSyncManifest, buildManifest, isSyncStale } from './sync-manifest.js';
+import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
 import { PLUGINS_CAPABLE_AGENTS } from './agents.js';
 import { emit } from './events.js';
 import { safeJoin } from './paths.js';
@@ -109,10 +109,14 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.skills = Array.from(skillNames);
-    // Hooks (files). Only executable files in hooks/ count as hooks. Auxiliary
-    // files like README.md (docs) or promptcuts.yaml (data read directly by a
-    // hook script) live alongside hooks but are not hooks themselves and must
-    // not be synced as such.
+    // Hooks (files). A hook is an actual script: known script extension, OR
+    // executable bit on a file with a non-data extension. Auxiliary content
+    // like `README.md` (docs) or `promptcuts.yaml` (data read directly by the
+    // expand-promptcuts script) lives in hooks/ but is not a hook. Older sync
+    // runs chmod 0o755'd everything they copied, so an exec bit alone can no
+    // longer be trusted as the signal.
+    const NON_SCRIPT_EXTS = new Set(['.md', '.markdown', '.rst', '.txt', '.yaml', '.yml', '.json', '.toml', '.ini', '.conf']);
+    const SCRIPT_EXTS = new Set(['.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1']);
     const hookNames = new Set();
     for (const { base } of resourceBases) {
         const hooksDir = path.join(base, 'hooks');
@@ -123,7 +127,14 @@ export function getAvailableResources(cwd = process.cwd()) {
                 continue;
             try {
                 const stat = fs.statSync(path.join(hooksDir, name));
-                if (stat.isFile() && (stat.mode & 0o111) !== 0)
+                if (!stat.isFile())
+                    continue;
+                const ext = path.extname(name).toLowerCase();
+                if (SCRIPT_EXTS.has(ext)) {
+                    hookNames.add(name);
+                    continue;
+                }
+                if ((stat.mode & 0o111) !== 0 && !NON_SCRIPT_EXTS.has(ext))
                     hookNames.add(name);
             }
             catch { /* ignore unreadable */ }
@@ -1451,6 +1462,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const versionHome = getVersionHomePath(agent, version);
     const agentDir = path.join(versionHome, `.${agent}`);
     fs.mkdirSync(agentDir, { recursive: true });
+    // Capture whether the caller passed a selection. The pattern-expansion
+    // path below reassigns `selection`, but for manifest write semantics we
+    // care about the ORIGINAL intent: a caller passing no selection means
+    // "full sync; persist the staleness manifest after."
+    const userPassedSelection = selection !== undefined;
     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);
@@ -1528,10 +1544,12 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     // 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).
+    // (unconditional file copies) to ~8-15ms (`isStale` walks the manifest's
+    // fingerprints, short-circuiting at the first mismatch). Numbers from
+    // scripts/bench-staleness.ts against a real ~50-resource project.
     if (!selection && !options.force) {
-        const manifest = loadSyncManifest(agent, version);
-        if (manifest && !isSyncStale(manifest, available, agent, version, cwd)) {
+        const manifest = loadManifest(agent, version);
+        if (manifest && !isStale(manifest, agent, version, cwd)) {
             return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
         }
     }
@@ -1864,9 +1882,13 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
         // workflow patterns already written via ensureVersionResourcePatterns above.
     }
-    // Write manifest after a successful full sync so the next launch can skip this work.
-    if (!selection) {
-        saveSyncManifest(agent, version, buildManifest(agent, version, available, cwd));
+    // Write manifest after a full sync (no user-passed selection) so the next
+    // launch can skip the slow path. Pattern-derived selections still count as
+    // "full" — the agents.yaml patterns describe the intended scope, not a
+    // one-off override, so the resulting state matches what the manifest
+    // records as the synced set.
+    if (!userPassedSelection) {
+        saveManifest(agent, version, buildSyncManifest(agent, version, cwd));
     }
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,81 +0,0 @@
-/**
- * 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>;
-    permissionPreset: 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 isRulesStale() to catch @-import changes
- * for agents that pre-compile their rules file.
- */
-export declare function isSyncStale(manifest: SyncManifest, available: AvailableResources, agent: AgentId, version: string, cwd: string): boolean;
-export {};