@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/staleness/registry.js

@@ -0,0 +1,123 @@
+/**
+ * Writer + detector registry for resource sync.
+ *
+ * Two parallel maps keyed by (ResourceKind, AgentId). At module import time
+ * (which fires once when the CLI boots) we verify that EVERY supported
+ * (agent, kind) pair has both a writer and a detector. Missing entries
+ * throw immediately — silent-skip bugs become startup errors.
+ *
+ *   - Adding a new agent? Either declare every supported kind with a writer
+ *     here OR mark the kind `false` in `AgentConfig.capabilities`.
+ *   - Adding a new kind? Declare it on every agent's capabilities and add a
+ *     writer module.
+ *
+ * The capability matrix in `lib/agents.ts:AGENTS` is the single source of
+ * truth for "is this (agent, kind) supported?". The assertion below maps the
+ * matrix to required registry entries.
+ */
+import { AGENTS } from '../agents.js';
+import { supports } from '../capabilities.js';
+import { ALL_RESOURCE_KINDS, kindToCapability, } from './writers/kinds.js';
+import { commandsWriters } from './writers/commands.js';
+import { skillsWriters } from './writers/skills.js';
+import { hooksWriters } from './writers/hooks.js';
+import { rulesWriters } from './writers/rules.js';
+import { mcpWriters } from './writers/mcp.js';
+import { permissionsWriters } from './writers/permissions.js';
+import { subagentsWriters } from './writers/subagents.js';
+import { pluginsWriters } from './writers/plugins.js';
+import { workflowsWriters } from './writers/workflows.js';
+import { commandsDetectors } from './detectors/commands.js';
+import { skillsDetectors } from './detectors/skills.js';
+import { hooksDetectors } from './detectors/hooks.js';
+import { rulesDetectors } from './detectors/rules.js';
+import { mcpDetectors } from './detectors/mcp.js';
+import { permissionsDetectors } from './detectors/permissions.js';
+import { subagentsDetectors } from './detectors/subagents.js';
+import { pluginsDetectors } from './detectors/plugins.js';
+import { workflowsDetectors } from './detectors/workflows.js';
+export { kindToCapability, ALL_RESOURCE_KINDS } from './writers/kinds.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const WRITERS = {
+    commands: commandsWriters,
+    skills: skillsWriters,
+    hooks: hooksWriters,
+    rules: rulesWriters,
+    mcp: mcpWriters,
+    permissions: permissionsWriters,
+    subagents: subagentsWriters,
+    plugins: pluginsWriters,
+    workflows: workflowsWriters,
+};
+/* eslint-enable @typescript-eslint/no-explicit-any */
+export const DETECTORS = {
+    commands: commandsDetectors,
+    skills: skillsDetectors,
+    hooks: hooksDetectors,
+    rules: rulesDetectors,
+    mcp: mcpDetectors,
+    permissions: permissionsDetectors,
+    subagents: subagentsDetectors,
+    plugins: pluginsDetectors,
+    workflows: workflowsDetectors,
+};
+/**
+ * Kinds excluded from the assertion. Skills + native-skills-dir agents are
+ * the only legitimate gap — Gemini reads `~/.agents/skills/` natively, so
+ * it deliberately has no per-version writer/detector. The orchestrator
+ * handles that case by clearing the version-home skills dir before launch.
+ * Anywhere else, a missing entry is a real bug.
+ */
+function isExempt(agent, kind) {
+    if (kind === 'skills' && AGENTS[agent].nativeAgentsSkillsDir)
+        return true;
+    return false;
+}
+let assertionFired = false;
+/**
+ * Verify every supported (agent, kind) pair has both a writer and a
+ * detector. Deferred from module-import time to the first `getWriter` /
+ * `getDetector` call to dodge the agents.ts ↔ versions.ts ↔ registry.ts
+ * import cycle (the same one the lazy writer/detector maps work around).
+ * Idempotent — runs at most once per process.
+ */
+export function assertRegistryComplete() {
+    if (assertionFired)
+        return;
+    assertionFired = true;
+    const missing = [];
+    for (const kind of ALL_RESOURCE_KINDS) {
+        const cap = kindToCapability(kind);
+        for (const agent of Object.keys(AGENTS)) {
+            if (!supports(agent, cap).ok)
+                continue;
+            if (isExempt(agent, kind))
+                continue;
+            const lacks = [];
+            if (!WRITERS[kind][agent])
+                lacks.push('writer');
+            if (!DETECTORS[kind][agent])
+                lacks.push('detector');
+            if (lacks.length > 0)
+                missing.push({ kind, agent, missing: lacks });
+        }
+    }
+    if (missing.length > 0) {
+        const detail = missing
+            .map((m) => `  - ${m.kind}/${m.agent}: missing ${m.missing.join(' and ')}`)
+            .join('\n');
+        throw new Error(`staleness/registry: missing required (kind, agent) entries:\n${detail}\n` +
+            `Fix: register the entry in src/lib/staleness/{writers,detectors}/<kind>.ts, OR ` +
+            `mark the capability false in AGENTS.${missing[0].agent}.capabilities.`);
+    }
+}
+/** Return the writer for (kind, agent), or undefined if unsupported. */
+export function getWriter(kind, agent) {
+    assertRegistryComplete();
+    return WRITERS[kind][agent];
+}
+/** Return the detector for (kind, agent), or undefined if unsupported. */
+export function getDetector(kind, agent) {
+    assertRegistryComplete();
+    return DETECTORS[kind][agent];
+}

