@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/languages/translations/czech.yaml

@@ -9,6 +9,7 @@ common.chat: Chat
 chat.answerDurationLabel: 'Odpověď za {duration}'
 common.book: Book
 common.timeouts: Časovače
+common.projects: Projekty
 common.more: Více
 chatEnterBehavior.sectionEyebrow: Klávesové zkratky
 chatEnterBehavior.sectionTitle: Psaní zpráv
@@ -130,19 +131,23 @@ header.legalAndAbout: Právo a informace
 header.settings: Nastavení
 header.landingPage: Úvodní stránka
 header.userMemory: Moje paměť
-header.userWallet: Moje peněženka
+header.userWallet: Peněženka agentů
 header.utilities: Nástroje
 header.mockedChats: Ukázkové chaty
 header.viewAllUsers: Zobrazit všechny uživatele
 header.createNewUser: Vytvořit nového uživatele
 header.servers: Servery
 header.environmentVariables: Proměnné prostředí
+header.vpsEmailServer: E-mailový server VPS
+header.resourceMonitor: Monitoring zdrojů
 header.update: Aktualizace
 header.database: Databáze
+header.internalS3: Interní S3
 header.logs: Logy
-header.codeRunners: Code runnery
+header.harnessAuth: Přihlášení harnessu
 header.cliAccess: CLI přístup
 header.models: Modely
+header.coreAgents: Základní agenti
 header.openApiDocumentation: Dokumentace OpenAPI
 header.apiTokens: API tokeny
 header.metadata: Metadata
@@ -152,7 +157,9 @@ header.customJs: Vlastní JS
 header.chatHistory: Historie chatů
 header.usageAnalytics: Analytika využití
 header.taskManager: Správa úloh
+header.vpsTaskManager: Správa úloh (všechny servery)
 header.messagesEmails: Zprávy a e-maily
+header.emailServer: E-mailový server
 header.backups: Zálohy
 header.chatFeedback: Hodnocení chatu
 header.browser: Prohlížeč
@@ -162,6 +169,7 @@ header.searchEngineTest: Test vyhledávače
 header.errorSimulation: Simulace chyb
 header.imagesGallery: Galerie obrázků
 header.files: Soubory
+header.agentProjects: Projekty agentů
 header.users: Uživatelé
 header.shibboleth: Shibboleth
 header.versionInfo: Informace o verzi
@@ -170,6 +178,19 @@ header.story: Příběh
 header.documentationOverview: Přehled
 header.documentationApiReference: API reference
 header.documentationAll: Vše
+documentation.downloadManual: Stáhnout manuál
+documentation.preparingManual: Připravuji manuál…
+documentation.openDownloadOptions: Otevřít možnosti stažení manuálu
+documentation.exportFormatLabel: Formát
+documentation.exportLanguageLabel: Jazyk
+documentation.includeLowLevelCommitmentsLabel: Zahrnout nízkoúrovňové commitmenty
+documentation.includeLowLevelCommitmentsHint: Přidá závěrečnou kapitolu s pokročilými commitmenty, jako je MODEL. Většina autorů je nikdy nepotřebuje.
+documentation.bakedAgentsLabel: Agenti zahrnutí v manuálu
+documentation.bakedAgentsHint: 'Vybraní agenti ({count}) poskytnou příklady a určují prioritu commitmentů.'
+documentation.noBakedAgentsHint: Nejsou vybraní žádní agenti. Exportovaný manuál bude stejný pro každý server.
+documentation.noAgentsAvailable: Na tomto serveru nejsou k dispozici žádní agenti.
+documentation.downloadFailedTitle: Stažení manuálu se nezdařilo
+documentation.downloadFailedMessage: Book language manuál se nepodařilo stáhnout.
 header.loggedInAs: 'Přihlášen jako {username}'
 header.searchThisServerPlaceholder: Prohledat tento server…
 header.searchBoxDefaultPlaceholder: Hledat agenty, složky, dokumentaci nebo konverzace…
@@ -380,22 +401,39 @@ footer.logosAndBranding: Loga a vizuální identita
 footer.connectSectionTitle: Spojte se s námi
 footer.linksSectionTitle: Odkazy
 footer.allRightsReserved: Všechna práva vyhrazena.
