publishport-opencli 1.8.4-pp.1

package/dist/src/browser/compound.js

@@ -0,0 +1,112 @@
+/**
+ * Compound-component expansion for high-agent-failure form controls.
+ *
+ * Agents burn turns on three recurring input categories because the raw
+ * attribute dump from `browser state` under-specifies them:
+ *
+ *   - date / time / datetime-local / month / week — agents type
+ *     free-form strings and the browser silently ignores mismatched formats.
+ *   - select — the snapshot caps visible options at ~6; agents don't know
+ *     the full option set, can't match by label, and waste turns clicking
+ *     to open the dropdown just to read options.
+ *   - file — the snapshot shows current filenames but not `accept` or
+ *     `multiple`; agents re-upload or pick unsupported MIME types.
+ *
+ * `compoundInfoOf(el)` returns a structured JSON summary agents can rely
+ * on. Included in `browser find --css` envelope so the agent gets the
+ * rich view without extra round-trips.
+ *
+ * Emitted as a JS source string (`COMPOUND_INFO_JS`) so it can be inlined
+ * into the generated evaluate scripts under find / snapshot / eval.
+ */
+/** Max options included in a SelectCompound.options[]. Above this, `options_total` still reflects the true count. */
+export const COMPOUND_SELECT_OPTIONS_CAP = 50;
+/** Max characters per option label / file name. */
+export const COMPOUND_LABEL_CAP = 80;
+/**
+ * JavaScript source declaring `compoundInfoOf(el)`. Inlined into the JS
+ * emitted by `buildFindJs` (and any other evaluate script that needs the
+ * rich compound view). Returns a `CompoundInfo` object or `null`.
+ */
+export const COMPOUND_INFO_JS = `
+function compoundInfoOf(el) {
+  if (!el || !el.tagName) return null;
+  const tag = el.tagName;
+  const LABEL_CAP = ${COMPOUND_LABEL_CAP};
+  const OPTS_CAP = ${COMPOUND_SELECT_OPTIONS_CAP};
+  if (tag === 'INPUT') {
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    const FORMATS = {
+      'date': 'YYYY-MM-DD',
+      'time': 'HH:MM',
+      'datetime-local': 'YYYY-MM-DDTHH:MM',
+      'month': 'YYYY-MM',
+      'week': 'YYYY-W##',
+    };
+    if (FORMATS[type]) {
+      const info = {
+        control: type,
+        format: FORMATS[type],
+        current: (el.value == null ? '' : String(el.value)),
+      };
+      const min = el.getAttribute('min');
+      if (min) info.min = min;
+      const max = el.getAttribute('max');
+      if (max) info.max = max;
+      return info;
+    }
+    if (type === 'file') {
+      const info = {
+        control: 'file',
+        multiple: !!el.multiple,
+        current: [],
+      };
+      const accept = el.getAttribute('accept');
+      if (accept) info.accept = accept;
+      try {
+        if (el.files && el.files.length) {
+          for (let i = 0; i < el.files.length; i++) {
+            const name = (el.files[i].name || '').slice(0, LABEL_CAP);
+            info.current.push(name);
+          }
+        }
+      } catch (_) {}
+      return info;
+    }
+    return null;
+  }
+  if (tag === 'SELECT') {
+    const multiple = !!el.multiple;
+    const options = [];
+    const selectedLabels = [];
+    let total = 0;
+    try {
+      const opts = el.options || [];
+      total = opts.length;
+      // Walk ALL options so \`current\` reflects selections that sit beyond the
+      // serialization cap. Only the first OPTS_CAP entries get pushed into
+      // options[]; anything past the cap still contributes to selectedLabels
+      // so agents see the true current state of big dropdowns.
+      for (let i = 0; i < opts.length; i++) {
+        const o = opts[i];
+        const labelRaw = (o.label != null && o.label !== '') ? o.label : (o.text || '');
+        const label = String(labelRaw).trim().slice(0, LABEL_CAP);
+        if (i < OPTS_CAP) {
+          const entry = { label: label, value: o.value, selected: !!o.selected };
+          if (o.disabled) entry.disabled = true;
+          options.push(entry);
+        }
+        if (o.selected) selectedLabels.push(label);
+      }
+    } catch (_) {}
+    return {
+      control: 'select',
+      multiple: multiple,
+      current: multiple ? selectedLabels : (selectedLabels[0] || ''),
+      options: options,
+      options_total: total,
+    };
+  }
+  return null;
+}
+`;

