@phnx-labs/agents-cli 1.18.2 → 1.18.4

package/dist/lib/browser/service.js

@@ -1,16 +1,48 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from './cdp.js';
-import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, } from './profiles.js';
+import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH } from './drivers/ssh.js';
-import { generateTaskId, generateShortId, generateFunName, } from './types.js';
+import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
+/**
+ * Read width/height from a JPEG buffer by walking SOF markers. Returns null
+ * if the buffer doesn't start with the JPEG SOI marker or no SOF segment is
+ * found. We use this on every screenshot so the CLI can surface the actual
+ * captured pixel dimensions (which differ from viewport size at non-1x DPR).
+ */
+function readPngDimensions(buf) {
+    // PNG signature (8 bytes) + IHDR chunk: length (4) + 'IHDR' (4) + width (4) + height (4)
+    if (buf.length < 24)
+        return null;
+    const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    for (let i = 0; i < 8; i++)
+        if (buf[i] !== sig[i])
+            return null;
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+function readJpegDimensions(buf) {
+    if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8)
+        return null;
+    let i = 2;
+    while (i + 9 < buf.length) {
+        if (buf[i] !== 0xff)
+            return null;
+        const marker = buf[i + 1];
+        // SOF0–SOFn carry dimensions, except DHT (0xC4), JPG (0xC8), DAC (0xCC).
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+        }
+        i += 2 + buf.readUInt16BE(i + 2);
+    }
+    return null;
+}
 /**
  * Parse a `targetFilter` string into its kind + value, or return `null`
  * when the input is missing or malformed. Filter syntax:
@@ -106,39 +138,60 @@ export class BrowserService {
         if (!profile) {
             throw new Error(`Profile "${profileName}" not found`);
         }
-        const taskName = opts.taskName || generateFunName();
+        // Pick the endpoint preset. Throws with the candidate list if the user
+        // passed an unknown name. The composite identifier `<profile>@<endpoint>`
+        // is what the connection map + per-profile runtime dirs are keyed on, so
+        // a single YAML profile can run at multiple endpoints concurrently.
+        const resolved = resolveEndpoint(profile, opts.endpointName);
+        const composite = `${profileName}@${resolved.name}`;
+        const effectiveProfile = {
+            ...profile,
+            name: composite,
+            binary: resolved.binary,
+            targetFilter: resolved.targetFilter,
+        };
+        let taskName;
+        if (opts.taskName) {
+            if (this.hasTaskNamed(opts.taskName)) {
+                throw new Error(`Task "${opts.taskName}" already exists. Pick a different --task name or stop the existing one first.`);
+            }
+            taskName = opts.taskName;
+        }
+        else {
+            taskName = this.generateUniqueTaskName();
+        }
         const taskId = generateTaskId();
-        let conn = this.connections.get(profileName);
-        let effectiveProfileName = profileName;
+        let conn = this.connections.get(composite);
+        let effectiveProfileName = composite;
         if (conn && conn.electron && conn.tasks.size > 0) {
-            if (this.forkingProfiles.has(profileName)) {
-                while (this.forkingProfiles.has(profileName)) {
+            if (this.forkingProfiles.has(composite)) {
+                while (this.forkingProfiles.has(composite)) {
                     await new Promise((r) => setTimeout(r, 50));
                 }
-                const existingFork = this.findAvailableFork(profileName);
+                const existingFork = this.findAvailableFork(composite);
                 if (existingFork) {
                     conn = existingFork.conn;
                     effectiveProfileName = existingFork.name;
                 }
                 else {
-                    throw new Error(`Fork in progress but no available fork found for "${profileName}"`);
+                    throw new Error(`Fork in progress but no available fork found for "${composite}"`);
                 }
             }
             else {
-                this.forkingProfiles.add(profileName);
+                this.forkingProfiles.add(composite);
                 try {
-                    const { forkName, connection } = await this.forkElectronProfile(profile);
+                    const { forkName, connection } = await this.forkElectronProfile(effectiveProfile);
                     conn = connection;
                     effectiveProfileName = forkName;
                 }
                 finally {
-                    this.forkingProfiles.delete(profileName);
+                    this.forkingProfiles.delete(composite);
                 }
             }
         }
         else if (!conn) {
-            conn = await this.connectProfile(profile);
-            this.connections.set(profileName, conn);
+            conn = await this.connectProfile(effectiveProfile, resolved.target);
+            this.connections.set(composite, conn);
         }
         const task = {
             id: taskId,
@@ -178,25 +231,7 @@ export class BrowserService {
             const result = await this.navigate(taskName, opts.url, effectiveProfileName);
             tabId = result.tabId;
         }
-        return { task: taskId, name: taskName, tabId };
-    }
-    /**
-     * Launch (or attach to) the profile's browser without creating a task. Used by
-     * `agents browser profiles launch <name>` so users can warm up the browser —
-     * including the first-run onboarding flow — before any automation starts.
-     */
-    async launchProfile(profileName) {
-        const profile = await getProfile(profileName);
-        if (!profile) {
-            throw new Error(`Profile "${profileName}" not found`);
-        }
-        let conn = this.connections.get(profileName);
-        if (!conn) {
-            conn = await this.connectProfile(profile);
-            this.connections.set(profileName, conn);
-        }
-        emit('browser.launch', { profile: profileName, task: '', pid: conn.pid });
-        return { port: conn.port, pid: conn.pid };
+        return { task: taskId, name: taskName, tabId, profile: effectiveProfileName };
     }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
