@promptbook/cli 0.113.0-0 → 0.113.0-10

package/apps/agents-server/src/utils/taskTerminal/taskTerminalLog.ts

@@ -0,0 +1,360 @@
+import { EventEmitter } from 'events';
+
+/**
+ * Maximum buffered terminal output kept in memory for one task.
+ */
+const MAX_TASK_TERMINAL_OUTPUT_LENGTH = 200_000;
+
+/**
+ * How long a finished task terminal stays readable for post-mortem inspection.
+ */
+const TASK_TERMINAL_RETENTION_MILLISECONDS = 30 * 60 * 1000;
+
+/**
+ * Maximum number of task terminals tracked at once before the oldest ones are evicted.
+ */
+const MAX_TRACKED_TASK_TERMINAL_COUNT = 200;
+
+/**
+ * ANSI dim style used for terminal line timestamps.
+ */
+const ANSI_STYLE_DIM = '\x1b[2m';
+
+/**
+ * ANSI style reset used after styled terminal fragments.
+ */
+const ANSI_STYLE_RESET = '\x1b[0m';
+
+/**
+ * Serializable snapshot of one task-scoped terminal log.
+ *
+ * The shape intentionally matches the shared `AdminTerminalSession` browser contract
+ * so the existing admin terminal SSE helper and xterm renderer can be reused.
+ */
+export type TaskTerminalLogSnapshot = {
+    /**
+     * Task identifier the terminal output belongs to.
+     */
+    readonly id: string;
+
+    /**
+     * Whether the task is still expected to produce more output.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * Buffered task terminal output.
+     */
+    readonly output: string;
+
+    /**
+     * ISO timestamp of the first captured output.
+     */
+    readonly startedAt: string;
+
+    /**
+     * ISO timestamp when the task terminal was marked finished, when available.
+     */
+    readonly finishedAt: string | null;
+
+    /**
+     * Synthetic exit code once the task finished (`0` on success, `1` otherwise).
+     */
+    readonly exitCode: number | null;
+
+    /**
+     * Always `null` — task terminals are not backed by one dedicated OS process.
+     */
+    readonly signal: null;
+};
+
+/**
+ * Output event emitted while one task terminal is collecting output.
+ */
+export type TaskTerminalLogOutputEvent = {
+    readonly type: 'output';
+    readonly chunk: string;
+};
+
+/**
+ * Exit event emitted when one task terminal is marked finished.
+ */
+export type TaskTerminalLogExitEvent = {
+    readonly type: 'exit';
+    readonly snapshot: TaskTerminalLogSnapshot;
+};
+
+/**
+ * Browser stream callbacks used by one subscribed task terminal client.
+ */
+export type TaskTerminalLogSubscriber = {
+    /**
+     * Called whenever new task terminal output arrives.
+     */
+    readonly onOutput: (event: TaskTerminalLogOutputEvent) => void;
+
+    /**
+     * Called once the task terminal is marked finished.
+     */
+    readonly onExit: (event: TaskTerminalLogExitEvent) => void;
+};
+
+/**
+ * Internal mutable per-task terminal state stored in-process.
+ */
+type TaskTerminalLogEntry = {
+    readonly taskId: string;
+    readonly events: EventEmitter<{
+        output: [TaskTerminalLogOutputEvent];
+        exit: [TaskTerminalLogExitEvent];
+    }>;
+    readonly startedAt: Date;
+    cleanupTimeout: NodeJS.Timeout | null;
+    output: string;
+    isFinished: boolean;
+    finishedAt: Date | null;
+    exitCode: number | null;
+    updatedAtMs: number;
+};
+
+/**
+ * Shared in-memory task terminal state reused across requests in the server process.
+ */
+type TaskTerminalLogState = {
+    readonly entriesByTaskId: Map<string, TaskTerminalLogEntry>;
+};
+
+/**
+ * Appends one output chunk to the terminal log of the given task.
+ *
+ * The task terminal log is created lazily on the first appended chunk. A previously
+ * finished terminal is reopened so retried tasks keep collecting output into the
+ * same buffer.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param chunk - Raw terminal text to append.
+ */
+export function appendTaskTerminalLogOutput(taskId: string, chunk: string): void {
+    if (!chunk) {
+        return;
+    }
+
+    const entry = ensureTaskTerminalLogEntry(taskId);
+
+    if (entry.isFinished) {
+        reopenTaskTerminalLogEntry(entry);
+    }
+
+    entry.output = (entry.output + chunk).slice(-MAX_TASK_TERMINAL_OUTPUT_LENGTH);
+    entry.updatedAtMs = Date.now();
+    entry.events.emit('output', {
+        type: 'output',
+        chunk,
+    });
+}
+
+/**
+ * Appends one timestamped line to the terminal log of the given task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param message - Line content, optionally containing ANSI styling.
+ */
+export function appendTaskTerminalLogLine(taskId: string, message: string): void {
+    appendTaskTerminalLogOutput(
+        taskId,
+        `${ANSI_STYLE_DIM}${new Date().toISOString()}${ANSI_STYLE_RESET} ${message}\n`,
+    );
+}
+
+/**
+ * Marks one task terminal as finished and notifies live subscribers.
+ *
+ * Does nothing when no output was ever captured for the task in this process.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param options - Finish metadata.
+ */
+export function markTaskTerminalLogFinished(taskId: string, options: { readonly isSuccessful: boolean }): void {
+    const entry = getTaskTerminalLogState().entriesByTaskId.get(taskId);
+    if (!entry || entry.isFinished) {
+        return;
+    }
+
+    entry.isFinished = true;
+    entry.finishedAt = new Date();
+    entry.exitCode = options.isSuccessful ? 0 : 1;
+    entry.updatedAtMs = Date.now();
+
+    entry.events.emit('exit', {
+        type: 'exit',
+        snapshot: createTaskTerminalLogSnapshot(entry),
+    });
+
+    scheduleTaskTerminalLogCleanup(entry);
+}
+
+/**
+ * Reads the buffered terminal log snapshot for one task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @returns Snapshot or `null` when nothing was captured for the task in this process.
+ */
+export function getTaskTerminalLogSnapshot(taskId: string): TaskTerminalLogSnapshot | null {
+    const entry = getTaskTerminalLogState().entriesByTaskId.get(taskId);
+    return entry ? createTaskTerminalLogSnapshot(entry) : null;
+}
+
+/**
+ * Subscribes one browser connection to live task terminal events.
+ *
+ * The entry is created eagerly so subscribers attached before the first output
+ * chunk still receive everything the task produces later.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param subscriber - Stream callbacks.
+ * @returns Cleanup callback.
+ */
+export function subscribeToTaskTerminalLog(taskId: string, subscriber: TaskTerminalLogSubscriber): () => void {
+    const entry = ensureTaskTerminalLogEntry(taskId);
+
+    entry.events.on('output', subscriber.onOutput);
+    entry.events.on('exit', subscriber.onExit);
+
+    return () => {
+        entry.events.off('output', subscriber.onOutput);
+        entry.events.off('exit', subscriber.onExit);
+    };
+}
+
+/**
+ * Returns the mutable singleton state for task terminal logs.
+ *
+ * @returns Shared in-memory task terminal state.
+ */
+function getTaskTerminalLogState(): TaskTerminalLogState {
+    const globalState = globalThis as typeof globalThis & {
+        __promptbookTaskTerminalLogState?: TaskTerminalLogState;
+    };
+
+    if (!globalState.__promptbookTaskTerminalLogState) {
+        globalState.__promptbookTaskTerminalLogState = {
+            entriesByTaskId: new Map(),
+        };
+    }
+
+    return globalState.__promptbookTaskTerminalLogState;
+}
+
+/**
+ * Reads or creates the mutable terminal entry for one task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @returns Mutable terminal entry.
+ */
+function ensureTaskTerminalLogEntry(taskId: string): TaskTerminalLogEntry {
+    const state = getTaskTerminalLogState();
+    const existingEntry = state.entriesByTaskId.get(taskId);
+    if (existingEntry) {
+        return existingEntry;
+    }
+
+    evictStaleTaskTerminalLogEntries(state);
+
+    const entry: TaskTerminalLogEntry = {
+        taskId,
+        events: new EventEmitter(),
+        startedAt: new Date(),
+        cleanupTimeout: null,
+        output: '',
+        isFinished: false,
+        finishedAt: null,
+        exitCode: null,
+        updatedAtMs: Date.now(),
+    };
+
+    state.entriesByTaskId.set(taskId, entry);
+    return entry;
+}
+
+/**
+ * Reopens one finished terminal entry so a retried task keeps appending output.
+ *
+ * @param entry - Mutable terminal entry.
+ */
+function reopenTaskTerminalLogEntry(entry: TaskTerminalLogEntry): void {
+    entry.isFinished = false;
+    entry.finishedAt = null;
+    entry.exitCode = null;
+
+    if (entry.cleanupTimeout) {
+        clearTimeout(entry.cleanupTimeout);
+        entry.cleanupTimeout = null;
+    }
+}
+
+/**
+ * Schedules retention cleanup for one finished terminal entry.
+ *
+ * @param entry - Finished terminal entry.
+ */
+function scheduleTaskTerminalLogCleanup(entry: TaskTerminalLogEntry): void {
+    if (entry.cleanupTimeout) {
+        clearTimeout(entry.cleanupTimeout);
+    }
+
+    entry.cleanupTimeout = setTimeout(() => {
+        const state = getTaskTerminalLogState();
+        if (state.entriesByTaskId.get(entry.taskId) === entry) {
+            state.entriesByTaskId.delete(entry.taskId);
+        }
+    }, TASK_TERMINAL_RETENTION_MILLISECONDS);
+    entry.cleanupTimeout.unref?.();
+}
+
+/**
+ * Evicts the least recently updated entries when the registry grows past its cap.
+ *
+ * Finished entries are evicted first so terminals of still-running tasks survive bursts.
+ *
+ * @param state - Shared in-memory task terminal state.
+ */
+function evictStaleTaskTerminalLogEntries(state: TaskTerminalLogState): void {
+    if (state.entriesByTaskId.size < MAX_TRACKED_TASK_TERMINAL_COUNT) {
+        return;
+    }
+
+    const entriesOldestFirst = [...state.entriesByTaskId.values()].sort(
+        (leftEntry, rightEntry) =>
+            Number(rightEntry.isFinished) - Number(leftEntry.isFinished) ||
+            leftEntry.updatedAtMs - rightEntry.updatedAtMs,
+    );
+
+    for (const entry of entriesOldestFirst) {
+        if (state.entriesByTaskId.size < MAX_TRACKED_TASK_TERMINAL_COUNT) {
+            break;
+        }
+
+        if (entry.cleanupTimeout) {
+            clearTimeout(entry.cleanupTimeout);
+        }
+        state.entriesByTaskId.delete(entry.taskId);
+    }
+}
+
+/**
+ * Converts one mutable terminal entry into a browser-safe snapshot.
+ *
+ * @param entry - Mutable terminal entry.
+ * @returns Serializable terminal snapshot.
+ */
+function createTaskTerminalLogSnapshot(entry: TaskTerminalLogEntry): TaskTerminalLogSnapshot {
+    return {
+        id: entry.taskId,
+        isRunning: !entry.isFinished,
+        output: entry.output,
+        startedAt: entry.startedAt.toISOString(),
+        finishedAt: entry.finishedAt ? entry.finishedAt.toISOString() : null,
+        exitCode: entry.exitCode,
+        signal: null,
+    };
+}

package/apps/agents-server/src/utils/userChat/finalizeUserChatJob.ts

@@ -1,6 +1,7 @@
 import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
+import { markTaskTerminalLogFinished } from '../taskTerminal/taskTerminalLog';
 import type { UserChatJobRow } from './UserChatJobRow';
 import type { UserChatJobRecord, UserChatJobStatus } from './UserChatJobRecord';
 import { mapUserChatJobRow } from './mapUserChatJobRow';
@@ -20,6 +21,21 @@ export async function finalizeUserChatJob(options: {
     provider?: string | null;
     failureReason?: string | null;
     failureDetails?: string | null;
+}): Promise<UserChatJobRecord | null> {
+    const finalizedJob = await persistFinalUserChatJobStatus(options);
+    markTaskTerminalLogFinished(options.jobId, { isSuccessful: options.status === 'COMPLETED' });
+    return finalizedJob;
+}
+
+/**
+ * Persists one final job status through the mode-specific database path.
+ */
+async function persistFinalUserChatJobStatus(options: {
+    jobId: string;
+    status: FinalUserChatJobStatus;
+    provider?: string | null;
+    failureReason?: string | null;
+    failureDetails?: string | null;
 }): Promise<UserChatJobRecord | null> {
     if (isAgentsServerSqliteMode()) {
         return finalizeUserChatJobViaSupabaseQuery(options);

package/apps/agents-server/src/utils/userChat/userChatMessageLifecycle.ts

@@ -1,4 +1,6 @@
 import type { ChatMessage } from '../../../../../src/_packages/types.index';
+import { appendChatAttachmentContextWithContent } from '../../../../../src/utils/chat/chatAttachments/appendChatAttachmentContextWithContent';
+
 /**
  * Lifecycle states rendered on canonical server-owned chat messages.
  */
@@ -99,11 +101,11 @@ export function resolvePromptThreadBeforeUserMessage(
 /**
  * Creates the complete chat thread mirrored to a runner before it writes the next answer.
  */
-export function createUserChatRunnerThreadMessages(options: {
+export async function createUserChatRunnerThreadMessages(options: {
     messages: ReadonlyArray<ChatMessage>;
     userMessageId: string;
     resolveInitialAgentMessage: () => string | null | undefined;
-}): Array<UserChatRunnerThreadMessage> {
+}): Promise<Array<UserChatRunnerThreadMessage>> {
     const userMessage = options.messages.find((message) => message.id === options.userMessageId);
     if (!userMessage) {
         return [];
@@ -111,19 +113,16 @@ export function createUserChatRunnerThreadMessages(options: {
 
     const previousThreadMessages = resolvePromptThreadBeforeUserMessage(options.messages, options.userMessageId);
 
-    return [
+    const threadMessages = [
         ...createInitialUserChatRunnerThreadMessages({
             isFirstUserTurn: previousThreadMessages.length === 0,
             resolveInitialAgentMessage: options.resolveInitialAgentMessage,
         }),
         ...previousThreadMessages,
         userMessage,
-    ]
-        .filter(isUserChatRunnerThreadMessage)
-        .map((message) => ({
-            sender: message.sender,
-            content: message.content,
-        }));
+    ].filter(isUserChatRunnerThreadMessage);
+
+    return await Promise.all(threadMessages.map(createUserChatRunnerThreadMessage));
 }
 
 /**
@@ -176,3 +175,34 @@ function isUserChatRunnerThreadMessage(message: ChatMessage): message is ChatMes
     const isRunnerSender = message.sender === 'USER' || message.sender === 'AGENT';
     return message.isComplete !== false && isRunnerSender;
 }
+
+/**
+ * Creates one runner-visible message with attachment context inlined into user-authored content.
+ *
+ * @private helper of `createUserChatRunnerThreadMessages`
+ */
+async function createUserChatRunnerThreadMessage(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<UserChatRunnerThreadMessage> {
+    return {
+        sender: message.sender,
+        content: await createUserChatRunnerThreadMessageContent(message),
+    };
+}
+
+/**
+ * Adds attachment URLs and best-effort text previews to user messages mirrored into runner `.book` files.
+ *
+ * @private helper of `createUserChatRunnerThreadMessage`
+ */
+async function createUserChatRunnerThreadMessageContent(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<string> {
+    if (message.sender !== 'USER' || !message.attachments || message.attachments.length === 0) {
+        return message.content;
+    }
+
+    return await appendChatAttachmentContextWithContent(message.content, message.attachments, {
+        allowLocalhost: true,
+    });
+}

package/apps/agents-server/src/utils/userChatTimeout/userChatTimeoutStore/updateUserChatTimeoutTerminalState.ts

@@ -1,6 +1,7 @@
 import { mapUserChatTimeoutRow } from './mapUserChatTimeoutRow';
 import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
 import { provideUserChatTimeoutTable } from './provideUserChatTimeoutTable';
+import { markTaskTerminalLogFinished } from '../../taskTerminal/taskTerminalLog';
 import type { UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
 
 /**
@@ -36,5 +37,7 @@ export async function updateUserChatTimeoutTerminalState(
         throw new Error(`Failed to update user chat timeout "${timeoutId}": ${error.message}`);
     }
 
+    markTaskTerminalLogFinished(timeoutId, { isSuccessful: status === 'COMPLETED' });
+
     return data ? mapUserChatTimeoutRow(data as UserChatTimeoutRow) : null;
 }

package/apps/agents-server/src/utils/userChatTimeout/userChatTimeoutWorker.ts

@@ -10,6 +10,7 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobByClientMessageId } from '../userChat/getUserChatJobByClientMessageId';
 import { mutateUserChat } from '../userChat/mutateUserChat';
 import { triggerUserChatJobWorker } from '../userChat/triggerUserChatJobWorker';
+import { runWithTaskTerminalCapture } from '../taskTerminal/runWithTaskTerminalCapture';
 import type { UserChatTimeoutParameters, UserChatTimeoutRecord } from './UserChatTimeoutRecord';
 import { createTimeoutWakeUpMessage } from './createTimeoutWakeUpMessage';
 import {
@@ -214,7 +215,9 @@ export async function runUserChatTimeoutWorkerTick(): Promise<void> {
                 break;
             }
 
-            await processClaimedUserChatTimeout(claimedTimeout);
+            await runWithTaskTerminalCapture(claimedTimeout.timeoutId, () =>
+                processClaimedUserChatTimeout(claimedTimeout),
+            );
         }
     } catch (error) {
         console.error('[user-chat-timeout]', 'worker_tick_failed', serializeError(error as Error));

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

@@ -42,6 +42,10 @@ export const VPS_ENVIRONMENT_VARIABLE_KEYS = [
     'PTBK_AGENTS_SERVER_SQLITE_PATH',
     'SUPABASE_TABLE_PREFIX',
     'SUPABASE_AUTO_MIGRATE',
+    'PROMPTBOOK_REPOSITORY_REF',
+    'PTBK_AUTO_SELF_UPDATE_ENABLED',
+    'PTBK_AUTO_SELF_UPDATE_CRON',
+    'AGENTS_SERVER_GC_KEEP_VERSIONS',
     'COPILOT_GITHUB_TOKEN',
     'GH_TOKEN',
     'ANTHROPIC_API_KEY',

package/apps/agents-server/src/utils/vpsSelfUpdate/deleteVpsSelfUpdateInstalledVersion.ts

@@ -0,0 +1,81 @@
+import { rm, stat } from 'fs/promises';
+import { resolve } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { readPersistedVpsSelfUpdateJob } from './readPersistedVpsSelfUpdateJob';
+import { resolveManagedPromptbookRepositoryDirectory } from './vpsSelfUpdateConfiguration';
+import { resolveVpsSelfUpdateReleasesDirectory } from './vpsSelfUpdateInstalledVersions';
+
+/**
+ * Deletes one old installed Agents Server version from the releases directory.
+ *
+ * Only non-current version directories inside the releases directory can be deleted,
+ * and never while a self-update job is running (the installer may be using them).
+ *
+ * @param versionName - Release directory name shown on the Update page (e.g. `10dbbe7`).
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function deleteVpsSelfUpdateInstalledVersion(versionName: string): Promise<void> {
+    if (process.platform !== 'linux') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Installed Agents Server versions can be deleted only on the standalone Linux VPS deployment.
+            `),
+        );
+    }
+
+    const normalizedVersionName = versionName?.trim() || '';
+    if (!/^[A-Za-z0-9._-]+$/u.test(normalizedVersionName) || normalizedVersionName.startsWith('.')) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version name \`${versionName}\` is not a valid installed version.
+
+                **Version names contain only letters, digits, dots, underscores, and dashes and do not start with a dot.**
+            `),
+        );
+    }
+
+    const currentJob = await readPersistedVpsSelfUpdateJob({ isLogTailIncluded: false });
+    if (currentJob.status === 'running' && !currentJob.isStale) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Installed versions cannot be deleted while a standalone VPS self-update is running.
+            `),
+        );
+    }
+
+    const releasesDirectory = await resolveVpsSelfUpdateReleasesDirectory();
+    if (!releasesDirectory) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The releases directory with installed Agents Server versions could not be resolved on this server.
+            `),
+        );
+    }
+
+    const versionDirectory = resolve(releasesDirectory, normalizedVersionName);
+    const currentRepositoryDirectory = await resolveManagedPromptbookRepositoryDirectory();
+    if (currentRepositoryDirectory !== null && versionDirectory === currentRepositoryDirectory) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version \`${normalizedVersionName}\` is the currently deployed Agents Server version and cannot be deleted.
+            `),
+        );
+    }
+
+    try {
+        const versionDirectoryStats = await stat(versionDirectory);
+        if (!versionDirectoryStats.isDirectory()) {
+            throw new Error('Not a directory');
+        }
+    } catch {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version \`${normalizedVersionName}\` is not installed in the releases directory.
+            `),
+        );
+    }
+
+    await rm(versionDirectory, { recursive: true, force: true });
+}