@flame0510/project-aether 1.11.0 → 1.11.1

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-10-01
+> **Last updated:** 2026-10-02
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -251,10 +251,15 @@ Returns current provider configuration state.
 
 **Response:** each provider carries its models, and a model carries `params` (the total
 parameter count) when its Hugging Face card publishes one — the Gateway row shows it next
-to the price, and a model without a card simply omits it.
+to the price, and a model without a card simply omits it. A model priced by time of day
+carries `band` (`"peak"` or `"off-peak"`, what the vendor bills right now — the Gateway row
+shows it as a chip) and its `pricing` is the rate in force at answer time, not the peak
+list price: it flips with the band, like the agents' synced prices. The top level carries
+`nextPriceChangeMs`, when the band flips next, so an open page can refresh the chips.
 
 ```json
 {
+  "nextPriceChangeMs": 1790532000000,
   "providers": [
     {
       "provider": "deepseek",
@@ -263,8 +268,8 @@ to the price, and a model without a card simply omits it.
       "baseUrl": "https://api.deepseek.com",
       "docsUrl": "https://platform.deepseek.com/api_keys",
       "models": [
-        { "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "enabled": true },
-        { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "enabled": true }
+        { "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "enabled": true, "band": "off-peak", "pricing": { "input": 0.15, "output": 0.6, "cacheRead": 0.003, "cacheWrite": 0.15 } },
+        { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "enabled": true, "band": "off-peak", "pricing": { "input": 0.66, "output": 1.98, "cacheRead": 0.022, "cacheWrite": 0.66 } }
       ]
     }
   ]
@@ -320,8 +325,8 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 ---
 
 ### `GET /api/models/details?id=<model id>`
-Everything the details modal shows for one model, and nothing more: fields the sources do
-not have are **absent**, never `null` and never a guess.
+Everything the details modal shows for one model, and nothing more: unknown optional
+facts are omitted; `price` and `info` can be `null` when absent.
 
 **Auth:** browser cookie or bearer token
 
@@ -330,7 +335,7 @@ not have are **absent**, never `null` and never a guess.
 {
   "id": "glm/glm-5.3-flash", "name": "GLM-5.3 Flash", "provider": "glm",
   "modality": "text+image+video->text", "enabled": false, "deprecated": false,
-  "price": { "input": 0.15, "output": 0.5, "source": "vendor" },
+  "price": { "input": 0.15, "output": 0.5, "source": "vendor", "scheduled": false },
   "details": { "description": "…", "created": "2026-08-26", "context": 1310720,
                "providerContext": 1048576, "maxOutput": 943718,
                "reasoning": { "mandatory": true, "default_effort": "max", "supported_efforts": ["max","high","low"] },
@@ -338,13 +343,15 @@ not have are **absent**, never `null` and never a guess.
                "benchmarks": { "design_arena": [ … ], "artificial_analysis": { … } },
                "huggingFaceId": "zai-org/GLM-5.3-Flash", "url": "https://openrouter.ai/…" },
   "info": null,
-  "asOf": "2026-09-23T14:02:40.271Z",
+  "asOf": "2026-10-02T10:46:53.452Z",
   "detailsSource": "openrouter"
 }
 ```
 
 `price.source` is `openrouter` for an `openrouter/*` entry and `vendor` for a direct one,
-which keeps prices honest: the refresh script never writes a vendor price. `details` comes
+which keeps prices honest: the refresh script never writes a vendor price. `price.scheduled`
+identifies a time-of-day list price; the Gateway row separately shows the rate in force.
+`details` comes
 from the generated `model-details.json` (`npm run refresh:pricing`, see
 `docs/dev/GATEWAY.md`), `info` from the catalogue's hand-written block, and `asOf` is when
 the generated part was produced. An id the catalogue does not carry answers `404`.
@@ -652,11 +659,14 @@ One agent's spend for its panel, from `costs.db`.
 
 **Auth:** browser cookie or Bearer
 
