@promptbook/cli 0.113.0-8 → 0.114.0-0

package/README.md

@@ -26,15 +26,16 @@ Create persistent AI agents that turn your company's scattered knowledge into ac
 Run the standalone VPS installer _(for example on DigitalOcean)_ only on a fresh server. Interactive mode asks for the installation values:
 
 ```bash
-sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/install.sh | bash
 ```
 
-Non-interactive mode takes defaults from command-line options. When `--openai-api-key` is provided with the default OpenAI Codex runner, the installer installs and configures Codex automatically; other runner authentication can be configured later from the UI or SSH:
+Non-interactive mode takes defaults from command-line options. Use `--env live`, `--env preview`, `--env production`, or `--env lts` to pick the installed environment; the default is `preview`. When `--openai-api-key` is provided with the default OpenAI Codex runner, the installer installs and configures Codex automatically; other runner authentication can be configured later from the UI or SSH:
 
 ```bash
-sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash -s -- \
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/install.sh | bash -s -- \
     --non-interactive \
     --yes-i-understand-that-script-should-be-run-on-fresh-server \
+    --env preview \
     --domain my-server.com \
     --openai-api-key sk-proj-xxx \
     --admin-password xxx

package/apps/agents-server/next.config.ts

@@ -78,7 +78,7 @@ const nextConfig: NextConfig = {
         },
     },
 
-    webpack(config, { isServer }) {
+    webpack(config, { isServer, nextRuntime }) {
         config.resolve.alias = {
             ...config.resolve.alias,
             '@': path.resolve(__dirname),
@@ -92,17 +92,22 @@ const nextConfig: NextConfig = {
             );
         }
 
-        // Exclude Node.js-only modules from client bundle
-        if (!isServer) {
+        // Exclude Node.js-only modules from client and edge bundles
+        if (!isServer || nextRuntime === 'edge') {
             config.resolve.fallback = {
                 ...config.resolve.fallback,
                 fs: false,
+                'fs/promises': false,
+                path: false,
+                util: false,
                 net: false,
                 tls: false,
                 dns: false,
                 child_process: false,
                 // jsdom and related dependencies that require Node.js APIs
                 canvas: false,
+                // Standalone VPS SQLite backend is Node-only; edge middleware never runs it
+                'better-sqlite3': false,
             };
         }
 

package/apps/agents-server/package.json

@@ -2,14 +2,14 @@
     "name": "promptbook-agents-server",
     "scripts": {
         "generate-reserved-paths": "ts-node ./scripts/generate-reserved-paths/generate-reserved-paths.ts",
-        "prebuild": "npm run generate-reserved-paths && npx kill-port 4440 ||  exit 0",
+        "prebuild": "npm run generate-reserved-paths && node ./scripts/clearNextGeneratedTypes.js && npx kill-port 4440 ||  exit 0",
         "predev": "npm run generate-reserved-paths && npx kill-port 4440 ||  exit 0",
         "dev": "next dev -p 4440",
         "test": "npm run lint && npm run test-build && npm run test-e2e",
         "test-e2e": "playwright test",
         "pretest-build": "npx kill-port 4021 4440 || exit 0",
-        "test-build": "node -r ./scripts/ignore-kill-eperm.js ../../node_modules/next/dist/bin/next build && node ./scripts/prerender-homepage.js",
-        "build": "node -r ./scripts/ignore-kill-eperm.js ../../node_modules/next/dist/bin/next build && node ./scripts/prerender-homepage.js",
+        "test-build": "npm run build",
+        "build": "node --max-old-space-size=8192 -r ./scripts/ignore-kill-eperm.js ./scripts/next-cli.js build && node ./scripts/prerender-homepage.js",
         "start": "next start -p 4440",
         "lint": "eslint src/ --max-warnings=0",
         "postinstall": "cd ../../ && npm ci"

package/apps/agents-server/playwright.config.ts

@@ -21,6 +21,11 @@ const APP_PORT = 4440;
  */
 const APP_URL = `http://127.0.0.1:${APP_PORT}`;
 
