@flame0510/project-aether 1.1.9

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

@@ -0,0 +1,124 @@
+# What PULSE Can Answer
+
+> **Last updated:** 2026-07-18
+
+PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
+
+---
+
+## Navigation Questions
+
+- "Where do I find the agents page?"
+- "How do I get to the container list?"
+- "Where can I see the onboarding wizard?"
+- "Is there a page for cron jobs?"
+- "Where can I see my AI providers?" — The Gateway page (`/gateway`) shows providers, models, agent assignments.
+- "How do I create a new agent?"
+- "What templates are available?"
+- "What is the Custom template?"
+- "How does the custom agent bootstrap work?"
+- "Where is the lineage graph?"
+- "How do I open the file explorer?"
+- "Which page shows costs?"
+- "Where do I manage credentials (GitHub, Trello, etc.)?"
+- "How do I connect an agent to Telegram?"
+- "How do I approve a Telegram pairing?"
+- "What does the TG badge mean?"
+- "How do I get to the gateway?"
+- "Where is the terminal for a container?"
+- "Where can I edit memory files?"
+- "How do I see the plugins?"
+- "Where can I check system health?"
+
+## How-To Questions
+
+- "How do I create an agent?"
+- "How do I set up Rev4a for the first time?"
+- "How do I complete the onboarding wizard?"
+- "How do I add an API key for a provider?"
+- "How do I filter agents by status?"
+- "How do I open a terminal for a container?"
+- "How do I see the tool calls for a session?"
+- "How do I configure a provider?"
+- "How do I set up the gateway?"
+- "How do I enable/disable models on the gateway?"
+- "How do I check if my API key is working?"
+- "How do I take a screenshot of the dashboard?"
+- "How do I view memory files?"
+- "How do I sync credentials to an agent?"
+- "How do I back up an agent?"
+- "How do I restore an agent from a backup?"
+- "How do I recreate an agent with the latest image?"
+- "How do I delete an agent?"
+- "How do I restart the Rev4a server?"
+- "How do I change environment variables?"
+- "How do I add a cost override?"
+- "How do I see the session lineage?"
+- "How do I log in to an agent's control UI?"
+- "How do I register a new provider via OAuth?"
+- "How do I manage agent model fallbacks?"
+- "How do I connect an agent to Telegram?"
+- "How do I approve a pairing code?"
+
+## Explanation Questions
+
+- "What does the lineage graph show?"
+- "What do the different statuses mean (idle, working, completed, error)?"
+- "What is a gateway?"
+- "What is the Provider Gateway?"
+- "What is the difference between a plugin and a skill?"
+- "What are MCP tools?"
+- "What does 'cost override' mean?"
+- "What is the vault?"
+- "What are credentials in Rev4a?"
+- "What is an agent template?"
+- "What happens when I recreate an agent?"
+- "How do agent backups work?"
+- "What is an agent persistent volume?"
+- "What is the onboarding wizard?"
+- "What is the difference between Gateway and Providers pages?"
+- "What is the Provider Gateway proxy?"
+- "How does the SSE stream work?"
+- "What is the shared gateway token?"
+- "What are model fallbacks?"
+- "What is the Channel Manager?"
+- "What is pairing?"
+- "What is Telegram pairing?"
+- "What is the TG badge on the agent list?"
+
+## Troubleshooting Questions
+
+- "Why is my agent not showing up?"
+- "Why are costs missing for some sessions?"
+- "Why can't I connect to the container terminal?"
+- "Why is the gateway sync not working?"
+- "Why am I seeing an onboarding banner?"
+- "How do I check if the daemon is running?"
+- "Why are credentials not showing in my agent?"
+- "Why is the agent base image banner showing?"
+- "How do I fix 'image is outdated'?"
+- "What happens if I abort a build?"
+- "Can I close the build modal while it's running?"
+- "How do agent image rebuilds work?"
+- "Why is my Telegram bot not connecting?"
+- "Why can't I approve a pairing code?"
+- "Why is the TG badge missing from my agent?"
+
+## What PULSE CANNOT do
+
+- Access real-time data (session costs, live statuses, actual CPU/RAM). She only knows features and navigation.
+- Execute actions (create agents, sync gateway, change config). She guides you to the right page.
+- Read the contents of specific files on the server.
+- See your API keys or credentials.
+- Predict costs for future sessions.
+
+---
+
+## How PULSE uses context
+
+When you ask a question, PULSE knows which page you're currently on (e.g. `/agents`, `/gateway`). She tailors her answer to the page you're looking at. If you're on the Agents page and ask "how do I create one?", she knows you mean an agent, not a cron job.
+
+### Best results
+1. **Open the relevant page first.** PULSE gives better guidance when you're on the Agents page asking about agents, or on the Gateway page asking about model routing.
+2. **Be specific.** "How do I add a fallback model?" works better than "help me with models."
+3. **Ask follow-ups.** PULSE remembers the conversation within the same chat session.

