// @generated by microsandbox-types. Do not edit by hand.

import type {
  EnvVar,
  HandoffInit,
  HostPermissions,
  MountOptions,
  NetworkPolicy,
  SandboxLogLevel,
  SandboxPolicy,
  SecretInjection,
  SecurityProfile,
  StatVirtualization,
} from "./domain.js";
export type * from "./domain.js";

export type CloudSandboxSpec = {
  /**
   * Unique sandbox name.
   */
  name: string;
  /**
   * Root filesystem source.
   */
  image: CloudRootfsSource;
  /**
   * CPU, memory, and user-facing disk resources.
   */
  resources: CloudSandboxResources;
  /**
   * Guest runtime options.
   */
  runtime: CloudSandboxRuntimeOptions;
  /**
   * Environment variables visible to commands in the sandbox.
   */
  env: Array<EnvVar>;
  /**
   * User-defined labels attached to the sandbox.
   */
  labels: { [key in string]: string };
  /**
   * Sandbox-wide resource limits inherited by guest processes.
   */
  rlimits: Array<CloudRlimit>;
  /**
   * Volume mounts.
   */
  mounts: Array<CloudVolumeMount>;
  /**
   * Rootfs patches applied before VM start.
   */
  patches: Array<CloudPatch>;
  /**
   * Network specification.
   */
  network: CloudNetworkSpec;
  /**
   * Hand off PID 1 to a guest init binary after agentd setup.
   */
  init: HandoffInit | null;
  /**
   * Pull policy for OCI images.
   */
  pull_policy: CloudPullPolicy;
  /**
   * In-guest security profile.
   */
  security_profile: SecurityProfile;
  /**
   * Sandbox lifecycle policy.
   */
  lifecycle: SandboxPolicy;
};

export type CloudRootfsSource = {
  "type": "bind";
  /**
   * Host path to bind mount.
   */
  path: string;
} | {
  "type": "oci";
  /**
   * OCI image reference (e.g. `python`).
   */
  reference: string;
} | {
  "type": "disk_image";
  /**
   * Path to the disk image file on the host.
   */
  path: string;
  /**
   * Disk image format.
   */
  format: CloudDiskImageFormat;
  /**
   * Inner filesystem type (optional; auto-detected if absent).
   */
  fstype: string | null;
};

export type CloudVolumeMount = {
  "type": "bind";
  /**
   * Host directory to bind into the guest.
   */
  host: string;
  /**
   * Guest path to mount at.
   */
  guest: string;
  /**
   * Mount options (read-only, no-exec, …).
   */
  options: MountOptions;
  /**
   * How guest `stat()` results are virtualized.
   */
  stat_virtualization: StatVirtualization;
  /**
   * Host permission policy applied to the mount.
   */
  host_permissions: HostPermissions;
  /**
   * Optional guest-write quota in MiB.
   */
  quota_mib: number | null;
} | {
  "type": "named";
  /**
   * Named volume to mount.
   */
  name: string;
  /**
   * Guest path to mount at.
   */
  guest: string;
  /**
   * Mount options (read-only, no-exec, …).
   */
  options: MountOptions;
  /**
   * How guest `stat()` results are virtualized.
   */
  stat_virtualization: StatVirtualization;
  /**
   * Host permission policy applied to the mount.
   */
  host_permissions: HostPermissions;
} | {
  "type": "tmpfs";
  /**
   * Guest path to mount at.
   */
  guest: string;
  /**
   * Optional size cap in MiB.
   */
  size_mib: number | null;
  /**
   * Mount options (read-only, no-exec, …).
   */
  options: MountOptions;
} | {
  "type": "disk_image";
  /**
   * Host path to the disk image file.
   */
  host: string;
  /**
   * Guest path to mount at.
   */
  guest: string;
  /**
   * Disk image format.
   */
  format: CloudDiskImageFormat;
  /**
   * Inner filesystem type (auto-detected if absent).
   */
  fstype: string | null;
  /**
   * Mount options (read-only, no-exec, …).
   */
  options: MountOptions;
};

export type CloudSandboxResources = {
  /**
   * Number of virtual CPUs.
   */
  vcpus: number;
  /**
   * Guest memory in MiB.
   */
  memory_mib: number;
  /**
   * Writable disk size in MiB. Applies only to OCI root filesystems.
   */
  disk_size_mib?: number | null;
};

export type CloudSandboxRuntimeOptions = {
  /**
   * Working directory for guest commands.
   */
  workdir: string | null;
  /**
   * Default shell.
   */
  shell: string | null;
  /**
   * Named in-guest scripts.
   */
  scripts: { [key in string]: string };
  /**
   * Entrypoint override.
   */
  entrypoint: Array<string> | null;
  /**
   * Command override.
   */
  cmd: Array<string> | null;
  /**
   * Guest user.
   */
  user: string | null;
  /**
   * Runtime log level.
   */
  log_level: SandboxLogLevel | null;
};

export type CloudPullPolicy = "if_missing" | "always" | "never";

export type CloudDiskImageFormat = "qcow2" | "raw" | "vmdk";

export type CloudRlimitResource =
  | "cpu"
  | "fsize"
  | "data"
  | "stack"
  | "core"
  | "rss"
  | "nproc"
  | "nofile"
  | "memlock"
  | "as"
  | "locks"
  | "sigpending"
  | "msgqueue"
  | "nice"
  | "rtprio"
  | "rttime";

export type CloudRlimit = {
  /**
   * Resource type.
   */
  resource: CloudRlimitResource;
  /**
   * Soft limit (can be raised up to the hard limit by the process).
   */
  soft: number;
  /**
   * Hard limit (ceiling, requires privileges to raise).
   */
  hard: number;
};

export type CloudPatch = {
  "type": "text";
  /**
   * Absolute guest path, such as `/etc/app.conf`.
   */
  path: string;
  /**
   * Text content to write.
   */
  content: string;
  /**
   * File permissions, such as `0o644`. `None` uses the default.
   */
  mode: number | null;
  /**
   * Allow replacing a file that already exists in the rootfs.
   */
  replace: boolean;
} | {
  "type": "file";
  /**
   * Absolute guest path.
   */
  path: string;
  /**
   * Raw byte content to write.
   */
  content: Array<number>;
  /**
   * File permissions, such as `0o644`. `None` uses the default.
   */
  mode: number | null;
  /**
   * Allow replacing a file that already exists in the rootfs.
   */
  replace: boolean;
} | {
  "type": "copy_file";
  /**
   * Host path to copy from.
   */
  src: string;
  /**
   * Absolute guest destination path.
   */
  dst: string;
  /**
   * File permissions. `None` preserves source permissions.
   */
  mode: number | null;
  /**
   * Allow replacing a file that already exists in the rootfs.
   */
  replace: boolean;
} | {
  "type": "copy_dir";
  /**
   * Host directory to copy from.
   */
  src: string;
  /**
   * Absolute guest destination path.
   */
  dst: string;
  /**
   * Allow replacing files that already exist in the rootfs.
   */
  replace: boolean;
} | {
  "type": "symlink";
  /**
   * Symlink target path.
   */
  target: string;
  /**
   * Absolute guest path where the symlink is created.
   */
  link: string;
  /**
   * Allow replacing a path that already exists in the rootfs.
   */
  replace: boolean;
} | {
  "type": "mkdir";
  /**
   * Absolute guest path.
   */
  path: string;
  /**
   * Directory permissions, such as `0o755`. `None` uses the default.
   */
  mode: number | null;
} | {
  "type": "remove";
  /**
   * Absolute guest path to remove.
   */
  path: string;
} | {
  "type": "append";
  /**
   * Absolute guest path of the file to append to.
   */
  path: string;
  /**
   * Content to append.
   */
  content: string;
};

export type CloudNetworkSpec = {
  /**
   * Whether networking is enabled for this sandbox.
   */
  enabled: boolean;
  /**
   * Egress/ingress policy.
   */
  policy: NetworkPolicy | null;
  /**
   * Secret-injection config.
   */
  secrets: CloudSecretsConfig | null;
  /**
   * Max concurrent guest connections.
   */
  max_connections: number | null;
};

