@flame0510/project-aether 1.3.0 → 1.4.0

package/docs/dev/DATABASE.md

@@ -107,6 +107,102 @@ CREATE INDEX idx_metrics_ts ON system_metrics(ts);
 
 Rows older than 24 h are pruned automatically by the daemon.
 
+### `agent_upgrades` — agent updates and rollbacks
+
+```sql
+CREATE TABLE agent_upgrades (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_id      TEXT NOT NULL,
+  status        TEXT NOT NULL,   -- pending, backing_up, migrating, verifying, done, failed,
+                                 -- interrupted, rolling_back, rolled_back, rollback_failed
+  from_version  TEXT,
+  to_version    TEXT NOT NULL,
+  backup_file   TEXT,            -- pre-update cold backup in the rev4a-backups volume
+  baseline_json TEXT,            -- transcript events per session and cron job names before
+  verify_json   TEXT,            -- the comparison after the update
+  error         TEXT,
+  started_at    INTEGER NOT NULL,
+  updated_at    INTEGER NOT NULL,
+  finished_at   INTEGER
+);
+
+CREATE INDEX idx_agent_upgrades_agent ON agent_upgrades(agent_id, started_at);
+```
+
+One row per update attempt (`lib/agent-update.ts`); a rollback moves the same row on to
+`rolling_back`. Created by `lib/db-bootstrap.mjs`. At startup, rows still in an active
+status are marked `interrupted`. Rows are never pruned.
+
+### `agent_recreates` — agent recreates
+
+```sql
+CREATE TABLE agent_recreates (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_id    TEXT NOT NULL,
+  status      TEXT NOT NULL,   -- backing_up, recreating, done, failed, interrupted
+  image       TEXT,            -- the image the container is rebuilt on
+  backup_file TEXT,            -- pre-recreate cold backup in the rev4a-backups volume
+  error       TEXT,
+  started_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL,
+  finished_at INTEGER
+);
+
+CREATE INDEX idx_agent_recreates_agent ON agent_recreates(agent_id, started_at);
+```
+
+One row per recreate attempt (`lib/agent-recreate.ts`), the same-version counterpart of
+an update: a cold backup, the container rebuilt, the gateway waited for. It is written
+so a page reload or a Rev4a restart mid-way is visible instead of lost
+(`GET /api/agents/[id]/recreate`). At startup, rows still in an active status become
+`interrupted` and the agent is started again once its backup helper has finished. Rows
+are never pruned.
+
+### `agent_restores` — agent restores
+
+```sql
+CREATE TABLE agent_restores (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_id    TEXT NOT NULL,
+  status      TEXT NOT NULL,   -- restoring, done, failed, interrupted
+  file        TEXT,            -- the archive being applied, in the rev4a-backups volume
+  error       TEXT,
+  started_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL,
+  finished_at INTEGER
+);
+
+CREATE INDEX idx_agent_restores_agent ON agent_restores(agent_id, started_at);
+```
+
+One row per restore attempt (`lib/agent-restore.ts`): the volume is replaced from the
+archive. Persisted for the same reason as a recreate (`GET /api/agents/[id]/restore`),
+and at startup an active row becomes `interrupted` with the container started again.
+Rows are never pruned.
+
+### `agent_edits` — agent renames and port changes
+
+```sql
+CREATE TABLE agent_edits (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_id     TEXT NOT NULL,
+  status       TEXT NOT NULL,   -- rebuilding, done, failed, interrupted
+  display_name TEXT,            -- the name being applied, when it was a rename
+  port_range   TEXT,            -- the range being applied, when it was a port change
+  error        TEXT,
+  started_at   INTEGER NOT NULL,
+  updated_at   INTEGER NOT NULL,
+  finished_at  INTEGER
+);
+
+CREATE INDEX idx_agent_edits_agent ON agent_edits(agent_id, started_at);
+```
+
+One row per edit attempt (`lib/agent-edit.ts`): the container is rebuilt with the new
+name/ports, no backup involved. Persisted for the same reason as the others
+(`GET /api/agents/[id]`); at startup an active row becomes `interrupted` with the
+container started again. Rows are never pruned.
+
 ## Useful Queries
 
 ```sql

package/docs/dev/GATEWAY.md

@@ -1,6 +1,6 @@
 # Gateway Page
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 The Gateway page (`/gateway`) is the control panel for provider configuration:
 API keys and the model catalogue offered to every agent container. It does not
@@ -170,7 +170,10 @@ Saving calls `PUT /api/gateway/agent`, which writes the container's
   container's existing list untouched, `[]` clears it. The Model panel is the only
   UI that sets them; the create wizard does not
 - **no restart** — `agents` is in OpenClaw's hot-reload column, so the write
-  applies on the agent's next turn
+  applies on the agent's next turn. Exception on OpenClaw 2026.7.1-2: a Telegram
+  channel keeps the configuration it had when it started, so Telegram replies stay on
+  the old model until the container is restarted. The Control UI picks the change up
+  at once. OpenClaw 9.x reads the configuration per message
 
 The agent list shows each agent's current model as a chip, fed by
 `GET /api/agents/models-summary`. The red states are split by remedy, because they
@@ -218,6 +221,9 @@ Two failures, handled differently on purpose:
 
 - **Docker unreachable** — refused before anything is written: `503`, nothing saved,
   the checkbox does not move, so the checkboxes never disagree with every agent.
+- **An agent under a cold backup** is skipped: writing its config while tar reads the
+  volume would put a half-changed file in the archive. It is listed in `sync.failed`
+  with the reason; the next sync catches it up.
 - **Some containers fail once Docker answers** — the toggle stands and `sync.failed`
   lists them; the page shows it in amber, and an agent whose primary is affected shows
   `OUT OF SYNC`. Rolling
@@ -359,18 +365,27 @@ Restart the Rev4a server (via systemd).
 4. **No gateway restart after model sync** — The sync module writes `models.providers`
    to the file directly without restarting the gateway.
 
+   The model `input` list follows each agent's OpenClaw version
+   (`lib/agent-versions.json`, resolved by `containerVersionSync()`): the newest release
+   accepts `text | image | audio | video`, while `2026.7.1-2` accepts only `text | image`,
+   and one unknown value makes it discard the whole generated catalogue
+   (`model catalog load issue`). That is why the previous version stays in the table
+   while agents still run it.
+
 5. **Entrypoint does not generate openclaw.json** — The entrypoint resolves the
    auth token and starts the gateway with `--allow-unconfigured`; OpenClaw
    generates its own default config on first boot. All post-creation config
    (controlUi, model refs, providers) is written by the create route
    (`POST /api/agents/create`) after the gateway is fully ready.
-   The entrypoint also runs `openclaw doctor --non-interactive` **before** the
-   gateway, but only when the OpenClaw version changed since last boot
-   (tracked in `/root/.openclaw/.last-version`) — safe migrations only, no restart.
+   Before the gateway starts, the entrypoint runs `openclaw doctor --fix --non-interactive`
+   when the OpenClaw version changed since the last successful run (tracked in
+   `/root/.openclaw/.last-version`), and fills in the image defaults that are missing:
+   plugin load path, web search provider, heartbeat off. See
+   [REV4A.md](../REV4A.md#agent-templates).
 
 6. **Model ref written after gateway readiness** — When the wizard creates an agent,
    the create route waits for the gateway to finish starting (`waitForGatewayReady`), then writes
-   `agents.defaults.model.primary` + fallbacks and `gateway.controlUi.allowedOrigins`,
+   `agents.defaults.model.primary` + fallbacks and the Control UI origin policy (`gateway.controlUi`),
    then writes the provider block from `buildRev4aProviderConfig()` with `openclaw config patch --stdin`. The Gateway sync (`PUT /api/gateway/provider`)
    never touches model references — only `models.providers` is synced.
 

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-13
+> **Last updated:** 2026-09-15
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -90,9 +90,11 @@ Agents page.
 
 **Update frequency:** polled every 2 seconds, continuously
 
-`GET /api/agents/image-status` compares the local image digest with the remote
-registry digest on ghcr.io. The banner polls it every 2 seconds for as long as the
-page is open, not only while something is running.
+`GET /api/agents/image-status` lists the supported OpenClaw versions downloaded and
+compares them with the versions the registry publishes. The registry list is refreshed
+at most every 10 minutes, so a newly published version can take that long to appear.
+The banner polls the endpoint every 2 seconds for as long as the page is open, not only
+while something is running.
 
 The operation the banner triggers is a **`docker pull`**, not a build. While it
 runs the banner shows an indeterminate animated bar: there is no percentage, no

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -18,6 +18,9 @@ A small inline label component used for status indicators and channel chips. Six
 ## Backup (Agent)
 A compressed archive (`.tar.gz`) of an agent's persistent volume (`/root/`). Backups exclude the npm cache to keep sizes small (~1.5 MB). Stored in the `rev4a-backups` Docker volume. Used for restore operations and auto-created before each recreate.
 
+## Browser Access
+Which browsers may open an agent's Control UI. On OpenClaw 9.x every new browser must be approved once; the approval is remembered per browser. Managed in the "BROWSER ACCESS" section of the agent detail panel: approve or reject waiting browsers, rename or revoke approved ones. The Open button uses a one-time link that skips the approval. The Invite link button gives a link for someone else: their browser still waits for approval.
+
 ## Container
 A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers, including infrastructure ones such as databases and reverse proxies, with a web terminal link. It shows no CPU or memory metrics.
 
@@ -73,11 +76,14 @@ Rev4a's built-in proxy that gives all agents unified access to configured LLM pr
 The AI concierge embedded in Rev4a. Click the floating chat button (bottom-right) on any page to ask questions about the dashboard features and navigation.
 
 ## Recreate (Agent)
-Rebuild an agent container from the latest `openclaw-agent-base:latest` image while preserving the persistent volume. Auto-backups the volume first — if the backup fails, the recreate is aborted. This is how agents pick up OpenClaw image updates.
+Rebuild an agent container on its own OpenClaw version while preserving the persistent volume. Auto-backups the volume first — if the backup fails, the recreate is aborted. A recreate never changes the OpenClaw version; moving to a newer version is a separate update.
 
 ## Restore (Agent)
 Replace an agent's persistent volume with a previously created backup. The container is stopped, the volume content is fully replaced, then the container is restarted.
 
+## Rollback (Agent)
+Undo an agent's latest OpenClaw update: the backup taken just before the update is put back and the agent starts again on its previous version. Anything the agent did after the update is lost. Offered in the agent's OPENCLAW VERSION section while that backup exists.
+
 ## Session
 One instance of an agent doing work. Tracks: start/end time, tokens used, cost, model, status, and task description. A session starts when an agent receives a task and ends when it completes or fails.
 
@@ -113,7 +119,10 @@ A capability available to agents: running shell commands, reading files, searchi
 A record of an agent using a tool during a session. Useful for auditing what an agent actually did. Shown in the Session Drawer.
 
 ## Traefik
-Optional reverse proxy for routing web traffic to agent containers. If configured, an agent gets a public URL. Rev4a itself runs on port 3740 and does not require Traefik.
+Optional reverse proxy an operator can put in front of the Rev4a dashboard or of an agent's port. Rev4a does not configure it and sets no routing labels on agents: an agent's Control UI is reached on its published port. Rev4a itself runs on port 3740 and does not require Traefik.
+
+## Update (Agent)
+Move one agent to a newer OpenClaw version downloaded on the Agents page, from its OPENCLAW VERSION section. The agent goes offline for a few minutes: it is backed up while stopped, started on the new version (which converts its data), and checked for missing conversation history or cron jobs. Undone with Rollback.
 
 ## Vault
 Rev4a's store for third-party service tokens (GitHub, Trello, Vercel, Supabase, Notion). Provider API keys live separately in `provider-keys.json`, managed from the Gateway page. Supports reveal (written to an audit table no route or view reads), sync to and from containers, and live detection of which credentials are actually installed. Secrets are stored unencrypted.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-13
+> **Last updated:** 2026-09-15
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
@@ -34,10 +34,23 @@ Manage Docker containers running OpenClaw agents. See which agents are running,
 
 The agent list also shows a compact TG chip next to each agent name (green = connected, hidden if not configured).
 
-The Agents page includes a banner for the **agent base image**
-(`openclaw-agent-base:latest`). It is hidden when the image is present and current.
-When the image is missing or outdated it appears with one button, labelled
-**Download Image** or **Download Update**.
+**Browser access:** on agents running OpenClaw 9.x, every new browser has to be approved once before the agent's Control UI connects. The detail panel's "BROWSER ACCESS" section lists browsers waiting for approval, with Approve and Reject, and the browsers already approved, with Rename and Revoke. A yellow "BROWSER WAITING" chip on the agent card says a request is pending. The **Open** button tries a one-time link that lets the browser in without any approval; if the agent cannot issue one (agents still on OpenClaw 2026.7.x) it opens the normal link, which on those agents needs no approval anyway. To let someone else in, **Invite link** gives a link to send them: their browser appears under waiting for approval, and nothing opens until you approve it. The link contains the token all agents share; changing the agents token cancels every link already sent.
+
+The Agents page includes a banner for the **agent base image**, which is kept per
+OpenClaw version. It is hidden when a supported version is downloaded and nothing newer
+is published. When no image is downloaded it offers **Download Image**; when a newer
+supported OpenClaw version is published it says so and offers **Download <version>**.
+Downloading changes no agent: new agents are created on the newest version downloaded,
+existing agents keep their version (a recreate never changes it), and their card shows
+**UPDATE AVAILABLE**.
+
+**Updating an agent:** the detail panel's "OPENCLAW VERSION" section shows the version the
+agent runs and, when a newer one is downloaded, **Update to <version>**. The update takes
+the agent offline for a few minutes: it backs the agent up while stopped, starts it on the
+new version (which converts its data), and checks that no conversation history or cron job
+went missing. Afterwards **Roll back to <version>** puts back the backup taken just before
+the update, on the old version; anything the agent did after the update is lost. The agent
+must be running to start an update.
 
 That button runs a `docker pull` from the registry. It is a download, not a build.
 While it runs the banner shows an indeterminate animated bar with no percentage and

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -48,13 +48,17 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How do I sync credentials to an agent?"
 - "How do I back up an agent?"
 - "How do I restore an agent from a backup?"
-- "How do I recreate an agent with the latest image?"
+- "How do I rebuild (recreate) an agent's container?"
 - "How do I delete an agent?"
 - "How do I restart the Rev4a server?"
 - "How do I change environment variables?"
 - "How do I add a cost override?" — There is no screen for it. The endpoint exists, but nothing in the dashboard calls it.
 - "How do I see the session lineage?"
 - "How do I log in to an agent's control UI?"
+- "Why does the Control UI ask me to approve this browser?"
+- "How do I approve or revoke a browser for an agent?"
+- "How do I give someone else access to an agent's Control UI?"
+- "How do I update an agent to a newer OpenClaw version, and how do I go back?"
 - "How do I register a new provider via OAuth?" — The endpoint exists but no page uses it. Providers are added by pasting an API key on the Gateway page.
 - "How do I manage agent model fallbacks?"
 - "How do I connect an agent to Telegram?"

package/instrumentation.ts

@@ -22,5 +22,48 @@ export async function register() {
       // Best-effort — don't block startup if sync fails
       console.warn('[rev4a] Failed to sync agents on startup');
     }
+    // Updates cut off by the restart: no job runs in a fresh process, so any update
+    // still marked active becomes `interrupted` and waits for the operator.
+    try {
+      const { recoverInterruptedUpdates } = await import('./lib/agent-update');
+      const interrupted = await recoverInterruptedUpdates();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent update(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent updates on startup');
+    }
+    // Recreates cut off by the restart: the row becomes `interrupted` and an agent the
+    // backup had stopped is started again, so nothing stays down.
+    try {
+      const { recoverInterruptedRecreates } = await import('./lib/agent-recreate');
+      const interrupted = await recoverInterruptedRecreates();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent recreate(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent recreates on startup');
+    }
+    // Restores cut off by the restart: same treatment — the row becomes `interrupted`
+    // and a container left stopped is started again.
+    try {
+      const { recoverInterruptedRestores } = await import('./lib/agent-restore');
+      const interrupted = await recoverInterruptedRestores();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent restore(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent restores on startup');
+    }
+    // Edits cut off by the restart: same treatment.
+    try {
+      const { recoverInterruptedEdits } = await import('./lib/agent-edit');
+      const interrupted = await recoverInterruptedEdits();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent edit(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent edits on startup');
+    }
+    // Cold backups whose helper outlived a Rev4a restart: finish the exited ones (the
+    // agent is started again if it was running) and keep watching the rest.
+    try {
+      const { reconcileColdBackups } = await import('./lib/cold-backup');
+      await reconcileColdBackups();
+    } catch {
+      console.warn('[rev4a] Could not reconcile cold backups on startup');
+    }
   }
 }

package/lib/agent-busy.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether an agent is in the middle of a long operation that nothing else may touch:
+ * an edit (lib/agent-edit.ts), a restore (lib/agent-restore.ts), a recreate
+ * (lib/agent-recreate.ts), an update (lib/agent-update.ts) or a cold backup
+ * (lib/cold-backup.ts). The routes that change an agent answer 409 with this reason.
+ */
+import { isColdBackupRunning } from '@/lib/cold-backup';
+import { isUpdateActive } from '@/lib/agent-update-state';
+import { isRecreateActive } from '@/lib/agent-recreate-state';
+import { isRestoreActive } from '@/lib/agent-restore-state';
+import { isEditActive } from '@/lib/agent-edit-state';
+
+export async function agentBusyReason(agentId: string): Promise<string | null> {
+  if (isUpdateActive(agentId)) return 'An update of this agent is running';
+  if (isRecreateActive(agentId)) return 'A recreate of this agent is running';
+  if (isRestoreActive(agentId)) return 'A restore of this agent is running';
+  if (isEditActive(agentId)) return 'An edit of this agent is running';
+  if (await isColdBackupRunning(agentId)) return 'A backup of this agent is running';
+  return null;
+}
+