@flame0510/project-aether 1.5.1 → 1.6.0

package/app/gateway/ModelDetailsModal.tsx

@@ -0,0 +1,322 @@
+'use client';
+
+/**
+ * Everything known about one model: what it is, what it costs, what it can do and how it
+ * scores. Opened from the Gateway's model row and **fetched when it opens**
+ * (`GET /api/models/details`) — descriptions are long and one model is looked at at a
+ * time, so inlining them in `/api/models` would weigh down every page poll.
+ *
+ * Absent data is not shown at all: no "n/a" blocks, and no number without its source.
+ * Prices come from the owner of the model (`model-pricing.json`), specs, description and
+ * OpenRouter benchmarks from the generated `model-details.json`, and anything else from
+ * the catalogue's hand-written `info` block.
+ */
+import { useEffect, useState } from 'react';
+import { Button, LoadingSpinner, Metric, Modal, ModalityIcons, Pill, PropertyList } from '../components/ui';
+import { formatParams, formatPrice } from '../lib/model-format';
+
+/** Mirrors lib/model-details.ts: a client component cannot import a module that reads files. */
+interface DetailsView {
+  id: string;
+  name: string;
+  provider: string;
+  providerLabel: string;
+  modality?: string;
+  enabled: boolean;
+  deprecated: boolean;
+  price: { input: number; output: number; source: 'openrouter' | 'vendor' } | null;
+  details: {
+    description?: string;
+    created?: string;
+    context?: number;
+    providerContext?: number;
+    maxOutput?: number;
+    tokenizer?: string;
+    instructType?: string;
+    /** Total parameter count, from the model's Hugging Face card (open weights only). */
+    params?: number;
+    paramsSource?: string;
+    /** Architecture facts from the model card (Hugging Face); open weights only. */
+    hf?: {
+      id: string;
+      total?: number;
+      byDtype?: Record<string, number>;
+      family?: string;
+      modelType?: string;
+      moe?: { experts?: number; perToken?: number; shared?: number };
+      layers?: number;
+      hidden?: number;
+      heads?: number;
+      kvHeads?: number;
+      vocab?: number;
+      context?: number;
+      vision?: boolean;
+      quantization?: string;
+      task?: string;
+      languages?: string[];
+      license?: string;
+      licenseName?: string;
+      published?: string;
+      updated?: string;
+      weightsBytes?: number;
+      tags?: string[];
+      downloads?: number;
+      likes?: number;
+    };
+    knowledgeCutoff?: string;
+    huggingFaceId?: string;
+    canonicalSlug?: string;
+    url?: string;
+    reasoning?: { mandatory?: boolean; default_enabled?: boolean; supported_efforts?: string[]; default_effort?: string };
+    supportedParameters?: string[];
+    moderated?: boolean;
+    benchmarks?: {
+      design_arena?: { arena?: string; category?: string; elo?: number; win_rate?: number; rank?: number }[];
+      artificial_analysis?: Record<string, number>;
+    };
+  } | null;
+  info: {
+    params?: string;
+    released?: string;
+    docUrl?: string;
+    knowledgeCutoff?: string;
+    benchmarks?: { name: string; value: number; source: string; asOf?: string }[];
+    notes?: string;
+  } | null;
+  asOf: string | null;
+  detailsSource: 'openrouter' | 'none';
+}
+
+const count = (n?: number): string | undefined => (typeof n === 'number' ? n.toLocaleString('en-US') : undefined);
+
+/** "1,048,576" is unreadable in a small metric: 1.05M reads at a glance. */
+function compactCount(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 2)}M`;
+  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
+  return String(n);
+}
+
+/** "BF16 6.9B · FP8 314.4B" — the weights' precision mix, biggest first. */
+function dtypeMix(byDtype: Record<string, number>): string {
+  return Object.entries(byDtype)
+    .filter(([, n]) => n > 1e6)
+    .sort((a, b) => b[1] - a[1])
+    .map(([k, n]) => `${k.replace('F8_E4M3', 'FP8').replace('F32', 'FP32')} ${formatParams(n)}`)
+    .join(' · ');
+}
+/** `parallel_tool_calls` reads better as words in a chip. */
+const human = (p: string): string => p.replace(/_/g, ' ');
+
+export default function ModelDetailsModal({ modelId, onClose }: { modelId: string; onClose: () => void }) {
+  const [view, setView] = useState<DetailsView | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [fullDescription, setFullDescription] = useState(false);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setView(null);
+    setError(null);
+    fetch(`/api/models/details?id=${encodeURIComponent(modelId)}`, { signal: controller.signal })
+      .then(async (res) => {
+        const data = await res.json().catch(() => null);
+        if (!res.ok) throw new Error((data as { error?: string } | null)?.error || `HTTP ${res.status}`);
+        return data as DetailsView;
+      })
+      .then(setView)
+      .catch((e: unknown) => { if ((e as Error)?.name !== 'AbortError') setError((e as Error).message); });
+    return () => controller.abort();
+  }, [modelId]);
+
+  const d = view?.details ?? null;
+  const info = view?.info ?? null;
+  const hf = d?.hf ?? null;
+  const reasoning = d?.reasoning;
+  const arenas = d?.benchmarks?.design_arena ?? [];
+  const aa = d?.benchmarks?.artificial_analysis;
+  const released = info?.released ?? hf?.published ?? d?.created;
+
+  return (
+    <Modal open onClose={onClose} title={view ? view.name : modelId} maxWidth={720}>
+      {error ? (
+        <div style={{ fontSize: 12, color: 'var(--red)' }}>{error}</div>
+      ) : !view ? (
+        <LoadingSpinner label="Loading model details…" />
+      ) : (
+        <div style={{ display: 'grid', gap: 4, fontSize: 12 }}>
+          {/* Identity */}
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+            <Pill>{view.provider}</Pill>
+            {view.deprecated && <Pill tone="warning">deprecated</Pill>}
+            {view.enabled ? <Pill tone="success">enabled</Pill> : <Pill>disabled</Pill>}
+            {view.modality && <ModalityIcons modality={view.modality} />}
+          </div>
+          <div style={{ fontFamily: 'var(--font-mono)', fontSize: 11, color: 'var(--text-dim)', overflowWrap: 'anywhere' }}>
+            {view.id}
+          </div>
+
+          {d?.description && (
+            <div style={{ margin: '8px 0 0' }}>
+              <p style={{
+                fontSize: 12, lineHeight: 1.5, color: 'var(--text)', margin: 0,
+                ...(fullDescription ? {} : { display: '-webkit-box', WebkitLineClamp: 4, WebkitBoxOrient: 'vertical' as const, overflow: 'hidden' }),
+              }}>{d.description}</p>
+              {d.description.length > 340 && (
+                <Button variant="ghost" size="sm" onClick={() => setFullDescription(!fullDescription)}>
+                  {fullDescription ? 'Show less' : 'Show more'}
+                </Button>
+              )}
+            </div>
+          )}
+
+          {(info?.notes || view.deprecated) && (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Status</div>
+              <div style={{ fontSize: 11, color: 'var(--yellow)' }}>
+                {info?.notes ?? 'Upstream has retired this id: it still answers, but is redirected.'}
+              </div>
+            </>
+          )}
+
+          {/* Price */}
+          <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Price</div>
+          <PropertyList rows={[
+            { label: 'Input / output', value: formatPrice(view.price) },
+            ...(view.price ? [{ label: 'Per 1M tokens, from', value: view.providerLabel, dim: true }] : []),
+          ]} />
+
+          {/* Architecture: the factory facts from the model card, open weights only */}
+          {hf && (hf.total || hf.moe || hf.layers) ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Architecture</div>
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(108px, 1fr))', gap: 8, marginBottom: 8 }}>
+                {hf.total ? <Metric size="sm" title="Parameters" value={formatParams(hf.total)} /> : null}
+                {hf.moe ? <Metric size="sm" title="Experts" value={`${count(hf.moe.experts) ?? '?'}${hf.moe.perToken ? ` · ${hf.moe.perToken}/tok` : ''}`} /> : null}
+                {hf.layers ? <Metric size="sm" title="Layers" value={hf.layers} /> : null}
+                {hf.context ? <Metric size="sm" title="Max context" value={`${compactCount(hf.context)} tok`} /> : null}
+              </div>
+              <PropertyList rows={[
+                ...(hf.family ? [{ label: 'Family', value: hf.family }] : []),
+                ...(hf.modelType ? [{ label: 'Model type', value: hf.modelType, dim: true }] : []),
+                ...(hf.hidden ? [{ label: 'Hidden size', value: count(hf.hidden) ?? '' }] : []),
+                ...(hf.heads ? [{ label: 'Attention heads', value: `${hf.heads}${hf.kvHeads && hf.kvHeads !== hf.heads ? ` (${hf.kvHeads} KV)` : ''}` }] : []),
+                ...(hf.vocab ? [{ label: 'Vocabulary', value: count(hf.vocab) ?? '' }] : []),
+                ...(hf.vision ? [{ label: 'Vision encoder', value: 'yes (multimodal)' }] : []),
+                ...(hf.quantization ? [{ label: 'Precision', value: hf.quantization.toUpperCase() }] : []),
+                ...(hf.weightsBytes ? [{ label: 'Weights on disk', value: `~${hf.weightsBytes >= 1e12 ? `${(hf.weightsBytes / 1e12).toFixed(1)} TB` : `${Math.round(hf.weightsBytes / 1e9)} GB`}` }] : []),
+                ...(hf.license ? [{ label: 'Licence', value: hf.license === 'other' ? 'custom — see the model card' : `${hf.license.toUpperCase()}${hf.licenseName ? ` (${hf.licenseName})` : ''}` }] : []),
+                ...(hf.byDtype ? [{ label: 'Weights by dtype', value: dtypeMix(hf.byDtype), dim: true }] : []),
+                ...(hf.task ? [{ label: 'Task', value: human(hf.task) }] : []),
+                ...(hf.languages?.length ? [{ label: 'Languages', value: hf.languages.join(', ') }] : []),
+                ...(hf.downloads || hf.likes ? [{ label: 'Popularity', value: `${count(hf.downloads) ?? '—'} downloads · ${count(hf.likes) ?? '—'} likes`, dim: true }] : []),
+              ]} />
+              <div style={{ fontSize: 10, color: 'var(--text-dim)', marginTop: 4 }}>
+                From the model card on Hugging Face ({hf.id}).
+              </div>
+            </>
+          ) : null}
+
+          {/* Specs */}
+          <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Specs</div>
+          <PropertyList rows={[
+            ...(released ? [{ label: 'Released', value: released }] : []),
+            ...(hf?.updated && hf.updated !== released ? [{ label: 'Card updated', value: hf.updated, dim: true }] : []),
+            ...(count(d?.context) ? [{ label: 'Context', value: `${count(d?.context)} tokens` }] : []),
+            ...(d?.providerContext && d.providerContext !== d.context ? [{ label: 'Provider limit', value: `${count(d.providerContext)} tokens`, dim: true }] : []),
+            ...(count(d?.maxOutput) ? [{ label: 'Max output', value: `${count(d?.maxOutput)} tokens` }] : []),
+            // The curated value can be more precise than the card (MoE total vs active);
+            // when there is none, the Hugging Face count is the honest number we have.
+            ...(info?.params
+              // The vendor's own framing (total/active), next to the card's total below:
+              // labelled, or the two numbers read as a contradiction.
+              ? [{ label: 'Parameters (vendor)', value: info.params }]
+              : []),
+            ...(info?.knowledgeCutoff || d?.knowledgeCutoff ? [{ label: 'Knowledge cutoff', value: info?.knowledgeCutoff ?? d?.knowledgeCutoff ?? '' }] : []),
+            ...(d?.tokenizer ? [{ label: 'Tokenizer', value: d.tokenizer, dim: true }] : []),
+            ...(d?.instructType ? [{ label: 'Instruct type', value: d.instructType, dim: true }] : []),
+            ...(d?.moderated ? [{ label: 'Moderated', value: 'yes' }] : []),
+          ]} />
+
+          {/* Reasoning */}
+          {reasoning && (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Reasoning</div>
+              <PropertyList rows={[
+                { label: 'Mode', value: reasoning.mandatory ? 'always reasons' : reasoning.default_enabled ? 'on by default' : 'optional' },
+                ...(reasoning.default_effort ? [{ label: 'Default effort', value: reasoning.default_effort }] : []),
+                ...(reasoning.supported_efforts?.length ? [{ label: 'Efforts', value: reasoning.supported_efforts.join(', ') }] : []),
+              ]} />
+            </>
+          )}
+
+          {/* Capabilities */}
+          {(d?.supportedParameters?.length || hf?.tags?.length) ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 6px' }}>Capabilities</div>
+              <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+                {[...new Set([...(d?.supportedParameters ?? []), ...(hf?.tags ?? [])])].map((c) => <Pill key={c}>{human(c)}</Pill>)}
+              </div>
+            </>
+          ) : null}
+
+          {/* Benchmarks: OpenRouter's, then the curated ones */}
+          {aa || arenas.length > 0 || info?.benchmarks?.length ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '14px 0 6px' }}>Benchmarks</div>
+              {aa && (
+                <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(120px, 1fr))', gap: 8, marginBottom: 8 }}>
+                  {Object.entries(aa).map(([k, v]) => <Metric key={k} title={human(k)} value={v} />)}
+                </div>
+              )}
+              {arenas.length > 0 && (
+                <div style={{ display: 'grid', gap: 2 }}>
+                  <div style={{ display: 'grid', gridTemplateColumns: '1fr 60px 50px 60px', gap: 6, fontSize: 10, color: 'var(--text-dim)', textTransform: 'uppercase', letterSpacing: '0.06em' }}>
+                    <span>Design arena</span><span style={{ textAlign: 'right' }}>Elo</span><span style={{ textAlign: 'right' }}>Rank</span><span style={{ textAlign: 'right' }}>Win rate</span>
+                  </div>
+                  {arenas.map((a, i) => (
+                    <div key={`${a.category ?? i}`} style={{ display: 'grid', gridTemplateColumns: '1fr 60px 50px 60px', gap: 6, fontSize: 11 }}>
+                      <span>{human(String(a.category ?? a.arena ?? '—'))}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.elo ?? '—'}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.rank ? `#${a.rank}` : '—'}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.win_rate !== undefined ? `${a.win_rate}%` : '—'}</span>
+                    </div>
+                  ))}
+                  <div style={{ fontSize: 10, color: 'var(--text-dim)', marginTop: 2 }}>OpenRouter arenas (community votes), as of the file's date below.</div>
+                </div>
+              )}
+              {info?.benchmarks?.length ? (
+                <div style={{ display: 'grid', gap: 3, marginTop: 8 }}>
+                  {info.benchmarks.map((b) => (
+                    <div key={b.name} style={{ fontSize: 11 }}>
+                      <span style={{ fontFamily: 'var(--font-mono)' }}>{b.value}</span>
+                      <span style={{ marginLeft: 6 }}>{b.name}</span>
+                      <a href={b.source} target="_blank" rel="noreferrer" style={{ marginLeft: 6, color: 'var(--violet)', fontSize: 10 }}>source</a>
+                      {b.asOf && <span style={{ marginLeft: 6, color: 'var(--text-dim)', fontSize: 10 }}>({b.asOf})</span>}
+                    </div>
+                  ))}
+                </div>
+              ) : null}
+            </>
+          ) : null}
+
+          {/* Links + provenance */}
+          <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'center', marginTop: 14, fontSize: 10, color: 'var(--text-dim)' }}>
+            {d?.url && <a href={d.url} target="_blank" rel="noreferrer" style={{ color: 'var(--violet)' }}>OpenRouter page</a>}
+            {d?.huggingFaceId && <span>HF: {d.huggingFaceId}</span>}
+            {info?.docUrl && <a href={info.docUrl} target="_blank" rel="noreferrer" style={{ color: 'var(--violet)' }}>Vendor docs</a>}
+          </div>
+          <div style={{ marginTop: 6, fontSize: 10, color: 'var(--text-dim)' }}>
+            {view.detailsSource === 'openrouter'
+              ? `Specs and benchmarks via OpenRouter${d?.paramsSource === 'huggingface' ? ', size via Hugging Face' : ''}`
+              : 'No generated details for this model'}
+            {view.asOf ? ` · data as of ${view.asOf.slice(0, 10)}` : ''}
+          </div>
+
+          <div style={{ display: 'flex', justifyContent: 'flex-end', marginTop: 12 }}>
+            <Button variant="secondary" size="sm" onClick={onClose}>Close</Button>
+          </div>
+        </div>
+      )}
+    </Modal>
+  );
+}

package/app/gateway/PageClient.tsx

@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { Button, ConfirmModal, Input, LoadingSpinner, Metric, ModalityIcons, Page, PageHeader, Pill, Surface } from '../components/ui';
+import ModelDetailsModal from './ModelDetailsModal';
+import { formatParams, formatPrice } from '../lib/model-format';
 import PasswordInput from '../components/PasswordInput';
 import { Skeleton } from '../components/Skeleton';
 import { useModels } from '../lib/models-context';
@@ -19,6 +21,8 @@ interface ModelInfo {
   pricingLive?: boolean;
   /** e.g. "text+image+file->text" — curated, matches what sync.ts provisions. */
   modality?: string;
+  /** Total parameters, when the model's card publishes them (open weights only). */
+  params?: number;
 }
 
 interface GatewayProvider {
@@ -89,6 +93,8 @@ export default function GatewayPageClient() {
 
   // Balance fetch state (per provider)
   const [balances, setBalances] = useState<Record<string, { balance: string; label?: string; loading?: boolean; error?: string; unsupported?: boolean } | null>>({});
+  /** Model whose details modal is open, null when none. */
+  const [detailsId, setDetailsId] = useState<string | null>(null);
   const [fetchingBalance, setFetchingBalance] = useState<Record<string, boolean>>({});
 
   // Accordion state — which provider cards are expanded
@@ -155,14 +161,8 @@ export default function GatewayPageClient() {
 
   useEffect(() => { void loadAll(); }, [loadAll]);
 
-  /** Format pricing for display: "$0.44 / $0.87" or "Free" or "Dynamic" or "—" */
-  function fmtPrice(p: { input: number; output: number } | null | undefined): string {
-    if (!p) return '—';
-    if (p.input === -1 && p.output === -1) return 'Dynamic';
-    if (p.input === 0 && p.output === 0) return 'Free';
-    const f = (n: number) => n < 0.01 ? `$${n.toFixed(3)}` : `$${n.toFixed(2)}`;
-    return `${f(p.input)} / ${f(p.output)}`;
-  }
+  /** Format pricing for display — shared with the details modal (app/lib/model-format.ts). */
+  const fmtPrice = formatPrice;
 
   /**
    * Local model filter. Matches against both the display name and the id,
@@ -430,7 +430,7 @@ export default function GatewayPageClient() {
       </section>
 
       {/* =========================================================== */}
-      {/*  REV4A API KEY — sezione speciale                         */}
+      {/*  REV4A API KEY — special section                         */}
       {/* =========================================================== */}
       <div style={{ marginBottom: 20 }}>
       <Surface variant="panel">
@@ -658,6 +658,14 @@ export default function GatewayPageClient() {
                                   <span style={{ marginLeft: 8, color: 'var(--violet)', fontWeight: 500 }}>
                                     {fmtPrice(pricing)}
                                   </span>
+                                  {typeof m.params === 'number' && (
+                                    <span
+                                      style={{ marginLeft: 8, color: 'var(--text-dim)' }}
+                                      title={`${m.params.toLocaleString('en-US')} parameters (Hugging Face)`}
+                                    >
+                                      {formatParams(m.params)}
+                                    </span>
+                                  )}
                                   {m.pricingLive && (
                                     <span
                                       title="Live price from the OpenRouter API"
@@ -668,6 +676,15 @@ export default function GatewayPageClient() {
                                   )}
                                 </div>
                               </div>
+                              <Button
+                                variant="ghost"
+                                size="sm"
+                                aria-label={`Details for ${m.name}`}
+                                title="Details"
+                                onClick={() => setDetailsId(m.id)}
+                              >
+                                ⋯
+                              </Button>
                               {modelMsg && (
                                 // Its own full-width line under the name, not a third column. As an
                                 // unconstrained flex item a long sync summary took its natural width
@@ -710,6 +727,7 @@ export default function GatewayPageClient() {
         cancelLabel="Cancel"
         tone="danger"
       />
-    </Page>
+          {detailsId && <ModelDetailsModal modelId={detailsId} onClose={() => setDetailsId(null)} />}
+</Page>
   );
 }

package/app/globals.css

@@ -615,6 +615,9 @@ html, body { height: 100%; height: 100dvh; background: var(--bg); color: var(--t
 .ui-tone--danger { border-color: #7f1d1d; }
 .ui-muted { color: var(--text-dim); }
 .ui-metric-value { margin-top: 14px; font-size: 26px; font-weight: 800; color: var(--text); }
+/* Compact metric: for grids inside dialogs, where the card value would wrap. */
+.ui-metric--sm .ui-metric-value { margin-top: 6px; font-size: 15px; font-weight: 700; line-height: 1.25; word-break: break-word; }
+.ui-metric--sm .ui-kicker { font-size: 9px; }
 .ui-tone--danger .ui-metric-value { color: var(--red); }
 .ui-metric-subtitle { margin-top: 8px; font-size: 11px; }
 .ui-card-head { display: flex; justify-content: space-between; gap: 10px; margin-bottom: 12px; }
@@ -1386,7 +1389,7 @@ html, body { height: 100%; height: 100dvh; background: var(--bg); color: var(--t
 
   /* Padding bottom per non coprire contenuti — handled by .app-shell__content */
 
-  /* Chat button alzato sopra la bottom navbar */
+  /* Chat button raised above the bottom navbar */
   .ochat__trigger {
     bottom: 70px !important;
   }

package/app/lib/model-format.ts

@@ -0,0 +1,21 @@
+/**
+ * Formatting shared by the Gateway model row and the details modal, so the same number
+ * never reads two ways in the same page.
+ */
+
+/** "1.60T", "321.3B", "9.7B", "300M" — the size people actually ask about. */
+export function formatParams(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(0)}M`;
+  return String(n);
+}
+
+/** USD per 1M tokens: "$0.15 / $0.50", or "Free", "Dynamic", "—". */
+export function formatPrice(p: { input: number; output: number } | null | undefined): string {
+  if (!p) return '—';
+  if (p.input === -1 && p.output === -1) return 'Dynamic';
+  if (p.input === 0 && p.output === 0) return 'Free';
+  const f = (n: number) => (n < 0.01 ? `$${n.toFixed(3)}` : `$${n.toFixed(2)}`);
+  return `${f(p.input)} / ${f(p.output)}`;
+}

package/bin/rev4a.js

@@ -428,7 +428,9 @@ function seedAgentToken() {
 function build() {
   log('BUILD', 'Building Next.js app…');
   try {
-    execSync('npx next build', { stdio: 'inherit', cwd: ROOT, timeout: 120_000 });
+    // Generous on purpose: a build is the slowest step of an install, and killing it
+    // because it passed two minutes takes the server down over slowness alone.
+    execSync('npx next build', { stdio: 'inherit', cwd: ROOT, timeout: 30 * 60_000 });
     log('BUILD', 'Build complete');
   } catch (err) {
     log('BUILD', `Build failed: ${err.message}`);
@@ -754,13 +756,14 @@ if (cmd === 'update') {
       console.log('Detected git repo — pulling and building…');
       execSync(`cd ${root} && git pull && npm install && npm run build`, {
         stdio: 'inherit',
-        timeout: 120_000,
+        // npm install + a full build: minutes, not two.
+        timeout: 30 * 60_000,
       });
     } else {
       console.log('Using npm global install…');
       execSync(`npm install -g ${PKG_NAME}@latest`, {
         stdio: 'inherit',
-        timeout: 120_000,
+        timeout: 20 * 60_000,
       });
       // Wipe old build so rev4a serve rebuilds with the new version
       const nextDir = join(ROOT, '.next');

package/daemon.js

@@ -28,7 +28,7 @@ const MODEL_PRICING = {
   'default':          { in: 3.00,  out: 15.00 },
 };
 
-// Alias diretti per modelli che non matchano per substring
+// Direct aliases for models that do not match by substring
 const MODEL_ALIASES = {
   'cheap': 'flash',
   'fast':  'claude-sonnet-4',
@@ -69,7 +69,7 @@ try {
 process.on('uncaughtException', (err) => {
   console.error(`[UNCAUGHT] ${err.message}\n${err.stack}`);
   console.error('Daemon will attempt restart via watchdog cron');
-  // NON uscire — il watchdog lo vede da healthcheck
+  // Do NOT exit — the watchdog reads this from the healthcheck
 });
 
 db.exec(`
@@ -749,7 +749,7 @@ function pollSessions() {
     }
   }
 
-  // WAL checkpoint FULL ogni 10 poll
+  // FULL WAL checkpoint every 10 polls
   pollCount = (pollCount || 0) + 1;
   if (pollCount % 10 === 0) {
     db.pragma('wal_checkpoint(FULL)');

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -207,8 +207,17 @@ The central container, running the Next.js dashboard + orchestration API.
   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`.
+  is refused, and an interrupted one is **run again from the same archive** at startup: a
+  half-written volume must never be presented as a restore, and the archive was already
+  checked before the job started (when it is gone the container is started on whatever the
+  volume holds, and the row says so). The extract has no percentage (it is a single
+  `tar xzf`); the panel and the agent card show `RESTORING`.
+- **The four job tables share one implementation**: `lib/agent-job-state.ts` builds the
+  insert/update/latest/active/`markInterrupted` machinery for `agent_upgrades`,
+  `agent_recreates`, `agent_restores` and `agent_edits`; each `lib/agent-*-state.ts` keeps
+  only its table's types and function names. They were four near-identical copies that had
+  started to drift. At startup `lib/agent-jobs-maintenance.ts` prunes each table to the
+  newest 20 rows per agent — the panel reads the latest row only, so the rest is history.
 - **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`.
@@ -279,6 +288,19 @@ the rules for anything you touch, not as a description of the whole tree:
 `promisify(exec)` silently ignores an `input` option: the process starts, stdin
 is never written, and the command hangs with no error to point at.
 
+- **The process model and self-update.** `rev4a serve` (the systemd unit's process) is a
+  supervisor: it spawns `rev4a _run <port>`, which in turn runs Next, the daemon and the
+  terminal WebSocket. `rev4a update` installs the new version, then `rev4a restart` writes
+  `.restart-flag` in the data directory; `_run` sees it, stops its children, waits for the
+  port to come free and exits with code **42**, and the supervisor relaunches `_run` on the
+  new code — so the supervisor itself never goes down (the unit's `NRestarts` stays 0).
+  The dashboard's **Update now** is only a detached `rev4a update` (`POST
+  /api/update-check`): it must not try to restart anything itself, because the update
+  stops the very process that spawned it, and the CLI's own flag is the mechanism that
+  matters. Its output goes to `update.log` in the data directory, since nothing else can
+  report the outcome: the banner records what it asked for, waits for the installed
+  version to change and only then reloads (see `VersionBanner`).
+
 ### 3.2 Agent Container Template (`openclaw-agent-base`)
 
 Docker image for every agent container.

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 
 ## Layering
 
@@ -36,7 +36,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `TemplateOption` | `TemplateOption.tsx` | Agent template selection card with avatar, description, optional badge. Centralises create-agent card styling. |
 | `Pill` | `Pill.tsx` | Small status/attribute label. Variants: `default`, `accent`. |
 | `ModalityIcons` | `ModalityIcons.tsx` | Capability badges parsed from a model's `modality` string (`"text+image->text"`). Input types render as icons; a non-text **output** is called out separately, since reading an image and generating one are different capabilities. Pass `dynamic` for router models, which advertise the union of everything they might route to and so show "varies" instead. |
-| `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone. |
+| `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone, and a `size` (`md` default, `sm` for a grid inside a dialog: smaller value, tighter spacing). |
 | `StatusCard` | `StatusCard.tsx` | Health/status report card. |
 | `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
@@ -46,10 +46,12 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `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. |
+| `VersionBanner` | `app/components/VersionBanner.tsx` | "Update available" banner for Rev4a itself, when `GET /api/update-check?check=1` reports a newer published version (dismissable per version, remembered in `localStorage`). **Update now** starts `POST /api/update-check`; because that update restarts the server, the banner cannot be told the outcome by the response: it records what it asked for in `sessionStorage`, polls `/api/update-check` until the installed version moves (two minutes at most) and reloads, then on the next mount either confirms "Updated to vX" or reports that the update did not complete and points at `update.log` (the update's own output). It never reloads blindly onto the same version. |
 | `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. |
+| `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`). When that store cannot be read the panel shows the reason instead of "No approved senders" (`PairingState.error`), so an empty list is never a guess. 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. The port range is validated **as it is typed**: the modal fetches `GET /api/agents/ports` when it opens (the same set the create form uses, every container, running or stopped) and excludes the agent's own block, so an occupied range shows the API's message inline and the Save button stays disabled — the create wizard does the same with the same endpoint. |
 | `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`. |
+| `ModelDetailsModal` | `app/gateway/ModelDetailsModal.tsx` | Details for one model, opened by the `⋯` button on a Gateway model row (`aria-label="Details for <name>"`). Fetches `GET /api/models/details?id=` **when it opens** (AbortController, shared spinner, error text) instead of inlining descriptions in the polled list. Sections appear only when their source has data: identity (provider, modality through the shared `ModalityIcons`, enabled and deprecated chips, the id), price with its origin (the provider's display label, from `lib/provider-labels.ts`), specs (release date, context and the provider's own limit when it differs, max output, knowledge cutoff, tokenizer, instruct type, moderation, **Architecture** (a metric row — parameters, experts, layers, max context — over the facts from the model card: family, model type, hidden size, attention heads with KV heads, vocabulary, vision encoder, precision and the weight mix by dtype, task, languages, popularity, attributed to Hugging Face), the description truncated to four lines with a **Show more** toggle, reasoning (mode, default effort, efforts), capabilities as `Pill`s, benchmarks (Artificial Analysis indices as `Metric`s, the design-arena table, then the curated ones with source and date), status (deprecated + notes) and a footer with the generated part's date. Never shows "n/a": an absent field is an absent block. |
 | `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. |
 | `useWizard` | `app/wizard/useWizard.ts` | Shared hook: wizard state, step transitions, provider save, restart. Receives server-side initial state to avoid a loading flash. |

package/docs/REV4A.md

@@ -201,6 +201,23 @@ If the daemon never answers, `serve` starts anyway, skips the network and image
 checks, and says so in the log. The startup sync then reaches no agent, and logs
 that too; run Sync All Agents once Docker is up.
 
+### Memory (a host that runs several agents)
+
+`rev4a update` installs the new version and the server rebuilds Next before it comes
+back (`rev4a` wipes `.next`, so the build always runs). That build is the memory peak
+of the whole installation: with several agent Gateways resident (roughly 0.5-0.8 GB
+each) a host with no swap can hit the kernel OOM killer during the update — it killed
+`next-server` on a 7.7 GB VPS, which then stayed unreachable until a reboot.
+
+Give such a host swap (4-8 GB is enough for the build) and a conservative
+`vm.swappiness`:
+
+```bash
+fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+echo 'vm.swappiness=10' > /etc/sysctl.d/99-rev4a-swap.conf
+```
+
 ### Systemd environment override
 
 File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)