// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as BoxesAPI from './boxes';
import {
  BoxCreateParams,
  BoxCreateSnapshotParams,
  BoxDeleteServiceURLParams,
  BoxGenerateDownloadURLParams,
  BoxGenerateServiceURLParams,
  BoxListParams,
  BoxListServiceURLsParams,
  BoxListServiceURLsResponse,
  BoxListServiceURLsResponsesItemsCursorGetPagination,
  BoxUpdateParams,
  Boxes,
} from './boxes';
import * as RegistriesAPI from './registries';
import {
  Registries,
  RegistryCreateParams,
  RegistryListParams,
  RegistryListResponse,
  RegistryResponse,
  RegistryUpdateParams,
} from './registries';
import * as SnapshotsAPI from './snapshots';
import {
  SnapshotCreateParams,
  SnapshotListParams,
  SnapshotRetrieveByNameResponse,
  Snapshots,
} from './snapshots';
import {
  ItemsCursorGetPagination,
  type ItemsCursorGetPaginationParams,
  PagePromise,
} from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';

export class Sandboxes extends APIResource {
  boxes: BoxesAPI.Boxes = new BoxesAPI.Boxes(this._client);
  registries: RegistriesAPI.Registries = new RegistriesAPI.Registries(this._client);
  snapshots: SnapshotsAPI.Snapshots = new SnapshotsAPI.Snapshots(this._client);

  /**
   * Returns priced usage per sandbox or snapshot and UTC hour in the half-open
   * requested interval. LCU uses the recorded compute amount for sandboxes;
   * snapshots have zero LCU. LSU allocates the recorded workspace storage amount
   * proportionally to attributed bytes, including checkpoints on their sandbox and
   * snapshots as separate resources. Resource filters preserve each resource's
   * share. Rate changes do not reprice recorded amounts. An access-filtered page can
   * have no items and a non-null next_cursor; continue until next_cursor is null.
   */
  listUsageCosts(
    query: SandboxListUsageCostsParams,
    options?: RequestOptions,
  ): PagePromise<SandboxListUsageCostsResponsesItemsCursorGetPagination, SandboxListUsageCostsResponse> {
    return this._client.getAPIList(
      '/api/v2/sandboxes/usage/costs',
      ItemsCursorGetPagination<SandboxListUsageCostsResponse>,
      { query, ...options },
    );
  }
}

export type SandboxListUsageCostsResponsesItemsCursorGetPagination =
  ItemsCursorGetPagination<SandboxListUsageCostsResponse>;

export type SandboxResponsesItemsCursorGetPagination = ItemsCursorGetPagination<SandboxResponse>;

export type SnapshotResponsesItemsCursorGetPagination = ItemsCursorGetPagination<SnapshotResponse>;

export interface DownloadURLResponse {
  token: string;

  download_url: string;

  /**
   * ExpiresAt is null for a link that never expires.
   */
  expires_at?: string | null;
}

export interface SandboxListResponse {
  /**
   * This page of sandboxes.
   */
  items?: Array<SandboxResponse>;

  /**
   * Cursor for the next page, or null on the last page. A non-null value is the only
   * signal that more pages exist. Treat it as opaque.
   */
  next_cursor?: string;

  /**
   * Deprecated: use next_cursor. Offset to request for the next page, or 0 when no
   * pages remain.
   */
  offset?: number;

  /**
   * Deprecated: use items. Duplicates items.
   */
  sandboxes?: Array<SandboxResponse>;
}

export interface SandboxResponse {
  id?: string;

  /**
   * AccessDelegation is the LangSmith access this sandbox was granted, absent when
   * it has none. It is reported exactly as it was requested at create.
   */
  access_delegation?: SandboxResponse.AccessDelegation;

  cpu_millicores?: number;

  created_at?: string;

  created_by?: string;

  dataplane_url?: string;

  delete_after_stop_seconds?: number;

  fs_capacity_bytes?: number;

  idle_ttl_seconds?: number;

  labels?: { [key: string]: string };

  mem_bytes?: number;

