@evolvingmachines/daytona 0.0.55 → 0.0.56

package/dist/index.d.ts

@@ -1,23 +1,765 @@
+import { CreateSandboxFromImageParams, CreateSandboxFromSnapshotParams, Sandbox, ListSandboxesQuery } from '@daytonaio/sdk';
+
+/**
+ * GENERATED — DO NOT EDIT. `npm run generate:image-version` (repo root)
+ * rewrites this file from the evolve-all image build inputs under
+ * assets/docker/ (see assets/docker/image-digest.ts for the derivation).
+ * The value is content-addressed: same inputs → same tag, any input
+ * change → a new tag. The coherence test in
+ * packages/daytona/tests/unit/daytona-image-version.test.ts fails the
+ * suite whenever this checked-in copy is stale.
+ */
+declare const EVOLVE_IMAGE_VERSION = "c-880c264ce574";
+
 /**
  * Daytona Sandbox Provider
  *
- * @requires @daytonaio/sdk >= 0.134.0
+ * @requires @daytonaio/sdk >= 0.203.0 (cursor-based list pagination; Daytona
+ *   retired the page-numbered endpoint on 2026-06-25)
  *
  * Design principles:
  * - Mirror E2B provider interface for SDK compatibility
  * - Uses public Docker images via IMAGE_MAP
  * - Parallel structure to E2B provider
+ *
+ * Daytona-specific notes:
+ * - Network policy maps to Daytona's three network controls
+ *   (daytona.io/docs/en/network-limits): networkBlockAll (all egress
+ *   dropped), networkAllowList (IPv4 CIDRs only, max 10 entries,
+ *   DAYTONA_MAX_NETWORK_ALLOWLIST) and domainAllowList (DNS domains, `*.`
+ *   prefix wildcards allowed, max 20 entries, DAYTONA_MAX_DOMAIN_ALLOWLIST).
+ *   Per the docs "The options are mutually exclusive. Set at most one
+ *   non-empty value" — so CIDR destinations map to networkAllowList,
+ *   hostname/wildcard destinations map to domainAllowList, and a policy
+ *   mixing the two kinds is refused typed (mixed-allowlist) rather than
+ *   sent to a guaranteed 400. Destinations Daytona can never enforce
+ *   (IPv6, ports, non-prefix wildcards, over-cap lists) throw
+ *   DaytonaNetworkPolicyError instead of silently weakening the policy.
+ *   Hostnames are forwarded AS NAMES — nothing is DNS-resolved or pinned.
+ * - The `user` option is a CREATE-TIME OS user (Daytona's osUser field);
+ *   there is no per-exec user switch — the Daytona daemon runs commands as
+ *   the container's user (governed by the image's USER directive; default
+ *   images use "daytona" with passwordless sudo). `user: "root"` keeps the
+ *   image's default user and elevates every command through a `sudo -n`
+ *   wrapper instead (mirrors the Modal provider's su wrapper). File
+ *   operations always go through the Daytona daemon and are NOT elevated.
+ * - Private registry images (AWS ECR, GHCR, GCP Artifact Registry, ...)
+ *   require registry credentials pre-registered in the Daytona dashboard
+ *   (Registries page) — Daytona has no per-call image pull secret. Pull
+ *   failures for such images throw DaytonaImagePullError.
+ * - getInfo()/list() report the API's real createdAt timestamp (never a
+ *   fabricated client-side date); Daytona exposes no end timestamp, so
+ *   endAt is always undefined.
+ */
+
+/**
+ * Daytona's hard cap on network allowlist size (validated server-side too).
+ * Policies that resolve to more CIDRs throw DaytonaNetworkPolicyError.
+ */
+/**
+ * Minutes a STOPPED sandbox is kept before Daytona deletes it. Long enough that
+ * a stop nobody ordered leaves something to look at and something to collect
+ * from; short enough that it is never a way to hold billable state.
+ */
+declare const DAYTONA_AUTO_DELETE_GRACE_MINUTES = 10;
+declare const DAYTONA_MAX_NETWORK_ALLOWLIST = 10;
+/**
+ * Daytona's hard cap on domainAllowList size (network-limits docs: "Maximum
+ * entries: 20 comma-separated items"). Policies naming more domains throw
+ * DaytonaNetworkPolicyError.
+ */
+declare const DAYTONA_MAX_DOMAIN_ALLOWLIST = 20;
+/**
+ * How long a reactivated snapshot may take to come back before create() gives
+ * up. Daytona deactivates any snapshot unused for two weeks (official docs:
+ * "Snapshots automatically become inactive after 2 weeks of not being used"),
+ * so exists-but-inactive is the steady state of every image that shipped more
+ * than a fortnight before its next user — reactivation is a pull, not a build,
+ * and one that outlives this bound is a provider incident worth a loud error.
+ */
+declare const DAYTONA_SNAPSHOT_ACTIVATE_TIMEOUT_MS = 180000;
+/**
+ * How long a create that LOST a snapshot name race waits for the winner's
+ * build before giving up. Same budget the build path already spends on its own
+ * snapshot create and on the sandbox create that follows it ({ timeout: 600 }),
+ * and the same number Harbor waits — see
+ * REFERENCES/Harbor/src/harbor/environments/daytona/snapshots.py:306-311
+ * (`_wait_for_active`, `timeout: int = 600`).
+ */
+declare const DAYTONA_SNAPSHOT_CONFLICT_TIMEOUT_MS = 600000;
+/**
+ * Clocks of a STREAMED run (see awaitStreamedExit). The poll that reads the
+ * command's exit code backs off from pollMin to pollMax. A follow whose
+ * command has already ended is cut once it has been SILENT for drainMs —
+ * silence, never elapsed time, so a stream still delivering is never
+ * truncated. killGrace is what the caller's timeoutMs is widened by before a
+ * streamed run gives up, because withInBoxTimeout kills with `timeout -k 10`:
+ * the box may legitimately take ten seconds past the deadline to record a
+ * status. And a follow that has CLOSED means the command ended, so its record
+ * must catch up within settleMs — the only backstop a caller who passed no
+ * timeoutMs has, which is why it is generous rather than tight.
+ */
+declare const DAYTONA_STREAM_TIMINGS: {
+    pollMinMs: number;
+    pollMaxMs: number;
+    drainMs: number;
+    killGraceMs: number;
+    settleMs: number;
+};
+type DaytonaStreamTimings = typeof DAYTONA_STREAM_TIMINGS;
+/**
+ * Sandboxes requested per list fetch — the cursor API's per-page size
+ * (ListSandboxesQuery.limit bounds one fetch, never the total). Held at the
+ * value every provider in this lineup accepts, so one number is valid
+ * everywhere a fleet is enumerated.
+ */
+declare const DAYTONA_LIST_PAGE_SIZE = 100;
+/**
+ * Row ceiling for one enumeration — the same 10,000 sandboxes the old
+ * 100-pages-of-100 ceiling allowed, restated in rows because cursor pagination
+ * has no page numbers to count. A walk that reaches it stops and reports
+ * itself INCOMPLETE, because the one thing a fleet enumeration may never do is
+ * return a short list that reads like a whole one.
+ */
+declare const DAYTONA_MAX_LIST_SCAN = 10000;
+/** Why a network policy cannot be enforced by Daytona. */
+type DaytonaNetworkPolicyReason = 
+/**
+ * A wildcard NOT of the documented `*.domain` prefix form. Daytona's
+ * domainAllowList supports exactly one wildcard shape ("Prefix a domain
+ * with `*.` to allow the base domain and its subdomains"); any other
+ * placement cannot be expressed.
+ */
+"wildcard-hostname" | "ipv6-unsupported" | "port-unsupported" | "invalid-ipv4"
+/**
+ * An empty/whitespace-only destination, or one carrying a comma. Both wire
+ * allowlists are single comma-joined strings, so a blank entry would emit
+ * an empty allowlist — which Daytona reads, with blockAll:false, as
+ * UNRESTRICTED egress — and an embedded comma would smuggle extra entries
+ * past the 10/20 caps and corrupt the joined value. Rejected before
+ * classification so a sealed policy can never boot an open box.
  */
