@pasko70/pibo 1.1.0 → 1.2.0

package/dist/tools/index.js

@@ -1,9 +1,15 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { Command } from 'commander';
 import { ErrorCode, formatCliError } from '../cli-errors.js';
-import { acquireBrowserUseLease, listBrowserUseLeases, printBrowserUseAuthTemplateEnv, printBrowserUseAuthTemplatePath, reapStaleBrowserUseLeases, releaseBrowserUseLease, } from './browser-use-leases.js';
-import { formatBrowserUseTargets, listBrowserUseCdpTargets, printAttachChatExports, selectBestChatTarget, } from './browser-use-cdp.js';
+import { acquireAgentBrowserLease, listAgentBrowserLeases, printAgentBrowserAuthTemplateEnv, printAgentBrowserAuthTemplatePath, reapStaleAgentBrowserLeases, releaseAgentBrowserLease, } from './agent-browser-leases.js';
+import { ensureAgentBrowserWrapper } from './agent-browser-wrapper.js';
+import { acquireBrowserUseLease, isExpired, listBrowserUseLeases, printBrowserUseAuthTemplateEnv, printBrowserUseAuthTemplatePath, readRegistry, reapStaleBrowserUseLeases, releaseBrowserUseLease, } from './browser-use-leases.js';
+import { formatBrowserUseTargets, listBrowserUseCdpTargets, normalizeCdpUrlSync, printAttachChatExports, selectBestChatTarget, } from './browser-use-cdp.js';
 import { ensureBrowserUseWrapper } from './browser-use-wrapper.js';