package/lib/agent-setup.ts

@@ -0,0 +1,130 @@
+/**
+ * Rev4a Agent Setup — Centralized volumes & config guarantees.
+ *
+ * Every Rev4a-managed agent gets a fixed set of bind mounts + a
+ * guaranteed set of OpenClaw config keys.  This module is the single
+ * source of truth; both the "create" and "recreate" API routes import
+ * from here so that a future volume or mandatory config key is a
+ * one-file change.
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+
+// ── Volumes ──────────────────────────────────────────────────────────────────
+
+export interface Rev4aVolume {
+  /** Absolute host path (e.g. /docker/shared-skills). */
+  source: string;
+  /** Absolute path inside the container. */
+  target: string;
+  /** Mount mode — "ro" for read-only, "rw" for read-write. */
+  mode: 'ro' | 'rw';
+}
+
+/**
+ * Fixed volumes mounted into every Rev4a agent container.
+ * Append entries here to add a new shared volume across all agents.
+ */
+export const REV4A_VOLUMES: Rev4aVolume[] = [
+  {
+    source: '/docker/shared-skills',
+    target: '/data/.openclaw/shared-skills',
+    mode: 'ro',
+  },
+  {
+    source: '/docker/rev4a-rules',
+    target: '/root/.openclaw/workspace/.rev4a',
+    mode: 'ro',
+  },
+];
+
+// ── Mount flags ──────────────────────────────────────────────────────────────
+
+/**
+ * Return an array of `-v source:target:mode` flags ready for `docker run`.
+ */
+export function getMountFlags(): string[] {
+  const flags: string[] = [];
+  for (const vol of REV4A_VOLUMES) {
+    flags.push('-v', `${vol.source}:${vol.target}:${vol.mode}`);
+  }
+  return flags;
+}
+
+// ── Host directory bootstrap ─────────────────────────────────────────────────
+
+/**
+ * Create every host-side source directory if it doesn't exist.
+ * Called once during `rev4a serve` preflight; safe to call
+ * multiple times.
+ */
+export function ensureHostDirs(): void {
+  for (const vol of REV4A_VOLUMES) {
+    if (!fs.existsSync(vol.source)) {
+      try {
+        execSync(`sudo mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
+      } catch {
+        execSync(`mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
+      }
+    }
+  }
+}
+
+// ── Runtime config guarantees ────────────────────────────────────────────────
+
+/**
+ * JSON patch payloads that MUST be present in every agent's openclaw.json.
+ * Each entry is a deep-merge patch applied via `openclaw config patch --stdin`.
+ *
+ * Ordered intentionally: provider config (which can vary per host) goes last
+ * so it can reference earlier-merged keys if needed.
+ */
+const GUARANTEED_CONFIG_PATCHES: object[] = [
+  // Rev4a system rules hook — loads .rev4a/*.md into every session
+  {
+    hooks: {
+      internal: {
+        entries: {
+          'bootstrap-extra-files': {
+            enabled: true,
+            paths: ['.rev4a/*.md'],
+          },
+        },
+      },
+    },
+  },
+  // Extra skill directories (shared across all agents)
+  {
+    skills: {
+      load: {
+        extraDirs: ['/data/.openclaw/shared-skills'],
+      },
+    },
+  },
+];
+
+/**
+ * Apply all guaranteed config patches to a running container.
+ * Uses `openclaw config patch --stdin` (deep-merge) so existing
+ * user customizations are never overwritten.
+ */
+export function applyRuntimeConfig(containerName: string): void {
+  for (const patch of GUARANTEED_CONFIG_PATCHES) {
+    const json = JSON.stringify(patch);
+    try {
+      execSync(
+        `docker exec -i ${escapeShell(containerName)} sh -c 'openclaw config patch --stdin'`,
+        { timeout: 15_000, stdio: 'pipe', input: json },
+      );
+    } catch {
+      // config patch is best-effort — the image may already have it
+    }
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+export function escapeShell(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/lib/alerts.ts

@@ -0,0 +1,115 @@
+import Database from 'better-sqlite3';
+import { DB_PATH, ensureDbReady } from './db';
+
+export type AlertKind = 'db-freshness';
+
+export interface AlertContext {
+  key: string;
+  kind: AlertKind;
+  title: string;
+  message: string;
+  resolvedMessage?: string;
+  stale: boolean;
+}
+
+const ALERTS_TABLE = `
+  CREATE TABLE IF NOT EXISTS alert_state (
+    alert_key TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    state TEXT NOT NULL,
+    last_sent_at INTEGER,
+    last_resolved_at INTEGER,
+    updated_at INTEGER NOT NULL,
+    payload TEXT
+  );
+`;
+
+function getConfig() {
+  return {
+    enabled: process.env.REV4A_ALERTS_ENABLED === 'true',
+    token: process.env.REV4A_TELEGRAM_BOT_TOKEN?.trim() ?? '',
+    chatId: process.env.REV4A_TELEGRAM_CHAT_ID?.trim() ?? '',
+    cooldownMs: Math.max(0, Number(process.env.REV4A_ALERT_COOLDOWN_MS ?? 10 * 60 * 1000)),
+  };
+}
+
+function openWritableDb() {
+  ensureDbReady();
+  const db = new Database(DB_PATH);
+  db.exec(ALERTS_TABLE);
+  return db;
+}
+
+async function sendTelegramMessage(text: string): Promise<void> {
+  const { token, chatId } = getConfig();
+  const response = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ chat_id: chatId, text, disable_web_page_preview: true }),
+  });
+  if (!response.ok) {
+    throw new Error(`Telegram send failed (${response.status})`);
+  }
+}
+
+export async function maybeSendAlert(context: AlertContext): Promise<{ action: 'noop' | 'sent' | 'dry-run'; reason: string }> {
+  const config = getConfig();
+  if (!config.enabled) return { action: 'noop', reason: 'alerts disabled' };
+
+  const now = Date.now();
+  const db = openWritableDb();
+  try {
+    const existing = db.prepare('SELECT * FROM alert_state WHERE alert_key = ?').get(context.key) as { state?: string; last_sent_at?: number | null } | undefined;
+    const message = context.stale ? `⚠️ ${context.title}\n${context.message}` : `✅ ${context.title}\n${context.resolvedMessage ?? context.message}`;
+
+    if (!config.token || !config.chatId) {
+      console.info('[alerts] dry-run', { key: context.key, stale: context.stale, hasToken: Boolean(config.token), hasChatId: Boolean(config.chatId) });
+      if (context.stale) {
+        db.prepare(
+          `INSERT INTO alert_state (alert_key, kind, state, last_sent_at, updated_at, payload)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(alert_key) DO UPDATE SET state=excluded.state, last_sent_at=excluded.last_sent_at, updated_at=excluded.updated_at, payload=excluded.payload`,
+        ).run(context.key, context.kind, 'alerted', now, now, JSON.stringify(context));
+      } else if (existing?.state === 'alerted') {
+        db.prepare(
+          `INSERT INTO alert_state (alert_key, kind, state, last_resolved_at, updated_at, payload)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(alert_key) DO UPDATE SET state=excluded.state, last_resolved_at=excluded.last_resolved_at, updated_at=excluded.updated_at, payload=excluded.payload`,
+        ).run(context.key, context.kind, 'resolved', now, now, JSON.stringify(context));
+      }
+      return { action: 'dry-run', reason: 'missing telegram credentials' };
+    }
+
+    if (context.stale) {
+      const lastSentAt = Number(existing?.last_sent_at ?? 0);
+      if (lastSentAt && now - lastSentAt < config.cooldownMs) return { action: 'noop', reason: 'cooldown active' };
+      await sendTelegramMessage(message);
+      db.prepare(
+        `INSERT INTO alert_state (alert_key, kind, state, last_sent_at, updated_at, payload)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(alert_key) DO UPDATE SET state=excluded.state, last_sent_at=excluded.last_sent_at, updated_at=excluded.updated_at, payload=excluded.payload`,
+      ).run(context.key, context.kind, 'alerted', now, now, JSON.stringify(context));
+      return { action: 'sent', reason: 'stale alert sent' };
+    }
+
+    if (existing?.state === 'alerted') {
+      await sendTelegramMessage(message);
+      db.prepare(
+        `INSERT INTO alert_state (alert_key, kind, state, last_resolved_at, updated_at, payload)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(alert_key) DO UPDATE SET state=excluded.state, last_resolved_at=excluded.last_resolved_at, updated_at=excluded.updated_at, payload=excluded.payload`,
+      ).run(context.key, context.kind, 'resolved', now, now, JSON.stringify(context));
+      return { action: 'sent', reason: 'resolved alert sent' };
+    }
+
+    db.prepare(
+      `INSERT INTO alert_state (alert_key, kind, state, updated_at, payload)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(alert_key) DO UPDATE SET state=excluded.state, updated_at=excluded.updated_at, payload=excluded.payload`,
+    ).run(context.key, context.kind, 'ok', now, JSON.stringify(context));
+    return { action: 'noop', reason: 'already ok' };
+  } finally {
+    db.close();
+  }
+}
+

