@flame0510/project-aether 1.3.0 → 1.4.1

package/lib/agent-versions.json

@@ -0,0 +1,14 @@
+{
+  "localRepository": "openclaw-agent-base",
+  "registryRepository": "ghcr.io/flame0510/rev4a/openclaw-agent-base",
+  "supported": [
+    {
+      "version": "2026.9.3",
+      "modelInput": ["text", "image", "audio", "video"]
+    },
+    {
+      "version": "2026.7.1-2",
+      "modelInput": ["text", "image"]
+    }
+  ]
+}

package/lib/agent-versions.ts

@@ -0,0 +1,80 @@
+/**
+ * The OpenClaw versions this Rev4a release supports, newest first.
+ *
+ * The table lives in `agent-versions.json` so the `rev4a` CLI (plain CommonJS) reads
+ * the same list the server does. A new OpenClaw release is supported by adding its
+ * entry here together with the Dockerfile's `ARG OPENCLAW_VERSION`; nothing detects
+ * versions at runtime.
+ *
+ * `modelInput` is the model `input` list written into `models.json` for that version:
+ * OpenClaw validates it against the modalities it knows, so a value an older release
+ * does not know invalidates the whole catalogue.
+ */
+import table from './agent-versions.json';
+
+export interface SupportedVersion {
+  version: string;
+  modelInput: string[];
+}
+
+export const SUPPORTED_VERSIONS: readonly SupportedVersion[] = table.supported;
+
+/** Local image repository; agents run `openclaw-agent-base:<version>`. */
+export const LOCAL_IMAGE_REPOSITORY: string = table.localRepository;
+
+/**
+ * Where images are pulled from. `REV4A_AGENT_IMAGE_REGISTRY` points Rev4a at another
+ * registry with the same tags, such as a local `registry:2` for tests.
+ */
+export function registryRepository(): string {
+  return process.env.REV4A_AGENT_IMAGE_REGISTRY?.trim() || table.registryRepository;
+}
+
+export const localImageRef = (version: string): string => `${LOCAL_IMAGE_REPOSITORY}:${version}`;
+
+export const newestSupportedVersion = (): string => SUPPORTED_VERSIONS[0].version;
+
+export const isSupportedVersion = (version: unknown): version is string =>
+  typeof version === 'string' && SUPPORTED_VERSIONS.some((v) => v.version === version);
+
+/** Model `input` values every supported version accepts — the safe list when the version is unknown. */
+export function conservativeModelInput(): string[] {
+  return SUPPORTED_VERSIONS.reduce<string[]>(
+    (acc, v, i) => (i === 0 ? [...v.modelInput] : acc.filter((x) => v.modelInput.includes(x))),
+    [],
+  );
+}
+
+/**
+ * Model `input` values for a version. An unknown version gets the conservative
+ * intersection rather than the newest list: sending an older release a value it does
+ * not know discards its whole generated catalogue, so the fallback must be the set all
+ * supported versions accept.
+ */
+export function modelInputFor(version?: string | null): string[] {
+  const entry = version ? SUPPORTED_VERSIONS.find((v) => v.version === version) : undefined;
+  return entry ? entry.modelInput : conservativeModelInput();
+}
+
+const VERSION_RE = /(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-(\d+))?/;
+
+/** The version in `2026.9.3`, `2026.7.1-2` or `OpenClaw 2026.9.3 (1391f7c)`; null when there is none. */
+export function parseOpenClawVersion(text: string | null | undefined): string | null {
+  const m = VERSION_RE.exec(text ?? '');
+  if (!m) return null;
+  return `${Number(m[1])}.${Number(m[2])}.${Number(m[3])}${m[4] !== undefined ? `-${Number(m[4])}` : ''}`;
+}
+
+/** Negative when `a` is older than `b`, zero when equal, positive when newer. Unparseable sorts oldest. */
+export function compareVersions(a: string, b: string): number {
+  const parts = (v: string) => {
+    const m = VERSION_RE.exec(v);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4] ?? 0)] : [-1, -1, -1, -1];
+  };
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < pa.length; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}

package/lib/buildAgentImage.ts

