@agent-compose/sdk 0.8.1 → 0.8.3

package/dist/runtimes/session-env.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Session env sourcing (session secrets) — the turn-launch half of the
+ * contract. The server writes `$HOME/.agent-compose/session-env.sh` at
+ * sandbox acquire; the detached JSONL launch sources it fresh EVERY turn
+ * via `sessionEnvSourceFragment`. Pinned here:
+ *
+ *   - the fragment sources exactly the configured $HOME-relative path,
+ *     silently, and never fails the turn when the file is absent;
+ *   - hostile/malformed paths (quotes, spaces, `..`, absolute) are DROPPED
+ *     — a bad option must not break the launch or escape $HOME;
+ *   - no option ⇒ empty fragment (local/BYOM runs never read a user's
+ *     dotfiles by surprise).
+ */
+export {};

package/dist/sandbox/sizes.d.ts

@@ -1,19 +1,78 @@
 /**
- * Sandbox machine sizes + the E2B template aliases derived from them.
+ * Sandbox machine sizes — THE single source of the size vocabulary.
  *
- * A coarse hardware knob that maps to provider machine specs at create time:
- * Vercel honours it natively via `resources.vcpus`; E2B sizing is baked into
- * the template, so on E2B a size resolves to a pre-built per-size template.
+ * Everything that names a size (the server's `SANDBOX_DEFAULT_SIZE` env enum,
+ * the register/invoke zod schemas, the run + session row types, the CLI's
+ * `--size` flag, the dashboard pickers via `GET /v1/sandbox-sizes`) derives
+ * from `SANDBOX_SIZES` / `SandboxSize` here. Adding a size is a ONE-LINE edit
+ * to `SANDBOX_MACHINES`: the type, the enums, the E2B build matrix and the
+ * pickers all follow. Do NOT re-declare the union inline anywhere.
+ *
+ * A size is a coarse hardware knob that maps to provider machine specs:
+ * Vercel honours it natively via `resources.vcpus`; E2B sizing is BAKED INTO
+ * THE TEMPLATE (e2b 2.30.5 has no create-time cpu/mem knob — `NewSandbox`
+ * carries only `templateID`), so on E2B a size resolves to a pre-built
+ * per-size template.
  */
-/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
- *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
- *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
- *    4vcpu-8gb   =  4 vCPU /  8 GiB
- *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
- *                                     probed live: 16 & 32 vCPU 400 on dev)
- *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
-export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
-/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
+/** Every sandbox hardware SKU, with its real machine spec. Named for the
+ *  machine (vCPU + RAM) rather than abstract t-shirt sizes, so a size can
+ *  never quietly mean something different than it says.
+ *
+ *  RAM is 2048 MB/vCPU everywhere EXCEPT `8vcpu-8gb`, which exists because
+ *  E2B caps a sandbox at 8 vCPU / 8192 MB (e2b.dev/docs/billing: Hobby and
+ *  Pro both "8 vCPU / 8 GB", raised only by arrangement): 8 vCPU at the 2 GB
+ *  rule would need 16 GiB and cannot be built. `8vcpu-8gb` is the CPU ceiling
+ *  at the memory ceiling — the only way to get 8 cores on E2B today, and a
+ *  spec already proven bakeable by the devbox (`E2B_DEVBOX_SPEC`).
+ *
+ *  Adding an entry here automatically: widens `SandboxSize`, widens every
+ *  derived enum, and — if it fits under the E2B caps — adds it to
+ *  `E2B_TEMPLATE_SIZES`, which is what `infra/e2b-template/build.ts` and the
+ *  `sandbox-images` CI job loop over. Two templates get baked per size, so
+ *  the matrix is not free; see that workflow's header. */
+export declare const SANDBOX_MACHINES: {
+    /** 1 vCPU / 2 GiB — the cheap floor. Plenty for a terminal session or a
+     *  shell-shaped agent; tight for a big `bun install` or a browser. */
+    readonly "1vcpu-2gb": {
+        readonly vcpus: 1;
+        readonly memoryMB: 2048;
+    };
+    /** 2 vCPU / 4 GiB — the default (Vercel's own default machine too). */
+    readonly "2vcpu-4gb": {
+        readonly vcpus: 2;
+        readonly memoryMB: 4096;
+    };
+    /** 4 vCPU / 8 GiB — comfortable for builds and multi-tool agent turns. */
+    readonly "4vcpu-8gb": {
+        readonly vcpus: 4;
+        readonly memoryMB: 8192;
+    };
+    /** 8 vCPU / 8 GiB — E2B's per-sandbox CEILING (cores maxed at the memory
+     *  cap). NOT expressible on Vercel, whose RAM follows vCPUs at 2 GB each. */
+    readonly "8vcpu-8gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 8192;
+    };
+    /** 8 vCPU / 16 GiB — Vercel only; exceeds E2B's 8 GiB memory cap. */
+    readonly "8vcpu-16gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 16384;
+    };
+    /** 32 vCPU / 64 GiB — Vercel Enterprise only; far past every E2B cap. */
+    readonly "32vcpu-64gb": {
+        readonly vcpus: 32;
+        readonly memoryMB: 65536;
+    };
+};
+/** Sandbox hardware SKU. Derived from `SANDBOX_MACHINES` — never re-spelled
+ *  as an inline union. */
+export type SandboxSize = keyof typeof SANDBOX_MACHINES;
+/** The vocabulary as an ordered, smallest-first array — the shape zod
+ *  (`z.enum`), the CLI's `--size` validation, and the wire catalogue want.
+ *  Ordering is the pickers' display order, so keep it ascending. */
+export declare const SANDBOX_SIZES: readonly [SandboxSize, ...SandboxSize[]];
+/** SKU → Vercel vCPU count (Vercel's RAM follows automatically at 2048
+ *  MB/vCPU — which is why `isVercelSupportedSize` exists). */
 export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
 /** SDK fallback size when neither the caller nor the deployment specifies one.
  *  Deliberately conservative — the OPERATIONAL default is the server's
@@ -21,30 +80,61 @@ export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
  *  small matters because Vercel rate-limits creation by vCPUs-per-window
  *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
  *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
- *  workflow rather than inflating the default for everyone. */
+ *  workflow rather than inflating the default for everyone.
+ *
+ *  NOT `1vcpu-2gb`: the floor is an opt-IN for cheap sessions, not a quiet
+ *  downgrade of every existing run's machine. */
 export declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
