@phnx-labs/agents-cli 1.14.3 → 1.14.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.14.5
+
+**Browser: custom binary and Electron app support**
+
+- Added `binary` field to browser profiles for specifying custom executable paths (e.g., Electron apps like Rush)
+- Added `electron` field to browser profiles — when true, uses existing windows instead of creating new ones (Electron doesn't support `Target.createTarget`)
+- New `custom` browser type that requires a binary path
+- Works with both local and SSH-based browser connections
+- Example profile for Rush: `agents browser profiles edit rush --browser custom --binary "/Applications/Rush.app/Contents/MacOS/Rush" --electron`
+
 ## Unreleased
 
 **System repo moved to `~/.agents-system`; `~/.agents` is now free for user-owned repos**

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/browser.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerBrowserSubcommands } from './commands/browser.js';
+const program = new Command();
+program.name('browser').description('Browser automation via CDP');
+registerBrowserSubcommands(program);
+program.parse();

package/dist/commands/browser.d.ts

@@ -1,2 +1,3 @@
 import { Command } from 'commander';
 export declare function registerBrowserCommand(program: Command): void;
+export declare function registerBrowserSubcommands(program: Command): void;

package/dist/commands/browser.js

@@ -8,6 +8,10 @@ export function registerBrowserCommand(program) {
     registerProfilesCommands(browser);
     registerTaskCommands(browser);
 }
+export function registerBrowserSubcommands(program) {
+    registerProfilesCommands(program);
+    registerTaskCommands(program);
+}
 function registerProfilesCommands(browser) {
     const profiles = browser
         .command('profiles')

package/dist/commands/teams.js

@@ -679,12 +679,14 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .description('Start a new team. No teammates yet; add them with `teams add`.')
         .option('-d, --description <text>', 'One-line summary of what this team is working on')
         .option('--enable-worktrees', 'Each teammate works in its own git worktree (requires --worktree on add)')
+        .option('--use-worktree <path>', 'All teammates share this existing worktree path (mutually exclusive with --enable-worktrees)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         try {
             const meta = await createTeam(team, {
                 description: opts.description,
                 enableWorktrees: opts.enableWorktrees,
+                useWorktree: opts.useWorktree,
             });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify({ team, ...meta }, null, 2));
@@ -694,7 +696,9 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             if (meta.description)
                 console.log(chalk.gray(`  ${meta.description}`));
             if (meta.enable_worktrees)
-                console.log(chalk.gray(`  worktrees: enabled`));
+                console.log(chalk.gray(`  worktrees: per-teammate`));
+            if (meta.use_worktree)
+                console.log(chalk.gray(`  worktree: ${meta.use_worktree}`));
             console.log();
             console.log(chalk.gray('Add your first teammate:'));
             if (meta.enable_worktrees) {
@@ -776,12 +780,30 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         }
         // Auto-create the team if it doesn't exist yet (friendlier UX than erroring).
         await ensureTeam(team);
-        // Check if team has worktrees enabled
+        // Check if team has worktrees enabled or a shared worktree
         const teamMeta = await getTeam(team);
         const worktreesEnabled = teamMeta?.enable_worktrees ?? false;
+        const sharedWorktree = teamMeta?.use_worktree ?? null;
         let worktreeName = null;
         let worktreePath = null;
-        if (worktreesEnabled) {
+        if (sharedWorktree) {
+            // Team uses a shared worktree for all teammates
+            const fsp = await import('fs/promises');
+            try {
+                const stat = await fsp.stat(sharedWorktree);
+                if (!stat.isDirectory()) {
+                    die(`Shared worktree path is not a directory: ${sharedWorktree}`);
+                }
+            }
+            catch {
+                die(`Shared worktree path does not exist: ${sharedWorktree}`);
+            }
+            worktreePath = sharedWorktree;
+            if (opts.worktree) {
+                die(`Team '${team}' uses --use-worktree (shared). Don't pass --worktree on add.`);
+            }
+        }
+        else if (worktreesEnabled) {
             if (!opts.worktree) {
                 die(`Team '${team}' has worktrees enabled. Use --worktree <name> to specify a worktree name.`);
             }

package/dist/commands/view.js

@@ -336,7 +336,7 @@ async function showInstalledVersions(filterAgentId) {
             const available = getAvailableResources();
             const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
             const newResources = getNewResources(available, synced);
-            if (hasNewResources(newResources, filterAgentId)) {
+            if (hasNewResources(newResources, filterAgentId, defaultVersion)) {
                 try {
                     const selection = await promptNewResourceSelection(filterAgentId, newResources);
                     if (selection && Object.keys(selection).length > 0) {

package/dist/lib/browser/chrome.d.ts

@@ -1,12 +1,12 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
-export declare function findBrowserPath(browserType: BrowserType): string;
+export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
 export interface LaunchResult {
     pid: number;
     port: number;
     wsUrl: string;
 }
-export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string): Promise<LaunchResult>;
+export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string): Promise<LaunchResult>;
 export declare function attachToChrome(port: number): Promise<string>;
 export declare function killChrome(pid: number): void;
 export declare function getRunningChromeInfo(profileName: string): {

package/dist/lib/browser/chrome.js

@@ -15,6 +15,7 @@ const BROWSER_PATHS = {
         chromium: ['/Applications/Chromium.app/Contents/MacOS/Chromium'],
         brave: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
         edge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        custom: [],
     },
     linux: {
         chrome: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable'],
@@ -22,6 +23,7 @@ const BROWSER_PATHS = {
         chromium: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
         brave: ['/usr/bin/brave-browser', '/usr/bin/brave'],
         edge: ['/usr/bin/microsoft-edge'],
+        custom: [],
     },
     win32: {
         chrome: [
@@ -36,9 +38,19 @@ const BROWSER_PATHS = {
         edge: [
             'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
         ],
+        custom: [],
     },
 };
-export function findBrowserPath(browserType) {
+export function findBrowserPath(browserType, customBinary) {
+    if (customBinary) {
+        if (!fs.existsSync(customBinary)) {
+            throw new Error(`Custom binary not found: ${customBinary}`);
+        }
+        return customBinary;
+    }
+    if (browserType === 'custom') {
+        throw new Error('browser: custom requires a binary path in the profile');
+    }
     const platform = os.platform();
     const platformPaths = BROWSER_PATHS[platform];
     if (!platformPaths) {
@@ -52,8 +64,8 @@ export function findBrowserPath(browserType) {
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
-export async function launchBrowser(profileName, browserType, port, options = {}, secrets) {
-    const browserPath = findBrowserPath(browserType);
+export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary) {
+    const browserPath = findBrowserPath(browserType, customBinary);
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });

package/dist/lib/browser/drivers/local.js

@@ -14,7 +14,7 @@ export async function connectLocal(endpoint, profile) {
     }
     catch {
         const newPort = allocatePort();
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets);
+        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets, profile.binary);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port: newPort, pid };

package/dist/lib/browser/drivers/ssh.js

@@ -12,7 +12,7 @@ export async function connectSSH(endpoint, profile) {
     const remotePort = parseInt(url.searchParams.get('port') || '9222', 10);
     const localPort = allocatePort();
     try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort);
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
     }
     catch {
         // Browser may already be running, continue
@@ -96,7 +96,7 @@ function tryConnect(port) {
         socket.on('error', reject);
     });
 }
-async function ensureRemoteBrowser(user, host, browserType, port) {
+async function ensureRemoteBrowser(user, host, browserType, port, customBinary) {
     const browserPaths = {
         chrome: '/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome',
         comet: '/Applications/Comet.app/Contents/MacOS/Comet',
@@ -104,9 +104,18 @@ async function ensureRemoteBrowser(user, host, browserType, port) {
         brave: '/Applications/Brave\\ Browser.app/Contents/MacOS/Brave\\ Browser',
         edge: '/Applications/Microsoft\\ Edge.app/Contents/MacOS/Microsoft\\ Edge',
     };
-    const browserPath = browserPaths[browserType];
-    if (!browserPath) {
-        throw new Error(`Unknown browser type: ${browserType}`);
+    let browserPath;
+    if (customBinary) {
+        browserPath = customBinary.replace(/ /g, '\\ ');
+    }
+    else if (browserType === 'custom') {
+        throw new Error('browser: custom requires a binary path in the profile');
+    }
+    else {
+        browserPath = browserPaths[browserType];
+        if (!browserPath) {
+            throw new Error(`Unknown browser type: ${browserType}`);
+        }
     }
     const remoteCmd = `${browserPath} --remote-debugging-port=${port} '--remote-allow-origins=*' --disable-background-timer-throttling --user-data-dir=/tmp/agents-browser-${port} </dev/null >/dev/null 2>&1 &`;
     return new Promise((resolve, reject) => {

package/dist/lib/browser/service.js

@@ -28,7 +28,7 @@ export class BrowserService {
             const task = conn.tasks.get(finalTaskId);
             return { task: finalTaskId, windowTargetId: task.windowTargetId };
         }
-        const { windowTargetId } = await this.createTaskWindow(conn.cdp, finalTaskId);
+        const { windowTargetId } = await this.createTaskWindow(conn, finalTaskId);
         const task = {
             id: finalTaskId,
             profile: profileName,
@@ -88,6 +88,19 @@ export class BrowserService {
     }
     async navigate(taskId, url, profileName) {
         const { conn, task } = await this.findTask(taskId, profileName);
+        if (conn.electron) {
+            const tabId = task.windowTargetId || task.tabIds[0];
+            if (!tabId) {
+                throw new Error('No existing tab to navigate in Electron app');
+            }
+            const sessionId = await this.getSessionId(conn, tabId);
+            await conn.cdp.send('Page.navigate', { url }, sessionId);
+            if (!task.tabIds.includes(tabId)) {
+                task.tabIds.push(tabId);
+            }
+            await this.saveTaskState(task.profile, conn.tasks);
+            return { tabId, url };
+        }
         const result = (await conn.cdp.send('Target.createTarget', {
             url,
         }));
@@ -255,6 +268,7 @@ export class BrowserService {
                 cdp,
                 port: existingInfo.port,
                 pid: existingInfo.pid,
+                electron: profile.electron,
                 tasks,
                 sessionCache: new Map(),
             };
@@ -280,6 +294,7 @@ export class BrowserService {
                 cdp: conn.cdp,
                 port: conn.port,
                 pid: conn.pid,
+                electron: profile.electron,
                 tasks: conn.pid === 0 ? this.loadTaskState(profile.name) : new Map(),
                 sessionCache: new Map(),
             };
@@ -291,6 +306,7 @@ export class BrowserService {
                 cdp: conn.cdp,
                 port: conn.port,
                 pid: conn.pid,
+                electron: profile.electron,
                 tasks: new Map(),
                 sessionCache: new Map(),
             };
@@ -300,8 +316,13 @@ export class BrowserService {
     async enableDomains(cdp) {
         await cdp.send('Target.setDiscoverTargets', { discover: true });
     }
-    async createTaskWindow(cdp, _taskId) {
-        const result = (await cdp.send('Target.createTarget', {
+    async createTaskWindow(conn, _taskId) {
+        if (conn.electron) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            const pageTarget = targetInfos.find((t) => t.type === 'page');
+            return { windowTargetId: pageTarget?.targetId };
+        }
+        const result = (await conn.cdp.send('Target.createTarget', {
             url: 'about:blank',
             newWindow: true,
         }));

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

@@ -1,8 +1,10 @@
-export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge';
+export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
 export interface BrowserProfile {
     name: string;
     description?: string;
     browser: BrowserType;
+    binary?: string;
+    electron?: boolean;
     endpoints: string[];
     chrome?: ChromeOptions;
     secrets?: string;

package/dist/lib/migrate.js

@@ -152,6 +152,49 @@ function migrateUserVersionsToSystem() {
         console.log(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents-system/versions/ (kept legacy copy at ~/.agents/versions/)`);
     }
 }
+/**
+ * Move ~/. agents/runs/ -> ~/.agents/routines/runs/.
+ * Runs now live inside routines directory for cleaner organization.
+ */
+function migrateRunsIntoRoutines() {
+    const src = path.join(USER_DIR, 'runs');
+    const dest = path.join(USER_DIR, 'routines', 'runs');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        fs.renameSync(src, dest);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents/trash/ -> ~/.agents/.trash/.
+ * Hide the trash directory.
+ */
+function migrateTrashToHidden() {
+    const src = path.join(USER_DIR, 'trash');
+    const dest = path.join(USER_DIR, '.trash');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents/backups/ -> ~/.agents/.backups/.
+ * Hide the backups directory.
+ */
+function migrateBackupsToHidden() {
+    const src = path.join(USER_DIR, 'backups');
+    const dest = path.join(USER_DIR, '.backups');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch { /* best-effort */ }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export function runMigration() {
     migrateAgentsYaml();
@@ -159,4 +202,7 @@ export function runMigration() {
     migrateSystemConfigJson();
     migratePromptcutsIntoHooks();
     migrateUserVersionsToSystem();
+    migrateRunsIntoRoutines();
+    migrateTrashToHidden();
+    migrateBackupsToHidden();
 }

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

@@ -0,0 +1,46 @@
+/**
+ * Commands resource handler.
+ *
+ * Commands are slash-command definitions stored as .md files (Claude/Codex/Cursor/OpenCode)
+ * or .toml files (Gemini). This handler resolves commands across layers (project > user > system),
+ * handles format conversion during sync, and provides consistent list/resolve/sync behavior.
+ */
+import type { AgentId, ResolvedItem, ResourceHandler, ResourceKind } from './types.js';
+/** Command item metadata. */
+export interface CommandItem {
+    name: string;
+    description: string;
+    content: string;
+    format: 'md' | 'toml';
+}
+/**
+ * Commands resource handler implementing ResourceHandler<CommandItem>.
+ */
+export declare class CommandsHandler implements ResourceHandler<CommandItem> {
+    readonly kind: ResourceKind;
+    /**
+     * List all commands across layers, with higher layer winning on name conflict.
+     * Returns a union of all commands, deduplicated by name.
+     */
+    listAll(agent: AgentId, cwd?: string): ResolvedItem<CommandItem>[];
+    /**
+     * Resolve a single command by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(agent: AgentId, name: string, cwd?: string): ResolvedItem<CommandItem> | null;
+    /**
+     * Sync resolved commands to the agent's version home directory.
+     * Copies/transforms commands 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';
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(agent: AgentId): string;
+}
+/** Singleton instance of the commands handler. */
+export declare const commandsHandler: CommandsHandler;

package/dist/lib/resources/commands.js

@@ -0,0 +1,208 @@
+/**
+ * Commands resource handler.
+ *
+ * Commands are slash-command definitions stored as .md files (Claude/Codex/Cursor/OpenCode)
+ * or .toml files (Gemini). This handler resolves commands across layers (project > user > system),
+ * handles format conversion during sync, and provides consistent list/resolve/sync behavior.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from '../state.js';
+import { AGENTS } from '../agents.js';
+import { markdownToToml } from '../convert.js';
+/**
+ * Get the commands directory for a given layer root.
+ */
+function getCommandsDirForRoot(root) {
+    return path.join(root, 'commands');
+}
+/**
+ * Parse a command file and extract metadata.
+ */
+function parseCommandFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const format = filePath.endsWith('.toml') ? 'toml' : 'md';
+        const name = path.basename(filePath).replace(/\.(md|toml)$/, '');
+        let description = '';
+        if (format === 'md') {
+            // Parse YAML frontmatter for description
+            const lines = content.split('\n');
+            if (lines[0] === '---') {
+                const endIndex = lines.slice(1).findIndex((l) => l === '---');
+                if (endIndex > 0) {
+                    const frontmatter = lines.slice(1, endIndex + 1).join('\n');
+                    const descMatch = frontmatter.match(/description:\s*(.+)/i);
+                    if (descMatch)
+                        description = descMatch[1].trim();
+                }
+            }
+        }
+        else {
+            // Parse TOML for description
+            const descMatch = content.match(/description\s*=\s*"([^"]+)"/);
+            if (descMatch)
+                description = descMatch[1];
+        }
+        return { name, description, content, format };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List command files in a directory.
+ */
+function listCommandsInDir(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const commands = [];
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                if (entry.name.endsWith('.md')) {
+                    commands.push({
+                        name: entry.name.replace('.md', ''),
+                        path: path.join(dir, entry.name),
+                        format: 'md',
+                    });
+                }
+                else if (entry.name.endsWith('.toml')) {
+                    commands.push({
+                        name: entry.name.replace('.toml', ''),
+                        path: path.join(dir, entry.name),
+                        format: 'toml',
+                    });
+                }
+            }
+        }
+        return commands;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Commands resource handler implementing ResourceHandler<CommandItem>.
+ */
+export class CommandsHandler {
+    kind = 'command';
+    /**
+     * List all commands across layers, with higher layer winning on name conflict.
+     * Returns a union of all commands, deduplicated by name.
+     */
+    listAll(agent, cwd) {
+        const seen = new Set();
+        const results = [];
+        const projectDir = getProjectAgentsDir(cwd);
+        const extraRepos = getEnabledExtraRepos();
+        // Build layer roots in precedence order: project > user > system > extras
+        const roots = [];
+        if (projectDir) {
+            roots.push({ dir: getCommandsDirForRoot(projectDir), layer: 'project' });
+        }
+        roots.push({ dir: getCommandsDirForRoot(getUserAgentsDir()), layer: 'user' });
+        roots.push({ dir: getCommandsDirForRoot(getSystemAgentsDir()), layer: 'system' });
+        for (const extra of extraRepos) {
+            roots.push({ dir: getCommandsDirForRoot(extra.dir), layer: 'system' });
+        }
+        for (const { dir, layer } of roots) {
+            const commands = listCommandsInDir(dir);
+            for (const cmd of commands) {
+                if (seen.has(cmd.name))
+                    continue;
+                seen.add(cmd.name);
+                const item = parseCommandFile(cmd.path);
+                if (item) {
+                    results.push({
+                        name: cmd.name,
+                        item,
+                        layer,
+                        path: cmd.path,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Resolve a single command by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(agent, name, cwd) {
+        const projectDir = getProjectAgentsDir(cwd);
+        const extraRepos = getEnabledExtraRepos();
+        // Build candidate paths in precedence order
+        const candidates = [];
+        if (projectDir) {
+            candidates.push({ dir: getCommandsDirForRoot(projectDir), layer: 'project' });
+        }
+        candidates.push({ dir: getCommandsDirForRoot(getUserAgentsDir()), layer: 'user' });
+        candidates.push({ dir: getCommandsDirForRoot(getSystemAgentsDir()), layer: 'system' });
+        for (const extra of extraRepos) {
+            candidates.push({ dir: getCommandsDirForRoot(extra.dir), layer: 'system' });
+        }
+        for (const { dir, layer } of candidates) {
+            // Try .md first, then .toml
+            for (const ext of ['.md', '.toml']) {
+                const filePath = path.join(dir, `${name}${ext}`);
+                const item = parseCommandFile(filePath);
+                if (item) {
+                    return { name, item, layer, path: filePath };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Sync resolved commands to the agent's version home directory.
+     * Copies/transforms commands as needed for the agent's expected format.
+     */
+    sync(agent, versionHome, cwd) {
+        const agentConfig = AGENTS[agent];
+        const targetFormat = this.format(agent);
+        const targetDir = path.join(versionHome, `.${agent}`, this.targetDir(agent));
+        // Ensure target directory exists
+        fs.mkdirSync(targetDir, { recursive: true });
+        // Get all resolved commands
+        const commands = this.listAll(agent, cwd);
+        for (const resolved of commands) {
+            const ext = targetFormat === 'toml' ? '.toml' : '.md';
+            const targetPath = path.join(targetDir, `${resolved.name}${ext}`);
+            // Convert format if needed
+            if (targetFormat === 'toml' && resolved.item.format === 'md') {
+                // Convert markdown to TOML
+                const tomlContent = markdownToToml(resolved.name, resolved.item.content);
+                fs.writeFileSync(targetPath, tomlContent, 'utf-8');
+            }
+            else if (targetFormat === 'md' && resolved.item.format === 'toml') {
+                // For now, copy TOML as-is if target expects md (edge case)
+                // In practice, source commands are always .md
+                fs.copyFileSync(resolved.path, targetPath);
+            }
+            else {
+                // Same format, copy directly
+                fs.copyFileSync(resolved.path, targetPath);
+            }
+        }
+    }
+    /**
+     * Get the file format this resource uses for a given agent.
+     */
+    format(agent) {
+        const agentConfig = AGENTS[agent];
+        return agentConfig.format === 'toml' ? 'toml' : 'md';
+    }
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(agent) {
+        const agentConfig = AGENTS[agent];
+        return agentConfig.commandsSubdir || 'commands';
+    }
+}
+/** Singleton instance of the commands handler. */
+export const commandsHandler = new CommandsHandler();

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

@@ -0,0 +1,12 @@
+/**
+ * HooksHandler - ResourceHandler implementation for hooks.
+ *
+ * Hooks are declared in hooks.yaml at each layer (system, user, project).
+ * Resolution: project > user > system (higher layer wins on name conflict).
+ * Non-conflicting hooks from all layers are unioned together.
+ */
+import type { ResourceHandler } from './types.js';
+import type { ManifestHook } from '../types.js';
+export type HookItem = ManifestHook;
+export declare const HooksHandler: ResourceHandler<HookItem>;
+export default HooksHandler;