@promptbook/cli 0.112.0-99 → 0.112.0

package/apps/agents-server/src/constants/newAgentWizard.ts

@@ -1,22 +1,27 @@
 /**
  * Metadata key that controls which "new agent" creation experience is shown.
  */
-export const NEW_AGENT_WIZZARD_METADATA_KEY = 'NEW_AGENT_WIZZARD' as const;
+export const NEW_AGENT_WIZARD_METADATA_KEY = 'NEW_AGENT_WIZARD' as const;
+
+/**
+ * Previous metadata key retained only for reading already persisted settings.
+ */
+export const LEGACY_NEW_AGENT_WIZARD_METADATA_KEY = ['NEW_AGENT_', 'WIZ', 'ZARD'].join('');
 
 /**
  * Supported new-agent creation experiences.
  */
-export const NEW_AGENT_WIZZARD_VALUES = ['BOILERPLATE', 'WIZARD'] as const;
+export const NEW_AGENT_WIZARD_VALUES = ['BOILERPLATE', 'WIZARD', 'MANGO_WIZARD'] as const;
 
 /**
  * Canonical union of supported new-agent creation experiences.
  */
-export type NewAgentWizardMode = (typeof NEW_AGENT_WIZZARD_VALUES)[number];
+export type NewAgentWizardMode = (typeof NEW_AGENT_WIZARD_VALUES)[number];
 
 /**
  * Shared select options for the new-agent experience metadata.
  */