-footer.madeInCzechRepublic: Vytvořeno s {emoji} v České republice.
+footer.madeInCzechRepublic: Vytvořeno s {emoji} v Evropě.
 footer.engineVersion: Verze jádra Promptbooku
 forbidden.title: 403 Zakázáno
 forbidden.message: Nemáte oprávnění k přístupu na tuto stránku.
 users.loadingUsers: Načítám uživatele…
 users.sectionTitle: 'Uživatelé ({count})'
+users.tableDescription: Pojmenovaní uživatelé jsou nahoře, anonymní návštěvníci jsou pod nimi.
+users.userColumn: Uživatel
+users.roleColumn: Role a identita
+users.activityColumn: Aktivita
+users.actionsColumn: Akce
+users.noUsers: Nebyli nalezeni žádní uživatelé.
 users.adminRole: Správce
+users.userRole: Uživatel
+users.anonymousUser: Anonymní uživatel
+users.anonymousLabel: Anonymní
 users.createdLabel: Vytvořeno
 users.removeAdmin: Odebrat roli správce
 users.makeAdmin: Nastavit jako správce
 users.delete: Smazat
 users.addNewUser: Přidat nového uživatele
+users.createDialogTitle: Vytvořit nového uživatele
+users.createDialogDescription: Přidejte účet, který se může přihlásit k tomuto serveru.
+users.closeCreateDialog: Zavřít dialog vytvoření uživatele
+users.usernameLabel: Uživatelské jméno
 users.usernamePlaceholder: Uživatelské jméno
+users.passwordLabel: Heslo
 users.passwordPlaceholder: Heslo
 users.passwordAriaLabel: Heslo
+users.generatePassword: Vygenerovat bezpečné heslo
+users.passwordGeneratorDescription: Používá bezpečný generátor náhodných hodnot vašeho prohlížeče.
 users.isAdminCheckbox: Administrátor
+users.adminRoleDescription: Správci mohou spravovat tento server a jeho uživatele.
 users.createUser: Vytvořit uživatele
 users.deleteConfirmTitle: Smazat uživatele
 users.deleteConfirmMessage: 'Opravdu chcete smazat uživatele {username}?'
@@ -418,7 +456,19 @@ users.deleteUserAction: Smazat uživatele
 users.createdAgentsTitle: Agenti tohoto uživatele
 users.createdAgentsDescription: Seznam agentů vytvořených tímto uživatelem zatím není propojený s datovým modelem.
 users.activityTitle: Aktivita
-users.activityDescription: Podrobné sledování aktivity zatím není k dispozici. Jako orientační přehled změn zatím můžete použít výše uvedené časy vytvoření a poslední úpravy.
+users.activityDescription: Poslední zaznamenané chatové zprávy tohoto uživatele.
+users.activityLoading: Načítám aktivitu…
+users.noActivity: Nebyla zaznamenána žádná aktivita v chatu.
+users.activityTime: Čas
+users.activityAgent: Agent
+users.activityRole: Role
+users.activityMessage: Zpráva
+users.activityAction: Akce
+users.openActivity: Otevřít
+users.activityShowing: Zobrazeno {count} z {total} zpráv.
+users.viewChatHistory: Historie chatu
+users.viewProfile: Zobrazit profil
+users.viewTasks: Správce úloh
 chat.feedback.reportIssueButtonTitle: Nahlásit problém
 chat.feedback.reportIssueButtonAriaLabel: Nahlásit problém s touto odpovědí
 chat.feedback.reportIssueModalTitle: Nahlásit problém

package/apps/agents-server/src/languages/translations/english.yaml

@@ -9,6 +9,7 @@ common.chat: Chat
 chat.answerDurationLabel: '{duration} to answer'
 common.book: Book
 common.timeouts: Timeouts
+common.projects: Projects
 common.more: More
 chatEnterBehavior.sectionEyebrow: Keybindings
 chatEnterBehavior.sectionTitle: Chat composer
@@ -132,19 +133,23 @@ header.legalAndAbout: Legal & About
 header.settings: Settings
 header.landingPage: Landing page
 header.userMemory: User Memory
-header.userWallet: User Wallet
+header.userWallet: Agent Wallet
 header.utilities: Utilities
 header.mockedChats: Mocked Chats
 header.viewAllUsers: View all users
 header.createNewUser: Create new user
 header.servers: Servers
 header.environmentVariables: Environment variables
+header.vpsEmailServer: VPS email server
+header.resourceMonitor: Resource monitor
 header.update: Update
 header.database: Database
