@flame0510/project-aether 1.2.0 → 1.4.0

package/app/api/agents/[id]/restart/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { execSync } from 'child_process';
 import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { agentBusyReason } from '@/lib/agent-busy';
 
 export const dynamic = 'force-dynamic';
 
@@ -23,6 +24,10 @@ export async function POST(request: Request,
       return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
     }
 
+    // A restart during an update, recreate, restore, edit or backup would cut it in half.
+    const busy = await agentBusyReason(id);
+    if (busy) return NextResponse.json({ error: busy }, { status: 409 });
+
     execSync(`docker restart ${containerName}`, { timeout: 30000 });
 
     return NextResponse.json({ success: true });

package/app/api/agents/[id]/restore/route.ts

@@ -1,81 +1,51 @@
-import { NextResponse } from 'next/server';
-import { execSync } from 'child_process';
-import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { requireAuthJWT } from '@/lib/rev4a-auth';
-
-export const dynamic = 'force-dynamic';
-
-const BACKUP_VOLUME = 'rev4a-backups';
-
 /**
- * POST /api/agents/[id]/restore?file=agent-xxx-2026-07-11_2115.tar.gz
- * Restore an agent's persistent volume from a backup.
- * Stops the container, restores the volume, then restarts.
+ * Restore one agent's volume from a backup archive (lib/agent-restore.ts).
+ *
+ *   POST ?file=…  start: the container is stopped, the volume cleared and the archive
+ *                 extracted (up to 30 minutes), then the container is started again even
+ *                 when the extract failed. 202 once the job has started; the steps
+ *                 continue in the background and are recorded in `agent_restores`.
+ *   GET           `{ restore }`: the running or last job; null when none.
+ *
+ * While it runs, anything else that would touch the agent answers 409 (lib/agent-busy.ts).
  */
