@flame0510/project-aether 1.2.0 → 1.4.0

package/lib/container-file.ts

@@ -0,0 +1,27 @@
+/**
+ * Reading one file out of an agent container, running or not.
+ *
+ * `docker exec` cannot reach a stopped or paused container; `docker cp` can, and
+ * streams the file as a tar archive. Used by the config sync, which also writes
+ * back through `docker cp`, and by the model summary behind the agent cards.
+ */
+
+/** The single regular file in a `docker cp … -` tar stream: its bytes and mode. */
+export function singleFileFromTar(tar: Buffer): { body: Buffer; mode: number } {
+  if (tar.length < 512) throw new Error('docker cp returned an empty archive');
+  const header = tar.subarray(0, 512);
+  const field = (start: number, len: number) => {
+    const text = header.subarray(start, start + len).toString('ascii');
+    const nul = text.indexOf('\0');
+    return (nul === -1 ? text : text.slice(0, nul)).trim();
+  };
+  const type = field(156, 1);
+  // '0' (or NUL on old writers) is a regular file. Anything else — a pax header,
+  // a directory — is not the shape expected, and guessing past it could mean
+  // writing a config that was never read.
+  if (type !== '0' && type !== '') throw new Error(`docker cp returned a non-file entry (type ${type})`);
+  const size = parseInt(field(124, 12), 8);
+  if (!Number.isFinite(size) || tar.length < 512 + size) throw new Error('docker cp returned a truncated archive');
+  const mode = parseInt(field(100, 8), 8);
+  return { body: tar.subarray(512, 512 + size), mode: Number.isFinite(mode) ? mode & 0o777 : 0o600 };
+}

package/lib/credentials/delivery.ts

@@ -149,7 +149,7 @@ async function deliverGithub(container: string, secret: Record<string, string>):
   if (!token) throw new Error('Missing token');
 
   // Require gh CLI preinstalled in the agent image
-  if (!await cliPresent(container, 'gh')) throw new Error('gh CLI not installed in this container. Rebuild the base image: docker build -t openclaw-agent-base:latest agent-templates/base-image/');
+  if (!await cliPresent(container, 'gh')) throw new Error('gh CLI not installed in this container. Download the current agent image from the Agents page and update this agent.');
 
   await containerExec(
     container,
@@ -162,7 +162,7 @@ async function deliverVercel(container: string, secret: Record<string, string>):
   if (!token) throw new Error('Missing token');
 
   // Require vercel CLI preinstalled in the agent image
-  if (!await cliPresent(container, 'vercel')) throw new Error('vercel CLI not installed in this container. Rebuild the base image: docker build -t openclaw-agent-base:latest agent-templates/base-image/');
+  if (!await cliPresent(container, 'vercel')) throw new Error('vercel CLI not installed in this container. Download the current agent image from the Agents page and update this agent.');
 
   // Validate token and discover team scope via Node fetch (no curl/exec)
   const scope = await discoverVercelScope(token);
@@ -191,7 +191,7 @@ async function deliverSupabase(container: string, secret: Record<string, string>
   if (!accessToken || !accessToken.trim()) throw new Error('Missing Supabase access token');
 
   // Check supabase CLI is available (installed globally in the image)
-  if (!await cliPresent(container, 'supabase')) throw new Error('supabase CLI not installed in this container. Rebuild the base image: docker build -t openclaw-agent-base:latest agent-templates/base-image/');
+  if (!await cliPresent(container, 'supabase')) throw new Error('supabase CLI not installed in this container. Download the current agent image from the Agents page and update this agent.');
 
   // Login with access token — grants access to all projects on the account
   // supabase login --token supports non-interactive auth

package/lib/db-bootstrap.mjs

@@ -139,6 +139,82 @@ export function initializeRev4aDb(dbPath) {
     ['model', 'TEXT'],
   ]);
 
+  // Agent updates: one row per attempt to move an agent to a newer OpenClaw version
+  // (lib/agent-update.ts). It answers, after any restart, where an update stopped and
+  // which archive restores the agent.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_upgrades (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      from_version TEXT,
+      to_version TEXT NOT NULL,
+      backup_file TEXT,
+      baseline_json TEXT,
+      verify_json TEXT,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      finished_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_upgrades_agent ON agent_upgrades(agent_id, started_at);
+  `);
+
+  // Recreate jobs (lib/agent-recreate.ts): same shape as an update minus the
+  // migration — a cold backup, the container rebuilt on the same version, the
+  // gateway started again. Persisted so a reload or a Rev4a restart mid-way is
+  // visible instead of lost, and so an interrupted job is marked at startup.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_recreates (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      image TEXT,
+      backup_file TEXT,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      finished_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_recreates_agent ON agent_recreates(agent_id, started_at);
+  `);
+
+
+  // Restore jobs (lib/agent-restore.ts): the volume is replaced from an archive, so the
+  // job is visible and survives a reload or a Rev4a restart like a recreate does.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_restores (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      file TEXT,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      finished_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_restores_agent ON agent_restores(agent_id, started_at);
+  `);
+
+
+  // Edit jobs (lib/agent-edit.ts): the container is rebuilt with a new display name
+  // and/or port range, no volume backup involved. Persisted like the others so a
+  // reload or a Rev4a restart never loses track of it.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_edits (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      display_name TEXT,
+      port_range TEXT,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      finished_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_edits_agent ON agent_edits(agent_id, started_at);
+  `);
+
 
   db.close();
 }

