@analitikisler/ai-tag-debugger 0.20.1 → 0.22.0

package/src/mcp.js

@@ -29,7 +29,12 @@ import { checkTopic, discoverPlan, TOPICS } from "./discover.js";
 import { createProvider } from "./providers.js";
 import { savePlan } from "./plan.js";
 import { changesLines, sinceLastRun } from "./changes.js";
-import { DEFAULT_PROVIDERS, isCollectionEndpoint, parseTrackingRequest, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
+import { decodeGcd, DEFAULT_PROVIDERS, googleConsent, isCollectionEndpoint, parseTrackingRequest, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
+import { hitParams } from "./hit-params.js";
+import { CAMPAIGN_PARAMS, campaignParamsIn, withCampaignParams } from "./campaign.js";
+import { cmpFacts } from "./cmp.js";
+import { containerRows, loadSources } from "./containers.js";
+import { consentMatrixMarkdown, consentTable, runConsentScenarios } from "./consent.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -44,7 +49,7 @@ Two kinds of request: a PLAN is what should be tracked, an AUDIT is what the sit
 
 Before starting, ask the user which platforms to check and suggest the default (${DEFAULT_PROVIDERS.map((k) => TRACKING_PROVIDERS[k]).join(", ")}, plus any other platform the site turns out to use); pass their choice as providers, or leave it out for the default.
 
-To audit a journey yourself: call start_audit with the site URL and a journey (a ready-made one: ${Object.keys(JOURNEY_PRESETS).join(", ")}, or the user's own description), then browser_action one step at a time until the journey is done (each result shows the page and the tracking hits that step sent), then finish_audit (with against to check the run against a saved plan) to get the findings and the report. Explain the findings to the user in plain language.
+To audit a journey yourself: call start_audit with the site URL and a journey (a ready-made one: ${Object.keys(JOURNEY_PRESETS).join(", ")}, or the user's own description), then browser_action one step at a time until the journey is done (each result shows the page and the tracking hits that step sent), then finish_audit (with against to check the run against a saved plan) to get the findings and the report. Explain the findings to the user in plain language. When a question needs a hit's raw parameters (client id, gcs, gcd decoded per consent signal, session flags), call get_hit with the step number and the hit's [h] number; get_step shows an earlier step again.
 
 While browsing:
 ${SYSTEM_PROMPT.split("How to work:\n")[1]}`;
@@ -82,28 +87,34 @@ function wholeFieldsIn(value, depth = 0, out = []) {
   return out;
 }
 
-function describeHit(h, steps) {
+const consentText = (c) => Object.entries(c).map(([k, v]) => `${k}=${v}`).join(" ");
+/** The Google protocol fields of a hit, short: values for the ids and consent strings, bare names for the 1-flags. */
+const protocolText = (p) => Object.entries(p).map(([k, v]) => (["_fv", "_ss", "_nsi"].includes(k) && v === "1" ? k : `${k}=${v}`)).join(" ");
+
+function describeHit(h, steps, index) {
   const entries = Object.entries(h.params ?? {}).filter(([k]) => !["v", "tid", "gtm", "_p", "cid", "sid", "_s", "sct", "seg", "dl", "dr", "dt", "ul", "sr", "_et", "en"].includes(k));
   const params = [
     ...entries.filter(([k]) => !WHOLE_FIELDS.has(k)).slice(0, 12).map(([k, v]) => cut(`${k}=${show(v)}`, VALUE_LIMIT)),
     ...entries.filter(([k]) => WHOLE_FIELDS.has(k)).map(([k, v]) => `${k}=${show(v)}`),
   ].join(", ");
   const late = h.late ? ` (arrived ${(h.late.ms / 1000).toFixed(1)} s late, after the step that loaded its page: "${steps[h.step]?.label ?? `step ${h.step}`}")` : "";
-  return `- ${h.platform} ${h.name}${h.consent ? ` [consent ${Object.entries(h.consent).map(([k, v]) => `${k}=${v}`).join(" ")}]` : ""}${params ? `: ${params}` : ""}${late}`;
+  return `- [h${index}] ${h.platform} ${h.name}${h.consent ? ` [consent ${consentText(h.consent)}]` : ""}${h.protocol ? ` {${protocolText(h.protocol)}}` : ""}${params ? `: ${params}` : ""}${late}`;
 }
 
 /** A consent command in full, as key=value; any other push as JSON, cut, with its page address fields whole. */
 function describePush(p) {
+  // Pushes to a dataLayer of another name (a container's l=) say which.
+  const layer = p.layer ? `[${p.layer}] ` : "";
   if (isConsentCommand(p, "default") || isConsentCommand(p, "update")) {
     const signals = p.value[2] && typeof p.value[2] === "object" ? Object.entries(p.value[2]).map(([k, v]) => `${k}=${show(v)}`).join(" ") : show(p.value[2]);
-    return `- consent ${p.value[1]}: ${signals}`;
+    return `- ${layer}consent ${p.value[1]}: ${signals}`;
   }
   const json = JSON.stringify(p.value) ?? String(p.value);
   const whole = json.length > PUSH_LIMIT ? wholeFieldsIn(p.value) : [];
-  return `- ${cut(json, PUSH_LIMIT)}${whole.length ? ` (${whole.map(([k, v]) => `${k}=${v}`).join(", ")})` : ""}`;
+  return `- ${layer}${cut(json, PUSH_LIMIT)}${whole.length ? ` (${whole.map(([k, v]) => `${k}=${v}`).join(", ")})` : ""}`;
 }
 
-/** A call to a tracking endpoint that carries no event the tool reads, such as a Consent Mode ping, with its consent parameters. */
+/** A call to a tracking endpoint that carries no event the tool reads, such as a Consent Mode ping, with its consent. */
 function describeCall(c) {
   let u;
   try {
@@ -111,8 +122,42 @@ function describeCall(c) {
   } catch {
     return `- ${c.vendor ?? c.provider} ${cut(c.url, VALUE_LIMIT)}`;
   }
-  const signals = ["gcs", "gcd", "dma", "npa"].filter((k) => u.searchParams.has(k)).map((k) => `${k}=${u.searchParams.get(k)}`).join(" ");
-  return `- ${c.vendor ?? c.provider}: ${u.hostname}${u.pathname}${signals ? ` [${signals}]` : ""}`;
+  const consent = googleConsent(u.searchParams);
+  // gclid is the landing click id the ping reports (0 when ads_data_redaction blanks it), gclaw the one _gcl_aw holds.
+  const signals = ["gcs", "gcd", "dma", "npa", "gclid", "gclaw"].filter((k) => u.searchParams.has(k))
+    .map((k) => `${k}=${u.searchParams.get(k)}${k === "gclid" && u.searchParams.get(k) === "0" ? " (redacted)" : ""}`).join(" ");
+  return `- ${c.vendor ?? c.provider}: ${u.hostname}${u.pathname}${signals ? ` [${signals}]` : ""}${consent ? ` [consent ${consentText(consent)}]` : ""}`;
+}
+
+const NAMES_SHOWN = 15;
+/** The cookies a step added, changed or removed, by name, and what the analytics and ad cookies say when that changed. */
+function cookieLines(session, step) {
+  const lines = [];
+  const changes = (session.cookieChanges ?? []).filter((c) => c.step === step);
+  const names = (kind) => [...new Set(changes.filter((c) => c.change === kind).map((c) => c.name))];
+  const part = (label, list) => (list.length ? `${label} ${list.slice(0, NAMES_SHOWN).join(", ")}${list.length > NAMES_SHOWN ? ` and ${list.length - NAMES_SHOWN} more` : ""}` : null);
+  const parts = [part("added", names("added")), part("changed", names("changed")), part("removed", names("removed"))].filter(Boolean);
+  if (parts.length) lines.push(`Cookies (names only): ${parts.join("; ")}`);
+  const id = session.steps[step]?.identity;
+  const before = session.steps.slice(0, step).map((st) => st.identity).filter(Boolean).at(-1);
+  if (!id || (!parts.length && JSON.stringify(id) === JSON.stringify(before))) return lines;
+  const facts = [];
+  if (id.ga_client_id) {
+    const prev = before?.ga_client_id;
+    const since = session.steps.findIndex((st) => st.identity?.ga_client_id === id.ga_client_id);
+    facts.push(`GA4 client id (_ga) ${id.ga_client_id}, ${!prev ? "new at this step" : prev === id.ga_client_id ? `the same since step ${since}` : `changed from ${prev}`}`);
+  }
+  if (id.gcl_aw) facts.push(id.gcl_aw === "landing" ? "_gcl_aw holds the landing gclid" : "_gcl_aw holds a gclid other than the landing one");
+  if (id.fbc) facts.push(id.fbc === "landing" ? "_fbc holds the landing fbclid" : "_fbc holds an fbclid other than the landing one");
+  if (facts.length) lines.push(`${facts.join("; ")}.`);
+  return lines;
+}
+
+/** One container load in words: its ID, what inserted it, its dataLayer and where it came from. */
+function describeLoad(l) {
+  const c = messages("en").ui.containers;
+  const extra = [l.layer !== "dataLayer" && `dataLayer ${l.layer}`, l.served === "site" && `served from ${l.host}`, l.environment && c.environment(l.environment)].filter(Boolean);
+  return `  ${l.id} (${c.script[l.script]}): ${c.kinds[l.kind](l.by)}${extra.length ? `; ${extra.join(", ")}` : ""}`;
 }
 
 export function stepCapture(audit, step) {
@@ -122,13 +167,137 @@ export function stepCapture(audit, step) {
   // Hits that arrived during this step for a page an earlier step loaded are listed there, and noted here.
   const lateHere = session.hits.filter((h) => h.late?.during === step);
   const pings = session.network.filter((c) => c.step === step && isCollectionEndpoint(c.url) && !parseTrackingRequest(c.url, c.postData ?? null));
-  const lines = [`Tracking hits sent by this step: ${hits.length}`, ...hits.map((h) => describeHit(h, session.steps))];
+  const problem = session.steps[step]?.pageProblem;
+  const lines = [
+    ...(problem?.kind === "challenge" ? [`WARNING: the page is a bot challenge from ${problem.vendor}, not the site. Nothing captured here says anything about the site's tracking; run the audit from a network the site trusts.`] : []),
+    ...(problem?.kind === "crash" ? [`WARNING: the page crashed in the browser (the ${problem.vendor} error screen)${problem.refusedScripts ? `; ${problem.refusedScripts} of its own scripts came back as HTML pages, which bot protection or a mismatched deployment does` : ""}. Its tags may never have run.`] : []),
+    `Step ${step}: "${session.steps[step]?.label ?? ""}". Read a hit's full parameters with get_hit (audit_id, step ${step}, its [h] number).`,
+    `Tracking hits sent by this step: ${hits.length}`,
+    ...hits.map((h, i) => describeHit(h, session.steps, i)),
+  ];
   if (lateHere.length) lines.push(`Arrived during this step but belong to the step that loaded their page: ${lateHere.map((h) => `${h.platform} ${h.name} (step "${session.steps[h.step]?.label ?? h.step}")`).join(", ")}`);
   if (pings.length) lines.push("Other calls to analytics and ad endpoints, not read as events (Consent Mode pings, resends, remarketing):", ...pings.map(describeCall));
   if (pushes.length) lines.push("dataLayer pushes:", ...pushes.map(describePush));
+  const loads = loadSources({ containerLoads: (session.containerLoads ?? []).filter((l) => l.step === step), dataLayerLog: session.dataLayerLog });
+  if (loads.length) lines.push("Google containers loaded:", ...loads.map(describeLoad));
+  lines.push(...cookieLines(session, step));
+  const tag = session.steps[step]?.tagConsent;
+  if (tag) {
+    const state = (e) => (e.default && e.update ? `${e.default} → ${e.update}` : e.default ? `${e.default} (default)` : e.update ? `${e.update} (update)` : "not set");
+    const flags = [tag.usedDefault ? "default applied" : "no default applied", tag.usedUpdate && "update applied", tag.wasSetLate && "default set late", tag.waitPeriodTimedOut && "wait_for_update ran out"].filter(Boolean);
+    lines.push(`Google tag consent state (google_tag_data.ics), changed at this step: ${Object.entries(tag.entries).map(([k, e]) => `${k} ${state(e)}`).join(", ")}; ${flags.join(", ")}.`);
+  }
+  // The consent platform once, on the step it was first seen at.
+  const platform = session.cmp?.step === step ? cmpFacts(messages("en"), [{ cmp: session.cmp, network: session.network }]) : null;
+  if (platform) lines.push(`Consent platform: ${platform.vendor}. ${platform.facts.join(" ")}`);
+  return lines.join("\n");
+}
+
+const MAX_PARAM_VALUE = 2000;
+/** What a gcd letter says about one signal, in words. */
+function gcdWords({ letter, default: d, update: u, known }) {
+  if (!known) return `${letter}: a letter this tool doesn't know`;
+  if (!d && !u) return `${letter}: consent mode not used`;
+  return `${letter}: ${d ? `${d} by default` : "no default"}, ${u ? `${u} by update` : "no update"}`;
+}
+
+/** One hit in full: where it was sent, its consent and every parameter its request carried. */
+export function hitDetail(audit, step, index) {
+  const { session } = audit;
+  const hits = session.hits.filter((h) => h.step === step);
+  const h = hits[index];
+  if (!h) return null;
+  const { call, batch, event, context } = hitParams(session, h);
+  const label = session.steps[step]?.label ?? "";
+  const rows = (entries) => entries.map(([k, v]) => `  ${k} = ${cut(String(v), MAX_PARAM_VALUE)}`);
+  const lines = [`[h${index}] ${h.platform} ${h.name}, step ${step} "${label}"${h.late ? `, sent ${(h.late.ms / 1000).toFixed(1)} s late during step ${h.late.during} "${session.steps[h.late.during]?.label ?? ""}"` : ""}`];
+  lines.push(`Request: ${call ? `${call.method ?? ""} ${call.url}`.trim() : h.url}${call?.blocked ? " (answered locally, never reached the platform)" : ""}`);
+  if (h.consent) lines.push(`Consent: ${consentText(h.consent)}`);
+  const gcd = decodeGcd(h.protocol?.gcd);
+  if (gcd) lines.push(`gcd ${h.protocol.gcd}: ${Object.entries(gcd).map(([signal, state]) => `${signal} ${gcdWords(state)}`).join("; ")}`);
+  if (h.userData?.fields?.length) lines.push(`User data redacted from this hit: ${h.userData.fields.join(", ")}`);
+  lines.push(`Event parameters${batch ? ` (event ${batch[0]} of ${batch[1]} in one request)` : ""}:`, ...(event.length ? rows(event) : ["  (none)"]));
+  if (context.length) lines.push("Other parameters (ids, page, device, consent):", ...rows(context));
   return lines.join("\n");
 }
 
+/**
+ * One entry per step, short enough to return with finish_audit and read without the report: what the step did, the
+ * hits it sent with their consent, its consent commands and other tracking calls, the Google tag's consent when it
+ * changed, and the cookies and ids that changed.
+ */
+/** A container load or row as compact JSON: the ID, its source, and the dataLayer, host and environment when they are not the usual ones. */
+function containerJson(l) {
+  return {
+    id: l.id, source: l.kind, ...(l.by ? { by: l.by } : {}),
+    ...(l.layer !== "dataLayer" ? { data_layer: l.layer } : {}),
+    ...(l.served === "site" ? { served_from: l.host } : {}),
+    ...(l.environment ? { gtm_environment: l.environment } : {}),
+    ...(l.pages ? { pages: l.pages } : {}),
+  };
+}
+
+/** The Google containers of the runs and how each reached the page, as lines for a tool result; [] when none loaded. */
+export function containerLines(runs) {
+  const rows = containerRows(runs);
+  if (!rows.length) return [];
+  const c = messages("en").ui.containers;
+  return [
+    "Google containers (how each reached the page):",
+    ...rows.map((r) => {
+      const extra = [r.layer !== "dataLayer" && `dataLayer ${r.layer}`, r.served === "site" && `served from ${r.host}`, r.environment && c.environment(r.environment), `${r.pages.length} ${r.pages.length === 1 ? "page" : "pages"}`].filter(Boolean);
+      return `  ${r.id} (${c.script[r.script]}): ${c.kinds[r.kind](r.by)}; ${extra.join(", ")}`;
+    }),
+  ];
+}
+
+export function timelineOf(run) {
+  let lastIds = null;
+  return (run.steps ?? []).map((st) => {
+    const hits = (run.hits ?? []).filter((h) => h.step === st.index);
+    const commands = (run.dataLayerLog ?? []).filter((e) => e.step === st.index && (isConsentCommand(e, "default") || isConsentCommand(e, "update")));
+    const others = (run.network ?? []).filter((c) => c.step === st.index && isCollectionEndpoint(c.url) && !parseTrackingRequest(c.url, c.postData ?? null));
+    const changes = (run.cookieChanges ?? []).filter((c) => c.step === st.index);
+    const names = (kind) => [...new Set(changes.filter((c) => c.change === kind).map((c) => c.name))];
+    const entry = { step: st.index, action: st.label, ...(st.pagePath ? { page: st.pagePath } : {}) };
+    if (st.error) entry.error = st.error;
+    if (hits.length) entry.hits = hits.map((h) => ({ platform: h.platform, event: h.name, ...(h.consent ? { consent: h.consent } : {}), ...(h.late ? { late_ms: h.late.ms } : {}) }));
+    if (others.length) entry.other_tracking_calls = others.length;
+    if (commands.length) entry.consent_commands = commands.map((e) => ({ [e.value[1]]: e.value[2] }));
+    if (st.tagConsent) entry.tag_consent = Object.fromEntries(Object.entries(st.tagConsent.entries).map(([k, e]) => [k, e.update ?? e.default ?? null]));
+    const cookies = Object.fromEntries(["added", "changed", "removed"].map((k) => [k, names(k)]).filter(([, list]) => list.length));
+    if (Object.keys(cookies).length) entry.cookies = cookies;
+    const loads = loadSources({ containerLoads: (run.containerLoads ?? []).filter((l) => l.step === st.index), dataLayerLog: run.dataLayerLog });
+    if (loads.length) entry.containers = loads.map(containerJson);
+    if (st.identity && JSON.stringify(st.identity) !== JSON.stringify(lastIds)) entry.ids = st.identity;
+    if (st.identity) lastIds = st.identity;
+    return entry;
+  });
+}
+
+const campaignSchema = () => z.union([z.boolean(), z.object(Object.fromEntries(CAMPAIGN_PARAMS.map((k) => [k, z.string().min(1).optional()]))).strict()]).optional();
+const CAMPAIGN_DOC = `Default true: test values (utm_source=aitd, gclid=aitd-gclid, fbclid=aitd-fbclid...) unless the site address already carries campaign parameters. false opens the site as given. Or your own values, e.g. {"utm_source": "newsletter", "utm_campaign": "autumn", "gclid": "test123"}; allowed keys: ${CAMPAIGN_PARAMS.join(", ")}.`;
+
+const LIVE_NOTE = "LIVE: tracking requests go to the real analytics and ad accounts, so this test traffic shows in their reports (GA4 Realtime and DebugView, Meta Events Manager).";
+
+const OFFSCREEN_SHOWN = 40;
+const UNCHANGED_TEXT = "(unchanged since the last page view)";
+const UNCHANGED_ELEMENTS = "(unchanged since the last page view: the same refs still apply)";
+const DETAIL_DOC = "compact (default for browser_action): up to 40 elements above or below the screen, and the page text or element list replaced by a note when unchanged since the last view. full: every element and the whole text again.";
+
+/**
+ * The page view for the chat app. Long sessions lose their oldest results from the context, so a compact view
+ * leaves out what the last one already showed: the same text, the same elements (and so the same refs).
+ */
+async function viewFor(audit, error, detail = "compact") {
+  const full = detail === "full";
+  const snap = await audit.session.snapshot({ offscreenLimit: full ? null : OFFSCREEN_SHOWN });
+  const last = audit.lastView;
+  audit.lastView = { url: snap.url, text: snap.text, elements: snap.elements };
+  if (full || !last || last.url !== snap.url) return pageView(snap, error);
+  return pageView({ ...snap, text: snap.text === last.text ? UNCHANGED_TEXT : snap.text, elements: snap.elements === last.elements ? UNCHANGED_ELEMENTS : snap.elements }, error);
+}
+
 function getAudit(id) {
   const audit = audits.get(id);
   if (!audit) throw new Error(`No open audit "${id}". Start one with start_audit. Audits close after ${IDLE_MS / 60000} minutes without activity.`);
@@ -187,6 +356,8 @@ async function loadAgainst(ref, site, opts) {
  */
 export function buildServer(opts) {
   const server = new McpServer({ name: "ai-tag-debugger", version: VERSION }, { instructions: INSTRUCTIONS });
+  // The reports this server wrote, by folder name: get_report reads these and nothing else, over HTTP too.
+  const written = new Map();
 
   server.registerTool(
     "start_audit",
@@ -209,9 +380,11 @@ export function buildServer(opts) {
           .array(z.enum(Object.keys(TRACKING_PROVIDERS)))
           .optional()
           .describe(`Tracking providers to check. Default ${DEFAULT_PROVIDERS.join(", ")} plus any other known platform the site sends to. When given, requests to the others are still answered locally, but they are only counted, not shown or checked.`),
+        campaign: campaignSchema().describe(`Open the first page the way an ad click does, so finish_audit checks that the campaign parameters survive redirects and reach the hits. ${CAMPAIGN_DOC}`),
+        live: z.boolean().optional().describe("Default false: tracking requests are answered locally and never reach the site's accounts. true lets them through to the real analytics and ad accounts, to check them in GA4 Realtime or DebugView, Meta Events Manager or Tag Assistant: the test traffic then shows in the site's reports. Only when the user asks for it."),
       },
     },
-    async ({ site, journey, viewport, allowed_hosts, providers }) => {
+    async ({ site, journey, viewport, allowed_hosts, providers, campaign = true, live = false }) => {
       let url;
       try {
         url = new URL(site);
@@ -227,7 +400,8 @@ export function buildServer(opts) {
       if (audits.size >= MAX_OPEN_AUDITS) return fail(`${audits.size} audits are already open. Finish one with finish_audit first.`);
       let session;
       try {
-        session = new AuditSession({ viewport: viewport ?? "desktop", site: url.href, allowedHosts: allowed_hosts, providers, blockPrivate: opts.blockPrivate });
+        if (live && !opts.allowLive) return fail("Live audits are off on this server: it was started without --allow-live. Leave live out to audit with tracking requests answered locally.");
+        session = new AuditSession({ viewport: viewport ?? "desktop", site: url.href, allowedHosts: allowed_hosts, providers, blockPrivate: opts.blockPrivate, blockHits: !live });
       } catch (err) {
         return fail(err.message);
       }
@@ -242,10 +416,14 @@ export function buildServer(opts) {
       const name = preset?.id ?? ((journey || "journey").toLowerCase().replace(/[^\w-]+/g, "-").slice(0, 40) || "journey");
       const audit = { id, session, site: url.href, journey: name, preset, viewport: viewport ?? "desktop", lastUsed: Date.now() };
       audits.set(id, audit);
-      const error = await session.act({ action: "goto", url: url.href, reason: `Open ${url.href}` });
-      const page = pageView(await session.snapshot(), error);
+      const start = campaign === false ? url.href : withCampaignParams(url.href, typeof campaign === "object" ? campaign : null);
+      const error = await session.act({ action: "goto", url: start, reason: `Open ${start}` });
+      const page = await viewFor(audit, error);
       const goal = preset ? `Journey goal: ${preset.goal}\nEvents expected on the way: ${preset.events.map((e) => `${e.platform} ${e.name}`).join(", ")}\n\n` : "";
-      return text(`audit_id: ${id}\n${goal}\n${page}\n\n${stepCapture(audit, session.currentStep)}`);
+      const sent = campaignParamsIn(start);
+      const opened = Object.keys(sent).length ? `Opened like an ad click with ${Object.entries(sent).map(([k, v]) => `${k}=${v}`).join(", ")}; finish_audit checks that they survive redirects and reach the hits.\n` : "";
+      const liveLine = live ? `${LIVE_NOTE}\n` : "";
+      return text(`audit_id: ${id}\n${liveLine}${opened}${goal}\n${page}\n\n${stepCapture(audit, session.currentStep)}`);
     },
   );
 
@@ -265,6 +443,7 @@ export function buildServer(opts) {
         reason: z.string().describe("Short description of the step, e.g. 'Add the first product to the cart'. Shown in the report."),
         accepts_consent: z.boolean().optional().describe("True only when this click accepts the cookie or consent banner."),
         rejects_consent: z.boolean().optional().describe("True only when this click rejects or declines all cookies on the consent banner."),
+        detail: z.enum(["compact", "full"]).optional().describe(DETAIL_DOC),
       },
     },
     async (input) => {
@@ -272,7 +451,7 @@ export function buildServer(opts) {
       if (["click", "fill", "select"].includes(input.action) && !Number.isInteger(input.ref) && !input.text?.trim()) return fail(`${input.action} needs a ref or text.`);
       if (input.action === "goto" && !input.url) return fail("goto needs a url.");
       const error = await audit.session.act(input);
-      const page = pageView(await audit.session.snapshot(), error);
+      const page = await viewFor(audit, error, input.detail);
       return text(`${page}\n\n${stepCapture(audit, audit.session.currentStep)}`);
     },
   );
@@ -281,11 +460,134 @@ export function buildServer(opts) {
     "get_page",
     {
       title: "Show the current page",
-      description: "Returns the current page view of an open audit without doing anything.",
+      description: "Returns the current page view of an open audit without doing anything. By default in full: every element and the whole page text.",
+      inputSchema: { audit_id: z.string(), detail: z.enum(["compact", "full"]).optional().describe(`Default full here. ${DETAIL_DOC}`) },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ audit_id, detail = "full" }) => text(await viewFor(getAudit(audit_id), null, detail)),
+  );
+
+  server.registerTool(
+    "get_hit",
+    {
+      title: "Show one tracking hit in full",
+      description:
+        "Returns every parameter one tracking hit's request carried (client and session ids, gcs and gcd with gcd decoded per consent signal, page, device and event parameters), where it was sent, and its consent. Step results list each hit with an [h] number; pass that and the step number.",
+      inputSchema: {
+        audit_id: z.string(),
+        step: z.number().int().min(0).describe("The step number from the step result's first line."),
+        hit: z.number().int().min(0).describe("The hit's [h] number in that step."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ audit_id, step, hit }) => {
+      const audit = getAudit(audit_id);
+      const detail = hitDetail(audit, step, hit);
+      if (detail !== null) return text(detail);
+      const count = audit.session.hits.filter((h) => h.step === step).length;
+      return fail(step >= audit.session.steps.length ? `There is no step ${step}; the last is ${audit.session.steps.length - 1}.` : `Step ${step} has ${count} hit${count === 1 ? "" : "s"}${count ? ` (h0 to h${count - 1})` : ""}.`);
+    },
+  );
+
+  server.registerTool(
+    "get_step",
+    {
+      title: "Show an earlier step's capture again",
+      description:
+        "Returns what an earlier step captured, as browser_action showed it: its hits, other tracking calls and dataLayer pushes. Use it to see a step again, for example after a hit that arrived late was added to the step that loaded its page.",
+      inputSchema: { audit_id: z.string(), step: z.number().int().min(0).describe("The step number from the step result's first line.") },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ audit_id, step }) => {
+      const audit = getAudit(audit_id);
+      if (step >= audit.session.steps.length) return fail(`There is no step ${step}; the last is ${audit.session.steps.length - 1}.`);
+      return text(stepCapture(audit, step));
+    },
+  );
+
+  server.registerTool(
+    "get_containers",
+    {
+      title: "List the Google containers loaded so far",
+      description:
+        "Returns every GTM container (gtm.js) and Google tag (gtag/js) this audit's pages loaded so far, and how each reached the page: a script tag in the HTML, the inline snippet, another script (named by its address, such as a consent platform), a Custom HTML tag or a Google tag in another GTM container, a container loading another itself (a Zone or a tag template), a gtag('config') command, an event's send_to with no config, or a destination of the Google tag. Also the dataLayer each reads, whether it was served from the site's own domain, the GTM environment when one is named, and the step it loaded at. Duplicates, GTM environments and split dataLayers are flagged by finish_audit.",
       inputSchema: { audit_id: z.string() },
       annotations: { readOnlyHint: true },
     },
-    async ({ audit_id }) => text(pageView(await getAudit(audit_id).session.snapshot())),
+    async ({ audit_id }) => {
+      const { session } = getAudit(audit_id);
+      const loads = loadSources({ containerLoads: session.containerLoads ?? [], dataLayerLog: session.dataLayerLog });
+      if (!loads.length) return text("No GTM container or Google tag script has loaded on this audit's pages yet.");
+      const lines = loads.map((l) => `Step ${l.step} ("${session.steps[l.step]?.label ?? ""}"), ${l.page ?? "?"}:\n${describeLoad(l)}`);
+      return text(`${loads.length} container ${loads.length === 1 ? "load" : "loads"}:\n${lines.join("\n")}\n\nAs JSON: ${JSON.stringify(loads.map((l) => ({ step: l.step, page: l.page, ...containerJson(l) })))}`);
+    },
+  );
+
+  server.registerTool(
+    "get_report",
+    {
+      title: "Read a report this server wrote",
+      description:
+        "Returns a report finish_audit or run_audit wrote, so it can be read without access to the computer running this server. part markdown (default): report.md, the verdict, findings, consent and journeys in about 120 lines. summary: summary.json, the counts, journeys and findings as JSON. timeline: one JSON entry per step of each journey (hits with their consent, consent commands, the Google tag's consent, cookies and ids, the Google containers loaded). containers: every GTM container and Google tag the journeys loaded as JSON, with how each reached the page (source html, inline, script, custom_html, google_tag, nested, config, send_to or destination, and by: the container or script that loaded it), its dataLayer, host, GTM environment and pages.",
+      inputSchema: {
+        report: z.string().describe("The report name finish_audit or run_audit gave."),
+        part: z.enum(["markdown", "summary", "timeline", "containers"]).optional().describe("Default markdown."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ report, part = "markdown" }) => {
+      const dir = written.get(report);
+      if (!dir) return fail(written.size ? `No report "${report}" from this server. Its reports: ${[...written.keys()].join(", ")}.` : "This server has written no report yet.");
+      try {
+        if (part === "markdown") return text(await readFile(path.join(dir, "report.md"), "utf8"));
+        if (part === "summary") return text(await readFile(path.join(dir, "summary.json"), "utf8"));
+        const capture = JSON.parse(await readFile(path.join(dir, "capture.json"), "utf8"));
+        if (part === "containers") return text(JSON.stringify(containerRows(capture.runs ?? []).map(containerJson)));
+        return text(JSON.stringify((capture.runs ?? []).map((r) => ({ journey: r.journeyId, viewport: r.viewport, steps: timelineOf(r) }))));
+      } catch (err) {
+        return fail(`Could not read the report: ${err.message}`);
+      }
+    },
+  );
+
+  server.registerTool(
+    "consent_matrix",
+    {
+      title: "Compare every consent choice side by side",
+      description:
+        "Opens the site's start page like an ad click in a fresh browser once per consent choice: no choice and on to the next page, accept all, reject all and analytics only. Returns which tags sent after each choice, and a matrix of the first Google hit's consent, whether the campaign parameters reached it, whether the GA4 client id was kept, the _gcl_aw cookie, the cookies set, when each tag was called and the Google tag's own consent, with what should not happen marked. Needs a consent banner the tool can answer. Takes about half a minute per choice.",
+      inputSchema: {
+        site: z.string().describe("The page to start from, e.g. https://www.example.com/"),
+        campaign: campaignSchema().describe(`The campaign parameters to open the start page with, as the UTM check. ${CAMPAIGN_DOC}`),
+        providers: z.array(z.enum(Object.keys(TRACKING_PROVIDERS))).optional().describe(`Tracking providers to count. Default ${DEFAULT_PROVIDERS.join(", ")} plus any other known platform the site sends to.`),
+        allowed_hosts: z.array(z.string()).optional().describe("Other hosts the pages may load from or redirect to."),
+        concurrency: z.number().int().min(1).max(4).optional().describe("How many choices to try at once, each in its own browser. Default 2."),
+        language: z.enum(Object.keys(LANGUAGES)).optional().describe("Language of the answer. Default en."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ site, campaign, providers, allowed_hosts, concurrency = 2, language = "en" }) => {
+      let url;
+      try {
+        url = new URL(site);
+        if (!["http:", "https:"].includes(url.protocol)) throw new Error();
+      } catch {
+        return fail("site must be an http or https URL.");
+      }
+      if (opts.blockPrivate) {
+        const refused = await navigationError(url.href, { isPrivate: privateHostChecker() });
+        if (refused) return fail(`${refused} Over HTTP, audits are limited to public websites.`);
+      }
+      const config = { site: url.href, providers, allowed_hosts };
+      const sc = await runConsentScenarios(config, { campaign, concurrency, ...(opts.blockPrivate ? { blockPrivate: opts.blockPrivate } : {}) });
+      if (!sc) return text(`No consent banner the tool can answer was found on ${url.href}, so the choices could not be compared. Walk the journey with start_audit and browser_action instead.`);
+      const m = messages(language);
+      const table = consentTable(sc);
+      const lines = [`Consent banner answered through: ${sc.cmp}.`, "", `| | ${table.cols.map((c) => m.ui.scenarioCols[c]).join(" | ")} |`, `|${" --- |".repeat(table.cols.length + 1)}`];
+      for (const r of table.rows) lines.push(`| ${TRACKING_PROVIDERS[r.platform] ?? r.platform} ${r.event} | ${r.cells.map((c) => (c.count === null ? "–" : `${c.count}${c.problem ? " ⚠" : ""}`)).join(" | ")} |`);
+      lines.push("", "Hits per tag and event after each choice; ⚠: sent with cookies where the choice says no.", "", ...consentMatrixMarkdown(m, sc));
+      return text(lines.join("\n"));
+    },
   );
 
   server.registerTool(
@@ -338,8 +640,10 @@ export function buildServer(opts) {
       const counts = summarize(grouped);
       const outDir = path.join(opts.reportsDir, `${new Date().toISOString().replace(/[:.]/g, "-")}-${audit.journey}`);
       const { reportPath } = await writeReports({ outDir, config: { site: audit.site }, plan, runs: [run], findings, explained: null, lang, against: againstPlan, branding: branding !== false });
+      written.set(path.basename(outDir), outDir);
       const m = messages(lang);
       const lines = [
+        ...(run.live ? [LIVE_NOTE] : []),
         m.ui.counts(counts),
         ...(againstPlan ? [m.ui.checkedAgainst(againstPlan.label)] : []),
         "",
@@ -347,15 +651,23 @@ export function buildServer(opts) {
         "",
         `${run.hits.length} tracking hits, ${run.dataLayerLog.length} dataLayer pushes and ${run.network.length} analytics or ad network calls captured over ${run.steps.length} steps.`,
         skippedLine(run),
+        ...((platform) => (platform ? [`Consent platform: ${platform.vendor}. ${platform.facts.join(" ")}`] : []))(cmpFacts(messages("en"), [run])),
+        ...containerLines([run]),
         opts.allowFiles
           ? `Full report with the event timeline: ${reportPath}`
           : opts.reportsUrl
             ? `Full report with the event timeline: ${opts.reportsUrl}/${path.basename(outDir)}/report.html`
             : "",
         "",
+        `To read the report here: get_report with report "${path.basename(outDir)}" (markdown, summary, timeline or containers).`,
         "Explain each problem to the user with its likely cause and fix.",
       ];
-      return text(lines.filter((l, i, a) => l !== "" || a[i - 1] !== "").join("\n"));
+      return {
+        content: [
+          { type: "text", text: lines.filter((l, i, a) => l !== "" || a[i - 1] !== "").join("\n") },
+          { type: "text", text: `Timeline (JSON, one entry per step):\n${JSON.stringify(timelineOf(run))}` },
+        ],
+      };
     },
   );
 
@@ -484,6 +796,7 @@ export function buildServer(opts) {
             "No AI provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY) is set on the computer running this server, so scripted false can't browse with a model. Call run_audit again with scripted true (or leave it out) to replay the journeys' fixed steps, or browse the site yourself with start_audit, browser_action and finish_audit. Neither needs a key.",
           );
         }
+        written.set(path.basename(result.outDir), result.outDir);
         const m = messages(result.lang);
         const grouped = groupFindings(result.findings).filter((f) => f.severity !== "ok");
         return text(
@@ -492,7 +805,9 @@ export function buildServer(opts) {
             ...(result.baseline ? [`${result.baseline.accepted} accepted from the baseline${result.baseline.partial ? `, ${result.baseline.partial} accepted in some places only (still counted)` : ""}, ${result.baseline.stale.length} stale baseline entries`] : []),
             ...result.runs.map((r) => `${r.journeyId} (${r.viewport}): ${r.completed ? "completed" : "not completed"}, ${r.note}`),
             ...grouped.map((f) => `- ${m.severity[f.severity]}${f.accepted ? ` (${m.ui.accepted})` : ""}: ${f.detail}`),
+            ...containerLines(result.runs),
             `Report: ${result.reportPath}`,
+            `To read the report here: get_report with report "${path.basename(result.outDir)}" (markdown, summary, timeline or containers).`,
           ].join("\n"),
         );
       },
@@ -503,7 +818,7 @@ export function buildServer(opts) {
 }
 
 /** Starts the MCP server on stdio, or on HTTP with --http. */
-export async function startMcp({ http = false, port = 8787, host = "127.0.0.1", token, reportsDir, publicUrl, allowPrivateNetwork = false } = {}) {
+export async function startMcp({ http = false, port = 8787, host = "127.0.0.1", token, reportsDir, publicUrl, allowPrivateNetwork = false, allowLive = false } = {}) {
   const dir = path.resolve(reportsDir ?? path.join(homedir(), "ai-tag-debugger-reports"));
   const shutdown = async () => {
     await Promise.all([...audits.keys()].map(closeAudit));
@@ -513,7 +828,8 @@ export async function startMcp({ http = false, port = 8787, host = "127.0.0.1",
   process.on("SIGTERM", shutdown);
 
   if (!http) {
-    const server = buildServer({ allowFiles: true, reportsDir: dir });
+    // On your own computer live runs are yours to start; a server others reach needs --allow-live.
+    const server = buildServer({ allowFiles: true, reportsDir: dir, allowLive: true });
     await server.connect(new StdioServerTransport());
     // stdout carries the protocol, so status goes to stderr.
     console.error(`ai-tag-debugger MCP server ready on stdio. Reports go to ${dir}`);
@@ -530,6 +846,9 @@ export async function startMcp({ http = false, port = 8787, host = "127.0.0.1",
   if (allowPrivateNetwork) {
     console.error("Warning: --allow-private-network lets audits open localhost and private network addresses. Use it only for a local tunnel you control.");
   }
+  if (allowLive) {
+    console.error("Warning: --allow-live lets start_audit send tracking requests to the real analytics and ad accounts of the sites it audits.");
+  }
   const secret = token ?? randomBytes(18).toString("base64url");
   const endpoint = `/mcp/${secret}`;
   const digest = (s) => createHash("sha256").update(s).digest();
@@ -597,7 +916,7 @@ export async function startMcp({ http = false, port = 8787, host = "127.0.0.1",
       return;
     }
     // Stateless: a new server and transport per request. Open audits live in the module, keyed by audit_id.
-    const server = buildServer({ allowFiles: false, blockPrivate: !allowPrivateNetwork, reportsDir: dir, reportsUrl });
+    const server = buildServer({ allowFiles: false, blockPrivate: !allowPrivateNetwork, reportsDir: dir, reportsUrl, allowLive });
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
     res.on("close", () => {
       transport.close();

package/src/metrics.js

@@ -4,7 +4,7 @@
 // { plan, runs, findings, consentScenarios } (no I/O, no AI, no HTML) and returns plain data; the
 // report decides how to show it. The rules are documented in docs/design/metrics.md.
 
-import { canonicalEvent, groupFindings, hasParam, hitMatchesEvent, isConsentCommand, PLAN_BUCKETS, planCheck, summarize } from "./checks.js";
+import { canonicalEvent, groupFindings, hasParam, hitMatchesEvent, isConsentCommand, PLAN_BUCKETS, planCheck, summarize, tagConsentStates } from "./checks.js";
 import { AD_PLATFORMS, CONSENT_STATES, consentTable } from "./consent.js";
 import { presetFor } from "./journeys.js";
 import { OWNERS, ownerOf } from "./verify.js";
@@ -32,7 +32,7 @@ const GOOGLE_PLATFORMS = new Set(["ga4", "google_ads"]);
 const V2_SIGNALS = ["ad_user_data", "ad_personalization"];
 // Consent findings that say the visitor's "no" was not honoured, against the ones that say the setup is risky.
 const CONSENT_FAIL_CHECKS = new Set(["after_reject", "cookies_after_reject", "reject_ignored", "reject_button_failed"]);
-const CONSENT_ATTENTION_CHECKS = new Set(["before_consent", "cookies_before_consent", "consent_default_missing", "consent_default_late", "consent_v2_missing", "consent_v2_update"]);
+const CONSENT_ATTENTION_CHECKS = new Set(["before_consent", "cookies_before_consent", "consent_default_missing", "consent_default_late", "consent_default_not_applied", "consent_v2_missing", "consent_v2_update"]);
 const CONSENT_CHECK = /^(consent_|cookies_|reject_|before_consent|after_reject)/;
 
 // Ecommerce parameters sites send under another name (UA-style products/revenue, order ids), as checks.js reads them.
@@ -243,15 +243,21 @@ export function platformParity({ runs = [] } = {}) {
 function consentDefaultIn(run) {
   const log = run.dataLayerLog ?? [];
   const entry = log.find((e) => isConsentCommand(e, "default")) ?? null;
+  // Without a dataLayer command, the Google tag's own state can still show a default (a consent platform's GTM template).
+  const tagStates = entry ? [] : tagConsentStates({ steps: run.steps ?? [] });
+  const tagDefault = tagStates.find((st) => st.usedDefault) ?? null;
+  const set = Boolean(entry || tagDefault);
   const firstGoogleHit = (run.hits ?? []).filter((h) => GOOGLE_PLATFORMS.has(h.platform)).sort(byTime)[0] ?? null;
   const step = entry ? stepOf(run, entry.step) : null;
-  const declared = uniq(log.filter((e) => isConsentCommand(e, "default")).flatMap((e) => Object.keys(e.value[2] ?? {})));
+  const declared = entry
+    ? uniq(log.filter((e) => isConsentCommand(e, "default")).flatMap((e) => Object.keys(e.value[2] ?? {})))
+    : tagDefault ? Object.entries(tagDefault.entries).filter(([, e]) => e.default).map(([k]) => k) : [];
   const missing = V2_SIGNALS.filter((k) => !declared.includes(k));
   return {
-    journey: run.journeyId, viewport: run.viewport, present: Boolean(entry),
-    step: entry?.step ?? null, stepLabel: step?.label ?? null, ms: entry && step && entry.t != null && step.t != null ? entry.t - step.t : null,
-    beforeFirstGoogleHit: entry && firstGoogleHit ? !sentBefore(firstGoogleHit, entry) : null,
-    v2Signals: { present: Boolean(entry) && !missing.length, missing: entry ? missing : V2_SIGNALS },
+    journey: run.journeyId, viewport: run.viewport, present: set, source: entry ? "dataLayer" : tagDefault ? "tag" : null,
+    step: entry?.step ?? tagDefault?.step ?? null, stepLabel: step?.label ?? null, ms: entry && step && entry.t != null && step.t != null ? entry.t - step.t : null,
+    beforeFirstGoogleHit: entry && firstGoogleHit ? !sentBefore(firstGoogleHit, entry) : tagDefault ? !tagStates.some((st) => st.wasSetLate) : null,
+    v2Signals: { present: set && !missing.length, missing: set ? missing : V2_SIGNALS },
   };
 }