+header.internalS3: Internal S3
 header.logs: Logs
-header.codeRunners: Code runners
+header.harnessAuth: Harness Auth
 header.cliAccess: CLI Access
 header.models: Models
+header.coreAgents: Core Agents
 header.openApiDocumentation: OpenAPI Documentation
 header.apiTokens: API Tokens
 header.metadata: Metadata
@@ -154,7 +159,9 @@ header.customJs: Custom JS
 header.chatHistory: Chat history
 header.usageAnalytics: Usage analytics
 header.taskManager: Task manager
+header.vpsTaskManager: Task manager (all servers)
 header.messagesEmails: Messages & Emails
+header.emailServer: Email server
 header.backups: Backups
 header.chatFeedback: Chat feedback
 header.browser: Browser
@@ -164,6 +171,7 @@ header.searchEngineTest: Search Engine Test
 header.errorSimulation: Error simulation
 header.imagesGallery: Images gallery
 header.files: Files
+header.agentProjects: Agent Projects
 header.users: Users
 header.shibboleth: Shibboleth
 header.versionInfo: Version info
@@ -172,6 +180,19 @@ header.story: Story
 header.documentationOverview: Overview
 header.documentationApiReference: API Reference
 header.documentationAll: All
+documentation.downloadManual: Download manual
+documentation.preparingManual: Preparing manual…
+documentation.openDownloadOptions: Open manual download options
+documentation.exportFormatLabel: Format
+documentation.exportLanguageLabel: Language
+documentation.includeLowLevelCommitmentsLabel: Include low level commitments
+documentation.includeLowLevelCommitmentsHint: Adds a closing chapter with advanced commitments such as MODEL. Most authors never need them.
+documentation.bakedAgentsLabel: Agents included in the manual
+documentation.bakedAgentsHint: '{count} selected agent(s) will provide the examples and commitment priority.'
+documentation.noBakedAgentsHint: No agents selected. The exported manual will be generic for every server.
+documentation.noAgentsAvailable: No agents are available on this server.
+documentation.downloadFailedTitle: Manual download failed
+documentation.downloadFailedMessage: Failed to download the Book language manual.
 header.loggedInAs: Logged in as {username}
 header.searchThisServerPlaceholder: Search this server...
 header.searchBoxDefaultPlaceholder: Search agents, folders, docs, conversations...
@@ -390,16 +411,33 @@ forbidden.title: 403 Forbidden
 forbidden.message: You do not have permission to access this page.
 users.loadingUsers: Loading users...
 users.sectionTitle: Users ({count})
+users.tableDescription: Named users appear first; anonymous visitors are grouped below them.
+users.userColumn: User
+users.roleColumn: Role and identity
+users.activityColumn: Activity
+users.actionsColumn: Actions
+users.noUsers: No users found.
 users.adminRole: Admin
+users.userRole: User
+users.anonymousUser: Anonymous user
+users.anonymousLabel: Anonymous
 users.createdLabel: Created
 users.removeAdmin: Remove Admin
 users.makeAdmin: Make Admin
 users.delete: Delete
 users.addNewUser: Add New User
+users.createDialogTitle: Create new user
+users.createDialogDescription: Add an account that can sign in to this server.
+users.closeCreateDialog: Close create user dialog
+users.usernameLabel: Username
 users.usernamePlaceholder: Username
+users.passwordLabel: Password
 users.passwordPlaceholder: Password
 users.passwordAriaLabel: Password
+users.generatePassword: Generate secure password
+users.passwordGeneratorDescription: Uses your browser's secure random generator.
 users.isAdminCheckbox: Is Admin
+users.adminRoleDescription: Administrators can manage this server and its users.
 users.createUser: Create User
 users.deleteConfirmTitle: Delete user
 users.deleteConfirmMessage: Are you sure you want to delete user {username}?
@@ -422,7 +460,19 @@ users.deleteUserAction: Delete user
 users.createdAgentsTitle: Created agents
 users.createdAgentsDescription: Listing agents created by users is not wired to the data model yet.
 users.activityTitle: Activity