+/**
+ * Maximum time allowed for the production Agents Server bundle used by browser tests.
+ */
+const E2E_WEB_SERVER_TIMEOUT_MS = 30 * 60 * 1000;
+
 /**
  * Shared environment variables required by the Agents Server in deterministic e2e runs.
  */
@@ -93,11 +98,11 @@ const config = defineConfig({
         },
         {
             command:
-                'npm run prebuild && node -r ./scripts/ignore-kill-eperm.js ../../node_modules/next/dist/bin/next build && npm run start',
+                'npm run prebuild && node --max-old-space-size=8192 -r ./scripts/ignore-kill-eperm.js ./scripts/next-cli.js build && npm run start',
             cwd: __dirname,
             url: APP_URL,
             reuseExistingServer: false,
-            timeout: 8 * 60 * 1000,
+            timeout: E2E_WEB_SERVER_TIMEOUT_MS,
             stdout: 'pipe',
             stderr: 'pipe',
             env: {

package/apps/agents-server/scripts/clearNextGeneratedTypes.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { rm } = require('node:fs/promises');
+const { join } = require('node:path');
+
+/**
+ * Next.js output directories used by normal and end-to-end builds.
+ */
+const NEXT_DIST_DIRECTORY_NAMES = ['.next', '.next-e2e'];
+
+/**
+ * Removes generated Next.js route types so a build cannot type-check stale routes from another output directory.
+ */
+async function clearNextGeneratedTypes() {
+    await Promise.all(
+        NEXT_DIST_DIRECTORY_NAMES.map((nextDistDirectoryName) =>
+            rm(join(__dirname, '..', nextDistDirectoryName, 'types'), { force: true, recursive: true }),
+        ),
+    );
+}
+
+void clearNextGeneratedTypes().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/CloudflareDnsRecordSyncPlan.ts

@@ -1,84 +1,14 @@
-/**
- * Cloudflare DNS records should not be proxied because Vercel must see the original DNS target directly.
- *
- * @private constant of `resolveDesiredCloudflareDnsRecord`
- */
-export const CLOUDFLARE_DNS_RECORD_PROXIED = false;
-
-/**
- * Cloudflare TTL `1` means automatic.
- *
- * @private constant of `resolveDesiredCloudflareDnsRecord`
- */
-export const CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC = 1;
+import type { CloudflareApiConfiguration, CloudflareDnsRecord } from '../../src/utils/cloudflare/CloudflareApi';
 
-/**
- * Cloudflare API configuration loaded from environment variables.
- *
- * @private type of `sync-vercel-domains`
- */
-export type CloudflareApiConfiguration = {
-    /**
-     * API token used for authentication.
-     */
-    readonly token: string;
-};
-
-/**
- * Minimal Cloudflare zone metadata used for domain-to-zone matching.
- *
- * @private type of `sync-vercel-domains`
- */
-export type CloudflareZone = {
-    /**
-     * Cloudflare zone id.
-     */
-    readonly id: string;
-    /**
-     * Zone apex name.
-     */
-    readonly name: string;
-};
-
-/**
- * Minimal Cloudflare DNS record payload used by the sync script.
- *
- * @private type of `sync-vercel-domains`
- */
-export type CloudflareDnsRecord = {
-    /**
-     * Cloudflare DNS record id.
-     */
-    readonly id: string;
-    /**
-     * DNS record type.
-     */
-    readonly type: string;
-    /**
-     * Fully qualified record name.
-     */
-    readonly name: string;
-    /**
-     * Record content or target.
-     */
-    readonly content: string;
-    /**
-     * Whether the record is proxied through Cloudflare.
-     */
-    readonly proxied?: boolean | null;
-    /**
-     * Record TTL.
-     */
-    readonly ttl?: number | null;
-    /**
-     * Optional user-visible record comment.
-     */
-    readonly comment?: string | null;
-    /**
-     * Optional record tags.
-     */
-    readonly tags?: ReadonlyArray<string>;
-};
+// Note: The Cloudflare API layer is shared with the Agents Server Cloudflare DNS wizard, so these are re-exported
+//       from `src/utils/cloudflare` instead of being defined twice.
+export {
+    CLOUDFLARE_DNS_RECORD_PROXIED,
+    CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC,
+    type CloudflareApiConfiguration,
+    type CloudflareDnsRecord,
+    type CloudflareZone,
+} from '../../src/utils/cloudflare/CloudflareApi';
 
 /**
  * Desired Cloudflare DNS record derived from one managed domain.

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/createCloudflareDnsRecordSyncPlan.ts

@@ -8,7 +8,7 @@ import type {
     DesiredCloudflareDnsRecord,
 } from './CloudflareDnsRecordSyncPlan';
 import { describeCloudflareDnsRecordUpdateReasons } from './describeCloudflareDnsRecordUpdateReasons';
-import { listAllCloudflareDnsRecords } from './listAllCloudflareDnsRecords';
+import { listAllCloudflareDnsRecords } from '../../src/utils/cloudflare/listAllCloudflareDnsRecords';
 import { selectCloudflareRecordForManagedDomain } from './selectCloudflareRecordForManagedDomain';
 
 /**

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/describeCloudflareDnsRecordUpdateReasons.ts

@@ -8,7 +8,7 @@ import {
     type CloudflareDnsRecord,
     type DesiredCloudflareDnsRecord,
 } from './CloudflareDnsRecordSyncPlan';
-import { normalizeCloudflareDnsRecordContent } from './normalizeCloudflareDnsRecordContent';
+import { normalizeCloudflareDnsRecordContent } from '../../src/utils/cloudflare/normalizeCloudflareDnsRecordContent';
 
 /**
  * Lists human-readable reasons why a Cloudflare DNS record should be updated.

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/resolveDesiredCloudflareDnsRecord.ts

@@ -12,7 +12,7 @@ import {
     type CloudflareZone,
     type DesiredCloudflareDnsRecord,
 } from './CloudflareDnsRecordSyncPlan';
-import { normalizeCloudflareDnsRecordContent } from './normalizeCloudflareDnsRecordContent';
+import { normalizeCloudflareDnsRecordContent } from '../../src/utils/cloudflare/normalizeCloudflareDnsRecordContent';
 
 /**
  * Resolves the desired Cloudflare DNS record for one managed domain.

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/resolveDesiredCloudflareDnsRecords.ts

@@ -1,5 +1,5 @@
+import { findBestMatchingCloudflareZoneForDomain } from '../../src/utils/cloudflare/findBestMatchingCloudflareZoneForDomain';
 import { getVercelDomainConfiguration, type VercelApiConfiguration } from '../createVercelDomainSyncPlan';
-import { normalizeManagedDomain } from '../normalizeManagedDomain';
 import type {
     CloudflareSkippedDomain,
     CloudflareZone,
@@ -45,31 +45,3 @@ export async function resolveDesiredCloudflareDnsRecords(options: {
         skippedDomains,
     };
 }
-
-/**
- * Finds the best matching Cloudflare zone for one fully-qualified domain.
- *
- * @param domain - Fully-qualified managed domain.
- * @param zones - Accessible Cloudflare zones.
- * @returns Best matching zone or `null`.
- */
-function findBestMatchingCloudflareZoneForDomain(
-    domain: string,
-    zones: ReadonlyArray<CloudflareZone>,
-): CloudflareZone | null {
-    const normalizedDomain = normalizeManagedDomain(domain);
-    let bestMatch: CloudflareZone | null = null;
-
-    for (const zone of zones) {
-        const normalizedZoneName = normalizeManagedDomain(zone.name);
-        if (normalizedDomain !== normalizedZoneName && !normalizedDomain.endsWith(`.${normalizedZoneName}`)) {
-            continue;
-        }
-
-        if (!bestMatch || normalizedZoneName.length > normalizeManagedDomain(bestMatch.name).length) {
-            bestMatch = zone;
-        }
-    }
-
-    return bestMatch;
-}

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/selectCloudflareRecordForManagedDomain.ts

@@ -1,6 +1,6 @@
 import { isManagedCloudflareDnsRecord } from './CLOUDFLARE_DNS_RECORD_COMMENT_MARKER';
 import type { CloudflareDnsRecord, DesiredCloudflareDnsRecord } from './CloudflareDnsRecordSyncPlan';
-import { normalizeCloudflareDnsRecordContent } from './normalizeCloudflareDnsRecordContent';
+import { normalizeCloudflareDnsRecordContent } from '../../src/utils/cloudflare/normalizeCloudflareDnsRecordContent';
 
 /**
  * Picks the Cloudflare record that should represent the managed hostname.

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/syncCloudflareDnsRecords.ts

@@ -7,11 +7,11 @@ import type {
     CloudflareSkippedDomain,
     DesiredCloudflareDnsRecord,
 } from './CloudflareDnsRecordSyncPlan';
-import { createCloudflareDnsRecord } from './createCloudflareDnsRecord';
+import { createCloudflareDnsRecord } from '../../src/utils/cloudflare/createCloudflareDnsRecord';
 import { createCloudflareDnsRecordSyncPlan } from './createCloudflareDnsRecordSyncPlan';
-import { listCloudflareZones } from './listCloudflareZones';
+import { listCloudflareZones } from '../../src/utils/cloudflare/listCloudflareZones';
 import { resolveDesiredCloudflareDnsRecords } from './resolveDesiredCloudflareDnsRecords';
-import { updateCloudflareDnsRecord } from './updateCloudflareDnsRecord';
+import { updateManagedCloudflareDnsRecord } from './updateManagedCloudflareDnsRecord';
 
 /**
  * Syncs Cloudflare DNS records for the desired managed domains.
@@ -145,7 +145,7 @@ async function syncCloudflareDnsRecordUpdates(options: {
             continue;
         }
 
-        await updateCloudflareDnsRecord(options.cloudflareConfiguration, recordToUpdate);
+        await updateManagedCloudflareDnsRecord(options.cloudflareConfiguration, recordToUpdate);
         logSyncEvent('info', 'cloudflare_record_updated', {
             domain: recordToUpdate.desiredRecord.name,
             zone: recordToUpdate.desiredRecord.zoneName,

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan/updateManagedCloudflareDnsRecord.ts

@@ -0,0 +1,26 @@
+import { updateCloudflareDnsRecord } from '../../src/utils/cloudflare/updateCloudflareDnsRecord';
+import {
+    createCloudflareManagedRecordComment,
+    mergeCloudflareDnsRecordTags,
+} from './CLOUDFLARE_DNS_RECORD_COMMENT_MARKER';
+import type { CloudflareApiConfiguration, CloudflareDnsRecordUpdate } from './CloudflareDnsRecordSyncPlan';
+
+/**
+ * Updates one Cloudflare DNS record while preserving existing non-automation comments and tags.
+ *
+ * @param configuration - Cloudflare API configuration.
+ * @param update - Existing and desired record pair.
+ *
+ * @private function of `syncCloudflareDnsRecords`
+ */
+export async function updateManagedCloudflareDnsRecord(
+    configuration: CloudflareApiConfiguration,
+    update: CloudflareDnsRecordUpdate,
+): Promise<void> {
+    await updateCloudflareDnsRecord(configuration, {
+        ...update.desiredRecord,
+        recordId: update.currentRecord.id,
+        comment: createCloudflareManagedRecordComment(update.currentRecord.comment),
+        tags: mergeCloudflareDnsRecordTags(update.currentRecord.tags),
+    });
+}

package/apps/agents-server/scripts/createCloudflareDnsRecordSyncPlan.ts

@@ -10,7 +10,7 @@ export {
     type DesiredCloudflareDnsRecord,
 } from './createCloudflareDnsRecordSyncPlan/CloudflareDnsRecordSyncPlan';
 export { createCloudflareDnsRecordSyncPlan } from './createCloudflareDnsRecordSyncPlan/createCloudflareDnsRecordSyncPlan';
-export { normalizeCloudflareDnsRecordContent } from './createCloudflareDnsRecordSyncPlan/normalizeCloudflareDnsRecordContent';
+export { normalizeCloudflareDnsRecordContent } from '../src/utils/cloudflare/normalizeCloudflareDnsRecordContent';
 export { resolveCloudflareSyncConfiguration } from './createCloudflareDnsRecordSyncPlan/resolveCloudflareSyncConfiguration';
 export { resolveDesiredCloudflareDnsRecord } from './createCloudflareDnsRecordSyncPlan/resolveDesiredCloudflareDnsRecord';
 export { syncCloudflareDnsRecords } from './createCloudflareDnsRecordSyncPlan/syncCloudflareDnsRecords';

package/apps/agents-server/scripts/next-cli.js

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Runs the Next.js command line interface resolved through Node's module resolution.
+ *
+ * Invoking `../../node_modules/next/dist/bin/next` directly assumes that the installed
+ * dependencies always sit exactly two directories above this workspace. That assumption breaks
+ * inside a git worktree (for example the `ptbk coder --isolate` worktrees under
+ * `.promptbook/coder-isolation-worktrees`), where the worktree root has no `node_modules` of its
+ * own and Node finds Next.js only by walking further up the directory tree. The hardcoded path
+ * then fails with `MODULE_NOT_FOUND` even though Next.js is perfectly resolvable.
+ *
+ * The Next.js binary parses `process.argv` itself, so requiring it here forwards every argument
+ * of this script unchanged, for example `node ./scripts/next-cli.js build`.
+ */
+require(require.resolve('next/dist/bin/next'));

package/apps/agents-server/src/app/admin/_components/AdminConfigurationShell.tsx

@@ -1,41 +1,38 @@
 import type { ReactNode } from 'react';
-import Link from 'next/link';
+import { AdminRouteTabs, type AdminRouteTabItem } from './AdminRouteTabs';
 
 /**
  * Supported admin configuration pages shown in the shared sub-navigation.
  *
  * @private admin configuration UI helper
  */
-type AdminConfigurationPage = 'environment' | 'metadata' | 'limits';
+type AdminConfigurationPage = 'environment' | 'metadata' | 'limits' | 'email-server';
 
 /**
  * One shared navigation item rendered in the configuration shell.
  *
  * @private admin configuration UI helper
  */
-const ADMIN_CONFIGURATION_NAVIGATION_ITEMS: ReadonlyArray<{
-    readonly id: AdminConfigurationPage;
-    readonly href: '/admin/environment' | '/admin/metadata' | '/admin/limits';
-    readonly label: string;
-    readonly description: string;
-}> = [
+const ADMIN_CONFIGURATION_NAVIGATION_ITEMS: ReadonlyArray<AdminRouteTabItem<AdminConfigurationPage>> = [
     {
         id: 'environment',
-        href: '/admin/environment',
+        href: '/superadmin/environment',
         label: 'Environment variables',
-        description: 'VPS-wide .env values with secrets masked in the browser.',
+    },
+    {
+        id: 'email-server',
+        href: '/admin/email-server',
+        label: 'Email server',
     },
     {
         id: 'metadata',
         href: '/admin/metadata',
         label: 'Metadata',
-        description: 'Domain-specific feature flags, text settings, and compatibility keys.',
     },
     {
         id: 'limits',
         href: '/admin/limits',
         label: 'Limits',
-        description: 'Operational quotas, retry windows, upload caps, and rate limits.',
     },
 ];
 
@@ -63,28 +60,7 @@ export function AdminConfigurationShell({ activePage, children }: AdminConfigura
                         limits from one configuration area.
                     </p>
                 </div>
-                <div className="grid gap-3 md:grid-cols-3">
-                    {ADMIN_CONFIGURATION_NAVIGATION_ITEMS.map((item) => {
-                        const isActive = item.id === activePage;
-
-                        return (
-                            <Link
-                                key={item.id}
-                                href={item.href}
-                                className={`rounded-2xl border px-4 py-4 transition ${
-                                    isActive
-                                        ? 'border-blue-300 bg-blue-50 text-blue-900 shadow-sm'
-                                        : 'border-slate-200 bg-white text-slate-700 hover:border-slate-300 hover:shadow-sm'
-                                }`}
-                            >
-                                <div className="text-sm font-semibold">{item.label}</div>
-                                <div className={`mt-1 text-sm ${isActive ? 'text-blue-800' : 'text-slate-500'}`}>
-                                    {item.description}
-                                </div>
-                            </Link>
-                        );
-                    })}
-                </div>
+                <AdminRouteTabs activeTabId={activePage} items={ADMIN_CONFIGURATION_NAVIGATION_ITEMS} />
             </div>
 
             {children}

package/apps/agents-server/src/app/admin/_components/AdminRouteTabs.tsx

@@ -0,0 +1,72 @@
+import Link from 'next/link';
+
+/**
+ * One route-backed tab rendered in admin page sub-navigation.
+ *
+ * @private shared admin UI type
+ */
+export type AdminRouteTabItem<TTabId extends string = string> = {
+    /**
+     * Stable tab identifier.
+     */
+    readonly id: TTabId;
+
+    /**
+     * Route opened by the tab.
+     */
+    readonly href: string;
+
+    /**
+     * Main tab label.
+     */
+    readonly label: string;
+};
+
+/**
+ * Props accepted by `AdminRouteTabs`.
+ *
+ * @private shared admin UI type
+ */
+type AdminRouteTabsProps<TTabId extends string> = {
+    /**
+     * Currently active tab id.
+     */
+    readonly activeTabId: TTabId;
+
+    /**
+     * Route-backed tabs to render.
+     */
+    readonly items: ReadonlyArray<AdminRouteTabItem<TTabId>>;
+};
+
+/**
+ * Shared route-tab navigation used by admin pages that link sibling sections.
+ *
+ * @private shared admin UI component
+ */
+export function AdminRouteTabs<TTabId extends string>({ activeTabId, items }: AdminRouteTabsProps<TTabId>) {
+    return (
+        <nav aria-label="Admin page sections">
+            <div className="flex flex-wrap items-center gap-1 border-b border-gray-200">
+                {items.map((item) => {
+                    const isActive = item.id === activeTabId;
+
+                    return (
+                        <Link
+                            key={item.id}
+                            href={item.href}
+                            aria-current={isActive ? 'page' : undefined}
+                            className={`-mb-px border-b-2 px-4 py-2 text-sm font-medium transition-colors ${
+                                isActive
+                                    ? 'border-blue-600 text-blue-700'
+                                    : 'border-transparent text-gray-500 hover:border-gray-300 hover:text-gray-700'
+                            }`}
+                        >
+                            {item.label}
+                        </Link>
+                    );
+                })}
+            </div>
+        </nav>
+    );
+}

package/apps/agents-server/src/app/admin/_components/AdminSortableTableHeaderCell.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import { ArrowDown, ArrowUp, ChevronsUpDown } from 'lucide-react';
+import type { ReactNode } from 'react';
+import type { AdminTableSortOrder } from './adminTableSorting';
+
+/**
+ * Text alignment supported by sortable admin table headers.
+ *
+ * @private internal admin table component
+ */
+type AdminSortableTableHeaderAlignment = 'left' | 'right';
+
+/**
+ * Props for `AdminSortableTableHeaderCell`.
+ *
+ * @private internal admin table component
+ */
+type AdminSortableTableHeaderCellProps<TSortField extends string> = {
+    readonly activeSortBy: TSortField;
+    readonly children: ReactNode;
+    readonly className: string;
+    readonly label: string;
+    readonly onSortChange: (sortBy: TSortField) => void;
+    readonly sortBy: TSortField;
+    readonly sortOrder: AdminTableSortOrder;
+    readonly textAlign?: AdminSortableTableHeaderAlignment;
+};
+
+/**
+ * Shared admin table header cell with clickable sort affordance.
+ *
+ * @private internal admin table component
+ */
+export function AdminSortableTableHeaderCell<TSortField extends string>({
+    activeSortBy,
+    children,
+    className,
+    label,
+    onSortChange,
+    sortBy,
+    sortOrder,
+    textAlign = 'left',
+}: AdminSortableTableHeaderCellProps<TSortField>) {
+    const isSorted = activeSortBy === sortBy;
+    const SortIcon = isSorted ? (sortOrder === 'asc' ? ArrowUp : ArrowDown) : ChevronsUpDown;
+
+    return (
+        <th className={className} aria-sort={resolveAdminSortableTableHeaderAriaSort(isSorted, sortOrder)}>
+            <button
+                type="button"
+                onClick={() => onSortChange(sortBy)}
+                className={`inline-flex w-full items-center gap-1.5 rounded-sm text-inherit transition-colors hover:text-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 ${
+                    textAlign === 'right' ? 'justify-end' : 'justify-start'
+                }`}
+                title={`Sort by ${label}`}
+                aria-label={`Sort by ${label}`}
+            >
+                <span>{children}</span>
+                <SortIcon className={`h-3.5 w-3.5 ${isSorted ? 'text-gray-700' : 'text-gray-300'}`} aria-hidden />
+            </button>
+        </th>
+    );
+}
+
+/**
+ * Resolves the accessible sort state for one table header.
+ *
+ * @private internal admin table component
+ */
+function resolveAdminSortableTableHeaderAriaSort(
+    isSorted: boolean,
+    sortOrder: AdminTableSortOrder,
+): 'ascending' | 'descending' | 'none' {
+    if (!isSorted) {
+        return 'none';
+    }
+
+    return sortOrder === 'asc' ? 'ascending' : 'descending';
+}

package/apps/agents-server/src/app/admin/_components/AdminStorageTabs.tsx

@@ -0,0 +1,47 @@
+import { AdminRouteTabs, type AdminRouteTabItem } from './AdminRouteTabs';
+
+/**
+ * Supported storage pages shown to super-admins.
+ *
+ * @private storage admin UI type
+ */
+export type AdminStoragePage = 'internal-s3' | 'files';
+
+/**
+ * Route-backed storage navigation shared by `/admin/internal-s3` and `/admin/files`.
+ *
+ * @private storage admin UI constant
+ */
+const ADMIN_STORAGE_NAVIGATION_ITEMS: ReadonlyArray<AdminRouteTabItem<AdminStoragePage>> = [
+    {
+        id: 'internal-s3',
+        href: '/admin/internal-s3',
+        label: 'Internal S3',
+    },
+    {
+        id: 'files',
+        href: '/admin/files',
+        label: 'Server files',
+    },
+];
+
+/**
+ * Props accepted by `AdminStorageTabs`.
+ *
+ * @private storage admin UI type
+ */
+type AdminStorageTabsProps = {
+    /**
+     * Currently active storage page.
+     */
+    readonly activePage: AdminStoragePage;
+};
+
+/**
+ * Shared tabs interlinking global internal S3 storage and current-server files.
+ *
+ * @private storage admin UI component
+ */
+export function AdminStorageTabs({ activePage }: AdminStorageTabsProps) {
+    return <AdminRouteTabs activeTabId={activePage} items={ADMIN_STORAGE_NAVIGATION_ITEMS} />;
+}