@promptbook/cli 0.112.0-138 → 0.112.0-140

package/README.md

@@ -35,7 +35,7 @@ Run the standalone VPS installer only on a fresh server. Interactive mode asks f
 sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash
 ```
 
-Non-interactive mode takes defaults from command-line options and skips initial code-runner CLI setup, which can be configured later from the UI or SSH:
+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:
 
 ```bash
 sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash -s -- \

package/apps/agents-server/README.md

@@ -50,6 +50,15 @@ ptbk agents-server start --harness github-copilot --model gpt-5.4 --thinking-lev
 <a id="agents-server-env-promptbook-team-agent-access-token"></a>
 -   `PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN`: Dedicated secret used by same-server `TEAM` calls to authorize access to private teammate agents. Must be a dedicated random string — falling back to `ADMIN_PASSWORD` or `SUPABASE_SERVICE_ROLE_KEY` would let a leak of one credential compromise both authentication boundaries. When not configured, same-server team access stays disabled (the integration fails closed) so leaving the variable empty is safe but disables the feature. Use a long random string, for example the output of `openssl rand -hex 32`.
 
+<a id="agents-server-env-sendgrid-inbound-parse-public-key"></a>
+-   `SENDGRID_INBOUND_PARSE_PUBLIC_KEY`: Public verification key from SendGrid Signed Webhook settings for `/api/emails/incoming/sendgrid`. The route verifies `X-Twilio-Email-Event-Webhook-Signature` over the raw multipart body before parsing or inserting an inbound `EMAIL` message. Configure either this public key or `SENDGRID_INBOUND_PARSE_WEBHOOK_SECRET`; the SendGrid public-key flow is preferred.
+
+<a id="agents-server-env-sendgrid-inbound-parse-webhook-secret"></a>
+-   `SENDGRID_INBOUND_PARSE_WEBHOOK_SECRET`: Shared secret for deployments that sign SendGrid Inbound Parse callbacks with HMAC instead of SendGrid's public-key signature flow. Leave empty when `SENDGRID_INBOUND_PARSE_PUBLIC_KEY` is configured. Use a dedicated random string and keep it separate from `SENDGRID_API_KEY`, `ADMIN_PASSWORD`, and other server secrets.
+
+<a id="agents-server-env-sendgrid-inbound-parse-hosts"></a>
+-   `SENDGRID_INBOUND_PARSE_HOSTS`: Comma-separated list of public hostnames allowed to receive SendGrid Inbound Parse callbacks, for example `mail.example.com,parse.example.com`. The route rejects signed requests delivered through any other `Host` / `X-Forwarded-Host`, so point SendGrid only at the hostnames that are also protected by your reverse-proxy or platform IP allowlisting.
+
 ## Creating servers
 
 When creating new Agents server, search across the repository for [☁]

package/apps/agents-server/src/app/actions.ts

@@ -3,6 +3,7 @@
 import { $generateBookBoilerplate } from '@promptbook-local/core';
 import { string_agent_name, string_book } from '@promptbook-local/types';
 import { revalidatePath } from 'next/cache';
+import { headers } from 'next/headers';
 import { string_agent_permanent_id } from '../../../../src/types/typeAliases';
 import { DEFAULT_NAME_POOL, NAME_POOL_METADATA_KEY, parseNamePool } from '../constants/namePool';
 import { NEW_AGENT_WIZARD_METADATA_KEY, parseNewAgentWizardMode } from '../constants/newAgentWizard';
@@ -12,7 +13,8 @@ import { invalidateCachedActiveOrganizationSnapshots } from '../utils/agentOrgan
 import { resolveAgentRouteTarget } from '../utils/agentRouting/resolveAgentRouteTarget';
 import { buildAgentChatHref, buildAgentProfileHref } from '../utils/agentRouting/agentRouteHrefs';
 import { type AgentVisibility, parseAgentVisibility } from '../utils/agentVisibility';
