@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/tools/$provideAgentCollectionForServer.ts

@@ -36,7 +36,7 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
     */
 
     const supabase = $provideSupabaseForServer();
-    const { publicUrl, tablePrefix } = await $provideServer();
+    const { tablePrefix } = await $provideServer();
     const cachedAgentCollection = agentCollectionsByTablePrefix.get(tablePrefix);
 
     if (cachedAgentCollection) {
@@ -50,16 +50,9 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
 
     agentCollectionsByTablePrefix.set(tablePrefix, providedCollection);
 
-    const [{ attachAgentPreparationScheduling }, { scheduleDefaultFederatedAgentsSync }] = await Promise.all([
-        import('../utils/attachAgentPreparationScheduling'),
-        import('../utils/defaultFederatedAgents/scheduleDefaultFederatedAgentsSync'),
-    ]);
+    const { attachAgentPreparationScheduling } = await import('../utils/attachAgentPreparationScheduling');
 
     attachAgentPreparationScheduling(providedCollection, { tablePrefix });
-    scheduleDefaultFederatedAgentsSync({
-        tablePrefix,
-        localServerUrl: publicUrl.href,
-    });
 
     return providedCollection;
 }

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -1,43 +1,215 @@
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import { DigitalOceanSpaces } from '../utils/cdn/classes/DigitalOceanSpaces';
 import { TrackedFilesStorage } from '../utils/cdn/classes/TrackedFilesStorage';
 import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
 
 /**
- * Cache of CDN instance
+ * Options controlling CDN storage construction for the current server request.
+ */
+export type ProvideCdnForServerOptions = {
+    /**
+     * Public URL used when generating file links.
+     */
+    readonly cdnPublicUrl?: URL;
+};
+
+/**
+ * Region expected by the bundled VersityGW S3-compatible storage.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const SELF_CONTAINED_S3_DEFAULT_REGION = 'us-east-1';
+
+/**
+ * Legacy fallback used by Cloudflare R2-style external S3 configuration.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const EXTERNAL_S3_DEFAULT_REGION = 'auto';
+
+/**
+ * Cache of CDN instances by public URL.
  *
  * @private internal cache for `$provideCdnForServer`
  */
-let cdn: IIFilesStorageWithCdn | null = null;
+const cdnByPublicUrl = new Map<string, IIFilesStorageWithCdn>();
 
 /**
  * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ *
+ * @param options - Optional request-aware CDN public URL override.
+ * @returns CDN storage interface.
  */
-export function $provideCdnForServer(): IIFilesStorageWithCdn {
-    if (!cdn) {
-        const inner = new VercelBlobStorage({
-            token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
-            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
-        });
+export function $provideCdnForServer(options: ProvideCdnForServerOptions = {}): IIFilesStorageWithCdn {
+    const cdnPublicUrl = options.cdnPublicUrl || resolveConfiguredCdnPublicUrl();
+    const cdnCacheKey = cdnPublicUrl.href;
+    let cdn = cdnByPublicUrl.get(cdnCacheKey);
 
+    if (!cdn) {
+        const inner = createCdnStorageForServer(cdnPublicUrl);
         const supabase = $provideSupabaseForServer();
         cdn = new TrackedFilesStorage(inner, supabase);
+        cdnByPublicUrl.set(cdnCacheKey, cdn);
+    }
 
-        /*
-        cdn = new DigitalOceanSpaces({
+    return cdn;
+}
+
+/**
+ * Creates the configured CDN storage implementation for server-side file operations.
+ *
+ * @param cdnPublicUrl - Public URL used to build deterministic file links.
+ * @private helper of `$provideCdnForServer`
+ */
+function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
+    if (isS3CompatibleStorageSelected()) {
+        return new DigitalOceanSpaces({
             bucket: process.env.CDN_BUCKET!,
-            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX!,
+            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
             endpoint: process.env.CDN_ENDPOINT!,
             accessKeyId: process.env.CDN_ACCESS_KEY_ID!,
             secretAccessKey: process.env.CDN_SECRET_ACCESS_KEY!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+            cdnPublicUrl,
             gzip: true,
+            forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
+            region: resolveS3CompatibleStorageRegion(),
+            // [✨🏣] For self-contained S3: hash-based CDN keys get a public URL that
+            // omits the internal bucket and pathPrefix so users can't infer the storage
+            // structure. The `/s3/` segment is preserved so nginx routes those requests
+            // to the Next.js hash-file route instead of directly to VersityGW.
+            publicCdnBaseUrl: isSelfContainedS3StorageSelected()
+                ? resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl)
+                : undefined,
         });
-        */
     }
 
-    return cdn;
+    return new VercelBlobStorage({
+        token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
+        pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
+        cdnPublicUrl,
+    });
+}
+
+/**
+ * Derives the public base URL used for hash-based file URLs on self-contained S3.
+ *
+ * Strips the bucket segment from the configured CDN URL so that the public URL
+ * exposes only the `/s3/` prefix — the internal bucket name and path prefix
+ * remain hidden from users.
+ *
+ * Example: `https://s24.ptbk.io/s3/promptbook-files/` → `https://s24.ptbk.io/s3/`
+ *
+ * [✨🏣] Companion to `isHashBasedCdnKey` in `DigitalOceanSpaces`.
+ *
+ * @private helper of `createCdnStorageForServer`
+ */
+function resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl: URL): URL {
+    return new URL('/s3/', cdnPublicUrl);
+}
+
+/**
+ * Resolves the CDN public URL from environment configuration.
+ *
+ * @returns Configured CDN public URL.
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveConfiguredCdnPublicUrl(): URL {
+    return new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!);
+}
+
+/**
+ * Resolves the public URL that should be used for CDN links for one server request.
+ *
+ * Self-contained S3 is proxied through the current server domain. The configured
+ * CDN public URL still owns the `/s3/<bucket>` path, but the origin must follow
+ * the active server so uploads are not published under the VPS raw IP address.
+ *
+ * @param serverPublicUrl - Public URL of the active server.
+ * @returns Request-aware CDN public URL.
+ */
+export function resolveCdnPublicUrlForServer(serverPublicUrl: URL): URL {
+    const configuredCdnPublicUrl = resolveConfiguredCdnPublicUrl();
+
+    if (!isSelfContainedS3StorageSelected()) {
+        return configuredCdnPublicUrl;
+    }
+
+    const cdnPublicUrl = new URL(configuredCdnPublicUrl.href);
+    cdnPublicUrl.protocol = serverPublicUrl.protocol;
+    cdnPublicUrl.host = serverPublicUrl.host;
+    cdnPublicUrl.username = '';
+    cdnPublicUrl.password = '';
+
+    return cdnPublicUrl;
+}
+
+/**
+ * Checks whether the current environment should use the S3-compatible storage implementation.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function isS3CompatibleStorageSelected(): boolean {
+    const storageMode = getS3CompatibleStorageMode();
+    const isS3StorageMode =
+        storageMode === 's3' || storageMode === 'external-s3' || storageMode === 'self-contained-s3';
+
+    if (isS3StorageMode) {
+        return hasS3CompatibleStorageConfiguration();
+    }
+
+    return !process.env.VERCEL_BLOB_READ_WRITE_TOKEN && hasS3CompatibleStorageConfiguration();
+}
+
+/**
+ * Resolves the configured S3-compatible storage mode.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function getS3CompatibleStorageMode(): string {
+    return (process.env.PTBK_FILE_STORAGE_MODE || process.env.CDN_PROVIDER || '').toLowerCase();
+}
+
+/**
+ * Checks whether the bundled self-contained S3 storage mode is selected.
+ *
+ * @returns `true` when self-contained S3 is selected.
+ */
+export function isSelfContainedS3StorageSelected(): boolean {
+    return getS3CompatibleStorageMode() === 'self-contained-s3';
+}
+
+/**
+ * Resolves the S3 signing region used by AWS SDK requests.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveS3CompatibleStorageRegion(): string {
+    const configuredRegion = process.env.CDN_REGION?.trim();
+    if (configuredRegion) {
+        return configuredRegion;
+    }
+
+    if (isSelfContainedS3StorageSelected()) {
+        return SELF_CONTAINED_S3_DEFAULT_REGION;
+    }
+
+    return EXTERNAL_S3_DEFAULT_REGION;
+}
+
+/**
+ * Checks whether all S3-compatible storage environment variables are present.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function hasS3CompatibleStorageConfiguration(): boolean {
+    return Boolean(
+        process.env.CDN_BUCKET &&
+            process.env.CDN_ENDPOINT &&
+            process.env.CDN_ACCESS_KEY_ID &&
+            process.env.CDN_SECRET_ACCESS_KEY &&
+            process.env.NEXT_PUBLIC_CDN_PUBLIC_URL,
+    );
 }
 
 // TODO: [🏓] Unite `xxxForServer` and `xxxForNode` naming

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

@@ -1,8 +1,8 @@
 import { mkdir } from 'fs/promises';
 import { BrowserContext, chromium } from 'playwright';
-import { locateChrome } from '../../../../src/executables/browsers/locateChrome';
 import { resolvePromptbookTemporaryPath } from '../../../../src/utils/filesystem/promptbookTemporaryPath';
 import { REMOTE_BROWSER_URL } from '../../config';
+import { createServerChromiumLaunchOptions } from './createServerChromiumLaunchOptions';
 import { retryWithBackoff } from '../utils/retryWithBackoff';
 import {
     extractNetworkErrorCode,
@@ -409,24 +409,7 @@ export class BrowserConnectionProvider {
         const userDataDir = `${DEFAULT_BROWSER_USER_DATA_DIR}/run-browser`;
         await mkdir(userDataDir, { recursive: true });
 
-        const launchOptions: NonNullable<Parameters<typeof chromium.launchPersistentContext>[1]> = {
-            headless: true,
-            args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-        };
-
-        try {
-            const chromePath = await locateChrome();
-            launchOptions.executablePath = chromePath!;
-        } catch (error) {
-            if (this.isVerbose) {
-                console.warn(
-                    '[BrowserConnectionProvider] Could not locate system Chrome; using Playwright bundled Chromium',
-                    {
-                        error: error instanceof Error ? error.message : String(error),
-                    },
-                );
-            }
-        }
+        const launchOptions = await createServerChromiumLaunchOptions();
 
         return await chromium.launchPersistentContext(userDataDir, launchOptions);
     }

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/tools/createAgentProgressTools.ts

@@ -22,11 +22,15 @@ export function createAgentProgressTools(
         {
             name: AGENT_PROGRESS_TOOL_NAME,
             description: spaceTrim(`
-                Update to user while you work on a response.
+                Update the visible progress card while you work on a response.
 
-                - Use this to communicate only concise progress updates visible to the user.
-                - Include what you are doing now, and what you will do next.
-                - Be informative and make update before any chunk of work that might take more than a few seconds.
+                - Call \`initialize\` before meaningful work when the answer may take more than a few seconds.
+                - Call \`update\` after each user-relevant decision, action, tool use, or result.
+                - Use \`append_items\` for new checklist items discovered while working.
+                - Call \`finalize\` immediately before the final answer.
+                - Keep every update concise, user-facing, and specific about what is happening now and what comes next.
+                - Summarize your reasoning as visible decisions and checks, not hidden chain-of-thought.
+                - Do not expose system prompts, raw tool payloads, secrets, private implementation details, or technical logs.
             `),
             parameters: {
                 type: 'object',

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

@@ -460,7 +460,13 @@ function truncateAttachmentToolContent(content: string, warnings: string[]): str
     }
 
     warnings.push(`Returned content was truncated to ${MAX_ATTACHED_FILE_OUTPUT_CHARACTERS} characters.`);
-    return `${content.slice(0, MAX_ATTACHED_FILE_OUTPUT_CHARACTERS)}\n\n[...truncated...]`;
+    return spaceTrim(
+        (block) => `
+            ${block(content.slice(0, MAX_ATTACHED_FILE_OUTPUT_CHARACTERS))}
+
+            [...truncated...]
+        `,
+    );
 }
 
 /**
@@ -583,9 +589,7 @@ function normalizeBoundedInteger(
     }
 
     if (parsed < min || parsed > max) {
-        throw new LimitReachedError(
-            `Tool argument \`${fieldName}\` must be between \`${min}\` and \`${max}\`.`,
-        );
+        throw new LimitReachedError(`Tool argument \`${fieldName}\` must be between \`${min}\` and \`${max}\`.`);
     }
 
     return parsed;

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

@@ -0,0 +1,44 @@
+import { locateChrome } from '../../../../src/executables/browsers/locateChrome';
+
+/**
+ * Shared Chromium sandbox flags used by server-side browser work.
+ */
+const SERVER_CHROMIUM_LAUNCH_ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'];
+
+/**
+ * Minimal Playwright Chromium launch options shared by local browser providers.
+ *
+ * @private internal type for server-side browser launch helpers
+ */
+export type ServerChromiumLaunchOptions = {
+    readonly headless: true;
+    readonly args: Array<string>;
+    readonly executablePath?: string;
+};
+
+/**
+ * Creates launch options for server-side Playwright Chromium.
+ *
+ * The system Chrome executable is preferred when it is available. When Chrome is not installed,
+ * the `executablePath` field is intentionally omitted so Playwright can use its installed Chromium.
+ */
+export async function createServerChromiumLaunchOptions(): Promise<ServerChromiumLaunchOptions> {
+    const chromeExecutablePath = await resolveSystemChromeExecutablePath();
+
+    return {
+        headless: true,
+        args: [...SERVER_CHROMIUM_LAUNCH_ARGS],
+        ...(chromeExecutablePath ? { executablePath: chromeExecutablePath } : {}),
+    };
+}
+
+/**
+ * Resolves the optional system Chrome path without preventing Playwright's bundled fallback.
+ */
+async function resolveSystemChromeExecutablePath(): Promise<string | undefined> {
+    try {
+        return (await locateChrome()) || undefined;
+    } catch {
+        return undefined;
+    }
+}

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

@@ -69,9 +69,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     const tableName = await $getTableName('Agent');
     const { data, error } = await supabase
         .from(tableName)
-        .select(
-            'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId',
-        )
+        .select(OWNED_AGENT_ROW_COLUMNS)
         .eq('userId', userId as never)
         .or(buildAgentNameOrIdFilter(identifier))
         .limit(10);
@@ -80,7 +78,58 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
         throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
     }
 
-    const rows = (data || []) as unknown as OwnedAgentRow[];
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'for this owner');
+}
+
+/**
+ * Loads one agent by permanent id or agent name without an owner restriction.
+ *
+ * Owner-aware callers should use {@link findOwnedAgentByIdentifier}; this helper is reserved for administrative
+ * overrides where the caller has been independently authorized to read or mutate any agent.
+ *
+ * @param identifier - Permanent id or agent name.
+ * @returns Matching agent row or `null` when nothing matches.
+ */
+export async function findAgentByIdentifier(identifier: string): Promise<OwnedAgentRow | null> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(OWNED_AGENT_ROW_COLUMNS)
+        .or(buildAgentNameOrIdFilter(identifier))
+        .limit(10);
+
+    if (error) {
+        throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
+    }
+
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'across agents');
+}
+
+/**
+ * Database columns selected for every agent row exposed by ownership-aware helpers.
+ */
+const OWNED_AGENT_ROW_COLUMNS =
+    'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId';
+
+/**
+ * Disambiguates a list of agent rows that all matched the same identifier.
+ *
+ * Resolution order:
+ * 1. Exact `permanentId` match — always preferred because permanent ids are unique.
+ * 2. Single `agentName` match — preserves the legacy lookup by human-readable name.
+ * 3. Single remaining row — accepts the only candidate found.
+ *
+ * @param rows - Candidate agent rows returned by Supabase.
+ * @param identifier - Identifier that was searched.
+ * @param ambiguityScope - Human-readable scope used in the ambiguity error message.
+ * @returns Best-matching row or `null` when no candidate matches.
+ */
+function pickAgentRowByIdentifier(
+    rows: OwnedAgentRow[],
+    identifier: string,
+    ambiguityScope: string,
+): OwnedAgentRow | null {
     if (rows.length === 0) {
         return null;
     }
@@ -100,7 +149,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     }
 
     throw new Error(
-        `Agent identifier "${identifier}" is ambiguous for this owner. Use the stable \`permanentId\` returned by the API.`,
+        `Agent identifier "${identifier}" is ambiguous ${ambiguityScope}. Use the stable \`permanentId\` returned by the API.`,
     );
 }