  mount_config?: SandboxResponse.MountConfig;

  name?: string;

  preserve_memory_on_stop?: boolean;

  proxy_config?: SandboxResponse.ProxyConfig;

  /**
   * RunConfig is what the sandbox's commands run with: the user, working directory
   * and base env beneath env_vars.
   */
  run_config?: SandboxResponse.RunConfig;

  size_class?: string;

  snapshot_id?: string;

  status?: string;

  status_message?: string;

  stopped_at?: string;

  updated_at?: string;

  updated_by?: string;

  vcpus?: number;
}

export namespace SandboxResponse {
  /**
   * AccessDelegation is the LangSmith access this sandbox was granted, absent when
   * it has none. It is reported exactly as it was requested at create.
   */
  export interface AccessDelegation {
    mode: 'INHERIT' | 'EXPLICIT';

    permissions?: Array<string>;
  }

  export interface MountConfig {
    auth?: MountConfig.Auth;

    mounts?: Array<
      | MountConfig.SandboxapiS3BucketMountSpec
      | MountConfig.SandboxapiGcsBucketMountSpec
      | MountConfig.SandboxapiGitRepoMountSpec
      | MountConfig.SandboxapiContextHubRepoMountSpec
    >;
  }

  export namespace MountConfig {
    export interface Auth {
      aws?: Auth.SandboxesSandboxAwsMountRoleAuthConfig | Auth.SandboxesSandboxAwsMountStaticAuthConfig;

      gcp?: Auth.Gcp;
    }

    export namespace Auth {
      export interface SandboxesSandboxAwsMountRoleAuthConfig {
        /**
         * IAM role to assume with permissions scoped to the configured S3 mounts. Mutually
         * exclusive with static credentials. Configure only at creation.
         */
        role_arn: string;
      }

      export interface SandboxesSandboxAwsMountStaticAuthConfig {
        access_key_id: SandboxesSandboxAwsMountStaticAuthConfig.AccessKeyID;

        secret_access_key: SandboxesSandboxAwsMountStaticAuthConfig.SecretAccessKey;

        /**
         * IAM role to assume with permissions scoped to the configured S3 mounts. Mutually
         * exclusive with static credentials. Configure only at creation.
         */
        role_arn?: '';
      }

      export namespace SandboxesSandboxAwsMountStaticAuthConfig {
        export interface AccessKeyID {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }

        export interface SecretAccessKey {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }
      }

      export interface Gcp {
        service_account_json: Gcp.ServiceAccountJson;
      }

      export namespace Gcp {
        export interface ServiceAccountJson {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }
      }
    }

    export interface SandboxapiS3BucketMountSpec {
      id: string;

      mount_path: string;

      s3: SandboxapiS3BucketMountSpec.S3;

      type: 's3' | 'gcs' | 'git' | 'contexthub';

      cache?: SandboxapiS3BucketMountSpec.Cache;

      contexthub?: SandboxapiS3BucketMountSpec.Contexthub;

      encryption?: SandboxapiS3BucketMountSpec.Encryption;

      gcs?: SandboxapiS3BucketMountSpec.Gcs;

      git?: SandboxapiS3BucketMountSpec.Git;

      read_only?: boolean;
    }

    export namespace SandboxapiS3BucketMountSpec {
      export interface S3 {
        bucket: string;

        region: string;

        endpoint_url?: string;

        path_style?: boolean;

        prefix?: string;
      }

      export interface Cache {
        max_size_bytes?: number;

        writeback_seconds?: number;
      }

      export interface Contexthub {
        /**
         * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent",
         * where "-" is the current workspace). The repo's latest commit tree is mirrored
         * into the mount path.
         */
        repo: string;

        /**
         * InitialPullOnly syncs the repo once at startup instead of polling for updates
         * for the sandbox's lifetime.
         */
        initial_pull_only?: boolean;
      }

      export interface Encryption {
        /**
         * KMSKey is the key to encrypt uploads with. S3 mounts take a KMS key ARN in the
         * mount's region.
         */
        kms_key: string;
      }

