@olives/devos 2.1.0

package/.agents/skills/vercel-optimize/lib/deep-dive.mjs

@@ -0,0 +1,350 @@
+// Per-candidate deep-dive query specs. Runs after gate, before sub-agent reads source.
+//
+// CLI quirks:
+//   - Multi `-a` flag is NOT supported. One percentile per query.
+//   - External-API "calling route" dim is `origin_route` (NOT `route`).
+
+// Same window as broad pass so rolls are comparable.
+import { TIME_WINDOW } from './queries.mjs';
+
+export { TIME_WINDOW };
+
+// Per-query is scoped to one route/hostname, so cardinality stays small — higher than broad-pass caps.
+const DEPLOYMENT_LIMIT = 10;
+const ERROR_DEPLOYMENT_LIMIT = 30;
+const ERROR_CODE_LIMIT = 50;
+const WAF_RULE_LIMIT = 20;
+const MIDDLEWARE_PATH_LIMIT = 50;
+const CALLER_LIMIT = 20;
+
+// OData escapes a literal `'` inside a string by doubling it (`it's` → `it''s`).
+export function escapeODataString(s) {
+  if (typeof s !== 'string') return '';
+  return s.replace(/'/g, "''");
+}
+
+export function odataEq(dim, value) {
+  return `${dim} eq '${escapeODataString(value)}'`;
+}
+
+export function odataAnd(...conds) {
+  return conds.filter(Boolean).join(' and ');
+}
+
+export const SPEC_GENERATORS = {
+  slow_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    // cacheBreakdown/bandwidthByCache let sub-agent see miss-path cost on static routes (dynamic='error' can still show p95=900ms over millions of requests).
+    return [
+      ...latencyPercentiles('latency', 'vercel.function_invocation.function_duration_ms', f),
+      ...latencyPercentiles('ttfb', 'vercel.function_invocation.ttfb_ms', f),
+      ...latencyPercentiles('cpu', 'vercel.function_invocation.function_cpu_time_ms', f, ['p95']),
+      {
+        id: 'startTypeSplit',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['function_start_type'],
+        filter: f,
+        broadPassEquivalent: { key: 'fnStartTypeByRoute', routeFilter: route, projectDims: ['function_start_type'] },
+      },
+      // function-invocation status (5xx from function) — distinct from request-level status, can't reuse broad-pass.
+      {
+        id: 'statusDistribution',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['http_status'],
+        filter: f,
+      },
+      {
+        id: 'perDeployment',
+        metricId: 'vercel.function_invocation.function_duration_ms',
+        aggregation: 'p95',
+        groupBy: ['deployment_id'],
+        filter: f,
+        limit: DEPLOYMENT_LIMIT,
+      },
+      {
+        id: 'cacheBreakdown',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteCache', routeFilter: route, projectDims: ['cache_result'] },
+      },
+      // broad-pass bandwidthByCacheResult is account-wide, so per-route still required.
+      {
+        id: 'bandwidthByCache',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  uncached_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'cacheBreakdown',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteCache', routeFilter: route, projectDims: ['cache_result'] },
+      },
+      {
+        id: 'methodDistribution',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['request_method'],
+        filter: f,
+        broadPassEquivalent: { key: 'requestsByRouteMethod', routeFilter: route, projectDims: ['request_method'] },
+      },
+      {
+        id: 'botShare',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['bot_category'],
+        filter: f,
+      },
+      {
+        id: 'bandwidthByCache',
+        metricId: 'vercel.request.fdt_total_bytes',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  cold_start(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'startTypeSplit',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['function_start_type'],
+        filter: f,
+      },
+      {
+        id: 'coldVsWarmLatencyP95',
+        metricId: 'vercel.function_invocation.function_duration_ms',
+        aggregation: 'p95',
+        groupBy: ['function_start_type'],
+        filter: f,
+      },
+      {
+        id: 'coldByDeployment',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['deployment_id'],
+        filter: odataAnd(f, odataEq('function_start_type', 'cold')),
+        limit: DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  route_errors(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'errorStatusPattern',
+        metricId: 'vercel.request.count',
+        aggregation: 'sum',
+        groupBy: ['http_status'],
+        filter: odataAnd(f, "http_status ge '500'"),
+      },
+      {
+        id: 'errorCodes',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['error_code'],
+        filter: f,
+        limit: ERROR_CODE_LIMIT,
+      },
+      {
+        id: 'errorsByDeployment',
+        metricId: 'vercel.function_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['deployment_id', 'http_status'],
+        filter: f,
+        limit: ERROR_DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  external_api_slow(c) {
+    const host = c.hostname;
+    if (!host) return [];
+    const f = odataEq('origin_hostname', host);
+    return [
+      ...latencyPercentiles('latency', 'vercel.external_api_request.request_duration_ms', f),
+      {
+        // "calling route" dim is origin_route (verified via metrics schema).
+        id: 'callersByRoute',
+        metricId: 'vercel.external_api_request.count',
+        aggregation: 'sum',
+        groupBy: ['origin_route'],
+        filter: f,
+        limit: CALLER_LIMIT,
+      },
+      {
+        id: 'transferBytes',
+        metricId: 'vercel.external_api_request.transfer_bytes',
+        aggregation: 'sum',
+        groupBy: [],
+        filter: f,
+      },
+    ];
+  },
+
+  isr_overrevalidation(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      {
+        id: 'writePattern',
+        metricId: 'vercel.isr_operation.write_units',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+      {
+        id: 'readPattern',
+        metricId: 'vercel.isr_operation.read_units',
+        aggregation: 'sum',
+        groupBy: ['cache_result'],
+        filter: f,
+      },
+    ];
+  },
+
+  cwv_poor(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq('route', route);
+    return [
+      ...latencyPercentiles('lcp', 'vercel.speed_insights_metric.lcp', f, ['p50', 'p75', 'p95']),
+      ...latencyPercentiles('inp', 'vercel.speed_insights_metric.inp', f, ['p50', 'p75', 'p95']),
+      ...latencyPercentiles('cls', 'vercel.speed_insights_metric.cls', f, ['p50', 'p75', 'p95']),
+    ];
+  },
+
+  middleware_heavy(_c) {
+    // Account-scope. Surface top middleware-paths so recommender has named targets.
+    return [
+      {
+        id: 'topMiddlewarePaths',
+        metricId: 'vercel.middleware_invocation.count',
+        aggregation: 'sum',
+        groupBy: ['request_path'],
+        limit: MIDDLEWARE_PATH_LIMIT,
+      },
+    ];
+  },
+
+  platform_fluid_compute(_c) {
+    // Broad-pass fnStartTypeByRoute already covers this account-scope rec; runner notes reuse.
+    return [];
+  },
+
+  platform_bot_protection(_c) {
+    return [
+      {
+        id: 'wafRuleFirings',
+        metricId: 'vercel.firewall_action.count',
+        aggregation: 'sum',
+        groupBy: ['waf_rule_id'],
+        limit: WAF_RULE_LIMIT,
+      },
+    ];
+  },
+
+  observability_events_attribution(_c) {
+    // Account-scope billing signal; broad-pass usage and existing route/cache/middleware metrics carry the evidence.
+    return [];
+  },
+
+  usage_spike_triage(_c) {
+    // Daily billing breakdown is already in the gate evidence; no per-candidate metrics query exists.
+    return [];
+  },
+
+  build_minutes_fanout(_c) {
+    // Account-scope billing signal + scanner findings carry the evidence; no per-candidate query.
+    return [];
+  },
+
+  region_misconfig(_c) {
+    // Branch 2 (scanner-only) — per-region TTFB metric unavailable today, so no deep-dive query.
+    return [];
+  },
+};
+
+// Scanner-driven kinds skip deep-dive — evidence already in scanner findings (file + line).
+export const SCANNER_KINDS = new Set([
+  'image_optimization',
+  'cache_header_gap',
+  'rendering_candidate',
+  'use_cache_date_stamp',
+  'cache_components_suspense_dedupe',
+]);
+
+export function specsForCandidate(candidate) {
+  const kind = candidate?.kind;
+  if (!kind) return [];
+  if (SCANNER_KINDS.has(kind)) return [];
+  const gen = SPEC_GENERATORS[kind];
+  if (!gen) return [];
+  return gen(candidate).map((s) => ({ since: TIME_WINDOW, ...s }));
+}
+
+// One spec per percentile — CLI does not support `-a p50 -a p95` multi-aggregation.
+function latencyPercentiles(idPrefix, metricId, filter, percentiles = ['p50', 'p75', 'p95', 'p99']) {
+  return percentiles.map((p) => ({
+    id: `${idPrefix}.${p}`,
+    metricId,
+    aggregation: p,
+    groupBy: [],
+    filter,
+  }));
+}
+
+// Dot-notation spec ids (`latency.p95`) nest under their group prefix.
+export function mergeIntoEvidence(results) {
+  const out = {};
+  for (const r of results) {
+    const id = r?.spec?.id;
+    if (!id) continue;
+    const dot = id.indexOf('.');
+    if (dot > -1) {
+      const head = id.slice(0, dot);
+      const leaf = id.slice(dot + 1);
+      if (!out[head]) out[head] = {};
+      out[head][leaf] = simplify(r);
+    } else {
+      out[id] = simplify(r);
+    }
+  }
+  return out;
+}
+
+// Avoid leaking raw CLI payload / candidate+spec wrapper into evidence — keep summary-only.
+function simplify(r) {
+  if (!r || r.ok === false) return { error: r?.error ?? 'unknown' };
+  // Check rows before value so tabular results with both stay tabular.
+  if (Array.isArray(r.rows)) return r.rows;
+  if ('value' in r) return r.value;
+  return null;
+}

package/.agents/skills/vercel-optimize/lib/display-labels.mjs

@@ -0,0 +1,185 @@
+import { canonicalizeRoute } from './route-normalize.mjs';
+
+const KIND_LABELS = new Map([
+  ['slow_route', 'Slow route'],
+  ['uncached_route', 'Low cache-hit route'],
+  ['cold_start', 'Cold starts'],
+  ['route_errors', 'Route errors'],
+  ['cache_header_gap', 'Missing cache headers'],
+  ['image_optimization', 'Image optimization'],
+  ['external_api_slow', 'Slow external API'],
+  ['isr_overrevalidation', 'ISR over-revalidation'],
+  ['middleware_heavy', 'Heavy middleware'],
+  ['cwv_poor', 'Poor Core Web Vitals'],
+  ['platform_fluid_compute', 'Fluid Compute usage'],
+  ['platform_bot_protection', 'Bot traffic'],
+  ['rendering_candidate', 'Rendering opportunity'],
+  ['missing_cache_headers', 'Missing cache headers'],
+  ['max_age_without_s_maxage', 'Browser-only cache header'],
+  ['force_dynamic', 'Forced dynamic rendering'],
+  ['headers_in_page', 'Dynamic API in page'],
+  ['unoptimized_image', 'Image optimization gap'],
+  ['large_static_asset', 'Large static asset'],
+  ['source_maps_production', 'Production source maps'],
+  ['edge_heavy_import', 'Heavy Edge import'],
+]);
+
+const SIGNAL_LABELS = new Map([
+  ['inv', 'function invocations'],
+  ['runs', 'function invocations'],
+  ['middleware_inv', 'middleware invocations'],
+  ['total_req', 'total requests'],
+  ['requests', 'requests'],
+  ['p95', '95th percentile duration'],
+  ['p75', '75th percentile duration'],
+  ['5xx', '5xx error rate'],
+  ['errs', '5xx errors'],
+  ['rate', '5xx error rate'],
+  ['cache', 'cache hit rate'],
+  ['get', 'GET request share'],
+  ['cold', 'cold start rate'],
+  ['writes', 'ISR write units'],
+  ['reads', 'ISR read units'],
+  ['w/r', 'ISR writes per read'],
+  ['ratio', 'ratio'],
+  ['host', 'host'],
+  ['calls', 'external API calls'],
+  ['edge_cost', 'Edge Request cost units'],
+  ['bot_protection', 'Bot Protection'],
+  ['bot_fdt_pct', 'bot Fast Data Transfer share'],
+  ['LCP', 'Largest Contentful Paint (LCP)'],
+  ['INP', 'Interaction to Next Paint (INP)'],
+  ['CLS', 'Cumulative Layout Shift (CLS)'],
+]);
+
+const REQUEST_COUNT_KINDS = new Set([
+  'uncached_route',
+]);
+
+const PUBLIC_ASSIGNMENT_LABELS = new Map([
+  ...SIGNAL_LABELS,
+  ['deepDive.latency.p95', 'deepDive latency p95'],
+  ['deepDive.cpu.p95', 'deepDive CPU p95'],
+  ['deepDive.ttfb.p95', 'deepDive TTFB p95'],
+  ['cpu.p95', 'CPU p95'],
+  ['latency.p95', 'latency p95'],
+  ['ttfb.p95', 'TTFB p95'],
+  ['cache_result', 'cache result'],
+  ['http_status', 'HTTP status'],
+  ['error_code', 'error code'],
+  ['status', 'status'],
+  ['count', 'count'],
+]);
+
+export function formatKind(kind) {
+  if (!kind) return 'Candidate';
+  if (KIND_LABELS.has(kind)) return KIND_LABELS.get(kind);
+  return String(kind)
+    .split(/[_-]+/g)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'Candidate';
+}
+
+export function formatRoute(candidate) {
+  const route = candidate?.displayRoute ?? candidate?.route ?? candidate?.hostname ?? null;
+  if (route) return String(canonicalizeRoute(route));
+  if (Array.isArray(candidate?.files) && candidate.files.length > 0) return candidate.files[0];
+  return 'account-wide';
+}
+
+export function formatSignal(signal, context = {}) {
+  if (typeof signal !== 'string' || signal.trim() === '') return 'no signal recorded';
+
+  const parts = signal
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => formatSignalPart(part, context));
+
+  return parts.length > 0 ? parts.join('; ') : signal;
+}
+
+export function formatPublicText(value) {
+  if (value == null) return '';
+  return normalizeObservedWindowUnits(String(value))
+    .replace(/\bo11y\b/gi, 'observability')
+    .replace(/\bcache[- ]components gotcha\b/gi, 'Cache Components edge case')
+    .replace(/\bcache_result\b(?!\s*=)/g, 'cache result')
+    .replace(/\bhttp_status\b(?!\s*=)/g, 'HTTP status')
+    .replace(/\berror_code\b(?!\s*=)/g, 'error code')
+    .replace(/,(?=\s*([A-Za-z0-9][\w./-]*)=)/g, (match, key) =>
+      PUBLIC_ASSIGNMENT_LABELS.has(key) ? '; ' : match
+    )
+    .replace(/\b([A-Za-z0-9][\w./-]*)=([^,;\s]+)/g, (match, key, rawValue) => {
+      const label = PUBLIC_ASSIGNMENT_LABELS.get(key);
+      if (!label) return match;
+      return `${label}: ${formatSignalValue(key, rawValue)}`;
+    })
+    .replace(/\b(cache breakdown[^.!?\n;]{0,160}?)\b(?:function\s+)?invocations\b/gi, (match, prefix) =>
+      /\bstatus distribution\b/i.test(prefix) ? match : `${prefix}requests`
+    )
+    .replace(/\b(cache breakdown[^.!?\n;]{0,220}?\bout of\s+[\d,]+)\s+invocations\b/gi, '$1 requests')
+    .replace(/\b(cache hits over\s+[\d,.]+(?:\s?(?:K|M|B))?)\s+invocations\b/gi, '$1 requests')
+    .replace(/\b(?:function\s+)?invocations\b([^.!?\n;]{0,120}\b(?:empty\s+)?cache result(?: label)?\b)/gi, 'requests$1');
+}
+
+export function normalizeObservedWindowUnits(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/(?<!\$)\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/mo\b/gi, '$1/window')
+    .replace(/\bmonthly\s+function\s+invocations\b/gi, 'function invocations/window')
+    .replace(/\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/mo\b/gi, '$1/window')
+    .replace(/\bmonthly\s+(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi, '$1/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+function\s+invocations\s+per month\b/gi, '$1 function invocations/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|invocations?|bytes|writes?|reads?|errors?)\s+per month\b/gi, '$1 $2/window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi, '$1 $2 in this window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi, '$1 $2 in this window')
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\b/gi, '$1 in this window')
+    .replace(/\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi, '$1 in this window');
+}
+
+export function formatCandidateLine(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)} - ${formatSignal(candidate?.o11ySignal, candidate)}`;
+}
+
+export function formatCandidateLabel(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)}`;
+}
+
+function formatSignalPart(part, context = {}) {
+  const eq = part.indexOf('=');
+  if (eq === -1) return part;
+
+  const key = part.slice(0, eq).trim();
+  const value = part.slice(eq + 1).trim();
+  const label = signalLabel(key, context);
+  return `${label}: ${formatSignalValue(key, value)}`;
+}
+
+function signalLabel(key, context = {}) {
+  const kind = typeof context === 'string' ? context : context?.kind;
+  if (key === 'inv' && REQUEST_COUNT_KINDS.has(kind)) return 'requests';
+  return SIGNAL_LABELS.get(key) ?? humanizeKey(key);
+}
+
+function humanizeKey(key) {
+  return String(key)
+    .replaceAll('.', ' ')
+    .replaceAll('_', ' ')
+    .replaceAll('-', ' ')
+    .trim();
+}
+
+function formatSignalValue(key, value) {
+  if (key === 'inv' || key === 'runs' || key === 'middleware_inv' || key === 'total_req' || key === 'requests' || key === 'calls' || key === 'errs' || key === 'writes' || key === 'reads') {
+    return formatNumberLike(value);
+  }
+  return value;
+}
+
+function formatNumberLike(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return value;
+  return new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 }).format(n);
+}