@limrun/api 0.41.1 → 0.42.0

package/src/client.ts

@@ -54,6 +54,19 @@ import {
   XcodeInstanceListParams,
   XcodeInstancesItems,
 } from './resources/xcode-instances';
+import {
+  GradleInstance,
+  GradleInstanceCreateParams,
+  GradleInstanceListParams,
+  GradleInstancesItems,
+} from './resources/gradle-instances';
+import {
+  GradleInstances,
+  GradleCreateClientParams,
+  GradleClient,
+  GradleSyncOptions,
+  GradleBuildOptions,
+} from './resources/gradle-instances-helpers';
 import {
   XcodeInstances,
   XcodeCreateClientParams,
@@ -822,6 +835,7 @@ export class Limrun {
   assets: API.Assets = new API.Assets(this);
   iosInstances: API.IosInstances = new API.IosInstances(this);
   xcodeInstances: API.XcodeInstances = new API.XcodeInstances(this);
+  gradleInstances: API.GradleInstances = new API.GradleInstances(this);
   analytics: API.Analytics = new API.Analytics(this);
 }
 
@@ -829,6 +843,7 @@ Limrun.AndroidInstances = AndroidInstances;
 Limrun.Assets = Assets;
 Limrun.IosInstances = IosInstances;
 Limrun.XcodeInstances = XcodeInstances;
+Limrun.GradleInstances = GradleInstances;
 Limrun.Analytics = Analytics;
 
 export declare namespace Limrun {
@@ -883,6 +898,18 @@ export declare namespace Limrun {
     type SimulatorInstallState as SimulatorInstallState,
   };
 
+  export {
+    GradleInstances as GradleInstances,
+    type GradleInstance as GradleInstance,
+    type GradleInstancesItems as GradleInstancesItems,
+    type GradleInstanceCreateParams as GradleInstanceCreateParams,
+    type GradleInstanceListParams as GradleInstanceListParams,
+    type GradleCreateClientParams as GradleCreateClientParams,
+    type GradleClient as GradleClient,
+    type GradleSyncOptions as GradleSyncOptions,
+    type GradleBuildOptions as GradleBuildOptions,
+  };
+
   export {
     Analytics as Analytics,
     type AnalyticsInstancesResponse as AnalyticsInstancesResponse,

package/src/exec-client.ts

@@ -12,7 +12,9 @@ import { nodeProxyTransport } from './internal/proxy-transport';
 // Types
 // =============================================================================
 
-export type ExecRequest = {
+export type ExecRequest = XcodeBuildExecRequest | GradleBuildExecRequest;
+
+export type XcodeBuildExecRequest = {
   command: 'xcodebuild';
   xcodebuild?: {
     workspace?: string;
@@ -43,6 +45,41 @@ export type ExecRequest = {
   };
 };
 
+/** Android ABIs the gradle daemon accepts; 'all' keeps the project's own configuration. */
+export type GradleAndroidABI = 'armeabi-v7a' | 'arm64-v8a' | 'x86' | 'x86_64' | 'all';
+
+/**
+ * React Native / Expo tuning for gradle builds. The server detects Expo
+ * managed-workflow projects automatically when the workspace has no
+ * Gradle root; setting this forces the React Native pipeline (dependency
+ * install, expo prebuild) and is an error for projects with no detected
+ * Expo app.
+ */
+export type GradleReactNativeConfig = {
+  /** Relative path to the Expo app directory in a monorepo. Omit to auto-detect. */
+  expoAppDir?: string;
+  /**
+   * Android ABIs to build. The server defaults to x86_64 (what Limrun
+   * Android instances run) except for release and bundle tasks, which
+   * keep the project's own ABI configuration; pass ['all'] to always
+   * keep it.
+   */
+  architectures?: GradleAndroidABI[];
+};
+
+export type GradleBuildExecRequest = {
+  command: 'gradlebuild';
+  /** Gradle tasks to run. Omit for the server default (assembleDebug). */
+  tasks?: string[];
+  /** Relative path to the Gradle root when auto-discovery is ambiguous. */
+  projectPath?: string;
+  reactNative?: GradleReactNativeConfig;
+  signedUploadUrl?: string;
+  additionalMetadata?: {
+    signedDownloadUrl?: string;
+  };
+};
+
 export type ExecOptions = {
   apiUrl: string;
   token: string;
@@ -232,7 +269,12 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
     const { log } = this;
     const { apiUrl, token } = this.options;
 
-    // 1. Trigger the build via POST /exec
+    // 1. Trigger the build via POST /exec.
+    // additionalMetadata is a client-only carrier (no daemon reads it; it is
+    // spread into ExecResult below so callers can surface the download URL), so
+    // it is stripped from the wire body: the daemon OpenAPI schemas do not
+    // declare it, and sending it would 400 under strict request validation.
+    const { additionalMetadata: _clientOnly, ...wireRequest } = request;
     let execRes: Response;
     try {
       execRes = await nodeProxyTransport.fetch(`${apiUrl}/exec`, {
@@ -241,7 +283,7 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
           'Content-Type': 'application/json',
           Authorization: `Bearer ${token}`,
         },
-        body: JSON.stringify(request),
+        body: JSON.stringify(wireRequest),
         signal: this.abortController.signal,
       });
     } catch (err) {
@@ -259,7 +301,15 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
 
     if (!execRes.ok) {
       const text = await execRes.text();
-      throw new Error(`exec failed: ${execRes.status} ${text}`);
+      let message = text;
+      try {
+        // The daemon returns an APIError JSON body; surface its message
+        // instead of the raw escaped JSON.
+        message = (JSON.parse(text) as { message?: string }).message || text;
+      } catch {
+        // Not JSON; keep the raw body.
+      }
+      throw new Error(`exec failed: ${execRes.status} ${message}`);
     }
 
     const execData = (await execRes.json()) as { execId: string };
@@ -273,7 +323,7 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
     // budget by its server-side verdict watch plus upload headroom so a long
     // build is not force-failed client-side while the server still succeeds.
     let timeoutMs = 3600 * 1000;
-    if (request.testflight) {
+    if (request.command === 'xcodebuild' && request.testflight) {
       timeoutMs += (Math.max(0, request.testflight.waitTimeoutSeconds ?? 120) + 900) * 1000;
     }
     let exitCode: number;

package/src/folder-sync-ignore.ts

@@ -31,6 +31,14 @@ export type IgnoreFnOptions = {
    * in it.
    */
   xcodeDefaults?: boolean;
+  /**
+   * Honor .gitignore files in nested directories, not just the project root.
+   * Defaults to whatever `xcodeDefaults` is, so existing callers are unchanged;
+   * a caller can enable it independently (e.g. gradle sync, whose nested module
+   * build/ dirs are excluded by their own app/.gitignore) without opting into
+   * the Xcode-specific default excludes and force-includes.
+   */
+  nestedGitignore?: boolean;
   basisCacheDir: string;
   log?: IgnoreLogger;
 };
@@ -43,6 +51,14 @@ function normalizeRelativePath(relativePath: string): string {
     .replace(/\/+/g, '/');
 }
 
+// Linear-time replacement for `.replace(/\/+$/, '')`: that regex backtracks
+// quadratically on long runs of '/' (flagged by CodeQL as polynomial ReDoS).
+function stripTrailingSlashes(s: string): string {
+  let end = s.length;
+  while (end > 0 && s[end - 1] === '/') end--;
+  return end === s.length ? s : s.slice(0, end);
+}
+
 type GitTrackedSets = {
   tracked: Set<string>;
   prefixes: Set<string>;
@@ -138,7 +154,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
   // install sync) keep the legacy behavior: root-only .gitignore and no
   // project force-includes, so a build artifact isn't reshaped by gitignore
   // files or Xcode-specific rules that happen to sit inside it.
-  const nestedGitignore = !!options.xcodeDefaults;
+  const nestedGitignore = options.nestedGitignore ?? !!options.xcodeDefaults;
 
   // Evaluates the .gitignore chain for a path (trailing slash preserved so
   // dir-only rules like `build/` match the directory itself). Files are
@@ -146,7 +162,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
   // files naturally override shallower ones. When nestedGitignore is off,
   // only the root .gitignore is consulted.
   const gitignoreDecision = (testPath: string): { ignored: boolean; rule?: string } | undefined => {
-    const withoutTrailingSlash = testPath.replace(/\/+$/, '');
+    const withoutTrailingSlash = stripTrailingSlashes(testPath);
     const trailingSlash = testPath.endsWith('/') ? '/' : '';
     const parts = withoutTrailingSlash.split('/');
     let decision: { ignored: boolean; rule?: string } | undefined;
@@ -164,9 +180,9 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     return decision;
   };
 
-  const basisCacheRelative = normalizeRelativePath(
-    path.relative(rootResolved, options.basisCacheDir),
-  ).replace(/\/+$/, '');
+  const basisCacheRelative = stripTrailingSlashes(
+    normalizeRelativePath(path.relative(rootResolved, options.basisCacheDir)),
+  );
   const shouldIgnoreBasisCache =
     basisCacheRelative &&
     basisCacheRelative !== '.' &&
@@ -181,7 +197,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
   return (relativePath: string) => {
     const normalized = normalizeRelativePath(relativePath);
     if (!normalized) return false;
-    const withoutTrailingSlash = normalized.replace(/\/+$/, '');
+    const withoutTrailingSlash = stripTrailingSlashes(normalized);
 
     // 1. The basis cache must not sync itself, even when --include matches.
     if (

package/src/index.ts

@@ -13,6 +13,10 @@ export { buildSettingKeyPattern, parseBuildSettingEntries, validateBuildSettings
 export {
   exec,
   type ExecRequest,
+  type XcodeBuildExecRequest,
+  type GradleAndroidABI,
+  type GradleBuildExecRequest,
+  type GradleReactNativeConfig,
   type ExecOptions,
   type ExecResult,
   type ExecChildProcess,
@@ -46,6 +50,12 @@ export {
   type SimulatorDeviceInfo,
   type SimulatorInstallState,
 } from './resources/xcode-instances-helpers';
+export {
+  type GradleCreateClientParams,
+  type GradleClient,
+  type GradleSyncOptions,
+  type GradleBuildOptions,
+} from './resources/gradle-instances-helpers';
 export {
   LIMRUN_DIR,
   TRY_IMPORT_LINE,

package/src/resources/daemon-client-shared.ts

@@ -0,0 +1,71 @@
+// Helpers and platform-neutral types shared by the per-instance build-daemon
+// clients (xcode, gradle).
+
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+/**
+ * Derives the client-side folder-sync cache location for a local project.
+ * The key format is a compatibility contract: changing it orphans every
+ * user's existing basis cache, so both daemon clients must share this one
+ * derivation.
+ */
+export function deriveBasisCache(
+  localCodePath: string,
+  override?: string,
+): { cacheKey: string; basisCacheDir: string } {
+  const resolvedPath = path.resolve(localCodePath);
+  const folderName = path.basename(resolvedPath);
+  const hash = crypto.createHash('sha1').update(resolvedPath).digest('hex').slice(0, 8);
+  const cacheKey = `limsync-cache-${folderName}-${hash}`;
+  return { cacheKey, basisCacheDir: override ?? path.join(os.tmpdir(), cacheKey) };
+}
+
+export type SyncResult = {
+  /**
+   * Number of bytes transmitted to the server for this sync (full uploads plus
+   * delta patches, before transport compression). In watch mode, this reflects
+   * the initial sync only.
+   */
+  bytesSent?: number;
+  /** Present only when watch=true; call to stop watching */
+  stopWatching?: () => Promise<void>;
+};
+
+export type AssetUploadUrls = { signedUploadUrl: string; signedDownloadUrl: string };
+
+/**
+ * Mints presigned upload/download URLs for a named asset via assets.getOrCreate,
+ * wrapping failures with the asset name (and the original error as cause).
+ */
+export function mintAssetUploadUrls(
+  assets: { getOrCreate: (body: { name: string; ttl?: string }) => Promise<AssetUploadUrls> },
+  name: string,
+  ttl?: string,
+): Promise<AssetUploadUrls> {
+  return assets.getOrCreate({ name, ...(ttl && { ttl }) }).catch((err) => {
+    const message = `Failed to create upload URL for asset '${name}': ${
+      err instanceof Error ? err.message : err
+    }`;
+    // @ts-ignore - not all envs have native support for cause yet
+    throw new Error(message, { cause: err });
+  });
+}
+
+const logLevels: LogLevel[] = ['none', 'error', 'warn', 'info', 'debug'];
+
+export function createDaemonLogger(prefix: string, logLevel: LogLevel) {
+  const threshold = logLevels.indexOf(logLevel);
+  const shouldLog = (level: LogLevel) => threshold >= logLevels.indexOf(level);
+  return (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
+    if (!shouldLog(level)) return;
+    if (level === 'error' || level === 'warn') {
+      console[level](prefix, msg);
+    } else {
+      console.log(prefix, msg);
+    }
+  };
+}

package/src/resources/gradle-instances-helpers.ts

@@ -0,0 +1,155 @@
+import { GradleInstances as GeneratedGradleInstances, type GradleInstance } from './gradle-instances';
+import {
+  exec,
+  type ExecChildProcess,
+  type GradleBuildExecRequest,
+  type GradleReactNativeConfig,
+} from '../exec-client';
+import { syncFolder as syncFolderImpl, type FolderSyncOptions } from '../folder-sync';
+import { createIgnoreFn } from '../folder-sync-ignore';
+import {
+  createDaemonLogger,
+  deriveBasisCache,
+  mintAssetUploadUrls,
+  type LogLevel,
+  type SyncResult,
+} from './daemon-client-shared';
+
+export type GradleCreateClientParams = { logLevel?: LogLevel } & (
+  | { instance: GradleInstance }
+  | { apiUrl: string; token: string }
+);
+
+export type GradleSyncOptions = {
+  /**
+   * Directory for the client-side folder-sync cache.
+   * Defaults to a temporary directory under the OS temp directory.
+   */
+  basisCacheDir?: string;
+  /**
+   * Optional predicate for ignoring files and directories during sync.
+   * Called with the relative path from the sync root (using forward slashes).
+   * For directories, the path ends with '/'.
+   * Return true to ignore, false to keep.
+   */
+  ignore?: (relativePath: string) => boolean;
+  /**
+   * Optional predicate for force-including paths that would otherwise be
+   * dropped. Same calling convention as `ignore`; return true to force-sync.
+   */
+  include?: (relativePath: string) => boolean;
+};
+
+export type GradleBuildOptions = {
+  /** Gradle tasks to run. Omit for the server default (assembleDebug). */
+  tasks?: string[];
+  /** Relative path to the Gradle root when auto-discovery is ambiguous. */
+  projectPath?: string;
+  /** Upload the built APK as a named org asset, or to a presigned URL. */
+  upload?: { assetName: string; signedUploadUrl?: never } | { signedUploadUrl: string; assetName?: never };
+  /** React Native / Expo tuning. */
+  reactNative?: GradleReactNativeConfig;
+};
+
+export type GradleClient = {
+  sync(localCodePath: string, opts?: GradleSyncOptions): Promise<SyncResult>;
+  gradlebuild(options?: GradleBuildOptions): ExecChildProcess;
+};
+
+// Machine-local or regenerable files that must never reach the build
+// sandbox: local.properties points at the developer's own SDK and would
+// shadow the image's. Only ROOT-level cache/output dirs are defaulted;
+// nested module build/ dirs are the project .gitignore's job (dropping any
+// 'build' segment would silently exclude legitimate packages named build).
+function gradleDefaultIgnore(relativePath: string): boolean {
+  const trimmed = relativePath.endsWith('/') ? relativePath.slice(0, -1) : relativePath;
+  const segments = trimmed.split('/');
+  if (segments[segments.length - 1] === 'local.properties') {
+    return true;
+  }
+  return segments.length === 1 && (trimmed === '.gradle' || trimmed === '.kotlin' || trimmed === 'build');
+}
+
+export class GradleInstances extends GeneratedGradleInstances {
+  async createClient(params: GradleCreateClientParams): Promise<GradleClient> {
+    let apiUrl: string;
+    let token: string;
+    if ('instance' in params) {
+      if (!params.instance.status.apiUrl) {
+        throw new Error('Instance not ready: apiUrl is not available');
+      }
+      apiUrl = params.instance.status.apiUrl;
+      token = params.instance.status.token;
+    } else {
+      apiUrl = params.apiUrl;
+      token = params.token;
+    }
+
+    const log = createDaemonLogger('[GradleInstance]', params.logLevel ?? 'info');
+    const client = this._client;
+
+    return {
+      async sync(localCodePath: string, opts?: GradleSyncOptions): Promise<SyncResult> {
+        const { cacheKey, basisCacheDir } = deriveBasisCache(localCodePath, opts?.basisCacheDir);
+        const userIgnore = opts?.ignore;
+        const codeSyncOpts: FolderSyncOptions = {
+          apiUrl,
+          token,
+          udid: cacheKey,
+          install: false,
+          ignoreFn: await createIgnoreFn(localCodePath, {
+            basisCacheDir,
+            log,
+            xcodeDefaults: false,
+            // Honor nested module .gitignore files (app/.gitignore's /build,
+            // etc.); gradleDefaultIgnore only covers root-level build/.gradle/
+            // .kotlin, so without this a locally-built project would sync its
+            // nested build/ artifact trees.
+            nestedGitignore: true,
+            additional: userIgnore ? (p) => gradleDefaultIgnore(p) || userIgnore(p) : gradleDefaultIgnore,
+            ...(opts?.include ? { include: opts.include } : {}),
+          }),
+          basisCacheDir,
+          // Gradle builds are one-shot; no dev-loop watch like xcode.
+          watch: false,
+          launchMode: 'ForegroundIfRunning',
+          log,
+          syncSymlinks: true,
+        };
+
+        const result = await syncFolderImpl(localCodePath, codeSyncOpts);
+        const out: SyncResult = {};
+        if (result.bytesSent !== undefined) {
+          out.bytesSent = result.bytesSent;
+        }
+        return out;
+      },
+
+      gradlebuild(options?: GradleBuildOptions): ExecChildProcess {
+        const request: GradleBuildExecRequest = {
+          command: 'gradlebuild',
+          ...(options?.tasks?.length && { tasks: options.tasks }),
+          ...(options?.projectPath && { projectPath: options.projectPath }),
+          ...(options?.reactNative && { reactNative: options.reactNative }),
+        };
+
+        if (options?.upload && 'assetName' in options.upload) {
+          const requestPromise = mintAssetUploadUrls(client.assets, options.upload.assetName).then(
+            (asset) => {
+              request.signedUploadUrl = asset.signedUploadUrl;
+              request.additionalMetadata = { signedDownloadUrl: asset.signedDownloadUrl };
+              return request;
+            },
+          );
+          return exec(requestPromise, { apiUrl, token, log });
+        }
+
+        if (options?.upload && 'signedUploadUrl' in options.upload) {
+          request.signedUploadUrl = options.upload.signedUploadUrl;
+        }
+
+        return exec(request, { apiUrl, token, log });
+      },
+    };
+  }
+}

package/src/resources/gradle-instances.ts

@@ -0,0 +1,206 @@
+// Hand-written following the Stainless resource pattern; a future generation
+// from the OpenAPI spec reconciles with this file.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { Items, type ItemsParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class GradleInstances extends APIResource {
+  /**
+   * Create a gradle instance
+   */
+  create(params: GradleInstanceCreateParams, options?: RequestOptions): APIPromise<GradleInstance> {
+    const { reuseIfExists, wait, ...body } = params;
+    return this._client.post('/v1/gradle_instances', { query: { reuseIfExists, wait }, body, ...options });
+  }
+
+  /**
+   * List gradle instances
+   */
+  list(
+    query: GradleInstanceListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<GradleInstancesItems, GradleInstance> {
+    return this._client.getAPIList('/v1/gradle_instances', Items<GradleInstance>, { query, ...options });
+  }
+
+  /**
+   * Delete gradle instance with given name
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/gradle_instances/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Get gradle instance with given ID
+   */
+  get(id: string, options?: RequestOptions): APIPromise<GradleInstance> {
+    return this._client.get(path`/v1/gradle_instances/${id}`, options);
+  }
+}
+
+export type GradleInstancesItems = Items<GradleInstance>;
+
+export interface GradleInstance {
+  metadata: GradleInstance.Metadata;
+
+  spec: GradleInstance.Spec;
+
+  status: GradleInstance.Status;
+}
+
+export namespace GradleInstance {
+  export interface Metadata {
+    id: string;
+
+    createdAt: string;
+
+    organizationId: string;
+
+    displayName?: string;
+
+    labels?: { [key: string]: string };
+
+    terminatedAt?: string;
+  }
+
+  export interface Spec {
+    inactivityTimeout: string;
+
+    region: string;
+
+    hardTimeout?: string;
+  }
+
+  export interface Status {
+    token: string;
+
+    state: 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated';
+
+    apiUrl?: string;
+
+    errorMessage?: string;
+
+    /**
+     * Machine-readable reason the instance was terminated. Always present once state
+     * is "terminated", never present before that. New values may be added over time,
+     * so treat any unrecognized value as "Unknown". Known values:
+     *
+     * - "UserRequested": terminated by a delete request to the API.
+     * - "InactivityTimeout": the timeout given in spec.inactivityTimeout elapsed.
+     * - "HardTimeout": the timeout given in spec.hardTimeout elapsed.
+     * - "Unknown": terminated for a cause the platform did not attribute, including
+     *   instances that failed to get ready during creation. See errorMessage for
+     *   details when available.
+     */
+    terminationReason?: string;
+  }
+}
+
+export interface GradleInstanceCreateParams {
+  /**
+   * Query param: If there is another instance with given labels and region, return
+   * that one instead of creating a new instance.
+   */
+  reuseIfExists?: boolean;
+
+  /**
+   * Query param: Return after the instance is ready to connect.
+   */
+  wait?: boolean;
+
+  /**
+   * Body param
+   */
+  metadata?: GradleInstanceCreateParams.Metadata;
+
+  /**
+   * Body param
+   */
+  spec?: GradleInstanceCreateParams.Spec;
+}
+
+export namespace GradleInstanceCreateParams {
+  export interface Metadata {
+    displayName?: string;
+
+    labels?: { [key: string]: string };
+  }
+
+  export interface Spec {
+    clues?: Array<Spec.Clue>;
+
+    /**
+     * After how many minutes should the instance be terminated. Example values 1m,
+     * 10m, 3h. Default is "0" which means no hard timeout.
+     */
+    hardTimeout?: string;
+
+    /**
+     * After how many minutes of inactivity should the instance be terminated. Example
+     * values 1m, 10m, 3h. Default is 5m.
+     */
+    inactivityTimeout?: string;
+
+    /**
+     * Where the instance will be created. If not given, the region is decided based on
+     * scheduling clues (client IP) and availability.
+     *
+     * A region is a preference, not a hard pin: the request always overflows to every
+     * other available region, ordered by proximity, when the preferred ones are full.
+     *
+     * Accepted values:
+     *
+     * - A specific region name (e.g. "us-west1"). It is tried first, then the
+     *   remaining regions in order of proximity to it. Scheduling clues (client IP)
+     *   are ignored when a region is given.
+     * - A region group name (e.g. "us", "eu"). Its member regions are tried first in
+     *   their listed order, then the remaining regions by proximity to the first
+     *   member.
+     * - A pipe-separated, ordered list of regions (e.g. "us-east1|us-west1"). Those
+     *   are tried first in the given order, then the remaining regions by proximity to
+     *   the first.
+     */
+    region?: string;
+  }
+
+  export namespace Spec {
+    export interface Clue {
+      kind: 'ClientIP';
+
+      clientIp?: string;
+    }
+  }
+}
+
+export interface GradleInstanceListParams extends ItemsParams {
+  /**
+   * Labels filter to apply to instances to return. Expects a comma-separated list of
+   * key=value pairs (e.g., env=prod,region=us-west).
+   */
+  labelSelector?: string;
+
+  /**
+   * State filter to apply to gradle instances to return. Each comma-separated state
+   * will be used as part of an OR clause, e.g. "assigned,ready" will return all
+   * instances that are either assigned or ready.
+   *
+   * Valid states: creating, assigned, ready, terminated, unknown
+   */
+  state?: string;
+}
+
+export declare namespace GradleInstances {
+  export {
+    type GradleInstance as GradleInstance,
+    type GradleInstancesItems as GradleInstancesItems,
+    type GradleInstanceCreateParams as GradleInstanceCreateParams,
+    type GradleInstanceListParams as GradleInstanceListParams,
+  };
+}