@mastra/factory 0.11.1 → 0.12.0-alpha.0

package/dist/sandbox/base-checkpoint.js

@@ -1,145 +0,0 @@
-import { materializeRepo, runWorktreeSetup, sh, shellQuote } from "../integrations/github/sandbox.js";
-import { createHash } from "crypto";
-//#region src/sandbox/base-checkpoint.ts
-/**
-* Base-checkpoint build job.
-*
-* Keeps a continuously-refreshed "base checkpoint" per connected repo: a
-* sandbox filesystem with the default branch already cloned and the repo's
-* setup command already run, snapshotted under `repo-<projectRepositoryId>`.
-* New sessions boot from this checkpoint and only pay `git fetch` + branch
-* checkout instead of a cold clone + install.
-*
-* Builds are triggered on repo connect, merges/pushes to the default branch,
-* and the reconcile sweep. Rapid triggers coalesce: only one build runs per
-* repo at a time, and a trigger arriving mid-build marks it dirty so exactly
-* one follow-up build runs afterwards.
-*
-* Providers without real checkpoint support (capability-driven via
-* `supportsCheckpoints`) skip the snapshot — sessions keep using the cold
-* path. A failed build never blocks sessions either; it only logs, and the
-* reconcile sweep retries later.
-*/
-/** Provider checkpoint name for a repo's warm base image. */
-function baseCheckpointName(projectRepositoryId) {
-	return `repo-${projectRepositoryId}`;
-}
-/** Stable hash of the setup command, used to invalidate stale checkpoints. */
-function hashSetupCommand(setupCommand) {
-	if (!setupCommand) return null;
-	return createHash("sha256").update(setupCommand).digest("hex");
-}
-/**
-* Coalescing runner for base-checkpoint builds. One instance per server;
-* `request()` is fire-and-forget safe (never throws).
-*/
-var BaseCheckpointBuilder = class {
-	#fleet;
-	#logger;
-	/** In-flight build per projectRepositoryId. */
-	#inflight = /* @__PURE__ */ new Map();
-	/** Repos re-triggered mid-build: run exactly one follow-up build. */
-	#dirty = /* @__PURE__ */ new Map();
-	constructor(options) {
-		this.#fleet = options.fleet;
-		this.#logger = options.logger;
-	}
-	/** True when a build for this repo is currently running. */
-	isBuilding(projectRepositoryId) {
-		return this.#inflight.has(projectRepositoryId);
-	}
-	/**
-	* Request a (re)build of the repo's base checkpoint. Coalesces with any
-	* in-flight build for the same repo. Resolves when this request's build
-	* (or the follow-up build it folded into) settles. Never rejects.
-	*/
-	request(job) {
-		const key = job.projectRepositoryId;
-		const existing = this.#inflight.get(key);
-		if (existing) {
-			this.#dirty.set(key, job);
-			return existing.then(() => {
-				return this.#inflight.get(key) ?? Promise.resolve();
-			});
-		}
-		const run = this.#buildSafely(job).then(() => {
-			this.#inflight.delete(key);
-			const followUp = this.#dirty.get(key);
-			if (followUp) {
-				this.#dirty.delete(key);
-				return this.request(followUp);
-			}
-		});
-		this.#inflight.set(key, run);
-		return run;
-	}
-	/** One build attempt; logs failures instead of throwing. */
-	async #buildSafely(job) {
-		try {
-			await this.#build(job);
-		} catch (error) {
-			this.#logger?.warn?.(`Base-checkpoint build failed for ${job.repoFullName} (${job.projectRepositoryId}): ${error instanceof Error ? error.message : String(error)}`);
-		}
-	}
-	async #build(job) {
-		if (!this.#fleet.enabled) return;
-		const checkpointName = baseCheckpointName(job.projectRepositoryId);
-		let boundSandboxId = null;
-		const binding = {
-			get sandboxId() {
-				return boundSandboxId;
-			},
-			checkpointName,
-			setSandboxId: async (id) => {
-				boundSandboxId = id;
-			},
-			clear: async () => {
-				boundSandboxId = null;
-			}
-		};
-		const token = await job.getToken();
-		let sandbox;
-		try {
-			sandbox = await this.#fleet.ensureSandbox(binding, { GH_TOKEN: token }, void 0, {
-				workingDirectory: job.workdir,
-				...job.actingUserId ? { actingUserId: job.actingUserId } : {}
-			});
-			if (!sandbox.supportsCheckpoints || !sandbox.snapshot) return;
-			await materializeRepo({
-				row: {
-					id: job.projectRepositoryId,
-					sandboxWorkdir: job.workdir,
-					materializedAt: null
-				},
-				repoInfo: {
-					repoFullName: job.repoFullName,
-					defaultBranch: job.defaultBranch
-				},
-				sandbox,
-				token,
-				storage: { markMaterialized: async () => {} }
-			});
-			if (job.setupCommand) await runWorktreeSetup(sandbox, job.workdir, job.setupCommand);
-			const head = await sh(sandbox, `git -C ${shellQuote(job.workdir)} rev-parse HEAD`);
-			if (head.exitCode !== 0) throw new Error(`Failed to read HEAD after materialize: ${head.stderr}`);
-			const sha = head.stdout.trim();
-			await sandbox.snapshot();
-			await job.storage.projectRepositories.setBaseCheckpoint({
-				id: job.projectRepositoryId,
-				checkpoint: {
-					name: checkpointName,
-					sha,
-					builtAt: /* @__PURE__ */ new Date(),
-					setupCommandHash: hashSetupCommand(job.setupCommand)
-				},
-				expectedSetupCommand: job.setupCommand
-			});
-		} finally {
-			await this.#fleet.teardownSandbox(binding, sandbox).catch(() => {});
-		}
-	}
-};
-//#endregion
-export { BaseCheckpointBuilder, baseCheckpointName, hashSetupCommand };
-
-//# sourceMappingURL=base-checkpoint.js.map

