Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(web): a storage page in Settings, report-only

lmlihenge3eed00efcc8
diff --git a/packages/web/src/api/endpoints.ts b/packages/web/src/api/endpoints.ts
index f9a2de43..97bcd519 100644
--- a/packages/web/src/api/endpoints.ts
+++ b/packages/web/src/api/endpoints.ts
@@ -186,6 +186,7 @@ import type {
SessionTracesResponse,
SkillArchiveInstallRequest,
SteerRequest,
+ StorageReportResponse,
SubagentMessageResponse,
TaskCreateRequest,
TaskCreateResponse,
@@ -344,6 +345,13 @@ export const adminGetProxyProbeTargets = () =>
export const adminProbeProxy = (provider: ProxyProbeProvider) =>
apiFetch<ProxyProbeResponse>(`/api/admin/settings/proxy-probe/${provider}`, { method: "POST" });
+/**
+ * The data root's storage ledger (admin): what is on disk, by class, with the entries that
+ * matched a cleanup rule. A measurement and nothing more — the server moves and deletes no file
+ * to answer this, and no route executes a cleanup on the strength of the report it returns.
+ */
+export const adminGetStorageReport = () => apiFetch<StorageReportResponse>("/api/admin/storage");
+
// Project & members --------------------------------------------------------------
export const listProjects = () => apiFetch<ProjectsResponse>("/api/projects");
diff --git a/packages/web/src/features/settings/settings-dialog.tsx b/packages/web/src/features/settings/settings-dialog.tsx
index aada3f19..7cea2f6d 100644
--- a/packages/web/src/features/settings/settings-dialog.tsx
+++ b/packages/web/src/features/settings/settings-dialog.tsx
@@ -28,6 +28,7 @@ import { ProxySection } from "./proxy-section";
import { UploadsSection } from "./uploads-section";
import { CompanySection } from "./company-section";
import { PluginsSection } from "./plugins-section";
+import { StorageSection } from "./storage-section";
import { AdminUsersSection } from "../admin/admin-users-page";
import { CreditsSection } from "./credits-section";
@@ -54,6 +55,8 @@ const SECTION_ICONS: Record<SettingsSectionKey, string> = {
uploads: "M12 15V4m0 0L7 9m5-5l5 5M4 20h16",
/** The building the mode switch wears: company mode. */
company: ICONS.building,
+ /** A drive: the data root's storage ledger. */
+ storage: ICONS.hardDrive,
/** Puzzle piece: plugins. */
plugins:
"M10 4a2 2 0 1 1 4 0v2h3a1 1 0 0 1 1 1v3h-2a2 2 0 1 0 0 4h2v3a1 1 0 0 1-1 1h-3v-2a2 2 0 1 0-4 0v2H7a1 1 0 0 1-1-1v-3h2a2 2 0 1 0 0-4H6V7a1 1 0 0 1 1-1h3V4z",
@@ -107,6 +110,7 @@ export function SettingsDialog({
uploads: S.settings.uploadLimitsTitle,
company: S.settings.companyModeTitle,
plugins: S.settings.pluginsTitle,
+ storage: S.settings.storageTitle,
users: S.admin.users,
};
const groupLabel: Record<SettingsGroupKey, string> = {
@@ -121,6 +125,7 @@ export function SettingsDialog({
uploads: S.settings.uploadLimitsInfo(uploadLimits.attachmentMaxCount, uploadLimits.imageMaxMb),
company: S.settings.companyModeServerInfo,
plugins: S.settings.pluginsInfo,
+ storage: S.settings.storageInfo,
};
const groups: Array<PagedDialogGroup<SettingsSectionKey>> = settingsGroups(sections).map(
@@ -167,6 +172,7 @@ export function SettingsDialog({
{current === "plugins" && (
<PluginsSection {...(pluginFocus !== undefined ? { focus: pluginFocus } : {})} />
)}
+ {current === "storage" && <StorageSection />}
{current === "users" && <AdminUsersSection />}
</PagedDialog>
);
diff --git a/packages/web/src/features/settings/storage-labels.ts b/packages/web/src/features/settings/storage-labels.ts
new file mode 100644
index 00000000..b037aa1d
--- /dev/null
+++ b/packages/web/src/features/settings/storage-labels.ts
@@ -0,0 +1,61 @@
+/**
+ * The storage report's vocabulary in the reader's words (storage-section.tsx draws it).
+ *
+ * The ledger's classes and rules arrive as ids — `session_drafts`, `orphan` — because the API,
+ * the rules engine in `@lmliheng/penguin-core` (its `state/storage.ts` defines them) and a future
+ * cleanup plan all have to agree on them. A person reading the report has to recognise what
+ * `shared_env` or `budget` means, so every id is translated here, in one place, and both
+ * dictionaries carry the words (`S.settings`), so the labels follow the UI language like the
+ * rest of the app.
+ *
+ * Every map is keyed by the DTO's own union and read through it rather than being a partial list
+ * with a fallback: a fallback would quietly render a class the engine added as "Other", which is
+ * exactly the kind of claim this report must not make — the same value would then be missing from
+ * a class's figures and appear under someone else's name. Instead a new class is a type error
+ * here, and the build stops until a human decides what it is called and what clearing it costs.
+ *
+ * The strings are read through `S` at call time, not captured at module scope, so a language
+ * switch (which remounts the tree) reads the new dictionary.
+ */
+import type {
+ StorageCandidateRule,
+ StorageClass,
+ StorageEnvGroup,
+} from "@lmliheng/penguin-server/api";
+import { S } from "../../lib/strings";
+
+/** The class of `entry` in the reader's words (`protected` → 用户资产 / "User assets"). */
+export function storageClassLabel(entry: StorageClass): string {
+ return S.settings.storageClassNames[entry];
+}
+
+/**
+ * What clearing one entry of that class would cost the person — the draft images that stop
+ * previewing, the rebuild source a Trace is, the environment to install again. Shown under the
+ * class's name, so the sentence assumes the name has been read.
+ */
+export function storageClassCost(entry: StorageClass): string {
+ return S.settings.storageClassCost[entry];
+}
+
+/** Why one entry is listed as a candidate (`orphan` → 会话已删除 / "Session deleted"). */
+export function storageRuleLabel(rule: StorageCandidateRule): string {
+ return S.settings.storageRuleNames[rule];
+}
+
+/**
+ * Every rule one candidate matched, in one line. An empty list is shown as its own words rather
+ * than as an empty cell: a candidate with no recorded rule is a fact about the report, and a blank
+ * beside other rows would read as "no reason at all".
+ */
+export function storageRulesLabel(rules: readonly StorageCandidateRule[]): string {
+ if (rules.length === 0) return S.settings.storageRulesNone;
+ return rules.map(storageRuleLabel).join(" · ");
+}
+
+/** Whether a look-alike environment group was matched by name or by what it holds. */
+export function storageEnvGroupKindLabel(kind: StorageEnvGroup["kind"]): string {
+ return kind === "name"
+ ? S.settings.storageEnvGroupKindName
+ : S.settings.storageEnvGroupKindStructure;
+}
diff --git a/packages/web/src/features/settings/storage-section.tsx b/packages/web/src/features/settings/storage-section.tsx
new file mode 100644
index 00000000..2b18175a
--- /dev/null
+++ b/packages/web/src/features/settings/storage-section.tsx
@@ -0,0 +1,297 @@
+/**
+ * The storage ledger (admin only, server-global): what the data root holds, and what a person
+ * could clean up. **Read-only, and the page has to look it.** The app's default is that it keeps
+ * every byte, and there is no automatic cleanup anywhere: a future destructive step is a separate,
+ * human-reviewed one, so this page draws no delete button, no checkbox and no "clean now" — the
+ * sentences at the top say what the page is and that nothing here removes data, and the only
+ * control is measuring again.
+ *
+ * The report is one measurement of one instant (`scannedAt`), so the page replaces it wholesale
+ * rather than merging: a figure from an older walk beside a newer one cannot be told apart. It is
+ * an admin route (`GET /api/admin/storage`), hence the page-level 403 a non-admin would get — the
+ * rail already keeps them from opening it (settings-sections.ts), and this page adds no guard of
+ * its own beyond the failure it reports.
+ *
+ * A measurement walks the whole data root, so it is not free and not instant: the button says it
+ * is running and stays disabled while it does, and the first mount fires it exactly once.
+ *
+ * What the page will NOT do is round the report off. A class the scan could not read, a path it
+ * could not enter, a candidate whose mtime is unknown — each is shown as such (see `unreadable`
+ * and `StorageCandidate.lastModifiedAt`), because a report that hides its own gaps is the one
+ * thing a cleanup decision must not be based on.
+ */
+import { useCallback, useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import type { StorageReport } from "@lmliheng/penguin-server/api";
+import {
+ Button,
+ EmptyState,
+ SettingsSection,
+ Table,
+ TableBody,
+ TableCell,
+ TableHead,
+ TableHeaderCell,
+ TableRow,
+ toastError,
+} from "@lmliheng/penguin-ui";
+import * as api from "../../api/endpoints";
+import { S } from "../../lib/strings";
+import { apiErrorText } from "../../lib/api-error";
+import { formatBytes, formatDateTime } from "../../lib/format";
+import {
+ storageClassCost,
+ storageClassLabel,
+ storageEnvGroupKindLabel,
+ storageRulesLabel,
+} from "./storage-labels";
+
+/** A section of the page: its heading, an optional line saying what the heading's rows mean. */
+function Block({ title, hint, children }: { title: string; hint?: string; children: ReactNode }) {
+ return (
+ <section className="mt-6">
+ <div className="mb-2 text-sm font-medium">{title}</div>
+ {hint !== undefined && (
+ <p className="mb-3 text-xs text-gray-500 dark:text-gray-400">{hint}</p>
+ )}
+ {children}
+ </section>
+ );
+}
+
+/** The report's own header: the root, the instant it describes, the total, and the volume's numbers. */
+function ReportHeader({ report }: { report: StorageReport }) {
+ return (
+ <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-3 gap-y-1 text-xs">
+ <dt className="text-gray-500 dark:text-gray-400">{S.settings.storageRoot}</dt>
+ <dd className="min-w-0 font-mono break-all">{report.root}</dd>
+ <dt className="text-gray-500 dark:text-gray-400">{S.settings.storageMeasuredAt}</dt>
+ <dd className="tabular-nums">{formatDateTime(report.scannedAt)}</dd>
+ <dt className="text-gray-500 dark:text-gray-400">{S.settings.storageTotal}</dt>
+ <dd className="tabular-nums">{formatBytes(report.totalBytes)}</dd>
+ <dt className="text-gray-500 dark:text-gray-400">{S.settings.storageDiskFree}</dt>
+ {/* The volume's own numbers are beside the ledger, not in it: a scan can read the root and
+ still fail to learn how much room the disk has, and saying so beats leaving the row out
+ (a missing row reads as "not asked"). */}
+ <dd className="tabular-nums">
+ {report.disk === null
+ ? S.settings.storageDiskUnknown
+ : `${formatBytes(report.disk.freeBytes)} / ${formatBytes(report.disk.totalBytes)}`}
+ </dd>
+ </dl>
+ );
+}
+
+/** One row per class: what it holds, and what clearing an entry of it would cost. */
+function ClassTable({ report }: { report: StorageReport }) {
+ return (
+ <Table size="sm" tableClassName="min-w-[560px]">
+ <TableHead>
+ <TableHeaderCell>{S.settings.storageColClass}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColBytes}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColFiles}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColEntries}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColCandidateEntries}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColCandidateBytes}</TableHeaderCell>
+ </TableHead>
+ <TableBody>
+ {report.classes.map((row) => (
+ <TableRow key={row.class}>
+ <TableCell>
+ <span className="font-medium">{storageClassLabel(row.class)}</span>
+ {/* The cost line rides with the class name rather than in the candidates table: it is
+ a property of the class, and it stays on screen for a class that has no candidate
+ right now — which is when a threshold is off and the number above is zero. */}
+ <p className="mt-0.5 text-xs text-gray-500 dark:text-gray-400">
+ {storageClassCost(row.class)}
+ </p>
+ </TableCell>
+ <TableCell numeric>{formatBytes(row.bytes)}</TableCell>
+ <TableCell numeric>{row.files}</TableCell>
+ <TableCell numeric>{row.entries}</TableCell>
+ <TableCell numeric>{row.candidateEntries}</TableCell>
+ <TableCell numeric>{formatBytes(row.candidateBytes)}</TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ );
+}
+
+/** The candidate entries: what they are, how big, and what each one matched. */
+function CandidateTable({ report }: { report: StorageReport }) {
+ const columns = (
+ <TableHead>
+ <TableHeaderCell>{S.settings.storageColPath}</TableHeaderCell>
+ <TableHeaderCell>{S.settings.storageColClass}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColBytes}</TableHeaderCell>
+ <TableHeaderCell align="right">{S.settings.storageColFiles}</TableHeaderCell>
+ <TableHeaderCell>{S.settings.storageColLastModified}</TableHeaderCell>
+ <TableHeaderCell>{S.settings.storageColReferenced}</TableHeaderCell>
+ <TableHeaderCell>{S.settings.storageColRules}</TableHeaderCell>
+ </TableHead>
+ );
+ return (
+ <Block title={S.settings.storageCandidatesTitle}>
+ {report.candidates.length === 0 ? (
+ // Both halves matter: "nothing found" alone would read as "nothing to find", and the
+ // second line says why a clean list is not a clean disk (most rules are off by default).
+ <EmptyState
+ dashed
+ title={S.settings.storageCandidatesEmpty}
+ description={S.settings.storageCandidatesEmptyHint}
+ />
+ ) : (
+ <Table size="sm" tableClassName="min-w-[720px]">
+ {columns}
+ <TableBody>
+ {report.candidates.map((candidate) => (
+ <TableRow key={candidate.path}>
+ {/* The recorded path is what a future plan and a pin name, so it is shown as
+ recorded, monospaced and allowed to break. */}
+ <TableCell className="max-w-[280px] font-mono text-xs break-all">
+ {candidate.path}
+ </TableCell>
+ <TableCell className="whitespace-nowrap">
+ {storageClassLabel(candidate.class)}
+ </TableCell>
+ <TableCell numeric>{formatBytes(candidate.bytes)}</TableCell>
+ <TableCell numeric>{candidate.files}</TableCell>
+ <TableCell className="whitespace-nowrap tabular-nums">
+ {candidate.lastModifiedAt === null
+ ? S.settings.storageNeverModified
+ : formatDateTime(candidate.lastModifiedAt)}
+ </TableCell>
+ {/* Recomputed when a cleanup actually runs, never trusted from here — so the
+ column is a statement about the moment of the scan and says which. */}
+ <TableCell className="whitespace-nowrap">
+ {candidate.referenced
+ ? S.settings.storageReferencedYes
+ : S.settings.storageReferencedNo}
+ </TableCell>
+ <TableCell className="whitespace-nowrap">
+ {storageRulesLabel(candidate.rules)}
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ )}
+ </Block>
+ );
+}
+
+/**
+ * The environments that look like the same toolchain installed more than once. Listed with what
+ * they hold and how big the group is, and labelled report-only in the hint: two look-alike
+ * environments may be at different versions, so the remedy is a merge a person triggers.
+ */
+function EnvGroups({ report }: { report: StorageReport }) {
+ return (
+ <Block title={S.settings.storageEnvGroupsTitle} hint={S.settings.storageEnvGroupsHint}>
+ <ul className="divide-y divide-gray-100 text-xs dark:divide-gray-800/60">
+ {report.sharedEnvGroups.map((group) => (
+ <li key={`${group.kind}:${group.key}`} className="py-2.5 first:pt-0 last:pb-0">
+ <div className="flex items-baseline justify-between gap-3">
+ <span className="font-medium">
+ {group.key} · {storageEnvGroupKindLabel(group.kind)}
+ </span>
+ <span className="shrink-0 tabular-nums text-gray-500 dark:text-gray-400">
+ {S.settings.storageEnvGroupMembers(group.members.length)} ·{" "}
+ {formatBytes(group.bytes)}
+ </span>
+ </div>
+ <ul className="mt-1 space-y-1">
+ {group.members.map((member) => (
+ <li key={member} className="font-mono break-all text-gray-500 dark:text-gray-400">
+ {member}
+ </li>
+ ))}
+ </ul>
+ </li>
+ ))}
+ </ul>
+ </Block>
+ );
+}
+
+/**
+ * Paths the scan could not read. Rendered only when there are any, and then always: these are the
+ * report's own admission that its figures are a lower bound, which is the one thing a reader must
+ * not have to go looking for.
+ */
+function Unreadable({ report }: { report: StorageReport }) {
+ return (
+ <Block title={S.settings.storageUnreadableTitle} hint={S.settings.storageUnreadableHint}>
+ <ul className="space-y-1 text-xs">
+ {report.unreadable.map((path) => (
+ <li key={path} className="font-mono break-all text-gray-500 dark:text-gray-400">
+ {path}
+ </li>
+ ))}
+ </ul>
+ </Block>
+ );
+}
+
+export function StorageSection() {
+ /** The last measurement (null until one lands) — replaced, never patched, by the next. */
+ const [report, setReport] = useState<StorageReport | null>(null);
+ const [busy, setBusy] = useState(false);
+ /** A measurement that failed: the page says so and offers to try again. */
+ const [failed, setFailed] = useState(false);
+
+ const measure = useCallback(async () => {
+ setBusy(true);
+ setFailed(false);
+ try {
+ setReport((await api.adminGetStorageReport()).report);
+ } catch (e) {
+ // The reason is worth a toast (403, a lost session, a dead server), but the page also has
+ // to change: a spinner that never stops claims the walk is still running.
+ setFailed(true);
+ toastError(apiErrorText(e));
+ } finally {
+ setBusy(false);
+ }
+ }, []);
+
+ useEffect(() => {
+ void measure();
+ }, [measure]);
+
+ return (
+ <SettingsSection
+ actions={
+ <Button size="sm" disabled={busy} aria-busy={busy} onClick={() => void measure()}>
+ {busy ? S.settings.storageRescanning : S.settings.storageRescan}
+ </Button>
+ }
+ >
+ {/* The page's first sentence is what it is not: a report. Everything below is a figure a
+ reader could otherwise mistake for an offer to free space. */}
+ <p className="text-xs text-gray-500 dark:text-gray-400">{S.settings.storageReportOnly}</p>
+ {report === null && (
+ <p className="text-sm text-gray-400">
+ {failed ? S.settings.storageFailed : S.settings.storageLoading}
+ </p>
+ )}
+ {report !== null && (
+ <>
+ {failed && (
+ // A re-measure that failed leaves the previous report on screen — it is still the last
+ // truth about the disk — so the page has to say which one is being read.
+ <p className="text-xs text-gray-500 dark:text-gray-400">{S.settings.storageFailed}</p>
+ )}
+ <ReportHeader report={report} />
+ <Block title={S.settings.storageClassesTitle}>
+ <ClassTable report={report} />
+ </Block>
+ <CandidateTable report={report} />
+ {report.sharedEnvGroups.length > 0 && <EnvGroups report={report} />}
+ {report.unreadable.length > 0 && <Unreadable report={report} />}
+ </>
+ )}
+ </SettingsSection>
+ );
+}
diff --git a/packages/web/src/lib/settings-sections.ts b/packages/web/src/lib/settings-sections.ts
index 6d5c4bf0..149fc60d 100644
--- a/packages/web/src/lib/settings-sections.ts
+++ b/packages/web/src/lib/settings-sections.ts
@@ -36,6 +36,7 @@ export type SettingsSectionKey =
| "uploads"
| "company"
| "plugins"
+ | "storage"
| "users";
/** Rail heading a page sits under: the viewer's own preferences vs. the whole server's. */
@@ -77,6 +78,10 @@ const SECTION_RULES: ReadonlyArray<SettingsSection & { visible(viewer: SettingsV
{ key: "company", group: "server", visible: (v) => v.isAdmin },
// The sandbox, and the options loaded plugins declare (server-global, like the plugins themselves).
{ key: "plugins", group: "server", visible: (v) => v.isAdmin },
+ // The data root's storage ledger: a server-global report an admin reads. Read-only, so unlike
+ // user management below it stays in the desktop shell's window too — that install has the same
+ // data root and the same admin, and nothing here can be written by opening it.
+ { key: "storage", group: "server", visible: (v) => v.isAdmin },
// Single-user under the desktop shell: the server rejects the admin user routes there.
{ key: "users", group: "server", visible: (v) => v.isAdmin && !v.desktopMode },
];
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 075d65f7..eff3427a 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -458,6 +458,110 @@ export const en: Strings = {
`Run "${action}" on ${machine ?? "this server"}? It runs on that machine right away; what it does is up to the plugin.`,
/** Under a number field whose box does not parse; the save is not sent. */
pluginFieldNotNumber: "Must be a number",
+ /** Admin-only sub-page (server-global): the data root's storage ledger. A report, and nothing else. */
+ storageTitle: "Storage ledger",
+ /**
+ * The one line at the top of that page's own body: what the page is, and the promise it keeps.
+ * Deliberately visible rather than folded into the heading's "?" — it is what keeps every
+ * figure below from reading as an offer to clear something.
+ */
+ storageReportOnly:
+ "This is a read-only report: it measures and lists what is on disk and deletes nothing. " +
+ "Cleanup will be a separate step, taken by a person after reading this — the page offers no such action.",
+ /** The page's "?" at the pane heading: what is measured, and what a candidate is (and is not). */
+ storageInfo:
+ "The subject is this machine's data root, measured in one walk: every byte lands in exactly one class by provenance, and the total is the root's own size. " +
+ 'A "candidate" is the rule an entry matched — empty, unreferenced, orphaned, idle, over budget — a claim about provenance, not an action, and "still referenced" is recomputed at execution time rather than trusted from a report. ' +
+ "Most thresholds are off by default, so few candidates does not mean the disk holds nothing removable; " +
+ "the paths that could not be read are listed, so the report never looks more complete than it is.",
+ /** The report's own header: the root, when it was measured, the total, and the volume's numbers. */
+ storageRoot: "Data root",
+ storageMeasuredAt: "Measured at",
+ storageTotal: "Total",
+ storageDiskFree: "Disk free / total",
+ /** `disk` is null when the volume's own numbers could not be read. */
+ storageDiskUnknown: "Disk figures unreadable",
+ /** The page's only action: measure again (a walk of the whole root, so it is not free). */
+ storageRescan: "Measure again",
+ storageRescanning: "Measuring…",
+ storageLoading: "Measuring…",
+ storageFailed: "Could not read the storage report.",
+ /** The class table and its columns. */
+ storageClassesTitle: "By class",
+ storageColClass: "Class",
+ storageColBytes: "Size",
+ storageColFiles: "Files",
+ storageColEntries: "Entries",
+ storageColCandidateEntries: "Candidates",
+ storageColCandidateBytes: "Candidate size",
+ /** Class ids in the reader's words; the ids themselves stay protected / tmp_workspaces / … */
+ storageClassNames: {
+ protected: "User assets",
+ tmp_workspaces: "Temporary workspaces",
+ session_drafts: "Session drafts",
+ traces: "Traces",
+ shared_env: "Tool environments",
+ trash: "Trash",
+ database: "Database",
+ other: "Other",
+ },
+ /**
+ * What removing one entry of a class would cost, under its name in the class table. `protected`
+ * is never reported as a candidate, so its line says that rather than inventing a price.
+ */
+ storageClassCost: {
+ protected:
+ "Your own data: Agent State, Project configuration, the Workspaces you chose, vaults, plugins, Benchmark material and snapshots. It never becomes a candidate, and nothing here touches it.",
+ tmp_workspaces:
+ "A Workspace a tool made in a temporary directory: clearing it takes the files inside with it, and a run still working in it would be cut off.",
+ session_drafts:
+ "Session drafts: once cleared, images attached to old messages stop previewing, and reopening the message brings nothing back.",
+ traces:
+ "Traces: once cleared, history replay and the cost page lose their rebuild source — those Sessions' rounds and usage can no longer be computed.",
+ shared_env:
+ "An environment built for an Agent: once cleared, the next use has to install it again.",
+ trash: "What is in the trash: emptying it means it cannot be recovered.",
+ database:
+ "The server's own database (accounts, Session index, settings). Clearing it means losing that state.",
+ other:
+ "Files that fitted no other class: clearing one takes its contents with it, and nobody can say what was lost.",
+ },
+ /** The candidate list: its heading, its empty state, and its columns. */
+ storageCandidatesTitle: "Candidates",
+ storageCandidatesEmpty: "This measurement found no candidates.",
+ storageCandidatesEmptyHint:
+ "That does not mean the disk holds nothing removable: most rules are off by default, and only entries that matched one are listed here.",
+ storageColPath: "Path",
+ storageColLastModified: "Last modified",
+ /** A candidate whose newest mtime could not be read. */
+ storageNeverModified: "unreadable",
+ /** Dated on purpose: the value is what the scan saw, and a cleanup recomputes it before acting. */
+ storageColReferenced: "Referenced at scan",
+ storageReferencedYes: "yes",
+ storageReferencedNo: "no",
+ storageColRules: "Matched rules",
+ /** A candidate the server recorded no rule for — shown rather than left blank. */
+ storageRulesNone: "no rule recorded",
+ /** Rule ids in the reader's words; the ids themselves stay empty / orphan / idle / budget / unreferenced. */
+ storageRuleNames: {
+ empty: "Empty",
+ unreferenced: "Unreferenced",
+ orphan: "Session deleted",
+ idle: "Idle past its threshold",
+ budget: "Over budget",
+ },
+ /** Duplicate-looking tool environments. Report only — merging them is a person's call. */
+ storageEnvGroupsTitle: "Possibly duplicated tool environments",
+ storageEnvGroupsHint:
+ "Report only: the same tool may be installed more than once. Merging is a person's decision — two look-alike environments may be at different versions — and nothing here touches them.",
+ storageEnvGroupKindName: "same name",
+ storageEnvGroupKindStructure: "similar structure",
+ /** How many environments the group holds. */
+ storageEnvGroupMembers: (count: number): string => `${count} copies`,
+ /** Paths nobody could read: the report says what it does not know. */
+ storageUnreadableTitle: "Paths that could not be read",
+ storageUnreadableHint:
+ "Nothing under these paths entered the figures above, so those figures are a lower bound.",
uploadLimitsTitle: "Upload limits",
/** Its two number fields, both in whole MB. */
attachmentMaxMb: "Max attachment size (MB)",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index f2fc2b7d..313982a1 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -523,6 +523,106 @@ export const zh = {
`在${machine === null ? "本机" : ` ${machine} `}上执行「${action}」?它会立即在那台机器上运行,具体做什么由插件决定。`,
/** Under a number field whose box does not parse; the save is not sent. */
pluginFieldNotNumber: "必须是数字",
+ /** Admin-only sub-page (server-global): the data root's storage ledger. A report, and nothing else. */
+ storageTitle: "存储台账",
+ /**
+ * The one line at the top of that page's own body: what the page is, and the promise it keeps.
+ * Deliberately visible rather than folded into the heading's "?" — it is what keeps every
+ * figure below from reading as an offer to clear something.
+ */
+ storageReportOnly:
+ "这是一份只读报告:本页只测量并列出磁盘上的内容,不会删除任何数据。" +
+ "清理将是另一步,需要人看过之后自己决定——本页不提供这种操作。",
+ /** The page's "?" at the pane heading: what is measured, and what a candidate is (and is not). */
+ storageInfo:
+ "测量的是本机的数据根目录,一次遍历得出:每个字节按来源归入一个类别,各类别互不重叠,合计即根目录本身的大小。" +
+ "「候选」是条目命中的规则——空目录、无引用、会话已删除、静默超期、超出预算——它是一条关于出处的判断,不是一次操作," +
+ "而且「仍被引用」要等到真正执行时才重新计算。多数阈值默认关闭,所以候选少并不代表磁盘上没有冗余;" +
+ "「无法读取的路径」列出这次没读到的位置,报告因此不会显得比实际更完整。",
+ /** The report's own header: the root, when it was measured, the total, and the volume's numbers. */
+ storageRoot: "数据根目录",
+ storageMeasuredAt: "测量时间",
+ storageTotal: "合计",
+ storageDiskFree: "磁盘剩余 / 总容量",
+ /** `disk` is null when the volume's own numbers could not be read. */
+ storageDiskUnknown: "未读到磁盘容量",
+ /** The page's only action: measure again (a walk of the whole root, so it is not free). */
+ storageRescan: "重新测量",
+ storageRescanning: "测量中…",
+ storageLoading: "正在测量…",
+ storageFailed: "无法取得存储报告。",
+ /** The class table and its columns. */
+ storageClassesTitle: "按类别",
+ storageColClass: "类别",
+ storageColBytes: "占用",
+ storageColFiles: "文件",
+ storageColEntries: "条目",
+ storageColCandidateEntries: "候选条目",
+ storageColCandidateBytes: "候选占用",
+ /** Class ids in the reader's words; the ids themselves stay protected / tmp_workspaces / … */
+ storageClassNames: {
+ protected: "用户资产",
+ tmp_workspaces: "临时工作区",
+ session_drafts: "会话草稿",
+ traces: "轨迹",
+ shared_env: "工具环境",
+ trash: "回收站",
+ database: "数据库",
+ other: "其他",
+ },
+ /**
+ * What removing one entry of a class would cost, under its name in the class table. `protected`
+ * is never reported as a candidate, so its line says that rather than inventing a price.
+ */
+ storageClassCost: {
+ protected:
+ "你自己的数据:智能体状态、项目配置、你指定的 WorkSpace、密钥库、插件、评估集与快照。它从不成为候选,本页也不会动它。",
+ tmp_workspaces:
+ "工具在临时目录里建的 WorkSpace:清掉会连里面的文件一起消失,正在用它运行的任务会被打断。",
+ session_drafts:
+ "会话草稿:清掉之后,旧消息里附上的图片不再能预览,重新打开那条消息也恢复不了。",
+ traces: "轨迹:清掉之后,历史回放与成本页失去重建来源,那些会话的往返与用量再也算不出来。",
+ shared_env: "为智能体建的工具环境:清掉之后,下次用到它要重新装一遍。",
+ trash: "回收站里的东西:清空它就再也找不回来了。",
+ database: "服务器自己的数据库(账号、会话索引、设置)。清掉它等于丢掉这些状态。",
+ other: "没有归入其他类别的文件:清掉它连内容一起消失,而且没人能说出丢的是什么。",
+ },
+ /** The candidate list: its heading, its empty state, and its columns. */
+ storageCandidatesTitle: "候选条目",
+ storageCandidatesEmpty: "这次测量没有找到候选条目。",
+ storageCandidatesEmptyHint:
+ "这不代表磁盘上没有冗余:多数规则默认关闭,只有确实命中规则的条目才会列在这里。",
+ storageColPath: "路径",
+ storageColLastModified: "最近修改",
+ /** A candidate whose newest mtime could not be read. */
+ storageNeverModified: "读不到",
+ /** Dated on purpose: the value is what the scan saw, and a cleanup recomputes it before acting. */
+ storageColReferenced: "扫描时仍被引用",
+ storageReferencedYes: "是",
+ storageReferencedNo: "否",
+ storageColRules: "命中的规则",
+ /** A candidate the server recorded no rule for — shown rather than left blank. */
+ storageRulesNone: "未记录规则",
+ /** Rule ids in the reader's words; the ids themselves stay empty / orphan / idle / budget / unreferenced. */
+ storageRuleNames: {
+ empty: "空目录",
+ unreferenced: "无引用",
+ orphan: "会话已删除",
+ idle: "静默超期",
+ budget: "超出预算",
+ },
+ /** Duplicate-looking tool environments. Report only — merging them is a person's call. */
+ storageEnvGroupsTitle: "疑似重复的工具环境",
+ storageEnvGroupsHint:
+ "仅供查看:同一个工具可能装了不止一份。合并需要人来决定——两份看起来一样的未必是同一个版本——本页不会动它们。",
+ storageEnvGroupKindName: "同名",
+ storageEnvGroupKindStructure: "结构相似",
+ /** How many environments the group holds. */
+ storageEnvGroupMembers: (count: number): string => `${count} 份`,
+ /** Paths nobody could read: the report says what it does not know. */
+ storageUnreadableTitle: "无法读取的路径",
+ storageUnreadableHint:
+ "这些位置在测量时没有读到,其中的内容没有进入上面的统计,所以上面的数字是下限。",
uploadLimitsTitle: "上传限制",
/** Its two number fields, both in whole MB. */
attachmentMaxMb: "单个附件上限(MB)",
diff --git a/packages/web/test/settings-sections.test.ts b/packages/web/test/settings-sections.test.ts
index 4ed0153f..6ca0e070 100644
--- a/packages/web/test/settings-sections.test.ts
+++ b/packages/web/test/settings-sections.test.ts
@@ -57,13 +57,15 @@ describe("visibleSettingsSections", () => {
"uploads",
"company",
"plugins",
+ "storage",
"users",
]);
});
it("gives a non-admin their own pages and nothing server-global", () => {
// Not "fewer pages" — the exact list. Proxy, upload limits, the company-mode master
- // switch and user management are admin surfaces, and the whole point of dropping them is that a non-admin is never
+ // switch, the storage ledger and user management are admin surfaces, and the whole point of
+ // dropping them is that a non-admin is never
// told they exist. Updating is not among them either way: it lives in the sidebar user
// menu, outside this dialog, for every account.
expect(plain.map((s) => s.key)).toEqual([
@@ -79,7 +81,9 @@ describe("visibleSettingsSections", () => {
it("strips the desktop shell's window down to what a token session can use", () => {
// No account page (no password to change — see offersChangePassword), no user
// management (single-user server). The profile page stays: an avatar and a nickname need
- // no password, and this window is the only session a desktop install has.
+ // no password, and this window is the only session a desktop install has. The storage
+ // ledger stays as well: it is the same data root and the same admin, and opening a report
+ // writes nothing the single-user rule is there to protect.
expect(shell.map((s) => s.key)).toEqual([
"profile",
"general",
@@ -90,6 +94,7 @@ describe("visibleSettingsSections", () => {
"uploads",
"company",
"plugins",
+ "storage",
]);
});
@@ -107,10 +112,32 @@ describe("visibleSettingsSections", () => {
"uploads",
"company",
"plugins",
+ "storage",
]);
});
});
+/**
+ * The storage ledger is a read-only report, so nothing but its admin-only visibility separates it
+ * from the pages around it: it sits in the Server group, and a non-admin is answered exactly as
+ * they are for any other page they may not open (settings-sections.ts).
+ */
+describe("the storage report's place in the rail", () => {
+ it("is a Server page, and every admin gets it", () => {
+ for (const sections of [admin, shell, desktopBrowser]) {
+ expect(sections.find((s) => s.key === "storage")).toEqual({
+ key: "storage",
+ group: "server",
+ });
+ }
+ });
+
+ it("is never offered to a non-admin, and asking for it falls back like any forbidden page", () => {
+ expect(plain.map((s) => s.key)).not.toContain("storage");
+ expect(resolveSettingsSection("storage", plain)).toBe("profile");
+ });
+});
+
describe("settingsGroups", () => {
it("lists an admin's groups once each, in page order", () => {
expect(settingsGroups(admin)).toEqual(["personal", "server"]);
diff --git a/packages/web/test/storage-labels.test.ts b/packages/web/test/storage-labels.test.ts
new file mode 100644
index 00000000..90879d33
--- /dev/null
+++ b/packages/web/test/storage-labels.test.ts
@@ -0,0 +1,128 @@
+/**
+ * The storage report's vocabulary (features/settings/storage-labels.ts), pinned by value.
+ *
+ * The report's reader decides nothing from this page, but they do read it: a class or a rule
+ * rendered as its raw id (`session_drafts`, `orphan`) is a word this audience cannot act on, and a
+ * class that silently fell through to "Other" would hide the very thing the report measured. So
+ * every id the API can send is checked here, in both dictionaries, at once:
+ *
+ * - each class has a name of its own and a line saying what clearing it would cost — including the
+ * classes that never become a candidate, which say that rather than inventing a price;
+ * - each rule has a name of its own;
+ * - a candidate's rules render joined, and an empty list renders words rather than nothing;
+ * - a look-alike environment group says what matched it (the name, or what it holds).
+ *
+ * The lists below are written out rather than derived from a union, so a value the engine adds
+ * fails this test (as it fails the type check in storage-labels.ts) instead of passing quietly.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ storageClassCost,
+ storageClassLabel,
+ storageEnvGroupKindLabel,
+ storageRulesLabel,
+} from "../src/features/settings/storage-labels";
+import { setActiveStrings, zh } from "../src/lib/strings";
+import { en } from "../src/lib/strings-en";
+import type { StorageCandidateRule, StorageClass } from "@lmliheng/penguin-server/api";
+
+/** Every class the ledger accounts for (core's STORAGE_CLASSES, the API's StorageClass). */
+const CLASSES: StorageClass[] = [
+ "protected",
+ "tmp_workspaces",
+ "session_drafts",
+ "traces",
+ "shared_env",
+ "trash",
+ "database",
+ "other",
+];
+
+/** Every rule a candidate can carry. */
+const RULES: StorageCandidateRule[] = ["empty", "unreferenced", "orphan", "idle", "budget"];
+
+afterEach(() => setActiveStrings(zh));
+
+describe("storageClassLabel / storageClassCost", () => {
+ it("names every class in the reader's words, in both locales", () => {
+ for (const [locale, dict] of [
+ ["zh", zh],
+ ["en", en],
+ ] as const) {
+ setActiveStrings(dict);
+ const labels = CLASSES.map((cls) => storageClassLabel(cls));
+ for (const cls of CLASSES) {
+ expect(storageClassLabel(cls), `${locale} ${cls}`).toBe(
+ dict.settings.storageClassNames[cls],
+ );
+ // The hole this guards: a missing entry would leave the raw id on screen, which reads as
+ // a directory name rather than as a kind of data.
+ expect(storageClassLabel(cls), `${locale} ${cls}`).not.toBe(cls);
+ }
+ // One word per class: two classes sharing a name would merge in the reader's head.
+ expect(new Set(labels).size, locale).toBe(CLASSES.length);
+ }
+ });
+
+ it("says what clearing a class would cost, in both locales, once per class", () => {
+ for (const [locale, dict] of [
+ ["zh", zh],
+ ["en", en],
+ ] as const) {
+ setActiveStrings(dict);
+ for (const cls of CLASSES) {
+ const cost = storageClassCost(cls);
+ expect(cost, `${locale} ${cls}`).toBe(dict.settings.storageClassCost[cls]);
+ expect(cost.trim(), `${locale} ${cls}`).not.toBe("");
+ // The cost line is read under the class's own name, so it must not be the name again.
+ expect(cost, `${locale} ${cls}`).not.toBe(dict.settings.storageClassNames[cls]);
+ }
+ const costs = CLASSES.map((cls) => storageClassCost(cls));
+ expect(new Set(costs).size, locale).toBe(CLASSES.length);
+ }
+ });
+});
+
+describe("storageRulesLabel", () => {
+ it("names every rule in the reader's words, in both locales", () => {
+ for (const [locale, dict] of [
+ ["zh", zh],
+ ["en", en],
+ ] as const) {
+ setActiveStrings(dict);
+ for (const rule of RULES) {
+ expect(storageRulesLabel([rule]), `${locale} ${rule}`).toBe(
+ dict.settings.storageRuleNames[rule],
+ );
+ expect(storageRulesLabel([rule]), `${locale} ${rule}`).not.toBe(rule);
+ }
+ }
+ });
+
+ it("joins the rules one candidate matched, keeping their order and repeating none", () => {
+ setActiveStrings(zh);
+ expect(storageRulesLabel(["empty", "unreferenced"])).toBe("空目录 · 无引用");
+ expect(storageRulesLabel(["idle", "budget"])).toBe("静默超期 · 超出预算");
+ });
+
+ it("says so in words when the server recorded no rule, rather than rendering nothing", () => {
+ for (const dict of [zh, en]) {
+ setActiveStrings(dict);
+ expect(storageRulesLabel([])).toBe(dict.settings.storageRulesNone);
+ expect(storageRulesLabel([]).trim()).not.toBe("");
+ }
+ });
+});
+
+describe("storageEnvGroupKindLabel", () => {
+ it("says whether the group was matched by name or by what it holds", () => {
+ for (const dict of [zh, en]) {
+ setActiveStrings(dict);
+ expect(storageEnvGroupKindLabel("name")).toBe(dict.settings.storageEnvGroupKindName);
+ expect(storageEnvGroupKindLabel("structure")).toBe(
+ dict.settings.storageEnvGroupKindStructure,
+ );
+ expect(storageEnvGroupKindLabel("name")).not.toBe(storageEnvGroupKindLabel("structure"));
+ }
+ });
+});