      export interface Gcs {
        bucket: string;

        prefix?: string;
      }

      export interface Git {
        remote_url: string;

        ref?: Git.Ref;

        refresh_interval_seconds?: number;
      }

      export namespace Git {
        export interface Ref {
          name: string;

          type: 'branch' | 'tag';
        }
      }
    }

    export interface SandboxapiGcsBucketMountSpec {
      id: string;

      gcs: SandboxapiGcsBucketMountSpec.Gcs;

      mount_path: string;

      type: 's3' | 'gcs' | 'git' | 'contexthub';

      cache?: SandboxapiGcsBucketMountSpec.Cache;

      contexthub?: SandboxapiGcsBucketMountSpec.Contexthub;

      encryption?: SandboxapiGcsBucketMountSpec.Encryption;

      git?: SandboxapiGcsBucketMountSpec.Git;

      read_only?: boolean;

      s3?: SandboxapiGcsBucketMountSpec.S3;
    }

    export namespace SandboxapiGcsBucketMountSpec {
      export interface Gcs {
        bucket: string;

        prefix?: string;
      }

      export interface Cache {
        max_size_bytes?: number;

        writeback_seconds?: number;
      }

      export interface Contexthub {
        /**
         * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent",
         * where "-" is the current workspace). The repo's latest commit tree is mirrored
         * into the mount path.
         */
        repo: string;

        /**
         * InitialPullOnly syncs the repo once at startup instead of polling for updates
         * for the sandbox's lifetime.
         */
        initial_pull_only?: boolean;
      }

      export interface Encryption {
        /**
         * KMSKey is the key to encrypt uploads with. S3 mounts take a KMS key ARN in the
         * mount's region.
         */
        kms_key: string;
      }

      export interface Git {
        remote_url: string;

        ref?: Git.Ref;

        refresh_interval_seconds?: number;
      }

      export namespace Git {
        export interface Ref {
          name: string;

          type: 'branch' | 'tag';
        }
      }

      export interface S3 {
        bucket: string;

        region: string;

        endpoint_url?: string;

        path_style?: boolean;

        prefix?: string;
      }
    }

    export interface SandboxapiGitRepoMountSpec {
      id: string;

      git: SandboxapiGitRepoMountSpec.Git;

      mount_path: string;

      type: 's3' | 'gcs' | 'git' | 'contexthub';

      cache?: SandboxapiGitRepoMountSpec.Cache;

      contexthub?: SandboxapiGitRepoMountSpec.Contexthub;

      encryption?: SandboxapiGitRepoMountSpec.Encryption;

      gcs?: SandboxapiGitRepoMountSpec.Gcs;

      read_only?: boolean;

      s3?: SandboxapiGitRepoMountSpec.S3;
    }

    export namespace SandboxapiGitRepoMountSpec {
      export interface Git {
        remote_url: string;

        ref?: Git.Ref;

        refresh_interval_seconds?: number;
      }

      export namespace Git {
        export interface Ref {
          name: string;

          type: 'branch' | 'tag';
        }
      }

      export interface Cache {
        max_size_bytes?: number;

        writeback_seconds?: number;
      }

      export interface Contexthub {
        /**
         * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent",
         * where "-" is the current workspace). The repo's latest commit tree is mirrored
         * into the mount path.
         */
        repo: string;

        /**
         * InitialPullOnly syncs the repo once at startup instead of polling for updates
         * for the sandbox's lifetime.
         */
        initial_pull_only?: boolean;
      }

      export interface Encryption {
        /**
         * KMSKey is the key to encrypt uploads with. S3 mounts take a KMS key ARN in the
         * mount's region.
         */
        kms_key: string;
      }

      export interface Gcs {
        bucket: string;

        prefix?: string;
      }

      export interface S3 {
        bucket: string;

        region: string;

        endpoint_url?: string;

        path_style?: boolean;

        prefix?: string;
      }
    }

    export interface SandboxapiContextHubRepoMountSpec {
      id: string;

