mcp-scraper 0.3.45 → 0.3.47

package/dist/bin/api-server.cjs

@@ -10015,6 +10015,15 @@ var init_blob_store = __esm({
         (0, import_node_fs2.writeFileSync)(path6, data);
         return { key, url: `file://${path6}`, bytes: byteLength(data), contentType };
       }
+      async get(key) {
+        const path6 = (0, import_node_path2.join)(this.baseDir, "blobs", key);
+        try {
+          const { readFileSync: readFileSync4 } = await import("fs");
+          return readFileSync4(path6);
+        } catch {
+          return null;
+        }
+      }
     };
     cached = null;
     VercelBlobStore = class {
@@ -10034,6 +10043,19 @@ var init_blob_store = __esm({
         });
         return { key, url: result.url, bytes: byteLength(data), contentType };
       }
+      async get(key) {
+        try {
+          const { list } = await import("@vercel/blob");
+          const res = await list({ prefix: key, token: this.token, limit: 1 });
+          const match = res.blobs.find((b) => b.pathname === key || b.pathname.startsWith(key));
+          if (!match) return null;
+          const resp = await fetch(match.url);
+          if (!resp.ok) return null;
+          return Buffer.from(await resp.arrayBuffer());
+        } catch {
+          return null;
+        }
+      }
     };
   }
 });
@@ -10266,8 +10288,8 @@ var init_rates = __esm({
         label: "Video breakdown (frame-by-frame + transcript)",
         aliases: ["video_frame_analysis", "video breakdown", "video analysis", "analyze video"],
         credits: mcToCredits(MC_COSTS.video_analysis),
-        unit: "per video",
-        notes: "Full multi-lens video breakdown: samples up to 120 frames across a video (to 30 min), analyzes each with vision AI, transcribes the audio, then produces summary, pacing/energy, words-per-minute, topic outline, key points, hook analysis, visual style, and a how-to-replicate recipe with a quality-control pass. Flat $1 per video; refunded if the run fails."
+        unit: "per 120 frames (max 480)",
+        notes: "Full multi-lens video breakdown: samples frames across a video (up to 30 minutes), analyzes each with vision AI, transcribes the audio, then produces summary, pacing/energy, words-per-minute, topic outline, key points, hook analysis, visual style, and a how-to-replicate recipe with a quality-control pass. $1 per 120 frames requested (max 480 = $4); billed down automatically if the video cannot use the requested frames, and refunded fully if the run fails."
       }
     ];
     CONCURRENCY_PRICE_ID = "price_1Ta1NRS8aAcsk3TGwsRnYbix";