-/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
- *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
- *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
- *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
- *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
- *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
- *  templates) only once the account's memory limit is raised. The register/
- *  invoke guards reject an unsupported E2B size before it can reach here. */
+/** SESSION default — deliberately one size up from the run default
+ *  (2026-08-13): a session's sandbox carries the full desktop toolbelt
+ *  (VS Code + Chromium + dockerd) plus the KasmVNC encoder at the 60fps
+ *  cap, and that stack swap-thrashes on 4 GiB while the encoder starves on
+ *  2 shared vCPUs. Workflow runs keep DEFAULT_SANDBOX_SIZE — no desktop,
+ *  no toolbelt weight. Sessions bill active time only (parked = storage),
+ *  so the delta applies to active hours, not the fleet. */
+export declare const SESSION_DEFAULT_SANDBOX_SIZE: SandboxSize;
+/** E2B's per-sandbox ceiling on the plans we run (e2b.dev/docs/billing —
+ *  Hobby: "8 vCPU / 8 GB"; Pro: the same, "8+" only by arrangement with
+ *  support). Recorded live too: `Template.build` 400s with "Memory can't be
+ *  higher than 8192 MiB" past the memory cap.
+ *
+ *  These two numbers are the ONLY knob for which sizes get an E2B template —
+ *  raise them after E2B raises the account limit and the build matrix (and
+ *  therefore the session picker) widens on its own. */
+export declare const E2B_MAX_VCPUS = 8;
+export declare const E2B_MAX_MEMORY_MB = 8192;
+/** The E2B sizes we pre-build a template for — DERIVED from the caps, not
+ *  hand-listed, so a new `SANDBOX_MACHINES` entry can never be offered
+ *  without a template or omitted despite fitting. E2B sizing is
+ *  template-baked (no per-create cpu/mem knob), so honouring `resources.size`
+ *  on E2B means ONE pre-built template per size; `infra/e2b-template/build.ts`
+ *  loops exactly this list. The register / invoke / session-spawn / resize
+ *  guards all reject an unsupported E2B size before it can reach a create. */
 export declare const E2B_TEMPLATE_SIZES: readonly SandboxSize[];
-/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
- *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
- *  not — the guards lean on this so the "no E2B equivalent" decision lives in
- *  exactly one place. */
+/** Is `size` one E2B can be built/booted at? False for the sizes past E2B's
+ *  8 vCPU / 8 GiB ceiling (`8vcpu-16gb`, `32vcpu-64gb`) — those run on Vercel.
+ *  The "no E2B equivalent" decision lives in exactly one place: the caps. */
 export declare function isE2bSupportedSize(size: SandboxSize): boolean;
-/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
- *  always 2048 MB/vCPU, matching the size name + Vercel parity
- *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
- *  per-size base + agent-env templates. */
+/** Vercel's fixed memory-per-vCPU ratio. Vercel takes `resources.vcpus` and
+ *  allocates RAM itself at this rate — there is no independent memory knob. */
+export declare const VERCEL_MEMORY_MB_PER_VCPU = 2048;
+/** Is `size` expressible on Vercel? Only when its RAM matches what Vercel
+ *  would allocate for that vCPU count — otherwise asking for it would hand
+ *  the caller a machine that does not match the name (`8vcpu-8gb` would come
+ *  back with 16 GiB). Vercel's own ceiling (32 vCPU, Enterprise) is a plan
+ *  matter, not a shape matter, so it is not encoded here. */
+export declare function isVercelSupportedSize(size: SandboxSize): boolean;
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. Used
+ *  by `infra/e2b-template/build.ts` to stamp the per-size base + agent-env
+ *  templates. Reads the explicit table rather than deriving RAM from vCPUs —
+ *  `8vcpu-8gb` is deliberately off the 2048 MB/vCPU line. */
 export declare function e2bMachineSpec(size: SandboxSize): {
     cpuCount: number;
     memoryMB: number;
 };
+/** Human label for a size — "2 vCPU · 4 GB". The wire catalogue carries it so
+ *  the dashboard never has to parse the id back into numbers. */
+export declare function sandboxSizeLabel(size: SandboxSize): string;
 /** Stable E2B template ALIAS for the platform base at a given size
  *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
  *  multi-account-clean: the same string resolves in any E2B account that built

package/dist/sandbox.d.ts

@@ -14,7 +14,7 @@ export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions,
 export type { SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxNetworkPolicy, } from "./sandbox/network-policy.js";
 export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
 export type { SandboxSize } from "./sandbox/sizes.js";
-export { SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
+export { SANDBOX_SIZES, SANDBOX_MACHINES, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, SESSION_DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, E2B_MAX_VCPUS, E2B_MAX_MEMORY_MB, VERCEL_MEMORY_MB_PER_VCPU, isE2bSupportedSize, isVercelSupportedSize, sandboxSizeLabel, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
 export { E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef, } from "./sandbox/devbox.js";
 export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";