-users.activityDescription: Detailed activity tracking is not implemented yet. For now, you can use the created and updated timestamps above as a basic signal of recent changes.
+users.activityDescription: Recent recorded chat messages for this user.
+users.activityLoading: Loading activity...
+users.noActivity: No recorded chat activity.
+users.activityTime: Time
+users.activityAgent: Agent
+users.activityRole: Role
+users.activityMessage: Message
+users.activityAction: Action
+users.openActivity: Open
+users.activityShowing: Showing {count} of {total} messages.
+users.viewChatHistory: Chat history
+users.viewProfile: View profile
+users.viewTasks: Task manager
 chat.feedback.reportIssueButtonTitle: Report issue
 chat.feedback.reportIssueButtonAriaLabel: Report issue with this response
 chat.feedback.reportIssueModalTitle: Report issue

package/apps/agents-server/src/message-providers/email/_common/parseInboundEmail.ts

@@ -0,0 +1,71 @@
+import type { string_email, string_markdown } from '@promptbook-local/types';
+import { simpleParser, type AddressObject, type EmailAddress as ParsedEmailAddress } from 'mailparser';
+import TurndownService from 'turndown';
+import { extractBodyContentFromHtml } from '../../../utils/content/extractBodyContentFromHtml';
+import type { EmailAddress, InboundEmail } from './Email';
+import { parseEmailAddress } from './utils/parseEmailAddress';
+
+/**
+ * Parses one RFC 5322 message into the shared inbound-email representation.
+ */
+export async function parseInboundEmail(rawEmail: string | Buffer): Promise<InboundEmail> {
+    const parsedEmail = await simpleParser(rawEmail);
+    const from = parseAddressObjects(parsedEmail.from);
+    const to = parseAddressObjects(parsedEmail.to);
+    const cc = parseAddressObjects(parsedEmail.cc);
+    const turndownService = new TurndownService();
+    const content = (parsedEmail.html
+        ? turndownService.turndown(extractBodyContentFromHtml(parsedEmail.html))
+        : parsedEmail.text || '') as string_markdown;
+
+    return {
+        channel: 'EMAIL',
+        direction: 'INBOUND',
+        sender: from[0]?.fullEmail || ('' as string_email),
+        recipients: to.map((emailAddress) => emailAddress.fullEmail),
+        cc,
+        subject: parsedEmail.subject || '',
+        content,
+        attachments: [
+            /* <- TODO: [📯] Parse attachments */
+        ],
+        metadata: {
+            messageId: parsedEmail.messageId || null,
+            inReplyTo: parsedEmail.inReplyTo || null,
+            references: parsedEmail.references || [],
+            autoSubmitted: parsedEmail.headers.get('auto-submitted') || null,
+            promptbookAgentReply: parsedEmail.headers.get('x-promptbook-agent-reply') || null,
+        },
+    };
+}
+
+/**
+ * Normalizes MailParser's singular-or-array address field.
+ */
+function normalizeAddressObjects<T>(value: T | T[] | undefined): T[] {
+    if (value === undefined) {
+        return [];
+    }
+
+    return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Converts MailParser address structures without splitting quoted display names on commas.
+ */
+function parseAddressObjects(value: AddressObject | AddressObject[] | undefined): EmailAddress[] {
+    return normalizeAddressObjects(value)
+        .flatMap((addressObject) => addressObject.value)
+        .flatMap(flattenParsedEmailAddress)
+        .map((address) => parseEmailAddress(address));
+}
+
+/**
+ * Recursively extracts mailbox strings from regular and grouped parsed addresses.
+ */
+function flattenParsedEmailAddress(value: ParsedEmailAddress): string[] {
+    return [
+        ...(value.address ? [value.address] : []),
+        ...(value.group || []).flatMap(flattenParsedEmailAddress),
+    ];
+}

package/apps/agents-server/src/message-providers/email/sendgrid/parseInboundSendgridEmail.ts

@@ -1,49 +1,9 @@
-import { string_markdown } from '@promptbook-local/types';
-import { simpleParser } from 'mailparser';
-import TurndownService from 'turndown';
-import { extractBodyContentFromHtml } from '../../../utils/content/extractBodyContentFromHtml';
 import type { InboundEmail } from '../_common/Email';
-import { parseEmailAddress } from '../_common/utils/parseEmailAddress';
-import { parseEmailAddresses } from '../_common/utils/parseEmailAddresses';
+import { parseInboundEmail } from '../_common/parseInboundEmail';
 
 /**
  * Function parseInboundSendgridEmail will parse raw inbound email from Sendgrid and return Email object
  */
 export async function parseInboundSendgridEmail(rawEmail: string): Promise<InboundEmail> {
-    const parsedEmail = await simpleParser(rawEmail);
-
-    const toArray = !Array.isArray(parsedEmail.to)
-        ? parsedEmail.to === undefined
-            ? []
-            : [parsedEmail.to]
-        : parsedEmail.to;
-    const to = toArray.flatMap((_) => parseEmailAddresses(_.text));
-
-    const ccArray = !Array.isArray(parsedEmail.cc)
-        ? parsedEmail.cc === undefined
-            ? []
-            : [parsedEmail.cc]
-        : parsedEmail.cc;
-    const cc = ccArray.flatMap((_) => parseEmailAddresses(_.text));
-
-    const turndownService = new TurndownService();
-
-    const content = (parsedEmail.html
-        ? turndownService.turndown(extractBodyContentFromHtml(parsedEmail.html))
-        : parsedEmail.text || '') as string_markdown;
-
-    const email: InboundEmail = {
-        channel: 'EMAIL',
-        direction: 'INBOUND',
-        sender: parseEmailAddress(parsedEmail.from?.text || '').fullEmail,
-        recipients: to.map((_) => _.fullEmail),
-        cc,
-        subject: parsedEmail.subject || '',
-        content,
-        attachments: [
-            /* <- TODO: [📯] Parse attachments */
-        ],
-    };
-
-    return email;
+    return parseInboundEmail(rawEmail);
 }

package/apps/agents-server/src/message-providers/email/smtp/SmtpMessageProvider.ts

@@ -13,6 +13,7 @@ export type SmtpMessageProviderConfiguration = {
     host: string;
     port: number;
     secure: boolean;
+    isTlsCertificateValidationEnabled?: boolean;
     username: string;
     password: string;
 };
@@ -28,6 +29,9 @@ export class SmtpMessageProvider implements MessageProvider {
             host: configuration.host,
             port: configuration.port,
             secure: configuration.secure,
+            tls: {
+                rejectUnauthorized: configuration.isTlsCertificateValidationEnabled ?? true,
+            },
             auth: {
                 user: configuration.username,
                 pass: configuration.password,
@@ -49,6 +53,7 @@ export class SmtpMessageProvider implements MessageProvider {
 
         const text = removeMarkdownFormatting(message.content);
         const html = await marked.parse(message.content);
+        const headers = normalizeStringRecord(message.metadata?.headers);
 
         return this.transporter.sendMail({
             from: sender.fullName
@@ -62,6 +67,44 @@ export class SmtpMessageProvider implements MessageProvider {
             subject: message.subject || message.metadata?.subject || 'No Subject',
             text,
             html,
+            replyTo: normalizeOptionalString(message.metadata?.replyTo),
+            inReplyTo: normalizeOptionalString(message.metadata?.inReplyTo),
+            references: normalizeStringArray(message.metadata?.references),
+            headers: Object.keys(headers).length > 0 ? headers : undefined,
         });
     }
 }
+
+/**
+ * Normalizes an arbitrary metadata value to an optional non-empty string.
+ */
+function normalizeOptionalString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Normalizes an arbitrary metadata value to a string array.
+ */
+function normalizeStringArray(value: unknown): string[] | undefined {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+
+    const normalizedValues = value.filter((item): item is string => typeof item === 'string' && Boolean(item.trim()));
+    return normalizedValues.length > 0 ? normalizedValues : undefined;
+}
+
+/**
+ * Normalizes custom SMTP headers stored in message metadata.
+ */
+function normalizeStringRecord(value: unknown): Record<string, string> {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+
+    return Object.fromEntries(
+        Object.entries(value).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string' && Boolean(entry[1].trim()),
+        ),
+    );
+}

package/apps/agents-server/src/message-providers/email/stalwart/StalwartMessageProvider.ts

@@ -0,0 +1,74 @@
+import type { really_any } from '@promptbook-local/types';
+import { buildStalwartMailBridgeAddress } from '../../../utils/stalwart/stalwartMailBridge';
+import type { MessageProvider } from '../../interfaces/MessageProvider';
+import type { OutboundEmail } from '../_common/Email';
+import { parseEmailAddress } from '../_common/utils/parseEmailAddress';
+import { SmtpMessageProvider } from '../smtp/SmtpMessageProvider';
+
+/**
+ * SMTP settings shared by every domain hosted by the bundled Stalwart service.
+ */
+export type StalwartMessageProviderConfiguration = {
+    readonly host: string;
+    readonly port: number;
+    readonly isSecure: boolean;
+    readonly isTlsCertificateValidationEnabled: boolean;
+    readonly username: string | null;
+    readonly password: string;
+};
+
+/**
+ * Domain-aware Stalwart provider which authenticates through the bridge account matching the sender.
+ */
+export class StalwartMessageProvider implements MessageProvider {
+    public constructor(private readonly configuration: StalwartMessageProviderConfiguration) {}
+
+    /**
+     * Sends one message through the bridge account belonging to its From domain.
+     */
+    public async send(message: OutboundEmail): Promise<really_any> {
+        const senderAddress = parseEmailAddress(message.sender).fullEmail;
+        const senderDomain = senderAddress.slice(senderAddress.lastIndexOf('@') + 1).toLowerCase();
+        const provider = new SmtpMessageProvider({
+            host: this.configuration.host,
+            port: this.configuration.port,
+            secure: this.configuration.isSecure,
+            isTlsCertificateValidationEnabled: this.configuration.isTlsCertificateValidationEnabled,
+            username: this.configuration.username || buildStalwartMailBridgeAddress(senderDomain),
+            password: this.configuration.password,
+        });
+
+        return provider.send(message);
+    }
+}
+
+/**
+ * Submission port of a freshly bootstrapped Stalwart instance.
+ *
+ * Stalwart opens `smtp` on 25 and `submissions` on 465 (implicit TLS); it has **no** listener on the
+ * STARTTLS submission port 587, so mail submitted there is refused.
+ */
+const STALWART_DEFAULT_SUBMISSION_PORT = 465;
+
+/**
+ * Builds the bundled Stalwart provider when its SMTP credential is configured.
+ */
+export function createStalwartMessageProviderFromEnvironment(): StalwartMessageProvider | null {
+    const password = process.env.PTBK_STALWART_SMTP_PASSWORD;
+    if (!password) {
+        return null;
+    }
+
+    // Note: Port 465 speaks implicit TLS, so an unset `PTBK_STALWART_SMTP_SECURE` must default to `true`
+    const configuredSecureValue = process.env.PTBK_STALWART_SMTP_SECURE?.trim();
+
+    return new StalwartMessageProvider({
+        host: process.env.PTBK_STALWART_SMTP_HOST || '127.0.0.1',
+        port: Number(process.env.PTBK_STALWART_SMTP_PORT || STALWART_DEFAULT_SUBMISSION_PORT),
+        isSecure: configuredSecureValue ? configuredSecureValue === 'true' : true,
+        isTlsCertificateValidationEnabled:
+            process.env.PTBK_STALWART_SMTP_TLS_REJECT_UNAUTHORIZED === 'true',
+        username: process.env.PTBK_STALWART_SMTP_USERNAME?.trim() || null,
+        password,
+    });
+}

package/apps/agents-server/src/message-providers/email/stalwart/StalwartMtaHookPayload.ts

@@ -0,0 +1,32 @@
+/**
+ * Envelope mailbox included in a Stalwart MTA hook request.
+ */
+export type StalwartMtaHookMailbox = {
+    readonly address: string;
+    readonly parameters?: Readonly<Record<string, unknown>> | null;
+};
+
+/**
+ * DATA-stage payload sent by Stalwart to the Agents Server.
+ */
+export type StalwartMtaHookPayload = {
+    readonly context?: {
+        readonly stage?: string;
+        readonly queue?: {
+            readonly id?: string;
+        };
+        readonly sasl?: {
+            readonly login?: string;
+        } | null;
+    };
+    readonly envelope?: {
+        readonly from?: StalwartMtaHookMailbox | null;
+        readonly to?: ReadonlyArray<StalwartMtaHookMailbox>;
+    };
+    readonly message?: {
+        readonly headers?: ReadonlyArray<readonly [string, string]>;
+        readonly serverHeaders?: ReadonlyArray<readonly [string, string]>;
+        readonly contents?: string;
+        readonly size?: number;
+    };
+};

package/apps/agents-server/src/message-providers/email/stalwart/parseInboundStalwartEmail.ts

@@ -0,0 +1,74 @@
+import { ParseError } from '../../../../../../src/errors/ParseError';
+import { spaceTrim } from '../../../../../../src/utils/organization/spaceTrim';
+import type { InboundEmail } from '../_common/Email';
+import { parseInboundEmail } from '../_common/parseInboundEmail';
+import type { StalwartMtaHookPayload } from './StalwartMtaHookPayload';
+
+/**
+ * Parsed Stalwart inbound message together with the SMTP transport envelope.
+ */
+export type ParsedInboundStalwartEmail = {
+    readonly email: InboundEmail;
+    readonly envelopeSender: string;
+    readonly envelopeRecipients: ReadonlyArray<string>;
+    readonly queueId: string | null;
+};
+
+/**
+ * Reconstructs an RFC 5322 message from Stalwart's DATA-stage MTA hook payload.
+ */
+export async function parseInboundStalwartEmail(
+    payload: StalwartMtaHookPayload,
+): Promise<ParsedInboundStalwartEmail> {
+    if (payload.context?.stage?.toUpperCase() !== 'DATA') {
+        throw new ParseError(
+            spaceTrim(`
+                Stalwart sent an unsupported MTA hook stage.
+
+                **Expected:** \`DATA\`
+                **Received:** \`${payload.context?.stage || 'missing'}\`
+            `),
+        );
+    }
+
+    const headers = payload.message?.headers;
+    const contents = payload.message?.contents;
+    const envelopeSender = payload.envelope?.from?.address?.trim() || '';
+    const envelopeRecipients = (payload.envelope?.to || [])
+        .map((recipient) => recipient.address.trim())
+        .filter(Boolean);
+
+    if (!headers || typeof contents !== 'string' || envelopeRecipients.length === 0) {
+        throw new ParseError(
+            spaceTrim(`
+                Stalwart sent an incomplete DATA-stage MTA hook payload.
+
+                Required fields are \`message.headers\`, \`message.contents\`, and \`envelope.to\`.
+            `),
+        );
+    }
+
+    const rawEmail = `${[...(payload.message?.serverHeaders || []), ...headers]
+        .map(([name, value]) => `${name}: ${value}`)
+        .join('\r\n')}\r\n\r\n${contents}`;
+
+    let email: InboundEmail;
+    try {
+        email = await parseInboundEmail(rawEmail);
+    } catch (error) {
+        throw new ParseError(
+            spaceTrim(`
+                Stalwart supplied an invalid RFC 5322 message.
+
+                **Cause:** \`${error instanceof Error ? error.message : String(error)}\`
+            `),
+        );
+    }
+
+    return {
+        email,
+        envelopeSender,
+        envelopeRecipients,
+        queueId: payload.context?.queue?.id || null,
+    };
+}

package/apps/agents-server/src/message-providers/index.ts

@@ -1,4 +1,5 @@
 import { SendgridMessageProvider } from './email/sendgrid/SendgridMessageProvider';
+import { createStalwartMessageProviderFromEnvironment } from './email/stalwart/StalwartMessageProvider';
 import { ZeptomailMessageProvider } from './email/zeptomail/ZeptomailMessageProvider';
 import { MessageProvider } from './interfaces/MessageProvider';
 
@@ -7,6 +8,14 @@ import { MessageProvider } from './interfaces/MessageProvider';
  */
 export const EMAIL_PROVIDERS: Record<string, MessageProvider> = {};
 
+/**
+ * Optional bundled provider shared by ordinary outbound email flows.
+ */
+const STALWART_MESSAGE_PROVIDER = createStalwartMessageProviderFromEnvironment();
+if (STALWART_MESSAGE_PROVIDER) {
+    EMAIL_PROVIDERS['STALWART'] = STALWART_MESSAGE_PROVIDER;
+}
+
 if (process.env.ZEPTOMAIL_API_KEY) {
     EMAIL_PROVIDERS['ZEPTOMAIL'] = new ZeptomailMessageProvider(process.env.ZEPTOMAIL_API_KEY);
 }

package/apps/agents-server/src/middleware.ts

@@ -69,7 +69,8 @@ export const config = {
          * - public folder
          * - api/health (standalone VPS readiness probe)
          * - api/internal (worker/cron routes are authorized separately)
+         * - api/agent-project-runtime-auth (nginx internal auth subrequests are authorized by runtime domain)
          */
-        '/((?!_next/static|_next/image|favicon.ico|logo-|fonts/|robots.txt|api/health|api/internal).*)',
+        '/((?!_next/static|_next/image|favicon.ico|logo-|fonts/|robots.txt|api/health|api/internal|api/agent-project-runtime-auth).*)',
     ],
 };