pi-agent-browser-native 0.2.48 → 0.2.49

package/dist/extensions/agent-browser/lib/web-search.js

@@ -0,0 +1,562 @@
+/**
+ * Purpose: Provide the optional provider-backed `agent_browser_web_search` companion tool.
+ * Responsibilities: Define strict search input schema, resolve configured Brave/Exa credentials lazily, call the selected search API with cancellation/timeout, normalize compact results, and keep secrets out of content/details.
+ * Scope: Live web search only; browser automation remains in the `agent_browser` tool.
+ */
+import { JsonSchema } from "./json-schema.js";
+import { StringEnum as localStringEnum } from "./string-enum-schema.js";
+import { DEFAULT_WEB_SEARCH_PROVIDER, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
+export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
+export const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+export const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+export const DEFAULT_SEARCH_RESULT_COUNT = 5;
+export const MAX_SEARCH_RESULT_COUNT = 10;
+export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
+export const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
+export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
+export const EXA_SEARCH_TYPES = ["auto", "fast", "instant", "deep-lite", "deep", "deep-reasoning"];
+export const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
+export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
+    return Type.Object({
+        query: Type.String({
+            minLength: 1,
+            description: "Search query to run with the configured Exa or Brave web search provider.",
+        }),
+        provider: Type.Optional(StringEnum(WEB_SEARCH_PROVIDER_PARAM_VALUES, {
+            description: `Optional provider override. auto uses configured keys and preferredProvider; when both Exa and Brave are available, the default preferred provider is ${DEFAULT_WEB_SEARCH_PROVIDER}.`,
+        })),
+        searchType: Type.Optional(StringEnum(EXA_SEARCH_TYPES, {
+            description: "Optional Exa search type. Defaults to auto; ignored by Brave. Use deep/deep-reasoning only for harder research because they are slower.",
+        })),
+        count: Type.Optional(Type.Integer({
+            minimum: 1,
+            maximum: MAX_SEARCH_RESULT_COUNT,
+            description: `Number of web results to return. Defaults to ${DEFAULT_SEARCH_RESULT_COUNT}; max ${MAX_SEARCH_RESULT_COUNT}.`,
+        })),
+        offset: Type.Optional(Type.Integer({
+            minimum: 0,
+            maximum: 9,
+            description: "Zero-based result offset for pagination. Defaults to 0.",
+        })),
+        country: Type.Optional(Type.String({
+            pattern: "^[A-Za-z]{2}$",
+            description: "Optional 2-letter country code, such as US or GB.",
+        })),
+        searchLang: Type.Optional(Type.String({
+            minLength: 2,
+            maxLength: 8,
+            description: "Optional Brave search language code, such as en or en-US.",
+        })),
+        safesearch: Type.Optional(StringEnum(["off", "moderate", "strict"], {
+            description: "Optional search safety setting. Brave forwards this as safesearch; Exa maps moderate/strict to moderation=true.",
+        })),
+        freshness: Type.Optional(StringEnum(["pd", "pw", "pm", "py"], {
+            description: "Optional freshness window: pd=past day, pw=past week, pm=past month, py=past year.",
+        })),
+    }, { additionalProperties: false });
+}
+export const AgentBrowserWebSearchParams = createAgentBrowserWebSearchParamsSchema();
+const HTML_ENTITY_REPLACEMENTS = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    nbsp: " ",
+    quot: '"',
+};
+const HTML_TAG_NAMES_TO_STRIP = new Set([
+    "a",
+    "abbr",
+    "address",
+    "article",
+    "aside",
+    "audio",
+    "b",
+    "base",
+    "blockquote",
+    "body",
+    "br",
+    "button",
+    "canvas",
+    "code",
+    "div",
+    "em",
+    "embed",
+    "footer",
+    "form",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "html",
+    "i",
+    "iframe",
+    "img",
+    "input",
+    "li",
+    "link",
+    "main",
+    "mark",
+    "math",
+    "meta",
+    "nav",
+    "object",
+    "ol",
+    "option",
+    "p",
+    "pre",
+    "script",
+    "section",
+    "select",
+    "source",
+    "span",
+    "strong",
+    "style",
+    "svg",
+    "table",
+    "tbody",
+    "td",
+    "textarea",
+    "tfoot",
+    "th",
+    "thead",
+    "tr",
+    "u",
+    "ul",
+    "video",
+]);
+function decodeHtmlEntity(entity) {
+    const named = HTML_ENTITY_REPLACEMENTS[entity.toLowerCase()];
+    if (named !== undefined)
+        return named;
+    const decimalMatch = /^#(\d+)$/.exec(entity);
+    const hexMatch = /^#x([0-9a-f]+)$/i.exec(entity);
+    const codePoint = decimalMatch ? Number.parseInt(decimalMatch[1] ?? "", 10) : hexMatch ? Number.parseInt(hexMatch[1] ?? "", 16) : undefined;
+    if (codePoint === undefined || !Number.isFinite(codePoint))
+        return `&${entity};`;
+    try {
+        return String.fromCodePoint(codePoint);
+    }
+    catch {
+        return `&${entity};`;
+    }
+}
+export function decodeHtmlEntities(value) {
+    return value.replace(/&([a-z][a-z0-9]+|#\d+|#x[0-9a-f]+);/gi, (_match, entity) => decodeHtmlEntity(entity));
+}
+function stripDecodedHtmlTags(value) {
+    return value.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, " ").replace(/<\/?([a-z][a-z0-9-]*)(\s[^>]*)?>/gi, (match, tagName, attributes) => {
+        if (attributes || match.startsWith("</") || HTML_TAG_NAMES_TO_STRIP.has(tagName.toLowerCase()))
+            return " ";
+        return match;
+    });
+}
+export function cleanSearchText(value, maxLength = 500) {
+    if (typeof value !== "string")
+        return undefined;
+    const cleaned = stripDecodedHtmlTags(decodeHtmlEntities(value.replace(/<[^>]*>/g, " ")))
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return undefined;
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return `${cleaned.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+export function normalizeSearchUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function getHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeHighlightList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const highlights = value
+        .map((entry) => cleanSearchText(entry, 320))
+        .filter((entry) => Boolean(entry))
+        .slice(0, 3);
+    return highlights.length > 0 ? highlights : undefined;
+}
+export function normalizeBraveSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (!title || !url)
+        return undefined;
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.description, 320),
+        source: cleanSearchText(result.profile?.name, 120) ?? cleanSearchText(result.meta_url?.hostname, 120),
+        age: cleanSearchText(result.age, 80),
+        language: cleanSearchText(result.language, 40),
+    };
+}
+export function normalizeExaSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (!title || !url)
+        return undefined;
+    const highlights = normalizeHighlightList(result.highlights);
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.summary, 320) ?? highlights?.[0] ?? cleanSearchText(result.text, 320),
+        highlights,
+        source: cleanSearchText(result.author, 120) ?? cleanSearchText(getHostname(url), 120),
+        age: cleanSearchText(result.publishedDate, 80),
+    };
+}
+function getProviderLabel(provider) {
+    return provider === "exa" ? "Exa" : "Brave";
+}
+export function formatSearchResults(provider, query, results) {
+    const providerLabel = getProviderLabel(provider);
+    if (results.length === 0) {
+        return `No ${providerLabel} web results found for: ${query}`;
+    }
+    const lines = [`${providerLabel} web search results for: ${query}`, ""];
+    results.forEach((result, index) => {
+        lines.push(`${index + 1}. ${result.title}`);
+        lines.push(`   URL: ${result.url}`);
+        if (result.source)
+            lines.push(`   Source: ${result.source}`);
+        if (result.age)
+            lines.push(`   Age: ${result.age}`);
+        if (result.description)
+            lines.push(`   Summary: ${result.description}`);
+        if (result.highlights && result.highlights.length > 1) {
+            lines.push("   Highlights:");
+            for (const highlight of result.highlights)
+                lines.push(`   - ${highlight}`);
+        }
+        lines.push("");
+    });
+    return lines.join("\n").trimEnd();
+}
+export function buildBraveSearchUrl(params) {
+    const url = new URL(BRAVE_SEARCH_ENDPOINT);
+    url.searchParams.set("q", params.query);
+    url.searchParams.set("count", String(params.count));
+    url.searchParams.set("offset", String(params.offset));
+    if (params.country)
+        url.searchParams.set("country", params.country.toUpperCase());
+    if (params.searchLang)
+        url.searchParams.set("search_lang", params.searchLang);
+    if (params.safesearch)
+        url.searchParams.set("safesearch", params.safesearch);
+    if (params.freshness)
+        url.searchParams.set("freshness", params.freshness);
+    return url;
+}
+const FRESHNESS_DAYS = {
+    pd: 1,
+    pw: 7,
+    pm: 31,
+    py: 365,
+};
+function getStartPublishedDate(freshness, now) {
+    if (!freshness)
+        return undefined;
+    const days = FRESHNESS_DAYS[freshness];
+    return new Date(now().getTime() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+export function buildExaSearchRequestBody(params, now = () => new Date()) {
+    const body = {
+        query: params.query,
+        type: params.searchType ?? "auto",
+        numResults: Math.min(params.count + params.offset, 100),
+        contents: { highlights: true },
+    };
+    if (params.country)
+        body.userLocation = params.country.toUpperCase();
+    if (params.safesearch && params.safesearch !== "off")
+        body.moderation = true;
+    const startPublishedDate = getStartPublishedDate(params.freshness, now);
+    if (startPublishedDate)
+        body.startPublishedDate = startPublishedDate;
+    return body;
+}
+function redactSearchSecret(text, apiKey) {
+    return apiKey ? text.split(apiKey).join("[REDACTED]") : text;
+}
+function sleepWithAbort(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(signal.reason ?? new Error("Web search cancelled"));
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener("abort", abort);
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timeout);
+            cleanup();
+            reject(signal?.reason ?? new Error("Web search cancelled"));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export class WebSearchRequestGate {
+    now;
+    sleep;
+    lastRequestStartedAt = 0;
+    tail = Promise.resolve();
+    constructor(now = Date.now, sleep = sleepWithAbort) {
+        this.now = now;
+        this.sleep = sleep;
+    }
+    run(signal, task) {
+        const runTask = async () => {
+            const elapsedMs = this.lastRequestStartedAt === 0 ? WEB_SEARCH_MIN_REQUEST_INTERVAL_MS : this.now() - this.lastRequestStartedAt;
+            const waitMs = Math.max(0, WEB_SEARCH_MIN_REQUEST_INTERVAL_MS - elapsedMs);
+            if (waitMs > 0)
+                await this.sleep(waitMs, signal);
+            if (signal?.aborted)
+                throw signal.reason ?? new Error("Web search cancelled");
+            this.lastRequestStartedAt = this.now();
+            return task();
+        };
+        const result = this.tail.then(runTask, runTask);
+        this.tail = result.catch(() => undefined);
+        return result;
+    }
+}
+function formatSearchHttpError(provider, status, statusText, body, apiKey) {
+    const providerLabel = getProviderLabel(provider);
+    const errorPreview = cleanSearchText(redactSearchSecret(body, apiKey), 300);
+    if (status === 429) {
+        const preview = errorPreview ? ` Upstream details: ${redactSearchSecret(errorPreview, apiKey)}` : "";
+        return `${providerLabel} search rate limit exceeded (HTTP 429). Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect those results, then wait before retrying or ask the user to adjust their ${providerLabel} API plan/limits.${preview}`;
+    }
+    return `${providerLabel} search failed with HTTP ${status}: ${errorPreview ? redactSearchSecret(errorPreview, apiKey) : statusText}`;
+}
+async function fetchSearchJson(options) {
+    if (options.signal?.aborted) {
+        throw options.signal.reason ?? new Error(options.cancelMessage);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error(options.timeoutMessage)), options.timeoutMs);
+    const abort = () => controller.abort(options.signal?.reason ?? new Error(options.cancelMessage));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const response = await fetch(options.request, {
+            ...(options.init ?? {}),
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(formatSearchHttpError(options.provider, response.status, response.statusText, text, options.apiKey));
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`${options.invalidJsonMessage}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", abort);
+    }
+}
+export async function fetchBraveSearchJson(url, apiKey, signal) {
+    return fetchSearchJson({
+        apiKey,
+        cancelMessage: "Brave search cancelled",
+        init: {
+            headers: {
+                Accept: "application/json",
+                "X-Subscription-Token": apiKey,
+            },
+        },
+        invalidJsonMessage: "Brave search returned invalid JSON",
+        provider: "brave",
+        request: url,
+        signal,
+        timeoutMessage: "Brave search timed out",
+        timeoutMs: SEARCH_REQUEST_TIMEOUT_MS,
+    });
+}
+function getExaRequestTimeoutMs(searchType) {
+    return searchType?.startsWith("deep") ? EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS : SEARCH_REQUEST_TIMEOUT_MS;
+}
+export async function fetchExaSearchJson(body, apiKey, signal, timeoutMs = SEARCH_REQUEST_TIMEOUT_MS) {
+    return fetchSearchJson({
+        apiKey,
+        cancelMessage: "Exa search cancelled",
+        init: {
+            body: JSON.stringify(body),
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+            },
+            method: "POST",
+        },
+        invalidJsonMessage: "Exa search returned invalid JSON",
+        provider: "exa",
+        request: EXA_SEARCH_ENDPOINT,
+        signal,
+        timeoutMessage: "Exa search timed out",
+        timeoutMs,
+    });
+}
+const BRAVE_WEB_SEARCH_ADAPTER = {
+    provider: "brave",
+    buildRequest(params) {
+        return buildBraveSearchUrl({
+            query: params.query,
+            count: params.count,
+            offset: params.offset,
+            country: params.country,
+            searchLang: params.searchLang,
+            safesearch: params.safesearch,
+            freshness: params.freshness,
+        });
+    },
+    fetchJson(request, apiKey, signal) {
+        return fetchBraveSearchJson(request, apiKey, signal);
+    },
+    normalizeResponse(response, params) {
+        return {
+            results: (response.web?.results ?? [])
+                .map(normalizeBraveSearchResult)
+                .filter((result) => Boolean(result)),
+            returnedQuery: cleanSearchText(response.query?.altered, 300) ?? cleanSearchText(response.query?.original, 300) ?? params.query,
+        };
+    },
+};
+const EXA_WEB_SEARCH_ADAPTER = {
+    provider: "exa",
+    buildRequest(params) {
+        const searchType = params.searchType ?? "auto";
+        return {
+            body: buildExaSearchRequestBody({
+                query: params.query,
+                count: params.count,
+                offset: params.offset,
+                country: params.country,
+                safesearch: params.safesearch,
+                freshness: params.freshness,
+                searchType,
+            }),
+            timeoutMs: getExaRequestTimeoutMs(searchType),
+        };
+    },
+    fetchJson(request, apiKey, signal) {
+        return fetchExaSearchJson(request.body, apiKey, signal, request.timeoutMs);
+    },
+    normalizeResponse(response, params) {
+        const searchType = params.searchType ?? "auto";
+        return {
+            extraDetails: {
+                requestId: cleanSearchText(response.requestId, 120),
+                searchType: cleanSearchText(response.searchType, 80) ?? searchType,
+            },
+            results: (response.results ?? [])
+                .map(normalizeExaSearchResult)
+                .filter((result) => Boolean(result))
+                .slice(params.offset, params.offset + params.count),
+            returnedQuery: params.query,
+        };
+    },
+};
+export const WEB_SEARCH_PROVIDER_ADAPTERS = {
+    exa: EXA_WEB_SEARCH_ADAPTER,
+    brave: BRAVE_WEB_SEARCH_ADAPTER,
+};
+export function getWebSearchProviderAdapter(provider) {
+    return WEB_SEARCH_PROVIDER_ADAPTERS[provider];
+}
+function buildMissingCredentialError(provider) {
+    if (provider === "brave")
+        return "agent_browser_web_search provider brave was requested but no BRAVE_API_KEY/config credential resolved.";
+    if (provider === "exa")
+        return "agent_browser_web_search provider exa was requested but no EXA_API_KEY/config credential resolved.";
+    return "No Exa or Brave web search credential resolved. Configure webSearch.exaApiKey or webSearch.braveApiKey, or load EXA_API_KEY/BRAVE_API_KEY in the runtime environment.";
+}
+export function createAgentBrowserWebSearchTool(configState, options = {}) {
+    const requestGate = new WebSearchRequestGate();
+    return {
+        name: AGENT_BROWSER_WEB_SEARCH_TOOL_NAME,
+        label: "Agent Browser Web Search",
+        description: `Search the web with Exa or Brave when configured. Returns up to ${MAX_SEARCH_RESULT_COUNT} concise web results.`,
+        promptSnippet: "Search the live web with Exa or Brave for current or external information.",
+        promptGuidelines: [
+            "Use agent_browser_web_search when live web search would help answer the task, find current external information, or discover candidate URLs for agent_browser.",
+            "agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
+            "Prefer agent_browser_web_search over opening a search engine results page with agent_browser when a quick result list is enough; use agent_browser for interaction, DOM, screenshots, or auth.",
+            "Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect the results, then only run a focused follow-up if needed. If the provider returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",
+            "After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",
+        ],
+        parameters: AgentBrowserWebSearchParams,
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const runtimeConfigState = ctx ? options.loadConfigState?.(ctx) ?? configState : configState;
+            if (runtimeConfigState.errors.length > 0) {
+                throw new Error(`agent_browser_web_search config is invalid: ${runtimeConfigState.errors.join("; ")}`);
+            }
+            if (!runtimeConfigState.webSearchEnabled) {
+                throw new Error("agent_browser_web_search is disabled by pi-agent-browser-native config.");
+            }
+            const requestedProvider = params.provider ?? "auto";
+            const resolved = await resolvePreferredWebSearchCredential(runtimeConfigState, { provider: requestedProvider, signal });
+            if (!resolved)
+                throw new Error(buildMissingCredentialError(requestedProvider));
+            const query = params.query.trim();
+            if (!query)
+                throw new Error("query must not be blank");
+            const count = Math.min(Math.max(params.count ?? DEFAULT_SEARCH_RESULT_COUNT, 1), MAX_SEARCH_RESULT_COUNT);
+            const offset = Math.max(params.offset ?? 0, 0);
+            const adapter = getWebSearchProviderAdapter(resolved.provider);
+            const executionParams = {
+                country: params.country,
+                count,
+                freshness: params.freshness,
+                offset,
+                query,
+                safesearch: params.safesearch,
+                searchLang: params.searchLang,
+                searchType: params.searchType ?? "auto",
+            };
+            const request = adapter.buildRequest(executionParams);
+            const data = await requestGate.run(signal, () => adapter.fetchJson(request, resolved.credential.value, signal));
+            const normalized = adapter.normalizeResponse(data, executionParams);
+            const details = {
+                provider: adapter.provider,
+                query,
+                returnedQuery: normalized.returnedQuery,
+                count,
+                offset,
+                ...normalized.extraDetails,
+                fetchedAt: new Date().toISOString(),
+                results: normalized.results,
+            };
+            return {
+                content: [{ type: "text", text: formatSearchResults(adapter.provider, normalized.returnedQuery, normalized.results) }],
+                details,
+            };
+        },
+    };
+}

