pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/input-modes/lookups.js

@@ -1,236 +1,38 @@
-import { readFile, readdir } from "node:fs/promises";
-import { extname, join } from "node:path";
-import { isRecord } from "../parsing.js";
-import { redactInvocationArgs, redactSensitiveText } from "../runtime.js";
-import { getBatchResultItems, validateLookupMaxWorkspaceFiles } from "./shared.js";
-import { SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_IGNORED_DIRECTORIES, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_WORKSPACE_EXTENSIONS, } from "./types.js";
-export function compileAgentBrowserSourceLookup(input) {
-    if (!isRecord(input)) {
-        return { error: "sourceLookup must be an object." };
-    }
-    const selector = input.selector;
-    const reactFiberId = input.reactFiberId;
-    const componentName = input.componentName;
-    if (selector !== undefined && (typeof selector !== "string" || selector.trim().length === 0)) {
-        return { error: "sourceLookup.selector must be a non-empty string when provided." };
-    }
-    if (reactFiberId !== undefined && (typeof reactFiberId !== "string" || reactFiberId.trim().length === 0)) {
-        return { error: "sourceLookup.reactFiberId must be a non-empty string when provided." };
-    }
-    if (componentName !== undefined && (typeof componentName !== "string" || componentName.trim().length === 0)) {
-        return { error: "sourceLookup.componentName must be a non-empty string when provided." };
-    }
-    if (selector === undefined && reactFiberId === undefined && componentName === undefined) {
-        return { error: "sourceLookup requires selector, reactFiberId, or componentName." };
-    }
-    if (input.includeDomHints !== undefined && typeof input.includeDomHints !== "boolean") {
-        return { error: "sourceLookup.includeDomHints must be a boolean when provided." };
-    }
-    const rawMaxWorkspaceFiles = input.maxWorkspaceFiles;
-    if (rawMaxWorkspaceFiles !== undefined && (typeof rawMaxWorkspaceFiles !== "number" || !Number.isInteger(rawMaxWorkspaceFiles) || rawMaxWorkspaceFiles <= 0)) {
-        return { error: "sourceLookup.maxWorkspaceFiles must be a positive integer when provided." };
-    }
-    if (typeof rawMaxWorkspaceFiles === "number" && rawMaxWorkspaceFiles > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
-        return { error: `sourceLookup.maxWorkspaceFiles must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
-    }
-    const includeDomHints = input.includeDomHints !== false;
-    const maxWorkspaceFiles = rawMaxWorkspaceFiles ?? SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES;
-    const steps = [];
-    if (typeof selector === "string") {
-        steps.push({ action: "dom", args: ["is", "visible", selector] });
-        if (includeDomHints) {
-            steps.push({ action: "dom", args: ["get", "html", selector] });
-        }
-    }
-    if (typeof reactFiberId === "string") {
-        steps.push({ action: "react", args: ["react", "inspect", reactFiberId] });
-    }
-    if (typeof componentName === "string") {
-        steps.push({ action: "react", args: ["react", "tree"] });
-    }
-    return {
-        compiled: {
-            args: ["batch"],
-            query: { componentName, includeDomHints, maxWorkspaceFiles, reactFiberId, selector },
-            stdin: JSON.stringify(steps.map((step) => step.args)),
-            steps,
-        },
-    };
-}
-function extractStringField(value, names) {
-    for (const name of names) {
-        const field = value[name];
-        if (typeof field === "string" && field.trim().length > 0)
-            return field;
-    }
-    return undefined;
-}
-function extractNumberField(value, names) {
-    for (const name of names) {
-        const field = value[name];
-        if (typeof field === "number" && Number.isFinite(field))
-            return field;
-        if (typeof field === "string" && /^\d+$/.test(field))
-            return Number(field);
-    }
-    return undefined;
-}
-function candidateKey(candidate) {
-    return [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.column ?? "", candidate.componentName ?? ""].join(":");
-}
-function addSourceLookupCandidate(candidates, candidate) {
-    if (!candidates.some((existing) => candidateKey(existing) === candidateKey(candidate))) {
-        candidates.push(candidate);
-    }
-}
-function collectSourceCandidatesFromValue(value, source, candidates, evidence, depth = 0) {
-    if (depth > 6 || value === undefined || value === null)
-        return;
-    if (typeof value === "string") {
-        const sourcePattern = /([A-Za-z0-9_./@-]+\.(?:tsx|jsx|ts|js))(?:[:#](\d+))?(?:[:#](\d+))?/g;
-        for (const match of value.matchAll(sourcePattern)) {
-            addSourceLookupCandidate(candidates, {
-                column: match[3] ? Number(match[3]) : undefined,
-                confidence: source === "react-inspect" ? "high" : "medium",
-                evidence,
-                file: match[1],
-                line: match[2] ? Number(match[2]) : undefined,
-                source,
-            });
-        }
-        return;
-    }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectSourceCandidatesFromValue(item, source, candidates, evidence, depth + 1);
-        return;
-    }
-    if (!isRecord(value))
-        return;
-    const file = extractStringField(value, ["file", "fileName", "filename", "filePath", "path", "source", "url"]);
-    if (file && /\.(?:tsx|jsx|ts|js)(?:$|[:?#])/.test(file)) {
-        addSourceLookupCandidate(candidates, {
-            column: extractNumberField(value, ["column", "columnNumber", "col"]),
-            confidence: source === "react-inspect" ? "high" : "medium",
-            evidence,
-            file,
-            line: extractNumberField(value, ["line", "lineNumber"]),
-            source,
-        });
-    }
-    for (const nested of Object.values(value)) {
-        collectSourceCandidatesFromValue(nested, source, candidates, evidence, depth + 1);
-    }
-}
-function getHtmlAttributeValue(html, name) {
-    const pattern = new RegExp(`${name}=["']([^"']+)["']`, "i");
-    return pattern.exec(html)?.[1];
-}
-function collectDomSourceCandidates(html, candidates) {
-    if (typeof html !== "string")
-        return;
-    const file = getHtmlAttributeValue(html, "(?:data-source-file|data-file|data-component-file|data-source)");
-    if (file && /\.(?:tsx|jsx|ts|js)$/.test(file)) {
-        const line = getHtmlAttributeValue(html, "(?:data-source-line|data-line)");
-        const column = getHtmlAttributeValue(html, "(?:data-source-column|data-column)");
-        addSourceLookupCandidate(candidates, {
-            column: column && /^\d+$/.test(column) ? Number(column) : undefined,
-            confidence: "medium",
-            evidence: ["selector HTML contained source-like data attributes"],
-            file,
-            line: line && /^\d+$/.test(line) ? Number(line) : undefined,
-            source: "dom-attribute",
-        });
-    }
-    collectSourceCandidatesFromValue(html, "dom-attribute", candidates, ["selector HTML contained source-like text"]);
-}
-async function walkWorkspaceSourceFiles(root, maxFiles) {
-    const files = [];
-    async function visit(directory) {
-        if (files.length >= maxFiles)
-            return;
-        let entries;
-        try {
-            entries = await readdir(directory, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (files.length >= maxFiles)
-                return;
-            const path = join(directory, entry.name);
-            if (entry.isDirectory()) {
-                if (!SOURCE_LOOKUP_IGNORED_DIRECTORIES.has(entry.name))
-                    await visit(path);
+export { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, } from "./lookup-plan.js";
+export { redactNetworkSourceLookupAnalysis, redactNetworkSourceLookupArgs, redactNetworkSourceLookupSurface, redactNetworkSourceLookupUrl, } from "./lookup-redaction.js";
+function sourceStatus(candidateCount, unsupported) {
+    if (candidateCount > 0) {
+        return "candidates-found";
+    }
+    return unsupported ? "unsupported" : "no-candidates";
+}
+function sourceSummary(status, candidateCount, electronWorkspace) {
+    switch (status) {
+        case "candidates-found":
+            return `Source lookup found ${candidateCount} candidate location(s).`;
+        case "unsupported":
+            return "Source lookup could not inspect React metadata in this session.";
+        case "no-candidates":
+            if (electronWorkspace !== undefined) {
+                return `Source lookup found no candidate locations. The workspace scan was limited to ${electronWorkspace}; packaged Electron app code may live outside that cwd in app resources or app.asar.`;
             }
-            else if (entry.isFile() && SOURCE_LOOKUP_WORKSPACE_EXTENSIONS.has(extname(entry.name))) {
-                files.push(path);
-            }
-        }
-    }
-    await visit(root);
-    return files;
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-async function collectWorkspaceComponentCandidates(query, cwd, candidates, limitations) {
-    if (!query.componentName)
-        return;
-    const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
-    if (files.length >= query.maxWorkspaceFiles) {
-        limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
-    }
-    const componentPattern = new RegExp(`(?:function|class)\\s+${escapeRegExp(query.componentName)}\\b|(?:const|let|var)\\s+${escapeRegExp(query.componentName)}\\s*=|export\\s+default\\s+function\\s+${escapeRegExp(query.componentName)}\\b`);
-    for (const file of files) {
-        let text;
-        try {
-            text = await readFile(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        const match = componentPattern.exec(text);
-        if (!match)
-            continue;
-        const line = text.slice(0, match.index).split("\n").length;
-        addSourceLookupCandidate(candidates, {
-            componentName: query.componentName,
-            confidence: "low",
-            evidence: [`local workspace contains a matching ${query.componentName} declaration`],
-            file,
-            line,
-            source: "workspace-search",
-        });
-        if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10)
-            break;
+            return "Source lookup found no candidate locations.";
     }
 }
 export async function analyzeSourceLookupResults(data, compiled, cwd, context) {
-    const items = getBatchResultItems(data);
-    const candidates = [];
+    const { distinctSourceCandidates, observeSourceCandidates } = await import("./lookup-source-evidence.js");
+    const { scanWorkspaceComponent } = await import("./lookup-workspace.js");
+    const observed = observeSourceCandidates(data);
+    const workspace = await scanWorkspaceComponent(compiled.query, cwd);
+    const candidates = distinctSourceCandidates([...observed.candidates, ...workspace.candidates]);
+    const status = sourceStatus(candidates.length, observed.unsupported);
+    const electronContext = status === "no-candidates" ? context?.electronContext : undefined;
+    const workspaceRoot = context?.workspaceRoot ?? cwd;
     const limitations = [
         "Experimental lookup only reports candidates with evidence; it cannot guarantee a DOM node maps to one source file.",
         "React source hints require the page to be opened with --enable react-devtools and source information from the app build.",
+        ...workspace.limitations,
     ];
-    let unsupported = false;
-    for (const item of items) {
-        const command = Array.isArray(item.command) ? item.command : [];
-        const result = isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
-        if (item.success === false && command[0] === "react")
-            unsupported = true;
-        if (command[0] === "react" && command[1] === "inspect") {
-            collectSourceCandidatesFromValue(result, "react-inspect", candidates, ["react inspect returned source-like metadata"]);
-        }
-        if (command[0] === "get" && command[1] === "html") {
-            collectDomSourceCandidates(result, candidates);
-        }
-    }
-    await collectWorkspaceComponentCandidates(compiled.query, cwd, candidates, limitations);
-    const status = candidates.length > 0 ? "candidates-found" : unsupported ? "unsupported" : "no-candidates";
-    const electronContext = status === "no-candidates" ? context?.electronContext : undefined;
-    const workspaceRoot = context?.workspaceRoot ?? cwd;
     if (electronContext) {
         limitations.push(`Workspace source scan is limited to the captured execution directory: ${workspaceRoot}.`, "Packaged Electron app code may live inside installed app resources or app.asar outside the workspace; the wrapper does not unpack asar files or scan app bundle resources.");
     }
@@ -239,200 +41,43 @@ export async function analyzeSourceLookupResults(data, compiled, cwd, context) {
         electronContext,
         limitations,
         status,
-        summary: candidates.length > 0
-            ? `Source lookup found ${candidates.length} candidate location(s).`
-            : unsupported
-                ? "Source lookup could not inspect React metadata in this session."
-                : electronContext
-                    ? `Source lookup found no candidate locations. The workspace scan was limited to ${workspaceRoot}; packaged Electron app code may live outside that cwd in app resources or app.asar.`
-                    : "Source lookup found no candidate locations.",
+        summary: sourceSummary(status, candidates.length, electronContext ? workspaceRoot : undefined),
         workspaceRoot: electronContext ? workspaceRoot : undefined,
     };
 }
-export function compileAgentBrowserNetworkSourceLookup(input) {
-    if (!isRecord(input))
-        return { error: "networkSourceLookup must be an object." };
-    const filter = input.filter;
-    const requestId = input.requestId;
-    const namespace = input.namespace;
-    const session = input.session;
-    const url = input.url;
-    if (filter !== undefined && (typeof filter !== "string" || filter.trim().length === 0))
-        return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
-    if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0))
-        return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
-    if (namespace !== undefined && (typeof namespace !== "string" || (namespace !== "" && namespace.trim().length === 0)))
-        return { error: "networkSourceLookup.namespace must be a non-empty string or the empty default namespace when provided." };
-    if (session !== undefined && (typeof session !== "string" || session.trim().length === 0))
-        return { error: "networkSourceLookup.session must be a non-empty string when provided." };
-    if (url !== undefined && (typeof url !== "string" || url.trim().length === 0))
-        return { error: "networkSourceLookup.url must be a non-empty string when provided." };
-    if (filter === undefined && requestId === undefined && url === undefined)
-        return { error: "networkSourceLookup requires requestId, filter, or url." };
-    const maxWorkspaceFiles = validateLookupMaxWorkspaceFiles(input.maxWorkspaceFiles, "networkSourceLookup.maxWorkspaceFiles");
-    if (maxWorkspaceFiles.error)
-        return { error: maxWorkspaceFiles.error };
-    const steps = [];
-    if (typeof requestId === "string") {
-        steps.push({ action: "network", args: ["network", "request", requestId] });
-    }
-    const effectiveFilter = typeof filter === "string" ? filter : typeof url === "string" ? url : undefined;
-    if (effectiveFilter) {
-        steps.push({ action: "network", args: ["network", "requests", "--filter", effectiveFilter] });
-    }
-    const args = [...(typeof namespace === "string" ? ["--namespace", namespace] : []), ...(typeof session === "string" ? ["--session", session] : []), "batch"];
-    return { compiled: { args, query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value, namespace, requestId, session, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
-}
-function getResultPayload(item) {
-    return isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
-}
-function networkRequestMatchesQuery(url, queryText) {
-    return queryText === undefined || url === undefined || url.includes(queryText) || queryText.includes(url);
-}
-function isFailedNetworkRecord(request) {
-    const status = typeof request.status === "number" ? request.status : undefined;
-    const error = typeof request.error === "string" ? request.error : undefined;
-    return request.failed === true || error !== undefined || (status !== undefined && status >= 400);
-}
-function getFailedNetworkRequests(data, queryText) {
-    const failed = [];
-    for (const item of getBatchResultItems(data)) {
-        const payload = getResultPayload(item);
-        const requests = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : Array.isArray(payload) ? payload : isRecord(payload) ? [payload] : [];
-        for (const request of requests) {
-            if (!isRecord(request))
-                continue;
-            const url = typeof request.url === "string" ? request.url : undefined;
-            if (!networkRequestMatchesQuery(url, queryText) || !isFailedNetworkRecord(request))
-                continue;
-            failed.push({
-                error: typeof request.error === "string" ? request.error : undefined,
-                method: typeof request.method === "string" ? request.method : undefined,
-                requestId: typeof request.id === "string" ? request.id : typeof request.requestId === "string" ? request.requestId : undefined,
-                status: typeof request.status === "number" ? request.status : undefined,
-                url,
-            });
-        }
-    }
-    return failed;
-}
-function addNetworkCandidate(candidates, candidate) {
-    const key = [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.requestUrl ?? ""].join(":");
-    if (!candidates.some((existing) => [existing.source, existing.file ?? "", existing.line ?? "", existing.requestUrl ?? ""].join(":") === key))
-        candidates.push(candidate);
-}
-function collectInitiatorCandidates(data, failedRequests, candidates) {
-    const failedRequestIds = new Set(failedRequests.map((request) => request.requestId).filter((value) => value !== undefined));
-    const failedRequestUrls = new Set(failedRequests.map((request) => request.url).filter((value) => value !== undefined));
-    for (const item of getBatchResultItems(data)) {
-        const payload = getResultPayload(item);
-        const requestValues = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : [payload];
-        for (const value of requestValues) {
-            if (!isRecord(value))
-                continue;
-            const requestUrl = typeof value.url === "string" ? value.url : undefined;
-            const requestId = typeof value.id === "string" ? value.id : typeof value.requestId === "string" ? value.requestId : undefined;
-            const correlatesWithFailedRequest = (requestId !== undefined && failedRequestIds.has(requestId)) || (requestUrl !== undefined && failedRequestUrls.has(requestUrl));
-            if (!correlatesWithFailedRequest && !isFailedNetworkRecord(value))
-                continue;
-            for (const field of [value.initiator, value.stack, value.source, value.trace]) {
-                const localCandidates = [];
-                collectSourceCandidatesFromValue(field, "dom-attribute", localCandidates, ["failed network request included source-like initiator metadata"]);
-                for (const candidate of localCandidates) {
-                    addNetworkCandidate(candidates, { confidence: "medium", evidence: candidate.evidence, file: candidate.file, line: candidate.line, requestUrl, source: "initiator" });
-                }
-            }
-        }
-    }
-}
-async function collectWorkspaceRequestCandidates(query, failedRequests, cwd, candidates, limitations) {
-    const needles = [...new Set([query.url, query.filter, ...failedRequests.map((request) => request.url)].filter((value) => typeof value === "string" && value.length > 0).flatMap((value) => {
-            try {
-                const parsed = new URL(value);
-                return [value, parsed.pathname].filter((item) => item && item !== "/");
-            }
-            catch {
-                return [value];
-            }
-        }))].slice(0, 8);
-    if (needles.length === 0)
-        return;
-    const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
-    if (files.length >= query.maxWorkspaceFiles)
-        limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
-    for (const file of files) {
-        let text;
-        try {
-            text = await readFile(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        for (const needle of needles) {
-            const index = text.indexOf(needle);
-            if (index === -1)
-                continue;
-            addNetworkCandidate(candidates, { confidence: "low", evidence: [`local workspace contains request URL literal ${needle}`], file, line: text.slice(0, index).split("\n").length, requestUrl: needle, source: "workspace-search" });
-            if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10)
-                return;
-        }
+function networkStatus(failedCount, candidateCount) {
+    if (failedCount === 0) {
+        return "no-failed-requests";
     }
+    return candidateCount > 0 ? "failed-requests-found" : "no-candidates";
 }
-export function redactNetworkSourceLookupUrl(value) {
-    if (!value)
-        return value;
-    try {
-        const isRelative = value.startsWith("/");
-        const url = new URL(value, isRelative ? "https://redacted.invalid" : undefined);
-        url.username = url.username ? "[REDACTED]" : "";
-        url.password = url.password ? "[REDACTED]" : "";
-        for (const key of [...url.searchParams.keys()]) {
-            url.searchParams.set(key, "[REDACTED]");
-        }
-        if (/(?:token|secret|password|passwd|pwd|key|auth|session|jwt|credential)/i.test(url.hash)) {
-            url.hash = "#[REDACTED]";
-        }
-        return isRelative ? `${url.pathname}${url.search}${url.hash}` : url.toString();
+function networkSummary(status, failedCount, candidateCount) {
+    switch (status) {
+        case "no-failed-requests":
+            return "Network source lookup found no failed requests.";
+        case "failed-requests-found":
+            return `Network source lookup found ${failedCount} failed request(s) and ${candidateCount} candidate source hint(s).`;
+        case "no-candidates":
+            return `Network source lookup found ${failedCount} failed request(s) but no source candidates.`;
     }
-    catch {
-        return redactSensitiveText(value
-            .replace(/([a-z][a-z0-9+.-]*:\/\/)\S+:\S+@/gi, "$1[REDACTED]@")
-            .replace(/([?&][^=]+)=([^&#\s"'\]]+)/g, "$1=[REDACTED]"));
-    }
-}
-export function redactNetworkSourceLookupArgs(args) {
-    return redactInvocationArgs(args).map((arg) => redactNetworkSourceLookupUrl(arg) ?? arg);
-}
-export function redactNetworkSourceLookupSurface(value) {
-    if (typeof value === "string")
-        return redactNetworkSourceLookupUrl(value) ?? value;
-    if (Array.isArray(value))
-        return value.map((item) => redactNetworkSourceLookupSurface(item));
-    if (!isRecord(value))
-        return value;
-    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactNetworkSourceLookupSurface(item)]));
-}
-export function redactNetworkSourceLookupAnalysis(analysis) {
-    return {
-        ...analysis,
-        candidates: analysis.candidates.map((candidate) => ({
-            ...candidate,
-            evidence: candidate.evidence.map((item) => redactNetworkSourceLookupUrl(item) ?? redactSensitiveText(item)),
-            file: redactNetworkSourceLookupUrl(candidate.file),
-            requestUrl: redactNetworkSourceLookupUrl(candidate.requestUrl),
-        })),
-        failedRequests: analysis.failedRequests.map((request) => ({ ...request, error: redactNetworkSourceLookupUrl(request.error), url: redactNetworkSourceLookupUrl(request.url) })),
-    };
 }
 export async function analyzeNetworkSourceLookupResults(data, compiled, cwd) {
-    const limitations = [
-        "Experimental network source hints report candidates only; failed requests can be triggered indirectly by frameworks, caches, service workers, or third-party scripts.",
-        "Initiator/source-map metadata is upstream/browser-build dependent and may be absent.",
-    ];
+    const { distinctNetworkCandidates, getFailedNetworkRequests, observeInitiatorCandidates } = await import("./lookup-network-evidence.js");
+    const { scanWorkspaceRequests } = await import("./lookup-workspace.js");
     const failedRequests = getFailedNetworkRequests(data, compiled.query.url ?? compiled.query.filter);
-    const candidates = [];
-    collectInitiatorCandidates(data, failedRequests, candidates);
-    await collectWorkspaceRequestCandidates(compiled.query, failedRequests, cwd, candidates, limitations);
-    const status = failedRequests.length === 0 ? "no-failed-requests" : candidates.length > 0 ? "failed-requests-found" : "no-candidates";
-    return { candidates, failedRequests, limitations, status, summary: failedRequests.length === 0 ? "Network source lookup found no failed requests." : candidates.length > 0 ? `Network source lookup found ${failedRequests.length} failed request(s) and ${candidates.length} candidate source hint(s).` : `Network source lookup found ${failedRequests.length} failed request(s) but no source candidates.` };
+    const observed = observeInitiatorCandidates(data, failedRequests);
+    const workspace = await scanWorkspaceRequests(compiled.query, failedRequests, cwd);
+    const candidates = distinctNetworkCandidates([...observed, ...workspace.candidates]);
+    const status = networkStatus(failedRequests.length, candidates.length);
+    return {
+        candidates,
+        failedRequests,
+        limitations: [
+            "Experimental network source hints report candidates only; failed requests can be triggered indirectly by frameworks, caches, service workers, or third-party scripts.",
+            "Initiator/source-map metadata is upstream/browser-build dependent and may be absent.",
+            ...workspace.limitations,
+        ],
+        status,
+        summary: networkSummary(status, failedRequests.length, candidates.length),
+    };
 }

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -1,11 +1,14 @@
 import { JsonSchema } from "../json-schema.js";
 import { StringEnum as localStringEnum } from "../string-enum-schema.js";
-import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS } from "../electron/discovery.js";
+import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS, } from "../electron/discovery-types.js";
 import { AGENT_BROWSER_CODE_MAX_TIMEOUT_MS, AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
 const AGENT_BROWSER_ADVANCED_TOOLS = ["action", "qa", "electron", "source", "network"];
 function outputProperties(Type) {
     return {
-        outputPath: Type.Optional(Type.String({ description: "Result-data path, separate from browser artifact paths.", minLength: 1 })),
+        outputPath: Type.Optional(Type.String({
+            description: "Result-data path, separate from browser artifact paths.",
+            minLength: 1,
+        })),
         timeoutMs: Type.Optional(Type.Integer({ description: "Timeout in ms; exceed explicit waits.", minimum: 1 })),
     };
 }
@@ -18,17 +21,31 @@ function sessionModeProperty(Type, StringEnum) {
 // Keep the always-on schemas small; specialized guidance belongs to each advanced tool.
 export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Unsafe(Type.Object({
-        args: Type.Array(Type.String(), { description: "Native agent-browser argv without the binary or shell syntax. Fixed sequences: batch --bail with JSON-array stdin.", minItems: 1 }),
-        stdin: Type.Optional(Type.String({ description: "Native batch JSON, eval --stdin source, or auth save --password-stdin text." })),
+        args: Type.Array(Type.String(), {
+            description: "Native agent-browser argv without the binary or shell syntax. Fixed sequences: batch --bail with JSON-array stdin.",
+            minItems: 1,
+        }),
+        stdin: Type.Optional(Type.String({
+            description: "Native batch JSON, eval --stdin source, or auth save --password-stdin text.",
+        })),
         ...outputProperties(Type),
         sessionMode: sessionModeProperty(Type, StringEnum),
     }, { additionalProperties: false }));
 }
 export function createAgentBrowserCodeParamsSchema(Type = JsonSchema) {
     return Type.Unsafe(Type.Object({
-        code: Type.String({ description: "JavaScript with await browser({args, stdin?, timeoutMs?}), emit(JSON), and emitImage(image handle). Fresh JS context; persistent browser.", minLength: 1, maxLength: 65_536 }),
-        session: Type.Optional(Type.String({ description: "Explicit native session; omitted uses the ordinary default browser.", minLength: 1 })),
-        namespace: Type.Optional(Type.String({ description: "Native namespace; empty string selects the default namespace." })),
+        code: Type.String({
+            description: "JavaScript with await browser({args, stdin?, timeoutMs?}), emit(JSON), and emitImage(image handle). Fresh JS context; persistent browser.",
+            minLength: 1,
+            maxLength: 65_536,
+        }),
+        session: Type.Optional(Type.String({
+            description: "Explicit native session; omitted uses the ordinary default browser.",
+            minLength: 1,
+        })),
+        namespace: Type.Optional(Type.String({
+            description: "Native namespace; empty string selects the default namespace.",
+        })),
         ...outputProperties(Type),
         timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: AGENT_BROWSER_CODE_MAX_TIMEOUT_MS })),
     }, { additionalProperties: false }));
@@ -36,9 +53,16 @@ export function createAgentBrowserCodeParamsSchema(Type = JsonSchema) {
 export function createAgentBrowserActionParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Unsafe(Type.Object({
         action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS),
-        locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Select supports role or label." })),
-        value: Type.Optional(Type.String({ description: "Locator value or select option; label text for select by label." })),
-        values: Type.Optional(Type.Array(Type.String(), { description: "Select options; required for select by label.", minItems: 1 })),
+        locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
+            description: "Select supports role or label.",
+        })),
+        value: Type.Optional(Type.String({
+            description: "Locator value or select option; label text for select by label.",
+        })),
+        values: Type.Optional(Type.Array(Type.String(), {
+            description: "Select options; required for select by label.",
+            minItems: 1,
+        })),
         selector: Type.Optional(Type.String({ description: "Direct selector or current @ref." })),
         text: Type.Optional(Type.String({ description: "Fill text." })),
         role: Type.Optional(Type.String({ description: "Role locator; select needs combobox or listbox." })),
@@ -49,7 +73,10 @@ export function createAgentBrowserActionParamsSchema(Type = JsonSchema, StringEn
         additionalProperties: false,
         // Top-level properties let Pi normalize optional nulls before validating branches.
         anyOf: [
-            Type.Object({ action: StringEnum(["select"]), locator: Type.Optional(StringEnum(["role", "label"])) }, { not: { required: ["text"] } }),
+            Type.Object({
+                action: StringEnum(["select"]),
+                locator: Type.Optional(StringEnum(["role", "label"])),
+            }, { not: { required: ["text"] } }),
             Type.Object({ action: StringEnum(["check", "click", "fill"]) }, { not: { required: ["values"] } }),
         ],
     }));
@@ -70,7 +97,10 @@ export function createAgentBrowserQaParamsSchema(Type = JsonSchema, StringEnum =
     }, {
         additionalProperties: false,
         anyOf: [
-            Type.Object({ attached: Type.Literal(true), sessionMode: Type.Optional(StringEnum(["auto"])) }, { not: { required: ["url"] } }),
+            Type.Object({
+                attached: Type.Literal(true),
+                sessionMode: Type.Optional(StringEnum(["auto"])),
+            }, { not: { required: ["url"] } }),
             Type.Object({ url: Type.String(), attached: Type.Optional(Type.Literal(false)) }),
         ],
     }));
@@ -80,7 +110,10 @@ export function createAgentBrowserElectronParamsSchema(Type = JsonSchema, String
     const timeoutMs = Type.Optional(Type.Integer({ minimum: 1 }));
     const list = {
         query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
-        maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, clamped to ${ELECTRON_DISCOVERY_MAX_RESULTS}.`, minimum: 1 })),
+        maxResults: Type.Optional(Type.Integer({
+            description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, clamped to ${ELECTRON_DISCOVERY_MAX_RESULTS}.`,
+            minimum: 1,
+        })),
     };
     const launch = {
         appPath: Type.Optional(Type.String({ description: "macOS .app path.", minLength: 1 })),
@@ -100,7 +133,10 @@ export function createAgentBrowserElectronParamsSchema(Type = JsonSchema, String
     // Each branch retains its original action-specific field boundary.
     return Type.Unsafe(Type.Object({
         action: StringEnum(["list", "launch", "status", "cleanup", "probe"]),
-        ...list, ...launch, ...lifecycle, ...common,
+        ...list,
+        ...launch,
+        ...lifecycle,
+        ...common,
     }, {
         additionalProperties: false,
         anyOf: [
@@ -117,7 +153,11 @@ export function createAgentBrowserSourceParamsSchema(Type = JsonSchema, StringEn
         reactFiberId: Type.Optional(Type.String({ description: "React fiber id; requires --enable react-devtools." })),
         componentName: Type.Optional(Type.String({ description: "Component for local source search." })),
         includeDomHints: Type.Optional(Type.Boolean({ description: "Inspect DOM hints; default true." })),
-        maxWorkspaceFiles: Type.Optional(Type.Integer({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        maxWorkspaceFiles: Type.Optional(Type.Integer({
+            description: "Source scan cap; default 2000.",
+            minimum: 1,
+            maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES,
+        })),
         ...outputProperties(Type),
         sessionMode: sessionModeProperty(Type, StringEnum),
     }, { additionalProperties: false }));
@@ -129,14 +169,20 @@ export function createAgentBrowserNetworkSourceParamsSchema(Type = JsonSchema, S
         requestId: Type.Optional(Type.String({ description: "Request id to inspect." })),
         session: Type.Optional(Type.String()),
         url: Type.Optional(Type.String({ description: "Failed URL or fragment." })),
-        maxWorkspaceFiles: Type.Optional(Type.Integer({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        maxWorkspaceFiles: Type.Optional(Type.Integer({
+            description: "Source scan cap; default 2000.",
+            minimum: 1,
+            maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES,
+        })),
         ...outputProperties(Type),
         sessionMode: sessionModeProperty(Type, StringEnum),
     }, { additionalProperties: false }));
 }
 export function createAgentBrowserToolsParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Unsafe(Type.Object({
-        enable: Type.Optional(Type.Array(StringEnum(AGENT_BROWSER_ADVANCED_TOOLS), { description: "Add capabilities to active tools; omit to list inventory." })),
+        enable: Type.Optional(Type.Array(StringEnum(AGENT_BROWSER_ADVANCED_TOOLS), {
+            description: "Add capabilities to active tools; omit to list inventory.",
+        })),
     }, { additionalProperties: false }));
 }
 export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();