@limrun/api 0.65.1 → 0.67.0

package/resources/xcode-instances.d.ts

@@ -94,6 +94,11 @@ export declare namespace XcodeInstanceCreateParams {
         };
     }
     interface Spec {
+        /** Inline instance role. Omit for the organization's compatibility default. */
+        role?: {
+            /** Asset permissions delegated by the creator. An empty array grants nothing. */
+            permissions: Array<string>;
+        };
         /**
          * ClientLocation takes precedence over ClientIP regardless of clue order. Without
          * either clue, routing uses Cloudflare visitor coordinates, then its client IP.

package/resources/xcode-instances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xcode-instances.d.ts","sourceRoot":"","sources":["../src/resources/xcode-instances.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xcode-instances.d.ts","sourceRoot":"","sources":["../src/resources/xcode-instances.ts"],"names":[],"mappings":"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"}

package/src/client.ts

@@ -1,3 +1,4 @@
+import { WorkloadCredentials } from './lib/workload-credentials';
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
@@ -57,6 +58,7 @@ import {
 } from './resources/ios-instances';
 import { IosInstances } from './resources/ios-instances-helpers';
 import { SessionArtifact } from './resources/session-artifacts';
+import { AccessToken, AccessTokenCreateParams, AccessTokens } from './resources/access-tokens';
 import { ScopedToken, ScopedTokenCreateParams, ScopedTokens } from './resources/scoped-tokens';
 import {
   XcodeInstance,
@@ -99,6 +101,8 @@ import {
 import { isEmptyObj } from './internal/utils/values';
 
 export interface ClientOptions {
+  /** Projected workload JWT file. Defaults to LIMRUN_WORKLOAD_IDENTITY_TOKEN_FILE. Null disables discovery. */
+  workloadTokenFile?: string | null;
   /**
    * Defaults to process.env['LIM_API_KEY'].
    */
@@ -193,6 +197,7 @@ export class Limrun {
   fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
+  private workloadCredentials?: WorkloadCredentials;
   #encoder: Opts.RequestEncoder;
   protected idempotencyHeader?: string;
   private _options: ClientOptions;
@@ -215,10 +220,15 @@ export class Limrun {
     apiKey = readEnv('LIM_API_KEY') ?? null,
     ...opts
   }: ClientOptions = {}) {
+    const tokenFile =
+      opts.workloadTokenFile === null ?
+        undefined
+      : opts.workloadTokenFile ?? readEnv('LIMRUN_WORKLOAD_IDENTITY_TOKEN_FILE');
     const options: ClientOptions = {
       apiKey,
       ...opts,
-      baseURL: baseURL || `https://api.limrun.com`,
+      baseURL:
+        baseURL || (!apiKey && tokenFile ? readEnv('DIRECTOR_URL') : undefined) || `https://api.limrun.com`,
     };
 
     this.baseURL = options.baseURL!;
@@ -251,6 +261,13 @@ export class Limrun {
     this._options = options;
 
     this.apiKey = apiKey;
+    if (!apiKey && tokenFile)
+      this.workloadCredentials = new WorkloadCredentials(
+        this.baseURL,
+        tokenFile,
+        this.fetch,
+        this.fetchOptions,
+      );
   }
 
   /**
@@ -284,7 +301,7 @@ export class Limrun {
   }
 
   protected validateHeaders({ values, nulls }: NullableHeaders) {
-    if (this.apiKey && values.get('authorization')) {
+    if ((this.apiKey || this.workloadCredentials) && values.get('authorization')) {
       return;
     }
     if (nulls.has('authorization')) {
@@ -298,6 +315,10 @@ export class Limrun {
 
   protected async authHeaders(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
     if (this.apiKey == null) {
+      const explicit = buildHeaders([this._options.defaultHeaders, opts.headers]);
+      if (explicit.values.has('authorization') || explicit.nulls.has('authorization')) return undefined;
+      if (this.workloadCredentials)
+        return buildHeaders([{ Authorization: `Bearer ${await this.workloadCredentials.get()}` }]);
       return undefined;
     }
     return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
@@ -850,6 +871,8 @@ export class Limrun {
   xcodeInstances: API.XcodeInstances = new API.XcodeInstances(this);
   gradleInstances: API.GradleInstances = new API.GradleInstances(this);
   analytics: API.Analytics = new API.Analytics(this);
+  accessTokens: API.AccessTokens = new API.AccessTokens(this);
+  /** @deprecated Use accessTokens. */
   scopedTokens: API.ScopedTokens = new API.ScopedTokens(this);
 }
 
@@ -859,6 +882,7 @@ Limrun.IosInstances = IosInstances;
 Limrun.XcodeInstances = XcodeInstances;
 Limrun.GradleInstances = GradleInstances;
 Limrun.Analytics = Analytics;
+Limrun.AccessTokens = AccessTokens;
 Limrun.ScopedTokens = ScopedTokens;
 
 export declare namespace Limrun {
@@ -939,6 +963,9 @@ export declare namespace Limrun {
   };
 
   export {
+    AccessTokens as AccessTokens,
+    type AccessToken as AccessToken,
+    type AccessTokenCreateParams as AccessTokenCreateParams,
     ScopedTokens as ScopedTokens,
     type ScopedToken as ScopedToken,
     type ScopedTokenCreateParams as ScopedTokenCreateParams,

package/src/exec-client.ts

@@ -1,3 +1,4 @@
+import type { AssetUpload } from './lib/asset-permissions';
 /**
  * Client for executing commands on limbuild server with streaming output.
  *
@@ -111,6 +112,7 @@ export type XcodeBuildExecRequest = {
   gitInit?: boolean;
   /** How xcodebuild stdout is processed before streaming. Defaults to 'xcbeautify'. */
   logProcessor?: 'xcbeautify' | 'none';
+  assetUpload?: AssetUpload;
   signedUploadUrl?: string;
   /**
    * ID of the Limrun asset signedUploadUrl targets, when it was minted from
@@ -208,6 +210,7 @@ export type GradleBuildExecRequest = {
   reactNative?: GradleReactNativeConfig;
   signing?: GradleSigningConfig;
   playstore?: GradlePlaystoreConfig;
+  assetUpload?: AssetUpload;
   signedUploadUrl?: string;
   webhook?: WebhookConfig;
   additionalMetadata?: {

package/src/index.ts

@@ -226,3 +226,5 @@ export {
   UnprocessableEntityError,
 } from './core/error';
 export { isDirectInstanceHttpError, type DirectInstanceHttpError } from './internal/direct-instance-errors';
+
+export { type AssetUpload, type BuildUpload } from './lib/asset-permissions';

package/src/ios-client.ts

@@ -476,19 +476,77 @@ export type AppExitInfo = {
  */
 export type LaunchAppExitCallback = (logs: string[], info: AppExitInfo) => Promise<void> | void;
 
-/** Handle for an app watch registered via {@link InstanceClient.watchApp}. */
+/** Handle for a watch registered via {@link InstanceClient.monitorApp} or {@link InstanceClient.watchApp}. */
 export type AppWatch = {
   /** Identifier of this watch on the server. */
   execId: string;
-  /** Cancels the watch; the onExit callback will not be invoked afterwards. */
+  /** Cancels the watch; its callbacks will not be invoked afterwards. */
   stop: () => Promise<void>;
 };
 
+/** What {@link InstanceClient.monitorApp} reports. Pass either callback or both. */
+export type AppMonitorCallbacks = {
+  /** Called at every exit of any process of the app. Monitored apps report no logs. */
+  onExit?: LaunchAppExitCallback;
+  /** Called for each sample of a main-thread hang and once at its end. */
+  onHang?: AppHangCallback;
+};
+
+/**
+ * A sample of an app's main-thread hang, or the hang's end. The main thread is hung once it has
+ * not answered for 1 second. The simulator samples a hang 1, 3, 6 and 10 seconds in, then reports
+ * once more when the main thread answers or the app exits.
+ */
+export type AppHangInfo = {
+  bundleId: string;
+  pid: number;
+  /** Numbers the process's hangs from 1. A hang's samples and its end share it. */
+  hangId: number;
+  /** `false` for a sample while the main thread is still hung, `true` once it answered or the app exited. */
+  ended: boolean;
+  /** The hang's age at this sample, or its whole length at the end. */
+  durationMs: number;
+  /**
+   * The main thread's run state at the sample: `running`, `waiting`, `uninterruptible`, `stopped`
+   * or `halted`. This and the fields below come with samples only, each left out when the app
+   * could not read it.
+   */
+  mainThreadState?: string;
+  /**
+   * CPU time the main thread used during the hang. Close to `durationMs` while `running` means the
+   * app kept its main thread busy; near zero while `waiting` means it waited, and `stackTrace`
+   * shows on what.
+   */
+  mainThreadCpuMs?: number;
+  /** The part of `mainThreadCpuMs` spent in the kernel, for example reading compressed memory back. */
+  mainThreadKernelMs?: number;
+  /** CPU time all of the app's threads used during the hang. */
+  appCpuMs?: number;
+  /** Pages the app read in from disk during the hang. */
+  pageIns?: number;
+  /** The app's memory footprint at the sample. */
+  footprintBytes?: number;
+  /**
+   * The main thread's frames, with symbol names for the app's own code, followed by the binary
+   * images they belong to, laid out like {@link AppCrashInfo.stackTrace}.
+   */
+  stackTrace?: string;
+};
+
+/** Called for each sample of a hang and once at its end. */
+export type AppHangCallback = (info: AppHangInfo) => Promise<void> | void;
+
 type LaunchAppCommonOptions = {
   /** App environment variables. Requires relaunch; reserved keys and existing launch variables are ignored. */
   env?: Record<string, string>;
   /** Called once when the launched app exits, crashes, or is terminated. */
   onExit?: LaunchAppExitCallback;
+  /**
+   * Called for each sample of the launched process's main-thread hangs and once at each hang's
+   * end, until that process exits. Simulators that predate hang reports launch the app without
+   * them. See {@link InstanceClient.monitorApp}.
+   */
+  onHang?: AppHangCallback;
 };
 
 type StandardLaunchAppOptions = LaunchAppCommonOptions & {
@@ -804,6 +862,9 @@ export type InstanceClient = {
    * exit reason and crash details, the next time any process of the app exits. Watched apps
    * report no logs.
    *
+   * @deprecated Use {@link monitorApp}, which reports every exit and hang of the app until you
+   * stop it, including after relaunches. `watchApp` reports only the next exit and will be removed.
+   *
    * The app does not need to be running yet: if it starts later, it is picked up automatically.
    *
    * @param bundleId Bundle identifier of the app to watch
@@ -812,6 +873,23 @@ export type InstanceClient = {
    */
   watchApp: (bundleId: string, onExit: LaunchAppExitCallback) => Promise<AppWatch>;
 
+  /**
+   * Monitor an app without launching it through {@link launchApp}, for example an app a test
+   * runner relaunches or one opened with {@link openUrl}. `onExit` fires at every exit of any
+   * process of the app, with the reason and crash details. `onHang` fires for each sample of a
+   * main-thread hang (no answer for 1 second or more) and once at its end. The monitor outlives
+   * exits and relaunches until you stop it, and the app does not need to be running yet.
+   *
+   * Each app process reports at most 100 hangs. A simulator keeps its 8 newest monitors, so
+   * starting a ninth silently ends the oldest. Simulators that predate monitors reject the call
+   * after 10 seconds.
+   *
+   * @param bundleId Bundle identifier of the app to monitor
+   * @param callbacks `onExit`, `onHang`, or both
+   * @returns A handle whose `stop()` ends the monitor
+   */
+  monitorApp: (bundleId: string, callbacks: AppMonitorCallbacks) => Promise<AppWatch>;
+
   /**
    * Fetch the last N lines of app logs (combined stdout/stderr)
    * @param bundleId Bundle identifier of the app
@@ -1447,6 +1525,14 @@ type AppExitMessage = {
   logLineCount?: number;
 };
 
+/** appHang as the server sends it. */
+type AppHangMessage = {
+  type: 'appHang';
+  execId: string;
+  bundleId: string;
+  hang: Omit<AppHangInfo, 'bundleId'>;
+};
+
 type ServerResponse = {
   recordingId?: string;
   state?: FoldState;
@@ -1693,8 +1779,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
   const simctlExecutions: Map<string, SimctlExecution> = new Map();
 
   // Server notifications are keyed by notification type and that type's
-  // identifier field. They intentionally survive transient WebSocket reconnects
-  // and are one-shot once a matching notification is processed.
+  // identifier field. They intentionally survive transient WebSocket reconnects.
+  // appExit handlers are one-shot; appHang handlers stay until their watch stops.
   type ServerNotificationHandler = (message: ServerResponse) => Promise<void>;
   const serverNotifications: Map<string, Map<string, ServerNotificationHandler>> = new Map();
 
@@ -1811,6 +1897,11 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     return handler;
   };
 
+  const getServerNotification = (
+    type: string,
+    notificationId: string,
+  ): ServerNotificationHandler | undefined => serverNotifications.get(type)?.get(notificationId);
+
   const deleteServerNotification = (type: string, notificationId: string): void => {
     const handlers = serverNotifications.get(type);
     if (!handlers) {
@@ -1943,7 +2034,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         return true;
       }
 
-      const notification = takeServerNotification('appExit', execId);
+      // Launches and watchApp end at the exit; monitors keep their handler until stopped.
+      const notification =
+        takeServerNotification('appExit', execId) ?? getServerNotification('monitorExit', execId);
       if (!notification) {
         logger.debug(`Received appExit for unknown or already handled execId: ${execId}`);
         return true;
@@ -1956,6 +2049,26 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return true;
     };
 
+    const handleAppHang = (message: ServerResponse): boolean => {
+      if (message.type !== 'appHang') {
+        return false;
+      }
+      const { execId, bundleId, hang } = message as unknown as AppHangMessage;
+      if (typeof execId !== 'string' || typeof bundleId !== 'string' || typeof hang !== 'object' || !hang) {
+        logger.warn('Received malformed appHang message:', message);
+        return true;
+      }
+      const notification = getServerNotification('appHang', execId);
+      if (!notification) {
+        logger.debug(`Received appHang for unknown or stopped execId: ${execId}`);
+        return true;
+      }
+      void notification(message).catch((error) => {
+        logger.error(`Error processing appHang notification for execId ${execId}:`, error);
+      });
+      return true;
+    };
+
     // Response handlers - transform raw responses to typed results
     const responseHandlers: Record<string, (msg: ServerResponse) => unknown> = {
       screenshotResult: (msg) => ({
@@ -1979,6 +2092,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       launchAppResult: () => undefined,
       terminateAppResult: () => undefined,
       watchAppResult: () => undefined,
+      monitorAppResult: () => undefined,
       unwatchAppResult: () => undefined,
       appLogTailResult: (msg) => msg.logs ?? '',
       listAppsResult: (msg) => JSON.parse(msg.apps || '[]') as InstalledApp[],
@@ -2048,7 +2162,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
           return;
         }
 
-        if (handleAppExit(message)) {
+        if (handleAppExit(message) || handleAppHang(message)) {
           return;
         }
 
@@ -2190,6 +2304,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             launchApp,
             terminateApp,
             watchApp,
+            monitorApp,
             appLogTail,
             streamAppLog,
             streamSyslog,
@@ -2416,7 +2531,10 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<void>('toggleKeyboard');
     };
 
-    const launchApp = (bundleId: string, modeOrOptions?: LaunchAppMode | LaunchAppOptions): Promise<void> => {
+    const launchApp = async (
+      bundleId: string,
+      modeOrOptions?: LaunchAppMode | LaunchAppOptions,
+    ): Promise<void> => {
       const launchOptions: LaunchAppOptions =
         typeof modeOrOptions === 'string' ? { mode: modeOrOptions } : modeOrOptions ?? {};
       const requestedMode =
@@ -2424,8 +2542,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
           (modeOrOptions as { mode?: LaunchAppMode }).mode
         : launchOptions.mode;
       if (launchOptions.runtime && requestedMode === 'ForegroundIfRunning') {
-        return Promise.reject(
-          new Error('launchApp runtime launches require RelaunchIfRunning so runtime injection is applied.'),
+        throw new Error(
+          'launchApp runtime launches require RelaunchIfRunning so runtime injection is applied.',
         );
       }
       const hasEnvironment = Object.keys(launchOptions.env ?? {}).length > 0;
@@ -2433,23 +2551,34 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         launchOptions.runtime ? 'RelaunchIfRunning' : (
           launchOptions.mode ?? (hasEnvironment ? 'RelaunchIfRunning' : undefined)
         );
-      const onExit = launchOptions.onExit;
-      const execId = onExit ? generateId() : undefined;
-      if (execId && onExit) {
-        registerServerNotification('appExit', execId, appExitHandler(execId, onExit));
+      const { onExit, onHang } = launchOptions;
+      const execId = onExit || onHang ? generateId() : undefined;
+      if (execId) {
+        const exitHandler = onExit ? appExitHandler(execId, onExit) : undefined;
+        if (onHang) registerServerNotification('appHang', execId, appHangHandler(execId, onHang));
+        // The launch's hang reports end with its exit.
+        registerServerNotification('appExit', execId, async (message) => {
+          deleteServerNotification('appHang', execId);
+          await exitHandler?.(message);
+        });
       }
-      return sendRequest<void>('launchApp', {
-        bundleId,
-        mode,
-        runtime: launchOptions.runtime,
-        env: launchOptions.env,
-        execId,
-      }).catch((error) => {
+      try {
+        await sendRequest<void>('launchApp', {
+          bundleId,
+          mode,
+          runtime: launchOptions.runtime,
+          env: launchOptions.env,
+          execId,
+          // Sent only with onHang so other launches stay byte-identical.
+          hangs: onHang ? true : undefined,
+        });
+      } catch (error) {
         if (execId) {
           deleteServerNotification('appExit', execId);
+          deleteServerNotification('appHang', execId);
         }
         throw error;
-      });
+      }
     };
 
     /** Delivers one appExit to the callback, fetching the logs from servers that predate inline logs. */
@@ -2503,6 +2632,45 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       };
     };
 
+    /** Delivers each appHang of a launch or hang watch to the callback. */
+    const appHangHandler =
+      (execId: string, onHang: AppHangCallback): ServerNotificationHandler =>
+      async (response) => {
+        const { hang, bundleId } = response as unknown as AppHangMessage;
+        try {
+          await onHang({ ...hang, bundleId });
+        } catch (error) {
+          logger.error(`Error in onHang callback for execId ${execId}:`, error);
+        }
+      };
+
+    const monitorApp = async (
+      bundleId: string,
+      { onExit, onHang }: AppMonitorCallbacks,
+    ): Promise<AppWatch> => {
+      const execId = generateId();
+      const forget = () => {
+        deleteServerNotification('monitorExit', execId);
+        deleteServerNotification('appHang', execId);
+      };
+      if (onExit) registerServerNotification('monitorExit', execId, appExitHandler(execId, onExit));
+      if (onHang) registerServerNotification('appHang', execId, appHangHandler(execId, onHang));
+      try {
+        // Simulators that predate monitors never answer, so the wait stays short.
+        await sendRequest<void>('monitorApp', { bundleId, execId }, undefined, 10_000);
+      } catch (error) {
+        forget();
+        throw error;
+      }
+      return {
+        execId,
+        stop: async () => {
+          forget();
+          await sendRequest<void>('unwatchApp', { execId });
+        },
+      };
+    };
+
     const terminateApp = (bundleId: string): Promise<void> => {
       return sendRequest<void>('terminateApp', { bundleId });
     };

package/src/lib/asset-permissions.ts

@@ -0,0 +1,67 @@
+/** Uploaded by the daemon after the build, using fresh workload credentials unless token is supplied. */
+export interface AssetUpload {
+  target: string;
+  token?: string;
+  /** Asset expiry as a Go duration. Build uploads default to 336h. */
+  ttl?: string;
+  /** Metadata applied before the upload. Requires update permission. */
+  uploadOptions?: AssetUploadMetadata;
+}
+
+export interface AssetUploadMetadata {
+  displayName?: string;
+  bundleIdentifier?: string;
+  shortVersion?: string;
+  buildVersion?: string;
+  deeplink?: string;
+}
+
+export type BuildUpload =
+  | (AssetUpload & { assetName?: never; signedUploadUrl?: never })
+  | {
+      signedUploadUrl: string;
+      target?: never;
+      assetName?: never;
+      ttl?: never;
+      token?: never;
+      uploadOptions?: never;
+    }
+  | {
+      /** @deprecated Use a literal target such as "name/result.apk". Authorization now happens in the workload. */
+      assetName: string;
+      ttl?: string;
+      uploadOptions?: AssetUploadMetadata;
+      target?: never;
+      signedUploadUrl?: never;
+      token?: never;
+    };
+
+export const DEFAULT_BUILD_ASSET_TTL = '336h';
+
+/** Normalize compatibility names without requesting an asset URL on the client. */
+export function normalizeAssetUpload(
+  upload: BuildUpload,
+): { assetUpload: AssetUpload; signedUploadUrl?: never } | { signedUploadUrl: string; assetUpload?: never } {
+  const modes = [upload.target, upload.assetName, upload.signedUploadUrl].filter((v) => v !== undefined);
+  if (modes.length !== 1) throw new Error('Provide exactly one upload target or signedUploadUrl');
+  if (upload.signedUploadUrl !== undefined) {
+    if (!upload.signedUploadUrl) throw new Error('signedUploadUrl must not be empty');
+    return { signedUploadUrl: upload.signedUploadUrl };
+  }
+  if (upload.assetName === '') throw new Error('assetName must not be empty');
+  const target = upload.target ?? `name/${upload.assetName!}`;
+  if (target.startsWith('name/')) {
+    if (target === 'name/') throw new Error('Name targets must include an exact name after name/');
+  } else if (!/^asset_[0-7][0-9a-hjkmnp-tv-z]{25}$/.test(target)) {
+    throw new Error('Upload target must be an asset ID or an exact name target');
+  }
+  if (upload.token !== undefined && !upload.token.trim()) throw new Error('Upload token must not be empty');
+  return {
+    assetUpload: {
+      target,
+      ttl: upload.ttl || DEFAULT_BUILD_ASSET_TTL,
+      ...(upload.token !== undefined && { token: upload.token }),
+      ...(upload.uploadOptions !== undefined && { uploadOptions: upload.uploadOptions }),
+    },
+  };
+}

package/src/lib/workload-credentials.ts

@@ -0,0 +1,44 @@
+import type { MergedRequestInit } from '../internal/types';
+
+/** Refreshes workload credentials without retaining the projected JWT. */
+export class WorkloadCredentials {
+  private cached?: { token: string; expires: number };
+  private pending: Promise<string> | undefined;
+
+  constructor(
+    private endpoint: string,
+    private tokenFile: string,
+    private fetcher: typeof fetch,
+    private fetchOptions?: MergedRequestInit,
+  ) {}
+
+  async get(): Promise<string> {
+    if (this.cached && this.cached.expires - Date.now() > 60_000) return this.cached.token;
+    if (!this.pending)
+      this.pending = this.exchange().finally(() => {
+        this.pending = undefined;
+      });
+    return this.pending;
+  }
+
+  private async exchange(): Promise<string> {
+    const { readFile } = await import('node:fs/promises');
+    const jwt = (await readFile(this.tokenFile, 'utf8')).trim();
+    const response = await this.fetcher(`${this.endpoint.replace(/\/$/, '')}/v1/access_tokens`, {
+      ...(this.fetchOptions as RequestInit),
+      method: 'POST',
+      headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(30_000),
+      redirect: 'error',
+    });
+    if (!response.ok) throw new Error(`Workload token exchange returned HTTP ${response.status}`);
+    const body = (await response.json()) as { token?: string; expiresAt: string };
+    if (!body.token) throw new Error('This instance has no delegated asset permissions');
+    const expires = Date.parse(body.expiresAt);
+    if (!Number.isFinite(expires) || expires <= Date.now())
+      throw new Error('Workload token exchange returned an invalid expiration');
+    this.cached = { token: body.token, expires };
+    return body.token;
+  }
+}

package/src/resources/access-tokens.ts

@@ -0,0 +1,46 @@
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class AccessTokens extends APIResource {
+  /** Mint a temporary credential whose permissions are covered by the caller. */
+  create(body: AccessTokenCreateParams, options?: RequestOptions): APIPromise<AccessToken> {
+    return this._client.post('/v1/access_tokens', { body, ...options });
+  }
+
+  /** Revoke a credential by the ID returned when it was minted. */
+  revoke(id: string, options?: RequestOptions): APIPromise<{ status: string }> {
+    return this._client.delete(`/v1/access_tokens/${encodeURIComponent(id)}`, options);
+  }
+}
+
+export interface AccessToken {
+  id: string;
+  token: string;
+  permissions: Array<string>;
+  /** @deprecated Use permissions. */
+  scopes: Array<string>;
+  expiresAt: string;
+}
+
+export interface AccessTokenCreateParams {
+  /**
+   * Permissions in the form `<resource>:<id|*>:<action>`, e.g. `device:*:install`,
+   * `asset:asset_01h455vb4pex5vsknk084sn02q:read` or `applerelay:*:connect`.
+   * Resource IDs are the customer-visible IDs returned by the API.
+   */
+  permissions?: Array<string>;
+
+  /** @deprecated Use permissions. If both are supplied, their permission sets must match. */
+  scopes?: Array<string>;
+
+  /**
+   * How long the token stays valid. Defaults to 3600 (1 hour), maximum is 14400 (4
+   * hours).
+   */
+  ttlSeconds?: number;
+}
+
+export declare namespace AccessTokens {
+  export { type AccessToken as AccessToken, type AccessTokenCreateParams as AccessTokenCreateParams };
+}

package/src/resources/android-instances.ts

@@ -190,6 +190,12 @@ export namespace AndroidInstanceCreateParams {
   }
 
   export interface Spec {
+    /** Inline instance role. Omit for the organization's compatibility default. */
+    role?: {
+      /** Asset permissions delegated by the creator. An empty array grants nothing. */
+      permissions: Array<string>;
+    };
+
     /**
      * ClientLocation takes precedence over ClientIP regardless of clue order. Without
      * either clue, routing uses Cloudflare visitor coordinates, then its client IP.