@agent-vm/agent-vm 0.0.93 → 0.0.95

package/dist/integration-tests/e2e-harness.js

@@ -1,19 +1,26 @@
 import { execFile, execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { setTimeout as waitForRetryInterval } from 'node:timers/promises';
 import { promisify } from 'node:util';
 import { hasBuiltImageAssets, resolveGondolinMinimumZigVersion } from '@agent-vm/gondolin-adapter';
 import { computeFingerprintFromConfigPath } from '../build/gondolin-image-builder.js';
 import { generateManagedDockerfile, resolveManagedImageRelease, } from '../build/managed-image-dockerfile.js';
+import { readPreparedGondolinImage, writePreparedGondolinImage, } from '../build/prepared-gondolin-image-cache.js';
 import { isZigVersionAtLeast, resolveHostZigVersion } from '../build/zig-compatibility.js';
+import { runBuildCommand } from '../cli/build-command.js';
 import { scaffoldAgentVmProject } from '../cli/init-command.js';
 import { loadJsonConfigFile } from '../config/json-config-file.js';
 import { loadSystemConfig } from '../config/system-config.js';
 import { startControllerRuntime } from '../controller/controller-runtime.js';
 import { startGatewayZone } from '../gateway/gateway-zone-orchestrator.js';
 const defaultOpenClawMcpPortalExtensionsPath = '/home/openclaw/.openclaw/extensions/mcp-portal';
+const dockerContextLocalPackageTimestamp = new Date('2000-01-01T00:00:00.000Z');
+const e2ePreparedImageManifestFileName = 'prepared-e2e-images.json';
+const e2ePreparedImageManifestSchemaVersion = 1;
 const execFileAsync = promisify(execFile);
 const openClawMcpPortalPluginName = 'mcp-portal';
 const e2eTempRootPrefixes = [
@@ -32,6 +39,9 @@ function resolveE2eCacheRoot() {
     }
     return path.join(os.tmpdir(), 'agent-vm-e2e-cache');
 }
+function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export function shouldCleanupE2eDockerImages(options = {}) {
     const env = options.env ?? process.env;
     return options.cleanupImages === true || env.AGENT_VM_E2E_CLEAN_IMAGES === '1';
@@ -114,17 +124,253 @@ export async function findAvailablePort() {
         });
     });
 }