package/lib/docker-utils.ts

@@ -19,9 +19,9 @@
  *     user's browser open", not "what is this machine's WAN address". Those
  *     differ behind NAT, behind a reverse proxy, and over a tunnel.
  *
- * Agent URLs are now composed in the browser from the port returned by the API
- * plus `window.location.hostname` — a hostname already proven to reach this
- * server, since the dashboard is being served over it.
+ * Agent Control UI links are now built from the host the request reached Rev4a on
+ * (`hostnameFromHostHeader()` in `lib/agent-devices.ts`) — a hostname already
+ * proven to reach this server, since the dashboard is being served over it.
  */
 
 /**

package/lib/model-catalogue.ts

@@ -2,14 +2,13 @@
  * Model catalogue — bundle-first + user-overrides.
  *
  * Reads the bundled models.config.json from the npm package and applies
- * user toggles from REV4A_DATA/model-overrides.json.
- *
- * Imported by both provider/route.ts and gateway/sync.ts — shared logic,
- * avoids circular dependencies.
+ * user toggles from REV4A_DATA/model-overrides.json. The only module that reads
+ * either file: routes, pages and the sync all go through it.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { REV4A_DATA } from '@/lib/rev4a-paths';
+import { readProviderKeys } from '@/app/api/gateway/provider/keys';
 
 /* ------------------------------------------------------------------ */
 /*  Types                                                              */
@@ -21,6 +20,8 @@ export interface ModelConfigEntry {
   provider: string;
   enabled: boolean;
   modality?: string;
+  /** Upstream has retired this id. It still answers, but is redirected. */
+  deprecated?: boolean;
 }
 
 /* ------------------------------------------------------------------ */
