@promptbook/cli 0.113.0-9 → 0.114.0-1

package/apps/agents-server/src/utils/dnsProviderGuides.ts

@@ -0,0 +1,38 @@
+/**
+ * One external DNS-provider help link shown with DNS setup guidance.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsProviderGuide = {
+    /**
+     * Human-readable provider label.
+     */
+    readonly label: string;
+
+    /**
+     * Official provider help URL.
+     */
+    readonly href: string;
+};
+
+/**
+ * Common DNS-provider help links shown with server and project DNS instructions.
+ */
+export const DNS_PROVIDER_GUIDES: ReadonlyArray<DnsProviderGuide> = [
+    {
+        label: 'Cloudflare DNS records',
+        href: 'https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/',
+    },
+    {
+        label: 'GoDaddy DNS records',
+        href: 'https://www.godaddy.com/help/manage-dns-records-680',
+    },
+    {
+        label: 'Namecheap DNS records',
+        href: 'https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain/',
+    },
+    {
+        label: 'Squarespace DNS records',
+        href: 'https://support.squarespace.com/hc/en-us/articles/360002101888-Adding-custom-DNS-records-to-your-Squarespace-managed-domain',
+    },
+];

package/apps/agents-server/src/utils/dnsRecords/DnsRecordInstruction.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether every shown DNS record has to be configured or just one of the shown alternatives.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordSelection = 'all' | 'one';
+
+/**
+ * One DNS record shown to an Agents Server administrator for configuration at a DNS provider.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordInstruction = {
+    /**
+     * DNS record type.
+     */
+    readonly type: string;
+
+    /**
+     * Fully qualified DNS record name.
+     */
+    readonly name: string;
+
+    /**
+     * DNS record value to configure.
+     */
+    readonly value: string;
+
+    /**
+     * Explanation of when or why this record is needed.
+     */
+    readonly note: string | null;
+};

package/apps/agents-server/src/utils/dnsRecords/createDnsZoneFileExport.ts

@@ -0,0 +1,91 @@
+import { spaceTrim } from 'spacetrim';
+import { CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC } from '../cloudflare/CloudflareApi';
+import type { DnsRecordInstruction } from './DnsRecordInstruction';
+
+/**
+ * DNS record types whose value is a hostname which has to be absolute in a zone file.
+ */
+const DNS_ZONE_FILE_HOSTNAME_RECORD_TYPES: ReadonlySet<string> = new Set(['CNAME', 'NS', 'PTR']);
+
+/**
+ * A zone-file character string can hold at most 255 characters, longer `TXT` values are split into more strings.
+ */
+const DNS_ZONE_FILE_TEXT_CHUNK_LENGTH = 255;
+
+/**
+ * Creates a BIND zone file with all given DNS records.
+ *
+ * The file can be imported at once by DNS providers which support zone-file imports, so that an administrator does
+ * not have to retype the records one by one.
+ *
+ * @param options - Domain and the records which should be part of the export.
+ * @returns BIND zone file contents.
+ */
+export function createDnsZoneFileExport(options: {
+    readonly domain: string;
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+}): string {
+    const recordLines = options.records.map((record) =>
+        [
+            `${normalizeZoneFileRecordName(record.name)}.`,
+            String(CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC),
+            'IN',
+            record.type.toUpperCase(),
+            createZoneFileRecordData(record.type, record.value),
+        ].join('\t'),
+    );
+
+    return spaceTrim(
+        (block) => `
+            ; DNS records for ${options.domain} generated by the Promptbook Agents Server
+            ; Import this file at your DNS provider instead of adding every record by hand.
+
+            ${block(recordLines.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Normalizes one record name into its absolute zone-file form without the trailing dot.
+ *
+ * @param name - Fully qualified DNS record name.
+ * @returns Record name usable in a zone file.
+ */
+function normalizeZoneFileRecordName(name: string): string {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}
+
+/**
+ * Creates the zone-file record data of one DNS record.
+ *
+ * @param type - DNS record type.
+ * @param value - DNS record value as shown in the DNS manual.
+ * @returns Record data in the zone-file syntax.
+ */
+function createZoneFileRecordData(type: string, value: string): string {
+    const normalizedType = type.toUpperCase();
+    const normalizedValue = value.trim();
+
+    if (normalizedType === 'TXT') {
+        return createZoneFileTextRecordData(normalizedValue);
+    }
+
+    if (DNS_ZONE_FILE_HOSTNAME_RECORD_TYPES.has(normalizedType)) {
+        return normalizedValue.endsWith('.') ? normalizedValue : `${normalizedValue}.`;
+    }
+
+    return normalizedValue;
+}
+
+/**
+ * Quotes one `TXT` value and splits it into zone-file character strings.
+ *
+ * @param value - Raw text value, for example an SPF or DMARC policy.
+ * @returns Quoted character strings.
+ */
+function createZoneFileTextRecordData(value: string): string {
+    const unquotedValue = value.replace(/^"(.*)"$/s, '$1');
+    const textChunks = unquotedValue.match(new RegExp(`.{1,${DNS_ZONE_FILE_TEXT_CHUNK_LENGTH}}`, 'gs')) || [''];
+
+    return textChunks.map((textChunk) => `"${textChunk.replace(/"/g, '\\"')}"`).join(' ');
+}