-export const NEW_AGENT_WIZZARD_OPTIONS: ReadonlyArray<{
+export const NEW_AGENT_WIZARD_OPTIONS: ReadonlyArray<{
     readonly value: NewAgentWizardMode;
     readonly label: string;
 }> = [
@@ -28,12 +33,16 @@ export const NEW_AGENT_WIZZARD_OPTIONS: ReadonlyArray<{
         value: 'WIZARD',
         label: 'Wizard',
     },
+    {
+        value: 'MANGO_WIZARD',
+        label: 'manGo wizard',
+    },
 ] as const;
 
 /**
  * Default creation experience used when metadata is missing or invalid.
  */
-export const DEFAULT_NEW_AGENT_WIZZARD_MODE: NewAgentWizardMode = 'BOILERPLATE';
+export const DEFAULT_NEW_AGENT_WIZARD_MODE: NewAgentWizardMode = 'MANGO_WIZARD';
 
 /**
  * Returns whether the provided value is a supported new-agent creation experience.
@@ -42,7 +51,7 @@ export const DEFAULT_NEW_AGENT_WIZZARD_MODE: NewAgentWizardMode = 'BOILERPLATE';
  * @returns `true` when the value matches a supported mode.
  */
 export function isNewAgentWizardMode(value: unknown): value is NewAgentWizardMode {
-    return typeof value === 'string' && NEW_AGENT_WIZZARD_VALUES.includes(value as NewAgentWizardMode);
+    return typeof value === 'string' && NEW_AGENT_WIZARD_VALUES.includes(value as NewAgentWizardMode);
 }
 
 /**
@@ -54,12 +63,12 @@ export function isNewAgentWizardMode(value: unknown): value is NewAgentWizardMod
  */
 export function parseNewAgentWizardMode(
     value: unknown,
-    fallback: NewAgentWizardMode = DEFAULT_NEW_AGENT_WIZZARD_MODE,
+    fallback: NewAgentWizardMode = DEFAULT_NEW_AGENT_WIZARD_MODE,
 ): NewAgentWizardMode {
     if (typeof value !== 'string') {
         return fallback;
     }
 
-    const normalized = value.trim().toUpperCase();
+    const normalized = value.trim().toUpperCase().replace(/[\s-]+/g, '_');
     return isNewAgentWizardMode(normalized) ? normalized : fallback;
 }

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

@@ -32,6 +32,13 @@ export const DEFAULT_SPAWN_AGENT_RATE_LIMIT_MAX = 5;
  */
 export const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
 
+/**
+ * Default maximum number of failed local runner attempts before a queued message is moved to `messages/failed`.
+ *
+ * @private shared Agents Server constant
+ */
+export const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+
 /**
  * Stable keys used by the dedicated server-limits table.
  *
@@ -45,6 +52,7 @@ export const SERVER_LIMIT_KEYS = {
     SPAWN_AGENT_MAX_DEPTH: 'SPAWN_AGENT_MAX_DEPTH',
     SPAWN_AGENT_RATE_LIMIT_MAX: 'SPAWN_AGENT_RATE_LIMIT_MAX',
     SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: 'SPAWN_AGENT_RATE_LIMIT_WINDOW_MS',
+    LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS: 'LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS',
 } as const;
 
 /**
@@ -68,7 +76,7 @@ export type ServerLimitUnit = 'count' | 'MB' | 'ms';
  */
 export type ServerLimitDefinition = {
     readonly key: ServerLimitKey;
-    readonly category: 'Timeout tools' | 'Files' | 'Federation' | 'Agent spawning';
+    readonly category: 'Timeout tools' | 'Files' | 'Federation' | 'Agent spawning' | 'Local agent runner';
     readonly title: string;
     readonly description: string;
     readonly unit: ServerLimitUnit;
@@ -143,7 +151,8 @@ export const SERVER_LIMIT_DEFINITIONS = [
         key: SERVER_LIMIT_KEYS.SPAWN_AGENT_RATE_LIMIT_MAX,
         category: 'Agent spawning',
         title: 'Max spawned agents per window',
-        description: 'Limits how many persistent agents one actor can create through `spawn_agent` inside one rate-limit window.',
+        description:
+            'Limits how many persistent agents one actor can create through `spawn_agent` inside one rate-limit window.',
         unit: 'count',
         defaultValue: DEFAULT_SPAWN_AGENT_RATE_LIMIT_MAX,
         minimumValue: 1,
@@ -161,6 +170,17 @@ export const SERVER_LIMIT_DEFINITIONS = [
         step: 1_000,
         legacyMetadataKeys: [],
     },
+    {
+        key: SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+        category: 'Local agent runner',
+        title: 'Max failed message attempts',
+        description: 'Stops the local coding-agent watcher from retrying the same queued chat message forever.',
+        unit: 'count',
+        defaultValue: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+        minimumValue: 1,
+        step: 1,
+        legacyMetadataKeys: [],
+    },
 ] satisfies ReadonlyArray<ServerLimitDefinition>;
 
 /**

package/apps/agents-server/src/constants/shibbolethAuth.ts

@@ -0,0 +1,139 @@
+/**
+ * Metadata key that enables Shibboleth authentication in Agents Server.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY = 'IS_SHIBBOLETH_AUTH_ACTIVE' as const;
+
+/**
+ * Metadata key containing a URL with the Identity Provider SAML metadata XML.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY = 'SHIBBOLETH_IDP_METADATA_URL' as const;
+
+/**
+ * Metadata key containing pasted Identity Provider SAML metadata XML.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY = 'SHIBBOLETH_IDP_METADATA_XML' as const;
+
+/**
+ * Metadata key overriding the Service Provider entity ID sent to the Shibboleth Identity Provider.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY = 'SHIBBOLETH_SP_ENTITY_ID' as const;
+
+/**
+ * Metadata key defining accepted email attribute names.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY = 'SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES' as const;
+
+/**
+ * Metadata key defining accepted display-name attribute names.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY = 'SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES' as const;
+
+/**
+ * Metadata key defining accepted institutional identifier attribute names.
+ *
+ * @private internal Shibboleth authentication metadata key
+ */
+export const SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY =
+    'SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES' as const;
+
+/**
+ * Default Shibboleth email attribute names accepted from SAML assertions.
+ *
+ * @private internal Shibboleth authentication metadata default
+ */
+export const DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES = 'mail email urn:oid:0.9.2342.19200300.100.1.3' as const;
+
+/**
+ * Default Shibboleth display-name attribute names accepted from SAML assertions.
+ *
+ * @private internal Shibboleth authentication metadata default
+ */
+export const DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES = 'displayName urn:oid:2.16.840.1.113730.3.1.241' as const;
+
+/**
+ * Default Shibboleth institutional identifier attribute names accepted from SAML assertions.
+ *
+ * @private internal Shibboleth authentication metadata default
+ */
+export const DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES =
+    'unstructuredName eduPersonPrincipalName urn:oid:1.3.6.1.4.1.5923.1.1.1.6 uid' as const;
+
+/**
+ * Metadata keys required by the Shibboleth authentication integration.
+ *
+ * @private internal Shibboleth authentication metadata key list
+ */
+export const SHIBBOLETH_AUTHENTICATION_METADATA_KEYS = [
+    IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY,
+    SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY,
+    SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+] as const;
+
+/**
+ * Shape used by the header/menu layer to decide whether the Shibboleth menu item should appear.
+ *
+ * @private internal Shibboleth menu state
+ */
+export type ShibbolethAuthenticationMenuStatus = {
+    /**
+     * True when Shibboleth login is enabled by metadata.
+     */
+    readonly isActive: boolean;
+    /**
+     * True when the minimum metadata required to contact the Identity Provider is present.
+     */
+    readonly isConfigured: boolean;
+};
+
+/**
+ * Parses a metadata boolean value.
+ *
+ * @param value - Raw metadata value.
+ * @returns Boolean interpretation of the metadata value.
+ *
+ * @private internal Shibboleth metadata parser
+ */
+export function parseShibbolethBooleanMetadata(value: string | null | undefined): boolean {
+    return (value || '').trim().toLowerCase() === 'true';
+}
+
+/**
+ * Resolves the Shibboleth menu status from a metadata map.
+ *
+ * @param metadata - Metadata values keyed by metadata name.
+ * @returns Shibboleth activation/configuration status.
+ *
+ * @private internal Shibboleth menu helper
+ */
+export function resolveShibbolethAuthenticationMenuStatus(
+    metadata: Readonly<Record<string, string | null | undefined>>,
+): ShibbolethAuthenticationMenuStatus {
+    const isActive = parseShibbolethBooleanMetadata(metadata[IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY]);
+    const isIdentityProviderMetadataUrlConfigured = Boolean(
+        (metadata[SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY] || '').trim(),
+    );
+    const isIdentityProviderMetadataXmlConfigured = Boolean(
+        (metadata[SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY] || '').trim(),
+    );
+
+    return {
+        isActive,
+        isConfigured: isActive && (isIdentityProviderMetadataUrlConfigured || isIdentityProviderMetadataXmlConfigured),
+    };
+}

package/apps/agents-server/src/database/$provideClientSql.ts

@@ -31,6 +31,33 @@ export type ClientSqlExecutor = ClientSql & {
     readonly raw: ClientSqlRaw;
 };
 
+/**
+ * Maximum number of PostgreSQL connections in the shared pool.
+ *
+ * Configurable via `DATABASE_POOL_MAX` environment variable.
+ * Defaults to 20 which comfortably handles concurrent chat-stream polling loads.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const DATABASE_POOL_MAX = Math.max(1, parseInt(process.env.DATABASE_POOL_MAX || '20', 10));
+
+/**
+ * Milliseconds to wait for a free pool connection before failing.
+ *
+ * Without a timeout the default `pg` behaviour is to queue requests indefinitely,
+ * which causes the server to become unresponsive under pool exhaustion.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_CONNECTION_TIMEOUT_MS = 15_000;
+
+/**
+ * Milliseconds an idle client stays in the pool before being closed.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_IDLE_TIMEOUT_MS = 30_000;
+
 /**
  * Shared PostgreSQL pool reused across all requests in the server process.
  *
@@ -52,6 +79,16 @@ export async function $provideClientSql(): Promise<ClientSqlExecutor> {
         clientPool = new Pool({
             connectionString: resolvePostgresConnectionString(),
             ssl: { rejectUnauthorized: false },
+            max: DATABASE_POOL_MAX,
+            idleTimeoutMillis: POOL_IDLE_TIMEOUT_MS,
+            connectionTimeoutMillis: POOL_CONNECTION_TIMEOUT_MS,
+            allowExitOnIdle: true,
+        });
+
+        // Prevent unhandled errors from crashing the pool or the process.
+        // Individual query errors are still thrown at the call site.
+        clientPool.on('error', (error) => {
+            console.error('[database] Unexpected error on idle PostgreSQL client:', error);
         });
     }
 

package/apps/agents-server/src/database/$provideSupabaseForServer.ts

@@ -4,6 +4,44 @@ import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
 import { $provideLocalSqliteSupabase } from './sqlite/$provideLocalSqliteSupabase';
 import { AgentsServerDatabase } from './schema';
 
+/**
+ * Hard timeout for every Supabase HTTP request.
+ *
+ * Without this, a slow or unreachable PostgREST endpoint causes requests to
+ * hang indefinitely, eventually making the server appear unresponsive.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const SUPABASE_REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * Wraps the native `fetch` with a per-request timeout so Supabase queries
+ * always resolve (with an error) within `SUPABASE_REQUEST_TIMEOUT_MS`.
+ *
+ * When the caller already passes an AbortSignal the request is aborted when
+ * either that signal fires or the timeout fires — whichever comes first.
+ *
+ * Uses manual composition instead of `AbortSignal.any` for Node.js 18 compatibility
+ * (`AbortSignal.any` is only available in Node.js 20.3+).
+ *
+ * @private internal helper of Agents Server database layer
+ */
+function fetchWithSupabaseTimeout(url: RequestInfo | URL, options?: RequestInit): Promise<Response> {
+    const existingSignal = options?.signal instanceof AbortSignal ? options.signal : null;
+
+    if (!existingSignal) {
+        return fetch(url, { ...options, signal: AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS) });
+    }
+
+    // Compose the caller signal with the timeout: abort when either fires.
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    existingSignal.addEventListener('abort', abort, { once: true });
+    AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS).addEventListener('abort', abort, { once: true });
+
+    return fetch(url, { ...options, signal: controller.signal });
+}
+
 /**
  * Internal cache for `$provideSupabaseForServer`
  *
@@ -42,6 +80,9 @@ export function $provideSupabaseForServer(): SupabaseClient<AgentsServerDatabase
                     autoRefreshToken: false,
                     persistSession: false,
                 },
+                global: {
+                    fetch: fetchWithSupabaseTimeout,
+                },
             },
         );
     }

package/apps/agents-server/src/database/customJavascript.ts

@@ -14,6 +14,13 @@ export const MAX_CUSTOM_JAVASCRIPT_LENGTH = 100_000;
  */
 const CUSTOM_JAVASCRIPT_TABLE_BASENAME = 'CustomJavascript';
 