package/lib/apiFetch.ts

@@ -0,0 +1,7 @@
+'use client';
+
+export function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = typeof window !== 'undefined' ? new URL(path, window.location.origin) : new URL(path, 'http://localhost:3740');
+  // Auth via JWT cookie (set by /api/auth/login) — no query param needed
+  return fetch(url.toString(), { cache: 'no-store', credentials: 'same-origin', ...init });
+}

package/lib/auth.ts

@@ -0,0 +1,28 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { jwtVerify } from 'jose';
+import { TOKEN } from '@/lib/db';
+
+const JWT_SECRET = new TextEncoder().encode(
+  process.env.REV4A_JWT_SECRET ?? 'rev4a-jwt-secret-change-in-prod',
+);
+
+export async function requireBrowserAuth(request: NextRequest): Promise<NextResponse | null> {
+  const token = new URL(request.url).searchParams.get('token');
+  const auth = request.headers.get('authorization');
+
+  if (token === TOKEN || auth === `Bearer ${TOKEN}`) {
+    return null;
+  }
+
+  const cookieToken = request.cookies.get('rev4a_token')?.value;
+  if (cookieToken) {
+    try {
+      await jwtVerify(cookieToken, JWT_SECRET);
+      return null;
+    } catch {
+      // Fall through to unauthorized.
+    }
+  }
+
+  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+}