package/apps/agents-server/src/utils/dnsRecords/resolveDnsRecordBatchPlan.ts

@@ -0,0 +1,81 @@
+import type { DnsRecordInstruction, DnsRecordSelection } from './DnsRecordInstruction';
+
+/**
+ * Placeholder values like `<VPS_PUBLIC_IP>` have to be filled in by a human before the record can be created.
+ */
+const DNS_RECORD_PLACEHOLDER_VALUE_PATTERN = /<[^>]+>/;
+
+/**
+ * One DNS record which cannot be configured in one batch together with the other records.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type ExcludedDnsRecordInstruction = {
+    /**
+     * DNS record which has to be configured manually.
+     */
+    readonly record: DnsRecordInstruction;
+
+    /**
+     * Explanation why the record is not part of the batch.
+     */
+    readonly reason: string;
+};
+
+/**
+ * Split of the DNS records shown in one manual into records which can be configured in one batch and the rest.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordBatchPlan = {
+    /**
+     * DNS records which can be exported or written to the DNS provider without any human decision.
+     */
+    readonly applicableRecords: ReadonlyArray<DnsRecordInstruction>;
+
+    /**
+     * DNS records which are intentionally left out of the batch.
+     */
+    readonly excludedRecords: ReadonlyArray<ExcludedDnsRecordInstruction>;
+};
+
+/**
+ * Resolves which of the shown DNS records can be configured in one batch.
+ *
+ * This is the single source of truth for both the zone-file export and the Cloudflare API import, so that both ways
+ * of the wizard configure exactly the same records.
+ *
+ * @param options - Records shown in the DNS manual and whether they are alternatives.
+ * @returns Records which can be batched together with the reasons for the excluded ones.
+ */
+export function resolveDnsRecordBatchPlan(options: {
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+    readonly recordSelection: DnsRecordSelection;
+}): DnsRecordBatchPlan {
+    const applicableRecords: Array<DnsRecordInstruction> = [];
+    const excludedRecords: Array<ExcludedDnsRecordInstruction> = [];
+
+    for (const record of options.records) {
+        if (DNS_RECORD_PLACEHOLDER_VALUE_PATTERN.test(record.value)) {
+            excludedRecords.push({
+                record,
+                reason: `The value \`${record.value}\` is a placeholder which has to be filled in manually.`,
+            });
+            continue;
+        }
+
+        // Note: When the records are alternatives, only the first (recommended) one may be configured, because the
+        //       other ones would conflict with it on the same hostname.
+        if (options.recordSelection === 'one' && applicableRecords.length > 0) {
+            excludedRecords.push({
+                record,
+                reason: 'Alternative of the recommended record, configure it only instead of the recommended record.',
+            });
+            continue;
+        }
+
+        applicableRecords.push(record);
+    }
+
+    return { applicableRecords, excludedRecords };
+}

package/apps/agents-server/src/utils/email/EmailUserChatContext.ts

