@vizzly-testing/cli 0.35.2 → 0.35.3-beta.1

package/dist/commands/context.js

@@ -5,9 +5,11 @@
 import { createApiClient as defaultCreateApiClient, getBuildContext as defaultGetBuildContext, getComparisonContext as defaultGetComparisonContext, getReviewQueueContext as defaultGetReviewQueueContext, getScreenshotContext as defaultGetScreenshotContext, getSimilarFingerprintContext as defaultGetSimilarFingerprintContext } from '../api/index.js';
 import { createLocalWorkspaceContextProvider as defaultCreateLocalWorkspaceContextProvider } from '../context/local-workspace-provider.js';
 import { resolveContextSource as defaultResolveContextSource } from '../context/provider-resolver.js';
+import { VizzlyError } from '../errors/vizzly-error.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
 import { readSession as defaultReadSession } from '../utils/session.js';
+import { normalizeBuildContext } from '../utils/visual-context-normalizers.js';
 function buildAuthErrorMessage() {
   return 'Authentication required. Use --token, set VIZZLY_TOKEN, run "vizzly login", or link a project.';
 }
@@ -15,7 +17,7 @@ function buildSourceErrorMessage() {
   return '--source must be one of: auto, cloud, local';
 }
 function buildIncludeErrorMessage() {
-  return '--include must contain only: screenshots, diffs, comments';
+  return '--include must contain only: diffs';
 }
 function validateLimitRange(value, flagName, {
   min = 1,
@@ -29,15 +31,81 @@ function validateLimitRange(value, flagName, {
   }
   return [];
 }
-function validateOffset(value) {
+function validateCursor(value) {
   if (value == null) {
     return [];
   }
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return ['--cursor must be a non-empty opaque cursor'];
+  }
+  return [];
+}
+function validateOffset(value) {
+  if (value == null) return [];
   if (!Number.isInteger(value) || value < 0) {
     return ['--offset must be a non-negative integer'];
   }
   return [];
 }
+let COMPACT_CONTEXT_LIMIT = 10;
+let COMPACT_SUMMARY_MAX_BYTES = 64 * 1024;
+let COMPACT_DIFFS_MAX_BYTES = 512 * 1024;
+function getCompactPage(collection, label) {
+  if (!collection || !Array.isArray(collection.items) || !collection.page) {
+    throw new VizzlyError(`Vizzly returned an invalid compact ${label} collection`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (collection.items.length > COMPACT_CONTEXT_LIMIT) {
+    throw new VizzlyError(`Vizzly returned more than ${COMPACT_CONTEXT_LIMIT} compact ${label} items`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (collection.items.some(item => !item || typeof item !== 'object')) {
+    throw new VizzlyError(`Vizzly returned an invalid item in compact ${label}`, 'COMPACT_CONTEXT_INVALID');
+  }
+  let {
+    page
+  } = collection;
+  let validLimit = Number.isInteger(page.limit) && page.limit >= 1 && page.limit <= COMPACT_CONTEXT_LIMIT;
+  let validReturned = Number.isInteger(page.returned) && page.returned === collection.items.length;
+  let validTotal = page.total == null || Number.isInteger(page.total) && page.total >= 0 && page.total >= page.returned;
+  let validHasMore = typeof page.has_more === 'boolean';
+  let validCursor = page.next_cursor == null || typeof page.next_cursor === 'string' && page.next_cursor.length > 0;
+  if (!validLimit || !validReturned || !validTotal || !validHasMore || !validCursor) {
+    throw new VizzlyError(`Vizzly returned invalid pagination facts for compact ${label}`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (page.included === false && collection.items.length > 0) {
+    throw new VizzlyError(`Vizzly returned items for an omitted compact ${label} collection`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (page.has_more !== Boolean(page.next_cursor)) {
+    throw new VizzlyError(`Vizzly returned contradictory pagination facts for compact ${label}`, 'COMPACT_CONTEXT_INVALID');
+  }
+  return collection;
+}
+function validateCompactContext(context, resource) {
+  if (!context || typeof context !== 'object') {
+    throw new VizzlyError(`Vizzly returned an invalid compact ${resource} context`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (context.resource !== `${resource}_context` || !context[resource]?.id) {
+    throw new VizzlyError(`Vizzly returned an invalid compact ${resource} context`, 'COMPACT_CONTEXT_INVALID');
+  }
+  if (resource === 'build') {
+    getCompactPage(context.evidence, 'build evidence');
+  } else {
+    let history = context.history || {};
+    getCompactPage(history.similar_by_fingerprint, 'similar history');
+    getCompactPage(history.recent_by_name, 'recent history');
+  }
+  return context;
+}
+function validateCompactOutputSize(payload, resource, details) {
+  let bytes = Buffer.byteLength(JSON.stringify(payload));
+  let maxBytes = details === 'diffs' ? COMPACT_DIFFS_MAX_BYTES : COMPACT_SUMMARY_MAX_BYTES;
+  if (bytes > maxBytes) {
+    throw new VizzlyError(`Vizzly produced an oversized compact ${resource} context`, 'COMPACT_CONTEXT_OVERSIZED', {
+      bytes,
+      max_bytes: maxBytes
+    });
+  }
+  return payload;
+}
 function validateSourceOption(value) {
   if (value == null) {
     return [];
@@ -54,8 +122,23 @@ function parseIncludeOption(value) {
   let rawItems = Array.isArray(value) ? value : String(value).split(',');
   return rawItems.map(item => item.trim()).filter(Boolean);
 }
+function buildCompactContextRequest(options = {}, globalOptions = {}) {
+  let include = parseIncludeOption(options.include);
+  let compact = !options.full && (!globalOptions.json || options.agent);
+  let details = include.includes('diffs') ? 'diffs' : 'summary';
+  return {
+    compact,
+    details,
+    include,
+    query: compact ? {
+      details,
+      limit: COMPACT_CONTEXT_LIMIT,
+      cursor: options.cursor
+    } : undefined
+  };
+}
 function validateIncludeOption(value) {
-  let allowed = new Set(['screenshots', 'diffs', 'comments']);
+  let allowed = new Set(['diffs']);
   let invalid = parseIncludeOption(value).filter(item => !allowed.has(item));
   return invalid.length > 0 ? [buildIncludeErrorMessage()] : [];
 }
@@ -76,6 +159,24 @@ function createClient(config, createApiClient) {
     command: 'context'
   });
 }
+
+/**
+ * Attach the provider that produced a context payload.
+ *
+ * Context endpoints return API-owned evidence, while source selection belongs
+ * to the CLI. Keeping both in one payload prevents follow-up agent commands
+ * from silently crossing between cloud and local evidence.
+ *
+ * @param {Object} context - Context payload returned by a provider.
+ * @param {string} source - Provider source selected by the CLI.
+ * @returns {Object} Context payload with explicit source provenance.
+ */
+function attachContextSource(context, source) {
+  return {
+    ...context,
+    source
+  };
+}
 async function loadContextConfig(globalOptions, options, deps) {
   let {
     loadConfig = defaultLoadConfig,
@@ -108,20 +209,20 @@ function createCloudContextProvider(config, deps = {}) {
   let client = createClient(config, createApiClient);
   return {
     source: 'cloud',
-    async getBuildContext(buildId) {
-      return await getBuildContext(client, buildId);
+    async getBuildContext(buildId, query) {
+      return attachContextSource(await getBuildContext(client, buildId, query), 'cloud');
     },
     async getComparisonContext(comparisonId, query) {
-      return await getComparisonContext(client, comparisonId, query);
+      return attachContextSource(await getComparisonContext(client, comparisonId, query), 'cloud');
     },
     async getScreenshotContext(screenshotName, query) {
-      return await getScreenshotContext(client, screenshotName, query);
+      return attachContextSource(await getScreenshotContext(client, screenshotName, query), 'cloud');
     },
     async getSimilarFingerprintContext(fingerprintHash, query) {
-      return await getSimilarFingerprintContext(client, fingerprintHash, query);
+      return attachContextSource(await getSimilarFingerprintContext(client, fingerprintHash, query), 'cloud');
     },
     async getReviewQueueContext(query) {
-      return await getReviewQueueContext(client, query);
+      return attachContextSource(await getReviewQueueContext(client, query), 'cloud');
     }
   };
 }
@@ -220,12 +321,6 @@ function getStatusTone(colors, status) {
 function getComparisonDisplayState(comparison = {}) {
   return comparison.result || comparison.status || 'unknown';
 }
-function isChangedComparison(comparison = {}) {
-  return ['changed', 'failed', 'pending'].includes(getComparisonDisplayState(comparison));
-}
-function isNewComparison(comparison = {}) {
-  return getComparisonDisplayState(comparison) === 'new';
-}
 function getComparisonName(comparison = {}) {
   return comparison.screenshot_name || comparison.screenshot?.name || comparison.name || comparison.id || 'unknown screenshot';
 }
@@ -235,141 +330,203 @@ function getComparisonDiffPercentage(comparison = {}) {
 function getComparisonFingerprint(comparison = {}) {
   return comparison.diff?.fingerprint_hash || comparison.analysis?.fingerprint_hash || null;
 }
-function getComparisonDiffImageUrl(comparison = {}) {
-  return comparison.diff?.image_url || comparison.analysis?.diff_image_url || null;
-}
-function getComparisonRegionCount(comparison = {}) {
-  let regions = comparison.diff?.regions || comparison.analysis?.diff_regions;
-  return Array.isArray(regions) ? regions.length : 0;
-}
-function getComparisonScreenshot(comparison = {}) {
-  return comparison.screenshot || {};
-}
-function getComparisonBaseline(comparison = {}) {
-  return comparison.baseline || comparison.screenshot?.baseline || {};
-}
-function buildCompactDiff(comparison = {}, includeDiffs = false) {
-  let diff = comparison.diff || comparison.analysis || {};
-  let compact = {
-    percentage: getComparisonDiffPercentage(comparison),
-    changed_pixels: diff.changed_pixels ?? comparison.changed_pixels ?? null,
-    total_pixels: diff.total_pixels ?? comparison.total_pixels ?? null,
-    threshold: diff.threshold ?? comparison.threshold ?? null,
-    fingerprint_hash: getComparisonFingerprint(comparison),
-    region_count: getComparisonRegionCount(comparison),
-    image_url: getComparisonDiffImageUrl(comparison)
-  };
-  if (includeDiffs) {
-    compact.regions = diff.regions || diff.diff_regions || [];
-    compact.cluster_metadata = diff.cluster_metadata || null;
-    compact.ssim_score = diff.ssim_score ?? null;
-    compact.gmsd_score = diff.gmsd_score ?? null;
-    compact.diff_lines = diff.diff_lines || [];
+
+/**
+ * Quote a value only when a suggested command needs shell protection.
+ *
+ * Suggested commands are meant to be executable, so names with whitespace or
+ * apostrophes must survive copy and paste without changing their value.
+ *
+ * @param {unknown} value - CLI argument value.
+ * @returns {string} A shell-safe argument for the displayed command.
+ */
+function quoteCommandArgument(value) {
+  let stringValue = String(value);
+  if (/^[A-Za-z0-9._:/-]+$/.test(stringValue)) {
+    return stringValue;
   }
-  return compact;
+  return `'${stringValue.replaceAll("'", `'\\''`)}'`;
 }
-function buildCompactComparison(comparison = {}, {
-  includeDiffs = false
-} = {}) {
-  let screenshot = getComparisonScreenshot(comparison);
-  let baseline = getComparisonBaseline(comparison);
-  return {
-    id: comparison.id || null,
-    name: getComparisonName(comparison),
-    result: getComparisonDisplayState(comparison),
-    approval_status: comparison.approval_status || null,
-    needs_review: Boolean(comparison.needs_review),
-    is_flaky: Boolean(comparison.is_flaky),
-    screenshot: {
-      id: screenshot.id || null,
-      url: screenshot.url || screenshot.original_url || null
-    },
-    baseline: {
-      id: baseline.id || null,
-      build_id: baseline.build_id || null,
-      url: baseline.url || baseline.original_url || null
-    },
-    diff: buildCompactDiff(comparison, includeDiffs)
-  };
+
+/**
+ * Recognize both local source labels emitted across supported context shapes.
+ *
+ * @param {Object} context - Normalized context response.
+ * @returns {boolean} Whether follow-up commands must stay in local mode.
+ */
+function isLocalContext(context = {}) {
+  return ['local', 'local_workspace'].includes(context.source);
+}
+
+/**
+ * Keep executable suggestions on the source that produced their evidence.
+ *
+ * Mixed workspaces can contain both a cloud run session and persisted local
+ * TDD results. Pinning either source prevents a follow-up command from
+ * silently crossing that boundary and describing a different build.
+ *
+ * @param {string} command - Base CLI command.
+ * @param {Object} context - Context that produced the command.
+ * @returns {string} Command pinned to its originating source.
+ */
+function appendContextSource(command, context = {}) {
+  let source = isLocalContext(context) ? 'local' : 'cloud';
+  return `${command} --source ${source}`;
+}
+function buildCompactBuildCommands(context = {}, include = [], cursor = null) {
+  let evidence = context.evidence?.items || [];
+  let page = context.evidence?.page || {};
+  let commands = [];
+  let buildTarget = isLocalContext(context) ? 'current' : context.build?.id || null;
+  let firstComparison = evidence.find(item => item.type === 'comparison' && item.id);
+  let firstNamedEvidence = evidence.find(item => item.screenshot_name);
+  if (firstComparison) {
+    commands.push({
+      label: 'Inspect comparison context',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(firstComparison.id)} --agent`, context)
+    });
+  }
+  if (firstNamedEvidence) {
+    let screenshotName = firstNamedEvidence.screenshot_name;
+    commands.push({
+      label: 'Inspect screenshot history',
+      command: appendContextSource(`vizzly --json context screenshot ${quoteCommandArgument(screenshotName)}`, context)
+    });
+  }
+  if (buildTarget && evidence.length > 0) {
+    let cursorFlag = cursor ? ` --cursor ${quoteCommandArgument(cursor)}` : '';
+    commands.push({
+      label: 'Load raw diff diagnostics',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --include diffs${cursorFlag}`, context)
+    });
+  }
+  if (buildTarget && page.has_more && page.next_cursor) {
+    let includeFlag = include.length > 0 ? ` --include ${include.join(',')}` : '';
+    commands.push({
+      label: 'Load next evidence page',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --cursor ${quoteCommandArgument(page.next_cursor)}${includeFlag}`, context)
+    });
+  }
+  if (buildTarget) {
+    commands.push({
+      label: 'Load full build context',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --full`, context)
+    });
+  }
+  return commands;
 }
-function summarizeComparisons(comparisons = []) {
+function buildCompactBuildPayload(context, include = [], cursor = null) {
   return {
-    total: comparisons.length,
-    changed: comparisons.filter(isChangedComparison).length,
-    new: comparisons.filter(isNewComparison).length,
-    needs_review: comparisons.filter(comparison => comparison.needs_review).length
+    ...context,
+    resource: 'build_agent_context',
+    suggested_commands: buildCompactBuildCommands(context, include, cursor)
   };
 }
-function buildAgentNextActions(context = {}, comparisonSummary = {}) {
-  if (context.status?.needs_review) {
-    return ['Inspect the changed and new comparisons before editing related UI.', 'Use approved baselines as the expected visual behavior.', 'Leave approval decisions to human reviewers.'];
+function buildCompactComparisonCommands(context = {}, include = []) {
+  let commands = [];
+  let comparisonId = context.comparison?.id;
+  let streams = [['similar_by_fingerprint', 'similar history'], ['recent_by_name', 'recent history']];
+  let includeFlag = include.length > 0 ? ` --include ${include.join(',')}` : '';
+  for (let [stream, label] of streams) {
+    let page = context.history?.[stream]?.page;
+    if (!comparisonId || !page?.has_more || !page.next_cursor) {
+      continue;
+    }
+    commands.push({
+      label: `Load next ${label} page`,
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --cursor ${quoteCommandArgument(page.next_cursor)}${includeFlag}`, context)
+    });
   }
-  if (comparisonSummary.total > 0) {
-    return ['Use the approved baseline and reviewed screenshots as current visual truth.', 'Prefer targeted edits that preserve identical comparisons.'];
+  if (comparisonId) {
+    commands.push({
+      label: 'Load full comparison context',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --full`, context)
+    });
   }
-  return ['No comparisons were returned for this build context.', 'Open the build URL for more detail if this is unexpected.'];
+  return commands;
 }
-function formatAgentStatus(status = {}) {
+function buildCompactComparisonPayload(context, include = []) {
   return {
-    needs_review: Boolean(status.needs_review),
-    reasons: status.reasons || [],
-    pending_comparisons: status.pending_comparisons || 0,
-    unresolved_comments: status.unresolved_comments || 0
+    ...context,
+    resource: 'comparison_agent_context',
+    suggested_commands: buildCompactComparisonCommands(context, include)
   };
 }
-function formatAgentSummary(context = {}, comparisons = []) {
-  return {
-    comparisons: context.summary?.comparisons || summarizeComparisons(comparisons),
-    review: context.summary?.review || {},
-    comments: context.summary?.comments || {
-      build: getBuildCommentsCount(context),
-      screenshot: getScreenshotCommentsCount(context)
+function formatKnownBoolean(value) {
+  if (value === true) return 'yes';
+  if (value === false) return 'no';
+  return 'unknown';
+}
+function formatCompactPage(collection) {
+  let page = collection?.page || {};
+  let returned = page.returned ?? collection?.items?.length;
+  let total = page.total;
+  if (returned == null) return 'unknown';
+  if (total == null) return String(returned);
+  return `${returned} of ${total}${page.has_more ? ' · more available' : ''}`;
+}
+function displayCompactHeading(output, context, title, status) {
+  let colors = output.getColors();
+  let tone = getStatusTone(colors, status);
+  let organization = context.scope?.organization?.slug || 'unknown';
+  let project = context.scope?.project?.slug || 'unknown';
+  output.print(`  ${colors.bold(title)} ${tone(status.toUpperCase())}`);
+  output.print(`  ${colors.dim(`@${organization}/${project}`)}`);
+  output.blank();
+}
+function displayCompactBuildContext(output, context) {
+  output.header('context', 'build');
+  let colors = output.getColors();
+  let build = context.build || {};
+  let displayStatus = build.status || context.status?.state || 'unknown';
+  displayCompactHeading(output, context, build.name || build.id || 'unknown build', displayStatus);
+  output.labelValue('Attention', formatKnownBoolean(context.status?.needs_review));
+  output.labelValue('Evidence', formatCompactPage(context.evidence));
+  let items = context.evidence?.items || [];
+  if (items.length > 0) {
+    output.blank();
+    output.print('  Evidence');
+    for (let item of items) {
+      let result = item.result || item.status || 'unknown';
+      let percentage = getComparisonDiffPercentage(item);
+      let detail = percentage == null ? '' : ` · ${percentage}% diff`;
+      output.print(`  ${colors.dim('•')} ${getComparisonName(item)}: ${result}${detail}`);
     }
-  };
+  }
+  if (context.evidence?.page?.has_more) {
+    let next = context.suggested_commands?.find(command => command.label === 'Load next evidence page');
+    if (next) {
+      output.blank();
+      output.labelValue('Next', next.command);
+    }
+  }
+  if (context.links?.build_url) {
+    output.labelValue('Build URL', context.links.build_url);
+  }
 }
-function buildAgentBuildPayload(context, {
-  source = null,
-  include = [],
-  evidenceLimit = 10
-} = {}) {
-  let comparisons = context.comparisons || [];
-  let includeSet = new Set(include);
-  let includeDiffs = includeSet.has('diffs');
-  let changed = comparisons.filter(isChangedComparison);
-  let fresh = comparisons.filter(isNewComparison);
-  let evidence = [...changed, ...fresh].slice(0, evidenceLimit).map(comparison => buildCompactComparison(comparison, {
-    includeDiffs
-  }));
-  let comparisonSummary = summarizeComparisons(comparisons);
-  let payload = {
-    resource: 'build_agent_context',
-    source: context.source || source || 'cloud',
-    scope: context.scope || null,
-    project: {
-      organization: context.scope?.organization?.slug || null,
-      slug: context.scope?.project?.slug || null,
-      name: context.scope?.project?.name || null,
-      visibility: context.scope?.project?.visibility || null
-    },
-    build: context.build || null,
-    baseline: {
-      selected: context.baseline?.selected || null,
-      selection_reason: context.baseline?.selection_reason || null
-    },
-    status: formatAgentStatus(context.status),
-    summary: formatAgentSummary(context, comparisons),
-    evidence,
-    links: context.links || {},
-    preview: context.preview || null,
-    next_actions: buildAgentNextActions(context, comparisonSummary)
-  };
-  if (includeSet.has('screenshots')) {
-    payload.screenshots = context.screenshots || [];
+function displayCompactComparisonContext(output, context) {
+  output.header('context', 'comparison');
+  let comparison = context.comparison || {};
+  let displayState = getComparisonDisplayState(comparison);
+  displayCompactHeading(output, context, getComparisonName(comparison), displayState);
+  output.labelValue('Images', comparison.diff?.image_url || comparison.analysis?.diff_image_url ? 'baseline/current/diff available' : 'unavailable');
+  output.labelValue('Similar history', formatCompactPage(context.history?.similar_by_fingerprint));
+  output.labelValue('Recent history', formatCompactPage(context.history?.recent_by_name));
+  let similar = context.history?.similar_by_fingerprint?.items || [];
+  if (similar.length > 0) {
+    output.blank();
+    output.print('  Similar Diffs');
+    printComparisonList(output, similar);
   }
-  if (includeSet.has('comments')) {
-    payload.comments = context.comments || {};
+  let recent = context.history?.recent_by_name?.items || [];
+  if (recent.length > 0) {
+    output.blank();
+    output.print('  Recent Diffs');
+    printComparisonList(output, recent);
+  }
+  if (context.links?.comparison_url) {
+    output.labelValue('Comparison URL', context.links.comparison_url);
   }
-  return payload;
 }
 function getBuildCommentsCount(context = {}) {
   if (Array.isArray(context.comments?.build)) {
@@ -396,12 +553,17 @@ function formatNeedsReview(status = {}) {
   if (!status || status.needs_review == null) {
     return null;
   }
-  let pending = status.pending_comparisons || 0;
-  let unresolved = status.unresolved_comments || 0;
   if (!status.needs_review) {
     return 'no';
   }
-  return `yes · ${pending} comparisons · ${unresolved} unresolved comments`;
+  let details = [];
+  if (status.pending_comparisons != null) {
+    details.push(`${status.pending_comparisons} comparisons`);
+  }
+  if (status.unresolved_comments != null) {
+    details.push(`${status.unresolved_comments} unresolved comments`);
+  }
+  return details.length > 0 ? `yes · ${details.join(' · ')}` : 'yes';
 }
 function formatConfirmedRegionLabels(regions = []) {
   return regions.map(region => region.label).filter(Boolean).slice(0, 3).join(' · ');
@@ -436,98 +598,132 @@ function printComparisonList(output, comparisons = [], {
     }
   }
 }
+function getGroupDisplayState(group = {}) {
+  let aggregate = group.aggregate_status || {};
+  if ((aggregate.failed_count ?? 0) > 0) return 'failed';
+  if (aggregate.has_rejected === true) return 'rejected';
+  if (aggregate.has_changes === true) return 'changed';
+  if (aggregate.has_new === true) return 'new';
+  if (aggregate.needs_review === true) return 'needs review';
+  if (aggregate.all_approved === true) return 'approved';
+  return null;
+}
+function formatViewport(viewport) {
+  if (!viewport) {
+    return null;
+  }
+  return `${viewport.width ?? '?'}×${viewport.height ?? '?'}`;
+}
+function printScreenshotGroups(output, groups = [], {
+  limit = 8
+} = {}) {
+  let colors = output.getColors();
+  let visibleGroups = groups.slice(0, limit);
+  output.print('  Screenshot groups');
+  for (let group of visibleGroups) {
+    let displayState = getGroupDisplayState(group);
+    let tone = getStatusTone(colors, displayState);
+    let aggregate = group.aggregate_status || {};
+    let details = [];
+    if (group.variant_count != null) {
+      details.push(`${group.variant_count} variants`);
+    }
+    if (aggregate.needs_review_count != null) {
+      details.push(`${aggregate.needs_review_count} needs review`);
+    }
+    if (aggregate.failed_count != null && aggregate.failed_count > 0) {
+      details.push(`${aggregate.failed_count} failed`);
+    }
+    if (aggregate.max_diff_percentage != null) {
+      details.push(`${aggregate.max_diff_percentage}% max diff`);
+    }
+    output.print(`  ${colors.bold(group.name)}${displayState ? ` ${tone(displayState.toUpperCase())}` : ''}`);
+    if (details.length > 0) {
+      output.print(`    ${colors.dim(details.join(' · '))}`);
+    }
+    for (let variant of group.variants.slice(0, 3)) {
+      let variantDetails = [variant.review_state, variant.browser, formatViewport(variant.viewport)].filter(Boolean);
+      output.print(`    ${getStatusTone(colors, variant.result)((variant.result || 'unknown').toUpperCase())}${variantDetails.length > 0 ? ` · ${colors.dim(variantDetails.join(' · '))}` : ''}`);
+    }
+  }
+  if (groups.length > visibleGroups.length) {
+    output.print(`    ${colors.dim(`...${groups.length - visibleGroups.length} more groups`)}`);
+  }
+}
+function printFailedCaptures(output, captures = []) {
+  let colors = output.getColors();
+  output.print('  Failed captures');
+  for (let capture of captures.slice(0, 8)) {
+    let details = [capture.error_message, capture.browser, formatViewport(capture.viewport), capture.screenshot.url].filter(Boolean);
+    output.print(`  ${colors.bold(capture.name)} ${colors.brand.error('FAILED')}`);
+    if (details.length > 0) {
+      output.print(`    ${colors.dim(details.join(' · '))}`);
+    }
+  }
+}
+function formatReviewSummary(review = {}) {
+  let details = [review.pending != null ? `${review.pending} pending` : null, review.approved != null ? `${review.approved} approved` : null, review.rejected != null ? `${review.rejected} rejected` : null].filter(Boolean);
+  return details.length > 0 ? details.join(' · ') : null;
+}
 function displayBuildContext(output, context) {
   output.header('context', 'build');
+  let normalizedContext = normalizeBuildContext(context);
   let colors = output.getColors();
-  let buildTone = getStatusTone(colors, context.build.status);
-  let comparisons = context.comparisons || [];
-  let screenshots = context.screenshots || [];
-  let reviewSummary = context.summary?.review || {};
-  let commentsSummary = context.summary?.comments || {};
-  let needsReview = formatNeedsReview(context.status);
-  let baseline = context.baseline?.selected || null;
-  output.print(`  ${colors.bold(context.build.name || context.build.id)} ${buildTone((context.build.status || 'unknown').toUpperCase())}`);
-  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  let build = normalizedContext.build || {};
+  let buildTone = getStatusTone(colors, build.status);
+  let comparisons = normalizedContext.comparisons;
+  let groups = normalizedContext.groups;
+  let screenshots = normalizedContext.screenshots || [];
+  let failedCaptures = normalizedContext.failed_captures;
+  let reviewSummary = formatReviewSummary(normalizedContext.summary?.review);
+  let commentsSummary = normalizedContext.summary?.comments || {};
+  let needsReview = formatNeedsReview(normalizedContext.status);
+  let baseline = normalizedContext.baseline?.selected || null;
+  let comparisonCount = normalizedContext.summary?.comparisons?.total ?? normalizedContext.total_comparisons ?? (Array.isArray(context.comparisons) ? comparisons.length : null);
+  let screenshotCount = normalizedContext.summary?.screenshots?.total ?? normalizedContext.screenshot_count ?? (Array.isArray(context.screenshots) ? screenshots.length : null);
+  output.print(`  ${colors.bold(build.name || build.id || 'unknown build')} ${buildTone((build.status || 'unknown').toUpperCase())}`);
+  output.print(`  ${colors.dim(`@${normalizedContext.scope?.organization?.slug || 'unknown'}/${normalizedContext.scope?.project?.slug || 'unknown'}`)}`);
   output.blank();
-  output.labelValue('Comparisons', String(comparisons.length));
-  if (screenshots.length > 0) {
-    output.labelValue('Screenshots', String(screenshots.length));
+  if (comparisonCount != null) {
+    output.labelValue('Comparisons', String(comparisonCount));
+  }
+  if (groups.length > 0) {
+    output.labelValue('Screenshot Groups', String(groups.length));
+  }
+  if (screenshotCount != null) {
+    output.labelValue('Screenshots', String(screenshotCount));
   }
   if (baseline) {
-    output.labelValue('Baseline', `${baseline.name || baseline.id || 'selected'}${context.baseline.selection_reason ? ` · ${context.baseline.selection_reason}` : ''}`);
+    output.labelValue('Baseline', `${baseline.name || baseline.id || 'selected'}${normalizedContext.baseline.selection_reason ? ` · ${normalizedContext.baseline.selection_reason}` : ''}`);
   }
   if (needsReview) {
     output.labelValue('Needs Review', needsReview);
   }
-  output.labelValue('Review', `${reviewSummary.pending || 0} pending · ${reviewSummary.approved || 0} approved · ${reviewSummary.rejected || 0} rejected`);
-  output.labelValue('Memory', `${commentsSummary.build ?? getBuildCommentsCount(context)} build comments · ${commentsSummary.screenshot ?? getScreenshotCommentsCount(context)} screenshot comments · ${getReviewAssignmentsCount(context)} assignments`);
-  if (context.preview) {
-    let previewUrl = context.preview.preview_url || context.preview.url;
-    output.labelValue('Preview', `${context.preview.status || 'unknown'}${previewUrl ? ' · available' : ''}`);
-  }
-  if (context.links?.build_url) {
-    output.labelValue('Build URL', context.links.build_url);
-  }
-  if (comparisons.length > 0) {
-    output.blank();
-    output.print('  Comparisons');
-    printComparisonList(output, comparisons);
+  if (reviewSummary) {
+    output.labelValue('Review', reviewSummary);
   }
-}
-function formatAgentBuildContext(context) {
-  let comparisons = context.comparisons || [];
-  let changed = comparisons.filter(isChangedComparison);
-  let fresh = comparisons.filter(isNewComparison);
-  let needsReview = comparisons.filter(comparison => comparison.needs_review);
-  let baseline = context.baseline?.selected;
-  let lines = [`# Vizzly Visual Context: ${context.build?.name || context.build?.id || 'Build'}`, '', `Project: ${context.scope?.organization?.slug || 'unknown'}/${context.scope?.project?.slug || 'unknown'}`, `Build: ${context.build?.id || 'unknown'} (${context.build?.status || 'unknown'})`];
-  if (baseline) {
-    lines.push(`Approved baseline: ${baseline.name || baseline.id || 'selected'} (${baseline.approval_status || 'unknown'})`);
+  let buildComments = commentsSummary.build ?? (Array.isArray(normalizedContext.comments?.build) ? getBuildCommentsCount(normalizedContext) : null);
+  let screenshotComments = commentsSummary.screenshot ?? (Number.isInteger(normalizedContext.comments?.screenshot_count) ? getScreenshotCommentsCount(normalizedContext) : null);
+  let assignments = Array.isArray(normalizedContext.review?.assignments) ? getReviewAssignmentsCount(normalizedContext) : null;
+  let memory = [buildComments != null ? `${buildComments} build comments` : null, screenshotComments != null ? `${screenshotComments} screenshot comments` : null, assignments != null ? `${assignments} assignments` : null].filter(Boolean);
+  if (memory.length > 0) {
+    output.labelValue('Memory', memory.join(' · '));
   }
-  if (context.status) {
-    lines.push(`Needs review: ${context.status.needs_review ? 'yes' : 'no'} (${context.status.pending_comparisons || 0} pending comparisons)`);
+  if (normalizedContext.preview) {
+    let previewUrl = normalizedContext.preview.preview_url || normalizedContext.preview.url;
+    output.labelValue('Preview', `${normalizedContext.preview.status || 'unknown'}${previewUrl ? ' · available' : ''}`);
   }
-  if (context.preview?.url || context.preview?.preview_url) {
-    lines.push(`Preview: ${context.preview.url || context.preview.preview_url}`);
+  if (normalizedContext.links?.build_url) {
+    output.labelValue('Build URL', normalizedContext.links.build_url);
   }
-  if (context.links?.build_url) {
-    lines.push(`Build URL: ${context.links.build_url}`);
-  }
-  if (context.links?.report_url) {
-    lines.push(`Report: ${context.links.report_url}`);
-  }
-  lines.push('');
-  lines.push('## Diff Summary');
-  lines.push(`- Total comparisons: ${comparisons.length}`);
-  lines.push(`- Changed: ${changed.length}`);
-  lines.push(`- New: ${fresh.length}`);
-  lines.push(`- Needs review: ${needsReview.length}`);
-  if (changed.length > 0 || fresh.length > 0) {
-    lines.push('');
-    lines.push('## Evidence To Inspect');
-    for (let comparison of [...changed, ...fresh].slice(0, 10)) {
-      let diffPercentage = getComparisonDiffPercentage(comparison);
-      let detail = diffPercentage == null ? '' : ` · ${diffPercentage}% diff`;
-      let diffUrl = comparison.diff?.image_url || comparison.analysis?.diff_image_url;
-      lines.push(`- ${getComparisonName(comparison)}: ${getComparisonDisplayState(comparison)}${detail}`);
-      if (diffUrl) {
-        lines.push(`  Diff: ${diffUrl}`);
-      }
-    }
+  if (groups.length > 0) {
+    output.blank();
+    printScreenshotGroups(output, groups);
   }
-  if (comparisons.length > 0 && changed.length === 0 && fresh.length === 0) {
-    lines.push('');
-    lines.push('## Reviewed Screenshots');
-    for (let comparison of comparisons.slice(0, 10)) {
-      lines.push(`- ${getComparisonName(comparison)}: ${getComparisonDisplayState(comparison)}`);
-    }
-    if (comparisons.length > 10) {
-      lines.push(`- ...${comparisons.length - 10} more`);
-    }
+  if (failedCaptures.length > 0) {
+    output.blank();
+    printFailedCaptures(output, failedCaptures);
   }
-  lines.push('');
-  lines.push('Use this as reviewed UI context. Treat approved baselines as visual truth, inspect meaningful diffs, and leave approval decisions to humans.');
-  return lines.join('\n');
 }
 function countScreenshotCommentEntries(groups = []) {
   return groups.reduce((total, group) => total + (group.comments?.length || 0), 0);
@@ -631,14 +827,23 @@ export async function contextBuildCommand(buildId, options = {}, globalOptions =
       return;
     }
     let resolvedBuildId = resolveBuildContextId(buildId, runtime, deps);
+    let {
+      compact,
+      details,
+      include,
+      query
+    } = buildCompactContextRequest(options, globalOptions);
     output.startSpinner('Fetching build context...');
-    let context = await runtime.provider.getBuildContext(resolvedBuildId);
+    let context = await runtime.provider.getBuildContext(resolvedBuildId, query);
     output.stopSpinner();
-    if (globalOptions.json && options.agent && !options.full) {
-      output.data(buildAgentBuildPayload(context, {
-        source: runtime.source,
-        include: parseIncludeOption(options.include)
-      }));
+    if (compact) {
+      let compactContext = validateCompactContext(context, 'build');
+      let payload = validateCompactOutputSize(buildCompactBuildPayload(compactContext, include, options.cursor), 'build', details);
+      if (globalOptions.json) {
+        output.data(payload);
+      } else {
+        displayCompactBuildContext(output, payload);
+      }
       output.cleanup();
       return;
     }
@@ -647,11 +852,6 @@ export async function contextBuildCommand(buildId, options = {}, globalOptions =
       output.cleanup();
       return;
     }
-    if (options.agent) {
-      output.print(formatAgentBuildContext(context));
-      output.cleanup();
-      return;
-    }
     displayBuildContext(output, context);
     output.cleanup();
   } catch (error) {
@@ -680,14 +880,26 @@ export async function contextComparisonCommand(comparisonId, options = {}, globa
     if (!runtime) {
       return;
     }
-    let query = {
-      similarLimit: options.similarLimit,
-      recentLimit: options.recentLimit,
-      windowSize: options.windowSize
-    };
+    let {
+      compact,
+      details,
+      include,
+      query
+    } = buildCompactContextRequest(options, globalOptions);
     output.startSpinner('Fetching comparison context...');
     let context = await runtime.provider.getComparisonContext(comparisonId, query);
     output.stopSpinner();
+    if (compact) {
+      let compactContext = validateCompactContext(context, 'comparison');
+      let payload = validateCompactOutputSize(buildCompactComparisonPayload(compactContext, include), 'comparison', details);
+      if (globalOptions.json) {
+        output.data(payload);
+      } else {
+        displayCompactComparisonContext(output, payload);
+      }
+      output.cleanup();
+      return;
+    }
     if (globalOptions.json) {
       output.data(context);
       output.cleanup();
@@ -824,20 +1036,14 @@ export async function contextReviewQueueCommand(options = {}, globalOptions = {}
 export function validateContextBuildOptions(_options = {}) {
   let errors = validateSourceOption(_options.source);
   errors.push(...validateIncludeOption(_options.include));
+  errors.push(...validateCursor(_options.cursor));
   return errors;
 }
 export function validateContextComparisonOptions(options = {}) {
   let errors = [];
   errors.push(...validateSourceOption(options.source));
-  errors.push(...validateLimitRange(options.similarLimit, '--similar-limit', {
-    max: 50
-  }));
-  errors.push(...validateLimitRange(options.recentLimit, '--recent-limit', {
-    max: 50
-  }));
-  errors.push(...validateLimitRange(options.windowSize, '--window-size', {
-    max: 50
-  }));
+  errors.push(...validateIncludeOption(options.include));
+  errors.push(...validateCursor(options.cursor));
   return errors;
 }
 export function validateContextScreenshotOptions(options = {}) {