mcp-scraper 0.65.1 → 0.66.1

package/dist/bin/api-server.cjs

@@ -46,7 +46,7 @@ var init_harvest_timeout = __esm({
   "src/harvest-timeout.ts"() {
     "use strict";
     SCRAPE_FUNCTION_MAX_MS = 8e5;
-    DEFAULT_TOOL_CLIENT_TIMEOUT_MS = 3e5;
+    DEFAULT_TOOL_CLIENT_TIMEOUT_MS = 59e4;
     CLIENT_OVER_SERVER_MARGIN_MS = 15e3;
   }
 });
@@ -186,8 +186,9 @@ function publicErrorMessage(code) {
     case "proxy_unavailable":
       return "The web request could not establish a working connection. Please retry later.";
     case "harvest_timeout":
-    case "mcp_request_timeout":
       return "The request timed out before it completed. Please retry with a smaller request.";
+    case "mcp_request_timeout":
+      return "The MCP caller stopped waiting before a final response arrived. Durable work may still be running; continue with the returned Task or job handle instead of restarting it.";
     case "concurrency_limit_exceeded":
       return "The service is available, but this account has reached its parallel-operation limit. Wait for an active operation to finish or add capacity.";
     case "unauthorized":
@@ -16552,7 +16553,7 @@ var init_site_extract_repository = __esm({
 
 // src/api/vendor-errors.ts
 function isVendorUnavailableError(err, message) {
-  return err instanceof import_sdk5.AuthenticationError || err instanceof import_sdk5.PermissionDeniedError || err instanceof import_sdk5.APIConnectionError || err instanceof import_sdk5.APIConnectionTimeoutError || err instanceof import_sdk5.InternalServerError || message === BRIGHTDATA_NOT_CONFIGURED_MESSAGE;
+  return err instanceof import_sdk5.AuthenticationError || err instanceof import_sdk5.PermissionDeniedError || err instanceof import_sdk5.APIConnectionError || err instanceof import_sdk5.APIConnectionTimeoutError || err instanceof import_sdk5.InternalServerError || /^401\s+Invalid or disabled API key\s*$/i.test(message.trim()) || message === BRIGHTDATA_NOT_CONFIGURED_MESSAGE;
 }
 var import_sdk5, BRIGHTDATA_NOT_CONFIGURED_MESSAGE;
 var init_vendor_errors = __esm({
@@ -27069,6 +27070,19 @@ async function acquireConcurrencyGate(user, operation, options = {}) {
   if (Number(res.rowsAffected ?? 0) > 0) {
     return { ok: true, lockId, active, limit, operation };
   }
+  await logRequestEvent({
+    userId: user.id,
+    source: "concurrency_gate",
+    status: "failed",
+    query: operation,
+    result: { active, limit },
+    error: "concurrency_limit_exceeded"
+  }).catch((error) => {
+    console.error("[concurrency-gate] rejection telemetry failed", {
+      operation,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  });
   return { ok: false, active, limit, operation, retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS };
 }
 async function releaseConcurrencyGate(lockId) {
@@ -29195,6 +29209,9 @@ function classifyAttemptError(err) {
   if (err instanceof RequestAbortedError) return "request_aborted";
   if (err instanceof DOMException && (err.name === "TimeoutError" || err.name === "AbortError")) return "timeout";
   const message = err instanceof Error ? err.message : String(err);
+  if (/browser (?:has been )?closed|context (?:has been )?closed|target page, context or browser has been closed|session closed|page has been closed/i.test(message)) {
+    return "browser_session_interrupted";
+  }
   if (looksLikeProxyTunnelFailure2(message)) return "proxy_tunnel_failed";
   if (looksLikeProxyUnavailable2(message)) return "proxy_unavailable";
   return /timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message) ? "timeout" : "error";
@@ -29242,6 +29259,9 @@ function looksLikeProxyUnavailable2(message) {
 function retryableLocationProxyError(outcome) {
   return outcome === "captcha" || outcome === "proxy_tunnel_failed" || outcome === "proxy_unavailable";
 }
+function retryableFreshBrowserError(outcome) {
+  return outcome === "browser_session_interrupted";
+}
 function locationMismatchMessage(result) {
   const evidence = result.diagnostics.debug?.locationEvidence;
   const expected = evidence?.expected?.canonicalLocation ?? result.location ?? "requested location";
@@ -29425,7 +29445,7 @@ async function harvest(rawOptions) {
           proxyFailures++;
           if (proxyFailures >= 2) effectiveProxyMode = "none";
         }
-        const willRetry2 = i < maxAttempts - 1 && (outcome2 === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome2));
+        const willRetry2 = i < maxAttempts - 1 && (outcome2 === "captcha" || retryableFreshBrowserError(outcome2) || proxyMode === "location" && retryableLocationProxyError(outcome2));
         if (outcome2 === "captcha") {
           console.warn(JSON.stringify({
             event: "harvest_attempt_captcha",
@@ -29543,7 +29563,7 @@ async function harvest(rawOptions) {
         proxyFailures++;
         if (proxyFailures >= 2) effectiveProxyMode = "none";
       }
-      const willRetry = i < maxAttempts - 1 && (outcome === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome));
+      const willRetry = i < maxAttempts - 1 && (outcome === "captcha" || retryableFreshBrowserError(outcome) || proxyMode === "location" && retryableLocationProxyError(outcome));
       if (outcome === "captcha") {
         console.warn(JSON.stringify({
           event: "harvest_attempt_captcha",
@@ -29781,7 +29801,7 @@ function businessWords(value) {
   return tokens2;
 }
 function cleanName(value) {
-  return value.replace(/^(?:Mr\.?|Ms\.?|Mrs\.?|Dr\.?)\s+/i, "").replace(/\s+/g, " ").trim();
+  return value.replace(/^(?:Mr\.?|Ms\.?|Mrs\.?|Dr\.?)\s+/i, "").replace(/[.!?]\s+.*$/, "").replace(/[.,;:!?]+$/, "").replace(/\s+/g, " ").trim();
 }
 function plausibleName(value, businessName) {
   const tokens2 = words(value);
@@ -29798,6 +29818,8 @@ function relationshipFor(role) {
   return "team_member";
 }
 function normalizedRole(role) {
+  if (/founded/i.test(role)) return "Founder";
+  if (/owned/i.test(role)) return "Owner";
   return compact2(role, 80).replace(/\bceo\b/i, "CEO").replace(/\b\w/g, (letter) => letter.toUpperCase());
 }
 function resultContext(result) {
@@ -29810,24 +29832,80 @@ function orderedResults(results) {
     return a - b || left.index - right.index;
   }).map((item) => item.result);
 }
+function publicHttpUrl(value) {
+  if (!value) return null;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
 function quoted(value) {
   return `"${value.replace(/["\\]/g, " ").replace(/\s+/g, " ").trim()}"`;
 }
-function buildAssociatedPeopleQuery(input) {
-  const roles = input.mode === "owners" ? 'owner founder "managing member" president' : "owner founder president manager leadership team";
-  return [quoted(input.businessName), roles, compact2(input.location ?? "", 120)].filter(Boolean).join(" ");
+function queryValue(value) {
+  return compact2(value ?? "", 120).replace(/["\\]/g, " ");
+}
+function defaultQueryTemplate(mode) {
+  return mode === "owners" ? '"{business}" owner of company {location}' : '"{business}" leadership team {location}';
+}
+function buildAssociatedPeopleQueries(input) {
+  const values = {
+    business: queryValue(input.businessName),
+    city: queryValue(input.city),
+    region: queryValue(input.region),
+    location: queryValue(input.location)
+  };
+  const queries = (input.queryTemplates?.length ? input.queryTemplates : [defaultQueryTemplate(input.mode)]).map((template) => compact2(template.replace(/\{(business|city|region|location)\}/g, (_match, key) => values[key]), 240)).filter(Boolean);
+  return [...new Set(queries)].slice(0, 3);
 }
 function buildLinkedInPersonQuery(input) {
   return `site:linkedin.com/in ${quoted(input.personName)} ${quoted(input.businessName)}`;
 }
 function extractAssociatedPeopleEvidence(input) {
   const accepted = /* @__PURE__ */ new Map();
+  const documents = [];
+  const overviewText = input.aiOverview?.detected ? compact2(input.aiOverview.text ?? "") : "";
+  if (overviewText) {
+    const searchUrl = publicHttpUrl(input.aiOverview?.shareUrl) ?? (input.query ? `https://www.google.com/search?q=${encodeURIComponent(input.query)}` : "https://www.google.com/");
+    const citationUrls = (input.aiOverview?.citations ?? []).flatMap((citation) => {
+      try {
+        const parsed = new URL(citation.href);
+        return ["http:", "https:"].includes(parsed.protocol) ? [parsed.href] : [];
+      } catch {
+        return [];
+      }
+    }).slice(0, 5);
+    documents.push({
+      sourceType: "ai_overview",
+      sourceUrl: searchUrl,
+      sourceTitle: "Google AI Overview",
+      sourcePosition: 0,
+      context: overviewText,
+      ...citationUrls.length ? { citationUrls } : {}
+    });
+  }
   for (const result of orderedResults(input.results)) {
-    const context = resultContext(result);
+    documents.push({
+      sourceType: "serp_snippet",
+      sourceUrl: result.url,
+      sourceTitle: result.title,
+      sourcePosition: result.position,
+      context: resultContext(result)
+    });
+  }
+  for (const document2 of documents) {
+    const context = document2.context;
     if (!containsBusiness(context, input.businessName)) continue;
+    const disambiguatingPlace = input.city || (input.location ?? "").split(",")[0] || "";
+    const locationTokens = words(disambiguatingPlace).filter((token6) => token6.length > 2);
+    const locationMatched = locationTokens.some((token6) => words(context).includes(token6));
+    if (document2.sourceType === "ai_overview" && locationTokens.length && !locationMatched) continue;
     const matches = [];
     for (const match of context.matchAll(new RegExp(NAME_THEN_ROLE_SOURCE, "giu"))) matches.push({ name: match[1] ?? "", role: match[2] ?? "" });
     for (const match of context.matchAll(new RegExp(ROLE_THEN_NAME_SOURCE, "giu"))) matches.push({ name: match[2] ?? "", role: match[1] ?? "" });
+    for (const match of context.matchAll(new RegExp(PASSIVE_ROLE_THEN_NAME_SOURCE, "giu"))) matches.push({ name: match[2] ?? "", role: match[1] ?? "" });
     for (const match of matches) {
       const name = cleanName(match.name);
       const role = normalizedRole(match.role);
@@ -29835,22 +29913,36 @@ function extractAssociatedPeopleEvidence(input) {
       const relationship = relationshipFor(role);
       if (input.mode === "owners" && relationship !== "owner" && relationship !== "founder") continue;
       const key = words(name).join(" ");
-      if (!key || accepted.has(key)) continue;
+      if (!key) continue;
+      const source = {
+        sourceType: document2.sourceType,
+        purpose: "role",
+        sourceUrl: document2.sourceUrl,
+        sourceTitle: document2.sourceTitle,
+        sourcePosition: document2.sourcePosition,
+        context,
+        ...document2.citationUrls ? { citationUrls: document2.citationUrls } : {}
+      };
+      const existing = accepted.get(key);
+      if (existing) {
+        if (existing.sources.length < 2 && !existing.sources.some((item) => item.sourceUrl === source.sourceUrl)) existing.sources.push(source);
+        existing.reasons = [.../* @__PURE__ */ new Set([...existing.reasons, "multiple_search_sources"])];
+        existing.confidence = Math.max(existing.confidence, document2.sourceType === "ai_overview" ? locationMatched ? 0.93 : 0.9 : 0.88);
+        continue;
+      }
+      const aiOverview = document2.sourceType === "ai_overview";
       accepted.set(key, {
         name,
         role,
         relationship,
         linkedinUrl: null,
-        confidence: 0.88,
-        reasons: ["name_role_in_search_result", "exact_business_query_context"],
-        sources: [{
-          sourceType: "serp_snippet",
-          purpose: "role",
-          sourceUrl: result.url,
-          sourceTitle: result.title,
-          sourcePosition: result.position,
-          context
-        }]
+        confidence: aiOverview ? locationMatched ? 0.93 : 0.9 : 0.88,
+        reasons: [
+          aiOverview ? "name_role_in_ai_overview" : "name_role_in_search_result",
+          "exact_business_query_context",
+          ...aiOverview && locationMatched ? ["ai_overview_location_match"] : []
+        ],
+        sources: [source]
       });
       if (accepted.size >= MAX_CANDIDATES) return [...accepted.values()];
     }
@@ -29906,7 +29998,7 @@ function attachLinkedInProfile(input) {
   }
   return input.person;
 }
-var MAX_CONTEXT_CHARS3, MAX_CANDIDATES, ROLE, NAME, NAME_THEN_ROLE_SOURCE, ROLE_THEN_NAME_SOURCE, NAME_STOP_WORDS, LEGAL_SUFFIXES;
+var MAX_CONTEXT_CHARS3, MAX_CANDIDATES, ROLE, NAME, NAME_THEN_ROLE_SOURCE, ROLE_THEN_NAME_SOURCE, PASSIVE_ROLE_THEN_NAME_SOURCE, NAME_STOP_WORDS, LEGAL_SUFFIXES;
 var init_serp_people_evidence = __esm({
   "src/leads/serp-people-evidence.ts"() {
     "use strict";
@@ -29934,7 +30026,8 @@ var init_serp_people_evidence = __esm({
     ].join("|");
     NAME = String.raw`(?:Mr\.?|Ms\.?|Mrs\.?|Dr\.?)?\s*([\p{Lu}][\p{L}'’.-]+(?:\s+[\p{Lu}][\p{L}'’.-]+){1,3})`;
     NAME_THEN_ROLE_SOURCE = `${NAME}\\s*(?:,|[-\u2013\u2014]|\\bis\\b|\\bas\\b|\\bserves as\\b)?\\s*(${ROLE})\\b`;
-    ROLE_THEN_NAME_SOURCE = `\\b(${ROLE})\\b\\s*(?:[,:\u2013\u2014-]|\\bis\\b|\\bof\\b)\\s*${NAME}`;
+    ROLE_THEN_NAME_SOURCE = `\\b(${ROLE})\\b\\s*(?:[,:\u2013\u2014-]|\\bis\\b|\\bof\\b)?\\s*${NAME}`;
+    PASSIVE_ROLE_THEN_NAME_SOURCE = `\\b((?:co[- ]?)?owned|founded)\\s+by\\s+${NAME}`;
     NAME_STOP_WORDS = /* @__PURE__ */ new Set([
       "about",
       "additional",
@@ -29971,7 +30064,7 @@ function privateIpv4(hostname) {
   if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
   return parts[0] === 10 || parts[0] === 127 || parts[0] === 169 && parts[1] === 254 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168 || parts[0] === 0;
 }
-function publicHttpUrl(value) {
+function publicHttpUrl2(value) {
   if (!value) return null;
   try {
     const parsed = new URL(value);
@@ -30039,8 +30132,8 @@ function normalizeLeadRows(input) {
     if (!name) throw new Error(`Row ${ordinal + 1} requires a non-empty name`);
     const websiteRaw = mappedValue(source, columnMap.websiteUrl);
     const profileRaw = mappedValue(source, columnMap.profileUrl);
-    const websiteUrl = websiteRaw ? publicHttpUrl(websiteRaw) : null;
-    const profileUrl = profileRaw ? publicHttpUrl(profileRaw) : null;
+    const websiteUrl = websiteRaw ? publicHttpUrl2(websiteRaw) : null;
+    const profileUrl = profileRaw ? publicHttpUrl2(profileRaw) : null;
     if (websiteRaw && !websiteUrl || profileRaw && !profileUrl) throw new Error(`Row ${ordinal + 1} URL must be a public HTTP(S) URL`);
     const location2 = mappedValue(source, columnMap.location);
     const city = mappedValue(source, columnMap.city);
@@ -30147,6 +30240,9 @@ function rankIdentityCandidates(row, candidates) {
 function serpResults(response) {
   return Array.isArray(response) ? response : response.organicResults;
 }
+function peopleSerpEvidence(response) {
+  return Array.isArray(response) ? { organicResults: response } : response;
+}
 async function discoverAssociatedPeople(input) {
   if (input.options.peopleDiscovery === "off") return [];
   if (input.mapped.entityType !== "business") {
@@ -30160,23 +30256,42 @@ async function discoverAssociatedPeople(input) {
   const searchPeopleSerp = input.adapters.searchPeopleSerp;
   const mode = input.options.peopleDiscovery;
   const location2 = combineLocation(input.mapped.location, input.mapped.city, input.mapped.region);
-  let candidates;
-  try {
-    const response = await searchPeopleSerp({
-      query: buildAssociatedPeopleQuery({ businessName: input.mapped.name, location: location2, mode }),
-      gl: input.options.gl,
-      hl: input.options.hl
-    });
-    input.usage.serpSearches += 1;
-    candidates = extractAssociatedPeopleEvidence({
-      businessName: input.mapped.name,
-      mode,
-      results: serpResults(response)
-    }).slice(0, input.options.maxPeoplePerLead);
-  } catch {
-    input.warnings.push("people_search_failed");
-    return [];
+  const queries = buildAssociatedPeopleQueries({
+    businessName: input.mapped.name,
+    location: location2,
+    city: input.mapped.city,
+    region: input.mapped.region,
+    mode,
+    queryTemplates: input.options.peopleQueryTemplates
+  });
+  const candidatesByName = /* @__PURE__ */ new Map();
+  let completedRoleSearches = 0;
+  for (const query of queries) {
+    try {
+      const response = await searchPeopleSerp({ query, gl: input.options.gl, hl: input.options.hl, includeAiOverview: true });
+      input.usage.serpSearches += 1;
+      completedRoleSearches += 1;
+      const evidence = peopleSerpEvidence(response);
+      for (const person of extractAssociatedPeopleEvidence({
+        businessName: input.mapped.name,
+        location: location2,
+        city: input.mapped.city,
+        query,
+        mode,
+        results: evidence.organicResults,
+        aiOverview: evidence.aiOverview
+      })) {
+        const key = person.name.toLocaleLowerCase("en-US");
+        if (!candidatesByName.has(key)) candidatesByName.set(key, person);
+        if (candidatesByName.size >= input.options.maxPeoplePerLead) break;
+      }
+      if (candidatesByName.size >= input.options.maxPeoplePerLead) break;
+    } catch {
+      input.warnings.push("people_search_failed");
+    }
   }
+  const candidates = [...candidatesByName.values()].slice(0, input.options.maxPeoplePerLead);
+  if (!completedRoleSearches) return [];
   if (!candidates.length) {
     input.warnings.push("people_not_found");
     return [];
@@ -30187,7 +30302,8 @@ async function discoverAssociatedPeople(input) {
       const response = await searchPeopleSerp({
         query: buildLinkedInPersonQuery({ personName: person.name, businessName: input.mapped.name }),
         gl: input.options.gl,
-        hl: input.options.hl
+        hl: input.options.hl,
+        includeAiOverview: false
       });
       input.usage.serpSearches += 1;
       people.push(attachLinkedInProfile({
@@ -30491,7 +30607,7 @@ function leadListOutputRows(results, sourceHeaders) {
     })
   };
 }
-var import_zod13, LeadScalarSchema, RESERVED_OUTPUT_PREFIX, MAX_ROWS, MAX_COLUMNS, MAX_CELL_BYTES, MAX_INLINE_BYTES, MAX_NORMALIZED_ARTIFACT_BYTES, LeadListRowsSchema, LeadColumnMapSchema, LeadListEnrichmentOptionsSchema, DEFAULT_HEADER_ALIASES, LEGAL_SUFFIXES2, LEAD_LIST_ENRICHED_HEADERS;
+var import_zod13, LeadScalarSchema, RESERVED_OUTPUT_PREFIX, MAX_ROWS, MAX_COLUMNS, MAX_CELL_BYTES, MAX_INLINE_BYTES, MAX_NORMALIZED_ARTIFACT_BYTES, LeadListRowsSchema, LeadColumnMapSchema, PEOPLE_QUERY_TEMPLATE_PLACEHOLDER, LeadPeopleQueryTemplateSchema, LeadPeopleQueryTemplatesSchema, LeadListEnrichmentOptionsSchema, DEFAULT_HEADER_ALIASES, LEGAL_SUFFIXES2, LEAD_LIST_ENRICHED_HEADERS;
 var init_lead_list_enrichment = __esm({
   "src/leads/lead-list-enrichment.ts"() {
     "use strict";
@@ -30527,6 +30643,9 @@ var init_lead_list_enrichment = __esm({
       email: import_zod13.z.string().min(1).optional(),
       entityType: import_zod13.z.string().min(1).optional()
     }).strict();
+    PEOPLE_QUERY_TEMPLATE_PLACEHOLDER = /\{(?:business|city|region|location)\}/g;
+    LeadPeopleQueryTemplateSchema = import_zod13.z.string().trim().min(1).max(240).refine((value) => !/[\r\n]/.test(value), "People query templates must be one line").refine((value) => value.includes("{business}"), "People query templates must include {business}").refine((value) => !/[{}]/.test(value.replace(PEOPLE_QUERY_TEMPLATE_PLACEHOLDER, "")), "People query templates may use only {business}, {city}, {region}, and {location}");
+    LeadPeopleQueryTemplatesSchema = import_zod13.z.array(LeadPeopleQueryTemplateSchema).min(1).max(3);
     LeadListEnrichmentOptionsSchema = import_zod13.z.object({
       resolveMissingUrls: import_zod13.z.boolean().default(true),
       defaultEntityType: import_zod13.z.enum(["business", "person"]).default("business"),
@@ -30536,6 +30655,7 @@ var init_lead_list_enrichment = __esm({
       concurrency: import_zod13.z.number().int().min(1).max(5).default(3),
       emailSearchFallback: import_zod13.z.enum(["off", "serp_snippets"]).default("off"),
       peopleDiscovery: import_zod13.z.enum(["off", "owners", "leadership"]).default("off"),
+      peopleQueryTemplates: LeadPeopleQueryTemplatesSchema.optional(),
       maxPeoplePerLead: import_zod13.z.number().int().min(1).max(3).default(2),
       outputFormats: import_zod13.z.array(import_zod13.z.enum(["csv", "xlsx"])).min(1).max(2).transform((values) => [...new Set(values)]).default(["csv", "xlsx"])
     }).strict();
@@ -31468,12 +31588,13 @@ function createLeadListEnrichmentAdapters(userId) {
       pages: 1,
       maxQuestions: 1,
       headless: true,
+      includeAiOverview: input.includeAiOverview === true,
       format: "json",
       outputDir: "/tmp/paa-output-api",
       kernelApiKey,
       proxyMode: DEFAULT_PROXY_MODE
     }));
-    return result.organicResults;
+    return result;
   };
   return {
     async mapsSearch(input) {
@@ -31506,8 +31627,13 @@ function createLeadListEnrichmentAdapters(userId) {
         contactEvidence: page.contactEvidence
       };
     },
-    searchEmailSerp: searchSerp,
-    searchPeopleSerp: searchSerp
+    async searchEmailSerp(input) {
+      return (await searchSerp(input)).organicResults;
+    },
+    async searchPeopleSerp(input) {
+      const result = await searchSerp(input);
+      return { organicResults: result.organicResults, aiOverview: result.aiOverview };
+    }
   };
 }
 function cancelledResult(row) {
@@ -31906,6 +32032,9 @@ function looksLikeProxyUnavailable3(message) {
 function looksLikeInternalServiceUnavailable(message) {
   return /(?:spending|billing|organization|account).{0,80}(?:cap|limit|blocked|disabled)|(?:quota|capacity).{0,40}(?:reached|exceeded)|https?:\/\/\S*dashboard/i.test(message);
 }
+function looksLikeBrowserSessionInterrupted(message) {
+  return /browser (?:has been )?closed|context (?:has been )?closed|target page, context or browser has been closed|session closed|page has been closed/i.test(message);
+}
 function classifyHarvestProblem(err) {
   const message = errorMessage4(err);
   if (err instanceof RequestAbortedError) {
@@ -31968,6 +32097,16 @@ function classifyHarvestProblem(err) {
       terminalStatus: "failed"
     };
   }
+  if (looksLikeBrowserSessionInterrupted(message)) {
+    return {
+      error_code: "browser_session_interrupted",
+      error_type: "extraction",
+      message: publicErrorMessage("browser_session_interrupted"),
+      retryable: true,
+      httpStatus: 503,
+      terminalStatus: "failed"
+    };
+  }
   if (looksLikeTimeout(err, message)) {
     return {
       error_code: "harvest_timeout",
@@ -45731,7 +45870,7 @@ var init_lead_list_enrichment_routes = __esm({
       if (!gate.ok) {
         return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       }
-      const holdMc = input.rows.length * ((input.options.resolveMissingUrls ? MC_COSTS.maps_search : 0) + input.options.maxPagesPerLead * MC_COSTS.page_scrape + (input.options.emailSearchFallback === "serp_snippets" ? MC_COSTS.serp_headful : 0) + (input.options.peopleDiscovery === "off" ? 0 : (1 + input.options.maxPeoplePerLead) * MC_COSTS.serp_headful));
+      const holdMc = input.rows.length * ((input.options.resolveMissingUrls ? MC_COSTS.maps_search : 0) + input.options.maxPagesPerLead * MC_COSTS.page_scrape + (input.options.emailSearchFallback === "serp_snippets" ? MC_COSTS.serp_headful : 0) + (input.options.peopleDiscovery === "off" ? 0 : ((input.options.peopleQueryTemplates?.length ?? 1) + input.options.maxPeoplePerLead) * MC_COSTS.serp_headful));
       let creation;
       try {
         creation = await createOrGetLeadListEnrichmentJob({
@@ -49709,6 +49848,7 @@ var init_schemas4 = __esm({
       "location_mismatch",
       "proxy_tunnel_failed",
       "proxy_unavailable",
+      "browser_session_interrupted",
       "mcp_unavailable",
       "error"
     ];
@@ -50397,7 +50537,7 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.65.1";
+    PACKAGE_VERSION = "0.66.1";
   }
 });
 
@@ -50570,7 +50710,7 @@ decide whether the site needs a login:**
 
 ## Workflows
 Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when the whole job is one of these:
-- Lead-list file bytes are unavailable to this MCP -> **lead_list_upload_start**. For CSV/TSV text or sheet/header inspection -> **lead_list_import**. For supplied mapped rows or an imported \`leadListId\` -> **lead_list_enrich**, then **lead_list_enrich_status**. Use its opt-in peopleDiscovery mode for owners, leadership, and company-matched LinkedIn profile candidates; do not manually open LinkedIn pages.
+- Lead-list file bytes are unavailable to this MCP -> **lead_list_upload_start**. For CSV/TSV text or sheet/header inspection -> **lead_list_import**. For supplied mapped rows or an imported \`leadListId\` -> **lead_list_enrich**, then **lead_list_enrich_status**. For owners or leadership, enable peopleDiscovery and author focused peopleQueryTemplates with one role intent per query; the tool reads AI Overview and organic evidence before company-matched LinkedIn candidates, so do not manually open LinkedIn pages.
 - Start without a supplied list, from a niche plus one market -> **workflow_run** with workflowId \`get-leads\`. For candidate-only Google Maps discovery -> **maps_search**.
 - Build a local business directory for a niche across a state/region -> **directory_workflow**.
 - Stand up a rank-tracking blueprint (database + cron + ingestion plan) -> **rank_tracker_workflow**.
@@ -52246,6 +52386,7 @@ var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
     import_zod45 = require("zod");
+    init_lead_list_enrichment();
     init_contracts();
     init_wayback_schemas();
     init_local_sourcebook_schema();
@@ -52605,8 +52746,9 @@ var init_mcp_tool_schemas = __esm({
       hl: import_zod45.z.string().trim().length(2).default("en").describe("Two-letter Google language code used only for missing-URL Maps resolution."),
       maxPagesPerLead: import_zod45.z.number().int().min(1).max(4).default(3).describe("Maximum public page extraction attempts per row, including its starting page."),
       emailSearchFallback: import_zod45.z.enum(["off", "serp_snippets"]).default("off").describe("Optional recovery after bounded page extraction finds no email. serp_snippets spends at most one current-rate SERP search per unresolved row and accepts only exact-domain email occurrences from result titles/snippets. These public occurrences do not verify deliverability or consent."),
-      peopleDiscovery: import_zod45.z.enum(["off", "owners", "leadership"]).default("off").describe("Optional associated-person recovery for business rows. owners finds explicit owners/founders; leadership also accepts role-bearing executives, managers, and team members. It performs one exact-business role search plus at most maxPeoplePerLead LinkedIn result searches, never opens LinkedIn pages, and returns provenance-bearing public candidates rather than verified employment."),
-      maxPeoplePerLead: import_zod45.z.number().int().min(1).max(3).default(2).describe("Maximum associated people retained and LinkedIn-searched per business row when peopleDiscovery is enabled. The maximum added SERP cost is one role search plus this many profile searches."),
+      peopleDiscovery: import_zod45.z.enum(["off", "owners", "leadership"]).default("off").describe("Optional associated-person recovery for business rows. owners finds explicit owners/founders; leadership also accepts role-bearing executives, managers, and team members. It searches AI Overview plus organic results, never opens LinkedIn pages, and returns provenance-bearing public candidates rather than verified employment."),
+      peopleQueryTemplates: LeadPeopleQueryTemplatesSchema.optional().describe("Ordered query templates the calling model should author when peopleDiscovery is enabled: use one role intent per template and the placeholders {business}, {city}, {region}, or {location}, for example {business} owner of company; one focused server fallback is used when omitted."),
+      maxPeoplePerLead: import_zod45.z.number().int().min(1).max(3).default(2).describe("Maximum associated people retained and LinkedIn-searched per business row when peopleDiscovery is enabled; maximum added SERP cost is peopleQueryTemplates length (or one fallback) plus one profile search per retained person."),
       concurrency: import_zod45.z.number().int().min(1).max(5).default(3).describe("Maximum rows enriched concurrently. Default 3; maximum 5."),
       outputFormats: import_zod45.z.array(import_zod45.z.enum(["csv", "xlsx"])).min(1).max(2).default(["csv", "xlsx"]).refine((values) => new Set(values).size === values.length, "outputFormats must be unique").describe("Unique requested result formats. Defaults to both CSV and XLSX; this changes rendering only.")
     };
@@ -53292,12 +53434,13 @@ var init_mcp_tool_schemas = __esm({
       serpMc: import_zod45.z.number().int().min(0).optional()
     });
     LeadAssociatedPersonSourceOutputSchema = import_zod45.z.object({
-      sourceType: import_zod45.z.literal("serp_snippet"),
+      sourceType: import_zod45.z.enum(["serp_snippet", "ai_overview"]),
       purpose: import_zod45.z.enum(["role", "linkedin"]),
       sourceUrl: import_zod45.z.string().url(),
       sourceTitle: import_zod45.z.string(),
-      sourcePosition: import_zod45.z.number().int().min(1),
-      context: import_zod45.z.string()
+      sourcePosition: import_zod45.z.number().int().min(0),
+      context: import_zod45.z.string(),
+      citationUrls: import_zod45.z.array(import_zod45.z.string().url()).max(5).optional()
     }).strict();
     LeadAssociatedPersonOutputSchema = import_zod45.z.object({
       name: import_zod45.z.string(),
@@ -53306,7 +53449,7 @@ var init_mcp_tool_schemas = __esm({
       linkedinUrl: NullableString,
       confidence: import_zod45.z.number().min(0).max(1),
       reasons: import_zod45.z.array(import_zod45.z.string()).max(10),
-      sources: import_zod45.z.array(LeadAssociatedPersonSourceOutputSchema).max(2)
+      sources: import_zod45.z.array(LeadAssociatedPersonSourceOutputSchema).max(3)
     }).strict();
     LeadSampleRowOutputSchema = import_zod45.z.object({
       people: import_zod45.z.array(LeadAssociatedPersonOutputSchema).max(3).optional()
@@ -55575,7 +55718,7 @@ function decodeTaskHandle(taskId, secret2, ownerId2) {
       decipher.update(ciphertext),
       decipher.final()
     ]).toString("utf8"));
-    if (parsed.v !== 1 || parsed.ownerId !== ownerId2 || !["site_export", "directory_workflow", "video_frame_analysis", "lead_list_enrichment"].includes(String(parsed.kind)) || typeof parsed.operationId !== "string" || !parsed.operationId || typeof parsed.createdAtMs !== "number" || typeof parsed.expiresAtMs !== "number") throw new Error("invalid payload");
+    if (parsed.v !== 1 || parsed.ownerId !== ownerId2 || !["paa_harvest", "site_export", "directory_workflow", "video_frame_analysis", "lead_list_enrichment"].includes(String(parsed.kind)) || typeof parsed.operationId !== "string" || !parsed.operationId || typeof parsed.createdAtMs !== "number" || typeof parsed.expiresAtMs !== "number") throw new Error("invalid payload");
     if (Date.now() > parsed.expiresAtMs) {
       throw new import_server.ProtocolError(TASK_INVALID_PARAMS, "Failed to retrieve task: Task has expired");
     }
@@ -55588,9 +55731,25 @@ function decodeTaskHandle(taskId, secret2, ownerId2) {
 function objectValue(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
-function taskSeed(kind, result) {
+function resultValue(result) {
   const structured = objectValue(result.structuredContent);
+  if (structured) return structured;
+  const block = result.content.find((item) => item.type === "text");
+  if (!block || block.type !== "text") return void 0;
+  try {
+    return objectValue(JSON.parse(block.text));
+  } catch {
+    return void 0;
+  }
+}
+function taskSeed(kind, result) {
+  const structured = resultValue(result);
   if (!structured || result.isError === true) return void 0;
+  if (kind === "paa_harvest") {
+    const operationId2 = structured.job_id ?? structured.jobId;
+    if (typeof operationId2 !== "string" || !["pending", "running"].includes(String(structured.status))) return void 0;
+    return { kind, operationId: operationId2, statusMessage: "PAA harvest started. Progress will be preserved while the client polls this Task." };
+  }
   if (kind === "site_export") {
     const operationId2 = structured.jobId;
     if (typeof operationId2 !== "string" || structured.status !== "pending") return void 0;
@@ -55621,10 +55780,13 @@ function taskBase(payload, taskId) {
   };
 }
 function statusFrom(result) {
-  const status = objectValue(result.structuredContent)?.status;
+  const status = resultValue(result)?.status;
   return typeof status === "string" ? status : void 0;
 }
 async function pollTask(executor, payload) {
+  if (payload.kind === "paa_harvest") {
+    return executor.harvestPaaStatus({ jobId: payload.operationId });
+  }
   if (payload.kind === "site_export") {
     return executor.checkSiteExport({ jobId: payload.operationId });
   }
@@ -55636,6 +55798,30 @@ async function pollTask(executor, payload) {
   }
   return executor.videoFrameAnalysisStatus({ runId: payload.operationId });
 }
+function taskProgressMessage(kind, result, status) {
+  const value = resultValue(result) ?? {};
+  if (kind === "paa_harvest") {
+    const resultRecord = objectValue(value.result) ?? {};
+    const progress = objectValue(resultRecord.progress) ?? {};
+    const records = Array.isArray(progress.records) ? progress.records.length : 0;
+    const attempts = Array.isArray(value.attempts) ? value.attempts.length : 0;
+    const pieces = [records > 0 ? `${records} questions preserved` : null, attempts > 0 ? `${attempts} attempts recorded` : null].filter(Boolean);
+    return pieces.length > 0 ? `PAA harvest is ${status ?? "running"}: ${pieces.join(", ")}.` : `PAA harvest is ${status ?? "running"}; no question checkpoint has been persisted yet.`;
+  }
+  if (kind === "lead_list_enrichment") {
+    const progress = objectValue(value.progress) ?? {};
+    const completed = typeof progress.completedRows === "number" ? progress.completedRows : null;
+    const total = typeof progress.totalRows === "number" ? progress.totalRows : null;
+    if (completed !== null && total !== null) return `Lead list enrichment is ${status ?? "running"}: ${completed}/${total} rows completed.`;
+  }
+  if (kind === "directory_workflow") {
+    const progress = objectValue(value.progress) ?? {};
+    const completed = typeof progress.completedCities === "number" ? progress.completedCities : null;
+    const total = typeof progress.totalCities === "number" ? progress.totalCities : null;
+    if (completed !== null && total !== null) return `Directory workflow is ${status ?? "running"}: ${completed}/${total} markets completed.`;
+  }
+  return status ? `Underlying operation status: ${status}.` : "Underlying operation is running.";
+}
 async function cancelTask(executor, payload) {
   if (payload.kind !== "lead_list_enrichment") return;
   const result = await executor.leadListEnrichCancel({ jobId: payload.operationId });
@@ -55652,7 +55838,7 @@ async function detailedTask(executor, taskId, options) {
     return {
       ...base,
       status: "working",
-      statusMessage: status ? `Underlying operation status: ${status}.` : "Underlying operation is running."
+      statusMessage: taskProgressMessage(payload.kind, result, status)
     };
   }
   if (payload.kind === "lead_list_enrichment" && status === "failed") {
@@ -55663,6 +55849,22 @@ async function detailedTask(executor, taskId, options) {
       result
     };
   }
+  if (payload.kind === "paa_harvest" && status === "failed") {
+    return {
+      ...base,
+      status: "failed",
+      statusMessage: "PAA harvest failed; persisted attempts and billing state are included in the result.",
+      result
+    };
+  }
+  if (payload.kind === "paa_harvest" && status === "cancelled") {
+    return {
+      ...base,
+      status: "cancelled",
+      statusMessage: "PAA harvest was cancelled.",
+      result
+    };
+  }
   if (payload.kind === "lead_list_enrichment" && status === "cancelled") {
     return {
       ...base,
@@ -55679,6 +55881,7 @@ async function detailedTask(executor, taskId, options) {
   };
 }
 function isWorking(kind, status) {
+  if (kind === "paa_harvest") return status === "pending" || status === "running";
   if (kind === "site_export") return status === "pending" || status === "running";
   if (kind === "directory_workflow") return status === "queued" || status === "running";
   if (kind === "lead_list_enrichment") return status === "queued" || status === "running";
@@ -55710,6 +55913,9 @@ function registerMcpTasksExtension(server, executor, options) {
     return {};
   });
   return {
+    supportsTasks() {
+      return hasTasksCapability(server.server.getClientCapabilities());
+    },
     taskify(kind, result) {
       if (!hasTasksCapability(server.server.getClientCapabilities())) return result;
       const seed = taskSeed(kind, result);
@@ -56266,7 +56472,12 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
     inputSchema: harvestPaaInputSchema,
     outputSchema: recordOutputSchema("harvest_paa", HarvestPaaOutputSchema),
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
-  }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
+  }, async (input, requestContext) => {
+    if (tasks.supportsTasks()) {
+      return tasks.taskify("paa_harvest", await executor.startHarvestPaa(input), requestContext);
+    }
+    return formatHarvestPaa(await executor.harvestPaa(input), input);
+  });
   server.registerTool("search_serp", {
     title: "Google SERP Lookup",
     description: `Google SERP lookup without PAA expansion. Defaults to organic rankings and Google entity IDs; request local pack, forums, videos, AI surfaces, and What People Are Saying with individual include flags or includeAllSerpFeatures at the same product price. Use gl for country and location only when city or regional context matters. Costs ${SERP_SEARCH_CREDITS} Credits per search. Call credits_info for current pricing and balance.`,
@@ -56744,7 +56955,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatLeadListImport(await executor.leadListImport(input)));
   server.registerTool("lead_list_enrich", {
     title: "Enrich a Lead List",
-    description: "Enrich 1\u2013250 mapped business or person rows, supplied inline or by leadListId, with matched public website, phone, email, social, contact-form, and optional associated-person evidence. Use when the list already exists; to inspect a file first use lead_list_import, to discover businesses from a niche plus city use workflow_run with get-leads, and for candidate-only Maps discovery use maps_search. Starts an owner-scoped durable Task, bills underlying Maps/page/SERP attempts with unused hold refunded, and retains requested CSV/XLSX results seven days. Opt-in email snippet recovery costs at most one SERP search per unresolved row. Opt-in peopleDiscovery costs one role search plus at most maxPeoplePerLead LinkedIn result searches per business row; it never opens LinkedIn pages and returns public role/profile candidates with separate provenance, not verified employment. Public email occurrence is not deliverability or consent verification and is not permission to contact. A public role or LinkedIn occurrence is not verified current employment. Reuse idempotencyKey only to retry the same intended job.",
+    description: "Enrich 1\u2013250 mapped business or person rows, supplied inline or by leadListId, with matched public website, phone, email, social, contact-form, and optional associated-person evidence. Use when the list already exists; to inspect a file first use lead_list_import, to discover businesses from a niche plus city use workflow_run with get-leads, and for candidate-only Maps discovery use maps_search. Starts an owner-scoped durable Task, bills underlying Maps/page/SERP attempts with unused hold refunded, and retains requested CSV/XLSX results seven days. Opt-in email snippet recovery costs at most one SERP search per unresolved row. For peopleDiscovery, author one-to-three focused peopleQueryTemplates with one role intent per query; each role query reads AI Overview plus organic results, then at most maxPeoplePerLead company-matched LinkedIn result searches run without opening LinkedIn pages. Public email occurrence is not deliverability or consent verification and is not permission to contact. A public role or LinkedIn occurrence is not verified current employment. Reuse idempotencyKey only to retry the same intended job.",
     inputSchema: LeadListEnrichInputSchema,
     outputSchema: recordOutputSchema("lead_list_enrich", LeadListEnrichmentOutputSchema),
     annotations: { title: "Enrich a Lead List", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
@@ -57267,7 +57478,7 @@ var init_http_mcp_tool_executor = __esm({
                   retryable: true,
                   path: path6,
                   timeoutMs,
-                  message: `MCP Scraper request exceeded ${Math.round(timeoutMs / 1e3)}s and was cancelled client-side. The operation may still be running or may have already completed and been billed on our side. Retry with fewer results or use the async API for deep harvests. ${timeoutGuidance}`
+                  message: `MCP Scraper stopped waiting after ${Math.round(timeoutMs / 1e3)}s. This does not prove server-side work stopped: the operation may still be running or may have already completed and been billed. Prefer the returned Task or job handle for long work. ${timeoutGuidance}`
                 })
               }],
               isError: true
@@ -57353,6 +57564,13 @@ var init_http_mcp_tool_executor = __esm({
         const headers = input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : {};
         return this.call("/harvest/sync", input, timeoutMs, "POST", headers, true);
       }
+      startHarvestPaa(input) {
+        const headers = input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : {};
+        return this.call("/harvest", input, this.timeoutMs, "POST", headers, true);
+      }
+      harvestPaaStatus(input) {
+        return this.getJson(`/jobs/${encodeURIComponent(input.jobId)}`);
+      }
       searchSerp(input) {
         const timeoutMs = this.httpTimeoutOverrideMs ?? harvestTimeoutBudget(0, true).clientMs;
         const headers = input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : {};
@@ -59585,6 +59803,1539 @@ var init_browser_agent_mcp_server = __esm({
   }
 });
 
+// src/mcp/memory-image-tool-schemas.generated.ts
+var MEMORY_IMAGE_TOOL_SCHEMAS;
+var init_memory_image_tool_schemas_generated = __esm({
+  "src/mcp/memory-image-tool-schemas.generated.ts"() {
+    "use strict";
+    MEMORY_IMAGE_TOOL_SCHEMAS = [
+      {
+        "id": "image_project_create",
+        "upstreamName": "image_project_create",
+        "description": "Create a stable image project inside a writable hosted Memory vault. Projects organize governed private image assets; they do not create local folders or change object keys.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string",
+              "description": "Writable logical Memory vault. Defaults to the active vault."
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            },
+            "description": {
+              "type": "string",
+              "maxLength": 2e3
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "project": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "createdAt": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name",
+                "description",
+                "createdAt"
+              ],
+              "additionalProperties": false
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Create Image Project",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_project_list",
+        "upstreamName": "image_project_list",
+        "description": "List image projects in an accessible hosted Memory vault. Returns organization metadata only, never object-store keys.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "projects": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "description": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "status": {
+                    "type": "string"
+                  },
+                  "createdAt": {
+                    "type": "string"
+                  },
+                  "updatedAt": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "name",
+                  "description",
+                  "status",
+                  "createdAt",
+                  "updatedAt"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "List Image Projects",
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_folder_create",
+        "upstreamName": "image_folder_create",
+        "description": "Create a nested image folder inside one writable Memory image project. Maximum nesting depth is eight; this changes logical organization only.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "projectId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "parentId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            }
+          },
+          "required": [
+            "projectId",
+            "name"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "folder": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "projectId": {
+                  "type": "string"
+                },
+                "parentId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "name": {
+                  "type": "string"
+                },
+                "depth": {
+                  "type": "number"
+                },
+                "createdAt": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "projectId",
+                "parentId",
+                "name",
+                "depth",
+                "createdAt"
+              ],
+              "additionalProperties": false
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Create Image Folder",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_folder_list",
+        "upstreamName": "image_folder_list",
+        "description": "List the bounded folder tree for one accessible Memory image project.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "projectId": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "projectId"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "folders": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "projectId": {
+                    "type": "string"
+                  },
+                  "parentId": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "depth": {
+                    "type": "number"
+                  },
+                  "createdAt": {
+                    "type": "string"
+                  },
+                  "updatedAt": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "projectId",
+                  "parentId",
+                  "name",
+                  "depth",
+                  "createdAt",
+                  "updatedAt"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "List Image Folders",
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_asset_save",
+        "upstreamName": "image_asset_save",
+        "description": "Opt in to preserving one image in hosted Memory. Saves immutable private bytes, creates a sanitized preview, consumes storage/embedding quota, and queues visual plus useful fused embeddings. Use for durable image recall; do not use merely to view a transient scrape result.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "projectId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "folderId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "sourceUrl": {
+              "type": "string",
+              "format": "uri",
+              "description": "Public HTTPS image URL. Private-network and redirect targets are rejected."
+            },
+            "artifactId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Owned MCP Scraper artifact ID. Available through the aggregate MCP handoff."
+            },
+            "imageBase64": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Bounded base64 image for clients without an upload transport; maximum decoded size is 20 MiB."
+            },
+            "title": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 240
+            },
+            "description": {
+              "type": "string",
+              "maxLength": 4e3
+            },
+            "altText": {
+              "type": "string",
+              "maxLength": 2e3
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80
+              },
+              "maxItems": 20
+            },
+            "sourceRef": {
+              "type": "object",
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "maxLength": 1e3
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "idempotencyKey": {
+              "type": "string",
+              "minLength": 8,
+              "maxLength": 200,
+              "description": "Stable key for this logical save. Retrying the same request returns the same asset without another write."
+            }
+          },
+          "required": [
+            "title",
+            "idempotencyKey"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "asset": {
+              "type": "object",
+              "properties": {
+                "assetId": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "altText": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceUrl": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceKind": {
+                  "type": "string"
+                },
+                "mimeType": {
+                  "type": "string"
+                },
+                "bytes": {
+                  "type": "number"
+                },
+                "width": {
+                  "type": "number"
+                },
+                "height": {
+                  "type": "number"
+                },
+                "projectId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "folderId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "status": {
+                  "type": "string"
+                },
+                "embeddingStatus": {
+                  "type": "string"
+                },
+                "createdAt": {
+                  "type": "string"
+                },
+                "updatedAt": {
+                  "type": "string"
+                },
+                "preview": {
+                  "type": "object",
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "format": "uri"
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "mimeType": {
+                      "type": "string",
+                      "const": "image/webp"
+                    }
+                  },
+                  "required": [
+                    "url",
+                    "expiresAt",
+                    "mimeType"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "assetId",
+                "title",
+                "description",
+                "altText",
+                "sourceUrl",
+                "sourceKind",
+                "mimeType",
+                "bytes",
+                "width",
+                "height",
+                "projectId",
+                "folderId",
+                "tags",
+                "status",
+                "embeddingStatus",
+                "createdAt",
+                "updatedAt"
+              ],
+              "additionalProperties": false
+            },
+            "reusedObject": {
+              "type": "boolean"
+            },
+            "nextAction": {
+              "type": "string"
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Save Image Asset",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      },
+      {
+        "id": "image_asset_get",
+        "upstreamName": "image_asset_get",
+        "description": "Read one authorized private image asset and optionally mint a five-minute preview URL. The URL is never persisted; call again after expiry.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "assetId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "includePreview": {
+              "type": "boolean",
+              "default": true
+            }
+          },
+          "required": [
+            "assetId"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "asset": {
+              "type": "object",
+              "properties": {
+                "assetId": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "altText": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceUrl": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceKind": {
+                  "type": "string"
+                },
+                "mimeType": {
+                  "type": "string"
+                },
+                "bytes": {
+                  "type": "number"
+                },
+                "width": {
+                  "type": "number"
+                },
+                "height": {
+                  "type": "number"
+                },
+                "projectId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "folderId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "status": {
+                  "type": "string"
+                },
+                "embeddingStatus": {
+                  "type": "string"
+                },
+                "createdAt": {
+                  "type": "string"
+                },
+                "updatedAt": {
+                  "type": "string"
+                },
+                "preview": {
+                  "type": "object",
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "format": "uri"
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "mimeType": {
+                      "type": "string",
+                      "const": "image/webp"
+                    }
+                  },
+                  "required": [
+                    "url",
+                    "expiresAt",
+                    "mimeType"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "assetId",
+                "title",
+                "description",
+                "altText",
+                "sourceUrl",
+                "sourceKind",
+                "mimeType",
+                "bytes",
+                "width",
+                "height",
+                "projectId",
+                "folderId",
+                "tags",
+                "status",
+                "embeddingStatus",
+                "createdAt",
+                "updatedAt"
+              ],
+              "additionalProperties": false
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Get Image Asset",
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_asset_list",
+        "upstreamName": "image_asset_list",
+        "description": "List authorized private image metadata with exact location, provenance, media, tag, and creation-time filters. Use image_asset_search for semantic retrieval.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "projectId": {
+              "type": "string"
+            },
+            "folderId": {
+              "type": "string"
+            },
+            "sourceKind": {
+              "type": "string",
+              "enum": [
+                "upload",
+                "scrape",
+                "screenshot",
+                "instagram",
+                "external_url",
+                "import"
+              ]
+            },
+            "sourceHost": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 253
+            },
+            "mimeType": {
+              "type": "string",
+              "enum": [
+                "image/jpeg",
+                "image/png",
+                "image/webp",
+                "image/gif"
+              ]
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80
+              },
+              "maxItems": 20
+            },
+            "createdAfter": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "createdBefore": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 30
+            }
+          },
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "assets": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "assetId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  },
+                  "description": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "altText": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "sourceUrl": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "sourceKind": {
+                    "type": "string"
+                  },
+                  "mimeType": {
+                    "type": "string"
+                  },
+                  "bytes": {
+                    "type": "number"
+                  },
+                  "width": {
+                    "type": "number"
+                  },
+                  "height": {
+                    "type": "number"
+                  },
+                  "projectId": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "folderId": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "status": {
+                    "type": "string"
+                  },
+                  "embeddingStatus": {
+                    "type": "string"
+                  },
+                  "createdAt": {
+                    "type": "string"
+                  },
+                  "updatedAt": {
+                    "type": "string"
+                  },
+                  "preview": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "expiresAt": {
+                        "type": "string",
+                        "format": "date-time"
+                      },
+                      "mimeType": {
+                        "type": "string",
+                        "const": "image/webp"
+                      }
+                    },
+                    "required": [
+                      "url",
+                      "expiresAt",
+                      "mimeType"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "assetId",
+                  "title",
+                  "description",
+                  "altText",
+                  "sourceUrl",
+                  "sourceKind",
+                  "mimeType",
+                  "bytes",
+                  "width",
+                  "height",
+                  "projectId",
+                  "folderId",
+                  "tags",
+                  "status",
+                  "embeddingStatus",
+                  "createdAt",
+                  "updatedAt"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "count": {
+              "type": "number"
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "List Image Assets",
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_asset_search",
+        "upstreamName": "image_asset_search",
+        "description": "Semantically search authorized private image Memory using text, a stored asset, a public HTTPS image, or bounded base64. Text plus one image performs a fused query. This consumes query-embedding usage.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "queryText": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4e3
+            },
+            "queryAssetId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "queryUrl": {
+              "type": "string",
+              "format": "uri"
+            },
+            "queryImageBase64": {
+              "type": "string",
+              "minLength": 1
+            },
+            "projectId": {
+              "type": "string"
+            },
+            "folderId": {
+              "type": "string"
+            },
+            "sourceKind": {
+              "type": "string",
+              "enum": [
+                "upload",
+                "scrape",
+                "screenshot",
+                "instagram",
+                "external_url",
+                "import"
+              ]
+            },
+            "sourceHost": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 253
+            },
+            "mimeType": {
+              "type": "string",
+              "enum": [
+                "image/jpeg",
+                "image/png",
+                "image/webp",
+                "image/gif"
+              ]
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80
+              },
+              "maxItems": 20
+            },
+            "createdAfter": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "createdBefore": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 30,
+              "default": 10
+            },
+            "includePreview": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "results": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "asset": {
+                    "type": "object",
+                    "properties": {
+                      "assetId": {
+                        "type": "string"
+                      },
+                      "title": {
+                        "type": "string"
+                      },
+                      "description": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "altText": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "sourceUrl": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "sourceKind": {
+                        "type": "string"
+                      },
+                      "mimeType": {
+                        "type": "string"
+                      },
+                      "bytes": {
+                        "type": "number"
+                      },
+                      "width": {
+                        "type": "number"
+                      },
+                      "height": {
+                        "type": "number"
+                      },
+                      "projectId": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "folderId": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "tags": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "status": {
+                        "type": "string"
+                      },
+                      "embeddingStatus": {
+                        "type": "string"
+                      },
+                      "createdAt": {
+                        "type": "string"
+                      },
+                      "updatedAt": {
+                        "type": "string"
+                      },
+                      "preview": {
+                        "type": "object",
+                        "properties": {
+                          "url": {
+                            "type": "string",
+                            "format": "uri"
+                          },
+                          "expiresAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "mimeType": {
+                            "type": "string",
+                            "const": "image/webp"
+                          }
+                        },
+                        "required": [
+                          "url",
+                          "expiresAt",
+                          "mimeType"
+                        ],
+                        "additionalProperties": false
+                      }
+                    },
+                    "required": [
+                      "assetId",
+                      "title",
+                      "description",
+                      "altText",
+                      "sourceUrl",
+                      "sourceKind",
+                      "mimeType",
+                      "bytes",
+                      "width",
+                      "height",
+                      "projectId",
+                      "folderId",
+                      "tags",
+                      "status",
+                      "embeddingStatus",
+                      "createdAt",
+                      "updatedAt"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "score": {
+                    "type": "number"
+                  },
+                  "matchRepresentations": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "visual",
+                        "fused"
+                      ]
+                    }
+                  },
+                  "embeddingModel": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "asset",
+                  "score",
+                  "matchRepresentations",
+                  "embeddingModel"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "count": {
+              "type": "number"
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Search Image Assets",
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      },
+      {
+        "id": "image_asset_move",
+        "upstreamName": "image_asset_move",
+        "description": "Move an image asset between project/folder locations in the same writable Memory vault. This updates metadata only and never copies private image bytes.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "assetId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "projectId": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "folderId": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "assetId"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "asset": {
+              "type": "object",
+              "properties": {
+                "assetId": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "altText": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceUrl": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sourceKind": {
+                  "type": "string"
+                },
+                "mimeType": {
+                  "type": "string"
+                },
+                "bytes": {
+                  "type": "number"
+                },
+                "width": {
+                  "type": "number"
+                },
+                "height": {
+                  "type": "number"
+                },
+                "projectId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "folderId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "status": {
+                  "type": "string"
+                },
+                "embeddingStatus": {
+                  "type": "string"
+                },
+                "createdAt": {
+                  "type": "string"
+                },
+                "updatedAt": {
+                  "type": "string"
+                },
+                "preview": {
+                  "type": "object",
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "format": "uri"
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "mimeType": {
+                      "type": "string",
+                      "const": "image/webp"
+                    }
+                  },
+                  "required": [
+                    "url",
+                    "expiresAt",
+                    "mimeType"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "assetId",
+                "title",
+                "description",
+                "altText",
+                "sourceUrl",
+                "sourceKind",
+                "mimeType",
+                "bytes",
+                "width",
+                "height",
+                "projectId",
+                "folderId",
+                "tags",
+                "status",
+                "embeddingStatus",
+                "createdAt",
+                "updatedAt"
+              ],
+              "additionalProperties": false
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Move Image Asset",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "id": "image_asset_delete",
+        "upstreamName": "image_asset_delete",
+        "description": "DESTRUCTIVE: delete one governed image asset, remove its semantic vectors, and purge private bytes when no other logical asset uses them. Retry with the same assetId if an earlier response was lost.",
+        "inputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "vault": {
+              "type": "string"
+            },
+            "assetId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "confirmDelete": {
+              "type": "boolean",
+              "const": true,
+              "description": "Must be true after the caller has confirmed deletion."
+            }
+          },
+          "required": [
+            "assetId",
+            "confirmDelete"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "outputJsonSchema": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean",
+              "enum": [
+                true,
+                false
+              ]
+            },
+            "deleted": {
+              "type": "boolean"
+            },
+            "assetId": {
+              "type": "string"
+            },
+            "code": {
+              "type": "string"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ok"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        },
+        "annotations": {
+          "title": "Delete Image Asset",
+          "readOnlyHint": false,
+          "destructiveHint": true,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      }
+    ];
+  }
+});
+
 // src/mcp/memory-tool-schemas.ts
 var import_zod50, AcceptShareSchema, ApproveSenderSchema, DeclineShareSchema, GetChatLinkSchema, GetVaultAppLinkSchema, InboxSettingsSchema, InviteAccountSchema, issueKeyTool_scopeShape, IssueKeySchema, ListApprovedSendersSchema, ListKeysSchema, NoteInboxSchema, RemoveApprovedSenderSchema, RevokeChatLinkSchema, RevokeKeySchema, RevokeShareSchema, RevokeVaultAppLinkSchema, SetAgentIdentitySchema, SetScopeSchema, ShareNoteSchema, ShareVaultSchema, SwapVaultSchema, SwitchAccountSchema, UnlinkShareSchema, memoryCaptureTool_notePropsSchema, MemoryCaptureSchema, MemoryQuestionsSchema, PrepareMemoryWriteSchema, validateMemoryWriteTool_notePropsSchema, ValidateMemoryWriteSchema, CreateChannelSchema, GetMessageNoteSchema, ListChannelMembersSchema, ListChannelMessagesSchema, MyMentionsSchema, PollChannelSchema, PostMessageSchema, ReactMessageSchema, RemoveChannelMemberSchema, ReplyMessageSchema, factHistoryTool_entryShape, FactHistorySchema, recordFactTool_factShape, RecordFactSchema, NoteBacklinksSchema, GraphPathSchema, GraphUniverseSchema, LibraryIngestSchema, bulkDeleteNotesTool_FilterSchema, BulkDeleteNotesSchema, DeleteNoteSchema, ExportSchema, getTool_notePropsSchema, GetSchema, listNoteSchema, ListSchema, putTool_notePropsSchema, PutSchema, searchTool_primitiveValue, SearchSchema, SuggestSchema, UploadSchema, TemporalRecallSchema, ScheduledArtifactSelectionSchema2, CreateScheduledActionSchema, UpdateScheduledActionSchema, DeleteScheduledActionSchema, GetScheduleLinkSchema, GetScheduleStatusSchema, ListScheduledActionsSchema, PauseScheduledActionSchema, ProposeScheduledActionSchema, ResumeScheduledActionSchema, RevokeScheduleLinkSchema, SetScheduleDefaultsSchema, SetScheduleEntitlementSchema, CostUsageSchema, StorageUsageSchema, CreateTableSchema, deleteTableRowsTool_FilterSchema, DeleteTableRowsSchema, DescribeTableSchema, DropTableSchema, InsertTableRowsSchema, ListTablesSchema, queryTableTool_FilterSchema, QueryTableSchema, ListTagsSchema, MergeTagsSchema, ResolveTagsSchema, UpsertTagSchema, AddVaultSchema, CreateSecureVaultSchema, DeleteVaultSchema, GetVaultContractSchema, ListSharedWithMeSchema, ListVaultsSchema, ProvisionDefaultsSchema, RouteMemorySchema, VideoAnalyzeStartSchema, VideoAnalyzeStatusSchema, CreateWebhookSchema, ListWebhooksSchema, RevokeWebhookSchema, MEMORY_TOOL_SCHEMAS;
 var init_memory_tool_schemas = __esm({
@@ -62114,11 +63865,11 @@ var init_memory_tool_schemas = __esm({
 });
 
 // src/mcp/memory-tool-registry.ts
-var import_image_assets, MEMORY_TOOL_DESCRIPTION_OVERRIDES, MEMORY_TOOL_REGISTRY;
+var MEMORY_TOOL_DESCRIPTION_OVERRIDES, MEMORY_TOOL_REGISTRY;
 var init_memory_tool_registry = __esm({
   "src/mcp/memory-tool-registry.ts"() {
     "use strict";
-    import_image_assets = require("mcpscraper-memory-tools/tools/assets/image-assets");
+    init_memory_image_tool_schemas_generated();
     init_memory_tool_schemas();
     MEMORY_TOOL_DESCRIPTION_OVERRIDES = {
       "access-swap-vault": "Set the account's persisted active vault so later memory calls may omit vault and use it by default across stateless requests. The vault must be entitled to the key and the key must hold 'swap' scope."
@@ -62128,7 +63879,7 @@ var init_memory_tool_registry = __esm({
         ...schema,
         description: MEMORY_TOOL_DESCRIPTION_OVERRIDES[schema.id] ?? schema.description
       })),
-      ...import_image_assets.IMAGE_ASSET_MCP_DEFINITIONS
+      ...MEMORY_IMAGE_TOOL_SCHEMAS
     ];
   }
 });
@@ -87416,8 +89167,6 @@ var init_server = __esm({
         if (checked.error) return c.json({ error: checked.error }, 400);
         body.callback_url = checked.parsed?.href;
       }
-      const limitErr = await checkHarvestLimits(user, c.req.header("x-mcp-scraper-concurrency-lock"));
-      if (limitErr) return c.json(limitErr, 429, { "Retry-After": "30" });
       const options = {
         query: body.query.trim(),
         location: body.location,
@@ -87439,6 +89188,26 @@ var init_server = __esm({
         includeAiOverview: body.includeAiOverview ?? false,
         includeWhatPeopleSaying: body.includeWhatPeopleSaying ?? false
       };
+      const suppliedIdempotencyKey = c.req.header("idempotency-key") ?? c.req.header("x-idempotency-key");
+      let derivedJobId = null;
+      let requestFingerprint3 = null;
+      if (!options.serpOnly && suppliedIdempotencyKey != null) {
+        const trimmedKey = suppliedIdempotencyKey.trim();
+        if (!trimmedKey || trimmedKey.length > 200) {
+          return c.json({ error: "Idempotency-Key must contain 1-200 characters.", errorCode: "invalid_idempotency_key", retryable: false }, 400);
+        }
+        derivedJobId = `paa-${sha256Hex(`${user.id}\0${trimmedKey}`).slice(0, 24)}`;
+        requestFingerprint3 = sha256Hex(JSON.stringify({ options, callbackUrl: body.callback_url ?? null }));
+        const existing = await getJob(derivedJobId, user.id);
+        if (existing) {
+          if (existing.options.requestFingerprint !== requestFingerprint3) {
+            return c.json({ error: "Idempotency-Key was already used for a different asynchronous harvest_paa call.", errorCode: "idempotency_conflict", retryable: false }, 409);
+          }
+          return c.json({ job_id: existing.id, status: existing.status, replayed: true }, ["done", "failed", "cancelled"].includes(existing.status) ? 200 : 202);
+        }
+      }
+      const limitErr = await checkHarvestLimits(user, c.req.header("x-mcp-scraper-concurrency-lock"));
+      if (limitErr) return c.json(limitErr, 429, { "Retry-After": "30" });
       const harvestCost = options.serpOnly ? MC_COSTS.serp_headful : paaCostForQuestionCount2(options.maxQuestions);
       let jobId2;
       if (options.serpOnly) {
@@ -87451,7 +89220,7 @@ var init_server = __esm({
         if (!harvestOk) return c.json(insufficientBalanceResponse(harvestBal, harvestCost), 402);
         jobId2 = await createJob(user.id, options.query, { ...options, billingHoldMc: harvestCost }, body.callback_url);
       } else {
-        jobId2 = (0, import_node_crypto72.randomUUID)();
+        jobId2 = derivedJobId ?? (0, import_node_crypto72.randomUUID)();
         const billingDebitKey = `paa-harvest:${jobId2}:hold`;
         const description = `PAA harvest: ${options.query}`.slice(0, 500);
         const hold = await debitMcIdempotent(
@@ -87467,9 +89236,14 @@ var init_server = __esm({
             ...options,
             executionOwner: "inngest",
             billingHoldMc: harvestCost,
-            billingDebitKey
+            billingDebitKey,
+            ...requestFingerprint3 ? { requestFingerprint: requestFingerprint3 } : {}
           }, body.callback_url);
         } catch (error) {
+          const existing = derivedJobId ? await getJob(derivedJobId, user.id).catch(() => null) : null;
+          if (existing && existing.options.requestFingerprint === requestFingerprint3) {
+            return c.json({ job_id: existing.id, status: existing.status, replayed: true }, 202);
+          }
           await settleDebitMcIdempotent(
             user.id,
             billingDebitKey,
@@ -89282,4 +91056,3 @@ async function main() {
   }
 }
 void main();
-//# sourceMappingURL=api-server.cjs.map