eve/dist/src/execution/sandbox/bindings/microsandbox-lifecycle.js

Filesystem-first framework for durable backend AI agents that run anywhere.

import{randomUUID}from"node:crypto";import{mkdir,rename,rm}from"node:fs/promises";import{dirname}from"node:path";import{withDevelopmentSandboxMetadataPathTag}from"#execution/sandbox/development-run.js";import{createFileBackedInternalSandboxSession,touchDirectory}from"#execution/sandbox/bindings/local-provider-utils.js";import{assertDockerDaemonAvailable,createDockerCli}from"#execution/sandbox/bindings/docker-cli.js";import{buildSandboxDockerfile,dockerfileImageReference,publishDockerImageForMicrosandbox}from"#execution/sandbox/dockerfile.js";import{hydrateSandboxProviderResources,prepareImmutableResources}from"#execution/sandbox/bindings/immutable-resources.js";import{createLoggingSandboxSession}from"#execution/sandbox/logging-session.js";import{buildSandboxSession}from"#execution/sandbox/session.js";import{isSandboxPreparedArtifactRecord}from"#shared/sandbox-provider.js";import{SandboxTemplateNotProvisionedError}from"#shared/sandbox-template-error.js";import{MICROSANDBOX_METADATA_VERSION,readSessionMetadata,readTemplateMetadata,resolveMicrosandboxMetadataPath,writeTemplateMetadata}from"#execution/sandbox/bindings/microsandbox-metadata.js";import{connectMicrosandbox,createPreparedMicrosandbox,createProviderName,createStableHash,doesPathExist,loadMicrosandboxModule,removeSnapshotIfExists,sandboxExists,snapshotExists}from"#execution/sandbox/bindings/microsandbox-runtime.js";import{resolveMicrosandboxSessionRootPath,resolveMicrosandboxTemplateRootPath}from"#execution/sandbox/bindings/microsandbox-templates.js";const activeMicrosandboxSessionHandles=new Map;async function prewarmMicrosandboxTemplate(e){e.context.log?.(`loading microsandbox runtime`);let t=await loadMicrosandboxModule({host:e.context.host,log:e.context.log,options:e.options}),n=e.context.storagePath,r=resolveMicrosandboxTemplateRootPath(n,e.templateKey),i=resolveMicrosandboxMetadataPath(r);e.context.log?.(`checking cached snapshot`);let a=await readTemplateMetadata(i);if(a?.optionsHash===e.optionsHash&&await snapshotExists(t,a.snapshotName))return e.context.log?.(`reusing cached snapshot`),await touchDirectory(r),microsandboxTemplateArtifact(a);let o=createProviderName(`eve-sbx-tpl`,e.templateKey,e.optionsHash),s=`${r}.${randomUUID()}.tmp`,c=createProviderName(`eve-sbx-tpl-tmp`,`${e.templateKey}:${randomUUID()}`);await removeSnapshotIfExists(t,o),await rm(s,{force:!0,recursive:!0}),await mkdir(s,{recursive:!0});let l=e.options;if(e.dockerfile!==void 0){let t=createDockerCli();await assertDockerDaemonAvailable(t);let n=dockerfileImageReference({dockerfile:e.dockerfile,templateKey:e.templateKey});e.context.log?.(`building sandbox Dockerfile "${e.dockerfile.path}"`),await buildSandboxDockerfile({cli:t,dockerfile:e.dockerfile,imageReference:n}),e.context.log?.(`publishing Dockerfile image for microsandbox`);let r=await publishDockerImageForMicrosandbox({cli:t,imageReference:n});l={...e.options,image:r,pullPolicy:`always`}}let u=e.context.resources.source,d=u.kind===`materialized`?await prepareImmutableResources({storagePath:e.context.storagePath,provider:e.providerName,resourcesKey:u.key,sourcePath:u.path}):void 0;e.context.log?.(`creating template VM from image "${l.image}"`);let f=await createPreparedMicrosandbox({log:e.context.log,module:t,name:c,networkPolicy:`allow-all`,options:l,resourcesPath:d,sessionKey:e.templateKey,setupBaseRuntime:!0,tags:void 0}),p=buildSandboxSession(createMicrosandboxInternalSession(f),async e=>{await f.setNetworkPolicy(e)});try{await hydrateSandboxProviderResources({copySkills:!0,log:e.context.log,resources:e.context.resources,session:p}),e.prepare!==void 0&&(e.context.log?.(`running sandbox preparation`),await e.prepare(createLoggingSandboxSession({log:e.context.log,session:p}))),e.context.log?.(`snapshotting template VM`),await f.stopAndSnapshot(o),await writeTemplateMetadata(resolveMicrosandboxMetadataPath(s),{image:e.dockerfile===void 0?void 0:l.image,optionsHash:e.optionsHash,snapshotName:o,version:MICROSANDBOX_METADATA_VERSION}),await mkdir(dirname(r),{recursive:!0}),await rm(r,{force:!0,recursive:!0});try{await rename(s,r)}catch(e){if(await doesPathExist(r)){let e=await readTemplateMetadata(i);if(e!==null)return microsandboxTemplateArtifact(e)}throw e}}finally{await f.removePersisted(),await rm(s,{force:!0,recursive:!0}).catch(()=>{})}return microsandboxTemplateArtifact({image:e.dockerfile===void 0?void 0:l.image,optionsHash:e.optionsHash,snapshotName:o,version:MICROSANDBOX_METADATA_VERSION})}async function createMicrosandboxHandle(e){let t=requirePreparedMicrosandboxTemplate(e.artifact,e.providerName),n=e.sessionIdentity??createStableHash(`${e.context.session.id}:${t.snapshotName}:${e.optionsHash}`).slice(0,32),r=resolveMicrosandboxSessionRootPath(e.context.storagePath,n),i=resolveMicrosandboxMetadataPath(r),a=await readSessionMetadata(i),o=resolveMicrosandboxImage(a,t,e.options),s={...e.options,...o,networkPolicy:e.runtimeOptions?.networkPolicy},c=await loadMicrosandboxModule({host:e.context.host,options:s}),l=createActiveMicrosandboxSessionKey(r,e.optionsHash),u=activeMicrosandboxSessionHandles.get(l),d={optionsHash:e.optionsHash,sessionIdentity:n,version:3};if(u!==void 0)return{handle:u,state:d};let f=withDevelopmentSandboxMetadataPathTag({sessionId:e.context.session.id},i);if(a?.optionsHash===e.optionsHash&&(await sandboxExists(c,a.sandboxName)||a.stateSnapshotName!==void 0&&await snapshotExists(c,a.stateSnapshotName))){let t=await connectMicrosandbox({metadata:a,metadataPath:i,module:c,options:s,sessionKey:e.context.session.id,tags:f});if(t!==null)return{handle:cacheHandle(l,createHandle(t,e.optionsHash,()=>{activeMicrosandboxSessionHandles.delete(l)})),state:d}}if(e.sessionIdentity!==void 0&&e.createIfMissing===!1)throw Error(`microsandbox session "${e.sessionIdentity}" is no longer available to resume.`);if(t.optionsHash!==e.optionsHash||!await snapshotExists(c,t.snapshotName))throw new SandboxTemplateNotProvisionedError({providerName:e.providerName,templateKey:t.snapshotName});let p=createProviderName(`eve-sbx-ses`,n),m=await createPreparedMicrosandbox({fromSnapshot:t.snapshotName,module:c,name:p,networkPolicy:s.networkPolicy,options:s,sessionKey:e.context.session.id,setupBaseRuntime:!1,tags:f});return await m.writeMetadata(i,e.optionsHash),{handle:cacheHandle(l,createHandle(m,e.optionsHash,()=>{activeMicrosandboxSessionHandles.delete(l)})),state:d}}function resolveMicrosandboxImage(e,t,n){return e?.image===void 0?t?.image===void 0?{image:n.image,pullPolicy:n.pullPolicy}:{image:t.image,pullPolicy:`always`}:{image:e.image,pullPolicy:`always`}}function microsandboxTemplateArtifact(e){return{image:e.image??null,optionsHash:e.optionsHash,snapshotName:e.snapshotName,version:e.version}}function requirePreparedMicrosandboxTemplate(e,t){if(!isSandboxPreparedArtifactRecord(e)||e.version!==MICROSANDBOX_METADATA_VERSION||typeof e.optionsHash!=`string`||typeof e.snapshotName!=`string`)throw new SandboxTemplateNotProvisionedError({providerName:t,templateKey:`invalid-artifact`});return{image:typeof e.image==`string`?e.image:void 0,optionsHash:e.optionsHash,snapshotName:e.snapshotName,version:MICROSANDBOX_METADATA_VERSION}}function createHandle(e,t,n){return{sandbox:buildSandboxSession(createMicrosandboxInternalSession(e),async t=>{await e.setNetworkPolicy(t)}),async onSessionDelete(){await e.shutdown(),await e.removePersisted(),n?.()},async onSessionStop(){await e.stop(),n?.()},async onRuntimeShutdown(){n?.(),await e.shutdown()}}}function createMicrosandboxInternalSession(e){return createFileBackedInternalSandboxSession({sandbox:e})}function createActiveMicrosandboxSessionKey(e,t){return`${e}\0${t}`}function cacheHandle(e,t){return activeMicrosandboxSessionHandles.set(e,t),t}function clearActiveMicrosandboxSessionHandlesForTest(){activeMicrosandboxSessionHandles.clear()}export{clearActiveMicrosandboxSessionHandlesForTest,createMicrosandboxHandle,prewarmMicrosandboxTemplate};