export type CloudSecretsConfig = {
  /**
   * Secrets to inject.
   */
  entries: Array<CloudSecretEntry>;
  /**
   * Default action when a placeholder leaks to a disallowed host.
   */
  on_violation: CloudViolationAction;
};

export type CloudSecretEntry = {
  /**
   * Environment variable name exposed to the sandbox.
   */
  env_var: string;
  /**
   * The secret value (empty when `source` carries a reference instead).
   */
  value: string;
  /**
   * Host-side source resolved into `value` at spawn time.
   */
  source?: CloudSecretSource | null;
  /**
   * Placeholder the sandbox sees instead of the real value.
   */
  placeholder: string;
  /**
   * Hosts allowed to receive this secret.
   */
  allowed_hosts: Array<CloudHostPattern>;
  /**
   * Where the secret may be injected.
   */
  injection: SecretInjection;
  /**
   * Per-secret violation action overriding the config default.
   */
  on_violation?: CloudViolationAction | null;
  /**
   * Require verified TLS identity before substituting (default: true).
   */
  require_tls_identity: boolean;
};

export type CloudSecretSource = {
  "type": "env";
  /**
   * Host environment variable name.
   */
  var: string;
} | {
  "type": "store";
  /**
   * Store-specific secret reference.
   */
  reference: string;
};

export type CloudHostPattern = {
  "type": "exact";
  /**
   * Hostname to match exactly.
   */
  value: string;
} | {
  "type": "wildcard";
  /**
   * Wildcard pattern.
   */
  value: string;
} | { "type": "any" };

export type CloudViolationAction =
  | { "type": "block" }
  | { "type": "block_and_log" }
  | { "type": "block_and_terminate" }
  | {
    "type": "passthrough";
    /**
     * Hosts for which the placeholder passes through unchanged.
     */
    hosts: Array<CloudHostPattern>;
  };

export type CloudCreateSandboxResponse = {
  /**
   * Server-side UUID.
   */
  id: string;
  /**
   * Owning org's UUID.
   */
  org_id: string;
  /**
   * User-facing, per-org sandbox name.
   */
  name: string;
  /**
   * Canonical, resolved SSH username token.
   */
  slug: string;
  /**
   * Current lifecycle status.
   */
  status: CloudSandboxStatus;
  /**
   * Why the sandbox is not running yet, when known. Only present while
   * `status` is `starting`.
   */
  status_reason: CloudSandboxStatusReason | null;
  /**
   * Curated resolved-spec projection returned by the control plane, when
   * available. Lifecycle and agent operations intentionally do not depend
   * on reconstructing the create request from this server-owned view.
   */
  spec?: unknown | null | undefined;
  /**
   * Whether the sandbox should be removed when its allocation terminates.
   */
  ephemeral: boolean;
  /**
   * Creation timestamp.
   */
  created_at: string;
  /**
   * Last start timestamp, when known.
   */
  started_at: string | null;
  /**
   * Last stop timestamp, when known.
   */
  stopped_at: string | null;
  /**
   * Human-readable message for the most recent failure, when any.
   */
  last_failure_message: string | null;
};

export type CloudSandboxStatus =
  | "created"
  | "starting"
  | "running"
  | "stopping"
  | "stopped"
  | "failed";

export type CloudSandboxStatusReason = "scheduling" | "insufficient_capacity";

export type CloudPaginated<T> = {
  /**
   * Page of response items.
   */
  data: Array<T>;
  /**
   * Cursor for the next page, when one exists.
   */
  next_cursor: string | null;
};

export type CloudMessageResponse = {
  /**
   * Human-readable response message.
   */
  message: string;
};

export type CloudErrorBody = {
  /**
   * Flat machine-readable error code, when returned in this shape.
   */
  code: string | null;
  /**
   * Flat human-readable error message, when returned in this shape.
   */
  message: string | null;
  /**
   * Nested error object returned by the API error responder.
   */
  error: CloudErrorDetails | null;
};

export type CloudErrorDetails = {
  /**
   * Machine-readable error code.
   */
  code: string | null;
  /**
   * Human-readable error message.
   */
  message: string | null;
};