package/dist/lib/staleness/writers/commands.d.ts

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const commandsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/commands.js

@@ -0,0 +1,111 @@
+/**
+ * Commands writer.
+ *
+ * Two physical formats, picked per-(agent, version) at write time:
+ *
+ *  - command-as-skill — fires when `shouldInstallCommandAsSkill(agent, version)`
+ *    is true. Used for grok (no native commands, but skills/) and Codex
+ *    >= 0.117.0 (commands capability ends, skills capability remains).
+ *    Writes `{agentDir}/skills/<name>/SKILL.md` with the `agents_command`
+ *    marker; the agent picks it up as a slash-command equivalent.
+ *
+ *  - native command file — `{agentDir}/<commandsSubdir>/<name>.md` (or .toml
+ *    when the agent's format is toml). Standard path for Claude, Codex
+ *    < 0.117.0, Gemini, Cursor, OpenCode, Copilot, Amp, Kiro, Roo,
+ *    Antigravity.
+ *
+ * Source resolution is `resolveCommandSource` (user → system → extras —
+ * project layer intentionally excluded).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { supports } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { markdownToToml } from '../../convert.js';
+import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
+import { installCommandSkillToVersion, shouldInstallCommandAsSkill } from '../../command-skills.js';
+import { resolveCommandSource, trustedSkillRoots } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildCommandsWriter(agent) {
+    return {
+        kind: 'commands',
+        agent,
+        write({ version, versionHome, selection }) {
+            const agentConfig = AGENTS[agent];
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+            const supportsCommands = supports(agent, 'commands', version).ok;
+            // Writers fire only after supports() OR commands-as-skills says yes —
+            // both paths produce a usable result here.
+            if (!commandsAsSkills && !supportsCommands) {
+                throw new Error(`commands writer reached for ${agent}@${version} with no path (cmd=false, asSkill=false)`);
+            }
+            const skillRoots = trustedSkillRoots();
+            const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
+            if (!commandsAsSkills) {
+                fs.mkdirSync(commandsTarget, { recursive: true });
+            }
+            const synced = [];
+            for (const cmd of selection) {
+                const srcFile = resolveCommandSource(cmd);
+                if (!srcFile)
+                    continue;
+                const metadata = parseCommandMetadata(srcFile);
+                if (!commandAppliesTo(agent, version, metadata).ok)
+                    continue;
+                if (commandsAsSkills) {
+                    const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillRoots);
+                    if (!installed.success)
+                        continue;
+                }
+                else if (agentConfig.format === 'toml') {
+                    const content = fs.readFileSync(srcFile, 'utf-8');
+                    const tomlContent = markdownToToml(cmd, content);
+                    fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
+                }
+                else {
+                    fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
+                }
+                synced.push(cmd);
+            }
+            return { synced };
+        },
+    };
+}
+// Built lazily on first access — see lazy-map.ts for the cycle rationale.
+//
+// Registration covers two cases:
+//   - native commands (claude, codex < 0.117.0, gemini, etc.) — `commands` cap
+//   - commands-as-skills (grok, codex >= 0.117.0)
+//
+// Agents that have skills but use a NATIVE non-file slash-command system
+// (openclaw → Gateway-based commands) are NOT registered. The signal is an
+// empty `commandsSubdir`: there's no directory to write to AND the agent
+// doesn't want commands-as-skills either (it has its own runtime command
+// resolver).
+export const commandsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const id of Object.keys(AGENTS)) {
+        const cfg = AGENTS[id];
+        if (cfg.capabilities.commands === false && (!cfg.skillsDir || cfg.skillsDir === ''))
+            continue;
+        // Native non-file slash-command runtime — no version-home write.
+        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '')) {
+            // Grok has empty commandsSubdir AND wants commands-as-skills.
+            // Distinguish: grok has skillsDir set; openclaw also has skillsDir, so we
+            // can't use that. The cleanest signal is the agent's `cliCommand` set —
+            // openclaw flags `commands: false` AND has its Gateway runtime, while
+            // grok flags `commands: false` because grok's slash commands are skills.
+            // We opt in explicitly: only grok takes commands-as-skills today.
+            if (id !== 'grok')
+                continue;
+        }
+        const hasCommands = cfg.capabilities.commands !== false;
+        const hasSkills = cfg.capabilities.skills !== false;
+        if (hasCommands || hasSkills) {
+            m[id] = buildCommandsWriter(id);
+        }
+    }
+    return m;
+});

package/dist/lib/staleness/writers/hooks.d.ts

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const hooksWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/hooks.js

@@ -0,0 +1,47 @@
+/**
+ * Hooks writer — copies trusted hook script files into `{agentDir}/hooks/`.
+ * Caller filters by `supports(agent, 'hooks', version)` before invoking.
+ * Orphan sweep (delete hooks in version-home that aren't in `availableNames`)
+ * stays in the orchestrator since it depends on the broader available set.
+ */
+import * as fs from 'fs';
+import { agentConfigDirName } from '../../agents.js';
+import * as path from 'path';
+import { capableAgents } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { registerHooksToSettings } from '../../hooks.js';
+import { resolveHookSource } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildHooksWriter(agent) {
+    return {
+        kind: 'hooks',
+        agent,
+        write({ versionHome, selection }) {
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const hooksTarget = path.join(agentDir, 'hooks');
+            fs.mkdirSync(hooksTarget, { recursive: true });
+            const synced = [];
+            for (const hook of selection) {
+                const srcFile = resolveHookSource(hook);
+                if (!srcFile)
+                    continue;
+                const destFile = safeJoin(hooksTarget, hook);
+                fs.copyFileSync(srcFile, destFile);
+                fs.chmodSync(destFile, 0o755);
+                synced.push(hook);
+            }
+            // Native hook registration in settings.json/hooks.json. Grok auto-
+            // discovers from ~/.grok/hooks/ so the file copy is sufficient.
+            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi') {
+                registerHooksToSettings(agent, versionHome);
+            }
+            return { synced };
+        },
+    };
+}
+export const hooksWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('hooks'))
+        m[agent] = buildHooksWriter(agent);
+    return m;
+});