@@ -0,0 +1,64 @@
+/**
+ * Email transport context persisted with a durable user-chat job.
+ */
+export type EmailUserChatContext = {
+    readonly agentDisplayName: string;
+    readonly agentLocalParts: ReadonlyArray<string>;
+    readonly sender: string;
+    readonly to: ReadonlyArray<string>;
+    readonly cc: ReadonlyArray<string>;
+    readonly deliveredTo: string;
+    readonly subject: string;
+    readonly messageId: string | null;
+    readonly references: ReadonlyArray<string>;
+};
+
+/**
+ * Durable job parameter key containing inbound email transport context.
+ */
+export const EMAIL_USER_CHAT_CONTEXT_PARAMETER = 'emailContext';
+
+/**
+ * Reads validated email context from arbitrary durable-job parameters.
+ */
+export function parseEmailUserChatContext(parameters: Readonly<Record<string, unknown>>): EmailUserChatContext | null {
+    const value = parameters[EMAIL_USER_CHAT_CONTEXT_PARAMETER];
+
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+
+    const candidate = value as Partial<Record<keyof EmailUserChatContext, unknown>>;
+    if (
+        typeof candidate.sender !== 'string' ||
+        typeof candidate.agentDisplayName !== 'string' ||
+        typeof candidate.deliveredTo !== 'string' ||
+        typeof candidate.subject !== 'string' ||
+        !isStringArray(candidate.agentLocalParts) ||
+        !isStringArray(candidate.to) ||
+        !isStringArray(candidate.cc) ||
+        !isStringArray(candidate.references) ||
+        (candidate.messageId !== null && typeof candidate.messageId !== 'string')
+    ) {
+        return null;
+    }
+
+    return {
+        agentDisplayName: candidate.agentDisplayName,
+        agentLocalParts: candidate.agentLocalParts,
+        sender: candidate.sender,
+        to: candidate.to,
+        cc: candidate.cc,
+        deliveredTo: candidate.deliveredTo,
+        subject: candidate.subject,
+        messageId: candidate.messageId,
+        references: candidate.references,
+    };
+}
+
+/**
+ * Checks whether an unknown value is an array of strings.
+ */
+function isStringArray(value: unknown): value is string[] {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}

package/apps/agents-server/src/utils/email/agentEmailAddress.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent identity fields used to derive routable email aliases.
+ */
+export type AgentEmailIdentityInput = {
+    readonly agentName: string;
+    readonly permanentId: string;
+    readonly fullname?: string | null;
+};
+
+/**
+ * Removes display-name syntax and plus tags, then lowercases an email address.
+ *
+ * This is also the canonical identity used for ad-hoc email users.
+ */
+export function normalizeEmailAddressForIdentity(value: string): string {
+    const emailAddress = extractEmailAddress(value).toLowerCase();
+    const separatorIndex = emailAddress.lastIndexOf('@');
+
+    if (separatorIndex === -1) {
+        return emailAddress;
+    }
+
+    const localPart = emailAddress.slice(0, separatorIndex).split('+', 1)[0] || '';
+    return `${localPart}@${emailAddress.slice(separatorIndex + 1)}`;
+}
+
+/**
+ * Creates all accepted local parts for an agent name or identifier.
+ *
+ * Both dotted (`john.doe`) and compact (`johndoe`) spellings are returned.
+ */
+export function createAgentEmailLocalParts(value: string): string[] {
+    const words = normalizeEmailWords(value);
+
+    if (words.length === 0) {
+        return [];
+    }
+
+    return [...new Set([words.join('.'), words.join('')])];
+}
+
+/**
+ * Creates the preferred, human-readable email address for an agent.
+ */
+export function createAgentEmailAddress(identity: AgentEmailIdentityInput, domain: string): string {
+    const localPart =
+        createAgentEmailLocalParts(identity.fullname || '')[0] ||
+        createAgentEmailLocalParts(identity.agentName)[0] ||
+        createAgentIdEmailLocalPart(identity.permanentId) ||
+        createAgentEmailLocalParts(identity.permanentId)[0];
+
+    return `${localPart}@${normalizeEmailDomain(domain)}`;
+}
+
+/**
+ * Creates every local part which should route to one agent.
+ */
+export function createAgentEmailAliases(identity: AgentEmailIdentityInput): string[] {
+    return [
+        ...new Set([
+            ...createAgentEmailLocalParts(identity.fullname || ''),
+            ...createAgentEmailLocalParts(identity.agentName),
+            createAgentIdEmailLocalPart(identity.permanentId),
+            ...createAgentEmailLocalParts(identity.permanentId),
+        ].filter(Boolean)),
+    ];
+}
+
+/**
+ * Normalizes a recipient local part for agent lookup while preserving plus tags for replies elsewhere.
+ */
+export function normalizeAgentEmailRecipientLocalPart(value: string): string {
+    const emailAddress = extractEmailAddress(value).toLowerCase();
+    const localPart = emailAddress.includes('@') ? emailAddress.slice(0, emailAddress.lastIndexOf('@')) : emailAddress;
+    return localPart.split('+', 1)[0] || '';
+}
+
+/**
+ * Extracts the mailbox from either a bare address or a display-name address.
+ */
+export function extractEmailAddress(value: string): string {
+    return value.match(/<\s*([^>]+?)\s*>/)?.[1]?.trim() || value.trim();
+}
+
+/**
+ * Normalizes a mail domain for comparisons and generated addresses.
+ */
+export function normalizeEmailDomain(value: string): string {
+    return value.trim().replace(/\.$/, '').toLowerCase();
+}
+
+/**
+ * Preserves the exact punctuation of an agent id when it is valid in an email local part.
+ */
+export function createAgentIdEmailLocalPart(value: string): string {
+    return value
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/\.{2,}/g, '.')
+        .replace(/^[.-]+|[.-]+$/g, '');
+}
+
+/**
+ * Converts a human name or identifier to ASCII email-local-part words.
+ */
+function normalizeEmailWords(value: string): string[] {
+    return value
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/g)
+        .filter(Boolean);
+}