@@ -1,75 +1,41 @@
 /**
  * buildAgentImage.ts
  *
- * Shared logic for obtaining the openclaw-agent-base Docker image.
- * Used by /api/agents/download-image, /api/agents/image-status, and
- * the rev4a serve CLI.
+ * Downloading the agent base image for one OpenClaw version. Used by
+ * POST /api/agents/download-image (the Agents page banner) and
+ * POST /api/setup/agent-image (the setup wizard, streamed).
  *
- * Strategy (in order):
- *   1. docker pull from ghcr.io/flame0510/rev4a/openclaw-agent-base:latest (public, no auth)
- *   2. If pull fails (offline / no network) → fallback to local docker build
+ * The image is pulled from the registry as `<registry>:<version>` and kept as
+ * `openclaw-agent-base:<version>` (see lib/agent-images.ts). When the pull fails and
+ * this repository's Dockerfile builds that same version, the image is built locally
+ * instead — development without registry access. Any other version cannot be built
+ * from here, so its download fails.
  *
- * Logs are written to /tmp/rev4a-download-<timestamp>.log so they survive
- * page refreshes and modal closes.
+ * One download at a time (in-process lock). Output goes to
+ * /tmp/rev4a-download-<timestamp>.log so it survives page refreshes and modal closes.
  */
-import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync as execSyncRaw } from 'child_process';
+import { isSupportedVersion, localImageRef, newestSupportedVersion } from '@/lib/agent-versions';
+import { localVersionExists, pullAgentImage, remoteSupportedVersions, runDocker } from '@/lib/agent-images';
+import { dockerAvailable } from '@/lib/docker-socket';
 
-const REGISTRY_IMAGE = 'ghcr.io/flame0510/rev4a/openclaw-agent-base:latest';
-const LOCAL_IMAGE = 'openclaw-agent-base:latest';
+const DOCKERFILE_DIR = path.join(process.cwd(), 'agent-templates', 'base-image');
+const BUILD_TIMEOUT_MS = 60 * 60 * 1000;
 
-let isDownloading = false;
+/** The version being downloaded; `pending` while the default version is being resolved. */
+let downloadingVersion: string | null = null;
 let downloadLogPath: string | null = null;