@@ -455,7 +490,7 @@ export class BrowserService {
         }
         return result.result.value;
     }
-    async screenshot(taskId, tabHint, outputPath) {
+    async screenshot(taskId, tabHint, outputPath, quality = 'compressed') {
         const { conn, task } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
@@ -464,22 +499,201 @@ export class BrowserService {
             throw new Error(`Tab ${shortId} not found`);
         }
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 }, sessionId));
-        let buffer = Buffer.from(data, 'base64');
-        const MAX_SIZE = 100 * 1024;
-        if (buffer.length > MAX_SIZE) {
-            let quality = 50;
-            while (buffer.length > MAX_SIZE && quality > 10) {
-                const { data: resized } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality }, sessionId));
-                buffer = Buffer.from(resized, 'base64');
-                quality -= 10;
+        let buffer;
+        let extension;
+        if (quality === 'raw') {
+            // Pixel-faithful PNG, no downscale. For archived QA evidence where
+            // lossy JPEG would hide rendering bugs. Files run 0.5–3 MB.
+            const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId));
+            buffer = Buffer.from(data, 'base64');
+            extension = 'png';
+        }
+        else {
+            // Default: JPEG quality 70, then iteratively downscale to keep the
+            // file under 100 KB so chat-injected screenshots stay token-cheap.
+            const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 }, sessionId));
+            buffer = Buffer.from(data, 'base64');
+            const MAX_SIZE = 100 * 1024;
+            if (buffer.length > MAX_SIZE) {
+                let q = 50;
+                while (buffer.length > MAX_SIZE && q > 10) {
+                    const { data: resized } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: q }, sessionId));
+                    buffer = Buffer.from(resized, 'base64');
+                    q -= 10;
+                }
             }
+            extension = 'jpg';
         }
         const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
-        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.jpg`);
+        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.${extension}`);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
         await fs.promises.writeFile(finalPath, buffer);