-import { detectDesktopEnv } from './desktop-env.js';
+import { browserPoolPaths, createEmptyBrowserPoolState, loadBrowserPoolState, reapIdleBrowserPool, } from './browser-pool.js';
+import { detectDesktopEnv, hasDesktopDisplay } from './desktop-env.js';
 import { doctorCliTool, findCliToolEntry, findToolGuide, getCliToolStatus, installCliTool, listCliToolEntries, removeCliTool, } from './registry.js';
 function requireEntry(name) {
     const entry = findCliToolEntry(name);
@@ -42,11 +48,33 @@ function printShow(name) {
     const status = getCliToolStatus(entry);
     console.log(`${entry.name}`);
     console.log(`  ${entry.description}`);
-    console.log(`  package: ${entry.runtime.packageName}`);
+    console.log(`  kind: ${entry.kind === 'internal' ? 'built-in' : 'external'}`);
+    if (entry.runtime)
+        console.log(`  package: ${entry.runtime.packageName}`);
     console.log(`  status: ${status.installed ? 'installed' : 'available'}`);
-    console.log(`  runtime: ${status.rootDir}`);
-    console.log(`  home: ${status.homeDir}`);
-    console.log(`  executable: ${status.executablePath}`);
+    if (status.rootDir)
+        console.log(`  runtime: ${status.rootDir}`);
+    if (status.homeDir)
+        console.log(`  home: ${status.homeDir}`);
+    if (entry.name === 'browser-use') {
+        const wrapperPath = ensureBrowserUseWrapper(status);
+        console.log(`  wrapper: ${wrapperPath ?? 'not generated'}`);
+        console.log(`  executable: ${status.executablePath}`);
+        console.log('');
+        console.log('  IMPORTANT: Always use the wrapper path above, not the raw executable.');
+        console.log('  The wrapper manages persistent Chrome profiles and CDP automatically.');
+    }
+    else if (entry.name === 'agent-browser') {
+        const wrapperPath = ensureAgentBrowserWrapper(status);
+        console.log(`  wrapper: ${wrapperPath ?? 'not generated'}`);
+        console.log(`  executable: ${status.executablePath}`);
+        console.log('');
+        console.log('  IMPORTANT: Always use the wrapper path above, not the raw executable.');
+        console.log('  The wrapper keeps Agent Browser state under the Pibo tool home.');
+    }
+    else {
+        console.log(`  executable: ${status.executablePath}`);
+    }
     console.log('');
     console.log('Guides:');
     for (const guide of entry.guides) {
@@ -60,11 +88,19 @@ function printShow(name) {
     }
     console.log('');
     console.log('Next:');
-    console.log(`  pibo tools env ${entry.name}`);
+    if (entry.kind !== 'internal')
+        console.log(`  pibo tools env ${entry.name}`);
     console.log(`  pibo tools guide ${entry.name} ${entry.guides[0]?.name ?? ''}`.trimEnd());
     if (entry.name === 'browser-use') {
         console.log('  pibo tools browser-use');
     }
+    if (entry.name === 'agent-browser') {
+        console.log('  pibo tools agent-browser');
+    }
+    if (entry.name === 'ralph') {
+        console.log('  pibo tools ralph');
+        console.log('  pibo ralph templates');
+    }
 }
 function printGuides(name) {
     const entry = requireEntry(name);
@@ -95,12 +131,34 @@ function printGuide(name, guideName) {
 }
 function printPath(name) {
     const entry = requireEntry(name);
-    console.log(getCliToolStatus(entry).executablePath);
+    const status = getCliToolStatus(entry);
+    if (entry.name === 'browser-use') {
+        const wrapperPath = ensureBrowserUseWrapper(status);
+        if (wrapperPath) {
+            console.log(wrapperPath);
+            return;
+        }
+    }
+    if (entry.name === 'agent-browser') {
+        const wrapperPath = ensureAgentBrowserWrapper(status);
+        if (wrapperPath) {
+            console.log(wrapperPath);
+            return;
+        }
+    }
+    console.log(status.executablePath);
 }
 function printEnv(name) {
     const entry = requireEntry(name);
     const status = getCliToolStatus(entry);
     const desktop = detectDesktopEnv();
+    if (entry.kind === 'internal') {
+        console.log(`# ${entry.name} is built into pibo; no extra environment is required.`);
+        console.log(`# Run: pibo ${entry.name} --help`);
+        return;
+    }
+    if (!entry.runtime)
+        throw new Error(`CLI tool "${entry.name}" is missing runtime`);
     if (process.platform === 'win32') {
         console.log(`$env:PATH = "${status.executablePath.replace(/\\[^\\]+$/, '')};$env:PATH"`);
         if (entry.runtime.homeEnvVar)
@@ -108,7 +166,7 @@ function printEnv(name) {
         return;
     }
     const binDir = status.executablePath.replace(/\/[^/]+$/, '');
-    const wrapperPath = ensureBrowserUseWrapper(status);
+    const wrapperPath = entry.name === 'agent-browser' ? ensureAgentBrowserWrapper(status) : ensureBrowserUseWrapper(status);
     const wrapperBinDir = wrapperPath ? wrapperPath.replace(/\/[^/]+$/, '') : `${status.homeDir}/bin`;
     console.log(`export PATH="${wrapperBinDir}:${binDir}:$PATH"`);
     if (entry.runtime.homeEnvVar)
@@ -132,6 +190,13 @@ function parsePositiveInteger(value) {
     }
     return parsed;
 }
+function parseNonNegativeInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Expected a non-negative integer, got "${value}"`);
+    }
+    return parsed;
+}
 function printBrowserUseDiscovery() {
     console.log(`pibo tools browser-use - browser-use helpers
 
@@ -147,16 +212,407 @@ Commands:
   lease list                  List authenticated browser slots
   lease release <id>          Release one browser slot
   lease reap-stale            Release expired or dead browser slots
+  pool status                 Show read-only managed browser-pool status
+  pool reap                   Reap an idle managed browser pool
+  health                      Check browser-use health and report issues
 
 Next:
   pibo tools show browser-use
   pibo tools guide browser-use browser-use
   pibo tools browser-use targets
   pibo tools browser-use auth-template env
-  pibo tools browser-use lease acquire`);
+  pibo tools browser-use lease acquire
+  pibo tools browser-use pool status
+  pibo tools browser-use pool reap --json`);
+}
+function getBrowserPoolStatusIdentity(options) {
+    return {
+        workerId: options.workerId || process.env.PIBO_BROWSER_POOL_WORKER_ID || process.env.PIBO_COMPUTE_WORKER_ID || process.env.HOSTNAME || 'local',
+        poolId: options.poolId || process.env.PIBO_BROWSER_POOL_ID || 'default',
+        maxBrowserProcesses: parsePositiveInteger(process.env.PIBO_BROWSER_POOL_MAX_PROCESSES || '1'),
+    };
+}
+function getBrowserPoolRoot(status, options) {
+    return options.root || process.env.PIBO_BROWSER_POOL_ROOT || join(process.env.BROWSER_USE_HOME || status.homeDir, 'pibo-browser-pool');
+}
+function browserPoolStatusNextCommands(state) {
+    if (state.state === 'stale' || state.state === 'dirty') {
+        return [
+            'pibo tools browser-use pool status --json',
+            'pibo tools browser-use pool reap --json',
+            'pibo tools browser-use health',
+            'eval "$(pibo tools env browser-use)" && browser-use --pibo-ensure-chrome',
+        ];
+    }
+    if (state.state === 'empty') {
+        return ['eval "$(pibo tools env browser-use)" && browser-use --pibo-ensure-chrome'];
+    }
+    return ['pibo tools browser-use pool status --json'];
+}
+async function getBrowserPoolStatus(status, options) {
+    const identity = getBrowserPoolStatusIdentity(options);
+    const rootDir = getBrowserPoolRoot(status, options);
+    const paths = browserPoolPaths(rootDir, identity);
+    const stateFileExists = existsSync(paths.statePath);
+    let state = await loadBrowserPoolState(paths.statePath, { ...identity, onMissing: 'empty', onMalformed: 'empty' });
+    if (!stateFileExists && state.state === 'empty')
+        state = createEmptyBrowserPoolState(identity);
+    const staleReason = state.state === 'stale' ? state.lastError || 'Recorded browser is stale' : undefined;
+    const dirtyReason = state.state === 'dirty' ? state.lastError || 'Browser pool state is dirty' : undefined;
+    return {
+        ...state,
+        rootDir,
+        statePath: paths.statePath,
+        lockPath: paths.lockPath,
+        stateFileExists,
+        readOnly: true,
+        staleReason,
+        dirtyReason,
+        nextCommands: browserPoolStatusNextCommands(state),
+    };
+}
+function printBrowserPoolStatusText(result) {
+    const stateLabel = result.state === 'ready' ? 'ready (idle)' : result.state;
+    console.log(`browser pool status: ${stateLabel}`);
+    console.log(`  worker id: ${result.workerId}`);
+    console.log(`  pool id: ${result.poolId}`);
+    console.log(`  max browser processes: ${result.maxBrowserProcesses}`);
+    console.log(`  pid: ${result.pid ?? '-'}`);
+    console.log(`  process group id: ${result.processGroupId ?? '-'}`);
+    console.log(`  CDP URL: ${result.cdpUrl ?? '-'}`);
+    console.log(`  CDP port: ${result.cdpPort ?? '-'}`);
+    console.log(`  user-data dir: ${result.userDataDir ?? '-'}`);
+    console.log(`  active lease id: ${result.activeLeaseId ?? '-'}`);
+    console.log(`  holder: ${result.holder ?? '-'}`);
+    console.log(`  last used at: ${result.lastUsedAt ?? '-'}`);
+    console.log(`  idle expiry: ${result.idleExpiresAt ?? '-'}`);
+    console.log(`  root: ${result.rootDir}`);
+    console.log(`  state file: ${result.stateFileExists ? result.statePath : `${result.statePath} (missing)`}`);
+    if (result.staleReason || result.dirtyReason || result.lastError) {
+        console.log(`  stale/dirty reason: ${result.staleReason || result.dirtyReason || result.lastError}`);
+    }
+    if (result.state === 'stale' || result.state === 'dirty') {
+        console.log('');
+        console.log('Next:');
+        for (const command of result.nextCommands)
+            console.log(`  ${command}`);
+    }
+}
+async function printBrowserPoolStatus(status, options) {
+    const result = await getBrowserPoolStatus(status, options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    printBrowserPoolStatusText(result);
+}
+function browserPoolReapNextCommands(result) {
+    if (result.cleanupStatus === 'failed' || result.state.state === 'dirty') {
+        return [
+            'pibo tools browser-use pool status --json',
+            'pibo tools browser-use health',
+            'pibo tools browser-use pool reap --json',
+        ];
+    }
+    return ['pibo tools browser-use pool status --json'];
+}
+async function getBrowserPoolReap(status, options) {
+    const identity = getBrowserPoolStatusIdentity(options);
+    const rootDir = getBrowserPoolRoot(status, options);
+    const paths = browserPoolPaths(rootDir, identity);
+    const missingState = !existsSync(paths.statePath);
+    const result = missingState
+        ? {
+            reaped: false,
+            eligible: false,
+            reason: 'Browser pool has no recorded browser to reap',
+            affectedLeases: 0,
+            affectedBrowserPools: 0,
+            terminatedProcessTrees: 0,
+            staleStateFiles: 0,
+            cleanupStatus: 'skipped',
+            lastError: 'Browser pool has no recorded browser to reap',
+            state: createEmptyBrowserPoolState(identity),
+        }
+        : await reapIdleBrowserPool(paths, identity, { idleTimeoutMs: options.idleTimeoutMs });
+    return {
+        rootDir,
+        statePath: paths.statePath,
+        lockPath: paths.lockPath,
+        counts: {
+            affectedLeases: result.affectedLeases,
+            affectedBrowserPools: result.affectedBrowserPools,
+            terminatedProcessTrees: result.terminatedProcessTrees,
+            staleStateFiles: result.staleStateFiles,
+        },
+        pools: [{
+                workerId: result.state.workerId,
+                poolId: result.state.poolId,
+                reaped: result.reaped,
+                eligible: result.eligible,
+                reason: result.reason,
+                cleanupStatus: result.cleanupStatus,
+                lastError: result.lastError,
+                state: result.state,
+                terminatedProcessTrees: result.terminatedProcessTrees,
+                staleStateFiles: result.staleStateFiles,
+                affectedLeases: result.affectedLeases,
+            }],
+        nextCommands: browserPoolReapNextCommands(result),
+    };
+}
+function printBrowserPoolReapText(result) {
+    const pool = result.pools[0];
+    const label = pool.cleanupStatus === 'failed' ? 'failed' : pool.reaped ? 'success' : 'no-op';
+    console.log(`browser pool reap: ${label}`);
+    console.log(`  worker id: ${pool.workerId}`);
+    console.log(`  pool id: ${pool.poolId}`);
+    console.log(`  reason: ${pool.reason ?? '-'}`);
+    console.log(`  cleanup status: ${pool.cleanupStatus}`);
+    console.log(`  affected leases: ${result.counts.affectedLeases}`);
+    console.log(`  affected browser pools: ${result.counts.affectedBrowserPools}`);
+    console.log(`  terminated process trees: ${result.counts.terminatedProcessTrees}`);
+    console.log(`  stale state files: ${result.counts.staleStateFiles}`);
+    console.log(`  state file: ${result.statePath}`);
+    if (pool.lastError)
+        console.log(`  error: ${pool.lastError}`);
+    if (pool.cleanupStatus === 'failed' || pool.state.state === 'dirty') {
+        console.log('');
+        console.log('Next:');
+        for (const command of result.nextCommands)
+            console.log(`  ${command}`);
+    }
+}
+async function printBrowserPoolReap(status, options) {
+    const result = await getBrowserPoolReap(status, options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    printBrowserPoolReapText(result);
+}
+function findChromeBinary() {
+    if (process.env.AGENT_BROWSER_EXECUTABLE_PATH && existsSync(process.env.AGENT_BROWSER_EXECUTABLE_PATH)) {
+        return process.env.AGENT_BROWSER_EXECUTABLE_PATH;
+    }
+    if (process.env.PIBO_BROWSER_USE_CHROME && existsSync(process.env.PIBO_BROWSER_USE_CHROME)) {
+        return process.env.PIBO_BROWSER_USE_CHROME;
+    }
+    const candidates = ['google-chrome', 'chromium', 'chromium-browser', 'chrome'];
+    for (const name of candidates) {
+        const result = spawnSync('command', ['-v', name], { shell: true, encoding: 'utf-8' });
+        if (result.status === 0 && result.stdout.trim()) {
+            return result.stdout.trim();
+        }
+    }
+    return undefined;
+}
+function checkStaleCdpState(homeDir) {
+    const stateDir = join(homeDir, 'pibo-cdp');
+    if (!existsSync(stateDir))
+        return { stalePids: 0, stalePorts: 0, details: [] };
+    let stalePids = 0;
+    let stalePorts = 0;
+    const details = [];
+    for (const file of readdirSync(stateDir)) {
+        if (file.endsWith('.pid')) {
+            const pidPath = join(stateDir, file);
+            const text = readFileSync(pidPath, 'utf-8').trim();
+            const pid = Number.parseInt(text, 10);
+            let isDead = false;
+            if (!Number.isFinite(pid) || pid <= 0) {
+                isDead = true;
+            }
+            else {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch {
+                    isDead = true;
+                }
+            }
+            if (isDead) {
+                stalePids += 1;
+                details.push(`stale pid file: ${file}`);
+            }
+        }
+        else if (file.endsWith('.port')) {
+            const base = file.slice(0, -5);
+            const pidPath = join(stateDir, `${base}.pid`);
+            if (!existsSync(pidPath)) {
+                stalePorts += 1;
+                details.push(`orphan port file: ${file}`);
+            }
+        }
+    }
+    return { stalePids, stalePorts, details };
+}
+async function printAgentBrowserHealth(status, json = false) {
+    const wrapperPath = join(status.homeDir, 'bin', 'agent-browser');
+    const wrapperExists = existsSync(wrapperPath);
+    const npmExecutableExists = existsSync(status.executablePath);
+    const chromePath = findChromeBinary();
+    const desktop = detectDesktopEnv();
+    const hasDisplay = hasDesktopDisplay(desktop);
+    const nodeVersion = spawnSync('node', ['--version'], { encoding: 'utf-8' });
+    const npmVersion = spawnSync('npm', ['--version'], { encoding: 'utf-8' });
+    const packageJsonPath = join(status.rootDir, 'node', 'node_modules', 'agent-browser', 'package.json');
+    let packageVersion;
+    try {
+        packageVersion = JSON.parse(readFileSync(packageJsonPath, 'utf-8')).version;
+    }
+    catch {
+        packageVersion = undefined;
+    }
+    const staleState = checkStaleCdpState(status.homeDir);
+    const overall = !wrapperExists || !npmExecutableExists ? 'critical' : staleState.stalePids > 0 || staleState.stalePorts > 0 ? 'degraded' : 'ok';
+    const result = {
+        overall,
+        wrapper: { exists: wrapperExists, path: wrapperPath },
+        npmRuntime: { executable: npmExecutableExists, path: status.executablePath, packageVersion },
+        node: { ok: nodeVersion.status === 0, version: nodeVersion.stdout.trim() },
+        npm: { ok: npmVersion.status === 0, version: npmVersion.stdout.trim() },
+        chrome: { found: Boolean(chromePath), path: chromePath },
+        display: { available: hasDisplay, display: desktop.display, waylandDisplay: desktop.waylandDisplay },
+        staleState: { pidFiles: staleState.stalePids, portFiles: staleState.stalePorts, details: staleState.details },
+        nextCommands: ['pibo tools install agent-browser', 'eval "$(pibo tools env agent-browser)"', 'agent-browser doctor --offline --quick'],
+    };
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`agent-browser health: ${overall}`);
+    console.log(`  wrapper: ${wrapperExists ? 'ok' : 'MISSING'} (${wrapperPath})`);
+    console.log(`  executable: ${npmExecutableExists ? 'ok' : 'MISSING'} (${status.executablePath})`);
+    console.log(`  package version: ${packageVersion ?? 'unknown'}`);
+    console.log(`  node: ${nodeVersion.status === 0 ? nodeVersion.stdout.trim() : 'missing'}`);
+    console.log(`  npm: ${npmVersion.status === 0 ? npmVersion.stdout.trim() : 'missing'}`);
+    console.log(`  chrome: ${chromePath ? `ok (${chromePath})` : 'not found; upstream install may be needed'}`);
+    console.log(`  display: ${hasDisplay ? 'available' : 'none'} (${desktop.display || 'no DISPLAY'})`);
+    console.log(`  stale state: ${staleState.stalePids} stale pid files, ${staleState.stalePorts} orphan port files`);
+    if (overall !== 'ok') {
+        console.log('');
+        console.log('Suggestions:');
+        if (!wrapperExists || !npmExecutableExists)
+            console.log('  Run: pibo tools install agent-browser');
+        if (!chromePath)
+            console.log('  Install Chrome/Chromium or run: agent-browser install');
+        if (staleState.stalePids > 0 || staleState.stalePorts > 0)
+            console.log('  Inspect and release stale sessions before deleting state.');
+    }
+}
+async function printAgentBrowserSessions(status, json = false) {
+    const wrapperPath = ensureAgentBrowserWrapper(status) || status.executablePath;
+    if (!existsSync(status.executablePath)) {
+        const result = { sessions: [], installed: false, nextCommands: ['pibo tools install agent-browser'] };
+        console.log(json ? JSON.stringify(result, null, 2) : 'agent-browser is not installed. Run: pibo tools install agent-browser');
+        return;
+    }
+    const result = spawnSync(wrapperPath, ['session', 'list'], {
+        encoding: 'utf-8',
+        env: { ...process.env, AGENT_BROWSER_HOME: status.homeDir },
+    });
+    if (json) {
+        console.log(JSON.stringify({ installed: true, ok: result.status === 0, stdout: result.stdout, stderr: result.stderr }, null, 2));
+        return;
+    }
+    if (result.stdout.trim())
+        console.log(result.stdout.trimEnd());
+    if (result.status !== 0 && result.stderr.trim())
+        console.error(result.stderr.trimEnd());
+}
+async function printBrowserUseHealth(status, json = false) {
+    const wrapperPath = join(status.homeDir, 'bin', 'browser-use');
+    const wrapperExists = existsSync(wrapperPath);
+    const chromePath = findChromeBinary();
+    const desktop = detectDesktopEnv();
+    const hasDisplay = hasDesktopDisplay(desktop);
+    const staleState = checkStaleCdpState(status.homeDir);
+    let expiredLeases = 0;
+    try {
+        const registry = readRegistry(status);
+        for (const lease of registry.leases) {
+            if (lease.status === 'active' && isExpired(lease))
+                expiredLeases++;
+        }
+    }
+    catch {
+        // ignore registry read errors
+    }
+    const overall = !wrapperExists || !chromePath ? 'critical' : staleState.stalePids > 0 || staleState.stalePorts > 0 || expiredLeases > 0 ? 'degraded' : 'ok';
+    const result = {
+        overall,
+        wrapper: { exists: wrapperExists, path: wrapperPath },
+        chrome: { found: Boolean(chromePath), path: chromePath },
+        display: { available: hasDisplay, display: desktop.display, waylandDisplay: desktop.waylandDisplay },
+        staleState: { pidFiles: staleState.stalePids, portFiles: staleState.stalePorts, details: staleState.details },
+        leases: { expired: expiredLeases },
+    };
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`browser-use health: ${overall}`);
+    console.log(`  wrapper: ${wrapperExists ? 'ok' : 'MISSING'} (${wrapperPath})`);
+    console.log(`  chrome: ${chromePath ? `ok (${chromePath})` : 'NOT FOUND'}`);
+    console.log(`  display: ${hasDisplay ? 'available' : 'none'} (${desktop.display || 'no DISPLAY'})`);
+    console.log(`  stale state: ${staleState.stalePids} stale pid files, ${staleState.stalePorts} orphan port files`);
+    console.log(`  leases: ${expiredLeases} expired`);
+    if (overall !== 'ok') {
+        console.log('');
+        console.log('Suggestions:');
+        if (!wrapperExists)
+            console.log('  Run: pibo tools install browser-use');
+        if (!chromePath)
+            console.log('  Install Chrome/Chromium (e.g. apt install chromium)');
+        if (staleState.stalePids > 0 || staleState.stalePorts > 0) {
+            console.log('  Clean stale state: pibo tools browser-use lease reap-stale');
+        }
+        if (expiredLeases > 0)
+            console.log('  Reap expired leases: pibo tools browser-use lease reap-stale');
+    }
+}
+function printAgentBrowserDiscovery() {
+    console.log(`pibo tools agent-browser - Agent Browser helpers
+
+Start:
+  eval "$(pibo tools env agent-browser)"
+
+Commands:
+  health                      Check Agent Browser health and report issues
+  sessions                    List upstream Agent Browser sessions
+  targets                     List Chrome CDP targets with Chat auth hints
+  attach-chat                 Export the best existing authenticated Chat target
+  auth-template path          Print the default authenticated template profile path
+  auth-template env           Print shell exports for preparing the auth template profile
+  lease acquire               Acquire an isolated authenticated browser slot
+  lease list                  List authenticated browser slots
+  lease release <id>          Release one browser slot
+  lease reap-stale            Release expired browser slots
+
+Next:
+  pibo tools show agent-browser
+  pibo tools guide agent-browser agent-browser
+  pibo tools agent-browser health
+  pibo tools agent-browser lease acquire`);
+}
+function printRalphDiscovery() {
+    console.log(`pibo tools ralph - Ralph job helpers
+
+Commands:
+  pibo ralph templates --json
+  pibo ralph add --template <id> --room <room-id> --start --json
+  pibo ralph list --all --json
+  pibo ralph runs --job <job-id> --json
+  pibo ralph stop <job-id>
+  pibo ralph cancel <job-id>
+
+Next:
+  pibo tools guide ralph ralph
+  pibo ralph templates`);
 }
 function printToolsDiscovery() {
-    console.log(`pibo tools - curated external CLI tools
+    console.log(`pibo tools - curated CLI tools
 
 Commands:
   list                      List curated tools
@@ -169,6 +625,8 @@ Commands:
   path <name>               Print executable path
   env <name>                Print shell exports
   browser-use               Browser-use auth slots and helper commands
+  agent-browser             Agent Browser sessions, targets, and auth slots
+  ralph                     Ralph job helper commands
 
 Next:
   pibo tools list`);
@@ -240,6 +698,159 @@ export async function runToolsCli(argv = process.argv) {
         .argument('<name>')
         .description('Print shell exports for using the tool directly')
         .action(printEnv);
+    program
+        .command('ralph')
+        .description('Ralph job helper commands')
+        .action(printRalphDiscovery);
+    const agentBrowser = program
+        .command('agent-browser')
+        .description('Agent Browser sessions, targets, and auth slots')
+        .action(printAgentBrowserDiscovery);
+    agentBrowser
+        .command('health')
+        .description('Check Agent Browser health and report issues')
+        .option('--json', 'Print machine-readable health data')
+        .action(async (options) => {
+        await printAgentBrowserHealth(getCliToolStatus(requireEntry('agent-browser')), Boolean(options.json));
+    });
+    agentBrowser
+        .command('sessions')
+        .description('List upstream Agent Browser sessions')
+        .option('--json', 'Print machine-readable session output')
+        .action(async (options) => {
+        await printAgentBrowserSessions(getCliToolStatus(requireEntry('agent-browser')), Boolean(options.json));
+    });
+    agentBrowser
+        .command('targets')
+        .description('List Chrome CDP targets with Chat auth hints')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL')
+        .option('--no-probe', 'Only read /json/list without page DOM probes')
+        .option('--json', 'Print machine-readable target data')
+        .action(async (options) => {
+        const status = getCliToolStatus(requireEntry('agent-browser'));
+        const previousHome = process.env.BROWSER_USE_HOME;
+        process.env.BROWSER_USE_HOME = status.homeDir;
+        try {
+            const targets = await listBrowserUseCdpTargets({ cdpUrl: options.cdpUrl, probe: options.probe });
+            if (options.json) {
+                console.log(JSON.stringify({ targets }, null, 2));
+                return;
+            }
+            console.log(formatBrowserUseTargets(targets));
+            if (targets.length === 0)
+                console.log('\nNext: eval "$(pibo tools env agent-browser)"');
+        }
+        finally {
+            if (previousHome === undefined)
+                delete process.env.BROWSER_USE_HOME;
+            else
+                process.env.BROWSER_USE_HOME = previousHome;
+        }
+    });
+    agentBrowser
+        .command('attach-chat')
+        .description('Export the best existing authenticated Chat target')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL')
+        .option('--json', 'Print machine-readable target data')
+        .action(async (options) => {
+        const status = getCliToolStatus(requireEntry('agent-browser'));
+        const previousHome = process.env.BROWSER_USE_HOME;
+        process.env.BROWSER_USE_HOME = status.homeDir;
+        try {
+            const targets = await listBrowserUseCdpTargets({ cdpUrl: options.cdpUrl });
+            const target = selectBestChatTarget(targets);
+            if (!target) {
+                throw new Error(formatCliError({
+                    code: ErrorCode.CLIENT_ERROR,
+                    type: 'AGENT_BROWSER_CHAT_TARGET_NOT_FOUND',
+                    message: 'No authenticated Chat Web target with a composer textarea was found',
+                    suggestion: 'Run `pibo tools agent-browser targets`, reuse an authenticated tab, or acquire a slot with `pibo tools agent-browser lease acquire`.',
+                }));
+            }
+            if (options.json) {
+                console.log(JSON.stringify({ target }, null, 2));
+                return;
+            }
+            const cdpUrl = options.cdpUrl ? normalizeCdpUrlSync(options.cdpUrl) : 'http://127.0.0.1:56663';
+            console.log(`export PIBO_AGENT_BROWSER_CDP_URL='${cdpUrl.replaceAll("'", "'\\''")}'`);
+            printAttachChatExports(target, cdpUrl);
+        }
+        finally {
+            if (previousHome === undefined)
+                delete process.env.BROWSER_USE_HOME;
+            else
+                process.env.BROWSER_USE_HOME = previousHome;
+        }
+    });
+    const agentAuthTemplate = agentBrowser
+        .command('auth-template')
+        .description('Manage the Agent Browser authenticated template profile')
+        .action(() => {
+        console.log(`pibo tools agent-browser auth-template
+
+Commands:
+  path    Print the default authenticated template profile path
+  env     Print shell exports for preparing the auth template profile`);
+    });
+    agentAuthTemplate
+        .command('path')
+        .option('--app <name>', 'Auth pool app name', 'pibo-chat')
+        .description('Print the default authenticated template profile path')
+        .action((options) => {
+        printAgentBrowserAuthTemplatePath(getCliToolStatus(requireEntry('agent-browser')), options.app);
+    });
+    agentAuthTemplate
+        .command('env')
+        .option('--app <name>', 'Auth pool app name', 'pibo-chat')
+        .description('Print shell exports for preparing the auth template profile')
+        .action(async (options) => {
+        await printAgentBrowserAuthTemplateEnv(getCliToolStatus(requireEntry('agent-browser')), options.app);
+    });
+    const agentLease = agentBrowser
+        .command('lease')
+        .description('Acquire and manage isolated Agent Browser slots')
+        .action(() => {
+        console.log(`pibo tools agent-browser lease
+
+Commands:
+  acquire       Acquire an isolated authenticated browser slot
+  list          List authenticated browser slots
+  release <id>  Release one browser slot
+  reap-stale    Release expired browser slots`);
+    });
+    agentLease
+        .command('acquire')
+        .description('Acquire an isolated authenticated browser slot')
+        .option('--app <name>', 'Auth pool app name', 'pibo-chat')
+        .option('--holder <holder>', 'Lease holder label')
+        .option('--ttl-ms <ms>', 'Lease time-to-live in milliseconds', parsePositiveInteger)
+        .option('--max-slots <count>', 'Maximum active slots for the app', parsePositiveInteger)
+        .option('--json', 'Print machine-readable lease data')
+        .action(async (options) => {
+        await acquireAgentBrowserLease(getCliToolStatus(requireEntry('agent-browser')), options);
+    });
+    agentLease
+        .command('list')
+        .description('List authenticated browser slots')
+        .option('--json', 'Print machine-readable lease data')
+        .action(async (options) => {
+        await listAgentBrowserLeases(getCliToolStatus(requireEntry('agent-browser')), Boolean(options.json));
+    });
+    agentLease
+        .command('release')
+        .argument('<id>')
+        .option('--delete-profile', 'Delete the slot browser profile')
+        .description('Release one browser slot')
+        .action(async (id, options) => {
+        await releaseAgentBrowserLease(getCliToolStatus(requireEntry('agent-browser')), id, options);
+    });
+    agentLease
+        .command('reap-stale')
+        .description('Release expired browser slots')
+        .option('--json', 'Print machine-readable reap result')
+        .action(async (options) => {
+        await reapStaleAgentBrowserLeases(getCliToolStatus(requireEntry('agent-browser')), Boolean(options.json));
+    });
     const browserUse = program
         .command('browser-use')
         .description('Browser-use auth slots and helper commands')
@@ -247,7 +858,7 @@ export async function runToolsCli(argv = process.argv) {
     browserUse
         .command('targets')
         .description('List Chrome CDP targets with Chat auth hints')
-        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL', 'http://127.0.0.1:56663')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL')
         .option('--no-probe', 'Only read /json/list without page DOM probes')
         .option('--json', 'Print machine-readable target data')
         .action(async (options) => {
@@ -265,7 +876,7 @@ export async function runToolsCli(argv = process.argv) {
     browserUse
         .command('attach-chat')
         .description('Export the best existing authenticated Chat target')
-        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL', 'http://127.0.0.1:56663')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL')
         .option('--json', 'Print machine-readable target data')
         .action(async (options) => {
         const targets = await listBrowserUseCdpTargets({ cdpUrl: options.cdpUrl });
@@ -282,7 +893,46 @@ export async function runToolsCli(argv = process.argv) {
             console.log(JSON.stringify({ target }, null, 2));
             return;
         }
-        printAttachChatExports(target, options.cdpUrl);
+        const cdpUrl = options.cdpUrl ? normalizeCdpUrlSync(options.cdpUrl) : undefined;
+        printAttachChatExports(target, cdpUrl);
+    });
+    browserUse
+        .command('health')
+        .description('Check browser-use health and report issues')
+        .option('--json', 'Print machine-readable health data')
+        .action(async (options) => {
+        await printBrowserUseHealth(getCliToolStatus(requireEntry('browser-use')), Boolean(options.json));
+    });
+    const pool = browserUse
+        .command('pool')
+        .description('Inspect and reap the managed browser pool')
+        .action(() => {
+        console.log(`pibo tools browser-use pool
+
+Commands:
+  status    Show read-only managed browser-pool status
+  reap      Reap an idle managed browser pool`);
+    });
+    pool
+        .command('status')
+        .description('Show read-only managed browser-pool status')
+        .option('--worker-id <id>', 'Worker id to inspect')
+        .option('--pool-id <id>', 'Browser pool id to inspect')
+        .option('--root <path>', 'Browser pool root directory')
+        .option('--json', 'Print machine-readable pool status')
+        .action(async (options) => {
+        await printBrowserPoolStatus(getCliToolStatus(requireEntry('browser-use')), options);
+    });
+    pool
+        .command('reap')
+        .description('Reap an idle managed browser pool')
+        .option('--worker-id <id>', 'Worker id to inspect')
+        .option('--pool-id <id>', 'Browser pool id to inspect')
+        .option('--root <path>', 'Browser pool root directory')
+        .option('--idle-timeout-ms <ms>', 'Idle timeout in milliseconds (0 means immediately eligible)', parseNonNegativeInteger)
+        .option('--json', 'Print machine-readable reap result')
+        .action(async (options) => {
+        await printBrowserPoolReap(getCliToolStatus(requireEntry('browser-use')), options);
     });
     const authTemplate = browserUse
         .command('auth-template')
@@ -322,7 +972,7 @@ Commands:
         .command('acquire')
         .description('Acquire an isolated authenticated browser slot')
         .option('--app <name>', 'Auth pool app name', 'pibo-chat')
-        .option('--owner <owner>', 'Lease owner label')
+        .option('--holder <holder>', 'Lease holder label')
         .option('--ttl-minutes <minutes>', 'Lease time-to-live in minutes', parsePositiveInteger)
         .option('--max-slots <count>', 'Maximum active slots for the app', parsePositiveInteger)
         .option('--template-dir <path>', 'Authenticated Chrome user-data-dir template to clone')