@flame0510/project-aether 1.3.0 → 1.4.0

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

@@ -0,0 +1,126 @@
+/**
+ * Browser access to one agent's Control UI.
+ *
+ *   GET     pending approvals and approved browsers
+ *   POST    { action: "approve" | "reject", requestId }
+ *   PATCH   { deviceId, name }            rename an approved browser
+ *   DELETE  ?deviceId=<id>                revoke: the browser needs approval again
+ *
+ * All operations run the OpenClaw CLI inside the container asynchronously; see
+ * `lib/agent-devices.ts`.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import {
+  approveBrowser,
+  cleanDeviceName,
+  findAgentContainer,
+  isDeviceId,
+  isRequestId,
+  listBrowserAccess,
+  rejectBrowser,
+  removeBrowser,
+  renameBrowser,
+  type AgentContainer,
+} from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+/** The agent's container, or the response that explains why there is none to act on. */
+async function resolveAgent(id: string): Promise<AgentContainer | NextResponse> {
+  let agent: AgentContainer | null;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return NextResponse.json({ error: `Docker is unreachable: ${(e as Error).message}` }, { status: 503 });
+  }
+  if (!agent) return NextResponse.json({ error: `No agent '${id}'` }, { status: 404 });
+  return agent;
+}
+
+const failed = (e: unknown) => NextResponse.json({ error: (e as Error).message || 'OpenClaw command failed' }, { status: 502 });
+
+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;
+  const agent = await resolveAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  if (!agent.running) return NextResponse.json({ running: false, requiresApproval: null, pending: [], approved: [] });
+  try {
+    return NextResponse.json({ running: true, ...(await listBrowserAccess(agent.name)) });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+async function runningAgent(id: string): Promise<AgentContainer | NextResponse> {
+  const agent = await resolveAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  if (!agent.running) return NextResponse.json({ error: 'The agent is not running' }, { status: 409 });
+  return agent;
+}
+
+async function readBody(request: NextRequest): Promise<Record<string, unknown> | null> {
+  try {
+    const body = await request.json();
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+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;
+  const body = await readBody(request);
+  if (!body || (body.action !== 'approve' && body.action !== 'reject')) {
+    return NextResponse.json({ error: 'action must be "approve" or "reject"' }, { status: 400 });
+  }
+  if (!isRequestId(body.requestId)) return NextResponse.json({ error: 'A valid requestId is required' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    if (body.action === 'approve') await approveBrowser(agent.name, body.requestId);
+    else await rejectBrowser(agent.name, body.requestId);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+export async function PATCH(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const body = await readBody(request);
+  if (!body || !isDeviceId(body.deviceId)) return NextResponse.json({ error: 'A valid deviceId is required' }, { status: 400 });
+  const name = cleanDeviceName(body.name);
+  if (!name) return NextResponse.json({ error: 'name must be 1-64 printable characters' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    await renameBrowser(agent.name, body.deviceId, name);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+export async function DELETE(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const deviceId = request.nextUrl.searchParams.get('deviceId');
+  if (!isDeviceId(deviceId)) return NextResponse.json({ error: 'A valid deviceId query parameter is required' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    await removeBrowser(agent.name, deviceId);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}

package/app/api/agents/[id]/invite-link/route.ts

@@ -0,0 +1,53 @@
+/**
+ * GET /api/agents/[id]/invite-link
+ *
+ * A Control UI link to send to someone else. It carries the gateway token, so the
+ * browser that opens it passes gateway auth and lands in the agent's "waiting for
+ * approval" list; nothing opens until an operator approves it.
+ *
+ * Refused on agents without browser approval, where the same link would open the
+ * Control UI directly. The host is the one this request reached Rev4a on, never a
+ * parameter.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { buildInviteLink, findAgentContainer, hostnameFromHostHeader, requiresBrowserApproval } from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+const noStore = { 'Cache-Control': 'no-store' };
+
+const fail = (status: number, error: string) => NextResponse.json({ error }, { status, headers: noStore });
+
+const isLoopback = (hostname: string) =>
+  hostname === 'localhost' || hostname.startsWith('127.') || hostname === '[::1]';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const hostname = hostnameFromHostHeader(request.headers.get('host'));
+  if (!hostname) return fail(400, 'Could not tell which address Rev4a is being reached on');
+
+  let agent;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return fail(503, `Docker is unreachable: ${(e as Error).message}`);
+  }
+  if (!agent) return fail(404, `No agent '${id}'`);
+  if (!agent.running || !agent.controlPort) return fail(409, 'The agent is not running or publishes no Control UI port');
+
+  const requiresApproval = await requiresBrowserApproval(agent.name);
+  if (requiresApproval === null) return fail(502, 'Could not tell whether this agent requires browser approval');
+  if (!requiresApproval) return fail(409, 'This agent does not require browser approval: anyone with the link would get in');
+
+  try {
+    const url = await buildInviteLink(agent.name, hostname, agent.controlPort);
+    return NextResponse.json({ url, loopbackHost: isLoopback(hostname) }, { headers: noStore });
+  } catch (e) {
+    return fail(502, (e as Error).message);
+  }
+}

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { execSync } from 'child_process';
 import { resolveAgentedContainer, isValidAgentId, isLifecycleCoolingDown, markLifecycleCooldown } from '@/lib/container';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { agentBusyReason } from '@/lib/agent-busy';
 
 export const dynamic = 'force-dynamic';
 
@@ -23,6 +24,8 @@ export async function POST(
     const { id } = await params;
     if (!id) return NextResponse.json({ error: 'Agent ID required' }, { status: 400 });
     if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+    const busy = await agentBusyReason(id);
+    if (busy) return NextResponse.json({ error: busy }, { status: 409 });
 
     const containerName = resolveAgentedContainer(id);
     if (!containerName) {

package/app/api/agents/[id]/open-control-ui/route.ts

@@ -0,0 +1,58 @@
+/**
+ * GET /api/agents/[id]/open-control-ui
+ *
+ * What the "Open" buttons navigate to, in a new tab. Redirects to the agent's Control
+ * UI: through a one-time link that pairs the browser with no approval on OpenClaw 9.x,
+ * or through the plain token link on 2026.7.x or when no one-time link can be issued.
+ *
+ * The target host is the one this request reached Rev4a on (the `Host` header), with
+ * the agent's published port. It is never a parameter: a page elsewhere that gets a
+ * signed-in browser to open this URL can at most open the Control UI in that same
+ * browser, never send the link to another host.
+ *
+ * A navigation rather than a fetch on purpose: the button opens this URL inside the
+ * click, so nothing is left to assign to a blank tab after an `await`, and there is
+ * no popup for the browser to block. See `lib/agent-devices.ts`.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { findAgentContainer, hostnameFromHostHeader, resolveControlUiUrl } from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+/** A plain-text page: this route is opened in a browser tab, not read by code. */
+function page(status: number, text: string): NextResponse {
+  return new NextResponse(`${text}\n`, {
+    status,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' },
+  });
+}
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const host = hostnameFromHostHeader(request.headers.get('host'));
+  if (!host) return page(400, 'Could not tell which address Rev4a is being reached on.');
+
+  let agent;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return page(503, `Docker is unreachable: ${(e as Error).message}`);
+  }
+  if (!agent) return page(404, `No agent '${id}'.`);
+  if (!agent.running || !agent.controlPort) return page(409, 'The agent is not running or publishes no Control UI port.');
+
+  try {
+    const { url } = await resolveControlUiUrl(agent.name, host, agent.controlPort);
+    return new NextResponse(null, {
+      status: 302,
+      headers: { Location: url, 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' },
+    });
+  } catch (e) {
+    return page(502, `Could not open the Control UI: ${(e as Error).message}.`);
+  }
+}

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

@@ -1,175 +1,45 @@
-import { NextResponse } from 'next/server';
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { patchRev4aProvider } from '@/app/api/gateway/sync';
-import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
+/**
+ * Recreate one agent's container on the image it already runs (lib/agent-recreate.ts).
+ *
+ *   POST    start: a cold backup is taken (the agent stops for it), then the container
+ *           is rebuilt and the gateway waited for. 202 once the job has started; the
+ *           steps continue in the background and are recorded in `agent_recreates`.
+ *   GET     `{ recreate }`: the running or last job, with backup progress; null when none.
+ *
+ * While it runs, anything else that would touch the agent answers 409 (lib/agent-busy.ts).
+ */
+import { NextResponse, type NextRequest } from 'next/server';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
-import { waitForGatewayReady } from '@/lib/agent-readiness';
+import { isValidAgentId } from '@/lib/container';
+import { agentRecreateView, RecreateRefusedError, startAgentRecreate } from '@/lib/agent-recreate';
 
 export const dynamic = 'force-dynamic';
-export const maxDuration = 180; // docker run (60s) + startup wait (60s) + config patch (60s)
 
-const BACKUP_VOLUME = 'rev4a-backups';
+type Ctx = { params: Promise<{ id: string }> };
 
-/** Timestamp YYYY-MM-DD_HHmmssSSS (ms precision avoids same-second collisions). */
-function ts(): string {
-  const d = new Date();
-  const pad = (n: number) => String(n).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${ms}`;
+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 });
 }
 
-
-/**
- * POST /api/agents/[id]/recreate
- * Stop -> backup -> rm -> run with same params + shared volumes.
- * Workspace data and state are preserved in the persistent volume.
- * Shared volumes (skills, repos) are always mounted.
- * After the container is up, guarantee extraDirs + provider config.
- */
-export async function POST(request: Request,
-  { params }: { params: Promise<{ id: string }> },
-): Promise<NextResponse> {
-  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+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;
   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 });
-
-    // Resolve the actual container name via AGENT_ID label
-    const containerName = resolveAgentedContainer(id);
-    if (!containerName) {
-      return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
-    }
-
-    // Inspect the existing container to capture its parameters
-    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 env: string[] = container.Config?.Env || [];
-
-    // Filter and reformat env vars (skip system vars, keep AGENT_*, MODEL_*, OPENCLAW_*, TZ)
-    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(' ');
-
-    // Extract labels (keep AGENT_ID, traefik.*, description, maintainer)
-    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(' ');
-
-    // Determine network (must exist on the container)
-    const networks = container.NetworkSettings?.Networks || {};
-    const network = Object.keys(networks)[0];
-    if (!network) {
-      return NextResponse.json({ error: 'Cannot determine network — container may have no networks attached' }, { status: 500 });
-    }
-
-    // Determine if there was a custom port mapping
-    const portMappings = (container.HostConfig?.PortBindings || {}) as Record<string, { HostPort: string }[]>;
-    const portOpts = Object.entries(portMappings)
-      .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(' ');
-
-    const volumeName = `agent-${id}-data`;
-
-    // Auto-backup the volume BEFORE destroying the container
-    const backupFile = `agent-${id}-prerecreate-${ts()}.tar.gz`;
-    try {
-      execSync(
-        `docker run --rm ` +
-        `-v ${volumeName}:/source:ro ` +
-        `-v ${BACKUP_VOLUME}:/backup ` +
-        `alpine sh -c 'tar czf /backup/${backupFile} --exclude=.npm/_cacache -C /source . && chmod 644 /backup/${backupFile}'`,
-        { timeout: 60000, stdio: 'pipe' },
-      );
-    } catch (backupErr) {
-      return NextResponse.json(
-        { error: `Pre-recreate backup failed, aborting: ${(backupErr as Error).message}` },
-        { status: 500 },
-      );
-    }
-
-    // Stop & remove the old container. If removal fails (Docker daemon
-    // overloaded, container stuck in "removal in progress"), abort — we
-    // can't run a new container with a conflicting name.
-    try {
-      execSync(`docker rm -f ${containerName}`, { timeout: 15000 });
-    } catch (rmErr) {
-      return NextResponse.json(
-        { error: `Failed to remove old container '${containerName}': ${(rmErr as Error).message}. The original container may still be running.` },
-        { status: 500 },
-      );
-    }
-
-    // Run the new container with all mounts (persistent volume + shared skills + shared repos + rev4a rules)
-    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 the new container to finish starting — /startupz, not /health
-    const ready = await waitForGatewayReady(id);
-    if (!ready) {
-      return NextResponse.json(
-        { success: false, error: 'Container started but its gateway did not finish starting within 60s.' },
-        { status: 500 },
-      );
-    }
-
-    // Guarantee Rev4a runtime config (hooks, shared-skills, provider).
-    // Uses config patch (deep-merge) — idempotent, preserves user customizations.
-    try {
-      applyRuntimeConfig(id);
-
-      // Also guarantee models.providers.rev4a (host-dependent, not in base image)
-      patchRev4aProvider(id);
-    } catch (e) {
-      // best-effort on recreate, but a skipped patch must show up in the log
-      console.error('[agent:recreate] runtime config patch failed:', (e as Error).message);
-    }
-
-    return NextResponse.json({ success: true, name: id, image, network, backup: backupFile });
-  } catch (e: unknown) {
-    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+    const rowId = await startAgentRecreate(id);
+    return NextResponse.json({ started: true, id: rowId }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof RecreateRefusedError
+      ? 409
+      : /No container|not available locally|Cannot tell which image/.test((e as Error).message) ? 404 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
   }
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+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({ recreate: await agentRecreateView(id) }, { headers: { 'Cache-Control': 'no-store' } });
 }

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' } });
+}