@@ -45,21 +46,61 @@ function resolveBundledPath(): string {
 /*  Loaders                                                             */
 /* ------------------------------------------------------------------ */
 
+/** Last catalogue read successfully by this process. */
+let lastGoodBundle: ModelConfigEntry[] | null = null;
+
+/** How the most recent read of models.config.json went. */
+let bundleStatus: 'ok' | 'stale' | 'unavailable' = 'ok';
+
+/**
+ * Where the last catalogue read left us:
+ * - `ok`          the file was read and parsed
+ * - `stale`       the read failed; this process's last good copy was used
+ * - `unavailable` the read failed with no earlier copy, so the catalogue is empty
+ */
+export function bundledCatalogueStatus(): 'ok' | 'stale' | 'unavailable' {
+  return bundleStatus;
+}
+
+/**
+ * The bundled catalogue.
+ *
+ * A failed read must not look like an empty catalogue. It used to: this returned
+ * `[]`, the loader then treated every user override as an orphan and deleted them
+ * all from disk, the sync pushed an empty model list into every agent, and the
+ * proxy refused every request. One unlucky read — the pricing script rewriting the
+ * file in place, a malformed release — was enough. A failed read now falls back to
+ * the last good copy and reports it through `bundledCatalogueStatus()`.
+ */
 function loadBundledModels(): ModelConfigEntry[] {
   try {
     const raw = fs.readFileSync(resolveBundledPath(), 'utf-8');
     const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed.models)) {
-      return parsed.models.map((m: Record<string, unknown>) => ({
-        id: String(m.id ?? ''),
-        name: String(m.name ?? ''),
-        provider: String(m.provider ?? ''),
-        enabled: Boolean(m.enabled),
-        modality: typeof m.modality === 'string' ? m.modality : undefined,
-      }));
+    if (!Array.isArray(parsed.models) || parsed.models.length === 0) {
+      throw new Error('no models array');
     }
-  } catch { /* fall through */ }
-  return [];
+    const models: ModelConfigEntry[] = parsed.models.map((m: Record<string, unknown>) => ({
+      id: String(m.id ?? ''),
+      name: String(m.name ?? ''),
+      provider: String(m.provider ?? ''),
+      enabled: Boolean(m.enabled),
+      modality: typeof m.modality === 'string' ? m.modality : undefined,
+      deprecated: m.deprecated === true ? true : undefined,
+    }));
+    lastGoodBundle = models;
+    bundleStatus = 'ok';
+    return models;
+  } catch (e) {
+    const why = (e as Error).message;
+    if (lastGoodBundle) {
+      if (bundleStatus !== 'stale') console.warn(`[model-catalogue] models.config.json unreadable, using the last good copy: ${why}`);
+      bundleStatus = 'stale';
+      return lastGoodBundle;
+    }
+    if (bundleStatus !== 'unavailable') console.error(`[model-catalogue] models.config.json unreadable and no earlier copy: ${why}`);
+    bundleStatus = 'unavailable';
+    return [];
+  }
 }
 
 export function loadOverrides(): Record<string, boolean> {
@@ -90,23 +131,14 @@ export function writeOverrides(overrides: Record<string, boolean>): void {
  * 1. Read models.config.json from the npm package (bundle).
  * 2. Apply user overrides (enabled/disabled toggles).
  *
- * The bundle is read-only at runtime. User choices live in model-overrides.json.
+ * Read-only. Overrides for ids the bundle no longer has are ignored here and
+ * pruned only by `toggleModelOverride`, against a fresh read: this runs on every
+ * proxy request, and a read path that deletes user settings is one failed read
+ * away from deleting all of them.
  */
 export function loadModelsConfig(): ModelConfigEntry[] {
   const bundled = loadBundledModels();
   const overrides = loadOverrides();
-
-  // Clean up orphan overrides (models removed from bundle)
-  const bundledIds = new Set(bundled.map((m) => m.id));
-  let dirty = false;
-  for (const id of Object.keys(overrides)) {
-    if (!bundledIds.has(id)) {
-      delete overrides[id];
-      dirty = true;
-    }
-  }
-  if (dirty) writeOverrides(overrides);
-
   return bundled.map((m) => ({
     ...m,
     enabled: Object.prototype.hasOwnProperty.call(overrides, m.id) ? overrides[m.id] : m.enabled,
@@ -126,6 +158,87 @@ export function toggleModelOverride(modelId: string, enabled: boolean): boolean
   } else {
     overrides[modelId] = enabled;
   }
+
+  // Drop overrides for models the catalogue no longer has — but only against a
+  // catalogue read just now. Against a stale or missing copy every override
+  // would look orphaned.
+  if (bundledCatalogueStatus() === 'ok') {
+    const ids = new Set(bundled.map((m) => m.id));
+    for (const id of Object.keys(overrides)) if (!ids.has(id)) delete overrides[id];
+  }
+
   writeOverrides(overrides);
   return true;
 }
+
+/**
+ * The models this deployment actually offers.
+ *
+ * Two conditions, and they are separate questions:
+ *
+ *  - **enabled** — policy. What the operator wants offered, `models.config.json`
+ *    as the default and `model-overrides.json` as their decision on top.
+ *  - **provider has a key** — availability. Offering a model nobody can be billed
+ *    for produces a runtime failure at the worst moment.
+ *
+ * This exists because four readers each answered it differently, and the answers
+ * mattered. Measured on the production host, which has keys for four providers
+ * and eight overrides that all diverge from the bundled default: the create
+ * wizard listed 58 models where the correct answer was 62, offering two the
+ * operator had switched off and hiding six they had switched on. It read the
+ * bundle directly and never opened the overrides file. Meanwhile
+ * `/api/provider/v1/models` applied the overrides but not the key filter, so it
+ * advertised models for providers with no credentials.
+ *
+ * Callers still shape the result themselves — the sync adds `input` modalities,
+ * the pickers add prices — but the *set* is decided here, once.
+ */
+export function loadOfferedModels(): ModelConfigEntry[] {
+  const configured = new Set(Object.keys(readProviderKeys()));
+  return loadModelsConfig().filter((m) => {
+    if (!m.enabled) return false;
+    if (configured.has(m.provider)) return true;
+    // A `rev4a/*` alias bills through DeepSeek upstream, so a DeepSeek key is
+    // enough to offer one. The catalogue currently defines none.
+    if (m.provider === 'rev4a' && configured.has('deepseek')) return true;
+    return false;
+  });
+}
+
+/**
+ * May this deployment serve a request for this model?
+ *
+ * `loadOfferedModels` answers what to *show*; this answers what to *honour*. They
+ * were the same question asked in two places and only the first was ever asked:
+ * the proxy and the assistant took whatever model the caller named and billed it.
+ * Unchecking a model on the Gateway page removed it from every picker and stopped
+ * nothing, because a client that already held the id — a stale in-memory list, a
+ * saved preference, an agent configured before the change — kept working.
+ *
+ * Takes the *resolved* pair, not the raw string. Callers reach it through
+ * `extractProviderAndModel`, which collapses `rev4a/deepseek/deepseek-flash`,
+ * `deepseek/deepseek-flash` and the two-segment alias `rev4a/deepseek-flash` onto
+ * one provider and model, so all three are tested as the same catalogue id.
+ */
+export function isModelOffered(provider: string, model: string): boolean {
+  const id = `${provider}/${model}`;
+  return loadOfferedModels().some((m) => m.id === id);
+}
+
+/**
+ * Where a model id stands against the catalogue, for explaining a failure.
+ *
+ * - `offered`  — enabled and its provider has a key; the proxy serves it
+ * - `disabled` — in the catalogue but not offered: unchecked, or no key
+ * - `missing`  — not in the catalogue at all, e.g. removed in a release
+ *
+ * Takes a bare id, without the `rev4a/` prefix. The Model panel used to infer the
+ * cause from the offered list alone, so a model removed from the catalogue was
+ * explained as "unchecked, or its provider has no key" while the card said
+ * `NOT IN CATALOGUE`. `models-summary` computes the same two sets once for the
+ * whole fleet instead of calling this per agent.
+ */
+export function catalogueStatus(id: string): 'offered' | 'disabled' | 'missing' {
+  if (!loadModelsConfig().some((m) => m.id === id)) return 'missing';
+  return loadOfferedModels().some((m) => m.id === id) ? 'offered' : 'disabled';
+}

package/lib/provider-balance.ts

@@ -27,6 +27,9 @@ interface BalanceInfo {
   granted_balance?: string;
 }
 
+/** Thrown when the provider has no balance API for this account type (permanent, not transient). */
+export class BalanceUnsupportedError extends Error {}
+
 /* ------------------------------------------------------------------ */
 /*  DeepSeek                                                            */
 /* ------------------------------------------------------------------ */
@@ -99,7 +102,21 @@ async function fetchZAIBalance(apiKey: string): Promise<BalanceResult> {
   if (!resp.ok) {
     throw new Error(`Z.AI quota API returned ${resp.status}`);
   }
-  const json = await resp.json() as { limits?: ZAILimit[] };
+  const json = await resp.json() as {
+    success?: boolean;
+    msg?: string;
+    limits?: ZAILimit[];
+  };
+
+  // The endpoint only serves GLM Coding Plan subscriptions. A pay-as-you-go
+  // account gets HTTP 200 with success:false and no limits; Z.AI exposes no
+  // balance API for it (no undocumented endpoint either, verified 2026-09-16),
+  // so this is permanent, not transient: the UI hides the badge entirely.
+  if (json.success === false) {
+    throw new BalanceUnsupportedError(
+      `Z.AI exposes no balance API for pay-as-you-go accounts (the token-quota endpoint requires a Coding Plan)`,
+    );
+  }
 
   const tokenLimit = json.limits?.find((l) => l.limitType === 'TOKENS_LIMIT');
   if (tokenLimit) {
@@ -116,17 +133,21 @@ async function fetchZAIBalance(apiKey: string): Promise<BalanceResult> {
     };
   }
 
-  // Fallback: sum all limits
-  const totalRemaining = (json.limits ?? []).reduce(
-    (sum, l) => sum + (l.remaining ?? l.limitValue - l.usage),
-    0,
-  );
-  return {
-    balance: `${(totalRemaining / 1_000_000).toFixed(1)}M tokens`,
-    currency: 'TOKENS',
-    value: totalRemaining,
-    label: 'Remaining',
-  };
+  // Fallback: sum all limits, only when the API actually returned some.
+  if ((json.limits ?? []).length > 0) {
+    const totalRemaining = (json.limits ?? []).reduce(
+      (sum, l) => sum + (l.remaining ?? l.limitValue - l.usage),
+      0,
+    );
+    return {
+      balance: `${(totalRemaining / 1_000_000).toFixed(1)}M tokens`,
+      currency: 'TOKENS',
+      value: totalRemaining,
+      label: 'Remaining',
+    };
+  }
+
+  throw new Error('Z.AI returned no quota limits');
 }
 
 /* ------------------------------------------------------------------ */

package/lib/rev4a-paths.ts

@@ -58,27 +58,6 @@ export const SHARED_SKILLS_DIR = path.join(REV4A_DATA, 'shared', 'shared-skills'
 /** Rev4a system rules injected into every agent workspace, mounted read-only. */
 export const REV4A_RULES_DIR = path.join(REV4A_DATA, 'shared', 'rev4a-rules');
 
-/**
- * Model catalogue — read-only, shipped with the package.
- * Resolved at module load from the package root (alongside bin/rev4a.js).
- */
-function resolvePackageFile(filename: string): string {
-  // cwd in dev (workspace checkout)
-  const cwdPath = path.join(process.cwd(), filename);
-  if (fs.existsSync(cwdPath)) return cwdPath;
-
-  // Installed package: this file is at <pkgRoot>/lib/rev4a-paths.js
-  const pkgRoot = path.resolve(__dirname, '..');
-  const pkgPath = path.join(pkgRoot, filename);
-  if (fs.existsSync(pkgPath)) return pkgPath;
-
-  // Last resort: accept that it may not exist (will throw at read time)
-  return cwdPath;
-}
-
-/** Static model catalogue — read-only, inside the package repo */
-export const MODELS_CONFIG_FILE = resolvePackageFile('models.config.json');
-
 /** Top-level .next build directory (kept inside npm package for now — built by rev4a serve) */
 export function nextDir(pkgRoot: string): string {
   return path.join(pkgRoot, '.next');