      contexthub: SandboxapiContextHubRepoMountSpec.Contexthub;

      mount_path: string;

      type: 's3' | 'gcs' | 'git' | 'contexthub';

      cache?: SandboxapiContextHubRepoMountSpec.Cache;

      encryption?: SandboxapiContextHubRepoMountSpec.Encryption;

      gcs?: SandboxapiContextHubRepoMountSpec.Gcs;

      git?: SandboxapiContextHubRepoMountSpec.Git;

      read_only?: boolean;

      s3?: SandboxapiContextHubRepoMountSpec.S3;
    }

    export namespace SandboxapiContextHubRepoMountSpec {
      export interface Contexthub {
        /**
         * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent",
         * where "-" is the current workspace). The repo's latest commit tree is mirrored
         * into the mount path.
         */
        repo: string;

        /**
         * InitialPullOnly syncs the repo once at startup instead of polling for updates
         * for the sandbox's lifetime.
         */
        initial_pull_only?: boolean;
      }

      export interface Cache {
        max_size_bytes?: number;

        writeback_seconds?: number;
      }

      export interface Encryption {
        /**
         * KMSKey is the key to encrypt uploads with. S3 mounts take a KMS key ARN in the
         * mount's region.
         */
        kms_key: string;
      }

      export interface Gcs {
        bucket: string;

        prefix?: string;
      }

      export interface Git {
        remote_url: string;

        ref?: Git.Ref;

        refresh_interval_seconds?: number;
      }

      export namespace Git {
        export interface Ref {
          name: string;

          type: 'branch' | 'tag';
        }
      }

      export interface S3 {
        bucket: string;

        region: string;

        endpoint_url?: string;

        path_style?: boolean;

        prefix?: string;
      }
    }
  }

  export interface ProxyConfig {
    access_control?: ProxyConfig.AccessControl;

    callbacks?: Array<ProxyConfig.Callback>;

    /**
     * Description says what this configuration as a whole lets the sandbox reach,
     * complementing the per-rule descriptions. At most 1024 characters.
     */
    description?: string;

    no_proxy?: Array<string>;

    rules?: Array<ProxyConfig.Rule>;
  }

  export namespace ProxyConfig {
    export interface AccessControl {
      allow_list?: Array<string>;

      deny_list?: Array<string>;
    }

    export interface Callback {
      match_hosts: Array<string>;

      ttl_seconds: number;

      url: string;

      full_request?: boolean;

      request_headers?: Array<Callback.RequestHeader>;
    }

    export namespace Callback {
      export interface RequestHeader {
        name: string;

        type: 'plaintext' | 'opaque' | 'workspace_secret';

        is_set?: boolean;

        value?: string;
      }
    }

    export interface Rule {
      name: string;

      aws?: Rule.SandboxesProxyAwsRoleConfig | Rule.SandboxesProxyAwsStaticConfig;

      /**
       * Description says what this rule lets the sandbox reach, so an agent driving the
       * sandbox can be told its capabilities. At most 1024 characters.
       */
      description?: string;

      enabled?: boolean;

      /**
       * EnvVars are plaintext env vars set for every command in the sandbox while this
       * rule is enabled. Use them for tools that refuse to run unless a credential env
       * var is present (e.g. gh needs GH_TOKEN) even though this rule injects the real
       * credential on the wire — set a dummy value here so the command starts. Explicit
       * per-sandbox env_vars win over these, and provider-managed (AWS/GCP) vars win
       * over both.
       */
      env_vars?: { [key: string]: string };

      gcp?: Rule.Gcp;

      headers?: Array<Rule.Header>;

      /**
       * MatchHeaders restricts a header injection rule to requests carrying every listed
       * header, each written "name: value" with a lowercase name and an exact value.
       * Pair with headers of the same name to swap a placeholder the sandbox sends (e.g.
       * "authorization: Bearer account-b") for a real credential, so one host can serve
       * several accounts. Rules are evaluated in order and the first match wins.
       */
      match_headers?: Array<string>;

