@promptbook/cli 0.113.0-7 → 0.113.0-9

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupPreviews.ts

@@ -0,0 +1,97 @@
+import type { AgentRow, BackupAgentPreview, BackupUserPreview, UserRow } from './serverBackupTypes';
+
+/**
+ * Builds the user preview map reused across metadata sidecars.
+ *
+ * @param users - Full user rows.
+ * @returns User preview map keyed by numeric id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createUserPreviewById(users: ReadonlyArray<UserRow>): Map<number, BackupUserPreview> {
+    return new Map(
+        users.map((user) => [
+            user.id,
+            {
+                id: user.id,
+                username: user.username,
+                isAdmin: user.isAdmin,
+                profileImageUrl: user.profileImageUrl,
+            } satisfies BackupUserPreview,
+        ] as const),
+    );
+}
+
+/**
+ * Builds the agent preview map keyed by numeric id.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by numeric id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewById(agents: ReadonlyArray<AgentRow>): Map<number, BackupAgentPreview> {
+    return new Map(
+        agents.map((agent) => [
+            agent.id,
+            {
+                id: agent.id,
+                agentName: agent.agentName,
+                permanentId: agent.permanentId,
+            } satisfies BackupAgentPreview,
+        ] as const),
+    );
+}
+
+/**
+ * Builds the agent preview map keyed by permanent id.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by permanent id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewByPermanentId(agents: ReadonlyArray<AgentRow>): Map<string, BackupAgentPreview> {
+    return new Map(
+        agents.flatMap((agent) =>
+            agent.permanentId
+                ? [
+                      [
+                          agent.permanentId,
+                          {
+                              id: agent.id,
+                              agentName: agent.agentName,
+                              permanentId: agent.permanentId,
+                          } satisfies BackupAgentPreview,
+                      ] as const,
+                  ]
+                : [],
+        ),
+    );
+}
+
+/**
+ * Builds the first-agent-by-name preview map used by feedback sidecars.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by agent name.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewByName(agents: ReadonlyArray<AgentRow>): Map<string, BackupAgentPreview> {
+    const agentPreviewByName = new Map<string, BackupAgentPreview>();
+
+    for (const agent of agents) {
+        if (agentPreviewByName.has(agent.agentName)) {
+            continue;
+        }
+
+        agentPreviewByName.set(agent.agentName, {
+            id: agent.id,
+            agentName: agent.agentName,
+            permanentId: agent.permanentId,
+        });
+    }
+
+    return agentPreviewByName;
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupRowUtilities.ts

@@ -0,0 +1,158 @@
+/**
+ * Groups rows by a computed key.
+ *
+ * @param rows - Rows to group.
+ * @param getKey - Key selector.
+ * @returns Grouped rows keyed by the computed value.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function groupRowsBy<Row, Key extends string | number>(
+    rows: ReadonlyArray<Row>,
+    getKey: (row: Row) => Key,
+): Map<Key, Array<Row>> {
+    const rowsByKey = new Map<Key, Array<Row>>();
+
+    for (const row of rows) {
+        const key = getKey(row);
+        const groupedRows = rowsByKey.get(key) || [];
+        groupedRows.push(row);
+        rowsByKey.set(key, groupedRows);
+    }
+
+    return rowsByKey;
+}
+
+/**
+ * Converts one unknown persisted message array into serializable objects.
+ *
+ * @param value - Raw message array candidate.
+ * @returns Serializable message array.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolveSerializableArray(value: unknown): Array<Record<string, unknown>> {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter(isRecord);
+}
+
+/**
+ * Type guard for plain objects used throughout the backup builders.
+ *
+ * @param value - Unknown value.
+ * @returns `true` when the value is a non-array object.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Deduplicates JSON-serializable objects using their serialized representation.
+ *
+ * @param values - Serializable objects.
+ * @returns Deduplicated object list in first-seen order.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function deduplicateSerializableObjects<Value extends object>(values: ReadonlyArray<Value>): Array<Value> {
+    const seenSerializedValues = new Set<string>();
+    const deduplicatedValues: Array<Value> = [];
+
+    for (const value of values) {
+        const serializedValue = JSON.stringify(value);
+        if (seenSerializedValues.has(serializedValue)) {
+            continue;
+        }
+
+        seenSerializedValues.add(serializedValue);
+        deduplicatedValues.push(value);
+    }
+
+    return deduplicatedValues;
+}
+
+/**
+ * Normalizes one optional text field to a trimmed string or `null`.
+ *
+ * @param value - Raw value.
+ * @returns Trimmed text or `null`.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function normalizeOptionalText(value: unknown): string | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const normalizedValue = value.trim();
+    return normalizedValue.length > 0 ? normalizedValue : null;
+}
+
+/**
+ * Sorts exported rows so JSON files remain stable and easier to diff.
+ *
+ * @param rows - Raw table rows fetched from Supabase.
+ * @returns Sorted shallow-cloned row list.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function sortBackupRows(rows: ReadonlyArray<Record<string, unknown>>): Array<Record<string, unknown>> {
+    return [...rows].sort(compareBackupRows);
+}
+
+/**
+ * Compares two generic backup rows using the most common stable identifier fields.
+ *
+ * @param left - First row.
+ * @param right - Second row.
+ * @returns Stable ordering for backup JSON output.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+function compareBackupRows(left: Record<string, unknown>, right: Record<string, unknown>): number {
+    const comparableKeys = ['sortOrder', 'id', 'key', 'username', 'agentName', 'permanentId', 'messageHash', 'createdAt'];
+
+    for (const comparableKey of comparableKeys) {
+        const comparison = compareComparableValues(left[comparableKey], right[comparableKey]);
+
+        if (comparison !== 0) {
+            return comparison;
+        }
+    }
+
+    return JSON.stringify(left).localeCompare(JSON.stringify(right));
+}
+
+/**
+ * Compares one optional pair of identifier values.
+ *
+ * @param left - First value.
+ * @param right - Second value.
+ * @returns Comparison result compatible with `Array.sort`.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+function compareComparableValues(left: unknown, right: unknown): number {
+    if (left === right) {
+        return 0;
+    }
+
+    if (typeof left === 'number' && typeof right === 'number') {
+        return left - right;
+    }
+
+    if (left === undefined || left === null) {
+        return 1;
+    }
+
+    if (right === undefined || right === null) {
+        return -1;
+    }
+
+    return String(left).localeCompare(String(right));
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupTypes.ts

@@ -0,0 +1,59 @@
+import type { AgentsServerDatabase } from '../../../database/schema';
+
+/**
+ * Typed row alias for `Agent`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type AgentRow = AgentsServerDatabase['public']['Tables']['Agent']['Row'];
+
+/**
+ * Typed row alias for `User`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+
+/**
+ * Typed row alias for `UserChat`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type UserChatRow = AgentsServerDatabase['public']['Tables']['UserChat']['Row'];
+
+/**
+ * Typed row alias for `ChatFeedback`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type ChatFeedbackRow = AgentsServerDatabase['public']['Tables']['ChatFeedback']['Row'];
+
+/**
+ * Typed row alias for `Wallet`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type WalletRow = AgentsServerDatabase['public']['Tables']['Wallet']['Row'];
+
+/**
+ * Shared preview persisted for referenced users inside backup metadata files.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupUserPreview = {
+    readonly id: number;
+    readonly username: string;
+    readonly isAdmin: boolean;
+    readonly profileImageUrl: string | null;
+};
+
+/**
+ * Shared preview persisted for referenced agents inside backup metadata files.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupAgentPreview = {
+    readonly id: number;
+    readonly agentName: string;
+    readonly permanentId: string | null;
+};

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;
+};