@canonry/canonry 4.133.2 → 4.134.0

package/dist/{chunk-ZPQX5ZQ2.js → chunk-PC7AYXND.js}

@@ -47,8 +47,8 @@ function authInvalid() {
 function forbidden(message = "Forbidden", details) {
   return new AppError("FORBIDDEN", message, 403, details);
 }
-function quotaExceeded(metric) {
-  return new AppError("QUOTA_EXCEEDED", `Quota exceeded for ${metric}`, 429);
+function quotaExceeded(metric, details) {
+  return new AppError("QUOTA_EXCEEDED", `Quota exceeded for ${metric}`, 429, details);
 }
 function providerError(message, details) {
   return new AppError("PROVIDER_ERROR", message, 502, details);
@@ -960,6 +960,111 @@ function formatIsoDate(iso) {
     return iso;
   }
 }
+function zonedClockFormat(timeZone) {
+  return new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23"
+  });
+}
+function readZonedParts(format, date) {
+  const values = {};
+  for (const part of format.formatToParts(date)) values[part.type] = part.value;
+  return values;
+}
+function readZonedClock(format, date) {
+  const parts = readZonedParts(format, date);
+  const value = (raw) => {
+    if (raw === void 0) return null;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : null;
+  };
+  const year = value(parts.year);
+  const month = value(parts.month);
+  const day = value(parts.day);
+  const hour = value(parts.hour);
+  const minute = value(parts.minute);
+  const second = value(parts.second);
+  if (year === null || month === null || day === null) return null;
+  if (hour === null || minute === null || second === null) return null;
+  return { year, month, day, hour, minute, second };
+}
+function formatIsoDateInTimeZone(iso, timeZone) {
+  if (!iso) return formatIsoDate(iso);
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  try {
+    const parts = readZonedParts(zonedClockFormat(timeZone), d);
+    const yyyy = parts.year;
+    const mm = parts.month;
+    const dd = parts.day;
+    if (!yyyy || !mm || !dd) return formatIsoDate(iso);
+    return `${yyyy}-${mm}-${dd}`;
+  } catch {
+    return formatIsoDate(iso);
+  }
+}
+function shiftIsoCalendarDate(isoDate, days) {
+  if (!Number.isFinite(days)) return isoDate;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(isoDate);
+  if (!match?.[1] || !match[2] || !match[3]) return isoDate;
+  const shifted = new Date(Date.UTC(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3]) + Math.trunc(days)
+  ));
+  if (Number.isNaN(shifted.getTime())) return isoDate;
+  const yyyy = shifted.getUTCFullYear();
+  const mm = String(shifted.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(shifted.getUTCDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+}
+function isoDateDaysBeforeInTimeZone(iso, days, timeZone) {
+  return shiftIsoCalendarDate(formatIsoDateInTimeZone(iso, timeZone), -days);
+}
+var HOURS_PER_DAY = 24;
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+function localHourExists(format, year, month, day, hour) {
+  const asIfUtcMs = Date.UTC(year, month - 1, day, hour);
+  for (const probeMs of [asIfUtcMs - ONE_DAY_MS, asIfUtcMs + ONE_DAY_MS]) {
+    const probeClock = readZonedClock(format, new Date(probeMs));
+    if (!probeClock) continue;
+    const offsetMs = Date.UTC(
+      probeClock.year,
+      probeClock.month - 1,
+      probeClock.day,
+      probeClock.hour,
+      probeClock.minute,
+      probeClock.second
+    ) - probeMs;
+    const candidate = readZonedClock(format, new Date(asIfUtcMs - offsetMs));
+    if (!candidate) continue;
+    if (candidate.year === year && candidate.month === month && candidate.day === day && candidate.hour === hour && candidate.minute === 0 && candidate.second === 0) return true;
+  }
+  return false;
+}
+function startOfDayHourInTimeZone(isoDate, timeZone) {
+  const hourBoundary = (hour) => `${isoDate}T${String(hour).padStart(2, "0")}`;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(isoDate);
+  if (!match?.[1] || !match[2] || !match[3]) return hourBoundary(0);
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  try {
+    const format = zonedClockFormat(timeZone);
+    for (let hour = 0; hour < HOURS_PER_DAY; hour += 1) {
+      if (localHourExists(format, year, month, day, hour)) return hourBoundary(hour);
+    }
+    return hourBoundary(0);
+  } catch {
+    return hourBoundary(0);
+  }
+}
 function formatDateRange(start, end) {
   if (!start && !end) return "";
   if (start && end) return `${formatDate(start)} \u2192 ${formatDate(end)}`;
@@ -6518,6 +6623,8 @@ var researchRunQuerySchema = z37.object({
   groundingSources: z37.array(groundingSourceSchema),
   citedDomains: z37.array(z37.string()),
   searchQueries: z37.array(z37.string()),
+  namedCompetitors: z37.array(z37.string()).default([]),
+  citedCompetitorDomains: z37.array(z37.string()).default([]),
   answerMentioned: z37.boolean().nullable(),
   citationState: citationStateSchema.nullable(),
   error: z37.string().nullable(),
@@ -6742,6 +6849,91 @@ var adsSummaryDtoSchema = z38.object({
   /** Campaign-level rollup totals over the window (levels are not summed across). */
   totals: adsTotalsDtoSchema
 });
+var adsDeliverySnapshotStatusSchema = z38.enum(["unavailable", "partial", "complete"]);
+var AdsDeliverySnapshotStatuses = adsDeliverySnapshotStatusSchema.enum;
+var adsDeliverySnapshotIssueSchema = z38.enum([
+  "no_ads_connection",
+  "connection_not_synced",
+  "no_ads_sync",
+  "entity_rows_missing_sync_run_id",
+  "entity_rows_span_multiple_sync_runs",
+  "source_sync_missing",
+  "source_sync_not_ads_sync",
+  "source_sync_not_completed"
+]);
+var AdsDeliverySnapshotIssues = adsDeliverySnapshotIssueSchema.enum;
+var adsHistoricalCampaignRollupStatusSchema = z38.enum(["unavailable", "reported"]);
+var AdsHistoricalCampaignRollupStatuses = adsHistoricalCampaignRollupStatusSchema.enum;
+var AdsDeliveryConfigurationBases = {
+  storedSnapshot: "stored_ads_snapshot"
+};
+var adsActivityAssessmentStateSchema = z38.enum([
+  "unavailable",
+  "partial_snapshot",
+  "metrics_unavailable",
+  "observed_activity",
+  "no_observed_activity"
+]);
+var AdsActivityAssessmentStates = adsActivityAssessmentStateSchema.enum;
+var adsDeliveryDiagnosticsAdSchema = z38.object({
+  id: z38.string(),
+  name: z38.string(),
+  status: z38.string(),
+  reviewStatus: z38.string().nullable()
+});
+var adsDeliveryDiagnosticsAdGroupSchema = z38.object({
+  id: z38.string(),
+  name: z38.string(),
+  status: z38.string(),
+  billingEventType: z38.union([adsAdGroupBillingEventTypeSchema, z38.null()]),
+  maxBidMicros: z38.number().int().nullable(),
+  contextHints: z38.array(z38.string()),
+  ads: z38.array(adsDeliveryDiagnosticsAdSchema)
+});
+var adsDeliveryDiagnosticsCampaignSchema = z38.object({
+  id: z38.string(),
+  name: z38.string(),
+  status: z38.string(),
+  biddingType: z38.union([adsCampaignBiddingTypeSchema, z38.null()]),
+  dailySpendLimitMicros: z38.number().int().nullable(),
+  lifetimeSpendLimitMicros: z38.number().int().nullable(),
+  conversionEventSettingIds: z38.array(z38.string()),
+  adGroups: z38.array(adsDeliveryDiagnosticsAdGroupSchema)
+});
+var adsDeliveryDiagnosticsDtoSchema = z38.object({
+  snapshot: z38.object({
+    status: adsDeliverySnapshotStatusSchema,
+    // A union keeps the OpenAPI form explicit enough for the generated SDK to
+    // retain the complete-snapshot `null` value (rather than narrowing it to
+    // the issue enum alone).
+    issue: z38.union([adsDeliverySnapshotIssueSchema, z38.null()]),
+    lastSyncedAt: z38.string().nullable(),
+    campaignCount: z38.number().int().nonnegative(),
+    adGroupCount: z38.number().int().nonnegative(),
+    adCount: z38.number().int().nonnegative(),
+    sourceSync: z38.object({
+      runId: z38.string(),
+      status: runStatusSchema
+    }).nullable()
+  }),
+  historicalCampaignRollups: z38.object({
+    status: adsHistoricalCampaignRollupStatusSchema,
+    window: z38.object({ from: z38.string().nullable(), to: z38.string().nullable() }),
+    totals: adsTotalsDtoSchema.nullable()
+  }),
+  storedConfiguration: z38.object({
+    basis: z38.literal(AdsDeliveryConfigurationBases.storedSnapshot),
+    connection: z38.object({
+      status: z38.string().nullable(),
+      reviewStatus: z38.string().nullable(),
+      integrityReviewStatus: z38.string().nullable(),
+      integrityDecision: z38.string().nullable(),
+      conversionTrackingConfigured: z38.boolean()
+    }).nullable(),
+    campaigns: z38.array(adsDeliveryDiagnosticsCampaignSchema)
+  }),
+  assessment: z38.object({ state: adsActivityAssessmentStateSchema })
+});
 var adsOperationKeySchema = z38.string().min(8).max(128).regex(/^[\w.:-]+$/, "operationKey may contain letters, numbers, dot, underscore, colon, and hyphen");
 var adsEntityIdSchema = z38.string().min(1).max(200);
 var adsNameSchema = z38.string().min(3).max(1e3).refine((value) => value.trim().length > 0);
@@ -7248,6 +7440,122 @@ var adsOperationReconcileResponseSchema = z38.object({
   operation: adsOperationDtoSchema,
   resolved: z38.boolean()
 });
+var adsLiveDeliveryQuerySchema = z38.object({
+  campaignId: z38.string().min(1).max(200).optional(),
+  lookbackDays: z38.coerce.number().int().min(1).max(30).default(7)
+});
+var adsLiveEntityTypeSchema = z38.enum(["campaign", "ad_group", "ad"]);
+var AdsLiveEntityTypes = adsLiveEntityTypeSchema.enum;
+var adsLivePresenceSchema = z38.enum(["both", "live-only", "stored-only"]);
+var AdsLivePresences = adsLivePresenceSchema.enum;
+var adsLiveDeliveryBasisSchema = z38.literal("live-provider-read");
+var AdsLiveDeliveryBases = { liveProviderRead: "live-provider-read" };
+var adsLiveMetricRowSchema = z38.object({
+  date: z38.string().nullable(),
+  startTime: z38.number().nullable(),
+  endTime: z38.number().nullable(),
+  impressions: z38.number().nullable(),
+  clicks: z38.number().nullable(),
+  spend: z38.number().nullable(),
+  conversions: z38.number().nullable(),
+  ctr: z38.number().nullable(),
+  cpc: z38.number().nullable(),
+  cpm: z38.number().nullable()
+});
+var adsLiveMetricValuesSchema = z38.object({
+  impressions: z38.number().int(),
+  clicks: z38.number().int(),
+  spendMicros: z38.number().int(),
+  conversions: z38.number().int()
+});
+var adsLiveMetricDeltaSchema = z38.object({
+  date: z38.string(),
+  live: adsLiveMetricValuesSchema.nullable(),
+  stored: adsLiveMetricValuesSchema.nullable(),
+  drifted: z38.boolean()
+});
+var adsLiveFieldDeltaSchema = z38.object({
+  field: z38.string(),
+  live: z38.string().nullable(),
+  stored: z38.string().nullable()
+});
+var adsLiveEntityStateSchema = z38.object({
+  name: z38.string().nullable(),
+  status: z38.string(),
+  reviewStatus: z38.string().nullable(),
+  mode: z38.string().nullable(),
+  updatedAt: z38.number().nullable()
+});
+var adsStoredEntityStateSchema = z38.object({
+  name: z38.string(),
+  status: z38.string(),
+  reviewStatus: z38.string().nullable(),
+  upstreamUpdatedAt: z38.number().nullable(),
+  syncedAt: z38.string()
+});
+var adsLiveEntityComparisonSchema = z38.object({
+  entityType: adsLiveEntityTypeSchema,
+  id: z38.string(),
+  parentId: z38.string().nullable(),
+  presence: adsLivePresenceSchema,
+  live: adsLiveEntityStateSchema.nullable(),
+  stored: adsStoredEntityStateSchema.nullable(),
+  fieldDeltas: z38.array(adsLiveFieldDeltaSchema),
+  /** Provider rows, unaggregated. Null for ads (no per-ad insights surface). */
+  liveMetrics: z38.array(adsLiveMetricRowSchema).nullable(),
+  metricDeltas: z38.array(adsLiveMetricDeltaSchema).nullable(),
+  drifted: z38.boolean()
+});
+var adsLiveReadFailureSchema = z38.object({
+  surface: z38.string(),
+  entityId: z38.string().nullable(),
+  upstreamStatus: z38.number().int().nullable()
+});
+var adsLiveDeliveryDtoSchema = z38.object({
+  basis: adsLiveDeliveryBasisSchema,
+  /** Instant the live read was issued; the metrics window is measured back from it. */
+  fetchedAt: z38.string(),
+  adAccountId: z38.string(),
+  storedSnapshotSyncedAt: z38.string().nullable(),
+  metricsWindow: z38.object({ lookbackDays: z38.number().int().positive() }),
+  /**
+   * Two different units live here, and confusing them understates the cost of
+   * this endpoint by two orders of magnitude.
+   *
+   * A READER CALL is one logical list or insight read. Every list/insight
+   * reader call is an auto-paginating walk, so one reader call can issue up to
+   * `maxPagesPerReaderCall` upstream HTTP requests before the client gives up.
+   * `maxUpstreamHttpRequests` is the honest worst-case ceiling in HTTP
+   * requests (`maxReaderCalls * maxPagesPerReaderCall`, about 4000 at the
+   * shipped defaults, not 40).
+   *
+   * `readerCalls` is an observed count of reader calls. There is deliberately
+   * no observed HTTP-request count: the pagination happens inside the provider
+   * client, below the injected reader seam, so the route cannot see it.
+   */
+  bounds: z38.object({
+    maxCampaigns: z38.number().int().positive(),
+    maxAdGroupsPerCampaign: z38.number().int().positive(),
+    maxAdsPerAdGroup: z38.number().int().positive(),
+    /** Budget in logical reader calls, NOT in upstream HTTP requests. */
+    maxReaderCalls: z38.number().int().positive(),
+    /** Reader calls this read actually issued. Observed, not a bound. */
+    readerCalls: z38.number().int().nonnegative(),
+    /** Pages one paginated reader call may fetch before the client gives up. */
+    maxPagesPerReaderCall: z38.number().int().positive(),
+    /** Worst-case upstream HTTP requests. A documented bound, not an observation. */
+    maxUpstreamHttpRequests: z38.number().int().positive(),
+    truncated: z38.boolean()
+  }),
+  entities: z38.array(adsLiveEntityComparisonSchema),
+  drift: z38.object({
+    entitiesCompared: z38.number().int().nonnegative(),
+    driftedEntities: z38.number().int().nonnegative(),
+    statusDrifted: z38.number().int().nonnegative(),
+    metricsDrifted: z38.number().int().nonnegative()
+  }),
+  errors: z38.array(adsLiveReadFailureSchema)
+});
 function adsCtr(clicks, impressions) {
   return impressions > 0 ? clicks / impressions : null;
 }
@@ -7498,6 +7806,9 @@ export {
   formatNumber,
   formatDate,
   formatIsoDate,
+  formatIsoDateInTimeZone,
+  isoDateDaysBeforeInTimeZone,
+  startOfDayHourInTimeZone,
   formatDateRange,
   parseInclusiveEndMs,
   deltaPercent,
@@ -7776,8 +8087,15 @@ export {
   AdsAdGroupBillingEventTypes,
   adsCampaignListResponseSchema,
   adsInsightLevelSchema,
+  AdsInsightLevels,
   adsInsightsResponseSchema,
   adsSummaryDtoSchema,
+  AdsDeliverySnapshotStatuses,
+  AdsDeliverySnapshotIssues,
+  AdsHistoricalCampaignRollupStatuses,
+  AdsDeliveryConfigurationBases,
+  AdsActivityAssessmentStates,
+  adsDeliveryDiagnosticsDtoSchema,
   AdsOperationKinds,
   AdsOperationStates,
   AdsReconcileStrategies,
@@ -7810,6 +8128,11 @@ export {
   adsUnresolvedOperationListResponseSchema,
   adsOperationReconcileRequestSchema,
   adsOperationReconcileResponseSchema,
+  adsLiveDeliveryQuerySchema,
+  AdsLiveEntityTypes,
+  AdsLivePresences,
+  AdsLiveDeliveryBases,
+  adsLiveDeliveryDtoSchema,
   adsCtr,
   adsCpcMicros,
   dollarsToMicros,

package/dist/{chunk-V2YR3YK6.js → chunk-TKXWTDV6.js}

@@ -10,7 +10,7 @@ import {
   loadConfig,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-JTJQZ4UC.js";
+} from "./chunk-ZUQPHGEN.js";
 import {
   CC_CACHE_DIR,
   DUCKDB_SPEC,
@@ -40,6 +40,7 @@ import {
   classifyAiUserFetch,
   classifyCrawler,
   competitors,
+  computeCitedCompetitorDomains,
   computeCompetitorOverlap,
   countAttributes,
   countPopulatedGroups,
@@ -118,7 +119,7 @@ import {
   siteAuditPages,
   siteAuditSnapshots,
   usageCounters
-} from "./chunk-IEZTETUZ.js";
+} from "./chunk-LIXWDIDR.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -188,10 +189,11 @@ import {
   serializeRunError,
   skillsClientSchema,
   splitList,
+  startOfDayHourInTimeZone,
   validationError,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-ZPQX5ZQ2.js";
+} from "./chunk-PC7AYXND.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -4877,14 +4879,22 @@ function accountHour(date, timezone) {
   };
   return `${value("year")}-${value("month")}-${value("day")}T${value("hour")}`;
 }
-function trailingAdsInsightHourRange(now, timezone) {
+function trailingAdsInsightHourRange(now, timezone, lookbackMs = INSIGHTS_LOOKBACK_MS) {
   return {
     type: "hour_range",
-    since: accountHour(new Date(now.getTime() - INSIGHTS_LOOKBACK_MS), timezone),
+    since: accountHour(new Date(now.getTime() - lookbackMs), timezone),
     until: accountHour(now, timezone),
     timezone
   };
 }
+function liveAdsInsightHourRange(request) {
+  return {
+    type: "hour_range",
+    since: startOfDayHourInTimeZone(request.startDate, request.timezone),
+    until: accountHour(new Date(request.fetchedAtMs), request.timezone),
+    timezone: request.timezone
+  };
+}
 function toInsightUpserts(level, entityId, rows) {
   const upserts = [];
   for (const row of rows) {
@@ -7000,7 +7010,7 @@ function readStoredGroundingSources(rawResponse) {
   return result;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-WZNE23TV.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-4XOFUN5E.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -9113,6 +9123,8 @@ var AERO_ADS_OPERATOR_MCP_TOOL_NAMES = /* @__PURE__ */ new Set([
   CanonryMcpToolNames.canonry_ads_campaigns,
   CanonryMcpToolNames.canonry_ads_insights,
   CanonryMcpToolNames.canonry_ads_summary,
+  CanonryMcpToolNames.canonry_ads_delivery_diagnostics,
+  CanonryMcpToolNames.canonry_ads_live_delivery,
   CanonryMcpToolNames.canonry_ads_operations_unresolved,
   CanonryMcpToolNames.canonry_ads_operation_get,
   CanonryMcpToolNames.canonry_ads_operation_reconcile,
@@ -9234,7 +9246,7 @@ function buildAdsOperatorContextTool(ctx) {
   return {
     name: AERO_ADS_OPERATOR_CONTEXT_TOOL_NAME,
     label: "Get ads operator context",
-    description: "One-call Aero context pack for ads operations. Reads the project overview, ads connection, paid summary, bounded campaign snapshots, recent paid rollups, ads doctor checks, and recent Aero memory. Use before diagnosing ChatGPT ads performance or planning the next operator action.",
+    description: "One-call Aero context pack for ads operations. Reads the project overview, stored ads delivery diagnostics, ads connection, paid summary, bounded campaign snapshots, recent paid rollups, ads doctor checks, and recent Aero memory. Use before diagnosing ChatGPT ads performance or planning the next operator action.",
     parameters: Type3.Object({
       windowDays: Type3.Optional(Type3.Integer({
         minimum: 1,
@@ -9262,6 +9274,7 @@ function buildAdsOperatorContextTool(ctx) {
       const [
         overview,
         adsStatus,
+        deliveryDiagnostics,
         adsSummary,
         campaigns,
         campaignInsights,
@@ -9271,6 +9284,7 @@ function buildAdsOperatorContextTool(ctx) {
       ] = await Promise.all([
         readSection(() => ctx.client.getProjectOverview(ctx.projectName)),
         readSection(() => ctx.client.getAdsStatus(ctx.projectName)),
+        readSection(() => ctx.client.getAdsDeliveryDiagnostics(ctx.projectName)),
         readSection(() => ctx.client.getAdsSummary(ctx.projectName)),
         readSection(async () => compactCampaigns(await ctx.client.getAdsCampaigns(ctx.projectName), campaignLimit)),
         readSection(
@@ -9298,6 +9312,7 @@ function buildAdsOperatorContextTool(ctx) {
         overview: overview.status === "ok" && overview.data ? { status: "ok", data: compactOverview(overview.data) } : overview,
         ads: {
           status: adsStatus,
+          deliveryDiagnostics,
           summary: adsSummary,
           campaigns,
           insights: {
@@ -11588,6 +11603,14 @@ async function executeResearchRun(db, registry, runId, projectId) {
           return provider.adapter.executeTrackedQuery({ query: row.queryText, canonicalDomains: domains, competitorDomains, ...run.location ? { location: run.location } : {} }, config);
         });
         const normalized = provider.adapter.normalizeResult(raw);
+        const namedCompetitors = extractRecommendedCompetitors(
+          normalized.answerText,
+          domains,
+          normalized.citedDomains,
+          competitorDomains,
+          brands
+        );
+        const citedCompetitorDomains = computeCitedCompetitorDomains(normalized.citedDomains, competitorDomains);
         const completed = db.update(researchRunQueries).set({
           status: ResearchQueryStatuses.completed,
           servedModel: raw.servedModel ?? null,
@@ -11595,6 +11618,8 @@ async function executeResearchRun(db, registry, runId, projectId) {
           groundingSources: normalized.groundingSources,
           citedDomains: normalized.citedDomains,
           searchQueries: normalized.searchQueries,
+          namedCompetitors,
+          citedCompetitorDomains,
           answerMentioned: determineAnswerMentioned(normalized.answerText, brands, domains),
           citationState: determineCitationState(normalized, domains),
           rawResponse: raw.rawResponse,
@@ -12200,6 +12225,42 @@ async function createServer(opts) {
     activateAd: async (apiKey, id) => adsAdEntityResult(await activateAd(apiKey, id)),
     pauseAd: async (apiKey, id) => adsAdEntityResult(await pauseAd(apiKey, id))
   };
+  const adsLiveEntity = (entity, extra) => ({
+    id: entity.id,
+    name: entity.name,
+    status: entity.status,
+    reviewStatus: extra?.reviewStatus ?? null,
+    mode: extra?.mode ?? null,
+    updatedAt: entity.updated_at
+  });
+  const adsLiveMetricRow = (row) => ({
+    date: row.readable_time ?? null,
+    startTime: row.start_time ?? null,
+    endTime: row.end_time ?? null,
+    impressions: row.impressions ?? null,
+    clicks: row.clicks ?? null,
+    // Provider units: the insights API returns decimal currency for spend.
+    spend: row.spend ?? null,
+    conversions: row.conversions ?? null,
+    ctr: row.ctr ?? null,
+    cpc: row.cpc ?? null,
+    cpm: row.cpm ?? null
+  });
+  const adsLiveDeliveryReader = {
+    listCampaigns: async (apiKey) => (await listCampaigns(apiKey)).map((campaign) => adsLiveEntity(campaign, { mode: campaign.mode })),
+    listAdGroups: async (apiKey, campaignId) => (await listAdGroups(apiKey, campaignId)).map((adGroup) => adsLiveEntity(adGroup)),
+    listAds: async (apiKey, adGroupId) => (await listAds(apiKey, adGroupId)).map(
+      (ad) => adsLiveEntity(ad, { reviewStatus: ad.review_status ?? ad.review?.status ?? null })
+    ),
+    campaignInsights: async (apiKey, campaignId, request) => (await getCampaignInsights(apiKey, campaignId, {
+      fields: CAMPAIGN_INSIGHT_FIELDS,
+      timeRanges: [liveAdsInsightHourRange(request)]
+    })).map(adsLiveMetricRow),
+    adGroupInsights: async (apiKey, adGroupId, request) => (await getAdGroupInsights(apiKey, adGroupId, {
+      fields: AD_GROUP_INSIGHT_FIELDS,
+      timeRanges: [liveAdsInsightHourRange(request)]
+    })).map(adsLiveMetricRow)
+  };
   const scheduler = new Scheduler(opts.db, {
     onRunCreated: (runId, projectId, providers2, location) => {
       jobRunner.executeRun(runId, projectId, providers2, location).catch((err) => {
@@ -12799,6 +12860,11 @@ async function createServer(opts) {
     adsCredentialStore,
     verifyAdsAccount,
     adsReader,
+    adsLiveDeliveryReader,
+    // Reporting only: lets the route state the true upstream HTTP ceiling
+    // (reader-call budget x pages per reader call) instead of implying that a
+    // reader call is one request.
+    adsLiveDeliveryMaxPagesPerReaderCall: OPENAI_ADS_MAX_PAGES,
     adsOperator,
     onAdsSyncRequested: (runId, projectId) => {
       runAdsSync(runId, projectId);

package/dist/{chunk-JTJQZ4UC.js → chunk-ZUQPHGEN.js}

@@ -42,7 +42,7 @@ import {
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
   trafficSeriesGranularitySchema
-} from "./chunk-ZPQX5ZQ2.js";
+} from "./chunk-PC7AYXND.js";
 
 // src/config.ts
 import fs from "fs";
@@ -2727,6 +2727,30 @@ var getApiV1ProjectsByNameAdsSummary = (options) => {
     ...options
   });
 };
+var getApiV1ProjectsByNameAdsDeliveryDiagnostics = (options) => {
+  return (options.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/projects/{name}/ads/delivery-diagnostics",
+    ...options
+  });
+};
+var getApiV1ProjectsByNameAdsLiveDelivery = (options) => {
+  return (options.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/projects/{name}/ads/live-delivery",
+    ...options
+  });
+};
 var postApiV1ProjectsByNameBingConnect = (options) => {
   return (options.client ?? client).post({
     security: [
@@ -4854,6 +4878,23 @@ var ApiClient = class {
       () => getApiV1ProjectsByNameAdsSummary({ client: this.heyClient, path: { name: project } })
     );
   }
+  async getAdsDeliveryDiagnostics(project) {
+    return this.invoke(
+      () => getApiV1ProjectsByNameAdsDeliveryDiagnostics({ client: this.heyClient, path: { name: project } })
+    );
+  }
+  async getAdsLiveDelivery(project, opts) {
+    return this.invoke(
+      () => getApiV1ProjectsByNameAdsLiveDelivery({
+        client: this.heyClient,
+        path: { name: project },
+        query: {
+          ...opts?.campaignId === void 0 ? {} : { campaignId: opts.campaignId },
+          ...opts?.lookbackDays === void 0 ? {} : { lookbackDays: opts.lookbackDays }
+        }
+      })
+    );
+  }
   async getAdsOperation(project, operationKey) {
     return this.invoke(
       () => getApiV1ProjectsByNameAdsOperationsByOperationKey({
@@ -6152,6 +6193,11 @@ var adsInsightsInputSchema = z2.object({
 var adsGeoSearchInputSchema = adsGeoSearchQuerySchema.extend({
   project: projectNameSchema
 });
+var adsLiveDeliveryInputSchema = z2.object({
+  project: projectNameSchema,
+  campaignId: z2.string().min(1).max(200).optional(),
+  lookbackDays: z2.number().int().min(1).max(30).optional()
+});
 var adsOperationInputSchema = z2.object({
   project: projectNameSchema,
   operationKey: z2.string().min(8).max(128)
@@ -7693,7 +7739,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_research_run_get",
     title: "Get research query run",
-    description: "Get the saved per-query answers, sources, cited domains, and independent mention/citation results for one research run. It is read-only and does not promote or track any query.",
+    description: "Get saved per-query answers, source links, cited domains, answer-text named competitors, cited competitor domains, and independent mention/citation results for one research run. It is read-only and does not promote or track any query.",
     access: "read",
     tier: "discovery",
     inputSchema: researchRunIdInputSchema,
@@ -7912,6 +7958,31 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/ads/summary"],
     handler: (client2, input) => client2.getAdsSummary(input.project)
   }),
+  defineTool({
+    name: "canonry_ads_delivery_diagnostics",
+    title: "Stored ads delivery diagnostics",
+    description: "Read stored ads snapshot provenance, account/campaign/ad-group/ad configuration facts, and historical campaign activity in one call. This is not a live OpenAI eligibility or serving verdict.",
+    access: "read",
+    tier: "ads",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/ads/delivery-diagnostics"],
+    handler: (client2, input) => client2.getAdsDeliveryDiagnostics(input.project)
+  }),
+  defineTool({
+    name: "canonry_ads_live_delivery",
+    title: "Live ads read with stored-snapshot delta",
+    description: "Call the OpenAI Ads API right now and return the provider's current status and metrics per campaign / ad group / ad, unaggregated, alongside the stored snapshot values and an explicit per-entity delta. Use this when stored data is suspected of being stale or contradicted by the advertiser UI. Read-only: it mutates nothing and does not wait for a sync. The walk is bounded and one project may issue at most one live read per minute, so prefer canonry_ads_delivery_diagnostics for routine checks.",
+    access: "read",
+    tier: "ads",
+    inputSchema: adsLiveDeliveryInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/ads/live-delivery"],
+    handler: (client2, input) => client2.getAdsLiveDelivery(input.project, {
+      campaignId: input.campaignId,
+      lookbackDays: input.lookbackDays
+    })
+  }),
   defineTool({
     name: "canonry_ads_operations_unresolved",
     title: "List unresolved ads mutation receipts",