feat: backup restore rehydrate, server timezone API, and scoped provider reload (#34)

Restore syncs providers and reloads agents in-process; rename cron_timezone to
default_timezone with GET /api/settings/timezone; reload only impacted agents
after provider changes; align dashboard timestamps to the server timezone.

Co-authored-by: jubaoliang <jubaoliang@tencent.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

AGENTS.md

@@ -257,6 +257,20 @@ i18n/
 
 Do **not** use gettext (`.po` files). Do **not** embed user-visible English in `infra/` when a backend i18n key exists. Expert catalog (`infra/agents/experts/`) still uses embedded `label_zh`/`label_en` in source data — out of scope unless explicitly migrating that catalog.
 
+**Timezone (config.json):**
+
+User-facing datetime display and cron/scheduling defaults MUST use the server timezone from `config.json` → `default_timezone` (env override `OCTOP_DEFAULT_TIMEZONE`; legacy `cron_timezone` / `OCTOP_CRON_TIMEZONE` still accepted) — not the browser's local timezone.
+
+| Layer | Entry |
+|-------|--------|
+| Config | `OctopConfig.default_timezone` in `config.py` |
+| API | `GET /api/settings/timezone` → `{ "timezone": "…" }` (`GET /api/cron/settings` remains a compat alias) |
+| Dashboard | `useServerTimezone()`; format with `formatServerDateTime` / `formatServerIsoDateTime` / `formatMessageTime(..., timeZone)` in `dashboard/src/utils/formatMessageTime.ts` |
+
+**Do not** use bare `toLocaleString()` / `toLocaleDateString()` / `toLocaleTimeString()` for timestamps users see without passing the server `timeZone`. Number grouping via `Number#toLocaleString()` (e.g. download counts) is fine.
+
+**Language:** Keep the existing locale resolution (user preference → `Accept-Language` / dashboard i18n → channel hints → `DEFAULT_LOCALE`). Language is **not** a `config.json` key — do not add one unless explicitly requested.
+
 **Workspace storage:** `infra/backend/resolver.py` resolves harness `BackendProtocol` from agent config; remote backends use `probe.py` for fast tree listing.
 
 **Connectors:** `infra/connectors/` — catalog, OAuth registry, MCP gateway; HTTP surface in `api/routers/connectors.py`.
@@ -312,6 +326,7 @@ Boundary rules are in [§5](#5-module-boundaries). Additionally:
 | How does the frontend call the API? | `dashboard/src/api/request.ts` |
 | Internationalization (backend) | `src/octop/i18n/`, `infra/utils/locale.py`, `api/routers/i18n.py` |
 | Internationalization (dashboard) | `dashboard/src/locales/`, `dashboard/src/i18n.ts`, `dashboard/src/utils/apiError.ts` |
+| Server timezone (config.json) | `default_timezone` in `config.py`; `GET /api/settings/timezone`; `dashboard/src/hooks/useServerTimezone.ts`; `dashboard/src/utils/formatMessageTime.ts` |
 | Test layout & shared helpers | `tests/support/` (`fakes`, `auth`, `http`, `scenarios`, `app`), `tests/integration/conftest.py`, `tests/unit/{db,cron,gateway,agents,api,cli}/` |
 | What is a Thread? | `infra/gateway/threads.py`, `infra/db/repos/threads.py` |
 | Workspace backend resolution | `infra/backend/resolver.py`, `infra/backend/adapter.py` |

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="snapshots/banner.png" alt="Octop Banner" width="600" />
+  <img src="docs/assets/readme-banner.png" alt="Octop Banner" width="600" />
 </p>
 
 <p align="center">
@@ -326,7 +326,7 @@ Full reference: **[docs/cli.md](docs/cli.md)**.
 After `octop run`, open **http://127.0.0.1:8088**.
 
 <p align="center">
-  <img src="snapshots/chat.png" alt="Octop Web Dashboard" width="800" />
+  <img src="docs/assets/readme-chat.png" alt="Octop Web Dashboard" width="800" />
 </p>
 
 - **Chat** — real-time conversation with agents

README_CN.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="snapshots/banner.png" alt="Octop Banner" width="600" />
+  <img src="docs/assets/readme-banner-zh.png" alt="Octop Banner" width="600" />
 </p>
 
 <p align="center">
@@ -332,7 +332,7 @@ OpenAI 兼容 API、DashScope（千问）、Ollama 等预设 — 在控制台或
 `octop run` 启动后访问 **http://127.0.0.1:8088**。
 
 <p align="center">
-  <img src="snapshots/chat_zh.png" alt="Octop Web 控制台" width="800" />
+  <img src="docs/assets/readme-chat-zh.png" alt="Octop Web 控制台" width="800" />
 </p>
 
 - **对话** — 与 Agent 实时聊天

dashboard/src/api/modules/backup.ts

@@ -4,6 +4,7 @@ export interface BackupFileItem {
   name: string;
   size: number;
   modified_at: string;
+  created_at: string;
 }
 
 export interface BackupListResponse {
@@ -48,10 +49,11 @@ export const backupApi = {
   /** Upload archive into backups dir (does not restore). */
   uploadBackup: (
     file: File,
+    onProgress?: (percent: number) => void,
   ): Promise<{ ok: boolean; item: BackupFileItem }> => {
     const formData = new FormData();
     formData.append("file", file);
-    return requestUpload("/admin/backup/import", formData);
+    return requestUpload("/admin/backup/import", formData, {}, onProgress);
   },
 
   /** Ephemeral download without saving to backups dir. */

dashboard/src/api/modules/settings.ts

@@ -0,0 +1,9 @@
+import { request } from "../request";
+
+export interface OctopTimezoneSettings {
+  timezone: string;
+}
+
+export const octopSettingsApi = {
+  timezone: () => request<OctopTimezoneSettings>("/settings/timezone"),
+};

dashboard/src/api/request.ts

@@ -288,42 +288,116 @@ export async function requestBlob(
   return response.blob();
 }
 
+export type UploadProgressHandler = (percent: number) => void;
+
 /**
  * Upload a FormData payload (no explicit Content-Type — browser handles boundary).
+ * Uses XMLHttpRequest so callers can report upload progress.
  */
 export async function requestUpload<T = unknown>(
   path: string,
   body: FormData,
   options: RequestInit = {},
+  onProgress?: UploadProgressHandler,
 ): Promise<T> {
   const url = getApiUrl(path);
   const headers = buildAuthHeaders(path);
+  const method = options.method ?? "POST";
 
-  const response = await fetch(url, {
-    method: "POST",
-    ...options,
-    headers: { ...headers, ...(options.headers as Record<string, string>) },
-    body,
-  });
+  return new Promise<T>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(method, url);
 
-  if (await check503ForSetupRequired(path, response)) {
-    throw new Error("Setup required — redirecting to /setup");
-  }
+    for (const [key, value] of Object.entries(headers)) {
+      xhr.setRequestHeader(key, value);
+    }
+    if (options.headers) {
+      const extraEntries =
+        options.headers instanceof Headers
+          ? Array.from(options.headers.entries())
+          : Array.isArray(options.headers)
+          ? options.headers
+          : Object.entries(options.headers);
+      for (const [k, v] of extraEntries) {
+        xhr.setRequestHeader(k, String(v));
+      }
+    }
 
-  await throwIfUnauthorized(path, response);
-  applyRenewedAccessToken(response);
+    if (onProgress) {
+      xhr.upload.onprogress = (event) => {
+        if (event.lengthComputable && event.total > 0) {
+          onProgress(Math.round((event.loaded / event.total) * 100));
+        }
+      };
+    }
 
-  if (!response.ok) {
-    const text = await response.text().catch(() => "");
-    let detail = `Upload failed: ${response.status}`;
-    try {
-      const json = JSON.parse(text);
-      if (json.detail) detail = json.detail;
-    } catch {
-      if (text) detail = text;
+    if (options.signal) {
+      if (options.signal.aborted) {
+        reject(new DOMException("The operation was aborted.", "AbortError"));
+        return;
+      }
+      options.signal.addEventListener(
+        "abort",
+        () => {
+          xhr.abort();
+        },
+        { once: true },
+      );
     }
-    throw new Error(detail);
-  }
 
-  return (await response.json()) as T;
+    xhr.onload = () => {
+      void (async () => {
+        const status = xhr.status;
+        const responseText = xhr.responseText;
+        const responseHeaders = new Headers();
+        const renewed = xhr.getResponseHeader(ACCESS_TOKEN_RESPONSE_HEADER);
+        if (renewed) {
+          responseHeaders.set(ACCESS_TOKEN_RESPONSE_HEADER, renewed);
+        }
+        const response = new Response(responseText, {
+          status,
+          headers: responseHeaders,
+        });
+
+        if (await check503ForSetupRequired(path, response)) {
+          reject(new Error("Setup required — redirecting to /setup"));
+          return;
+        }
+
+        try {
+          await throwIfUnauthorized(path, response);
+        } catch (err) {
+          reject(err);
+          return;
+        }
+
+        applyRenewedAccessToken(response);
+
+        if (!response.ok) {
+          const text = responseText;
+          let detail = `Upload failed: ${status}`;
+          try {
+            const json = JSON.parse(text) as { detail?: string };
+            if (json.detail) detail = json.detail;
+          } catch {
+            if (text) detail = text;
+          }
+          reject(new Error(detail));
+          return;
+        }
+
+        try {
+          resolve((await response.json()) as T);
+        } catch {
+          reject(new Error("Upload failed: invalid JSON response"));
+        }
+      })();
+    };
+
+    xhr.onerror = () => reject(new Error("Network error"));
+    xhr.onabort = () =>
+      reject(new DOMException("The operation was aborted.", "AbortError"));
+
+    xhr.send(body);
+  });
 }

dashboard/src/hooks/useServerTimezone.ts

@@ -1,14 +1,14 @@
 import { useEffect, useState } from "react";
-import { octopCronApi } from "../api/modules/cronjob";
+import { octopSettingsApi } from "../api/modules/settings";
 
 let cachedTimezone: string | null = null;
 let inflight: Promise<string> | null = null;
 
 async function fetchServerTimezone(): Promise<string> {
   if (cachedTimezone) return cachedTimezone;
   if (!inflight) {
-    inflight = octopCronApi
-      .settings()
+    inflight = octopSettingsApi
+      .timezone()
       .then((settings) => {
         cachedTimezone = settings.timezone?.trim() || "UTC";
         return cachedTimezone;
@@ -24,7 +24,7 @@ async function fetchServerTimezone(): Promise<string> {
   return inflight;
 }
 
-/** Server timezone from config.json `cron_timezone` (via GET /api/cron/settings). */
+/** Server timezone from config.json `default_timezone` (via GET /api/settings/timezone). */
 export function useServerTimezone(): string {
   const [timezone, setTimezone] = useState(cachedTimezone ?? "UTC");
 

dashboard/src/layouts/Sidebar.tsx

@@ -137,7 +137,6 @@ function buildNavGroups(role: "admin" | "user" | null): NavGroup[] {
           path: "/experts",
           icon: <GraduationCap size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.experts",
-          badge: "new",
         },
         {
           key: "tasks",
@@ -150,7 +149,6 @@ function buildNavGroups(role: "admin" | "user" | null): NavGroup[] {
           path: "/connectors",
           icon: <Link2 size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.connectors",
-          badge: "new",
         },
         {
           key: "token-usage",
@@ -181,7 +179,6 @@ function buildNavGroups(role: "admin" | "user" | null): NavGroup[] {
           path: "/subagents",
           icon: <Bot size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.subagents",
-          badge: "new",
         },
         {
           key: "terminal",
@@ -200,14 +197,12 @@ function buildNavGroups(role: "admin" | "user" | null): NavGroup[] {
           path: "/remote-desktop",
           icon: <Monitor size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.remoteDesktop",
-          badge: "new",
         },
         {
           key: "acp",
           path: "/acp",
           icon: <Share2 size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.acp",
-          badge: "new",
         },
         {
           key: "mbti",
@@ -246,7 +241,6 @@ function buildNavGroups(role: "admin" | "user" | null): NavGroup[] {
           path: "/admin/backend",
           icon: <FolderOpen size={iconSize} strokeWidth={iconStroke} />,
           labelKey: "nav.adminStorage",
-          badge: "new",
         },
         {
           key: "admin-audit",

dashboard/src/locales/en.json

@@ -751,6 +751,7 @@
     "emptyList": "No backup files yet",
     "colName": "Filename",
     "colSize": "Size",
+    "colCreated": "Created",
     "colModified": "Modified",
     "colActions": "Actions",
     "restoreAction": "Restore",
@@ -763,15 +764,17 @@
     "exportSuccess": "Backup download started",
     "exportFailed": "Download failed",
     "importTitle": "Import backup",
-    "importDesc": "Restore from a previously exported .tar.gz archive. Prefer a maintenance window; restart the server after restore.",
+    "importDesc": "Restore from a previously exported .tar.gz archive. Prefer a maintenance window.",
     "importButton": "Choose backup file",
-    "importWarning": "Restore overwrites the current database and local workspaces. This cannot be undone.",
+    "uploading": "Uploading… {{percent}}%",
+    "restoring": "Restoring…",
+    "importWarning": "Restore overwrites the current database and local workspaces, then hot-reloads models and experts. If you also restore config/env, restart the service manually for those to fully apply. This cannot be undone.",
     "importConfirmTitle": "Confirm restore",
-    "importConfirmBody": "Restore from “{{name}}”? Existing data will be overwritten.",
+    "importConfirmBody": "Restore from “{{name}}”? Existing data will be overwritten. Models and experts are hot-reloaded afterward (no service restart). If you restore config/env, restart manually for those settings to take full effect.",
     "importConfirmOk": "Restore",
     "importSuccess": "Restore complete ({{agents}} agents, {{files}} workspace files)",
     "importFailed": "Failed to restore backup",
-    "restoreConfig": "Also restore config.json and env"
+    "restoreConfig": "Also restore config.json and env (requires a manual service restart to apply)"
   },
   "skills": {
     "title": "Skills",
@@ -964,7 +967,7 @@
       "cronTooltip": "Standard 5-field cron expression: minute hour day month weekday.",
       "cronExamples": "Examples: 0 9 * * * (daily at 9am) | */30 * * * * (every 30min) | 0 9 * * 1 (Mon 9am)",
       "timezone": "Timezone",
-      "timezoneTooltip": "Server-wide scheduler timezone from config.json (cron_timezone) or OCTOP_CRON_TIMEZONE. Shared by all cron jobs.",
+      "timezoneTooltip": "Server-wide default timezone from config.json (default_timezone) or OCTOP_DEFAULT_TIMEZONE. Used for scheduling and dashboard timestamps.",
       "sectionTask": "Task Content",
       "sectionTaskDesc": "Define what to do when triggered.",
       "taskType": "Task Type",

dashboard/src/locales/zh.json

@@ -748,6 +748,7 @@
     "emptyList": "暂无备份文件",
     "colName": "文件名",
     "colSize": "大小",
+    "colCreated": "创建时间",
     "colModified": "修改时间",
     "colActions": "操作",
     "restoreAction": "恢复",
@@ -760,15 +761,17 @@
     "exportSuccess": "备份已开始下载",
     "exportFailed": "下载失败",
     "importTitle": "导入备份",
-    "importDesc": "从先前导出的 .tar.gz 归档恢复系统。建议在维护窗口操作，恢复后重启服务。",
+    "importDesc": "从先前导出的 .tar.gz 归档恢复系统。建议在维护窗口操作。",
     "importButton": "选择备份文件",
-    "importWarning": "恢复将覆盖当前数据库与本地工作区，操作不可撤销。",
+    "uploading": "正在上传… {{percent}}%",
+    "restoring": "正在恢复…",
+    "importWarning": "恢复将覆盖当前数据库与本地工作区，并热加载模型与专家。若同时恢复了 config/env，完整生效仍需手动重启服务。此操作不可撤销。",
     "importConfirmTitle": "确认恢复备份",
-    "importConfirmBody": "确定从「{{name}}」恢复？这将覆盖现有数据。",
+    "importConfirmBody": "确定从「{{name}}」恢复？这将覆盖现有数据。恢复后会热加载模型与专家，无需重启服务；若勾选恢复配置，config/env 需重启后才完全生效。",
     "importConfirmOk": "恢复",
     "importSuccess": "恢复完成（{{agents}} 个 Agent，{{files}} 个工作区文件）",
     "importFailed": "恢复备份失败",
-    "restoreConfig": "同时恢复 config.json 与 env"
+    "restoreConfig": "同时恢复 config.json 与 env（需手动重启服务后生效）"
   },
   "skills": {
     "title": "技能",
@@ -960,7 +963,7 @@
       "cronTooltip": "标准 5 位 Cron 表达式，格式：分 时 日 月 周。",
       "cronExamples": "示例：0 9 * * *（每天9点）| */30 * * * *（每30分钟）| 0 9 * * 1（每周一9点）",
       "timezone": "时区",
-      "timezoneTooltip": "服务端调度时区，在 config.json 的 cron_timezone 或环境变量 OCTOP_CRON_TIMEZONE 中配置，所有定时任务共用。",
+      "timezoneTooltip": "服务端默认时区，在 config.json 的 default_timezone 或环境变量 OCTOP_DEFAULT_TIMEZONE 中配置，用于定时任务与界面时间展示。",
       "sectionTask": "任务内容",
       "sectionTaskDesc": "定义触发时要做什么。",
       "taskType": "任务类型",