@promptbook/cli 0.113.0-8 → 0.113.0-9

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

@@ -3,7 +3,8 @@ import { AVATAR_VISUALS, resolveAvatarVisualId } from '../../../../src/avatars/v
 import { DEFAULT_AGENT_AVATAR_VISUAL_ID as SHARED_DEFAULT_AGENT_AVATAR_VISUAL_ID } from '../../../../src/utils/agents/resolveAgentAvatarImageUrl';
 
 /**
- * Metadata key controlling the built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`.
+ * Metadata key controlling the built-in avatar visual used for agents without `META IMAGE`, `META AVATAR`,
+ * or `META VISUAL`.
  */
 export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_KEY = 'DEFAULT_AGENT_AVATAR_VISUAL';
 
@@ -58,8 +59,8 @@ export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUE =
 /**
  * Resolves one raw metadata value to a supported built-in avatar visual id.
  *
- * The same separator-insensitive lookup is shared with `META AVATAR`, so both
- * `PIXEL_ART` and `pixel art` resolve to the same built-in visual.
+ * The same separator-insensitive lookup is shared with `META AVATAR` / `META VISUAL`,
+ * so both `PIXEL_ART` and `pixel art` resolve to the same built-in visual.
  *
  * @param value - Raw metadata value stored in `Metadata`.
  * @returns Safe supported visual id.

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

@@ -407,7 +407,7 @@ export const metadataDefaults: ReadonlyArray<MetadataDefinition> = [
     {
         key: DEFAULT_AGENT_AVATAR_VISUAL_METADATA_KEY,
         value: DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUE,
-        note: `Default built-in avatar visual used for agents without \`META IMAGE\` or \`META AVATAR\`. Allowed values: ${formatMetadataOptionValues(
+        note: `Default built-in avatar visual used for agents without \`META IMAGE\`, \`META AVATAR\`, or \`META VISUAL\`. Allowed values: ${formatMetadataOptionValues(
             DEFAULT_AGENT_AVATAR_VISUAL_METADATA_OPTIONS.map(({ metadataValue, title }) => ({
                 value: metadataValue,
                 label: title,

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

@@ -1,14 +1,22 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
 import colors from 'colors';
 import {
     DATABASE_MIGRATION_APPLIED_BY,
     resolveDatabaseMigrationRuntimeConfiguration,
     runDatabaseMigrations,
+    type RunDatabaseMigrationsResult,
 } from './runDatabaseMigrations';
 import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
 import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
 
 loadAgentsServerEnvFile();
 
+/**
+ * Optional output path for a machine-readable migration summary used by standalone VPS self-update.
+ */
+const DATABASE_MIGRATION_SUMMARY_FILE_ENV_NAME = 'PTBK_DATABASE_MIGRATION_SUMMARY_FILE';
+
 /**
  * Runs manual migration command from CLI arguments.
  */
@@ -31,7 +39,7 @@ async function migrate(): Promise<void> {
     }
 
     try {
-        await runDatabaseMigrations({
+        const migrationResult = await runDatabaseMigrations({
             prefixes: runtimeConfiguration.prefixes,
             registeredServers: runtimeConfiguration.registeredServers,
             connectionString: runtimeConfiguration.connectionString,
@@ -40,6 +48,7 @@ async function migrate(): Promise<void> {
             logger: console,
             logSqlStatements: true,
         });
+        await writeDatabaseMigrationSummaryFile(migrationResult);
         console.info(colors.bgGreen('\n🎉 All migrations completed successfully'));
     } catch (error) {
         console.error(colors.bgRed('\n❌ Migration failed:'));
@@ -52,6 +61,21 @@ async function migrate(): Promise<void> {
     }
 }
 
+/**
+ * Writes machine-readable migration summary when the caller provides an output path.
+ *
+ * @param migrationResult - Result returned by the shared migration runner.
+ */
+async function writeDatabaseMigrationSummaryFile(migrationResult: RunDatabaseMigrationsResult): Promise<void> {
+    const summaryFilePath = process.env[DATABASE_MIGRATION_SUMMARY_FILE_ENV_NAME]?.trim();
+    if (!summaryFilePath) {
+        return;
+    }
+
+    await mkdir(dirname(summaryFilePath), { recursive: true });
+    await writeFile(summaryFilePath, `${JSON.stringify(migrationResult, null, 2)}\n`, 'utf-8');
+}
+
 /**
  * Parses optional `--only` flag from CLI arguments.
  *

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

@@ -44,6 +44,10 @@ export type MigratePrefixOptions = {
      * Optional observer notified about the current prefix migration sub-step.
      */
     readonly onProgress?: (progress: MigratePrefixProgress) => void;
+    /**
+     * Optional observer notified after one migration file has been applied and recorded.
+     */
+    readonly onMigrationApplied?: (appliedMigration: MigratePrefixAppliedMigration) => void;
 };
 
 /**
@@ -77,6 +81,22 @@ export type MigratePrefixProgress = {
     readonly migrationFile?: string;
 };
 
+/**
+ * Snapshot emitted after one migration file has been successfully applied for one prefix.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type MigratePrefixAppliedMigration = {
+    /**
+     * Prefix currently being migrated.
+     */
+    readonly prefix: string;
+    /**
+     * Migration file that has been applied and recorded.
+     */
+    readonly migrationFile: string;
+};
+
 /**
  * Context for migrations-table schema synchronization.
  *
@@ -159,6 +179,10 @@ export async function applyPendingMigrationsForPrefix(options: MigratePrefixOpti
             [migrationFile, options.appliedBy],
         );
         appliedCount++;
+        options.onMigrationApplied?.({
+            prefix: options.prefix,
+            migrationFile,
+        });
         options.logger.info(`  ✅ Applied ${migrationFile}`);
     }
 

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

@@ -109,6 +109,10 @@ export type DatabaseMigrationPrefixResult = {
      * Number of newly applied migration files.
      */
     readonly appliedCount: number;
+    /**
+     * Migration filenames newly applied for this prefix.
+     */
+    readonly appliedMigrationFiles: ReadonlyArray<string>;
 };
 
 /**
@@ -270,6 +274,7 @@ export async function runDatabaseMigrations(
         }
 
         for (const prefix of selectedPrefixes) {
+            const appliedMigrationFiles: Array<string> = [];
             failureContext.stage = 'migrate-prefix';
             failureContext.currentPrefix = prefix;
             failureContext.currentPrefixStage = undefined;
@@ -289,8 +294,11 @@ export async function runDatabaseMigrations(
                     failureContext.currentPrefixStage = stage;
                     failureContext.currentMigrationFile = migrationFile;
                 },
+                onMigrationApplied: ({ migrationFile }) => {
+                    appliedMigrationFiles.push(migrationFile);
+                },
             });
-            perPrefix.push({ prefix, appliedCount });
+            perPrefix.push({ prefix, appliedCount, appliedMigrationFiles });
         }
 
         return {

package/apps/agents-server/src/instrumentation-node.ts

@@ -15,6 +15,21 @@ export async function registerNodeRuntimeInstrumentation(): Promise<void> {
             createAutomaticMigrationFailureLogContext(error),
         );
     }
+
+    try {
+        const { ensureAutomaticVpsSelfUpdateSchedulerBootstrapped } = await import(
+            './utils/vpsSelfUpdate/vpsSelfUpdateScheduler'
+        );
+        ensureAutomaticVpsSelfUpdateSchedulerBootstrapped();
+    } catch (error) {
+        console.error('❌ Automatic VPS self-update scheduler failed during Agents Server instrumentation.', {
+            nextRuntime: process.env.NEXT_RUNTIME,
+            nodeEnv: process.env.NODE_ENV,
+            errorName: error instanceof Error ? error.name : undefined,
+            errorMessage: error instanceof Error ? error.message : String(error),
+            errorStack: error instanceof Error ? error.stack : undefined,
+        });
+    }
 }
 
 /**

package/apps/agents-server/src/languages/ServerTranslationKeys.ts

@@ -143,6 +143,7 @@ export const SERVER_TRANSLATION_KEYS = [
     'header.createNewUser',
     'header.servers',
     'header.environmentVariables',
+    'header.resourceMonitor',
     'header.update',
     'header.database',
     'header.logs',

package/apps/agents-server/src/languages/translations/czech.yaml

@@ -137,6 +137,7 @@ header.viewAllUsers: Zobrazit všechny uživatele
 header.createNewUser: Vytvořit nového uživatele
 header.servers: Servery
 header.environmentVariables: Proměnné prostředí
+header.resourceMonitor: Monitoring zdrojů
 header.update: Aktualizace
 header.database: Databáze
 header.logs: Logy

package/apps/agents-server/src/languages/translations/english.yaml

@@ -139,6 +139,7 @@ header.viewAllUsers: View all users
 header.createNewUser: Create new user
 header.servers: Servers
 header.environmentVariables: Environment variables
+header.resourceMonitor: Resource monitor
 header.update: Update
 header.database: Database
 header.logs: Logs

package/apps/agents-server/src/{components/Homepage → utils/agentOrganization}/hiddenFolders.ts

@@ -1,24 +1,53 @@
-import type { AgentOrganizationAgent, AgentOrganizationFolder } from '../../utils/agentOrganization/types';
-import { buildFolderMaps, collectDescendantFolderIds } from './agentOrganizationUtils';
+import { buildFolderTree, collectDescendantFolderIds } from './folderTree';
 
 /**
- * Prefix that marks a folder as hidden from default homepage listings.
+ * Prefix that marks a folder as hidden from default organization 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.
+ * from default agent/folder listings unless the caller explicitly opts into showing them.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
 export const HIDDEN_FOLDER_NAME_PREFIX = '.';
 
+/**
+ * Minimal folder shape required by the hidden-folder utilities.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type HiddenFolderTreeFolder = {
+    readonly id: number;
+    readonly name: string;
+    readonly parentId: number | null;
+};
+
+/**
+ * Minimal agent shape required by the hidden-folder utilities.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type HiddenFolderTreeAgent = {
+    readonly folderId: number | null;
+};
+
+/**
+ * Result of removing hidden folders and their agents from one organization snapshot.
+ *
+ * @private shared hidden-folder helper for Agents Server
+ */
+type FilterHiddenFolderTreeResult<TFolder extends HiddenFolderTreeFolder, TAgent extends HiddenFolderTreeAgent> = {
+    readonly folders: TFolder[];
+    readonly agents: TAgent[];
+    readonly hasHiddenFolders: boolean;
+};
+
 /**
  * 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
+ * @private shared hidden-folder helper for Agents Server
  */
 export function isHiddenFolderName(folderName: string): boolean {
     return folderName.startsWith(HIDDEN_FOLDER_NAME_PREFIX);
@@ -34,10 +63,10 @@ export function isHiddenFolderName(folderName: string): boolean {
  * @param folders - All folders in the organization.
  * @returns Set of folder identifiers that should be excluded from default views.
  *
- * @private function of AgentsList
+ * @private shared hidden-folder helper for Agents Server
  */
-export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationFolder>): Set<number> {
-    const folderMaps = buildFolderMaps(folders);
+export function collectHiddenFolderIds(folders: ReadonlyArray<HiddenFolderTreeFolder>): Set<number> {
+    const folderTree = buildFolderTree(Array.from(folders));
     const hiddenFolderIds = new Set<number>();
 
     for (const folder of folders) {
@@ -45,7 +74,7 @@ export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationF
             continue;
         }
 
-        for (const descendantId of collectDescendantFolderIds(folder.id, folderMaps.childrenByParentId)) {
+        for (const descendantId of collectDescendantFolderIds(folder.id, folderTree.childrenByParentId)) {
             hiddenFolderIds.add(descendantId);
         }
     }
@@ -53,37 +82,28 @@ export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationF
     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.
+ * descendants and the agents inside them) are removed in one pass.
  *
  * @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
+ * @private shared hidden-folder helper for Agents Server
  */
-export function filterHiddenFolderTree(
-    folders: ReadonlyArray<AgentOrganizationFolder>,
-    agents: ReadonlyArray<AgentOrganizationAgent>,
+export function filterHiddenFolderTree<
+    TFolder extends HiddenFolderTreeFolder,
+    TAgent extends HiddenFolderTreeAgent,
+>(
+    folders: ReadonlyArray<TFolder>,
+    agents: ReadonlyArray<TAgent>,
     isHiddenFoldersVisible: boolean,
-): FilterHiddenFolderTreeResult {
+): FilterHiddenFolderTreeResult<TFolder, TAgent> {
     const hasHiddenFolders = folders.some((folder) => isHiddenFolderName(folder.name));
 
     if (isHiddenFoldersVisible || !hasHiddenFolders) {

package/apps/agents-server/src/utils/chat/createAttachmentAwareCitationLabelResolver.ts

@@ -0,0 +1,147 @@
+'use client';
+
+import type { CitationLabelResolver, ChatMessage, ParsedCitation } from '@promptbook-local/types';
+import { resolveAgentsServerCitationLabel } from './resolveAgentsServerCitationLabel';
+
+/**
+ * Pattern matching trailing punctuation a model may append after a cited URL.
+ *
+ * @private utility constant of Agents Server chat citations
+ */
+const TRAILING_URL_PUNCTUATION_REGEX = /[.,;:!?)\]]+$/;
+
+/**
+ * Creates a citation-label resolver that prefers original chat attachment filenames.
+ *
+ * Attached images and files are cited by their CDN URL, but that URL only carries
+ * a normalized (kebab-cased) filename, so the shared resolver would otherwise fetch
+ * the binary and show unreadable content. This resolver maps a citation whose URL
+ * points to one of the chat attachments back to the attachment's original `name`
+ * (for example `DSC_0139 (2).JPG`) and delegates every other citation to
+ * `resolveAgentsServerCitationLabel`.
+ *
+ * @param messages - Chat messages whose attachments provide the original filenames.
+ * @returns Resolver returning the attachment filename, or the shared server label.
+ *
+ * @private utility of Agents Server chat citations
+ */
+export function createAttachmentAwareCitationLabelResolver(
+    messages: ReadonlyArray<ChatMessage>,
+): CitationLabelResolver {
+    const attachmentNamesByUrlKey = collectAttachmentNamesByUrlKey(messages);
+
+    return async (citation) => {
+        const attachmentName = resolveAttachmentNameForCitation(citation, attachmentNamesByUrlKey);
+        if (attachmentName) {
+            return attachmentName;
+        }
+
+        return resolveAgentsServerCitationLabel(citation);
+    };
+}
+
+/**
+ * Builds a lookup from normalized attachment URL to the original attachment filename.
+ *
+ * @param messages - Chat messages that may carry file attachments.
+ * @returns Map keyed by normalized attachment URL with the original filename as value.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function collectAttachmentNamesByUrlKey(messages: ReadonlyArray<ChatMessage>): Map<string, string> {
+    const attachmentNamesByUrlKey = new Map<string, string>();
+
+    for (const message of messages) {
+        for (const attachment of message.attachments ?? []) {
+            const attachmentUrlKey = normalizeAttachmentUrlKey(attachment.url);
+            const attachmentName = attachment.name.trim();
+
+            if (attachmentUrlKey && attachmentName && !attachmentNamesByUrlKey.has(attachmentUrlKey)) {
+                attachmentNamesByUrlKey.set(attachmentUrlKey, attachmentName);
+            }
+        }
+    }
+
+    return attachmentNamesByUrlKey;
+}
+
+/**
+ * Resolves the original filename for one citation when it points to a known attachment.
+ *
+ * @param citation - Citation whose `url`/`source` may reference an attachment.
+ * @param attachmentNamesByUrlKey - Lookup produced by `collectAttachmentNamesByUrlKey`.
+ * @returns Original attachment filename or `null` when the citation is not an attachment.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function resolveAttachmentNameForCitation(
+    citation: ParsedCitation,
+    attachmentNamesByUrlKey: Map<string, string>,
+): string | null {
+    if (attachmentNamesByUrlKey.size === 0) {
+        return null;
+    }
+
+    for (const citationTarget of [citation.url, citation.source]) {
+        if (!citationTarget) {
+            continue;
+        }
+
+        const citationUrlKey = normalizeAttachmentUrlKey(citationTarget);
+        if (!citationUrlKey) {
+            continue;
+        }
+
+        const attachmentName = attachmentNamesByUrlKey.get(citationUrlKey);
+        if (attachmentName) {
+            return attachmentName;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Normalizes an attachment/citation URL into a stable comparison key.
+ *
+ * Only the origin and decoded pathname are compared so that citations reproduced
+ * by the model still match regardless of query strings or trailing punctuation.
+ *
+ * @param rawUrl - Raw URL value from an attachment or citation.
+ * @returns Comparison key, or `null` when the value is not an HTTP(S) URL.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function normalizeAttachmentUrlKey(rawUrl: string): string | null {
+    const trimmedUrl = rawUrl.trim().replace(TRAILING_URL_PUNCTUATION_REGEX, '');
+    if (!trimmedUrl) {
+        return null;
+    }
+
+    try {
+        const url = new URL(trimmedUrl);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return null;
+        }
+
+        return `${url.origin}${decodeUrlPathnameSafely(url.pathname)}`;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Safely decodes a URL pathname, falling back to the raw value on malformed input.
+ *
+ * @param pathname - Raw URL pathname.
+ * @returns Decoded pathname or the original value when decoding fails.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function decodeUrlPathnameSafely(pathname: string): string {
+    try {
+        return decodeURIComponent(pathname);
+    } catch {
+        return pathname;
+    }
+}

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

@@ -10,7 +10,7 @@ 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`.
+ * `VPS_SELF_UPDATE` represents a manual or automatic standalone VPS self-update session.
  * `BROWSER_PREVIEW` represents an ephemeral live browser stream used by citation previews.
  *
  * @private internal admin utility of Agents Server

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

@@ -7,7 +7,6 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
-import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
@@ -15,6 +14,7 @@ import {
     createUserChatRunnerThreadMessages,
     resolvePromptThreadBeforeUserMessage,
 } from '../userChat/userChatMessageLifecycle';
+import { runWithTaskTerminalCapture } from '../taskTerminal/runWithTaskTerminalCapture';
 import {
     EXTERNAL_USER_CHAT_JOB_ANSWER_TIMEOUT_MS,
     EXTERNAL_USER_CHAT_JOB_PROVIDER,
@@ -53,6 +53,15 @@ export type ProcessExternalUserChatJobResult = {
  * Processes one UserChatJob through the git-backed external runner contract.
  */
 export async function processExternalUserChatJob(job: UserChatJobRecord): Promise<ProcessExternalUserChatJobResult> {
+    return await runWithTaskTerminalCapture(job.id, () => processExternalUserChatJobWithinTerminalCapture(job));
+}
+
+/**
+ * Processes one external job while its console output is mirrored into the task terminal log.
+ */
+async function processExternalUserChatJobWithinTerminalCapture(
+    job: UserChatJobRecord,
+): Promise<ProcessExternalUserChatJobResult> {
     try {
         if (job.status === 'COMPLETED' || job.status === 'CANCELLED') {
             return { didMutate: false, outcome: 'ignored' };
@@ -189,10 +198,7 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
-            progressCard: createUserChatRunnerProgressCard({
-                runnerKind: 'external',
-                phase: 'queued_for_runner',
-            }),
+            progressCard: undefined,
         }),
     });
 

package/apps/agents-server/src/utils/getAdminChatTasksResponse/getAdminChatTasks/GetAdminChatTasksData.ts

@@ -0,0 +1,12 @@
+import type { AdminChatTaskCounters, AdminChatTaskRecord } from '../../chatTasksAdmin';
+
+/**
+ * Loaded admin chat-task data before the final response envelope is assembled.
+ *
+ * @private type of `getAdminChatTasks`
+ */
+export type GetAdminChatTasksData = {
+    items: Array<AdminChatTaskRecord>;
+    counters: AdminChatTaskCounters;
+    total: number;
+};