package/dist/lib/staleness/writers/kinds.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical list of resource kinds dispatched through the writer/detector
+ * registry. Each name is the capability name on AgentConfig — except
+ * "permissions", which maps to the legacy capability name "allowlist".
+ */
+import type { CapabilityName } from '../../types.js';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
+export declare const ALL_RESOURCE_KINDS: readonly ResourceKind[];
+/** Map kind -> capability name on AgentConfig.capabilities. */
+export declare function kindToCapability(kind: ResourceKind): CapabilityName;

package/dist/lib/staleness/writers/kinds.js

@@ -0,0 +1,15 @@
+export const ALL_RESOURCE_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+    'plugins',
+    'workflows',
+];
+/** Map kind -> capability name on AgentConfig.capabilities. */
+export function kindToCapability(kind) {
+    return kind === 'permissions' ? 'allowlist' : kind;
+}

package/dist/lib/staleness/writers/lazy-map.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lazy-built per-agent map.
+ *
+ * The writer/detector modules form a circular dependency with agents.ts:
+ * agents.ts → versions.ts → staleness/registry.ts → writers/<kind>.ts →
+ * (capableAgents/AGENTS via capabilities or agents directly). If a writer
+ * module iterates AGENTS at module top-level it fires before the AGENTS
+ * const is initialized through the cycle. Wrapping the per-agent map in a
+ * lazily-evaluated Proxy defers every read until call time, by which point
+ * the cycle has resolved.
+ */
+import type { AgentId } from '../../types.js';
+export declare function lazyAgentMap<T>(build: () => Partial<Record<AgentId, T>>): Partial<Record<AgentId, T>>;

package/dist/lib/staleness/writers/lazy-map.js

@@ -0,0 +1,19 @@
+export function lazyAgentMap(build) {
+    let cache = null;
+    const ensure = () => {
+        if (!cache)
+            cache = build();
+        return cache;
+    };
+    return new Proxy({}, {
+        get(_t, prop) { return ensure()[prop]; },
+        has(_t, prop) { return prop in ensure(); },
+        ownKeys() { return Reflect.ownKeys(ensure()); },
+        getOwnPropertyDescriptor(_t, prop) {
+            const m = ensure();
+            if (prop in m)
+                return { configurable: true, enumerable: true, value: m[prop] };
+            return undefined;
+        },
+    });
+}