package/dist/src/browser/compound.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/compound.test.js

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import { COMPOUND_INFO_JS, COMPOUND_LABEL_CAP, COMPOUND_SELECT_OPTIONS_CAP, } from './compound.js';
+/**
+ * Tests run the JS source in a sandbox via `new Function`, feeding it
+ * minimal mock elements shaped like the DOM elements the real code sees
+ * at runtime. Avoids a full jsdom setup while still exercising the logic
+ * end-to-end instead of only snapshotting string markers.
+ */
+function runCompound(mockEl) {
+    const fn = new Function('el', `${COMPOUND_INFO_JS}\nreturn compoundInfoOf(el);`);
+    return fn(mockEl);
+}
+function mockInput(attrs, extras = {}) {
+    return {
+        tagName: 'INPUT',
+        value: extras.value,
+        multiple: extras.multiple,
+        files: extras.files,
+        getAttribute(name) {
+            return attrs[name] ?? null;
+        },
+    };
+}
+function mockSelect(options, multiple = false) {
+    const opts = options.map(o => ({ ...o, selected: !!o.selected }));
+    return {
+        tagName: 'SELECT',
+        multiple,
+        options: opts,
+        getAttribute: () => null,
+    };
+}
+describe('compoundInfoOf — date-like inputs', () => {
+    it('returns { control, format, current } for <input type=date>', () => {
+        const info = runCompound(mockInput({ type: 'date' }, { value: '2026-04-21' }));
+        expect(info).toEqual({ control: 'date', format: 'YYYY-MM-DD', current: '2026-04-21' });
+    });
+    it('surfaces min + max when present', () => {
+        const info = runCompound(mockInput({ type: 'date', min: '2026-01-01', max: '2026-12-31' }, { value: '2026-04-21' }));
+        expect(info).toMatchObject({ min: '2026-01-01', max: '2026-12-31' });
+    });
+    it('handles time / datetime-local / month / week with correct format strings', () => {
+        const formats = {
+            time: 'HH:MM',
+            'datetime-local': 'YYYY-MM-DDTHH:MM',
+            month: 'YYYY-MM',
+            week: 'YYYY-W##',
+        };
+        for (const [type, fmt] of Object.entries(formats)) {
+            const info = runCompound(mockInput({ type }, { value: '' }));
+            expect(info.format).toBe(fmt);
+        }
+    });
+    it('coerces null value into empty string instead of crashing', () => {
+        const info = runCompound(mockInput({ type: 'date' }));
+        expect(info).toMatchObject({ control: 'date', current: '' });
+    });
+});
+describe('compoundInfoOf — file inputs', () => {
+    it('returns { control: file, multiple, current[] }', () => {
+        const info = runCompound(mockInput({ type: 'file' }, {
+            multiple: true,
+            files: [{ name: 'a.png' }, { name: 'b.jpg' }],
+        }));
+        expect(info).toEqual({ control: 'file', multiple: true, current: ['a.png', 'b.jpg'] });
+    });
+    it('includes accept when present', () => {
+        const info = runCompound(mockInput({ type: 'file', accept: 'image/*' }, { multiple: false }));
+        expect(info).toMatchObject({ control: 'file', accept: 'image/*' });
+    });
+    it('returns empty current[] when nothing uploaded', () => {
+        const info = runCompound(mockInput({ type: 'file' }, { multiple: false }));
+        expect(info).toEqual({ control: 'file', multiple: false, current: [] });
+    });
+    it('caps file name at COMPOUND_LABEL_CAP', () => {
+        const longName = 'x'.repeat(COMPOUND_LABEL_CAP + 50);
+        const info = runCompound(mockInput({ type: 'file' }, { multiple: false, files: [{ name: longName }] }));
+        expect(info.current[0].length).toBe(COMPOUND_LABEL_CAP);
+    });
+});
+describe('compoundInfoOf — select', () => {
+    it('returns full options list with labels, values, selected flag', () => {
+        const info = runCompound(mockSelect([
+            { value: 'us', label: 'United States', selected: true },
+            { value: 'ca', label: 'Canada' },
+            { value: 'fr', label: 'France' },
+        ]));
+        expect(info.options).toHaveLength(3);
+        expect(info.options[0]).toEqual({ label: 'United States', value: 'us', selected: true });
+        expect(info.options[2]).toEqual({ label: 'France', value: 'fr', selected: false });
+    });
+    it('sets current to the selected label (single-select)', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'Alpha' },
+            { value: 'b', label: 'Bravo', selected: true },
+        ]));
+        expect(info).toMatchObject({ control: 'select', multiple: false, current: 'Bravo' });
+    });
+    it('sets current to an array of labels when multiple=true', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'Alpha', selected: true },
+            { value: 'b', label: 'Bravo' },
+            { value: 'c', label: 'Charlie', selected: true },
+        ], true));
+        expect(info).toMatchObject({ control: 'select', multiple: true, current: ['Alpha', 'Charlie'] });
+    });
+    it('falls back from option.label to option.text', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', text: 'FromText' },
+            { value: 'b', label: '', text: 'EmptyLabelFallback' },
+        ]));
+        expect(info.options[0].label).toBe('FromText');
+        expect(info.options[1].label).toBe('EmptyLabelFallback');
+    });
+    it('marks disabled options', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B', disabled: true },
+        ]));
+        expect(info.options[0].disabled).toBeUndefined();
+        expect(info.options[1].disabled).toBe(true);
+    });
+    it('caps options[] at COMPOUND_SELECT_OPTIONS_CAP but keeps true options_total', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 25 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+        }));
+        const info = runCompound(mockSelect(big));
+        expect(info.options.length).toBe(COMPOUND_SELECT_OPTIONS_CAP);
+        expect(info.options_total).toBe(COMPOUND_SELECT_OPTIONS_CAP + 25);
+    });
+    it('returns "" for current on single-select with no selected option', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B' },
+        ]));
+        expect(info).toMatchObject({ current: '' });
+    });
+    // Regression: the previous loop stopped walking options once it hit
+    // COMPOUND_SELECT_OPTIONS_CAP, so a long country dropdown with the
+    // selected country sitting at index 80 would be reported with current="".
+    // Agents then thought nothing was selected and picked another country.
+    it('populates current even when the selected option sits past the serialization cap', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 25 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+            selected: i === COMPOUND_SELECT_OPTIONS_CAP + 10,
+        }));
+        const info = runCompound(mockSelect(big));
+        expect(info.current).toBe('L' + (COMPOUND_SELECT_OPTIONS_CAP + 10));
+        expect(info.options.length).toBe(COMPOUND_SELECT_OPTIONS_CAP);
+        expect(info.options_total).toBe(COMPOUND_SELECT_OPTIONS_CAP + 25);
+    });
+    it('multi-select: current[] includes labels for selected options beyond the cap', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 10 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+            selected: i === 3 || i === COMPOUND_SELECT_OPTIONS_CAP + 5,
+        }));
+        const info = runCompound(mockSelect(big, true));
+        expect(info.current).toEqual(['L3', 'L' + (COMPOUND_SELECT_OPTIONS_CAP + 5)]);
+    });
+});
+describe('compoundInfoOf — unsupported shapes', () => {
+    it('returns null for plain text input', () => {
+        expect(runCompound(mockInput({ type: 'text' }, { value: 'hi' }))).toBeNull();
+    });
+    it('returns null for non-form tags', () => {
+        expect(runCompound({ tagName: 'DIV', getAttribute: () => null })).toBeNull();
+    });
+    it('returns null for null / missing element', () => {
+        expect(runCompound(null)).toBeNull();
+        expect(runCompound({})).toBeNull();
+    });
+});

