@promptbook/cli 0.112.0-98 → 0.112.0

package/apps/agents-server/src/app/api/admin/cli-access/route.ts

@@ -1,6 +1,4 @@
-import { NextResponse } from 'next/server';
-import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
-import { createInteractiveTerminalEventStream } from '@/src/utils/createInteractiveTerminalEventStream';
+import { createAdminTerminalRouteHandlers } from '@/src/utils/createAdminTerminalRouteHandlers';
 import {
     getLatestServerCliAccessSession,
     getServerCliAccessSession,
@@ -14,124 +12,30 @@ export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
 /**
- * Loads the latest CLI access session or streams a specific terminal session.
+ * Shared route handlers for the raw server shell terminal.
  */
-export async function GET(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const { searchParams } = new URL(request.url);
-        const sessionId = searchParams.get('sessionId')?.trim() || '';
-        const isStreamRequested = searchParams.get('stream') === '1';
-
-        if (isStreamRequested) {
-            if (!sessionId) {
-                return NextResponse.json({ error: 'CLI access session id is required.' }, { status: 400 });
-            }
-
-            const session = getServerCliAccessSession(sessionId);
-            if (!session) {
-                return NextResponse.json({ error: 'CLI access session was not found.' }, { status: 404 });
-            }
-
-            return createInteractiveTerminalEventStream(
-                request,
-                sessionId,
-                session,
-                subscribeToServerCliAccessSession,
-            );
-        }
-
-        return NextResponse.json({
-            session: getLatestServerCliAccessSession(),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to load the CLI access session.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Starts or reconnects to the raw server shell exposed in the browser.
- */
-export async function POST() {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        return NextResponse.json({
-            session: await startServerCliAccessSession(),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to start the CLI access session.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Sends raw input to the running CLI access shell.
- */
-export async function PATCH(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const body = (await request.json().catch(() => null)) as
-            | {
-                  readonly sessionId?: string;
-                  readonly input?: string;
-              }
-            | null;
-
-        if (!body?.sessionId || typeof body.input !== 'string') {
-            return NextResponse.json({ error: 'CLI access session input is required.' }, { status: 400 });
-        }
-
-        return NextResponse.json({
-            session: writeServerCliAccessSessionInput(body.sessionId, body.input),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to send CLI access input.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Stops one running CLI access shell session.
- */
-export async function DELETE(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const body = (await request.json().catch(() => null)) as
-            | {
-                  readonly sessionId?: string;
-              }
-            | null;
-
-        if (!body?.sessionId) {
-            return NextResponse.json({ error: 'CLI access session id is required.' }, { status: 400 });
-        }
-
-        return NextResponse.json({
-            session: stopServerCliAccessSession(body.sessionId),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to stop the CLI access session.' },
-            { status: 500 },
-        );
-    }
-}
+const cliAccessTerminalRouteHandlers = createAdminTerminalRouteHandlers(
+    {
+        getLatestSession: getLatestServerCliAccessSession,
+        getSession: getServerCliAccessSession,
+        startSession: startServerCliAccessSession,
+        writeSessionInput: writeServerCliAccessSessionInput,
+        stopSession: stopServerCliAccessSession,
+        subscribeToSession: subscribeToServerCliAccessSession,
+    },
+    {
+        loadErrorMessage: 'Failed to load the CLI access session.',
+        missingStreamSessionIdMessage: 'CLI access session id is required.',
+        sessionNotFoundMessage: 'CLI access session was not found.',
+        startErrorMessage: 'Failed to start the CLI access session.',
+        missingInputMessage: 'CLI access session input is required.',
+        sendErrorMessage: 'Failed to send CLI access input.',
+        missingStopSessionIdMessage: 'CLI access session id is required.',
+        stopErrorMessage: 'Failed to stop the CLI access session.',
+    },
+);
+
+export const GET = cliAccessTerminalRouteHandlers.GET;
+export const POST = cliAccessTerminalRouteHandlers.POST;
+export const PATCH = cliAccessTerminalRouteHandlers.PATCH;
+export const DELETE = cliAccessTerminalRouteHandlers.DELETE;

package/apps/agents-server/src/app/api/admin/code-runners/authentication/route.ts

@@ -1,6 +1,3 @@
-import { NextResponse } from 'next/server';
-import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
-import { createInteractiveTerminalEventStream } from '@/src/utils/createInteractiveTerminalEventStream';
 import {
     getCodeRunnerAuthenticationSession,
     getLatestCodeRunnerAuthenticationSession,
@@ -9,132 +6,43 @@ import {
     subscribeToCodeRunnerAuthenticationSession,
     writeCodeRunnerAuthenticationSessionInput,
 } from '@/src/utils/codeRunnerAuthentication';
+import { createAdminTerminalRouteHandlers } from '@/src/utils/createAdminTerminalRouteHandlers';
 import { readConfiguredCodeRunner } from '@/src/utils/codeRunnerConfiguration';
 
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
 /**
- * Loads the latest authentication session for the saved runner or streams a specific session.
+ * Shared route handlers for the code-runner authentication terminal.
  */
-export async function GET(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const { searchParams } = new URL(request.url);
-        const sessionId = searchParams.get('sessionId')?.trim() || '';
-        const isStreamRequested = searchParams.get('stream') === '1';
-
-        if (isStreamRequested) {
-            if (!sessionId) {
-                return NextResponse.json({ error: 'Authentication session id is required.' }, { status: 400 });
-            }
-
-            const session = getCodeRunnerAuthenticationSession(sessionId);
-            if (!session) {
-                return NextResponse.json({ error: 'Authentication session was not found.' }, { status: 404 });
-            }
-
-            return createInteractiveTerminalEventStream(
-                request,
-                sessionId,
-                session,
-                subscribeToCodeRunnerAuthenticationSession,
-            );
-        }
-
-        const { agent } = await readConfiguredCodeRunner();
-        return NextResponse.json({
-            session: getLatestCodeRunnerAuthenticationSession(agent),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to load the authentication session.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Starts a new browser-driven authentication terminal for the saved runner.
- */
-export async function POST() {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const { agent } = await readConfiguredCodeRunner();
-        return NextResponse.json({
-            session: await startCodeRunnerAuthenticationSession(agent),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to start the authentication session.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Sends terminal input to a running authentication session.
- */
-export async function PATCH(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const body = (await request.json().catch(() => null)) as
-            | {
-                  readonly sessionId?: string;
-                  readonly input?: string;
-              }
-            | null;
-
-        if (!body?.sessionId || typeof body.input !== 'string') {
-            return NextResponse.json({ error: 'Authentication session input is required.' }, { status: 400 });
-        }
-
-        return NextResponse.json({
-            session: writeCodeRunnerAuthenticationSessionInput(body.sessionId, body.input),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to send authentication input.' },
-            { status: 500 },
-        );
-    }
-}
-
-/**
- * Stops one authentication terminal from the admin UI.
- */
-export async function DELETE(request: Request) {
-    if (!(await isUserGlobalAdmin())) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    try {
-        const body = (await request.json().catch(() => null)) as
-            | {
-                  readonly sessionId?: string;
-              }
-            | null;
-
-        if (!body?.sessionId) {
-            return NextResponse.json({ error: 'Authentication session id is required.' }, { status: 400 });
-        }
-
-        return NextResponse.json({
-            session: stopCodeRunnerAuthenticationSession(body.sessionId),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to stop the authentication session.' },
-            { status: 500 },
-        );
-    }
-}
+const authenticationTerminalRouteHandlers = createAdminTerminalRouteHandlers(
+    {
+        async getLatestSession() {
+            const { agent } = await readConfiguredCodeRunner();
+            return getLatestCodeRunnerAuthenticationSession(agent);
+        },
+        getSession: getCodeRunnerAuthenticationSession,
+        async startSession() {
+            const { agent } = await readConfiguredCodeRunner();
+            return startCodeRunnerAuthenticationSession(agent);
+        },
+        writeSessionInput: writeCodeRunnerAuthenticationSessionInput,
+        stopSession: stopCodeRunnerAuthenticationSession,
+        subscribeToSession: subscribeToCodeRunnerAuthenticationSession,
+    },
+    {
+        loadErrorMessage: 'Failed to load the authentication session.',
+        missingStreamSessionIdMessage: 'Authentication session id is required.',
+        sessionNotFoundMessage: 'Authentication session was not found.',
+        startErrorMessage: 'Failed to start the authentication session.',
+        missingInputMessage: 'Authentication session input is required.',
+        sendErrorMessage: 'Failed to send authentication input.',
+        missingStopSessionIdMessage: 'Authentication session id is required.',
+        stopErrorMessage: 'Failed to stop the authentication session.',
+    },
+);
+
+export const GET = authenticationTerminalRouteHandlers.GET;
+export const POST = authenticationTerminalRouteHandlers.POST;
+export const PATCH = authenticationTerminalRouteHandlers.PATCH;
+export const DELETE = authenticationTerminalRouteHandlers.DELETE;

package/apps/agents-server/src/app/api/admin/code-runners/route.ts

@@ -52,7 +52,7 @@ export async function PATCH(request: Request) {
         }
 
         await updateVpsEnvironmentVariables({
-            PTBK_AGENT: body.agent || '',
+            PTBK_HARNESS: body.agent || '',
             PTBK_MODEL: body.model || '',
             PTBK_THINKING_LEVEL: body.thinkingLevel || '',
         });

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { spaceTrim } from 'spacetrim';
 import { DatabaseError } from '../../../../../../../src/errors/DatabaseError';
 import { isAgentsServerSqliteMode } from '../../../../database/agentsServerDatabaseMode';
+import { seedDefaultAgents } from '../../../../database/seedDefaultAgents';
 import { resolveCurrentServerRegistryContext } from '../../../../utils/currentServerRegistryContext';
 import { isUserAdmin } from '../../../../utils/isUserAdmin';
 import { isUserGlobalAdmin } from '../../../../utils/isUserGlobalAdmin';
@@ -97,6 +98,7 @@ export async function POST(request: Request) {
 
         const body = withEnvironmentAdminUser((await request.json()) as CreateServerInput);
         if (isAgentsServerSqliteMode()) {
+            const isDefaultAgentsInstalled = body.isDefaultAgentsInstalled !== false;
             const normalizedDomain = normalizeServerDomain(body.domain);
             if (!normalizedDomain) {
                 return NextResponse.json({ error: 'A valid domain is required.' }, { status: 400 });
@@ -114,6 +116,9 @@ export async function POST(request: Request) {
                     iconUrl: body.iconUrl,
                 });
             }
+            if (isDefaultAgentsInstalled) {
+                await seedDefaultAgents({ tablePrefix });
+            }
 
             return NextResponse.json(
                 {

package/apps/agents-server/src/app/api/admin/update/commits/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+import { listVpsSelfUpdateCandidateCommits } from '@/src/utils/vpsSelfUpdate';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/**
+ * Lists candidate commits for the standalone VPS self-update custom-target picker.
+ */
+export async function GET(request: Request) {
+    if (!(await isUserGlobalAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const requestUrl = new URL(request.url);
+        const limitParameter = requestUrl.searchParams.get('limit');
+        const parsedLimit = limitParameter ? Number.parseInt(limitParameter, 10) : null;
+
+        const commits = await listVpsSelfUpdateCandidateCommits({
+            searchText: requestUrl.searchParams.get('search'),
+            authoredAfter: requestUrl.searchParams.get('after'),
+            authoredBefore: requestUrl.searchParams.get('before'),
+            limit: Number.isFinite(parsedLimit) ? parsedLimit : null,
+        });
+
+        return NextResponse.json({ commits });
+    } catch (error) {
+        return NextResponse.json(
+            { error: error instanceof Error ? error.message : 'Failed to load candidate commits.' },
+            { status: 500 },
+        );
+    }
+}

package/apps/agents-server/src/app/api/admin/update/log/route.ts

@@ -0,0 +1,42 @@
+import { basename } from 'path';
+import { NextResponse } from 'next/server';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+import { readVpsSelfUpdateLogFileContent, resolveVpsSelfUpdateLogFilePath } from '@/src/utils/vpsSelfUpdate';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/**
+ * Streams the full persisted standalone VPS self-update log so the super-admin UI can copy or download it
+ * for sharing with the developers when a self-update fails.
+ */
+export async function GET() {
+    if (!(await isUserGlobalAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const logFileContent = await readVpsSelfUpdateLogFileContent();
+        if (logFileContent === null) {
+            return NextResponse.json(
+                { error: 'The standalone VPS self-update log file does not exist yet.' },
+                { status: 404 },
+            );
+        }
+
+        const logFileName = basename(resolveVpsSelfUpdateLogFilePath());
+        return new NextResponse(logFileContent, {
+            status: 200,
+            headers: {
+                'Content-Type': 'text/plain; charset=utf-8',
+                'Content-Disposition': `attachment; filename="${logFileName}"`,
+                'Cache-Control': 'no-store',
+            },
+        });
+    } catch (error) {
+        return NextResponse.json(
+            { error: error instanceof Error ? error.message : 'Failed to load the self-update log file.' },
+            { status: 500 },
+        );
+    }
+}

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

@@ -24,7 +24,7 @@ export async function GET() {
 }
 
 /**
- * Starts a detached standalone VPS self-update for the selected environment.
+ * Starts a detached standalone VPS self-update for the selected environment or arbitrary ref.
  */
 export async function POST(request: Request) {
     if (!(await isUserGlobalAdmin())) {
@@ -35,6 +35,8 @@ export async function POST(request: Request) {
         const body = (await request.json().catch(() => null)) as
             | {
                   readonly environment?: string;
+                  readonly customRef?: string | null;
+                  readonly originRepositoryUrl?: string | null;
               }
             | null;
 
@@ -42,7 +44,13 @@ export async function POST(request: Request) {
             return NextResponse.json({ error: 'Update environment is required.' }, { status: 400 });
         }
 
-        return NextResponse.json(await startVpsSelfUpdate(body.environment), { status: 202 });
+        const overview = await startVpsSelfUpdate({
+            environmentId: body.environment,
+            customRef: body.customRef ?? null,
+            originRepositoryUrl: body.originRepositoryUrl ?? null,
+        });
+
+        return NextResponse.json(overview, { status: 202 });
     } catch (error) {
         return NextResponse.json(
             { error: error instanceof Error ? error.message : 'Failed to start the update.' },

package/apps/agents-server/src/app/api/agents/[agentName]/route.ts

@@ -7,11 +7,23 @@ import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentColle
 import { $provideAgentReferenceResolver } from '@/src/utils/agentReferenceResolver/$provideAgentReferenceResolver';
 import { renameAgentSource } from '@/src/utils/renameAgentSource';
 import { isAgentVisibility, type AgentVisibility } from '@/src/utils/agentVisibility';
-import { TODO_any } from '@promptbook-local/types';
+import { TODO_any, type string_book } from '@promptbook-local/types';
 import { NextResponse } from 'next/server';
-import { buildAgentNameOrIdFilter } from '@/src/utils/agentIdentifier';
+import { findAgentForCallerWriteAccess } from '@/src/utils/findAgentForCallerWriteAccess';
 import { getCurrentUser } from '@/src/utils/getCurrentUser';
 import { resolveServerAgentContext } from '@/src/utils/resolveServerAgentContext';
+import { invalidateCachedActiveOrganizationSnapshots } from '@/src/utils/agentOrganization/loadAgentOrganizationState';
+import type { OwnedAgentRow } from '@/src/utils/agentOwnership';
+
+/**
+ * Resolves the stable identifier used when calling the agent collection.
+ *
+ * @param agent - Persisted agent row.
+ * @returns Permanent id when available, otherwise the legacy agent name.
+ */
+function getAgentCollectionIdentifier(agent: OwnedAgentRow): string {
+    return agent.permanentId || agent.agentName;
+}
 
 /**
  * Handles patch.
@@ -24,6 +36,11 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             return NextResponse.json({ success: false, error: 'Forbidden' }, { status: 403 });
         }
 
+        const targetAgent = await findAgentForCallerWriteAccess(agentName);
+        if (!targetAgent || targetAgent.deletedAt) {
+            return NextResponse.json({ success: false, error: 'Agent not found' }, { status: 404 });
+        }
+
         const body = (await request.json()) as { visibility?: AgentVisibility; name?: string };
 
         if (typeof body.name === 'string') {
@@ -33,9 +50,8 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             }
 
             const collection = await $provideAgentCollectionForServer();
-            const agentId = await collection.getAgentPermanentId(agentName);
-            const agentSource = await collection.getAgentSource(agentId);
-            const nextAgentSource = renameAgentSource(agentSource, trimmedName);
+            const agentId = getAgentCollectionIdentifier(targetAgent);
+            const nextAgentSource = renameAgentSource(targetAgent.agentSource as string_book, trimmedName);
 
             await collection.updateAgentSource(agentId, nextAgentSource);
             const baseAgentReferenceResolver = await $provideAgentReferenceResolver();
@@ -45,6 +61,7 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
                 localServerUrl: new URL(request.url).origin,
                 fallbackResolver: baseAgentReferenceResolver,
             });
+            invalidateCachedActiveOrganizationSnapshots();
 
             return NextResponse.json({
                 success: true,
@@ -67,13 +84,15 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             .from(await $getTableName(`Agent`))
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             .update({ visibility } as any)
-            .or(buildAgentNameOrIdFilter(agentName))
+            .eq('id', targetAgent.id)
             .is('deletedAt', null);
 
         if (updateResult.error) {
             return NextResponse.json({ success: false, error: updateResult.error.message }, { status: 500 });
         }
 
+        invalidateCachedActiveOrganizationSnapshots();
+
         return NextResponse.json({ success: true });
     } catch (error) {
         return NextResponse.json(
@@ -88,15 +107,20 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
  */
 export async function DELETE(request: Request, { params }: { params: Promise<{ agentName: string }> }) {
     const { agentName } = await params;
-    const collection = await $provideAgentCollectionForServer();
 
     try {
         if (!(await getCurrentUser())) {
             return NextResponse.json({ success: false, error: 'Forbidden' }, { status: 403 });
         }
 
-        const agentId = await collection.getAgentPermanentId(agentName);
-        await collection.deleteAgent(agentId);
+        const targetAgent = await findAgentForCallerWriteAccess(agentName);
+        if (!targetAgent || targetAgent.deletedAt) {
+            return NextResponse.json({ success: false, error: 'Agent not found' }, { status: 404 });
+        }
+
+        const collection = await $provideAgentCollectionForServer();
+        await collection.deleteAgent(getAgentCollectionIdentifier(targetAgent));
+        invalidateCachedActiveOrganizationSnapshots();
         return NextResponse.json({ success: true });
     } catch (error) {
         return NextResponse.json(

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

@@ -0,0 +1,67 @@
+import { ParseError } from '@promptbook-local/core';
+import { NextResponse } from 'next/server';
+import { Readable } from 'node:stream';
+import { createAgentsExportZipStream } from '../../../../utils/agentsTransfer/createAgentsExportZipStream';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
+
+/**
+ * This route is always dynamic because it depends on live DB state and auth.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Streaming ZIP generation requires the Node.js runtime.
+ */
+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(request: Request) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        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, {
+            headers: {
+                'Content-Type': 'application/zip',
+                'Content-Disposition': `attachment; filename="${filename}"`,
+                'Cache-Control': 'no-store',
+            },
+        });
+    } 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;
+}