package/apps/agents-server/src/utils/email/emailSystemAddresses.ts

@@ -0,0 +1,15 @@
+/**
+ * Mailboxes which are handled operationally instead of being routed to agents.
+ */
+export const EMAIL_SYSTEM_LOCAL_PARTS = [
+    'postmaster',
+    'dmarc-reports',
+    'tls-reports',
+] as const;
+
+/**
+ * Returns true when a normalized recipient belongs to a reserved operational mailbox.
+ */
+export function isEmailSystemLocalPart(localPart: string): boolean {
+    return EMAIL_SYSTEM_LOCAL_PARTS.some((systemLocalPart) => systemLocalPart === localPart);
+}

package/apps/agents-server/src/utils/email/findOrCreateEmailAdHocUser.ts

@@ -0,0 +1,94 @@
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { $getTableName } from '../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '../../database/schema';
+import { normalizeEmailAddressForIdentity } from './agentEmailAddress';
+
+/**
+ * Authentication marker for users created from inbound email.
+ */
+const EMAIL_AUTHENTICATION_PROVIDER = 'EMAIL';
+
+/**
+ * Non-login password marker for users created from inbound email.
+ */
+const EMAIL_PASSWORDLESS_USER_PASSWORD_HASH = 'email-passwordless-user';
+
+/**
+ * User fields added by the external-authentication migration but not present in the generated base schema.
+ */
+type EmailAdHocUserInsert = AgentsServerDatabase['public']['Tables']['User']['Insert'] & {
+    readonly email: string;
+    readonly displayName: null;
+    readonly authenticationProvider: typeof EMAIL_AUTHENTICATION_PROVIDER;
+};
+
+/**
+ * Finds or creates the passwordless ad-hoc user representing an email sender.
+ */
+export async function findOrCreateEmailAdHocUser(sender: string): Promise<{ readonly id: number; readonly email: string }> {
+    const email = normalizeEmailAddressForIdentity(sender);
+    const supabase = await $provideSupabaseForServer();
+    const tableName = await $getTableName('User');
+    const { data: existingUser, error: findError } = await supabase
+        .from(tableName)
+        .select('id, username')
+        .eq('username', email)
+        .maybeSingle();
+
+    if (findError) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to find the ad-hoc email user \`${email}\`.
+
+                **Cause:** \`${findError.message}\`
+            `),
+        );
+    }
+
+    if (existingUser) {
+        return { id: existingUser.id, email };
+    }
+
+    const now = new Date().toISOString();
+    const insertPayload: EmailAdHocUserInsert = {
+        username: email,
+        passwordHash: EMAIL_PASSWORDLESS_USER_PASSWORD_HASH,
+        isAdmin: false,
+        email,
+        displayName: null,
+        authenticationProvider: EMAIL_AUTHENTICATION_PROVIDER,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const { data: insertedUser, error: insertError } = await supabase
+        .from(tableName)
+        .insert(insertPayload)
+        .select('id, username')
+        .single();
+
+    if (!insertError && insertedUser) {
+        return { id: insertedUser.id, email };
+    }
+
+    if (insertError?.code === '23505') {
+        const { data: racedUser, error: raceFindError } = await supabase
+            .from(tableName)
+            .select('id, username')
+            .eq('username', email)
+            .single();
+
+        if (!raceFindError && racedUser) {
+            return { id: racedUser.id, email };
+        }
+    }
+
+    throw new DatabaseError(
+        spaceTrim(`
+            Failed to create the ad-hoc email user \`${email}\`.
+
+            **Cause:** \`${insertError?.message || 'The database did not return the created user.'}\`
+        `),
+    );
+}

