@mercuryo-ai/agentbrowse 0.2.50

package/dist/control-semantics.js

@@ -0,0 +1,419 @@
+const DATE_LIKE_LABEL_RE = /(?:\b\d{1,2}\b|январ|феврал|март|апрел|ма[йя]|июн|июл|август|сентябр|октябр|ноябр|декабр|january|february|march|april|may|june|july|august|september|october|november|december|date|дата|calendar|datepicker|календар)/i;
+const SUBMIT_LABEL_RE = /(?:buy|book|continue|search|find|open|submit|next|pay|купить|забронировать|продолжить|найти|открыть|оплатить)/i;
+const PREREQUISITE_HINT_RE = /(?:choose|select|pick|set|enter|fill|complete)\b.*\b(?:first|before)\b|(?:first|before)\b.*\b(?:choose|select|pick|set|enter|fill|complete)\b|(?:сначала|сперва)\b.*\b(?:выберите|заполните|укажите|введите|завершите)\b|\b(?:выберите|заполните|укажите|введите|завершите)\b.*\b(?:сначала|сперва)\b|required first|available after|unlock/i;
+const PHONE_FIELD_RE = /\b(phone|mobile|telephone|tel)\b/i;
+const CARD_NUMBER_FIELD_RE = /\b(card.?number|cc.?number|cardnumber|pan|cc-number)\b/i;
+const CARD_EXPIRY_FIELD_RE = /\b(exp(?:iry|iration)(?: date)?|cc-exp|valid\s+thru|valid\s+through|mm\s*\/\s*yy(?:yy)?)\b/i;
+const CARD_CVC_FIELD_RE = /\b(cvc|cvv|cc-csc|security code|card cvc)\b/i;
+const DATE_VALUE_MASK_RE = /(?:^|\b)(?:dd|d|дд|д)\s*[./-]\s*(?:mm|m|мм|м)\s*[./-]\s*(?:yyyy|yyy|yy|y|гггг|гг|г)(?:\b|$)/i;
+const NON_CARD_DATE_FIELD_RE = /\b(?:birth|dob|date|issued|expires|expiry|expiration|expir)\b|(?:дата|рожд|срок)/i;
+function normalizeText(value) {
+    return (value ?? '').trim().toLowerCase();
+}
+function primaryLabel(facts) {
+    return facts.label ?? facts.displayLabel ?? facts.text ?? facts.placeholder ?? '';
+}
+function valueTypeHintBlob(facts) {
+    return [
+        facts.label,
+        facts.displayLabel,
+        facts.text,
+        facts.placeholder,
+        facts.inputName,
+        facts.autocomplete,
+    ]
+        .filter((value) => Boolean(value))
+        .join(' ')
+        .trim();
+}
+export function inferComparableValueTypeFromFacts(facts) {
+    const inputType = normalizeText(facts.inputType);
+    const autocomplete = normalizeText(facts.autocomplete);
+    const hintBlob = valueTypeHintBlob(facts);
+    if (inputType === 'tel' || autocomplete.includes('tel') || PHONE_FIELD_RE.test(hintBlob)) {
+        return 'phone';
+    }
+    if (autocomplete.includes('cc-number') || CARD_NUMBER_FIELD_RE.test(hintBlob)) {
+        return 'card-number';
+    }
+    const cardExpiryLike = autocomplete.includes('cc-exp') ||
+        (inputType !== 'date' &&
+            CARD_EXPIRY_FIELD_RE.test(hintBlob) &&
+            (autocomplete.startsWith('cc-') ||
+                /\b(card|credit|debit)\b/i.test(hintBlob) ||
+                /\bmm\s*\/\s*yy(?:yy)?\b/i.test(hintBlob)));
+    if (cardExpiryLike) {
+        return 'expiry';
+    }
+    if (autocomplete.includes('cc-csc') || CARD_CVC_FIELD_RE.test(hintBlob)) {
+        return 'cvc';
+    }
+    const nonCardDateLike = inputType === 'date' ||
+        DATE_VALUE_MASK_RE.test(hintBlob) ||
+        (NON_CARD_DATE_FIELD_RE.test(hintBlob) &&
+            !autocomplete.startsWith('cc-') &&
+            !/\b(card|credit|debit|cvc|cvv|security code)\b/i.test(hintBlob));
+    if (nonCardDateLike) {
+        return 'date';
+    }
+    return undefined;
+}
+function isPopupBackedTextEntry(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const surfaceKind = normalizeText(facts.surfaceKind);
+    if ((kind === 'input' || kind === 'textarea' || role === 'textbox') &&
+        (Boolean(facts.controlsSurfaceSelector) ||
+            surfaceKind === 'listbox' ||
+            surfaceKind === 'menu' ||
+            facts.states?.expanded !== undefined)) {
+        return true;
+    }
+    return false;
+}
+function isPopupBackedComboboxFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const surfaceKind = normalizeText(facts.surfaceKind);
+    if (kind !== 'combobox' && role !== 'combobox') {
+        return false;
+    }
+    return (Boolean(facts.controlsSurfaceSelector) ||
+        surfaceKind === 'listbox' ||
+        surfaceKind === 'menu' ||
+        surfaceKind === 'floating-panel' ||
+        facts.states?.expanded !== undefined);
+}
+function isSearchableComboboxFacts(facts) {
+    const ariaAutocomplete = normalizeText(facts.ariaAutocomplete);
+    if (!isPopupBackedComboboxFacts(facts)) {
+        return false;
+    }
+    return (ariaAutocomplete === 'list' || ariaAutocomplete === 'both' || ariaAutocomplete === 'inline');
+}
+function isSelectLikePopupOwner(facts) {
+    const kind = normalizeText(facts.kind);
+    if (kind === 'select') {
+        return true;
+    }
+    if (isPopupBackedComboboxFacts(facts)) {
+        return true;
+    }
+    return isPopupBackedTextEntry(facts) && facts.states?.readonly === true;
+}
+function isButtonLikeInputFacts(facts) {
+    return (normalizeText(facts.kind) === 'input' &&
+        ['button', 'submit', 'reset'].includes(normalizeText(facts.inputType)));
+}
+function isSelectionItemLikeFacts(facts) {
+    return isPopupSelectionListitemFacts(facts) || isLegacySelectionItemLikeFacts(facts);
+}
+function isLegacySelectionItemLikeFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    return (kind === 'option' ||
+        role === 'option' ||
+        role === 'menuitem' ||
+        facts.structure?.family === 'structured-grid');
+}
+function isPopupSelectionListitemFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const surfaceKind = normalizeText(facts.surfaceKind);
+    return ((kind === 'listitem' || role === 'listitem') &&
+        (surfaceKind === 'floating-panel' ||
+            surfaceKind === 'listbox' ||
+            surfaceKind === 'menu' ||
+            facts.states?.selected === true ||
+            facts.states?.current === true ||
+            facts.states?.selectable === true));
+}
+function isBinaryToggleControlFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const inputType = normalizeText(facts.inputType);
+    return (kind === 'checkbox' ||
+        kind === 'radio' ||
+        role === 'checkbox' ||
+        role === 'radio' ||
+        role === 'switch' ||
+        kind === 'tab' ||
+        role === 'tab' ||
+        inputType === 'checkbox' ||
+        inputType === 'radio');
+}
+function isDisclosureLikeTriggerFacts(facts, controlFamily) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const inputType = normalizeText(facts.inputType);
+    const popupBacked = Boolean(facts.controlsSurfaceSelector) || facts.states?.expanded !== undefined;
+    if (!popupBacked) {
+        return false;
+    }
+    if (isSelectionItemLikeFacts(facts) || controlFamily === 'text-input') {
+        return false;
+    }
+    if (controlFamily === 'select' || controlFamily === 'datepicker') {
+        return true;
+    }
+    return (kind === 'button' ||
+        role === 'button' ||
+        kind === 'link' ||
+        role === 'link' ||
+        kind === 'combobox' ||
+        role === 'combobox' ||
+        kind === 'select' ||
+        isButtonLikeInputFacts(facts) ||
+        inputType === 'button' ||
+        isPopupBackedTextEntry(facts));
+}
+function isToggleLikeControlFacts(facts, controlFamily) {
+    const states = facts.states;
+    if (!states) {
+        return false;
+    }
+    if (states.checked !== undefined || isBinaryToggleControlFacts(facts)) {
+        return true;
+    }
+    if (states.selected !== undefined) {
+        if (isSelectionItemLikeFacts(facts) ||
+            controlFamily === 'select' ||
+            controlFamily === 'datepicker' ||
+            isDisclosureLikeTriggerFacts(facts, controlFamily)) {
+            return false;
+        }
+        return true;
+    }
+    if (states.pressed !== undefined) {
+        return !isDisclosureLikeTriggerFacts(facts, controlFamily);
+    }
+    return false;
+}
+export function isLikelyDateLikeLabel(value) {
+    const trimmed = (value ?? '').trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (/^\+?\d{1,4}$/.test(trimmed)) {
+        return false;
+    }
+    if (/\+\d{1,4}\b/.test(trimmed)) {
+        return false;
+    }
+    return DATE_LIKE_LABEL_RE.test(trimmed);
+}
+export function inferAllowedActionsFromFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const interactionHint = normalizeText(facts.interactionHint);
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const selectLikePopupOwner = isSelectLikePopupOwner(facts);
+    const buttonLikeInput = isButtonLikeInputFacts(facts);
+    const checkedToggle = facts.states?.checked !== undefined ||
+        kind === 'checkbox' ||
+        kind === 'radio' ||
+        role === 'checkbox' ||
+        role === 'radio' ||
+        role === 'switch';
+    const actions = new Set();
+    if (selectLikePopupOwner) {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+        if (facts.surfaceKind === 'datepicker' || isLikelyDateLikeLabel(primaryLabel(facts))) {
+            actions.add('fill');
+        }
+        if ((kind === 'combobox' || role === 'combobox') && isSearchableComboboxFacts(facts)) {
+            actions.add('fill');
+            actions.add('type');
+        }
+    }
+    else if (!buttonLikeInput &&
+        (kind === 'input' ||
+            kind === 'textarea' ||
+            role === 'textbox' ||
+            ((kind === 'combobox' || role === 'combobox') && !isPopupBackedComboboxFacts(facts)))) {
+        actions.add('click');
+        actions.add('fill');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (!selectLikePopupOwner && kind === 'select') {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+    }
+    if (kind === 'option' || role === 'option' || role === 'menuitem') {
+        actions.add('click');
+    }
+    if (isPopupSelectionListitemFacts(facts)) {
+        actions.add('click');
+        actions.add('press');
+        actions.add('select');
+    }
+    if (checkedToggle) {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (role === 'gridcell' || facts.structure?.family === 'structured-grid') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (kind === 'button' ||
+        kind === 'link' ||
+        kind === 'tab' ||
+        role === 'button' ||
+        role === 'link' ||
+        role === 'tab') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (interactionHint === 'click') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (legacyMethod === 'click') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (legacyMethod === 'fill') {
+        actions.add('click');
+        actions.add('fill');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (legacyMethod === 'type') {
+        actions.add('click');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (legacyMethod === 'select') {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+    }
+    if (legacyMethod === 'press') {
+        actions.add('press');
+    }
+    return [...actions];
+}
+export function inferAvailabilityFromFacts(states, contextHint, options = {}) {
+    if (states?.occupied === true) {
+        return { state: 'gated', reason: 'occupied' };
+    }
+    const blocked = states?.disabled === true ||
+        states?.ariaDisabled === true ||
+        states?.readonly === true ||
+        states?.selectable === false;
+    if (blocked && PREREQUISITE_HINT_RE.test(contextHint ?? '')) {
+        return { state: 'gated', reason: 'prerequisite' };
+    }
+    if (states?.selectable === false) {
+        return { state: 'gated', reason: 'not-selectable' };
+    }
+    if (states?.disabled === true || states?.ariaDisabled === true) {
+        return { state: 'gated', reason: 'disabled' };
+    }
+    if (states?.readonly === true) {
+        if (options.readonlyInteractive) {
+            return { state: 'available' };
+        }
+        return { state: 'gated', reason: 'readonly' };
+    }
+    return { state: 'available' };
+}
+export function inferControlFamilyFromFacts(facts, allowedActions) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const label = primaryLabel(facts);
+    const dateLike = isLikelyDateLikeLabel(label) || facts.surfaceKind === 'datepicker';
+    const comparableValueType = inferComparableValueTypeFromFacts(facts);
+    if (facts.structure?.family === 'structured-grid') {
+        return 'structured-grid';
+    }
+    if (comparableValueType === 'expiry') {
+        return 'text-input';
+    }
+    if (dateLike &&
+        (kind === 'input' ||
+            kind === 'textarea' ||
+            kind === 'select' ||
+            kind === 'combobox' ||
+            role === 'textbox' ||
+            role === 'combobox' ||
+            kind === 'option' ||
+            role === 'option' ||
+            role === 'menuitem' ||
+            allowedActions.includes('select') ||
+            legacyMethod === 'select')) {
+        return 'datepicker';
+    }
+    if (isSelectLikePopupOwner(facts) ||
+        kind === 'option' ||
+        role === 'option' ||
+        role === 'menuitem' ||
+        allowedActions.includes('select') ||
+        legacyMethod === 'select') {
+        return 'select';
+    }
+    if (isButtonLikeInputFacts(facts)) {
+        return 'trigger';
+    }
+    if (kind === 'input' ||
+        kind === 'textarea' ||
+        role === 'textbox' ||
+        allowedActions.includes('fill') ||
+        allowedActions.includes('type') ||
+        legacyMethod === 'fill' ||
+        legacyMethod === 'type') {
+        return 'text-input';
+    }
+    if (kind === 'button' ||
+        kind === 'link' ||
+        role === 'button' ||
+        role === 'link' ||
+        allowedActions.includes('click') ||
+        allowedActions.includes('press') ||
+        legacyMethod === 'click' ||
+        legacyMethod === 'press') {
+        return 'trigger';
+    }
+    return undefined;
+}
+export function inferAcceptancePolicyFromFacts(facts, allowedActions) {
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const label = primaryLabel(facts);
+    const states = facts.states;
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const controlFamily = inferControlFamilyFromFacts(facts, allowedActions);
+    if (facts.structure?.family === 'structured-grid') {
+        return facts.structure.variant === 'date-cell' ? 'date-selection' : 'selection';
+    }
+    if (controlFamily === 'text-input') {
+        return 'value-change';
+    }
+    if (isDisclosureLikeTriggerFacts(facts, controlFamily)) {
+        return 'disclosure';
+    }
+    if (isToggleLikeControlFacts(facts, controlFamily)) {
+        return 'toggle';
+    }
+    if (controlFamily === 'datepicker') {
+        return 'date-selection';
+    }
+    if (controlFamily === 'select') {
+        return 'selection';
+    }
+    if (role === 'link' || kind === 'link') {
+        return 'navigation';
+    }
+    if (!legacyMethod && SUBMIT_LABEL_RE.test(label)) {
+        return 'submit';
+    }
+    if (controlFamily === 'trigger' || legacyMethod === 'click' || legacyMethod === 'press') {
+        return 'generic-click';
+    }
+    return undefined;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,132 @@
+import type { BrowserSessionState } from './browser-session-state.js';
+/** Command names emitted through the diagnostics hook surface. */
+export type DiagnosticCommand = 'launch' | 'navigate' | 'observe' | 'act' | 'extract' | 'screenshot' | 'browser-status' | 'status' | 'close';
+export type DiagnosticStepRefs = {
+    pageRef?: string;
+    targetRef?: string;
+    surfaceRef?: string;
+    fillRef?: string;
+    requestId?: string;
+};
+export type DiagnosticSnapshotPhase = 'before' | 'after' | 'point-in-time';
+export type DiagnosticChildSpanKind = 'client';
+/** Step handle returned by `startStep(...)` and passed back to later hooks. */
+export type DiagnosticStepHandle = {
+    runId: string;
+    stepId: string;
+    command: DiagnosticCommand;
+};
+export type DiagnosticStepStartInput = {
+    runId?: string;
+    command: DiagnosticCommand;
+    input?: Record<string, unknown>;
+    refs?: DiagnosticStepRefs;
+    protectedStep?: boolean;
+};
+export type DiagnosticStepFinishInput = {
+    step: DiagnosticStepHandle | null | undefined;
+    success: boolean;
+    outcomeType?: string;
+    message?: string;
+    reason?: string;
+    artifactManifestId?: string;
+};
+export type DiagnosticSnapshotInput = {
+    step: DiagnosticStepHandle | null | undefined;
+    session: BrowserSessionState;
+    phase: DiagnosticSnapshotPhase;
+    pageRef?: string;
+    url?: string;
+    title?: string;
+    artifactRefs?: {
+        screenshotPath?: string;
+        htmlPath?: string;
+        tracePath?: string;
+        logPath?: string;
+    };
+};
+export type DiagnosticLifecycleEventInput = {
+    step: DiagnosticStepHandle | null | undefined;
+    phase: 'started' | 'completed' | 'failed';
+    attributes?: Record<string, unknown>;
+};
+export type DiagnosticChildSpanInput = {
+    step: DiagnosticStepHandle | null | undefined;
+    name: string;
+    kind?: DiagnosticChildSpanKind;
+    startedAt: string;
+    endedAt: string;
+    statusCode: 'unset' | 'ok' | 'error';
+    statusMessage?: string;
+    attributes?: Record<string, unknown>;
+};
+export type DiagnosticArtifactManifest = {
+    artifactManifestId: string;
+    stepId: string;
+    screenshots: Array<{
+        path: string;
+        purpose: string;
+        storageBucket?: string;
+        storagePath?: string;
+    }>;
+    htmlSnapshots: Array<{
+        path: string;
+        purpose: string;
+        storageBucket?: string;
+        storagePath?: string;
+    }>;
+    traces: Array<{
+        path: string;
+        purpose: string;
+        storageBucket?: string;
+        storagePath?: string;
+    }>;
+    logs: Array<{
+        path: string;
+        purpose: string;
+        storageBucket?: string;
+        storagePath?: string;
+    }>;
+    suppressed: Array<{
+        kind: 'screenshot' | 'html' | 'trace' | 'log';
+        reason: 'protected_exposure_active' | 'sensitive_scope' | 'policy_blocked' | 'capture_failed';
+    }>;
+};
+export type DiagnosticArtifactManifestInput = {
+    runId: string;
+    step?: DiagnosticStepHandle | null;
+    manifest: DiagnosticArtifactManifest;
+};
+export type AgentbrowseDiagnosticsHooks = {
+    startStep?: (input: DiagnosticStepStartInput) => DiagnosticStepHandle | null;
+    finishStep?: (input: DiagnosticStepFinishInput) => void | Promise<void>;
+    captureSnapshot?: (input: DiagnosticSnapshotInput) => void | Promise<void>;
+    recordCommandEvent?: (input: DiagnosticLifecycleEventInput) => void | Promise<void>;
+    recordChildSpan?: (input: DiagnosticChildSpanInput) => void | Promise<void>;
+    recordArtifactManifest?: (input: DiagnosticArtifactManifestInput) => void | Promise<void>;
+    flushRun?: (runId: string | undefined) => void | Promise<void>;
+};
+/** Configures process-global diagnostics hooks for AgentBrowse commands. */
+export declare function configureAgentbrowseDiagnostics(hooks: AgentbrowseDiagnosticsHooks | null | undefined): void;
+/** Clears the currently configured process-global diagnostics hooks. */
+export declare function resetAgentbrowseDiagnostics(): void;
+/** Starts a new diagnostic step when the caller provided a run id and hooks are configured. */
+export declare function startDiagnosticStep(input: DiagnosticStepStartInput, options?: {
+    session?: BrowserSessionState | null;
+}): DiagnosticStepHandle | null;
+/** Finishes a diagnostic step and suppresses hook failures. */
+export declare function finishDiagnosticStepBestEffort(input: DiagnosticStepFinishInput): Promise<void>;
+/** Captures a best-effort diagnostics snapshot for the current page state. */
+export declare function captureDiagnosticSnapshotBestEffort(input: DiagnosticSnapshotInput): void;
+/** Records a best-effort command lifecycle event. */
+export declare function recordCommandLifecycleEventBestEffort(input: DiagnosticLifecycleEventInput): void;
+/** Records a best-effort child span inside the current command step. */
+export declare function recordDiagnosticChildSpanBestEffort(input: DiagnosticChildSpanInput): void;
+/** Records a best-effort artifact manifest for the current diagnostics run. */
+export declare function recordDiagnosticArtifactManifestBestEffort(input: DiagnosticArtifactManifestInput | null | undefined): Promise<string | undefined>;
+/** Flushes any pending diagnostics work for the run when hooks provide a flush handler. */
+export declare function flushDiagnosticRunBestEffort(runId: string | undefined, options?: {
+    session?: BrowserSessionState | null;
+    step?: DiagnosticStepHandle | null;
+}): Promise<void>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,UAAU,GACV,SAAS,GACT,KAAK,GACL,SAAS,GACT,YAAY,GACZ,gBAAgB,GAChB,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,eAAe,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,uBAAuB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE;QACb,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,aAAa,EAAE,KAAK,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,IAAI,EAAE,KAAK,CAAC;QACV,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;QAC9C,MAAM,EAAE,2BAA2B,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;KAC/F,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnC,QAAQ,EAAE,0BAA0B,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,oBAAoB,GAAG,IAAI,CAAC;IAC7E,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,6BAA6B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,+BAA+B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE,CAAC;AAkBF,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,2BAA2B,GAAG,IAAI,GAAG,SAAS,GACpD,IAAI,CAEN;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAoBD,+FAA+F;AAC/F,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,EAC/B,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACjC,GACL,oBAAoB,GAAG,IAAI,CAW7B;AAED,+DAA+D;AAC/D,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,8EAA8E;AAC9E,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAYxF;AAED,qDAAqD;AACrD,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,6BAA6B,GAAG,IAAI,CAUhG;AAED,wEAAwE;AACxE,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI,CAUzF;AAED,+EAA+E;AAC/E,wBAAsB,0CAA0C,CAC9D,KAAK,EAAE,+BAA+B,GAAG,IAAI,GAAG,SAAS,GACxD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkB7B;AAED,2FAA2F;AAC3F,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrC,IAAI,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/B,GACL,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/diagnostics.js

@@ -0,0 +1,120 @@
+import { getAgentbrowseSessionBindings } from './client-bindings.js';
+let currentHooks = {};
+const hooksByStep = new WeakMap();
+function isPromiseLike(value) {
+    return typeof value === 'object' && value !== null && 'then' in value;
+}
+function fireAndForget(result) {
+    if (isPromiseLike(result)) {
+        void result.then(() => undefined, () => undefined);
+    }
+}
+/** Configures process-global diagnostics hooks for AgentBrowse commands. */
+export function configureAgentbrowseDiagnostics(hooks) {
+    currentHooks = hooks ?? {};
+}
+/** Clears the currently configured process-global diagnostics hooks. */
+export function resetAgentbrowseDiagnostics() {
+    currentHooks = {};
+}
+function resolveDiagnosticHooks(options = {}) {
+    const stepHooks = options.step ? hooksByStep.get(options.step) : null;
+    if (stepHooks) {
+        return stepHooks;
+    }
+    const boundHooks = options.session
+        ? (getAgentbrowseSessionBindings(options.session)?.diagnostics ?? null)
+        : null;
+    return boundHooks ?? currentHooks;
+}
+/** Starts a new diagnostic step when the caller provided a run id and hooks are configured. */
+export function startDiagnosticStep(input, options = {}) {
+    if (!input.runId) {
+        return null;
+    }
+    const hooks = resolveDiagnosticHooks(options);
+    const step = hooks.startStep?.(input) ?? null;
+    if (step) {
+        hooksByStep.set(step, hooks);
+    }
+    return step;
+}
+/** Finishes a diagnostic step and suppresses hook failures. */
+export async function finishDiagnosticStepBestEffort(input) {
+    if (!input.step) {
+        return;
+    }
+    try {
+        await resolveDiagnosticHooks({ step: input.step }).finishStep?.(input);
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/** Captures a best-effort diagnostics snapshot for the current page state. */
+export function captureDiagnosticSnapshotBestEffort(input) {
+    if (!input.step) {
+        return;
+    }
+    try {
+        fireAndForget(resolveDiagnosticHooks({ step: input.step, session: input.session }).captureSnapshot?.(input));
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/** Records a best-effort command lifecycle event. */
+export function recordCommandLifecycleEventBestEffort(input) {
+    if (!input.step) {
+        return;
+    }
+    try {
+        fireAndForget(resolveDiagnosticHooks({ step: input.step }).recordCommandEvent?.(input));
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/** Records a best-effort child span inside the current command step. */
+export function recordDiagnosticChildSpanBestEffort(input) {
+    if (!input.step) {
+        return;
+    }
+    try {
+        fireAndForget(resolveDiagnosticHooks({ step: input.step }).recordChildSpan?.(input));
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/** Records a best-effort artifact manifest for the current diagnostics run. */
+export async function recordDiagnosticArtifactManifestBestEffort(input) {
+    if (!input?.runId) {
+        return undefined;
+    }
+    const recordArtifactManifest = resolveDiagnosticHooks({
+        step: input.step,
+    }).recordArtifactManifest;
+    if (!recordArtifactManifest) {
+        return undefined;
+    }
+    try {
+        await recordArtifactManifest(input);
+        return input.manifest.artifactManifestId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Flushes any pending diagnostics work for the run when hooks provide a flush handler. */
+export async function flushDiagnosticRunBestEffort(runId, options = {}) {
+    if (!runId) {
+        return;
+    }
+    try {
+        await resolveDiagnosticHooks(options).flushRun?.(runId);
+    }
+    catch {
+        // Best effort only.
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+declare function main(argv?: string[]): Promise<void>;
+export { main };
+export declare function isDirectExecution(metaUrl: string, argv?: string[]): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAmQA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqJhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}