-export async function POST(request: Request,
-  { params }: { params: Promise<{ id: string }> },
-): Promise<NextResponse> {
-  const denied = await requireAuthJWT(request); if (denied) return denied as any;
-  try {
-    const { id } = await params;
-    if (!id) return NextResponse.json({ error: 'Agent name required' }, { status: 400 });
-    if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
-
-    const url = new URL(request.url);
-    const file = url.searchParams.get('file');
-    if (!file) return NextResponse.json({ error: 'file query param required' }, { status: 400 });
-
-    // Safety: only allow restoring agent-specific files, reject path traversal
-    if (!file.startsWith(`agent-${id}-`) || !file.endsWith('.tar.gz') || file.includes('/') || file.includes('..')) {
-      return NextResponse.json({ error: 'Invalid backup file name' }, { status: 400 });
-    }
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { agentRestoreView, RestoreRefusedError, startAgentRestore } from '@/lib/agent-restore';
 
-    const volume = `agent-${id}-data`;
+export const dynamic = 'force-dynamic';
 
-    // Resolve the actual container name via AGENT_ID label
-    const containerName = resolveAgentedContainer(id);
+type Ctx = { params: Promise<{ id: string }> };
 
-    // Check backup exists
-    const check = execSync(
-      `docker run --rm -v ${BACKUP_VOLUME}:/backup alpine sh -c 'test -f /backup/${file} && echo ok || true'`,
-      { timeout: 10000, encoding: 'utf-8' },
-    ).trim();
-    if (check !== 'ok') {
-      return NextResponse.json({ error: `Backup file '${file}' not found` }, { status: 404 });
-    }
+async function agentId(ctx: Ctx): Promise<string | NextResponse> {
+  const { id } = await ctx.params;
+  return isValidAgentId(id) ? id : NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+}
 
-    // Stop the container if running
-    if (containerName) {
-      execSync(`docker stop ${containerName} 2>/dev/null; exit 0`, { timeout: 15000 });
-    }
+export async function POST(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
 
-    // Clear the volume and restore from backup.
-    // Run a temporary container with the volume, delete ALL contents (including
-    // dotfiles/dotdirs like .openclaw, .config, .local — the .[!.]* glob is
-    // required, otherwise the restore only merges on top of stale state), then
-    // extract the backup. Always restart the container afterwards, even on failure.
-    try {
-      execSync(
-        `docker run --rm ` +
-        `-v ${volume}:/target ` +
-        `-v ${BACKUP_VOLUME}:/backup ` +
-        `alpine sh -c 'rm -rf /target/* /target/.[!.]* /target/..?* 2>/dev/null; tar xzf /backup/${file} -C /target'`,
-        { timeout: 30000, stdio: 'pipe' },
-      );
-    } finally {
-      // Restart the container regardless of extract outcome so it never stays down.
-      if (containerName) {
-        try {
-          execSync(`docker start ${containerName}`, { timeout: 15000, stdio: 'pipe' });
-        } catch {
-          // container start failure is surfaced separately; nothing else to do here
-        }
-      }
-    }
+  const file = new URL(request.url).searchParams.get('file');
+  if (!file) return NextResponse.json({ error: 'file query param required' }, { status: 400 });
 
-    return NextResponse.json({ success: true, container: containerName || id });
-  } catch (e: unknown) {
-    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+  try {
+    const rowId = await startAgentRestore(id, file);
+    return NextResponse.json({ started: true, id: rowId }, { status: 202 });
+  } catch (e) {
+    const message = (e as Error).message;
+    const status = e instanceof RestoreRefusedError
+      ? (/Invalid backup file name|Invalid agent id/.test(message) ? 400 : /not found/.test(message) ? 404 : 409)
+      : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
   }
 }
 
+export async function GET(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
+  return NextResponse.json({ restore: agentRestoreView(id) }, { headers: { 'Cache-Control': 'no-store' } });
+}

package/app/api/agents/[id]/route.ts

@@ -3,8 +3,8 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { buildRev4aProviderConfig } from '@/app/api/gateway/sync';
-import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
+import { agentBusyReason } from '@/lib/agent-busy';
+import { agentEditView, EditRefusedError, startAgentEdit } from '@/lib/agent-edit';
 import { DB_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
@@ -29,6 +29,9 @@ export async function DELETE(request: Request,
       return NextResponse.json({ success: false, error: 'Invalid agent id' }, { status: 400 });
     }
 
+    const busy = await agentBusyReason(id);
+    if (busy) return NextResponse.json({ error: busy }, { status: 409 });
+
     // Only allow deletion of containers that have a matching AGENT_ID label
     const containerName = resolveAgentedContainer(id);
     if (!containerName) {
@@ -86,31 +89,14 @@ export async function DELETE(request: Request,
   }
 }
 
-function waitForContainerReady(name: string, timeoutMs = 60000): boolean {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      execSync(
-        `docker exec ${name} sh -c 'curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 || wget -qO- http://127.0.0.1:3000/health >/dev/null 2>&1'`,
-        { timeout: 5000 },
-      );
-      return true;
-    } catch { /* not ready */ }
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
 /**
  * PATCH /api/agents/[id]
  *
- * Update agent settings (display name, ports — future).
- * Recreates the container with updated env vars while preserving the
- * persistent volume, workspace, sessions, and all data.
+ * Edit an agent's display name and/or port range. The container is rebuilt on the image
+ * it already runs — **no backup**, the persistent volume is never touched — and the job
+ * runs in the background (`lib/agent-edit.ts`): `202` once it has started, then
+ * `GET /api/agents/[id]` reports the running or last edit so the panel can resume.
+ * While it runs, anything else that would touch the agent answers `409`.
  */
 export async function PATCH(
   request: Request,
@@ -129,154 +115,37 @@ export async function PATCH(
       return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
     }
 
-    const { displayName, portRange } = body;
-    if (!displayName && !portRange) {
-      return NextResponse.json({ error: 'No fields to update' }, { status: 400 });
-    }
-
-    if (displayName !== undefined && (!displayName || displayName.trim().length < 1)) {
-      return NextResponse.json({ error: 'Display name must not be empty' }, { status: 400 });
-    }
-
-    // Resolve the container
-    const containerName = resolveAgentedContainer(id);
-    if (!containerName) {
-      return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
-    }
-
-    // Inspect existing container
-    let inspect: string;
-    try {
-      inspect = execSync(`docker inspect ${containerName}`, { timeout: 10000, encoding: 'utf-8' }).trim();
-    } catch {
-      return NextResponse.json({ error: `Container '${containerName}' not found` }, { status: 404 });
-    }
-
-    const info = JSON.parse(inspect);
-    const [container] = info;
-    const image = container.Config?.Image || 'openclaw-agent-base:latest';
-    const currentEnv: string[] = container.Config?.Env || [];
-
-    // Update AGENT_NAME in env vars
-    let env = [...currentEnv];
-    if (displayName) {
-      const idx = env.findIndex((e: string) => e.startsWith('AGENT_NAME='));
-      const newEntry = `AGENT_NAME=${displayName.trim()}`;
-      if (idx >= 0) {
-        env[idx] = newEntry;
-      } else {
-        env.push(newEntry);
-      }
-    }
-
-    // Keep only relevant env vars
-    const keepPrefixes = ['AGENT_', 'MODEL_', 'OPENCLAW_', 'TZ='];
-    const envOpts = env
-      .filter((e: string) => keepPrefixes.some((p) => e.startsWith(p)))
-      .map((e: string) => `-e ${shellQuote(e)}`)
-      .join(' ');
-
-    // Labels
-    const labels = container.Config?.Labels || {};
-    const keepLabelKeys = ['AGENT_ID', 'traefik.', 'description', 'maintainer'];
-    const labelOpts = Object.entries(labels)
-      .filter(([k]) => keepLabelKeys.some((p) => k === p || k.startsWith(p)))
-      .map(([k, v]) => `-l ${shellQuote(`${k}=${v}`)}`)
-      .join(' ');
-
-    // Network
-    const networks = container.NetworkSettings?.Networks || {};
-    const network = Object.keys(networks)[0];
-    if (!network) {
-      return NextResponse.json({ error: 'Cannot determine network' }, { status: 500 });
-    }
-
-    // Port mappings
-    const portBindings = (container.HostConfig?.PortBindings || {}) as Record<string, { HostPort: string }[]>;
-    let portOpts = Object.entries(portBindings)
-      .map(([containerPort, bindings]) => {
-        const hostPort = bindings[0]?.HostPort;
-        if (!hostPort) return '';
-        const proto = containerPort.includes('/udp') ? '/udp' : '';
-        return `-p ${hostPort}:${containerPort.replace(/\/.*$/, '')}${proto}`;
-      })
-      .filter(Boolean)
-      .join(' ');
-
-    // If portRange is provided, replace the port mapping
-    if (portRange) {
-      const parts = portRange.trim().split('-');
-      const start = parseInt(parts[0], 10);
-      const end = parts[1] ? parseInt(parts[1], 10) : start;
-      if (isNaN(start) || isNaN(end) || start < 1 || end > 65535 || end < start) {
-        return NextResponse.json({ error: 'Invalid port range' }, { status: 400 });
-      }
-      if (end === start) {
-        portOpts = `-p ${start}:3000`;
-      } else {
-        portOpts = `-p ${start}-${end}:3000-${3000 + (end - start)}`;
-      }
-    }
-
-    const volumeName = `agent-${id}-data`;
-
-    // Stop & remove old container (keep volume)
-    try {
-      execSync(`docker rm -f ${containerName}`, { timeout: 15000 });
-    } catch (rmErr) {
-      return NextResponse.json(
-        { error: `Failed to remove old container: ${(rmErr as Error).message}` },
-        { status: 500 },
-      );
-    }
-
-    // Run new container with same volume
-    const cmd = [
-      `docker run -d`,
-      `--name "${id}"`,
-      `--network "${network}"`,
-      `--restart unless-stopped`,
-      `--add-host host.docker.internal:host-gateway`,
-      `-v ${volumeName}:/root`,
-      ...getMountFlags(),
-      labelOpts,
-      envOpts,
-      portOpts,
-      `"${image}"`,
-    ].filter(Boolean).join(' \\\n  ');
-
-    execSync(cmd, { timeout: 60000, encoding: 'utf-8' });
-
-    // Wait for healthy
-    const ready = waitForContainerReady(id);
-    if (!ready) {
-      return NextResponse.json(
-        { error: 'Container started but gateway did not become healthy within 60s.' },
-        { status: 500 },
-      );
-    }
-
-    // Apply runtime config
-    try {
-      applyRuntimeConfig(id);
-      const providerConfig = buildRev4aProviderConfig();
-      const providerJson = JSON.stringify({ models: { providers: { rev4a: providerConfig } } });
-      execSync(
-        `docker exec -i ${id} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
-      // No gateway restart: `config patch` reports "Change will apply without
-      // restarting the gateway" for a models-only patch, and the Gateway watches
-      // openclaw.json with gateway.reload defaulting to hybrid.
-    } catch { /* non-fatal */ }
-
-    return NextResponse.json({
-      success: true,
-      displayName: displayName?.trim() || null,
-    });
+    const rowId = await startAgentEdit(id, { displayName: body.displayName, portRange: body.portRange });
+    return NextResponse.json({ started: true, id: rowId }, { status: 202 });
   } catch (e: unknown) {
+    if (e instanceof EditRefusedError) {
+      const message = e.message;
+      // The shared port validator's messages (lib/agent-ports.ts) are validation errors:
+      // they answer 400, like the create route. Everything else is a busy refusal (409).
+      const status = /Invalid agent id|Display name must not be empty|No fields to update|Invalid format|Ports must be between|End port must be greater|reserved for Rev4a|already in use|Use a number/.test(message)
+        ? 400
+        : 409;
+      return NextResponse.json({ error: message }, { status });
+    }
     return NextResponse.json({ error: (e as Error).message }, { status: 500 });
   }
 }
 
+/**
+ * GET /api/agents/[id]
+ *
+ * The running or last edit of an agent (`null` when it was never edited): what the edit
+ * panel polls to resume after a reload.
+ */
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  return NextResponse.json({ edit: agentEditView(id) }, { headers: { 'Cache-Control': 'no-store' } });
+}
+
+
 

package/app/api/agents/[id]/update/rollback/route.ts

@@ -0,0 +1,30 @@
+/**
+ * POST /api/agents/[id]/update/rollback
+ *
+ * Roll back the agent's latest update (lib/agent-update.ts): its pre-update backup is
+ * restored and the container recreated on the version it ran before. Everything the
+ * agent did after that backup is lost. 202 with the update; the steps continue in the
+ * background, `GET /api/agents/[id]/update` follows them.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { UpdateRefusedError, agentUpdateView, startAgentRollback } from '@/lib/agent-update';
+
+export const dynamic = 'force-dynamic';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  try {
+    await startAgentRollback(id);
+    return NextResponse.json({ update: await agentUpdateView(id) }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof UpdateRefusedError ? 409 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
+  }
+}

package/app/api/agents/[id]/update/route.ts

@@ -0,0 +1,50 @@
+/**
+ * Update one agent to a newer supported OpenClaw version (lib/agent-update.ts).
+ *
+ *   GET   `{ currentVersion, candidate, update }`: the version the agent runs, the
+ *         `{ fromVersion, toVersion }` an update would do (null when none is newer),
+ *         and the latest update with its status and live backup progress.
+ *   POST  `{ version? }` — start an update, by default to the newest supported version
+ *         downloaded. 202 with the new update; the steps continue in the background.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { isSupportedVersion } from '@/lib/agent-versions';
+import { UpdateRefusedError, agentUpdateView, startAgentUpdate, updateCandidate } from '@/lib/agent-update';
+
+export const dynamic = 'force-dynamic';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function GET(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  try {
+    const { currentVersion, candidate } = await updateCandidate(id);
+    return NextResponse.json(
+      { currentVersion, candidate, update: await agentUpdateView(id) },
+      { headers: { 'Cache-Control': 'no-store' } },
+    );
+  } catch (e) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 503 });
+  }
+}
+
+export async function POST(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  const body = (await request.json().catch(() => null)) as { version?: unknown } | null;
+  if (body?.version !== undefined && body.version !== null && !isSupportedVersion(body.version)) {
+    return NextResponse.json({ error: 'version must be an OpenClaw version this Rev4a supports' }, { status: 400 });
+  }
+  try {
+    await startAgentUpdate(id, (body?.version as string | undefined) ?? undefined);
+    return NextResponse.json({ update: await agentUpdateView(id) }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof UpdateRefusedError ? 409 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
+  }
+}

package/app/api/agents/activity-summary/route.ts

@@ -0,0 +1,67 @@
+/**
+ * GET /api/agents/activity-summary
+ *
+ * The long operation each agent is in the middle of, if any — the chip on the agent
+ * cards: `BACKUP nn%`, `RESTORING`, `RECREATING`, `UPDATING`.
+ *
+ * One Docker list call plus, per running cold backup, its status read. Idle agents are
+ * not listed at all, so an idle system costs one call.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { coldBackupStatus, listRunningColdBackups } from '@/lib/cold-backup';
+import { activeRestoreAgentIds, latestRestore } from '@/lib/agent-restore-state';
+import { activeRecreateAgentIds, latestRecreate } from '@/lib/agent-recreate-state';
+import { activeUpdateAgentIds, latestUpdate } from '@/lib/agent-update-state';
+import { activeEditAgentIds, latestEdit } from '@/lib/agent-edit-state';
+
+export const dynamic = 'force-dynamic';
+
+export type AgentActivityKind = 'backup' | 'restore' | 'recreate' | 'update' | 'edit';
+
+interface AgentActivity {
+  agentId: string;
+  kind: AgentActivityKind;
+  file?: string | null;
+  version?: string | null;
+  percent?: number | null;
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+
+  const byAgent = new Map<string, AgentActivity>();
+
+  // Update and recreate first: a running cold backup then overrides them, because while
+  // its helper archives the volume that is the phase actually in progress.
+  for (const agentId of activeUpdateAgentIds()) {
+    const row = latestUpdate(agentId);
+    if (row && (row.status === 'migrating' || row.status === 'verifying' || row.status === 'rolling_back')) {
+      byAgent.set(agentId, { agentId, kind: 'update', version: row.to_version });
+    }
+  }
+  for (const agentId of activeRecreateAgentIds()) {
+    const row = latestRecreate(agentId);
+    if (row && row.status === 'recreating') {
+      byAgent.set(agentId, { agentId, kind: 'recreate', version: row.image });
+    }
+  }
+  for (const agentId of activeRestoreAgentIds()) {
+    byAgent.set(agentId, { agentId, kind: 'restore', file: latestRestore(agentId)?.file ?? null });
+  }
+  for (const agentId of activeEditAgentIds()) {
+    const row = latestEdit(agentId);
+    if (row && row.status === 'rebuilding') {
+      byAgent.set(agentId, { agentId, kind: 'edit', file: row.display_name });
+    }
+  }
+
+  const backupIds = await listRunningColdBackups().catch(() => []);
+  await Promise.all(backupIds.map(async (agentId) => {
+    const job = await coldBackupStatus(agentId).catch(() => null);
+    if (!job || job.status !== 'running') return;
+    byAgent.set(agentId, { agentId, kind: 'backup', file: job.file, percent: job.percent });
+  }));
+
+  return NextResponse.json({ agents: [...byAgent.values()] }, { headers: { 'Cache-Control': 'no-store' } });
+}