@phnx-labs/agents-cli 1.15.0 → 1.17.0

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

@@ -11,17 +11,26 @@ export interface BrowserProfile {
     viewport?: {
         width: number;
         height: number;
+        x?: number;
+        y?: number;
     };
 }
 export interface ChromeOptions {
     headless?: boolean;
     args?: string[];
+    viewport?: {
+        width: number;
+        height: number;
+        x?: number;
+        y?: number;
+    };
 }
 export interface Task {
     id: string;
+    name: string;
     profile: string;
-    windowTargetId?: string;
-    tabIds: string[];
+    tabs: Record<string, string>;
+    currentTabId?: string;
     createdAt: number;
     pid: number;
 }
@@ -36,17 +45,39 @@ export interface ProfileStatus {
     running: boolean;
     port?: number;
     pid?: number;
+    /** The port declared in the profile's first endpoint, when it differs from the running port. */
+    configuredPort?: number;
     tasks: TaskStatus[];
 }
 export interface TaskStatus {
     id: string;
+    name: string;
     tabCount: number;
+    currentTabId?: string;
     createdAt: number;
+    endedAt?: number;
+    domains?: string[];
+    tabs?: Array<{
+        id: string;
+        url: string;
+        title?: string;
+        current?: boolean;
+    }>;
 }
-export type IPCAction = 'start' | 'stop' | 'status' | 'navigate' | 'tabs' | 'close' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover';
+export interface HistoricalTask {
+    id: string;
+    name: string;
+    profile: string;
+    createdAt: number;
+    endedAt: number;
+    domains: string[];
+    tabCount: number;
+}
+export type IPCAction = 'start' | 'launch-profile' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
+    taskName?: string;
     profile?: string;
     url?: string;
     tabId?: string;