-import { authenticateUser } from '../utils/authenticateUser';
+import { authenticateUserWithRateLimit } from '../utils/authenticateUser';
+import { resolveAuthenticationAttemptHeaderIp } from '../utils/authenticationAttemptRateLimit';
 import { createAgentWithDefaultVisibility } from '../utils/createAgentWithDefaultVisibility';
 import { resolveCurrentUserIdentity } from '../utils/currentUserIdentity';
 import { isUserAdmin } from '../utils/isUserAdmin';
@@ -150,15 +152,24 @@ export async function $createAgentFromBookAction(
  * @returns Success state for the login attempt.
  */
 export async function loginAction(formData: FormData) {
-    const username = formData.get('username') as string;
-    const password = formData.get('password') as string;
+    const username = formData.get('username');
+    const password = formData.get('password');
 
-    console.info(`Login attempt for user: ${username}`);
+    if (typeof username !== 'string' || typeof password !== 'string' || !username || !password) {
+        return { success: false, message: 'Username and password are required' };
+    }
+
+    const requestIp = resolveAuthenticationAttemptHeaderIp(await headers());
+    const authenticationResult = await authenticateUserWithRateLimit(username, password, {
+        requestIp,
+    });
 
-    const user = await authenticateUser(username, password);
+    if (authenticationResult.isRateLimited) {
+        return { success: false, message: authenticationResult.message };
+    }
 
-    if (user) {
-        await setSession(user);
+    if (authenticationResult.user) {
+        await setSession(authenticationResult.user);
         revalidatePath('/', 'layout');
         return { success: true };
     } else {

package/apps/agents-server/src/app/admin/login-methods/shibboleth/page.tsx

@@ -8,6 +8,7 @@ import { isUserAdmin } from '../../../../utils/isUserAdmin';
 import type { ServerLanguageCode } from '../../../../languages/ServerLanguageRegistry';
 import { formatServerLanguageHumanReadableDate } from '../../../../utils/localization/formatServerLanguageHumanReadableDate';
 import { getRequestServerLanguage } from '../../../../utils/localization/getRequestServerLanguage';
+import { PUBLIC_USER_SELECT_COLUMNS, toPublicUser, type PublicUser } from '../../../../utils/publicUser';
 import {
     getShibbolethAuthenticationAttemptTableName,
     getShibbolethUserIdentityTableName,
@@ -16,18 +17,6 @@ import {
     type ShibbolethUserIdentityRow,
 } from '../../../../utils/shibbolethAuthentication';
 
-/**
- * User row subset displayed on the Shibboleth dashboard.
- */
-type DashboardUserRow = {
-    readonly id: number;
-    readonly username: string;
-    readonly email?: string | null;
-    readonly displayName?: string | null;
-    readonly authenticationProvider?: string | null;
-    readonly isAdmin: boolean;
-};
-
 /**
  * Builds an absolute URL for Shibboleth route configuration inside server components.
  */
@@ -62,7 +51,7 @@ async function loadShibbolethAuthenticationAttempts(): Promise<ReadonlyArray<Shi
  */
 async function loadShibbolethIdentitiesWithUsers(): Promise<{
     readonly identities: ReadonlyArray<ShibbolethUserIdentityRow>;
-    readonly usersById: ReadonlyMap<number, DashboardUserRow>;
+    readonly usersById: ReadonlyMap<number, PublicUser>;
 }> {
     const supabase = $provideSupabaseForServer();
     const { data: identities, error } = await supabase
@@ -90,7 +79,7 @@ async function loadShibbolethIdentitiesWithUsers(): Promise<{
 
     const { data: users, error: usersError } = await supabase
         .from(await $getTableName('User'))
-        .select('*')
+        .select(PUBLIC_USER_SELECT_COLUMNS)
         .in('id', userIds);
 
     if (usersError) {
@@ -101,9 +90,10 @@ async function loadShibbolethIdentitiesWithUsers(): Promise<{
         };
     }
 
-    const usersById = new Map<number, DashboardUserRow>();
-    for (const user of (users as unknown as DashboardUserRow[] | null) || []) {
-        usersById.set(user.id, user);
+    const usersById = new Map<number, PublicUser>();
+    for (const user of (users as unknown as PublicUser[] | null) || []) {
+        const publicUser = toPublicUser(user);
+        usersById.set(publicUser.id, publicUser);
     }
 
     return {

package/apps/agents-server/src/app/admin/metadata/MetadataClient.tsx

@@ -13,10 +13,19 @@ import {
 } from 'lucide-react';
 import Link from 'next/link';
 import { Fragment, useEffect, useRef, useState } from 'react';
+import { spaceTrim } from 'spacetrim';
 import { showConfirm } from '../../../components/AsyncDialogs/asyncDialogs';
 import { useFileUploadAvailability } from '../../../components/FileUploadAvailability/FileUploadAvailabilityContext';
-import { getDeprecatedLimitMetadataDefinition, type DeprecatedLimitMetadataDefinition } from '../../../constants/serverLimits';
-import { getMetadataDefinition, metadataDefaults, type MetadataDefinition } from '../../../database/metadataDefaults';
+import {
+    getDeprecatedLimitMetadataDefinition,
+    type DeprecatedLimitMetadataDefinition,
+} from '../../../constants/serverLimits';
+import {
+    getMetadataDefinition,
+    metadataDefaults,
+    validateMetadataValue,
+    type MetadataDefinition,
+} from '../../../database/metadataDefaults';
 import { getSafeCdnPath } from '../../../utils/cdn/utils/getSafeCdnPath';
 import { downloadBlob, parseFilenameFromContentDisposition } from '../../../utils/download/browserFileDownload';
 import { normalizeUploadFilename } from '../../../utils/normalization/normalizeUploadFilename';
@@ -78,6 +87,62 @@ type MetadataImportSummary = {
     resetCount?: number;
 };
 
+/**
+ * One metadata entry from a standalone metadata import JSON file.
+ *
+ * @private
+ */
+type MetadataImportEntry = {
+    /**
+     * Metadata key.
+     */
+    readonly key: string;
+
+    /**
+     * Metadata value, omitted when the exported value matched the built-in default.
+     */
+    readonly value?: string;
+
+    /**
+     * Metadata note, omitted when the exported note matched the built-in default.
+     */
+    readonly note?: string | null;
+};
+
+/**
+ * Standalone metadata import payload parsed in the browser before upload.
+ *
+ * @private
+ */
+type MetadataImportPayload = {
+    /**
+     * Promptbook version that generated the import file.
+     */
+    readonly promptbookVersion: string;
+
+    /**
+     * Metadata entries included in the import file.
+     */
+    readonly metadata: ReadonlyArray<MetadataImportEntry>;
+};
+
+/**
+ * Result of browser-side metadata import parsing.
+ *
+ * @private
+ */
+type MetadataImportPayloadParseResult = {
+    /**
+     * Parsed payload when the import file is usable.
+     */
+    readonly payload: MetadataImportPayload | null;
+
+    /**
+     * User-facing error message when parsing failed.
+     */
+    readonly errorMessage: string | null;
+};
+
 /**
  * Shared class names for single-line metadata inputs.
  *
@@ -93,6 +158,34 @@ const METADATA_INPUT_CLASS_NAME =
  */
 const METADATA_TEXTAREA_CLASS_NAME = `${METADATA_INPUT_CLASS_NAME} min-h-[100px]`;
 
+/**
+ * Endpoint used by the interactive import flow after the admin selected individual entries.
+ *
+ * @private
+ */
+const METADATA_IMPORT_WITHOUT_DEFAULT_RESET_ENDPOINT = `${METADATA_IMPORT_ENDPOINT}?isDefaultResetSkipped=true`;
+
+/**
+ * Maximum value preview length inside one metadata import choice dialog.
+ *
+ * @private
+ */
+const METADATA_IMPORT_VALUE_PREVIEW_MAX_LENGTH = 180;
+
+/**
+ * Label used when a metadata value is intentionally empty.
+ *
+ * @private
+ */
+const METADATA_IMPORT_EMPTY_VALUE_LABEL = '(empty)';
+
+/**
+ * Label used when a metadata key is not currently persisted.
+ *
+ * @private
+ */
+const METADATA_IMPORT_MISSING_VALUE_LABEL = '(not set)';
+
 /**
  * Normalizes metadata keys so they are safe to use as HTML id suffixes.
  *
@@ -146,6 +239,271 @@ async function resolveMetadataTransferErrorMessage(response: Response, fallbackM
     return fallbackMessage;
 }
 
+/**
+ * Parses one metadata import JSON file for browser-side per-entry selection.
+ *
+ * @param fileContent - Raw JSON file content.
+ * @returns Parsed payload or user-facing error message.
+ *
+ * @private
+ */
+function parseMetadataImportPayloadForSelection(fileContent: string): MetadataImportPayloadParseResult {
+    try {
+        return normalizeMetadataImportPayloadForSelection(JSON.parse(fileContent));
+    } catch {
+        return {
+            payload: null,
+            errorMessage: 'Metadata import must be valid JSON.',
+        };
+    }
+}
+
+/**
+ * Normalizes parsed metadata import JSON enough to ask the admin about each entry.
+ *
+ * @param payload - Parsed JSON import payload.
+ * @returns Parsed payload or user-facing error message.
+ *
+ * @private
+ */
+function normalizeMetadataImportPayloadForSelection(payload: unknown): MetadataImportPayloadParseResult {
+    if (!payload || typeof payload !== 'object') {
+        return {
+            payload: null,
+            errorMessage: 'Metadata import must be a JSON object.',
+        };
+    }
+
+    const payloadRecord = payload as Record<string, unknown>;
+
+    if (typeof payloadRecord.promptbookVersion !== 'string' || payloadRecord.promptbookVersion.trim() === '') {
+        return {
+            payload: null,
+            errorMessage: 'Metadata import is missing `promptbookVersion`.',
+        };
+    }
+
+    if (!Array.isArray(payloadRecord.metadata)) {
+        return {
+            payload: null,
+            errorMessage: 'Metadata import must contain a `metadata` array.',
+        };
+    }
+
+    const importedMetadataKeys = new Set<string>();
+    const metadataEntries: Array<MetadataImportEntry> = [];
+
+    for (const [index, rawMetadataEntry] of payloadRecord.metadata.entries()) {
+        const normalizedMetadataEntry = normalizeMetadataImportEntryForSelection(
+            rawMetadataEntry,
+            index,
+            importedMetadataKeys,
+        );
+
+        if (typeof normalizedMetadataEntry === 'string') {
+            return {
+                payload: null,
+                errorMessage: normalizedMetadataEntry,
+            };
+        }
+
+        metadataEntries.push(normalizedMetadataEntry);
+    }
+
+    return {
+        payload: {
+            promptbookVersion: payloadRecord.promptbookVersion,
+            metadata: metadataEntries,
+        },
+        errorMessage: null,
+    };
+}
+
+/**
+ * Normalizes one metadata import entry for browser-side selection.
+ *
+ * @param rawMetadataEntry - Untrusted entry from the import JSON.
+ * @param index - Zero-based entry index for error messages.
+ * @param importedMetadataKeys - Mutable set used to reject duplicate keys.
+ * @returns Normalized entry or user-facing error message.
+ *
+ * @private
+ */
+function normalizeMetadataImportEntryForSelection(
+    rawMetadataEntry: unknown,
+    index: number,
+    importedMetadataKeys: Set<string>,
+): MetadataImportEntry | string {
+    if (!rawMetadataEntry || typeof rawMetadataEntry !== 'object') {
+        return `Metadata entry #${index + 1} must be an object.`;
+    }
+
+    const rawMetadataEntryRecord = rawMetadataEntry as Record<string, unknown>;
+    const rawKey = rawMetadataEntryRecord.key;
+    if (typeof rawKey !== 'string' || rawKey.trim() === '') {
+        return `Metadata entry #${index + 1} is missing a non-empty \`key\`.`;
+    }
+
+    const key = rawKey.trim();
+    const isDuplicateKey = importedMetadataKeys.has(key);
+    if (isDuplicateKey) {
+        return `Metadata import contains duplicate key \`${key}\`.`;
+    }
+    importedMetadataKeys.add(key);
+
+    const metadataDefinition = getMetadataDefinition(key);
+    const isValueProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'value');
+    const isNoteProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'note');
+
+    if (isValueProvided && typeof rawMetadataEntryRecord.value !== 'string') {
+        return `Metadata entry \`${key}\` has invalid \`value\`; expected a string.`;
+    }
+
+    if (isNoteProvided && typeof rawMetadataEntryRecord.note !== 'string' && rawMetadataEntryRecord.note !== null) {
+        return `Metadata entry \`${key}\` has invalid \`note\`; expected a string or null.`;
+    }
+
+    if (!isValueProvided && !metadataDefinition) {
+        return spaceTrim(`
+            Metadata entry \`${key}\` is missing \`value\`.
+
+            Only built-in metadata keys can omit default values.
+        `);
+    }
+
+    const value = isValueProvided ? (rawMetadataEntryRecord.value as string) : metadataDefinition!.value;
+    const validationError = validateMetadataValue(key, value);
+
+    if (validationError) {
+        return validationError;
+    }
+
+    const metadataEntry: MetadataImportEntry = {
+        key,
+    };
+
+    if (isValueProvided) {
+        (metadataEntry as { value: string }).value = rawMetadataEntryRecord.value as string;
+    }
+
+    if (isNoteProvided) {
+        (metadataEntry as { note: string | null }).note = rawMetadataEntryRecord.note as string | null;
+    }
+
+    return metadataEntry;
+}
+
+/**
+ * Resolves the effective imported metadata value after omitted built-in defaults are applied.
+ *
+ * @param importEntry - Metadata import entry.
+ * @returns Effective imported value.
+ *
+ * @private
+ */
+function resolveImportedMetadataValue(importEntry: MetadataImportEntry): string {
+    const isValueProvided = Object.prototype.hasOwnProperty.call(importEntry, 'value');
+
+    if (isValueProvided) {
+        return importEntry.value!;
+    }
+
+    return getMetadataDefinition(importEntry.key)?.value ?? '';
+}
+
+/**
+ * Resolves the effective imported metadata note after omitted built-in defaults are applied.
+ *
+ * @param importEntry - Metadata import entry.
+ * @returns Effective imported note.
+ *
+ * @private
+ */
+function resolveImportedMetadataNote(importEntry: MetadataImportEntry): string | null {
+    const isNoteProvided = Object.prototype.hasOwnProperty.call(importEntry, 'note');
+
+    if (isNoteProvided) {
+        return importEntry.note!;
+    }
+
+    return getMetadataDefinition(importEntry.key)?.note ?? null;
+}
+
+/**
+ * Formats one metadata value for compact import choice dialogs.
+ *
+ * @param value - Raw value or note.
+ * @returns Single-line preview for the dialog body.
+ *
+ * @private
+ */
+function formatMetadataImportDialogValue(value: string | null | undefined): string {
+    if (value === null || value === undefined) {
+        return METADATA_IMPORT_EMPTY_VALUE_LABEL;
+    }
+
+    const normalizedValue = value.replace(/\s+/g, ' ').trim();
+
+    if (normalizedValue === '') {
+        return METADATA_IMPORT_EMPTY_VALUE_LABEL;
+    }
+
+    if (normalizedValue.length <= METADATA_IMPORT_VALUE_PREVIEW_MAX_LENGTH) {
+        return normalizedValue;
+    }
+
+    return `${normalizedValue.slice(0, METADATA_IMPORT_VALUE_PREVIEW_MAX_LENGTH)}...`;
+}
+
+/**
+ * Asks the admin which imported metadata entries should replace current values.
+ *
+ * @param importPayload - Parsed metadata import payload.
+ * @param currentMetadataEntries - Metadata entries currently displayed in the admin table.
+ * @returns Filtered import payload containing only selected entries.
+ *
+ * @private
+ */
+async function createSelectedMetadataImportPayload(
+    importPayload: MetadataImportPayload,
+    currentMetadataEntries: ReadonlyArray<MetadataEntry>,
+): Promise<MetadataImportPayload> {
+    const currentMetadataByKey = new Map<string, MetadataEntry>(
+        currentMetadataEntries.map((metadataEntry) => [metadataEntry.key, metadataEntry]),
+    );
+    const selectedMetadataEntries: Array<MetadataImportEntry> = [];
+
+    for (const importEntry of importPayload.metadata) {
+        const currentMetadataEntry = currentMetadataByKey.get(importEntry.key);
+        const currentValue = currentMetadataEntry?.value ?? METADATA_IMPORT_MISSING_VALUE_LABEL;
+        const currentNote = currentMetadataEntry?.note ?? null;
+        const importedValue = resolveImportedMetadataValue(importEntry);
+        const importedNote = resolveImportedMetadataNote(importEntry);
+        const isImportedSelected = await showConfirm({
+            title: `Import ${importEntry.key}`,
+            message: spaceTrim(`
+                Choose metadata for \`${importEntry.key}\`.
+
+                Current value: ${formatMetadataImportDialogValue(currentValue)}
+                Imported value: ${formatMetadataImportDialogValue(importedValue)}
+                Current note: ${formatMetadataImportDialogValue(currentNote)}
+                Imported note: ${formatMetadataImportDialogValue(importedNote)}
+            `),
+            confirmLabel: 'Use imported',
+            cancelLabel: 'Keep current',
+        }).catch(() => false);
+
+        if (isImportedSelected) {
+            selectedMetadataEntries.push(importEntry);
+        }
+    }
+
+    return {
+        promptbookVersion: importPayload.promptbookVersion,
+        metadata: selectedMetadataEntries,
+    };
+}
+
 /**
  * Validates whether the provided string is an IPv4, IPv6, or CIDR range.
  *
@@ -380,16 +738,16 @@ function mergeMetadataWithDefaults(data: MetadataEntry[]): MetadataEntry[] {
 
     // First prefer existing (non-default) metadata coming from the database
     for (const entry of data) {
-            const existing = byKey.get(entry.key);
-            if (!existing || existing.isDefault) {
-                const definition = getMetadataDefinition(entry.key);
-                byKey.set(entry.key, {
-                    ...entry,
-                    definition,
-                    deprecatedLimitMetadata: getDeprecatedLimitMetadataDefinition(entry.key),
-                });
-            }
+        const existing = byKey.get(entry.key);
+        if (!existing || existing.isDefault) {
+            const definition = getMetadataDefinition(entry.key);
+            byKey.set(entry.key, {
+                ...entry,
+                definition,
+                deprecatedLimitMetadata: getDeprecatedLimitMetadataDefinition(entry.key),
+            });
         }
+    }
 
     // Then add defaults only for keys that are missing
     for (const def of metadataDefaults) {
@@ -534,29 +892,32 @@ export function MetadataClient() {
             return;
         }
 
-        const isConfirmed = await showConfirm({
-            title: 'Import metadata',
-            message: 'Import metadata from this JSON file? Existing built-in metadata not present in the file will be reset to defaults.',
-            confirmLabel: 'Import metadata',
-            cancelLabel: 'Cancel',
-        }).catch(() => false);
-
-        if (!isConfirmed) {
-            if (importFileInputRef.current) {
-                importFileInputRef.current.value = '';
-            }
-            return;
-        }
-
         setError(null);
         setSuccessMessage(null);
         setIsImportingMetadata(true);
 
         try {
-            const response = await fetch(METADATA_IMPORT_ENDPOINT, {
+            const parsedImportPayload = parseMetadataImportPayloadForSelection(await file.text());
+
+            if (parsedImportPayload.errorMessage || !parsedImportPayload.payload) {
+                setError(parsedImportPayload.errorMessage || 'Metadata import failed.');
+                return;
+            }
+
+            const selectedImportPayload = await createSelectedMetadataImportPayload(
+                parsedImportPayload.payload,
+                metadata,
+            );
+
+            if (selectedImportPayload.metadata.length === 0) {
+                setSuccessMessage('Metadata import skipped; all imported entries kept current.');
+                return;
+            }
+
+            const response = await fetch(METADATA_IMPORT_WITHOUT_DEFAULT_RESET_ENDPOINT, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: await file.text(),
+                body: JSON.stringify(selectedImportPayload),
             });
 
             if (!response.ok) {
@@ -676,7 +1037,6 @@ export function MetadataClient() {
         }
     };
 
-
     /**
      * Parameters required to upload an image and store the resulting URL in a metadata form.
      *
@@ -1017,11 +1377,16 @@ export function MetadataClient() {
                                                                     Value
                                                                 </label>
                                                                 <MetadataValueField
-                                                                    definition={getMetadataDefinition(editingFormState.key)}
+                                                                    definition={getMetadataDefinition(
+                                                                        editingFormState.key,
+                                                                    )}
                                                                     fieldId={editValueFieldId}
                                                                     value={editingFormState.value}
                                                                     onValueChange={(value) =>
-                                                                        setEditingFormState((prev) => ({ ...prev, value }))
+                                                                        setEditingFormState((prev) => ({
+                                                                            ...prev,
+                                                                            value,
+                                                                        }))
                                                                     }
                                                                     isUploading={isEditUploading}
                                                                     isUploadAvailable={

package/apps/agents-server/src/app/api/agents/export/route.ts

@@ -1,3 +1,4 @@
+import { ParseError } from '@promptbook-local/core';
 import { NextResponse } from 'next/server';
 import { Readable } from 'node:stream';
 import { createAgentsExportZipStream } from '../../../../utils/agentsTransfer/createAgentsExportZipStream';
@@ -16,15 +17,17 @@ export const runtime = 'nodejs';
 /**
  * Streams an agents-only ZIP export containing book files in folder structure.
  *
+ * @param request - Export request with an optional `folderId` search parameter.
  * @returns ZIP response for admins or `401` for non-admin callers.
  */
-export async function GET() {
+export async function GET(request: Request) {
     if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
     try {
-        const { filename, stream } = await createAgentsExportZipStream();
+        const folderId = parseAgentsExportFolderId(new URL(request.url).searchParams.get('folderId'));
+        const { filename, stream } = await createAgentsExportZipStream({ folderId });
         const body = Readable.toWeb(stream as Readable) as ReadableStream<Uint8Array>;
 
         return new NextResponse(body, {
@@ -35,7 +38,30 @@ export async function GET() {
             },
         });
     } catch (error) {
+        if (error instanceof ParseError) {
+            return NextResponse.json({ error: error.message }, { status: 400 });
+        }
+
         console.error('Agents export error:', error);
         return NextResponse.json({ error: 'Failed to generate agents export.' }, { status: 500 });
     }
 }
+
+/**
+ * Parses the optional folder scope for agents export.
+ *
+ * @param value - Raw `folderId` search parameter.
+ * @returns Folder id or `undefined` for full-server exports.
+ */
+function parseAgentsExportFolderId(value: string | null): number | undefined {
+    if (value === null || value === '' || value === 'null') {
+        return undefined;
+    }
+
+    const parsedValue = Number(value);
+    if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+        throw new ParseError(`Invalid export folder id \`${value}\`.`);
+    }
+
+    return parsedValue;
+}