@flame0510/project-aether 1.3.0 → 1.4.0

package/app/api/setup/agent-image/route.ts

@@ -1,60 +1,36 @@
 /**
  * GET /api/setup/agent-image
  *
- * Checks if openclaw-agent-base:latest exists locally or needs downloading.
- * Returns status and a hint for the UI.
+ * Whether a supported OpenClaw version of the agent base image is downloaded.
+ * Returns `{ exists, version }`, the version being the newest one present.
  *
  * POST /api/setup/agent-image
  *
- * Downloads openclaw-agent-base:latest from ghcr.io (public registry).
- * Streams progress via SSE so the setup wizard can show a live progress bar.
+ * Downloads the newest supported version the registry publishes, and streams
+ * progress via SSE so the setup wizard can show a live progress bar. Nothing is
+ * downloaded when that version is already here.
  *
  * Only one download at a time — returns 409 if already running.
- * Cleans up the docker process if the client disconnects.
  */
 import { NextResponse, type NextRequest } from 'next/server';
 import { downloadAgentImage, getIsDownloading } from '@/lib/buildAgentImage';
-import { execSync } from 'child_process';
 import { requireAuthIfConfigured } from '@/lib/rev4a-auth';
+import { dockerAvailable } from '@/lib/docker-socket';
+import { listLocalAgentImages, newestLocalSupportedVersion } from '@/lib/agent-images';
 
 export const dynamic = 'force-dynamic';
 