+function readNodeNetworkErrorCode(error) {
+    if (!(error instanceof TypeError) || error.message !== 'fetch failed') {
+        return null;
+    }
+    const cause = error.cause;
+    if (typeof cause !== 'object' || cause === null || !('code' in cause)) {
+        return null;
+    }
+    return typeof cause.code === 'string' ? cause.code : null;
+}
+function isRecoverableControllerReadyError(error) {
+    return ['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH'].includes(readNodeNetworkErrorCode(error) ?? '');
+}
 export async function waitForControllerReady(controllerPort) {
-    for (let attempt = 0; attempt < 40; attempt += 1) {
-        // oxlint-disable-next-line eslint/no-await-in-loop -- readiness polling is sequential
-        const response = await fetch(`http://127.0.0.1:${controllerPort}/controller-status`).catch(() => null);
-        if (response?.ok) {
-            return;
+    const timeoutMs = 5_000;
+    const retryIntervalMs = 50;
+    const startedAtMs = performance.now();
+    let lastError = 'not attempted';
+    while (performance.now() - startedAtMs <= timeoutMs) {
+        try {
+            // oxlint-disable-next-line no-await-in-loop -- controller startup readiness must observe sequential protocol state.
+            const response = await fetch(`http://127.0.0.1:${String(controllerPort)}/controller-status`, {
+                signal: AbortSignal.timeout(1_000),
+            });
+            if (response.ok) {
+                return;
+            }
+            lastError = `HTTP ${String(response.status)}`;
+        }
+        catch (error) {
+            if (!isRecoverableControllerReadyError(error)) {
+                throw error;
+            }
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        // oxlint-disable-next-line no-await-in-loop -- controller readiness has no event source from the subprocess boundary.
+        await waitForRetryInterval(retryIntervalMs);
+    }
+    throw new Error(`Controller did not report ready within ${String(timeoutMs)}ms. Last error: ${lastError}`);
+}
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function listDirectoryFiles(directoryPath) {
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const entryPath = path.join(directoryPath, entry.name);
+        if (entry.isDirectory()) {
+            return await listDirectoryFiles(entryPath);
+        }
+        return entry.isFile() ? [entryPath] : [];
+    }));
+    return files.flat().toSorted((leftPath, rightPath) => leftPath.localeCompare(rightPath));
+}
+async function hashFileInto(hasher, filePath, baseDirectory) {
+    const relativePath = path.relative(baseDirectory, filePath).split(path.sep).join('/');
+    hasher.update(`file:${relativePath}\0`);
+    hasher.update(await fs.readFile(filePath));
+    hasher.update('\0');
+}
+async function computeDockerContextFingerprint(dockerfilePath) {
+    const dockerContextDirectory = path.dirname(dockerfilePath);
+    const hasher = crypto.createHash('sha256');
+    for (const filePath of await listDirectoryFiles(dockerContextDirectory)) {
+        // oxlint-disable-next-line no-await-in-loop -- hash order is deterministic and low-volume for e2e Docker contexts.
+        await hashFileInto(hasher, filePath, dockerContextDirectory);
+    }
+    return hasher.digest('hex');
+}
+async function readTextIfPresent(filePath) {
+    if (filePath === undefined || !(await pathExists(filePath))) {
+        return undefined;
+    }
+    return await fs.readFile(filePath, 'utf8');
+}
+async function normalizeE2eImageSourceForFingerprint(source) {
+    if (!isObjectRecord(source)) {
+        return source;
+    }
+    const overlay = source.overlay;
+    return {
+        ...source,
+        ...(typeof overlay === 'string'
+            ? { overlay: { content: await readTextIfPresent(overlay) } }
+            : {}),
+    };
+}
+async function computeE2eImageRecipeFingerprint(options) {
+    const hasher = crypto.createHash('sha256');
+    hasher.update(JSON.stringify({
+        buildConfig: await readTextIfPresent(options.buildConfigPath),
+        dockerContext: options.dockerfile === undefined
+            ? undefined
+            : await computeDockerContextFingerprint(options.dockerfile),
+        source: await normalizeE2eImageSourceForFingerprint(options.source),
+    }));
+    return hasher.digest('hex');
+}
+async function collectE2eImageTargets(project) {
+    const createImageTarget = async (family, profileName, profile) => {
+        const target = {
+            buildConfigPath: profile.buildConfig,
+            cacheDirectory: path.join(project.systemConfig.cacheDir, family === 'gateway' ? 'gateway-images' : 'tool-vm-images', profileName),
+            e2eManifestEligible: profile.source === undefined,
+            family,
+            name: profileName,
+            recipeFingerprint: await computeE2eImageRecipeFingerprint({
+                buildConfigPath: profile.buildConfig,
+                ...(profile.dockerfile === undefined ? {} : { dockerfile: profile.dockerfile }),
+                ...(profile.source === undefined ? {} : { source: profile.source }),
+            }),
+        };
+        if (profile.dockerfile !== undefined) {
+            return { ...target, dockerfile: profile.dockerfile };
+        }
+        if (profile.source !== undefined) {
+            return { ...target, source: profile.source };
+        }
+        return target;
+    };
+    const gatewayTargets = await Promise.all(Object.entries(project.systemConfig.imageProfiles.gateways).map(async ([profileName, profile]) => await createImageTarget('gateway', profileName, profile)));
+    const toolVmTargets = await Promise.all(Object.entries(project.systemConfig.imageProfiles.toolVms).map(async ([profileName, profile]) => await createImageTarget('toolVm', profileName, profile)));
+    return [...gatewayTargets, ...toolVmTargets];
+}
+function e2ePreparedImageManifestPath(cacheDir) {
+    return path.join(cacheDir, e2ePreparedImageManifestFileName);
+}
+function parseE2ePreparedImageManifest(value) {
+    if (!isObjectRecord(value) || value.schemaVersion !== e2ePreparedImageManifestSchemaVersion) {
+        return { entries: [], schemaVersion: e2ePreparedImageManifestSchemaVersion };
+    }
+    if (!Array.isArray(value.entries)) {
+        return { entries: [], schemaVersion: e2ePreparedImageManifestSchemaVersion };
+    }
+    const entries = value.entries.filter((entry) => {
+        if (!isObjectRecord(entry)) {
+            return false;
+        }
+        return ((entry.family === 'gateway' || entry.family === 'toolVm') &&
+            typeof entry.name === 'string' &&
+            typeof entry.recipeFingerprint === 'string' &&
+            typeof entry.buildConfigPath === 'string' &&
+            typeof entry.cacheDirectory === 'string' &&
+            typeof entry.fingerprint === 'string' &&
+            typeof entry.imagePath === 'string');
+    });
+    return { entries, schemaVersion: e2ePreparedImageManifestSchemaVersion };
+}
+async function readE2ePreparedImageManifest(cacheDir) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(e2ePreparedImageManifestPath(cacheDir), 'utf8'));
+        return parseE2ePreparedImageManifest(parsed);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return { entries: [], schemaVersion: e2ePreparedImageManifestSchemaVersion };
+        }
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            return { entries: [], schemaVersion: e2ePreparedImageManifestSchemaVersion };
+        }
+        throw error;
+    }
+}
+async function writeE2ePreparedImageManifest(cacheDir, manifest) {
+    await fs.mkdir(cacheDir, { recursive: true });
+    await fs.writeFile(e2ePreparedImageManifestPath(cacheDir), `${JSON.stringify(manifest, null, '\t')}\n`, 'utf8');
+}
+function e2eImageTargetKey(target) {
+    return `${target.family}:${target.name}:${target.recipeFingerprint}`;
+}
+function e2eManifestEntryKey(entry) {
+    return `${entry.family}:${entry.name}:${entry.recipeFingerprint}`;
+}
+async function materializePreparedE2eImagesFromManifest(project, targets) {
+    if (targets.some((target) => !target.e2eManifestEligible)) {
+        return false;
+    }
+    const manifest = await readE2ePreparedImageManifest(project.systemConfig.cacheDir);
+    const entriesByKey = new Map(manifest.entries.map((entry) => [e2eManifestEntryKey(entry), entry]));
+    const targetReadiness = await Promise.all(targets.map(async (target) => {
+        const entry = entriesByKey.get(e2eImageTargetKey(target));
+        return entry !== undefined && (await hasBuiltImageAssets(entry.imagePath));
+    }));
+    if (targetReadiness.some((isReady) => !isReady)) {
+        return false;
+    }
+    await Promise.all(targets.map(async (target) => {
+        const entry = entriesByKey.get(e2eImageTargetKey(target));
+        if (entry === undefined) {
+            throw new Error(`Missing prepared e2e image manifest entry for ${target.family}/${target.name}.`);
+        }
+        await writePreparedGondolinImage({
+            buildConfigPath: target.buildConfigPath,
+            cacheDir: target.cacheDirectory,
+            fingerprint: entry.fingerprint,
+            ...(entry.fingerprintInput === undefined
+                ? {}
+                : { fingerprintInput: entry.fingerprintInput }),
+            imagePath: entry.imagePath,
+        });
+    }));
+    return true;
+}
+async function recordPreparedE2eImages(project, targets) {
+    const manifest = await readE2ePreparedImageManifest(project.systemConfig.cacheDir);
+    const entriesByKey = new Map(manifest.entries.map((entry) => [e2eManifestEntryKey(entry), entry]));
+    const preparedImages = await Promise.all(targets.map(async (target) => {
+        if (!target.e2eManifestEligible) {
+            return null;
+        }
+        const preparedImage = await readPreparedGondolinImage({
+            buildConfigPath: target.buildConfigPath,
+            cacheDir: target.cacheDirectory,
+        });
+        return { preparedImage, target };
+    }));
+    for (const item of preparedImages) {
+        if (item === null || item.preparedImage === undefined) {
+            continue;
         }
-        // oxlint-disable-next-line eslint/no-await-in-loop -- readiness polling is sequential
-        await new Promise((resolve) => setTimeout(resolve, 500));
+        const { preparedImage, target } = item;
+        entriesByKey.set(e2eImageTargetKey(target), {
+            buildConfigPath: path.resolve(target.buildConfigPath),
+            cacheDirectory: path.resolve(target.cacheDirectory),
+            family: target.family,
+            fingerprint: preparedImage.fingerprint,
+            ...(preparedImage.fingerprintInput === undefined
+                ? {}
+                : { fingerprintInput: preparedImage.fingerprintInput }),
+            imagePath: preparedImage.imagePath,
+            name: target.name,
+            recipeFingerprint: target.recipeFingerprint,
+        });
     }
-    throw new Error('Controller did not become ready in time.');
+    await writeE2ePreparedImageManifest(project.systemConfig.cacheDir, {
+        entries: [...entriesByKey.values()].toSorted((leftEntry, rightEntry) => e2eManifestEntryKey(leftEntry).localeCompare(e2eManifestEntryKey(rightEntry))),
+        schemaVersion: e2ePreparedImageManifestSchemaVersion,
+    });
 }
 export async function findReusableGatewayImageDirectory(currentProjectRoot, gatewayBuildConfigPath, imageProfileName = 'worker') {
     const explicitE2eCacheRoot = process.env.AGENT_VM_E2E_CACHE_DIR;
@@ -132,6 +378,9 @@ export async function findReusableGatewayImageDirectory(currentProjectRoot, gate
         return null;
     }
     const requiredFingerprint = await computeFingerprintFromConfigPath(gatewayBuildConfigPath);
+    if (!(await pathExists(explicitE2eCacheRoot))) {
+        return null;
+    }
     const tempRootEntries = await fs.readdir(explicitE2eCacheRoot, { withFileTypes: true });
     const e2eRunDirectories = tempRootEntries
         .filter((entry) => entry.isDirectory())
@@ -168,6 +417,23 @@ export async function seedGatewayImageCacheIfAvailable(options) {
     await fs.mkdir(path.dirname(activeImageDir), { recursive: true });
     await fs.symlink(reusableImageDir, activeImageDir, 'dir');
 }
+export async function prepareGatewayE2eProjectImages(options) {
+    const imageTargets = await collectE2eImageTargets(options.project);
+    if (await materializePreparedE2eImagesFromManifest(options.project, imageTargets)) {
+        return;
+    }
+    await Promise.all(Object.entries(options.project.systemConfig.imageProfiles.gateways).map(async ([profileName, gatewayProfile]) => {
+        await seedGatewayImageCacheIfAvailable({
+            activeCacheDir: options.project.systemConfig.cacheDir,
+            currentProjectRoot: options.project.tempRoot,
+            gatewayBuildConfigPath: gatewayProfile.buildConfig,
+            imageProfileName: profileName,
+        });
+    }));
+    const runBuild = options.runBuild ?? runBuildCommand;
+    await runBuild({ systemConfig: options.project.systemConfig });
+    await recordPreparedE2eImages(options.project, imageTargets);
+}
 export function createSmokeSecretResolver(secrets) {
     const resolve = async (ref) => {
         if (ref.source === 'config') {
@@ -251,43 +517,162 @@ async function assertLocalPackageFilesExist(props) {
 export function resolveLocalPackagePackArgs(packDirectory) {
     return ['pack', '--pack-destination', packDirectory, '--config.ignore-scripts=true'];
 }
+function parseLocalPackagePackPlan(value, packageName) {
+    if (!isJsonRecord(value)) {
+        throw new Error(`Expected pnpm pack dry-run for ${packageName} to return an object.`);
+    }
+    const files = Array.isArray(value.files)
+        ? value.files.filter((file) => {
+            return isJsonRecord(file) && typeof file.path === 'string' && file.path.length > 0;
+        })
+        : [];
+    if (typeof value.name !== 'string' ||
+        typeof value.version !== 'string' ||
+        typeof value.filename !== 'string' ||
+        files.length === 0) {
+        throw new Error(`Unexpected pnpm pack dry-run result for ${packageName}.`);
+    }
+    return {
+        filename: value.filename,
+        files,
+        name: value.name,
+        version: value.version,
+    };
+}
+function resolveLocalPackagePackPlan(packageDirectory, packageName) {
+    const dryRunOutput = execFileSync('pnpm', ['pack', '--dry-run', '--json', '--config.ignore-scripts=true'], {
+        cwd: packageDirectory,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseLocalPackagePackPlan(JSON.parse(dryRunOutput), packageName);
+}
+function cacheSafeLocalPackageName(packageName) {
+    return packageName.replace(/^@/u, '').replaceAll('/', '__');
+}
+async function computeLocalPackagePackFingerprint(packageDirectory, packPlan) {
+    const hash = crypto.createHash('sha256');
+    hash.update(`${packPlan.name}\0${packPlan.version}\0${packPlan.filename}\0`);
+    for (const file of packPlan.files.toSorted((left, right) => left.path.localeCompare(right.path))) {
+        const filePath = path.join(packageDirectory, file.path);
+        // oxlint-disable-next-line no-await-in-loop -- ordered hashing keeps cache keys deterministic
+        const fileContents = await fs.readFile(filePath);
+        hash.update(`${file.path}\0`);
+        hash.update(fileContents);
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 24);
+}
 async function packLocalPackageTarball(props) {
     const packageJsonPath = path.join(props.packageDirectory, 'package.json');
     await fs.access(packageJsonPath);
     await assertLocalPackageFilesExist(props);
+    const packPlan = resolveLocalPackagePackPlan(props.packageDirectory, props.packageName);
+    const packFingerprint = await computeLocalPackagePackFingerprint(props.packageDirectory, packPlan);
+    const cachedPackageDirectory = path.join(resolveE2eCacheRoot(), 'local-package-tarballs', cacheSafeLocalPackageName(props.packageName), packFingerprint);
+    const cachedTarballPath = path.join(cachedPackageDirectory, packPlan.filename);
+    try {
+        await fs.access(cachedTarballPath);
+        return cachedTarballPath;
+    }
+    catch (error) {
+        if (!isJsonRecord(error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
     const packDirectory = await fs.mkdtemp(path.join(os.tmpdir(), `${props.packageName}-pack-`));
     try {
         execFileSync('pnpm', [...resolveLocalPackagePackArgs(packDirectory)], {
             cwd: props.packageDirectory,
             stdio: 'pipe',
         });
-        const packedTarballs = (await fs.readdir(packDirectory)).filter((fileName) => fileName.endsWith('.tgz'));
-        const [packedTarballName] = packedTarballs;
-        if (packedTarballName === undefined) {
-            throw new Error(`Failed to pack local ${props.packageName} tarball for smoke image.`);
-        }
-        if (packedTarballs.length > 1) {
-            throw new Error(`Expected pnpm pack for ${props.packageName} to produce exactly one tarball.`);
-        }
-        return path.join(packDirectory, packedTarballName);
+        const packedTarballPath = path.join(packDirectory, packPlan.filename);
+        await fs.access(packedTarballPath);
+        await fs.mkdir(cachedPackageDirectory, { recursive: true });
+        const temporaryCachedTarballPath = path.join(cachedPackageDirectory, `${packPlan.filename}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        await fs.copyFile(packedTarballPath, temporaryCachedTarballPath);
+        await fs.rename(temporaryCachedTarballPath, cachedTarballPath).catch(async (error) => {
+            await fs.rm(temporaryCachedTarballPath, { force: true });
+            if (isJsonRecord(error) && error.code === 'EEXIST') {
+                return;
+            }
+            throw error;
+        });
+        return cachedTarballPath;
     }
     catch (error) {
         await fs.rm(packDirectory, { force: true, recursive: true });
         throw error;
     }
+    finally {
+        await fs.rm(packDirectory, { force: true, recursive: true });
+    }
+}
+function isOwnedLocalPackagePackDirectory(packDirectory) {
+    const resolvedPackDirectory = path.resolve(packDirectory);
+    const resolvedSystemTempRoot = path.resolve(os.tmpdir());
+    if (resolvedPackDirectory === resolvedSystemTempRoot ||
+        !resolvedPackDirectory.startsWith(`${resolvedSystemTempRoot}${path.sep}`)) {
+        return false;
+    }
+    return path.basename(resolvedPackDirectory).includes('-pack-');
 }
-async function removeLocalPackageTarballDirectories(tarballPaths) {
+export async function removeE2eLocalPackageTarballs(tarballPaths) {
     await Promise.all(Array.from(new Set(tarballPaths
         .filter((tarballPath) => tarballPath !== undefined)
-        .map((tarballPath) => path.dirname(tarballPath)))).map(async (packDirectory) => {
+        .map((tarballPath) => path.dirname(tarballPath))))
+        .filter(isOwnedLocalPackagePackDirectory)
+        .map(async (packDirectory) => {
         await fs.rm(packDirectory, { force: true, recursive: true });
     }));
 }
 async function copyLocalPackageTarballsToDockerContext(options) {
     await Promise.all(options.tarballs.map(async (tarball) => {
-        await fs.copyFile(tarball.sourcePath, path.join(options.dockerContextDirectory, tarball.archiveName));
+        const targetPath = path.join(options.dockerContextDirectory, tarball.archiveName);
+        await fs.copyFile(tarball.sourcePath, targetPath);
+        await fs.utimes(targetPath, dockerContextLocalPackageTimestamp, dockerContextLocalPackageTimestamp);
     }));
 }
+function shellSingleQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function createLocalDockerPackageTarball(props) {
+    return {
+        archiveName: path.basename(props.sourcePath),
+        packageName: props.packageName,
+        sourcePath: props.sourcePath,
+    };
+}
+function localDockerPackageDependencyName(tarball) {
+    return `@agent-vm/${tarball.packageName}`;
+}
+function renderLocalDockerPackageManifest(tarballs) {
+    const dependencies = Object.fromEntries(tarballs.map((tarball) => [
+        localDockerPackageDependencyName(tarball),
+        `file:/tmp/${tarball.archiveName}`,
+    ]));
+    return `${JSON.stringify({
+        private: true,
+        dependencies,
+        pnpm: {
+            overrides: dependencies,
+        },
+    }, null, 2)}\n`;
+}
+function renderLocalDockerPackageInstallLines(tarballs) {
+    const manifestWriterScript = [
+        'require("node:fs").writeFileSync(',
+        '"/opt/agent-vm/local-packages/package.json",',
+        JSON.stringify(renderLocalDockerPackageManifest(tarballs)),
+        ')',
+    ].join('');
+    return [
+        'RUN mkdir -p /opt/agent-vm/local-packages && \\',
+        `    node -e ${shellSingleQuote(manifestWriterScript)} && \\`,
+        '    cd /opt/agent-vm/local-packages && pnpm install --prod --ignore-scripts && \\',
+        '    rm -f ' + tarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' '),
+    ];
+}
 async function useLocalToolVmMcpPortalPackageTarballs(options) {
     const managedImageRelease = await resolveManagedImageRelease();
     const baseImage = managedImageRelease.baseImages['tool-vm'];
@@ -295,35 +680,32 @@ async function useLocalToolVmMcpPortalPackageTarballs(options) {
     await Promise.all(toolVmProfiles.map(async ([profileName, toolVmProfile]) => {
         const dockerContextDirectory = path.join(options.projectRoot, 'vm-images', 'tool-vms', `${profileName}-local-mcp-portal`);
         const dockerfilePath = path.join(dockerContextDirectory, 'Dockerfile');
-        const localConfigContractsTarballName = 'config-contracts-local.tgz';
-        const localSecretManagementTarballName = 'secret-management-local.tgz';
-        const localTarballName = 'mcp-portal-local.tgz';
         await fs.rm(dockerContextDirectory, { force: true, recursive: true });
         await fs.mkdir(dockerContextDirectory, { recursive: true });
+        const localPackageTarballs = [
+            createLocalDockerPackageTarball({
+                packageName: 'config-contracts',
+                sourcePath: options.localConfigContractsTarballPath,
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'secret-management',
+                sourcePath: options.localSecretManagementTarballPath,
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'mcp-portal',
+                sourcePath: options.localMcpPortalTarballPath,
+            }),
+        ];
         await copyLocalPackageTarballsToDockerContext({
             dockerContextDirectory,
-            tarballs: [
-                {
-                    archiveName: localConfigContractsTarballName,
-                    sourcePath: options.localConfigContractsTarballPath,
-                },
-                {
-                    archiveName: localSecretManagementTarballName,
-                    sourcePath: options.localSecretManagementTarballPath,
-                },
-                { archiveName: localTarballName, sourcePath: options.localMcpPortalTarballPath },
-            ],
+            tarballs: localPackageTarballs,
         });
         await fs.writeFile(dockerfilePath, [
             `FROM ${baseImage.repository}:${baseImage.tag}`,
             '',
             '# Generated by the OpenClaw smoke harness from the local MCP Portal package.',
-            'COPY config-contracts-local.tgz /tmp/config-contracts-local.tgz',
-            'COPY secret-management-local.tgz /tmp/secret-management-local.tgz',
-            'COPY mcp-portal-local.tgz /tmp/mcp-portal-local.tgz',
-            'RUN mkdir -p /opt/agent-vm/local-packages && \\',
-            '    npm install --omit=dev --no-audit --no-fund --prefix /opt/agent-vm/local-packages /tmp/config-contracts-local.tgz /tmp/secret-management-local.tgz /tmp/mcp-portal-local.tgz && \\',
-            '    rm -f /tmp/config-contracts-local.tgz /tmp/secret-management-local.tgz /tmp/mcp-portal-local.tgz',
+            ...localPackageTarballs.map((tarball) => `COPY ${tarball.archiveName} /tmp/${tarball.archiveName}`),
+            ...renderLocalDockerPackageInstallLines(localPackageTarballs),
             '',
         ].join('\n'), 'utf8');
         toolVmProfile.dockerfile = dockerfilePath;
@@ -353,16 +735,13 @@ export async function useLocalToolVmMcpPortalPackage(options) {
         });
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localConfigContractsTarballPath,
             localSecretManagementTarballPath,
             localMcpPortalTarballPath,
         ]);
     }
 }
-function localPackageTarballArchiveName(packageName) {
-    return `${packageName}-local.tgz`;
-}
 async function writeManagedOpenClawE2eDockerfileBase(options) {
     const managedImageRelease = await resolveManagedImageRelease();
     const result = await generateManagedDockerfile({
@@ -506,34 +885,34 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
     });
     try {
         const localPackageTarballs = [
-            {
-                archiveName: localPackageTarballArchiveName('config-contracts'),
+            createLocalDockerPackageTarball({
+                packageName: 'config-contracts',
                 sourcePath: localConfigContractsTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('secret-management'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'secret-management',
                 sourcePath: localSecretManagementTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('gondolin-adapter'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'gondolin-adapter',
                 sourcePath: localGondolinAdapterTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('gateway-interface'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'gateway-interface',
                 sourcePath: localGatewayInterfaceTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('mcp-portal'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'mcp-portal',
                 sourcePath: localMcpPortalTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('openclaw-agent-vm-plugin'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'openclaw-agent-vm-plugin',
                 sourcePath: localOpenClawAgentVmPluginTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('openclaw-mcp-portal-plugin'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'openclaw-mcp-portal-plugin',
                 sourcePath: localOpenClawMcpPortalPluginTarballPath,
-            },
+            }),
         ];
         const dockerfilePath = await writeManagedOpenClawE2eDockerfileBase({
             dockerContextDirectory,
@@ -555,12 +934,7 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
             '',
             '# Local package overlay generated by the OpenClaw smoke harness.',
             ...localPackageTarballs.map((tarball) => `COPY ${tarball.archiveName} /tmp/${tarball.archiveName}`),
-            'RUN mkdir -p /opt/agent-vm/local-packages && \\',
-            '    npm install --omit=dev --no-audit --no-fund --prefix /opt/agent-vm/local-packages ' +
-                localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' ') +
-                ' && \\',
-            '    rm -f ' +
-                localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' '),
+            ...renderLocalDockerPackageInstallLines(localPackageTarballs),
             'RUN package_root="/opt/agent-vm/local-packages/node_modules" && \\',
             '    global_package_root="$(pnpm root -g)" && \\',
             '    mkdir -p "$global_package_root" /home/openclaw/.openclaw/extensions && \\',
@@ -573,7 +947,7 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
         delete gatewayProfile.source;
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localConfigContractsTarballPath,
             localSecretManagementTarballPath,
             localGondolinAdapterTarballPath,
@@ -608,22 +982,22 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
     });
     try {
         const localPackageTarballs = [
-            {
-                archiveName: localPackageTarballArchiveName('secret-management'),
+            createLocalDockerPackageTarball({
+                packageName: 'secret-management',
                 sourcePath: localSecretManagementTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('gondolin-adapter'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'gondolin-adapter',
                 sourcePath: localGondolinAdapterTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('gateway-interface'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'gateway-interface',
                 sourcePath: localGatewayInterfaceTarballPath,
-            },
-            {
-                archiveName: localPackageTarballArchiveName('openclaw-agent-vm-plugin'),
+            }),
+            createLocalDockerPackageTarball({
+                packageName: 'openclaw-agent-vm-plugin',
                 sourcePath: localOpenClawAgentVmPluginTarballPath,
-            },
+            }),
         ];
         const dockerfilePath = await writeManagedOpenClawE2eDockerfileBase({
             dockerContextDirectory,
@@ -638,12 +1012,7 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
             '',
             '# Local plugin overlay generated by the OpenClaw smoke harness.',
             ...localPackageTarballs.map((tarball) => `COPY ${tarball.archiveName} /tmp/${tarball.archiveName}`),
-            'RUN mkdir -p /opt/agent-vm/local-packages && \\',
-            '    npm install --omit=dev --no-audit --no-fund --prefix /opt/agent-vm/local-packages ' +
-                localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' ') +
-                ' && \\',
-            '    rm -f ' +
-                localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' '),
+            ...renderLocalDockerPackageInstallLines(localPackageTarballs),
             'RUN package_root="/opt/agent-vm/local-packages/node_modules" && \\',
             '    global_package_root="$(pnpm root -g)" && \\',
             '    mkdir -p "$global_package_root" /home/openclaw/.openclaw/extensions && \\',
@@ -655,7 +1024,7 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
         delete gatewayProfile.source;
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localSecretManagementTarballPath,
             localGondolinAdapterTarballPath,
             localGatewayInterfaceTarballPath,
@@ -690,21 +1059,10 @@ export async function scaffoldOpenClawE2eProject(options) {
     };
 }
 export async function prepareLocalWorkerPackageForGatewayImage(repoRoot) {
-    await fs.mkdir(path.join(repoRoot, 'tmp'), { recursive: true });
-    const packDirectory = await fs.mkdtemp(path.join(repoRoot, 'tmp', 'agent-vm-worker-pack-'));
-    execFileSync('pnpm', ['pack', '--pack-destination', packDirectory], {
-        cwd: path.join(repoRoot, 'packages', 'agent-vm-worker'),
-        stdio: 'pipe',
+    return await packLocalPackageTarball({
+        packageDirectory: path.join(repoRoot, 'packages', 'agent-vm-worker'),
+        packageName: 'agent-vm-worker',
     });
-    const packedTarballs = (await fs.readdir(packDirectory)).filter((fileName) => fileName.endsWith('.tgz'));
-    const [packedTarballName] = packedTarballs;
-    if (packedTarballName === undefined) {
-        throw new Error('Failed to pack local agent-vm-worker tarball for smoke image.');
-    }
-    if (packedTarballs.length > 1) {
-        throw new Error('Expected pnpm pack to produce exactly one agent-vm-worker tarball.');
-    }
-    return path.join(packDirectory, packedTarballName);
 }
 export async function scaffoldWorkerE2eProject(options) {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), options.prefix));