unbrowse 2.10.2 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbrowse",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "description": "Reverse-engineer any website into reusable API skills. Zero-dep single binary with embedded browser engine.",
   "type": "module",
   "bin": {
@@ -23,11 +23,14 @@
     "dev": "bun --watch src/index.ts"
   },
   "dependencies": {
-    "fastify": "^5.7.4",
     "@fastify/cors": "^11.2.0",
     "@fastify/rate-limit": "^10.3.0",
+    "@cascade-fyi/splits-sdk": "^0.11.1",
+    "@solana/kit": "^6.6.0",
+    "bs58": "^6.0.0",
     "cheerio": "^1.2.0",
     "dotenv": "^17.3.1",
+    "fastify": "^5.7.4",
     "nanoid": "^5.1.6",
     "tsx": "^4.20.6",
     "ws": "^8.19.0"

package/runtime-src/agent-outcome.ts

@@ -0,0 +1,166 @@
+import type { OrchestrationTiming, SkillManifest } from "./types/index.js";
+
+export interface AgentImpact {
+  source: string;
+  cache_hit: boolean;
+  browser_avoided: boolean;
+  baseline_total_ms?: number;
+  actual_total_ms?: number;
+  time_saved_ms?: number;
+  time_saved_pct: number;
+  tokens_saved: number;
+  tokens_saved_pct: number;
+  baseline_cost_uc?: number;
+  actual_cost_uc?: number;
+  cost_saved_uc?: number;
+}
+
+export interface AgentNextAction {
+  endpoint_id: string;
+  operation_id: string;
+  title: string;
+  why: string;
+  command: string;
+}
+
+const BROWSER_SOURCES = new Set(["live-capture", "first-pass", "browser-action"]);
+
+function edgePriority(kind: string): number {
+  switch (kind) {
+    case "parent_child":
+      return 4;
+    case "pagination":
+      return 3;
+    case "dependency":
+      return 2;
+    case "hint":
+      return 1;
+    case "auth":
+      return 0;
+    default:
+      return -1;
+  }
+}
+
+function nextActionWhy(kind: string, bindingKey: string, title: string): string {
+  switch (kind) {
+    case "parent_child":
+      return `Likely next detail step after this result. Exposes ${title}.`;
+    case "pagination":
+      return `Likely next page or continuation step. Carries ${bindingKey || "cursor"} forward.`;
+    case "dependency":
+      return `Unlocks the next dependent call using ${bindingKey || "known bindings"}.`;
+    case "auth":
+      return "Useful once authentication is in place.";
+    case "hint":
+      return "Common follow-up action from the current result.";
+    default:
+      return "Likely follow-up action.";
+  }
+}
+
+function operationTitle(operation: NonNullable<SkillManifest["operation_graph"]>["operations"][number]): string {
+  const semantic = [operation.action_kind, operation.resource_kind]
+    .filter(Boolean)
+    .join(" ")
+    .replace(/_/g, " ")
+    .trim();
+  return operation.description_out || semantic || operation.endpoint_id;
+}
+
+export function buildAgentImpact(
+  timing?: Partial<OrchestrationTiming> | null,
+): AgentImpact | undefined {
+  if (!timing?.source) return undefined;
+  return {
+    source: timing.source,
+    cache_hit: timing.cache_hit === true,
+    browser_avoided: !BROWSER_SOURCES.has(timing.source),
+    baseline_total_ms: timing.baseline_total_ms,
+    actual_total_ms: timing.actual_total_ms,
+    time_saved_ms: timing.time_saved_ms,
+    time_saved_pct: timing.time_saved_pct ?? 0,
+    tokens_saved: timing.tokens_saved ?? 0,
+    tokens_saved_pct: timing.tokens_saved_pct ?? 0,
+    baseline_cost_uc: timing.baseline_cost_uc,
+    actual_cost_uc: timing.actual_cost_uc,
+    cost_saved_uc: timing.cost_saved_uc,
+  };
+}
+
+export function buildNextActions(
+  skill: SkillManifest | undefined,
+  endpointId: string | undefined,
+  maxActions = 3,
+): AgentNextAction[] {
+  if (!skill?.operation_graph || !endpointId) return [];
+  const graph = skill.operation_graph;
+  const current = graph.operations.find((operation) => operation.endpoint_id === endpointId);
+  if (!current) return [];
+
+  const byOperationId = new Map(graph.operations.map((operation) => [operation.operation_id, operation]));
+  const scored = new Map<string, {
+    operation_id: string;
+    endpoint_id: string;
+    title: string;
+    why: string;
+    score: number;
+  }>();
+
+  for (const edge of graph.edges) {
+    if (edge.from_operation_id !== current.operation_id) continue;
+    const target = byOperationId.get(edge.to_operation_id);
+    if (!target) continue;
+
+    const candidate = {
+      operation_id: target.operation_id,
+      endpoint_id: target.endpoint_id,
+      title: operationTitle(target),
+      why: nextActionWhy(edge.kind, edge.binding_key, operationTitle(target)),
+      score: (edgePriority(edge.kind) * 10) + Math.round(edge.confidence * 10),
+    };
+    const existing = scored.get(target.operation_id);
+    if (!existing || candidate.score > existing.score) {
+      scored.set(target.operation_id, candidate);
+    }
+  }
+
+  return [...scored.values()]
+    .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
+    .slice(0, maxActions)
+    .map((candidate) => ({
+      endpoint_id: candidate.endpoint_id,
+      operation_id: candidate.operation_id,
+      title: candidate.title,
+      why: candidate.why,
+      command: `unbrowse execute --skill ${skill.skill_id} --endpoint ${candidate.endpoint_id}`,
+    }));
+}
+
+export function attachAgentOutcomeHints<T extends Record<string, unknown>>(
+  payload: T,
+  opts?: {
+    skill?: SkillManifest;
+    endpointId?: string;
+    timing?: Partial<OrchestrationTiming> | null;
+  },
+): T & {
+  impact?: AgentImpact;
+  next_actions?: AgentNextAction[];
+} {
+  const target = payload as Record<string, unknown>;
+  const impact = buildAgentImpact(opts?.timing);
+  if (impact) {
+    target.impact = impact;
+  }
+
+  const nextActions = buildNextActions(opts?.skill, opts?.endpointId);
+  if (nextActions.length > 0) {
+    target.next_actions = nextActions;
+  }
+
+  return target as T & {
+    impact?: AgentImpact;
+    next_actions?: AgentNextAction[];
+  };
+}

package/runtime-src/analytics-session.ts

@@ -10,15 +10,30 @@ export interface AnalyticsSessionPayload {
   cached_skill_calls: number;
   fresh_index_calls: number;
   browser_mode: "default" | "replaced" | "manual" | "unknown";
+  success?: boolean;
+  source?: string;
+  time_saved_ms?: number;
+  time_saved_pct?: number;
+  tokens_saved?: number;
+  tokens_saved_pct?: number;
+  cost_saved_uc?: number;
 }
 
 export function buildAnalyticsSessionPayload(
   sessionId: string,
   startedAt: string,
-  source: OrchestrationTiming["source"],
-  trace: Pick<ExecutionTrace, "completed_at" | "network_events" | "trace_version">,
+  source: OrchestrationTiming["source"] | "first-pass",
+  trace: Pick<ExecutionTrace, "completed_at" | "trace_version" | "success" | "tokens_saved" | "tokens_saved_pct"> & {
+    network_events?: unknown[];
+  },
+  timing?: Pick<OrchestrationTiming, "time_saved_ms" | "time_saved_pct" | "cost_saved_uc">,
 ): AnalyticsSessionPayload {
-  const cacheLike = source === "marketplace" || source === "route-cache" || source === "first-pass";
+  const cacheLike = source === "marketplace" || source === "route-cache";
+  const browserMode = source === "live-capture" || source === "browser-action"
+    ? "default"
+    : source === "first-pass"
+      ? "default"
+      : "replaced";
   return {
     session_id: sessionId,
     started_at: startedAt,
@@ -27,7 +42,14 @@ export function buildAnalyticsSessionPayload(
     api_calls: Math.max(1, trace.network_events?.length ?? 0),
     discovery_queries: cacheLike ? 1 : 0,
     cached_skill_calls: cacheLike ? 1 : 0,
-    fresh_index_calls: source === "live-capture" ? 1 : 0,
-    browser_mode: "unknown",
+    fresh_index_calls: source === "live-capture" || source === "first-pass" || source === "browser-action" ? 1 : 0,
+    browser_mode: browserMode,
+    success: trace.success ?? true,
+    source,
+    time_saved_ms: timing?.time_saved_ms,
+    time_saved_pct: timing?.time_saved_pct,
+    tokens_saved: trace.tokens_saved,
+    tokens_saved_pct: trace.tokens_saved_pct,
+    cost_saved_uc: timing?.cost_saved_uc,
   };
 }

package/runtime-src/api/browse-index.ts

@@ -0,0 +1,254 @@
+import { nanoid } from "nanoid";
+import { readFileSync } from "node:fs";
+import { extractEndpoints } from "../reverse-engineer/index.js";
+import { buildSkillOperationGraph, inferEndpointSemantic } from "../graph/index.js";
+import type { KuriHarEntry } from "../kuri/client.js";
+import type { EndpointDescriptor, SkillManifest } from "../types/index.js";
+import type { RawRequest } from "../capture/index.js";
+import { cachePublishedSkill, findExistingSkillForDomain } from "../client/index.js";
+import { mergeEndpoints } from "../marketplace/index.js";
+import { upsertDagEdgesFromOperationGraph } from "../orchestrator/dag-feedback.js";
+import {
+  buildResolveCacheKey,
+  domainSkillCache,
+  generateLocalDescription,
+  getDomainReuseKey,
+  invalidateRouteCacheForDomain,
+  persistDomainCache,
+  scopedCacheKey,
+  snapshotPathForCacheKey,
+  writeSkillSnapshot,
+} from "../orchestrator/index.js";
+
+function normalizeBrowseUrl(url: string, baseUrl?: string): string {
+  if (!url) return url;
+  try {
+    return new URL(url).toString();
+  } catch {
+    if (!baseUrl) return url;
+    try {
+      return new URL(url, baseUrl).toString();
+    } catch {
+      return url;
+    }
+  }
+}
+
+export function harEntriesToRawRequests(entries: KuriHarEntry[], baseUrl?: string): RawRequest[] {
+  return entries
+    .filter((entry) => entry.request && entry.response)
+    .map((entry) => ({
+      url: normalizeBrowseUrl(entry.request.url, baseUrl),
+      method: entry.request.method,
+      request_headers: Object.fromEntries((entry.request.headers ?? []).map((header) => [header.name.toLowerCase(), header.value])),
+      request_body: entry.request.postData?.text,
+      response_status: entry.response.status,
+      response_headers: Object.fromEntries((entry.response.headers ?? []).map((header) => [header.name.toLowerCase(), header.value])),
+      response_body: entry.response.content?.text,
+      timestamp: entry.startedDateTime ?? new Date().toISOString(),
+    }));
+}
+
+export function buildBrowseRequestKey(request: RawRequest): string {
+  return [
+    request.method,
+    request.url,
+    typeof request.request_body === "string" ? request.request_body : JSON.stringify(request.request_body ?? null),
+  ].join(":");
+}
+
+export function mergeBrowseRequests(intercepted: RawRequest[], harEntries: KuriHarEntry[], baseUrl?: string): RawRequest[] {
+  const normalizedIntercepted = intercepted.map((request) => ({
+    ...request,
+    url: normalizeBrowseUrl(request.url, baseUrl),
+  }));
+  const harRequests = harEntriesToRawRequests(harEntries, baseUrl);
+  const seen = new Set<string>();
+  const allRequests: RawRequest[] = [];
+
+  for (const request of normalizedIntercepted) {
+    const key = buildBrowseRequestKey(request);
+    if (!seen.has(key)) {
+      seen.add(key);
+      allRequests.push(request);
+    }
+  }
+
+  for (const request of harRequests) {
+    const key = buildBrowseRequestKey(request);
+    if (!seen.has(key)) {
+      seen.add(key);
+      allRequests.push(request);
+    }
+  }
+
+  return allRequests;
+}
+
+export interface BrowseIndexResult {
+  domain: string;
+  indexed: boolean;
+  mode: "http" | "dom" | "none";
+  skill: SkillManifest | null;
+}
+
+export async function cacheBrowseRequests(params: {
+  sessionUrl: string;
+  sessionDomain: string;
+  requests: RawRequest[];
+  getPageHtml?: () => Promise<string>;
+}): Promise<BrowseIndexResult> {
+  const { sessionUrl, sessionDomain, requests, getPageHtml } = params;
+  let domain: string;
+  try { domain = new URL(sessionUrl).hostname; } catch { domain = sessionDomain; }
+
+  const rawEndpoints = extractEndpoints(requests, undefined, { pageUrl: sessionUrl, finalUrl: sessionUrl });
+  if (rawEndpoints.length > 0) {
+    const existingSkill = findExistingSkillForDomain(domain);
+    let allExisting = existingSkill?.endpoints ?? [];
+
+    const domainKey = getDomainReuseKey(sessionUrl ?? domain);
+    if (domainKey) {
+      const cached = domainSkillCache.get(domainKey);
+      if (cached?.localSkillPath) {
+        try {
+          const snapshot = JSON.parse(readFileSync(cached.localSkillPath, "utf-8"));
+          if (snapshot?.endpoints?.length > 0) {
+            allExisting = mergeEndpoints(allExisting, snapshot.endpoints);
+          }
+        } catch {
+          // ignore stale snapshot
+        }
+      }
+    }
+
+    const mergedEndpoints = allExisting.length > 0 ? mergeEndpoints(allExisting, rawEndpoints) : rawEndpoints;
+    if (!existingSkill || mergedEndpoints.length >= existingSkill.endpoints.length) {
+      for (const endpoint of mergedEndpoints) {
+        if (!endpoint.description) endpoint.description = generateLocalDescription(endpoint);
+      }
+
+      const quickSkill: SkillManifest = {
+        skill_id: existingSkill?.skill_id ?? nanoid(),
+        version: "1.0.0",
+        schema_version: "1",
+        lifecycle: "active",
+        execution_type: "http",
+        created_at: existingSkill?.created_at ?? new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        name: domain,
+        intent_signature: `browse ${domain}`,
+        domain,
+        description: `API skill for ${domain}`,
+        owner_type: "agent",
+        endpoints: mergedEndpoints,
+        operation_graph: buildSkillOperationGraph(mergedEndpoints),
+        intents: Array.from(new Set([...(existingSkill?.intents ?? []), `browse ${domain}`])),
+      };
+
+      const cacheKey = buildResolveCacheKey(domain, `browse ${domain}`, sessionUrl);
+      const scopedKey = scopedCacheKey("global", cacheKey);
+      writeSkillSnapshot(scopedKey, quickSkill);
+      if (domainKey) {
+        domainSkillCache.set(domainKey, {
+          skillId: quickSkill.skill_id,
+          localSkillPath: snapshotPathForCacheKey(scopedKey),
+          ts: Date.now(),
+        });
+        persistDomainCache();
+      }
+      try { cachePublishedSkill(quickSkill); } catch {}
+      upsertDagEdgesFromOperationGraph(quickSkill);
+      invalidateRouteCacheForDomain(domain);
+      return { domain, indexed: true, mode: "http", skill: quickSkill };
+    }
+
+    return { domain, indexed: false, mode: "http", skill: existingSkill ?? null };
+  }
+
+  if (!getPageHtml) return { domain, indexed: false, mode: "none", skill: null };
+
+  try {
+    const html = await getPageHtml();
+    if (!html || !html.startsWith("<")) return { domain, indexed: false, mode: "none", skill: null };
+
+    const { extractFromDOM } = await import("../extraction/index.js");
+    const { detectSearchForms, isStructuredSearchForm } = await import("../execution/search-forms.js");
+    const { inferSchema } = await import("../transform/index.js");
+    const { templatizeQueryParams } = await import("../execution/index.js");
+
+    const extracted = extractFromDOM(html, `browse ${domain}`);
+    const searchForms = detectSearchForms(html);
+    const validForm = searchForms.find((form: { form_selector: string; fields: unknown[] }) => isStructuredSearchForm(form));
+
+    if (!extracted.data && !validForm) return { domain, indexed: false, mode: "none", skill: null };
+
+    const urlTemplate = templatizeQueryParams(sessionUrl);
+    const endpoint: EndpointDescriptor = {
+      endpoint_id: nanoid(),
+      method: "GET",
+      url_template: urlTemplate,
+      idempotency: "safe",
+      verification_status: "verified",
+      reliability_score: extracted.confidence ?? 0.7,
+      description: validForm ? `Search form for ${domain}` : `Page content from ${domain}`,
+      response_schema: extracted.data ? inferSchema([extracted.data]) : undefined,
+      dom_extraction: {
+        extraction_method: extracted.extraction_method ?? "repeated-elements",
+        confidence: extracted.confidence ?? 0.7,
+        ...(extracted.selector ? { selector: extracted.selector } : {}),
+      },
+      trigger_url: sessionUrl,
+      ...(validForm ? { search_form: validForm } : {}),
+    };
+
+    endpoint.semantic = inferEndpointSemantic(endpoint, {
+      sampleResponse: extracted.data,
+      observedAt: new Date().toISOString(),
+      sampleRequestUrl: sessionUrl,
+    });
+
+    const existing = findExistingSkillForDomain(domain);
+    const allEndpoints = existing ? mergeEndpoints(existing.endpoints, [endpoint]) : [endpoint];
+    for (const candidate of allEndpoints) {
+      if (!candidate.description) candidate.description = generateLocalDescription(candidate);
+    }
+
+    const skill: SkillManifest = {
+      skill_id: existing?.skill_id ?? nanoid(),
+      version: "1.0.0",
+      schema_version: "1",
+      lifecycle: "active",
+      execution_type: "http",
+      created_at: existing?.created_at ?? new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      name: domain,
+      intent_signature: `browse ${domain}`,
+      domain,
+      description: `DOM skill for ${domain}`,
+      owner_type: "agent",
+      endpoints: allEndpoints,
+      operation_graph: buildSkillOperationGraph(allEndpoints),
+      intents: [...new Set([...(existing?.intents ?? []), `browse ${domain}`])],
+    };
+
+    const cacheKey = buildResolveCacheKey(domain, `browse ${domain}`, sessionUrl);
+    const scopedKey = scopedCacheKey("global", cacheKey);
+    writeSkillSnapshot(scopedKey, skill);
+    const domainReuseKey = getDomainReuseKey(sessionUrl ?? domain);
+    if (domainReuseKey) {
+      domainSkillCache.set(domainReuseKey, {
+        skillId: skill.skill_id,
+        localSkillPath: snapshotPathForCacheKey(scopedKey),
+        ts: Date.now(),
+      });
+      persistDomainCache();
+    }
+    try { cachePublishedSkill(skill); } catch {}
+    upsertDagEdgesFromOperationGraph(skill);
+    invalidateRouteCacheForDomain(domain);
+    return { domain, indexed: true, mode: "dom", skill };
+  } catch {
+    return { domain, indexed: false, mode: "none", skill: null };
+  }
+}

package/runtime-src/api/browse-session.ts

@@ -0,0 +1,177 @@
+import { getKuriErrorMessage } from "../kuri/client.js";
+
+export interface BrowseSession {
+  tabId: string;
+  url: string;
+  harActive: boolean;
+  domain: string;
+}
+
+export interface BrowseTabRef {
+  id: string;
+  url?: string;
+}
+
+export interface BrowseSessionClient {
+  start(): Promise<void>;
+  newTab(): Promise<string>;
+  harStart(tabId: string): Promise<void>;
+  closeTab(tabId: string): Promise<void>;
+  discoverTabs(): Promise<BrowseTabRef[]>;
+  getCurrentUrl(tabId: string): Promise<string>;
+}
+
+const RECOVERABLE_BROWSE_FAILURES = [
+  "cdp command failed",
+  "transport closed",
+  "target closed",
+  "tab not found",
+  "session closed",
+  "execution context was destroyed",
+  "cannot find context with specified id",
+  "no such target",
+];
+
+export function extractBrowseFailureMessage(value: unknown): string | null {
+  return typeof value === "string" ? value : getKuriErrorMessage(value);
+}
+
+export function isRecoverableBrowseFailure(value: unknown): boolean {
+  const message = extractBrowseFailureMessage(value);
+  if (!message) return false;
+  const normalized = message.toLowerCase();
+  return RECOVERABLE_BROWSE_FAILURES.some((needle) => normalized.includes(needle));
+}
+
+async function createBrowseSession(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  injectInterceptor: (tabId: string) => Promise<unknown>,
+): Promise<BrowseSession> {
+  await client.start().catch(() => {});
+  const tabId = await client.newTab();
+  await client.harStart(tabId).catch(() => {});
+  await injectInterceptor(tabId);
+  const session: BrowseSession = { tabId, url: "about:blank", harActive: true, domain: "" };
+  sessions.set("default", session);
+  return session;
+}
+
+function extractDomain(url: string | undefined): string {
+  if (!url) return "";
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return "";
+  }
+}
+
+async function adoptExistingBrowseTab(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  injectInterceptor: (tabId: string) => Promise<unknown>,
+  preferredDomain?: string,
+): Promise<BrowseSession | null> {
+  try {
+    const tabs = await client.discoverTabs();
+    const normalizedPreferred = preferredDomain?.replace(/^www\./, "") ?? "";
+    const candidate =
+      tabs.find((tab) => {
+        const domain = extractDomain(tab.url);
+        return !!domain && !!normalizedPreferred && domain === normalizedPreferred;
+      }) ??
+      tabs.find((tab) => /^https?:\/\//.test(tab.url ?? ""));
+
+    if (!candidate?.id) return null;
+    await client.harStart(candidate.id).catch(() => {});
+    await injectInterceptor(candidate.id);
+    const session: BrowseSession = {
+      tabId: candidate.id,
+      url: candidate.url ?? "about:blank",
+      harActive: true,
+      domain: extractDomain(candidate.url),
+    };
+    sessions.set("default", session);
+    return session;
+  } catch {
+    return null;
+  }
+}
+
+async function dropBrowseSession(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  session: BrowseSession | undefined,
+): Promise<void> {
+  if (!session) return;
+  await client.closeTab(session.tabId).catch(() => {});
+  if (sessions.get("default")?.tabId === session.tabId) {
+    sessions.delete("default");
+  }
+}
+
+export async function isBrowseSessionLive(
+  session: BrowseSession,
+  client: BrowseSessionClient,
+): Promise<boolean> {
+  if (!session.tabId) return false;
+
+  try {
+    const tabs = await client.discoverTabs();
+    if (!tabs.some((tab) => tab.id === session.tabId)) return false;
+    const currentUrl = await client.getCurrentUrl(session.tabId);
+    return typeof currentUrl === "string" && currentUrl.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function resetBrowseSession(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  injectInterceptor: (tabId: string) => Promise<unknown>,
+): Promise<BrowseSession> {
+  const existing = sessions.get("default");
+  const preferredDomain = existing?.domain || extractDomain(existing?.url);
+  await dropBrowseSession(sessions, client, existing);
+  const adopted = await adoptExistingBrowseTab(sessions, client, injectInterceptor, preferredDomain);
+  if (adopted) return adopted;
+  return createBrowseSession(sessions, client, injectInterceptor);
+}
+
+export async function getOrCreateBrowseSession(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  injectInterceptor: (tabId: string) => Promise<unknown>,
+): Promise<BrowseSession> {
+  const existing = sessions.get("default");
+  if (existing && await isBrowseSessionLive(existing, client)) return existing;
+  const preferredDomain = existing?.domain || extractDomain(existing?.url);
+  if (existing) await dropBrowseSession(sessions, client, existing);
+  const adopted = await adoptExistingBrowseTab(sessions, client, injectInterceptor, preferredDomain);
+  if (adopted) return adopted;
+  return createBrowseSession(sessions, client, injectInterceptor);
+}
+
+export async function withRecoveredBrowseSession<T>(
+  sessions: Map<string, BrowseSession>,
+  client: BrowseSessionClient,
+  injectInterceptor: (tabId: string) => Promise<unknown>,
+  run: (session: BrowseSession) => Promise<T>,
+  shouldReset?: (result: T) => boolean,
+): Promise<{ session: BrowseSession; result: T; recovered: boolean }> {
+  let session = await getOrCreateBrowseSession(sessions, client, injectInterceptor);
+
+  try {
+    const result = await run(session);
+    if (!shouldReset || !shouldReset(result)) {
+      return { session, result, recovered: false };
+    }
+  } catch (error) {
+    if (!isRecoverableBrowseFailure(error)) throw error;
+  }
+
+  session = await resetBrowseSession(sessions, client, injectInterceptor);
+  const result = await run(session);
+  return { session, result, recovered: true };
+}