@kritchoff/agent-browser 0.9.2 → 0.9.4

package/dist/taxtree.js

@@ -0,0 +1,287 @@
+export async function getDualModeSnapshot(page, options = {}) {
+    const session = await page.context().newCDPSession(page);
+    let nodes = [];
+    let isDualMode = false;
+    try {
+        const result = (await session.send('Accessibility.getDualModeAXTree'));
+        nodes = result.nodes;
+        isDualMode = true;
+    }
+    catch (e) {
+        try {
+            const result = (await session.send('Accessibility.getFullAXTree'));
+            nodes = result.nodes;
+        }
+        catch (e2) {
+            console.warn('Failed to fetch AXTree via CDP:', e2);
+            return { tree: '(accessibility tree unavailable)', refs: {} };
+        }
+    }
+    finally {
+        await session.detach();
+    }
+    const refs = {};
+    let tree = '';
+    resetRefs();
+    if (isDualMode) {
+        const rootNodes = buildTreeFromFlatNodes(nodes);
+        tree = processDualModeTree(rootNodes, refs, options.interactive ?? false);
+    }
+    else {
+        const rootNodes = buildStandardTree(nodes);
+        tree = processStandardTree(rootNodes, refs, options.interactive ?? false);
+    }
+    return { tree, refs };
+}
+function buildTreeFromFlatNodes(nodes) {
+    const nodeMap = new Map();
+    nodes.forEach((n) => nodeMap.set(n.core.nodeId, n));
+    const roots = [];
+    nodes.forEach((node) => {
+        if (node.core.childrenIds) {
+            node.children = node.core.childrenIds
+                .map((id) => nodeMap.get(id))
+                .filter((n) => !!n);
+        }
+        const parentId = node.core.parentId;
+        if (parentId === undefined || !nodeMap.has(parentId)) {
+            roots.push(node);
+        }
+    });
+    return roots;
+}
+function buildStandardTree(nodes) {
+    const nodeMap = new Map();
+    // Initialize with empty children array
+    nodes.forEach((n) => nodeMap.set(n.nodeId, { ...n, children: [] }));
+    const roots = [];
+    const childrenIdsSet = new Set();
+    nodes.forEach((node) => {
+        if (node.childIds) {
+            const parent = nodeMap.get(node.nodeId);
+            if (parent) {
+                node.childIds.forEach((childId) => {
+                    const child = nodeMap.get(childId);
+                    if (child) {
+                        parent.children.push(child);
+                        childrenIdsSet.add(childId);
+                    }
+                });
+            }
+        }
+    });
+    nodes.forEach((node) => {
+        if (!childrenIdsSet.has(node.nodeId)) {
+            const root = nodeMap.get(node.nodeId);
+            if (root)
+                roots.push(root);
+        }
+    });
+    return roots;
+}
+let refCounter = 0;
+function resetRefs() {
+    refCounter = 0;
+}
+function nextRef() {
+    return `e${++refCounter}`;
+}
+const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'checkbox',
+    'radio',
+    'combobox',
+    'listbox',
+    'menuitem',
+    'option',
+    'searchbox',
+    'slider',
+    'spinbutton',
+    'switch',
+    'tab',
+    'treeitem',
+]);
+function processDualModeTree(nodes, refs, interactiveOnly = false, depth = 0) {
+    const lines = [];
+    for (const node of nodes) {
+        const core = node.core;
+        if (!core.visible)
+            continue;
+        const semantics = node.xrayMode?.semantics || {};
+        const interaction = node.xrayMode?.interaction || {};
+        const design = node.designMode || {};
+        const role = (semantics.role || core.className || 'unknown').toLowerCase();
+        let name = semantics.name || core.text || core.contentDescription || '';
+        name = name.replace(/\s+/g, ' ').trim();
+        // Smart Merge: Use child text if name is empty
+        if (name === '' && node.children && node.children.length > 0) {
+            const textChild = node.children.find((c) => c.core.className === '#text.StaticText');
+            if (textChild) {
+                name = (textChild.core.text || '').trim();
+            }
+        }
+        const isInteractive = core.clickable ||
+            INTERACTIVE_ROLES.has(role) ||
+            semantics.intentTags?.includes('interactive');
+        if (interactiveOnly && !isInteractive && (!node.children || node.children.length === 0)) {
+            continue;
+        }
+        let line = `${'  '.repeat(depth)}- ${role}`;
+        if (name)
+            line += ` "${name.replace(/"/g, '\\"')}"`;
+        if (isInteractive || (name && !['unknown', 'generic', 'group'].includes(role))) {
+            const ref = nextRef();
+            line += ` [ref=${ref}]`;
+            const safeNameDouble = name.replace(/"/g, '\\"');
+            let selector = '';
+            if (['button', 'link', 'textbox', 'checkbox', 'radio'].includes(role)) {
+                if (name)
+                    selector = `getByRole('${role}', { name: "${safeNameDouble}" })`;
+                else
+                    selector = `getByRole('${role}')`;
+            }
+            else if (name) {
+                selector = `getByText("${safeNameDouble}")`;
+            }
+            else {
+                selector = `locator('.${core.className || role}')`;
+            }
+            refs[ref] = {
+                selector,
+                role,
+                name,
+                bounds: core.bounds,
+                nodeId: core.nodeId,
+            };
+        }
+        // --- FULL METADATA OUTPUT ---
+        // 1. Core Info (filtered to interesting flags)
+        const coreInfo = {};
+        if (core.clickable)
+            coreInfo.clickable = true;
+        if (core.longClickable)
+            coreInfo.longClickable = true;
+        if (core.scrollable)
+            coreInfo.scrollable = true;
+        if (core.focusable)
+            coreInfo.focusable = true;
+        if (core.editable)
+            coreInfo.editable = true;
+        if (core.checkable)
+            coreInfo.checkable = true;
+        if (core.checked)
+            coreInfo.checked = true;
+        if (core.selected)
+            coreInfo.selected = true;
+        if (core.focused)
+            coreInfo.focused = true;
+        if (!core.enabled)
+            coreInfo.disabled = true;
+        // 2. Xray Info (semantics + interaction)
+        const xrayInfo = {};
+        if (semantics.importanceScore)
+            xrayInfo.importance = semantics.importanceScore;
+        if (semantics.intentTags?.length)
+            xrayInfo.intent = semantics.intentTags;
+        if (interaction.availableActions?.length)
+            xrayInfo.actions = interaction.availableActions;
+        if (interaction.affordanceScore)
+            xrayInfo.affordance = interaction.affordanceScore;
+        // 3. Design Info (visual + layout + spatial)
+        // Only include if non-default/interesting
+        const designInfo = {};
+        if (design.visual) {
+            if (design.visual.backgroundColor)
+                designInfo.bg = design.visual.backgroundColor;
+            if (design.visual.foregroundColor)
+                designInfo.fg = design.visual.foregroundColor;
+            if (design.visual.fontSize)
+                designInfo.fontSize = design.visual.fontSize;
+            if (design.visual.fontWeight && design.visual.fontWeight !== 400)
+                designInfo.weight = design.visual.fontWeight;
+            if (design.visual.opacity !== 1)
+                designInfo.opacity = design.visual.opacity;
+        }
+        if (design.layout) {
+            if (design.layout.zIndex !== 0)
+                designInfo.zIndex = design.layout.zIndex;
+            if (design.layout.isFixedPosition)
+                designInfo.fixed = true;
+            if (design.layout.isSticky)
+                designInfo.sticky = true;
+        }
+        if (design.spatial) {
+            if (!design.spatial.isAboveFold)
+                designInfo.belowFold = true;
+            if (design.spatial.visualProminenceScore)
+                designInfo.prominence = design.spatial.visualProminenceScore;
+        }
+        // Append JSON objects to line, indented
+        const indent = '  '.repeat(depth + 1);
+        if (Object.keys(coreInfo).length > 0) {
+            line += `\n${indent}core: ${JSON.stringify(coreInfo)}`;
+        }
+        if (Object.keys(xrayInfo).length > 0) {
+            line += `\n${indent}xray: ${JSON.stringify(xrayInfo)}`;
+        }
+        if (Object.keys(designInfo).length > 0) {
+            line += `\n${indent}design: ${JSON.stringify(designInfo)}`;
+        }
+        lines.push(line);
+        if (node.children) {
+            const filteredChildren = node.children.filter((c) => c.core.className !== '#text.StaticText');
+            if (filteredChildren.length > 0) {
+                const childrenStr = processDualModeTree(filteredChildren, refs, interactiveOnly, depth + 1);
+                if (childrenStr)
+                    lines.push(childrenStr);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function processStandardTree(nodes, refs, interactiveOnly, depth = 0) {
+    const lines = [];
+    for (const node of nodes) {
+        const role = (node.role?.value || 'unknown').toLowerCase();
+        let name = node.name?.value || '';
+        name = name.replace(/\s+/g, ' ').trim();
+        const isInteractive = INTERACTIVE_ROLES.has(role);
+        let line = `${'  '.repeat(depth)}- ${role}`;
+        if (name) {
+            line += ` "${name.replace(/"/g, '\\"')}"`;
+        }
+        if (isInteractive || (name && role !== 'unknown')) {
+            const ref = nextRef();
+            line += ` [ref=${ref}]`;
+            const safeNameDouble = name.replace(/"/g, '\\"');
+            let selector = '';
+            if (isInteractive) {
+                if (name)
+                    selector = `getByRole('${role}', { name: "${safeNameDouble}" })`;
+                else
+                    selector = `getByRole('${role}')`;
+            }
+            else if (name) {
+                selector = `getByText("${safeNameDouble}")`;
+            }
+            else {
+                selector = `locator('${role}')`;
+            }
+            refs[ref] = {
+                selector: selector,
+                role: role,
+                name: name,
+            };
+        }
+        lines.push(line);
+        if (node.children && node.children.length > 0) {
+            const childrenTree = processStandardTree(node.children, refs, interactiveOnly, depth + 1);
+            if (childrenTree)
+                lines.push(childrenTree);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=taxtree.js.map

package/dist/taxtree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taxtree.js","sourceRoot":"","sources":["../src/taxtree.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kritchoff/agent-browser",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Headless browser automation CLI for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "scripts",
     "skills",
     "sdk.sh",
+    "start.sh",
     "docker-compose.sdk.yml"
   ],
   "bin": {
@@ -31,6 +32,7 @@
     "fast-reset": "./scripts/fast_reset.sh",
     "sdk": "./sdk.sh",
     "release": "npm run version:sync && npm run build && npm run build:all-platforms && npm publish",
+    "prepublishOnly": "npm run build",
     "start": "node dist/daemon.js",
     "dev": "tsx src/daemon.ts",
     "typecheck": "tsc --noEmit",

package/start.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=================================================${NC}"
+echo -e "${BLUE}   Agent Browser - Android Environment Setup     ${NC}"
+echo -e "${BLUE}=================================================${NC}"
+
+SNAPSHOT_PATH=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --snapshot)
+            SNAPSHOT_PATH="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# 1. Pre-flight Checks
+echo -e "\n${YELLOW}[1/4] Checking System Requirements...${NC}"
+
+if ! command -v docker &> /dev/null; then
+    echo -e "${RED}Error: Docker is not installed.${NC}"
+    exit 1
+fi
+
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    if [ -e /dev/kvm ]; then
+        echo -e "${GREEN}✓ KVM Acceleration detected (/dev/kvm)${NC}"
+    else
+        echo -e "${YELLOW}⚠ Warning: No KVM detected. Emulator will be slow.${NC}"
+    fi
+fi
+
+# 2. Start Services
+echo -e "\n${YELLOW}[2/4] Starting Docker Stack...${NC}"
+echo "      (First run may take a few minutes to download images)"
+
+docker compose -f "${COMPOSE_FILE:-docker-compose.prod.yml}" up -d --build --remove-orphans > /dev/null 2>&1
+
+# Find actual container names
+ANDROID_CONTAINER=$(docker compose -f "${COMPOSE_FILE:-docker-compose.prod.yml}" ps -q android-service)
+AGENT_CONTAINER=$(docker compose -f "${COMPOSE_FILE:-docker-compose.prod.yml}" ps -q agent-service)
+
+# 2b. Import Snapshot (if requested)
+if [ -n "$SNAPSHOT_PATH" ]; then
+    echo -e "\n${YELLOW}[2.5/4] Importing Snapshot: $SNAPSHOT_PATH...${NC}"
+    
+    # Wait for container to be responsive
+    echo -n "      Waiting for container to be ready for import... "
+    until docker exec "$ANDROID_CONTAINER" echo "ready" &>/dev/null; do
+        sleep 1
+    done
+    echo -e "${GREEN}OK${NC}"
+
+    # Import
+    if ./scripts/snapshot_manager.sh import "$SNAPSHOT_PATH" "w8rl_imported"; then
+        echo -e "${GREEN}      Snapshot imported successfully.${NC}"
+        
+        # Configure emulator to load this snapshot
+        # We set the env var in the container for the next boot
+        # (This assumes the entrypoint script respects EMULATOR_SNAPSHOT_NAME)
+        # For now, we'll rely on the default behavior or standard AVD loading
+        
+        echo "      Restarting Android service to load snapshot..."
+        docker compose -f "${COMPOSE_FILE:-docker-compose.prod.yml}" restart android-service
+        
+        # Update container ID after restart
+        ANDROID_CONTAINER=$(docker compose -f "${COMPOSE_FILE:-docker-compose.prod.yml}" ps -q android-service)
+    else
+        echo -e "${RED}Error: Failed to import snapshot.${NC}"
+        exit 1
+    fi
+fi
+
+# 3. Wait for Readiness
+echo -e "\n${YELLOW}[3/4] Waiting for Initialization...${NC}"
+
+wait_for_log() {
+    local container=$1
+    local pattern=$2
+    local label=$3
+    
+    echo -n "      Waiting for $label... "
+    until docker logs "$container" 2>&1 | grep -q "$pattern"; do
+        sleep 2
+    done
+    echo -e "${GREEN}Done!${NC}"
+}
+
+wait_for_log "$ANDROID_CONTAINER" "Emulator boot complete" "Android Emulator Boot"
+wait_for_log "$ANDROID_CONTAINER" "APK installation complete" "WootzApp Installation"
+wait_for_log "$ANDROID_CONTAINER" "CDP Bridge ready" "CDP Bridge"
+wait_for_log "$AGENT_CONTAINER" "Ready on port 3000" "Agent Daemon Connection"
+
+# 4. Success
+echo -e "\n${GREEN}[4/4] Environment Ready!${NC}"
+echo -e "${BLUE}=================================================${NC}"
+echo -e "You can now control the Android browser."
+echo -e ""
+echo -e "Try these commands:"
+echo -e "  ${GREEN}./agent open https://google.com${NC}"
+echo -e "  ${GREEN}./agent snapshot${NC}"
+echo -e "  ${GREEN}./agent click @e1${NC}"
+echo -e ""
+echo -e "See COMMANDS.md for full reference."
+echo -e "${BLUE}=================================================${NC}"