+/**
+ * Process-level cache lifetime for custom JavaScript rows.
+ *
+ * @private
+ */
+const CUSTOM_JAVASCRIPT_CACHE_TTL_MS = 30_000;
+
 /**
  * Stored `CustomJavascript` row shape.
  *
@@ -90,6 +97,28 @@ type DynamicSupabaseClient = {
     from: (tableName: string) => DynamicCustomJavascriptTableQuery;
 };
 
+/**
+ * Cached custom JavaScript rows keyed by the resolved table name.
+ *
+ * @private
+ */
+const cachedCustomJavascriptByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly rowsPromise: Promise<CustomJavascriptRow[]>;
+    }
+>();
+
+/**
+ * Clears process-level custom JavaScript cache after admin writes.
+ *
+ * @private
+ */
+export function invalidateCustomJavascriptCache(): void {
+    cachedCustomJavascriptByTableName.clear();
+}
+
 /**
  * Resolves the prefixed table name for `CustomJavascript`.
  *
@@ -137,8 +166,37 @@ function getCustomJavascriptClient() {
  */
 export async function getCustomJavascriptFiles(): Promise<CustomJavascriptRow[]> {
     const table = await getCustomJavascriptTableName();
-    const supabase = getCustomJavascriptClient();
+    const cachedJavascript = cachedCustomJavascriptByTableName.get(table);
+    if (cachedJavascript && Date.now() - cachedJavascript.loadedAt < CUSTOM_JAVASCRIPT_CACHE_TTL_MS) {
+        return cachedJavascript.rowsPromise;
+    }
+
+    const rowsPromise = loadCustomJavascriptFilesFromDatabase(table);
+    cachedCustomJavascriptByTableName.set(table, {
+        loadedAt: Date.now(),
+        rowsPromise,
+    });
+
+    try {
+        return await rowsPromise;
+    } catch (error) {
+        if (cachedCustomJavascriptByTableName.get(table)?.rowsPromise === rowsPromise) {
+            cachedCustomJavascriptByTableName.delete(table);
+        }
+        throw error;
+    }
+}
 