-function dockerOk(): boolean {
-  try {
-    execSync('docker version --format "{{.Client.Version}}" 2>/dev/null', {
-      encoding: 'utf-8',
-      timeout: 2000,
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function GET(request: NextRequest): Promise<NextResponse> {
   const denied = await requireAuthIfConfigured(request);
   if (denied) return denied;
-  if (!dockerOk()) {
-    return NextResponse.json({ exists: false });
+  if (!dockerAvailable()) {
+    return NextResponse.json({ exists: false, version: null });
   }
   try {
-    const { exec } = await import('child_process');
-    const result = await new Promise<string>((resolve, reject) => {
-      exec(
-        'docker image inspect openclaw-agent-base:latest --format "{{.ID}}" 2>/dev/null',
-        { timeout: 5000 },
-        (err, stdout) => {
-          if (err) return reject(err);
-          resolve(stdout.trim());
-        },
-      );
-    });
-    if (result) {
-      return NextResponse.json({ exists: true, imageId: result });
-    }
-    return NextResponse.json({ exists: false });
+    const version = newestLocalSupportedVersion(await listLocalAgentImages());
+    return NextResponse.json({ exists: version !== null, version });
   } catch {
-    return NextResponse.json({ exists: false });
+    return NextResponse.json({ exists: false, version: null });
   }
 }
 
@@ -81,11 +57,7 @@ export async function POST(request: NextRequest): Promise<Response> {
       const ctrl = controller as ReadableStreamDefaultController & { signal?: AbortSignal };
 
       try {
-        await downloadAgentImage({
-          force: false, // setup: skip if already exists
-          onEvent: send,
-          signal: ctrl.signal,
-        });
+        await downloadAgentImage({ onEvent: send, signal: ctrl.signal });
       } catch (e: unknown) {
         send(JSON.stringify({
           type: 'error',
@@ -94,7 +66,7 @@ export async function POST(request: NextRequest): Promise<Response> {
       }
       controller.close();
     },
-    cancel() { /* downloadAgentImage handles cleanup via signal */ },
+    cancel() { /* downloadAgentImage stops the docker process through the signal */ },
   });
 
   return new Response(stream, {

package/app/components/DashboardToolbar.tsx

@@ -32,7 +32,7 @@ export default function DashboardToolbar({ filter, onChange, agents = ['all'] }:
         className={`agent-btn ${filter.showOnlyActive ? 'active' : ''}`}
         onClick={() => onChange({ showOnlyActive: !filter.showOnlyActive })}
       >
-        solo attivi
+        active only
       </button>
 
       <button

package/app/gateway/PageClient.tsx

@@ -88,7 +88,7 @@ export default function GatewayPageClient() {
   const [modelSearch, setModelSearch] = useState<Record<string, string>>({});
 
   // Balance fetch state (per provider)
-  const [balances, setBalances] = useState<Record<string, { balance: string; label?: string; loading?: boolean; error?: string } | null>>({});
+  const [balances, setBalances] = useState<Record<string, { balance: string; label?: string; loading?: boolean; error?: string; unsupported?: boolean } | null>>({});
   const [fetchingBalance, setFetchingBalance] = useState<Record<string, boolean>>({});
 
   // Accordion state — which provider cards are expanded
@@ -135,6 +135,9 @@ export default function GatewayPageClient() {
             const bJson = await bRes.json();
             if (bRes.ok && bJson.balance) {
               setBalances((prev) => ({ ...prev, [bp]: { balance: bJson.balance, label: bJson.label } }));
+            } else if (bJson.reason === 'no-balance-api') {
+              // Permanent: this provider has no balance API for the account — hide the badge.
+              setBalances((prev) => ({ ...prev, [bp]: { balance: '', unsupported: true } }));
             } else {
               setBalances((prev) => ({ ...prev, [bp]: { balance: '—', error: bJson.error || 'Failed' } }));
             }
@@ -198,6 +201,8 @@ export default function GatewayPageClient() {
       const json = await res.json();
       if (res.ok && json.balance) {
         setBalances((prev) => ({ ...prev, [provider]: { balance: json.balance, label: json.label } }));
+      } else if (json.reason === 'no-balance-api') {
+        setBalances((prev) => ({ ...prev, [provider]: { balance: '', unsupported: true } }));
       } else {
         setBalances((prev) => ({ ...prev, [provider]: { balance: '—', error: json.error || 'Failed' } }));
       }
@@ -519,43 +524,33 @@ export default function GatewayPageClient() {
                 <span style={{ marginLeft: 'auto', fontSize: 11, color: 'var(--text-dim)' }}>
                   {p.models.length} models
                 </span>
-                {/* Balance badge — auto-loaded for supported providers with configured key */}
-                {p.configured && ['deepseek','openrouter','glm'].includes(p.provider) && (
-                  balances[p.provider] && !balances[p.provider]?.error ? (
-                    <span
-                      title={balances[p.provider]?.label || ''}
-                      onClick={(e) => { e.stopPropagation(); fetchBalance(p.provider); }}
-                      style={{
-                        fontSize: 11, fontWeight: 600,
-                        color: 'var(--green)',
-                        background: 'rgba(var(--green-rgb,34,197,94),0.1)',
-                        padding: '2px 8px', borderRadius: 0,
-                        border: '1px solid rgba(var(--green-rgb,34,197,94),0.2)',
-                        cursor: 'pointer',
-                      }}
-                    >
-                      {balances[p.provider]!.balance}
-                    </span>
-                  ) : (
-                    <span
-                      onClick={(e) => { e.stopPropagation(); fetchBalance(p.provider); }}
-                      style={{
-                        fontSize: 11,
-                        color: 'var(--text-dim)',
-                        opacity: 0.5,
-                        cursor: 'pointer',
-                      }}
-                    >
-                      {fetchingBalance[p.provider] ? '…' : '…'}
-                    </span>
-                  )
+                {/* Balance badge — auto-loaded for supported providers with configured key.
+                    Same squared chip in every state: "..." while loading, "—" (dimmed, tooltip) on error.
+                    Hidden entirely when the provider has no balance API for the account (permanent). */}
+                {p.configured && ['deepseek','openrouter','glm'].includes(p.provider) && !balances[p.provider]?.unsupported && (
+                  <button
+                    type="button"
+                    title={balances[p.provider]?.error || balances[p.provider]?.label || ''}
+                    onClick={(e) => { e.stopPropagation(); fetchBalance(p.provider); }}
+                    style={{
+                      fontSize: 11, fontWeight: 600,
+                      color: 'var(--green)',
+                      background: 'rgba(var(--green-rgb,34,197,94),0.1)',
+                      padding: '2px 8px', borderRadius: 0,
+                      border: '1px solid rgba(var(--green-rgb,34,197,94),0.2)',
+                      cursor: 'pointer',
+                      opacity: balances[p.provider]?.error ? 0.5 : 1,
+                    }}
+                  >
+                    {balances[p.provider] && !balances[p.provider]?.error ? balances[p.provider]!.balance : balances[p.provider]?.error ? '—' : '...'}
+                  </button>
                 )}
               </div>
 
               {/* Accordion body — expandable */}
               {isExpanded && (
                 <div style={{ padding: '0 18px 16px 18px', display: 'grid', gap: 14, borderTop: '1px solid var(--border)', paddingTop: 14 }}>
-                  {/* API Key input con show/hide integrato */}
+                  {/* API Key input with an inline show/hide toggle */}
                   <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
                     <PasswordInput
                       value={apiKeyInputs[p.provider] ?? ''}

package/bin/rev4a.js

@@ -41,8 +41,8 @@ const DATA_DIR = join(CONFIG_DIR, 'data');
 const ENV_SOURCE = join(CONFIG_DIR, '.env');
 const ENV_LINK = join(ROOT, '.env');
 const DOCKERFILE = join(ROOT, 'agent-templates', 'base-image', 'Dockerfile');
-const AGENT_IMAGE = 'openclaw-agent-base:latest';
-const AGENT_IMAGE_REGISTRY = 'ghcr.io/flame0510/rev4a/openclaw-agent-base:latest';
+// Supported OpenClaw versions and image repositories, shared with the server.
+const AGENT_VERSIONS = require(join(ROOT, 'lib', 'agent-versions.json'));
 const DOCKER_NETWORK = 'rev4a-network';
 // How long `serve` waits for the Docker daemon before starting without it. Like
 // REV4A_DATA_DIR it is read from the real process environment (a systemd
@@ -204,55 +204,57 @@ function ensureDocker() {
 function ensureAgentImage() {
   if (!hasCmd('docker')) return; // Docker not available — skip, warn later
 
-  // Check if image already exists locally
+  // The newest OpenClaw version this release supports, kept under its version tag.
+  // `:latest` is never used: an agent's version decides its data schema.
+  const version = AGENT_VERSIONS.supported[0].version;
+  const localRef = `${AGENT_VERSIONS.localRepository}:${version}`;
+  const registry = (process.env.REV4A_AGENT_IMAGE_REGISTRY || '').trim() || AGENT_VERSIONS.registryRepository;
+  const remoteRef = `${registry}:${version}`;
+
   try {
-    const r = execSync(
-      `docker image inspect ${AGENT_IMAGE} --format '{{.Id}}'`,
-      { stdio: 'pipe', timeout: 10_000 },
-    );
+    const r = execSync(`docker image inspect ${localRef} --format '{{.Id}}'`, { stdio: 'pipe', timeout: 10_000 });
     if (r.toString().trim()) {
-      log('IMAGE', `Agent base image ${AGENT_IMAGE} already exists`);
+      log('IMAGE', `Agent base image ${localRef} already exists`);
       return;
     }
   } catch {
-    // Image doesn't exist locally
+    // Not downloaded yet
   }
 
-  log('IMAGE', `Pulling agent base image from ${AGENT_IMAGE_REGISTRY}…`);
-
+  log('IMAGE', `Pulling agent base image ${remoteRef}…`);
   try {
-    execSync(`docker pull ${AGENT_IMAGE_REGISTRY}`, {
-      stdio: 'inherit',
-      timeout: 300_000, // 5 min timeout
-    });
-    // Tag locally for Rev4a internal use
-    execSync(`docker tag ${AGENT_IMAGE_REGISTRY} ${AGENT_IMAGE}`, {
-      stdio: 'inherit',
-      timeout: 10_000,
-    });
-    log('IMAGE', `Agent base image pulled and tagged as ${AGENT_IMAGE}`);
+    execSync(`docker pull ${remoteRef}`, { stdio: 'inherit', timeout: 1_800_000 });
+    execSync(`docker tag ${remoteRef} ${localRef}`, { stdio: 'inherit', timeout: 10_000 });
+    try {
+      execSync(`docker rmi ${remoteRef}`, { stdio: 'pipe', timeout: 30_000 }); // untag; the layers stay
+    } catch { /* keeping the registry reference is harmless */ }
+    log('IMAGE', `Agent base image pulled and tagged as ${localRef}`);
+    return;
   } catch {
-    log('IMAGE', `⚠ Pull from registry failed — attempting local build as fallback…`);
-
-    if (!existsSync(DOCKERFILE)) {
-      log('IMAGE', `⚠ Agent base image Dockerfile not found at ${DOCKERFILE}`);
-      log('IMAGE', '  Agent creation will be unavailable until the image is available.');
-      return;
-    }
+    log('IMAGE', '⚠ Pull from registry failed');
+  }
 
-    log('IMAGE', `Building agent base image ${AGENT_IMAGE} (this will take a few minutes)…`);
-    log('IMAGE', '  → pulling node:24-bookworm-slim + installing OpenClaw + tooling');
+  // A local build is only the same image when this Dockerfile builds that version.
+  const dockerfileVersion = existsSync(DOCKERFILE)
+    ? (/^ARG OPENCLAW_VERSION=(\S+)/m.exec(readFileSync(DOCKERFILE, 'utf-8')) || [])[1] || null
+    : null;
+  if (dockerfileVersion !== version) {
+    log('IMAGE', `  The Dockerfile here builds ${dockerfileVersion || 'no version'}, not ${version}: no local build.`);
+    log('IMAGE', '  Agent creation will be unavailable until the image is downloaded from the Agents page.');
+    return;
+  }
 
-    try {
-      execSync(`docker build -t ${AGENT_IMAGE} -f "${DOCKERFILE}" "${join(DOCKERFILE, '..')}"`, {
-        stdio: 'inherit',
-        timeout: 600_000, // 10 min timeout
-      });
-      log('IMAGE', `Agent base image built successfully`);
-    } catch {
-      log('IMAGE', '⚠ Agent base image build failed. Agent creation will be unavailable.');
-      log('IMAGE', '  Pull the image manually: docker pull ' + AGENT_IMAGE_REGISTRY);
-    }
+  log('IMAGE', `Building agent base image ${localRef} (this will take a few minutes)…`);
+  log('IMAGE', '  → pulling node:24-bookworm-slim + installing OpenClaw + tooling');
+  try {
+    execSync(
+      `docker build --build-arg OPENCLAW_VERSION=${version} -t ${localRef} -f "${DOCKERFILE}" "${join(DOCKERFILE, '..')}"`,
+      { stdio: 'inherit', timeout: 3_600_000 },
+    );
+    log('IMAGE', 'Agent base image built successfully');
+  } catch {
+    log('IMAGE', '⚠ Agent base image build failed. Agent creation will be unavailable.');
+    log('IMAGE', `  Pull it manually: docker pull ${remoteRef} && docker tag ${remoteRef} ${localRef}`);
   }
 }
 
@@ -639,7 +641,7 @@ EXAMPLES:
 On first run, rev4a serve automatically:
   • Generates .env (JWT secret + API token)
   • Installs Docker if missing (requires root)
-  • Builds the agent base image (openclaw-agent-base:latest)
+  • Downloads the agent base image for the newest supported OpenClaw version
   • Builds the Next.js app if no build is found
   • Starts Next.js, daemon, and terminal WebSocket as a single process group
   • Cleanly stops all services on Ctrl+C / SIGTERM

package/daemon.js

@@ -668,12 +668,12 @@ function pollSessions() {
   // ── Timeout Detection ────────────────────────────────────────────────────
   // Find sub-agents that were 'working' in the last snapshot but are no longer
   // present in the current output and have been missing for more than 10 minutes.
-  // Questi vengono marcati come 'timeout' nella tabella events.
-  const TIMEOUT_THRESHOLD_MS = 10 * 60 * 1000; // 10 minuti
+  // These are recorded as 'timeout' in the events table.
+  const TIMEOUT_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
   for (const [session_id, snap] of knownSessions) {
     // Only sub-agents (contain 'subagent' in the key)
     if (!session_id.includes('subagent')) continue;
-    // Solo se erano working nell'ultimo poll
+    // Only if they were working in the last poll
     if (snap.status !== 'working') continue;
     // Only if not present in the current poll
     if (currentIds.has(session_id)) continue;
@@ -694,10 +694,10 @@ function pollSessions() {
       data: JSON.stringify({
         missing_for_ms: missingFor,
         last_status: snap.status,
-        message: `Subagente missing dopo ${Math.round(missingFor / 60000)}min senza completare`,
+        message: `Subagent missing for ${Math.round(missingFor / 60000)} min without completing`,
       }),
     });
-    log(`[TIMEOUT] ${session_id} missing da ${Math.round(missingFor / 60000)}min`);
+    log(`[TIMEOUT] ${session_id} missing for ${Math.round(missingFor / 60000)} min`);
 
     // Notify Michele via openclaw message (only if openclaw is available)
     try {
@@ -708,7 +708,7 @@ function pollSessions() {
         'message', 'send',
         '--account', 'ops',
         '--target', '297086793',
-        '--text', `⚠️ Rev4a: agent timeout\n\`${session_id.slice(-36)}\`\nMissing for ${Math.round(missingFor / 60000)} min senza completare.`,
+        '--text', `⚠️ Rev4a: agent timeout\n\`${session_id.slice(-36)}\`\nMissing for ${Math.round(missingFor / 60000)} min without completing.`,
       ], { encoding: 'utf8', timeout: 10_000, killSignal: 'SIGKILL' });
     } catch (e) {
       log(`[TIMEOUT] Telegram notification failed: ${e.message}`);

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -130,6 +130,89 @@ The central container, running the Next.js dashboard + orchestration API.
   a key), `isModelOffered()` (enforced by the proxy and the assistant) and
   `catalogueStatus()`. A failed read of `models.config.json` falls back to the last
   good copy and never deletes overrides.
+- **Agent images and OpenClaw versions.** `lib/agent-versions.json` lists the supported
+  OpenClaw versions, newest first, with the model `input` list for each; the server reads
+  it through `lib/agent-versions.ts`, the `rev4a` CLI with `require`. The provider sync
+  takes each agent's own list (`containerVersionSync()`: image tag, else the entrypoint's
+  `.last-version` file), so a 2026.7.x agent is never sent an `input` value it would
+  reject — one unknown value discards the whole generated catalogue. The previous
+  versions stay listed while agents still run them: that is also what lets a rollback
+  pull the previous image. `lib/agent-images.ts`
+  lists local `openclaw-agent-base:<version>` images through the Docker API, reads an
+  agent's version (image label or tag, else `openclaw --version` in the container, cached
+  per image id), reads the registry tag list over HTTP (cached 10 min), pulls a version
+  and resolves the image a recreate uses. Images are never addressed as `:latest`: create
+  takes the newest supported version downloaded, recreate the agent's own.
+- **Cold backups** are `lib/cold-backup.ts`. The agent is stopped and a detached helper
+  container, `rev4a-backup-<id>` from the agent's own image, archives its volume to
+  `rev4a-backups` as `.partial`, reads it back and renames it; the agent is started
+  again if it was running. The helper and its labels are the job, so no request waits
+  on it and a Rev4a restart does not lose it (`reconcileColdBackups()` in
+  `instrumentation.ts`). While a helper runs, the routes that change the agent answer
+  409 (`isColdBackupRunning()`), and `syncAllAgents()` skips the agent.
+- **Agent updates** are `lib/agent-update.ts`, with their state in the `agent_upgrades`
+  table (`lib/agent-update-state.ts`). An update counts the agent's transcript events per
+  session and its cron jobs, takes a cold pre-update backup, recreates the container on
+  the newer version (`lib/agent-recreate.ts`, argv only, env values outside the process
+  table), waits for `/startupz` to report that version, re-applies Rev4a's config and
+  checks the counts. A rollback restores the pre-update backup on the previous version.
+  Both run inside the Rev4a process; `markInterruptedUpdates()` at startup turns an
+  unfinished one into `interrupted`. `lib/agent-busy.ts` gives the routes one 409 reason
+  for "edit, update, recreate, restore or backup running". After a successful update, `pruneAgentImages()`
+  keeps only images in use plus the newest and previous versions.
+- **Agent recreates** are `lib/agent-recreate.ts`, with their state in the
+  `agent_recreates` table (`lib/agent-recreate-state.ts`): the same-version counterpart
+  of an update. A cold backup, then the container rebuilt on the image the agent already
+  runs, then `/startupz`, then the runtime config. It answers `202` and runs in the
+  background, so a page reload or a Rev4a restart does not lose it; at startup a job
+  still active becomes `interrupted` and the agent is started again — after its backup
+  helper has finished, never while the archive is written. On success the older
+  `prerecreate` archives are pruned to the newest two. The same `recreateAgentContainer()`
+  serves the edit route (`PATCH` → 202, no backup) and the Update action.
+  `agentBusyReason()` (`lib/agent-busy.ts`) covers it for every route that changes an agent.
+- **Host ports** are shared between creation and the edit flow by `lib/agent-ports.ts`
+  (pure: `validatePortInput`, `findAvailablePortBlock`, `portMappingArgs`) and
+  `lib/agent-ports-server.ts` (`getUsedHostPorts()`, the Docker lookup, server-only since
+  client components cannot import `child_process`). One block maps to the container's
+  gateway port 3000 (`3700-3709` → `3700-3709:3000-3009`); both flows produce the same
+  validation messages, and the edit excludes the agent's own ports so its block never
+  conflicts with itself.
+- **Agent edits** are `lib/agent-edit.ts`, with their state in the `agent_edits` table
+  (`lib/agent-edit-state.ts`): the display name (`AGENT_NAME`) and/or the port range are
+  applied by rebuilding the container on the image it already runs — **no backup**, the
+  volume is never touched. Same 202-and-background shape as a restore; the parameters
+  live in the row, so recovery can tell what was being applied. The panel shows a banner
+  and the agent card an `EDITING` chip.
+- **Agent restores** are `lib/agent-restore.ts`, with their state in the `agent_restores`
+  table (`lib/agent-restore-state.ts`): the archive replaces the volume (stop, clear,
+  extract, start), up to 30 minutes. Same 202-and-background shape as a recreate, and the
+  same guarantees — a reload or a Rev4a restart does not lose the job, a second restore
+  is refused, an interrupted one starts the container again. The extract has no
+  percentage (it is a single `tar xzf`); the panel and the agent card show `RESTORING`.
+- **Browser access** to an agent's Control UI goes through `lib/agent-devices.ts`:
+  `openclaw devices list | approve | reject | rename | remove` and
+  `openclaw dashboard --json`, run inside the container with the async `dockerExec`.
+  The gateway token is resolved inside the container (`/root/.agent-token`, then its
+  environment), never passed in argv. Whether approval applies is decided by the
+  OpenClaw version: 9.x answers `/startupz` with JSON and always requires it;
+  2026.7.x follows `gateway.controlUi.dangerouslyDisableDeviceAuth`.
+  `buildInviteLink()` builds the plain token link for someone else; the invite route
+   refuses agents without approval. Every link's token is read inside the container,
+   and its host is the request's `Host` header (`hostnameFromHostHeader()`), never a
+   caller-supplied value.
+- **Telegram DM pairing** lives in `lib/channelManager.ts`. The bot binding is config
+  (`channels.telegram.botToken`/`dmPolicy`); *who* may talk is OpenClaw's pairing
+  store — on 2026.9.3 the SQLite rows in `~/.openclaw/state/openclaw.sqlite`, not the
+  `credentials/*.json` files older releases used. Reading and revoking go through the
+  store's own functions (`readChannelAllowFromStoreSync`,
+  `removeChannelAllowFromStoreEntry`): no CLI, RPC or documented export exposes them,
+  so a small script run inside the container finds OpenClaw's `pairing-store` module by
+  glob and its functions by name (the names survive minification; no hash or minified
+  symbol is hardcoded) and calls them, which uses the same state transaction the CLI
+  does. If a release stops exposing the store, the revoke fails with a message pointing
+  at `/allowlist remove` — it never reports success without changing anything. Approving
+  a pairing request (`openclaw pairing approve`) also bootstraps
+  `commands.ownerAllowFrom` for the first owner (OpenClaw's own behaviour).
 
 **Running commands inside containers** (`lib/docker-exec.ts`):
 
@@ -149,6 +232,7 @@ the rules for anything you touch, not as a description of the whole tree:
   container cannot blank an entire page. Callers: `app/api/skills/route.js`,
   `app/api/agents/models-summary/route.ts`,
   `app/api/agents/channels-summary/route.ts`,
+  `app/api/agents/devices-summary/route.ts`,
   `lib/openclaw-cron.ts`, `app/api/credentials/detect/route.ts`,
   `lib/credentials/delivery.ts`.
 - **Never interpolate a secret into a command string.** Pass it through the `env`
@@ -195,7 +279,9 @@ agent-{name}-data (named vol)         → /root                             (rw,
 All shared volumes are defined centrally in `lib/agent-setup.ts`
 (`REV4A_VOLUMES`) and used by both the create and recreate API routes.
 The `bootstrap-extra-files` hook is pre-wired in the base image Dockerfile
-and guaranteed at runtime by `applyRuntimeConfig()`.
+and guaranteed at runtime by `applyRuntimeConfig()`, which also applies the Control
+UI browser-origin policy (`withControlUiPolicy()`): the Host-header fallback on, an
+`allowedOrigins: ["*"]` list and the retired `dangerouslyDisableDeviceAuth` removed.
 
 **Injected environment variables:**
 ```
@@ -337,7 +423,7 @@ Rev4a Dashboard UI
 POST   /api/agents/create          Create new container agent (template + model)
 DELETE /api/agents/{id}            Destructive: remove container + volume + backups
 POST   /api/agents/{id}/restart    Restart container
-POST   /api/agents/{id}/recreate   Rebuild from latest image (volume preserved)
+POST   /api/agents/{id}/recreate   Rebuild on the agent's own version (volume preserved)
 GET    /api/agents                 List all agents (Docker containers with AGENT_ID)
 ```
 
@@ -422,7 +508,7 @@ networks:
 - Agent → Rev4a Gateway: `http://rev4a-control:3721`
 - Agent → Rev4a Dashboard: `http://rev4a-control:3720`
 - Rev4a → Agent (healthcheck): `http://agent-{id}:3000`
-- Traefik → Agent (external access): via Docker labels
+- Browser → Agent Control UI: the container's published host port, `http://<host>:<port>`. Rev4a sets no reverse-proxy labels
 
 ---
 
@@ -573,10 +659,10 @@ ALTER TABLE sessions ADD COLUMN ended_at INTEGER;
    - Distributed: per-agent memory, Rev4a indexes centrally — more resilient
    - Recommendation: distributed with central index
 
-3. **Traefik routing: should agents be externally reachable?**
-   - If yes: per-agent Traefik labels managed by Rev4a
-   - If no: internal Docker network only
-   - Recommendation: no by default, yes only for agents serving APIs/UI
+3. **External access to agents** — decided: each agent's Control UI is published on a
+   host port, and Rev4a sets no reverse-proxy labels. HTTPS or a domain means the
+   operator's own proxy in front of that port. A first-class integration, with routing
+   labels applied at `docker run`, would be a separate feature.
 
 4. **Hermes and other frameworks: dashboard integration?**
    - Hermes has its own session format
@@ -628,6 +714,6 @@ for the full rationale.
 | Memory | Per-agent SQLite + central index | New |
 | Config | Generated YAML/JSON | New |
 | Credential stores | SQLite + JSON | credentials.db for service tokens, provider-keys.json for provider API keys. Neither is encrypted |
-| Reverse proxy | Traefik | Already in use |
+| Reverse proxy | Optional, operator's choice | Rev4a sets no reverse-proxy labels on agent containers |
 | Monitoring | Rev4a daemon (extended) | Evolution of current daemon |
 | Version control | Git + GitHub | `github.com/Flame0510/rev4a.git` |

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 ## Layering
 
@@ -42,6 +42,13 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
 | `PasswordInput` | `PasswordInput.tsx` | Password input with inline show/hide toggle (`<button type="button">` with `aria-label`). |
+| `UpdateSection` | `app/agents/UpdateSection.tsx` | OPENCLAW VERSION section of the agent detail panel: the version the agent runs, **Update to <version>** when a newer supported version is downloaded (confirm modal, disabled while the agent is stopped), the running update's steps with backup progress, the outcome, and **Roll back to <version>** after an update. Polls `/api/agents/[id]/update` every 2 s while an update or rollback runs; one action at a time (keyed busy state). |
+| `BackupSection` | inline in `app/agents/PageClient.tsx` | BACKUP section of the agent detail panel, on the cold backup and the restore. **Backup Now** starts `POST /api/agents/[id]/cold-backup`; while the job runs a banner shows the file and its live percent with **Cancel** (`DELETE /cold-backup`). **Restore** (after a confirm) starts `POST /restore` and a banner shows `Restoring <file>…` (no percent: the extract is a single `tar xzf`, and there is no Cancel). Both sections poll their `GET` every 2 s while running, and on mount pick up a job that is already running — a backup lives in a Docker helper, a restore in `agent_restores`, so reloading the page or navigating away never loses them nor allows a second one (the server answers 409 anyway). Delete per row; all actions disabled while one runs; keyed busy state `{ kind, file }` so only the row in action shows the spinner. On the agent list, an activity Badge (fed by `/api/agents/activity-summary`, polled at 2 s only while something runs, otherwise riding the 15 s list poll) reads `BACKUP nn%`, `RESTORING`, `RECREATING`, `EDITING` or `UPDATING`. |
+| `RecreateSection` | inline in `app/agents/PageClient.tsx` | RECREATE section of the agent detail panel. **Recreate Container** starts `POST /api/agents/[id]/recreate` (202) after a confirm; a banner then shows the phase — *Backing up … nn%* while the cold backup runs, *Recreating container…* while the container is rebuilt and the gateway starts. The section polls `GET /recreate` every 2 s, and on mount picks up a recreate that is already running, so a reload or navigation never loses it; it refetches the agent once the job reports `done`. |
+| `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and shows the download in progress and its completion. Downloading changes no agent. |
+| `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
+| `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). Polls pairings every 5 s while open; one keyed busy state per action. |
+| `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. |
 | `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
 | `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |
 | `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |