@promptbook/cli 0.112.0 → 0.113.0-1

package/apps/agents-server/src/components/Homepage/hiddenFolders.ts

@@ -0,0 +1,104 @@
+import type { AgentOrganizationAgent, AgentOrganizationFolder } from '../../utils/agentOrganization/types';
+import { buildFolderMaps, collectDescendantFolderIds } from './agentOrganizationUtils';
+
+/**
+ * Prefix that marks a folder as hidden from default homepage listings.
+ *
+ * Folders whose name starts with this prefix (for example `.core`) are excluded
+ * from the agents list, graph, and office views unless the user explicitly toggles
+ * hidden-folder visibility on.
+ *
+ * @private function of AgentsList
+ */
+export const HIDDEN_FOLDER_NAME_PREFIX = '.';
+
+/**
+ * Determines whether one folder name represents a hidden folder.
+ *
+ * @param folderName - Folder name persisted in the database.
+ * @returns True when the folder should be hidden by default.
+ *
+ * @private function of AgentsList
+ */
+export function isHiddenFolderName(folderName: string): boolean {
+    return folderName.startsWith(HIDDEN_FOLDER_NAME_PREFIX);
+}
+
+/**
+ * Collects identifiers of all hidden folders together with their descendant folders.
+ *
+ * A folder is hidden when its own name starts with the hidden-folder prefix, or when
+ * it lives under another hidden folder. Descendants are included so that nested
+ * content is hidden together with the marker folder.
+ *
+ * @param folders - All folders in the organization.
+ * @returns Set of folder identifiers that should be excluded from default views.
+ *
+ * @private function of AgentsList
+ */
+export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationFolder>): Set<number> {
+    const folderMaps = buildFolderMaps(folders);
+    const hiddenFolderIds = new Set<number>();
+
+    for (const folder of folders) {
+        if (!isHiddenFolderName(folder.name)) {
+            continue;
+        }
+
+        for (const descendantId of collectDescendantFolderIds(folder.id, folderMaps.childrenByParentId)) {
+            hiddenFolderIds.add(descendantId);
+        }
+    }
+
+    return hiddenFolderIds;
+}
+
+/**
+ * Result of removing hidden folders and their agents from one organization snapshot.
+ *
+ * @private function of AgentsList
+ */
+type FilterHiddenFolderTreeResult = {
+    readonly folders: AgentOrganizationFolder[];
+    readonly agents: AgentOrganizationAgent[];
+    readonly hasHiddenFolders: boolean;
+};
+
+/**
+ * Removes hidden folders and their agents from one organization snapshot.
+ *
+ * When `isHiddenFoldersVisible` is true the snapshot passes through unchanged so the
+ * caller can render every folder. When false, all hidden folders (including their
+ * descendants and the agents inside them) are removed in one pass — keeping the
+ * single filtering rule in one place across list, graph, and office views.
+ *
+ * @param folders - All folders in the organization.
+ * @param agents - All agents in the organization.
+ * @param isHiddenFoldersVisible - Whether the user has opted to display hidden folders.
+ * @returns Filtered organization snapshot together with the unfiltered detection flag.
+ *
+ * @private function of AgentsList
+ */
+export function filterHiddenFolderTree(
+    folders: ReadonlyArray<AgentOrganizationFolder>,
+    agents: ReadonlyArray<AgentOrganizationAgent>,
+    isHiddenFoldersVisible: boolean,
+): FilterHiddenFolderTreeResult {
+    const hasHiddenFolders = folders.some((folder) => isHiddenFolderName(folder.name));
+
+    if (isHiddenFoldersVisible || !hasHiddenFolders) {
+        return {
+            folders: Array.from(folders),
+            agents: Array.from(agents),
+            hasHiddenFolders,
+        };
+    }
+
+    const hiddenFolderIds = collectHiddenFolderIds(folders);
+
+    return {
+        folders: folders.filter((folder) => !hiddenFolderIds.has(folder.id)),
+        agents: agents.filter((agent) => agent.folderId === null || !hiddenFolderIds.has(agent.folderId)),
+        hasHiddenFolders,
+    };
+}

package/apps/agents-server/src/components/Homepage/useAgentsListQueryState.ts

@@ -6,6 +6,20 @@ import { useCurrentPathQueryNavigation } from '../_utils/useCurrentPathQueryNavi
 import type { HomeViewMode } from './homeViewMode';
 import { getHomeViewQueryValue, resolveHomeViewMode } from './homeViewMode';
 
+/**
+ * Query parameter name used to opt into showing hidden folders.
+ *
+ * @private function of AgentsList
+ */
+const HIDDEN_FOLDERS_QUERY_PARAM = 'hidden';
+
+/**
+ * Query value that opts the agents list into showing hidden folders.
+ *
+ * @private function of AgentsList
+ */
+const HIDDEN_FOLDERS_VISIBLE_QUERY_VALUE = 'show';
+
 /**
  * Route/query state returned to the private `useAgentsListState` facade.
  *
@@ -13,8 +27,10 @@ import { getHomeViewQueryValue, resolveHomeViewMode } from './homeViewMode';
  */
 type UseAgentsListQueryStateResult = {
     readonly folderQuery: string | null;
+    readonly isHiddenFoldersVisible: boolean;
     readonly routeSyncKey: string;
     readonly searchParamsSnapshot: string;
+    readonly setHiddenFoldersVisible: (isVisible: boolean) => void;
     readonly setViewMode: (mode: HomeViewMode) => void;
     readonly viewMode: HomeViewMode;
     readonly updateCurrentPathQuery: ReturnType<typeof useCurrentPathQueryNavigation>;
@@ -34,6 +50,8 @@ export function useAgentsListQueryState(): UseAgentsListQueryStateResult {
     const routeSyncKey = `?${searchParamsSnapshot}`;
     const folderQuery = searchParams?.get('folder') || null;
     const viewMode = resolveHomeViewMode(searchParams?.get('view'));
+    const isHiddenFoldersVisible =
+        searchParams?.get(HIDDEN_FOLDERS_QUERY_PARAM) === HIDDEN_FOLDERS_VISIBLE_QUERY_VALUE;
 
     const setViewMode = useCallback(
         (mode: HomeViewMode) => {
@@ -51,10 +69,27 @@ export function useAgentsListQueryState(): UseAgentsListQueryStateResult {
         [searchParams, updateCurrentPathQuery],
     );
 
+    const setHiddenFoldersVisible = useCallback(
+        (isVisible: boolean) => {
+            const nextSearchParams = new URLSearchParams(searchParams?.toString() || '');
+
+            if (isVisible) {
+                nextSearchParams.set(HIDDEN_FOLDERS_QUERY_PARAM, HIDDEN_FOLDERS_VISIBLE_QUERY_VALUE);
+            } else {
+                nextSearchParams.delete(HIDDEN_FOLDERS_QUERY_PARAM);
+            }
+
+            updateCurrentPathQuery(nextSearchParams, 'replace');
+        },
+        [searchParams, updateCurrentPathQuery],
+    );
+
     return {
         folderQuery,
+        isHiddenFoldersVisible,
         routeSyncKey,
         searchParamsSnapshot,
+        setHiddenFoldersVisible,
         setViewMode,
         viewMode,
         updateCurrentPathQuery,

package/apps/agents-server/src/components/Homepage/useAgentsListState.ts

@@ -5,6 +5,7 @@ import { useMemo } from 'react';
 import type { AgentOrganizationAgent, AgentOrganizationFolder } from '../../utils/agentOrganization/types';
 import { useAgentNaming } from '../AgentNaming/AgentNamingContext';
 import { getAgentIdentifier } from './agentOrganizationUtils';
+import { filterHiddenFolderTree } from './hiddenFolders';
 import { useAgentsListAgentState } from './useAgentsListAgentState';
 import { useAgentsListDerivedState } from './useAgentsListDerivedState';
 import {
@@ -82,14 +83,22 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         showFederatedAgents,
         externalAgents: initialExternalAgents,
     } = props;
-    const { folderQuery, routeSyncKey, searchParamsSnapshot, setViewMode, updateCurrentPathQuery, viewMode } =
-        useAgentsListQueryState();
+    const {
+        folderQuery,
+        isHiddenFoldersVisible,
+        routeSyncKey,
+        searchParamsSnapshot,
+        setHiddenFoldersVisible,
+        setViewMode,
+        updateCurrentPathQuery,
+        viewMode,
+    } = useAgentsListQueryState();
     const { formatText } = useAgentNaming();
     const isTouchInput = useIsTouchInput();
     const allowFullCardDrag = canOrganize && viewMode === 'LIST' && !isTouchInput;
     const {
-        agents,
-        folders,
+        agents: agentsBeforeHiddenFilter,
+        folders: foldersBeforeHiddenFilter,
         lastSyncedRouteKey,
         persistQueuedOrganizationMutation,
         setAgents,
@@ -100,6 +109,14 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         initialFolders,
         routeSyncKey,
     });
+    const {
+        agents,
+        folders,
+        hasHiddenFolders,
+    } = useMemo(
+        () => filterHiddenFolderTree(foldersBeforeHiddenFilter, agentsBeforeHiddenFilter, isHiddenFoldersVisible),
+        [foldersBeforeHiddenFilter, agentsBeforeHiddenFilter, isHiddenFoldersVisible],
+    );
     const {
         agentCount,
         allAgentsLabel,
@@ -272,11 +289,13 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         handleRequestFolderVisibilityUpdate: folderState.handleRequestFolderVisibilityUpdate,
         handleShowQrCode: overlayState.handleShowQrCode,
         handleSubmitFolderEdit: folderState.handleSubmitFolderEdit,
+        hasHiddenFolders,
         headingTitle,
         isAgentsExporting: importExportState.isAgentsExporting,
         isAgentsImportDragActive: importExportState.isAgentsImportDragActive,
         isAgentsImporting: importExportState.isAgentsImporting,
         isFolderEditSubmitting: folderState.isFolderEditSubmitting,
+        isHiddenFoldersVisible,
         navigateToFolder,
         mazeAgents,
         officeAgents,
@@ -286,6 +305,7 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         qrCodeAgentEmail,
         qrCodeAgentUrl,
         sensors,
+        setHiddenFoldersVisible,
         setViewMode,
         viewMode,
         visibleAgentDragIds,

package/apps/agents-server/src/constants/chatVisualMode.ts

@@ -46,7 +46,7 @@ export const CHAT_VISUAL_MODE_COOKIE_NAME = 'promptbook_agents_chat_visual_mode'
 /**
  * Fallback visual mode when metadata/browser values are missing or invalid.
  */
-export const DEFAULT_CHAT_VISUAL_MODE: ChatVisualMode = CHAT_VISUAL_MODES.BUBBLE_MODE;
+export const DEFAULT_CHAT_VISUAL_MODE: ChatVisualMode = CHAT_VISUAL_MODES.ARTICLE_MODE;
 
 /**
  * Resolves one raw visual mode value to a supported mode.

package/apps/agents-server/src/constants/serverLimits.ts

@@ -39,6 +39,13 @@ export const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
  */
 export const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
 
+/**
+ * Default maximum number of local runner harness instances allowed to answer queued messages at once.
+ *
+ * @private shared Agents Server constant
+ */
+export const DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES = 3;
+
 /**
  * Stable keys used by the dedicated server-limits table.
  *
@@ -53,6 +60,7 @@ export const SERVER_LIMIT_KEYS = {
     SPAWN_AGENT_RATE_LIMIT_MAX: 'SPAWN_AGENT_RATE_LIMIT_MAX',
     SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: 'SPAWN_AGENT_RATE_LIMIT_WINDOW_MS',
     LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS: 'LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS',
+    LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES: 'LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES',
 } as const;
 
 /**
@@ -181,6 +189,17 @@ export const SERVER_LIMIT_DEFINITIONS = [
         step: 1,
         legacyMetadataKeys: [],
     },
+    {
+        key: SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+        category: 'Local agent runner',
+        title: 'Max parallel harness instances',
+        description: 'Caps how many queued chat messages the local coding-agent harness may answer at the same time.',
+        unit: 'count',
+        defaultValue: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+        minimumValue: 1,
+        step: 1,
+        legacyMetadataKeys: [],
+    },
 ] satisfies ReadonlyArray<ServerLimitDefinition>;
 
 /**

package/apps/agents-server/src/constants/themeMode.ts

@@ -46,7 +46,7 @@ export const THEME_MODE_OPTIONS: ReadonlyArray<{
 /**
  * Built-in fallback theme mode applied when metadata/browser values are missing or invalid.
  */
-export const DEFAULT_THEME_MODE: ThemeMode = THEME_MODES.SYSTEM;
+export const DEFAULT_THEME_MODE: ThemeMode = THEME_MODES.LIGHT;
 
 /**
  * Local storage key used to keep the latest browser theme mode in sync.

package/apps/agents-server/src/database/migrations/2026-05-2600-default-theme.sql

@@ -1,6 +1,6 @@
 INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
 SELECT 'DEFAULT_THEME',
-       'SYSTEM',
+       'LIGHT',
        'Default theme mode for browsers without a saved preference. Allowed values: SYSTEM, LIGHT, DARK.',
        NOW(),
        NOW()
@@ -9,7 +9,7 @@ WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_THEME')
 UPDATE "prefix_Metadata"
 SET "value" = CASE
                   WHEN UPPER(COALESCE("value", '')) IN ('SYSTEM', 'LIGHT', 'DARK') THEN UPPER("value")
-                  ELSE 'SYSTEM'
+                  ELSE 'LIGHT'
               END,
     "note" = 'Default theme mode for browsers without a saved preference. Allowed values: SYSTEM, LIGHT, DARK.',
     "updatedAt" = NOW()

package/apps/agents-server/src/database/seedCoreAgents.ts

@@ -6,7 +6,6 @@ import { parseAgentSource } from '../../../../src/book-2.0/agent-source/parseAge
 import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
 import { DatabaseError } from '../../../../src/errors/DatabaseError';
 import { CORE_AGENT_DIRECTORY_NAME, loadCoreAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
-import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
 import { $provideSupabaseForServer } from './$provideSupabaseForServer';
 
 /**
@@ -100,7 +99,6 @@ export async function seedCoreAgents(options: SeedCoreAgentsOptions = {}): Promi
         const createdAgent = await collection.createAgent(coreAgentBook, {
             folderId: coreFolderId,
             sortOrder: index,
-            visibility: DEFAULT_AGENT_VISIBILITY,
         });
         createdAgentNames.push(createdAgent.agentName);
         logger.info(`Created \`.core\` agent: ${createdAgent.agentName}`);

package/apps/agents-server/src/database/seedDefaultAgents.ts

@@ -2,7 +2,6 @@ import type { SupabaseClient } from '@supabase/supabase-js';
 import { AgentCollectionInSupabase } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase';
 import type { AgentsDatabaseSchema } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentsDatabaseSchema';
 import { $provideSupabaseForServer } from './$provideSupabaseForServer';
-import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
 import { loadDefaultAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
 import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
 import { seedCoreAgents } from './seedCoreAgents';
@@ -161,7 +160,6 @@ async function seedDefaultAgentBooks(
     for (const [index, defaultAgentBook] of defaultAgentBooks.entries()) {
         const createdAgent = await collection.createAgent(defaultAgentBook, {
             sortOrder: index,
-            visibility: DEFAULT_AGENT_VISIBILITY,
         });
         createdAgentNames.push(createdAgent.agentName);
         logger.info(`Created default agent: ${createdAgent.agentName}`);

package/apps/agents-server/src/tools/agent_progress.ts

@@ -8,11 +8,6 @@ import type { ChatMessage } from '@promptbook-local/types';
 import type { ChatProgressCard, ChatProgressItem } from '../../../../src/book-components/Chat/types/ChatMessage';
 import { updateUserChatAssistantMessage } from '../utils/userChat/updateUserChatAssistantMessage';
 
-/**
- * Internal default title used when the progress card is initialized without explicit heading.
- */
-const DEFAULT_PROGRESS_TITLE = 'Working on your request';
-
 /**
  * Maximum markdown length accepted for one progress-card text field.
  */
@@ -227,7 +222,6 @@ function applyAgentProgressPayloadToMessage(
 function normalizeStoredProgressCard(rawCard: ChatMessage['progressCard']): ChatProgressCard {
     if (!rawCard) {
         return {
-            title: DEFAULT_PROGRESS_TITLE,
             items: [],
             isVisible: true,
         };
@@ -244,8 +238,10 @@ function normalizeStoredProgressCard(rawCard: ChatMessage['progressCard']): Chat
               .filter((item) => item.text.length > 0)
         : [];
 
+    const normalizedTitle = normalizeOptionalText(rawCard.title);
+
     return {
-        title: normalizeOptionalText(rawCard.title) || DEFAULT_PROGRESS_TITLE,
+        ...(normalizedTitle ? { title: normalizedTitle } : {}),
         now: normalizeOptionalText(rawCard.now) || undefined,
         next: normalizeOptionalText(rawCard.next) || undefined,
         items: normalizedItems,
@@ -264,7 +260,7 @@ function applyAgentProgressPayloadToCard(
 ): ChatProgressCard {
     if (payload.action === 'initialize') {
         return {
-            title: payload.title || DEFAULT_PROGRESS_TITLE,
+            ...(payload.title ? { title: payload.title } : {}),
             ...(payload.now !== undefined ? { now: payload.now } : {}),
             ...(payload.next !== undefined ? { next: payload.next } : {}),
             items: payload.items || [],
@@ -290,7 +286,6 @@ function applyAgentProgressPayloadToCard(
 
         return {
             ...currentCard,
-            title: currentCard.title || DEFAULT_PROGRESS_TITLE,
             items: existingItems,
             updatedAt,
             isVisible: true,
@@ -303,7 +298,6 @@ function applyAgentProgressPayloadToCard(
         ...(payload.now !== undefined ? { now: payload.now } : {}),
         ...(payload.next !== undefined ? { next: payload.next } : {}),
         ...(payload.items !== undefined ? { items: payload.items } : {}),
-        title: payload.title || currentCard.title || DEFAULT_PROGRESS_TITLE,
         updatedAt,
         isVisible: true,
     };

package/apps/agents-server/src/utils/agentVisibility.ts

@@ -1,12 +1,25 @@
+import {
+    AGENT_VISIBILITY_VALUES,
+    DEFAULT_AGENT_VISIBILITY,
+    getNextAgentVisibility,
+    isAgentVisibility,
+    isPublicAgentVisibility,
+    normalizeAgentVisibility,
+    parseAgentVisibility,
+    parseAgentSourceVisibility,
+    setAgentSourceVisibility,
+    type AgentVisibility,
+} from '../../../../src/book-2.0/agent-source/agentSourceVisibility';
+
 /**
  * Supported visibility states for Agents Server agents.
  */
-export const AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'] as const;
+export { AGENT_VISIBILITY_VALUES };
 
 /**
  * Canonical visibility union for agents.
  */
-export type AgentVisibility = (typeof AGENT_VISIBILITY_VALUES)[number];
+export type { AgentVisibility };
 
 /**
  * Shared select options for agent-visibility pickers.
@@ -42,63 +55,13 @@ export const LEGACY_DEFAULT_VISIBILITY_METADATA_KEY = 'DEFAULT_AGENT_VISIBILITY'
 /**
  * Fallback visibility used when metadata is missing or invalid.
  */
-export const DEFAULT_AGENT_VISIBILITY: AgentVisibility = 'UNLISTED';
-
-/**
- * Returns `true` when the value is one of supported visibility states.
- *
- * @param value - Raw value to validate.
- * @returns Whether the value is a valid `AgentVisibility`.
- */
-export function isAgentVisibility(value: unknown): value is AgentVisibility {
-    return typeof value === 'string' && AGENT_VISIBILITY_VALUES.includes(value as AgentVisibility);
-}
-
-/**
- * Parses visibility from an unknown value with a safe fallback.
- *
- * @param value - Raw visibility value.
- * @param fallback - Fallback when the value is invalid.
- * @returns Parsed visibility.
- */
-export function parseAgentVisibility(
-    value: unknown,
-    fallback: AgentVisibility = DEFAULT_AGENT_VISIBILITY,
-): AgentVisibility {
-    if (typeof value !== 'string') {
-        return fallback;
-    }
-
-    const normalized = value.trim().toUpperCase();
-    return isAgentVisibility(normalized) ? normalized : fallback;
-}
-
-/**
- * Returns whether an agent should be listed publicly in anonymous views.
- *
- * @param visibility - Agent visibility to evaluate.
- * @returns `true` for publicly listed agents.
- */
-export function isPublicAgentVisibility(visibility: AgentVisibility | null | undefined): boolean {
-    return visibility === 'PUBLIC';
-}
-
-/**
- * Returns the next visibility in UI rotation order.
- *
- * @param visibility - Current visibility.
- * @returns Next visibility value.
- */
-export function getNextAgentVisibility(
-    visibility: AgentVisibility | null | undefined,
-): AgentVisibility {
-    switch (visibility) {
-        case 'PRIVATE':
-            return 'UNLISTED';
-        case 'UNLISTED':
-            return 'PUBLIC';
-        case 'PUBLIC':
-        default:
-            return 'PRIVATE';
-    }
-}
+export {
+    DEFAULT_AGENT_VISIBILITY,
+    getNextAgentVisibility,
+    isAgentVisibility,
+    isPublicAgentVisibility,
+    normalizeAgentVisibility,
+    parseAgentVisibility,
+    parseAgentSourceVisibility,
+    setAgentSourceVisibility,
+};

package/apps/agents-server/src/utils/chatTasksAdmin.ts

@@ -10,9 +10,11 @@ export type AdminChatTaskView = 'active' | 'running' | 'queued' | 'failed' | 'al
 /**
  * Durable task kinds currently surfaced by the admin task manager.
  *
+ * `VPS_SELF_UPDATE` represents the standalone VPS self-update session triggered from `/admin/update`.
+ *
  * @private internal admin utility of Agents Server
  */
-export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT';
+export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT' | 'VPS_SELF_UPDATE';
 
 /**
  * One row shown in the admin task-manager table.

package/apps/agents-server/src/utils/createAgentWithDefaultVisibility.ts

@@ -1,6 +1,7 @@
 import type { AgentBasicInformation, AgentCollection, string_book } from '@promptbook-local/types';
 import type { CreateAgentInput } from '../../../../src/collection/agent-collection/CreateAgentInput';
 import { assignAgentOwner } from './agentOwnership';
+import { parseAgentSourceVisibility } from './agentVisibility';
 import { getDefaultAgentVisibility } from './getDefaultAgentVisibility';
 
 /**
@@ -27,7 +28,8 @@ export async function createAgentWithDefaultVisibility(
     options: CreateAgentWithDefaultVisibilityOptions = {},
 ): Promise<AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>> {
     const { userId, ...createOptions } = options;
-    const visibility = options.visibility ?? (await getDefaultAgentVisibility());
+    const sourceVisibility = parseAgentSourceVisibility(agentSource, { isStrict: true });
+    const visibility = options.visibility ?? sourceVisibility ?? (await getDefaultAgentVisibility());
 
     const createdAgent = await collection.createAgent(agentSource, {
         ...createOptions,

package/apps/agents-server/src/utils/externalChatRunner/processExternalUserChatJob.ts

@@ -11,7 +11,10 @@ import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunn
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
-import { resolvePromptThreadBeforeUserMessage } from '../userChat/userChatMessageLifecycle';
+import {
+    createUserChatRunnerThreadMessages,
+    resolvePromptThreadBeforeUserMessage,
+} from '../userChat/userChatMessageLifecycle';
 import {
     EXTERNAL_USER_CHAT_JOB_ANSWER_TIMEOUT_MS,
     EXTERNAL_USER_CHAT_JOB_PROVIDER,
@@ -150,22 +153,11 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
         return { didMutate: false, outcome: 'waiting' };
     }
 
-    const agentInitialMessage = previousThreadMessages.length === 0
-        ? parseAgentSource(agentSourceSnapshot.agentSource).initialMessage
-        : null;
-    const initialAgentThreadMessages = agentInitialMessage
-        ? [{ sender: 'AGENT' as const, content: agentInitialMessage }]
-        : [];
-
-    const threadMessages = [
-        ...initialAgentThreadMessages,
-        ...[...previousThreadMessages, userMessage]
-            .filter((message) => message.isComplete !== false)
-            .filter((message) => message.sender === 'USER' || message.sender === 'AGENT'),
-    ].map((message) => ({
-        sender: String(message.sender),
-        content: message.content,
-    }));
+    const threadMessages = createUserChatRunnerThreadMessages({
+        messages: chat.messages,
+        userMessageId: job.userMessageId,
+        resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,
+    });
 
     const repository = await ensureExternalAgentRepository(agentSourceSnapshot);
     const queuedAt = new Date().toISOString();

package/apps/agents-server/src/utils/getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask.ts

@@ -0,0 +1,84 @@
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+import type { UserChatJobStatus } from '../userChat/UserChatJobRecord';
+import type { VpsSelfUpdateJobSnapshot } from '../vpsSelfUpdate';
+
+/**
+ * Stable synthetic task id used for the singleton standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = 'vps-self-update';
+
+/**
+ * Synthetic queue name used for the standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME = 'vps-self-update';
+
+/**
+ * Maps a persisted VPS self-update job snapshot to the admin task manager row shape.
+ *
+ * @param job - Latest persisted self-update job snapshot.
+ * @returns Task manager row or `null` when no self-update has ever been triggered on this server.
+ */
+export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot): AdminChatTaskRecord | null {
+    const status = toAdminChatTaskStatus(job);
+    if (!status) {
+        return null;
+    }
+
+    const isTerminalStatus = status === 'COMPLETED' || status === 'FAILED';
+    const startedAt = job.startedAt;
+    const finishedAt = isTerminalStatus ? job.finishedAt || startedAt : null;
+    const updatedAt = finishedAt || startedAt || new Date().toISOString();
+    const errorSummary = job.errorMessage || null;
+    const currentStepDetails = job.currentStep || null;
+
+    return {
+        id: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        kind: 'VPS_SELF_UPDATE',
+        status,
+        createdAt: startedAt || updatedAt,
+        queuedAt: startedAt || updatedAt,
+        startedAt,
+        updatedAt,
+        finishedAt,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: null,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: errorSummary,
+        lastErrorDetails: currentStepDetails,
+        userId: 0,
+        username: null,
+        agentPermanentId: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        agentName: job.targetEnvironment.label,
+        chatId: job.targetBranch || job.targetEnvironment.branch || VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        workerId: job.pid !== null ? String(job.pid) : null,
+        queueName: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME,
+    };
+}
+
+/**
+ * Maps the shell-owned self-update status to the durable chat-task status enum used by the admin task manager.
+ *
+ * @param job - Persisted self-update job snapshot.
+ * @returns Equivalent durable chat-job status, or `null` when the job is idle (no run has been triggered yet).
+ */
+function toAdminChatTaskStatus(job: VpsSelfUpdateJobSnapshot): UserChatJobStatus | null {
+    switch (job.status) {
+        case 'running':
+            return 'RUNNING';
+        case 'succeeded':
+            return 'COMPLETED';
+        case 'failed':
+            return 'FAILED';
+        case 'idle':
+            return null;
+    }
+}