+/**
+ * Reads custom JavaScript rows from the database.
+ *
+ * @param table - Resolved CustomJavascript table name.
+ * @returns Stored JavaScript rows.
+ *
+ * @private
+ */
+async function loadCustomJavascriptFilesFromDatabase(table: string): Promise<CustomJavascriptRow[]> {
+    const supabase = getCustomJavascriptClient();
     const { data, error } = await supabase.from(table).select('*').order('scope', { ascending: true });
 
     if (error) {
@@ -234,6 +292,7 @@ export async function saveCustomJavascriptFile({
         throw new Error(`Failed to save custom JavaScript: ${error.message || String(error)}`);
     }
 
+    invalidateCustomJavascriptCache();
     return data as CustomJavascriptRow;
 }
 
@@ -255,4 +314,6 @@ export async function deleteCustomJavascriptFile(id: number): Promise<void> {
 
         throw new Error(`Failed to delete custom JavaScript: ${error.message || String(error)}`);
     }
+
+    invalidateCustomJavascriptCache();
 }

package/apps/agents-server/src/database/customStylesheet.ts

@@ -7,6 +7,11 @@ import { $provideSupabase } from './$provideSupabase';
  */
 const CUSTOM_STYLESHEET_TABLE_BASENAME = 'CustomStylesheet';
 
+/**
+ * Process-level cache lifetime for custom stylesheet rows.
+ */
+const CUSTOM_STYLESHEET_CACHE_TTL_MS = 30_000;
+
 /**
  * Stored CustomStylesheet row shape.
  *
@@ -82,6 +87,28 @@ type DynamicSupabaseClient = {
     from: (tableName: string) => DynamicCustomStylesheetTableQuery;
 };
 
+/**
+ * Cached custom stylesheet rows keyed by the resolved table name.
+ *
+ * @private
+ */
+const cachedCustomStylesheetsByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly rowsPromise: Promise<CustomStylesheetRow[]>;
+    }
+>();
+
+/**
+ * Clears process-level stylesheet cache after admin writes.
+ *
+ * @public
+ */
+export function invalidateCustomStylesheetCache(): void {
+    cachedCustomStylesheetsByTableName.clear();
+}
+
 /**
  * Resolves the prefixed table name for CustomStylesheet.
  *
@@ -127,8 +154,37 @@ function getCustomStylesheetClient(): DynamicSupabaseClient {
  */
 export async function listCustomStylesheets(): Promise<CustomStylesheetRow[]> {
     const table = await getCustomStylesheetTableName();
-    const supabase = getCustomStylesheetClient();
+    const cachedStylesheets = cachedCustomStylesheetsByTableName.get(table);
+    if (cachedStylesheets && Date.now() - cachedStylesheets.loadedAt < CUSTOM_STYLESHEET_CACHE_TTL_MS) {
+        return cachedStylesheets.rowsPromise;
+    }
+
+    const rowsPromise = loadCustomStylesheetsFromDatabase(table);
+    cachedCustomStylesheetsByTableName.set(table, {
+        loadedAt: Date.now(),
+        rowsPromise,
+    });
+
+    try {
+        return await rowsPromise;
+    } catch (error) {
+        if (cachedCustomStylesheetsByTableName.get(table)?.rowsPromise === rowsPromise) {
+            cachedCustomStylesheetsByTableName.delete(table);
+        }
+        throw error;
+    }
+}
 
+/**
+ * Reads custom stylesheet rows from the database.
+ *
+ * @param table - Resolved CustomStylesheet table name.
+ * @returns Stored stylesheet rows.
+ *
+ * @private
+ */
+async function loadCustomStylesheetsFromDatabase(table: string): Promise<CustomStylesheetRow[]> {
+    const supabase = getCustomStylesheetClient();
     const { data, error } = await supabase.from(table).select('*').order('createdAt', { ascending: true });
 
     if (error) {
@@ -206,6 +262,7 @@ export async function saveCustomStylesheetFile({
         throw new Error(`Failed to save custom stylesheet: ${error.message || String(error)}`);
     }
 
+    invalidateCustomStylesheetCache();
     return data as CustomStylesheetRow;
 }
 
@@ -229,4 +286,6 @@ export async function deleteCustomStylesheetFile(id: number): Promise<void> {
 
         throw new Error(`Failed to delete custom stylesheet: ${error.message || String(error)}`);
     }
+
+    invalidateCustomStylesheetCache();
 }