package/dist/src/browser/daemon-client.d.ts

@@ -0,0 +1,133 @@
+/**
+ * HTTP client for communicating with the opencli daemon.
+ *
+ * Provides a typed send() function that posts a Command and returns a Result.
+ */
+export interface DaemonCommand {
+    id: string;
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames';
+    /** Target page identity (targetId). Cross-layer contract with the extension. */
+    page?: string;
+    code?: string;
+    session?: string;
+    surface?: 'browser' | 'adapter';
+    /** Adapter site session lifecycle. Persistent site sessions do not idle-expire. */
+    siteSession?: 'ephemeral' | 'persistent';
+    url?: string;
+    op?: string;
+    index?: number;
+    domain?: string;
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    /** Override viewport width in CSS pixels for screenshot (0 / undefined = use current) */
+    width?: number;
+    /** Override viewport height in CSS pixels for screenshot (0 / undefined = use current; ignored when fullPage) */
+    height?: number;
+    /** Local file paths for set-file-input action */
+    files?: string[];
+    /** CSS selector for file input element (set-file-input action) */
+    selector?: string;
+    /** Raw text payload for insert-text action */
+    text?: string;
+    /** URL substring filter pattern for network capture */
+    pattern?: string;
+    /** Download wait timeout in milliseconds */
+    timeoutMs?: number;
+    cdpMethod?: string;
+    cdpParams?: Record<string, unknown>;
+    /** Window foreground/background policy for owned Browser Bridge containers. */
+    windowMode?: 'foreground' | 'background';
+    /** Custom idle timeout in seconds for this session. Overrides the default. */
+    idleTimeout?: number;
+    /** Frame index for cross-frame operations (0-based, from 'frames' action) */
+    frameIndex?: number;
+    /** Browser profile/context to route the command to. */
+    contextId?: string;
+}
+export interface DaemonResult {
+    id: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+    errorCode?: string;
+    errorHint?: string;
+    /** Page identity (targetId) — present on page-scoped command responses */
+    page?: string;
+}
+export declare class BrowserCommandError extends Error {
+    readonly code?: string | undefined;
+    readonly hint?: string | undefined;
+    constructor(message: string, code?: string | undefined, hint?: string | undefined);
+}
+export interface DaemonStatus {
+    ok: boolean;
+    pid: number;
+    uptime: number;
+    daemonVersion?: string;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    extensionCompatRange?: string;
+    contextId?: string;
+    profileRequired?: boolean;
+    profileDisconnected?: boolean;
+    profiles?: BrowserProfileStatus[];
+    pending: number;
+    commandResultUnknown?: number;
+    memoryMB: number;
+    port: number;
+}
+export interface BrowserProfileStatus {
+    contextId: string;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    extensionCompatRange?: string;
+    pending: number;
+    lastSeenAt?: number;
+}
+export declare function fetchDaemonStatus(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonStatus | null>;
+export type DaemonHealth = {
+    state: 'stopped';
+    status: null;
+} | {
+    state: 'no-extension';
+    status: DaemonStatus;
+} | {
+    state: 'profile-required';
+    status: DaemonStatus;
+} | {
+    state: 'profile-disconnected';
+    status: DaemonStatus;
+} | {
+    state: 'ready';
+    status: DaemonStatus;
+};
+/**
+ * Unified daemon health check — single entry point for all status queries.
+ * Replaces isDaemonRunning(), isExtensionConnected(), and checkDaemonStatus().
+ */
+export declare function getDaemonHealth(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonHealth>;
+export declare function requestDaemonShutdown(opts?: {
+    timeout?: number;
+}): Promise<boolean>;
+/**
+ * Send a command to the daemon and return the result data.
+ */
+export declare function sendCommand(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<unknown>;
+/**
+ * Like sendCommand, but returns both data and page identity (targetId).
+ * Use this for page-scoped commands where the caller needs the page identity.
+ */
+export declare function sendCommandFull(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<{
+    data: unknown;
+    page?: string;
+}>;
+export declare function bindTab(session: string, opts?: {
+    contextId?: string;
+}): Promise<unknown>;

package/dist/src/browser/daemon-client.js

@@ -0,0 +1,154 @@
+/**
+ * HTTP client for communicating with the opencli daemon.
+ *
+ * Provides a typed send() function that posts a Command and returns a Result.
+ */
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { sleep } from '../utils.js';
+import { classifyBrowserError } from './errors.js';
+import { resolveProfileContextId } from './profile.js';
+const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
+const OPENCLI_HEADERS = { 'X-OpenCLI': '1' };
+let _idCounter = 0;
+function generateId() {
+    return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
+}
+export class BrowserCommandError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = 'BrowserCommandError';
+    }
+}
+async function requestDaemon(pathname, init) {
+    const { timeout = 2000, headers, ...rest } = init ?? {};
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        return await fetch(`${DAEMON_URL}${pathname}`, {
+            ...rest,
+            headers: { ...OPENCLI_HEADERS, ...headers },
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchDaemonStatus(opts) {
+    try {
+        const params = opts?.contextId ? `?contextId=${encodeURIComponent(opts.contextId)}` : '';
+        const res = await requestDaemon(`/status${params}`, { timeout: opts?.timeout ?? 2000 });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Unified daemon health check — single entry point for all status queries.
+ * Replaces isDaemonRunning(), isExtensionConnected(), and checkDaemonStatus().
+ */
+export async function getDaemonHealth(opts) {
+    const status = await fetchDaemonStatus(opts);
+    if (!status)
+        return { state: 'stopped', status: null };
+    if (status.profileRequired)
+        return { state: 'profile-required', status };
+    if (status.profileDisconnected)
+        return { state: 'profile-disconnected', status };
+    if (!status.extensionConnected)
+        return { state: 'no-extension', status };
+    return { state: 'ready', status };
+}
+export async function requestDaemonShutdown(opts) {
+    try {
+        const res = await requestDaemon('/shutdown', { method: 'POST', timeout: opts?.timeout ?? 5000 });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Internal: send a command to the daemon with retry logic.
+ * Returns the raw DaemonResult. All retry policy lives here — callers
+ * (sendCommand, sendCommandFull) only shape the return value.
+ *
+ * Retries up to 4 times:
+ * - Network errors (TypeError, AbortError): retry at 500ms
+ * - Transient browser errors: retry at the delay suggested by classifyBrowserError()
+ */
+async function sendCommandRaw(action, params) {
+    const maxRetries = 4;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const id = generateId();
+        const rawWindowMode = process.env.OPENCLI_WINDOW;
+        const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
+            ? rawWindowMode
+            : undefined;
+        const contextId = params.contextId ?? resolveProfileContextId();
+        const windowMode = params.windowMode ?? envWindowMode;
+        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowMode && { windowMode }) };
+        try {
+            const res = await requestDaemon('/command', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(command),
+                timeout: 30000,
+            });
+            const result = (await res.json());
+            if (!result.ok) {
+                if (result.errorCode === 'command_result_unknown') {
+                    throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
+                }
+                const isDuplicateCommandId = res.status === 409
+                    || (result.error ?? '').includes('Duplicate command id');
+                if (isDuplicateCommandId && attempt < maxRetries) {
+                    continue;
+                }
+                const advice = classifyBrowserError(new Error(result.error ?? ''));
+                if (advice.retryable && attempt < maxRetries) {
+                    await sleep(advice.delayMs);
+                    continue;
+                }
+                throw new BrowserCommandError(result.error ?? 'Daemon command failed', result.errorCode, result.errorHint);
+            }
+            return result;
+        }
+        catch (err) {
+            const isNetworkError = err instanceof TypeError
+                || (err instanceof Error && err.name === 'AbortError');
+            if (isNetworkError && attempt < maxRetries) {
+                await sleep(500);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error('sendCommand: max retries exhausted');
+}
+/**
+ * Send a command to the daemon and return the result data.
+ */
+export async function sendCommand(action, params = {}) {
+    const result = await sendCommandRaw(action, params);
+    return result.data;
+}
+/**
+ * Like sendCommand, but returns both data and page identity (targetId).
+ * Use this for page-scoped commands where the caller needs the page identity.
+ */
+export async function sendCommandFull(action, params = {}) {
+    const result = await sendCommandRaw(action, params);
+    return { data: result.data, page: result.page };
+}
+export async function bindTab(session, opts = {}) {
+    return sendCommand('bind', { session, surface: 'browser', ...opts });
+}

package/dist/src/browser/daemon-client.test.d.ts

@@ -0,0 +1 @@
+export {};