@@ -10343,6 +10365,7 @@ var init_rates = __esm({
       REDDIT_THREAD_REFUND: "reddit_thread_refund",
       VIDEO_ANALYSIS: "video_analysis",
       VIDEO_ANALYSIS_REFUND: "video_analysis_refund",
+      VIDEO_ANALYSIS_ADJUST: "video_analysis_adjust",
       MEMORY_AI: "memory_ai",
       MEMORY_AI_REFUND: "memory_ai_refund"
     };
@@ -16635,6 +16658,9 @@ var init_memory = __esm({
 function invalidRequest5(message) {
   return { error_code: "invalid_request", message };
 }
+function tiersFor(frames) {
+  return Math.ceil(Math.min(Math.max(frames, 1), 480) / 120);
+}
 var import_hono9, import_zod20, videoApp, AnalyzeBodySchema;
 var init_video_routes = __esm({
   "src/api/video-routes.ts"() {
@@ -16649,7 +16675,7 @@ var init_video_routes = __esm({
     AnalyzeBodySchema = import_zod20.z.object({
       sourceUrl: import_zod20.z.string().trim().url("sourceUrl must be a direct video file URL"),
       intervalS: import_zod20.z.number().min(1).max(30).optional(),
-      maxFrames: import_zod20.z.number().int().min(1).max(120).optional(),
+      maxFrames: import_zod20.z.number().int().min(1).max(480).optional(),
       detail: import_zod20.z.enum(["fast", "standard", "deep"]).optional(),
       vault: import_zod20.z.string().trim().min(1).optional()
     });
@@ -16660,21 +16686,24 @@ var init_video_routes = __esm({
       const user = c.get("user");
       const { key: memKey, error: memErr } = await getOrCreateUserMemoryKey(user);
       if (!memKey) return c.json({ error_code: "memory_unavailable", message: memErr ?? "memory unavailable" }, 502);
-      const { ok, balance_mc } = await debitMc(user.id, MC_COSTS.video_analysis, LedgerOperation.VIDEO_ANALYSIS, body.sourceUrl);
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.video_analysis), 402);
+      const requestedFrames = Math.min(Math.max(body.maxFrames ?? 120, 1), 480);
+      const tiers = tiersFor(requestedFrames);
+      const holdMc = tiers * MC_COSTS.video_analysis;
+      const { ok, balance_mc } = await debitMc(user.id, holdMc, LedgerOperation.VIDEO_ANALYSIS, body.sourceUrl);
+      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, holdMc), 402);
       const started = await memoryCall(
         "videoAnalyzeStartTool",
         {
           sourceUrl: body.sourceUrl,
           intervalS: body.intervalS ?? 2,
-          maxFrames: body.maxFrames ?? 120,
+          maxFrames: requestedFrames,
           detail: body.detail ?? "standard",
           vault: body.vault ?? "Library"
         },
         memKey
       );
       if (!started.ok || !started.runId) {
-        await creditMc(user.id, MC_COSTS.video_analysis, LedgerOperation.VIDEO_ANALYSIS_REFUND, `start-failed:${body.sourceUrl}`);
+        await creditMc(user.id, holdMc, LedgerOperation.VIDEO_ANALYSIS_REFUND, `start-failed:${body.sourceUrl}`);
         return c.json({ error_code: "video_start_failed", message: started.error ?? "could not start analysis" }, 502);
       }
       return c.json({
@@ -16693,11 +16722,30 @@ var init_video_routes = __esm({
       if (!memKey) return c.json({ error_code: "memory_unavailable", message: memErr ?? "memory unavailable" }, 502);
       const st = await memoryCall("videoAnalyzeStatusTool", { runId }, memKey);
       if (!st.ok) return c.json({ error_code: "not_found", message: st.error ?? "run not found" }, 404);
+      const requestedTiers = tiersFor(st.maxFrames ?? 120);
+      let reconciliation = null;
       if (st.status === "failed") {
+        const refundMc = requestedTiers * MC_COSTS.video_analysis;
         const refundOp = `${LedgerOperation.VIDEO_ANALYSIS_REFUND}:${runId}`;
         if (!await ledgerExistsForOperation(user.id, refundOp)) {
-          await creditMc(user.id, MC_COSTS.video_analysis, refundOp, `run-failed:${runId}`);
+          await creditMc(user.id, refundMc, refundOp, `run-failed:${runId}`);
         }
+        reconciliation = { billedMc: requestedTiers * MC_COSTS.video_analysis, refundedMc: refundMc, effectiveFrames: null };
+      }
+      if (st.status === "done") {
+        const effectiveTiers = tiersFor(st.frameCount ?? 120);
+        const diff = requestedTiers - effectiveTiers;
+        if (diff > 0) {
+          const adjustOp = `${LedgerOperation.VIDEO_ANALYSIS_ADJUST}:${runId}`;
+          if (!await ledgerExistsForOperation(user.id, adjustOp)) {
+            await creditMc(user.id, diff * MC_COSTS.video_analysis, adjustOp, `tier-reconcile:${runId}`);
+          }
+        }
+        reconciliation = {
+          billedMc: requestedTiers * MC_COSTS.video_analysis,
+          refundedMc: Math.max(diff, 0) * MC_COSTS.video_analysis,
+          effectiveFrames: st.frameCount ?? null
+        };
       }
       return c.json({
         ok: true,
@@ -16706,7 +16754,8 @@ var init_video_routes = __esm({
         progress: st.progress ?? null,
         frameCount: st.frameCount ?? null,
         ...st.status === "done" ? { artifactPath: st.artifactPath ?? null, report: st.report ?? null } : {},
-        ...st.error ? { error: st.error } : {}
+        ...st.error ? { error: st.error } : {},
+        ...reconciliation ? { reconciliation } : {}
       });
     });
   }
@@ -17839,6 +17888,57 @@ var init_workflow_catalog = __esm({
   }
 });
 
+// src/mcp/report-artifact-offload.ts
+async function offloadReport(toolName, ownerId, report) {
+  const timestamp2 = Date.now();
+  const random = (0, import_node_crypto7.randomBytes)(6).toString("hex");
+  const key = `${REPORT_BLOB_PREFIX}${ownerId}/${toolName}/${timestamp2}-${random}.md`;
+  const stored = await getBlobStore().put(key, report, "text/markdown");
+  return {
+    artifactId: stored.key,
+    bytes: stored.bytes,
+    expiresAt: new Date(timestamp2 + REPORT_BLOB_TTL_MS).toISOString(),
+    preview: report.slice(0, PREVIEW_CHARS)
+  };
+}
+function artifactOwnerId(artifactId) {
+  if (!artifactId.startsWith(REPORT_BLOB_PREFIX)) return null;
+  const rest = artifactId.slice(REPORT_BLOB_PREFIX.length);
+  const segment = rest.split("/")[0];
+  return segment || null;
+}
+async function readArtifactWindow(artifactId, offset, maxBytes) {
+  const buf = await getBlobStore().get(artifactId);
+  if (!buf) return null;
+  const totalBytes = buf.length;
+  const start = Math.max(0, offset);
+  const end = Math.min(totalBytes, start + maxBytes);
+  const slice = buf.subarray(start, end);
+  const nextOffset = end < totalBytes ? end : null;
+  return { text: slice.toString("utf8"), totalBytes, nextOffset };
+}
+function summaryEnvelope(executiveSummary, offloaded) {
+  return [
+    executiveSummary.trim(),
+    "",
+    "--- Full report stored as artifact ---",
+    `artifactId: ${offloaded.artifactId} \xB7 ${offloaded.bytes} bytes \xB7 expires ${offloaded.expiresAt}`,
+    "Read it with report_artifact_read (supports offset/maxBytes windowing)."
+  ].join("\n");
+}
+var import_node_crypto7, REPORT_BLOB_TTL_MS, REPORT_BLOB_PREFIX, PREVIEW_CHARS, ARTIFACT_OFFLOAD_ENABLED;
+var init_report_artifact_offload = __esm({
+  "src/mcp/report-artifact-offload.ts"() {
+    "use strict";
+    import_node_crypto7 = require("crypto");
+    init_blob_store();
+    REPORT_BLOB_TTL_MS = 24 * 60 * 60 * 1e3;
+    REPORT_BLOB_PREFIX = "mcp-reports/";
+    PREVIEW_CHARS = 2e3;
+    ARTIFACT_OFFLOAD_ENABLED = process.env.MCP_SCRAPER_ARTIFACT_OFFLOAD !== "false";
+  }
+});
+
 // src/mcp/mcp-response-formatter.ts
 function configureReportSaving(enabled) {
   reportSavingEnabled = enabled;
@@ -18004,6 +18104,20 @@ function oneBlock(content, diskContent) {
 \u{1F4C4} Saved: \`${filePath}\`` : content;
   return { content: [{ type: "text", text }] };
 }
+async function maybeOffload(toolName, ctx, fullText, summaryText, structuredContent) {
+  if (!ctx?.hosted || !ARTIFACT_OFFLOAD_ENABLED) return null;
+  const bytes = Buffer.byteLength(fullText);
+  if (bytes <= INLINE_BUDGET_BYTES) return null;
+  const offloaded = await offloadReport(toolName, ctx.ownerId, fullText);
+  return {
+    content: [{ type: "text", text: summaryEnvelope(summaryText, offloaded) }],
+    structuredContent: { ...structuredContent, artifact: offloaded }
+  };
+}
+function capArray(items, cap) {
+  if (items.length <= cap) return { items };
+  return { items: items.slice(0, cap), truncatedCount: items.length - cap };
+}
 function workflowRecipeTable(recipes) {
   if (!recipes.length) return "";
   return [
@@ -18355,7 +18469,7 @@ ${headingSection}${kpoSection}${brandingSection}${bodySectionFull}${memSection}$
   }
   return { ...textResult, structuredContent };
 }
-function formatMapSiteUrls(raw, input) {
+async function formatMapSiteUrls(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -18396,20 +18510,28 @@ ${broken.map((u) => `- ${u.url} (${u.status})`).join("\n")}` : "",
 - Extract content from all pages: use \`extract_site\`
 - Scrape a single page: use \`extract_url\``
   ].filter(Boolean).join("\n");
-  return {
-    ...oneBlock(full),
-    structuredContent: {
-      startUrl: d.startUrl ?? input.url,
-      totalFound: d.totalFound ?? urls.length,
-      truncated: d.truncated === true,
-      okCount: ok.length,
-      redirectCount: redirects.length,
-      brokenCount: broken.length,
-      inventoryFile: inventoryFile ?? null,
-      urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
-      durationMs: d.durationMs ?? 0
-    }
+  const structuredContent = {
+    startUrl: d.startUrl ?? input.url,
+    totalFound: d.totalFound ?? urls.length,
+    truncated: d.truncated === true,
+    okCount: ok.length,
+    redirectCount: redirects.length,
+    brokenCount: broken.length,
+    inventoryFile: inventoryFile ?? null,
+    urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
+    durationMs: d.durationMs ?? 0
   };
+  const summary = `# URL Map: ${input.url}
+**${d.totalFound} URLs** \xB7 ${(d.durationMs / 1e3).toFixed(1)}s
+
+## Summary
+- 2xx: ${ok.length}
+- 3xx: ${redirects.length}
+- 4xx+: ${broken.length}`;
+  const capped = capArray(structuredContent.urls, STRUCTURED_ARRAY_CAP);
+  const offloaded = await maybeOffload("map_site_urls", ctx, full, summary, { ...structuredContent, urls: capped.items, truncatedCount: capped.truncatedCount });
+  if (offloaded) return offloaded;
+  return { ...oneBlock(full), structuredContent };
 }
 function buildSeoExport(siteUrl, pages, branding) {
   const { edges, metrics } = buildLinkGraph(pages, siteUrl);
@@ -18429,7 +18551,7 @@ function buildSeoExport(siteUrl, pages, branding) {
     branding: branding ?? void 0
   };
 }
-function formatExtractSite(raw, input) {
+async function formatExtractSite(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -18464,6 +18586,36 @@ function formatExtractSite(raw, input) {
       schemaTypes: schemaTypesOf(p)
     })));
     const preview = pages.slice(0, BULK_PAGE_THRESHOLD).map(pageRow).join("\n");
+    const summaryHeader = [
+      `# Site Extract: ${input.url}`,
+      durationLine,
+      `
+## Pages (first ${Math.min(BULK_PAGE_THRESHOLD, pages.length)} of ${pages.length})
+| # | Title | URL | Schema |
+|---|-------|-----|--------|
+${preview}`
+    ].join("\n");
+    if (!bulk && ctx?.hosted) {
+      const pageDetails2 = pages.map((p, i) => {
+        const body = (p.bodyMarkdown ?? "").trim();
+        return [
+          `
+## ${i + 1}. ${p.title ?? "Untitled"}`,
+          `- **URL:** ${p.url}`,
+          p.metaDescription ? `- **Description:** ${p.metaDescription}` : "",
+          body ? `
+${body}` : "_(no content extracted)_"
+        ].filter(Boolean).join("\n");
+      }).join("\n");
+      const fullForOffload = `${summaryHeader}
+
+---
+# Full Page Content
+${pageDetails2}${tips}`;
+      const capped = capArray(structuredContent.pages, STRUCTURED_ARRAY_CAP);
+      const offloaded = await maybeOffload("extract_site", ctx, fullForOffload, `${summaryHeader}${tips}`, { ...structuredContent, pages: capped.items, truncatedCount: capped.truncatedCount });
+      if (offloaded) return offloaded;
+    }
     const location2 = bulk ? `
 ## \u{1F4C1} Bulk scrape saved
 - **Folder:** \`${bulk.dir}\` \u2190 all scraped page content is here
@@ -18516,7 +18668,7 @@ ${body}` : "_(no content extracted)_"
 ${pageDetails}${tips}`;
   return { ...oneBlock(full, diskReport), structuredContent };
 }
-async function formatAuditSite(raw, input) {
+async function formatAuditSite(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -18547,6 +18699,24 @@ async function formatAuditSite(raw, input) {
     images: { unique: img.unique, totalBytes: img.totalBytes, over100kb: img.over100kb, legacyFormat: img.legacyFormat },
     links: { internal: lr.internal.totalLinks, external: lr.external.totalLinks, orphans: lr.internal.orphans, brokenInternal: lr.internal.brokenInternal, externalDomains: lr.external.uniqueDomains }
   };
+  const summary = [
+    `# Technical SEO Audit: ${input.url}`,
+    durationLine,
+    `
+## Top issues
+${topIssues || "_none found_"}`,
+    `
+## Links
+${linkLine}`,
+    `
+## Images
+${imgLine}`
+  ].join("\n");
+  if (!bulk && ctx?.hosted) {
+    const fullForOffload = [summary, "\n---\n# Full Audit Report", seo.reportMd, renderImageSection(imageAudit), renderLinkReport(seo.linkReport)].join("\n");
+    const offloaded = await maybeOffload("audit_site", ctx, fullForOffload, summary, structuredContent);
+    if (offloaded) return offloaded;
+  }
   const location2 = bulk ? `
 ## \u{1F4C1} Technical audit saved
 - **Folder:** \`${bulk.dir}\` \u2190 full audit + page content here
@@ -19317,7 +19487,7 @@ ${rows}`,
     }
   };
 }
-function formatDirectoryWorkflow(raw, input) {
+async function formatDirectoryWorkflow(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -19369,26 +19539,29 @@ ${businessRows}` : null,
     durationMs != null ? `
 *Completed in ${(durationMs / 1e3).toFixed(1)}s*` : null
   ].filter(Boolean).join("\n");
-  return {
-    ...oneBlock(full),
-    structuredContent: {
-      query: d.query,
-      state: d.state,
-      minPopulation: d.minPopulation,
-      populationYear: d.populationYear,
-      maxResultsPerCity: d.maxResultsPerCity,
-      concurrency: d.concurrency,
-      censusSourceUrl: d.censusSourceUrl,
-      usZipsSourcePath: d.usZipsSourcePath ?? null,
-      warnings,
-      extractedAt: d.extractedAt,
-      selectedCityCount: d.selectedCityCount,
-      totalResultCount,
-      csvPath,
-      cities,
-      durationMs: durationMs ?? 0
-    }
+  const structuredContent = {
+    query: d.query,
+    state: d.state,
+    minPopulation: d.minPopulation,
+    populationYear: d.populationYear,
+    maxResultsPerCity: d.maxResultsPerCity,
+    concurrency: d.concurrency,
+    censusSourceUrl: d.censusSourceUrl,
+    usZipsSourcePath: d.usZipsSourcePath ?? null,
+    warnings,
+    extractedAt: d.extractedAt,
+    selectedCityCount: d.selectedCityCount,
+    totalResultCount,
+    csvPath,
+    cities,
+    durationMs: durationMs ?? 0
   };
+  const summary = `# Directory Workflow: ${input.query}
+**Markets:** ${cities.length} \xB7 **Maps results:** ${totalResultCount} \xB7 **State:** ${d.state ?? input.state ?? "US"}`;
+  const capped = capArray(cities, STRUCTURED_ARRAY_CAP);
+  const offloaded = await maybeOffload("directory_workflow", ctx, full, summary, { ...structuredContent, cities: capped.items, truncatedCount: capped.truncatedCount });
+  if (offloaded) return offloaded;
+  return { ...oneBlock(full), structuredContent };
 }
 function formatMapsPlaceIntel(raw, input) {
   const parsed = parseData(raw);
@@ -19908,7 +20081,7 @@ ${rows}` : ""
     }
   };
 }
-var import_node_fs5, import_node_os5, import_node_path7, reportSavingEnabled, BULK_PAGE_THRESHOLD, BULK_URL_THRESHOLD;
+var import_node_fs5, import_node_os5, import_node_path7, INLINE_BUDGET_BYTES, STRUCTURED_ARRAY_CAP, reportSavingEnabled, BULK_PAGE_THRESHOLD, BULK_URL_THRESHOLD;
 var init_mcp_response_formatter = __esm({
   "src/mcp/mcp-response-formatter.ts"() {
     "use strict";
@@ -19921,6 +20094,9 @@ var init_mcp_response_formatter = __esm({
     init_seo_link_report();
     init_seo_issues();
     init_image_audit();
+    init_report_artifact_offload();
+    INLINE_BUDGET_BYTES = Number(process.env.MCP_SCRAPER_INLINE_BUDGET ?? 5e4);
+    STRUCTURED_ARRAY_CAP = 25;
     reportSavingEnabled = true;
     BULK_PAGE_THRESHOLD = 25;
     BULK_URL_THRESHOLD = 500;
@@ -22482,7 +22658,7 @@ async function readManifestFromSummary(summary) {
 function webhookSignature(body, timestamp2) {
   const secret2 = process.env.MCP_SCRAPER_WEBHOOK_SECRET?.trim();
   if (!secret2) return null;
-  return (0, import_node_crypto7.createHmac)("sha256", secret2).update(`${timestamp2}.${body}`).digest("hex");
+  return (0, import_node_crypto8.createHmac)("sha256", secret2).update(`${timestamp2}.${body}`).digest("hex");
 }
 async function deliverWorkflowWebhook(input) {
   if (!input.webhookUrl) return;
@@ -22689,11 +22865,11 @@ async function dispatchDueWorkflowSchedules(apiUrl, limit = 3) {
   }
   return { dispatched: results.length, results };
 }
-var import_node_crypto7, import_promises9, import_hono12, import_zod29, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema, TERMINAL_RUN_STATUSES;
+var import_node_crypto8, import_promises9, import_hono12, import_zod29, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema, TERMINAL_RUN_STATUSES;
 var init_workflow_routes = __esm({
   "src/api/workflow-routes.ts"() {
     "use strict";
-    import_node_crypto7 = require("crypto");
+    import_node_crypto8 = require("crypto");
     import_promises9 = require("fs/promises");
     import_hono12 = require("hono");
     import_zod29 = require("zod");
@@ -22974,7 +23150,7 @@ var init_workflow_routes = __esm({
 // src/serp-intelligence/page-snapshot-extractor.ts
 function sha256(value) {
   if (!value) return null;
-  return (0, import_node_crypto8.createHash)("sha256").update(value).digest("hex");
+  return (0, import_node_crypto9.createHash)("sha256").update(value).digest("hex");
 }
 function countWords(markdown) {
   const matches = markdown.trim().match(/\b[\p{L}\p{N}][\p{L}\p{N}'-]*\b/gu);
@@ -23274,11 +23450,11 @@ async function capturePageSnapshots(targets, options = {}) {
     }
   };
 }
-var import_node_crypto8, import_p_limit3, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_CONTENT_CHARS;
+var import_node_crypto9, import_p_limit3, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_CONTENT_CHARS;
 var init_page_snapshot_extractor = __esm({
   "src/serp-intelligence/page-snapshot-extractor.ts"() {
     "use strict";
-    import_node_crypto8 = require("crypto");
+    import_node_crypto9 = require("crypto");
     import_p_limit3 = __toESM(require("p-limit"), 1);
     init_kpo_extractor();
     init_url_utils();
@@ -25854,18 +26030,18 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.3.45";
+    PACKAGE_VERSION = "0.3.47";
   }
 });
 
 // src/mcp/server-instructions.ts
-var SERVER_INSTRUCTIONS;
-var init_server_instructions = __esm({
-  "src/mcp/server-instructions.ts"() {
-    "use strict";
-    SERVER_INSTRUCTIONS = `
+function serverInstructions(savesReportsLocally) {
+  const reportLine = savesReportsLocally ? "All report-producing tools also save a full Markdown report to disk." : "On this hosted endpoint, small reports return inline; large reports are stored as artifacts \u2014 read them back with report_artifact_read.";
+  return `
 # MCP Scraper
 
+${reportLine}
+
 Scrapes and analyzes web, search, maps, social, and site data. **Pick a tool by NAME from the map
 below, then load its schema before calling.** Where a tool needs a value another tool produces, the
 seam is noted so you can chain them.
@@ -25949,14 +26125,34 @@ Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when
   sites. It returns a saved folder/artifact plus a summary, not the full content inline.
 - Browser sessions and media transcription cost credits and take longer \u2014 prefer the cheapest tool that
   answers the question (plain search/extract before browser agents).
-- Large results are saved to disk or an artifact and returned as a summary plus a path; read the path for
-  full detail rather than expecting the whole payload inline.
+- Large results are saved to disk or an artifact and returned as a summary plus a path or artifactId;
+  read it back for full detail rather than expecting the whole payload inline.
 `.trim();
+}
+var SERVER_INSTRUCTIONS;
+var init_server_instructions = __esm({
+  "src/mcp/server-instructions.ts"() {
+    "use strict";
+    SERVER_INSTRUCTIONS = serverInstructions(true);
+  }
+});
+
+// src/mcp/output-schema-registry.ts
+function recordOutputSchema(name, schema) {
+  OUTPUT_SCHEMAS[name] = schema;
+  return ADVERTISE_OUTPUT_SCHEMAS ? schema : void 0;
+}
+var ADVERTISE_OUTPUT_SCHEMAS, OUTPUT_SCHEMAS;
+var init_output_schema_registry = __esm({
+  "src/mcp/output-schema-registry.ts"() {
+    "use strict";
+    ADVERTISE_OUTPUT_SCHEMAS = process.env.MCP_SCRAPER_ADVERTISE_OUTPUT_SCHEMAS === "true";
+    OUTPUT_SCHEMAS = {};
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod31, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, AuditSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, RedditThreadInputSchema, VideoFrameAnalysisInputSchema, VideoFrameAnalysisStatusInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, GoogleAdsSearchInputSchema, GoogleAdsPageIntelInputSchema, GoogleAdsTranscribeInputSchema, InstagramProfileContentInputSchema, InstagramMediaDownloadInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, AuditSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, VideoFrameAnalysisOutputSchema, VideoFrameAnalysisStatusOutputSchema, RedditThreadOutputSchema, FacebookPageIntelOutputSchema, GoogleAdsSearchOutputSchema, GoogleAdsPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, TranscriptChunkOutput, InstagramBrowserOutput, InstagramPaginationOutput, InstagramProfileContentOutputSchema, InstagramMediaTrackOutput, InstagramDownloadOutput, InstagramMediaDownloadOutputSchema, YoutubeTranscribeOutputSchema, FacebookAdTranscribeOutputSchema, GoogleAdsTranscribeOutputSchema, CaptureSerpSnapshotOutputSchema, CaptureSerpPageSnapshotsOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStepInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStepOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod31, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, AuditSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, RedditThreadInputSchema, VideoFrameAnalysisInputSchema, VideoFrameAnalysisStatusInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, GoogleAdsSearchInputSchema, GoogleAdsPageIntelInputSchema, GoogleAdsTranscribeInputSchema, InstagramProfileContentInputSchema, InstagramMediaDownloadInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, ArtifactPointerOutputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, AuditSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, VideoFrameAnalysisOutputSchema, VideoFrameAnalysisStatusOutputSchema, RedditThreadOutputSchema, FacebookPageIntelOutputSchema, GoogleAdsSearchOutputSchema, GoogleAdsPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, TranscriptChunkOutput, InstagramBrowserOutput, InstagramPaginationOutput, InstagramProfileContentOutputSchema, InstagramMediaTrackOutput, InstagramDownloadOutput, InstagramMediaDownloadOutputSchema, YoutubeTranscribeOutputSchema, FacebookAdTranscribeOutputSchema, GoogleAdsTranscribeOutputSchema, CaptureSerpSnapshotOutputSchema, CaptureSerpPageSnapshotsOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStepInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStepOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema, ReportArtifactReadInputSchema, ReportArtifactReadOutputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -26030,7 +26226,7 @@ var init_mcp_tool_schemas = __esm({
     VideoFrameAnalysisInputSchema = {
       sourceUrl: import_zod31.z.string().min(1).describe("A DIRECT video file URL (.mp4/.webm/.mov). Not a YouTube/Facebook/Instagram page URL \u2014 resolve those to a direct media URL first. Videos up to 30 minutes are supported."),
       intervalS: import_zod31.z.number().min(1).max(30).optional().describe("Preferred seconds between sampled frames (1-30, default 2). Automatically widened for long videos so the whole duration is covered within the frame budget."),
-      maxFrames: import_zod31.z.number().int().min(1).max(120).optional().describe("Max frames analyzed (<=120, default 120). Frames are spread evenly across the whole video."),
+      maxFrames: import_zod31.z.number().int().min(1).max(480).optional().describe("Max frames analyzed (<=480, default 120). $1 per 120 frames requested \u2014 120=$1 \u2026 480=$4 \u2014 automatically refunded down if the video cannot use them (minimum 1s between frames). Frames are spread evenly across the whole video."),
       detail: import_zod31.z.enum(["fast", "standard", "deep"]).optional().describe("Analysis depth. Default standard."),
       vault: import_zod31.z.string().min(1).optional().describe('Memory vault to save the finished breakdown into. Default "Library".')
     };
@@ -26105,12 +26301,18 @@ var init_mcp_tool_schemas = __esm({
       maxResultsPerCity: import_zod31.z.number().int().min(1).max(50).default(50).describe("Google Maps candidates to collect per city."),
       concurrency: import_zod31.z.number().int().min(1).max(5).default(5).describe("City Maps searches to run in parallel."),
       includeZipGroups: import_zod31.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available (MCP_SCRAPER_USZIPS_CSV_PATH or usZipsCsvPath)."),
-      usZipsCsvPath: import_zod31.z.string().optional().describe("Local/test-only path to a US ZIPS CSV (state_abbr, zipcode, county, city columns). Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
+      usZipsCsvPath: import_zod31.z.string().optional().describe("Local/test-only path to a US ZIPS CSV (state_abbr, zipcode, county, city columns). Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead. For ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the server, or pass this in local/test mode."),
       saveCsv: import_zod31.z.boolean().default(true).describe("Save a directory-ready CSV of results to the MCP Scraper output directory and return its path."),
       proxyMode: import_zod31.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting per city search. Defaults to location (city/ZIP-group residential targeting); configured forces the service proxy; none is local debugging only."),
       proxyZip: import_zod31.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting; normally omitted."),
       debug: import_zod31.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics.")
     };
+    ArtifactPointerOutputSchema = import_zod31.z.object({
+      artifactId: import_zod31.z.string(),
+      bytes: import_zod31.z.number().int().min(0),
+      expiresAt: import_zod31.z.string(),
+      preview: import_zod31.z.string()
+    });
     RankTrackerModeSchema = import_zod31.z.enum(["maps", "organic", "ai_overview", "paa"]);
     RankTrackerBlueprintInputSchema = {
       projectName: import_zod31.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
@@ -26224,7 +26426,9 @@ var init_mcp_tool_schemas = __esm({
         attempts: import_zod31.z.array(MapsSearchAttemptOutput),
         results: import_zod31.z.array(DirectoryMapsBusinessOutput)
       })),
-      durationMs: import_zod31.z.number().int().min(0)
+      durationMs: import_zod31.z.number().int().min(0),
+      truncatedCount: import_zod31.z.number().int().min(0).optional(),
+      artifact: ArtifactPointerOutputSchema.optional()
     };
     RankTrackerToolPlanOutput = import_zod31.z.object({
       tool: import_zod31.z.string(),
@@ -26344,7 +26548,9 @@ var init_mcp_tool_schemas = __esm({
         title: NullableString,
         schemaTypes: import_zod31.z.array(import_zod31.z.string())
       })),
-      durationMs: import_zod31.z.number().min(0)
+      durationMs: import_zod31.z.number().min(0),
+      truncatedCount: import_zod31.z.number().int().min(0).optional(),
+      artifact: ArtifactPointerOutputSchema.optional()
     };
     AuditSiteOutputSchema = {
       url: import_zod31.z.string(),
@@ -26364,7 +26570,8 @@ var init_mcp_tool_schemas = __esm({
         orphans: import_zod31.z.number().int().min(0),
         brokenInternal: import_zod31.z.number().int().min(0),
         externalDomains: import_zod31.z.number().int().min(0)
-      })
+      }),
+      artifact: ArtifactPointerOutputSchema.optional()
     };
     MapsPlaceIntelOutputSchema = {
       name: import_zod31.z.string(),
@@ -26436,7 +26643,9 @@ var init_mcp_tool_schemas = __esm({
         url: import_zod31.z.string(),
         status: import_zod31.z.number().int().nullable()
       })),
-      durationMs: import_zod31.z.number().min(0)
+      durationMs: import_zod31.z.number().min(0),
+      truncatedCount: import_zod31.z.number().int().min(0).optional(),
+      artifact: ArtifactPointerOutputSchema.optional()
     };
     YoutubeHarvestOutputSchema = {
       mode: import_zod31.z.string(),
@@ -26480,7 +26689,12 @@ var init_mcp_tool_schemas = __esm({
       frameCount: import_zod31.z.number().int().nullable().optional(),
       artifactPath: NullableString,
       report: NullableString,
-      error: NullableString
+      error: NullableString,
+      reconciliation: import_zod31.z.object({
+        billedMc: import_zod31.z.number().int(),
+        refundedMc: import_zod31.z.number().int(),
+        effectiveFrames: import_zod31.z.number().int().nullable()
+      }).nullable().optional()
     };
     RedditThreadOutputSchema = {
       sourceUrl: NullableString,
@@ -26868,6 +27082,17 @@ var init_mcp_tool_schemas = __esm({
       timeoutMs: import_zod31.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds; timeouts return as structured capture failures."),
       debug: import_zod31.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics.")
     };
+    ReportArtifactReadInputSchema = {
+      artifactId: import_zod31.z.string().min(1).describe("Artifact id returned inline by a tool whose result was too large to inline. Use only a returned artifactId; do not construct one yourself."),
+      offset: import_zod31.z.number().int().min(0).default(0).describe("Byte offset to start reading from. Pass the previous call's nextOffset to continue."),
+      maxBytes: import_zod31.z.number().int().min(1e3).max(1e5).default(2e4).describe("Maximum bytes of artifact text to return in this window.")
+    };
+    ReportArtifactReadOutputSchema = {
+      artifactId: import_zod31.z.string(),
+      text: import_zod31.z.string(),
+      totalBytes: import_zod31.z.number().int().min(0),
+      nextOffset: import_zod31.z.number().int().min(0).nullable()
+    };
   }
 });
 
@@ -27201,6 +27426,9 @@ var init_rank_tracker_blueprint = __esm({
 });
 
 // src/mcp/paa-mcp-server.ts
+function hashOwnerId(callerKey) {
+  return (0, import_node_crypto10.createHash)("sha256").update(callerKey).digest("hex").slice(0, 24);
+}
 function liveWebToolAnnotations(title) {
   return {
     title,
@@ -27213,16 +27441,16 @@ function liveWebToolAnnotations(title) {
 function registerSerpIntelligenceCaptureTools(server, executor) {
   server.registerTool("capture_serp_snapshot", {
     title: "SERP Intelligence Snapshot",
-    description: "Capture a structured SERP Intelligence Google snapshot (the product capture path used by Phoenix). Split query from location; leave proxyMode unset.",
+    description: "Capture a structured SERP Intelligence snapshot of a Google query \u2014 the persistent evidence format used by rank-tracking and comparison pipelines. Split query from location; leave proxyMode unset.",
     inputSchema: CaptureSerpSnapshotInputSchema,
-    outputSchema: CaptureSerpSnapshotOutputSchema,
+    outputSchema: recordOutputSchema("capture_serp_snapshot", CaptureSerpSnapshotOutputSchema),
     annotations: liveWebToolAnnotations("SERP Intelligence Snapshot")
   }, async (input) => formatCaptureSerpSnapshot(await executor.captureSerpSnapshot(input), input));
   server.registerTool("capture_serp_page_snapshots", {
     title: "SERP Intelligence Page Snapshots",
-    description: "Capture public ranking-page evidence as SERP Intelligence page snapshots (the product path used by Phoenix). Provide urls, or targets to preserve source metadata. Private IPs, localhost, file, and internal URLs are rejected.",
+    description: "Capture public ranking pages as SERP Intelligence page snapshots \u2014 persistent page evidence linked to a captured SERP. Provide urls, or targets to preserve source metadata. Private IPs, localhost, file, and internal URLs are rejected.",
     inputSchema: CaptureSerpPageSnapshotsInputSchema,
-    outputSchema: CaptureSerpPageSnapshotsOutputSchema,
+    outputSchema: recordOutputSchema("capture_serp_page_snapshots", CaptureSerpPageSnapshotsOutputSchema),
     annotations: liveWebToolAnnotations("SERP Intelligence Page Snapshots")
   }, async (input) => formatCaptureSerpPageSnapshots(await executor.captureSerpPageSnapshots(input), input));
 }
@@ -27270,230 +27498,251 @@ function registerSavedReportResources(server) {
   );
 }
 function buildPaaExtractorMcpServer(executor, options = {}) {
-  const server = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+  const server = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION }, { instructions: serverInstructions(options.savesReportsLocally !== false) });
   registerPaaExtractorMcpTools(server, executor, options);
   return server;
 }
 function registerPaaExtractorMcpTools(server, executor, options = {}) {
   const savesReports = options.savesReportsLocally !== false;
-  const reportNote = savesReports ? " Saves a full Markdown report to disk." : " Reports are returned inline; no files are saved on this hosted endpoint.";
-  const withReportNote = (description) => `${description}${reportNote}`;
+  const fileBehavior = (local, hosted) => savesReports ? local : hosted;
+  const ownerId = options.ownerId ?? "local";
+  const ctx = { hosted: !savesReports, ownerId };
   if (savesReports) registerSavedReportResources(server);
   server.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote("Best default tool for Google search research: People Also Ask questions with answers/sources, organic SERP, local pack, entity IDs, and AI Overview. Split topic from location; leave proxyMode unset. Warn the user before maxQuestions above 100 \u2014 deep harvests can run several minutes with no interim progress, billed per extracted question."),
+    description: "Best default tool for Google search research: People Also Ask questions with answers/sources, organic SERP, local pack, entity IDs, and AI Overview. Split topic from location; leave proxyMode unset. Warn the user before maxQuestions above 100 \u2014 deep harvests can run several minutes with no interim progress, billed per extracted question.",
     inputSchema: HarvestPaaInputSchema,
-    outputSchema: HarvestPaaOutputSchema,
+    outputSchema: recordOutputSchema("harvest_paa", HarvestPaaOutputSchema),
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion \u2014 rankings, organic results, local pack, positions. Split topic from location; leave proxyMode unset."),
+    description: "Fast Google SERP lookup without PAA expansion \u2014 rankings, organic results, local pack, positions. Split topic from location; leave proxyMode unset.",
     inputSchema: SearchSerpInputSchema,
-    outputSchema: SearchSerpOutputSchema,
+    outputSchema: recordOutputSchema("search_serp", SearchSerpOutputSchema),
     annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
   server.registerTool("extract_url", {
     title: "Single URL Extract",
-    description: withReportNote("Extract structured data from one public URL: content, schema, headings, metadata, screenshots, branding, or media assets. Set depositToVault:true to save the full page into the user's MCP Memory vault server-side (not returned to chat)."),
+    description: "Extract structured data from one public URL: content, schema, headings, metadata, screenshots, branding, or media assets. Set depositToVault:true to save the full page into the user's MCP Memory vault server-side (not returned to chat).",
     inputSchema: ExtractUrlInputSchema,
-    outputSchema: ExtractUrlOutputSchema,
+    outputSchema: recordOutputSchema("extract_url", ExtractUrlOutputSchema),
     annotations: liveWebToolAnnotations("Single URL Extract")
   }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
   server.registerTool("map_site_urls", {
     title: "Site URL Map",
-    description: withReportNote("Map/crawl a public website for a sitemap, URL inventory, or broken-link scan. Returns internal URLs with HTTP status; maps over 500 URLs are written to a local CSV file instead of inlined."),
+    description: `Map/crawl a public website for a sitemap, URL inventory, or broken-link scan. Returns internal URLs with HTTP status; ${fileBehavior("maps over 500 URLs are written to a local CSV file instead of inlined.", "large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")}`,
     inputSchema: MapSiteUrlsInputSchema,
-    outputSchema: MapSiteUrlsOutputSchema,
+    outputSchema: recordOutputSchema("map_site_urls", MapSiteUrlsOutputSchema),
     annotations: liveWebToolAnnotations("Site URL Map")
-  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
+  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input, ctx));
   server.registerTool("extract_site", {
     title: "Multi-Page Site Content Crawl",
-    description: withReportNote("Crawl a public website and return page CONTENT (Markdown) across multiple pages. Bulk crawls over 25 pages are saved as per-page Markdown files in a local folder instead of inlined. Content only \u2014 for a technical SEO audit use audit_site instead."),
+    description: `Crawl a public website and return page CONTENT (Markdown) across multiple pages. ${fileBehavior("Bulk crawls over 25 pages are saved as per-page Markdown files in a local folder instead of inlined.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")} Content only \u2014 for a technical SEO audit use audit_site instead.`,
     inputSchema: ExtractSiteInputSchema,
-    outputSchema: ExtractSiteOutputSchema,
+    outputSchema: recordOutputSchema("extract_site", ExtractSiteOutputSchema),
     annotations: liveWebToolAnnotations("Multi-Page Site Content Crawl")
-  }, async (input) => formatExtractSite(await executor.extractSite(input), input));
+  }, async (input) => formatExtractSite(await executor.extractSite(input), input, ctx));
   server.registerTool("audit_site", {
     title: "Technical SEO Audit",
-    description: withReportNote("Run a full technical SEO audit (Screaming-Frog-style) on a public website: on-page issues, internal link graph, indexability, heading/image analysis. Writes a folder of analysis files plus per-page content, and returns a summary plus the folder path. Use extract_site instead for plain page content."),
+    description: `Run a full technical SEO audit (Screaming-Frog-style) on a public website: on-page issues, internal link graph, indexability, heading/image analysis. ${fileBehavior("Writes a folder of analysis files plus per-page content, and returns a summary plus the folder path.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")} Use extract_site instead for plain page content.`,
     inputSchema: AuditSiteInputSchema,
-    outputSchema: AuditSiteOutputSchema,
+    outputSchema: recordOutputSchema("audit_site", AuditSiteOutputSchema),
     annotations: liveWebToolAnnotations("Technical SEO Audit")
-  }, async (input) => formatAuditSite(await executor.auditSite(input), input));
+  }, async (input) => formatAuditSite(await executor.auditSite(input), input, ctx));
   server.registerTool("youtube_harvest", {
     title: "YouTube Video Harvest",
-    description: withReportNote('Harvest YouTube video metadata by topic search or channel library. Use mode "search" for keyword/topic requests, mode "channel" for @handles/channel IDs/URLs. Returns titles, views, durations, and videoIds.'),
+    description: 'Harvest YouTube video metadata by topic search or channel library. Use mode "search" for keyword/topic requests, mode "channel" for @handles/channel IDs/URLs. Returns titles, views, durations, and videoIds.',
     inputSchema: YoutubeHarvestInputSchema,
-    outputSchema: YoutubeHarvestOutputSchema,
+    outputSchema: recordOutputSchema("youtube_harvest", YoutubeHarvestOutputSchema),
     annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
   server.registerTool("youtube_transcribe", {
     title: "YouTube Transcription",
-    description: withReportNote("Fetch and transcribe captions from a YouTube video. Pass videoId from youtube_harvest, or a url the user pasted. Returns full transcript, timestamped chunks, and word count."),
+    description: "Fetch and transcribe captions from a YouTube video. Pass videoId from youtube_harvest, or a url the user pasted. Returns full transcript, timestamped chunks, and word count.",
     inputSchema: YoutubeTranscribeInputSchema,
-    outputSchema: YoutubeTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("youtube_transcribe", YoutubeTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server.registerTool("facebook_page_intel", {
     title: "Facebook Advertiser Ad Intel",
-    description: withReportNote("Harvest ads from a Facebook advertiser: copy, creative angles, CTAs, and direct video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name."),
+    description: "Harvest ads from a Facebook advertiser: copy, creative angles, CTAs, and direct video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name.",
     inputSchema: FacebookPageIntelInputSchema,
-    outputSchema: FacebookPageIntelOutputSchema,
+    outputSchema: recordOutputSchema("facebook_page_intel", FacebookPageIntelOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
   server.registerTool("facebook_ad_search", {
     title: "Facebook Ad Library Search",
-    description: withReportNote("Search Facebook Ad Library to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs."),
+    description: "Search Facebook Ad Library to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs.",
     inputSchema: FacebookAdSearchInputSchema,
-    outputSchema: FacebookAdSearchOutputSchema,
+    outputSchema: recordOutputSchema("facebook_ad_search", FacebookAdSearchOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server.registerTool("reddit_thread", {
     title: "Reddit Thread + Comments",
-    description: withReportNote("Capture a Reddit post and its comment tree from a reddit.com thread URL \u2014 comments, opinions, audience voice. Handles Reddit's bot protection automatically; pass maxComments to cap the list."),
+    description: "Capture a Reddit post and its comment tree from a reddit.com thread URL \u2014 comments, opinions, audience voice. Handles Reddit's bot protection automatically; pass maxComments to cap the list.",
     inputSchema: RedditThreadInputSchema,
-    outputSchema: RedditThreadOutputSchema,
+    outputSchema: recordOutputSchema("reddit_thread", RedditThreadOutputSchema),
     annotations: liveWebToolAnnotations("Reddit Thread + Comments")
   }, async (input) => formatRedditThread(await executor.redditThread(input), input));
   server.registerTool("video_frame_analysis", {
     title: "Video Breakdown (frame-by-frame + transcript)",
-    description: "Produce a deep frame-by-frame + transcript breakdown of a video \u2014 pacing, hook, visual style, and how to replicate it. Pass a DIRECT video file URL (.mp4/.webm/.mov), not a page URL. Runs asynchronously and costs a flat $1 (refunded on failure): returns a runId immediately; poll video_frame_analysis_status until done.",
+    description: "Produce a deep frame-by-frame + transcript breakdown of a video \u2014 pacing, hook, visual style, and how to replicate it. Pass a DIRECT video file URL (.mp4/.webm/.mov), not a page URL. Costs $1 per 120 frames requested (max 480 = $4; refunded down if the video can't use them; refunded fully on failure): returns a runId immediately; poll video_frame_analysis_status until done. Videos up to 30 minutes.",
     inputSchema: VideoFrameAnalysisInputSchema,
-    outputSchema: VideoFrameAnalysisOutputSchema,
+    outputSchema: recordOutputSchema("video_frame_analysis", VideoFrameAnalysisOutputSchema),
     annotations: { title: "Video Breakdown", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
   }, async (input) => executor.videoFrameAnalysis(input));
   server.registerTool("video_frame_analysis_status", {
     title: "Video Breakdown Status",
-    description: 'Check progress of a video breakdown started with video_frame_analysis, using its runId. Free to call. When status is "done" it returns the full report and vault path; stop polling on "done" or "failed".',
+    description: 'Check progress of a video breakdown started with video_frame_analysis, using its runId. Free to call. When status is "done" it returns the full report and vault path; stop polling on "done" or "failed". Reports the billed tier reconciliation when done.',
     inputSchema: VideoFrameAnalysisStatusInputSchema,
-    outputSchema: VideoFrameAnalysisStatusOutputSchema,
+    outputSchema: recordOutputSchema("video_frame_analysis_status", VideoFrameAnalysisStatusOutputSchema),
     annotations: { title: "Video Breakdown Status", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
   }, async (input) => executor.videoFrameAnalysisStatus(input));
   server.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
     description: "Transcribe audio from a Facebook ad video CDN URL returned by facebook_page_intel. Use only that direct videoUrl value \u2014 do not pass public Facebook post/reel/share URLs (use facebook_video_transcribe for those).",
     inputSchema: FacebookAdTranscribeInputSchema,
-    outputSchema: FacebookAdTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("facebook_ad_transcribe", FacebookAdTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
   server.registerTool("google_ads_search", {
     title: "Google Ads Transparency Search",
-    description: withReportNote("Search the Google Ads Transparency Center to find advertisers by domain or brand name. Returns advertisers with advertiser ID and approximate ad count, to pass to google_ads_page_intel."),
+    description: "Search the Google Ads Transparency Center to find advertisers by domain or brand name. Returns advertisers with advertiser ID and approximate ad count, to pass to google_ads_page_intel.",
     inputSchema: GoogleAdsSearchInputSchema,
-    outputSchema: GoogleAdsSearchOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_search", GoogleAdsSearchOutputSchema),
     annotations: liveWebToolAnnotations("Google Ads Transparency Search")
   }, async (input) => formatGoogleAdsSearch(await executor.googleAdsSearch(input), input));
   server.registerTool("google_ads_page_intel", {
     title: "Google Ads Advertiser Intel",
-    description: withReportNote("Harvest an advertiser's ad creatives from the Google Ads Transparency Center: format, image URLs, and \u2014 for video ads \u2014 a YouTube video ID or direct video URL. Accepts advertiserId (from google_ads_search) or a domain."),
+    description: "Harvest an advertiser's ad creatives from the Google Ads Transparency Center: format, image URLs, and \u2014 for video ads \u2014 a YouTube video ID or direct video URL. Accepts advertiserId (from google_ads_search) or a domain.",
     inputSchema: GoogleAdsPageIntelInputSchema,
-    outputSchema: GoogleAdsPageIntelOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_page_intel", GoogleAdsPageIntelOutputSchema),
     annotations: liveWebToolAnnotations("Google Ads Advertiser Intel")
   }, async (input) => formatGoogleAdsPageIntel(await executor.googleAdsPageIntel(input), input));
   server.registerTool("google_ads_transcribe", {
     title: "Google Ad Video Transcription",
     description: "Transcribe audio from a Google video ad's direct videoUrl (a googlevideo.com playback URL) returned by google_ads_page_intel. For YouTube-hosted ads, use youtube_transcribe with the returned youtubeVideoId instead.",
     inputSchema: GoogleAdsTranscribeInputSchema,
-    outputSchema: GoogleAdsTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_transcribe", GoogleAdsTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Google Ad Video Transcription")
   }, async (input) => formatGoogleAdsTranscribe(await executor.googleAdsTranscribe(input), input));
   server.registerTool("facebook_video_transcribe", {
     title: "Facebook Organic Video Transcription",
-    description: withReportNote("Transcribe audio from an organic Facebook reel/video/post/share URL (including fb.watch). Renders the page, selects the best public CDN MP4, and returns the transcript plus resolved video metadata."),
+    description: "Transcribe audio from an organic Facebook reel/video/post/share URL (including fb.watch). Renders the page, selects the best public CDN MP4, and returns the transcript plus resolved video metadata.",
     inputSchema: FacebookVideoTranscribeInputSchema,
-    outputSchema: FacebookVideoTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("facebook_video_transcribe", FacebookVideoTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Organic Video Transcription")
   }, async (input) => formatFacebookVideoTranscribe(await executor.facebookVideoTranscribe(input), input));
   server.registerTool("instagram_profile_content", {
     title: "Instagram Profile Content Discovery",
-    description: withReportNote("Discover Instagram profile grid content links (posts/reels/tv) for a handle or profile URL, for later selection with instagram_media_download. Returns profile stats and collected URLs."),
+    description: "Discover Instagram profile grid content links (posts/reels/tv) for a handle or profile URL, for later selection with instagram_media_download. Returns profile stats and collected URLs.",
     inputSchema: InstagramProfileContentInputSchema,
-    outputSchema: InstagramProfileContentOutputSchema,
+    outputSchema: recordOutputSchema("instagram_profile_content", InstagramProfileContentOutputSchema),
     annotations: liveWebToolAnnotations("Instagram Profile Content Discovery")
   }, async (input) => formatInstagramProfileContent(await executor.instagramProfileContent(input), input));
   server.registerTool("instagram_media_download", {
     title: "Instagram Post/Reel Media Download",
-    description: withReportNote("Extract and download media from one Instagram post, reel, or tv URL \u2014 image, caption, video/audio tracks, optional muxed MP4, or transcript. Selects the best video/audio track pair and muxes when ffmpeg is available."),
+    description: "Extract and download media from one Instagram post, reel, or tv URL \u2014 image, caption, video/audio tracks, optional muxed MP4, or transcript. Selects the best video/audio track pair and muxes when ffmpeg is available.",
     inputSchema: InstagramMediaDownloadInputSchema,
-    outputSchema: InstagramMediaDownloadOutputSchema,
+    outputSchema: recordOutputSchema("instagram_media_download", InstagramMediaDownloadOutputSchema),
     annotations: liveWebToolAnnotations("Instagram Post/Reel Media Download")
   }, async (input) => formatInstagramMediaDownload(await executor.instagramMediaDownload(input), input));
   server.registerTool("maps_place_intel", {
     title: "Google Maps Business Profile Details",
-    description: withReportNote("Extract Google Maps business intelligence for one known/named business: rating, reviews, category, address, phone, hours, entity IDs. Not for category searches or multi-business prospect lists \u2014 use maps_search for those. Split business name from location."),
+    description: "Extract Google Maps business intelligence for one known/named business: rating, reviews, category, address, phone, hours, entity IDs. Not for category searches or multi-business prospect lists \u2014 use maps_search for those. Split business name from location.",
     inputSchema: MapsPlaceIntelInputSchema,
-    outputSchema: MapsPlaceIntelOutputSchema,
+    outputSchema: recordOutputSchema("maps_place_intel", MapsPlaceIntelOutputSchema),
     annotations: liveWebToolAnnotations("Google Maps Business Profile Details")
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote("Search Google Maps for multiple businesses by category, niche, or local market \u2014 leads, prospects, competitors, or beyond the 3-pack. Leave proxyMode unset. Returns up to 50 candidates (default 10) with names, place URLs, CIDs, ratings."),
+    description: "Search Google Maps for multiple businesses by category, niche, or local market \u2014 leads, prospects, competitors, or beyond the 3-pack. Leave proxyMode unset. Returns up to 50 candidates (default 10) with names, place URLs, CIDs, ratings.",
     inputSchema: MapsSearchInputSchema,
-    outputSchema: MapsSearchOutputSchema,
+    outputSchema: recordOutputSchema("maps_search", MapsSearchOutputSchema),
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets: selects US city markets from Census population data, optionally joins configured ZIP groups, then runs Google Maps business searches per city in parallel. Use for "all cities over 100k population in a state" or market+Maps workflows. Saves a CSV of results per city. For ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the server, or pass usZipsCsvPath in local/test mode.'),
+    description: `Build directory/prospecting datasets: selects US city markets from Census population data, optionally joins configured ZIP groups, then runs Google Maps business searches per city in parallel. Use for "all cities over 100k population in a state" or market+Maps workflows. ${fileBehavior("Saves a CSV of results per city.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")}`,
     inputSchema: DirectoryWorkflowInputSchema,
-    outputSchema: DirectoryWorkflowOutputSchema,
+    outputSchema: recordOutputSchema("directory_workflow", DirectoryWorkflowOutputSchema),
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
-  }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input));
+  }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input, ctx));
   server.registerTool("workflow_list", {
     title: "Workflow Catalog",
     description: "List MCP Scraper higher-level workflows and recipes \u2014 market analysis, ICP research, CRO audits, competitive positioning, content gap briefs, AI search visibility, and more. Returns runnable workflow ids plus tool-chain guidance.",
     inputSchema: WorkflowListInputSchema,
-    outputSchema: WorkflowListOutputSchema,
+    outputSchema: recordOutputSchema("workflow_list", WorkflowListOutputSchema),
     annotations: localPlanningToolAnnotations("Workflow Catalog")
   }, async (input) => formatWorkflowList(await executor.workflowList(input), input));
   server.registerTool("workflow_suggest", {
     title: "Workflow Intent Router",
     description: "Route a high-level business/research goal (market analysis, ICP research, CRO audit, competitor comparison, content gap brief, AI search visibility, etc) to the right MCP Scraper workflow/tool chain. Free; tells you what to run next.",
     inputSchema: WorkflowSuggestInputSchema,
-    outputSchema: WorkflowSuggestOutputSchema,
+    outputSchema: recordOutputSchema("workflow_suggest", WorkflowSuggestOutputSchema),
     annotations: localPlanningToolAnnotations("Workflow Intent Router")
   }, async (input) => formatWorkflowSuggest(input));
   server.registerTool("workflow_run", {
     title: "Run Workflow",
-    description: withReportNote("Start a higher-level MCP Scraper workflow (directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language). Use after workflow_suggest or workflow_list. Stepwise workflows return runId + nextStep \u2014 call workflow_step with the runId until done is true."),
+    description: "Start a higher-level MCP Scraper workflow (directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language). Use after workflow_suggest or workflow_list. Stepwise workflows return runId + nextStep \u2014 call workflow_step with the runId until done is true.",
     inputSchema: WorkflowRunInputSchema,
-    outputSchema: WorkflowRunOutputSchema,
+    outputSchema: recordOutputSchema("workflow_run", WorkflowRunOutputSchema),
     annotations: liveWebToolAnnotations("Run Workflow")
   }, async (input) => formatWorkflowRun(await executor.workflowRun(input), input));
   server.registerTool("workflow_step", {
     title: "Advance Workflow Step",
-    description: withReportNote("Run the next leg of a stepwise workflow started with workflow_run. Pass the runId; each call executes one step and returns its output plus nextStep. Keep calling with the same runId until done is true."),
+    description: "Run the next leg of a stepwise workflow started with workflow_run. Pass the runId; each call executes one step and returns its output plus nextStep. Keep calling with the same runId until done is true.",
     inputSchema: WorkflowStepInputSchema,
-    outputSchema: WorkflowStepOutputSchema,
+    outputSchema: recordOutputSchema("workflow_step", WorkflowStepOutputSchema),
     annotations: liveWebToolAnnotations("Advance Workflow Step")
   }, async (input) => formatWorkflowStep(await executor.workflowStep(input), input));
   server.registerTool("workflow_status", {
     title: "Workflow Status",
     description: "Fetch a hosted workflow run by id and list its current status and artifacts, to re-open a run or recover artifact ids. Use only a runId returned by workflow_run/workflow_step/workflow_status.",
     inputSchema: WorkflowStatusInputSchema,
-    outputSchema: WorkflowStatusOutputSchema,
+    outputSchema: recordOutputSchema("workflow_status", WorkflowStatusOutputSchema),
     annotations: liveWebToolAnnotations("Workflow Status")
   }, async (input) => formatWorkflowStatus(await executor.workflowStatus(input), input));
   server.registerTool("workflow_artifact_read", {
     title: "Read Workflow Artifact",
     description: "Read a workflow artifact back into context by run id and artifact id, so final deliverables are grounded in generated evidence rather than memory. Use workflow_status first when artifact ids are unknown. Use maxBytes to limit large artifacts.",
     inputSchema: WorkflowArtifactReadInputSchema,
-    outputSchema: WorkflowArtifactReadOutputSchema,
+    outputSchema: recordOutputSchema("workflow_artifact_read", WorkflowArtifactReadOutputSchema),
     annotations: liveWebToolAnnotations("Read Workflow Artifact")
   }, async (input) => formatWorkflowArtifactRead(await executor.workflowArtifactRead(input), input));
+  server.registerTool("report_artifact_read", {
+    title: "Read Report Artifact",
+    description: "Read back a stored report artifact by artifactId (returned by any tool whose result was too large to inline). Windowed: pass offset/maxBytes and keep reading until nextOffset is null.",
+    inputSchema: ReportArtifactReadInputSchema,
+    outputSchema: recordOutputSchema("report_artifact_read", ReportArtifactReadOutputSchema),
+    annotations: liveWebToolAnnotations("Read Report Artifact")
+  }, async (input) => {
+    const owner = artifactOwnerId(input.artifactId);
+    if (!owner || owner !== ownerId) {
+      return { content: [{ type: "text", text: "Artifact not found or not owned by this caller." }], isError: true };
+    }
+    const window2 = await readArtifactWindow(input.artifactId, input.offset ?? 0, input.maxBytes ?? 2e4);
+    if (!window2) {
+      return { content: [{ type: "text", text: "Artifact not found or expired." }], isError: true };
+    }
+    return {
+      content: [{ type: "text", text: window2.text }],
+      structuredContent: { artifactId: input.artifactId, text: window2.text, totalBytes: window2.totalBytes, nextOffset: window2.nextOffset }
+    };
+  });
   server.registerTool("rank_tracker_workflow", {
     title: "Rank Tracker Blueprint Builder",
     description: "Generate a build-ready database schema, cron plan, and implementation prompt for a rank tracker powered by MCP Scraper (Maps, organic, AI Overview, or PAA tracking). Local planning only \u2014 does not call the web or spend credits.",
     inputSchema: RankTrackerBlueprintInputSchema,
-    outputSchema: RankTrackerBlueprintOutputSchema,
+    outputSchema: recordOutputSchema("rank_tracker_workflow", RankTrackerBlueprintOutputSchema),
     annotations: localPlanningToolAnnotations("Rank Tracker Blueprint Builder")
   }, async (input) => buildRankTrackerBlueprint(input));
   server.registerTool("credits_info", {
     title: "MCP Scraper Credits & Costs",
     description: "Answer questions about MCP Scraper credits, usage limits, and concurrency upgrades \u2014 balance, tool costs, concurrency limits, billing URL. Does not expose payment methods or card information.",
     inputSchema: CreditsInfoInputSchema,
-    outputSchema: CreditsInfoOutputSchema,
+    outputSchema: recordOutputSchema("credits_info", CreditsInfoOutputSchema),
     annotations: {
       title: "MCP Scraper Credits & Costs",
       readOnlyHint: true,
@@ -27503,16 +27752,19 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
     }
   }, async (input) => formatCreditsInfo(await executor.creditsInfo(input), input));
 }
-var import_mcp, import_node_fs8, import_node_path11;
+var import_mcp, import_node_fs8, import_node_path11, import_node_crypto10;
 var init_paa_mcp_server = __esm({
   "src/mcp/paa-mcp-server.ts"() {
     "use strict";
     import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
     import_node_fs8 = require("fs");
     import_node_path11 = require("path");
+    import_node_crypto10 = require("crypto");
     init_version();
     init_mcp_response_formatter();
     init_server_instructions();
+    init_output_schema_registry();
+    init_report_artifact_offload();
     init_mcp_tool_schemas();
     init_rank_tracker_blueprint();
     init_mcp_response_formatter();
@@ -28724,7 +28976,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Save a Site Login to a Profile",
       description: "Save a logged-in browser session so this server can reuse a site the user is signed into (ChatGPT, Claude, Reddit, any account-gated site). Returns a watch_url; the user signs in fresh (existing browser cookies are NOT imported) and cookies save to a named profile. ONE profile holds MANY logins \u2014 call again with the same profile and a different domain to stack another account. NOT for one-off scraping (use extract_url) or driving the browser (use browser_open). After sign-in, poll browser_profile_list until AUTHENTICATED, then browser_open with the profile.",
       inputSchema: BrowserProfileConnectInputSchema,
-      outputSchema: BrowserProfileConnectOutputSchema,
+      outputSchema: recordOutputSchema("browser_profile_connect", BrowserProfileConnectOutputSchema),
       annotations: annotations("Save a Site Login to a Profile")
     },
     async (input) => {
@@ -28782,7 +29034,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "List Saved Logins in a Profile",
       description: "List every site login saved in a profile with its auth status (NEEDS_AUTH/AUTHENTICATED), email, and note. Use to check what's connected, or to poll a just-saved login until AUTHENTICATED. Read-only, no cost. Pass profile (or email to derive it); narrow with domain or connection_id.",
       inputSchema: BrowserProfileListInputSchema,
-      outputSchema: BrowserProfileListOutputSchema,
+      outputSchema: recordOutputSchema("browser_profile_list", BrowserProfileListOutputSchema),
       annotations: annotations("List Saved Logins in a Profile", true)
     },
     async (input) => {
@@ -28816,7 +29068,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Open Browser Session",
       description: "Open a direct no-proxy hosted browser session you can drive. Pass a saved profile name to load a session already logged into that profile's sites (set one up first with browser_profile_connect). Returns a session_id used by all other browser_* tools.",
       inputSchema: BrowserOpenInputSchema,
-      outputSchema: BrowserOpenOutputSchema,
+      outputSchema: recordOutputSchema("browser_open", BrowserOpenOutputSchema),
       annotations: annotations("Open Browser Session")
     },
     async (input) => {
@@ -28850,7 +29102,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "See Page (Screenshot + Elements)",
       description: "Capture what the browser currently shows: a screenshot plus a text snapshot of interactive elements with x,y coordinates, page url/title, and visible text. Primary way to perceive the page; click elements by their listed x,y. If a Cloudflare/CAPTCHA challenge is visible, wait and screenshot again rather than clicking it.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserScreenshotOutputSchema,
+      outputSchema: recordOutputSchema("browser_screenshot", BrowserScreenshotOutputSchema),
       annotations: annotations("See Page", true)
     },
     async (input) => {
@@ -28882,7 +29134,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Read Page Text + Elements",
       description: "Return the page url, title, visible text, and interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a click target.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserReadOutputSchema,
+      outputSchema: recordOutputSchema("browser_read", BrowserReadOutputSchema),
       annotations: annotations("Read Page", true)
     },
     async (input) => {
@@ -28906,7 +29158,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Locate DOM Targets",
       description: "Locate exact visible DOM elements or text ranges and return left/top/width/height bounds in screenshot pixels. Use before drawing annotations that must circle, box, underline, or point to a real element. Prefer CSS selectors; use text when selector is unknown.",
       inputSchema: BrowserLocateInputSchema,
-      outputSchema: BrowserLocateOutputSchema,
+      outputSchema: recordOutputSchema("browser_locate", BrowserLocateOutputSchema),
       annotations: annotations("Locate DOM Targets", true)
     },
     async (input) => {
@@ -28931,7 +29183,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Navigate To URL",
       description: "Navigate an existing browser session to a URL. Use browser_open first if no session exists; follow with browser_screenshot to see the loaded page.",
       inputSchema: BrowserGotoInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_goto", BrowserActionOutputSchema),
       annotations: annotations("Navigate To URL")
     },
     async (input) => {
@@ -28945,7 +29197,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Click",
       description: "Click a visible page target using screenshot pixel coordinates. Use x/y only from the latest browser_screenshot, browser_read, or browser_locate result; do not guess coordinates.",
       inputSchema: BrowserClickInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_click", BrowserActionOutputSchema),
       annotations: annotations("Click")
     },
     async (input) => {
@@ -28964,7 +29216,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Type Text",
       description: 'Type text into the currently focused browser field. Click or Tab to the field first if focus is uncertain. Use browser_press with ["Return"] to submit.',
       inputSchema: BrowserTypeInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_type", BrowserActionOutputSchema),
       annotations: annotations("Type Text")
     },
     async (input) => {
@@ -28978,7 +29230,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Scroll",
       description: "Scroll the page to reveal more content. Positive delta_y scrolls down; negative scrolls up.",
       inputSchema: BrowserScrollInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_scroll", BrowserActionOutputSchema),
       annotations: annotations("Scroll")
     },
     async (input) => {
@@ -28997,7 +29249,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Press Keys",
       description: "Press keyboard keys or combinations in the active browser session \u2014 submit, Escape, Tab navigation, select-all, or shortcuts. Use browser_type for text entry.",
       inputSchema: BrowserPressInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_press", BrowserActionOutputSchema),
       annotations: annotations("Press Keys")
     },
     async (input) => {
@@ -29011,7 +29263,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Start Recording",
       description: "Start recording an MP4 replay of the session. Returns replay_id and a download_url. Stop with browser_replay_stop.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserReplayStartOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_start", BrowserReplayStartOutputSchema),
       annotations: annotations("Start Recording")
     },
     async (input) => {
@@ -29034,7 +29286,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Stop Recording",
       description: "Stop a replay recording and expose its final view_url/download_url. Use browser_replay_download to save the MP4.",
       inputSchema: BrowserReplayStopInputSchema,
-      outputSchema: BrowserReplayStopOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_stop", BrowserReplayStopOutputSchema),
       annotations: annotations("Stop Recording")
     },
     async (input) => {
@@ -29057,7 +29309,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "List Replay Videos",
       description: "List replay recordings for a browser session, including view_url and download_url when available.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserListReplaysOutputSchema,
+      outputSchema: recordOutputSchema("browser_list_replays", BrowserListReplaysOutputSchema),
       annotations: annotations("List Replay Videos", true)
     },
     async (input) => {
@@ -29077,9 +29329,9 @@ function registerBrowserAgentMcpTools(server, opts) {
     "browser_replay_download",
     {
       title: "Download Replay MP4",
-      description: "Download a replay recording and save the MP4 under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
+      description: opts.savesReportsLocally === false ? "Download a replay recording. Returns the download_url; fetch it directly (nothing is saved on this hosted endpoint). Use after browser_replay_stop or browser_list_replays." : "Download a replay recording and save the MP4 under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
       inputSchema: BrowserReplayDownloadInputSchema,
-      outputSchema: BrowserReplayDownloadOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_download", BrowserReplayDownloadOutputSchema),
       annotations: annotations("Download Replay MP4")
     },
     async (input) => {
@@ -29103,7 +29355,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Mark Replay Annotation",
       description: "While a replay is actively recording, locate one exact DOM target and return a ready-to-use annotation with DOM bounds and replay-relative timing, instead of guessing start_seconds or rectangles. Pass the returned annotations to browser_replay_annotate after stopping the replay.",
       inputSchema: BrowserReplayMarkInputSchema,
-      outputSchema: BrowserReplayMarkOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_mark", BrowserReplayMarkOutputSchema),
       annotations: annotations("Mark Replay Annotation", true)
     },
     async (input) => {
@@ -29153,7 +29405,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Annotate Replay MP4",
       description: "Download a browser replay MP4, render visual annotations (circles/boxes/arrows/labels) over it, and save a new annotated MP4. Prefer annotations from browser_replay_mark for accurate timing; otherwise use exact bounds from browser_locate. Pass source_width/source_height if the replay video size differs from the screenshot coordinate space.",
       inputSchema: BrowserReplayAnnotateInputSchema,
-      outputSchema: BrowserReplayAnnotateOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_annotate", BrowserReplayAnnotateOutputSchema),
       annotations: annotations("Annotate Replay MP4")
     },
     async (input) => {
@@ -29195,7 +29447,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Close Browser Session",
       description: "Close and release a browser session when the task is done, to end active browser billing. Use browser_list_sessions first to recover a session_id.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserCloseOutputSchema,
+      outputSchema: recordOutputSchema("browser_close", BrowserCloseOutputSchema),
       annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     async (input) => {
@@ -29216,7 +29468,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "List Browser Sessions",
       description: "List browser sessions and their status, with a watch_url for each. Use to recover a session_id or decide which session to close.",
       inputSchema: BrowserListInputSchema,
-      outputSchema: BrowserListSessionsOutputSchema,
+      outputSchema: recordOutputSchema("browser_list_sessions", BrowserListSessionsOutputSchema),
       annotations: annotations("List Browser Sessions", true)
     },
     async (input) => {
@@ -29238,7 +29490,7 @@ function registerBrowserAgentMcpTools(server, opts) {
       title: "Capture AI Search Fan-Out",
       description: "Capture the query fan-out behind a ChatGPT or Claude web-search answer for AEO: sub-queries issued, every researched URL split into cited vs browsed-only, and top sourced sites. Returns raw structured data for you to classify and analyze. Set export=true for JSON/CSV/TSV/HTML artifacts. WRITE NOTE: passing prompt submits a real message in the user's logged-in account \u2014 only send when the user wants that; omit it to capture a prompt the user just ran. The session must already be open on chatgpt.com or claude.ai (see browser_profile_connect) while the prompt streams. NOT for Google AI Overview \u2014 use harvest_paa for that.",
       inputSchema: BrowserCaptureFanoutInputSchema,
-      outputSchema: BrowserCaptureFanoutOutputSchema,
+      outputSchema: recordOutputSchema("query_fanout_workflow", BrowserCaptureFanoutOutputSchema),
       annotations: annotations("Capture AI Search Fan-Out")
     },
     async (input) => {
@@ -29303,6 +29555,7 @@ var init_browser_agent_mcp_server = __esm({
     init_browser_agent_tool_schemas();
     init_replay_annotator();
     init_outbound_sanitize();
+    init_output_schema_registry();
   }
 });
 
@@ -29418,9 +29671,9 @@ var init_mcp_routes = __esm({
           enableJsonResponse: true
         });
         const consoleBaseUrl = process.env.BROWSER_AGENT_CONSOLE_URL?.trim() || baseUrl;
-        const server = buildPaaExtractorMcpServer(executor, { savesReportsLocally: false });
+        const server = buildPaaExtractorMcpServer(executor, { savesReportsLocally: false, ownerId: hashOwnerId(callerKey) });
         registerSerpIntelligenceCaptureTools(server, executor);
-        registerBrowserAgentMcpTools(server, { baseUrl, apiKey: callerKey, consoleBaseUrl });
+        registerBrowserAgentMcpTools(server, { baseUrl, apiKey: callerKey, consoleBaseUrl, savesReportsLocally: false });
         await server.connect(transport);
         return transport.handleRequest(c.req.raw);
       } catch {
@@ -29541,7 +29794,7 @@ async function listAuthConnectionsByProfile(profile) {
 }
 async function createSessionRow(input) {
   const db = getDb();
-  const id = `bas_${(0, import_node_crypto9.randomUUID)().replace(/-/g, "").slice(0, 20)}`;
+  const id = `bas_${(0, import_node_crypto11.randomUUID)().replace(/-/g, "").slice(0, 20)}`;
   await db.execute({
     sql: `INSERT INTO browser_agent_sessions (id, runtime_session_id, live_view_url, cdp_ws_url, status, label, user_id, concurrency_lock_id, last_action_at)
           VALUES (?, ?, ?, ?, 'open', ?, ?, ?, datetime('now'))`,
@@ -29610,7 +29863,7 @@ async function recordAction(input) {
     sql: `INSERT INTO browser_agent_actions (id, session_id, type, params_json, ok, error)
           VALUES (?, ?, ?, ?, ?, ?)`,
     args: [
-      `baa_${(0, import_node_crypto9.randomUUID)().replace(/-/g, "").slice(0, 20)}`,
+      `baa_${(0, import_node_crypto11.randomUUID)().replace(/-/g, "").slice(0, 20)}`,
       input.sessionId,
       input.type,
       input.params == null ? null : JSON.stringify(input.params),
@@ -29650,11 +29903,11 @@ async function listReplayRows(sessionId) {
   });
   return res.rows;
 }
-var import_node_crypto9, _ready2;
+var import_node_crypto11, _ready2;
 var init_browser_agent_db = __esm({
   "src/api/browser-agent-db.ts"() {
     "use strict";
-    import_node_crypto9 = require("crypto");
+    import_node_crypto11 = require("crypto");
     init_db();
     _ready2 = false;
   }
@@ -31780,7 +32033,7 @@ async function getKeys() {
   const privateKey = await (0, import_jose2.importPKCS8)(pem, "RS256", { extractable: true });
   const full = await (0, import_jose2.exportJWK)(privateKey);
   const publicJwk = { kty: full.kty, n: full.n, e: full.e };
-  const kid = (0, import_node_crypto10.createHash)("sha256").update(JSON.stringify({ e: publicJwk.e, kty: publicJwk.kty, n: publicJwk.n })).digest("base64url").slice(0, 16);
+  const kid = (0, import_node_crypto12.createHash)("sha256").update(JSON.stringify({ e: publicJwk.e, kty: publicJwk.kty, n: publicJwk.n })).digest("base64url").slice(0, 16);
   publicJwk.kid = kid;
   publicJwk.alg = "RS256";
   publicJwk.use = "sig";
@@ -31959,23 +32212,23 @@ async function validateAuthRequest(p) {
 }
 function pkceMatches(verifier, challenge) {
   if (!verifier) return false;
-  const computed = (0, import_node_crypto10.createHash)("sha256").update(verifier).digest("base64url");
+  const computed = (0, import_node_crypto12.createHash)("sha256").update(verifier).digest("base64url");
   return computed === challenge;
 }
 async function mintAccessToken(identity, scope, plan, audience) {
   const { privateKey, kid } = await getKeys();
-  return new import_jose2.SignJWT({ scope, plan }).setProtectedHeader({ alg: "RS256", kid }).setIssuer(ISSUER).setSubject(identity).setAudience(audience).setIssuedAt().setJti((0, import_node_crypto10.randomUUID)()).setExpirationTime(`${ACCESS_TTL_SECONDS}s`).sign(privateKey);
+  return new import_jose2.SignJWT({ scope, plan }).setProtectedHeader({ alg: "RS256", kid }).setIssuer(ISSUER).setSubject(identity).setAudience(audience).setIssuedAt().setJti((0, import_node_crypto12.randomUUID)()).setExpirationTime(`${ACCESS_TTL_SECONDS}s`).sign(privateKey);
 }
 function tokenErrorResponse(c, error, description, status) {
   return c.json({ error, error_description: description }, status);
 }
-var import_hono17, import_cookie, import_node_crypto10, import_jose2, ISSUER, RESOURCE, SCRAPER_RESOURCE, MEMORY_SCOPES, SCRAPER_SCOPES, SUPPORTED_SCOPES, ACCESS_TTL_SECONDS, REFRESH_TTL_SECONDS, CODE_TTL_SECONDS, ROTATION_GRACE_SECONDS, secureCookies, sessionCookieOptions, cachedKeys, oauthApp;
+var import_hono17, import_cookie, import_node_crypto12, import_jose2, ISSUER, RESOURCE, SCRAPER_RESOURCE, MEMORY_SCOPES, SCRAPER_SCOPES, SUPPORTED_SCOPES, ACCESS_TTL_SECONDS, REFRESH_TTL_SECONDS, CODE_TTL_SECONDS, ROTATION_GRACE_SECONDS, secureCookies, sessionCookieOptions, cachedKeys, oauthApp;
 var init_oauth_routes = __esm({
   "src/api/oauth-routes.ts"() {
     "use strict";
     import_hono17 = require("hono");
     import_cookie = require("hono/cookie");
-    import_node_crypto10 = require("crypto");
+    import_node_crypto12 = require("crypto");
     import_jose2 = require("jose");
     init_session();
     init_db();
@@ -32061,7 +32314,7 @@ var init_oauth_routes = __esm({
         }
       }
       const clientName = typeof body.client_name === "string" ? body.client_name : null;
-      const clientId = `client_${(0, import_node_crypto10.randomBytes)(16).toString("hex")}`;
+      const clientId = `client_${(0, import_node_crypto12.randomBytes)(16).toString("hex")}`;
       await registerClient(clientId, redirectUris, clientName);
       console.log("[oauth-dcr] register OK client_id=%s redirect_uris=%s", clientId, JSON.stringify(redirectUris));
       return c.json({
@@ -32114,7 +32367,7 @@ var init_oauth_routes = __esm({
       if (action === "deny") return redirectWithError(p.redirect_uri, p.state, "access_denied");
       if (action !== "approve") return c.text("unsupported action", 400);
       const scope = negotiateScope(p.scope, user, p.resource);
-      const code = `code_${(0, import_node_crypto10.randomBytes)(32).toString("base64url")}`;
+      const code = `code_${(0, import_node_crypto12.randomBytes)(32).toString("base64url")}`;
       const expiresAt = new Date(Date.now() + CODE_TTL_SECONDS * 1e3).toISOString();
       await putCode({
         code,
@@ -32153,7 +32406,7 @@ var init_oauth_routes = __esm({
         const plan = user ? resolvePlan(user) : "free";
         const audience = record.resource ?? RESOURCE();
         const accessToken = await mintAccessToken(record.identity, record.scope, plan, audience);
-        const refreshToken = `rt_${(0, import_node_crypto10.randomBytes)(40).toString("base64url")}`;
+        const refreshToken = `rt_${(0, import_node_crypto12.randomBytes)(40).toString("base64url")}`;
         await putRefresh({
           refresh_token: refreshToken,
           client_id: clientId,
@@ -32183,7 +32436,7 @@ var init_oauth_routes = __esm({
         const plan = user ? resolvePlan(user) : "free";
         const audience = record.resource ?? RESOURCE();
         const accessToken = await mintAccessToken(record.identity, record.scope, plan, audience);
-        const nextRefresh = `rt_${(0, import_node_crypto10.randomBytes)(40).toString("base64url")}`;
+        const nextRefresh = `rt_${(0, import_node_crypto12.randomBytes)(40).toString("base64url")}`;
         await rotateRefresh(refreshToken, {
           refresh_token: nextRefresh,
           client_id: record.client_id,