-**Response:** `{ "available": true, "intervalS": 300, "today": 0.011, "week": 0.019,
+**Response:** `{ "available": true, "intervalS": 300, "pricing": { "vendor": "DeepSeek", "band": "off-peak", "nextChange": 1790532000000, "source": "https://api-docs.deepseek.com/quick_start/pricing" }, "today": 0.011, "week": 0.019,
 "month": 0.022, "tokensMonth": 2409574, "topModel": { "model": "deepseek/deepseek-flash",
 "cost": 0.022 }, "unpricedMonth": 81, "collectedAt": 1790529516737, "error": null }` —
-UTC days (today, last 7, last 30); `collectedAt`/`error` from the agent's last read.
-`{ "available": false, "intervalS": 300 }` before `costs.db` exists.
+UTC days (today, last 7, last 30); `pricing` is the band billed right now, the same object
+the Costs page header shows (`null` when no scheduled model is on offer); `collectedAt`/`error`
+from the agent's last read. Before `costs.db` exists, the response is
+`{ "available": false, "intervalS": 300, "pricing": null }` (or the current pricing
+object when a scheduled model is on offer).
 
 **Errors:** `400` for an invalid container name; `500` when `costs.db` cannot be read.
 
@@ -2881,8 +2891,10 @@ the update kills this process on its way in (`fuser -k <port>/tcp`) and `rev4a s
 brings the child back on the new binary via its `.restart-flag`, so the connection
 drops and the page has to wait for the server to answer again.
 
-The child's output goes to `update.log` in the data directory — the update restarts
-the process that spawned it, so that file is the only record of what happened.
+The child's output goes to `update.log` under `<REV4A_DATA_DIR>/data` (or
+`~/.config/rev4a/data` by default) — the update restarts the process that spawned
+it, so that file is the only record of what happened. The endpoint creates the
+directory if needed and reports a failure if it cannot start the updater.
 
 **Auth:** browser cookie or bearer token
 

package/docs/dev/GATEWAY.md

@@ -1,6 +1,6 @@
 # Gateway Page
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-02
 
 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
@@ -113,9 +113,10 @@ its own Control UI too. Rev4a computes no cost: the daemon reads OpenClaw's figu
   (cached tokens priced as if the cache gave no discount); one without `cacheWrite` to
   1.25 × the input rate — vendors that bill cache writes apart charge more than input
   (Anthropic's five-minute cache: 1.25×), and the ones that report no cache writes never
-  use it. Either way an overestimate, never an undercount. `refresh:pricing` writes them
-  for OpenRouter models when OpenRouter publishes them (104 and 44 of 181 entries when
-  added); direct vendors are filled by hand from their pricing page.
+  use it. These fallbacks avoid treating an unknown cache rate as free, but can differ
+  from what a vendor bills. `refresh:pricing` writes published OpenRouter cache rates;
+  the file currently has cache-read rates for 107 models and cache-write rates for 44 of
+  184 entries. Direct vendors are filled by hand from their pricing page.
 - **Time-of-day prices.** DeepSeek bills half its rates off-peak (peak 01:00–04:00 and
   06:00–10:00 UTC, Monday–Friday). `PRICE_SCHEDULES` in `lib/model-pricing.ts` holds
   that schedule; `priceAt()` writes the rate of the moment, and
@@ -131,6 +132,11 @@ its own Control UI too. Rev4a computes no cost: the daemon reads OpenClaw's figu
   time, so a later change of rate does not reprice a call (verified with a real call,
   priced off-peak and read again after the switch to peak). Chinese public holidays,
   which DeepSeek bills off-peak all day, are priced as peak — a small overestimate.
+  Where the band is visible: the Costs page header (a pill with the time of the next
+  change), the agent panel's COSTS section (Rates now), and the Gateway page — a
+  band-priced model's row carries a PEAK / OFF-PEAK chip next to its price, and that price
+  is the rate in force now (off-peak it shows half the list price), refreshed just after
+  each change while the page stays open (`nextPriceChangeMs`).
 - **Calls made before a model had a price** are priced by OpenClaw when read, at the
   rate in force then; OpenClaw reindexes its transcripts after a price change, which is
   why a read can briefly answer `cacheStatus: refreshing`.
@@ -206,6 +212,9 @@ sources, each one labelled in the modal:
 | Price | `model-pricing.json` | refreshed for `openrouter/*`, hand for direct vendors |
 | Description, specs, benchmarks | `model-details.json` | **generated**, never hand-edited |
 
+For a scheduled vendor, the modal labels the static rate as a list price; the Gateway
+row shows the rate in force and its peak/off-peak band.
+
 `npm run refresh:pricing` (script `scripts/refresh-model-pricing.mjs`) fetches the
 OpenRouter catalogue once and writes both the prices and `model-details.json`:
 description, release date (`created`), context and the provider's own limit, max output,

package/docs/rag/GLOSSARY.md

@@ -34,7 +34,7 @@ Modal in the agent detail panel for configuring Telegram channels. Connect with
 What an agent spent in USD. Each agent's OpenClaw prices every model call itself, with the prices Rev4a writes into it (input, output, cached input), and Rev4a reads those figures every 5 minutes. The Costs page (`/costs`) shows them for today, 7 or 30 days — by day, by agent, by model, and the most expensive sessions. The dashboard's "Spent today" card shows the same figures for today, and each agent's panel on the Agents page has a COSTS section with its own. The Costs page also compares the agents' figures with what DeepSeek and OpenRouter actually billed (their balance or usage, read every hour).
 
 ## Off-peak
-DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header shows the current band.
+DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header and the agent panel's COSTS section (Rates now) show the current band.
 
 ## Cost Override
 A manual correction for a month's total cost, stored through `/api/cost-override`. There is currently no screen for it: no page in the dashboard reads or writes an override, so it can only be set by calling the API directly.

package/docs/rag/REV4A-OVERVIEW.md

@@ -74,7 +74,7 @@ Wizard to spin up a new agent. Steps: choose a template (Prometheus, Argus, Atla
 Interactive graph showing session family trees — which agent spawned which child agent, across configurable time periods: 1d, 3d, 7d, 15d, 30d, and all. Click any node to inspect. Includes a live feed side panel.
 
 ### Gateway (`/gateway`)
-Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page. Every model row has a **Details** button: the modal shows the model's description, price and provider, its architecture and parameter count when the weights are public, reasoning modes, capabilities, benchmarks with sources, licence and how much disk the weights take — the numbers come from the model card on Hugging Face and from curated entries that cite a source, never from estimates.
+Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page. A DeepSeek model row shows its current rate and a peak/off-peak chip; the rate updates after the next band change. Every model row has a **Details** button: the modal shows the model's description, list price and provider, its architecture and parameter count when the weights are public, reasoning modes, capabilities, benchmarks with sources, licence and how much disk the weights take — the numbers come from the model card on Hugging Face and from curated entries that cite a source, never from estimates.
 
 ### Containers (`/containers`)
 Full list of all Docker containers on the server, including stopped ones. Each row shows name, status, image, IP, ports, and an agent pill where applicable. Click "Terminal" to open an interactive shell into that container. A running container also shows what it consumes now — CPU share, memory and processes — with a "Charts" link to its history on the System page.
@@ -82,7 +82,7 @@ Full list of all Docker containers on the server, including stopped ones. Each r
 The page has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
 
 ### Costs (`/costs`)
-What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS).
+What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS), with the current DeepSeek band (Rates now).
 
 ### System (`/system`)
 The machine Rev4a runs on. Three cards — CPU (percent, cores, load average), memory (used, available, swap) and storage (each disk with its used and free space, and whether it is the system disk, where Docker keeps agents, or where Rev4a keeps its data) — then charts of CPU, memory and each disk over 1 hour, 24 hours, 7 days or 30 days (for CPU and memory the average line with the peak shaded). Hover a chart (or focus it and use the arrow keys) to read a point; each chart has a Table view. Bars turn yellow and red when they reach their thresholds. Figures refresh every 30 seconds; history is kept 30 days.

