@promptbook/cli 0.113.0-9 → 0.114.0-1

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).*)',
     ],
 };

package/apps/agents-server/src/search/createDefaultServerSearchProviders/createConversationsSearchProvider.ts

@@ -28,7 +28,7 @@ type UserChatSearchRow = Pick<
  */
 type ChatHistorySearchRow = Pick<
     AgentsServerDatabase['public']['Tables']['ChatHistory']['Row'],
-    'id' | 'createdAt' | 'agentName' | 'message' | 'url' | 'ip'
+    'id' | 'createdAt' | 'agentName' | 'chatId' | 'message' | 'url' | 'ip'
 >;
 
 /**
@@ -162,7 +162,7 @@ async function searchAdminConversations(
     const supabase = $provideSupabaseForServer();
     const { data, error } = await supabase
         .from(await $getTableName('ChatHistory'))
-        .select('id, createdAt, agentName, message, url, ip')
+        .select('id, createdAt, agentName, chatId, message, url, ip')
         .order('createdAt', { ascending: false })
         .limit(defaultServerSearchProviderConfig.adminLogLimit);
 
@@ -185,6 +185,13 @@ async function searchAdminConversations(
             continue;
         }
 
+        const adminChatHistoryParams = new URLSearchParams({ agentName: row.agentName });
+        if (row.chatId) {
+            // Note: Deep-link straight to the recorded conversation (most detailed view) when the thread is known
+            adminChatHistoryParams.set('chatId', row.chatId);
+            adminChatHistoryParams.set('view', 'chat');
+        }
+
         results.push({
             id: `conversation-admin-${row.id}`,
             providerId: 'conversations',
@@ -193,7 +200,7 @@ async function searchAdminConversations(
             icon: 'conversation',
             title: `Chat log #${row.id} (${row.agentName})`,
             snippet: match.snippet,
-            href: `/admin/chat-history?agentName=${encodeURIComponent(row.agentName)}`,
+            href: `/admin/chat-history?${adminChatHistoryParams.toString()}`,
             score: match.score + 6,
         });
     }

package/apps/agents-server/src/tools/$provideBrowserForServer.ts

@@ -14,7 +14,10 @@ let browserProvider: BrowserConnectionProvider | null = null;
  * This function supports both local and remote browser connections based on environment configuration.
  * Use REMOTE_BROWSER_URL environment variable to configure a remote Playwright server.
  *
- * @param options - Optional runtime request options used for cancellation and logging context.
+ * Pass `options.browserProfileDirectory` to browse inside the persistent isolated browser profile
+ * of one agent instead of the shared default profile.
+ *
+ * @param options - Optional runtime request options used for cancellation, profile selection and logging context.
  * @returns Browser context instance
  */
 export async function $provideBrowserForServer(options: BrowserContextRequestOptions = {}): Promise<BrowserContext> {

package/apps/agents-server/src/tools/$provideServer.ts

@@ -5,11 +5,12 @@ import { isAgentsServerSqliteMode } from '../database/agentsServerDatabaseMode';
 import { resolveInternalServerOrigin } from '../utils/resolveInternalServerOrigin';
 import { createServerPublicUrl, listRegisteredServersUsingServiceRole } from '../utils/serverRegistry';
 import { resolveServerSelection } from '../utils/serverSelection';
+import { getServerContextOverride } from './serverContextOverride';
 
 /**
  * Resolved server routing context for the current request.
  */
-type ProvidedServer = {
+export type ProvidedServer = {
     /**
      * Registered server id when the request points to one.
      */
@@ -63,7 +64,7 @@ const getCachedProvidedServer = cache(async (): Promise<ProvidedServer> => {
                     };
                 }
 
-                throw new Error(`Server with host "${requestHost}" is not registered in SERVERS`);
+                throw new Error(`Server with host "${requestHost}" is not registered in the VPS server registry`);
             }
 
             return {
@@ -118,9 +119,20 @@ const getCachedProvidedServer = cache(async (): Promise<ProvidedServer> => {
 /**
  * Resolves the current server routing context.
  *
+ * When a background worker runs work on behalf of one specific VPS server (see
+ * `runWithServerContextOverride`), the explicit override wins over the request-header
+ * resolution. This lets a single detached worker tick process every registered server
+ * on the VPS without depending on a matching `host` header, which loopback self-calls
+ * never carry.
+ *
  * @returns Server routing context for the current request.
  */
 export async function $provideServer(): Promise<ProvidedServer> {
+    const overriddenServer = getServerContextOverride();
+    if (overriddenServer) {
+        return overriddenServer;
+    }
+
     return getCachedProvidedServer();
 }