@phnx-labs/agents-cli 1.20.62 → 1.20.63

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -174,6 +174,8 @@ Run and dispatch:
   defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
+  webhook                         Receive signed GitHub/Linear webhooks for trigger routines
+  funnel                          Expose a webhook receiver through Tailscale Funnel
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
   logs [id]                       Show a run's log — host-dispatch task or session; -f to follow
   browser                         Automate a browser — navigate, click, screenshot, console, network
@@ -702,6 +704,8 @@ async function registerAllEagerCommands() {
     await reg(loadLogs);
     await reg(loadEvents);
     await reg(loadAudit);
+    await reg(loadWebhook);
+    await reg(loadFunnel);
     await reg(loadFeed);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
@@ -875,7 +879,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v12';
+        const sentinelValue = 'v13';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/agents.d.ts

@@ -130,6 +130,32 @@ export interface AccountInfo {
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/**
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
+ */
+export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+} | null;
+/** @internal test hook — clear the per-process keyring probe cache. */
+export declare function __resetAntigravityKeychainCacheForTest(): void;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -1027,31 +1027,69 @@ function decryptDroidCredential(base) {
 }
 let cachedAgyKeychainSignedIn;
 /**
- * Antigravity (`agy`, a Codeium/Windsurf-based CLI) stores its OAuth token in
- * the macOS keychain — service `gemini`, account `antigravity` — NOT a file.
- * The file path (`antigravity-oauth-token`) only exists on Linux, where the Go
- * keyring falls back to disk. Probe the keychain for existence (metadata only;
- * `-w` omitted so it never prompts). Cached per process — the keychain is
- * account-global, so one probe covers every installed version. Returns false on
- * non-macOS (the file path handles those).
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
  */
+export function antigravityOsKeyringProbe(platform = process.platform) {
+    if (platform === 'darwin') {
+        return {
+            cmd: 'security',
+            args: ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'],
+        };
+    }
+    if (platform === 'linux') {
+        // go-keyring secret_service attributes: "service" + "username" (not
+        // "account" — that flag is the macOS security(1) spelling of the same user).
+        return {
+            cmd: 'secret-tool',
+            args: ['lookup', 'service', 'gemini', 'username', 'antigravity'],
+        };
+    }
+    return null;
+}
+/** @internal test hook — clear the per-process keyring probe cache. */
+export function __resetAntigravityKeychainCacheForTest() {
+    cachedAgyKeychainSignedIn = undefined;
+}
 async function antigravityKeychainSignedIn() {
-    if (cachedAgyKeychainSignedIn !== undefined)
-        return cachedAgyKeychainSignedIn;
-    // Test isolation: the real macOS keychain can't be sandboxed per-test, so
-    // allow suites asserting "signed out" to opt out of the probe (same spirit as
-    // AGENTS_REAL_HOME). Not cached, so tests can toggle it.
+    // Test isolation first (before cache): real OS keyrings can't be sandboxed
+    // per-test. Same spirit as AGENTS_REAL_HOME. Not cached, so tests can toggle.
     if (process.env.AGENTS_NO_KEYCHAIN_PROBE === '1')
         return false;
-    if (process.platform !== 'darwin') {
+    if (cachedAgyKeychainSignedIn !== undefined)
+        return cachedAgyKeychainSignedIn;
+    const probe = antigravityOsKeyringProbe();
+    if (!probe) {
         cachedAgyKeychainSignedIn = false;
         return false;
     }
     try {
-        await execFileAsync('security', ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'], { timeout: 3000 });
+        // Discard stdout: Linux secret-tool lookup prints the secret value.
+        await execFileAsync(probe.cmd, probe.args, {
+            timeout: 3000,
+            // encoding so stdout is a string we can drop without ever logging it
+            encoding: 'utf8',
+        });
         cachedAgyKeychainSignedIn = true;
     }
     catch {
+        // Missing tool (ENOENT), missing item, locked collection, timeout → signed out.
         cachedAgyKeychainSignedIn = false;
     }
     return cachedAgyKeychainSignedIn;
@@ -1282,10 +1320,12 @@ export async function getAccountInfo(agentId, home) {
                 // Antigravity (`agy`) stores a consumer Google OAuth grant (access +
                 // refresh token, no id_token) — presence of a refresh token is the only
                 // signed-in signal we can derive without a network call. Storage is
-                // platform-split: on Linux it's a file at
-                // ~/.gemini/antigravity-cli/antigravity-oauth-token; on macOS the Go
-                // keyring puts it in the keychain (service 'gemini', account
-                // 'antigravity'), so no file exists — check both.
+                // platform-split via go-keyring:
+                //   - file ~/.gemini/antigravity-cli/antigravity-oauth-token (Linux
+                //     fallback when no Secret Service is available)
+                //   - macOS keychain / Linux libsecret (service gemini + user
+                //     antigravity) when a keyring daemon is present
+                // Check the file first, then the OS keyring probe.
                 const tokenPath = resolveAccountCredentialPath(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
                 if (tokenPath) {
                     const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));

package/dist/lib/browser/ipc.js

@@ -432,11 +432,12 @@ export class BrowserIPCServer {
                 return { ok: true };
             }
             case 'set-download-path': {
-                if (!request.task || !request.downloadPath) {
-                    return { ok: false, error: 'Task and download path required' };
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
                 }
-                await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
-                return { ok: true };
+                // downloadPath optional: omitted → service defaults to the profile's downloads dir.
+                const resolved = await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
+                return { ok: true, downloadPath: resolved };
             }
             case 'wait-download': {
                 if (!request.task) {

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

@@ -11,6 +11,19 @@ export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export declare function getProfileDownloadsDir(name: string): string;
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export declare function getProfileSessionsDir(name: string, task: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**

package/dist/lib/browser/profiles.js

@@ -19,6 +19,23 @@ export function getBrowserRuntimeDir() {
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export function getProfileDownloadsDir(name) {
+    return path.join(getProfileRuntimeDir(name), 'downloads');
+}
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export function getProfileSessionsDir(name, task) {
+    return path.join(getProfileRuntimeDir(name), 'sessions', task);
+}
 function configToProfile(name, config) {
     validateRemoteBrowserBinaries(config);
     return {

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

@@ -226,7 +226,18 @@ export declare class BrowserService {
         timeout?: number;
         tabHint?: string;
     }): Promise<void>;
-    setDownloadPath(taskId: string, downloadPath: string, tabHint?: string): Promise<void>;
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    private applyDefaultDownloadBehavior;
+    setDownloadPath(taskId: string, downloadPath?: string, tabHint?: string): Promise<string>;
     waitForDownload(taskId: string, timeout?: number): Promise<string>;
     private findTaskBySession;
     shutdown(): Promise<void>;

package/dist/lib/browser/service.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
-import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
+import { getProfile, getProfileRuntimeDir, getProfileDownloadsDir, getProfileSessionsDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
@@ -308,7 +308,9 @@ export class BrowserService {
         }
         else if (!conn) {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
+            conn.profileName = composite;
             this.connections.set(composite, conn);
+            await this.applyDefaultDownloadBehavior(conn, composite);
         }
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
@@ -645,7 +647,7 @@ export class BrowserService {
         return result.result.value;
     }
     async screenshot(taskId, tabHint, outputPath, quality = 'compressed') {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = 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);
@@ -678,7 +680,7 @@ export class BrowserService {
             }
             extension = 'jpg';
         }
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.${extension}`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -695,7 +697,7 @@ export class BrowserService {
      * — without it, dark-mode pages render on a blank sheet.
      */
     async printToPdf(taskId, tabHint, outputPath) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = 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);
@@ -705,7 +707,7 @@ export class BrowserService {
         const sessionId = await this.getSessionId(conn, target.targetId);
         const { data } = (await conn.cdp.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true }, sessionId));
         const buffer = Buffer.from(data, 'base64');
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.pdf`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -723,7 +725,7 @@ export class BrowserService {
         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 { conn, task, profileName } = 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);
@@ -739,7 +741,7 @@ export class BrowserService {
             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');
+        const recordingsDir = path.join(getProfileSessionsDir(profileName, 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.
@@ -1481,20 +1483,50 @@ export class BrowserService {
         throw new Error(`Wait condition "${type}:${value}" not met within ${timeout}ms`);
     }
     // ─── Downloads ───────────────────────────────────────────────────────────────
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    async applyDefaultDownloadBehavior(conn, profileName) {
+        const downloadPath = getProfileDownloadsDir(profileName);
+        try {
+            await fs.promises.mkdir(downloadPath, { recursive: true });
+            await conn.cdp.send('Browser.setDownloadBehavior', {
+                behavior: 'allow',
+                downloadPath,
+                eventsEnabled: true,
+            });
+        }
+        catch {
+            // Best effort: a remote CDP endpoint (ssh://, ws(s)://) may not expose the
+            // Browser domain. Downloads then keep the endpoint's own default; the connect
+            // must still succeed.
+        }
+    }
     async setDownloadPath(taskId, downloadPath, tabHint) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = 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);
+        // No explicit --path: fall back to the profile's downloads dir, the same
+        // destination already set browser-global at connect (applyDefaultDownloadBehavior).
+        const resolvedPath = downloadPath ?? getProfileDownloadsDir(profileName);
+        await fs.promises.mkdir(resolvedPath, { recursive: true });
         await conn.cdp.send('Browser.setDownloadBehavior', {
             behavior: 'allow',
-            downloadPath,
+            downloadPath: resolvedPath,
             eventsEnabled: true,
         }, sessionId);
-        this.pendingDownloads.set(taskId, { path: downloadPath, completed: false });
+        this.pendingDownloads.set(taskId, { path: resolvedPath, completed: false });
         conn.cdp.on('Browser.downloadProgress', (params) => {
             if (params.state === 'completed') {
                 const dl = this.pendingDownloads.get(taskId);
@@ -1504,6 +1536,7 @@ export class BrowserService {
                 }
             }
         });
+        return resolvedPath;
     }
     async waitForDownload(taskId, timeout = 60000) {
         const start = Date.now();
@@ -1590,11 +1623,13 @@ export class BrowserService {
             pid,
             electron: true,
             targetFilter: profile.targetFilter,
+            profileName: forkName,
             forkedFrom: profile.name,
             tasks: new Map(),
             sessionCache: new Map(),
         };
         this.connections.set(forkName, connection);
+        await this.applyDefaultDownloadBehavior(connection, forkName);
         return { forkName, connection };
     }
     /**
@@ -1776,12 +1811,12 @@ export class BrowserService {
             if (!task) {
                 throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
             }
-            return { conn, task };
+            return { conn, task, profileName };
         }
-        for (const [, conn] of this.connections) {
+        for (const [key, conn] of this.connections) {
             const task = conn.tasks.get(taskId);
             if (task) {
-                return { conn, task };
+                return { conn, task, profileName: conn.profileName ?? key };
             }
         }
         throw new Error(`Task "${taskId}" not found`);

package/dist/lib/browser/sessions-list.d.ts

@@ -0,0 +1,40 @@
+export type ArtifactKind = 'screenshot' | 'pdf' | 'recording' | 'download';
+export interface BrowserArtifact {
+    kind: ArtifactKind;
+    /** Owning task for session captures; undefined for downloads. */
+    task?: string;
+    name: string;
+    path: string;
+    bytes: number;
+    mtimeMs: number;
+}
+export interface ProfileArtifacts {
+    profile: string;
+    artifacts: BrowserArtifact[];
+}
+/** Every capture for one profile, newest first. */
+export declare function listProfileArtifacts(profile: string): BrowserArtifact[];
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export declare function listBrowserSessions(only?: string): ProfileArtifacts[];
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export declare function renderBrowserSessions(groups: ProfileArtifacts[]): string;
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
+/** Open a file in the OS default app. Returns true on success. */
+export declare function openArtifact(filePath: string): boolean;
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export declare function runBrowserSessions(opts: {
+    profile?: string;
+    open?: string | boolean;
+    json?: boolean;
+}): void;

package/dist/lib/browser/sessions-list.js

@@ -0,0 +1,190 @@
+/**
+ * Read-only listing of a browser profile's on-disk captures — screenshots, PDFs,
+ * recordings (`<profile>/sessions/<task>/`) and downloads (`<profile>/downloads/`).
+ * Reads straight from `.cache/browser/<profile>/`, so it works whether or not the
+ * browser daemon is running. Backs both `agents browser sessions` and the
+ * `agents sessions --browser` alias.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
+import { formatRelativeTime } from '../session/relative-time.js';
+const EXT_KIND = {
+    '.png': 'screenshot',
+    '.jpg': 'screenshot',
+    '.jpeg': 'screenshot',
+    '.webp': 'screenshot',
+    '.pdf': 'pdf',
+    '.webm': 'recording',
+};
+function statSafe(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function walkFiles(dir) {
+    let out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            out = out.concat(walkFiles(full));
+        else if (e.isFile())
+            out.push(full);
+    }
+    return out;
+}
+/** Every capture for one profile, newest first. */
+export function listProfileArtifacts(profile) {
+    const root = getProfileRuntimeDir(profile);
+    const artifacts = [];
+    const sessionsRoot = path.join(root, 'sessions');
+    let taskDirs = [];
+    try {
+        taskDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true });
+    }
+    catch { /* none */ }
+    for (const t of taskDirs) {
+        if (!t.isDirectory())
+            continue;
+        for (const file of walkFiles(path.join(sessionsRoot, t.name))) {
+            const kind = EXT_KIND[path.extname(file).toLowerCase()];
+            if (!kind)
+                continue;
+            const st = statSafe(file);
+            if (!st)
+                continue;
+            artifacts.push({ kind, task: t.name, name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+        }
+    }
+    for (const file of walkFiles(path.join(root, 'downloads'))) {
+        const st = statSafe(file);
+        if (!st)
+            continue;
+        artifacts.push({ kind: 'download', name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+    }
+    artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return artifacts;
+}
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export function listBrowserSessions(only) {
+    let profiles;
+    if (only) {
+        profiles = [only];
+    }
+    else {
+        try {
+            profiles = fs.readdirSync(getBrowserRuntimeDir(), { withFileTypes: true })
+                .filter((e) => e.isDirectory() && e.name !== 'sessions')
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            profiles = [];
+        }
+    }
+    return profiles
+        .map((p) => ({ profile: p, artifacts: listProfileArtifacts(p) }))
+        .filter((r) => !!only || r.artifacts.length > 0);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let val = n / 1024;
+    let i = 0;
+    while (val >= 1024 && i < units.length - 1) {
+        val /= 1024;
+        i++;
+    }
+    return `${val < 10 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
+}
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export function renderBrowserSessions(groups) {
+    if (groups.length === 0)
+        return 'No browser profiles found.';
+    const lines = [];
+    for (const g of groups) {
+        const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
+        for (const a of g.artifacts)
+            counts[a.kind]++;
+        lines.push(`${g.profile}  ` +
+            `screenshots ${counts.screenshot}  pdfs ${counts.pdf}  recordings ${counts.recording}  downloads ${counts.download}`);
+        if (g.artifacts.length === 0) {
+            lines.push('  (no captures yet)');
+            continue;
+        }
+        for (const a of g.artifacts) {
+            const when = formatRelativeTime(new Date(a.mtimeMs).toISOString());
+            const where = a.kind === 'download' ? 'downloads/' : `sessions/${a.task}/`;
+            lines.push(`  ${when.padEnd(12)}  ${a.name.padEnd(28)}  ${formatBytes(a.bytes).padStart(8)}  ${where}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export function resolveArtifact(groups, selector) {
+    const all = groups.flatMap((g) => g.artifacts).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    if (all.length === 0)
+        return null;
+    if (selector === 'latest')
+        return all[0].path;
+    const hit = all.find((a) => a.name === selector) ?? all.find((a) => a.name.includes(selector));
+    return hit ? hit.path : null;
+}
+/** Open a file in the OS default app. Returns true on success. */
+export function openArtifact(filePath) {
+    const openers = process.platform === 'darwin'
+        ? [['open', [filePath]]]
+        : process.platform === 'win32'
+            ? [['cmd', ['/c', 'start', '""', filePath]]]
+            : [['xdg-open', [filePath]], ['gnome-open', [filePath]]];
+    for (const [cmd, args] of openers) {
+        if (spawnSync(cmd, args, { stdio: 'ignore' }).status === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export function runBrowserSessions(opts) {
+    const groups = listBrowserSessions(opts.profile);
+    if (opts.open !== undefined && opts.open !== false) {
+        const selector = opts.open === true ? 'latest' : opts.open;
+        const target = resolveArtifact(groups, selector);
+        if (!target) {
+            console.error(`No capture matching "${selector}".`);
+            process.exit(1);
+        }
+        console.log(target);
+        if (!openArtifact(target)) {
+            console.error(`Could not open ${target}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(groups, null, 2));
+        return;
+    }
+    console.log(renderBrowserSessions(groups));
+}