@phnx-labs/agents-cli 1.14.7 → 1.16.0

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

@@ -16,12 +16,17 @@ export interface BrowserProfile {
 export interface ChromeOptions {
     headless?: boolean;
     args?: string[];
+    viewport?: {
+        width: number;
+        height: 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 +41,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' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | '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;
@@ -57,6 +84,20 @@ export interface IPCRequest {
     key?: string;
     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 +107,47 @@ export interface IPCResponse {
     windowTargetId?: string;
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
+    history?: HistoricalTask[];
     result?: unknown;
     path?: string;
     refs?: string;
+    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.js

@@ -9,7 +9,7 @@ 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';
@@ -20,7 +20,7 @@ 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');
+const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
 function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')

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

@@ -79,6 +79,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;

package/dist/lib/commands.js

@@ -11,7 +11,7 @@ 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. */
@@ -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 };

package/dist/lib/daemon.js

@@ -6,17 +6,16 @@
  * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
-import { spawn, execSync } from 'child_process';
+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;
 }
@@ -297,10 +296,10 @@ function startDaemonLocked() {
             }
             fs.writeFileSync(plistPath, generateLaunchdPlist(), 'utf-8');
             try {
-                execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
+                execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
             catch { /* not loaded, expected */ }
-            execSync(`launchctl load "${plistPath}"`, { encoding: 'utf-8' });
+            execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8' });
             const pid = waitForPid(3000);
             return { pid, method: 'launchd' };
         }
@@ -358,7 +357,7 @@ export function stopDaemon() {
         const plistPath = getLaunchdPlistPath();
         if (fs.existsSync(plistPath)) {
             try {
-                execSync(`launchctl unload "${plistPath}"`, { encoding: 'utf-8' });
+                execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8' });
                 fs.unlinkSync(plistPath);
             }
             catch (err) {

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.d.ts

@@ -3,8 +3,15 @@
  *
  * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
+ *
+ * Features:
+ * - Rich metadata: hostname, platform, arch, pid, timezone
+ * - Timing helpers: measure operation duration automatically
+ * - Truncation: long inputs/outputs are trimmed with ellipsis
+ * - Permissions: logs dir is 0700, files are 0600 (owner-only)
+ * - Performance tracking: withTiming() wrapper for any async function
  */
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.error' | 'resource.sync' | 'error' | 'warn' | 'info';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
 export interface EventMeta {
     ts: string;
     tz: string;
@@ -13,17 +20,33 @@ export interface EventMeta {
     platform: NodeJS.Platform;
     arch: string;
     pid: number;
+    ppid: number;
     event: EventType;
 }
 export interface EventPayload {
     agent?: string;
     version?: string;
+    sessionId?: string;
     cwd?: string;
+    command?: string;
+    args?: string[];
+    input?: string;
+    output?: string;
+    prompt?: string;
     durationMs?: number;
+    startupMs?: number;
+    exitCode?: number;
+    status?: string;
     error?: string;
+    errorStack?: string;
     [key: string]: unknown;
 }
 export type EventRecord = EventMeta & EventPayload;
+/**
+ * Truncate a string to maxLength, adding ellipsis if truncated.
+ * Returns undefined for null/undefined input.
+ */
+export declare function truncate(str: string | null | undefined, maxLength?: number): string | undefined;
 /**
  * Emit a structured event to the daily log file.
  *
@@ -41,6 +64,62 @@ export declare function emit(event: EventType, payload?: EventPayload): void;
  * done({ exitCode: 0 }); // emits agent.run.end with durationMs
  */
 export declare function emitStart(startEvent: EventType, payload?: EventPayload): (endPayload?: EventPayload) => void;
+/**
+ * Measure execution time of a synchronous function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = time('parse-config', () => parseConfig(path));
+ */
+export declare function time<T>(label: string, fn: () => T, payload?: EventPayload): T;
+/**
+ * Measure execution time of an async function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = await timeAsync('fetch-data', () => fetchData(url));
+ */
+export declare function timeAsync<T>(label: string, fn: () => Promise<T>, payload?: EventPayload): Promise<T>;
+/**
+ * Create a timing context for measuring multiple phases of an operation.
+ * Useful for tracking startup time vs execution time.
+ *
+ * @example
+ * const timer = createTimer('agent.run', { agent: 'claude' });
+ * // ... setup work ...
+ * timer.mark('startup'); // records startup time
+ * // ... main work ...
+ * timer.end({ exitCode: 0 }); // records total time and emits event
+ */
+export declare function createTimer(label: string, payload?: EventPayload): {
+    mark: (phase: string) => number;
+    end: (endPayload?: EventPayload) => void;
+    elapsed: () => number;
+};
+/**
+ * Higher-order function that wraps an async function with timing.
+ * The wrapper emits start/end events automatically.
+ *
+ * @example
+ * const timedFetch = withTiming('fetch', fetchData, { service: 'api' });
+ * const result = await timedFetch(url);
+ */
+export declare function withTiming<Args extends unknown[], R>(label: string, fn: (...args: Args) => Promise<R>, basePayload?: EventPayload): (...args: Args) => Promise<R>;
+/**
+ * Emit a command.start event with CLI args.
+ * Returns a done() function to emit command.end with duration.
+ *
+ * @example
+ * // At CLI entry point:
+ * const done = emitCommand('run', process.argv.slice(2));
+ * // ... execute command ...
+ * done({ exitCode: 0 });
+ */
+export declare function emitCommand(command: string, args?: string[], payload?: EventPayload): (endPayload?: EventPayload) => void;
+/**
+ * Emit an error event with full details.
+ */
+export declare function emitError(err: Error | string, payload?: EventPayload): void;
 /**
  * Remove log files older than the retention period.
  * Called lazily on emit or explicitly via CLI.
@@ -61,6 +140,20 @@ export declare function query(options: {
     endDate?: Date;
     eventTypes?: EventType[];
     agent?: string;
+    command?: string;
     limit?: number;
 }): EventRecord[];
+/**
+ * Get performance stats for a specific label.
+ */
+export declare function getTimingStats(label: string, options?: {
+    days?: number;
+}): {
+    count: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p50Ms: number;
+    p95Ms: number;
+} | null;
 export declare const LOGS_PATH: string;