@chrysb/alphaclaw 0.4.6-beta.9 → 0.5.1-beta.0

package/lib/public/js/components/usage-tab/index.js

@@ -2,6 +2,7 @@ import { h } from "https://esm.sh/preact";
 import htm from "https://esm.sh/htm";
 import { ActionButton } from "../action-button.js";
 import { PageHeader } from "../page-header.js";
+import { showToast } from "../toast.js";
 import { OverviewSection } from "./overview-section.js";
 import { SessionsSection } from "./sessions-section.js";
 import { useUsageTab } from "./use-usage-tab.js";
@@ -26,6 +27,20 @@ export const UsageTab = ({ sessionId = "" }) => {
     );
   };
 
+  const handleRunBackfill = async () => {
+    try {
+      const result = await actions.triggerBackfill();
+      const backfilledEvents = Number(result?.backfilledEvents || 0);
+      const filesScanned = Number(result?.filesScanned || 0);
+      showToast(
+        `Imported ${backfilledEvents.toLocaleString()} usage events from ${filesScanned.toLocaleString()} session files`,
+        "success",
+      );
+    } catch (error) {
+      showToast(error.message || "Could not import historical usage data", "error");
+    }
+  };
+
   return html`
     <div class="space-y-4">
       <${PageHeader}
@@ -46,6 +61,34 @@ export const UsageTab = ({ sessionId = "" }) => {
             ${state.error}
           </div>`
         : null}
