@promptbook/cli 0.112.0-99 → 0.112.0

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

@@ -10,6 +10,56 @@ import { cache } from 'react';
  */
 const metadataDefaultsMap = new Map<string, string>(metadataDefaults.map((metadata) => [metadata.key, metadata.value]));
 
+/**
+ * Precomputed map of legacy metadata keys keyed by canonical metadata key.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+const metadataLegacyKeysMap = new Map<string, ReadonlyArray<string>>(
+    metadataDefaults
+        .filter((metadata) => metadata.legacyKeys && metadata.legacyKeys.length > 0)
+        .map((metadata): [string, ReadonlyArray<string>] => [metadata.key, metadata.legacyKeys ?? []]),
+);
+
+/**
+ * Process-level cache lifetime for metadata reads.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+const METADATA_CACHE_TTL_MS = 30_000;
+
+/**
+ * Cached metadata table payload keyed by the resolved table name.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+const cachedMetadataValuesByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly valuesPromise: Promise<Map<string, string | null>>;
+    }
+>();
+
+/**
+ * Metadata row shape loaded by the lightweight metadata select.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+type MetadataValueRow = {
+    readonly key: string;
+    readonly value: string | null;
+};
+
+/**
+ * Clears process-level metadata cache after admin metadata writes.
+ *
+ * @public exported from `apps/agents-server`
+ */
+export function invalidateMetadataCache(): void {
+    cachedMetadataValuesByTableName.clear();
+}
+
 /**
  * Loads the full metadata table once per request so callers can cheaply project subsets.
  *
@@ -18,17 +68,59 @@ const metadataDefaultsMap = new Map<string, string>(metadataDefaults.map((metada
  * @private Internal helper for batched metadata lookups in `apps/agents-server`.
  */
 const loadAllMetadataValues = cache(async (): Promise<Map<string, string | null>> => {
-    const supabase = $provideSupabase();
     const table = await $getTableName('Metadata');
+    return loadCachedMetadataValues(table);
+});
+
+/**
+ * Loads metadata values using a short process-level cache shared by consecutive requests.
+ *
+ * @param table - Resolved metadata table name.
+ * @returns Metadata values keyed by metadata key.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+async function loadCachedMetadataValues(table: string): Promise<Map<string, string | null>> {
+    const cachedMetadataValues = cachedMetadataValuesByTableName.get(table);
+    if (cachedMetadataValues && Date.now() - cachedMetadataValues.loadedAt < METADATA_CACHE_TTL_MS) {
+        return cachedMetadataValues.valuesPromise;
+    }
+
+    const valuesPromise = loadMetadataValuesFromDatabase(table);
+    cachedMetadataValuesByTableName.set(table, {
+        loadedAt: Date.now(),
+        valuesPromise,
+    });
+
+    try {
+        return await valuesPromise;
+    } catch (error) {
+        if (cachedMetadataValuesByTableName.get(table)?.valuesPromise === valuesPromise) {
+            cachedMetadataValuesByTableName.delete(table);
+        }
+        throw error;
+    }
+}
+
+/**
+ * Reads all persisted metadata values from the database.
+ *
+ * @param table - Resolved metadata table name.
+ * @returns Metadata values keyed by metadata key.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+async function loadMetadataValuesFromDatabase(table: string): Promise<Map<string, string | null>> {
+    const supabase = $provideSupabase();
     const { data } = await supabase.from(table).select('key, value');
 
     const loadedMap = new Map<string, string | null>();
-    for (const row of data ?? []) {
+    for (const row of (data ?? []) as Array<MetadataValueRow>) {
         loadedMap.set(row.key, row.value);
     }
 
     return loadedMap;
-});
+}
 
 /**
  * Get metadata value by key
@@ -65,8 +157,33 @@ export async function getMetadataMap(keys: readonly string[]): Promise<Record<st
 
     const metadataRecord: Record<string, string | null> = {};
     for (const key of uniqueKeys) {
-        metadataRecord[key] = loadedMap.get(key) ?? metadataDefaultsMap.get(key) ?? null;
+        metadataRecord[key] = resolveMetadataValue(key, loadedMap);
     }
 
     return metadataRecord;
 }
+
+/**
+ * Resolves one metadata value from canonical rows, legacy rows, or default definitions.
+ *
+ * @param key - Canonical metadata key requested by the caller.
+ * @param loadedMap - Persisted metadata values keyed by database row key.
+ * @returns Stored, legacy, default, or `null` metadata value.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+function resolveMetadataValue(key: string, loadedMap: ReadonlyMap<string, string | null>): string | null {
+    const storedValue = loadedMap.get(key);
+    if (storedValue !== undefined && storedValue !== null) {
+        return storedValue;
+    }
+
+    for (const legacyKey of metadataLegacyKeysMap.get(key) ?? []) {
+        const legacyValue = loadedMap.get(legacyKey);
+        if (legacyValue !== undefined && legacyValue !== null) {
+            return legacyValue;
+        }
+    }
+
+    return metadataDefaultsMap.get(key) ?? null;
+}

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

@@ -0,0 +1,29 @@
+import * as dotenv from 'dotenv';
+
+/**
+ * Environment variable pointing to the installed Agents Server `.env` file.
+ *
+ * @private utility of standalone database scripts
+ */
+export const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
+
+/**
+ * Loads Agents Server environment variables for standalone database scripts.
+ *
+ * The installer passes an explicit `.env` file from the installation directory. That file must override ambient
+ * `PTBK_*` values because these scripts often run from the repository checkout while the server runs from the
+ * installation directory, so a stale relative SQLite path would point at a different database.
+ *
+ * @private utility of standalone database scripts
+ */
+export function loadAgentsServerEnvFile(): void {
+    const explicitEnvFilePath = process.env[AGENTS_SERVER_ENV_FILE_ENV_NAME]?.trim();
+    if (explicitEnvFilePath) {
+        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath, override: true });
+        if (!explicitLoadResult.error) {
+            return;
+        }
+    }
+
+    dotenv.config();
+}

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

