@flame0510/project-aether 1.5.1 → 1.6.0

package/lib/agent-restore-state.ts

@@ -2,9 +2,10 @@
  * Persisted state of agent restores: the `agent_restores` table (lib/db-bootstrap.mjs).
  *
  * Kept apart from lib/agent-restore.ts so busy checks (lib/agent-busy.ts) can ask which
- * agents are being restored without importing the restore action.
+ * agents are being restored without importing the restore action. The machinery is
+ * lib/agent-job-state.ts; this file holds the table's types and names.
  */
-import { openDb } from '@/lib/db';
+import { createJobState } from '@/lib/agent-job-state';
 
 export type RestoreStatus = 'restoring' | 'done' | 'failed' | 'interrupted';
 
@@ -24,84 +25,42 @@ export interface AgentRestoreRow {
 
 const FINAL: readonly RestoreStatus[] = ['done', 'failed', 'interrupted'];
 
-export function insertRestore(agentId: string, file: string): number {
-  const db = openDb(false);
-  try {
-    const now = Date.now();
-    const info = db.prepare(
-      `INSERT INTO agent_restores (agent_id, status, file, started_at, updated_at)
-       VALUES (?, 'restoring', ?, ?, ?)`,
-    ).run(agentId, file, now, now);
-    return Number(info.lastInsertRowid);
-  } finally {
-    db.close();
-  }
-}
+const state = createJobState({
+  table: 'agent_restores',
+  initialStatus: 'restoring',
+  activeStatuses: ACTIVE_RESTORE_STATUSES,
+  finalStatuses: FINAL,
+  insertColumns: ['file'],
+  writableColumns: [],
+});
 
 type Writable = Partial<Pick<AgentRestoreRow, 'status' | 'error'>>;
 
+export function insertRestore(agentId: string, file: string): number {
+  return state.insert(agentId, file);
+}
+
 export function updateRestoreRow(id: number, fields: Writable): void {
-  const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
-  const now = Date.now();
-  const sets = [...entries.map(([k]) => `${k} = ?`), 'updated_at = ?'];
-  const values: unknown[] = [...entries.map(([, v]) => v), now];
-  if (fields.status && FINAL.includes(fields.status)) {
-    sets.push('finished_at = ?');
-    values.push(now);
-  } else if (fields.status) {
-    sets.push('finished_at = NULL');
-  }
-  const db = openDb(false);
-  try {
-    db.prepare(`UPDATE agent_restores SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
-  } finally {
-    db.close();
-  }
+  state.update(id, fields);
 }
 
 export function latestRestore(agentId: string): AgentRestoreRow | null {
-  const db = openDb(true);
-  try {
-    return (db.prepare('SELECT * FROM agent_restores WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentRestoreRow | undefined) ?? null;
-  } finally {
-    db.close();
-  }
+  return state.latest<AgentRestoreRow>(agentId);
 }
 
 export function isRestoreActive(agentId: string): boolean {
-  const row = latestRestore(agentId);
-  return !!row && ACTIVE_RESTORE_STATUSES.includes(row.status);
+  return state.isActive(agentId);
 }
 
-/** AGENT_IDs with a restore in an active status. */
 export function activeRestoreAgentIds(): Set<string> {
-  const db = openDb(true);
-  try {
-    const placeholders = ACTIVE_RESTORE_STATUSES.map(() => '?').join(', ');
-    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_restores WHERE status IN (${placeholders})`).all(...ACTIVE_RESTORE_STATUSES) as { agent_id: string }[];
-    return new Set(rows.map((r) => r.agent_id));
-  } finally {
-    db.close();
-  }
+  return state.activeAgentIds();
 }
 
-/**
- * At startup no restore job can be running: a row still active was cut off by the
- * restart. It becomes `interrupted`, keeping the archive it was restoring.
- */
 export function markInterruptedRestores(): number {
-  const db = openDb(false);
-  try {
-    const placeholders = ACTIVE_RESTORE_STATUSES.map(() => '?').join(', ');
-    const now = Date.now();
-    const info = db.prepare(
-      `UPDATE agent_restores
-         SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
-             status = 'interrupted', updated_at = ?, finished_at = ?
-       WHERE status IN (${placeholders})`,
-    ).run(now, now, ...ACTIVE_RESTORE_STATUSES);
-    return info.changes;
-  } finally {
-    db.close();
-  }
+  return state.markInterrupted();
+}
+
+/** Keep the newest `keepPerAgent` restores of each agent; the rest is history. */
+export function pruneRestores(keepPerAgent: number): number {
+  return state.prune(keepPerAgent);
 }

package/lib/agent-restore.ts

@@ -123,19 +123,42 @@ export function agentRestoreView(agentId: string): AgentRestoreView | null {
 
 /**
  * At startup no restore job can be running: rows still active were cut off by the
- * restart. They become `interrupted`; a container left stopped is started again,
- * best-effort, so nothing stays down.
+ * restart. A restore interrupted **mid-extract** leaves a half-written volume, so
+ * starting the container would present a partial workspace as if it were the restore: the
+ * extract is run again from the same archive (it is the source of truth and the file was
+ * checked before the job started), in the background, and the row lands in its final
+ * status. When the archive is gone the container is started on whatever the volume holds,
+ * and the row says so.
  */
 export async function recoverInterruptedRestores(): Promise<number> {
   const ids = activeRestoreAgentIds();
   if (ids.size === 0) return 0;
   const interrupted = markInterruptedRestores();
   for (const agentId of ids) {
-    const container = await inspectAgentContainer(agentId).catch(() => null);
-    const name = container?.Name?.replace(/^\//, '');
-    if (!name || container?.State?.Running) continue;
+    const row = latestRestore(agentId);
+    const name = (await inspectAgentContainer(agentId).catch(() => null))?.Name?.replace(/^\//, '');
+    if (row?.file && (await backupFileExists(agentId, row.file))) {
+      console.log(`[agent:restore] ${agentId}: re-running the interrupted restore from ${row.file}`);
+      void runRestore(row.id, agentId, row.file).finally(() => undefined);
+      continue;
+    }
+    if (!name) continue;
     const started = await startAndVerifyContainer(agentId, name);
     if (!started.ok) console.warn(`[agent:restore] ${agentId} did not come back after an interrupted restore: ${started.error}`);
   }
   return interrupted;
 }
+
+/** Whether the archive still exists in the backup volume. */
+async function backupFileExists(agentId: string, file: string): Promise<boolean> {
+  if (!isValidBackupFile(agentId, file)) return false;
+  try {
+    await runDocker(
+      ['run', '--rm', '-v', `${BACKUP_VOLUME}:/backup`, 'alpine', 'sh', '-c', 'test -f "/backup/$FILE"'],
+      { timeoutMs: 30_000, env: { FILE: file } },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/agent-update-state.ts

@@ -2,9 +2,10 @@
  * Persisted state of agent updates: the `agent_upgrades` table (lib/db-bootstrap.mjs).
  *
  * Kept apart from lib/agent-update.ts so the provider sync can ask which agents are
- * being updated without importing the update action, which imports the sync.
+ * being updated without importing the update action, which imports the sync. The
+ * machinery is lib/agent-job-state.ts; this file holds the table's types and names.
  */
-import { openDb } from '@/lib/db';
+import { createJobState } from '@/lib/agent-job-state';
 
 export type UpdateStatus =
   | 'pending'
@@ -38,65 +39,36 @@ export interface AgentUpdateRow {
 
 const FINAL: readonly UpdateStatus[] = ['done', 'failed', 'interrupted', 'rolled_back', 'rollback_failed'];
 
-export function insertUpdate(agentId: string, fromVersion: string | null, toVersion: string): number {
-  const db = openDb(false);
-  try {
-    const now = Date.now();
-    const info = db.prepare(
-      `INSERT INTO agent_upgrades (agent_id, status, from_version, to_version, started_at, updated_at)
-       VALUES (?, 'pending', ?, ?, ?, ?)`,
-    ).run(agentId, fromVersion, toVersion, now, now);
-    return Number(info.lastInsertRowid);
-  } finally {
-    db.close();
-  }
-}
+const state = createJobState({
+  table: 'agent_upgrades',
+  initialStatus: 'pending',
+  activeStatuses: ACTIVE_STATUSES,
+  finalStatuses: FINAL,
+  insertColumns: ['from_version', 'to_version'],
+  writableColumns: ['backup_file', 'baseline_json', 'verify_json'],
+});
 
 type Writable = Partial<Pick<AgentUpdateRow, 'status' | 'backup_file' | 'baseline_json' | 'verify_json' | 'error'>>;
 
+export function insertUpdate(agentId: string, fromVersion: string | null, toVersion: string): number {
+  return state.insert(agentId, fromVersion, toVersion);
+}
+
 export function updateRow(id: number, fields: Writable): void {
-  const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
-  const now = Date.now();
-  const sets = [...entries.map(([k]) => `${k} = ?`), 'updated_at = ?'];
-  const values: unknown[] = [...entries.map(([, v]) => v), now];
-  if (fields.status && FINAL.includes(fields.status)) {
-    sets.push('finished_at = ?');
-    values.push(now);
-  } else if (fields.status) {
-    sets.push('finished_at = NULL');
-  }
-  const db = openDb(false);
-  try {
-    db.prepare(`UPDATE agent_upgrades SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
-  } finally {
-    db.close();
-  }
+  state.update(id, fields);
 }
 
 export function latestUpdate(agentId: string): AgentUpdateRow | null {
-  const db = openDb(true);
-  try {
-    return (db.prepare('SELECT * FROM agent_upgrades WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentUpdateRow | undefined) ?? null;
-  } finally {
-    db.close();
-  }
+  return state.latest<AgentUpdateRow>(agentId);
 }
 
 export function isUpdateActive(agentId: string): boolean {
-  const row = latestUpdate(agentId);
-  return !!row && ACTIVE_STATUSES.includes(row.status);
+  return state.isActive(agentId);
 }
 
 /** AGENT_IDs with an update in an active status. */
 export function activeUpdateAgentIds(): Set<string> {
-  const db = openDb(true);
-  try {
-    const placeholders = ACTIVE_STATUSES.map(() => '?').join(', ');
-    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_upgrades WHERE status IN (${placeholders})`).all(...ACTIVE_STATUSES) as { agent_id: string }[];
-    return new Set(rows.map((r) => r.agent_id));
-  } finally {
-    db.close();
-  }
+  return state.activeAgentIds();
 }
 
 /**
@@ -105,18 +77,10 @@ export function activeUpdateAgentIds(): Set<string> {
  * between Rollback and a new Update.
  */
 export function markInterruptedUpdates(): number {
-  const db = openDb(false);
-  try {
-    const placeholders = ACTIVE_STATUSES.map(() => '?').join(', ');
-    const now = Date.now();
-    const info = db.prepare(
-      `UPDATE agent_upgrades
-         SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
-             status = 'interrupted', updated_at = ?, finished_at = ?
-       WHERE status IN (${placeholders})`,
-    ).run(now, now, ...ACTIVE_STATUSES);
-    return info.changes;
-  } finally {
-    db.close();
-  }
+  return state.markInterrupted();
+}
+
+/** Keep the newest `keepPerAgent` updates of each agent; the rest is history. */
+export function pruneUpdates(keepPerAgent: number): number {
+  return state.prune(keepPerAgent);
 }

package/lib/channelManager.ts

@@ -287,6 +287,12 @@ export interface ApprovedPairing {
 export interface PairingState {
   pending: PendingPairing[];
   approved: ApprovedPairing[];
+  /**
+   * Why the approved list is empty, when that is not simply "none": the pairing store
+   * could not be read (the writer is not in this OpenClaw build, or the read failed).
+   * Callers must show it instead of "No approved senders", which would be a guess.
+   */
+  error?: string | null;
 }
 
 /**
@@ -428,8 +434,13 @@ export async function getPairings(agentId: string, channel: string = 'telegram')
   if (store.status === 'ok') {
     for (const entry of store.entries ?? []) approved.push({ senderId: String(entry) });
   }
+  // 'absent' is a real answer (no store yet, so no approved senders); anything else means
+  // the read did not succeed and an empty list must not be presented as "none".
+  const error = store.status === 'ok' || store.status === 'absent'
+    ? null
+    : (store.error ?? 'The approved senders could not be read');
 
-  return { pending, approved };
+  return { pending, approved, error };
 }
 
 /** Approve a pending pairing code */

package/lib/memory-context.ts

@@ -124,7 +124,7 @@ function formatBytesForWarning(value: number): string {
 function applyBootstrapSizeWarnings(file: FileSummary): void {
   const limit = BOOTSTRAP_FILE_WARN_BYTES[file.key as BootstrapFileName];
   if (!limit || file.size === null || file.size <= limit) return;
-  file.warnings.push(`${file.key} sopra soglia: ${formatBytesForWarning(file.size)} / ${formatBytesForWarning(limit)}`);
+  file.warnings.push(`${file.key} above threshold: ${formatBytesForWarning(file.size)} / ${formatBytesForWarning(limit)}`);
 }
 
 export function inspectFile(filePath: string, key: string): FileSummary {
@@ -334,7 +334,7 @@ function inspectAgent(seed: AgentSeed): AgentMemorySummary {
 
   summary.strategy = classifyAgent(summary);
   if (bootstrapBytes > WORKSPACE_TOTAL_WARN_BYTES) {
-    summary.warnings.push(`Bootstrap totale sopra budget: ${formatBytesForWarning(bootstrapBytes)} / ${formatBytesForWarning(WORKSPACE_TOTAL_WARN_BYTES)}`);
+    summary.warnings.push(`Bootstrap total above budget: ${formatBytesForWarning(bootstrapBytes)} / ${formatBytesForWarning(WORKSPACE_TOTAL_WARN_BYTES)}`);
   }
   summary.warnings = uniqueStrings(summary.warnings.concat(...Object.values(files).map((file) => file.warnings)));
   return summary;

package/lib/model-catalogue.ts

@@ -14,6 +14,20 @@ import { readProviderKeys } from '@/app/api/gateway/provider/keys';
 /*  Types                                                              */
 /* ------------------------------------------------------------------ */
 
+/**
+ * The hand-written `info` block of a catalogue entry: what OpenRouter cannot tell us
+ * (parameter counts, the vendor's own docs, benchmarks published elsewhere). Every
+ * field is optional and every number carries its source — never an estimate.
+ */
+export interface ModelInfo {
+  params?: string;
+  released?: string;
+  docUrl?: string;
+  knowledgeCutoff?: string;
+  benchmarks?: { name: string; value: number; source: string; asOf?: string }[];
+  notes?: string;
+}
+
 export interface ModelConfigEntry {
   id: string;
   name: string;
@@ -22,6 +36,8 @@ export interface ModelConfigEntry {
   modality?: string;
   /** Upstream has retired this id. It still answers, but is redirected. */
   deprecated?: boolean;
+  /** Curated extras for the details modal (lib/model-details.ts). */
+  info?: ModelInfo;
 }
 
 /* ------------------------------------------------------------------ */
@@ -86,6 +102,7 @@ function loadBundledModels(): ModelConfigEntry[] {
       enabled: Boolean(m.enabled),
       modality: typeof m.modality === 'string' ? m.modality : undefined,
       deprecated: m.deprecated === true ? true : undefined,
+      info: m.info && typeof m.info === 'object' ? (m.info as ModelInfo) : undefined,
     }));
     lastGoodBundle = models;
     bundleStatus = 'ok';

package/lib/model-details.ts

@@ -0,0 +1,124 @@
+/**
+ * Model details for the details modal: the curated catalogue entry
+ * (`models.config.json`), its price (`model-pricing.json`) and the generated specs,
+ * description and benchmarks (`model-details.json`, written by
+ * `scripts/refresh-model-pricing.mjs` from the OpenRouter catalogue).
+ *
+ * The generated file is optional on purpose: a checkout that never ran the script has
+ * fewer fields, never an error. Prices for direct providers come from their own price list
+ * (the script is scoped to `openrouter/*`), so the view labels where each number is from.
+ */
+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';
+
+/** What `scripts/refresh-model-pricing.mjs` writes per id. All optional. */
+export interface GeneratedDetails {
+  description?: string;
+  /** Release/listing date, `YYYY-MM-DD`. */
+  created?: string;
+  context?: number;
+  /** The provider's own context limit, when OpenRouter reports a different one. */
+  providerContext?: number;
+  maxOutput?: number;
+  tokenizer?: string;
+  instructType?: string;
+  /** Total parameter count and its source (Hugging Face, open weights only). */
+  params?: number;
+  paramsSource?: string;
+  hfArchitecture?: string;
+  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?: Record<string, unknown>;
+}
+
+export interface ModelDetailsView {
+  id: string;
+  name: string;
+  provider: string;
+  /** How the UI names that provider ("GLM (Z.AI)", "OpenRouter"). */
+  providerLabel: string;
+  modality?: string;
+  enabled: boolean;
+  deprecated: boolean;
+  price: { input: number; output: number; source: 'openrouter' | 'vendor' } | null;
+  details: GeneratedDetails | null;
+  info: ModelInfo | null;
+  /** When the generated part was produced. */
+  asOf: string | null;
+  detailsSource: 'openrouter' | 'none';
+}
+
+interface DetailsFile {
+  source?: string;
+  generatedAt?: string;
+  models?: Record<string, GeneratedDetails>;
+}
+
+function resolveDetailsPath(): string {
+  const cwdPath = path.resolve(process.cwd(), 'model-details.json');
+  if (fs.existsSync(cwdPath)) return cwdPath;
+  // Fallback: relative to this module, for a global install whose cwd is elsewhere.
+  return path.resolve(__dirname, '..', 'model-details.json');
+}
+
+let cache: DetailsFile | null = null;
+let cacheMtime = 0;
+
+function loadDetails(): DetailsFile {
+  try {
+    const stat = fs.statSync(resolveDetailsPath());
+    if (cache && stat.mtimeMs <= cacheMtime) return cache;
+    cache = JSON.parse(fs.readFileSync(resolveDetailsPath(), 'utf-8')) as DetailsFile;
+    cacheMtime = stat.mtimeMs;
+    return cache ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parameter count per model id, for the list views that show a size next to the price.
+ * One cached read of the generated file; a model without a Hugging Face card is simply
+ * absent — the row shows nothing rather than a guess.
+ */
+export function getModelParams(): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const [id, details] of Object.entries(loadDetails().models ?? {})) {
+    if (typeof details.params === 'number' && details.params > 0) out[id] = details.params;
+  }
+  return out;
+}
+
+/** The merged view for one model id, or null when the catalogue does not carry it. */
+export function getModelDetails(id: string): ModelDetailsView | null {
+  const entry = loadModelsConfig().find((m) => m.id === id);
+  if (!entry) return null;
+
+  const file = loadDetails();
+  const details = file.models?.[id] ?? null;
+  const pricing = getPricing(id);
+  const info = entry.info ?? null;
+
+  return {
+    id: entry.id,
+    name: entry.name,
+    provider: entry.provider,
+    providerLabel: providerLabel(entry.provider),
+    modality: entry.modality,
+    enabled: entry.enabled,
+    deprecated: entry.deprecated === true,
+    price: pricing ? { ...pricing, source: id.startsWith('openrouter/') ? 'openrouter' : 'vendor' } : null,
+    details,
+    info,
+    asOf: file.generatedAt ?? null,
+    detailsSource: details ? 'openrouter' : 'none',
+  };
+}

package/lib/provider-labels.ts

@@ -0,0 +1,21 @@
+/**
+ * What the UI calls each provider key the model catalogue uses. One source: the Gateway's
+ * provider cards and the details modal both read it, so a provider is never named two ways.
+ */
+export const PROVIDER_LABELS: Record<string, string> = {
+  google: 'Google Gemini',
+  deepseek: 'DeepSeek',
+  openrouter: 'OpenRouter',
+  openai: 'OpenAI',
+  anthropic: 'Anthropic',
+  groq: 'Groq',
+  kimi: 'Kimi',
+  glm: 'GLM (Z.AI)',
+  qwen: 'Qwen',
+  rev4a: 'REV4A API KEY',
+};
+
+/** The label for a provider key, falling back to the key itself. */
+export function providerLabel(key: string): string {
+  return PROVIDER_LABELS[key] ?? key;
+}