+      ${state.showBackfillBanner
+        ? html`
+            <div class="bg-surface border border-border rounded-xl p-4 space-y-3">
+              <p class="text-xs text-gray-300 leading-5">
+                We found historical usage data from
+                <span class="font-medium text-gray-200"
+                  >${Number(state.estimatedBackfillFiles || 0).toLocaleString()}</span
+                >
+                session files. Import it?
+              </p>
+              <div class="flex flex-wrap items-center gap-2">
+                <${ActionButton}
+                  onClick=${handleRunBackfill}
+                  loading=${state.runningBackfill}
+                  disabled=${state.loadingBackfillStatus}
+                  idleLabel="Import historical data"
+                  loadingLabel="Importing..."
+                />
+                <${ActionButton}
+                  onClick=${actions.dismissBackfillBanner}
+                  tone="secondary"
+                  disabled=${state.runningBackfill}
+                  idleLabel="Dismiss"
+                />
+              </div>
+            </div>
+          `
+        : null}
       ${state.loadingSummary && !state.summary
         ? html`<div class="text-sm text-[var(--text-muted)]">Loading usage summary...</div>`
         : html`

package/lib/public/js/components/usage-tab/overview-section.js

@@ -31,8 +31,9 @@ const getCacheHitRateValueClass = (ratio) => {
 const getOverviewMetrics = (summary) => {
   const totals = summary?.totals || {};
   const cacheReadTokens = Number(totals.cacheReadTokens || 0);
+  const cacheWriteTokens = Number(totals.cacheWriteTokens || 0);
   const inputTokens = Number(totals.inputTokens || 0);
-  const promptTokens = inputTokens + cacheReadTokens;
+  const promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens;
   const turnCount = Number(totals.turnCount || 0);
   const totalTokens = Number(totals.totalTokens || 0);
   const totalCost = Number(totals.totalCost || 0);

package/lib/public/js/components/usage-tab/use-usage-tab.js

@@ -6,9 +6,11 @@ import {
   useState,
 } from "https://esm.sh/preact/hooks";
 import {
+  fetchUsageBackfillStatus,
   fetchUsageSessionDetail,
   fetchUsageSessions,
   fetchUsageSummary,
+  runUsageBackfill,
 } from "../../lib/api.js";
 import { formatInteger, formatUsd } from "../../lib/format.js";
 import { readUiSettings, writeUiSettings } from "../../lib/ui-settings.js";
@@ -41,6 +43,10 @@ export const useUsageTab = ({ sessionId = "" }) => {
   const [loadingSummary, setLoadingSummary] = useState(false);
   const [loadingSessions, setLoadingSessions] = useState(false);
   const [loadingDetailById, setLoadingDetailById] = useState({});
+  const [loadingBackfillStatus, setLoadingBackfillStatus] = useState(false);
+  const [runningBackfill, setRunningBackfill] = useState(false);
+  const [showBackfillBanner, setShowBackfillBanner] = useState(false);
+  const [estimatedBackfillFiles, setEstimatedBackfillFiles] = useState(0);
   const [expandedSessionIds, setExpandedSessionIds] = useState(() =>
     sessionId ? [String(sessionId)] : [],
   );
@@ -96,6 +102,37 @@ export const useUsageTab = ({ sessionId = "" }) => {
     }
   }, []);
 
+  const loadBackfillStatus = useCallback(async () => {
+    setLoadingBackfillStatus(true);
+    try {
+      const data = await fetchUsageBackfillStatus();
+      const available = !!data?.available;
+      setShowBackfillBanner(available);
+      setEstimatedBackfillFiles(Number(data?.estimatedFiles || 0));
+    } catch {
+      setShowBackfillBanner(false);
+      setEstimatedBackfillFiles(0);
+    } finally {
+      setLoadingBackfillStatus(false);
+    }
+  }, []);
+
+  const triggerBackfill = useCallback(async () => {
+    setRunningBackfill(true);
+    try {
+      const result = await runUsageBackfill();
+      setShowBackfillBanner(false);
+      await loadSummary();
+      await loadSessions();
+      return result;
+    } catch (err) {
+      setError(err.message || "Could not backfill usage data");
+      throw err;
+    } finally {
+      setRunningBackfill(false);
+    }
+  }, [loadSessions, loadSummary]);
+
   useEffect(() => {
     loadSummary();
   }, [loadSummary]);
@@ -111,6 +148,10 @@ export const useUsageTab = ({ sessionId = "" }) => {
     loadSessions();
   }, [loadSessions]);
 
+  useEffect(() => {
+    loadBackfillStatus();
+  }, [loadBackfillStatus]);
+
   useEffect(() => {
     const safeSessionId = String(sessionId || "").trim();
     if (!safeSessionId) return;
@@ -256,6 +297,10 @@ export const useUsageTab = ({ sessionId = "" }) => {
       loadingSummary,
       loadingSessions,
       loadingDetailById,
+      loadingBackfillStatus,
+      runningBackfill,
+      showBackfillBanner,
+      estimatedBackfillFiles,
       expandedSessionIds,
       error,
       periodSummary,
@@ -265,6 +310,9 @@ export const useUsageTab = ({ sessionId = "" }) => {
       setDays,
       setMetric,
       loadSummary,
+      loadBackfillStatus,
+      triggerBackfill,
+      dismissBackfillBanner: () => setShowBackfillBanner(false),
       loadSessionDetail,
       setExpandedSessionIds,
     },

package/lib/public/js/lib/api.js

@@ -345,6 +345,20 @@ export async function fetchUsageSessionTimeSeries(sessionId, maxPoints = 100) {
   return parseJsonOrThrow(res, "Could not load usage time series");
 }
 
+export async function fetchUsageBackfillStatus() {
+  const res = await authFetch("/api/usage/backfill/status");
+  return parseJsonOrThrow(res, "Could not load usage backfill status");
+}
+
+export async function runUsageBackfill() {
+  const res = await authFetch("/api/usage/backfill", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({}),
+  });
+  return parseJsonOrThrow(res, "Could not backfill usage data");
+}
+
 export async function fetchWatchdogEvents(limit = 20) {
   const res = await authFetch(
     `/api/watchdog/events?limit=${encodeURIComponent(String(limit))}`,

package/lib/server/db/usage/backfill.js

@@ -0,0 +1,416 @@
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const kSessionsStoreFileName = "sessions.json";
+const kSessionFileSuffix = ".jsonl";
+
+const toFiniteNumber = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+};
+
+const toNonNegativeInt = (value) => {
+  const parsed = toFiniteNumber(value);
+  if (parsed === undefined) return undefined;
+  if (parsed <= 0) return 0;
+  return Math.floor(parsed);
+};
+
+const normalizeUsage = (rawUsage) => {
+  if (!rawUsage || typeof rawUsage !== "object") return null;
+  const inputTokens = toNonNegativeInt(
+    rawUsage.input ??
+      rawUsage.inputTokens ??
+      rawUsage.input_tokens ??
+      rawUsage.promptTokens ??
+      rawUsage.prompt_tokens,
+  );
+  const outputTokens = toNonNegativeInt(
+    rawUsage.output ??
+      rawUsage.outputTokens ??
+      rawUsage.output_tokens ??
+      rawUsage.completionTokens ??
+      rawUsage.completion_tokens,
+  );
+  const cacheReadTokens = toNonNegativeInt(
+    rawUsage.cacheRead ??
+      rawUsage.cache_read ??
+      rawUsage.cache_read_input_tokens ??
+      rawUsage.cached_tokens ??
+      rawUsage.prompt_tokens_details?.cached_tokens,
+  );
+  const cacheWriteTokens = toNonNegativeInt(
+    rawUsage.cacheWrite ??
+      rawUsage.cache_write ??
+      rawUsage.cache_creation_input_tokens,
+  );
+  const totalTokens = toNonNegativeInt(
+    rawUsage.total ?? rawUsage.totalTokens ?? rawUsage.total_tokens,
+  );
+  if (
+    inputTokens === undefined &&
+    outputTokens === undefined &&
+    cacheReadTokens === undefined &&
+    cacheWriteTokens === undefined &&
+    totalTokens === undefined
+  ) {
+    return null;
+  }
+
+  const normalized = {
+    inputTokens: inputTokens ?? 0,
+    outputTokens: outputTokens ?? 0,
+    cacheReadTokens: cacheReadTokens ?? 0,
+    cacheWriteTokens: cacheWriteTokens ?? 0,
+    totalTokens:
+      totalTokens ??
+      (inputTokens ?? 0) +
+        (outputTokens ?? 0) +
+        (cacheReadTokens ?? 0) +
+        (cacheWriteTokens ?? 0),
+  };
+  if (normalized.totalTokens <= 0) return null;
+  return normalized;
+};
+
+const parseTimestampMs = (entry) => {
+  const rawTimestamp = toFiniteNumber(entry?.timestamp);
+  if (rawTimestamp !== undefined && rawTimestamp > 0) {
+    return Math.floor(rawTimestamp);
+  }
+
+  const rawTimestampIso = String(entry?.timestamp || "").trim();
+  if (rawTimestampIso) {
+    const parsedDate = new Date(rawTimestampIso);
+    const parsedMs = parsedDate.valueOf();
+    if (Number.isFinite(parsedMs) && parsedMs > 0) return parsedMs;
+  }
+
+  const messageTimestamp = toFiniteNumber(entry?.message?.timestamp);
+  if (messageTimestamp !== undefined && messageTimestamp > 0) {
+    return Math.floor(messageTimestamp);
+  }
+  return null;
+};
+
+const toDayKey = (timestampMs) =>
+  new Date(Number(timestampMs || 0)).toISOString().slice(0, 10);
+
+const resolveSessionsDir = (openclawDir) =>
+  path.join(String(openclawDir || ""), "agents", "main", "sessions");
+
+const listBackfillCandidateFiles = ({
+  openclawDir,
+  earliestExistingTimestampMs = null,
+  fsModule = fs,
+}) => {
+  const sessionsDir = resolveSessionsDir(openclawDir);
+  if (!sessionsDir || !fsModule.existsSync(sessionsDir)) return [];
+  const entries = fsModule.readdirSync(sessionsDir, { withFileTypes: true });
+  const candidateFiles = [];
+  for (const entry of entries) {
+    if (!entry?.isFile?.()) continue;
+    const fileName = String(entry.name || "");
+    if (!fileName.endsWith(kSessionFileSuffix)) continue;
+    if (!earliestExistingTimestampMs || earliestExistingTimestampMs <= 0) {
+      candidateFiles.push(fileName);
+      continue;
+    }
+    const absolutePath = path.join(sessionsDir, fileName);
+    try {
+      const stats = fsModule.statSync(absolutePath);
+      if (Number(stats?.mtimeMs || 0) < earliestExistingTimestampMs) {
+        candidateFiles.push(fileName);
+      }
+    } catch {}
+  }
+  return candidateFiles.sort((leftValue, rightValue) =>
+    leftValue.localeCompare(rightValue),
+  );
+};
+
+const getEarliestUsageTimestampMs = (database) => {
+  const row = database
+    .prepare("SELECT MIN(timestamp) AS earliest_timestamp FROM usage_events")
+    .get();
+  const parsed = toNonNegativeInt(row?.earliest_timestamp);
+  return parsed && parsed > 0 ? parsed : null;
+};
+
+const readSessionsStore = ({ sessionsDir, fsModule = fs }) => {
+  const sessionsStorePath = path.join(sessionsDir, kSessionsStoreFileName);
+  if (!fsModule.existsSync(sessionsStorePath)) return {};
+  try {
+    const raw = fsModule.readFileSync(sessionsStorePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+
+const buildSessionContextByFileName = ({ sessionsDir, fsModule = fs }) => {
+  const sessionStore = readSessionsStore({ sessionsDir, fsModule });
+  const byFileName = new Map();
+  for (const [sessionKey, entry] of Object.entries(sessionStore)) {
+    const safeSessionKey = String(sessionKey || "").trim();
+    if (!safeSessionKey) continue;
+    const rawSessionId = String(entry?.sessionId || "").trim();
+    const rawSessionFile = String(entry?.sessionFile || "").trim();
+    const baseContext = {
+      sessionKey: safeSessionKey,
+      sessionId: rawSessionId,
+    };
+    if (rawSessionFile) {
+      byFileName.set(path.basename(rawSessionFile), baseContext);
+    }
+    if (rawSessionId) {
+      byFileName.set(`${rawSessionId}${kSessionFileSuffix}`, baseContext);
+    }
+  }
+  return byFileName;
+};
+
+const resolveSessionContext = ({ fileName, sessionContextByFileName }) => {
+  const mappedContext = sessionContextByFileName.get(fileName) || null;
+  if (mappedContext) return mappedContext;
+  return {
+    sessionKey: "",
+    sessionId: String(fileName || "").replace(/\.jsonl$/i, ""),
+  };
+};
+
+const scanUsageRecordsFromFile = async ({
+  filePath,
+  onRecord = () => {},
+  onSkip = () => {},
+  earliestExistingTimestampMs = null,
+}) => {
+  const stream = fs.createReadStream(filePath, { encoding: "utf8" });
+  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const rawLine of lines) {
+      const trimmedLine = String(rawLine || "").trim();
+      if (!trimmedLine) {
+        onSkip();
+        continue;
+      }
+      let parsed = null;
+      try {
+        parsed = JSON.parse(trimmedLine);
+      } catch {
+        onSkip();
+        continue;
+      }
+      const message = parsed?.message;
+      if (!message || typeof message !== "object") {
+        onSkip();
+        continue;
+      }
+      if (String(message.role || "").trim() !== "assistant") {
+        onSkip();
+        continue;
+      }
+      const usage = normalizeUsage(message.usage ?? parsed?.usage);
+      if (!usage) {
+        onSkip();
+        continue;
+      }
+      const timestampMs = parseTimestampMs(parsed);
+      if (!timestampMs) {
+        onSkip();
+        continue;
+      }
+      if (
+        earliestExistingTimestampMs &&
+        timestampMs >= earliestExistingTimestampMs
+      ) {
+        onSkip();
+        continue;
+      }
+      const provider =
+        String(message.provider || parsed?.provider || "").trim() || "unknown";
+      const model = String(message.model || parsed?.model || "").trim() || "unknown";
+      const runId =
+        String(
+          parsed?.runId ||
+            parsed?.run_id ||
+            message?.runId ||
+            message?.run_id ||
+            "",
+        ).trim() || "";
+      onRecord({
+        timestampMs,
+        provider,
+        model,
+        runId,
+        ...usage,
+      });
+    }
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+};
+
+const getBackfillStatus = ({ database, openclawDir, fsModule = fs }) => {
+  if (!database) throw new Error("Usage DB is not initialized");
+  const earliestExistingTimestampMs = getEarliestUsageTimestampMs(database);
+  const files = listBackfillCandidateFiles({
+    openclawDir,
+    earliestExistingTimestampMs,
+    fsModule,
+  });
+  return {
+    available: files.length > 0,
+    estimatedFiles: files.length,
+    earliestExistingTimestampMs,
+  };
+};
+
+const backfillFromTranscripts = async ({
+  database,
+  openclawDir,
+  fsModule = fs,
+}) => {
+  if (!database) throw new Error("Usage DB is not initialized");
+  const earliestExistingTimestampMs = getEarliestUsageTimestampMs(database);
+  const sessionsDir = resolveSessionsDir(openclawDir);
+  const files = listBackfillCandidateFiles({
+    openclawDir,
+    earliestExistingTimestampMs,
+    fsModule,
+  });
+  const sessionContextByFileName = buildSessionContextByFileName({
+    sessionsDir,
+    fsModule,
+  });
+
+  const insertUsageEventStmt = database.prepare(`
+    INSERT INTO usage_events (
+      timestamp,
+      session_id,
+      session_key,
+      run_id,
+      provider,
+      model,
+      input_tokens,
+      output_tokens,
+      cache_read_tokens,
+      cache_write_tokens,
+      total_tokens
+    ) VALUES (
+      $timestamp,
+      $session_id,
+      $session_key,
+      $run_id,
+      $provider,
+      $model,
+      $input_tokens,
+      $output_tokens,
+      $cache_read_tokens,
+      $cache_write_tokens,
+      $total_tokens
+    )
+  `);
+  const upsertUsageDailyStmt = database.prepare(`
+    INSERT INTO usage_daily (
+      date,
+      model,
+      provider,
+      input_tokens,
+      output_tokens,
+      cache_read_tokens,
+      cache_write_tokens,
+      total_tokens,
+      turn_count
+    ) VALUES (
+      $date,
+      $model,
+      $provider,
+      $input_tokens,
+      $output_tokens,
+      $cache_read_tokens,
+      $cache_write_tokens,
+      $total_tokens,
+      1
+    )
+    ON CONFLICT(date, model) DO UPDATE SET
+      provider = COALESCE(excluded.provider, usage_daily.provider),
+      input_tokens = usage_daily.input_tokens + excluded.input_tokens,
+      output_tokens = usage_daily.output_tokens + excluded.output_tokens,
+      cache_read_tokens = usage_daily.cache_read_tokens + excluded.cache_read_tokens,
+      cache_write_tokens = usage_daily.cache_write_tokens + excluded.cache_write_tokens,
+      total_tokens = usage_daily.total_tokens + excluded.total_tokens,
+      turn_count = usage_daily.turn_count + 1
+  `);
+
+  let backfilledEvents = 0;
+  let skippedEvents = 0;
+  let filesScanned = 0;
+  database.exec("BEGIN");
+  try {
+    for (const fileName of files) {
+      filesScanned += 1;
+      const filePath = path.join(sessionsDir, fileName);
+      const sessionContext = resolveSessionContext({
+        fileName,
+        sessionContextByFileName,
+      });
+      await scanUsageRecordsFromFile({
+        filePath,
+        earliestExistingTimestampMs,
+        onSkip: () => {
+          skippedEvents += 1;
+        },
+        onRecord: (record) => {
+          insertUsageEventStmt.run({
+            $timestamp: record.timestampMs,
+            $session_id: String(sessionContext.sessionId || ""),
+            $session_key: String(sessionContext.sessionKey || ""),
+            $run_id: String(record.runId || ""),
+            $provider: record.provider,
+            $model: record.model,
+            $input_tokens: record.inputTokens,
+            $output_tokens: record.outputTokens,
+            $cache_read_tokens: record.cacheReadTokens,
+            $cache_write_tokens: record.cacheWriteTokens,
+            $total_tokens: record.totalTokens,
+          });
+          upsertUsageDailyStmt.run({
+            $date: toDayKey(record.timestampMs),
+            $model: record.model,
+            $provider: record.provider,
+            $input_tokens: record.inputTokens,
+            $output_tokens: record.outputTokens,
+            $cache_read_tokens: record.cacheReadTokens,
+            $cache_write_tokens: record.cacheWriteTokens,
+            $total_tokens: record.totalTokens,
+          });
+          backfilledEvents += 1;
+        },
+      });
+    }
+    database.exec("COMMIT");
+  } catch (error) {
+    database.exec("ROLLBACK");
+    throw error;
+  }
+
+  return {
+    backfilledEvents,
+    skippedEvents,
+    filesScanned,
+    cutoffMs: earliestExistingTimestampMs,
+  };
+};
+
+module.exports = {
+  getBackfillStatus,
+  backfillFromTranscripts,
+};

package/lib/server/db/usage/index.js

@@ -6,6 +6,7 @@ const { getDailySummary } = require("./summary");
 const { getSessionsList, getSessionDetail } = require("./sessions");
 const { getSessionTimeSeries } = require("./timeseries");
 const { kGlobalModelPricing } = require("./pricing");
+const { getBackfillStatus, backfillFromTranscripts } = require("./backfill");
 
 let db = null;
 let usageDbPath = "";
@@ -31,5 +32,8 @@ module.exports = {
   getSessionDetail: (options = {}) => getSessionDetail({ database: ensureDb(), ...options }),
   getSessionTimeSeries: (options = {}) =>
     getSessionTimeSeries({ database: ensureDb(), ...options }),
+  getBackfillStatus: (options = {}) => getBackfillStatus({ database: ensureDb(), ...options }),
+  backfillFromTranscripts: (options = {}) =>
+    backfillFromTranscripts({ database: ensureDb(), ...options }),
   kGlobalModelPricing,
 };

package/lib/server/routes/usage.js

@@ -1,10 +1,33 @@
 const topicRegistry = require("../topic-registry");
 const { parsePositiveInt } = require("../utils/number");
+const fs = require("fs");
+const path = require("path");
 
 const kSummaryCacheTtlMs = 60 * 1000;
 const kClientTimeZoneHeader = "x-client-timezone";
 
 const createSummaryCache = () => new Map();
+const readOnboardingMarker = ({ onboardingMarkerPath, fsModule = fs }) => {
+  const safePath = String(onboardingMarkerPath || "").trim();
+  if (!safePath || !fsModule.existsSync(safePath)) return {};
+  try {
+    const parsed = JSON.parse(fsModule.readFileSync(safePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+
+const writeOnboardingMarker = ({
+  onboardingMarkerPath,
+  marker,
+  fsModule = fs,
+}) => {
+  const safePath = String(onboardingMarkerPath || "").trim();
+  if (!safePath) return;
+  fsModule.mkdirSync(path.dirname(safePath), { recursive: true });
+  fsModule.writeFileSync(safePath, JSON.stringify(marker || {}, null, 2));
+};
 const toTitleLabel = (value) => {
   const raw = String(value || "").trim();
   if (!raw) return "";
@@ -92,6 +115,11 @@ const registerUsageRoutes = ({
   getSessionsList,
   getSessionDetail,
   getSessionTimeSeries,
+  getBackfillStatus,
+  backfillFromTranscripts,
+  openclawDir = "",
+  onboardingMarkerPath = "",
+  fsModule = fs,
 }) => {
   const summaryCache = createSummaryCache();
 
@@ -151,6 +179,58 @@ const registerUsageRoutes = ({
       res.status(500).json({ ok: false, error: err.message });
     }
   });
+
+  app.get("/api/usage/backfill/status", requireAuth, (req, res) => {
+    try {
+      const marker = readOnboardingMarker({ onboardingMarkerPath, fsModule });
+      if (String(marker?.usageBackfilledAt || "").trim()) {
+        res.json({ ok: true, available: false, estimatedFiles: 0 });
+        return;
+      }
+      const status = getBackfillStatus({ openclawDir, fsModule });
+      res.json({
+        ok: true,
+        available: !!status?.available,
+        estimatedFiles: Number(status?.estimatedFiles || 0),
+      });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  app.post("/api/usage/backfill", requireAuth, async (req, res) => {
+    try {
+      const marker = readOnboardingMarker({ onboardingMarkerPath, fsModule });
+      if (String(marker?.usageBackfilledAt || "").trim()) {
+        res.json({
+          ok: true,
+          alreadyBackfilled: true,
+          backfilledEvents: 0,
+          skippedEvents: 0,
+          filesScanned: 0,
+        });
+        return;
+      }
+      const result = await backfillFromTranscripts({ openclawDir, fsModule });
+      writeOnboardingMarker({
+        onboardingMarkerPath,
+        fsModule,
+        marker: {
+          ...marker,
+          onboarded:
+            typeof marker?.onboarded === "boolean" ? marker.onboarded : true,
+          reason: String(marker?.reason || "onboarding_complete"),
+          markedAt: String(marker?.markedAt || new Date().toISOString()),
+          usageBackfilledAt: new Date().toISOString(),
+          usageBackfilledEvents: Number(result?.backfilledEvents || 0),
+        },
+      });
+      summaryCache.clear();
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
 };
 
 module.exports = { registerUsageRoutes };

package/lib/server.js

@@ -42,6 +42,8 @@ const {
   getSessionsList,
   getSessionDetail,
   getSessionTimeSeries,
+  getBackfillStatus,
+  backfillFromTranscripts,
 } = require("./server/db/usage");
 const topicRegistry = require("./server/topic-registry");
 const {
@@ -373,6 +375,11 @@ registerUsageRoutes({
   getSessionsList,
   getSessionDetail,
   getSessionTimeSeries,
+  getBackfillStatus,
+  backfillFromTranscripts,
+  openclawDir: constants.OPENCLAW_DIR,
+  onboardingMarkerPath: constants.kOnboardingMarkerPath,
+  fsModule: fs,
 });
 registerDoctorRoutes({
   app,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrysb/alphaclaw",
-  "version": "0.4.6-beta.9",
+  "version": "0.5.1-beta.0",
   "publishConfig": {
     "access": "public"
   },