package/apps/agents-server/src/utils/email/listAgentEmailIdentities.ts

@@ -0,0 +1,102 @@
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { $getTableName } from '../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+import { createAgentEmailAddress, createAgentEmailAliases } from './agentEmailAddress';
+
+/**
+ * Agent information shared by inbound routing, Stalwart synchronization, and administration screens.
+ */
+export type AgentEmailIdentity = {
+    readonly agentName: string;
+    readonly displayName: string;
+    readonly permanentId: string;
+    readonly visibility: 'PUBLIC' | 'PRIVATE' | 'UNLISTED';
+    readonly aliases: ReadonlyArray<string>;
+    readonly preferredEmail: string;
+};
+
+/**
+ * Lists every active agent and its accepted email aliases for the current server.
+ */
+export async function listAgentEmailIdentities(domain: string): Promise<AgentEmailIdentity[]> {
+    const supabase = await $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('Agent'))
+        .select('agentName, permanentId, agentProfile, visibility, deletedAt')
+        .is('deletedAt', null);
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to list agents for email routing.
+
+                **Cause:** \`${error.message}\`
+            `),
+        );
+    }
+
+    return (data || []).flatMap((row) => {
+        if (!row.permanentId) {
+            return [];
+        }
+
+        const displayName = resolveAgentDisplayName(row.agentProfile, row.agentName);
+        const identity = {
+            agentName: row.agentName,
+            permanentId: row.permanentId,
+            fullname: displayName,
+        };
+
+        return [
+            {
+                agentName: row.agentName,
+                displayName,
+                permanentId: row.permanentId,
+                visibility: row.visibility,
+                aliases: createAgentEmailAliases(identity),
+                preferredEmail: createAgentEmailAddress(identity, domain),
+            },
+        ];
+    });
+}
+
+/**
+ * Finds the agent addressed by a normalized email local part.
+ */
+export function findAgentEmailIdentity(
+    identities: ReadonlyArray<AgentEmailIdentity>,
+    normalizedLocalPart: string,
+): AgentEmailIdentity | null {
+    const matches = identities.filter((identity) => identity.aliases.includes(normalizedLocalPart));
+
+    if (matches.length <= 1) {
+        return matches[0] || null;
+    }
+
+    const permanentIdMatch = matches.find((identity) =>
+        createAgentEmailAliases({
+            agentName: '',
+            permanentId: identity.permanentId,
+        }).includes(normalizedLocalPart),
+    );
+
+    return permanentIdMatch || null;
+}
+
+/**
+ * Reads an agent's human-facing full name from the persisted profile.
+ */
+function resolveAgentDisplayName(agentProfile: unknown, fallbackAgentName: string): string {
+    if (!agentProfile || typeof agentProfile !== 'object' || Array.isArray(agentProfile)) {
+        return fallbackAgentName;
+    }
+
+    const meta = Reflect.get(agentProfile, 'meta');
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {
+        return fallbackAgentName;
+    }
+
+    const fullname = Reflect.get(meta, 'fullname');
+    return typeof fullname === 'string' && fullname.trim() ? fullname.trim() : fallbackAgentName;
+}