@agent-vm/agent-vm 0.0.92 → 0.0.94

package/dist/integration-tests/{smoke-harness.js → e2e-harness.js}

@@ -1,30 +1,51 @@
 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 { resolveGondolinMinimumZigVersion } from '@agent-vm/gondolin-adapter';
+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 smokeTempRootPrefixes = [
-    'agent-vm-gateway-smoke-project-',
-    'agent-vm-smoke-harness-',
-    'openclaw-control-link-smoke-',
-    'openclaw-mcp-portal-smoke-',
-    'openclaw-subagent-lease-smoke-',
-    'openclaw-zone-git-smoke-',
-    'worker-loop-smoke-',
+const e2eTempRootPrefixes = [
+    'agent-vm-gateway-e2e-project-',
+    'agent-vm-e2e-harness-',
+    'openclaw-control-link-e2e-',
+    'openclaw-mcp-portal-e2e-',
+    'openclaw-subagent-lease-e2e-',
+    'openclaw-zone-git-e2e-',
+    'worker-loop-e2e-',
 ];
+function resolveE2eCacheRoot() {
+    const configuredCacheRoot = process.env.AGENT_VM_E2E_CACHE_DIR;
+    if (configuredCacheRoot !== undefined && configuredCacheRoot.length > 0) {
+        return path.resolve(configuredCacheRoot);
+    }
+    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';
+}
 export function hasCommand(command) {
     try {
         execFileSync('sh', ['-lc', `command -v ${command} >/dev/null`], { stdio: 'ignore' });
@@ -34,13 +55,13 @@ export function hasCommand(command) {
         return false;
     }
 }
-export function currentSmokeArchitecture() {
+export function currentE2eArchitecture() {
     return process.arch === 'arm64' ? 'aarch64' : 'x86_64';
 }
 export function qemuCommandForArchitecture(architecture) {
     return architecture === 'aarch64' ? 'qemu-system-aarch64' : 'qemu-system-x86_64';
 }
-function isOwnedSmokeTempRoot(tempRoot) {
+function isOwnedE2eTempRoot(tempRoot) {
     const resolvedTempRoot = path.resolve(tempRoot);
     const resolvedSystemTempRoot = path.resolve(os.tmpdir());
     if (resolvedTempRoot === resolvedSystemTempRoot ||
@@ -48,15 +69,15 @@ function isOwnedSmokeTempRoot(tempRoot) {
         return false;
     }
     const basename = path.basename(resolvedTempRoot);
-    return smokeTempRootPrefixes.some((prefix) => basename.startsWith(prefix));
+    return e2eTempRootPrefixes.some((prefix) => basename.startsWith(prefix));
 }
-export async function removeSmokeTempRoot(tempRoot) {
-    if (!isOwnedSmokeTempRoot(tempRoot)) {
+export async function removeE2eTempRoot(tempRoot) {
+    if (!isOwnedE2eTempRoot(tempRoot)) {
         return;
     }
     await fs.rm(tempRoot, { force: true, recursive: true });
 }
-export async function canRunGondolinSmoke(options) {
+export async function canRunGondolinE2e(options) {
     const commandExists = options.commandExists ?? hasCommand;
     if (!commandExists(qemuCommandForArchitecture(options.architecture)) ||
         !commandExists('docker')) {
@@ -67,14 +88,14 @@ export async function canRunGondolinSmoke(options) {
     return (installedZigVersion !== undefined &&
         isZigVersionAtLeast(installedZigVersion, requiredZigVersion));
 }
-export async function shouldRunWorkerGatewaySmoke(options) {
+export async function shouldRunWorkerGatewayE2e(options) {
     const env = options.env ?? process.env;
-    if (env.AGENT_VM_WORKER_SMOKE !== '1' ||
-        typeof env.OPEN_AI_TEST_KEY !== 'string' ||
-        env.OPEN_AI_TEST_KEY.length === 0) {
+    if (env.AGENT_VM_WORKER_E2E !== '1' ||
+        typeof env.AGENT_VM_TEST_OPENAI_API_KEY !== 'string' ||
+        env.AGENT_VM_TEST_OPENAI_API_KEY.length === 0) {
         return false;
     }
-    return await canRunGondolinSmoke({
+    return await canRunGondolinE2e({
         architecture: options.architecture,
         ...(options.commandExists ? { commandExists: options.commandExists } : {}),
         ...(options.resolveRequiredZigVersion
@@ -83,12 +104,6 @@ export async function shouldRunWorkerGatewaySmoke(options) {
         ...(options.resolveZigVersion ? { resolveZigVersion: options.resolveZigVersion } : {}),
     });
 }
-export function rebuildWorkspacePackages(repoRoot) {
-    execFileSync('pnpm', ['build'], {
-        cwd: repoRoot,
-        stdio: 'inherit',
-    });
-}
 export async function findAvailablePort() {
     return await new Promise((resolve, reject) => {
         const server = net.createServer();
@@ -109,57 +124,292 @@ 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 };
         }
-        // oxlint-disable-next-line eslint/no-await-in-loop -- readiness polling is sequential
-        await new Promise((resolve) => setTimeout(resolve, 500));
+        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 };
     }
-    throw new Error('Controller did not become ready in time.');
+    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 };
 }
-export async function findReusableGatewayImageDirectory(currentProjectRoot, gatewayBuildConfigPath) {
-    const explicitSmokeCacheRoot = process.env.AGENT_VM_SMOKE_CACHE_DIR;
-    if (!explicitSmokeCacheRoot) {
+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;
+        }
+        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,
+        });
+    }
+    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;
+    if (!explicitE2eCacheRoot) {
         return null;
     }
     const requiredFingerprint = await computeFingerprintFromConfigPath(gatewayBuildConfigPath);
-    const tempRootEntries = await fs.readdir(explicitSmokeCacheRoot, { withFileTypes: true });
-    const smokeRunDirectories = tempRootEntries
-        .filter((entry) => entry.isDirectory() && entry.name.includes('-smoke-'))
-        .map((entry) => path.join(explicitSmokeCacheRoot, entry.name));
-    for (const smokeRunDirectory of smokeRunDirectories) {
-        if (smokeRunDirectory === currentProjectRoot) {
+    if (!(await pathExists(explicitE2eCacheRoot))) {
+        return null;
+    }
+    const tempRootEntries = await fs.readdir(explicitE2eCacheRoot, { withFileTypes: true });
+    const e2eRunDirectories = tempRootEntries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(explicitE2eCacheRoot, entry.name));
+    for (const e2eRunDirectory of e2eRunDirectories) {
+        if (e2eRunDirectory === currentProjectRoot) {
             continue;
         }
-        const candidateImageDir = path.join(smokeRunDirectory, 'cache', 'images', 'gateway', requiredFingerprint);
-        try {
-            // oxlint-disable-next-line eslint/no-await-in-loop -- intentionally searches cache candidates
-            await fs.access(path.join(candidateImageDir, 'manifest.json'));
-            // oxlint-disable-next-line eslint/no-await-in-loop -- intentionally searches cache candidates
-            await fs.access(path.join(candidateImageDir, 'rootfs.ext4'));
-            // oxlint-disable-next-line eslint/no-await-in-loop -- intentionally searches cache candidates
-            await fs.access(path.join(candidateImageDir, 'initramfs.cpio.lz4'));
+        const candidateImageDirectories = [
+            path.join(e2eRunDirectory, 'gateway-images', imageProfileName, requiredFingerprint),
+            path.join(e2eRunDirectory, 'cache', 'gateway-images', imageProfileName, requiredFingerprint),
+        ];
+        for (const candidateImageDir of candidateImageDirectories) {
             // oxlint-disable-next-line eslint/no-await-in-loop -- intentionally searches cache candidates
-            await fs.access(path.join(candidateImageDir, 'vmlinuz-virt'));
-            return candidateImageDir;
-        }
-        catch {
-            continue;
+            if (await hasBuiltImageAssets(candidateImageDir)) {
+                return candidateImageDir;
+            }
         }
     }
     return null;
 }
 export async function seedGatewayImageCacheIfAvailable(options) {
-    const reusableImageDir = await findReusableGatewayImageDirectory(options.currentProjectRoot, options.gatewayBuildConfigPath);
+    const imageProfileName = options.imageProfileName ?? 'worker';
+    const reusableImageDir = await findReusableGatewayImageDirectory(options.currentProjectRoot, options.gatewayBuildConfigPath, imageProfileName);
     if (!reusableImageDir) {
         return;
     }
     const requiredFingerprint = await computeFingerprintFromConfigPath(options.gatewayBuildConfigPath);
-    const activeImageDir = path.join(options.activeCacheDir, 'images', 'gateway', requiredFingerprint);
+    const activeImageDir = path.join(options.activeCacheDir, 'gateway-images', imageProfileName, requiredFingerprint);
     if (activeImageDir === reusableImageDir) {
         return;
     }
@@ -167,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') {
@@ -208,14 +475,14 @@ function applySmokeEnvironment(secrets) {
         }
     };
 }
-export function getOpenClawSmokeZone(systemConfig) {
+export function getOpenClawE2eZone(systemConfig) {
     const zone = systemConfig.zones[0];
     if (!zone || zone.gateway.type !== 'openclaw') {
         throw new Error('Expected smoke system config to contain an OpenClaw zone.');
     }
     return { ...zone, gateway: zone.gateway };
 }
-function getWorkerSmokeZone(systemConfig) {
+function getWorkerE2eZone(systemConfig) {
     const zone = systemConfig.zones[0];
     if (!zone || zone.gateway.type !== 'worker') {
         throw new Error('Expected smoke system config to contain a Worker Gateway zone.');
@@ -247,41 +514,123 @@ 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', ['pack', '--pack-destination', packDirectory], {
+        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 });
+    }
 }
-async function removeLocalPackageTarballDirectories(tarballPaths) {
+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-');
+}
+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);
     }));
 }
 async function useLocalToolVmMcpPortalPackageTarballs(options) {
@@ -349,7 +698,7 @@ export async function useLocalToolVmMcpPortalPackage(options) {
         });
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localConfigContractsTarballPath,
             localSecretManagementTarballPath,
             localMcpPortalTarballPath,
@@ -359,13 +708,14 @@ export async function useLocalToolVmMcpPortalPackage(options) {
 function localPackageTarballArchiveName(packageName) {
     return `${packageName}-local.tgz`;
 }
-async function writeManagedOpenClawSmokeDockerfileBase(options) {
+async function writeManagedOpenClawE2eDockerfileBase(options) {
     const managedImageRelease = await resolveManagedImageRelease();
     const result = await generateManagedDockerfile({
         base: 'openclaw-gateway',
         imageTargetFamily: 'gateway',
         imageTargetName: options.profileName,
         managedImageRelease,
+        openClawAgentVmPackageInstallMode: options.openClawAgentVmPackageInstallMode,
         outputDirectory: options.dockerContextDirectory,
         requiredOpenClawPackageNames: ['@openclaw/discord'],
     });
@@ -383,7 +733,7 @@ function mutableJsonRecord(value) {
 async function runDockerCommand(args) {
     await execFileAsync('docker', [...args]);
 }
-async function readSmokeDockerImageTag(buildConfigPath) {
+async function readE2eDockerImageTag(buildConfigPath) {
     let buildConfig;
     try {
         buildConfig = mutableJsonRecord(await loadJsonConfigFile(buildConfigPath));
@@ -398,7 +748,7 @@ async function readSmokeDockerImageTag(buildConfigPath) {
     const imageTag = ociConfig?.image;
     return typeof imageTag === 'string' && imageTag.length > 0 ? imageTag : null;
 }
-export async function collectSmokeDockerImageTags(systemConfig) {
+export async function collectE2eDockerImageTags(systemConfig) {
     const imageProfiles = [
         ...Object.values(systemConfig.imageProfiles.gateways),
         ...Object.values(systemConfig.imageProfiles.toolVms),
@@ -406,14 +756,14 @@ export async function collectSmokeDockerImageTags(systemConfig) {
     const imageTags = [];
     for (const imageProfile of imageProfiles) {
         // oxlint-disable-next-line eslint/no-await-in-loop -- config files are intentionally read deterministically
-        const imageTag = await readSmokeDockerImageTag(imageProfile.buildConfig);
+        const imageTag = await readE2eDockerImageTag(imageProfile.buildConfig);
         if (imageTag !== null) {
             imageTags.push(imageTag);
         }
     }
     return Array.from(new Set(imageTags));
 }
-export async function removeSmokeDockerImages(imageTags, options = {}) {
+export async function removeE2eDockerImages(imageTags, options = {}) {
     const dockerCommand = options.runDockerCommand ?? runDockerCommand;
     for (const imageTag of Array.from(new Set(imageTags))) {
         try {
@@ -427,10 +777,10 @@ export async function removeSmokeDockerImages(imageTags, options = {}) {
         await dockerCommand(['image', 'rm', '--force', imageTag]);
     }
 }
-export async function removeSmokeDockerImagesForSystemConfig(systemConfig, options = {}) {
-    await removeSmokeDockerImages(await collectSmokeDockerImageTags(systemConfig), options);
+export async function removeE2eDockerImagesForSystemConfig(systemConfig, options = {}) {
+    await removeE2eDockerImages(await collectE2eDockerImageTags(systemConfig), options);
 }
-function throwIfSmokeHarnessCleanupFailed(errors) {
+function throwIfE2eHarnessCleanupFailed(errors) {
     if (errors.length === 0) {
         return;
     }
@@ -530,9 +880,10 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
                 sourcePath: localOpenClawMcpPortalPluginTarballPath,
             },
         ];
-        const dockerfilePath = await writeManagedOpenClawSmokeDockerfileBase({
+        const dockerfilePath = await writeManagedOpenClawE2eDockerfileBase({
             dockerContextDirectory,
             profileName: options.profileName,
+            openClawAgentVmPackageInstallMode: 'local-overlay',
         });
         await copyLocalPackageTarballsToDockerContext({
             dockerContextDirectory,
@@ -556,7 +907,9 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
             '    rm -f ' +
                 localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' '),
             'RUN package_root="/opt/agent-vm/local-packages/node_modules" && \\',
-            '    mkdir -p /home/openclaw/.openclaw/extensions && \\',
+            '    global_package_root="$(pnpm root -g)" && \\',
+            '    mkdir -p "$global_package_root" /home/openclaw/.openclaw/extensions && \\',
+            '    ln -sfn "$package_root/@agent-vm" "$global_package_root/@agent-vm" && \\',
             '    ln -sfn "$package_root/@agent-vm/openclaw-agent-vm-plugin/dist" /home/openclaw/.openclaw/extensions/gondolin && \\',
             '    ln -sfn "$package_root/@agent-vm/openclaw-mcp-portal-plugin/dist" /home/openclaw/.openclaw/extensions/mcp-portal',
             '',
@@ -565,7 +918,7 @@ export async function useLocalOpenClawGatewayImagePackages(options) {
         delete gatewayProfile.source;
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localConfigContractsTarballPath,
             localSecretManagementTarballPath,
             localGondolinAdapterTarballPath,
@@ -617,9 +970,10 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
                 sourcePath: localOpenClawAgentVmPluginTarballPath,
             },
         ];
-        const dockerfilePath = await writeManagedOpenClawSmokeDockerfileBase({
+        const dockerfilePath = await writeManagedOpenClawE2eDockerfileBase({
             dockerContextDirectory,
             profileName: options.profileName,
+            openClawAgentVmPackageInstallMode: 'local-overlay',
         });
         await copyLocalPackageTarballsToDockerContext({
             dockerContextDirectory,
@@ -636,7 +990,9 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
             '    rm -f ' +
                 localPackageTarballs.map((tarball) => `/tmp/${tarball.archiveName}`).join(' '),
             'RUN package_root="/opt/agent-vm/local-packages/node_modules" && \\',
-            '    mkdir -p /home/openclaw/.openclaw/extensions && \\',
+            '    global_package_root="$(pnpm root -g)" && \\',
+            '    mkdir -p "$global_package_root" /home/openclaw/.openclaw/extensions && \\',
+            '    ln -sfn "$package_root/@agent-vm" "$global_package_root/@agent-vm" && \\',
             '    ln -sfn "$package_root/@agent-vm/openclaw-agent-vm-plugin/dist" /home/openclaw/.openclaw/extensions/gondolin',
             '',
         ].join('\n'), 'utf8');
@@ -644,7 +1000,7 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
         delete gatewayProfile.source;
     }
     finally {
-        await removeLocalPackageTarballDirectories([
+        await removeE2eLocalPackageTarballs([
             localSecretManagementTarballPath,
             localGondolinAdapterTarballPath,
             localGatewayInterfaceTarballPath,
@@ -652,7 +1008,7 @@ export async function useLocalOpenClawPluginGatewayImage(options) {
         ]);
     }
 }
-export async function scaffoldOpenClawSmokeProject(options) {
+export async function scaffoldOpenClawE2eProject(options) {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), options.prefix));
     const controllerPort = await findAvailablePort();
     const gatewayPort = await findAvailablePort();
@@ -667,8 +1023,8 @@ export async function scaffoldOpenClawSmokeProject(options) {
     const systemConfig = await loadSystemConfig(path.join(tempRoot, 'config', 'system.json'));
     systemConfig.host.controllerPort = controllerPort;
     systemConfig.host.projectNamespace = 'claw-tests-zone-git';
-    systemConfig.cacheDir = path.join(tempRoot, 'cache');
-    const zone = getOpenClawSmokeZone(systemConfig);
+    systemConfig.cacheDir = path.join(resolveE2eCacheRoot(), 'openclaw');
+    const zone = getOpenClawE2eZone(systemConfig);
     zone.gateway.port = gatewayPort;
     return {
         controllerPort,
@@ -679,23 +1035,12 @@ export async function scaffoldOpenClawSmokeProject(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 scaffoldWorkerSmokeProject(options) {
+export async function scaffoldWorkerE2eProject(options) {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), options.prefix));
     const controllerPort = await findAvailablePort();
     const gatewayPort = await findAvailablePort();
@@ -709,12 +1054,12 @@ export async function scaffoldWorkerSmokeProject(options) {
     const systemConfig = await loadSystemConfig(path.join(tempRoot, 'config', 'system.json'));
     systemConfig.host.controllerPort = controllerPort;
     systemConfig.host.projectNamespace = 'claw-tests-worker';
-    systemConfig.cacheDir = path.join(tempRoot, 'cache');
+    systemConfig.cacheDir = path.join(resolveE2eCacheRoot(), 'worker');
     systemConfig.host.secretsProvider = {
         type: '1password',
-        tokenSource: { type: 'env', envVar: 'OPEN_AI_TEST_KEY' },
+        tokenSource: { type: 'env', envVar: 'AGENT_VM_TEST_OPENAI_API_KEY' },
     };
-    const zone = getWorkerSmokeZone(systemConfig);
+    const zone = getWorkerE2eZone(systemConfig);
     zone.gateway.port = gatewayPort;
     return {
         controllerPort,
@@ -724,27 +1069,27 @@ export async function scaffoldWorkerSmokeProject(options) {
         zone,
     };
 }
-export async function scaffoldGatewaySmokeProject(options) {
+export async function scaffoldGatewayE2eProject(options) {
     if (options.kind === 'openclaw') {
-        return await scaffoldOpenClawSmokeProject({
+        return await scaffoldOpenClawE2eProject({
             architecture: options.architecture,
             prefix: options.prefix,
             zoneId: options.zoneId,
             ...(options.agents ? { agents: options.agents } : {}),
         });
     }
-    return await scaffoldWorkerSmokeProject({
+    return await scaffoldWorkerE2eProject({
         architecture: options.architecture,
         prefix: options.prefix,
         zoneId: options.zoneId,
     });
 }
-export async function writeOpenClawMcpPortalSmokeConfigs(options) {
+export async function writeOpenClawMcpPortalE2eConfigs(options) {
     await fs.writeFile(path.join(options.configDir, 'mcp.config.jsonc'), `${JSON.stringify({
         $schema: '../../schemas/mcp.schema.json',
         providers: {
             upstreamMock: {
-                discovery: { summary: 'Mock upstream MCP server for smoke tests' },
+                discovery: { summary: 'Mock upstream MCP server for e2e tests' },
                 kind: 'mcp',
                 namespace: options.namespace,
                 transport: {
@@ -777,7 +1122,7 @@ export async function writeOpenClawMcpPortalSmokeConfigs(options) {
         schemaVersion: 1,
     }, null, '\t')}\n`, 'utf8');
 }
-export async function startSmokeControllerRuntime(options) {
+export async function startE2eControllerRuntime(options) {
     const restoreEnvironment = applySmokeEnvironment(options.secrets);
     const secretResolver = createSmokeSecretResolver(options.secrets);
     const tempRoot = path.dirname(path.dirname(options.startOptions.systemConfig.systemConfigPath));
@@ -816,7 +1161,7 @@ export async function startSmokeControllerRuntime(options) {
             runtime,
             systemConfig: options.startOptions.systemConfig,
             tempRoot,
-            close: async () => {
+            close: async (closeOptions = {}) => {
                 const cleanupErrors = [];
                 try {
                     await runtime.close();
@@ -824,14 +1169,19 @@ export async function startSmokeControllerRuntime(options) {
                 catch (error) {
                     cleanupErrors.push(error);
                 }
-                try {
-                    await removeSmokeDockerImagesForSystemConfig(options.startOptions.systemConfig);
-                }
-                catch (error) {
-                    cleanupErrors.push(error);
+                if (shouldCleanupE2eDockerImages({
+                    ...closeOptions,
+                    env: process.env,
+                })) {
+                    try {
+                        await removeE2eDockerImagesForSystemConfig(options.startOptions.systemConfig);
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
                 }
                 try {
-                    await removeSmokeTempRoot(tempRoot);
+                    await removeE2eTempRoot(tempRoot);
                 }
                 catch (error) {
                     cleanupErrors.push(error);
@@ -839,20 +1189,22 @@ export async function startSmokeControllerRuntime(options) {
                 finally {
                     restoreEnvironment();
                 }
-                throwIfSmokeHarnessCleanupFailed(cleanupErrors);
+                throwIfE2eHarnessCleanupFailed(cleanupErrors);
             },
         };
     }
     catch (error) {
         const cleanupErrors = [error];
-        try {
-            await removeSmokeDockerImagesForSystemConfig(options.startOptions.systemConfig);
-        }
-        catch (cleanupError) {
-            cleanupErrors.push(cleanupError);
+        if (shouldCleanupE2eDockerImages({ env: process.env })) {
+            try {
+                await removeE2eDockerImagesForSystemConfig(options.startOptions.systemConfig);
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
         }
         try {
-            await removeSmokeTempRoot(tempRoot);
+            await removeE2eTempRoot(tempRoot);
         }
         catch (cleanupError) {
             cleanupErrors.push(cleanupError);
@@ -860,8 +1212,8 @@ export async function startSmokeControllerRuntime(options) {
         finally {
             restoreEnvironment();
         }
-        throwIfSmokeHarnessCleanupFailed(cleanupErrors);
+        throwIfE2eHarnessCleanupFailed(cleanupErrors);
         throw error;
     }
 }
-//# sourceMappingURL=smoke-harness.js.map
+//# sourceMappingURL=e2e-harness.js.map