-let downloadChildProcess: ReturnType<(typeof import('child_process'))['exec']> | null = null;
-
-/** Check whether the docker CLI is available and functional. */
-function dockerAvailable(): boolean {
-  try {
-    execSyncRaw('docker version --format "{{.Client.Version}}" 2>/dev/null', {
-      encoding: 'utf-8',
-      timeout: 3000,
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Returns the SHA256 hash of the current Dockerfile. */
-export function getDockerfileHash(): string | null {
-  try {
-    const dockerfile = path.join(process.cwd(), 'agent-templates', 'base-image', 'Dockerfile');
-    if (!fs.existsSync(dockerfile)) return null;
-    const content = fs.readFileSync(dockerfile, 'utf-8');
-    return crypto.createHash('sha256').update(content).digest('hex');
-  } catch {
-    return null;
-  }
-}
-
 
 /** Checks if a download is already running (in-process flag only). */
 export function getIsDownloading(): boolean {
-  return isDownloading;
-}
-
-/** Acquire the lock atomically. Returns false if already locked. */
-function tryAcquireLock(): boolean {
-  if (getIsDownloading()) return false;
-  isDownloading = true;
-  return true;
+  return downloadingVersion !== null;
 }
 
-/** Release the lock and clear state. */
-function releaseLock(): void {
-  isDownloading = false;
-  downloadLogPath = null;
-  downloadChildProcess = null;
+export function getDownloadingVersion(): string | null {
+  return downloadingVersion === 'pending' ? null : downloadingVersion;
 }
 
-
 function appendLog(msg: string): void {
   if (!downloadLogPath) return;
   try {
@@ -81,270 +47,102 @@ function appendLog(msg: string): void {
 function cleanupOldLogs(): void {
   try {
     const tmpDir = '/tmp';
-    const files = fs.readdirSync(tmpDir);
     const cutoff = Date.now() - 24 * 60 * 60 * 1000;
-    for (const f of files) {
+    for (const f of fs.readdirSync(tmpDir)) {
       if (!f.startsWith('rev4a-download-') || !f.endsWith('.log')) continue;
       const fullPath = path.join(tmpDir, f);
-      const stat = fs.statSync(fullPath);
-      if (stat.mtimeMs < cutoff) {
-        fs.unlinkSync(fullPath);
-      }
+      if (fs.statSync(fullPath).mtimeMs < cutoff) fs.unlinkSync(fullPath);
     }
   } catch { /* ignore */ }
 }
 
-export interface DownloadOptions {
-  force?: boolean;
-  onEvent?: (data: string) => void;
-  signal?: AbortSignal;
-}
-
-function localImageExists(): boolean {
-  if (!dockerAvailable()) return false;
+/** The OpenClaw version this repository's Dockerfile builds (`ARG OPENCLAW_VERSION`). */
+export function dockerfileVersion(): string | null {
   try {
-    execSyncRaw(
-      `docker image inspect ${LOCAL_IMAGE} --format "{{.ID}}" 2>/dev/null`,
-      { timeout: 3000 },
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function getLocalImageId(): string | null {
-  if (!dockerAvailable()) return null;
-  try {
-    return execSyncRaw(
-      `docker image inspect ${LOCAL_IMAGE} --format "{{.ID}}" 2>/dev/null`,
-      { encoding: 'utf-8', timeout: 3000 },
-    ).trim() || null;
+    const content = fs.readFileSync(path.join(DOCKERFILE_DIR, 'Dockerfile'), 'utf-8');
+    return /^ARG OPENCLAW_VERSION=(\S+)/m.exec(content)?.[1] ?? null;
   } catch {
     return null;
   }
 }
 
-/**
- * Get the digest of the remote image (without pulling).
- * Returns null if not reachable.
- */
-function getRemoteDigest(): string | null {
-  if (!dockerAvailable()) return null;
-  try {
-    const out = execSyncRaw(
-      `docker manifest inspect ${REGISTRY_IMAGE} 2>/dev/null`,
-      { encoding: 'utf-8', timeout: 15000 },
-    );
-    const manifest = JSON.parse(out);
-    return manifest?.config?.digest || null;
-  } catch {
-    return null;
-  }
+/** What a download without an explicit version fetches: the newest supported version the registry publishes, else the newest supported. */
+export async function defaultDownloadVersion(): Promise<string> {
+  return (await remoteSupportedVersions())?.[0] ?? newestSupportedVersion();
 }
 
-/**
- * Pull the image from the public registry and tag it locally.
- */
-async function pullFromRegistry(
-  opts: DownloadOptions,
-  emit: (data: string) => void,
-): Promise<boolean> {
-  if (!dockerAvailable()) {
-    emit(JSON.stringify({ type: 'error', message: 'Docker is not available' }));
-    appendLog('Docker not available — cannot download image');
-    return false;
-  }
-
-  emit(JSON.stringify({ type: 'status', message: `Downloading ${REGISTRY_IMAGE}...` }));
-  appendLog(`Downloading from registry: ${REGISTRY_IMAGE}`);
-
-  return new Promise((resolve) => {
-    const { exec } = require('child_process');
-    const child = exec(
-      `docker pull ${REGISTRY_IMAGE}`,
-      { maxBuffer: 1024 * 1024 * 5, timeout: 300_000 },
-      (err: Error | null) => {
-        if (err) {
-          appendLog(`Download from registry failed: ${err.message}`);
-          emit(JSON.stringify({ type: 'log', message: 'Registry download failed, trying local build...' }));
-          resolve(false);
-          return;
-        }
-
-        try {
-          execSyncRaw(`docker tag ${REGISTRY_IMAGE} ${LOCAL_IMAGE}`, { timeout: 10_000 });
-        } catch { /* ignore tag error */ }
-        appendLog('Download completed successfully');
-        emit(JSON.stringify({ type: 'complete', message: 'Image downloaded from registry' }));
-        resolve(true);
-      },
-    );
-
-    downloadChildProcess = child;
-
-    child.stderr?.on('data', (chunk: Buffer) => {
-      appendLog(chunk.toString());
-    });
-
-    child.stdout?.on('data', (chunk: Buffer) => {
-      appendLog(chunk.toString());
-    });
-
-    child.on('error', (err: Error) => {
-      appendLog(`Pull process error: ${err.message}`);
-      // Do NOT release the lock here: the caller falls through to
-      // localBuild(), which must stay protected. Releasing early let a
-      // concurrent request past getIsDownloading() and start a second
-      // `docker build` against the same tag. The lock is released by
-      // localBuild's own close/error handlers, or by the success path.
-      resolve(false);
-    });
-  });
+export interface DownloadOptions {
+  version?: string;
+  onEvent?: (data: string) => void;
+  signal?: AbortSignal;
 }
 
-/**
- * Local docker build fallback. Returns a Promise.
- */
-function localBuild(
-  opts: DownloadOptions,
-  emit: (data: string) => void,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const dockerfileDir = path.join(process.cwd(), 'agent-templates', 'base-image');
-    const dockerfile = path.join(dockerfileDir, 'Dockerfile');
-
-    if (!fs.existsSync(dockerfile)) {
-      const msg = 'Dockerfile not found — cannot build locally';
-      emit(JSON.stringify({ type: 'error', message: msg }));
-      appendLog(msg);
-      releaseLock();
-      reject(new Error(msg));
-      return;
-    }
-
-    const hash = getDockerfileHash();
-    const noCache = opts.force ? '--no-cache ' : '';
-    const cmd = hash
-      ? `docker build ${noCache}-t ${LOCAL_IMAGE} --label "rev4a.dockerfile_hash=${hash}" --progress=plain .`
-      : `docker build ${noCache}-t ${LOCAL_IMAGE} --progress=plain .`;
-
-    appendLog('');
-    appendLog('=== Local build started (registry download failed) ===');
-    appendLog(`Dockerfile hash: ${hash || 'unknown'}`);
-    appendLog('');
-
-    emit(JSON.stringify({ type: 'status', message: 'Building agent base image locally...' }));
-
-    const { exec } = require('child_process');
-    const child = exec(cmd, {
-      cwd: dockerfileDir,
-      maxBuffer: 1024 * 1024 * 10,
-    });
-
-    downloadChildProcess = child;
-
-    child.stdout?.on('data', (chunk: string) => {
-      const lines = chunk.toString().split('\n').filter(Boolean);
-      for (const line of lines) {
-        appendLog(line);
-        if (line.startsWith('#')) {
-          emit(JSON.stringify({ type: 'step', message: line }));
-        } else if (line.includes('Downloading') || line.includes('Extracting') || line.includes('Pulling')) {
-          emit(JSON.stringify({ type: 'progress', message: line }));
-        }
-      }
-    });
-
-    child.stderr?.on('data', (chunk: string) => {
-      const text = chunk.toString().trim();
-      if (text) {
-        appendLog(text);
-        emit(JSON.stringify({ type: 'log', message: text }));
-      }
-    });
-
-    child.on('close', (code: number) => {
-      if (code === 0) {
-        appendLog('=== Build completed successfully ===');
-        emit(JSON.stringify({ type: 'complete', message: 'Agent base image built successfully' }));
-        releaseLock();
-        resolve();
-      } else {
-        appendLog(`=== Build failed with exit code ${code} ===`);
-        releaseLock();
-        reject(new Error(`docker build exited with code ${code}`));
-      }
-    });
-
-    child.on('error', (err: Error) => {
-      appendLog(`=== Build error: ${err.message} ===`);
-      releaseLock();
-      reject(err);
-    });
-  });
+export interface DownloadResult {
+  version: string;
+  source: 'present' | 'registry' | 'build';
 }
 
 /**
- * Main entry point: try pull first, fallback to local build.
+ * Download one OpenClaw version of the agent image. Emits JSON events
+ * (`status`, `progress`, `step`, `log`, `complete`) through `onEvent`; failures are
+ * thrown, not emitted.
  */
-export async function downloadAgentImage(opts: DownloadOptions): Promise<void> {
-  const { force = false, onEvent, signal } = opts;
-
-  if (!dockerAvailable()) {
-    const msg = 'Docker is not available — please install Docker and try again';
-    onEvent?.(JSON.stringify({ type: 'error', message: msg }));
-    throw new Error(msg);
-  }
-
-  if (!tryAcquireLock()) {
-    throw new Error('A download is already in progress');
-  }
+export async function downloadAgentImage(opts: DownloadOptions = {}): Promise<DownloadResult> {
+  const event = (type: string, message: string) => {
+    opts.onEvent?.(JSON.stringify({ type, message }));
+    appendLog(message);
+  };
 
-  const timestamp = Date.now();
-  downloadLogPath = `/tmp/rev4a-download-${timestamp}.log`;
+  if (!dockerAvailable()) throw new Error('Docker is not available — please install Docker and try again');
+  if (downloadingVersion !== null) throw new Error('A download is already in progress');
+  downloadingVersion = opts.version ?? 'pending';
+  downloadLogPath = `/tmp/rev4a-download-${Date.now()}.log`;
 
-  const emit = (data: string) => {
-    onEvent?.(data);
-    try {
-      const parsed = JSON.parse(data);
-      if (parsed.message) appendLog(parsed.message);
-    } catch { /* not JSON */ }
-  };
+  try {
+    const version = opts.version ?? (await defaultDownloadVersion());
+    if (!isSupportedVersion(version)) throw new Error(`OpenClaw ${version} is not supported by this Rev4a`);
+    downloadingVersion = version;
 
-  // If not forced and image already exists, check if update is needed
-  if (!force && localImageExists()) {
-    const remoteDigest = getRemoteDigest();
-    if (!remoteDigest) {
-      emit(JSON.stringify({ type: 'complete', message: 'Image already downloaded (offline, cannot check for updates)' }));
-      releaseLock();
-      return;
+    if (await localVersionExists(version)) {
+      event('complete', `OpenClaw ${version} image already downloaded`);
+      return { version, source: 'present' };
     }
 
-    emit(JSON.stringify({ type: 'complete', message: 'Image already downloaded' }));
-    releaseLock();
-    return;
-  }
-
-  // Force: remove local image first so we get a fresh pull
-  if (force) {
+    event('status', `Downloading OpenClaw ${version} image…`);
     try {
-      execSyncRaw(`docker rmi -f ${LOCAL_IMAGE} ${REGISTRY_IMAGE} 2>/dev/null || true`, { timeout: 5000 });
-    } catch { /* ok */ }
-  }
-
-  appendLog(opts.force ? '=== Image refresh started ===' : '=== Image download started ===');
-
-  // Try download from registry first
-  const downloaded = await pullFromRegistry(opts, emit);
+      await pullAgentImage(version, {
+        signal: opts.signal,
+        onLine: (line) => {
+          appendLog(line);
+          if (/Download|Extract|Pull/.test(line)) opts.onEvent?.(JSON.stringify({ type: 'progress', message: line }));
+        },
+      });
+      event('complete', `OpenClaw ${version} image downloaded`);
+      return { version, source: 'registry' };
+    } catch (e) {
+      appendLog(`Registry download failed: ${(e as Error).message}`);
+      if (opts.signal?.aborted || dockerfileVersion() !== version) {
+        throw new Error(`Could not download OpenClaw ${version}: ${(e as Error).message}`);
+      }
+    }
 
-  if (downloaded) {
+    event('log', 'Registry download failed, building the image locally…');
+    await runDocker(
+      ['build', '--build-arg', `OPENCLAW_VERSION=${version}`, '-t', localImageRef(version), '--progress=plain', DOCKERFILE_DIR],
+      {
+        signal: opts.signal,
+        timeoutMs: BUILD_TIMEOUT_MS,
+        onLine: (line) => {
+          appendLog(line);
+          if (line.startsWith('#')) opts.onEvent?.(JSON.stringify({ type: 'step', message: line }));
+        },
+      },
+    );
+    event('complete', `OpenClaw ${version} image built locally`);
+    return { version, source: 'build' };
+  } finally {
+    downloadingVersion = null;
+    downloadLogPath = null;
     cleanupOldLogs();
-    releaseLock();
-    return;
   }
-
-  // Fallback: local build
-  await localBuild(opts, emit);
-  cleanupOldLogs();
 }