package/lib/billing.ts

@@ -0,0 +1,100 @@
+import type { ModelCost } from '@/lib/types';
+
+export type BillingMode = 'usage' | 'fixed' | 'credits' | 'unknown';
+
+/**
+ * Economic dollar costs should only include providers we actually bill per usage.
+ * Today that is primarily OpenRouter, plus a small set of explicit pay-per-use aliases
+ * stored without provider prefixes in older rows.
+ */
+const BILLABLE_MODEL_PREFIXES = ['openrouter/'] as const;
+const BILLABLE_ALIAS_PREFIXES = ['deepseek', 'deepseek4', 'or-', 'openrouter', 'qwen', 'kimi', 'glm'] as const;
+const NON_BILLABLE_ALIAS_PATTERNS = [
+  /^gpt-5(\.|-|$)/,
+  /^codex(\.|-|$)/,
+  /^claude(\.|-|$)/,
+  /^claude-cli(\/|$)/,
+  /^anthropic(\/|$)/,
+  /^openai-codex(\/|$)/,
+  /^github-copilot(\/|$)/,
+] as const;
+
+export interface BillingBucket {
+  mode: BillingMode;
+  cost_usd: number;
+  sessions: number;
+  tokens_in: number;
+  tokens_out: number;
+  models: ModelCost[];
+}
+
+export interface BillingSummary {
+  usageBasedCost: number;
+  dbEstimatedCost: number;
+  buckets: Record<BillingMode, BillingBucket>;
+  usageModels: ModelCost[];
+  fixedModels: ModelCost[];
+  creditModels: ModelCost[];
+  unknownModels: ModelCost[];
+}
+
+export function isBillableDollarModel(model?: string | null): boolean {
+  const m = (model ?? '').trim().toLowerCase();
+  if (!m || m === 'unknown') return false;
+  if (BILLABLE_MODEL_PREFIXES.some((prefix) => m.startsWith(prefix))) return true;
+  if (NON_BILLABLE_ALIAS_PATTERNS.some((pattern) => pattern.test(m))) return false;
+  if (m.includes('/')) return false;
+  return BILLABLE_ALIAS_PREFIXES.some((prefix) => m.startsWith(prefix));
+}
+
+export function classifyBillingModel(model?: string | null): BillingMode {
+  const m = (model ?? '').toLowerCase();
+  if (!m || m === 'unknown') return 'unknown';
+  if (isBillableDollarModel(m)) return 'usage';
+  if (m.startsWith('openai-codex/')) return 'fixed';
+  if (m.startsWith('anthropic/') || m.includes('claude-cli')) return 'fixed';
+  if (m.startsWith('github-copilot/')) return 'credits';
+
+  // Rev4a DB often stores model aliases without provider prefix.
+  if (/^gpt-5\.(2|3|4|5)(-codex|-mini|-pro)?$/.test(m)) return 'fixed';
+  if (/^claude-(haiku|sonnet|opus)-/.test(m)) return 'fixed';
+  if (/^gemini-.*(flash|pro)/.test(m)) return 'credits';
+
+  // Known OpenRouter/free/usage-style aliases seen in this workspace.
+  if (/^(deepseek|deepseek4|or-|openrouter|qwen|kimi|glm)/.test(m)) return 'usage';
+  return 'unknown';
+}
+
+function emptyBucket(mode: BillingMode): BillingBucket {
+  return { mode, cost_usd: 0, sessions: 0, tokens_in: 0, tokens_out: 0, models: [] };
+}
+
+export function summarizeBilling(models: ModelCost[]): BillingSummary {
+  const buckets: Record<BillingMode, BillingBucket> = {
+    usage: emptyBucket('usage'),
+    fixed: emptyBucket('fixed'),
+    credits: emptyBucket('credits'),
+    unknown: emptyBucket('unknown'),
+  };
+
+  for (const model of models) {
+    const mode = classifyBillingModel(model.model);
+    const bucket = buckets[mode];
+    const cost = Number(model.cost_usd ?? 0);
+    bucket.cost_usd += cost;
+    bucket.sessions += Number(model.sessions ?? 0);
+    bucket.tokens_in += Number(model.tokens_in ?? 0);
+    bucket.tokens_out += Number(model.tokens_out ?? 0);
+    bucket.models.push(model);
+  }
+
+  return {
+    usageBasedCost: buckets.usage.cost_usd,
+    dbEstimatedCost: models.reduce((sum, model) => sum + Number(model.cost_usd ?? 0), 0),
+    buckets,
+    usageModels: buckets.usage.models,
+    fixedModels: buckets.fixed.models,
+    creditModels: buckets.credits.models,
+    unknownModels: buckets.unknown.models,
+  };
+}