      /**
       * MatchHosts is only accepted for header injection rules. Provider auth rules use
       * built-in host matching.
       */
      match_hosts?: Array<string>;

      match_paths?: Array<string>;

      type?: string;
    }

    export namespace Rule {
      export interface SandboxesProxyAwsRoleConfig {
        /**
         * RoleARN selects automatically renewed IAM-role credentials instead of static
         * keys. Access follows the role's effective AWS permissions, not the sandbox's
         * mount scope. Configure at creation; the role cannot be changed afterward.
         */
        role_arn: string;
      }

      export interface SandboxesProxyAwsStaticConfig {
        access_key_id: SandboxesProxyAwsStaticConfig.AccessKeyID;

        secret_access_key: SandboxesProxyAwsStaticConfig.SecretAccessKey;

        /**
         * RoleARN selects automatically renewed IAM-role credentials instead of static
         * keys. Access follows the role's effective AWS permissions, not the sandbox's
         * mount scope. Configure at creation; the role cannot be changed afterward.
         */
        role_arn?: '';
      }

      export namespace SandboxesProxyAwsStaticConfig {
        export interface AccessKeyID {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }

        export interface SecretAccessKey {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }
      }

      export interface Gcp {
        scopes: Array<string>;

        service_account_json: Gcp.ServiceAccountJson;
      }

      export namespace Gcp {
        export interface ServiceAccountJson {
          type: 'plaintext' | 'opaque' | 'workspace_secret';

          is_set?: boolean;

          value?: string;
        }
      }

      export interface Header {
        name: string;

        type: 'plaintext' | 'opaque' | 'workspace_secret';

        is_set?: boolean;

        value?: string;
      }
    }
  }

  /**
   * RunConfig is what the sandbox's commands run with: the user, working directory
   * and base env beneath env_vars.
   */
  export interface RunConfig {
    env_vars?: { [key: string]: string };

    user?: string;

    work_dir?: string;
  }
}

export interface SandboxStatusResponse {
  status?: string;

  status_message?: string;
}

export interface ServiceURLResponse {
  /**
   * Token and ExpiresAt are empty in LangSmith login mode (no token is minted).
   */
  token?: string;

  /**
   * Access echoes the enabled LangSmith login level ("restricted"/"workspace");
   * omitted in token mode.
   */
  access?: 'restricted' | 'workspace';

  browser_url?: string;

  expires_at?: string;

  service_url?: string;
}

export interface SnapshotListResponse {
  /**
   * This page of snapshots.
   */
  items?: Array<SnapshotResponse>;

  /**
   * Cursor for the next page, or null on the last page. A non-null value is the only
   * signal that more pages exist. Treat it as opaque.
   */
  next_cursor?: string;

  /**
   * Deprecated: use next_cursor. Offset to request for the next page, or 0 when no
   * pages remain.
   */
  offset?: number;

  /**
   * Deprecated: use items. Duplicates items.
   */
  snapshots?: Array<SnapshotResponse>;
}

export interface SnapshotResponse {
  id?: string;

  created_at?: string;

  created_by?: string;

  /**
   * Description says what this snapshot's image can do, so a caller can hand it to
   * an agent as a capability summary.
   */
  description?: string;

  docker_image?: string;

  fs_capacity_bytes?: number;

  fs_used_bytes?: number;

  image_digest?: string;

  labels?: { [key: string]: string };

  /**
   * MemorySnapshotSizeBytes is non-nil iff the snapshot was captured with VM memory
   * state. A non-nil value is the canonical signal that this snapshot can
   * warm-restore from memory; nil means rootfs only.
   */
  memory_snapshot_size_bytes?: number;

  name?: string;

  registry_id?: string;

  /**
   * RunConfig is what sandboxes from this snapshot boot with. Absent on snapshots
   * built before it was recorded, which run as root with their own env.
   */
  run_config?: SnapshotResponse.RunConfig;

  source_sandbox_id?: string;

  status?: string;

  status_message?: string;