package/lib/docker-socket-path.d.ts

@@ -0,0 +1,9 @@
+/** Types for the CommonJS Docker socket client shared with daemon.js. */
+
+export function resolveDockerSocket(): string | null;
+
+export function dockerRequestJson<T = unknown>(
+  method: string,
+  apiPath: string,
+  timeoutMs?: number,
+): Promise<T>;

package/lib/docker-stats.d.ts

@@ -0,0 +1,88 @@
+/** Types for the CommonJS Docker stats parser shared with daemon.js. */
+
+export const CONTAINER_NAME_RE: RegExp;
+export const DF_TIMEOUT_MS: number;
+export const MB: number;
+
+export function cleanName(value: unknown, fallback?: string | null): string | null;
+export function primaryName(names: unknown): string;
+export function workingSetBytes(memory: unknown): number | null;
+export function sumNetwork(networks: unknown): { rx: number | null; tx: number | null };
+export function sumBlockIo(blkio: unknown): { rd: number | null; wr: number | null };
+
+export interface ContainerCounters {
+  t: number;
+  cpuNs: number;
+  memBytes: number | null;
+  pids: number | null;
+  rx: number | null;
+  tx: number | null;
+  rd: number | null;
+  wr: number | null;
+}
+
+export function readCounters(stats: unknown, atMs: number): ContainerCounters | null;
+
+export interface ContainerRates {
+  cpuCores: number | null;
+  rxBps: number | null;
+  txBps: number | null;
+  rdBps: number | null;
+  wrBps: number | null;
+}
+
+export function ratesBetween(
+  prev: ContainerCounters | null | undefined,
+  cur: ContainerCounters | null | undefined,
+  maxWindowS?: number,
+): ContainerRates;
+
+export interface HostCapacity {
+  ncpu: number;
+  memTotalMb: number;
+}
+
+export interface ContainerRow {
+  container: string;
+  cpu_cores: number | null;
+  mem_mb: number | null;
+  pids: number | null;
+  net_rx_bps: number | null;
+  net_tx_bps: number | null;
+  blk_read_bps: number | null;
+  blk_write_bps: number | null;
+}
+
+export interface ContainerSource {
+  container: string;
+  agent_id: string | null;
+  name: string;
+  is_agent: 0 | 1;
+  volumes: string;
+}
+
+export interface ContainerSample {
+  ts: number;
+  host: HostCapacity | null;
+  rows: ContainerRow[];
+  sources: ContainerSource[];
+}
+
+export function createContainerSampler(options: {
+  request: (method: string, path: string, timeoutMs?: number) => Promise<unknown>;
+  now?: () => number;
+  maxWindowS?: number;
+}): { sample: () => Promise<ContainerSample> };
+
+export interface VolumeUsage {
+  name: string;
+  sizeBytes: number | null;
+  unused: boolean;
+}
+
+export function parseStorage(df: unknown): {
+  volumes: VolumeUsage[];
+  layers: { container: string; sizeBytes: number | null }[];
+  images: { sizeBytes: number | null; reclaimableBytes: number | null };
+  buildCache: { sizeBytes: number | null; reclaimableBytes: number | null };
+} | null;

