import { type SandboxBackendProtocolV2 } from "deepagents";
import type { IdentityDefinition } from "../identity/index.js";
import type { SandboxDefinition } from "../sandbox.js";
import { type Connector } from "./connector.js";
import type { ManagedRunConfig } from "./types.js";
/** Deployment secret naming the recipe snapshot baked at `mda deploy`. */
export declare const RECIPE_SNAPSHOT_ENV = "MDA_SANDBOX_RECIPE_SNAPSHOT";
/**
 * Env var naming the workspace the CLI baked the recipe snapshot into.
 *
 * `mda deploy` sets it on the deployment and `mda dev` stages it into the local
 * `.env`. Sandboxes and snapshots are workspace-scoped, so the runtime must
 * send it too — an API key whose default workspace differs from this one
 * resolves `snapshotName` in the wrong workspace and 404s on the recipe.
 */
export declare const WORKSPACE_ID_ENV = "LANGSMITH_WORKSPACE_ID";
/** Optional runtime inputs that drive connector sandbox provisioning. */
export interface ResolveManagedSandboxOptions {
    connectors?: Connector[];
    identity?: IdentityDefinition;
}
/**
 * Resolve (and cache) the per-thread LangSmith sandbox backend for this run.
 * When deploy baked a recipe, new sandboxes clone it; otherwise Host supplies
 * its default image.
 *
 * Connectors that implement {@link Connector.sandbox} run on create, when a
 * new thread starts against a reused sandbox (mode `"reuse"`), and on later
 * messages in an already-synced thread (mode `"credentials"`).
 */
export declare function resolveManagedSandbox(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined, options?: ResolveManagedSandboxOptions): Promise<SandboxBackendProtocolV2>;
/** Derive the process-level reuse key (always one sandbox per thread). */
export declare function sandboxScopeKey(config: ManagedRunConfig | undefined): string;
/** Clear the process-level sandbox cache. Test-only. */
export declare function clearManagedSandboxCacheForTests(): void;
/** Options that pin invalidation to the sandbox that actually failed. */
export interface InvalidateManagedSandboxOptions {
    /** Backend id captured before the failing operation. */
    expectedBackendId?: string;
    /** Host box name captured before the failing operation. */
    expectedHostName?: string;
}
/**
 * Drop a cached sandbox and delete its Host box so recreate cannot adopt it.
 *
 * Process-cache clear alone is not enough under deploy: names are deterministic
 * per thread, so the next resolve would re-adopt the same broken box. Mark the
 * name blocked (delete can lag) and best-effort `deleteSandbox`.
 *
 * When `expectedBackendId` / `expectedHostName` are set, only pop the cache
 * entry if it still refers to that failing sandbox. A concurrent sibling may
 * already have replaced it — deleting the replacement would strand the healthy
 * recreate.
 */
export declare function invalidateManagedSandbox(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined, options?: InvalidateManagedSandboxOptions): Promise<void>;
/** Host box name recorded for a resolved backend instance. */
export declare function managedSandboxHostName(backend: object): string | undefined;
/** True when a sandbox API error is worth invalidating + recreating once. */
export declare function isTransientSandboxError(error: unknown): boolean;
/**
 * Deployment this runtime belongs to, used to name the sandboxes it creates so
 * `mda delete` can find them again.
 *
 * `MDA_DEPLOYMENT_NAME` is injected by `mda deploy`; `LANGSMITH_DEPLOYMENT_NAME`
 * is the platform's own value and is preferred when present. Undefined under
 * local `mda dev`, where sandboxes stay unnamed and LangSmith generates a name.
 */
export declare function managedDeploymentName(): string | undefined;
/**
 * Deterministic sandbox name for a deployment and thread.
 *
 * The thread key is digested rather than embedded so names stay short and
 * stable across container restarts. Recipe (`setup.sh` / bake base) changes do
 * **not** rename live boxes — new threads clone the new recipe; live threads
 * keep `/workspace` until idle reclaim.
 */
export declare function managedSandboxName(deployment: string, scopeKey: string): string;
/**
 * Reconstruct the 0.5.x Host box name for one thread.
 *
 * 0.5.x hashed the thread scope plus the options it sent to `createSandbox`.
 * 0.6.0 hashes only the thread id, so a live 0.5.x box is invisible under the
 * new name. Used only to reconnect that existing box — new threads are still
 * created under {@link managedSandboxName}.
 */
export declare function legacyManagedSandboxName(deployment: string, scopeKey: string, createOptions?: Record<string, unknown>): string;
/**
 * Options for `createSandbox`. Thread boxes clone the deploy-baked recipe when
 * present; author `snapshotName` / `snapshotId` / `dockerImage` are bake bases
 * only and are not passed here.
 */
export declare function sandboxCreateOptions(sandbox: SandboxDefinition): Record<string, unknown>;
/**
 * Constructor options for the LangSmith sandbox client.
 *
 * Both the API key and the workspace scope come from the environment `mda`
 * wrote, so every sandbox call lands in the workspace holding the baked recipe.
 */
export declare function sandboxClientOptions(sandbox: SandboxDefinition): {
    apiKey?: string;
    headers?: Record<string, string>;
} | undefined;
//# sourceMappingURL=sandbox-manager.d.ts.map