import type { SandboxCapabilities, SandboxEnv, SandboxFactory } from './sandbox.js';
export interface SandboxRef {
    /** Stable, portable id for the underlying sandbox. */
    id: string;
    /** Capabilities reported by the underlying sandbox at registration time. */
    capabilities?: SandboxCapabilities;
    /** Sandbox cwd at registration time. */
    cwd: string;
    /** Free-form provider-specific routing data (used by cross-process refs in future). */
    metadata?: Record<string, unknown>;
}
/**
 * Cross-process / cross-machine sandbox reference. Created by
 * `session.sandboxRef({ portable: true })` and re-attached via
 * `attachSandbox(serialized)` in a separate process. Each `provider` string
 * maps to a decoder registered via `registerSandboxRefDecoder()`.
 */
export interface SerializedSandboxRef {
    /** Stable identity used for ownership leases and audit correlation. */
    referenceId?: string;
    /** Provider identifier — must match a registered decoder. */
    provider: string;
    /** Provider-specific routing data (sandbox/workspace/pod ID, region, etc.). */
    providerData: unknown;
    /** Sandbox cwd at encode time. */
    cwd: string;
    /** Capabilities snapshot at encode time. */
    capabilities?: SandboxCapabilities;
    /** Owner session id, for audit trails. */
    ownerSessionId?: string;
    /** Tenant that owns this sandbox. Attach requires the same tenant when set. */
    tenantId?: string;
    /** ISO timestamp of encoding. */
    encodedAt: string;
}
export type SandboxContinuityMode = 'reconnect' | 'snapshot' | 'restore' | 'fork' | 'none';
export interface SandboxContinuityCapabilities {
    reconnect: boolean;
    snapshot: boolean;
    restore: boolean;
    fork: boolean;
    modes: SandboxContinuityMode[];
}
/** Report the continuity operations that a backend or serialized ref can support. */
export declare function negotiateSandboxContinuity(value: SandboxEnv | SandboxRef | SerializedSandboxRef): SandboxContinuityCapabilities;
export interface SandboxOwnershipLeaseStore {
    prepare?(): Promise<void>;
    claim(key: string, ownerId: string, expiresAt: number, now: number): Promise<boolean>;
    renew(key: string, ownerId: string, expiresAt: number, now: number): Promise<boolean>;
    release(key: string, ownerId: string): Promise<void>;
}
export interface SandboxOwnershipOptions {
    store: SandboxOwnershipLeaseStore;
    /** Unique worker/replica identity. Reusing this value across workers defeats fencing. */
    ownerId: string;
    leaseMs?: number;
    now?: () => number;
}
export interface AttachSandboxOptions {
    tenantId?: string;
    ownership?: SandboxOwnershipOptions;
}
/** Process-local lease store for tests and single-replica durable workers. */
export declare function memorySandboxOwnershipLeaseStore(): SandboxOwnershipLeaseStore;
/**
 * Decoder for a `SerializedSandboxRef.provider`. Returns a SandboxFactory
 * that, when invoked, produces a SandboxEnv connected to the existing
 * remote sandbox identified by `providerData`.
 *
 * Decoders SHOULD attach without owning the remote sandbox's lifecycle —
 * the returned env's `cleanup()` should detach, not destroy.
 */
export type SandboxRefDecoder = (providerData: unknown, context: {
    cwd: string;
    capabilities?: SandboxCapabilities;
}) => SandboxFactory;
/**
 * Register a decoder for `provider` so `attachSandbox(serialized)` can
 * rehydrate a sandbox from another process. Typically called once at
 * startup by the package that owns the provider integration (e.g.
 * `@fabric-harness/connectors/e2b` registers the `e2b` provider).
 */
export declare function registerSandboxRefDecoder(provider: string, decoder: SandboxRefDecoder): void;
/** Test/internal: remove a decoder. */
export declare function unregisterSandboxRefDecoder(provider: string): void;
/** Returns the list of currently registered providers. */
export declare function listSandboxRefDecoders(): string[];
/**
 * Register a sandbox in the in-process registry and return a portable ref.
 * Subsequent calls for the same env return the same ref.
 */
export declare function registerSandbox(env: SandboxEnv, options?: {
    ownerSessionId?: string;
}): SandboxRef;
/**
 * Mark a registered sandbox as dead so future attach attempts fail.
 * Called from the owner session's cleanup path.
 */
export declare function unregisterSandbox(refId: string): void;
/**
 * Build a `SandboxFactory` that, when invoked, returns an `AttachedSandboxEnv`
 * delegating to the registered sandbox without owning its lifecycle. Calling
 * `cleanup()` on the attached env unregisters this attachment but does NOT
 * tear down the underlying sandbox.
 *
 * Pass an in-process `SandboxRef` to attach within the same process, or a
 * `SerializedSandboxRef` (from `session.sandboxRef({ portable: true })`) to
 * rehydrate a sandbox handed off from another process. Cross-process refs
 * require a decoder registered for `serialized.provider` via
 * `registerSandboxRefDecoder()`.
 */
export declare function attachSandbox(ref: SandboxRef | SerializedSandboxRef, options?: AttachSandboxOptions): SandboxFactory;
/**
 * Serialize an in-process `SandboxRef` into the cross-process form.
 * Requires the underlying sandbox to implement `encodeRef()`. Throws
 * `SANDBOX_UNAVAILABLE` if the backend is in-process-only.
 */
export declare function serializeSandboxRef(ref: SandboxRef, ownerSessionId?: string, tenantId?: string): SerializedSandboxRef;
/** Claim exclusive ownership of an already-connected portable sandbox. */
export declare function claimSandboxOwnership(ref: SerializedSandboxRef, env: SandboxEnv, options: SandboxOwnershipOptions): Promise<SandboxEnv>;
/** Test-only: clear the registry. */
export declare function _resetSandboxRegistry(): void;
//# sourceMappingURL=sandbox-ref.d.ts.map