package/lib/model-details.ts

@@ -12,7 +12,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadModelsConfig, type ModelInfo } from '@/lib/model-catalogue';
 import { providerLabel } from '@/lib/provider-labels';
-import { getPricing } from '@/lib/model-pricing';
+import { getPricing, priceScheduleFor } from '@/lib/model-pricing';
 
 /** What `scripts/refresh-model-pricing.mjs` writes per id. All optional. */
 export interface GeneratedDetails {
@@ -48,7 +48,7 @@ export interface ModelDetailsView {
   modality?: string;
   enabled: boolean;
   deprecated: boolean;
-  price: { input: number; output: number; source: 'openrouter' | 'vendor' } | null;
+  price: { input: number; output: number; source: 'openrouter' | 'vendor'; scheduled: boolean } | null;
   details: GeneratedDetails | null;
   info: ModelInfo | null;
   /** When the generated part was produced. */
@@ -115,7 +115,7 @@ export function getModelDetails(id: string): ModelDetailsView | null {
     modality: entry.modality,
     enabled: entry.enabled,
     deprecated: entry.deprecated === true,
-    price: pricing ? { ...pricing, source: id.startsWith('openrouter/') ? 'openrouter' : 'vendor' } : null,
+    price: pricing ? { ...pricing, source: id.startsWith('openrouter/') ? 'openrouter' : 'vendor', scheduled: !!priceScheduleFor(id) } : null,
     details,
     info,
     asOf: file.generatedAt ?? null,

package/lib/model-pricing.ts

@@ -108,7 +108,9 @@ export function formatPricing(p: ModelPricing | null | undefined): string {
 
 /** The time-of-day schedule a model is billed on, or null for a flat price. */
 export function priceScheduleFor(modelId: string): PriceSchedule | null {
-  return PRICE_SCHEDULES[modelId.split('/')[0]] ?? null;
+  // Own keys only: an id segment like "constructor" must not find Object.prototype.
+  const vendor = modelId.split('/')[0];
+  return Object.hasOwn(PRICE_SCHEDULES, vendor) ? PRICE_SCHEDULES[vendor] : null;
 }
 
 function isPeak(schedule: PriceSchedule, at: Date): boolean {
@@ -145,9 +147,9 @@ const CACHE_WRITE_FALLBACK = 1.25;
  *
  * Null when there is nothing to write: no entry, or a dynamic router price (-1), whose
  * calls OpenClaw then counts as unpriced. A free model (all zero) gets FREE_RATE. A cache
- * rate the file does not carry falls back to a rate that does not undercount: the input
- * rate for a cache read (as if the cache gave no discount), CACHE_WRITE_FALLBACK × input
- * for a cache write.
+ * rate the file does not carry falls back to the input rate for a cache read (as if the
+ * cache gave no discount), or CACHE_WRITE_FALLBACK × input for a cache write. These
+ * estimates avoid treating an unknown rate as free; they are not vendor quotes.
  */
 export function priceAt(modelId: string, at: Date = new Date()): ModelCost | null {
   const p = getPricing(modelId);