@phnx-labs/agents-cli 1.22.54 → 1.22.55

package/dist/lib/browser/ffmpeg.js

@@ -0,0 +1,184 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+let resolvedFfmpeg;
+function canonicalDirs(platform) {
+    if (platform === 'darwin')
+        return ['/opt/homebrew/bin', '/usr/local/bin'];
+    if (platform === 'linux')
+        return ['/usr/local/bin', '/usr/bin', '/snap/bin'];
+    return [];
+}
+function pathCandidates(env, platform, platformDirs) {
+    const names = platform === 'win32' ? ['ffmpeg.exe'] : ['ffmpeg'];
+    const dirs = [...new Set([...(env.PATH ?? '').split(path.delimiter).filter(Boolean), ...platformDirs])];
+    return dirs.flatMap((dir) => names.map((name) => path.join(dir, name)));
+}
+function managedCandidates(home, platform) {
+    const name = platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+    return [
+        path.join(home, '.agents', '.cache', 'bin', name),
+        path.join(home, '.agents', '.cache', 'ffmpeg', 'bin', name),
+        path.join(home, '.agents', '.cache', 'ffmpeg', 'node_modules', 'ffmpeg-static', name),
+    ];
+}
+async function isUsable(binary) {
+    try {
+        await execFileAsync(binary, ['-version'], { timeout: 10_000, windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function firstUsable(candidates) {
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && await isUsable(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function commandOnPath(name, env, platform, platformDirs) {
+    const names = platform === 'win32' ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+    const dirs = [...new Set([...(env.PATH ?? '').split(path.delimiter).filter(Boolean), ...platformDirs])];
+    for (const dir of dirs) {
+        for (const candidate of names.map((entry) => path.join(dir, entry))) {
+            try {
+                fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+                return candidate;
+            }
+            catch { /* keep looking */ }
+        }
+    }
+    return undefined;
+}
+export function ffmpegManualCommand(platform, osRelease = '') {
+    if (platform === 'darwin')
+        return 'brew install ffmpeg';
+    if (platform === 'win32')
+        return 'winget install Gyan.FFmpeg';
+    if (/\b(ID|ID_LIKE)=(?:"[^"]*\b)?(?:ubuntu|debian)\b/m.test(osRelease)) {
+        return 'sudo apt-get update && sudo apt-get install -y ffmpeg';
+    }
+    return 'install ffmpeg with your system package manager';
+}
+function readOsRelease() {
+    try {
+        return fs.readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function installManagedFfmpeg(home, env, platform, platformDirs) {
+    const npm = commandOnPath('npm', env, platform, platformDirs);
+    if (!npm)
+        return undefined;
+    const prefix = path.join(home, '.agents', '.cache', 'ffmpeg');
+    await fs.promises.mkdir(prefix, { recursive: true });
+    await execFileAsync(npm, [
+        'install', '--prefix', prefix, '--no-save', '--no-audit', '--no-fund',
+        'ffmpeg-static@5.2.0',
+    ], { env, timeout: 10 * 60_000, windowsHide: true });
+    return firstUsable(managedCandidates(home, platform));
+}
+function installAttempt(platform, env, osRelease, platformDirs) {
+    if (platform === 'darwin') {
+        const brew = commandOnPath('brew', env, platform, platformDirs);
+        return brew ? [{ command: brew, args: ['install', 'ffmpeg'] }] : undefined;
+    }
+    if (platform === 'win32') {
+        const winget = commandOnPath('winget', env, platform, platformDirs);
+        return winget ? [{ command: winget, args: ['install', '--id', 'Gyan.FFmpeg', '--exact', '--accept-source-agreements', '--accept-package-agreements'] }] : undefined;
+    }
+    if (platform !== 'linux')
+        return undefined;
+    if (/\b(ID|ID_LIKE)=(?:"[^"]*\b)?(?:ubuntu|debian)\b/m.test(osRelease)) {
+        const apt = commandOnPath('apt-get', env, platform, platformDirs);
+        if (!apt)
+            return undefined;
+        if (typeof process.getuid === 'function' && process.getuid() === 0) {
+            return [
+                { command: apt, args: ['update'] },
+                { command: apt, args: ['install', '-y', 'ffmpeg'] },
+            ];
+        }
+        const sudo = commandOnPath('sudo', env, platform, platformDirs);
+        return sudo ? [
+            { command: sudo, args: ['-n', apt, 'update'] },
+            { command: sudo, args: ['-n', apt, 'install', '-y', 'ffmpeg'] },
+        ] : undefined;
+    }
+    const managers = [
+        ['apk', ['add', 'ffmpeg']],
+        ['dnf', ['install', '-y', 'ffmpeg']],
+        ['yum', ['install', '-y', 'ffmpeg']],
+        ['pacman', ['-S', '--noconfirm', 'ffmpeg']],
+        ['zypper', ['--non-interactive', 'install', 'ffmpeg']],
+    ];
+    for (const [name, args] of managers) {
+        const command = commandOnPath(name, env, platform, platformDirs);
+        if (command)
+            return [{ command, args }];
+    }
+    return undefined;
+}
+export async function resolveFfmpeg(options = {}) {
+    if (resolvedFfmpeg)
+        return resolvedFfmpeg;
+    resolvedFfmpeg = (async () => {
+        const env = options.env ?? process.env;
+        const home = options.home ?? os.homedir();
+        const platform = options.platform ?? os.platform();
+        const osRelease = options.osRelease ?? readOsRelease();
+        const executableDirs = options.executableDirs ?? canonicalDirs(platform);
+        const candidates = [...pathCandidates(env, platform, executableDirs), ...managedCandidates(home, platform)];
+        const existing = await firstUsable(candidates);
+        if (existing)
+            return existing;
+        const attempt = installAttempt(platform, env, osRelease, executableDirs);
+        let failure = 'no supported automatic installer was found';
+        if (attempt) {
+            try {
+                for (const step of attempt) {
+                    await execFileAsync(step.command, step.args, {
+                        env,
+                        timeout: 10 * 60_000,
+                        windowsHide: true,
+                    });
+                }
+                const installed = await firstUsable([...pathCandidates(env, platform, executableDirs), ...managedCandidates(home, platform)]);
+                if (installed)
+                    return installed;
+                failure = `${path.basename(attempt.at(-1).command)} completed but ffmpeg is still unavailable`;
+            }
+            catch (error) {
+                failure = `${path.basename(attempt.at(-1).command)} failed: ${error.message}`;
+            }
+        }
+        try {
+            const managed = await installManagedFfmpeg(home, env, platform, executableDirs);
+            if (managed)
+                return managed;
+            failure += '; managed npm installation was unavailable';
+        }
+        catch (error) {
+            failure += `; managed npm installation failed: ${error.message}`;
+        }
+        const manual = ffmpegManualCommand(platform, osRelease);
+        throw new Error(`ffmpeg is required for browser recording and automatic installation failed (${failure}). Run \`${manual}\`, then retry.`);
+    })();
+    try {
+        return await resolvedFfmpeg;
+    }
+    catch (error) {
+        resolvedFfmpeg = undefined;
+        throw error;
+    }
+}
+export function resetFfmpegResolverForTest() {
+    resolvedFfmpeg = undefined;
+}

package/dist/lib/browser/service.js

@@ -21,6 +21,7 @@ import { emit } from '../feed/events.js';
 import { resolveActor } from '../actor.js';
 import { recordBrowserSession } from '../session/db.js';
 import { sshExecAsync } from '../ssh-exec.js';
+import { resolveFfmpeg } from './ffmpeg.js';
 /**
  * Canonical form for comparing a requested URL against what CDP reports for a
  * live target. `new URL('https://example.com').href` is `https://example.com/`,
@@ -1130,38 +1131,29 @@ export class BrowserService {
         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');
-        // CDP `Page.startScreencast` delivers frames at a VARIABLE cadence (paints
-        // are event-driven, not clocked). Feeding those into a fixed `-framerate`
-        // input made ffmpeg assume every frame was 1/fps apart, so a page that
-        // painted slower/faster than `fps` played back at the wrong speed. Instead
-        // stamp each frame with its wall-clock arrival time
-        // (`-use_wallclock_as_timestamps 1`) and keep those timings on output
-        // (`-vsync vfr`), so playback duration matches the real capture.
-        const ffmpeg = spawn('ffmpeg', [
+        const [{ spawn }, ffmpegPath] = await Promise.all([
+            import('child_process'),
+            resolveFfmpeg(),
+        ]);
+        // The frame pump below clocks the latest CDP paint into stdin at exactly
+        // `fps`, including repeated frames while the page is static. Declare that
+        // cadence to image2pipe so frame count / fps is the real capture duration.
+        const ffmpeg = spawn(ffmpegPath, [
             '-loglevel', 'error',
             '-f', 'image2pipe',
-            '-use_wallclock_as_timestamps', '1',
+            '-framerate', String(fps),
             '-i', '-',
             '-c:v', 'libvpx-vp9',
             '-b:v', '1M',
             '-pix_fmt', 'yuv420p',
-            '-vsync', 'vfr',
             '-y',
             outputPath,
         ], { stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
-        // 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.
+        // Wait for the spawn to confirm before wiring CDP frames into a dead pipe.
         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);
-                }
+                reject(err);
             };
             const onSpawn = () => {
                 ffmpeg.off('error', onError);
@@ -1181,13 +1173,33 @@ export class BrowserService {
         });
         const ffmpegStderr = () => stderrBuf;
         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) => {
+        let frameCount = 0;
+        let latestFrame;
+        let stdinBlocked = false;
+        let stdinError;
+        ffmpeg.stdin?.on('drain', () => { stdinBlocked = false; });
+        ffmpeg.stdin?.on('error', (error) => { stdinError = error; });
+        const writeFrame = (frame) => {
+            const stdin = ffmpeg.stdin;
+            if (!stdin || stdin.destroyed || stdinError || stdinBlocked)
+                return false;
+            stdinBlocked = !stdin.write(frame);
+            frameCount += 1;
+            return true;
+        };
+        const frameIntervalMs = 1000 / fps;
+        let resolveFirstFrame;
+        const firstFrame = new Promise((resolve) => { resolveFirstFrame = resolve; });
+        const frameHandler = (params, eventSessionId) => {
+            if (eventSessionId !== sessionId)
+                return;
             const p = params;
             try {
-                ffmpeg.stdin?.write(Buffer.from(p.data, 'base64'));
+                latestFrame = Buffer.from(p.data, 'base64');
+                if (frameCount === 0) {
+                    if (writeFrame(latestFrame))
+                        resolveFirstFrame();
+                }
             }
             catch {
                 // ffmpeg exited; ignore writes
@@ -1195,7 +1207,77 @@ export class BrowserService {
             // Must ack every frame or CDP stops sending.
             conn.cdp.send('Page.screencastFrameAck', { sessionId: p.sessionId }, sessionId).catch(() => { });
         };
+        // CDP emits on paints, so a static page can legitimately produce only one
+        // event in 15 seconds. Retain the latest real frame and clock it into the
+        // encoder at --fps; new paints replace it, while quiet time still advances
+        // the WebM timeline instead of collapsing to a one-frame, 0.04s artifact.
+        const framePump = setInterval(() => {
+            if (!latestFrame)
+                return;
+            try {
+                writeFrame(latestFrame);
+            }
+            catch {
+                // ffmpeg exited; recordStop reports its exit code and stderr.
+            }
+        }, frameIntervalMs);
+        // Register BEFORE startScreencast. Chrome may emit its first frame before
+        // the command response; missing that frame also misses its ack and stalls
+        // the entire stream with ffmpeg's stdin still empty (PHNX-2600).
         conn.cdp.on('Page.screencastFrame', frameHandler);
+        try {
+            await conn.cdp.send('Page.enable', {}, sessionId);
+            await conn.cdp.send('Page.startScreencast', {
+                format: 'jpeg',
+                quality: 60,
+                // Chrome's frames are paint-driven, not a 30fps clock. Asking for
+                // every third paint can suppress the only stored frame on a static
+                // page, so receive every paint and enforce --fps when writing stdin.
+                everyNthFrame: 1,
+                maxFramesInFlight: 1,
+                // A static/low-paint page may produce no new compositor frame after
+                // startScreencast. Ask Chrome to send its stored last frame so the
+                // first ack can bootstrap the stream instead of leaving ffmpeg stdin
+                // empty forever (confirmed live against Chrome 151 / PHNX-2600).
+                sendLastFrame: true,
+            }, sessionId);
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new Error('Chrome produced no screencast frame within 5s; recording was not started.')), 5000);
+                firstFrame.then(() => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+        }
+        catch (error) {
+            conn.cdp.off('Page.screencastFrame', frameHandler);
+            clearInterval(framePump);
+            try {
+                await conn.cdp.send('Page.stopScreencast', {}, sessionId);
+            }
+            catch { /* session may be gone */ }
+            try {
+                ffmpeg.stdin?.end();
+            }
+            catch { /* process may already be gone */ }
+            await new Promise((resolve) => {
+                if (ffmpeg.exitCode !== null)
+                    return resolve();
+                const timer = setTimeout(() => {
+                    try {
+                        ffmpeg.kill('SIGKILL');
+                    }
+                    catch { /* already gone */ }
+                    resolve();
+                }, 1000);
+                ffmpeg.once('exit', () => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+            await fs.promises.rm(outputPath, { force: true });
+            throw error;
+        }
         const durationMs = durationSec * 1000;
         const maxBytes = maxMb * 1024 * 1024;
         const state = {
@@ -1206,9 +1288,12 @@ export class BrowserService {
             maxBytes,
             ffmpeg,
             ffmpegStderr,
+            encoderError: () => stdinError,
+            get frameCount() { return frameCount; },
             sessionId,
             conn,
             frameHandler,
+            framePump,
             durationTimer: setTimeout(() => {
                 this.recordStop(taskId, 'duration-cap').catch(() => { });
             }, durationMs),
@@ -1242,6 +1327,7 @@ export class BrowserService {
         rec.stopReason = reason;
         clearTimeout(rec.durationTimer);
         clearInterval(rec.sizeCheckInterval);
+        clearInterval(rec.framePump);
         rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
         try {
             await rec.conn.cdp.send('Page.stopScreencast', {}, rec.sessionId);
@@ -1291,6 +1377,13 @@ export class BrowserService {
                 `${rec.outputPath}; the file is likely corrupt or empty.` +
                 (err ? ` ffmpeg: ${err.slice(-800)}` : ''));
         }
+        const encoderError = rec.encoderError?.();
+        if (encoderError) {
+            throw new Error(`ffmpeg stopped accepting recording frames at ${rec.outputPath}: ${encoderError.message}`);
+        }
+        if (rec.frameCount === 0) {
+            throw new Error(`Chrome delivered no frames for the recording at ${rec.outputPath}; the output is empty.`);
+        }
         let bytes = 0;
         try {
             const st = await fs.promises.stat(rec.outputPath);
@@ -1995,6 +2088,7 @@ export class BrowserService {
                 rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
             }
             catch { /* socket may be gone */ }
+            clearInterval(rec.framePump);
             try {
                 rec.ffmpeg.stdin?.end();
             }

package/dist/lib/daemon/browser-task-reap-service.d.ts

@@ -0,0 +1,14 @@
+/** Abandoned browser-task cleanup under supervision. */
+import { BrowserService } from '../browser/service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+import { BasePeriodicService, type DaemonContext } from './service.js';
+export declare class BrowserTaskReapService extends BasePeriodicService {
+    private readonly browserService;
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    constructor(browserService: BrowserService);
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/browser-task-reap-service.js

@@ -0,0 +1,26 @@
+/** Abandoned browser-task cleanup under supervision. */
+import { resolveBrowserTaskIdleMs } from '../device-config.js';
+import { BasePeriodicService } from './service.js';
+const BROWSER_TASK_REAP_TICK_MS = 5 * 60_000;
+const BROWSER_TASK_REAP_DEADLINE_MS = 2 * 60_000;
+export class BrowserTaskReapService extends BasePeriodicService {
+    browserService;
+    id = 'browser-task-reap';
+    intervalMs = BROWSER_TASK_REAP_TICK_MS;
+    deadlineMs = BROWSER_TASK_REAP_DEADLINE_MS;
+    constructor(browserService) {
+        super();
+        this.browserService = browserService;
+    }
+    async onStart(_ctx) { }
+    async onStop() { }
+    async onTick(ctx) {
+        const result = await this.browserService.reapAbandoned({ idleMs: resolveBrowserTaskIdleMs() });
+        if (result.closed.length > 0) {
+            ctx.log('INFO', `Browser-task reaper: closed ${result.closed.length} task(s)`);
+            for (const closed of result.closed) {
+                ctx.log('INFO', `  ${closed.task} (${closed.reason}, profile ${closed.profile})`);
+            }
+        }
+    }
+}