-        return finalPath;
+        const dims = (extension === 'png' ? readPngDimensions(buffer) : readJpegDimensions(buffer)) ??
+            { width: 0, height: 0 };
+        return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
+    }
+    // ─── Recording ──────────────────────────────────────────────────────────────
+    //
+    // CDP `Page.startScreencast` emits a JPEG frame per `everyNthFrame`. We pipe
+    // those frames into ffmpeg's stdin (image2pipe) and encode to a webm/vp9 file
+    // under `sessions/<task>/recordings/`. A background watcher enforces the
+    // duration + size caps so a forgotten recording can't fill the disk.
+    recordings = new Map();
+    async recordStart(taskId, tabHint, opts = {}) {
+        if (this.recordings.has(taskId)) {
+            throw new Error(`Task "${taskId}" is already recording. Call record stop first.`);
+        }
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target)
+            throw new Error(`Tab ${shortId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const fps = opts.fps ?? 5;
+        const durationSec = opts.duration ?? 60;
+        const maxMb = opts.maxMb ?? 25;
+        if (fps < 1 || fps > 30)
+            throw new Error('--fps must be between 1 and 30');
+        if (durationSec < 1 || durationSec > 3600)
+            throw new Error('--duration must be between 1 and 3600 seconds');
+        if (maxMb < 1 || maxMb > 500)
+            throw new Error('--max-mb must be between 1 and 500');
+        const recordingsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name, 'recordings');
+        await fs.promises.mkdir(recordingsDir, { recursive: true });
+        const outputPath = path.join(recordingsDir, `${Date.now()}.webm`);
+        // Resolve ffmpeg lazily so non-recording paths don't pay the import cost.
+        const { spawn } = await import('child_process');
+        const ffmpeg = spawn('ffmpeg', [
+            '-loglevel', 'error',
+            '-f', 'image2pipe',
+            '-framerate', String(fps),
+            '-i', '-',
+            '-c:v', 'libvpx-vp9',
+            '-b:v', '1M',
+            '-pix_fmt', 'yuv420p',
+            '-y',
+            outputPath,
+        ], { stdio: ['pipe', 'ignore', 'pipe'] });
+        // Wait for the spawn to confirm (or fail) before we wire CDP frames into a
+        // dead pipe. ENOENT from a missing ffmpeg surfaces here as a real error
+        // instead of a silently empty .webm.
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                ffmpeg.off('spawn', onSpawn);
+                if (err.code === 'ENOENT') {
+                    reject(new Error('ffmpeg not found on PATH — install via `brew install ffmpeg`'));
+                }
+                else {
+                    reject(err);
+                }
+            };
+            const onSpawn = () => {
+                ffmpeg.off('error', onError);
+                resolve();
+            };
+            ffmpeg.once('error', onError);
+            ffmpeg.once('spawn', onSpawn);
+        });
+        // Surface ffmpeg's own diagnostics (encoder error, etc.) in case stderr
+        // arrives after spawn.
+        ffmpeg.stderr?.on('data', () => { });
+        ffmpeg.on('error', () => { });
+        // 30 fps is CDP's screencast cap; everyNthFrame = round(30/fps).
+        const everyNthFrame = Math.max(1, Math.round(30 / fps));
+        await conn.cdp.send('Page.startScreencast', { format: 'jpeg', quality: 60, everyNthFrame }, sessionId);
+        const frameHandler = (params) => {
+            const p = params;
+            try {
+                ffmpeg.stdin?.write(Buffer.from(p.data, 'base64'));
+            }
+            catch {
+                // ffmpeg exited; ignore writes
+            }
+            // Must ack every frame or CDP stops sending.
+            conn.cdp.send('Page.screencastFrameAck', { sessionId: p.sessionId }, sessionId).catch(() => { });
+        };
+        conn.cdp.on('Page.screencastFrame', frameHandler);
+        const durationMs = durationSec * 1000;
+        const maxBytes = maxMb * 1024 * 1024;
+        const state = {
+            outputPath,
+            startedAt: Date.now(),
+            fps,
+            durationMs,
+            maxBytes,
+            ffmpeg,
+            sessionId,
+            conn,
+            frameHandler,
+            durationTimer: setTimeout(() => {
+                this.recordStop(taskId, 'duration-cap').catch(() => { });
+            }, durationMs),
+            sizeCheckInterval: setInterval(async () => {
+                try {
+                    const st = await fs.promises.stat(outputPath);
+                    if (st.size >= maxBytes) {
+                        await this.recordStop(taskId, 'size-cap');
+                    }
+                }
+                catch {
+                    // File may not exist yet
+                }
+            }, 1000),
+        };
+        this.recordings.set(taskId, state);
+        return { path: outputPath, fps, durationCapSec: durationSec, maxMb };
+    }
+    async recordStop(taskId, reason = 'manual') {
+        const rec = this.recordings.get(taskId);
+        if (!rec) {
+            throw new Error(`Task "${taskId}" is not currently recording`);
+        }
+        if (rec.stopReason) {
+            // Already stopping (e.g. size-cap fired while user also called stop).
+            // Wait for in-flight finalize.
+            while (this.recordings.has(taskId)) {
+                await new Promise((r) => setTimeout(r, 25));
+            }
+        }
+        rec.stopReason = reason;
+        clearTimeout(rec.durationTimer);
+        clearInterval(rec.sizeCheckInterval);
+        rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
+        try {
+            await rec.conn.cdp.send('Page.stopScreencast', {}, rec.sessionId);
+        }
+        catch {
+            // session may already be gone
+        }
+        // Close ffmpeg stdin so it flushes the output file cleanly.
+        await new Promise((resolve) => {
+            rec.ffmpeg.on('exit', () => resolve());
+            try {
+                rec.ffmpeg.stdin?.end();
+            }
+            catch {
+                resolve();
+            }
+            setTimeout(resolve, 5000); // Hard timeout if ffmpeg hangs
+        });
+        let bytes = 0;
+        try {
+            const st = await fs.promises.stat(rec.outputPath);
+            bytes = st.size;
+        }
+        catch {
+            // ffmpeg may have failed; file missing
+        }
+        const durationMs = Date.now() - rec.startedAt;
+        this.recordings.delete(taskId);
+        return { path: rec.outputPath, bytes, durationMs, reason };
+    }
+    async recordStatus(taskId) {
+        const rec = this.recordings.get(taskId);
+        if (!rec)
+            return { recording: false };
+        return { recording: true, path: rec.outputPath, elapsedMs: Date.now() - rec.startedAt };
     }
     refsCache = new Map();
     async refs(taskId, tabHint, opts = {}) {
@@ -969,6 +1183,34 @@ export class BrowserService {
         return undefined;
     }
     async shutdown() {
+        // Drain any in-flight recordings first so we don't orphan ffmpeg processes
+        // or leak the duration/size-check timers when the daemon goes down.
+        for (const [taskId, rec] of this.recordings) {
+            clearTimeout(rec.durationTimer);
+            clearInterval(rec.sizeCheckInterval);
+            try {
+                rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
+            }
+            catch { /* socket may be gone */ }
+            try {
+                rec.ffmpeg.stdin?.end();
+            }
+            catch { /* already closed */ }
+            // Give ffmpeg up to 1s to flush; then SIGKILL.
+            const exited = await new Promise((resolve) => {
+                let done = false;
+                rec.ffmpeg.once('exit', () => { done = true; resolve(true); });
+                setTimeout(() => { if (!done)
+                    resolve(false); }, 1000);
+            });
+            if (!exited) {
+                try {
+                    rec.ffmpeg.kill('SIGKILL');
+                }
+                catch { /* already dead */ }
+            }
+            this.recordings.delete(taskId);
+        }
         for (const [, conn] of this.connections) {
             conn.cdp.close();
         }
@@ -1007,39 +1249,39 @@ export class BrowserService {
         this.connections.set(forkName, connection);
         return { forkName, connection };
     }
-    async connectProfile(profile) {
-        const existingInfo = getRunningChromeInfo(profile.name);
+    /**
+     * Connect to a profile at a specific endpoint preset. The caller has
+     * already resolved the endpoint and built the `effectiveProfile` with
+     * the per-endpoint binary/targetFilter overrides applied; we just use it.
+     *
+     * `effectiveProfile.name` is the composite identifier (`<profile>@<endpoint>`)
+     * so per-endpoint pid/port files don't collide when the same app runs
+     * locally and remotely at the same time.
+     */
+    async connectProfile(effectiveProfile, target) {
+        const existingInfo = getRunningChromeInfo(effectiveProfile.name);
         if (existingInfo) {
             const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port);
-            verifyBrowserIdentity(browser, profile.browser, existingInfo.port);
+            verifyBrowserIdentity(browser, effectiveProfile.browser, existingInfo.port);
             const cdp = new CDPClient();
             await cdp.connect(wsUrl);
             await this.enableDomains(cdp);
-            const tasks = this.loadTaskState(profile.name);
+            const tasks = this.loadTaskState(effectiveProfile.name);
             return {
                 cdp,
                 port: existingInfo.port,
                 pid: existingInfo.pid,
-                electron: profile.electron,
-                targetFilter: profile.targetFilter,
+                electron: effectiveProfile.electron,
+                targetFilter: effectiveProfile.targetFilter,
                 tasks,
                 sessionCache: new Map(),
             };
         }
-        for (const endpoint of profile.endpoints) {
-            try {
-                const conn = await this.connectEndpoint(profile, endpoint);
-                if (conn)
-                    return conn;
-            }
-            catch (err) {
-                if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
-                    throw err;
-                }
-                // Try next endpoint
-            }
+        const conn = await this.connectEndpoint(effectiveProfile, target);
+        if (!conn) {
+            throw new Error(`Could not connect to endpoint ${target} for profile "${effectiveProfile.name}"`);
         }
-        throw new Error(`Could not connect to any endpoint for profile "${profile.name}"`);
+        return conn;
     }
     async connectEndpoint(profile, endpoint) {
         const url = new URL(endpoint);
@@ -1143,6 +1385,21 @@ export class BrowserService {
         conn.windowId = result.targetId;
         return result.targetId;
     }
+    hasTaskNamed(name) {
+        for (const conn of this.connections.values()) {
+            if (conn.tasks.has(name))
+                return true;
+        }
+        return false;
+    }
+    generateUniqueTaskName() {
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const candidate = generateTaskName();
+            if (!this.hasTaskNamed(candidate))
+                return candidate;
+        }
+        throw new Error('Could not generate unique task name after 8 attempts');
+    }
     async findTask(taskId, profileName) {
         if (profileName) {
             const conn = this.connections.get(profileName);

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

@@ -1,4 +1,19 @@
 export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+/**
+ * A single named endpoint preset within a profile. Lets one profile cover
+ * the local + remote variants of the same app (e.g. Rush on this Mac vs.
+ * Rush on mac-mini) instead of forcing two parallel profiles.
+ *
+ * Per-endpoint overrides take precedence over profile-level fields.
+ */
+export interface EndpointPreset {
+    /** CDP URL — `cdp://host:port` or `ssh://host?port=N` */
+    target: string;
+    /** Override the profile-level binary (e.g. mac-mini has no local binary). */
+    binary?: string;
+    /** Override the profile-level targetFilter (Electron app builds may diverge). */
+    targetFilter?: string;
+}
 export interface BrowserProfile {
     name: string;
     description?: string;
@@ -10,7 +25,14 @@ export interface BrowserProfile {
      * represents the visible UI for Electron apps with multiple WebContents.
      */
     targetFilter?: string;
-    endpoints: string[];
+    /**
+     * Endpoint presets. Accepts two shapes for backward compatibility:
+     *   - Legacy: `string[]` of CDP URLs; first entry is the default.
+     *   - New:    `{ [presetName]: EndpointPreset }`, with optional `defaultEndpoint`.
+     * Normalize via `resolveEndpoint(profile, name?)` instead of reading directly.
+     */
+    endpoints: string[] | Record<string, EndpointPreset>;
+    defaultEndpoint?: string;
     chrome?: ChromeOptions;
     secrets?: string;
     viewport?: {
@@ -83,7 +105,7 @@ export interface HistoricalTask {
     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' | 'upload';
+export type IPCAction = 'start' | 'record-start' | 'record-stop' | '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' | 'upload';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -119,6 +141,22 @@ export interface IPCRequest {
     files?: string[];
     trigger?: number;
     uploadMode?: 'auto' | 'input' | 'drop' | 'chooser';
+    quality?: 'compressed' | 'raw';
+    endpoint?: string;
+    fps?: number;
+    duration?: number;
+    maxMb?: number;
+}
+/** Subset of IPCResponse describing a recording start result. */
+export interface RecordStartFields {
+    fps?: number;
+    durationCapSec?: number;
+    maxMb?: number;
+}
+/** Subset of IPCResponse describing a recording stop result. */
+export interface RecordStopFields {
+    durationMs?: number;
+    stopReason?: 'manual' | 'duration-cap' | 'size-cap';
 }
 export interface IPCResponse {
     ok: boolean;
@@ -131,10 +169,18 @@ export interface IPCResponse {
     history?: HistoricalTask[];
     result?: unknown;
     path?: string;
+    bytes?: number;
+    width?: number;
+    height?: number;
     refs?: string;
     nodes?: RefNodeJson[];
     port?: number;
     pid?: number;
+    fps?: number;
+    durationCapSec?: number;
+    maxMb?: number;
+    durationMs?: number;
+    stopReason?: 'manual' | 'duration-cap' | 'size-cap';
     logs?: ConsoleEntry[];
     errors?: ErrorEntry[];
     requests?: NetworkRequest[];
@@ -183,3 +229,10 @@ export declare function isValidTaskId(id: string): boolean;
 export declare function generateTaskId(): string;
 export declare function generateShortId(): string;
 export declare function generateFunName(): string;
+/**
+ * Auto-generated task name: `<adjective>-<noun>-<noun>-<hex8>`, e.g.
+ * `swift-crab-falcon-a3f92b1c`. Three English words make it memorable and
+ * easy to read; 32 bits of hex give every spawned task enough entropy that
+ * parallel agents never collide on the daemon side.
+ */
+export declare function generateTaskName(): string;

package/dist/lib/browser/types.js

@@ -11,13 +11,33 @@ export function generateShortId() {
 const ADJECTIVES = [
     'swift', 'cosmic', 'jolly', 'quiet', 'bold', 'bright', 'calm', 'eager',
     'golden', 'happy', 'keen', 'lucky', 'noble', 'proud', 'quick', 'royal',
+    'silver', 'amber', 'crimson', 'misty', 'sunny', 'gentle', 'wild', 'brave',
+    'merry', 'sleek', 'wise', 'fierce', 'curious', 'humble', 'spry', 'witty',
 ];
 const NOUNS = [
     'falcon', 'comet', 'tiger', 'nebula', 'phoenix', 'river', 'summit', 'wave',
     'aurora', 'breeze', 'crystal', 'dragon', 'ember', 'forest', 'glacier', 'harbor',
+    'crab', 'otter', 'hawk', 'fox', 'wolf', 'panda', 'lynx', 'raven',
+    'meadow', 'canyon', 'valley', 'orchid', 'cedar', 'thistle', 'lotus', 'briar',
 ];
 export function generateFunName() {
     const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
     const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
     return `${adj}-${noun}`;
 }
+/**
+ * Auto-generated task name: `<adjective>-<noun>-<noun>-<hex8>`, e.g.
+ * `swift-crab-falcon-a3f92b1c`. Three English words make it memorable and
+ * easy to read; 32 bits of hex give every spawned task enough entropy that
+ * parallel agents never collide on the daemon side.
+ */
+export function generateTaskName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const noun1 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    let noun2 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    while (noun2 === noun1) {
+        noun2 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    }
+    const hex8 = crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+    return `${adj}-${noun1}-${noun2}-${hex8}`;
+}

package/dist/lib/help.js

@@ -23,12 +23,36 @@ function formatHelpCommandsFirst(cmd, helper) {
     function formatList(textArray) {
         return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
     }
-    let output = [`Usage: ${helper.commandUsage(cmd)}`, ''];
+    // Drop arguments flagged as hidden (deprecation / compat slots) from both
+    // the Usage line and the Arguments section. Commander v12's Argument lacks
+    // hideHelp(), so we read a custom `hidden` field that callers set directly.
+    const isHidden = (a) => a.hidden === true;
+    const registeredArgs = cmd.registeredArguments ?? [];
+    const parentNames = [];
+    for (let p = cmd.parent; p; p = p.parent)
+        parentNames.unshift(p.name());
+    const parentPrefix = parentNames.length > 0 ? parentNames.join(' ') + ' ' : '';
+    const visibleArgTokens = registeredArgs
+        .filter((a) => !isHidden(a))
+        .map((a) => {
+        const n = a.name() + (a.variadic ? '...' : '');
+        return a.required ? `<${n}>` : `[${n}]`;
+    })
+        .join(' ');
+    // commander always exposes -h/--help, so every command effectively has options.
+    // Order matches commander's default: name [options] <args> [command].
+    const argsToken = visibleArgTokens ? ` ${visibleArgTokens}` : '';
+    const commandToken = cmd.commands.length > 0 ? ' [command]' : '';
+    const usageLine = `${parentPrefix}${cmd.name()} [options]${argsToken}${commandToken}`;
+    let output = [`Usage: ${usageLine}`, ''];
     const commandDescription = helper.commandDescription(cmd);
     if (commandDescription.length > 0) {
         output = output.concat([helper.wrap(commandDescription, helpWidth, 0), '']);
     }
-    const argumentList = helper.visibleArguments(cmd).map((argument) => {
+    const argumentList = helper
+        .visibleArguments(cmd)
+        .filter((a) => !isHidden(a))
+        .map((argument) => {
         return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument));
     });
     if (argumentList.length > 0) {
@@ -36,9 +60,12 @@ function formatHelpCommandsFirst(cmd, helper) {
     }
     const visibleCommands = helper.visibleCommands(cmd);
     const subcommandTermNoAlias = (sub) => {
-        // Mirror commander's default subcommandTerm but drop the |alias suffix.
+        // Mirror commander's default subcommandTerm but drop the |alias suffix and
+        // skip arguments marked as hidden (Argument#hideHelp()), so deprecation /
+        // compatibility slots don't pollute the usage line.
         const argList = sub.registeredArguments ?? [];
         const args = argList
+            .filter((a) => !a.hidden)
             .map((a) => {
             const n = a.name() + (a.variadic ? '...' : '');
             return a.required ? `<${n}>` : `[${n}]`;