@promptbook/cli 0.112.0-104 → 0.112.0-106

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

@@ -2,9 +2,14 @@ import { $getTableName } from '@/src/database/$getTableName';
 import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
 import type { Json } from '@/src/database/schema';
 import { FILE_SECURITY_CHECKERS } from '@/src/file-security-checkers';
-import { $provideCdnForServer } from '@/src/tools/$provideCdnForServer';
+import {
+    $provideCdnForServer,
+    isSelfContainedS3StorageSelected,
+    resolveCdnPublicUrlForServer,
+} from '@/src/tools/$provideCdnForServer';
 import { $provideServer } from '@/src/tools/$provideServer';
 import { getUserFileCdnKey } from '@/src/utils/cdn/utils/getUserFileCdnKey';
+import { resolveFileUploadAvailability } from '@/src/utils/upload/fileUploadAvailability';
 import { validateMimeType } from '@/src/utils/validators/validateMimeType';
 import { normalizeChatAttachments } from '@promptbook-local/core';
 import type { TODO_any } from '@promptbook-local/types';
@@ -231,7 +236,20 @@ async function createShareTargetAttachment(file: File, maxFileUploadBytes: numbe
 
     const mimeType = resolveShareTargetMimeType(file.type);
     const blobPath = getUserFileCdnKey(buffer, normalizedFilename);
-    const cdn = $provideCdnForServer();
+    const providedServer = await $provideServer();
+    const fileUploadAvailability = resolveFileUploadAvailability({
+        serverId: providedServer.id,
+        serverPublicUrl: providedServer.publicUrl,
+        isSelfContainedS3StorageSelected: isSelfContainedS3StorageSelected(),
+    });
+
+    if (!fileUploadAvailability.isUploadAvailable) {
+        throw new NotAllowed(fileUploadAvailability.message || 'File uploads are not available for this server.');
+    }
+
+    const cdn = $provideCdnForServer({
+        cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
+    });
     const storageUrl = cdn.getItemUrl(blobPath).href;
 
     await cdn.setItem(blobPath, {

package/apps/agents-server/src/utils/upload/fileUploadAvailability.ts

@@ -0,0 +1,91 @@
+/**
+ * Message shown when self-contained file uploads cannot safely choose a serving domain.
+ */
+export const FILE_UPLOAD_REQUIRES_SERVER_DOMAIN_MESSAGE =
+    'Create the first server/domain before uploading files. Uploaded files are served from the current server domain, and raw-IP bootstrap access does not have one yet.';
+
+/**
+ * Browser-safe upload availability state.
+ */
+export type FileUploadAvailability = {
+    /**
+     * Whether file uploads may be accepted for the current request.
+     */
+    readonly isUploadAvailable: boolean;
+
+    /**
+     * User-facing reason shown when uploads are unavailable.
+     */
+    readonly message: string | null;
+};
+
+/**
+ * Inputs used to resolve whether uploads are allowed for the current server.
+ */
+export type ResolveFileUploadAvailabilityOptions = {
+    /**
+     * Current server id, or `null` before a request is matched to a server/domain.
+     */
+    readonly serverId: number | null;
+
+    /**
+     * Public URL resolved for the current request.
+     */
+    readonly serverPublicUrl: URL;
+
+    /**
+     * Whether the deployment is using the bundled self-contained S3 storage.
+     */
+    readonly isSelfContainedS3StorageSelected: boolean;
+};
+
+/**
+ * Default upload availability used when no server-side context is available.
+ */
+export const AVAILABLE_FILE_UPLOAD: FileUploadAvailability = {
+    isUploadAvailable: true,
+    message: null,
+};
+
+/**
+ * Resolves whether file uploads can be accepted for the current request.
+ *
+ * Self-contained S3 publishes files through the current server domain. While the
+ * standalone VPS is still being accessed as a bootstrap/default server, there is
+ * no server-specific domain to publish under, so uploads must be disabled.
+ *
+ * @param options - Current server and storage mode.
+ * @returns Browser-safe upload availability state.
+ */
+export function resolveFileUploadAvailability(
+    options: ResolveFileUploadAvailabilityOptions,
+): FileUploadAvailability {
+    if (!options.isSelfContainedS3StorageSelected) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    if (options.serverId !== null) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    if (isLocalDevelopmentUrl(options.serverPublicUrl)) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    return {
+        isUploadAvailable: false,
+        message: FILE_UPLOAD_REQUIRES_SERVER_DOMAIN_MESSAGE,
+    };
+}
+
+/**
+ * Checks whether a server URL points to local development.
+ *
+ * @param serverPublicUrl - Public URL resolved for the current request.
+ * @returns `true` for localhost and loopback hosts.
+ */
+function isLocalDevelopmentUrl(serverPublicUrl: URL): boolean {
+    const hostname = serverPublicUrl.hostname.toLowerCase();
+
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}

package/apps/agents-server/src/utils/upload/uploadFileToServer.ts

@@ -41,6 +41,16 @@ export type ServerFileUploadResult = {
     size: number;
 };
 
+/**
+ * Error response shape accepted from the upload endpoint.
+ *
+ * @private used by `uploadFileToServer`
+ */
+type ServerFileUploadErrorResponse = {
+    error?: string | { message?: string };
+    message?: string;
+};
+
 /**
  * Builds the default CDN key used for user-uploaded files.
  *
@@ -50,6 +60,38 @@ export function buildDefaultUserFileUploadPath(normalizedFilename: string): stri
     return `user/files/${normalizedFilename}`;
 }
 
+/**
+ * Resolves the most useful error message from an upload response body.
+ *
+ * @param responseBody - Parsed JSON response body.
+ * @param status - HTTP status code.
+ * @returns Error message for the rejected upload promise.
+ * @private helper of `uploadFileToServer`
+ */
+function resolveUploadErrorMessage(
+    responseBody: (Partial<ServerFileUploadResult> & ServerFileUploadErrorResponse) | null,
+    status: number,
+): string {
+    if (typeof responseBody?.error === 'string' && responseBody.error) {
+        return responseBody.error;
+    }
+
+    if (
+        typeof responseBody?.error === 'object' &&
+        responseBody.error !== null &&
+        typeof responseBody.error.message === 'string' &&
+        responseBody.error.message
+    ) {
+        return responseBody.error.message;
+    }
+
+    if (typeof responseBody?.message === 'string' && responseBody.message) {
+        return responseBody.message;
+    }
+
+    return `File upload failed with HTTP ${status}.`;
+}
+
 /**
  * Uploads one browser file to `/api/upload` using normal multipart form data.
  *
@@ -82,7 +124,9 @@ export function uploadFileToServer(options: ServerFileUploadOptions): Promise<Se
         };
 
         request.onload = () => {
-            const responseBody = request.response as Partial<ServerFileUploadResult> & { error?: string } | null;
+            const responseBody = request.response as
+                | (Partial<ServerFileUploadResult> & ServerFileUploadErrorResponse)
+                | null;
 
             if (request.status >= 200 && request.status < 300 && responseBody?.url) {
                 options.onProgress?.(1 as number_percent, {
@@ -94,7 +138,7 @@ export function uploadFileToServer(options: ServerFileUploadOptions): Promise<Se
                 return;
             }
 
-            reject(new Error(responseBody?.error || `File upload failed with HTTP ${request.status}.`));
+            reject(new Error(resolveUploadErrorMessage(responseBody, request.status)));
         };
 
         request.onerror = () => reject(new Error('File upload failed.'));

package/esm/apps/agents-server/src/constants/federatedAgentImport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Metadata key storing the delay between retry attempts when importing federated agent books.
+ *
+ * @private internal Agents Server constant
+ */
+export declare const FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS_METADATA_KEY: "FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS";
+/**
+ * Total number of attempts used when loading a federated imported agent before falling back.
+ *
+ * @private internal Agents Server constant
+ */
+export declare const FEDERATED_AGENT_IMPORT_MAX_ATTEMPTS: 3;
+/**
+ * Default delay in milliseconds between federated imported-agent retry attempts.
+ *
+ * @private internal Agents Server constant
+ */
+export declare const DEFAULT_FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS = 500;
+/**
+ * Runtime configuration applied to federated imported-agent retries.
+ *
+ * @private internal Agents Server type
+ */
+export type FederatedAgentImportConfiguration = {
+    /**
+     * Total number of attempts used before returning the fallback book.
+     */
+    readonly maxAttempts: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     */
+    readonly retryDelayMs: number;
+};
+/**
+ * Default retry configuration for federated imported-agent loading.
+ *
+ * @private internal Agents Server constant
+ */
+export declare const DEFAULT_FEDERATED_AGENT_IMPORT_CONFIGURATION: Readonly<{
+    maxAttempts: 3;
+    retryDelayMs: 500;
+}>;

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

@@ -0,0 +1,207 @@
+/**
+ * Legacy metadata key storing the maximum accepted file upload size in megabytes.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const MAX_FILE_UPLOAD_SIZE_MB_METADATA_KEY: "MAX_FILE_UPLOAD_SIZE_MB";
+/**
+ * Default maximum accepted spawn depth in one tool-runtime context.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEFAULT_SPAWN_AGENT_MAX_DEPTH = 2;
+/**
+ * Default maximum number of spawned agents allowed per actor in one time window.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEFAULT_SPAWN_AGENT_RATE_LIMIT_MAX = 5;
+/**
+ * Default spawn rate-limit window size in milliseconds.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: number;
+/**
+ * Default maximum number of failed local runner attempts before a queued message is moved to `messages/failed`.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+/**
+ * Stable keys used by the dedicated server-limits table.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const SERVER_LIMIT_KEYS: {
+    readonly TIMEOUT_MAX_ACTIVE_PER_CHAT: "TIMEOUT_MAX_ACTIVE_PER_CHAT";
+    readonly TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT: "TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT";
+    readonly MAX_FILE_UPLOAD_SIZE_MB: "MAX_FILE_UPLOAD_SIZE_MB";
+    readonly FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS: "FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS";
+    readonly SPAWN_AGENT_MAX_DEPTH: "SPAWN_AGENT_MAX_DEPTH";
+    readonly SPAWN_AGENT_RATE_LIMIT_MAX: "SPAWN_AGENT_RATE_LIMIT_MAX";
+    readonly SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: "SPAWN_AGENT_RATE_LIMIT_WINDOW_MS";
+    readonly LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS: "LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS";
+};
+/**
+ * One supported dedicated server-limit key.
+ *
+ * @private shared Agents Server type
+ */
+export type ServerLimitKey = (typeof SERVER_LIMIT_KEYS)[keyof typeof SERVER_LIMIT_KEYS];
+/**
+ * Supported units rendered in the admin limits page.
+ *
+ * @private shared Agents Server type
+ */
+export type ServerLimitUnit = 'count' | 'MB' | 'ms';
+/**
+ * Shared definition describing one supported configurable limit.
+ *
+ * @private shared Agents Server type
+ */
+export type ServerLimitDefinition = {
+    readonly key: ServerLimitKey;
+    readonly category: 'Timeout tools' | 'Files' | 'Federation' | 'Agent spawning' | 'Local agent runner';
+    readonly title: string;
+    readonly description: string;
+    readonly unit: ServerLimitUnit;
+    readonly defaultValue: number;
+    readonly minimumValue: number;
+    readonly step: number;
+    readonly legacyMetadataKeys: ReadonlyArray<string>;
+};
+/**
+ * Shared metadata for all server limits exposed in the admin UI and runtime loaders.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const SERVER_LIMIT_DEFINITIONS: ({
+    key: "TIMEOUT_MAX_ACTIVE_PER_CHAT";
+    category: "Timeout tools";
+    title: string;
+    description: string;
+    unit: "count";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: string[];
+} | {
+    key: "TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT";
+    category: "Timeout tools";
+    title: string;
+    description: string;
+    unit: "count";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: string[];
+} | {
+    key: "MAX_FILE_UPLOAD_SIZE_MB";
+    category: "Files";
+    title: string;
+    description: string;
+    unit: "MB";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: "MAX_FILE_UPLOAD_SIZE_MB"[];
+} | {
+    key: "FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS";
+    category: "Federation";
+    title: string;
+    description: string;
+    unit: "ms";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: "FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS"[];
+} | {
+    key: "SPAWN_AGENT_MAX_DEPTH";
+    category: "Agent spawning";
+    title: string;
+    description: string;
+    unit: "count";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: never[];
+} | {
+    key: "SPAWN_AGENT_RATE_LIMIT_MAX";
+    category: "Agent spawning";
+    title: string;
+    description: string;
+    unit: "count";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: never[];
+} | {
+    key: "SPAWN_AGENT_RATE_LIMIT_WINDOW_MS";
+    category: "Agent spawning";
+    title: string;
+    description: string;
+    unit: "ms";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: never[];
+} | {
+    key: "LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS";
+    category: "Local agent runner";
+    title: string;
+    description: string;
+    unit: "count";
+    defaultValue: number;
+    minimumValue: number;
+    step: number;
+    legacyMetadataKeys: never[];
+})[];
+/**
+ * Fast lookup map used by server-limit validators and UI helpers.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const SERVER_LIMIT_DEFINITION_BY_KEY: Map<ServerLimitKey, ServerLimitDefinition>;
+/**
+ * Default values used whenever a server-limit row has not been persisted yet.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEFAULT_SERVER_LIMIT_VALUES: Readonly<Record<ServerLimitKey, number>>;
+/**
+ * Deprecated metadata keys that now mirror dedicated server-limit rows for backward compatibility.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const DEPRECATED_LIMIT_METADATA_KEYS: string[];
+/**
+ * Description of one deprecated metadata key that now points to the dedicated limits page.
+ *
+ * @private shared Agents Server type
+ */
+export type DeprecatedLimitMetadataDefinition = {
+    readonly key: string;
+    readonly href: '/admin/limits';
+    readonly limitKeys: ReadonlyArray<ServerLimitKey>;
+    readonly limitTitles: ReadonlyArray<string>;
+    readonly message: string;
+};
+/**
+ * Returns the deprecated-metadata descriptor when one metadata key now belongs to the limits page.
+ *
+ * @param metadataKey - Metadata key being rendered in the admin metadata UI.
+ * @returns Deprecated metadata descriptor or `null`.
+ *
+ * @private shared Agents Server helper
+ */
+export declare function getDeprecatedLimitMetadataDefinition(metadataKey: string): DeprecatedLimitMetadataDefinition | null;
+/**
+ * Resolves one shared server-limit definition by key.
+ *
+ * @param key - Dedicated server-limit key.
+ * @returns Matching definition or `null`.
+ *
+ * @private shared Agents Server helper
+ */
+export declare function getServerLimitDefinition(key: string): ServerLimitDefinition | null;

package/esm/apps/agents-server/src/constants/toolUsageLimits.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Metadata key used to persist tool-usage limits.
+ *
+ * @private shared constant for Agents Server
+ */
+export declare const TOOL_USAGE_LIMITS_METADATA_KEY = "TOOL_USAGE_LIMITS";
+/**
+ * Timeout-specific limits supported by the current admin UI.
+ *
+ * @private shared type for Agents Server
+ */
+export type TimeoutToolUsageLimits = {
+    maxActivePerChat: number;
+    maxFiredPerDayPerChat: number;
+};
+/**
+ * Full tool-limits payload stored in metadata.
+ *
+ * The shape is intentionally extensible so other tools can be added later.
+ *
+ * @private shared type for Agents Server
+ */
+export type ToolUsageLimits = Record<string, unknown> & {
+    timeout: TimeoutToolUsageLimits;
+};
+/**
+ * Default timeout limits applied when administrators do not override them.
+ *
+ * @private shared constant for Agents Server
+ */
+export declare const DEFAULT_TIMEOUT_TOOL_USAGE_LIMITS: TimeoutToolUsageLimits;
+/**
+ * Default tool-limits payload used across metadata, admin UI, and runtime enforcement.
+ *
+ * @private shared constant for Agents Server
+ */
+export declare const DEFAULT_TOOL_USAGE_LIMITS: ToolUsageLimits;
+/**
+ * Normalizes the complete tool-limits payload while preserving unknown future keys.
+ *
+ * @param rawValue - Unknown persisted payload.
+ * @returns Normalized tool-usage limits.
+ *
+ * @private shared Agents Server helper
+ */
+export declare function normalizeToolUsageLimits(rawValue: unknown): ToolUsageLimits;
+/**
+ * Normalizes timeout-specific limits with defaults and integer guards.
+ *
+ * @param rawValue - Unknown timeout payload.
+ * @returns Normalized timeout tool limits.
+ *
+ * @private shared Agents Server helper
+ */
+export declare function normalizeTimeoutToolUsageLimits(rawValue: unknown): TimeoutToolUsageLimits;