@veris-ai/daytona 0.2.0 → 0.3.0

package/dist/control-plane.d.ts

@@ -45,11 +45,21 @@ export interface EgressCredential {
     expires_at?: string;
     /** Server-served CA trust env map; the SDK's vendored list is the fallback. */
     trust_env?: Record<string, string>;
+    /** IPv4 addresses the gateway listens on — what strict mode pins Daytona's
+     *  networkAllowList to. Absent on a control plane that predates the field;
+     *  the SDK then resolves the proxy host itself, once. */
+    gateway_ips?: string[];
 }
-/** Mutable fields of a running twin. An OMITTED key is left alone; an explicit
- *  null is a value (client_base_url: null unregisters). */
+/**
+ * Mutable fields of a running twin. An OMITTED key is left alone; an explicit
+ * null is a value (client_base_url: null unregisters).
+ *
+ * There is deliberately no ttl_minutes. The server's UpdateSandboxRequest
+ * declares client_base_url and nothing else, and pydantic ignores unknown
+ * fields rather than refusing them — so a PATCH carrying a TTL answers 200 and
+ * changes nothing. See the note where extendTtl used to be.
+ */
 export interface SandboxPatch {
-    ttl_minutes?: number;
     client_base_url?: string | null;
 }
 export interface ControlPlaneOpts {
@@ -82,8 +92,6 @@ export declare class ControlPlane {
     mintEgressCredential(environmentId: string, sandboxId: string): Promise<EgressCredential | null>;
     /** PATCH the twin resource. Omitted fields are untouched by the server. */
     updateSandbox(environmentId: string, sandboxId: string, patch: SandboxPatch): Promise<void>;
-    /** Extend a twin's TTL so it stays in lockstep with an extended Daytona sandbox. */
-    extendTtl(environmentId: string, sandboxId: string, ttlMinutes: number): Promise<void>;
     /** Create-time preflight: is the gateway infrastructure up, per the control plane? */
     gatewayHealth(): Promise<void>;
 }

package/dist/daytona-key.d.ts

@@ -0,0 +1,28 @@
+export declare const DAYTONA_API_URL = "https://app.daytona.io/api";
+/** The permission DELETE /api/sandbox/<id> checks for. */
+export declare const DELETE_SANDBOXES = "delete:sandboxes";
+/** The part of GET /api/api-keys/current this package reads. */
+export interface DaytonaKeyInfo {
+    name: string;
+    permissions: string[];
+}
+/** Where the Daytona API is, resolved the way @daytona/sdk resolves it. */
+export declare function daytonaApiUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * The key's own record, or undefined when Daytona would not say — a network
+ * error, a non-2xx, a body without a permissions list. Undefined means
+ * "unknown", and a caller must not read it as "cannot delete".
+ */
+export declare function fetchDaytonaKey(apiKey: string, apiUrl?: string): Promise<DaytonaKeyInfo | undefined>;
+/** True, false, or undefined when the key's permissions are not known. */
+export declare function canDeleteSandboxes(key: DaytonaKeyInfo | undefined): boolean | undefined;
+/** `"ci-key" (permissions: write:sandboxes)` — how a message names the key. */
+export declare function describeKey(key: DaytonaKeyInfo): string;
+/** How to get a key that can delete. One sentence, used wherever the lack is reported. */
+export declare const DELETE_PERMISSION_FIX = "create a key with the \"delete sandboxes\" permission at https://app.daytona.io/dashboard/keys";
+/**
+ * The warning `provision` and `run` print before creating a box with a key
+ * that cannot delete one. Says what will happen instead — the box's own
+ * brakes — so the reader can decide whether that is good enough.
+ */
+export declare function cannotTeardownWarning(key: DaytonaKeyInfo, autoStopMinutes: number, autoDeleteMinutes: number): string;

package/dist/daytona.d.ts

@@ -4,25 +4,25 @@ import type { VerisApi } from './veris-api';
 import type { EgressMode } from './network';
 import { CA_CERT_PATH } from './trust';
 export interface VerisOpts {
-    /** Veris API key. Falls back to process.env.VERIS_API_KEY. Required. */
+    /** Veris API key. Falls back to process.env.VERIS_API_KEY, then to the
+     *  profile `veris login` saved in ~/.veris/twin.yaml. Required. */
     apiKey?: string;
     /** Veris environment the twin is deployed from. Falls back to process.env.VERIS_ENVIRONMENT_ID. */
     environmentId?: string;
-    /** Control plane base. Falls back to process.env.VERIS_API_BASE, then 'https://svc.api.veris.ai'. */
+    /** Control plane base. Falls back to process.env.VERIS_API_BASE, then the
+     *  profile's api_base, then 'https://svc.api.veris.ai'. */
     apiBase?: string;
     /** Attach to an EXISTING twin instead of provisioning one (advanced). delete() will NOT remove it. */
     attachSandboxId?: string;
     /** Twin TTL backstop, minutes. Default 60, kept in step with the sandbox's ttlMinutes. */
     ttlMinutes?: number;
-    /** 'strict' (default): the sandbox reaches only its twin, its data planes,
-     *  the control plane and package registries. 'open': no allowlist at all —
-     *  debugging only, because a bypassing client then reaches the real vendor. */
+    /** 'strict' (default): Daytona may reach the Veris gateway's address and
+     *  nothing else; everything the code dials goes through the gateway, which
+     *  answers vendor hostnames from the twin and passes registries and other
+     *  public hosts through. 'open': no Daytona allowlist — for a control plane
+     *  that has not published the gateway's addresses. Daytona blocks anything
+     *  that bypasses the proxy in both modes. */
     egress?: EgressMode;
-    /** Extra hostnames to allow out. */
-    allowOut?: string[];
-    /** Allow package registries (npm, PyPI, apt, …). Default true: a coding
-     *  sandbox that cannot install dependencies is not usable. */
-    allowRegistries?: boolean;
     /** Install the gateway CA into the sandbox trust store. Default true; without
      *  it every HTTPS call to a vendor host fails certificate validation. */
     installCa?: boolean;
@@ -43,6 +43,24 @@ export type VerisSandbox = Sandbox & {
 };
 /** Is this sandbox one of ours? Narrows for callers who hold a bare Sandbox. */
 export declare function isVerisSandbox(sbx: Sandbox): sbx is VerisSandbox;
+/**
+ * The twin id stamped on this sandbox at create, if it has one.
+ *
+ * Read from the labels rather than from `sandbox.verisSandboxId`, so it answers
+ * for a sandbox whose Veris surface could NOT be rehydrated — no VERIS_API_KEY
+ * in the environment, say. That is exactly the case where a caller about to
+ * delete the sandbox needs telling that a twin exists and is out of reach.
+ */
+export declare function verisTwinId(sandbox: Sandbox): string | undefined;
+/**
+ * Does deleting this sandbox delete its twin too?
+ *
+ * True only for a twin this package created. A twin attached to with
+ * `veris.attachSandboxId` belongs to whoever made it and outlives the sandbox,
+ * and a sandbox with no twin at all has nothing to delete. This is the same
+ * label the wrapped `delete()` reads, so the two can never disagree.
+ */
+export declare function verisOwnsTwin(sandbox: Sandbox): boolean;
 export declare class Daytona extends BaseDaytona {
     private readonly verisDefaults;
     constructor(config?: VerisDaytonaConfig);
@@ -89,4 +107,62 @@ export declare class Daytona extends BaseDaytona {
     private baseCreate;
 }
 export default Daytona;
+/** What a create that threw left behind in Daytona, once it has been read back. */
+export interface FailedSandbox {
+    /** The DAYTONA sandbox id. Not the twin's. */
+    id: string;
+    /** Daytona's own state for it — `build_failed` for an image that never built. */
+    state?: string;
+    /** Daytona's account of what went wrong, when it kept one. */
+    errorReason?: string;
+    /** Whether the delete actually went through. The message says either way,
+     *  because "was deleted" has to be true or it is worse than saying nothing. */
+    deleted: boolean;
+}
+/** The parts of a Daytona Sandbox the reaper touches. */
+interface ReapableSandbox {
+    id: string;
+    state?: string;
+    errorReason?: string;
+    labels?: Record<string, string>;
+    refreshData(): Promise<void>;
+    delete(): Promise<void>;
+}
+/**
+ * Delete the half-built sandbox a failed create() left in Daytona, and bring
+ * back the reason Daytona recorded for it.
+ *
+ * The leak this exists for: `create({ image: 'only-on-my-laptop' })` builds
+ * server-side and fails at build time, so the SDK throws instead of returning
+ * a Sandbox — and a box sits in `build_failed` that nothing here can delete,
+ * until an autoDeleteInterval eventually reaps it. Found by the create id
+ * stamped in its labels, which is the one thing about it we know for certain.
+ *
+ * Best effort throughout: the create is already failing, and a reaper that
+ * threw would replace the real reason with its own.
+ */
+export declare function reapFailedCreate(list: (labels: Record<string, string>) => AsyncIterable<ReapableSandbox>, createId: string): Promise<FailedSandbox | undefined>;
+/**
+ * What a failed create says.
+ *
+ * Two things were missing from "Daytona sandbox create failed: Sandbox 7ba4…
+ * failed to start with status: build_failed, error reason: null".
+ *
+ * The reason, first. Daytona's SDK renders `error reason: ${this.errorReason}`
+ * off the Sandbox object it was polling, and the state change that ends the
+ * wait arrives over the event stream, which carries the new state and not the
+ * reason — so the field is still the null it started as, while Daytona's own
+ * record for that sandbox says "pull access denied, repository does not
+ * exist". Reading the record back is the whole fix.
+ *
+ * And, for the failure a first-timer actually hits, whose image it is. Daytona
+ * resolves and builds it on its own machines, from a registry; the tag sitting
+ * in the laptop's Docker daemon is not something it can see.
+ *
+ * The cause's own text is folded in HERE rather than left to VerisError, whose
+ * fold would otherwise append it after the sentences that explain it.
+ */
+export declare function sandboxCreateMessage(cause: unknown, failed: FailedSandbox | undefined, params?: {
+    image?: unknown;
+}): string;
 export { CA_CERT_PATH };

package/dist/exec.d.ts

@@ -0,0 +1,15 @@
+export interface ExecOptions {
+    /** The Daytona sandbox id — `provision`'s daytonaSandboxId. Not the twin's. */
+    sandboxId: string;
+    /** Directory to run in. Unset: the same workDir `provision` printed. */
+    cwd?: string;
+    /** KEY=VALUE pairs exported on top of the trust environment. */
+    env: Record<string, string>;
+    /** Seconds the command may run. */
+    timeoutSeconds: number;
+    /** The command itself, everything after `--`. */
+    command: string;
+}
+export declare const EXEC_USAGE = "usage: veris-daytona exec <daytona-sandbox-id> [options] -- <command>\n\nRuns <command> in a sandbox that already exists \u2014 the id `veris-daytona\nprovision` printed as daytonaSandboxId \u2014 with the Veris trust environment\napplied, and streams the output as it happens.\n\n  --cwd <dir>               directory to run in (default: <sandbox home>/veris-run, provision's workDir)\n  --env KEY=VALUE           exported on top of the trust environment (repeatable)\n  --timeout <seconds>       how long <command> may run (default: 1800)\n\nThe trust environment is applied for you, and that is the point of the verb:\nDaytona overwrites SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE and\nNODE_EXTRA_CA_CERTS inside the sandbox with its own CA file, which cannot verify\nthe twin gateway's certificates, and `daytona exec` has no way to set a variable\nat all. Every command here is run with the Veris values exported in front of it.\n--env is applied after them and wins.\n\nOutput streams rather than arriving at the end, so a long install or suite shows\nits progress. No receipt is read and no verdict is passed \u2014 take a watermark\nbefore and read `veris sandbox trace --since` after.\n\nneeds: DAYTONA_API_KEY.\n\nexit code: the command's own. 124 when it ran out of --timeout; 1 when there is\nno such sandbox; 2 on a usage error.";
+/** Parse everything after `exec`. Pure; throws UsageError with a human message. */
+export declare function parseExecArgs(argv: readonly string[]): ExecOptions;

package/dist/gateway.d.ts

@@ -25,6 +25,19 @@ export declare function gatewayProxyUrl(credential: {
     connect_address?: string;
     username: string;
 }): string;
+/**
+ * The gateway's IPv4 addresses, which strict mode pins Daytona to.
+ *
+ * The credential's own list wins: the control plane publishes the reserved
+ * load-balancer address behind the gateway hostname, and that is the authority
+ * on where the gateway is. A control plane that predates the field gets one
+ * DNS lookup of the proxy host from here — the caller's resolver is a weaker
+ * source, but it is what an older plane leaves. Empty when neither answers;
+ * buildNetwork turns that into the error that names the fix.
+ */
+export declare function gatewayIps(credential: {
+    gateway_ips?: string[];
+}, proxyUrl: string): Promise<string[]>;
 /**
  * Make the gateway's CA trusted, without requiring anything of the image.
  *
@@ -47,12 +60,33 @@ export declare function gatewayProxyUrl(credential: {
  * Daytona overrides the best-known trust variables with its own CA, correctly
  * for its proxy. The dozen it does not set still point at this bundle, which
  * carries both CAs and every public root — so those tools verify rather than
- * break.
+ * break. Node is the exception that makes ours load-bearing today: it ignores
+ * HTTPS_PROXY, is forwarded end to end, and validates OUR leaf with Daytona's
+ * file. Its file is read-only, so the store install above is what carries
+ * Node: NODE_TRUST_FLAG makes Node read the directory that install fills.
  *
  * The system-store install still runs when it can, for anything that reads the
  * store directly rather than honouring the variables. It is best-effort.
  */
 export declare function installCa(sandbox: Sandbox, caPem: string): Promise<void>;
+/**
+ * Run the bundled-CA patcher installed above, and report what it changed.
+ *
+ * The gap it closes: an SDK that ships its own CA bundle and loads it by
+ * explicit path reads none of the eighteen trust variables. stripe-python is
+ * the measured case — `verify=stripe.ca_bundle_path`, and the first call fails
+ * with "Could not verify Stripe's SSL certificate" in a sandbox where curl,
+ * Node and `requests` are all fine. This is the Daytona equivalent of the veris
+ * CLI's --patch-bundled-cas.
+ *
+ * Call it AFTER dependencies are installed. Idempotent, so calling it again
+ * after installing more costs one filesystem scan and reports nothing new.
+ *
+ * Never fatal. A sandbox with no such bundle is the normal case, and a scan
+ * that could not run is a missed optimisation, not a broken run — the failure
+ * it prevents still announces itself clearly in the client's own error.
+ */
+export declare function patchBundledCas(sandbox: Sandbox): Promise<string[]>;
 /**
  * The canary probe: one HTTPS request from inside the sandbox to a reserved
  * hostname only the gateway answers, with the twin id in the body.