@phnx-labs/agents-cli 1.17.2 → 1.17.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.17.4
+
+**Browser**
+
+- `agents browser type` now detects rich-text editor frameworks (Lexical, ProseMirror, Slate, Draft.js, Quill, CKEditor5, Trix) by walking up to 5 ancestor levels from each textbox and tagging refs with `[editor=<framework>]`. Editor-tagged refs route through the WHATWG `beforeinput` dispatch (`InputEvent('beforeinput', { inputType: 'insertText', ... })`) for Lexical/ProseMirror/Slate/Quill/CKEditor5/Draft and `el.editor.insertString()` for Trix. `agents browser refs --json` surfaces the new `editor` field, and `type --clear` prepends a select-all + `deleteContentBackward` dispatch before inserting.
+- Plain-input reliability also improved: `typeText` now issues a single CDP `Input.insertText` instead of per-character `dispatchKeyEvent`, so framework-controlled inputs (React, Vue, Solid, MUI/Chakra/Mantine `TextField`, masked-number fields, Canva-style pickers) actually receive `beforeinput`/`input`/`textInput` events. `focusNode` falls back to the first focusable descendant when `DOM.focus` throws "Element is not focusable" — fixes wrapper-ref UIs like Slack composer, Linear comments, Notion blocks, and every MUI/Chakra/Mantine `TextField`. ([#12](https://github.com/phnx-labs/agents-cli/pull/12))
+
+## 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**

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:`);
@@ -722,6 +754,7 @@ function registerTaskCommands(browser) {
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--all', 'Include non-interactive elements')
         .option('-l, --limit <n>', 'Max elements (default 500)', '500')
+        .option('--json', 'Output machine-readable JSON')
         .action(async (task, opts) => {
         const response = await sendIPCRequest({
             action: 'refs',
@@ -731,9 +764,18 @@ function registerTaskCommands(browser) {
             limit: parseInt(opts.limit, 10),
         });
         if (!response.ok) {
-            console.error(response.error);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: response.error }));
+            }
+            else {
+                console.error(response.error);
+            }
             process.exit(1);
         }
+        if (opts.json) {
+            console.log(JSON.stringify(response.nodes ?? [], null, 2));
+            return;
+        }
         console.log(response.refs);
     });
     browser
@@ -757,6 +799,7 @@ function registerTaskCommands(browser) {
         .command('type <task> <ref> <text>')
         .description('Type text into an element by ref')
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('--clear', 'Clear editor content before typing')
         .action(async (task, ref, text, opts) => {
         const response = await sendIPCRequest({
             action: 'type',
@@ -764,6 +807,7 @@ function registerTaskCommands(browser) {
             tabId: opts.tab,
             ref: parseInt(ref, 10),
             text,
+            clear: opts.clear,
         });
         if (!response.ok) {
             console.error(response.error);

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/lib/browser/editor.d.ts

@@ -0,0 +1,3 @@
+import type { CDPClient } from './cdp.js';
+import type { RefNode } from './refs.js';
+export declare function typeEditorText(cdp: CDPClient, sessionId: string, node: RefNode, text: string, clear?: boolean): Promise<void>;

package/dist/lib/browser/editor.js

@@ -0,0 +1,50 @@
+const BEFOREINPUT_INSERT_FN = `(function(text) {
+  this.focus();
+  var sel = window.getSelection();
+  var range = document.createRange();
+  range.selectNodeContents(this);
+  range.collapse(false);
+  sel.removeAllRanges();
+  sel.addRange(range);
+  this.dispatchEvent(new InputEvent('beforeinput', {
+    inputType: 'insertText',
+    data: text,
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  }));
+})`;
+const BEFOREINPUT_CLEAR_FN = `(function() {
+  this.focus();
+  var sel = window.getSelection();
+  var range = document.createRange();
+  range.selectNodeContents(this);
+  sel.removeAllRanges();
+  sel.addRange(range);
+  this.dispatchEvent(new InputEvent('beforeinput', {
+    inputType: 'deleteContentBackward',
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  }));
+})`;
+const TRIX_INSERT_FN = `(function(text) { this.editor.insertString(text); })`;
+export async function typeEditorText(cdp, sessionId, node, text, clear = false) {
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId: node.backendNodeId }, sessionId);
+    if (!object.objectId)
+        throw new Error(`Could not resolve DOM node for ref ${node.ref}`);
+    const objectId = object.objectId;
+    try {
+        if (node.editor === 'trix') {
+            await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: TRIX_INSERT_FN, arguments: [{ value: text }], returnByValue: true }, sessionId);
+            return;
+        }
+        if (clear) {
+            await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: BEFOREINPUT_CLEAR_FN, arguments: [], returnByValue: true }, sessionId);
+        }
+        await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: BEFOREINPUT_INSERT_FN, arguments: [{ value: text }], returnByValue: true }, sessionId);
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
+}

package/dist/lib/browser/input.js

@@ -8,11 +8,13 @@ export async function hoverAtCoords(cdp, sessionId, x, y) {
 export async function scrollAtCoords(cdp, sessionId, x, y, deltaX, deltaY) {
     await cdp.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x, y, deltaX, deltaY }, sessionId);
 }
+// `Input.insertText` is the CDP native text-insertion method. It dispatches a
+// real `beforeinput`/`input`/`textInput` sequence on the focused element, which
+// is what framework-controlled inputs (React, Vue, Solid, contenteditable
+// editors) actually listen for. Per-character `dispatchKeyEvent` only fires
+// `keydown`/`keyup` with no input event, so controlled inputs ignore it.
 export async function typeText(cdp, sessionId, text) {
-    for (const char of text) {
-        await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', text: char }, sessionId);
-        await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', text: char }, sessionId);
-    }
+    await cdp.send('Input.insertText', { text }, sessionId);
 }
 const KEY_CODES = {
     Enter: { key: 'Enter', code: 'Enter', keyCode: 13 },
@@ -50,6 +52,41 @@ export async function pressKey(cdp, sessionId, keyName) {
         nativeVirtualKeyCode: keyInfo.keyCode,
     }, sessionId);
 }
+const FOCUS_DESCENDANT_FN = `(function() {
+  const selector = 'input:not([disabled]):not([type=hidden]),textarea:not([disabled]),select:not([disabled]),[contenteditable=""],[contenteditable=true],[tabindex]:not([tabindex="-1"])';
+  const candidates = this.querySelectorAll(selector);
+  for (const el of candidates) {
+    el.focus();
+    if (document.activeElement === el) return true;
+  }
+  return false;
+})`;
+// `DOM.focus` only works on natively focusable elements. UIs that wrap real
+// inputs in styled containers (Slack composer, Linear comments, Notion blocks,
+// Canva pickers, MUI/Chakra/Mantine TextField) often expose the wrapper as the
+// accessible "ref" — focusing it throws "Element is not focusable". When that
+// happens, walk the subtree for the first focusable descendant.
 export async function focusNode(cdp, sessionId, backendNodeId) {
-    await cdp.send('DOM.focus', { backendNodeId }, sessionId);
+    try {
+        await cdp.send('DOM.focus', { backendNodeId }, sessionId);
+        return;
+    }
+    catch (err) {
+        const focused = await focusFirstFocusableDescendant(cdp, sessionId, backendNodeId);
+        if (!focused)
+            throw err;
+    }
+}
+async function focusFirstFocusableDescendant(cdp, sessionId, backendNodeId) {
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
+    if (!object.objectId)
+        return false;
+    const objectId = object.objectId;
+    try {
+        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: FOCUS_DESCENDANT_FN, returnByValue: true }, sessionId);
+        return result.value === true;
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
 }

package/dist/lib/browser/ipc.js

@@ -164,11 +164,17 @@ export class BrowserIPCServer {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
                 }
-                const { refs } = await this.service.refs(request.task, request.tabId, {
+                const { refs, nodeMap } = await this.service.refs(request.task, request.tabId, {
                     interactive: request.interactive ?? true,
                     limit: request.limit ?? 500,
                 });
-                return { ok: true, refs };
+                const nodes = Array.from(nodeMap.values()).map(n => {
+                    const entry = { ref: n.ref, role: n.role, name: n.name, attrs: n.attrs };
+                    if (n.editor !== undefined)
+                        entry.editor = n.editor;
+                    return entry;
+                });
+                return { ok: true, refs, nodes };
             }
             case 'click': {
                 if (!request.task || request.ref === undefined) {
@@ -181,7 +187,7 @@ export class BrowserIPCServer {
                 if (!request.task || request.ref === undefined || !request.text) {
                     return { ok: false, error: 'Task, ref, and text required' };
                 }
-                await this.service.type(request.task, request.ref, request.text, request.tabId);
+                await this.service.type(request.task, request.ref, request.text, request.tabId, request.clear);
                 return { ok: true };
             }
             case 'press': {

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/refs.d.ts

@@ -10,6 +10,7 @@ export interface RefNode {
     name: string;
     attrs: string[];
     backendNodeId?: number;
+    editor?: string;
 }
 export declare function getRefs(cdp: CDPClient, sessionId: string, opts?: RefOpts): Promise<{
     refs: string;

package/dist/lib/browser/refs.js

@@ -1,3 +1,31 @@
+const EDITOR_DETECT_FN = `(function() {
+  let el = this;
+  for (let i = 0; i < 5; i++) {
+    if (!el || el === document.documentElement) break;
+    if (el.hasAttribute && el.hasAttribute('data-lexical-editor')) return 'lexical';
+    if (el.classList && el.classList.contains('ProseMirror')) return 'prosemirror';
+    if (el.hasAttribute && el.hasAttribute('data-slate-editor')) return 'slate';
+    if (el.classList && Array.from(el.classList).some(function(c) { return /^DraftEditor-/.test(c); })) return 'draft';
+    if (el.classList && el.classList.contains('ql-editor')) return 'quill';
+    if (el.classList && el.classList.contains('ck-editor__editable')) return 'ckeditor5';
+    if (el.tagName === 'TRIX-EDITOR') return 'trix';
+    el = el.parentElement;
+  }
+  return null;
+})`;
+async function detectEditorForNode(cdp, sessionId, backendNodeId) {
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
+    if (!object.objectId)
+        return undefined;
+    const objectId = object.objectId;
+    try {
+        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: EDITOR_DETECT_FN, returnByValue: true }, sessionId);
+        return result.value ?? undefined;
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
+}
 const INTERACTIVE_ROLES = new Set([
     'button',
     'link',
@@ -59,12 +87,18 @@ export async function getRefs(cdp, sessionId, opts = {}) {
             attrs,
             backendNodeId: node.backendDOMNodeId,
         };
+        if (role === 'textbox' && node.backendDOMNodeId) {
+            const editor = await detectEditorForNode(cdp, sessionId, node.backendDOMNodeId);
+            if (editor)
+                refNode.editor = editor;
+        }
         nodeMap.set(ref, refNode);
         const attrStr = attrs.length > 0 ? ` [${attrs.join('] [')}]` : '';
+        const editorStr = refNode.editor ? ` [editor=${refNode.editor}]` : '';
         const nameStr = name ? ` "${truncate(name, 50)}"` : '';
         const line = compact
-            ? `${role}${nameStr} [ref=${ref}]${attrStr}`
-            : `- ${role}${nameStr} [ref=${ref}]${attrStr}`;
+            ? `${role}${nameStr} [ref=${ref}]${attrStr}${editorStr}`
+            : `- ${role}${nameStr} [ref=${ref}]${attrStr}${editorStr}`;
         lines.push(line);
     }
     return { refs: lines.join('\n'), nodeMap };

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;
@@ -66,7 +99,7 @@ export declare class BrowserService {
         nodeMap: Map<number, RefNode>;
     }>;
     click(taskId: string, ref: number, tabHint?: string): Promise<void>;
-    type(taskId: string, ref: number, text: string, tabHint?: string): Promise<void>;
+    type(taskId: string, ref: number, text: string, tabHint?: string, clear?: boolean): Promise<void>;
     press(taskId: string, key: string, tabHint?: string): Promise<void>;
     hover(taskId: string, ref: number, tabHint?: string): Promise<void>;
     scroll(taskId: string, deltaX: number, deltaY: number, atX?: number, atY?: number, tabHint?: string): Promise<void>;

package/dist/lib/browser/service.js

@@ -8,7 +8,89 @@ import { connectSSH } from './drivers/ssh.js';
 import { generateTaskId, generateShortId, generateFunName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
+import { typeEditorText } from './editor.js';
 import { 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 +433,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) {
@@ -403,7 +503,7 @@ export class BrowserService {
         const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
         await clickAtCoords(conn.cdp, sessionId, x, y);
     }
-    async type(taskId, ref, text, tabHint) {
+    async type(taskId, ref, text, tabHint, clear) {
         const { conn, task } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
@@ -415,10 +515,15 @@ export class BrowserService {
         const node = nodeMap.get(ref);
         if (!node)
             throw new Error(`Ref ${ref} not found`);
-        if (node.backendNodeId) {
-            await focusNode(conn.cdp, sessionId, node.backendNodeId);
+        if (node.editor) {
+            await typeEditorText(conn.cdp, sessionId, node, text, clear);
+        }
+        else {
+            if (node.backendNodeId) {
+                await focusNode(conn.cdp, sessionId, node.backendNodeId);
+            }
+            await typeText(conn.cdp, sessionId, text);
         }
-        await typeText(conn.cdp, sessionId, text);
     }
     async press(taskId, key, tabHint) {
         const { conn, task } = await this.findTask(taskId);
@@ -839,6 +944,7 @@ export class BrowserService {
             port,
             pid,
             electron: true,
+            targetFilter: profile.targetFilter,
             forkedFrom: profile.name,
             tasks: new Map(),
             sessionCache: new Map(),
@@ -860,6 +966,7 @@ export class BrowserService {
                 port: existingInfo.port,
                 pid: existingInfo.pid,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks,
                 sessionCache: new Map(),
             };
@@ -889,6 +996,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 +1009,7 @@ export class BrowserService {
                 port: conn.port,
                 pid: conn.pid,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: new Map(),
                 sessionCache: new Map(),
             };
@@ -914,6 +1023,7 @@ export class BrowserService {
                 port: 0,
                 pid: 0,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: this.loadTaskState(profile.name),
                 sessionCache: new Map(),
             };
@@ -930,6 +1040,7 @@ export class BrowserService {
                 port,
                 pid: 0,
                 electron: profile.electron,
+                targetFilter: profile.targetFilter,
                 tasks: this.loadTaskState(profile.name),
                 sessionCache: new Map(),
             };
@@ -951,11 +1062,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[];
@@ -119,6 +129,7 @@ export interface IPCResponse {
     result?: unknown;
     path?: string;
     refs?: string;
+    nodes?: RefNodeJson[];
     port?: number;
     pid?: number;
     logs?: ConsoleEntry[];
@@ -150,6 +161,13 @@ export interface NetworkRequest {
     mimeType?: string;
     timestamp: number;
 }
+export interface RefNodeJson {
+    ref: number;
+    role: string;
+    name: string;
+    attrs: string[];
+    editor?: string;
+}
 export interface DeviceDescriptor {
     width: number;
     height: number;

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.2",
+  "version": "1.17.4",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",
@@ -87,6 +87,7 @@
     "@types/diff": "^6.0.0",
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^22.0.0",
+    "playwright": "^1.44.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"