import type { AdapterExecutionTarget, AdapterExecutionTargetPaperclipBridgeHandle, AdapterExecutionTargetProcessSessionBridgeHandle, AdapterManagedRuntimeAsset, PreparedAdapterExecutionTargetRuntime } from "@tickernelz/paperclip-pro-adapter-utils/execution-target";
import type { AcpRunContext, AcquiredRunResources, LaunchEnvironmentContribution, PlacedWorkspace, ReadyRunResources, RunSiteTransport, SandboxReuseCandidate, SessionReuseStore, SitePlan } from "./run-contracts.js";
import type { WorkspaceRestoreOutcome } from "../workspace-restore-merge.js";
/**
 * One staged in-sandbox runtime the store keeps for the next compatible resume.
 * It is the value the staged-runtime map holds. The engine still owns this shape;
 * the store reads its `lastUsedAt` and its `dispose` through the config
 * accessors. The staged cache has no per-entry idle timer, so the entry carries
 * none — the run-start sweep is the only eviction path.
 */
export interface StagedRuntimeStoreEntry {
    stagedRuntime: PreparedAdapterExecutionTargetRuntime;
    envDelta: Record<string, string>;
    teardown: (() => Promise<WorkspaceRestoreOutcome>) | null;
    dispose: (() => Promise<void>) | null;
    lastUsedAt: number;
}
/**
 * The result of one workspace stage into the sandbox. The site records these
 * fields on the run and, after a clean turn, into the staged store.
 */
export interface StagedWorkspace {
    readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
    readonly teardown: (() => Promise<WorkspaceRestoreOutcome>) | null;
    readonly dispose: (() => Promise<void>) | null;
    readonly envDelta: Record<string, string>;
    /** True when the run reused an already-staged runtime rather than staging fresh. */
    readonly reused: boolean;
}
/** The leaf staging primitive the engine injects. It ships one asset set. */
export type StageWorkspace = (assets: AdapterManagedRuntimeAsset[]) => Promise<PreparedAdapterExecutionTargetRuntime>;
/**
 * The managed-home seam result, in the shape the site consumes. The engine maps
 * its adapter seam onto this before it passes the seam in.
 */
export interface ManagedHomeSeamResult {
    readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
    readonly teardown: (() => Promise<WorkspaceRestoreOutcome>) | null;
    readonly dispose: (() => Promise<void>) | null;
}
/** The construction options for the sandbox site. Every value is per run. */
export interface SandboxRunSiteOptions {
    /** The run ledger. `executeAcpxEngine` creates it and passes it in (one ledger). */
    readonly ledger: AcquiredRunResources;
    /** The staged-runtime map the store operates over. The engine owns it across runs. */
    readonly stagedRuntimes: Map<string, StagedRuntimeStoreEntry>;
    /** The per-key staging mutex the lease and the sweep share. */
    readonly stagingLocks: Map<string, Promise<unknown>>;
    readonly now: () => number;
    /** The staged-idle bound, in milliseconds. `0` or less disables the sweep. */
    readonly idleMs: number;
    /** The in-sandbox workspace dir the session binds to (a fingerprint input). */
    readonly sessionCwd: string;
    /** The host spawn cwd for the relay proxy on the remote process-session lane. */
    readonly spawnCwd: string;
    /** The remote runner-backed sandbox target. */
    readonly target: AdapterExecutionTarget;
    /**
     * The run env the site mutates in place. Staging repoints the managed-home env
     * var onto the in-sandbox home here, and the site captures the delta from it.
     */
    readonly env: Record<string, string>;
    /**
     * True when the supplied session params resume THIS staged session. Only a
     * compatible resume may reuse the already-staged runtime.
     */
    readonly isCompatibleResume: boolean;
    /** Ship the workspace (and, via the seam, the managed home) into the sandbox. */
    readonly stage: StageWorkspace;
    /**
     * Seed the managed home through `stage`, repoint the home env var, and wire the
     * per-run copy-back. Absent for custom agents and the shared-engine tests, where
     * the site stages the workspace with no home asset.
     */
    readonly seedManagedHome?: (stage: StageWorkspace) => Promise<ManagedHomeSeamResult>;
    /**
     * Remove a freshly staged in-sandbox runtime after the seam threw. The site
     * fires it when the seam fails after a successful stage.
     */
    readonly disposeFreshStagedRuntime: (stagedRuntime: PreparedAdapterExecutionTargetRuntime) => Promise<void>;
    /** Wrap the `stage.sync` step in the run's startup step timer. */
    readonly measureStageStep: <T>(run: () => Promise<T>) => Promise<T>;
    /** Publish the referenced-project workspace hints after a fresh stage. */
    readonly publishStagedProjectHints: (stagedProjectDirs: Record<string, string>) => void;
    readonly onReuseLog: () => Promise<void>;
    /** Start the host-side paperclip callback bridge. */
    readonly startPaperclipBridge: (runtimeRootDir: string | null) => Promise<AdapterExecutionTargetPaperclipBridgeHandle | null>;
    /** Start the host-side process-session bridge with a deferred launch env. */
    readonly startProcessSessionBridge: (input: {
        runtimeRootDir: string | null;
        launchEnv: () => Promise<Record<string, string>>;
    }) => Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null>;
    /** Wrap each concurrent bridge start in the run's startup step timer. */
    readonly measureBridgeStep: <T>(step: "bridge.paperclip" | "bridge.process-session", run: () => Promise<T>) => Promise<T>;
    /**
     * Finalize the run's branded launch environment from the bridge contribution.
     * The engine owns `finalizeLaunchEnvironment`, so it stays the sole consumer of
     * a contribution; the site calls this capability at the sequencing point.
     */
    readonly finalizeLaunchEnv: (contributions: readonly LaunchEnvironmentContribution[]) => Record<string, string>;
    readonly onPaperclipBridgeLog: () => Promise<void>;
    /** Stop both bridges and run the managed-home copy-back on teardown. */
    readonly stopBridges: (input: {
        controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;
        agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;
    }) => Promise<void>;
}
/** The transport the sandbox site started, plus the run-scoped launch env. */
export interface SandboxRunSiteTransport extends RunSiteTransport {
    /** The finalized launch env for the process launch. */
    readonly launchEnv: Record<string, string>;
}
/** The sandbox run site. It owns staging, the lease, both bridges, and sync-back. */
export interface SandboxRunSite {
    readonly kind: "sandbox";
    plan(context: AcpRunContext): SitePlan;
    placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace>;
    startTransport(context: AcpRunContext): Promise<SandboxRunSiteTransport>;
    reuse(): SessionReuseStore<StagedRuntimeStoreEntry>;
    reuseCandidate(resources: ReadyRunResources): SandboxReuseCandidate;
    syncBack(context: AcpRunContext): Promise<void>;
    /** The staged workspace the run installed or reused, or null before `placeWorkspace`. */
    readonly staged: StagedWorkspace | null;
    /**
     * The paperclip callback bridge the run started, or null before
     * `startTransport` or on the host lane. `startTransport` sets it before it
     * rethrows a partial-bring-up failure, so an abandon path can stop the bridge
     * that started when its sibling threw.
     */
    readonly controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;
    /** The process-session bridge the run started, or null before `startTransport`. */
    readonly agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;
    /**
     * Release the per-session staging lease `placeWorkspace` acquired, or null
     * before `placeWorkspace`. An abandon path calls it to free the lease when the
     * run never reaches sync-back.
     */
    readonly stagingLeaseRelease: (() => void) | null;
}
/** Create the sandbox run site over the engine's staged-runtime map and ledger. */
export declare function createSandboxRunSite(options: SandboxRunSiteOptions): SandboxRunSite;
//# sourceMappingURL=run-site-sandbox.d.ts.map