@agentrhq/webcmd 0.1.1 → 0.2.0

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

@@ -0,0 +1,2 @@
+export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
+export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;

package/dist/src/browser/config.js

@@ -0,0 +1,14 @@
+import { log } from '../logger.js';
+function parseEnvTimeout(envVar, fallback) {
+    const raw = process.env[envVar];
+    if (raw === undefined)
+        return fallback;
+    const parsed = parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        log.warn(`[runtime] Invalid ${envVar}="${raw}", using default ${fallback}s`);
+        return fallback;
+    }
+    return parsed;
+}
+export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseEnvTimeout('WEBCMD_BROWSER_CONNECT_TIMEOUT', 45);
+export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseEnvTimeout('WEBCMD_BROWSER_COMMAND_TIMEOUT', 60);

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

@@ -0,0 +1,33 @@
+/**
+ * HTTP client for communicating with the webcmd daemon.
+ *
+ * Provides a typed send() function that posts a Command and returns a Result.
+ */
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, type BrowserProfileStatus, type DaemonHealth, type DaemonStatus } from './daemon-transport.js';
+import type { BrowserRuntimeCommand, BrowserRuntimeResult } from './protocol.js';
+export declare function setDaemonCommandTimeoutSeconds(seconds: number | null): void;
+export type DaemonCommand = BrowserRuntimeCommand;
+export type DaemonResult = BrowserRuntimeResult;
+export declare class BrowserCommandError extends Error {
+    readonly code?: string | undefined;
+    readonly hint?: string | undefined;
+    constructor(message: string, code?: string | undefined, hint?: string | undefined);
+}
+export { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, type BrowserProfileStatus, type DaemonHealth, type DaemonStatus, };
+/**
+ * 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;
+    page?: string;
+    index?: number;
+}): Promise<unknown>;

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

@@ -0,0 +1,187 @@
+/**
+ * HTTP client for communicating with the webcmd daemon.
+ *
+ * Provides a typed send() function that posts a Command and returns a Result.
+ */
+import { sleep } from '../utils.js';
+import { BrowserConnectError } from '../errors.js';
+import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
+import { classifyBrowserError } from './errors.js';
+import { resolveProfileContextId } from './profile.js';
+import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
+import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
+import { isPreDispatchError } from './bridge-readiness.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemon, requestDaemonShutdown, } from './daemon-transport.js';
+let _idCounter = 0;
+function generateId() {
+    return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
+}
+const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+const RUNTIME_OP_TIMEOUT_MARGIN_MS = 15_000;
+const HTTP_TIMEOUT_MARGIN_MS = 10_000;
+const TRANSPORT_MAX_ATTEMPTS = 4;
+let _userCommandTimeoutSeconds = null;
+export function setDaemonCommandTimeoutSeconds(seconds) {
+    _userCommandTimeoutSeconds = typeof seconds === 'number' && seconds > 0 ? Math.ceil(seconds) : null;
+}
+function effectiveCommandTimeoutSeconds(params) {
+    const base = _userCommandTimeoutSeconds ?? DEFAULT_COMMAND_TIMEOUT_SECONDS;
+    if (typeof params.timeoutMs === 'number' && params.timeoutMs > 0) {
+        return Math.max(base, Math.ceil((params.timeoutMs + RUNTIME_OP_TIMEOUT_MARGIN_MS) / 1000));
+    }
+    return base;
+}
+const UNKNOWN_OUTCOME_CODES = new Set([
+    COMMAND_RESULT_UNKNOWN_CODE,
+    'command_lost',
+    'result_evicted',
+]);
+const PRE_CONNECT_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+]);
+function isPreConnectFetchError(err) {
+    const queue = [err];
+    const seen = new Set();
+    while (queue.length) {
+        const current = queue.pop();
+        if (!current || typeof current !== 'object' || seen.has(current))
+            continue;
+        seen.add(current);
+        const { code, cause, errors } = current;
+        if (typeof code === 'string' && PRE_CONNECT_ERROR_CODES.has(code))
+            return true;
+        if (cause)
+            queue.push(cause);
+        if (Array.isArray(errors))
+            queue.push(...errors);
+    }
+    return false;
+}
+export class BrowserCommandError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = 'BrowserCommandError';
+    }
+}
+export { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, };
+/**
+ * Internal: send a command to the daemon and return the raw `DaemonResult`.
+ *
+ * Retry policy is explicit:
+ * - pre-dispatch bridge/profile errors and pre-connect fetch failures run the
+ *   full daemon/runtime ensure path, then resend the same command id;
+ * - executor-transient errors that happened before page code ran get one new
+ *   logical attempt with a fresh id;
+ * - `command_result_unknown`, duplicate pending ids from old daemons,
+ *   post-connect drops, and AbortError are never retried automatically.
+ */
+async function sendCommandRaw(action, params) {
+    const timeoutSeconds = effectiveCommandTimeoutSeconds(params);
+    const deadlineAt = Date.now() + timeoutSeconds * 1000;
+    const rawWindowMode = process.env.WEBCMD_WINDOW;
+    const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
+        ? rawWindowMode
+        : undefined;
+    const contextId = params.contextId ?? resolveProfileContextId();
+    const windowMode = params.windowMode ?? envWindowMode;
+    let id = generateId();
+    let ensureUsed = false;
+    let semanticRetryUsed = false;
+    const ensureBridge = async () => {
+        const remainingSeconds = Math.ceil((deadlineAt - Date.now()) / 1000);
+        await ensureBrowserBridgeReady({
+            timeoutSeconds: Math.max(1, Math.min(DEFAULT_BROWSER_CONNECT_TIMEOUT, remainingSeconds)),
+            contextId,
+            verbose: false,
+        });
+    };
+    for (let attempt = 1; attempt <= TRANSPORT_MAX_ATTEMPTS; attempt++) {
+        if (attempt > 1 && Date.now() >= deadlineAt) {
+            throw new BrowserCommandError('Browser command deadline exhausted across transport retries.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+        }
+        const remainingMs = Math.max(1000, deadlineAt - Date.now());
+        const command = {
+            id,
+            action,
+            ...params,
+            timeout: timeoutSeconds,
+            deadlineAt,
+            ...(contextId && { contextId }),
+            ...(windowMode && { windowMode }),
+        };
+        try {
+            const res = await requestDaemon('/command', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(command),
+                timeout: remainingMs + HTTP_TIMEOUT_MARGIN_MS,
+            });
+            const result = (await res.json());
+            if (result.ok)
+                return result;
+            if (result.errorCode && UNKNOWN_OUTCOME_CODES.has(result.errorCode)) {
+                throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
+            }
+            const isDuplicateCommandId = res.status === 409
+                && !result.errorCode
+                && (result.error ?? '').includes('Duplicate command id');
+            if (isDuplicateCommandId) {
+                throw new BrowserCommandError('Daemon already has this command id pending; the command may already be running.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+            }
+            if (isPreDispatchError(result.errorCode) && !ensureUsed) {
+                ensureUsed = true;
+                await ensureBridge();
+                continue;
+            }
+            const advice = classifyBrowserError(new BrowserCommandError(result.error ?? '', result.errorCode));
+            if (advice.kind === 'extension-transient' && !semanticRetryUsed) {
+                semanticRetryUsed = true;
+                id = generateId();
+                await sleep(advice.delayMs);
+                continue;
+            }
+            throw new BrowserCommandError(result.error ?? 'Daemon command failed', result.errorCode, result.errorHint);
+        }
+        catch (err) {
+            if (err instanceof BrowserCommandError || err instanceof BrowserConnectError)
+                throw err;
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new BrowserCommandError('Browser command timed out client-side; the page may still have applied it.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+            }
+            if (err instanceof TypeError) {
+                await ensureBridge();
+                if (isPreConnectFetchError(err))
+                    continue;
+                throw new BrowserCommandError('Connection to the daemon was lost mid-command; it may have already been applied.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+            }
+            throw err;
+        }
+    }
+    throw new BrowserCommandError('sendCommand: max attempts exhausted', 'max_attempts_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 {};