@@ -55,8 +86,26 @@ export interface IPCRequest {
     ref?: number;
     text?: string;
     key?: string;
+    scrollX?: number;
+    scrollY?: number;
+    scrollAtX?: number;
+    scrollAtY?: number;
     interactive?: boolean;
     limit?: number;
+    width?: number;
+    height?: number;
+    deviceName?: string;
+    mobile?: boolean;
+    deviceScaleFactor?: number;
+    level?: 'log' | 'info' | 'warn' | 'error';
+    clear?: boolean;
+    filter?: string;
+    urlPattern?: string;
+    maxChars?: number;
+    waitType?: 'time' | 'selector' | 'url' | 'function' | 'load';
+    waitValue?: string | number;
+    timeout?: number;
+    downloadPath?: string;
 }
 export interface IPCResponse {
     ok: boolean;
@@ -66,10 +115,49 @@ export interface IPCResponse {
     windowTargetId?: string;
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
+    history?: HistoricalTask[];
     result?: unknown;
     path?: string;
     refs?: string;
+    port?: number;
+    pid?: number;
+    logs?: ConsoleEntry[];
+    errors?: ErrorEntry[];
+    requests?: NetworkRequest[];
+    body?: string;
+    downloadPath?: string;
+    devices?: string[];
+}
+export interface ConsoleEntry {
+    level: 'log' | 'info' | 'warn' | 'error';
+    text: string;
+    timestamp: number;
+    url?: string;
+    line?: number;
+}
+export interface ErrorEntry {
+    message: string;
+    stack?: string;
+    timestamp: number;
+    url?: string;
+    line?: number;
+}
+export interface NetworkRequest {
+    id: string;
+    url: string;
+    method: string;
+    status?: number;
+    mimeType?: string;
+    timestamp: number;
+}
+export interface DeviceDescriptor {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    mobile: boolean;
 }
 export declare const TASK_ID_REGEX: RegExp;
 export declare function isValidTaskId(id: string): boolean;
 export declare function generateTaskId(): string;
+export declare function generateShortId(): string;
+export declare function generateFunName(): string;

package/dist/lib/browser/types.js

@@ -5,3 +5,19 @@ export function isValidTaskId(id) {
 export function generateTaskId() {
     return crypto.randomUUID().slice(0, 8);
 }
+export function generateShortId() {
+    return crypto.randomUUID().split('-')[0]; // 8 chars
+}
+const ADJECTIVES = [
+    'swift', 'cosmic', 'jolly', 'quiet', 'bold', 'bright', 'calm', 'eager',
+    'golden', 'happy', 'keen', 'lucky', 'noble', 'proud', 'quick', 'royal',
+];
+const NOUNS = [
+    'falcon', 'comet', 'tiger', 'nebula', 'phoenix', 'river', 'summit', 'wave',
+    'aurora', 'breeze', 'crystal', 'dragon', 'ember', 'forest', 'glacier', 'harbor',
+];
+export function generateFunName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    return `${adj}-${noun}`;
+}

package/dist/lib/cloud/rush.d.ts

@@ -5,6 +5,8 @@
  * Requires the Rush GitHub App installed on the target repo.
  */
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+export declare const RUSH_CONSENT_PATH: string;
+export declare function hasRushUploadConsent(opts?: DispatchOptions): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
 export interface AccountManifestEntry {
     version: string;
@@ -35,7 +37,7 @@ export interface AccountTokenEntry {
  * Returns null when no Claude versions are signed in (the dispatch falls back
  * to the platform-wide key, current behavior).
  */
-export declare function buildAccountManifest(): Promise<AccountManifest | null>;
+export declare function buildAccountManifest(strategy?: string): Promise<AccountManifest | null>;
 /**
  * Re-load OAuth blobs for the given versions so they can be uploaded to the
  * server on a retry. Only the versions named in the manifest are loaded — we
@@ -52,6 +54,7 @@ export declare function buildDispatchBody(input: {
     agent?: string;
     prompt: string;
     mode?: string;
+    strategy?: string;
     resolvedRepos: Array<{
         installation_id: number;
         repo_owner: string;
@@ -60,6 +63,30 @@ export declare function buildDispatchBody(input: {
     accountManifest?: AccountManifest | null;
     accountTokens?: AccountTokenEntry[] | null;
 }): Record<string, unknown>;
+/** A single account registered in Rush Cloud's multi-account rotation pool. */
+export interface RemoteAccount {
+    id: string;
+    provider: string;
+    email: string | null;
+    subscription_type: string | null;
+    five_hour_pct: number | null;
+    seven_day_pct: number | null;
+    usage_fetched_at: string | null;
+    created_at: string;
+}
+/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
+export declare function listRemoteAccounts(): Promise<RemoteAccount[]>;
+/**
+ * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
+ * The server validates the token against the Anthropic usage API and stores it
+ * encrypted in Vault. Returns the account metadata (no token).
+ */
+export declare function addRemoteAccount(provider: string, pastedToken: string): Promise<RemoteAccount & {
+    five_hour_pct: number | null;
+    seven_day_pct: number | null;
+}>;
+/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
+export declare function removeRemoteAccount(id: string): Promise<void>;
 export declare class RushCloudProvider implements CloudProvider {
     id: "rush";
     name: string;

package/dist/lib/cloud/rush.js

@@ -9,20 +9,21 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import * as yaml from 'yaml';
-import { getUserAgentsDir } from '../state.js';
+import { getCloudDir } from '../state.js';
 import { resolveDispatchRepos } from './types.js';
 import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
 import { getAccountInfo } from '../agents.js';
 import { loadClaudeOauth } from '../usage.js';
+import { selectBalancedVersion } from '../rotate.js';
 const PROXY_BASE = 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
-const RUSH_CONSENT_PATH = path.join(getUserAgentsDir(), 'cloud', 'rush-consent.json');
+export const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
-function hasRushUploadConsent(opts) {
+export function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')
         return true;
     const po = opts?.providerOptions;
@@ -184,20 +185,37 @@ async function readClaudeCredentialsBlob(home) {
  * Returns null when no Claude versions are signed in (the dispatch falls back
  * to the platform-wide key, current behavior).
  */
-export async function buildAccountManifest() {
-    const versions = listInstalledVersions('claude');
-    if (versions.length === 0)
-        return null;
+export async function buildAccountManifest(strategy) {
+    let candidateVersions;
+    if (strategy === 'balanced') {
+        // Use the same health-checked, deduped-by-email set that `agents run --balanced` uses.
+        // `result.healthy` contains one candidate per unique email, ordered by remaining capacity.
+        const result = await selectBalancedVersion('claude');
+        if (!result || result.healthy.length === 0)
+            return null;
+        candidateVersions = result.healthy
+            .filter((c) => !!c.email)
+            .map((c) => ({ version: c.version, email: c.email }));
+    }
+    else {
+        // Default: all installed versions that have a signed-in account.
+        const versions = listInstalledVersions('claude');
+        if (versions.length === 0)
+            return null;
+        const rows = await Promise.all(versions.map(async (version) => {
+            const home = getVersionHomePath('claude', version);
+            const info = await getAccountInfo('claude', home);
+            return info.email ? { version, email: info.email } : null;
+        }));
+        candidateVersions = rows.filter((r) => r !== null);
+    }
     const entries = [];
-    for (const version of versions) {
+    for (const { version, email } of candidateVersions) {
         const home = getVersionHomePath('claude', version);
-        const info = await getAccountInfo('claude', home);
-        if (!info.email)
-            continue;
         const blob = await readClaudeCredentialsBlob(home);
         if (!blob)
             continue;
-        entries.push({ version, email: info.email, cred_fp: sha256(blob) });
+        entries.push({ version, email, cred_fp: sha256(blob) });
     }
     if (entries.length === 0)
         return null;
@@ -237,6 +255,7 @@ export function buildDispatchBody(input) {
         prompt: input.prompt,
         repos: input.resolvedRepos,
         mode: input.mode,
+        ...(input.strategy ? { strategy: input.strategy } : {}),
     };
     if (input.resolvedRepos.length === 1) {
         body.installation_id = primary.installation_id;
@@ -251,6 +270,37 @@ export function buildDispatchBody(input) {
     }
     return body;
 }
+/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
+export async function listRemoteAccounts() {
+    const token = readToken();
+    const res = await api('GET', '/api/v1/cloud-accounts', token);
+    if (!res.ok) {
+        throw new Error(`Failed to list accounts (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    const data = await res.json();
+    return data.accounts ?? [];
+}
+/**
+ * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
+ * The server validates the token against the Anthropic usage API and stores it
+ * encrypted in Vault. Returns the account metadata (no token).
+ */
+export async function addRemoteAccount(provider, pastedToken) {
+    const token = readToken();
+    const res = await api('POST', '/api/v1/cloud-accounts', token, { provider, token: pastedToken });
+    if (!res.ok) {
+        throw new Error(`Failed to add account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    return await res.json();
+}
+/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
+export async function removeRemoteAccount(id) {
+    const token = readToken();
+    const res = await api('DELETE', `/api/v1/cloud-accounts/${encodeURIComponent(id)}`, token);
+    if (!res.ok) {
+        throw new Error(`Failed to remove account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+}
 export class RushCloudProvider {
     id = 'rush';
     name = 'Rush Cloud';
@@ -289,13 +339,18 @@ export class RushCloudProvider {
             repo_owner: r.owner,
             repo_name: r.name,
         })));
-        const accountManifest = await buildAccountManifest();
+        const strategy = options.providerOptions?.strategy;
+        // When balanced, the server owns the pool and rotates internally — no
+        // client-side manifest needed. We just forward the strategy so the server
+        // knows to load from Vault instead of waiting for a manifest.
+        const accountManifest = strategy === 'balanced' ? null : await buildAccountManifest();
         const body = buildDispatchBody({
             agent: options.agent,
             prompt: options.prompt,
             mode: options.providerOptions?.mode,
             resolvedRepos,
             accountManifest,
+            strategy,
         });
         let res = await api('POST', '/api/v1/cloud-runs', token, body);
         // Server detects drift (new account or rotated token) by comparing the
@@ -317,7 +372,7 @@ export class RushCloudProvider {
                         ``,
                         `To consent, re-run with one of:`,
                         `  AGENTS_RUSH_UPLOAD_TOKENS=1 agents cloud run ...`,
-                        `  agents cloud run --upload-account-tokens ...   # if your CLI exposes this flag`,
+                        `  agents cloud run --upload-account-tokens ...`,
                         ``,
                         `Consent will be recorded at ${RUSH_CONSENT_PATH} so you won't be asked again.`,
                         `Remove that file to revoke.`,

package/dist/lib/cloud/store.js

@@ -8,8 +8,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getUserAgentsDir } from '../state.js';
-const CLOUD_DIR = path.join(getUserAgentsDir(), 'cloud');
+import { getCloudDir } from '../state.js';
+const CLOUD_DIR = getCloudDir();
 const DB_PATH = path.join(CLOUD_DIR, 'tasks.db');
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS tasks (

package/dist/lib/commands.d.ts

@@ -35,10 +35,6 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
-/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
-/** Validate command metadata, returning errors and warnings. */
-export declare function validateCommandMetadata(metadata: CommandMetadata | null, commandName: string): ValidationResult;
 /** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
 /** Find the source path for a command in a repository. */
@@ -79,6 +75,7 @@ export declare function installCommandToVersion(agent: AgentId, version: string,
 };
 /**
  * Remove a single command from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/commands/.
  */
 export declare function removeCommandFromVersion(agent: AgentId, version: string, commandName: string): {
     success: boolean;
@@ -97,17 +94,6 @@ export declare function iterCommandsCapableVersions(filter?: {
 }>;
 /** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
-/** List command names installed for an agent in the active version home. */
-export declare function listInstalledCommands(agentId: AgentId): string[];
-/**
- * Check if a command exists for an agent.
- */
-export declare function commandExists(agentId: AgentId, commandName: string): boolean;
-/**
- * Check if installed command content matches source content.
- * Handles format conversion (markdown to TOML for Gemini).
- */
-export declare function commandContentMatches(agentId: AgentId, commandName: string, sourcePath: string): boolean;
 /**
  * List installed commands with scope information.
  * Pass options.home to read from a version-managed agent's home directory.

package/dist/lib/commands.js

@@ -11,11 +11,11 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
 import { markdownToToml } from './convert.js';
-import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir } from './state.js';
+import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 /** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export function parseCommandMetadata(filePath) {
+function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
@@ -51,7 +51,7 @@ export function parseCommandMetadata(filePath) {
     }
 }
 /** Validate command metadata, returning errors and warnings. */
-export function validateCommandMetadata(metadata, commandName) {
+function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
     if (!metadata) {
@@ -279,6 +279,7 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
 }
 /**
  * Remove a single command from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/commands/.
  */
 export function removeCommandFromVersion(agent, version, commandName) {
     const versionHome = getVersionHomePath(agent, version);
@@ -292,7 +293,10 @@ export function removeCommandFromVersion(agent, version, commandName) {
         return { success: true };
     }
     try {
-        fs.unlinkSync(targetPath);
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const trashDir = path.join(getTrashCommandsDir(), agent, version, commandName);
+        fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+        fs.renameSync(targetPath, path.join(trashDir, `${commandName}${ext}.${stamp}`));
     }
     catch (err) {
         return { success: false, error: err.message };
@@ -332,7 +336,7 @@ export function uninstallCommand(agentId, commandName) {
     return false;
 }
 /** List command names installed for an agent in the active version home. */
-export function listInstalledCommands(agentId) {
+function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -348,7 +352,7 @@ export function listInstalledCommands(agentId) {
 /**
  * Check if a command exists for an agent.
  */
-export function commandExists(agentId, commandName) {
+function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -366,7 +370,7 @@ function normalizeContent(content) {
  * Check if installed command content matches source content.
  * Handles format conversion (markdown to TOML for Gemini).
  */
-export function commandContentMatches(agentId, commandName, sourcePath) {
+function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);

package/dist/lib/daemon.js

@@ -10,13 +10,12 @@ import { spawn, execSync, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { getAgentsDir } from './state.js';
+import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
-const DAEMON_DIR = 'helpers/daemon';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -25,7 +24,7 @@ const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 function getDaemonDir() {
-    const dir = path.join(getAgentsDir(), DAEMON_DIR);
+    const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }

package/dist/lib/doctor-diff.js

@@ -22,7 +22,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPromptcutsPath, } from './state.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
@@ -426,10 +426,10 @@ function diffPresenceOnly(kind, available, synced) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 function diffPromptcuts() {
-    const exists = fs.existsSync(getPromptcutsPath());
-    if (!exists)
+    const sourcePath = getEffectivePromptcutsPath();
+    if (!fs.existsSync(sourcePath))
         return [];
-    return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath: getPromptcutsPath() }];
+    return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath }];
 }
 export function diffVersionResources(agent, version, options = {}) {
     const cwd = options.cwd ?? process.cwd();

package/dist/lib/events.js

@@ -15,8 +15,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 // ─── Constants ────────────────────────────────────────────────────────────────
-const USER_AGENTS_DIR = path.join(os.homedir(), '.agents');
-const LOGS_DIR = path.join(USER_AGENTS_DIR, 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry.
+const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 30;
 /** Default max length for truncated strings. */

package/dist/lib/hooks.d.ts

@@ -66,6 +66,7 @@ export declare function installHookToVersion(agent: AgentId, version: string, ho
 };
 /**
  * Remove a single hook (script + data file) from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/hooks/.
  */
 export declare function removeHookFromVersion(agent: AgentId, version: string, hookName: string): {
     success: boolean;
@@ -113,10 +114,11 @@ export declare function installHooksCentrally(source: string): Promise<{
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse hooks.yaml manifests. Reads BOTH system (~/.agents-system/hooks.yaml)
- * and user (~/.agents/hooks.yaml), merging with user-wins-on-key-collision
- * precedence. A user entry with `enabled: false` disables the system-shipped
- * hook of the same name without forking the system file.
+ * Parse hook manifests. Reads system hooks from ~/.agents-system/hooks.yaml
+ * (npm-shipped defaults) and user hooks from the `hooks:` section of
+ * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
+ * A user entry with `enabled: false` disables the system-shipped hook of
+ * the same name without forking the system file.
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
@@ -124,10 +126,12 @@ export declare function parseHookManifest(): Record<string, ManifestHook>;
 /**
  * Register hooks as lifecycle events in an agent's config.
  * Reads hooks.yaml manifest, merges into the agent's config file(s).
- * Only manages hooks whose command paths are under ~/.agents/hooks/.
- * Does not remove user-added hooks.
+ * Only manages hooks whose command paths are under ~/.agents/hooks/ or
+ * ~/.agents-system/hooks/. Does not remove user-added hooks.
  *
- * @param agentsDirOverride - Override the agents dir (used in tests to inject a temp path).
+ * @param agentsDirOverride - When provided, treats this single dir as the
+ *   only managed hook root. Used by tests to inject a temp path. In normal
+ *   operation, both user and system roots are consulted with user precedence.
  */
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];