@@ -1,5 +1,3 @@
-import { spaceTrim } from 'spacetrim';
-import { CORE_AGENTS_SERVER } from '../../../../servers';
 import { DEFAULT_THINKING_MESSAGES } from '../../../../src/utils/DEFAULT_THINKING_MESSAGES';
 import { ANALYTICS_METADATA_KEYS, getAnalyticsMetadataDefinition } from '../constants/analyticsMetadata';
 import {
@@ -7,7 +5,11 @@ import {
     FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS_METADATA_KEY,
 } from '../constants/federatedAgentImport';
 import { MetadataType } from '../constants/metadataTypes';
-import { CHAT_VISUAL_MODE_OPTIONS, CHAT_VISUAL_MODE_METADATA_KEY, DEFAULT_CHAT_VISUAL_MODE } from '../constants/chatVisualMode';
+import {
+    CHAT_VISUAL_MODE_OPTIONS,
+    CHAT_VISUAL_MODE_METADATA_KEY,
+    DEFAULT_CHAT_VISUAL_MODE,
+} from '../constants/chatVisualMode';
 import {
     DEFAULT_AGENT_AVATAR_VISUAL_METADATA_KEY,
     DEFAULT_AGENT_AVATAR_VISUAL_METADATA_OPTIONS,
@@ -15,7 +17,24 @@ import {
 } from '../constants/defaultAgentAvatarVisual';
 import { DEFAULT_THEME_METADATA_KEY, DEFAULT_THEME_MODE, THEME_MODE_OPTIONS } from '../constants/themeMode';
 import { DEFAULT_NAME_POOL, NAME_POOL_METADATA_KEY, NAME_POOL_OPTIONS } from '../constants/namePool';
-import { NEW_AGENT_WIZZARD_METADATA_KEY, NEW_AGENT_WIZZARD_OPTIONS } from '../constants/newAgentWizard';
+import {
+    DEFAULT_NEW_AGENT_WIZARD_MODE,
+    LEGACY_NEW_AGENT_WIZARD_METADATA_KEY,
+    NEW_AGENT_WIZARD_METADATA_KEY,
+    NEW_AGENT_WIZARD_OPTIONS,
+} from '../constants/newAgentWizard';
+import {
+    DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES,
+    IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY,
+    SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY,
+    SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY,
+    SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+} from '../constants/shibbolethAuth';
 import {
     DEFAULT_SERVER_LIMIT_VALUES,
     MAX_FILE_UPLOAD_SIZE_MB_METADATA_KEY,
@@ -74,6 +93,11 @@ export type MetadataDefinition = {
      * Optional predefined values rendered as a select instead of a free-form input.
      */
     readonly options?: ReadonlyArray<MetadataDefinitionOption>;
+
+    /**
+     * Optional previous keys that should be read when the canonical key is absent.
+     */
+    readonly legacyKeys?: ReadonlyArray<string>;
 };
 
 /**
@@ -104,7 +128,7 @@ const analyticsMetadataDefaults = ANALYTICS_METADATA_KEYS.map((key) => {
 /**
  * Constant for metadata defaults.
  */
-export const metadataDefaults = [
+export const metadataDefaults: ReadonlyArray<MetadataDefinition> = [
     {
         key: 'SERVER_NAME',
         value: 'Promptbook Agents Server',
@@ -114,7 +138,9 @@ export const metadataDefaults = [
     {
         key: SERVER_LANGUAGE_METADATA_KEY,
         value: 'en',
-        note: `Default language of the server UI. Available values: ${formatMetadataOptionValues(SERVER_LANGUAGE_OPTIONS)}.`,
+        note: `Default language of the server UI. Available values: ${formatMetadataOptionValues(
+            SERVER_LANGUAGE_OPTIONS,
+        )}.`,
         type: 'TEXT_SINGLE_LINE',
         options: SERVER_LANGUAGE_OPTIONS,
     },
@@ -139,6 +165,48 @@ export const metadataDefaults = [
         type: 'TEXT_SINGLE_LINE',
         options: SERVER_VISIBILITY_OPTIONS,
     },
+    {
+        key: IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY,
+        value: 'false',
+        note: 'Enable Shibboleth authentication alongside standard username/password login.',
+        type: 'BOOLEAN',
+    },
+    {
+        key: SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY,
+        value: '',
+        note: 'URL of the Shibboleth Identity Provider metadata XML. For Silesian University this is https://idp-cro.slu.cz/idp/shibboleth.',
+        type: 'TEXT_SINGLE_LINE',
+    },
+    {
+        key: SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY,
+        value: '',
+        note: 'Optional pasted Shibboleth Identity Provider metadata XML. Used instead of SHIBBOLETH_IDP_METADATA_URL when filled.',
+        type: 'TEXT',
+    },
+    {
+        key: SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY,
+        value: '',
+        note: 'Optional Service Provider entity ID override. When empty, Agents Server uses the generated Shibboleth metadata endpoint URL.',
+        type: 'TEXT_SINGLE_LINE',
+    },
+    {
+        key: SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY,
+        value: DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES,
+        note: 'Space-separated SAML attribute names accepted as the user email during Shibboleth login.',
+        type: 'TEXT_SINGLE_LINE',
+    },
+    {
+        key: SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+        value: DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES,
+        note: 'Space-separated SAML attribute names accepted as the user display name during Shibboleth login.',
+        type: 'TEXT_SINGLE_LINE',
+    },
+    {
+        key: SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+        value: DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES,
+        note: 'Space-separated SAML attribute names accepted as the institutional identifier during Shibboleth login.',
+        type: 'TEXT_SINGLE_LINE',
+    },
     {
         key: 'AGENT_NAMING',
         value: 'Agent / Agents',
@@ -193,25 +261,6 @@ export const metadataDefaults = [
         note: 'Comma separated list of allowed IPs or CIDR ranges. If set, only clients from these IPs are allowed to access the server.',
         type: 'IP_RANGE',
     },
-    {
-        key: 'CORE_SERVER',
-        value: CORE_AGENTS_SERVER.url,
-        note: spaceTrim(`
-                Core Promptbook server URL used for agents that are used for common tasks, these agents are called well known agents:
-
-                On the core server, the following well known agents should be hosted: 
-                - \`adam\`: The default ancestor agent for new agents
-                - \`teacher\`: Agent that knows book syntax and can help with self-learning
-            
-            `),
-        type: 'TEXT',
-    },
-    {
-        key: 'IS_CORE_SERVER_HIDDEN',
-        value: 'false',
-        note: 'Hide the core federated server from homepage, navbar, search, and footer links while keeping it available for references when true.',
-        type: 'BOOLEAN',
-    },
     // <- TODO: [🆎] Allow to set well-known agent names via Metadata
 
     {
@@ -413,11 +462,14 @@ export const metadataDefaults = [
         options: AGENT_VISIBILITY_OPTIONS,
     },
     {
-        key: NEW_AGENT_WIZZARD_METADATA_KEY,
-        value: 'BOILERPLATE',
-        note: `Controls the "new agent" flow. Allowed values: ${formatMetadataOptionValues(NEW_AGENT_WIZZARD_OPTIONS)}.`,
+        key: NEW_AGENT_WIZARD_METADATA_KEY,
+        value: DEFAULT_NEW_AGENT_WIZARD_MODE,
+        note: `Controls the "new agent" flow. Allowed values: ${formatMetadataOptionValues(
+            NEW_AGENT_WIZARD_OPTIONS,
+        )}.`,
         type: 'TEXT_SINGLE_LINE',
-        options: NEW_AGENT_WIZZARD_OPTIONS,
+        options: NEW_AGENT_WIZARD_OPTIONS,
+        legacyKeys: [LEGACY_NEW_AGENT_WIZARD_METADATA_KEY],
     },
     {
         key: 'MANAGEMENT_API_CORS_ORIGINS',
@@ -474,7 +526,7 @@ export const metadataDefaults = [
         type: 'TEXT_SINGLE_LINE',
     },
     ...analyticsMetadataDefaults,
-] as const satisfies ReadonlyArray<MetadataDefinition>;
+];
 
 /**
  * Lookup map for metadata definitions by key.
@@ -517,5 +569,7 @@ export function validateMetadataValue(key: string, value: string): string | null
         return null;
     }
 
-    return `Unsupported value for \`${key}\`. Allowed values: ${formatMetadataOptionValues(metadataDefinition.options)}.`;
+    return `Unsupported value for \`${key}\`. Allowed values: ${formatMetadataOptionValues(
+        metadataDefinition.options,
+    )}.`;
 }

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

@@ -1,12 +1,13 @@
 import colors from 'colors';
-import * as dotenv from 'dotenv';
 import {
     DATABASE_MIGRATION_APPLIED_BY,
     resolveDatabaseMigrationRuntimeConfiguration,
     runDatabaseMigrations,
 } from './runDatabaseMigrations';
+import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
+import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
 
-dotenv.config();
+loadAgentsServerEnvFile();
 
 /**
  * Runs manual migration command from CLI arguments.
@@ -14,6 +15,11 @@ dotenv.config();
 async function migrate(): Promise<void> {
     console.info(colors.bgBlue('🚀 Starting database migration'));
 
+    if (isAgentsServerSqliteMode()) {
+        console.info(colors.yellow('⏭️ Skipping PostgreSQL migrations because Agents Server uses local SQLite.'));
+        return;
+    }
+
     const runtimeConfiguration = await resolveDatabaseMigrationRuntimeConfiguration(console);
     if (!runtimeConfiguration) {
         return;

package/apps/agents-server/src/database/migrations/2026-06-0100-shibboleth-auth.sql

@@ -0,0 +1,136 @@
+ALTER TABLE "prefix_User"
+    ADD COLUMN IF NOT EXISTS "email" TEXT NULL,
+    ADD COLUMN IF NOT EXISTS "displayName" TEXT NULL,
+    ADD COLUMN IF NOT EXISTS "authenticationProvider" TEXT NOT NULL DEFAULT 'LOCAL';
+
+COMMENT ON COLUMN "prefix_User"."email" IS 'Email address used for external authentication providers such as Shibboleth.';
+COMMENT ON COLUMN "prefix_User"."displayName" IS 'Human-readable display name from external authentication providers.';
+COMMENT ON COLUMN "prefix_User"."authenticationProvider" IS 'Primary authentication provider marker. Values include LOCAL, SHIBBOLETH, and LOCAL_AND_SHIBBOLETH.';
+
+CREATE TABLE IF NOT EXISTS "prefix_ShibbolethUserIdentity" (
+    "id" BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    "userId" BIGINT NOT NULL,
+    "email" TEXT NOT NULL,
+    "displayName" TEXT NULL,
+    "nameId" TEXT NULL,
+    "nameIdFormat" TEXT NULL,
+    "unstructuredName" TEXT NULL,
+    "eduPersonPrincipalName" TEXT NULL,
+    "rawAttributes" JSONB NULL,
+    "lastLoggedInAt" TIMESTAMP WITH TIME ZONE NULL,
+    "loginCount" BIGINT NOT NULL DEFAULT 0
+);
+
+COMMENT ON TABLE "prefix_ShibbolethUserIdentity" IS 'Link between Agents Server users and Shibboleth identities.';
+COMMENT ON COLUMN "prefix_ShibbolethUserIdentity"."rawAttributes" IS 'Raw SAML assertion profile attributes received from Shibboleth.';
+
+CREATE UNIQUE INDEX IF NOT EXISTS "prefix_ShibbolethUserIdentity_userId_idx"
+    ON "prefix_ShibbolethUserIdentity" ("userId");
+CREATE UNIQUE INDEX IF NOT EXISTS "prefix_ShibbolethUserIdentity_email_idx"
+    ON "prefix_ShibbolethUserIdentity" ("email");
+CREATE UNIQUE INDEX IF NOT EXISTS "prefix_ShibbolethUserIdentity_nameId_idx"
+    ON "prefix_ShibbolethUserIdentity" ("nameId");
+CREATE INDEX IF NOT EXISTS "prefix_ShibbolethUserIdentity_lastLoggedInAt_idx"
+    ON "prefix_ShibbolethUserIdentity" ("lastLoggedInAt" DESC);
+
+ALTER TABLE "prefix_ShibbolethUserIdentity"
+    DROP CONSTRAINT IF EXISTS "prefix_ShibbolethUserIdentity_userId_fkey",
+    ADD CONSTRAINT "prefix_ShibbolethUserIdentity_userId_fkey"
+    FOREIGN KEY ("userId")
+    REFERENCES "prefix_User"("id")
+    ON DELETE CASCADE;
+
+ALTER TABLE "prefix_ShibbolethUserIdentity" ENABLE ROW LEVEL SECURITY;
+
+CREATE TABLE IF NOT EXISTS "prefix_ShibbolethAuthenticationAttempt" (
+    "id" BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    "stage" TEXT NOT NULL,
+    "status" TEXT NOT NULL,
+    "userId" BIGINT NULL,
+    "email" TEXT NULL,
+    "displayName" TEXT NULL,
+    "nameId" TEXT NULL,
+    "relayState" TEXT NULL,
+    "ip" TEXT NULL,
+    "userAgent" TEXT NULL,
+    "errorMessage" TEXT NULL,
+    "rawAttributes" JSONB NULL
+);
+
+COMMENT ON TABLE "prefix_ShibbolethAuthenticationAttempt" IS 'Audit log of Shibboleth authentication attempts.';
+COMMENT ON COLUMN "prefix_ShibbolethAuthenticationAttempt"."stage" IS 'Authentication process stage such as LOGIN_REQUEST or ASSERTION_CONSUMER_SERVICE.';
+COMMENT ON COLUMN "prefix_ShibbolethAuthenticationAttempt"."status" IS 'Attempt result such as STARTED, REDIRECTED, SUCCESS, FAILED, or REJECTED.';
+COMMENT ON COLUMN "prefix_ShibbolethAuthenticationAttempt"."rawAttributes" IS 'Raw SAML assertion profile attributes when available.';
+
+CREATE INDEX IF NOT EXISTS "prefix_ShibbolethAuthenticationAttempt_createdAt_idx"
+    ON "prefix_ShibbolethAuthenticationAttempt" ("createdAt" DESC);
+CREATE INDEX IF NOT EXISTS "prefix_ShibbolethAuthenticationAttempt_email_idx"
+    ON "prefix_ShibbolethAuthenticationAttempt" ("email");
+
+ALTER TABLE "prefix_ShibbolethAuthenticationAttempt"
+    DROP CONSTRAINT IF EXISTS "prefix_ShibbolethAuthenticationAttempt_userId_fkey",
+    ADD CONSTRAINT "prefix_ShibbolethAuthenticationAttempt_userId_fkey"
+    FOREIGN KEY ("userId")
+    REFERENCES "prefix_User"("id")
+    ON DELETE SET NULL;
+
+ALTER TABLE "prefix_ShibbolethAuthenticationAttempt" ENABLE ROW LEVEL SECURITY;
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'IS_SHIBBOLETH_AUTH_ACTIVE',
+       'false',
+       'Enable Shibboleth authentication alongside standard username/password login.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'IS_SHIBBOLETH_AUTH_ACTIVE');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_IDP_METADATA_URL',
+       '',
+       'URL of the Shibboleth Identity Provider metadata XML. For Silesian University this is https://idp-cro.slu.cz/idp/shibboleth.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_IDP_METADATA_URL');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_IDP_METADATA_XML',
+       '',
+       'Optional pasted Shibboleth Identity Provider metadata XML. Used instead of SHIBBOLETH_IDP_METADATA_URL when filled.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_IDP_METADATA_XML');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_SP_ENTITY_ID',
+       '',
+       'Optional Service Provider entity ID override. When empty, Agents Server uses the generated Shibboleth metadata endpoint URL.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_SP_ENTITY_ID');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES',
+       'mail email urn:oid:0.9.2342.19200300.100.1.3',
+       'Space-separated SAML attribute names accepted as the user email during Shibboleth login.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES',
+       'displayName urn:oid:2.16.840.1.113730.3.1.241',
+       'Space-separated SAML attribute names accepted as the user display name during Shibboleth login.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES');
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES',
+       'unstructuredName eduPersonPrincipalName urn:oid:1.3.6.1.4.1.5923.1.1.1.6 uid',
+       'Space-separated SAML attribute names accepted as the institutional identifier during Shibboleth login.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES');

package/apps/agents-server/src/database/migrations/2026-06-0200-default-agent-avatar-visual-octopus3d3.sql

@@ -0,0 +1,16 @@
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'DEFAULT_AGENT_AVATAR_VISUAL',
+       'OCTOPUS3D3',
+       'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN UPPER(COALESCE("value", '')) = 'OCTOPUS3' THEN 'OCTOPUS3D3'
+                  ELSE "value"
+              END,
+    "note" = 'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+    "updatedAt" = NOW()
+WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL';

package/apps/agents-server/src/database/migrations/2026-06-1300-user-chat-active-read-indexes.sql

@@ -0,0 +1,7 @@
+CREATE INDEX IF NOT EXISTS "prefix_UserChatJob_chatId_userId_agentPermanentId_active_createdAt_idx"
+    ON "prefix_UserChatJob" ("chatId", "userId", "agentPermanentId", "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING');
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChatTimeout_chatId_userId_agentPermanentId_active_dueAt_idx"
+    ON "prefix_UserChatTimeout" ("chatId", "userId", "agentPermanentId", "dueAt" ASC, "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING') AND "pausedAt" IS NULL;

package/apps/agents-server/src/database/migrations/2026-06-2200-new-agent-wizard-metadata-key.sql

@@ -0,0 +1,27 @@
+UPDATE "prefix_Metadata"
+SET "key" = 'NEW_AGENT_WIZARD',
+    "note" = 'Controls the "new agent" flow. Allowed values: BOILERPLATE, WIZARD, MANGO_WIZARD.',
+    "updatedAt" = NOW()
+WHERE "key" = 'NEW_AGENT_' || 'WIZ' || 'ZARD'
+  AND NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'NEW_AGENT_WIZARD');
+
+DELETE FROM "prefix_Metadata"
+WHERE "key" = 'NEW_AGENT_' || 'WIZ' || 'ZARD';
+
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'NEW_AGENT_WIZARD',
+       'MANGO_WIZARD',
+       'Controls the "new agent" flow. Allowed values: BOILERPLATE, WIZARD, MANGO_WIZARD.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'NEW_AGENT_WIZARD');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN REPLACE(REPLACE(UPPER(TRIM(COALESCE("value", ''))), ' ', '_'), '-', '_') IN ('BOILERPLATE', 'WIZARD', 'MANGO_WIZARD')
+                      THEN REPLACE(REPLACE(UPPER(TRIM("value")), ' ', '_'), '-', '_')
+                  ELSE 'MANGO_WIZARD'
+              END,
+    "note" = 'Controls the "new agent" flow. Allowed values: BOILERPLATE, WIZARD, MANGO_WIZARD.',
+    "updatedAt" = NOW()
+WHERE "key" = 'NEW_AGENT_WIZARD';

package/apps/agents-server/src/database/migrations/2026-06-2201-new-agent-wizard-mango-default.sql

@@ -0,0 +1,11 @@
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN REPLACE(REPLACE(UPPER(TRIM(COALESCE("value", ''))), ' ', '_'), '-', '_') = 'BOILERPLATE'
+                      THEN 'MANGO_WIZARD'
+                  WHEN REPLACE(REPLACE(UPPER(TRIM(COALESCE("value", ''))), ' ', '_'), '-', '_') IN ('WIZARD', 'MANGO_WIZARD')
+                      THEN REPLACE(REPLACE(UPPER(TRIM("value")), ' ', '_'), '-', '_')
+                  ELSE 'MANGO_WIZARD'
+              END,
+    "note" = 'Controls the "new agent" flow. Allowed values: BOILERPLATE, WIZARD, MANGO_WIZARD.',
+    "updatedAt" = NOW()
+WHERE "key" = 'NEW_AGENT_WIZARD';

package/apps/agents-server/src/database/migrations/2026-06-2600-agent-directory-performance-indexes.sql

@@ -0,0 +1,14 @@
+CREATE INDEX IF NOT EXISTS "prefix_Agent_deletedAt_sortOrder_agentName_idx"
+    ON "prefix_Agent" ("deletedAt", "sortOrder", "agentName");
+
+CREATE INDEX IF NOT EXISTS "prefix_Agent_visibility_deletedAt_sortOrder_agentName_idx"
+    ON "prefix_Agent" ("visibility", "deletedAt", "sortOrder", "agentName");
+
+CREATE INDEX IF NOT EXISTS "prefix_AgentFolder_deletedAt_parentId_sortOrder_name_idx"
+    ON "prefix_AgentFolder" ("deletedAt", "parentId", "sortOrder", "name");
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChat_userId_agentPermanentId_source_createdAt_idx"
+    ON "prefix_UserChat" ("userId", "agentPermanentId", "source", "createdAt" DESC);
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChat_agentPermanentId_source_userId_createdAt_idx"
+    ON "prefix_UserChat" ("agentPermanentId", "source", "userId", "createdAt" DESC);

package/apps/agents-server/src/database/migrations/2026-06-2700-default-agent-avatar-visual-octopus3d4.sql

@@ -0,0 +1,16 @@
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'DEFAULT_AGENT_AVATAR_VISUAL',
+       'OCTOPUS3D4',
+       'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN UPPER(COALESCE("value", '')) = 'OCTOPUS3D3' THEN 'OCTOPUS3D4'
+                  ELSE "value"
+              END,
+    "note" = 'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+    "updatedAt" = NOW()
+WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL';