@promptbook/cli 0.112.0-103 → 0.112.0-105

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;