@mastra/e2b 0.10.0 → 0.11.0-alpha.0

package/dist/sandbox/index.d.ts

@@ -160,10 +160,22 @@ export declare class E2BSandbox extends MastraSandbox<Sandbox> {
     private readonly _preferredSandboxId?;
     private readonly _instructionsOverride?;
     private readonly _constructorOptions;
-    /** Resolved template ID after building (if needed) */
+    /**
+     * Resolved template ID after building (if needed). The single cache for
+     * template resolution: `resolveTemplate()` returns it when set, and the
+     * create-time fallback ladder rewrites it to whichever template actually
+     * produced a sandbox.
+     *
+     * `protected` so a subclass with its own default template (e.g. desktop
+     * sandboxes) shares the same cache when it overrides `resolveTemplate()`.
+     */
     protected _resolvedTemplateId?: string;
-    /** Promise for template preparation (started in constructor) */
-    private _templatePreparePromise?;
+    /**
+     * The named spec a deferred template spec resolved to — kept so the
+     * 404-on-create fallback ladder can walk the same name/fallback rungs it
+     * would for a plain named spec.
+     */
+    private _resolvedNamedSpec?;
     constructor(options?: E2BSandboxOptions);
     /**
      * Construct a sibling `E2BSandbox` that inherits this sandbox's
@@ -333,6 +345,35 @@ export declare class E2BSandbox extends MastraSandbox<Sandbox> {
      * desktop sandboxes) override this and {@link buildDefaultTemplate}.
      */
     protected resolveTemplate(): Promise<string>;
+    /**
+     * Resolve the default mountable template: reuse when it exists, build once
+     * when it does not.
+     */
+    /**
+     * Resolve a named spec's fallback template. A named fallback gets its own
+     * exists-then-build resolution; anything failing past that (including
+     * specs without a fallback, e.g. repo templates) lands on the default
+     * mountable template so a broken build never wedges a session.
+     */
+    /**
+     * Trigger a non-blocking template rebuild via `Template.buildInBackground`
+     * (the build runs on E2B's side, so it outlives this process). Deduped
+     * per-process by ref so concurrent session starts on the same moved head
+     * don't stack duplicate builds; a failed TRIGGER clears the guard so a
+     * later start retries. A build that fails server-side simply never
+     * registers the ref — the next start falls back to the stale build again
+     * and re-triggers.
+     */
+    private triggerBackgroundBuild;
+    private resolveFallbackTemplate;
+    /**
+     * Resources the configured template asked for. The default mountable
+     * template honors them too, so a repo template that falls back never
+     * silently downgrades the machine — a 2 GB session's setup would OOM in
+     * the 1 GB default. Per-size default templates cost one extra build each.
+     */
+    private requestedBuildResources;
+    private buildOrReuseDefaultTemplate;
     /**
      * Build the default mountable template (bypasses exists check).
      *

package/dist/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/process-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/sandbox/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAA8B,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1G,OAAO,KAAK,EAAiB,WAAW,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAmG1C;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,qBAAqB,CAAC,UAAU,CAAC;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IA+BvF;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAUpC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;CAuB3D"}
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/sandbox/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAA8B,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1G,OAAO,KAAK,EAAiB,WAAW,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAmG1C;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,qBAAqB,CAAC,UAAU,CAAC;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BtF;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAQnC;IAED;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAsBzD;CACF"}

package/dist/utils/repo-template.d.ts

@@ -0,0 +1,151 @@
+import type { ConnectionOpts } from 'e2b';
+import type { DeferredNamedTemplateSpec } from './template.js';
+/**
+ * Repository clone target plus an optional credential for it.
+ *
+ * Structurally identical to the factory capability of the same name, and
+ * declared here so this package carries no factory dependency: a host can
+ * pass its context accessor straight through.
+ */
+export interface RepositoryAccess {
+    /** https clone URL, e.g. `https://github.com/acme/widgets.git`. */
+    cloneUrl: string;
+    /**
+     * Credential for private repositories. `scheme` describes the credential
+     * itself; git over https accepts only basic auth, so a bearer token is
+     * presented as `x-access-token:<token>` (see {@link gitAuthFlag}).
+     */
+    authorization?: {
+        scheme: 'bearer';
+        token: string;
+    };
+}
+export interface RepoTemplateOptions {
+    /**
+     * Resolves the clone URL and, for private repositories, a SHORT-LIVED
+     * credential (e.g. a GitHub App installation token). Called once per
+     * template resolution: the credential authenticates the head lookup and,
+     * when a build is needed, the build's clone (via `setEnvs` plus an
+     * in-shell `http.extraheader` — it never touches the image filesystem,
+     * and probing confirms `setEnvs` values do not persist into runtime
+     * sandbox environments). Never supply a long-lived PAT: the value enters
+     * the template definition, where only its expiry bounds the exposure. A
+     * rejection degrades to tokenless behavior.
+     *
+     * Sole source of the clone URL, so what gets cloned and what the template
+     * is identified by can never disagree. A public repository needs no
+     * credential: `async () => ({ cloneUrl })`.
+     *
+     * The key is required so that passing a host context whose field was
+     * renamed fails to compile instead of silently producing no template.
+     * `undefined` means the session has no repository, and
+     * {@link createRepoTemplate} then returns undefined.
+     */
+    getRepositoryAccess: (() => Promise<RepositoryAccess | undefined>) | undefined;
+    /**
+     * Setup command run inside the checkout during the build (e.g.
+     * `pnpm install`). Hashed into the template name so a changed setup
+     * command produces a new template.
+     */
+    setupCommand?: string;
+    /**
+     * Extra environment for the build, available to every build step
+     * including {@link RepoTemplateOptions.setupCommand}. Use it for the
+     * credentials a setup command needs (registry tokens, private index
+     * URLs) so the build reaches the same state a runtime setup would.
+     *
+     * Hashed into the template name (keys and values), because env that
+     * changes what setup installs changes the image just as the setup command
+     * does. Rotating a value therefore forces a rebuild — put credentials
+     * that rotate often in {@link RepoTemplateOptions.getRepositoryAccess}
+     * instead, which is excluded from identity.
+     *
+     * Values reach the template definition, so they must be short-lived or
+     * non-secret.
+     */
+    buildEnv?: Record<string, string> | (() => Promise<Record<string, string>>);
+    /**
+     * vCPUs allocated to sandboxes created from this template. Resources are
+     * a property of the built template, not of an individual sandbox, so this
+     * is hashed into the template name — a resize builds a new template
+     * instead of silently reusing one built at the old size. Defaults to the
+     * SDK default (2). Account tier caps the maximum.
+     */
+    cpuCount?: number;
+    /**
+     * Memory in MB allocated to sandboxes created from this template. Hashed
+     * into the template name for the same reason as {@link cpuCount}.
+     * Defaults to the SDK default (1024).
+     */
+    memoryMB?: number;
+}
+/**
+ * Identity inputs for a repo template, already resolved. Separate from
+ * {@link RepoTemplateOptions} because identity must be computable without
+ * awaiting anything, while the clone URL and credential arrive from an
+ * async accessor.
+ */
+export interface RepoTemplateIdentity {
+    /** https clone URL. Host is part of the identity. */
+    cloneUrl: string;
+    /** Resolved head sha. Becomes the template's tag. */
+    sha?: string;
+    setupCommand?: string;
+    buildEnv?: Record<string, string>;
+    cpuCount?: number;
+    memoryMB?: number;
+}
+/**
+ * Compute the deterministic template ref for a set of repo template inputs
+ * without constructing the builder: `mastra-repo-<hash>` named over
+ * (clone URL, setup command, build env), tag-qualified with `:sha-<sha>`
+ * when the sha is known. Exposed so callers (and proofs) can predict which
+ * ref a sandbox will resolve.
+ */
+export declare function repoTemplateRef(identity: RepoTemplateIdentity): string;
+/**
+ * Create a sha-tagged repo template spec for `E2BSandbox`.
+ *
+ * Returns undefined when {@link RepoTemplateOptions.getRepositoryAccess} is
+ * absent, which is how a session with no repository asks for no template —
+ * so a host can write `template: createRepoTemplate(ctx)` without a
+ * conditional.
+ *
+ * Resolution is deferred: right before the exists-then-build check it
+ * resolves the clone URL and credential, resolves the repository's current
+ * default-branch head (`git ls-remote`, ~100ms, no clone), and keys the
+ * template ref as `mastra-repo-<hash>:sha-<head>` — so a moved default
+ * branch produces a fresh tagged build of the SAME template on the next new
+ * session (rebuild-in-place), and an unmoved head reuses the existing
+ * tagged build. When the head cannot be resolved the ref degrades to the
+ * untagged name and the build clones whatever the default branch is at
+ * build time.
+ *
+ * When the build itself fails — inaccessible repo, registry flake — the
+ * sandbox falls back to its fallback template and the session's runtime
+ * setup performs the full clone, so a broken build never wedges a session.
+ */
+export declare function createRepoTemplate(options: RepoTemplateOptions): DeferredNamedTemplateSpec | undefined;
+/** Result of a {@link refreshRepoTemplate} call. */
+export interface RefreshRepoTemplateResult {
+    /** Template ref (`name:tag`) that is now current. */
+    ref: string;
+    /** Whether an up-to-date build already existed or a fresh build ran. */
+    action: 'reused' | 'built';
+    /** Resolved head sha, when it could be determined. */
+    sha?: string;
+}
+/**
+ * Ensure the repo template is built at the repository's current
+ * default-branch head, building it (and moving the `current` tag) when it
+ * is not. This is the same resolution the lazy sandbox-start path performs
+ * — exposed standalone so template warming can be driven externally: call
+ * it from a scheduled workflow (cron) or a merge-to-main event handler and
+ * the next session boots warm instead of paying the build.
+ *
+ * The build is awaited; a build failure rejects so callers can observe it.
+ * An unresolvable head degrades to the sha-less `name:current` form, same
+ * as the lazy path.
+ */
+export declare function refreshRepoTemplate(options: RepoTemplateOptions, connection?: ConnectionOpts): Promise<RefreshRepoTemplateResult>;
+//# sourceMappingURL=repo-template.d.ts.map

package/dist/utils/repo-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-template.d.ts","sourceRoot":"","sources":["../../src/utils/repo-template.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,KAAK,CAAC;AAGzD,OAAO,KAAK,EAAE,yBAAyB,EAAqB,MAAM,YAAY,CAAC;AA4D/E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBAAmB,EAAE,CAAC,MAAM,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/E;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAQtE;AAiDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,yBAAyB,GAAG,SAAS,CAKtG;AAkCD,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,EAC5B,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,yBAAyB,CAAC,CAYpC"}

package/dist/utils/template.d.ts

@@ -33,7 +33,97 @@ import type { TemplateBuilder } from 'e2b';
  * })
  * ```
  */
-export type TemplateSpec = string | TemplateBuilder | ((base: TemplateBuilder) => TemplateBuilder);
+export type TemplateSpec = string | TemplateBuilder | ((base: TemplateBuilder) => TemplateBuilder) | NamedTemplateSpec | DeferredNamedTemplateSpec;
+/**
+ * A template builder paired with a deterministic name (the word E2B's own
+ * `Template.build(template, name)` uses: the name IS the identity, and may
+ * carry a `:tag` qualifier).
+ *
+ * Resolution is lazy build-if-missing: the sandbox checks
+ * `Template.exists(name)` and reuses the existing build when present, so
+ * every sandbox constructed with the same name shares one template. When
+ * the name is missing the build runs once; if the build fails the sandbox
+ * falls back to `fallbackTemplate` (or the default mountable template) so a
+ * broken build degrades to a cold start instead of a wedged session.
+ */
+export interface NamedTemplateSpec {
+    /** Deterministic template ref (`name:tag`, e.g. content-hashed name). */
+    ref: string;
+    /** Builder used when no template exists under the name yet. */
+    template: TemplateBuilder;
+    /**
+     * Template used when the named build fails. May itself be a named spec,
+     * resolved exists-then-build under its own name — one rung only: a named
+     * fallback's own `fallbackTemplate` is ignored, and anything failing past
+     * it lands on the default mountable template. Defaults to the default
+     * mountable template.
+     */
+    fallbackTemplate?: string | TemplateBuilder | NamedTemplateSpec;
+    /**
+     * Ref (`name:tag`) of a previous successful build of this template. When
+     * `name` does not exist yet but this ref does, the sandbox is created
+     * from the stale build immediately and the `name` build is kicked off in
+     * the background (non-blocking rebuild-in-place) — only the very first
+     * build of a template ever blocks a sandbox start.
+     */
+    staleRef?: string;
+    /**
+     * Extra tags assigned alongside the name's tag on every successful build
+     * (e.g. a stable `current` pointer that {@link staleRef} targets).
+     */
+    buildTags?: string[];
+    /**
+     * Machine resources for builds of this template — sandboxes created from
+     * it get exactly these. Applied to the named build and its background
+     * rebuilds. For content-hashed specs the same values must participate in
+     * the name, or a resize would silently reuse a template built at the
+     * old size.
+     */
+    buildResources?: TemplateResources;
+}
+/** Machine resources for a template build. */
+export interface TemplateResources {
+    cpuCount?: number;
+    memoryMB?: number;
+}
+/** Options for the default mountable template. */
+export interface MountableTemplateOptions extends TemplateResources {
+    /**
+     * Exact Node.js version installed over the base image's stale runtime
+     * (`MAJOR.MINOR.PATCH`). Part of the template identity, so changing it
+     * builds a new template. Defaults to {@link DEFAULT_NODE_VERSION}.
+     */
+    nodeVersion?: string;
+}
+/**
+ * Resource defaults matching the e2b SDK's own build defaults. Hashed and
+ * passed to every build explicitly, so a template's identity and its built
+ * artifact can never disagree about machine size — even if the SDK
+ * defaults drift.
+ */
+export declare const DEFAULT_CPU_COUNT = 2;
+export declare const DEFAULT_MEMORY_MB = 1024;
+/**
+ * Node.js version installed into the default template — the current LTS at
+ * pin time. An exact version rather than an `lts` alias so the template's
+ * contents can never drift under a stable identity hash; bump deliberately
+ * (each bump builds new templates).
+ */
+export declare const DEFAULT_NODE_VERSION = "24.20.0";
+export declare function isNamedTemplateSpec(spec: TemplateSpec): spec is NamedTemplateSpec;
+/**
+ * A named spec whose name and build steps are computed at resolution time
+ * rather than construction time — e.g. a repo template that pins itself to
+ * the repository's current default-branch head, fetched right before the
+ * exists-then-build check. `resolveSpec()` runs once per `start()` template
+ * resolution; failures inside it must be handled by the implementation
+ * (return a degraded spec) — a rejection falls through to the sandbox's
+ * default-template fallback.
+ */
+export interface DeferredNamedTemplateSpec {
+    resolveSpec(): Promise<NamedTemplateSpec>;
+}
+export declare function isDeferredNamedTemplateSpec(spec: TemplateSpec): spec is DeferredNamedTemplateSpec;
 /**
  * Result from createMountableTemplate containing both the template and its ID.
  */
@@ -44,12 +134,20 @@ export interface MountableTemplateResult {
     id: string;
     /** List of apt packages installed in the template */
     aptPackages: string[];
+    /**
+     * Machine resources baked into the identity, normalized to the defaults.
+     * Pass these to the build so the artifact matches the hash.
+     */
+    resources: Required<TemplateResources>;
 }
 /**
  * Version of the default mountable template.
  * Increment this when changing the default template dependencies.
+ * v2 added machine resources to the identity hash.
+ * v3 installed a pinned current Node LTS over the base image's stale
+ * runtime and enabled corepack.
  */
-export declare const MOUNTABLE_TEMPLATE_VERSION = "v1";
+export declare const MOUNTABLE_TEMPLATE_VERSION = "v3";
 /**
  * Create a base template with FUSE mounting dependencies pre-installed.
  *
@@ -80,5 +178,5 @@ export declare const MOUNTABLE_TEMPLATE_VERSION = "v1";
  *
  * @returns Object with template builder and deterministic ID
  */
-export declare function createDefaultMountableTemplate(): MountableTemplateResult;
+export declare function createDefaultMountableTemplate(options?: MountableTemplateOptions): MountableTemplateResult;
 //# sourceMappingURL=template.d.ts.map

package/dist/utils/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,eAAe,GAAG,CAAC,CAAC,IAAI,EAAE,eAAe,KAAK,eAAe,CAAC,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,EAAE,eAAe,CAAC;IAC1B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,8BAA8B,IAAI,uBAAuB,CAmBxE"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,eAAe,GACf,CAAC,CAAC,IAAI,EAAE,eAAe,KAAK,eAAe,CAAC,GAC5C,iBAAiB,GACjB,yBAAyB,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,iBAAiB,CAAC;IAChE;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kDAAkD;AAClD,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAI9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,iBAAiB,CAEjF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3C;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,yBAAyB,CAOjG;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,EAAE,eAAe,CAAC;IAC1B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,SAAS,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;CACxC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAkD1G"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/e2b",
-  "version": "0.10.0",
+  "version": "0.11.0-alpha.0",
   "description": "E2B cloud sandbox provider for Mastra workspaces",
   "type": "module",
   "main": "dist/index.js",
@@ -30,14 +30,14 @@
     "dotenv": "^17.4.2",
     "eslint": "^10.7.0",
     "tsdown": "0.22.9",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.126",
-    "@mastra/core": "1.62.0",
-    "@internal/workspace-test-utils": "0.0.70",
-    "@internal/types-builder": "0.0.101",
+    "@internal/types-builder": "0.0.104",
+    "@internal/workspace-test-utils": "0.0.73",
+    "@mastra/core": "1.63.3-alpha.0",
+    "@mastra/s3": "0.6.1",
     "@mastra/gcs": "0.3.2",
-    "@mastra/s3": "0.6.1"
+    "@internal/lint": "0.0.129"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.55.0-0 <2.0.0-0"