package/dist/lib/staleness/writers/mcp.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP writer — thin dispatcher into `installMcpServers` from `lib/mcp.ts`.
+ *
+ * The per-agent format handling (Claude CLI, Codex TOML, Cursor JSON, etc.)
+ * lives in lib/mcp.ts; we keep it there to avoid the import cycle with
+ * `versions.ts`. The writer simply hands the selection to that function.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const mcpWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/mcp.js

@@ -0,0 +1,19 @@
+import { capableAgents } from '../../capabilities.js';
+import { installMcpServers } from '../../mcp.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildMcpWriter(agent) {
+    return {
+        kind: 'mcp',
+        agent,
+        write({ version, versionHome, selection, cwd }) {
+            const r = installMcpServers(agent, version, versionHome, selection, { cwd });
+            return { synced: r.applied };
+        },
+    };
+}
+export const mcpWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('mcp'))
+        m[agent] = buildMcpWriter(agent);
+    return m;
+});

package/dist/lib/staleness/writers/permissions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Permissions writer — selection is a list of permission GROUP names. We
+ * build the PermissionSet from the discovered groups, then dispatch into the
+ * per-agent format writer in `lib/permissions.ts:applyPermissionsToVersion`.
+ *
+ * The per-agent format work lives in lib/permissions.ts because the format
+ * conversions (Claude settings.json vs Codex TOML+rules vs Gemini tools vs
+ * Antigravity permissions{} vs Grok [permission].rules) are tightly coupled
+ * to the converters defined alongside them.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const permissionsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/permissions.js

@@ -0,0 +1,26 @@
+import { capableAgents } from '../../capabilities.js';
+import { applyPermissionsToVersion as applyPermsToVersion, buildPermissionsFromGroups, } from '../../permissions.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildPermissionsWriter(agent) {
+    return {
+        kind: 'permissions',
+        agent,
+        write({ versionHome, selection }) {
+            if (selection.length === 0)
+                return { synced: [] };
+            const built = buildPermissionsFromGroups(selection);
+            const hasAllow = built.allow.length > 0;
+            const hasDeny = (built.deny?.length ?? 0) > 0;
+            if (!hasAllow && !hasDeny)
+                return { synced: [] };
+            const r = applyPermsToVersion(agent, built, versionHome, true);
+            return { synced: r.success ? selection : [] };
+        },
+    };
+}
+export const permissionsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('allowlist'))
+        m[agent] = buildPermissionsWriter(agent);
+    return m;
+});

package/dist/lib/staleness/writers/plugins.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Plugins writer — thin wrapper around `syncPluginToVersion`. Discovery and
+ * per-agent format work lives in lib/plugins.ts.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const pluginsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/plugins.js

@@ -0,0 +1,31 @@
+import { capableAgents } from '../../capabilities.js';
+import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills } from '../../plugins.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildPluginsWriter(agent) {
+    return {
+        kind: 'plugins',
+        agent,
+        write({ version, versionHome, selection }) {
+            const all = discoverPlugins();
+            const map = new Map(all.map(p => [p.name, p]));
+            // Clean orphan plugin-skills from plugins that no longer exist.
+            cleanOrphanedPluginSkills(agent, versionHome, new Set(all.map(p => p.name)));
+            const synced = [];
+            for (const name of selection) {
+                const plugin = map.get(name);
+                if (!plugin || !pluginSupportsAgent(plugin, agent))
+                    continue;
+                const r = syncPluginToVersion(plugin, agent, versionHome, { version });
+                if (r.success)
+                    synced.push(name);
+            }
+            return { synced };
+        },
+    };
+}
+export const pluginsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('plugins'))
+        m[agent] = buildPluginsWriter(agent);
+    return m;
+});

package/dist/lib/staleness/writers/rules.d.ts

@@ -0,0 +1,7 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export interface RulesSelection {
+    /** Preset name to compose. Empty string falls through to `"default"` in the composer. */
+    preset: string;
+}
+export declare const rulesWriters: Partial<Record<AgentId, ResourceWriter<RulesSelection>>>;

package/dist/lib/staleness/writers/rules.js

