@phnx-labs/agents-cli 1.20.4 → 1.20.5

package/dist/lib/project-launch.js

@@ -0,0 +1,367 @@
+/**
+ * Launch-time project compile. Invoked by the agent shim's hot path (via
+ * `agents sync --launch`) between version resolve and binary exec.
+ *
+ * Three responsibilities, all skip-fast when there's nothing to do:
+ *
+ * 1. Compile project rules from `<cwd>/.agents/rules/` into `<cwd>/AGENTS.md`
+ *    (+ per-agent symlinks). Delegates to compileRulesForProject, which is
+ *    the same helper management-side `agents sync` uses.
+ *
+ * 2. Mirror project resources from `<cwd>/.agents/{subagents,commands,skills}`
+ *    into the agent's workspace-local discovery dirs (`<cwd>/.claude/agents/`,
+ *    `<cwd>/.claude/commands/`, `<cwd>/.claude/skills/`). File-level symlinks
+ *    so edits in the source dir are live without re-sync. Skips any dest
+ *    entry that already exists and isn't one of our symlinks (don't-clobber).
+ *    v1: claude-only. Other agents have varying workspace conventions (amp
+ *    uses `~/.config/amp`, antigravity uses `~/.gemini/antigravity-cli`,
+ *    codex/gemini/cursor lack subagent support entirely) — they're follow-up
+ *    material. NOTE: `.mcp.json` is intentionally NOT auto-symlinked from
+ *    the launch path — that's a supply-chain surface (cloning a hostile
+ *    repo would auto-register an attacker MCP server). Belongs to full
+ *    `agents sync` with explicit opt-in, not the hot path.
+ *
+ * 3. Synthesize four scope-grouped plugin marketplaces under the version's
+ *    `<versionHome>/.{agent}/plugins/marketplaces/` (for plugin-capable agents):
+ *      - agents-cli         ← ~/.agents/plugins/*           (user scope, legacy name)
+ *      - agents-system      ← ~/.agents/.system/plugins/*
+ *      - extras-<alias>     ← ~/.agents-<alias>/plugins/*   (per enabled extra)
+ *      - agents-project     ← <cwd>/.agents/plugins/*
+ *    Each plugin is copied in (skip-fast via mtime cache), the marketplace
+ *    catalog is rewritten only when contents change, and the marketplace is
+ *    registered in known_marketplaces.json. Upstream marketplaces like
+ *    "claude-plugins-official" are left untouched. Project- and extras-
+ *    scope plugins do NOT auto-enable exec surfaces (.mcp.json, hooks, bin/,
+ *    scripts/) — user must explicitly `agents plugins enable` them.
+ *
+ * Heavy work (version-home reconciliation, hook registration, MCP merging)
+ * stays in `agents sync` without --launch and is NOT touched here. The
+ * launch path is filesystem-only and skip-fast: sub-50ms when no source
+ * has changed, scales linearly only with newly-modified plugins on the
+ * change path.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { supports } from './capabilities.js';
+import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
+import { getVersionHomePath } from './versions.js';
+import { compileRulesForProject } from './rules/compile.js';
+import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
+import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, addPluginToSettings, copyPluginToMarketplace, marketplaceNameFor, marketplaceRoot, pluginInstallDir, registerMarketplace, removePluginFromSettings, syncMarketplaceManifest, } from './plugin-marketplace.js';
+/**
+ * Run the launch-time project compile. Safe to call on every agent launch:
+ * each step is idempotent and skips when its inputs are missing.
+ */
+export function runLaunchSync(opts) {
+    const result = {
+        rulesCompiled: false,
+        workspaceLinks: 0,
+        workspaceSkipped: [],
+        marketplaces: {},
+    };
+    // Step 1: project rules
+    try {
+        const r = compileRulesForProject(opts.cwd);
+        result.rulesCompiled = r.compiled;
+    }
+    catch {
+        // Don't fail launch on a malformed project rules.yaml.
+    }
+    // Step 2: workspace resource mirror
+    const mirror = mirrorWorkspaceResources(opts.cwd, opts.agent);
+    result.workspaceLinks = mirror.links;
+    result.workspaceSkipped = mirror.skipped;
+    // Step 3: scoped plugin marketplaces
+    result.marketplaces = synthesizeScopedMarketplaces(opts.agent, opts.version, opts.cwd);
+    return result;
+}
+const CLAUDE_MIRROR_PLANS = [
+    { srcSubdir: 'subagents', destSubdir: 'agents', entriesAreDirs: false },
+    { srcSubdir: 'commands', destSubdir: 'commands', entriesAreDirs: false },
+    { srcSubdir: 'skills', destSubdir: 'skills', entriesAreDirs: true },
+];
+function mirrorWorkspaceResources(cwd, agent) {
+    // v1: claude-only. Other agents have workspace conventions we haven't
+    // mapped (amp: ~/.config/amp; antigravity: ~/.gemini/antigravity-cli;
+    // codex/gemini/cursor: no subagent support per capabilities). Adding them
+    // requires per-agent workspaceDirName + capability gates — follow-up.
+    if (agent !== 'claude')
+        return { links: 0, skipped: [] };
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return { links: 0, skipped: [] };
+    const agentWorkspaceDir = path.join(cwd, '.claude');
+    const projectAgentsResolved = (() => {
+        try {
+            return fs.realpathSync(projectAgentsDir);
+        }
+        catch {
+            return path.resolve(projectAgentsDir);
+        }
+    })();
+    let links = 0;
+    const skipped = [];
+    // Mirror subagents / commands / skills. mcp.json is intentionally excluded
+    // — see header doc, it's a supply-chain surface.
+    for (const plan of CLAUDE_MIRROR_PLANS) {
+        const srcDir = path.join(projectAgentsDir, plan.srcSubdir);
+        if (!fs.existsSync(srcDir))
+            continue;
+        const destDir = path.join(agentWorkspaceDir, plan.destSubdir);
+        fs.mkdirSync(destDir, { recursive: true });
+        const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (plan.entriesAreDirs && !entry.isDirectory())
+                continue;
+            if (!plan.entriesAreDirs && !entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            const srcPath = path.join(srcDir, entry.name);
+            const destPath = path.join(destDir, entry.name);
+            if (replaceWithSymlinkIfOwned(srcPath, destPath, projectAgentsResolved)) {
+                links += 1;
+            }
+            else {
+                skipped.push(path.relative(cwd, destPath));
+            }
+        }
+    }
+    return { links, skipped };
+}
+/**
+ * Create or refresh a symlink at `destPath` pointing at `srcPath`. Returns
+ * true if we wrote (or already had) the link, false if we skipped because
+ * the destination is user-owned (regular file, directory, or symlink pointing
+ * outside the project's `.agents/` tree, or a dangling symlink — treated as
+ * user state we don't yet understand).
+ *
+ * Skip-fast: if the destination is already a symlink resolving to the
+ * project-agents tree AND its target matches srcPath, no write happens.
+ */
+function replaceWithSymlinkIfOwned(srcPath, destPath, projectAgentsResolved) {
+    let destLstat = null;
+    try {
+        destLstat = fs.lstatSync(destPath);
+    }
+    catch { /* missing — write fresh */ }
+    if (destLstat) {
+        if (!destLstat.isSymbolicLink()) {
+            return false;
+        }
+        let destTargetReal = null;
+        try {
+            destTargetReal = fs.realpathSync(destPath);
+        }
+        catch { /* dangling */ }
+        // Dangling symlink → user-owned in-progress state; do not clobber.
+        if (destTargetReal === null) {
+            return false;
+        }
+        if (destTargetReal !== projectAgentsResolved && !destTargetReal.startsWith(projectAgentsResolved + path.sep)) {
+            return false;
+        }
+        let srcReal = null;
+        try {
+            srcReal = fs.realpathSync(srcPath);
+        }
+        catch { /* src vanished mid-launch */ }
+        if (srcReal !== null && destTargetReal === srcReal) {
+            return true; // already correct
+        }
+        try {
+            fs.unlinkSync(destPath);
+        }
+        catch { /* ignore */ }
+    }
+    try {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.symlinkSync(srcPath, destPath);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function makeScope(spec, pluginsDir, autoEnableExecSurfaces, precedence) {
+    return { spec, marketplaceName: marketplaceNameFor(spec), pluginsDir, autoEnableExecSurfaces, precedence };
+}
+function collectPluginScopes(cwd) {
+    const scopes = [];
+    // Precedence: project > extras > user > system. Same direction the rules
+    // composition uses (project layer shadows base layers).
+    scopes.push(makeScope({ kind: 'system', root: getSystemPluginsDir() }, getSystemPluginsDir(), true, 0));
+    scopes.push(makeScope({ kind: 'user' }, getPluginsDir(), true, 1));
+    for (const extra of getEnabledExtraRepos()) {
+        const root = getExtraPluginsDir(extra.alias);
+        scopes.push(makeScope({ kind: 'extra', alias: extra.alias, root }, root, false, 2));
+    }
+    const projectPluginsDir = getProjectPluginsDir(cwd);
+    if (projectPluginsDir) {
+        scopes.push(makeScope({ kind: 'project', root: projectPluginsDir }, projectPluginsDir, false, 3));
+    }
+    return scopes;
+}
+function synthesizeScopedMarketplaces(agent, version, cwd) {
+    const result = {};
+    if (!supports(agent, 'plugins', version).ok)
+        return result;
+    let versionHome;
+    try {
+        versionHome = getVersionHomePath(agent, version);
+    }
+    catch {
+        return result;
+    }
+    if (!fs.existsSync(versionHome))
+        return result;
+    // First pass: resolve cross-scope plugin name collisions by precedence.
+    // For each plugin name, the scope with the highest precedence wins; the
+    // plugin is installed only into that scope's marketplace.
+    const winner = new Map();
+    for (const scope of collectPluginScopes(cwd)) {
+        if (!fs.existsSync(scope.pluginsDir))
+            continue;
+        for (const plugin of discoverPluginsInDir(scope.pluginsDir)) {
+            const existing = winner.get(plugin.name);
+            if (!existing || scope.precedence > existing.scope.precedence) {
+                winner.set(plugin.name, { scope, plugin });
+            }
+        }
+    }
+    if (winner.size === 0)
+        return result;
+    // Group winners by their winning scope and synthesize one marketplace per
+    // scope. Skip-fast: scope hash sentinel short-circuits unchanged scopes.
+    const byScope = new Map();
+    for (const { scope, plugin } of winner.values()) {
+        let bucket = byScope.get(scope.marketplaceName);
+        if (!bucket) {
+            bucket = { scope, plugins: [] };
+            byScope.set(scope.marketplaceName, bucket);
+        }
+        bucket.plugins.push(plugin);
+    }
+    for (const { scope, plugins } of byScope.values()) {
+        plugins.sort((a, b) => a.name.localeCompare(b.name));
+        const installed = installScope(agent, versionHome, scope, plugins);
+        if (installed.length > 0)
+            result[scope.marketplaceName] = installed;
+    }
+    // Sweep any orphaned `<plugin>@*` keys whose plugin name is now owned by a
+    // different scope (e.g. plugin moved from user to project). Without this,
+    // the OLD scope's enabledPlugins key stays set forever, double-enabling.
+    pruneLosingScopeEnables(agent, versionHome, winner);
+    return result;
+}
+function installScope(agent, versionHome, scope, plugins) {
+    const newHash = computeScopeHash(plugins);
+    const sentinelPath = path.join(marketplaceRoot(scope.spec, agent, versionHome), '.agents-launch-sync');
+    const existingHash = readScopeHash(sentinelPath);
+    if (existingHash === newHash) {
+        // Nothing changed since last launch — fast path. Verify the manifest
+        // dir still exists; if a user blew it away, force a re-sync.
+        if (fs.existsSync(path.dirname(sentinelPath))) {
+            return plugins.map((p) => p.name);
+        }
+    }
+    const installed = [];
+    for (const plugin of plugins) {
+        try {
+            copyPluginToMarketplace(plugin, scope.spec, agent, versionHome);
+            installed.push(plugin.name);
+        }
+        catch {
+            // Individual plugin copy failure — keep going on the others.
+        }
+    }
+    if (installed.length === 0)
+        return [];
+    syncMarketplaceManifest(scope.spec, agent, versionHome);
+    registerMarketplace(scope.spec, agent, versionHome);
+    // Enable each plugin in settings unless the scope withholds auto-enable for
+    // exec surfaces (project + extras) AND the plugin actually ships any.
+    for (const plugin of plugins) {
+        if (!installed.includes(plugin.name))
+            continue;
+        if (!scope.autoEnableExecSurfaces && hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root)))
+            continue;
+        addPluginToSettings(plugin.name, scope.marketplaceName, agent, versionHome);
+    }
+    writeScopeHash(sentinelPath, newHash);
+    return installed;
+}
+function pruneLosingScopeEnables(agent, versionHome, winner) {
+    const ourScopeNames = new Set([
+        SYSTEM_MARKETPLACE_NAME,
+        MARKETPLACE_NAME,
+        PROJECT_MARKETPLACE_NAME,
+        ...getEnabledExtraRepos().map((e) => marketplaceNameFor({ kind: 'extra', alias: e.alias, root: getExtraPluginsDir(e.alias) })),
+    ]);
+    for (const [name, { scope: winningScope }] of winner) {
+        for (const candidateScope of ourScopeNames) {
+            if (candidateScope === winningScope.marketplaceName)
+                continue;
+            removePluginFromSettings(name, candidateScope, agent, versionHome);
+        }
+    }
+}
+/**
+ * Hash the plugin set so we can skip-fast when nothing changed since the
+ * last launch. Includes the source path (catches moves), the .claude-plugin/
+ * plugin.json content (catches metadata edits), and the file-mtime+size
+ * fingerprint of every file in the plugin (catches code edits).
+ */
+function computeScopeHash(plugins) {
+    const hash = crypto.createHash('sha256');
+    for (const plugin of [...plugins].sort((a, b) => a.name.localeCompare(b.name))) {
+        hash.update(`${plugin.name}\0${plugin.root}\0`);
+        fingerprintDir(plugin.root, hash);
+        hash.update('\0SEP\0');
+    }
+    return hash.digest('hex');
+}
+function fingerprintDir(dir, hash) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (entry.name === 'node_modules' || entry.name === '.git')
+            continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            hash.update(`D ${entry.name}\n`);
+            fingerprintDir(abs, hash);
+        }
+        else {
+            try {
+                const stat = fs.lstatSync(abs);
+                hash.update(`F ${entry.name} ${stat.size} ${stat.mtimeMs}\n`);
+            }
+            catch { /* race during launch — skip */ }
+        }
+    }
+}
+function readScopeHash(sentinelPath) {
+    try {
+        return fs.readFileSync(sentinelPath, 'utf-8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+function writeScopeHash(sentinelPath, hash) {
+    try {
+        fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
+        fs.writeFileSync(sentinelPath, hash + '\n');
+    }
+    catch { /* best-effort; missing sentinel just means next launch does full work */ }
+}
+// Re-export for the test's structural assertions; not used internally.
+export { pluginInstallDir };

package/dist/lib/pty-client.js

@@ -57,7 +57,7 @@ async function ensureServer() {
         }
         await new Promise(r => setTimeout(r, 100));
     }
-    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents-system/helpers/pty/logs.jsonl');
+    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents/.system/helpers/pty/logs.jsonl');
 }
 function getServerSpawnArgs() {
     // Prefer the dist/index.js from the same installation as this code.

package/dist/lib/pty-server.d.ts

@@ -6,7 +6,7 @@
  * across multiple CLI invocations. Each session holds a real PTY (via node-pty)
  * and a headless terminal emulator (via @xterm/headless) for screen rendering.
  *
- * Protocol: newline-delimited JSON over ~/.agents-system/pty.sock
+ * Protocol: newline-delimited JSON over ~/.agents/.system/pty.sock
  */
 /**
  * Capture a stable identifier for a process at the moment it was started.

package/dist/lib/pty-server.js

@@ -6,7 +6,7 @@
  * across multiple CLI invocations. Each session holds a real PTY (via node-pty)
  * and a headless terminal emulator (via @xterm/headless) for screen rendering.
  *
- * Protocol: newline-delimited JSON over ~/.agents-system/pty.sock
+ * Protocol: newline-delimited JSON over ~/.agents/.system/pty.sock
  */
 import * as net from 'net';
 import * as fs from 'fs';

package/dist/lib/refresh.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { AgentId } from './types.js';
+export interface RefreshOptions {
+    /** Limit operations to a single agent (claude/codex/etc). Default: all installed. */
+    agentFilter?: AgentId;
+    /** Auto-sync everything and skip interactive prompts. */
+    skipPrompts?: boolean;
+    /** Skip CLI version install/upgrade from agents.yaml. */
+    skipClis?: boolean;
+}
+/**
+ * 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 declare function refresh(options?: RefreshOptions): Promise<void>;