package/dist/sandbox/base-checkpoint.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"base-checkpoint.js","names":["#fleet","#logger","#inflight","#dirty","#buildSafely","#build"],"sources":["../../src/sandbox/base-checkpoint.ts"],"sourcesContent":["/**\n * Base-checkpoint build job.\n *\n * Keeps a continuously-refreshed \"base checkpoint\" per connected repo: a\n * sandbox filesystem with the default branch already cloned and the repo's\n * setup command already run, snapshotted under `repo-<projectRepositoryId>`.\n * New sessions boot from this checkpoint and only pay `git fetch` + branch\n * checkout instead of a cold clone + install.\n *\n * Builds are triggered on repo connect, merges/pushes to the default branch,\n * and the reconcile sweep. Rapid triggers coalesce: only one build runs per\n * repo at a time, and a trigger arriving mid-build marks it dirty so exactly\n * one follow-up build runs afterwards.\n *\n * Providers without real checkpoint support (capability-driven via\n * `supportsCheckpoints`) skip the snapshot — sessions keep using the cold\n * path. A failed build never blocks sessions either; it only logs, and the\n * reconcile sweep retries later.\n */\n\nimport { createHash } from 'node:crypto';\nimport type { IMastraLogger } from '@mastra/core/logger';\nimport { materializeRepo, runWorktreeSetup, sh, shellQuote } from '../integrations/github/sandbox.js';\nimport type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';\nimport type { MaterializationSandbox, SandboxBindingStore, SandboxFleet } from './fleet.js';\n\n/** Provider checkpoint name for a repo's warm base image. */\nexport function baseCheckpointName(projectRepositoryId: string): string {\n  return `repo-${projectRepositoryId}`;\n}\n\n/** Stable hash of the setup command, used to invalidate stale checkpoints. */\nexport function hashSetupCommand(setupCommand: string | null): string | null {\n  if (!setupCommand) return null;\n  return createHash('sha256').update(setupCommand).digest('hex');\n}\n\n/** Everything one build run needs; resolved by the trigger before enqueueing. */\nexport interface BaseCheckpointJob {\n  projectRepositoryId: string;\n  repoFullName: string;\n  defaultBranch: string;\n  setupCommand: string | null;\n  /** Workdir the clone lives at — must match what sessions use. */\n  workdir: string;\n  /** Mint a fresh short-lived installation token for git operations. */\n  getToken(): Promise<string>;\n  storage: SourceControlStorageHandle;\n  actingUserId?: string;\n}\n\n/**\n * Coalescing runner for base-checkpoint builds. One instance per server;\n * `request()` is fire-and-forget safe (never throws).\n */\nexport class BaseCheckpointBuilder {\n  readonly #fleet: SandboxFleet;\n  readonly #logger?: IMastraLogger;\n  /** In-flight build per projectRepositoryId. */\n  readonly #inflight = new Map<string, Promise<void>>();\n  /** Repos re-triggered mid-build: run exactly one follow-up build. */\n  readonly #dirty = new Map<string, BaseCheckpointJob>();\n\n  constructor(options: { fleet: SandboxFleet; logger?: IMastraLogger }) {\n    this.#fleet = options.fleet;\n    this.#logger = options.logger;\n  }\n\n  /** True when a build for this repo is currently running. */\n  isBuilding(projectRepositoryId: string): boolean {\n    return this.#inflight.has(projectRepositoryId);\n  }\n\n  /**\n   * Request a (re)build of the repo's base checkpoint. Coalesces with any\n   * in-flight build for the same repo. Resolves when this request's build\n   * (or the follow-up build it folded into) settles. Never rejects.\n   */\n  request(job: BaseCheckpointJob): Promise<void> {\n    const key = job.projectRepositoryId;\n    const existing = this.#inflight.get(key);\n    if (existing) {\n      // Fold into the in-flight build: remember the latest job so one\n      // follow-up rebuild runs with fresh inputs once the current one ends.\n      this.#dirty.set(key, job);\n      return existing.then(() => {\n        const pending = this.#inflight.get(key);\n        return pending ?? Promise.resolve();\n      });\n    }\n\n    const run = this.#buildSafely(job).then(() => {\n      this.#inflight.delete(key);\n      const followUp = this.#dirty.get(key);\n      if (followUp) {\n        this.#dirty.delete(key);\n        return this.request(followUp);\n      }\n    });\n    this.#inflight.set(key, run);\n    return run;\n  }\n\n  /** One build attempt; logs failures instead of throwing. */\n  async #buildSafely(job: BaseCheckpointJob): Promise<void> {\n    try {\n      await this.#build(job);\n    } catch (error) {\n      this.#logger?.warn?.(\n        `Base-checkpoint build failed for ${job.repoFullName} (${job.projectRepositoryId}): ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n      );\n    }\n  }\n\n  async #build(job: BaseCheckpointJob): Promise<void> {\n    if (!this.#fleet.enabled) return;\n\n    const checkpointName = baseCheckpointName(job.projectRepositoryId);\n    // Ephemeral binding: the builder VM is never reattached to — it exists\n    // only to produce the checkpoint. Incremental rebuilds still happen\n    // because the provider seeds the fresh VM from the previous checkpoint\n    // (same `checkpointName`), so materializeRepo pulls instead of cloning.\n    let boundSandboxId: string | null = null;\n    const binding: SandboxBindingStore = {\n      get sandboxId() {\n        return boundSandboxId;\n      },\n      checkpointName,\n      setSandboxId: async id => {\n        boundSandboxId = id;\n      },\n      clear: async () => {\n        boundSandboxId = null;\n      },\n    };\n\n    const token = await job.getToken();\n    let sandbox: MaterializationSandbox | undefined;\n    try {\n      sandbox = await this.#fleet.ensureSandbox(binding, { GH_TOKEN: token }, undefined, {\n        workingDirectory: job.workdir,\n        ...(job.actingUserId ? { actingUserId: job.actingUserId } : {}),\n      });\n\n      if (!sandbox.supportsCheckpoints || !sandbox.snapshot) {\n        // No real checkpoint support — nothing to build; sessions use the\n        // existing cold path.\n        return;\n      }\n\n      // Clone (cold) or pull (VM seeded from the previous checkpoint).\n      await materializeRepo({\n        row: { id: job.projectRepositoryId, sandboxWorkdir: job.workdir, materializedAt: null },\n        repoInfo: { repoFullName: job.repoFullName, defaultBranch: job.defaultBranch },\n        sandbox,\n        token,\n        storage: { markMaterialized: async () => {} },\n      });\n\n      if (job.setupCommand) {\n        await runWorktreeSetup(sandbox, job.workdir, job.setupCommand);\n      }\n\n      const head = await sh(sandbox, `git -C ${shellQuote(job.workdir)} rev-parse HEAD`);\n      if (head.exitCode !== 0) {\n        throw new Error(`Failed to read HEAD after materialize: ${head.stderr}`);\n      }\n      const sha = head.stdout.trim();\n\n      await sandbox.snapshot();\n\n      await job.storage.projectRepositories.setBaseCheckpoint({\n        id: job.projectRepositoryId,\n        checkpoint: {\n          name: checkpointName,\n          sha,\n          builtAt: new Date(),\n          setupCommandHash: hashSetupCommand(job.setupCommand),\n        },\n        expectedSetupCommand: job.setupCommand,\n      });\n    } finally {\n      // Best-effort teardown: the builder VM is single-use. Route cleanup\n      // through the fleet so the live-sandbox budget is released as well.\n      await this.#fleet.teardownSandbox(binding, sandbox).catch(() => {});\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/sandbox/fleet.d.ts

@@ -1,258 +0,0 @@
-/**
- * Project sandbox fleet: provisioning, reattach, teardown, and budgeting.
- *
- * Server-hosted projects never run on the web host itself. Each project gets
- * its own isolated sandbox (a `WorkspaceSandbox`, e.g. a Railway VM) `clone()`d
- * from the machine the factory was configured with. This module owns everything
- * about that fleet — which provider is active, where checkouts live inside a
- * sandbox, the idle window, the per-replica budget, and the
- * provision/reattach/teardown lifecycle — but knows nothing about what runs
- * inside a sandbox (git materialization lives with its feature, e.g. the
- * GitHub integration's `sandbox.ts`).
- *
- * The fleet is constructed once at boot with the machine config (or none, when
- * sandboxes are disabled) and handed to consumers — no global registry.
- * Persistence of the provider's reattach id is delegated to the caller via
- * {@link SandboxBindingStore}, so the fleet stays storage-agnostic. Tests can
- * swap the low-level construction via {@link SandboxFleet.setFactory}.
- */
-import type { WorkspaceSandbox } from '@mastra/core/workspace';
-/** Minimal command result shape sandbox consumers depend on. */
-export interface SandboxCommandResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}
-/**
- * Minimal live-sandbox surface fleet consumers need: an id, a way to start it,
- * a way to learn the provider's reattach id, and command execution.
- */
-export interface MaterializationSandbox {
-    readonly id: string;
-    /** Human-readable provider name, forwarded from the underlying sandbox. */
-    readonly name?: string;
-    /** Provider type discriminator, forwarded from the underlying sandbox. */
-    readonly provider?: string;
-    /** Sandbox usage instructions surfaced in tool descriptions. */
-    getInstructions?(opts?: {
-        requestContext?: unknown;
-    }): string;
-    /** Long-running process capability, when the provider supports it. */
-    readonly processes?: WorkspaceSandbox['processes'];
-    /** Mount capability, when the provider supports it. */
-    readonly mounts?: WorkspaceSandbox['mounts'];
-    start(): Promise<void>;
-    getInfo(): Promise<{
-        metadata?: Record<string, unknown>;
-    }>;
-    executeCommand(command: string, args?: string[], options?: {
-        timeout?: number;
-        env?: Record<string, string | undefined>;
-    }): Promise<SandboxCommandResult>;
-    /** Update an environment variable for future commands in this sandbox. */
-    setEnvironmentVariable?(name: string, value: string): void;
-    /** Tear down the underlying VM. Optional: providers without it are no-ops. */
-    stop?(): Promise<void>;
-    /** True when the provider persists real checkpoints (snapshot is not a no-op). */
-    readonly supportsCheckpoints?: boolean;
-    /** Persist the sandbox's current state under its bound checkpoint name. */
-    snapshot?(): Promise<void>;
-    /** Boot-only fallback checkpoint requested for this fresh provision. */
-    seedCheckpointNameUsed?: string;
-}
-/** Options for building (or reattaching) one sandbox. */
-export interface SandboxCreateOptions {
-    /** Reattach to this existing provider VM instead of provisioning a new one. */
-    providerSandboxId?: string;
-    /**
-     * Environment variables for commands run in the sandbox. Adapter-level
-     * only: merged into every `executeCommand`, never baked into the provider
-     * VM (see `SandboxFleet.#build`).
-     */
-    env?: Record<string, string>;
-    /** Provider working directory for this sandbox. */
-    workingDirectory?: string;
-    /** Idle teardown window (minutes). The provider stops the VM after this idle period. */
-    idleTimeoutMinutes?: number;
-    /** Provider checkpoint used to seed and preserve this sandbox's filesystem. */
-    checkpointName?: string;
-    /**
-     * Boot-only fallback checkpoint used when `checkpointName` has no stored
-     * state yet (e.g. the repo base checkpoint for a brand-new session).
-     * Snapshots keep writing to `checkpointName`.
-     */
-    seedCheckpointName?: string;
-    /** Opaque user subject attributed to provider API requests. */
-    actingUserId?: string;
-}
-/**
- * A coarse-grained step of the sandbox-preparation flow, reported as it happens
- * so the UI can show the user what the server is doing instead of a static
- * "Preparing…" toast. `phase` is a stable machine token; `message` is
- * user-facing copy.
- */
-export interface PrepareProgress {
-    phase: 'reattaching' | 'provisioning' | 'preparing-workspace' | 'cloning' | 'pulling' | 'finalizing' | 'done';
-    message: string;
-}
-/** Callback invoked with each preparation step. Best-effort; never throws. */
-export type ProgressFn = (event: PrepareProgress) => void;
-/** Invoke a progress callback without letting it break the actual work. */
-export declare function reportProgress(onProgress: ProgressFn | undefined, event: PrepareProgress): void;
-/**
- * Factory that builds a (not-yet-started) sandbox. When `providerSandboxId` is
- * provided the sandbox should reattach to that existing VM instead of
- * provisioning a new one.
- */
-export type SandboxFactory = (opts: SandboxCreateOptions) => MaterializationSandbox;
-/** Raised when provisioning would exceed the per-replica sandbox budget. */
-export declare class SandboxBudgetError extends Error {
-    readonly max: number;
-    readonly code: "sandbox-budget-exceeded";
-    constructor(max: number);
-}
-/** Optional knobs for provisioning/reattaching one sandbox. */
-export interface EnsureSandboxOptions {
-    /** Provider working directory for this sandbox. */
-    workingDirectory?: string;
-    /** Opaque user subject attributed to provider API requests. */
-    actingUserId?: string;
-}
-/**
- * Where a feature persists its sandbox binding. The fleet reads the stored
- * reattach id and writes updates through this seam so it stays agnostic of
- * the owning table (GitHub projects today, anything else tomorrow).
- */
-export interface SandboxBindingStore {
-    /** Stored provider reattach id from a previous provisioning, if any. */
-    readonly sandboxId: string | null;
-    /** Provider checkpoint used to seed and preserve this sandbox's filesystem. */
-    readonly checkpointName?: string;
-    /** Boot-only fallback checkpoint (e.g. repo base checkpoint) for first provision. */
-    readonly seedCheckpointName?: string;
-    /** Persist a freshly provisioned provider id, or clear a stale one with `null`. */
-    setSandboxId(id: string | null): Promise<void>;
-    /** Clear all stored sandbox state (reattach id + materialization mark) on teardown. */
-    clear(): Promise<void>;
-}
-/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
-export declare function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string;
-/**
- * Factory-resolved sandbox runtime the fleet is constructed with: the machine
- * projects clone their per-project sandboxes from, plus the knobs the factory
- * resolved around it.
- */
-export interface SandboxFleetConfig {
-    /**
-     * Template machine (validated by the factory to implement `clone()`).
-     * Never started — acts purely as the credential/default holder that
-     * per-project sandboxes are cloned from.
-     */
-    machine: WorkspaceSandbox;
-    /** In-sandbox base directory repos check out under (no trailing slash). */
-    workdirBase: string;
-    /** Per-replica cap on concurrently provisioned sandboxes. 0 = unlimited. */
-    maxSandboxes?: number;
-}
-/**
- * The sandbox fleet for one deployment. Constructed once at boot — with a
- * config when a sandbox machine was configured, or without one when sandboxes
- * are disabled (every provisioning entry point then throws and
- * {@link enabled} reports `false` so features stay off).
- */
-export declare class SandboxFleet {
-    #private;
-    constructor(config?: SandboxFleetConfig);
-    /**
-     * True when a sandbox machine was configured. The factory validates the
-     * machine implements `clone()` at boot, so a configured fleet is usable —
-     * sandbox-backed projects stay off only when the slot was omitted.
-     */
-    get enabled(): boolean;
-    /**
-     * Name of the active sandbox provider — the configured machine's `provider`
-     * discriminator (`'railway'`, `'local'`, …), or `'none'` when the fleet was
-     * constructed without a config. Diagnostic only; feature gating goes
-     * through {@link enabled}.
-     */
-    get provider(): string;
-    /**
-     * Usage instructions from the configured template machine, for surfacing in
-     * tool descriptions before any per-session sandbox has materialized.
-     * Empty string when no machine is configured or it exposes none.
-     */
-    getInstructions(): string;
-    /**
-     * Idle teardown window for provisioned sandboxes, in minutes; defaults to 30.
-     * Read back from the machine's own config when it exposes one
-     * (Railway's `idleTimeoutMinutes`) — the knob lives on the sandbox, the
-     * fleet only needs it to schedule GC and stamp sandbox clones. Advisory:
-     * providers without idle GC ignore it, and a re-open detects a torn-down VM
-     * and re-provisions cleanly.
-     */
-    get idleMinutes(): number;
-    /**
-     * Per-replica cap on concurrently *provisioned* sandboxes. 0 means unlimited.
-     * This is a lightweight per-process budget to keep a single replica from
-     * exhausting provider quota — it is not a global, cross-replica scheduler
-     * (that is a deferred follow-up).
-     */
-    get maxSandboxes(): number;
-    /**
-     * Count of sandboxes this fleet has freshly provisioned and not yet torn
-     * down. Reattaches to existing VMs do not count (they reuse an already-billed
-     * sandbox). Used to enforce {@link maxSandboxes}.
-     */
-    get liveCount(): number;
-    /** For tests: reset the live-sandbox counter to a known state. */
-    __resetLiveCount(value?: number): void;
-    /** Override the sandbox factory (tests). */
-    setFactory(factory: SandboxFactory): void;
-    /** Reset to the default machine-cloning factory. */
-    resetFactory(): void;
-    /**
-     * Compute the in-sandbox working directory for a repo: a nested
-     * `<base>/<owner>/<name>` layout under the factory-resolved checkout base.
-     * Nesting keeps same-name repos apart (`acme/api` vs `other/api`) — cloud
-     * sandboxes are one-per-project so it's merely tidy there, but local
-     * checkouts share one host root where it prevents collisions. Server-side
-     * only; never derived from client input.
-     */
-    computeWorkdir(repoFullName: string): string;
-    /**
-     * Compute the host working directory for a local GitHub session checkout.
-     * This is server-derived only: repo pieces are sanitized and the trusted
-     * session id is kept as a single path segment under the configured local root.
-     */
-    computeLocalSessionWorkdir(repoFullName: string, sessionId: string): string;
-    /**
-     * Provision a new sandbox (persisting its provider id on first open) or
-     * reattach to the stored one. Returns a started, live sandbox.
-     *
-     * Concurrent calls for the same binding coalesce onto one in-flight
-     * provision/reattach and share its sandbox handle — N simultaneous requests
-     * for one cold session (e.g. several browser tabs polling right after boot)
-     * must not each fire their own `POST /sandbox` against the provider.
-     * Failures are not cached: once the shared attempt settles, the next call
-     * starts fresh.
-     */
-    ensureSandbox(store: SandboxBindingStore, onProgress?: ProgressFn): Promise<MaterializationSandbox>;
-    ensureSandbox(store: SandboxBindingStore, env?: Record<string, string>, onProgress?: ProgressFn, options?: EnsureSandboxOptions): Promise<MaterializationSandbox>;
-    /**
-     * Tear down a sandbox binding: stop the live VM (best-effort) and clear the
-     * persisted state through the binding store so the next open re-provisions
-     * cleanly. Decrements the per-replica live-sandbox counter.
-     *
-     * @param store   the binding to tear down
-     * @param sandbox an already-reattached live sandbox to stop, when available
-     */
-    teardownSandbox(store: SandboxBindingStore, sandbox?: MaterializationSandbox): Promise<void>;
-    /**
-     * Reattach to an already-provisioned sandbox by its provider id and start it.
-     * Used by the workspace seam when opening a project that was already
-     * materialized (sandbox id + workdir carried on controller state), so no DB
-     * round-trip is needed.
-     */
-    reattachSandbox(providerSandboxId: string, options?: EnsureSandboxOptions): Promise<MaterializationSandbox>;
-}
-//# sourceMappingURL=fleet.d.ts.map

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

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