+ | "invalid-destination"
 /**
- * Wrap command with cwd and envs shell prefixes.
+ * The policy names both CIDR and domain destinations. Daytona keeps two
+ * allowlists — networkAllowList (CIDRs) and domainAllowList (names) — and
+ * its docs make them mutually exclusive: "Set at most one non-empty value.
+ * Sending a conflicting combination returns a 400 error." One policy can
+ * therefore hold IPs/CIDRs or hostnames, not both.
+ */
+ | "mixed-allowlist" | "allowlist-too-large"
+/**
+ * The ORGANIZATION is not allowed to set a sandbox-level network policy at
+ * all, whatever the policy says. Daytona gates this by plan tier:
+ * "Organizations on Tier 1 or Tier 2 cannot override network policy at the
+ * sandbox level" (Daytona docs, sandbox network configuration). It is a
+ * property of the account, not of the request, so no rewriting of the policy
+ * makes it succeed — the caller needs a tier upgrade or another provider.
+ */
+ | "org-tier-forbidden";
+/**
+ * Typed error for network policies Daytona cannot enforce.
+ *
+ * Daytona's controls (network-limits docs) are networkBlockAll, an IPv4-CIDR
+ * networkAllowList (max 10) and a DNS domainAllowList (max 20, `*.` prefix
+ * wildcards) — mutually exclusive, at most one non-empty. Anything that fits
+ * none of them is rejected loudly instead of silently weakening the
+ * sandbox's egress policy.
+ */
+declare class DaytonaNetworkPolicyError extends Error {
+    readonly reason: DaytonaNetworkPolicyReason;
+    /** The offending destination (absent for list-level violations). */
+    readonly destination?: string;
+    constructor(reason: DaytonaNetworkPolicyReason, message: string, destination?: string);
+}
+/**
+ * Typed error for image pull failures on private registries.
+ *
+ * Daytona has no per-call image pull secret: the registry must be
+ * pre-registered in the Daytona dashboard BEFORE creating the sandbox
+ * (dashboard → Registries → Add Registry) — username/password for GHCR, GCP
+ * Artifact Registry or private Docker Hub, and for AWS ECR a cross-account
+ * IAM role ARN Daytona assumes server-side (its docs: "Password is not used
+ * for ECR").
+ */
+declare class DaytonaImagePullError extends Error {
+    /** The image reference that failed to pull. */
+    readonly image: string;
+    constructor(image: string, cause?: unknown);
+}
+/**
+ * Typed error for create-time sizing requests an EXISTING snapshot cannot
+ * honor. Daytona pins cpu/memory/disk on the SNAPSHOT at build time;
+ * create-from-snapshot has no resources parameter, so a `resources` request
+ * against a cached snapshot would be silently ignored. Per the provider law
+ * (reject what you cannot enforce) it is refused loudly instead: pre-build a
+ * snapshot with the desired sizing under its own name, or drop `resources`.
+ */
+/**
+ * @deprecated No longer thrown. @daytonaio/sdk 0.203.0 grew a real
+ * `Resources.gpuType` field, so `resources.gpuTypes` is now FORWARDED on the
+ * snapshot-build path instead of refused (Daytona validates the type names
+ * server-side). Sizing against an EXISTING snapshot — GPU type included —
+ * still throws DaytonaResourcesError like every other pinned field. The class
+ * stays exported so callers with `instanceof` checks keep compiling.
+ */
+declare class DaytonaGpuTypeError extends Error {
+    /** The snapshot/image the create named. */
+    readonly snapshot: string;
+    constructor(snapshot: string);
+}
+declare class DaytonaResourcesError extends Error {
+    /** The existing snapshot whose pinned sizing cannot be overridden. */
+    readonly snapshot: string;
+    constructor(snapshot: string);
+}
+/**
+ * Typed error for an idle timeout Daytona cannot take as a SEPARATE bound.
+ * Daytona has no absolute lifetime at all: auto-stop is an inactivity clock and
+ * it is the only one there is, so `timeoutMs` is already mapped onto it. A
+ * second option pointing at the same knob could only contradict the first.
+ */
+declare class DaytonaBootCommandError extends Error {
+    constructor();
+}
+declare class DaytonaIdleTimeoutError extends Error {
+    constructor();
+}
+/**
+ * Where a boot is, read off Daytona's own sandbox state. 'image_pull' is
+ * every state in which the runner is still MATERIALIZING THE IMAGE —
+ * `pending_build` (queued for the builder), `building_snapshot` (the
+ * declarative build, whose FROM step is where the base image is pulled) and
+ * `pulling_snapshot` (a built snapshot being pulled onto the runner) — and
+ * 'boot' is everything else: the container start, and the stretch before the
+ * provider has reported any state at all. Two words only, because those are
+ * the two facts a caller acts on differently: a pull that is moving is
+ * allowed to be slow; a container that is silent is not.
+ */
+type DaytonaBootPhase = "image_pull" | "boot";
+/** The boot phase a reported sandbox state belongs to (see DaytonaBootPhase). */
+declare function daytonaBootPhaseOf(state: string | null | undefined): DaytonaBootPhase;
+/**
+ * One thing the provider reported while a create was in flight. `signal`
+ * names WHICH fact moved: the sandbox row's state changed, or the build log
+ * delivered a line (`line`, one line, trimmed — a chunk from the stream is
+ * split on newlines so a multi-line chunk is several events).
+ */
+interface DaytonaBootProgress {
+    signal: "state" | "build_log";
+    phase: DaytonaBootPhase;
+    /** Daytona's sandbox state as last read; null until the row has been found. */
+    state: string | null;
+    sandboxId: string | null;
+    line?: string;
+}
+/**
+ * Thrown by createSandboxObserved when its `signal` aborted: the create was
+ * abandoned, the half-made box deleted best-effort, and this names where the
+ * boot was at that moment. The DECISION to abort is the caller's — this
+ * package reports progress and honours the abort; it never judges silence.
+ */
+declare class DaytonaBootAbortedError extends Error {
+    readonly phase: DaytonaBootPhase;
+    readonly state: string | null;
+    readonly sandboxId: string | null;
+    constructor(phase: DaytonaBootPhase, state: string | null, sandboxId: string | null);
+}
+/**
+ * The label createSandboxObserved stamps on the box it creates — a fresh UUID
+ * per create — so the box is FINDABLE (daytona.list({ labels })) from the
+ * moment the control plane has a row for it, while the SDK's create promise
+ * is still opaque. Beside the caller's own labels, never in place of them.
+ */
+declare const DAYTONA_BOOT_LABEL = "evolve_boot";
+/** How often the in-flight box's state is re-read. Measured boots move on a scale of seconds, not milliseconds. */
+declare const DAYTONA_BOOT_POLL_MS = 5000;
+interface DaytonaObservedCreateOptions {
+    /** Every state change and build-log line, as it is observed. Must not throw. */
+    onProgress?: (progress: DaytonaBootProgress) => void;
+    /**
+     * Aborting it ends the wait: the create promise is abandoned, the box (if
+     * the row exists yet) is deleted best-effort, and the call rejects with
+     * DaytonaBootAbortedError. Without it the wait is unbounded — the SDK's own
+     * wall clock is OFF here (see createSandboxObserved), so a caller that
+     * passes no signal must be sure it wants to wait forever.
+     */
+    signal?: AbortSignal;
+    /** Poll period for the state read; default DAYTONA_BOOT_POLL_MS. */
+    pollMs?: number;
+}
+/** The slice of the Daytona client an observed create drives — structural, so tests can fake it. */
+interface DaytonaBootClient {
+    create(params: CreateSandboxFromImageParams | CreateSandboxFromSnapshotParams, options: {
+        timeout: number;
+        onSnapshotCreateLogs?: (chunk: string) => void;
+    }): Promise<Sandbox>;
+    list(query: ListSandboxesQuery): AsyncIterable<Sandbox>;
+}
+/**
+ * THE BOOT-PROGRESS HOOK. `Daytona.create()` is one opaque promise: it POSTs
+ * the sandbox, polls its state, streams the build log and waits for
+ * 'started' (@daytonaio/sdk 0.203 Daytona.create) — and says nothing to its
+ * caller until it resolves or its own wall clock (`timeout`, default 60 s)
+ * gives up. That silence is the whole problem for a caller that must tell a
+ * WEDGED boot from a SLOW one: a cold declarative build of a multi-GB image
+ * legitimately runs for ten minutes (the runner pulls the base image inside
+ * the build's FROM step), and a fixed wall wide enough to survive it is a
+ * wall that also waits ten minutes on a request that will never answer.
+ *
+ * This runs the same create and, beside it, READS what the provider reports:
+ * the sandbox row — found by the DAYTONA_BOOT_LABEL stamped at create, then
+ * refreshed every `pollMs` — and the build-log stream (the SDK's
+ * onSnapshotCreateLogs). Every state change and every log line is one
+ * DaytonaBootProgress to `onProgress`; the caller decides what silence means
+ * and says so through `signal`. The SDK's own wall clock is switched OFF
+ * (`timeout: 0` — "0 means no timeout", daytona.io/docs/en/typescript-sdk/
+ * daytona) because the caller watching progress must be the only clock.
+ *
+ * ON ABORT the create promise is abandoned and the box is deleted
+ * best-effort — the row known now, and whatever the abandoned create still
+ * yields later. Deleting it is also what ends the SDK's orphaned wait: its
+ * state polls 404 and reject. The SDK's own timeout leaves the box behind
+ * instead (a trial that timed out its boot on 2026-09-01 settled with no
+ * sandbox id while the box went on building).
+ *
+ * MEASURED 2026-09-01 (alpine:3.20, declarative, one unique layer): the row
+ * was listable by label 2.5 s after the request, in state 'building_snapshot';
+ * the log callback carried BuildKit's lines including the base-image pull
+ * step ('#4 [1/1] FROM docker.io/library/alpine:3.20@sha256:…'); the state
+ * moved 'building_snapshot' → 'started' at 11 s and the create resolved at
+ * 14 s. The row's `updatedAt` moved only with the state, so it is not read.
+ */
+declare function createSandboxObserved(client: DaytonaBootClient, params: CreateSandboxFromImageParams | CreateSandboxFromSnapshotParams, options?: DaytonaObservedCreateOptions): Promise<Sandbox>;
+/**
+ * Typed error for a snapshot that exists but could not be brought back to
+ * `active`. This is a final verdict, not a build trigger: the snapshot IS
+ * there, so rebuilding under the same name can only fail on the name conflict
+ * and then mask the real problem behind a slow direct image pull.
+ */
+declare class DaytonaSnapshotActivationError extends Error {
+    /** The snapshot that would not activate. */
+    readonly snapshot: string;
+    constructor(snapshot: string, detail: string);
+}
+/**
+ * The slice of the Daytona client the reactivation path touches — structural,
+ * so the unit tests can drive it with a plain mock.
+ */
+interface SnapshotActivationClient {
+    snapshot: {
+        get(name: string): Promise<{
+            state?: string;
+        }>;
+        activate(snapshot: unknown): Promise<{
+            state?: string;
+        }>;
+    };
+}
+/**
+ * Bring an exists-but-inactive snapshot back to `active`, or say loudly why
+ * not. Activation is asynchronous on Daytona's side — the activate call may
+ * answer with a transitional state (`pulling`) — so the result is polled until
+ * it lands on `active`, a terminal failure state, or the deadline.
+ */
+declare function activateSnapshot(client: SnapshotActivationClient, name: string, snapshot: {
+    state?: string;
+}, timing?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    state?: string;
+}>;
+/**
+ * Typed error for a name race this run could not wait out: the winner never
+ * finished inside the budget, or the wait itself became impossible (rejected
+ * credentials, a control plane that stopped answering). Either way there is
+ * nothing to reuse and nothing has failed either — the only honest answer is
+ * to say so.
+ *
+ * Deliberately NOT a direct-pull trigger: a second copy of a build that is
+ * still running would double the spend on the same image and hide a provider
+ * incident behind a slow success.
+ */
+declare class DaytonaSnapshotConflictError extends Error {
+    /** The contended snapshot name. */
+    readonly snapshot: string;
+    constructor(snapshot: string, detail: string);
+}
+/**
+ * The wait's answer when the NAME IS GONE. A healer (this one, or the same code
+ * in another process) can delete a dead snapshot while a second caller is
+ * waiting on it, and that waiter must not read the resulting 404s as the
+ * control plane failing — the thing it was waiting for cannot arrive, and the
+ * name is now free to build. A symbol rather than a state string so it can
+ * never collide with a state Daytona invents later.
+ */
+declare const DAYTONA_SNAPSHOT_GONE: unique symbol;
+/**
+ * The slice of the Daytona client the conflict wait touches — structural, so
+ * the unit tests can drive it with a plain mock.
+ */
+interface SnapshotWaitClient {
+    snapshot: {
+        get(name: string): Promise<{
+            state?: string;
+        } | undefined>;
+    };
+}
+/**
+ * MAY THIS PROVIDER DELETE THE SNAPSHOT BEHIND THIS NAME? — our answer to the
+ * question Harbor answers with SnapshotPolicy.
+ *
+ * Harbor deletes an ERROR-state snapshot and rebuilds it under AUTO, and
+ * refuses loudly under EXPLICIT, where the name is one the USER supplied for a
+ * snapshot they manage
+ * (REFERENCES/Harbor/src/harbor/environments/daytona/snapshots.py:200-212).
+ * This provider has no policy flag, so the split has to be derived from the
+ * name itself — and there is a sharper criterion available than "who typed it":
+ * CAN WE PUT IT BACK?
+ *
+ * THE TEST IS ON THE RESOLVED IMAGE, NOT THE NAME, and that distinction is the
+ * whole of it. The build path creates a snapshot from
+ * `IMAGE_MAP[imageName] ?? imageName`, so the question "can we rebuild it" is a
+ * question about THAT ref, and Daytona will only build one carrying a real tag
+ * or digest. Testing the name instead got the platform's own legacy alias
+ * exactly wrong: `evolve-all` is an IMAGE_MAP key, which looked like proof we
+ * own it — but it resolves to the UNTAGGED `evolvingmachines/evolve-all`, which
+ * Daytona refuses to build. Delete would have succeeded, the rebuild would have
+ * been refused, and the name would be gone: the precise harm this predicate
+ * exists to prevent, committed on our own default. Reading the resolved ref
+ * also closes the blind spot a bare `includes("/")` had, since a registry path
+ * with no tag is just as unbuildable.
+ *
+ * When the ref does not qualify, the name belongs to a snapshot record that
+ * exists only in the user's account — built by their own tooling,
+ * unreproducible from here — and deleting it would throw away something nothing
+ * in this process could recreate. That is exactly the harm Harbor's EXPLICIT
+ * branch refuses, arrived at without a policy the caller must remember to set.
+ *
+ * Bare labels (`eval-env-<hash>`, `my-team-env`) are excluded and STILL HEALED,
+ * just not here: the layer that authored the name owns rebuilding it. The eval
+ * platform deletes and rebuilds its own `eval-env-*` aliases in its image
+ * preparation path (swarm_dashboard lib/evaluations/worker/templates.ts,
+ * commit 3f51b8d, merged to project-sable as 6ee52ed) — the same rule this
+ * function states, applied one floor up.
+ *
+ * A REFINEMENT DELIBERATELY NOT BUILT: the sharpest provenance seam available
+ * is `config.snapshotName` — a name the CALLER pinned is explicit by
+ * construction, where the derived default (`evolve-all-<version>`) is ours by
+ * construction. Threading that distinction from the constructor to here would
+ * beat any inference from the ref, and it is where this should go if the
+ * question is ever reopened. It is not built today because the resolved-ref
+ * test already refuses everything unbuildable, which is the harm that matters.
+ */
+declare function providerCanRebuildSnapshot(imageName: string): boolean;
+/**
+ * Does this snapshot-create failure mean "someone else already owns this
+ * name"? Harbor decides the same question on the same evidence — lowercased
+ * message contains "already exists" or "conflict"
+ * (REFERENCES/Harbor/src/harbor/environments/daytona/snapshots.py:281-283) —
+ * and this adds the HTTP status the TS SDK carries on its error objects, which
+ * the Python side does not surface as plainly.
+ *
+ * Kept to those signals on purpose: anything looser (a bare "409" anywhere in
+ * the text, say) would classify an unrelated build failure as a race and make
+ * this create wait ten minutes for a winner that does not exist.
+ */
+declare function isSnapshotNameConflict(err: unknown): boolean;
+/**
+ * Wait for the winner of a snapshot name race to finish, and report which way
+ * it went.
+ *
+ * WAIT-ON-CONFLICT, Harbor's law: when snapshot.create loses the name, the
+ * image is already being built by the process that won it, so the right move
+ * is to wait for that build and then use it — never to start a second, slower
+ * copy of the same work. Harbor does exactly this at
+ * REFERENCES/Harbor/src/harbor/environments/daytona/snapshots.py:281-288
+ * (conflict -> `_wait_for_active`), with the poll loop at :306-332.
+ *
+ * Four deliberate adaptations to this provider's idiom:
+ *   - GET FIRST, then sleep. Harbor sleeps a full interval before its first
+ *     look; most races here are lost to a build that finished seconds ago, and
+ *     a wait that starts by looking costs nothing when the answer is already
+ *     "active". Same loop shape as activateSnapshot() above.
+ *   - A failed GET is not fatal, EXCEPT a not-found, which is an answer. The
+ *     winner's snapshot can be briefly unreadable mid-build, so an ordinary
+ *     poll error is logged and retried (Harbor warns and continues too,
+ *     :326-327) — unlike the activation poll, where a failed GET IS the
+ *     verdict. A 404 is different in kind: since this file gained a healer,
+ *     the ordinary reason a contended name stops resolving is that another
+ *     process cleared a corpse, so the FIRST not-found resolves the wait as
+ *     DAYTONA_SNAPSHOT_GONE rather than counting toward the
+ *     control-plane-is-down limit.
+ *
+ *     THE COST OF THAT CHOICE, ACCEPTED KNOWINGLY: a TRANSIENT 404 during a
+ *     legitimate build ends the wait early, and the caller builds a name whose
+ *     real owner still holds it — one doomed create, then the existing
+ *     fallback. Self-correcting, and cheap. Requiring two consecutive 404s
+ *     would remove it, at the price of an extra poll interval on what is now
+ *     the COMMON case; the heal is meant to be fast, so the rare doomed create
+ *     is the better trade.
+ *   - WAIT ONLY ON A WHITELIST of in-flight states, where Harbor waits on
+ *     everything that is not ACTIVE or ERROR (:316-323). Harbor's shape leaves
+ *     `inactive`, `removing` and any future state polling for the whole budget
+ *     to no purpose; here anything outside DAYTONA_SNAPSHOT_IN_FLIGHT_STATES
+ *     is returned as an answer for the caller to route.
+ *   - A DEAD WINNER IS RETURNED, NOT RAISED, where Harbor raises
+ *     SandboxBuildFailedError (:321-323). Harbor's caller is wrapped in an
+ *     outer retry that owns the recovery; this provider's caller owns it
+ *     directly, and its recovery is the direct image pull — so the state has
+ *     to come back as data. What IS raised here is the opposite case: a wait
+ *     that could not be completed at all (budget exhausted, credentials
+ *     refused, control plane silent), because none of those leave a sane
+ *     fallback.
+ *
+ * Returns the resolving snapshot record: `active` means reuse it, `inactive`
+ * means reuse it after reactivation, anything else means the winner's build is
+ * not going to produce a snapshot and the caller may fall back.
+ * Throws DaytonaSnapshotConflictError when the wait itself cannot finish.
+ */
+declare function waitForSnapshotConflictWinner(client: SnapshotWaitClient, name: string, timing?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    state?: string;
+} | typeof DAYTONA_SNAPSHOT_GONE>;
+/**
+ * Wrap command with cwd and envs shell prefixes, and (for user "root") a
+ * `sudo -n` elevation wrapper.
  *
  * Daytona's executeSessionCommand doesn't support cwd or envs natively,
  * so we inline them as shell commands. Values are single-quoted to handle
  * spaces and special characters safely.
+ *
+ * Daytona has no per-exec user switch: commands run as the container's OS
+ * user (image USER directive; default "daytona" with passwordless sudo).
+ * When the sandbox user is "root", the fully wrapped command is base64
+ * encoded and piped through `sudo -n bash` — base64 avoids escaping issues
+ * and `-n` fails fast (typed non-zero exit) instead of hanging on a
+ * password prompt if the image lacks passwordless sudo.
  */
