@phnx-labs/agents-cli 1.17.1 → 1.17.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.17.3
+
+**Browser**
+
+- `agents browser profiles create` gains `--electron`, `--binary`, and `--target-filter` for driving Electron desktop apps (Canva, Slack, etc.) that expose multiple CDP page targets. The picker matches by `url:<substring>` or `title:<substring>` (case-insensitive) and falls back to a skip-invisible heuristic when no filter is set; misses against an explicit filter throw with the full candidate list. `BrowserService.evaluate` now uses `awaitPromise: true` and surfaces `exceptionDetails` so async script errors propagate as thrown errors. ([#14](https://github.com/phnx-labs/agents-cli/pull/14))
+
+**Secrets**
+
+- `agents secrets list` rework — drop the misleading `SENSITIVE` column and add `SYNC` (iCloud yes/no) plus `CREATED` / `UPDATED` / `USED` relative-age columns. Timestamps live inside the keychain bundle JSON, are stamped on write (created sticky, updated always advances), and on resolve via a 60s throttle. Set `AGENTS_NO_USAGE_TRACK=1` to disable the usage stamp. `agents secrets view` shows the matching absolute ISO + relative age fields. ([#18](https://github.com/phnx-labs/agents-cli/pull/18))
+
+## 1.17.2
+
+**Fixes**
+
+- Auto-update prompt no longer hangs in non-interactive environments (CI, k8s pods, cloud sandbox factories). The TTY check now requires both stdin and stdout to be terminals before prompting, and `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` forces the check off entirely for headless deploys. ([#15](https://github.com/phnx-labs/agents-cli/issues/15))
+
 ## 1.17.1
 
 **Agent management**

package/README.md

@@ -588,6 +588,8 @@ The installer tries Bun first (faster), falls back to npm. Node 18+ required at
 
 Yes -- `agents run` is non-interactive by default. `--yes` auto-accepts prompts, `--json` for structured output. Pass explicit names and IDs instead of relying on interactive pickers.
 
+The auto-update prompt is suppressed automatically when stdin or stdout isn't a TTY. For headless environments where TTY detection misfires (k8s pods that allocate a PTY for stdout, cloud sandbox factories), set `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` to skip the update check entirely -- no prompt, no network call.
+
 ### What happens to my config when I switch versions?
 
 Each version has its own isolated config directory. Switching just repoints a symlink — your per-version config stays untouched. On first migration (if you had a real `~/.claude/` directory before using agents-cli), that gets backed up once to `~/.agents-system/backups/`.

package/dist/commands/browser.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, } from '../lib/browser/profiles.js';
 import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
+import { parseTargetFilter } from '../lib/browser/service.js';
 import { sendIPCRequest } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
@@ -51,7 +52,7 @@ function registerProfilesCommands(browser) {
             }
         }
     });
-    const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge'];
+    const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge', 'custom'];
     profiles
         .command('create <name>')
         .description('Create a new browser profile')
@@ -62,6 +63,9 @@ function registerProfilesCommands(browser) {
         .option('--headless', 'Run in headless mode')
         .option('--window <WxH>', 'Window size, e.g. 1512x982')
         .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
+        .option('--binary <path>', 'Absolute path to the browser/app binary (required with --browser custom)')
+        .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
+        .option('--target-filter <expr>', 'Pick the visible CDP page target when the app exposes more than one. Format: url:<substring> or title:<substring>')
         .action(async (name, opts) => {
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
             console.error('Profile name must be lowercase alphanumeric with hyphens');
@@ -71,6 +75,25 @@ function registerProfilesCommands(browser) {
             console.error(`Invalid browser type. Must be one of: ${VALID_BROWSERS.join(', ')}`);
             process.exit(1);
         }
+        if (opts.browser === 'custom' && !opts.binary) {
+            console.error('--browser custom requires --binary <path>');
+            process.exit(1);
+        }
+        if (opts.targetFilter) {
+            // Route through the same parser the runtime uses so the CLI gate matches
+            // the runtime contract — `url:` (empty value) and `url: foo` (leading
+            // whitespace) both pass a naive `kind` check but produce a silent
+            // heuristic fallback at runtime.
+            const parsed = parseTargetFilter(String(opts.targetFilter));
+            if (!parsed) {
+                console.error('--target-filter must be url:<substring> or title:<substring> (non-empty value, no leading whitespace)');
+                process.exit(1);
+            }
+            if (!opts.electron) {
+                console.error('--target-filter requires --electron (the filter is only consulted on Electron profiles)');
+                process.exit(1);
+            }
+        }
         // Auto-assign a free port if no endpoint was provided
         let endpoints = opts.endpoint;
         if (endpoints.length === 0) {
@@ -104,6 +127,9 @@ function registerProfilesCommands(browser) {
             name,
             description: opts.description,
             browser: opts.browser,
+            binary: opts.binary,
+            electron: opts.electron || undefined,
+            targetFilter: opts.targetFilter,
             endpoints,
             secrets: opts.secrets,
             chrome: opts.headless ? { headless: true } : undefined,
@@ -133,6 +159,12 @@ function registerProfilesCommands(browser) {
         }
         console.log(`Name: ${profile.name}`);
         console.log(`Browser: ${profile.browser}`);
+        if (profile.binary)
+            console.log(`Binary: ${profile.binary}`);
+        if (profile.electron)
+            console.log(`Electron: true`);
+        if (profile.targetFilter)
+            console.log(`Target filter: ${profile.targetFilter}`);
         if (profile.description)
             console.log(`Description: ${profile.description}`);
         console.log(`Endpoints:`);

package/dist/commands/secrets.js

@@ -128,16 +128,78 @@ function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
+/** Strip ANSI escape sequences so padding can be computed on visible width. */
+function visibleWidth(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+/** padEnd that respects ANSI color codes (chalk-wrapped strings have invisible bytes). */
+function padVisible(s, n) {
+    const w = visibleWidth(s);
+    if (w >= n)
+        return s;
+    return s + ' '.repeat(n - w);
+}
+/** Render an ISO-8601 timestamp as a compact relative age: "now", "5m", "1h", "3d", "2w", "4mo", "1y". */
+function relativeAge(iso) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return '-';
+    const deltaMs = Date.now() - t;
+    if (deltaMs < 0)
+        return 'now';
+    const sec = Math.floor(deltaMs / 1000);
+    if (sec < 60)
+        return 'now';
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h`;
+    const day = Math.floor(hr / 24);
+    if (day < 7)
+        return `${day}d`;
+    if (day < 30)
+        return `${Math.floor(day / 7)}w`;
+    const mo = Math.floor(day / 30);
+    if (mo < 12)
+        return `${mo}mo`;
+    return `${Math.floor(day / 365)}y`;
+}
+/** Long-form relative age for the `view` command. "now" stays as "now"; otherwise appends " ago". */
+function humanAge(iso) {
+    const age = relativeAge(iso);
+    if (age === 'now' || age === '-')
+        return age;
+    return `${age} ago`;
+}
 /** Format a single bundle as a table row for the `secrets list` output. */
 function renderBundleRow(b) {
     const entries = describeBundle(b);
     const keys = entries.length;
-    const sensitive = entries.filter((e) => e.kind === 'keychain').length;
-    const expiring = countExpiringSoon(b.meta);
-    const expiringCol = expiring > 0
-        ? chalk.yellow(String(expiring).padEnd(10))
-        : ''.padEnd(10);
-    return `${chalk.cyan(b.name.padEnd(20))} ${String(keys).padEnd(6)} ${chalk.yellow(String(sensitive).padEnd(10))} ${expiringCol} ${chalk.gray(b.description || '')}`;
+    const sync = b.icloud_sync ? chalk.cyan('icloud') : '';
+    const expiringCount = countExpiringSoon(b.meta);
+    const expiring = expiringCount > 0 ? chalk.yellow(String(expiringCount)) : chalk.gray('-');
+    // Timestamp distinction:
+    //   "?"     -> legacy bundle, never written under the timestamping code.
+    //   "never" -> bundle has been written but the action never happened
+    //              (currently only used for USED — CREATED/UPDATED are always
+    //              set together by writeBundle).
+    //   <age>   -> real data.
+    const created = b.created_at ? relativeAge(b.created_at) : chalk.gray('?');
+    const updated = b.updated_at ? relativeAge(b.updated_at) : chalk.gray('?');
+    const used = b.last_used
+        ? relativeAge(b.last_used)
+        : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
+    const head = `${chalk.cyan(b.name.padEnd(20))} ` +
+        `${String(keys).padEnd(5)} ` +
+        `${padVisible(sync, 6)} ` +
+        `${padVisible(expiring, 9)} ` +
+        `${padVisible(created, 9)} ` +
+        `${padVisible(updated, 9)} ` +
+        `${padVisible(used, 7)}`;
+    return b.description ? `${head} ${chalk.gray(b.description)}` : head.trimEnd();
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -340,7 +402,7 @@ Examples:
             console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(6)} ${'SENSITIVE'.padEnd(10)} ${'EXPIRING'.padEnd(10)} DESCRIPTION`));
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'SYNC'.padEnd(6)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
         for (const b of bundles) {
             console.log(renderBundleRow(b));
         }
@@ -363,6 +425,12 @@ Examples:
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.icloud_sync)
                 console.log(chalk.cyan('icloud_sync: true'));
+            if (bundle.created_at)
+                console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
+            if (bundle.updated_at)
+                console.log(chalk.gray(`updated_at: ${bundle.updated_at} (${humanAge(bundle.updated_at)})`));
+            if (bundle.last_used)
+                console.log(chalk.gray(`last_used:  ${bundle.last_used} (${humanAge(bundle.last_used)})`));
             console.log();
             if (entries.length === 0) {
                 console.log(chalk.gray('(no keys)'));

package/dist/index.js

@@ -60,7 +60,7 @@ import { registerUsageCommand } from './commands/usage.js';
 import { registerAliasCommand } from './commands/alias.js';
 import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
-import { isPromptCancelled } from './commands/utils.js';
+import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
 import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
@@ -240,7 +240,7 @@ function saveUpdateCheck(latestVersion) {
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
-    if (!process.stdout.isTTY) {
+    if (!isInteractiveTerminal()) {
         console.error(chalk.yellow(`Update available: ${VERSION} -> ${latestVersion}. Run: npm install -g @phnx-labs/agents-cli@latest`));
         return;
     }
@@ -309,6 +309,8 @@ function refreshUpdateCacheInBackground() {
 }
 /** Check for available updates using the local cache. Triggers a background refresh if stale. */
 async function checkForUpdates() {
+    if (process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE)
+        return;
     const cache = readUpdateCache();
     // Kick off network refresh in background if stale. Does not block.
     if (shouldFetchLatest(cache)) {

package/dist/lib/browser/profiles.js

@@ -15,6 +15,7 @@ function configToProfile(name, config) {
         browser: config.browser,
         binary: config.binary,
         electron: config.electron,
+        targetFilter: config.targetFilter,
         endpoints: config.endpoints,
         chrome: config.chrome,
         secrets: config.secrets,
@@ -32,6 +33,8 @@ function profileToConfig(profile) {
         config.binary = profile.binary;
     if (profile.electron)
         config.electron = profile.electron;
+    if (profile.targetFilter)
+        config.targetFilter = profile.targetFilter;
     if (profile.chrome)
         config.chrome = profile.chrome;
     if (profile.secrets)

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

@@ -1,5 +1,38 @@
 import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
 import { type RefOpts, type RefNode } from './refs.js';
+import type { TargetFilter } from './types.js';
+/**
+ * Parse a `targetFilter` string into its kind + value, or return `null`
+ * when the input is missing or malformed. Filter syntax:
+ *   - `url:<substring>`   — picks the first page target whose URL contains the substring
+ *   - `title:<substring>` — picks the first page target whose title contains the substring
+ *
+ * The match is case-insensitive on both sides because Electron apps
+ * frequently lowercase or title-case their target metadata in unpredictable ways.
+ */
+export declare function parseTargetFilter(filter: string | undefined): TargetFilter | null;
+/**
+ * Choose the CDP page target that represents the visible UI.
+ *
+ * Order:
+ *   1. If `filter` is set and parseable, narrow to page targets matching it
+ *      (case-insensitive substring). Among matches, prefer one that is not in
+ *      `INVISIBLE_URL_PATTERNS` — this is the tiebreaker that makes a coarse
+ *      filter like `url:https://www.canva.com/` skip the background service
+ *      (`https://www.canva.com/_desktop-background-service` *also* matches the
+ *      substring). If every match is invisible, return the first match so the
+ *      caller still gets something rather than silently falling through.
+ *      An explicit filter that finds *no* match returns `undefined` — callers
+ *      should surface this as an error rather than create an orphan window.
+ *   2. If `filter` is unset (or unparseable), apply the skip-invisible heuristic
+ *      across all page targets.
+ *   3. As a last resort, return the first page target.
+ */
+export declare function pickWindowTarget<T extends {
+    type: string;
+    url?: string;
+    title?: string;
+}>(targets: T[], filter: string | undefined): T | undefined;
 export declare class BrowserService {
     private connections;
     private forkingProfiles;

package/dist/lib/browser/service.js

@@ -9,6 +9,87 @@ import { generateTaskId, generateShortId, generateFunName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { emit } from '../events.js';
+/**
+ * Parse a `targetFilter` string into its kind + value, or return `null`
+ * when the input is missing or malformed. Filter syntax:
+ *   - `url:<substring>`   — picks the first page target whose URL contains the substring
+ *   - `title:<substring>` — picks the first page target whose title contains the substring
+ *
+ * The match is case-insensitive on both sides because Electron apps
+ * frequently lowercase or title-case their target metadata in unpredictable ways.
+ */
+export function parseTargetFilter(filter) {
+    if (!filter)
+        return null;
+    const idx = filter.indexOf(':');
+    if (idx <= 0)
+        return null;
+    const kind = filter.slice(0, idx).trim().toLowerCase();
+    // Strip whitespace around the value so `url: https://x` (with a copy-pasted
+    // space after the colon) doesn't silently fail to match — `.includes(' x')`
+    // never hits a URL because URLs don't contain spaces.
+    const value = filter.slice(idx + 1).trim();
+    if (kind !== 'url' && kind !== 'title')
+        return null;
+    if (!value)
+        return null;
+    return { kind, value };
+}
+/**
+ * URLs that the skip-invisible heuristic excludes when no explicit filter
+ * matches. These are page targets Electron apps ship for housekeeping;
+ * picking one means screenshots come back blank.
+ */
+const INVISIBLE_URL_PATTERNS = [
+    /^about:blank$/i,
+    /^file:\/\//i,
+    /\/_desktop-background-service(\?|$|\/)/i,
+    /\/_internal(\?|$|\/)/i,
+    /\/_background(\?|$|\/)/i,
+];
+function isLikelyInvisible(url) {
+    if (!url)
+        return true;
+    return INVISIBLE_URL_PATTERNS.some((re) => re.test(url));
+}
+/**
+ * Choose the CDP page target that represents the visible UI.
+ *
+ * Order:
+ *   1. If `filter` is set and parseable, narrow to page targets matching it
+ *      (case-insensitive substring). Among matches, prefer one that is not in
+ *      `INVISIBLE_URL_PATTERNS` — this is the tiebreaker that makes a coarse
+ *      filter like `url:https://www.canva.com/` skip the background service
+ *      (`https://www.canva.com/_desktop-background-service` *also* matches the
+ *      substring). If every match is invisible, return the first match so the
+ *      caller still gets something rather than silently falling through.
+ *      An explicit filter that finds *no* match returns `undefined` — callers
+ *      should surface this as an error rather than create an orphan window.
+ *   2. If `filter` is unset (or unparseable), apply the skip-invisible heuristic
+ *      across all page targets.
+ *   3. As a last resort, return the first page target.
+ */
+export function pickWindowTarget(targets, filter) {
+    const pages = targets.filter((t) => t.type === 'page');
+    if (pages.length === 0)
+        return undefined;
+    const parsed = parseTargetFilter(filter);
+    if (parsed) {
+        const needle = parsed.value.toLowerCase();
+        const matches = pages.filter((t) => {
+            const hay = (parsed.kind === 'url' ? t.url : t.title) ?? '';
+            return hay.toLowerCase().includes(needle);
+        });
+        if (matches.length === 0)
+            return undefined;
+        const visible = matches.find((t) => !isLikelyInvisible(t.url));
+        return visible ?? matches[0];
+    }
+    const visible = pages.find((t) => !isLikelyInvisible(t.url));
+    if (visible)
+        return visible;
+    return pages[0];
+}
 export class BrowserService {
     connections = new Map();
     forkingProfiles = new Set();
@@ -351,7 +432,25 @@ export class BrowserService {
             throw new Error(`Tab ${shortId} not found`);
         }
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const result = (await conn.cdp.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId));
+        // `awaitPromise: true` lets callers write `evaluate '(async () => {...})()'`
+        // and get the resolved value back instead of a stringified Promise. This
+        // is essential for any flow that needs sub-step waits inside the page
+        // (e.g. driving a multi-step modal where each step needs React to settle
+        // before the next call). Without it, the shell-side workaround is to
+        // chain N separate `evaluate` calls with `sleep` between them, which
+        // races against the page's own state machine.
+        //
+        // `exceptionDetails` is surfaced as a thrown error so a rejected promise
+        // or a thrown error inside the expression doesn't silently return `undefined`.
+        const result = (await conn.cdp.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, sessionId));
+        if (result.exceptionDetails) {
+            const ex = result.exceptionDetails;
+            const msg = ex.exception?.description ??
+                (typeof ex.exception?.value === 'string' ? ex.exception.value : undefined) ??
+                ex.text ??
+                'evaluate failed';
+            throw new Error(msg);
+        }
         return result.result.value;
     }
     async screenshot(taskId, tabHint, outputPath) {
@@ -839,6 +938,7 @@ export class BrowserService {
             port,
             pid,
             electron: true,
+            targetFilter: profile.targetFilter,
             forkedFrom: profile.name,
             tasks: new Map(),
             sessionCache: new Map(),
@@ -860,6 +960,7 @@ export class BrowserService {
                 port: existingInfo.port,
                 pid: existingInfo.pid,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks,
                 sessionCache: new Map(),
             };
@@ -889,6 +990,7 @@ export class BrowserService {
                 port: conn.port,
                 pid: conn.pid,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: conn.pid === 0 ? this.loadTaskState(profile.name) : new Map(),
                 sessionCache: new Map(),
             };
@@ -901,6 +1003,7 @@ export class BrowserService {
                 port: conn.port,
                 pid: conn.pid,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: new Map(),
                 sessionCache: new Map(),
             };
@@ -914,6 +1017,7 @@ export class BrowserService {
                 port: 0,
                 pid: 0,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: this.loadTaskState(profile.name),
                 sessionCache: new Map(),
             };
@@ -930,6 +1034,7 @@ export class BrowserService {
                 port,
                 pid: 0,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: this.loadTaskState(profile.name),
                 sessionCache: new Map(),
             };
@@ -951,11 +1056,24 @@ export class BrowserService {
         }
         // Check if browser already has a page target we can use
         const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
-        const existing = targetInfos.find((t) => t.type === 'page');
+        const existing = pickWindowTarget(targetInfos, conn.targetFilter);
         if (existing) {
             conn.windowId = existing.targetId;
             return existing.targetId;
         }
+        // If we have an explicit filter, `pickWindowTarget` returns undefined when nothing
+        // matches. That almost always means the profile is misconfigured (typo in the
+        // filter, target hasn't loaded yet, app version moved the URL). Falling through
+        // to `Target.createTarget` would silently create an orphan tab the user can't see.
+        // Surface the failure instead, with the candidate list so the fix is obvious.
+        if (parseTargetFilter(conn.targetFilter)) {
+            const candidates = targetInfos
+                .filter((t) => t.type === 'page')
+                .map((t) => `  - url=${t.url ?? ''} title=${t.title ?? ''}`)
+                .join('\n');
+            throw new Error(`Target filter ${JSON.stringify(conn.targetFilter)} matched no page target.\n` +
+                `Available page targets:\n${candidates || '  (none)'}`);
+        }
         // First ever use - create window
         const result = (await conn.cdp.send('Target.createTarget', {
             url: 'about:blank',

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

@@ -5,6 +5,11 @@ export interface BrowserProfile {
     browser: BrowserType;
     binary?: string;
     electron?: boolean;
+    /**
+     * `url:<substring>` or `title:<substring>`. Picks which CDP page target
+     * represents the visible UI for Electron apps with multiple WebContents.
+     */
+    targetFilter?: string;
     endpoints: string[];
     chrome?: ChromeOptions;
     secrets?: string;
@@ -15,6 +20,11 @@ export interface BrowserProfile {
         y?: number;
     };
 }
+/** Parsed form of `BrowserProfile.targetFilter`. */
+export interface TargetFilter {
+    kind: 'url' | 'title';
+    value: string;
+}
 export interface ChromeOptions {
     headless?: boolean;
     args?: string[];

package/dist/lib/secrets/bundles.d.ts

@@ -30,6 +30,12 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** When true, keychain-backed values and bundle metadata sync via iCloud Keychain. */
     icloud_sync?: boolean;
+    /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
+    created_at?: string;
+    /** ISO 8601 UTC timestamp. Refreshed on every writeBundle(). */
+    updated_at?: string;
+    /** ISO 8601 UTC timestamp. Stamped by resolveBundleEnv (throttled). */
+    last_used?: string;
     vars: Record<string, BundleValue>;
     /** Optional per-var metadata, keyed by var name (parallel to `vars`). */
     meta?: Record<string, VarMeta>;

package/dist/lib/secrets/bundles.js

@@ -29,6 +29,8 @@ export const SECRET_TYPES = [
     'webhook',
     'note',
 ];
+/** Minimum gap between last_used updates so the keychain isn't written on every secrets injection. */
+const LAST_USED_THROTTLE_MS = 60_000;
 const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
 const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
@@ -109,6 +111,12 @@ export function readBundle(name) {
         icloud_sync: Boolean(parsed.icloud_sync),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
+    if (typeof parsed.created_at === 'string')
+        bundle.created_at = parsed.created_at;
+    if (typeof parsed.updated_at === 'string')
+        bundle.updated_at = parsed.updated_at;
+    if (typeof parsed.last_used === 'string')
+        bundle.last_used = parsed.last_used;
     if (parsed.meta && typeof parsed.meta === 'object') {
         bundle.meta = parsed.meta;
     }
@@ -140,10 +148,20 @@ export function writeBundle(bundle) {
             }
         }
     }
+    // Stamp timestamps on the bundle so callers see what got persisted. created_at
+    // is sticky — once set we never overwrite it, including on legacy bundles
+    // that already carry one. updated_at always advances.
+    const now = new Date().toISOString();
+    if (!bundle.created_at)
+        bundle.created_at = now;
+    bundle.updated_at = now;
     const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         icloud_sync: bundle.icloud_sync ? true : undefined,
+        created_at: bundle.created_at,
+        updated_at: bundle.updated_at,
+        last_used: bundle.last_used,
         vars: bundle.vars,
         meta,
     };
@@ -194,11 +212,33 @@ export function describeBundle(bundle) {
     }
     return out;
 }
+// Bump `bundle.last_used` and persist the bundle, but no more than once per
+// throttle window so we don't pay a keychain write on every agent run. Failures
+// are swallowed — usage tracking is never allowed to break secret resolution.
+// Set AGENTS_NO_USAGE_TRACK=1 to disable the stamp entirely (used by tests).
+function stampLastUsed(bundle) {
+    if (process.env.AGENTS_NO_USAGE_TRACK)
+        return;
+    const nowMs = Date.now();
+    if (bundle.last_used) {
+        const prev = Date.parse(bundle.last_used);
+        if (Number.isFinite(prev) && nowMs - prev < LAST_USED_THROTTLE_MS)
+            return;
+    }
+    try {
+        bundle.last_used = new Date(nowMs).toISOString();
+        writeBundle(bundle);
+    }
+    catch {
+        // Swallow — telemetry must never block secret resolution.
+    }
+}
 // Walk the bundle and produce a flat env map. Keychain refs are translated via
 // the bundle-scoped naming scheme so two bundles with the same short ID never
 // collide. Throws on the first missing secret so `agents run` fails loudly
 // rather than silently injecting empty strings.
 export function resolveBundleEnv(bundle) {
+    stampLastUsed(bundle);
     const env = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
         const parsed = parseBundleValue(raw);

package/dist/lib/types.d.ts

@@ -426,6 +426,16 @@ export interface BrowserProfileConfig {
     browser: 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
     binary?: string;
     electron?: boolean;
+    /**
+     * Selects which CDP page target represents the visible UI when the
+     * browser/app exposes more than one. Format: `url:<substring>` or
+     * `title:<substring>`. Recommended for Electron apps that ship hidden
+     * helper WebContents (background services, OAuth windows, file://
+     * shells); without an explicit filter the connector falls back to a
+     * skip-invisible heuristic before picking the first page target.
+     * Only consulted when `electron` is true.
+     */
+    targetFilter?: string;
     endpoints: string[];
     chrome?: {
         headless?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.17.1",
+  "version": "1.17.3",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",