package/docs/RELEASE.md

@@ -38,7 +38,7 @@ For PR-ready local confidence before release-only lifecycle and platform cost, r
 npm run verify -- pre-pr
 ```
 
-`pre-pr` composes the default gate with `npm run verify -- package`: generated docs, TypeScript, the full unit/fake suite, live command-reference sampling, and package-content verification. It intentionally does not run lifecycle, packaged Pi smoke, Crabbox platform smoke, real-upstream, dogfood, or benchmark modes.
+`pre-pr` composes the default gate with `npm run verify -- package`: generated docs, clean `dist/` build, TypeScript, the full unit/fake suite, live command-reference sampling, and package-content verification. It intentionally does not run lifecycle, packaged Pi smoke, Crabbox platform smoke, startup-profile, real-upstream, dogfood, or benchmark modes.
 
 `npm run verify -- release` runs:
 
@@ -47,9 +47,18 @@ npm run verify -- pre-pr
 3. `npm run verify -- package-pi`, which first validates package contents via `npm pack --json --dry-run` and then smoke-loads the packed package in Pi isolation
 4. `npm run smoke:platform:doctor` and the full Crabbox matrix from [`platform-smoke.md`](platform-smoke.md): macOS SSH, Ubuntu local-container, and native Windows Parallels targets running fast target-local `platform-build` plus `browser-dogfood-smoke`
 
-`npm publish` runs npm’s `prepublishOnly` script from `package.json`, which executes the same `npm run verify -- release` gate and then `npm pack --dry-run`. That concatenated gate is everything in the default `npm run verify` step (generated playbook drift, TypeScript, the unit/fake suite, generated command-reference blocks, and live upstream command-reference sampling against the targeted `agent-browser` on `PATH`), the configured-source lifecycle harness, the packaged Pi smoke in `package-pi`, and the release-blocking Crabbox platform matrix. Using `npm publish --ignore-scripts` skips that contract intentionally.
+`npm publish` runs npm’s `prepublishOnly` script from `package.json`, which executes the same `npm run verify -- release` gate and then `npm pack --dry-run`. That concatenated gate is everything in the default `npm run verify` step (generated playbook drift, clean `dist/` build, TypeScript, the unit/fake suite, generated command-reference blocks, and live upstream command-reference sampling against the targeted `agent-browser` on `PATH`), the configured-source lifecycle harness, the packaged Pi smoke in `package-pi`, and the release-blocking Crabbox platform matrix. Using `npm publish --ignore-scripts` skips that contract intentionally.
 
-`prepublishOnly` intentionally does **not** run the standalone host-only `npm run verify -- real-upstream`, `npm run verify -- dogfood`, or `npm run verify -- benchmark` modes; those remain separate `npm run verify` modes in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs). The platform matrix includes its own fast target-local build/package gate and browser dogfood suite, and is automated through the `release` slice.
+`prepublishOnly` intentionally does **not** run the standalone host-only `npm run verify -- startup-profile`, `npm run verify -- real-upstream`, `npm run verify -- dogfood`, or `npm run verify -- benchmark` modes; those remain separate `npm run verify` modes in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs). The platform matrix includes its own fast target-local build/package gate and browser dogfood suite, and is automated through the `release` slice.
+
+Run the opt-in startup profiler whenever package layout, the compiled entrypoint, top-level imports, schema registration, or prompt/config startup logic changes:
+
+```bash
+npm run build
+npm run verify -- startup-profile --samples 3
+```
+
+The profiler first clean-builds `dist/`, then records only direct package entrypoint import/factory timing in fresh Node processes, writes `.artifacts/startup-profile/latest.json`, and includes a safety block confirming it did not launch Pi, tmux, mise, npm, browsers, or `agent-browser`. Full Pi TUI ready-prompt profiling is intentionally excluded because repeated real Pi/tmux launches proved too invasive for routine verification on the operator machine.
 
 For a deterministic host-only real-browser wrapper smoke without model choice in the loop, run:
 
@@ -76,7 +85,7 @@ Every release also requires interactive `tmux`-driven Pi dogfood with the native
 
 When reviewing saved session JSONL after a failed smoke or a `qa` preset that reclassified an upstream-successful batch, expect `agent_browser` tool rows to carry `isError: true` whenever `details.resultCategory` is `failure`. For normal prose output, model-visible text should end with a `Pi tool isError: true` category line; for caller-requested `--json` output, the hook preserves parseable JSON and only patches `isError`. The extension applies that patch on the `tool_result` path so Pi’s transcript matches the wrapper contract ([`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details)). Preserve a normal Pi session directory for those checks; avoiding `--no-session` keeps this evidence intact ([`AGENTS.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/AGENTS.md) preferred validation workflow).
 
-The configured-source lifecycle regression harness is required before release because it launches an interactive `pi` process under `tmux` with `--approve` and validates `/reload`, full relaunch with the same exact Pi 0.79 `--session-id`, managed-session continuity, persisted artifacts, and Pi failure-patch behavior. Branch-backed `session_tree` rehydration and cleanup ownership are validated by focused extension harness tests:
+The configured-source lifecycle regression harness is required before release because it launches an interactive `pi` process under `tmux` with `--approve` and validates `/reload`, full relaunch with the same exact Pi 0.79 `--session-id`, managed-session continuity, persisted artifacts, compiled-entrypoint pickup after process restart, and Pi failure-patch behavior. Branch-backed `session_tree` rehydration and cleanup ownership are validated by focused extension harness tests:
 
 ```bash
 npm run verify -- lifecycle
@@ -155,7 +164,7 @@ Evaluator expectations after the queued Sauce Demo fixes: the agent should indep
 [`scripts/agent-browser-efficiency-benchmark.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/agent-browser-efficiency-benchmark.mjs) is an accounting-only benchmark: it does not shell out to `agent-browser`, launch a browser, or read or write Pi sessions. It models representative `agent_browser` call shapes (including optional `stdin` for `batch` and top-level `job`, `qa`, or experimental `sourceLookup` / `networkSourceLookup` objects that compile to batch) and aggregates success rate, tool-call counts, UTF-8 size of model-visible strings, stale-ref failure and recovery counts, artifact success, distinct failure-category coverage, and summed elapsed-time estimates. When extending scenarios, keep them aligned with the closed `RQ-0068` “no reusable recipe layer” rationale in [`ARCHITECTURE.md`](ARCHITECTURE.md#no-reusable-recipe-layer-yet) (benchmark ids cited there are the canonical inventory for that evidence bar).
 
 - **During development:** `npm run benchmark:agent-browser` prints a Markdown report; `npm run benchmark:agent-browser -- --json` saves machine-readable metrics; `npm run benchmark:agent-browser -- --compare path/to/prior.json` fails with exit code `1` on regressions (see the script’s `--help` for exit codes). Optional `--sample-jsonl path/to/session.jsonl` adds a `jsonlSample` section with real UTF-8 byte totals and per-workflow/overall p95 sizes for model-visible `agent_browser` tool-result text without changing deterministic scenario metrics; comparison ignores `jsonlSample` blocks.
-- **Default gate:** `npm run verify` checks generated playbook drift, runs `tsc --noEmit`, runs the full unit/fake suite under `test/**/*.test.ts` with Node test concurrency pinned to `1` (including [`test/agent-browser.efficiency-benchmark.test.ts`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/agent-browser.efficiency-benchmark.test.ts) for scenario coverage and comparison behavior), verifies generated command-reference baseline blocks, and samples live upstream command-reference tokens. It does not spawn the standalone benchmark script’s JSON/Markdown run; that is what the opt-in slice below adds.
+- **Default gate:** `npm run verify` checks generated playbook drift, clean-builds `dist/`, runs `tsc --noEmit`, runs the full unit/fake suite under `test/**/*.test.ts` with Node test concurrency pinned to `1` (including [`test/agent-browser.efficiency-benchmark.test.ts`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/agent-browser.efficiency-benchmark.test.ts) for scenario coverage and comparison behavior), verifies generated command-reference baseline blocks, and samples live upstream command-reference tokens. It does not spawn the standalone benchmark script’s JSON/Markdown run; that is what the opt-in slice below adds.
 - **Pre-PR gate:** `npm run verify -- pre-pr` runs the default gate plus `npm run verify -- package` for larger handoffs that need package-content confidence without lifecycle, platform, real-upstream, dogfood, or benchmark cost.
 - **Opt-in slice:** `npm run verify -- benchmark` runs the benchmark script once with `--json` and then that same test module alone. It is intentionally **not** part of `npm run verify -- pre-pr` or `npm run verify -- release`, so routine handoff and publish gates stay decoupled from benchmark churn while still allowing a focused check after editing scenarios or `CURRENT_BENCHMARK_VERSION`.
 
@@ -168,9 +177,11 @@ Maintainer constraints for evolving scenarios and version bumps are summarized u
 - no repo-local `.pi/extensions/agent-browser.ts` autoload shim is present
 - `LICENSE` exists in the repo and the packed tarball
 - canonical published docs are present
+- `npm pack --json --dry-run` runs the `prepack` build and packs the compiled `dist/extensions/agent-browser/index.js` entrypoint
+- GitHub/source installs run the package `prepare` build so Pi can load the ignored compiled `dist/extensions/agent-browser/index.js` entrypoint from a fresh clone
 - the package-level doctor command and capability baseline are present
-- extension source files are present, including the split result-rendering modules required by the published facade
-- agent-only and superseded docs are absent from the tarball
+- compiled extension runtime files are present, including the split result-rendering modules required by the published facade
+- source-only, agent-only, and superseded docs are absent from the tarball
 
 `npm run verify -- package-pi` runs the same package-content checks and additionally confirms that:
 
@@ -187,7 +198,7 @@ Current forbidden packed files include:
 - `AGENTS.md`
 - archived planning drafts under `docs/archive/`
 - `.pi/extensions/agent-browser.ts`
-- test and repo-only maintenance files
+- TypeScript extension source and other test/repo-only maintenance files
 
 For a full packed file listing:
 
@@ -203,7 +214,7 @@ Before publishing, validate both local-checkout modes without mixing their assum
 
 1. Install `agent-browser` separately.
 2. Launch `pi --approve --no-extensions -e .` from this trusted repository root. Omit `--approve` only when testing Pi's Project Trust prompt.
-3. Confirm the checkout extension loads from `extensions/agent-browser/index.ts`.
+3. Confirm the checkout package loads the compiled `dist/extensions/agent-browser/index.js` entrypoint (run `npm run build` first after source edits).
 4. Run a smoke prompt that exercises `agent_browser`.
 5. Restart the `pi` process after extension edits; Pi settings and `/reload` are not the validation target in this isolated mode.
 
@@ -221,7 +232,7 @@ Run the automated harness for deterministic configured-source lifecycle regressi
 npm run verify -- lifecycle
 ```
 
-The harness creates an isolated `PI_CODING_AGENT_DIR`, writes settings with exactly one temporary configured package source, runs `pi` in `tmux` with `--approve`, default model **`zai/glm-5.1`**, and a deterministic `--session-id`, puts a deterministic fake `agent-browser` first on `PATH`, drives `/reload`, closes Pi, and relaunches with the same exact session id instead of typing `/resume`. It also asserts the JSONL session header id, same-page managed-session continuity, persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification. Per-step tmux waits default to **180000 ms** (three minutes) in [`scripts/verify-lifecycle.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/verify-lifecycle.mjs) (`DEFAULT_TIMEOUT_MS`); override with `--timeout-ms <ms>` when slower models or cold starts need more headroom. Override the model when needed:
+The harness creates an isolated `PI_CODING_AGENT_DIR`, writes settings with exactly one temporary configured package source, runs `pi` in `tmux` with `--approve`, default model **`zai/glm-5.1`**, and a deterministic `--session-id`, puts a deterministic fake `agent-browser` first on `PATH`, drives `/reload`, closes Pi, and relaunches with the same exact session id instead of typing `/resume`. It also asserts the JSONL session header id, same-page managed-session continuity, compiled JS code pickup after full process relaunch, persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification. Per-step tmux waits default to **180000 ms** (three minutes) in [`scripts/verify-lifecycle.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/verify-lifecycle.mjs) (`DEFAULT_TIMEOUT_MS`); override with `--timeout-ms <ms>` when slower models or cold starts need more headroom. Override the model when needed:
 
 ```bash
 npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal
@@ -235,7 +246,7 @@ npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal --timeout-ms 60
 
 On failure it retains transcripts/session artifacts; on success it performs best-effort cleanup. It does not replace occasional real-browser manual smoke testing.
 
-**Lifecycle triage:** a timeout on sentinel `v2` after `/reload` often means Pi rejected reload while the TUI still showed `Working…` (`Wait for the current response to finish before reloading`), even when the session JSONL already has a final assistant message. Re-run with `--keep-artifacts --verbose`, inspect the retained pane capture, and confirm the configured model follows tool prompts reliably. Slower models may need a higher `--timeout-ms` than the **180000 ms** default.
+**Lifecycle triage:** a timeout on sentinel `v2` after exact-session relaunch means the new compiled entrypoint did not load after process restart. A reload-step timeout or missing post-reload snapshot often means Pi rejected reload while the TUI still showed `Working…` (`Wait for the current response to finish before reloading`), even when the session JSONL already has a final assistant message. Re-run with `--keep-artifacts --verbose`, inspect the retained pane capture, and confirm the configured model follows tool prompts reliably. Slower models may need a higher `--timeout-ms` than the **180000 ms** default.
 
 ### Environment and automation pitfalls