-declare function wrapCommand(command: string, cwd?: string, envs?: Record<string, string>): string;
-/** @internal Test-only export for unit testing wrapCommand logic. */
-declare const _testWrapCommand: typeof wrapCommand;
+/**
+ * Enforce the timeout INSIDE the box, on BOTH execution paths. Daytona has no
+ * fixed sandbox lifetime, and its auto-stop timer measures INACTIVITY over SDK
+ * interactions ("no new events ... state changes or interactions with the
+ * Sandbox through the sdk"), so it bounds nothing that matters here: while a
+ * client is polling, that polling is itself an interaction and resets the clock,
+ * and once the client is gone the box still runs for the whole remaining
+ * interval before it merely STOPS. e2b and Modal both take an absolute,
+ * server-side lifetime; Daytona takes none.
+ *
+ * The session API's timeout argument does not close the hole on either path.
+ * spawn launches with runAsync:true, where that argument bounds the *call*, not
+ * the process, and the only deadline is a client-side poll in wait(). run blocks
+ * with runAsync:false, where the argument is documented as how long to WAIT for
+ * the command — and it is this process that waits, so a wait that ends because
+ * this process died is not a kill.
+ *
+ * coreutils `timeout` closes it for both: the kernel kills the command whether
+ * or not anything is still watching, and exits 124 — the same code wait()'s own
+ * deadline and the e2b adapter return, so a timeout means one thing across every
+ * provider and both paths. The script is passed base64 -> file so no quoting of
+ * the caller's command is ever attempted, and a box without coreutils degrades
+ * to the un-timed run rather than failing outright (the client-side deadlines
+ * still cover the case where a client is alive to enforce them).
+ *
+ * IT FAILS CLOSED ON A BAD DECODE, and that is not a nicety. `>` creates the
+ * file before the pipeline runs, so on an image with no `base64` the decode
+ * fails and leaves a ZERO-BYTE script — and `bash <empty>` exits 0 having
+ * printed nothing. This wrapper would then have turned a command that used to
+ * fail loudly into one that reports success with empty output, on exactly the
+ * images where it breaks: the eval artifact listing is itself a
+ * `find ... | base64 -w0`, so a box missing base64 failed that listing outright
+ * before this wrapper existed, and would afterwards have returned an empty
+ * listing instead — no files, no patch, and a clean exit all the way up. So the
+ * decode is chained with `&&` and the script is size-checked before bash is
+ * handed it; either way out is exit 126, which is nonzero and therefore visible
+ * to every caller that checks.
+ */
+declare function withInBoxTimeout(wrapped: string, timeoutSec?: number): string;
+/**
+ * NOTHING IS APPENDED TO THE CALLER'S LAST LINE. The command goes inside a
+ * brace group whose closing brace opens a line of its own, so what follows is
+ * never read as a continuation of whatever the command ended with. Appending
+ * `; ...` directly broke three shapes, all measured:
+ *
+ *   a command ending in a NEWLINE (every multi-line template literal) —
+ *     `\n; __evolve_eos=$?` is a syntax error, exit 2
+ *   a command ending in `&` — `& ;` is a syntax error and the command NEVER RAN
+ *   a HEREDOC whose terminator is the command's last line — the appended text
+ *     became part of the heredoc BODY: no error, exit 0, corrupt payload. That
+ *     is the shape of the managed-secret proxy readiness probe (agent.ts), and
+ *     it turned a healthy proxy into "failed to start".
+ *
+ * The group needs two guards of its own, both measured against /bin/sh,
+ * /bin/bash and /bin/dash:
+ *
+ *   a leading `:` so the body is never EMPTY. A comment-only command
+ *     (`# nothing`) otherwise leaves `{ # nothing\n}` — "syntax error near
+ *     unexpected token `}'", exit 2, where the caller's own shell would have
+ *     done nothing and exited 0. It runs BEFORE the command, so the status the
+ *     group reports is still the command's own.
+ *   a BLANK LINE before the closing brace, to be eaten by a command that ends
+ *     in a dangling backslash. That backslash continues onto whatever line
+ *     comes next; the blank line is what it consumes instead of the `}`, and
+ *     `echo HI \` then runs as the caller's shell would run it — exit 0, "HI",
+ *     with the exit code of a failing one (`false \` -> 1) still its own.
+ *
+ * WHAT STILL FAILS, LOUDLY: an UNTERMINATED heredoc (`cat <<'EOF'` with no
+ * EOF line). Its body swallows everything that follows, including the closing
+ * brace, so the command is a syntax error — exit 2, no output, the shell's own
+ * message on stderr. No text can fix that from out here: anything added lands
+ * inside the heredoc. A shell run of the same input without a wrapper prints
+ * the body and exits 0, so this is the one shape the sentinel changes, and it
+ * changes it to a loud failure rather than a quiet wrong answer.
+ */
+declare function withEndOfOutputSentinel(command: string, token: string): string;
+/**
+ * Shed the sentinel, and the terminator the transport put after it, from a
+ * settled stream.
+ *
+ * ONLY AT THE END, because that is the only place the sentinel can be: it is
+ * the last thing the command prints. A token anywhere else in the output is
+ * the caller's own bytes — `ps` shows this very command line, and `sh -x`
+ * traces the printf that writes it — and deleting those would be corruption,
+ * silent and impossible to debug.
+ */
+declare function stripEndOfOutputSentinel(text: string, token: string): string;
+/**
+ * A settled log read with the sentinel shed — from STDOUT only, because that is
+ * the only stream the command prints one to. Shedding anything from stderr
+ * could only ever delete bytes the command itself wrote (`sh -x` traces the
+ * printf that writes the token, and that trace goes to stderr).
+ */
+declare function settledStreams(logs: unknown, token: string): {
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Shed the sentinel from a stream still arriving, without holding back output
+ * that is merely on its way.
+ *
+ * Same rule as the settled read — only the end of the stream can be the
+ * sentinel — applied to bytes still coming: what could still GROW INTO it (the
+ * longest tail that is a prefix of `<token>\n`) waits for the rest, and
+ * everything else goes straight through, so a chunk that cannot be the start
+ * of a sentinel is never delayed. Nothing mid-stream is ever dropped.
+ */
+declare function createSentinelFilter(token: string, emit: (chunk: string) => void): {
+    push(chunk: string): void;
+    /** The stream is over: what was held is the sentinel, or it was output after all. */
+    flush(): void;
+};
+declare function wrapCommand(command: string, cwd?: string, envs?: Record<string, string>, user?: string): string;
+/** Daytona create() params derived from Evolve's provider-neutral network policy. */
+interface DaytonaNetworkCreateParams {
+    networkBlockAll?: boolean;
+    networkAllowList?: string;
+    domainAllowList?: string;
+}
+/**
+ * Daytona `updateNetworkSettings()` params. Every field is stated on this
+ * path, never omitted — see mapNetworkPolicyForUpdate for why an omitted field
+ * is a stale field here, which is not true at create.
+ */
+interface DaytonaNetworkUpdateParams {
+    networkBlockAll: boolean;
+    networkAllowList: string;
+    domainAllowList: string;
+}
+/**
+ * Map Evolve's provider-neutral network policy onto Daytona create() params
+ * (daytona.io/docs/en/network-limits).
+ *
+ * - outbound "open" (or no policy)     → no restrictions
+ * - outbound "blocked", no allowlist   → networkBlockAll: true (all egress dropped)
+ * - outbound "blocked" + IP/CIDR list  → networkAllowList (comma-separated IPv4
+ *   CIDRs; bare IPv4 gets /32; max 10 entries)
+ * - outbound "blocked" + hostname list → domainAllowList (comma-separated DNS
+ *   names, forwarded VERBATIM — Daytona enforces the domain layer itself, so
+ *   nothing is DNS-resolved or pinned here; `*.domain` prefix wildcards allow
+ *   the base domain and its subdomains; max 20 entries)
+ *
+ * The two allowlists are mutually exclusive on Daytona's wire ("Set at most
+ * one non-empty value. Sending a conflicting combination returns a 400
+ * error"), so a policy mixing CIDR and hostname destinations is refused typed
+ * (mixed-allowlist) with the fix named, rather than sent to a guaranteed 400.
+ * Destinations no list can express — IPv6, host:port, malformed IPv4, a
+ * wildcard anywhere but the `*.` prefix, an empty/whitespace or
+ * comma-carrying entry, an over-cap list — throw
+ * DaytonaNetworkPolicyError; the policy is never silently weakened.
+ *
+ * PUBLIC EXPORT (a security seal, not a helper): external callers that build
+ * Daytona create() params themselves — the eval worker's declarative boot
+ * path is one — reuse this as the ONE opinion on how destinations become
+ * wire fields, rather than growing a driftable second mapper.
+ */
+declare function mapNetworkPolicy(network?: SandboxCreateOptions["network"]): DaytonaNetworkCreateParams;
+/**
+ * The same policy expressed for the RUNTIME switch
+ * (`sandbox.updateNetworkSettings`), which differs from create in one way that
+ * matters: it edits a box that already HAS a policy, so every field the new
+ * policy does not set must be cleared by hand or the old value survives.
+ *
+ * Daytona keeps two independent allowlists (`networkAllowList` for CIDRs,
+ * `domainAllowList` for names), and mapNetworkPolicy writes exactly one of
+ * them per policy — but the box may have been created elsewhere, and the OTHER
+ * allowlist left behind would silently widen a policy we believe is narrow.
+ * So the update always states BOTH: the one it means, and "" for the one it
+ * does not — which also keeps the wire on the docs' "at most one non-empty
+ * value" law.
+ *
+ * Upstream does exactly this, and only on the apply path: harbor
+ * daytona/environment.py:1313-1343 (`_network_kwargs(..., clear_public_allowlist=True)`,
+ * called from `_apply_network_policy` at :1508-1514) with the comment
+ * "Daytona treats block-all as authoritative over stored allowlists. Clear
+ * stale allowlist fields when reopening public access or switching between
+ * domain and CIDR allowlists."
+ */
+declare function mapNetworkPolicyForUpdate(network?: SandboxCreateOptions["network"]): DaytonaNetworkUpdateParams;
+/**
+ * Does this refusal mean "your organization may not set sandbox network
+ * policy" rather than "this request was malformed"?
+ *
+ * Deliberately narrow. A bare 403 is NOT enough on its own: the same status
+ * covers a revoked API key, and calling that a tier problem would send a
+ * caller to the billing page over a credential. The verdict needs the status
+ * AND language naming the tier/plan/permission for this specific capability —
+ * or, without a status, an unmistakable phrase. Anything else stays
+ * unclassified and propagates verbatim, which is the honest outcome for a
+ * refusal we do not recognize.
+ */
+declare function isNetworkPolicyTierRefusal(err: unknown): boolean;
+/**
+ * Registry host of an image reference, or undefined for Docker Hub images.
+ * A reference carries a registry host only when its first path segment
+ * contains "." or ":" or is "localhost" (Docker's own heuristic).
+ */
+declare function imageRegistryHost(image: string): string | undefined;
+/** Fields we read off a Daytona SDK sandbox to build a SandboxInfo. */
+interface DaytonaSandboxLike {
+    id: string;
+    name?: string;
+    snapshot?: string;
+    labels?: Record<string, string>;
+    createdAt?: string;
+}
+/**
+ * Build a SandboxInfo from a Daytona sandbox entity. Timestamps come from
+ * the API's createdAt (never fabricated client-side; empty string when the
+ * API omits it). Daytona exposes no end timestamp, so endAt is always
+ * undefined.
+ */
+declare function toSandboxInfo(sandbox: DaytonaSandboxLike): SandboxInfo;
+/**
+ * Map a Daytona sandbox state onto Evolve's list() filter states.
+ * "started" → running; "stopped"/"archived"/"paused" → paused (our pause()
+ * stops the sandbox; Daytona 0.203.0 added a native "paused" state for
+ * pause-capable sandbox classes, and a box resting in it is paused by any
+ * reading); transitional and terminal states match no filter.
+ */
+declare function daytonaStateToEvolveState(state?: string): "running" | "paused" | undefined;
 /** Result of a completed sandbox command */
 interface SandboxCommandResult {
     exitCode: number;
@@ -46,6 +788,7 @@ interface SandboxInfo {
     name?: string;
     metadata: Record<string, string>;
     startedAt: string;
+    /** End time (undefined for running sandboxes; Daytona never exposes one) */
     endAt?: string;
 }
 /** File or directory entry info */
@@ -74,6 +817,19 @@ interface SandboxResources {
     memory?: number;
     /** Disk in GB (default: 10) */
     disk?: number;
+    /**
+     * GPU reservation (count). Applied when a SNAPSHOT IS BUILT (Daytona
+     * allocates GPU at snapshot build; GPU machines are tier-gated on Daytona's
+     * side) — against an existing snapshot it throws DaytonaResourcesError like
+     * every other pinned sizing field.
+     */
+    gpu?: number;
+    /**
+     * Acceptable GPU types (Daytona's GpuType names, e.g. "H100", "H200",
+     * "RTX-PRO-6000"). Forwarded on the build path — Daytona validates the
+     * names server-side — and refused on an existing snapshot alongside `gpu`.
+     */
+    gpuTypes?: string[];
 }
 /** Options for creating a sandbox */
 interface SandboxCreateOptions {
@@ -81,16 +837,106 @@ interface SandboxCreateOptions {
     envs?: Record<string, string>;
     metadata?: Record<string, string>;
     timeoutMs?: number;
+    /**
+     * REJECTED with DaytonaIdleTimeoutError — not for want of an idle clock, but
+     * because auto-stop is the ONLY clock Daytona has and `timeoutMs` is already
+     * mapped onto it (autoStopInterval). Two options, one knob.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * REJECTED with DaytonaBootCommandError. Daytona never runs an image
+     * entrypoint or any argv at boot, so a create-time boot command cannot be
+     * honored. The boot is already inert; exec the process after create.
+     */
+    bootCommand?: string[];
     workingDirectory?: string;
-    /** Resource allocation for the sandbox */
+    /**
+     * Resource allocation (cpu cores, memory GiB, disk GiB), applied when a
+     * SNAPSHOT IS BUILT for the image (Daytona pins sizing on the snapshot).
+     * When the named snapshot ALREADY exists it cannot be resized at create —
+     * declaring resources then throws DaytonaResourcesError rather than
+     * silently ignoring them (pre-build a sizing-addressed snapshot instead).
+     */
     resources?: SandboxResources;
+    /**
+     * Provider-neutral outbound network policy
+     * (daytona.io/docs/en/network-limits). "blocked" with no
+     * allowedDestinations drops all egress. With allowedDestinations, the list
+     * maps onto exactly one of Daytona's two mutually exclusive allowlists:
+     * IPs/CIDRs → networkAllowList (IPv4 CIDRs, bare IPs sent as /32, max 10);
+     * hostnames and `*.domain` prefix wildcards → domainAllowList (max 20),
+     * forwarded VERBATIM as names — Daytona enforces the domain layer itself,
+     * nothing is DNS-resolved or pinned here. A list mixing CIDRs with
+     * hostnames, and any destination neither list can express — IPv6,
+     * host:port, malformed IPv4, a wildcard anywhere but the `*.` prefix, a
+     * blank or comma-carrying entry, an over-cap list — throws
+     * DaytonaNetworkPolicyError rather than silently weakening the policy.
+     * Note: on Daytona orgs below Tier 3, org network policy overrides
+     * per-sandbox settings server-side.
+     */
+    network?: {
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    };
+    /**
+     * Every policy `updateNetwork()` may later be asked for on this box.
+     *
+     * ACCEPTED AND IGNORED HERE, deliberately. It exists because on modal the
+     * create call decides whether switching is possible at all, and a box built
+     * the blunt way can never be widened. Daytona has no such constraint — it
+     * switches freely at any time — so this changes nothing about the sandbox
+     * it creates.
+     *
+     * Declared anyway so the option means the SAME thing in every provider
+     * package: a caller reading these types must not conclude that Daytona
+     * cannot do phase switching because the option is missing here.
+     */
+    phaseNetworkPolicies?: Array<{
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    }>;
+    /**
+     * OS user for the sandbox, applied at CREATE time (Daytona's osUser field)
+     * — Daytona has no per-exec user switch, so the user commands actually run
+     * as is governed by the sandbox image (USER directive; default Daytona
+     * images use "daytona" with passwordless sudo). A non-root value must
+     * exist in the image. Pass "root" to keep the image's default user and
+     * elevate every command through a `sudo -n` wrapper instead (requires
+     * passwordless sudo in the image; default images have it). File operations
+     * go through the Daytona daemon and are NOT elevated.
+     */
+    user?: string;
+    /** Home directory used by the SDK for agent config paths; not consumed by the provider. */
+    homeDir?: string;
 }
 /** Options for listing sandboxes */
 interface SandboxListOptions {
+    /** "running" matches Daytona "started"; "paused" matches "stopped"/"archived". */
     state?: ("running" | "paused")[];
     metadata?: Record<string, string>;
     limit?: number;
 }
+/**
+ * A COMPLETE (or admittedly incomplete) enumeration of the organization's fleet.
+ *
+ * `complete` is the load-bearing field. Callers that need a whole fleet —
+ * orphan sweeps, lifecycle reconciliation — read a sandbox's ABSENCE from the
+ * list as evidence it is gone, so a truncated page and a small fleet must never
+ * be the same answer. `complete: false` means leave every row alone.
+ */
+interface SandboxListPage {
+    sandboxes: SandboxInfo[];
+    complete: boolean;
+    /**
+     * Fetch units consumed: rows scanned from the cursor stream (before
+     * filtering). Cursor pagination has no page numbers to count — and the modal
+     * provider already reports item counts here — so "pages" reads as "units of
+     * enumeration work", kept under this name because the field is shared
+     * provider-neutral surface.
+     */
+    pagesFetched: number;
+    error?: string;
+}
 /** Command execution capabilities */
 interface SandboxCommands {
     run(command: string, options?: SandboxRunOptions): Promise<SandboxCommandResult>;
@@ -106,6 +952,8 @@ interface SandboxFiles {
         path: string;
         data: string | Buffer | ArrayBuffer | Uint8Array;
     }>): Promise<void>;
+    /** Upload a local file by path, without buffering it whole */
+    writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
     makeDir(path: string): Promise<void>;
     exists(path: string): Promise<boolean>;
     list(path: string): Promise<FileInfo[]>;
@@ -122,6 +970,8 @@ interface SandboxInstance {
     getInfo(): Promise<SandboxInfo>;
     kill(): Promise<void>;
     pause(): Promise<void>;
+    /** Replace the outbound network policy of the running sandbox. */
+    updateNetwork(network: SandboxCreateOptions["network"]): Promise<void>;
 }
 /** Sandbox lifecycle management */
 interface SandboxProvider {
@@ -129,7 +979,10 @@ interface SandboxProvider {
     readonly name?: string;
     create(options: SandboxCreateOptions): Promise<SandboxInstance>;
     connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
+    /** List sandboxes, paginating to exhaustion. `limit` bounds items returned. */
     list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
+    /** The same enumeration for fleet bookkeeping: never throws, reports completeness. */
+    listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
 }
 interface DaytonaConfig {
     /** Daytona API key. Default: reads from DAYTONA_API_KEY env var */
@@ -140,8 +993,22 @@ interface DaytonaConfig {
     target?: string;
     /** Default timeout in ms */
     defaultTimeoutMs?: number;
-    /** Daytona snapshot name (default: 'evolve-all'). Create custom snapshots via `cd assets && ./build.sh daytona` */
+    /** Daytona snapshot name (default: 'evolve-all-<EVOLVE_IMAGE_VERSION>' direct, the platform's stable 'evolve-all' managed). Explicit names pass through untouched. Create custom snapshots via `cd assets && ./build.sh daytona` */
     snapshotName?: string;
+    /**
+     * Evolve-managed toolbox base URL. Setting it puts the provider in MANAGED
+     * mode, where `apiKey` is an Evolve API key rather than a Daytona one and
+     * both planes ride the Dashboard.
+     *
+     * One field rather than a separate `managed: true` because the two effects
+     * have one cause: if the toolbox belongs to the platform, so do the
+     * snapshots behind it, so managed creates name an existing platform snapshot
+     * and never build one. Resolved by the Evolve SDK; direct/BYO callers leave
+     * it unset.
+     *
+     * @internal
+     */
+    managedToolboxUrl?: string;
 }
 interface ResolvedDaytonaConfig {
     apiKey: string;
@@ -149,6 +1016,180 @@ interface ResolvedDaytonaConfig {
     target?: string;
     defaultTimeoutMs?: number;
     snapshotName?: string;
+    managedToolboxUrl?: string;
+}
+/** What a managed sandbox's streaming log follow needs to reach the Dashboard. */
+interface ManagedStreamContext {
+    toolboxUrl: string;
+    apiKey: string;
+}
+/**
+ * Split Daytona's multiplexed command log into stdout and stderr as the bytes
+ * arrive.
+ *
+ * The wire format is one byte stream with 3-byte markers announcing which
+ * stream the following bytes belong to (STDOUT_PREFIX_BYTES /
+ * STDERR_PREFIX_BYTES, both exported by the Daytona SDK — this reads their
+ * framing, it does not invent one). Two things make a streaming demux
+ * different from the SDK's whole-buffer one: a marker can be split across two
+ * chunks, so the last MAX_PREFIX_LEN-1 bytes are always held back rather than
+ * emitted; and a multi-byte UTF-8 character can be split too, so each stream
+ * keeps its own decoder in streaming mode.
+ */
+declare function createLogDemuxer(onStdout: (chunk: string) => void, onStderr: (chunk: string) => void): {
+    push(chunk: Uint8Array): void;
+    flush(): void;
+};
+/**
+ * Follow a session command's logs over plain HTTP.
+ *
+ * The Daytona SDK follows logs over a WEBSOCKET (Process.js:289 rewrites the
+ * toolbox base to ws:// and opens a socket). A managed sandbox's toolbox base
+ * is a Next.js route handler, and a Next route handler never sees a websocket
+ * upgrade — the codebase's one websocket proxy lives in a separate custom
+ * server for exactly that reason. So managed mode cannot use that transport.
+ *
+ * It does not have to. MEASURED 2026-07-26 against a live sandbox: the same
+ * endpoint with `?follow=true` over ordinary HTTP answers 200 with
+ * `transfer-encoding: chunked` and `content-type: application/octet-stream`,
+ * and chunks arrive as the command produces them — 95 ms, 1045 ms, 2127 ms,
+ * 2984 ms, 3976 ms for a command printing one line per second. That is real
+ * streaming through a plain response body, which is what the Dashboard route
+ * pipes through unbuffered.
+ */
+declare function followManagedSessionLogs(context: ManagedStreamContext, sandboxId: string, sessionId: string, commandId: string, onStdout: (chunk: string) => void, onStderr: (chunk: string) => void, signal?: AbortSignal): Promise<void>;
+/**
+ * Read a command's streams out of whatever shape Daytona returned.
+ *
+ * Session logs are USUALLY framed with per-stream markers, and the Daytona
+ * SDK's demux returns "" for a stream whose marker never appears. An empty
+ * string is not "this command printed nothing" — it means "this daemon build
+ * did not frame the output" — and `??` does not fall through an empty string,
+ * so reading `stdout ?? output` silently reports every such command as silent.
+ *
+ * Measured 2026-07-26 on a live sandbox booted from ubuntu:22.04: a command
+ * printing one line to each stream came back as
+ * {output: "hello-managed\noops\n", stdout: null, exitCode: 0} with no marker
+ * bytes anywhere in the log body, and the provider reported exit 0 with empty
+ * stdout. Unframed output goes to stdout, because that is what the combined
+ * `output` field is; a framed response is untouched.
+ */
+declare function readCommandStreams(source: {
+    stdout?: string | null;
+    stderr?: string | null;
+    output?: string | null;
+}): {
+    stdout: string;
+    stderr: string;
+};
+declare class DaytonaCommands implements SandboxCommands {
+    private sandbox;
+    private user?;
+    private managedStream?;
+    /** The streamed-run clocks, shrinkable by a subclass so a test need not wait them out. */
+    protected streamTimings: DaytonaStreamTimings;
+    constructor(sandbox: Sandbox, user?: string | undefined, managedStream?: ManagedStreamContext | undefined);
+    /**
+     * Stream a command's output to callbacks. Direct mode uses the Daytona
+     * SDK's own follow, which is a websocket; managed mode uses the HTTP
+     * chunked follow, because a Dashboard route handler cannot terminate a
+     * websocket upgrade (see followManagedSessionLogs).
+     *
+     * Only the managed follow takes the abandon signal — the SDK's websocket
+     * follow exposes none, so a direct-mode stall is stopped from waiting on
+     * but not closed; the ephemeral session's delete is what ends it.
+     */
+    private followLogs;
+    run(command: string, options?: SandboxRunOptions): Promise<SandboxCommandResult>;
+    /**
+     * WHAT SAYS A STREAMED RUN IS OVER: the command's record, never the follow.
+     *
+     * A chunked follow can stall open long after its command exited — nothing
+     * acks a response body — and awaiting it first, then polling for an exit
+     * code 20 times at 500ms, gave a streaming run() two failure modes the
+     * blocking path never had: a stalled socket hung run() forever (with no
+     * timeoutMs, nothing in the box or out of it bounds the wait), and a follow
+     * that closed a moment early threw "no exit code" on a command that had
+     * already succeeded.
+     *
+     * So the poll and the follow run TOGETHER. The poll decides when the run
+     * ended; the follow then gets as long as it keeps delivering and is cut
+     * only once it has been SILENT for the drain window, so a live stream is
+     * never truncated and a dead one is never waited on. Two ceilings bound the
+     * wait: the caller's timeoutMs widened by the in-box kill grace, and — for
+     * the caller who passed none — the settle bound measured from the moment
+     * the follow closed, because a closed stream means the command ended and a
+     * record that never catches up is a provider incident, not a long run.
+     * A run with no timeoutMs whose command is genuinely still streaming is
+     * still waited on indefinitely: that is what asking for no bound means.
+     */
+    private awaitStreamedExit;
+    spawn(command: string, options?: SandboxSpawnOptions): Promise<SandboxCommandHandle>;
+    list(): Promise<ProcessInfo[]>;
+    kill(processId: string): Promise<boolean>;
+}
+declare class DaytonaFiles implements SandboxFiles {
+    private sandbox;
+    constructor(sandbox: Sandbox);
+    read(path: string): Promise<string | Uint8Array>;
+    write(path: string, content: string | Buffer | ArrayBuffer | Uint8Array): Promise<void>;
+    writeBatch(files: Array<{
+        path: string;
+        data: string | Buffer | ArrayBuffer | Uint8Array;
+    }>): Promise<void>;
+    /**
+     * Upload a local file by PATH. Daytona's own uploadFile has a local-path
+     * overload (FileSystem.d.ts: `uploadFile(localPath: string, remotePath:
+     * string, timeout?)`), so the bytes never pass through this process's heap —
+     * which is what makes a large artifact safe to upload under concurrency.
+     */
+    writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
+    makeDir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    list(path: string): Promise<FileInfo[]>;
+    remove(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+}
+declare class DaytonaSandboxImpl implements SandboxInstance {
+    private sandbox;
+    readonly commands: SandboxCommands;
+    readonly files: SandboxFiles;
+    constructor(sandbox: Sandbox, user?: string, managedStream?: ManagedStreamContext);
+    get sandboxId(): string;
+    getHost(port: number): Promise<string>;
+    isRunning(): Promise<boolean>;
+    getInfo(): Promise<SandboxInfo>;
+    /**
+     * Replace the running sandbox's outbound policy — Daytona's
+     * `sandbox.updateNetworkSettings`, which "maps to the same mechanism as
+     * creating a sandbox with `networkBlockAll` / `networkAllowList` /
+     * `domainAllowList`: the runner applies iptables rules to the sandbox
+     * container" (@daytonaio/sdk@0.203.0 Sandbox.d.ts:495-511).
+     *
+     * TIER GATE, surfaced and never swallowed. Daytona allows sandbox-level
+     * network policy only on the higher plan tiers — "Organizations on Tier 1 or
+     * Tier 2 cannot override network policy at the sandbox level". Upstream does
+     * not model this: its validation passes and the runtime call then fails, so
+     * a task that declares a phase switch looks supported right up to the moment
+     * the agent is already running. Here the refusal becomes
+     * DaytonaNetworkPolicyError("org-tier-forbidden") — a typed answer a caller
+     * can act on, and never a quiet return, because a switch that silently does
+     * nothing leaves the agent running under the WRONG policy with no signal
+     * that anything went wrong.
+     *
+     * Refusals that do not match the tier signature propagate untouched: a
+     * revoked key and a plan limit both come back 403, and mislabelling the
+     * first as the second sends the caller to the billing page over a
+     * credential.
+     *
+     * Hostname destinations forward VERBATIM into domainAllowList, exactly as
+     * at create — nothing is DNS-resolved or pinned, Daytona enforces the
+     * domain layer itself — so create and switch express the same policy the
+     * same way.
+     */
+    updateNetwork(network: SandboxCreateOptions["network"]): Promise<void>;
+    kill(): Promise<void>;
+    pause(): Promise<void>;
 }
 declare class DaytonaProvider implements SandboxProvider {
     readonly providerType: "daytona";
@@ -156,11 +1197,138 @@ declare class DaytonaProvider implements SandboxProvider {
     private readonly client;
     private readonly defaultTimeoutMs;
     private readonly snapshotName;
+    /**
+     * Sandbox user configured at create time, reapplied on connect() so the
+     * root sudo wrapper keeps applying. In-memory only: a connect() from a
+     * fresh process falls back to the sandbox's create-time OS user without
+     * the wrapper — callers reconnecting across processes must recreate the
+     * provider and sandbox with the same user, or root-only operations fail
+     * loudly.
+     */
+    private readonly sandboxUsers;
+    /** Set only in Evolve-managed mode; see the EVOLVE-MANAGED MODE section. */
+    private readonly managedStream?;
+    /**
+     * Clocks of the WAIT-ON-CONFLICT path (see waitForSnapshotConflictWinner).
+     * A field rather than a constant so tests can drive the shape of the wait
+     * without spending its production budget, the same way streamTimings does.
+     */
+    protected snapshotConflictTiming: {
+        timeoutMs: number;
+        pollMs: number;
+    };
+    /**
+     * Clocks of the DELETE-CONFIRMATION poll (see deleteDeadSnapshot). Separate
+     * from snapshotConflictTiming because the two wait for different things on
+     * different scales: the conflict clock waits out another process's IMAGE
+     * BUILD, which legitimately takes minutes, while this one waits for a record
+     * to stop resolving after Daytona acknowledged its deletion — seconds of
+     * bookkeeping. Handing the delete poll the conflict budget let the fast path
+     * block for ten minutes on a lingering corpse and left this function's own
+     * constants unreachable.
+     */
+    protected snapshotDeleteTiming: {
+        timeoutMs: number;
+        pollMs: number;
+    };
     constructor(config: ResolvedDaytonaConfig);
     create(options: SandboxCreateOptions): Promise<SandboxInstance>;
+    /**
+     * Join a snapshot build another process is already running, and leave the
+     * name usable — or say why it is not.
+     *
+     * Returns FALSE when the snapshot can be used by name as it stands, and TRUE
+     * when the name was found dead, deleted, and now needs building: the caller
+     * runs the build it was waiting for. That is Harbor's _SnapshotNeedsCreate
+     * signal, which its resolve raises after deleting an ERROR-state snapshot
+     * (REFERENCES/Harbor/src/harbor/environments/daytona/snapshots.py:200-212).
+     *
+     * DELIBERATELY STRICTER THAN UPSTREAM ON ONE POINT. Harbor raises
+     * _SnapshotNeedsCreate whether or not its delete succeeded — _delete_snapshot
+     * logs a failure and returns, and the caller creates regardless (:213-224).
+     * This returns NEEDS-CREATE only when the name is CONFIRMED clear. A create
+     * fired over a corpse that is still there loses the name and lands back in
+     * the conflict wait, which is a slower way of reaching the same fallback with
+     * one wasted round trip; when the name is genuinely gone, the create is the
+     * whole point. Swallowing a FAILED delete, by contrast, is not a divergence
+     * at all — that matches Harbor exactly.
+     *
+     * Throws a plain Error when the in-flight build produced nothing usable AND
+     * the name could not be cleared, which is the ONE case create()'s direct
+     * image pull is still right: nobody is going to produce this snapshot, so
+     * waiting longer buys nothing. The typed errors (conflict, activation) pass
+     * straight through create()'s fallback as final verdicts.
+     */
+    private joinInFlightSnapshotBuild;
     connect(sandboxId: string, _timeoutMs?: number): Promise<SandboxInstance>;
+    /**
+     * List sandboxes, walking the cursor stream to exhaustion.
+     *
+     * An early version requested page 1 and stopped, discarding the rest — an
+     * organization with more than one page of sandboxes was silently truncated,
+     * and nothing in the return value said so. For any caller that reads absence
+     * from the list as "this sandbox is gone", that is a correctness bug. Cursor
+     * pagination (mandatory since Daytona retired page numbers on 2026-06-25)
+     * changes the mechanics, not the law: the walk still runs to the end or says
+     * it could not.
+     *
+     * ORDER OF OPERATIONS, because it is observable: `limit` bounds the
+     * sandboxes RETURNED, and the state filter runs client-side on every row
+     * BEFORE the limit is counted. Asking for 10 running sandboxes therefore
+     * keeps walking until ten running ones have been found, rather than
+     * filtering ten arbitrary rows down to whatever survives.
+     */
     list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
+    /**
+     * The fleet-bookkeeping enumeration: same walk, never throws.
+     *
+     * The distinction from `list()` is what a failure MEANS to the caller. An
+     * orphan sweep treats a missing sandbox as a terminated one, so it must be
+     * able to tell "the organization has no sandboxes" from "the enumeration
+     * stopped early".
+     */
+    listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
+    private paginate;
+    /**
+     * The cursor stream, asking the API to narrow server-side where it can.
+     *
+     * Since 0.203.0 the SDK's public `list(query)` takes `states` and `labels`
+     * directly and pages by cursor internally (items + nextCursor,
+     * esm/Daytona.js:430-476), so the old reach-around through the private
+     * `sandboxApi.listSandboxesPaginated` field is gone along with the method
+     * itself. The client-side filter in the walk stays the authority regardless:
+     * a server filter that silently stopped applying must never be able to admit
+     * a state the caller excluded.
+     */
+    private listStream;
 }
+/**
+ * Walk the cursor stream into one answer, with an honest completeness verdict.
+ *
+ * Separate from the provider because everything worth getting wrong lives here
+ * and none of it needs a network: the ways a walk can fail to terminate, the
+ * difference between "the caller asked for ten" and "the provider ran out",
+ * and the rule that a failure mid-walk yields the sandboxes seen so far marked
+ * INCOMPLETE rather than either an exception or a short complete list.
+ *
+ * WHAT CURSORS CHANGED HERE, and what they did not. The vendor's iterator ends
+ * itself when nextCursor runs out, so "exhausted" is now the stream ending
+ * rather than a totalPages comparison; a fetch failure mid-walk surfaces as
+ * the iterator throwing. The LAWS are unchanged: a walk that could not finish
+ * reports `complete: false` with what it saw, a caller's limit is reported as
+ * truncation whenever one more row provably exists (the row after the limit is
+ * that proof — the walk holds it, so no extra fetch is spent on it beyond, at
+ * worst, the one the iterator was already making), and a runaway fleet stops
+ * at the scan ceiling as a refusal, never as a short list that reads complete.
+ *
+ * Exported for its test (`_testCollectSandboxStream`).
+ */
+declare function collectSandboxStream(stream: AsyncIterable<DaytonaSandboxLike & {
+    state?: string;
+}>, options?: SandboxListOptions): Promise<SandboxListPage & {
+    stoppedAtLimit: boolean;
+}>;
+declare const _testCollectSandboxStream: typeof collectSandboxStream;
 /**
  * Create Daytona sandbox provider.
  *
@@ -168,5 +1336,36 @@ declare class DaytonaProvider implements SandboxProvider {
  * @throws Error if apiKey cannot be resolved
  */
 declare function createDaytonaProvider(config?: DaytonaConfig): SandboxProvider;
+/** @internal Test-only export for unit testing wrapCommand logic. */
+declare const _testWrapCommand: typeof wrapCommand;
+declare const _testWithInBoxTimeout: typeof withInBoxTimeout;
+/** @deprecated The create-side mapper is public API now — import
+ *  `mapNetworkPolicy` directly; this alias stays for existing tests only. */
+declare const _testMapNetworkPolicy: typeof mapNetworkPolicy;
+declare const _testMapNetworkPolicyForUpdate: typeof mapNetworkPolicyForUpdate;
+declare const _testIsNetworkPolicyTierRefusal: typeof isNetworkPolicyTierRefusal;
+declare const _testImageRegistryHost: typeof imageRegistryHost;
+declare const _testToSandboxInfo: typeof toSandboxInfo;
+declare const _testDaytonaStateToEvolveState: typeof daytonaStateToEvolveState;
+declare const _testActivateSnapshot: typeof activateSnapshot;
+declare const _testWaitForSnapshotConflictWinner: typeof waitForSnapshotConflictWinner;
+declare const _testIsSnapshotNameConflict: typeof isSnapshotNameConflict;
+declare const _testProviderCanRebuildSnapshot: typeof providerCanRebuildSnapshot;
+declare const _testImageMap: Record<string, string>;
+declare const _testWithEndOfOutputSentinel: typeof withEndOfOutputSentinel;
+declare const _testStripEndOfOutputSentinel: typeof stripEndOfOutputSentinel;
+declare const _testSettledStreams: typeof settledStreams;
+declare const _testCreateSentinelFilter: typeof createSentinelFilter;
+declare const _testCreateLogDemuxer: typeof createLogDemuxer;
+declare const _testFollowManagedSessionLogs: typeof followManagedSessionLogs;
+declare const _testReadCommandStreams: typeof readCommandStreams;
+/**
+ * TYPE-ONLY handle on the concrete sandbox class, for the contract-conformance
+ * seam. create() is declared to return the local SandboxInstance INTERFACE, so
+ * a seam reading create()'s return type checks the interface and never the
+ * class — which let a narrowed method on the class pass unnoticed. Exporting
+ * the type (never the constructor) gives the seam the real methods to pin.
+ */
+type _testDaytonaSandboxImpl = DaytonaSandboxImpl;
 
-export { type DaytonaConfig, DaytonaProvider, type FileInfo, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxProvider, type SandboxResources, type SandboxRunOptions, type SandboxSpawnOptions, _testWrapCommand, createDaytonaProvider };
+export { DAYTONA_AUTO_DELETE_GRACE_MINUTES, DAYTONA_BOOT_LABEL, DAYTONA_BOOT_POLL_MS, DAYTONA_LIST_PAGE_SIZE, DAYTONA_MAX_DOMAIN_ALLOWLIST, DAYTONA_MAX_LIST_SCAN, DAYTONA_MAX_NETWORK_ALLOWLIST, DAYTONA_SNAPSHOT_ACTIVATE_TIMEOUT_MS, DAYTONA_SNAPSHOT_CONFLICT_TIMEOUT_MS, DAYTONA_SNAPSHOT_GONE, DAYTONA_STREAM_TIMINGS, DaytonaBootAbortedError, type DaytonaBootClient, DaytonaBootCommandError, type DaytonaBootPhase, type DaytonaBootProgress, DaytonaCommands, type DaytonaConfig, DaytonaFiles, DaytonaGpuTypeError, DaytonaIdleTimeoutError, DaytonaImagePullError, DaytonaNetworkPolicyError, type DaytonaNetworkPolicyReason, type DaytonaObservedCreateOptions, DaytonaProvider, DaytonaResourcesError, DaytonaSnapshotActivationError, DaytonaSnapshotConflictError, type DaytonaStreamTimings, EVOLVE_IMAGE_VERSION, type FileInfo, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxListPage, type SandboxProvider, type SandboxResources, type SandboxRunOptions, type SandboxSpawnOptions, _testActivateSnapshot, _testCollectSandboxStream, _testCreateLogDemuxer, _testCreateSentinelFilter, type _testDaytonaSandboxImpl, _testDaytonaStateToEvolveState, _testFollowManagedSessionLogs, _testImageMap, _testImageRegistryHost, _testIsNetworkPolicyTierRefusal, _testIsSnapshotNameConflict, _testMapNetworkPolicy, _testMapNetworkPolicyForUpdate, _testProviderCanRebuildSnapshot, _testReadCommandStreams, _testSettledStreams, _testStripEndOfOutputSentinel, _testToSandboxInfo, _testWaitForSnapshotConflictWinner, _testWithEndOfOutputSentinel, _testWithInBoxTimeout, _testWrapCommand, createDaytonaProvider, createSandboxObserved, daytonaBootPhaseOf, mapNetworkPolicy };