mobile-debug-mcp 0.21.5 → 0.23.0

package/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+This file is the **cold-start entrypoint for autonomous agents** that arrive in this public repository without prior context.
+
+It is intentionally vendor-neutral and should be useful to Copilot, Codex, Claude, or custom agent systems.
+
+## What this repository is
+
+`mobile-debug-mcp` is an MCP server for mobile app debugging on Android and iOS. The codebase is TypeScript and the built server entrypoint is `dist/server.js`.
+
+Primary areas:
+
+- `src/server.ts` — runtime entrypoint
+- `src/server-core.ts` — tool registration and dispatch logic
+- `src/interact/` — tap, swipe, typing, waits, and interaction helpers
+- `src/observe/` — logs, screenshots, UI tree, fingerprints, snapshots
+- `src/manage/` — build, install, start, terminate, restart, reset-app-data
+- `src/system/` — environment and toolchain health checks
+- `src/utils/` — shared helpers and platform-specific utility code
+
+## First things an agent should know
+
+1. Prefer existing helpers and conventions over introducing new frameworks or abstractions.
+2. The repository already has a test structure; place tests in the correct tree instead of inventing new ones.
+3. Use existing validation commands:
+   - `npm run build`
+   - `npm run lint`
+   - `npm run test:unit`
+   - `npm run test:device`
+4. Device tests are split intentionally:
+   - `test/device/automated/...` = automated smoke/integration coverage
+   - `test/device/manual/...` = helper/debug/manual scripts
+5. Unit tests use the current lightweight self-running `tsx` pattern rather than a dedicated framework.
+
+## Where to look for deeper guidance
+
+### Skills
+
+Portable agent skills live under `skills/`.
+
+- `skills/README.md` — repo-wide skill convention
+- `skills/mcp-builder/` — build/install/toolchain guidance
+- `skills/test-authoring/` — test creation and placement guidance
+
+If the task is about **creating or updating tests**, load `skills/test-authoring/SKILL.md` first.
+
+If the task is about **building, installing, or diagnosing native tooling**, load `skills/mcp-builder/SKILL.md` first.
+
+### Repository docs
+
+- `README.md` — high-level repo overview and commands
+- `docs/tools/TOOLS.md` — tool documentation and contracts
+- `docs/CHANGELOG.md` — recent behavioral changes
+
+## Testing guidance
+
+Use these defaults unless the task clearly requires something else:
+
+- Add automated unit tests under `test/unit/...`
+- Add automated device smoke tests under `test/device/automated/...`
+- Add ad hoc or environment-specific helper scripts under `test/device/manual/...`
+
+For test authoring details, rely on the `test-authoring` skill package rather than duplicating its rules here.
+
+## Output expectations for agents
+
+- Make focused changes
+- Preserve existing repo behavior unless the task requires a change
+- Keep docs aligned when structure or usage changes
+- Prefer deterministic validation over ad hoc verification
+
+## Notes for maintainers
+
+This file is intentionally short. Keep task-specific guidance in `skills/...` so multiple agent systems can reuse the same instructions.

package/README.md

@@ -2,8 +2,10 @@
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-> **Note:**
-> * iOS only tested on simulator.
+> **Support:**
+> * Android support
+> * iOS only tested on simulator
+> * KMP support
 > * Flutter iOS projects not fetching logs
 > * React native not tested
 
@@ -32,15 +34,32 @@ You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
 ## Usage
 
 Examples: 
-* I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
-* Add a button, hook into the repository and confirm API request successful
+
+Crash fixing:
+> I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+
+Feature building:
+> Add a button, hook into the repository and confirm API request successful
 
 ## Docs
 
 - Tools: [Tools](docs/tools/TOOLS.md) — full input/response examples
 - Changelog: [Changelog](docs/CHANGELOG.md)
+- Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
+- Skills: [skills/README.md](skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
+
+## Testing
+
+- `npm run test:unit` runs every automated unit test under `test/unit/...`
+- `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
+- Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
+
+## Agent skills
+
+- `skills/mcp-builder/` contains reusable build/install guidance for agents
+- `skills/test-authoring/` contains reusable test-creation guidance aligned to this repo's current test structure
+- Skills are written as plain Markdown packages so they can be consumed by different agent systems rather than one vendor-specific runtime
 
 ## License
 
 MIT
-

package/dist/interact/classify.js

@@ -0,0 +1,35 @@
+/**
+ * Pure deterministic classifier. Applies rules in fixed order.
+ * Same inputs always produce the same output.
+ */
+export function classifyActionOutcome(input) {
+    const { uiChanged, expectedElementVisible, networkRequests, hasLogErrors } = input;
+    // Step 1 — UI signal is positive
+    if (uiChanged || expectedElementVisible === true) {
+        return { outcome: 'success', reasoning: expectedElementVisible === true ? 'expected element is visible' : 'UI changed after action' };
+    }
+    // Step 2 — UI did not change; network signal is required
+    if (networkRequests === null || networkRequests === undefined) {
+        return {
+            outcome: 'unknown',
+            reasoning: 'UI did not change; get_network_activity must be called before classification can proceed',
+            nextAction: 'call_get_network_activity'
+        };
+    }
+    // Step 3 — any network failure
+    const failedRequest = networkRequests.find((r) => r.status === 'failure' || r.status === 'retryable');
+    if (failedRequest) {
+        return { outcome: 'backend_failure', reasoning: `network request ${failedRequest.endpoint} returned ${failedRequest.status}` };
+    }
+    // Step 4 — no network requests at all
+    if (networkRequests.length === 0) {
+        const logNote = hasLogErrors ? ' (log errors present)' : '';
+        return { outcome: 'no_op', reasoning: `no UI change and no network activity${logNote}` };
+    }
+    // Step 5 — network requests exist and all succeeded
+    if (networkRequests.every((r) => r.status === 'success')) {
+        return { outcome: 'ui_failure', reasoning: 'network requests succeeded but UI did not change' };
+    }
+    // Step 6 — fallback
+    return { outcome: 'unknown', reasoning: 'signals are inconclusive' };
+}

package/dist/interact/index.js

@@ -1,9 +1,12 @@
+import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 export class ToolsInteract {
+    static _maxResolvedUiElements = 256;
+    static _resolvedUiElements = new Map();
     static _normalize(s) {
         if (s === null || s === undefined)
             return '';
@@ -14,6 +17,129 @@ export class ToolsInteract {
             return '';
         }
     }
+    static _normalizeBounds(bounds) {
+        if (!Array.isArray(bounds) || bounds.length < 4)
+            return null;
+        const normalized = bounds.slice(0, 4).map((value) => Number(value));
+        if (normalized.some((value) => Number.isNaN(value)))
+            return null;
+        return normalized;
+    }
+    static _isVisibleElement(el) {
+        const bounds = ToolsInteract._normalizeBounds(el.bounds);
+        return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1];
+    }
+    static _computeElementId(platform, deviceId, el, index) {
+        const identity = {
+            platform,
+            deviceId: deviceId || '',
+            text: ToolsInteract._normalize(el.text ?? el.label ?? el.value ?? ''),
+            resourceId: ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+            accessibilityId: ToolsInteract._normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? ''),
+            class: ToolsInteract._normalize(el.type ?? el.class ?? ''),
+            bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+            index
+        };
+        return `el_${createHash('sha1').update(JSON.stringify(identity)).digest('hex').slice(0, 24)}`;
+    }
+    static _buildResolvedElement(platform, deviceId, el, index) {
+        const bounds = ToolsInteract._normalizeBounds(el.bounds);
+        const elementId = ToolsInteract._computeElementId(platform, deviceId, el, index);
+        ToolsInteract._rememberResolvedElement(elementId, {
+            elementId,
+            platform,
+            deviceId,
+            bounds,
+            index
+        });
+        return {
+            text: el.text ?? null,
+            resource_id: el.resourceId ?? el.resourceID ?? el.id ?? null,
+            accessibility_id: el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? null,
+            class: el.type ?? el.class ?? null,
+            bounds,
+            index,
+            elementId
+        };
+    }
+    static _rememberResolvedElement(elementId, context) {
+        if (ToolsInteract._resolvedUiElements.has(elementId)) {
+            ToolsInteract._resolvedUiElements.delete(elementId);
+        }
+        ToolsInteract._resolvedUiElements.set(elementId, context);
+        while (ToolsInteract._resolvedUiElements.size > ToolsInteract._maxResolvedUiElements) {
+            const oldestElementId = ToolsInteract._resolvedUiElements.keys().next().value;
+            if (!oldestElementId)
+                break;
+            ToolsInteract._resolvedUiElements.delete(oldestElementId);
+        }
+    }
+    static _resetResolvedUiElementsForTests() {
+        ToolsInteract._resolvedUiElements.clear();
+    }
+    static _findCurrentResolvedElement(elements, platform, deviceId, resolved) {
+        const indexedCandidate = elements[resolved.index];
+        if (indexedCandidate && ToolsInteract._computeElementId(platform, deviceId, indexedCandidate, resolved.index) === resolved.elementId) {
+            return { el: indexedCandidate, index: resolved.index };
+        }
+        return null;
+    }
+    static _resolveActionableAncestor(elements, chosen) {
+        if (!chosen)
+            return null;
+        if (chosen.el.clickable || chosen.el.focusable)
+            return chosen;
+        let current = chosen;
+        let safety = 0;
+        while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable) && current.el.parentId !== undefined && current.el.parentId !== null) {
+            const parentId = current.el.parentId;
+            let parentIndex = null;
+            if (typeof parentId === 'number')
+                parentIndex = parentId;
+            else if (typeof parentId === 'string' && /^\d+$/.test(parentId))
+                parentIndex = Number(parentId);
+            if (parentIndex !== null && elements[parentIndex]) {
+                current = { el: elements[parentIndex], idx: parentIndex };
+                if (current.el.clickable || current.el.focusable)
+                    return current;
+            }
+            else if (typeof parentId === 'string') {
+                const foundIndex = elements.findIndex((el) => el.resourceId === parentId || el.id === parentId);
+                if (foundIndex === -1)
+                    break;
+                current = { el: elements[foundIndex], idx: foundIndex };
+                if (current.el.clickable || current.el.focusable)
+                    return current;
+            }
+            else {
+                break;
+            }
+            safety++;
+        }
+        const childBounds = ToolsInteract._normalizeBounds(chosen.el.bounds);
+        if (!childBounds)
+            return null;
+        const [cl, ct, cr, cb] = childBounds;
+        let best = null;
+        let bestArea = Infinity;
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (!el || !(el.clickable || el.focusable))
+                continue;
+            const bounds = ToolsInteract._normalizeBounds(el.bounds);
+            if (!bounds)
+                continue;
+            const [pl, pt, pr, pb] = bounds;
+            if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+                const area = (pr - pl) * (pb - pt);
+                if (area < bestArea) {
+                    bestArea = area;
+                    best = { el, idx: i };
+                }
+            }
+        }
+        return best;
+    }
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
         const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
@@ -24,6 +150,90 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.tap(x, y, resolved.id);
     }
+    static async tapElementHandler({ elementId }) {
+        const action = 'tap';
+        const resolved = ToolsInteract._resolvedUiElements.get(elementId);
+        if (!resolved) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'element_not_found',
+                    message: 'Element ID was not found in the current UI context'
+                }
+            };
+        }
+        const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
+        const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform;
+        const treeDeviceId = tree?.device?.id || resolved.deviceId;
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
+        if (!currentMatch) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'element_not_found',
+                    message: 'Element ID is not present in the current UI context'
+                }
+            };
+        }
+        if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'element_not_visible',
+                    message: 'Element is not visible'
+                }
+            };
+        }
+        if (currentMatch.el.enabled === false) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'element_not_enabled',
+                    message: 'Element is not enabled'
+                }
+            };
+        }
+        const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds;
+        if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'element_not_visible',
+                    message: 'Element does not have valid visible bounds'
+                }
+            };
+        }
+        const x = Math.floor((bounds[0] + bounds[2]) / 2);
+        const y = Math.floor((bounds[1] + bounds[3]) / 2);
+        const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId });
+        if (!tapResult.success) {
+            return {
+                success: false,
+                elementId,
+                action,
+                error: {
+                    code: 'tap_failed',
+                    message: tapResult.error || 'Tap failed'
+                }
+            };
+        }
+        return {
+            success: true,
+            elementId,
+            action
+        };
+    }
     static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.swipe(x1, y1, x2, y2, duration, resolved.id);
@@ -333,6 +543,7 @@ export class ToolsInteract {
                             chosen = null;
                         }
                         let conditionMet = false;
+                        let matchedElement = chosen;
                         if (condition === 'exists') {
                             // when an index is specified, existence requires that specific index be present
                             conditionMet = (pickIndex !== undefined) ? (chosen !== null) : (matchedCount >= 1);
@@ -351,11 +562,12 @@ export class ToolsInteract {
                                 conditionMet = false;
                         }
                         else if (condition === 'clickable') {
-                            if (chosen) {
-                                const b = chosen.el.bounds;
-                                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
-                                const enabled = !!chosen.el.enabled;
-                                const clickable = !!chosen.el.clickable || !!chosen.el._interactable;
+                            matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
+                            if (matchedElement) {
+                                const b = matchedElement.el.bounds;
+                                const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
+                                const enabled = !!matchedElement.el.enabled;
+                                const clickable = !!matchedElement.el.clickable || !!matchedElement.el._interactable || !!matchedElement.el.focusable;
                                 conditionMet = visibleFlag && enabled && clickable;
                             }
                             else
@@ -365,14 +577,9 @@ export class ToolsInteract {
                             const now = Date.now();
                             const latency_ms = now - overallStart;
                             // Build element output per spec
-                            const outEl = chosen ? {
-                                text: chosen.el.text ?? null,
-                                resource_id: chosen.el.resourceId ?? chosen.el.resourceID ?? chosen.el.id ?? null,
-                                accessibility_id: chosen.el.contentDescription ?? chosen.el.contentDesc ?? chosen.el.accessibilityLabel ?? chosen.el.label ?? null,
-                                class: chosen.el.type ?? chosen.el.class ?? null,
-                                bounds: Array.isArray(chosen.el.bounds) && chosen.el.bounds.length >= 4 ? chosen.el.bounds : null,
-                                index: chosen.idx
-                            } : null;
+                            const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
+                            const resolvedDeviceId = tree?.device?.id || deviceId;
+                            const outEl = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
                             return {
                                 status: 'success',
                                 matched: matchedCount,

package/dist/network/index.js

@@ -0,0 +1,232 @@
+import { execAdb, parseLogLine } from '../utils/android/utils.js';
+import { execCommand } from '../utils/ios/utils.js';
+// ─── Module state ─────────────────────────────────────────────────────────────
+// lastActionTimestamp: set when an action tool fires (tap, swipe, etc.)
+// lastConsumedTimestamp: advanced after each get_network_activity call to prevent duplicates
+let lastActionTimestamp = 0;
+let lastConsumedTimestamp = 0;
+export function notifyActionStart() {
+    lastActionTimestamp = Date.now();
+    lastConsumedTimestamp = 0;
+}
+/** Exposed for unit tests only. */
+export function _setTimestampsForTests(actionTs, consumedTs) {
+    lastActionTimestamp = actionTs;
+    lastConsumedTimestamp = consumedTs;
+}
+// ─── Parsing constants ────────────────────────────────────────────────────────
+const URL_RE = /https?:\/\/[^\s"'\]\)><]+/;
+const PATH_RE = /\/[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)+/;
+const METHOD_RE = /\b(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/;
+const NETWORK_ERROR_PATTERNS = [
+    { re: /timed?\s*out|timeout/i, code: 'timeout' },
+    { re: /dns|name[\s_]resolution|host\s*not\s*found|nodename/i, code: 'dns_error' },
+    { re: /\btls\b|\bssl\b|certificate|handshake/i, code: 'tls_error' },
+    { re: /connection\s*refused/i, code: 'connection_refused' },
+    { re: /connection\s*reset|reset\s*by\s*peer/i, code: 'connection_reset' },
+];
+const BACKGROUND_TOKENS = ['/analytics', '/metrics', '/tracking', '/log', '/events', '/telemetry', '/ping', '/beacon'];
+const BACKGROUND_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.css', '.js', '.svg', '.ico', '.woff', '.ttf'];
+const FILESYSTEM_PREFIXES = ['/data/', '/system/', '/apex/', '/proc/', '/dev/', '/vendor/', '/product/', '/storage/', '/sdcard/', '/mnt/', '/odm/', '/cache/', '/metadata/', '/acct/', '/sys/'];
+const FILESYSTEM_EXTENSIONS = ['.apk', '.apex', '.odex', '.vdex', '.dex', '.so', '.jar', '.bin', '.img', '.db', '.sqlite', '.c', '.cc', '.cpp', '.cxx', '.h', '.hpp', '.m', '.mm', '.kt', '.java', '.swift'];
+// ─── Parsing helpers ─────────────────────────────────────────────────────────
+function extractUrl(text) {
+    const m = text.match(URL_RE);
+    return m ? m[0] : null;
+}
+function isPlausibleEndpointPath(path) {
+    const lower = path.toLowerCase();
+    if (!lower.startsWith('/'))
+        return false;
+    if (FILESYSTEM_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+        return false;
+    if (FILESYSTEM_EXTENSIONS.some((ext) => lower.endsWith(ext)))
+        return false;
+    return true;
+}
+function extractPath(text) {
+    const m = text.match(PATH_RE);
+    if (!m)
+        return null;
+    return isPlausibleEndpointPath(m[0]) ? m[0] : null;
+}
+function toStatusCode(value) {
+    if (!value)
+        return null;
+    const code = Number(value);
+    return code >= 100 && code <= 599 ? code : null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function extractStatusCode(text, url, path, method) {
+    const directHttpMatch = text.match(/\bHTTP\/\d(?:\.\d)?\s+([1-5]\d{2})\b/i) || text.match(/\bHTTP\s+([1-5]\d{2})\b/i);
+    if (directHttpMatch)
+        return toStatusCode(directHttpMatch[1]);
+    const endpointToken = url || path;
+    const hasEndpointContext = endpointToken !== null;
+    if (!hasEndpointContext && method === null)
+        return null;
+    const labeledMatch = text.match(/\b(?:status(?:\s*code)?|response(?:\s*code)?)\s*[:=]?\s*([1-5]\d{2})\b/i);
+    if (labeledMatch && hasEndpointContext)
+        return toStatusCode(labeledMatch[1]);
+    if (endpointToken) {
+        const escapedEndpoint = escapeRegExp(endpointToken);
+        const endpointThenCode = new RegExp(`${escapedEndpoint}[^\\n]*?\\b([1-5]\\d{2})\\b`, 'i');
+        const codeThenEndpoint = new RegExp(`\\b([1-5]\\d{2})\\b[^\\n]*?${escapedEndpoint}`, 'i');
+        const contextualMatch = text.match(endpointThenCode) || text.match(codeThenEndpoint);
+        if (contextualMatch)
+            return toStatusCode(contextualMatch[1]);
+    }
+    if (method !== null && path !== null) {
+        const methodPathCodeMatch = text.match(/\b(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b[^\n]*?\b([1-5]\d{2})\b/i);
+        if (methodPathCodeMatch)
+            return toStatusCode(methodPathCodeMatch[1]);
+    }
+    return null;
+}
+function extractMethod(text) {
+    const m = text.match(METHOD_RE);
+    return m ? m[1] : null;
+}
+function detectNetworkError(text) {
+    for (const { re, code } of NETWORK_ERROR_PATTERNS) {
+        if (re.test(text))
+            return code;
+    }
+    return null;
+}
+export function normalizeEndpoint(raw) {
+    try {
+        const u = new URL(raw.startsWith('/') ? `https://x${raw}` : raw);
+        const p = u.pathname.toLowerCase().replace(/\/+$/, '');
+        return p || '/';
+    }
+    catch {
+        return raw.toLowerCase().replace(/\?.*$/, '').replace(/\/+$/, '') || '/';
+    }
+}
+export function classifyStatus(statusCode, networkError) {
+    if (networkError !== null)
+        return 'retryable';
+    if (statusCode === null)
+        return 'success'; // request detected, no failure signal
+    if (statusCode >= 200 && statusCode <= 299)
+        return 'success';
+    if (statusCode >= 400 && statusCode <= 499)
+        return 'failure';
+    return 'retryable'; // 5xx, 1xx, 3xx
+}
+function meetsEmissionCriteria(url, path, statusCode, method) {
+    if (url !== null)
+        return true; // condition 1: full http/https URL
+    if (statusCode !== null)
+        return true; // condition 2: valid HTTP status code
+    if (method !== null && path !== null)
+        return true; // condition 3: method + path
+    return false;
+}
+function classifyEventType(endpoint) {
+    const lower = endpoint.toLowerCase();
+    if (BACKGROUND_TOKENS.some(t => lower.includes(t)))
+        return 'background';
+    if (BACKGROUND_EXTENSIONS.some(e => lower.endsWith(e)))
+        return 'background';
+    return 'primary';
+}
+function filterToSignificantEvents(events) {
+    if (events.length === 0)
+        return events;
+    const hasPrimary = events.some(e => classifyEventType(e.endpoint) === 'primary');
+    return hasPrimary ? events.filter(e => classifyEventType(e.endpoint) === 'primary') : events;
+}
+/** Exported for unit testing. */
+export function parseMessageToEvent(message) {
+    const url = extractUrl(message);
+    const path = url ? null : extractPath(message);
+    const method = extractMethod(message);
+    const statusCode = extractStatusCode(message, url, path, method);
+    const networkError = detectNetworkError(message);
+    if (!meetsEmissionCriteria(url, path, statusCode, method))
+        return null;
+    const rawEndpoint = url || path || 'unknown';
+    return {
+        endpoint: normalizeEndpoint(rawEndpoint),
+        method: method || 'unknown',
+        statusCode,
+        networkError,
+        status: classifyStatus(statusCode, networkError),
+        durationMs: 0
+    };
+}
+// ─── Android ─────────────────────────────────────────────────────────────────
+async function getAndroidEvents(sinceMs, deviceId) {
+    try {
+        const stdout = await execAdb(['logcat', '-d', '-v', 'threadtime', '*:V', '-t', '2000'], deviceId);
+        const lines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : [];
+        const events = [];
+        for (const line of lines) {
+            const parsed = parseLogLine(line);
+            if (parsed._iso) {
+                const ts = new Date(parsed._iso).getTime();
+                if (ts > 0 && ts <= sinceMs)
+                    continue;
+            }
+            const event = parseMessageToEvent(parsed.message || line);
+            if (event)
+                events.push(event);
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+// ─── iOS ─────────────────────────────────────────────────────────────────────
+async function getIOSEvents(sinceMs, deviceId = 'booted') {
+    try {
+        const lookbackSeconds = Math.max(15, Math.ceil((Date.now() - sinceMs) / 1000) + 5);
+        const args = [
+            'simctl', 'spawn', deviceId, 'log', 'show',
+            '--last', `${lookbackSeconds}s`,
+            '--style', 'syslog',
+            '--predicate', 'eventMessage contains "http" OR eventMessage contains "URLSession" OR eventMessage contains "Task <" OR eventMessage contains "HTTP/"'
+        ];
+        const result = await execCommand(args, deviceId);
+        const lines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : [];
+        const events = [];
+        for (const line of lines) {
+            const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})/);
+            if (tsMatch) {
+                const ts = new Date(tsMatch[1]).getTime();
+                if (ts > 0 && ts <= sinceMs)
+                    continue;
+            }
+            const event = parseMessageToEvent(line);
+            if (event)
+                events.push(event);
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export class ToolsNetwork {
+    static notifyActionStart() {
+        notifyActionStart();
+    }
+    static async getNetworkActivity(params) {
+        const { platform, deviceId } = params;
+        const sinceMs = lastConsumedTimestamp > lastActionTimestamp
+            ? lastConsumedTimestamp
+            : lastActionTimestamp > 0 ? lastActionTimestamp : Date.now() - 30000;
+        const raw = platform === 'android'
+            ? await getAndroidEvents(sinceMs, deviceId)
+            : await getIOSEvents(sinceMs, deviceId);
+        const requests = filterToSignificantEvents(raw);
+        lastConsumedTimestamp = Date.now();
+        return { requests, count: requests.length };
+    }
+}