  /**
   * Tags currently resolving to this snapshot, under Name. A snapshot with no tags
   * is dangling — addressable only by id.
   */
  tags?: Array<string>;

  updated_at?: string;
}

export namespace SnapshotResponse {
  /**
   * RunConfig is what sandboxes from this snapshot boot with. Absent on snapshots
   * built before it was recorded, which run as root with their own env.
   */
  export interface RunConfig {
    env_vars?: { [key: string]: string };

    user?: string;

    work_dir?: string;
  }
}

export interface SandboxListUsageCostsResponse {
  /**
   * Recorded compute usage in LangSmith Compute Units (LCU), as a decimal string
   * with up to six fractional digits and trailing zeros omitted. Snapshots return
   * "0".
   */
  lcu: string;

  /**
   * Allocated storage usage in LangSmith Storage Units (LSU), as a decimal string
   * with up to six fractional digits and trailing zeros omitted.
   */
  lsu: string;

  period_start: string;

  resource_id: string;

  resource_type: 'SANDBOX' | 'SNAPSHOT';
}

export interface SandboxListUsageCostsParams extends ItemsCursorGetPaginationParams {
  /**
   * Exclusive RFC3339 end time; the range must not exceed 31 days
   */
  end_time: string;

  /**
   * Inclusive RFC3339 start time
   */
  start_time: string;

  /**
   * HOUR returns hourly buckets. RESOURCE sums each resource over the requested
   * interval and sets period_start to start_time.
   */
  granularity?: 'HOUR' | 'RESOURCE';

  /**
   * Resource UUID filter; repeat this parameter up to 100 times
   */
  resource_ids?: Array<string>;

  /**
   * Resource type filter
   */
  resource_type?: 'SANDBOX' | 'SNAPSHOT';
}

Sandboxes.Boxes = Boxes;
Sandboxes.Registries = Registries;
Sandboxes.Snapshots = Snapshots;

export declare namespace Sandboxes {
  export {
    type DownloadURLResponse as DownloadURLResponse,
    type SandboxListResponse as SandboxListResponse,
    type SandboxResponse as SandboxResponse,
    type SandboxStatusResponse as SandboxStatusResponse,
    type ServiceURLResponse as ServiceURLResponse,
    type SnapshotListResponse as SnapshotListResponse,
    type SnapshotResponse as SnapshotResponse,
    type SandboxListUsageCostsResponse as SandboxListUsageCostsResponse,
    type SandboxListUsageCostsResponsesItemsCursorGetPagination as SandboxListUsageCostsResponsesItemsCursorGetPagination,
    type SandboxListUsageCostsParams as SandboxListUsageCostsParams,
  };

  export {
    Boxes as Boxes,
    type BoxListServiceURLsResponse as BoxListServiceURLsResponse,
    type BoxListServiceURLsResponsesItemsCursorGetPagination as BoxListServiceURLsResponsesItemsCursorGetPagination,
    type BoxCreateParams as BoxCreateParams,
    type BoxUpdateParams as BoxUpdateParams,
    type BoxListParams as BoxListParams,
    type BoxCreateSnapshotParams as BoxCreateSnapshotParams,
    type BoxDeleteServiceURLParams as BoxDeleteServiceURLParams,
    type BoxGenerateDownloadURLParams as BoxGenerateDownloadURLParams,
    type BoxGenerateServiceURLParams as BoxGenerateServiceURLParams,
    type BoxListServiceURLsParams as BoxListServiceURLsParams,
  };

  export {
    Registries as Registries,
    type RegistryListResponse as RegistryListResponse,
    type RegistryResponse as RegistryResponse,
    type RegistryCreateParams as RegistryCreateParams,
    type RegistryUpdateParams as RegistryUpdateParams,
    type RegistryListParams as RegistryListParams,
  };

  export {
    Snapshots as Snapshots,
    type SnapshotRetrieveByNameResponse as SnapshotRetrieveByNameResponse,
    type SnapshotCreateParams as SnapshotCreateParams,
    type SnapshotListParams as SnapshotListParams,
  };
}