@effect-uai/core 0.5.1 → 0.6.0

package/dist/sandbox/Sandbox.d.mts

@@ -0,0 +1,717 @@
+import { a as SandboxError } from "../SandboxError-BvKypkJm.mjs";
+import { Brand, Context, Data, Duration, Effect, Redacted, Scope, Stream } from "effect";
+import * as _$effect_Unify0 from "effect/Unify";
+
+//#region src/sandbox/Sandbox.d.ts
+declare namespace Sandbox_d_exports {
+  export { BoundSecret, CommonCreateRequest, CommonExecRequest, CommonSpawnRequest, ExecEvent, ExecResult, FileEntry, FileEntryKind, ImageRef, NetworkPolicy, ProcessHandle, Sandbox, SandboxCustomImage, SandboxFilesystem, SandboxHostnameAllowlist, SandboxId, SandboxInstance, SandboxKernelSession, SandboxPauseResume, SandboxPortExposure, SandboxPortsApi, SandboxPty, SandboxRef, SandboxSecretInjection, SandboxService, SandboxSnapshots, SandboxSnapshotsApi, SandboxVolumes, SandboxVolumesApi, SnapshotId, VolumeId, VolumeMount, attach, create, createVolume, destroy, destroySnapshot, destroyVolume, exposePort, list, listSnapshots, listVolumes, snapshot };
+}
+/**
+ * Sandbox identifier. Branded `string` so providers don't accidentally
+ * accept a raw user-supplied id. Each provider mints these per its own
+ * naming scheme (uuid for E2B/Vercel, user-supplied name for
+ * Microsandbox/Modal, …); the core code treats them opaquely.
+ *
+ * Mint via the value-level `SandboxId(...)` smart constructor instead
+ * of `as SandboxId` casts.
+ */
+type SandboxId = Brand.Branded<string, "SandboxId">;
+declare const SandboxId: Brand.Constructor<SandboxId>;
+/**
+ * Reference returned by `list`. Carries just enough to call `attach` —
+ * provider-specific metadata (createdAt, region, tags, …) lives on the
+ * narrowed per-provider ref.
+ */
+type SandboxRef = {
+  readonly id: SandboxId;
+  readonly name?: string;
+};
+type VolumeId = Brand.Branded<string, "VolumeId">;
+declare const VolumeId: Brand.Constructor<VolumeId>;
+type SnapshotId = Brand.Branded<string, "SnapshotId">;
+declare const SnapshotId: Brand.Constructor<SnapshotId>;
+/**
+ * What runtime / filesystem to boot the sandbox from.
+ *
+ * - `Default` — provider picks its house image (Vercel: Amazon Linux
+ *   2023; Microsandbox: requires user image but a builder default may
+ *   apply, …). Use when you don't care what's pre-installed.
+ * - `Registry` — an OCI image reference. Supported by every provider
+ *   except those with a fixed base (Vercel ignores this and the
+ *   request-schema rejects at decode).
+ * - `Snapshot` — restore from a captured state. Gated by
+ *   {@link SandboxSnapshots} at the call site — the marker is provided
+ *   by adapters whose provider supports snapshot-as-image.
+ * - `Dockerfile` — provider builds a custom image from a Dockerfile.
+ *   Gated by {@link SandboxCustomImage}.
+ */
+type ImageRef = Data.TaggedEnum<{
+  Default: {};
+  Registry: {
+    readonly ref: string;
+  };
+  Snapshot: {
+    readonly id: SnapshotId;
+  };
+  Dockerfile: {
+    readonly contents: string;
+  };
+}>;
+declare const ImageRef: {
+  readonly Default: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Default";
+  }, "_tag">;
+  readonly Registry: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Registry";
+    readonly ref: string;
+  }, "_tag">;
+  readonly Snapshot: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Snapshot";
+    readonly id: SnapshotId;
+  }, "_tag">;
+  readonly Dockerfile: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Dockerfile";
+    readonly contents: string;
+  }, "_tag">;
+  readonly $is: <Tag extends "Default" | "Registry" | "Snapshot" | "Dockerfile">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Default";
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Registry";
+    readonly ref: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Snapshot";
+    readonly id: SnapshotId;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Dockerfile";
+    readonly contents: string;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Default: (args: {
+        readonly _tag: "Default";
+      }) => any;
+      readonly Registry: (args: {
+        readonly _tag: "Registry";
+        readonly ref: string;
+      }) => any;
+      readonly Snapshot: (args: {
+        readonly _tag: "Snapshot";
+        readonly id: SnapshotId;
+      }) => any;
+      readonly Dockerfile: (args: {
+        readonly _tag: "Dockerfile";
+        readonly contents: string;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Default";
+    } | {
+      readonly _tag: "Registry";
+      readonly ref: string;
+    } | {
+      readonly _tag: "Snapshot";
+      readonly id: SnapshotId;
+    } | {
+      readonly _tag: "Dockerfile";
+      readonly contents: string;
+    }) => _$effect_Unify0.Unify<ReturnType<Cases["Default" | "Registry" | "Snapshot" | "Dockerfile"]>>;
+    <Cases extends {
+      readonly Default: (args: {
+        readonly _tag: "Default";
+      }) => any;
+      readonly Registry: (args: {
+        readonly _tag: "Registry";
+        readonly ref: string;
+      }) => any;
+      readonly Snapshot: (args: {
+        readonly _tag: "Snapshot";
+        readonly id: SnapshotId;
+      }) => any;
+      readonly Dockerfile: (args: {
+        readonly _tag: "Dockerfile";
+        readonly contents: string;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Default";
+    } | {
+      readonly _tag: "Registry";
+      readonly ref: string;
+    } | {
+      readonly _tag: "Snapshot";
+      readonly id: SnapshotId;
+    } | {
+      readonly _tag: "Dockerfile";
+      readonly contents: string;
+    }, cases: Cases): _$effect_Unify0.Unify<ReturnType<Cases["Default" | "Registry" | "Snapshot" | "Dockerfile"]>>;
+  };
+};
+/**
+ * Outbound network policy for a sandbox.
+ *
+ * - `Open` — no egress restriction. The provider's defaults apply
+ *   (e.g. Microsandbox's "public-only" still blocks private ranges).
+ * - `Blocked` — fully airgapped, no outbound connectivity at all.
+ * - `Allowlist` — only the listed hosts / CIDRs may be reached.
+ *
+ * Providers vary in what they honour: hostname-allowlist requires
+ * {@link SandboxHostnameAllowlist}; CIDR-only providers ignore `hosts`
+ * and the adapter rejects at decode if `hosts` is non-empty.
+ */
+type NetworkPolicy = Data.TaggedEnum<{
+  Open: {};
+  Blocked: {};
+  Allowlist: {
+    readonly hosts?: ReadonlyArray<string>;
+    readonly cidrs?: ReadonlyArray<string>;
+  };
+}>;
+declare const NetworkPolicy: {
+  readonly Open: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Open";
+  }, "_tag">;
+  readonly Blocked: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Blocked";
+  }, "_tag">;
+  readonly Allowlist: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Allowlist";
+    readonly hosts?: ReadonlyArray<string>;
+    readonly cidrs?: ReadonlyArray<string>;
+  }, "_tag">;
+  readonly $is: <Tag extends "Open" | "Blocked" | "Allowlist">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Open";
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Blocked";
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Allowlist";
+    readonly hosts?: ReadonlyArray<string>;
+    readonly cidrs?: ReadonlyArray<string>;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Open: (args: {
+        readonly _tag: "Open";
+      }) => any;
+      readonly Blocked: (args: {
+        readonly _tag: "Blocked";
+      }) => any;
+      readonly Allowlist: (args: {
+        readonly _tag: "Allowlist";
+        readonly hosts?: ReadonlyArray<string>;
+        readonly cidrs?: ReadonlyArray<string>;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Open";
+    } | {
+      readonly _tag: "Blocked";
+    } | {
+      readonly _tag: "Allowlist";
+      readonly hosts?: ReadonlyArray<string>;
+      readonly cidrs?: ReadonlyArray<string>;
+    }) => _$effect_Unify0.Unify<ReturnType<Cases["Open" | "Blocked" | "Allowlist"]>>;
+    <Cases extends {
+      readonly Open: (args: {
+        readonly _tag: "Open";
+      }) => any;
+      readonly Blocked: (args: {
+        readonly _tag: "Blocked";
+      }) => any;
+      readonly Allowlist: (args: {
+        readonly _tag: "Allowlist";
+        readonly hosts?: ReadonlyArray<string>;
+        readonly cidrs?: ReadonlyArray<string>;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Open";
+    } | {
+      readonly _tag: "Blocked";
+    } | {
+      readonly _tag: "Allowlist";
+      readonly hosts?: ReadonlyArray<string>;
+      readonly cidrs?: ReadonlyArray<string>;
+    }, cases: Cases): _$effect_Unify0.Unify<ReturnType<Cases["Open" | "Blocked" | "Allowlist"]>>;
+  };
+};
+/**
+ * A secret bound to a sandbox at create time. The code inside the
+ * sandbox sees only a placeholder (`$MSB_<NAME>` for Microsandbox,
+ * `{name}` for Vercel header-injection, etc.); the real `value` lives
+ * on the provider's proxy and is substituted on outbound HTTPS to
+ * `hosts`.
+ *
+ * Requires the {@link SandboxSecretInjection} capability marker —
+ * provider Layers without proxy-layer secret rewriting do not ship the
+ * marker and consumer code fails at `Effect.provide` with a type
+ * error.
+ *
+ * `header` is the request header to inject (default
+ * `"Authorization: Bearer <value>"`). Providers that do not let
+ * callers pick the header (Microsandbox's `secretEnv` shorthand)
+ * silently ignore this field; providers that require an explicit
+ * header (Vercel's `transform.headers`) fail at decode if it's absent.
+ */
+type BoundSecret = {
+  readonly name: string;
+  readonly value: Redacted.Redacted<string>;
+  readonly hosts: ReadonlyArray<string>;
+  readonly header?: string;
+};
+type VolumeMount = {
+  readonly id: VolumeId;
+  readonly mountPath: string;
+  readonly readonly?: boolean;
+};
+/**
+ * Cross-provider create request. Provider-specific knobs (region,
+ * cpus, memory, template id, …) live on each provider's narrowed
+ * request type which extends this.
+ *
+ * Fields a provider can't honour fail at **decode time** (per the
+ * per-provider request schema), not silently at runtime. The
+ * ComputeSDK anti-pattern of "drop unsupported fields" is the
+ * footgun we're avoiding.
+ */
+type CommonCreateRequest = {
+  /** Image / snapshot to boot from. Omit for the provider's default. */readonly image?: ImageRef;
+  /**
+   * Idle / hard timeout. Accepts a number (millis), a string like
+   * `"30 seconds"`, or a `Duration`. Providers default differently.
+   */
+  readonly timeout?: Duration.Input;
+  /**
+   * Env vars exposed to the sandbox. NOT for secrets you want hidden
+   * from the running code — use {@link BoundSecret} instead.
+   */
+  readonly env?: Readonly<Record<string, string>>; /** Outbound network policy. */
+  readonly network?: NetworkPolicy;
+  /**
+   * Bound secrets — code inside the sandbox sees a placeholder; the
+   * proxy substitutes the real value on outbound HTTPS to listed hosts.
+   * Capability-gated on {@link SandboxSecretInjection}.
+   */
+  readonly secrets?: ReadonlyArray<BoundSecret>;
+  /**
+   * Persistent volumes to mount. Volumes are created via
+   * `Sandbox.volumes.create` and survive sandbox lifetime.
+   * Capability-gated on {@link SandboxVolumes}.
+   */
+  readonly volumes?: ReadonlyArray<VolumeMount>;
+};
+/**
+ * Cross-provider exec request. Background / long-running processes
+ * use `spawn` instead of `exec`; the semantics differ enough that
+ * overloading `exec` with a `detached` flag was rejected during
+ * design.
+ */
+type CommonExecRequest = {
+  /**
+   * Argv-style command. Pass a string for "run this through the
+   * shell" semantics (provider-dependent — most use `sh -c`); pass
+   * an array for direct argv with no shell parsing.
+   */
+  readonly cmd: string | ReadonlyArray<string>;
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly stdin?: string | Uint8Array;
+  /**
+   * Per-exec timeout. Accepts a number (millis), a string like
+   * `"5 seconds"`, or a `Duration`.
+   */
+  readonly timeout?: Duration.Input;
+};
+/**
+ * Spawn request — extends {@link CommonExecRequest} with the option
+ * to provide stdin as a `Stream<Uint8Array>`. The provider takes one
+ * chunk at a time and sends EOF when the stream completes. Useful
+ * for piping LLM output into a sandboxed process, or feeding stdin
+ * from another stream source. `exec` does not accept streams.
+ */
+type CommonSpawnRequest = Omit<CommonExecRequest, "stdin"> & {
+  readonly stdin?: string | Uint8Array | Stream.Stream<Uint8Array, never, never>;
+};
+type ExecResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+};
+/**
+ * Streaming exec output. `Complete` is terminal — the stream
+ * completes after emitting it.
+ */
+type ExecEvent = Data.TaggedEnum<{
+  Stdout: {
+    readonly chunk: Uint8Array;
+  };
+  Stderr: {
+    readonly chunk: Uint8Array;
+  };
+  Complete: {
+    readonly exitCode: number;
+    readonly durationMs: number;
+  };
+}>;
+declare const ExecEvent: {
+  readonly Stdout: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Stdout";
+    readonly chunk: Uint8Array;
+  }, "_tag">;
+  readonly Stderr: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Stderr";
+    readonly chunk: Uint8Array;
+  }, "_tag">;
+  readonly Complete: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Complete";
+    readonly exitCode: number;
+    readonly durationMs: number;
+  }, "_tag">;
+  readonly $is: <Tag extends "Stdout" | "Stderr" | "Complete">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Stdout";
+    readonly chunk: Uint8Array;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Stderr";
+    readonly chunk: Uint8Array;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Complete";
+    readonly exitCode: number;
+    readonly durationMs: number;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Stdout: (args: {
+        readonly _tag: "Stdout";
+        readonly chunk: Uint8Array;
+      }) => any;
+      readonly Stderr: (args: {
+        readonly _tag: "Stderr";
+        readonly chunk: Uint8Array;
+      }) => any;
+      readonly Complete: (args: {
+        readonly _tag: "Complete";
+        readonly exitCode: number;
+        readonly durationMs: number;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Stdout";
+      readonly chunk: Uint8Array;
+    } | {
+      readonly _tag: "Stderr";
+      readonly chunk: Uint8Array;
+    } | {
+      readonly _tag: "Complete";
+      readonly exitCode: number;
+      readonly durationMs: number;
+    }) => _$effect_Unify0.Unify<ReturnType<Cases["Stdout" | "Stderr" | "Complete"]>>;
+    <Cases extends {
+      readonly Stdout: (args: {
+        readonly _tag: "Stdout";
+        readonly chunk: Uint8Array;
+      }) => any;
+      readonly Stderr: (args: {
+        readonly _tag: "Stderr";
+        readonly chunk: Uint8Array;
+      }) => any;
+      readonly Complete: (args: {
+        readonly _tag: "Complete";
+        readonly exitCode: number;
+        readonly durationMs: number;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Stdout";
+      readonly chunk: Uint8Array;
+    } | {
+      readonly _tag: "Stderr";
+      readonly chunk: Uint8Array;
+    } | {
+      readonly _tag: "Complete";
+      readonly exitCode: number;
+      readonly durationMs: number;
+    }, cases: Cases): _$effect_Unify0.Unify<ReturnType<Cases["Stdout" | "Stderr" | "Complete"]>>;
+  };
+};
+type FileEntryKind = "file" | "directory" | "symlink" | "other";
+type FileEntry = {
+  readonly path: string;
+  readonly kind: FileEntryKind;
+};
+type SandboxFilesystem = {
+  readonly read: (path: string) => Effect.Effect<Uint8Array, SandboxError>;
+  readonly write: (path: string, contents: Uint8Array | string) => Effect.Effect<void, SandboxError>;
+  readonly remove: (path: string) => Effect.Effect<void, SandboxError>;
+  readonly mkdir: (path: string) => Effect.Effect<void, SandboxError>;
+  readonly list: (path: string) => Effect.Effect<ReadonlyArray<FileEntry>, SandboxError>;
+  readonly exists: (path: string) => Effect.Effect<boolean, SandboxError>;
+};
+/**
+ * Long-running process handle. Returned by `spawn` in a `Scope.Scope`
+ * — the process is killed on scope close. To outlive the calling
+ * scope, do `Effect.forkScoped` against a wider scope or use
+ * `attach`-style reconnection per the provider's escape hatch.
+ */
+type ProcessHandle = {
+  readonly pid: number;
+  readonly events: Stream.Stream<ExecEvent, SandboxError>;
+  readonly kill: Effect.Effect<void, SandboxError>;
+  readonly exit: Effect.Effect<{
+    readonly exitCode: number;
+  }, SandboxError>;
+};
+/**
+ * Live sandbox handle. Methods are plain `Effect` / `Stream` values
+ * — no nullary thunks (`destroy()`, `pause()`) — to match Effect's
+ * `Queue.shutdown` / `Fiber.interrupt` style. Destruction is the
+ * scope finalizer, not a method here; for the rare "kill from
+ * another fiber" case use the service-level escape hatch
+ * `Sandbox.destroy(id)`.
+ */
+type SandboxInstance = {
+  readonly id: SandboxId;
+  readonly exec: (request: CommonExecRequest) => Effect.Effect<ExecResult, SandboxError>;
+  readonly execStream: (request: CommonExecRequest) => Stream.Stream<ExecEvent, SandboxError>;
+  /**
+   * Spawn a background / long-running process. The returned handle is
+   * scoped — the process is killed on scope close. Use this for
+   * "dev server / watcher / tail -f" workloads. For one-shot
+   * commands prefer `exec`.
+   */
+  readonly spawn: (request: CommonSpawnRequest) => Effect.Effect<ProcessHandle, SandboxError, Scope.Scope>;
+  readonly files: SandboxFilesystem;
+};
+type SandboxSnapshotsApi = {
+  readonly create: (from: SandboxInstance, name?: string) => Effect.Effect<SnapshotId, SandboxError>;
+  readonly destroy: (id: SnapshotId) => Effect.Effect<void, SandboxError>;
+  readonly list: Effect.Effect<ReadonlyArray<{
+    readonly id: SnapshotId;
+    readonly name?: string;
+  }>, SandboxError>;
+};
+type SandboxVolumesApi = {
+  readonly create: (name: string, options?: {
+    readonly quotaBytes?: number;
+  }) => Effect.Effect<VolumeId, SandboxError>;
+  readonly destroy: (id: VolumeId) => Effect.Effect<void, SandboxError>;
+  readonly list: Effect.Effect<ReadonlyArray<{
+    readonly id: VolumeId;
+    readonly name: string;
+  }>, SandboxError>;
+};
+type SandboxPortsApi = {
+  /**
+   * Expose an internal sandbox port as a publicly reachable URL.
+   * Gated by {@link SandboxPortExposure} on the free helper; adapters
+   * that don't ship the marker leave this sub-API out of the public
+   * surface entirely (callers can't construct an Effect against it).
+   */
+  readonly expose: (instance: SandboxInstance, port: number) => Effect.Effect<{
+    readonly url: string;
+  }, SandboxError>;
+};
+/**
+ * Cross-provider sandbox service.
+ *
+ * Lifetime model: `create` returns a sandbox handle in `Scope.Scope`.
+ * The scope finalizer destroys the sandbox. Use `Effect.scoped` to
+ * bound a sandbox's lifetime to a single Effect, or manage the scope
+ * explicitly via `Scope.make` for sandboxes that span many calls.
+ * This is why there's no `destroy()` method on `SandboxInstance` —
+ * the scope is the lifecycle handle.
+ *
+ * `snapshots` and `volumes` sub-APIs are present on the service but
+ * are still capability-gated: provider Layers that don't support
+ * them ship implementations that always fail with
+ * `SandboxUnsupported`. The free helpers ({@link snapshot},
+ * {@link createVolume}) additionally require the corresponding
+ * capability marker on R, so misuses surface as type errors at
+ * `Effect.provide`, not as runtime failures.
+ */
+type SandboxService = {
+  /**
+   * Provision a new sandbox. The returned handle's lifetime is
+   * bound to the caller's scope; the sandbox is destroyed on scope
+   * close. To survive the scope, use `attach`-style reconnection or
+   * promote into a wider scope.
+   */
+  readonly create: (request: CommonCreateRequest) => Effect.Effect<SandboxInstance, SandboxError, Scope.Scope>;
+  /**
+   * Re-acquire an existing sandbox by id. The returned handle is
+   * scope-bound but the finalizer is "detach" (no destroy) —
+   * appropriate for paused / detached / persistent sandboxes that
+   * outlive any single agent run.
+   */
+  readonly attach: (id: SandboxId) => Effect.Effect<SandboxInstance, SandboxError, Scope.Scope>;
+  /**
+   * Enumerate sandboxes visible to the configured account / project.
+   */
+  readonly list: Effect.Effect<ReadonlyArray<SandboxRef>, SandboxError>;
+  /**
+   * Escape hatch for destroying a sandbox from outside its owning
+   * scope. Most callers should let the scope finalizer handle this.
+   */
+  readonly destroy: (id: SandboxId) => Effect.Effect<void, SandboxError>; /** Snapshot management. Capability-gated on {@link SandboxSnapshots}. */
+  readonly snapshots: SandboxSnapshotsApi; /** Volume management. Capability-gated on {@link SandboxVolumes}. */
+  readonly volumes: SandboxVolumesApi; /** Port exposure. Capability-gated on {@link SandboxPortExposure}. */
+  readonly ports: SandboxPortsApi;
+};
+declare const Sandbox_base: Context.ServiceClass<Sandbox, "@betalyra/effect-uai/Sandbox", SandboxService>;
+declare class Sandbox extends Sandbox_base {}
+declare const SandboxHostnameAllowlist_base: Context.ServiceClass<SandboxHostnameAllowlist, "@betalyra/effect-uai/capability/SandboxHostnameAllowlist", void>;
+/**
+ * Capability marker — provided by adapter Layers whose provider
+ * supports a hostname-level egress allowlist (matching against host
+ * names / wildcards, not just CIDRs). Vercel, Cloudflare, Deno,
+ * Microsandbox, Runloop, Anthropic srt ship this marker; Modal and
+ * Daytona (CIDR-only) do not.
+ *
+ * Phantom — the value is `void`; adapters register with
+ * `Layer.succeed(SandboxHostnameAllowlist, undefined)`.
+ */
+declare class SandboxHostnameAllowlist extends SandboxHostnameAllowlist_base {}
+declare const SandboxSecretInjection_base: Context.ServiceClass<SandboxSecretInjection, "@betalyra/effect-uai/capability/SandboxSecretInjection", void>;
+/**
+ * Capability marker — adapter's provider supports proxy-layer
+ * secret rewriting (header injection on outbound HTTPS to bound
+ * hosts; the running code never sees the real value). Deno,
+ * Cloudflare, E2B, Vercel (firewall transform), Microsandbox,
+ * Runloop (Agent Gateway) ship this. Modal, Daytona, CodeSandbox
+ * do not.
+ */
+declare class SandboxSecretInjection extends SandboxSecretInjection_base {}
+declare const SandboxSnapshots_base: Context.ServiceClass<SandboxSnapshots, "@betalyra/effect-uai/capability/SandboxSnapshots", void>;
+/**
+ * Capability marker — adapter supports snapshot-as-new-sandbox
+ * (capture state, restore as a derived sandbox with a fresh id).
+ * Distinct from {@link SandboxPauseResume}, which preserves the
+ * same id and resumes in place.
+ */
+declare class SandboxSnapshots extends SandboxSnapshots_base {}
+declare const SandboxPauseResume_base: Context.ServiceClass<SandboxPauseResume, "@betalyra/effect-uai/capability/SandboxPauseResume", void>;
+/**
+ * Capability marker — adapter supports in-place pause and resume on
+ * the same sandbox id (E2B, CodeSandbox). Memory + processes are
+ * preserved across the pause boundary. Most providers without this
+ * marker offer {@link SandboxSnapshots} instead.
+ */
+declare class SandboxPauseResume extends SandboxPauseResume_base {}
+declare const SandboxVolumes_base: Context.ServiceClass<SandboxVolumes, "@betalyra/effect-uai/capability/SandboxVolumes", void>;
+/**
+ * Capability marker — adapter manages named persistent volumes
+ * outside any single sandbox lifecycle (Modal Volume, Daytona,
+ * Microsandbox, BoxLite). Providers without this marker leave
+ * `Sandbox.volumes.*` returning `SandboxUnsupported`; the free
+ * helpers ({@link createVolume}, {@link destroyVolume}) additionally
+ * require this marker on R so misuses become a type error.
+ */
+declare class SandboxVolumes extends SandboxVolumes_base {}
+declare const SandboxKernelSession_base: Context.ServiceClass<SandboxKernelSession, "@betalyra/effect-uai/capability/SandboxKernelSession", void>;
+/**
+ * Capability marker — adapter supports a stateful kernel session
+ * (Jupyter-style: persistent Python / JS context that returns rich
+ * outputs across many `runCode` calls). Cloudflare Code Interpreter
+ * and E2B ship this; everyone else expects you to write your own
+ * script and `exec` it.
+ *
+ * The actual `runCode` helper lives separately (not on
+ * `SandboxInstance`) because the return shape is different — rich
+ * outputs with images/tables, not buffered stdout strings.
+ */
+declare class SandboxKernelSession extends SandboxKernelSession_base {}
+declare const SandboxPty_base: Context.ServiceClass<SandboxPty, "@betalyra/effect-uai/capability/SandboxPty", void>;
+/**
+ * Capability marker — adapter exposes an interactive PTY session
+ * (Runloop, Cloudflare terminal). Distinct from `execStream` which
+ * is byte-oriented and one-shot.
+ */
+declare class SandboxPty extends SandboxPty_base {}
+declare const SandboxCustomImage_base: Context.ServiceClass<SandboxCustomImage, "@betalyra/effect-uai/capability/SandboxCustomImage", void>;
+/**
+ * Capability marker — adapter accepts a user-supplied Dockerfile (or
+ * OCI image build) instead of just a registry reference. Vercel does
+ * not ship this (fixed AL2023). Deno does not (snapshots only).
+ * Most others do.
+ */
+declare class SandboxCustomImage extends SandboxCustomImage_base {}
+declare const SandboxPortExposure_base: Context.ServiceClass<SandboxPortExposure, "@betalyra/effect-uai/capability/SandboxPortExposure", void>;
+/**
+ * Capability marker — adapter can expose an internal port as a
+ * publicly reachable URL. Most cloud providers ship this; local
+ * providers (Microsandbox, BoxLite) typically only support
+ * host-side port forwarding (handled by ignoring this marker and
+ * documenting via the per-provider request type).
+ */
+declare class SandboxPortExposure extends SandboxPortExposure_base {}
+/**
+ * Provision a sandbox bound to the caller's scope. Drop the
+ * `Scope.Scope` requirement with `Effect.scoped`.
+ */
+declare const create: (request: CommonCreateRequest) => Effect.Effect<SandboxInstance, SandboxError, Sandbox | Scope.Scope>;
+/**
+ * Re-acquire an existing sandbox by id. Same scope semantics as
+ * `create`, but the finalizer detaches rather than destroying.
+ */
+declare const attach: (id: SandboxId) => Effect.Effect<SandboxInstance, SandboxError, Sandbox | Scope.Scope>;
+/** Enumerate sandboxes for the configured account / project. */
+declare const list: Effect.Effect<ReadonlyArray<SandboxRef>, SandboxError, Sandbox>;
+/**
+ * Escape hatch for destroying a sandbox from outside its owning
+ * scope. Most callers should let the scope finalizer handle this
+ * automatically.
+ */
+declare const destroy: (id: SandboxId) => Effect.Effect<void, SandboxError, Sandbox>;
+/**
+ * Create a snapshot of a live sandbox. Requires
+ * {@link SandboxSnapshots} on the R channel — adapters whose
+ * provider doesn't support snapshot-as-new-sandbox don't ship the
+ * marker and calls fail at `Effect.provide` with a type error.
+ */
+declare const snapshot: (from: SandboxInstance, name?: string) => Effect.Effect<SnapshotId, SandboxError, Sandbox | SandboxSnapshots>;
+/**
+ * Create a named persistent volume. Requires {@link SandboxVolumes}.
+ */
+declare const createVolume: (name: string, options?: {
+  readonly quotaBytes?: number;
+}) => Effect.Effect<VolumeId, SandboxError, Sandbox | SandboxVolumes>;
+/** Destroy a named volume. Requires {@link SandboxVolumes}. */
+declare const destroyVolume: (id: VolumeId) => Effect.Effect<void, SandboxError, Sandbox | SandboxVolumes>;
+/** Enumerate persistent volumes. Requires {@link SandboxVolumes}. */
+declare const listVolumes: Effect.Effect<ReadonlyArray<{
+  readonly id: VolumeId;
+  readonly name: string;
+}>, SandboxError, Sandbox | SandboxVolumes>;
+/** Destroy a snapshot. Requires {@link SandboxSnapshots}. */
+declare const destroySnapshot: (id: SnapshotId) => Effect.Effect<void, SandboxError, Sandbox | SandboxSnapshots>;
+/** Enumerate snapshots. Requires {@link SandboxSnapshots}. */
+declare const listSnapshots: Effect.Effect<ReadonlyArray<{
+  readonly id: SnapshotId;
+  readonly name?: string;
+}>, SandboxError, Sandbox | SandboxSnapshots>;
+/**
+ * Expose an internal port of a live sandbox as a publicly reachable
+ * URL. Requires {@link SandboxPortExposure} — adapters whose provider
+ * doesn't support runtime port exposure (e.g. Microsandbox, which
+ * forwards at create time only) don't ship the marker, and calls
+ * fail at `Effect.provide` with a type error.
+ */
+declare const exposePort: (instance: SandboxInstance, port: number) => Effect.Effect<{
+  readonly url: string;
+}, SandboxError, Sandbox | SandboxPortExposure>;
+//#endregion
+export { BoundSecret, CommonCreateRequest, CommonExecRequest, CommonSpawnRequest, ExecEvent, ExecResult, FileEntry, FileEntryKind, ImageRef, NetworkPolicy, ProcessHandle, Sandbox, SandboxCustomImage, SandboxFilesystem, SandboxHostnameAllowlist, SandboxId, SandboxInstance, SandboxKernelSession, SandboxPauseResume, SandboxPortExposure, SandboxPortsApi, SandboxPty, SandboxRef, SandboxSecretInjection, SandboxService, SandboxSnapshots, SandboxSnapshotsApi, SandboxVolumes, SandboxVolumesApi, SnapshotId, VolumeId, VolumeMount, attach, create, createVolume, destroy, destroySnapshot, destroyVolume, exposePort, list, listSnapshots, listVolumes, snapshot, Sandbox_d_exports as t };
+//# sourceMappingURL=Sandbox.d.mts.map