@@ -0,0 +1,55 @@
+/**
+ * Rules writer — composes one instruction file per supported agent.
+ *
+ * Single-target per agent (RulesCapability is `{ file: string } | false`).
+ * The composer in `lib/rules/compose.ts` handles all four layers
+ * (project > user > extras > system). We never write the project layer into
+ * the version home — it's resolved at agents-run time into the workspace
+ * AGENTS.md by `compileRulesForProject`.
+ *
+ * Selection shape: `{ preset: string }`. Use `getActiveRulesPreset(agent,
+ * version)` to derive the preset when the caller has no override.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { capableAgents } from '../../capabilities.js';
+import { composeRulesFromState } from '../../rules/compose.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildRulesWriter(agent) {
+    return {
+        kind: 'rules',
+        agent,
+        write({ versionHome, selection }) {
+            const cap = AGENTS[agent].capabilities.rules;
+            if (cap === false) {
+                throw new Error(`rules writer reached for ${agent} (rules: false)`);
+            }
+            const targetName = cap.file;
+            const composed = composeRulesFromState({ preset: selection.preset || undefined });
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            // `cap.file` is a trusted constant from AGENTS table; openclaw ships a
+            // nested path (`workspace/AGENTS.md`) so we use path.join rather than
+            // safeJoin (which rejects path separators in `name`).
+            const destFile = path.join(agentDir, targetName);
+            fs.mkdirSync(path.dirname(destFile), { recursive: true });
+            // Remove any pre-existing symlink before writing — a stale symlink
+            // could point at a deleted source and writeFileSync would chase it
+            // to nothing.
+            try {
+                const st = fs.lstatSync(destFile);
+                if (st.isSymbolicLink() || st.isFile())
+                    fs.unlinkSync(destFile);
+            }
+            catch { /* destination did not exist */ }
+            fs.writeFileSync(destFile, composed.content);
+            return { synced: [targetName] };
+        },
+    };
+}
+export const rulesWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('rules'))
+        m[agent] = buildRulesWriter(agent);
+    return m;
+});

package/dist/lib/staleness/writers/skills.d.ts

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const skillsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/skills.js

@@ -0,0 +1,81 @@
+/**
+ * Skills writer — copies each selected skill directory into
+ * `{agentDir}/skills/<name>/`. Agents flagged `nativeAgentsSkillsDir` (Gemini)
+ * read directly from `~/.agents/skills/` and have no writer registered; the
+ * sync orchestrator clears their version-home skills dir.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { capableAgents } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { resolveSkillSource } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        if (SKILL_COPY_IGNORE.has(entry.name))
+            continue;
+        const s = safeJoin(src, entry.name);
+        const d = safeJoin(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(s, d);
+        }
+        else if (entry.isFile()) {
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+function removePath(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (st.isSymbolicLink() || st.isFile())
+            fs.unlinkSync(p);
+        else if (st.isDirectory())
+            fs.rmSync(p, { recursive: true, force: true });
+    }
+    catch { /* already gone */ }
+}
+function buildSkillsWriter(agent) {
+    return {
+        kind: 'skills',
+        agent,
+        write({ versionHome, selection }) {
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const skillsTarget = path.join(agentDir, 'skills');
+            try {
+                if (fs.lstatSync(skillsTarget).isSymbolicLink()) {
+                    removePath(skillsTarget);
+                }
+            }
+            catch { /* does not exist yet */ }
+            fs.mkdirSync(skillsTarget, { recursive: true });
+            const synced = [];
+            for (const skill of selection) {
+                const srcDir = resolveSkillSource(skill);
+                if (!srcDir)
+                    continue;
+                const destDir = safeJoin(skillsTarget, skill);
+                removePath(destDir);
+                copyDir(srcDir, destDir);
+                synced.push(skill);
+            }
+            return { synced };
+        },
+    };
+}
+export const skillsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('skills')) {
+        // Agents that natively read ~/.agents/skills/ don't get a version-home
+        // write — the orchestrator clears the dir for them.
+        if (AGENTS[agent].nativeAgentsSkillsDir)
+            continue;
+        m[agent] = buildSkillsWriter(agent);
+    }
+    return m;
+});

package/dist/lib/staleness/writers/sources.d.ts

@@ -0,0 +1,16 @@
+export type EnabledExtra = {
+    alias: string;
+    dir: string;
+};
+/** Trusted source bases for content-like kinds. Project layer excluded. */
+export declare function trustedSourceBases(): {
+    dir: string;
+}[];
+/** Find the trusted source for a command markdown by name. */
+export declare function resolveCommandSource(name: string): string | null;
+/** Find the trusted source directory for a skill by name. */
+export declare function resolveSkillSource(name: string): string | null;
+/** Find the trusted source file for a hook by name. */
+export declare function resolveHookSource(name: string): string | null;
+/** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
+export declare function trustedSkillRoots(): string[];