@phnx-labs/agents-cli 1.17.4 → 1.17.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.17.6
+
+**Workflows**
+
+- New `workflows` skill — author-and-run guide for workflow bundles (`WORKFLOW.md` frontmatter, `subagents/` directory for multi-agent pipelines, scoped `skills/` and `plugins/`, sharing via `agents repo push` or GitHub install). Calls out the `--mode plan` deadlock that bites workflows which need to post comments or edit files.
+- `agents workflows --help` rewritten with a structure diagram, project > user > system resolution order, and an explicit note that workflows mutating state need `--mode edit` or `--mode full` to avoid a headless deadlock at `ExitPlanMode`.
+- README gains a `Workflows` section between Teams and Browser covering the bundle layout, frontmatter, subagents/skills/plugins, and the `--mode` requirement.
+
 ## 1.17.4
 
 **Browser**

package/README.md

@@ -47,6 +47,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [Sessions across agents](#sessions-across-agents)
 - [Run open models through Claude Code](#run-open-models-through-claude-code)
 - [Teams](#teams)
+- [Workflows](#workflows)
 - [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
@@ -244,6 +245,57 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ---
 
+## Workflows
+
+Bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline. One bundle, one invocation.
+
+```bash
+# Use a workflow — workflow name goes in the agent slot
+agents run code-review "review PR #42 on acme/api"
+
+# List + inspect
+agents workflows list
+agents workflows view code-review
+
+# Install from GitHub or local
+agents workflows add gh:yourteam/code-review
+agents workflows add ./my-workflow
+```
+
+A workflow is a directory:
+
+```
+~/.agents/workflows/code-review/
+  WORKFLOW.md          # YAML frontmatter + orchestrator system prompt
+  subagents/           # optional: *.md files exposed to the orchestrator
+    security.md
+    style.md
+  skills/              # optional: knowledge packs scoped to this workflow
+  plugins/             # optional: plugin bundles
+```
+
+`WORKFLOW.md`'s Markdown body is the orchestrator's system prompt. Files under `subagents/` get copied to `~/.claude/agents/` at run time so the built-in Agent tool can dispatch to them by name — including in parallel. `skills/` and `plugins/` sync into the version home just for the run.
+
+```yaml
+# WORKFLOW.md frontmatter
+---
+name: Code Review
+description: Evidence-grounded PR review with file:line citations.
+model: claude-opus-4-7
+tools:
+  - Read
+  - Grep
+  - Bash
+  - WebFetch
+---
+```
+
+Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit` or `--mode full`. `agents run` defaults to `--mode plan` (read-only), which deadlocks at `ExitPlanMode` in headless runs.
+
+Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline.
+
+---
+
 ## Browser
 
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.

package/dist/commands/browser.js

@@ -871,6 +871,53 @@ function registerTaskCommands(browser) {
         }
         console.log('Scrolled');
     });
+    browser
+        .command('upload <task>')
+        .description('Upload file(s) — supports hidden file inputs, drag-drop targets, and OS chooser interception')
+        .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('-r, --ref <n>', 'Ref of the upload target element (file input or drop zone)', (v) => parseInt(v, 10))
+        .option('--trigger <n>', 'Ref of a button that opens the OS file chooser (Pattern C)', (v) => parseInt(v, 10))
+        .option('-f, --file <path...>', 'Absolute path(s) to file(s) to upload (repeatable)')
+        .option('--drop', 'Force drag-drop pattern even if ref is an <input type=file>')
+        .option('--input', 'Force file-input pattern (DOM.setFileInputFiles)')
+        .option('--timeout <ms>', 'Timeout for chooser interception (Pattern C)', (v) => parseInt(v, 10))
+        .action(async (task, opts) => {
+        const files = opts.file ?? [];
+        if (files.length === 0) {
+            console.error('--file <path> is required (repeat for multiple files)');
+            process.exit(1);
+        }
+        if (opts.ref === undefined && opts.trigger === undefined) {
+            console.error('--ref <n> or --trigger <n> is required');
+            process.exit(1);
+        }
+        if (opts.drop && opts.input) {
+            console.error('--drop and --input are mutually exclusive');
+            process.exit(1);
+        }
+        let mode = 'auto';
+        if (opts.trigger !== undefined)
+            mode = 'chooser';
+        else if (opts.drop)
+            mode = 'drop';
+        else if (opts.input)
+            mode = 'input';
+        const response = await sendIPCRequest({
+            action: 'upload',
+            task,
+            tabId: opts.tab,
+            ref: opts.ref,
+            trigger: opts.trigger,
+            files,
+            uploadMode: mode,
+            timeout: opts.timeout,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(`Uploaded ${files.length} file${files.length === 1 ? '' : 's'} (${response.uploadMode})`);
+    });
     // ─── Viewport & Device ───────────────────────────────────────────────────────
     const setCmd = browser.command('set').description('Set browser emulation options');
     setCmd

package/dist/commands/workflows.js

@@ -17,21 +17,42 @@ export function registerWorkflowsCommands(program) {
         .command('workflows')
         .description('Manage multi-agent pipeline workflows (WORKFLOW.md bundles)')
         .addHelpText('after', `
-Workflows are directory bundles (WORKFLOW.md + subagents/) that define multi-agent pipelines run via:
-  agents run <workflow-name>
+Workflows are directory bundles that define reusable named agent pipelines.
+Run a workflow with:
+  agents run <workflow-name> [prompt]
+
+Structure:
+  ~/.agents/workflows/<name>/
+    WORKFLOW.md        required: YAML frontmatter + orchestrator system prompt
+    subagents/*.md     optional: subagents the orchestrator can dispatch to
+    skills/            optional: knowledge packs scoped to this workflow
+    plugins/           optional: plugin bundles scoped to this workflow
+
+Resolution: project (.agents/workflows/) > user (~/.agents/workflows/) > system.
+
+Note: agents run defaults to --mode plan (read-only). For workflows that
+write files, post comments, or otherwise mutate state, pass --mode edit or
+--mode full or the run will deadlock at ExitPlanMode.
 
 Examples:
   # See what workflows are available
   agents workflows list
 
-  # Install from GitHub
+  # Install from GitHub or a local directory
   agents workflows add gh:user/workflows
+  agents workflows add ./code-review
 
-  # Install a local workflow directory
-  agents workflows add ./rdev
+  # Inspect a workflow's frontmatter and subagents
+  agents workflows view code-review
 
-  # Remove a workflow
-  agents workflows remove rdev
+  # Run it (workflow name goes in the agent slot)
+  agents run code-review "review PR #42"
+
+  # Run a workflow that posts comments / edits files
+  agents run code-review --mode full "review PR #42 and post the review"
+
+  # Remove from version homes (and central storage on second run)
+  agents workflows remove code-review
 `);
     workflowsCmd
         .command('list [agent]')

package/dist/lib/browser/ipc.js

@@ -296,6 +296,19 @@ export class BrowserIPCServer {
                 const downloadPath = await this.service.waitForDownload(request.task, request.timeout);
                 return { ok: true, downloadPath };
             }
+            case 'upload': {
+                if (!request.task || !request.files || request.files.length === 0) {
+                    return { ok: false, error: 'Task and at least one file required' };
+                }
+                const result = await this.service.upload(request.task, request.files, {
+                    ref: request.ref,
+                    trigger: request.trigger,
+                    mode: request.uploadMode,
+                    tabHint: request.tabId,
+                    timeout: request.timeout,
+                });
+                return { ok: true, uploadMode: result.mode };
+            }
             default:
                 return { ok: false, error: `Unknown action: ${request.action}` };
         }

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

@@ -1,6 +1,7 @@
 import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
+export type UploadMode = 'auto' | 'input' | 'drop' | 'chooser';
 /**
  * Parse a `targetFilter` string into its kind + value, or return `null`
  * when the input is missing or malformed. Filter syntax:
@@ -103,6 +104,15 @@ export declare class BrowserService {
     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>;
+    upload(taskId: string, files: string[], options: {
+        ref?: number;
+        trigger?: number;
+        mode?: UploadMode;
+        tabHint?: string;
+        timeout?: number;
+    }): Promise<{
+        mode: 'input' | 'drop' | 'chooser';
+    }>;
     status(profileName?: string): Promise<ProfileStatus[]>;
     private reconcileFromDisk;
     setViewport(taskId: string, width: number, height: number, options?: {

package/dist/lib/browser/service.js

@@ -9,6 +9,7 @@ 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 { detectUploadPattern, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
 /**
  * Parse a `targetFilter` string into its kind + value, or return `null`
@@ -557,6 +558,60 @@ export class BrowserService {
         const sessionId = await this.getSessionId(conn, target.targetId);
         await scrollAtCoords(conn.cdp, sessionId, atX ?? 0, atY ?? 0, deltaX, deltaY);
     }
+    async upload(taskId, files, options) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = options.tabHint
+            ? await this.resolveTabHint(conn, task, options.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);
+        // Match the user-facing ref numbering from `agents browser refs` (which
+        // defaults to interactive=true). The other action helpers in this file
+        // use interactive=false historically, but that produces ref numbers the
+        // user never sees — `--ref 1` then resolves to the RootWebArea instead of
+        // the first interactive element. Match the listing the user actually saw.
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: true, limit: 1000 });
+        const mode = options.mode ?? 'auto';
+        if (options.trigger !== undefined || mode === 'chooser') {
+            const ref = options.trigger ?? options.ref;
+            if (ref === undefined) {
+                throw new Error('chooser mode requires --trigger <ref> (or --ref) pointing at the button that opens the file dialog');
+            }
+            const node = nodeMap.get(ref);
+            if (!node)
+                throw new Error(`Ref ${ref} not found`);
+            await uploadViaFileChooser(conn.cdp, sessionId, { node, nodeMap }, files, options.timeout);
+            return { mode: 'chooser' };
+        }
+        if (options.ref === undefined) {
+            throw new Error('upload requires --ref <n> (target element) or --trigger <n> (button that opens chooser)');
+        }
+        const node = nodeMap.get(options.ref);
+        if (!node)
+            throw new Error(`Ref ${options.ref} not found`);
+        if (!node.backendNodeId)
+            throw new Error(`Ref ${options.ref} has no DOM node`);
+        let resolved;
+        if (mode === 'input') {
+            resolved = 'input';
+        }
+        else if (mode === 'drop') {
+            resolved = 'drop';
+        }
+        else {
+            resolved = await detectUploadPattern(conn.cdp, sessionId, node.backendNodeId);
+        }
+        if (resolved === 'input') {
+            await uploadToFileInput(conn.cdp, sessionId, node.backendNodeId, files);
+        }
+        else {
+            await uploadToDropTarget(conn.cdp, sessionId, node.backendNodeId, files);
+        }
+        return { mode: resolved };
+    }
     async status(profileName) {
         const seen = new Set();
         const statuses = [];

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

@@ -83,7 +83,7 @@ export interface HistoricalTask {
     domains: string[];
     tabCount: number;
 }
-export type IPCAction = 'start' | 'launch-profile' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download';
+export type IPCAction = 'start' | 'launch-profile' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -116,6 +116,9 @@ export interface IPCRequest {
     waitValue?: string | number;
     timeout?: number;
     downloadPath?: string;
+    files?: string[];
+    trigger?: number;
+    uploadMode?: 'auto' | 'input' | 'drop' | 'chooser';
 }
 export interface IPCResponse {
     ok: boolean;
@@ -138,6 +141,7 @@ export interface IPCResponse {
     body?: string;
     downloadPath?: string;
     devices?: string[];
+    uploadMode?: 'input' | 'drop' | 'chooser';
 }
 export interface ConsoleEntry {
     level: 'log' | 'info' | 'warn' | 'error';

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

@@ -0,0 +1,54 @@
+import type { CDPClient } from './cdp.js';
+import { type RefNode } from './refs.js';
+/**
+ * File upload strategies for `agents browser upload`.
+ *
+ * Every uploader on the web is one of three patterns:
+ *
+ *   A. Direct file input — the page exposes (or hides) `<input type=file>`.
+ *      `DOM.setFileInputFiles` plants the paths directly. The cleanest
+ *      path; works whenever the input is in the DOM, even when CSS-hidden
+ *      or visually offscreen.
+ *
+ *   B. Drag-drop target — the page listens for `drop` events on a region
+ *      (Canva, Notion, Linear, GitHub PRs). We dispatch synthetic
+ *      `dragenter`/`dragover`/`drop` events with a `DataTransfer` whose
+ *      `files` list carries a `File` built from disk bytes. The dispatch
+ *      uses real elementFromPoint coordinates so React/DOM listeners fire.
+ *
+ *   C. Native chooser interception — the user clicks a button that calls
+ *      `input.click()` and the only file input is dynamically created in
+ *      response. `Page.setInterceptFileChooserDialog` flips the chooser
+ *      from a blocking OS dialog into a CDP event; we click the trigger,
+ *      wait for `Page.fileChooserOpened`, then satisfy it with
+ *      `Page.handleFileChooser({ action: 'accept', files })`. Lifecycle:
+ *      enable interception -> click -> wait -> accept -> disable.
+ */
+export interface UploadOptions {
+    files: string[];
+}
+/** Pattern A — direct file input via `DOM.setFileInputFiles`. */
+export declare function uploadToFileInput(cdp: CDPClient, sessionId: string, backendNodeId: number, files: string[]): Promise<void>;
+/** Pattern B — synthetic drag-drop onto a target node. */
+export declare function uploadToDropTarget(cdp: CDPClient, sessionId: string, backendNodeId: number, files: string[]): Promise<void>;
+/**
+ * Pattern C — click a trigger, intercept the OS file chooser, feed files.
+ *
+ * `Page.setInterceptFileChooserDialog` must be enabled before the click; the
+ * chooser only fires once, so we register a single-shot handler ahead of time.
+ * Auto-attached child sessions matter here: the chooser event arrives on the
+ * session whose page hosts the input, which is the same session we used for
+ * the click — so we filter event params by sessionId.
+ */
+export declare function uploadViaFileChooser(cdp: CDPClient, sessionId: string, triggerRef: {
+    node: RefNode;
+    nodeMap: Map<number, RefNode>;
+}, files: string[], timeoutMs?: number): Promise<void>;
+export declare function mimeFromExt(filePath: string): string;
+/**
+ * Inspect a ref's DOM node to decide which pattern fits when the caller
+ * didn't specify. Returns 'input' if the node is `<input type=file>`,
+ * otherwise 'drop'. Chooser interception (Pattern C) is never auto-selected
+ * because it requires clicking the ref, which mutates page state — opt-in only.
+ */
+export declare function detectUploadPattern(cdp: CDPClient, sessionId: string, backendNodeId: number): Promise<'input' | 'drop'>;

package/dist/lib/browser/upload.js

@@ -0,0 +1,264 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { clickAtCoords } from './input.js';
+import { resolveRefToCoords } from './refs.js';
+const RESOLVE_FILE_INPUT_FN = `(function() {
+  const start = this;
+  // Walk multiple paths to find an <input type=file>:
+  //   1. The node itself (when the AX backend node IS the input).
+  //   2. Its ancestors via parentElement (custom button wrappers).
+  //   3. closest('input[type=file]') (handles label/span/button inside or
+  //      near a file input).
+  //   4. Across user-agent shadow boundaries via getRootNode().host
+  //      (Chromium's internal shadow-button pseudo-element for file inputs).
+  //   5. If the AX backend node is associated with a <label for=...>, follow
+  //      the htmlFor relationship.
+  //   6. Last resort: if the start node was a click target that fires
+  //      input.click() inside a click handler, fall back to the unique
+  //      <input type=file> on the page (when there is exactly one).
+  let el = start;
+  for (let i = 0; i < 8 && el; i++) {
+    if (el.tagName === 'INPUT' && el.type === 'file') return el;
+    if (el.closest) {
+      const found = el.closest('input[type=file]');
+      if (found) return found;
+    }
+    if (el.tagName === 'LABEL' && el.htmlFor) {
+      const t = document.getElementById(el.htmlFor);
+      if (t && t.tagName === 'INPUT' && t.type === 'file') return t;
+    }
+    const root = el.getRootNode && el.getRootNode();
+    if (root && root.host && root !== document) {
+      el = root.host;
+      continue;
+    }
+    el = el.parentElement;
+  }
+  // Final fallback: if exactly one file input exists on the page, use it.
+  // This handles cases where the AX tree exposes the input as an internal
+  // pseudo-button whose parentElement is null. A page with a single uploader
+  // (Slack composer, Notion image block, Canva ingredient) hits this branch.
+  const all = document.querySelectorAll('input[type=file]');
+  if (all.length === 1) return all[0];
+  return null;
+})`;
+/** Pattern A — direct file input via `DOM.setFileInputFiles`. */
+export async function uploadToFileInput(cdp, sessionId, backendNodeId, files) {
+    validateFiles(files);
+    const resolvedId = await resolveActualFileInput(cdp, sessionId, backendNodeId);
+    await cdp.send('DOM.setFileInputFiles', { files, backendNodeId: resolvedId }, sessionId);
+}
+async function resolveActualFileInput(cdp, sessionId, backendNodeId) {
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
+    if (!object.objectId)
+        return backendNodeId;
+    const objectId = object.objectId;
+    try {
+        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: RESOLVE_FILE_INPUT_FN, returnByValue: false }, sessionId);
+        if (!result.objectId) {
+            throw new Error('Ref is not (and is not contained in) an <input type=file>');
+        }
+        const inputObjectId = result.objectId;
+        try {
+            const { node } = await cdp.send('DOM.describeNode', { objectId: inputObjectId }, sessionId);
+            return node.backendNodeId;
+        }
+        finally {
+            await cdp.send('Runtime.releaseObject', { objectId: inputObjectId }, sessionId);
+        }
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
+}
+const DRAG_DROP_FN = `(function(files) {
+  const el = this;
+  const rect = el.getBoundingClientRect();
+  const x = rect.left + rect.width / 2;
+  const y = rect.top + rect.height / 2;
+  const dt = new DataTransfer();
+  for (const f of files) {
+    const u8 = Uint8Array.from(atob(f.bytes), c => c.charCodeAt(0));
+    const blob = new Blob([u8], { type: f.type || 'application/octet-stream' });
+    const file = new File([blob], f.name, { type: f.type || 'application/octet-stream' });
+    dt.items.add(file);
+  }
+  function dispatch(type) {
+    // Chromium does not honor the dataTransfer field in DragEventInit for
+    // synthetic events. Build the DragEvent with no dataTransfer in the init,
+    // then override the event dataTransfer getter via defineProperty so
+    // page-level listeners see the File list we constructed.
+    const ev = new DragEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      clientX: x,
+      clientY: y,
+    });
+    Object.defineProperty(ev, 'dataTransfer', { value: dt });
+    el.dispatchEvent(ev);
+  }
+  dispatch('dragenter');
+  dispatch('dragover');
+  dispatch('drop');
+  return { dispatched: 3, files: files.length };
+})`;
+/** Pattern B — synthetic drag-drop onto a target node. */
+export async function uploadToDropTarget(cdp, sessionId, backendNodeId, files) {
+    validateFiles(files);
+    const payload = files.map((p) => ({
+        name: path.basename(p),
+        type: mimeFromExt(p),
+        bytes: fs.readFileSync(p).toString('base64'),
+    }));
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
+    if (!object.objectId) {
+        throw new Error('Drop target node could not be resolved');
+    }
+    const objectId = object.objectId;
+    try {
+        const r = await cdp.send('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: DRAG_DROP_FN,
+            arguments: [{ value: payload }],
+            returnByValue: true,
+            awaitPromise: true,
+        }, sessionId);
+        if (r.exceptionDetails) {
+            throw new Error('Drop dispatch threw: ' + JSON.stringify(r.exceptionDetails));
+        }
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
+}
+/**
+ * Pattern C — click a trigger, intercept the OS file chooser, feed files.
+ *
+ * `Page.setInterceptFileChooserDialog` must be enabled before the click; the
+ * chooser only fires once, so we register a single-shot handler ahead of time.
+ * Auto-attached child sessions matter here: the chooser event arrives on the
+ * session whose page hosts the input, which is the same session we used for
+ * the click — so we filter event params by sessionId.
+ */
+export async function uploadViaFileChooser(cdp, sessionId, triggerRef, files, timeoutMs = 5000) {
+    validateFiles(files);
+    await cdp.send('Page.enable', {}, sessionId);
+    await cdp.send('Page.setInterceptFileChooserDialog', { enabled: true }, sessionId);
+    let opened = null;
+    let resolve;
+    let reject;
+    const wait = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    const handler = (params) => {
+        const ev = params;
+        if (typeof ev.backendNodeId === 'number') {
+            opened = { backendNodeId: ev.backendNodeId };
+            resolve();
+        }
+    };
+    cdp.on('Page.fileChooserOpened', handler);
+    const timer = setTimeout(() => {
+        reject(new Error(`File chooser did not open within ${timeoutMs}ms — is the trigger ref correct?`));
+    }, timeoutMs);
+    try {
+        const { x, y } = await resolveRefToCoords(cdp, sessionId, triggerRef.nodeMap, triggerRef.node.ref);
+        await clickAtCoords(cdp, sessionId, x, y);
+        await wait;
+        await cdp.send('Page.handleFileChooser', { action: 'accept', files }, sessionId);
+        // Some Chromium builds expect setFileInputFiles instead of handleFileChooser.
+        // We try handleFileChooser first because it's the documented path for
+        // intercepted dialogs; if Chromium rejects it (older protocol), fall back
+        // to setFileInputFiles using the backendNodeId from the event.
+    }
+    catch (err) {
+        if (opened && err instanceof Error && /not supported|not found|Method/i.test(err.message)) {
+            await cdp.send('DOM.setFileInputFiles', { files, backendNodeId: opened.backendNodeId }, sessionId);
+        }
+        else {
+            throw err;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        cdp.off('Page.fileChooserOpened', handler);
+        await cdp.send('Page.setInterceptFileChooserDialog', { enabled: false }, sessionId).catch(() => { });
+    }
+}
+function validateFiles(files) {
+    if (!files || files.length === 0) {
+        throw new Error('At least one file path is required');
+    }
+    for (const f of files) {
+        if (!path.isAbsolute(f)) {
+            throw new Error(`Upload path must be absolute: ${f}`);
+        }
+        if (!fs.existsSync(f)) {
+            throw new Error(`File not found: ${f}`);
+        }
+    }
+}
+const MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.zip': 'application/zip',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+};
+export function mimeFromExt(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return MIME_BY_EXT[ext] ?? 'application/octet-stream';
+}
+/**
+ * Inspect a ref's DOM node to decide which pattern fits when the caller
+ * didn't specify. Returns 'input' if the node is `<input type=file>`,
+ * otherwise 'drop'. Chooser interception (Pattern C) is never auto-selected
+ * because it requires clicking the ref, which mutates page state — opt-in only.
+ */
+export async function detectUploadPattern(cdp, sessionId, backendNodeId) {
+    const { node } = await cdp.send('DOM.describeNode', { backendNodeId, depth: 0 }, sessionId);
+    if (isFileInputNode(node))
+        return 'input';
+    // The node itself isn't <input type=file>, but it might be a button or
+    // shadow-DOM descendant *inside* one — that's what the accessibility tree
+    // surfaces for file inputs. Walk up to confirm before falling back to drop.
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
+    if (!object.objectId)
+        return 'drop';
+    const objectId = object.objectId;
+    try {
+        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: RESOLVE_FILE_INPUT_FN, returnByValue: false }, sessionId);
+        if (result.objectId) {
+            await cdp.send('Runtime.releaseObject', { objectId: result.objectId }, sessionId);
+            return 'input';
+        }
+        return 'drop';
+    }
+    finally {
+        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
+    }
+}
+function isFileInputNode(node) {
+    const tag = (node.nodeName ?? '').toLowerCase();
+    if (tag !== 'input')
+        return false;
+    const attrs = node.attributes ?? [];
+    for (let i = 0; i < attrs.length; i += 2) {
+        if (attrs[i] === 'type' && attrs[i + 1]?.toLowerCase() === 'file') {
+            return true;
+        }
+    }
+    return false;
+}

package/package.json

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