@chatcops/server 0.5.0 → 0.7.0

package/dist/handler.js

@@ -1,49 +1,204 @@
-import { createProvider, ConversationManager, AnalyticsCollector, toolToDefinition, } from '@chatcops/core';
+import { createProvider, isAIProvider, ConversationManager, AnalyticsCollector, ANALYTICS_EVENTS, BufferedEventSink, statsFromSink, createBudgetGuard, withDefaultBudgets, createRateLimiter, memoryStorage, describeInvalidRequest, errorBody, partsOf, PROTOCOL_VERSION, runTurn, statusForError, toLegacyChunk, toolRegistry, toolToDefinition, validateTools, consoleLogger, } from '@chatcops/core';
 import { chatRequestSchema } from './config.js';
+import { allowedOriginsOf } from './security/origin-policy.js';
+import { DEFAULT_SESSION_TTL_SEC, createSessions } from './security/sessions.js';
+import { logSecurityAtStartup } from './security/startup-checks.js';
 import { VISITOR_CONTEXT_INSTRUCTION, buildVisitorContext, isLocaleTag, withVisitorContext } from './visitor-context.js';
-import { RateLimiter } from './rate-limit.js';
 import { WebhookDispatcher } from './webhook.js';
+import { historyBefore, knowledgeContext } from './knowledge.js';
 export function createChatHandler(config) {
+    const log = config.logger ?? consoleLogger();
     if (config.i18n) {
-        console.warn('[chatcops] The `i18n` option is deprecated and ignored. Set the widget text with its `strings` option.');
+        log.warn('deprecated_option', 'The `i18n` option is deprecated and ignored. Set the widget text with its `strings` option.');
     }
-    const providerPromise = createProvider(config.provider);
-    const conversations = new ConversationManager({ store: config.conversationStore });
-    const rateLimiter = config.rateLimit ? new RateLimiter(config.rateLimit) : new RateLimiter();
-    const analytics = config.analytics ? new AnalyticsCollector() : null;
-    const webhooks = config.webhooks?.length ? new WebhookDispatcher(config.webhooks) : null;
+    const providerPromise = isAIProvider(config.provider)
+        ? Promise.resolve(config.provider)
+        : createProvider({ logger: log, ...config.provider });
+    // A failed setup (unknown provider type, SDK that throws on a missing key)
+    // is logged once here and reported to visitors per request below. Without
+    // this handler it would be an unhandled rejection and stop the process.
+    // Only the message is logged: SDK errors can carry the config or headers.
+    providerPromise.catch((err) => {
+        log.error('provider_setup_failed', `Provider setup failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    if (config.storage && config.conversationStore) {
+        throw new Error('Set `storage` or `conversationStore`, not both. `storage.conversations` replaces `conversationStore`.');
+    }
+    if (!config.storage && !config.conversationStore && onServerless() && !warnedMemoryStorage) {
+        warnedMemoryStorage = true;
+        log.warn('memory_storage', 'No `storage` is set, so conversations are kept in memory. On serverless each instance has its own memory, so a conversation can lose its history between messages. Use a store package such as @chatcops/store-postgres or @chatcops/store-redis.');
+    }
+    const storage = config.storage ?? (config.conversationStore ? { conversations: config.conversationStore } : undefined);
+    const conversations = new ConversationManager({ ...(storage ? { storage } : {}), logger: log });
+    // Counted in the storage's counters when it has them, so limits and
+    // budgets hold across every server instance; otherwise in this process.
+    // Nothing runs on a timer, which Workers don't allow at global scope.
+    const counters = (storage?.counters ?? memoryStorage().counters);
+    const budgets = withDefaultBudgets(config.budgets);
+    const budgetGuard = budgets ? createBudgetGuard(counters, budgets.budgets) : undefined;
+    if (budgets && !loggedBudgets) {
+        loggedBudgets = true;
+        log.info('budgets', describeBudgets(budgets.budgets, budgets.defaulted));
+    }
+    const rateLimit = { maxRequests: 30, windowMs: 60_000, ...config.rateLimit };
+    if (rateLimit.maxRequests <= 0)
+        throw new Error('maxRequests must be greater than 0');
+    const rateLimiter = createRateLimiter(counters, {
+        limit: rateLimit.maxRequests,
+        windowMs: rateLimit.windowMs,
+    });
+    // Events always count in this process, and go to the storage's event sink
+    // too when it has one, so stats can cover every instance.
+    const collector = config.analytics ? new AnalyticsCollector() : null;
+    const eventSink = config.analytics ? storage?.events : undefined;
+    const bufferedEvents = eventSink ? new BufferedEventSink(eventSink, { logger: log }) : undefined;
+    const analytics = collector
+        ? {
+            track(type, data) {
+                collector.track(type, data);
+                bufferedEvents?.track(type, data);
+            },
+        }
+        : null;
+    const webhooks = config.webhooks?.length ? new WebhookDispatcher(config.webhooks, undefined, log) : null;
     const toolDefs = config.tools?.map(toolToDefinition) ?? [];
-    const toolsByName = new Map((config.tools ?? []).map((tool) => [tool.name, tool]));
-    // Periodic cleanup
-    const cleanupInterval = setInterval(() => rateLimiter.cleanup(), 60_000);
+    // A broken tool definition is a code mistake, so fail here, at startup,
+    // rather than as a provider error on the first message.
+    validateTools(toolDefs);
+    const tools = toolRegistry(config.tools);
+    const sessions = createSessions(config, async (id) => {
+        const conversation = await conversations.getOrCreate(id);
+        const uid = conversation.metadata?.uid;
+        return { unused: conversation.messages.length === 0, ...(typeof uid === 'string' ? { uid } : {}) };
+    });
+    // A tier's budgets replace those scopes of the base ones; counts are shared.
+    // Built here so a mistake in one fails at startup.
+    const tierGuards = new Map(budgets
+        ? Object.entries(config.identity?.tiers ?? {}).map(([tier, tierBudgets]) => [
+            tier,
+            createBudgetGuard(counters, { ...budgets.budgets, ...tierBudgets }),
+        ])
+        : []);
+    const guardFor = (tier) => (tier && tierGuards.get(tier)) || budgetGuard;
+    if (!loggedSecurity) {
+        loggedSecurity = true;
+        logSecurityAtStartup({
+            allowedOrigins: allowedOriginsOf(config),
+            sessionSecrets: config.sessionSecrets,
+            sessionTtlSec: sessions ? (config.sessionTtlSec ?? DEFAULT_SESSION_TTL_SEC) : undefined,
+            requireSession: sessions?.required,
+            turnstile: Boolean(config.turnstile),
+        }, log);
+    }
+    const requests = { v1: 0, legacy: 0, 'ai-sdk': 0 };
     /**
-     * Streams one reply. Pass `options.signal` to stop when the visitor goes
-     * away: the provider request is cancelled, nothing more is yielded, and the
-     * partial reply isn't saved.
+     * Starts one reply. Resolves a refusal for a request that can't be
+     * answered (protocol v1 sends it as an HTTP status before any stream), or
+     * the reply as protocol v1 parts. The conversation stays locked until the
+     * parts are read to the end or `return()` is called on them.
      */
-    async function* handleChat(body, clientIp, options = {}) {
-        const { signal } = options;
-        const provider = await providerPromise;
-        // Validate request
+    async function startChat(body, clientIp, options = {}) {
+        const format = options.format ?? 'v1';
+        requests[format] += 1;
+        if (format === 'legacy' && !loggedLegacyFormat) {
+            loggedLegacyFormat = true;
+            log.info('legacy_stream_format', 'Answered a request in the 0.5 stream format, from a widget older than 0.6 or a client that doesn\'t send `protocol: 1`. That format keeps working until 1.0.');
+        }
         const parsed = chatRequestSchema.safeParse(body);
         if (!parsed.success) {
-            yield JSON.stringify({ error: 'Invalid request', details: parsed.error.flatten() });
-            return;
+            return refuse('invalid_request', { message: describeInvalidRequest(parsed.error) }, { error: 'Invalid request', details: parsed.error.flatten() });
         }
         const req = parsed.data;
-        // Rate limit
+        let user;
+        if (sessions) {
+            const session = await sessions.check(options.authorization, options.origin ?? null, req.conversationId);
+            if (!session.ok)
+                return refuse(session.code, { message: session.message }, { error: 'provider_error' });
+            user = session.claims?.uid ? { uid: session.claims.uid, tier: session.claims.tier } : undefined;
+        }
         if (clientIp) {
-            const limit = rateLimiter.check(clientIp);
+            const limit = await rateLimiter.check(clientIp);
             if (!limit.allowed) {
-                yield JSON.stringify({ error: 'rate_limit', retryAfter: limit.retryAfter });
-                return;
+                const retryAfterMs = limit.retryAfterMs ?? 1000;
+                // 0.5 widgets read seconds.
+                return refuse('rate_limited', { retryAfterMs }, { error: 'rate_limit', retryAfter: Math.ceil(retryAfterMs / 1000) });
+            }
+        }
+        let provider;
+        try {
+            provider = await providerPromise;
+        }
+        catch {
+            // Already logged where the provider was created.
+            return refuse('provider_unavailable', {}, { error: 'provider_error' });
+        }
+        // One reply per conversation at a time: a second request while a reply
+        // is being written would otherwise answer the same history twice.
+        const release = await conversations.acquireTurn(req.conversationId);
+        if (!release) {
+            return refuse('conversation_busy', {}, { error: 'provider_error' });
+        }
+        return { ok: true, parts: replyParts(provider, req, options.signal, clientIp, release, user) };
+    }
+    async function* replyParts(provider, req, signal, clientIp, release, user) {
+        const pendingWebhooks = new Set();
+        try {
+            for await (const part of reply(provider, req, signal, pendingWebhooks, clientIp, user)) {
+                // Tells the widget to get a session before its next request.
+                yield part.type === 'start' && sessions ? { ...part, capabilities: { ...part.capabilities, session: true } } : part;
             }
         }
-        // Get or create conversation
-        await conversations.getOrCreate(req.conversationId);
-        const conversationMessages = await conversations.getMessages(req.conversationId);
+        finally {
+            await release();
+        }
+        // Keeping the stream open until lead webhooks and analytics writes
+        // finish keeps serverless runtimes from cutting them off once the
+        // response ends. A failed analytics write is logged, never thrown.
+        await awaitPendingWebhooks(pendingWebhooks);
+        await bufferedEvents?.flush();
+    }
+    /**
+     * Analytics stats for `range` (default: the last 30 days), counted in the
+     * storage's event sink when it can be queried, so they cover every
+     * instance. Otherwise they come from this process only, as
+     * `getAnalytics()` does. `null` when `analytics` is off.
+     */
+    async function analyticsStats(range) {
+        if (!collector)
+            return null;
+        if (!bufferedEvents || !eventSink?.query)
+            return collector.getStats();
+        await bufferedEvents.flush();
+        const to = range?.to ?? Date.now() + 1;
+        return statsFromSink(eventSink, { from: range?.from ?? to - 30 * DAY_MS, to });
+    }
+    /**
+     * Streams one reply in the 0.5 format, as JSON strings. Pass
+     * `options.signal` to stop when the visitor goes away: the provider request
+     * is cancelled and nothing more is yielded.
+     */
+    async function* handleChat(body, clientIp, options = {}) {
+        const start = await startChat(body, clientIp, { ...options, format: 'legacy' });
+        if (!start.ok) {
+            yield JSON.stringify(start.legacy);
+            return;
+        }
+        yield* toLegacyStream(start.parts);
+    }
+    async function* reply(provider, req, signal, pendingWebhooks, clientIp, user) {
+        const conversation = await conversations.getOrCreate(req.conversationId);
+        const conversationMessages = conversation.messages;
+        // Pre-chat answers are kept from the first message on, so the widget
+        // doesn't have to send them again and they can't change mid-conversation.
+        const storedVisitor = conversation.metadata?.visitor;
+        const newVisitor = storedVisitor ? undefined : allowedUserData(req.userData, config.preChatFields);
+        const userData = storedVisitor ?? newVisitor;
         let assistantToReplace;
-        if (req.regenerate) {
+        if (typeof req.regenerate === 'object') {
+            const id = req.regenerate.assistantMessageId;
+            assistantToReplace = conversationMessages.find((message) => message.id === id && message.role === 'assistant');
+        }
+        if (req.regenerate && !assistantToReplace) {
             const userIndex = req.messageId
                 ? conversationMessages.findIndex((message) => message.id === req.messageId)
                 : findLastIndex(conversationMessages, (message) => message.role === 'user');
@@ -54,11 +209,25 @@ export function createChatHandler(config) {
                 assistantToReplace = [...conversationMessages].reverse().find((message) => message.role === 'assistant');
             }
         }
+        // A retry of a message that already has a finished reply (the network
+        // dropped after the server saved it) gets that reply again instead of a
+        // second one. A partial reply is replaced once the new one succeeds.
+        if (!req.regenerate && req.messageId) {
+            const index = conversationMessages.findIndex((message) => message.id === req.messageId && message.role === 'user');
+            const answer = index === -1 ? undefined : conversationMessages[index + 1];
+            if (answer?.role === 'assistant') {
+                if (answer.status === undefined || answer.status === 'complete') {
+                    yield* replay(answer, req.conversationId);
+                    return;
+                }
+                assistantToReplace = answer;
+            }
+        }
         // Track analytics
         if (analytics && conversationMessages.length === 0) {
-            analytics.track('conversation:started', { conversationId: req.conversationId });
+            analytics.track(ANALYTICS_EVENTS.conversationStarted, { conversationId: req.conversationId });
         }
-        analytics?.track('message:sent', { conversationId: req.conversationId });
+        analytics?.track(ANALYTICS_EVENTS.messageSent, { conversationId: req.conversationId });
         // Add user message unless this is a retry of the same message or a regenerate request that already has a user message
         const hasExistingUserMessage = req.messageId
             ? conversationMessages.some((message) => message.id === req.messageId)
@@ -76,134 +245,246 @@ export function createChatHandler(config) {
                 content: req.message,
                 timestamp: Date.now(),
             };
-            await conversations.addMessage(req.conversationId, userMessage);
+            // The signed-in user it belongs to, set once with the first message.
+            const metadata = {
+                ...(newVisitor ? { visitor: newVisitor } : {}),
+                ...(user && conversation.metadata?.uid === undefined ? { uid: user.uid } : {}),
+            };
+            await conversations.appendMessages(req.conversationId, [userMessage], Object.keys(metadata).length ? { metadata } : undefined);
         }
-        // Build system prompt
-        let systemPrompt = config.systemPrompt;
-        // Add knowledge context
+        // The system prompt is the operator's text and nothing else, so it's the
+        // same on every request and providers can cache it. Everything that
+        // changes per request goes in the context after it.
+        const context = [];
+        let sources = [];
         if (config.knowledge?.length) {
-            const contexts = await Promise.all(config.knowledge.map((k) => k.getContext(req.message)));
-            const combined = contexts.filter(Boolean).join('\n\n');
-            if (combined) {
-                systemPrompt += '\n\n' + combined;
-            }
+            const found = await knowledgeContext(config.knowledge, req.message, historyBefore(conversationMessages, req), signal);
+            if (found.context)
+                context.push(found.context);
+            sources = found.sources;
         }
         // Visitor-supplied page context and pre-chat answers never go into the
         // system prompt; see visitor-context.ts.
-        const visitorContext = buildVisitorContext(req);
-        if (visitorContext) {
-            systemPrompt += `\n\n${VISITOR_CONTEXT_INSTRUCTION}`;
-        }
+        const visitorContext = buildVisitorContext({ pageContext: req.pageContext, userData });
+        if (visitorContext)
+            context.push(VISITOR_CONTEXT_INSTRUCTION);
         if (req.locale && isLocaleTag(req.locale)) {
-            systemPrompt += `\n\nReply in the visitor's language. Their browser locale is ${req.locale}.`;
+            context.push(`Reply in the visitor's language. Their browser locale is ${req.locale}.`);
         }
-        // Get conversation messages for context
-        const storedMessages = await conversations.getMessages(req.conversationId);
+        // The history the model sees, trimmed to the token budget
+        const storedMessages = await conversations.getHistory(req.conversationId);
         const messages = withVisitorContext(assistantToReplace
             ? storedMessages.filter((message) => message.id !== assistantToReplace.id)
             : storedMessages, visitorContext);
-        // Stream response
-        let fullResponse = '';
-        const pendingEvents = [];
-        const pendingWebhooks = new Set();
-        try {
-            for await (const chunk of provider.chat({
-                messages,
-                systemPrompt,
-                tools: toolDefs.length > 0 ? toolDefs : undefined,
-                toolTimeoutMs: config.toolTimeoutMs,
-                maxTokens: config.maxTokens,
-                temperature: config.temperature,
-                signal,
-                toolExecutor: async (toolCall) => {
-                    const tool = toolsByName.get(toolCall.name);
-                    if (!tool) {
-                        return {
-                            success: false,
-                            message: `Unknown tool: ${toolCall.name}`,
-                        };
-                    }
-                    const result = await tool.execute(toolCall.input);
-                    if (tool.name === 'capture_lead' && result.success) {
-                        analytics?.track('lead:captured', { conversationId: req.conversationId });
-                        pendingEvents.push(JSON.stringify({
-                            leadCaptured: true,
-                            leadData: result.data,
-                        }));
-                        if (webhooks) {
-                            const delivery = webhooks
-                                .dispatch('lead:captured', {
-                                lead: result.data,
-                                conversationId: req.conversationId,
-                            })
-                                .catch((err) => {
-                                console.error('[chatcops] Webhook delivery failed:', err);
-                            })
-                                .finally(() => {
-                                pendingWebhooks.delete(delivery);
-                            });
-                            pendingWebhooks.add(delivery);
-                        }
-                    }
-                    return result;
-                },
-            })) {
-                if (signal?.aborted)
-                    break;
-                while (pendingEvents.length > 0) {
-                    yield pendingEvents.shift();
+        // The reply is saved as it grows: appended after the first tool round,
+        // updated after each one. A reply that fails before anything was saved
+        // isn't saved at all, so a failed regenerate keeps the old answer.
+        let saved = false;
+        const turn = runTurn({
+            provider,
+            messages,
+            systemPrompt: config.systemPrompt,
+            ...(context.length ? { systemContext: context.join('\n\n') } : {}),
+            ...(sources.length ? { sources } : {}),
+            tools,
+            conversationId: req.conversationId,
+            toolTimeoutMs: config.toolTimeoutMs,
+            maxTokens: config.maxTokens,
+            temperature: config.temperature,
+            exposeUsage: config.exposeUsage,
+            logger: log,
+            signal,
+            ...(budgetGuard
+                ? { budget: { guard: guardFor(user?.tier) ?? budgetGuard, context: { conversationId: req.conversationId, ...(clientIp ? { ip: clientIp } : {}) } } }
+                : {}),
+            onPart: (part) => {
+                if (part.type !== 'lead-captured')
+                    return;
+                analytics?.track(ANALYTICS_EVENTS.leadCaptured, { conversationId: req.conversationId });
+                if (!webhooks)
+                    return;
+                const delivery = webhooks
+                    .dispatch('lead:captured', { lead: part.lead, conversationId: req.conversationId })
+                    .catch((err) => {
+                    log.error('webhook_failed', 'Webhook delivery failed', { error: err });
+                })
+                    .finally(() => {
+                    pendingWebhooks.delete(delivery);
+                });
+                pendingWebhooks.add(delivery);
+            },
+            onPersist: async (message, { final }) => {
+                const complete = message.status === 'complete';
+                if (!saved) {
+                    if (final && !message.content && !message.parts?.length)
+                        return;
+                    // A reply the visitor walked away from is kept, marked `aborted`,
+                    // so the conversation shows what they saw (the model doesn't see
+                    // it). When regenerating, the old answer stands instead. A reply
+                    // that failed isn't kept.
+                    if (final && !complete && (message.status !== 'aborted' || assistantToReplace))
+                        return;
+                    await conversations.appendMessages(req.conversationId, [message]);
+                    saved = true;
                 }
-                fullResponse += chunk;
-                yield JSON.stringify({ content: chunk });
-            }
-            while (pendingEvents.length > 0) {
-                yield pendingEvents.shift();
-            }
+                else {
+                    await conversations.updateMessage(req.conversationId, message);
+                }
+                if (final && complete) {
+                    if (assistantToReplace)
+                        await conversations.removeMessage(req.conversationId, assistantToReplace.id);
+                    if (message.content)
+                        analytics?.track(ANALYTICS_EVENTS.messageReceived, { conversationId: req.conversationId });
+                }
+            },
+        });
+        let failure;
+        let next = await turn.next();
+        while (!next.done) {
+            const part = next.value;
+            if (part.type === 'error')
+                failure = part;
+            yield part;
+            next = await turn.next();
         }
-        catch (err) {
-            if (signal?.aborted) {
-                // The visitor left. Let lead webhooks finish, but write nothing else.
-                await awaitPendingWebhooks(pendingWebhooks);
-                return;
+        const result = next.value;
+        if (failure && result.status !== 'aborted') {
+            if (failure.code === 'budget_exceeded') {
+                log.warn('budget_exceeded', `The ${failure.scope ?? ''} budget is used up, so a reply was refused.`, { scope: failure.scope });
             }
-            console.error('[chatcops] Provider error:', err);
-            await awaitPendingWebhooks(pendingWebhooks);
-            yield JSON.stringify({ error: 'provider_error' });
-            return;
-        }
-        if (signal?.aborted) {
-            await awaitPendingWebhooks(pendingWebhooks);
-            return;
-        }
-        // Save assistant message
-        if (fullResponse) {
-            const assistantMessage = {
-                id: crypto.randomUUID(),
-                role: 'assistant',
-                content: fullResponse,
-                timestamp: Date.now(),
-            };
-            await conversations.addMessage(req.conversationId, assistantMessage);
-            if (assistantToReplace) {
-                await conversations.removeMessage(req.conversationId, assistantToReplace.id);
+            else {
+                log.error('provider_error', 'Provider error', { error: result.error });
             }
-            analytics?.track('message:received', { conversationId: req.conversationId });
         }
-        // The reply is finished for the visitor, so say so first. Keeping the generator
-        // open until lead webhooks finish keeps serverless runtimes from cutting
-        // them off once the response ends.
-        yield JSON.stringify({ done: true });
-        await awaitPendingWebhooks(pendingWebhooks);
+        // The visitor left, or the reply failed: let lead webhooks finish before
+        // the stream ends.
+        if (failure || result.status === 'aborted')
+            await awaitPendingWebhooks(pendingWebhooks);
     }
-    function cleanup() {
-        clearInterval(cleanupInterval);
+    /**
+     * Deletes conversations last updated more than `retention.conversationsDays`
+     * (default 30) days ago. Resolves how many, or `null` when the store can't
+     * purge.
+     */
+    async function purge(now = Date.now()) {
+        const store = storage?.conversations;
+        if (!store?.purge)
+            return null;
+        const days = config.retention?.conversationsDays ?? 30;
+        return store.purge(now - days * DAY_MS);
     }
+    /** Kept for compatibility: the handler no longer holds timers, so there's nothing to clean up. */
+    function cleanup() { }
     return {
         handleChat,
-        getAnalytics: () => analytics?.getStats() ?? null,
+        startChat,
+        purge,
+        /** How many requests asked for each stream format, to tell when 0.5 widgets are gone. */
+        /** Answers `POST /session`, or `undefined` when session tokens are off. */
+        startSession: sessions
+            ? (body, origin, clientIp) => sessions.mint(body, origin, clientIp)
+            : undefined,
+        protocolStats: () => ({ ...requests }),
+        /** Stats from this process only. `analyticsStats()` reads the storage's event sink. */
+        getAnalytics: () => collector?.getStats() ?? null,
+        analyticsStats,
         cleanup,
+        /** The logger the handler writes to, for adapters to use as well. */
+        logger: log,
     };
 }
+function refuse(code, options, legacy) {
+    return { ok: false, status: statusForError(code), error: errorBody(code, options).error, legacy };
+}
+/**
+ * Protocol v1 parts as 0.5 chunks (JSON strings). An error goes out last,
+ * after the turn has ended and lead webhooks have finished, as in 0.5.
+ */
+export async function* toLegacyStream(parts) {
+    let failure = null;
+    let aborted = false;
+    for await (const part of parts) {
+        if (part.type === 'error') {
+            failure = toLegacyChunk(part);
+            continue;
+        }
+        if (part.type === 'finish' && part.reason === 'aborted')
+            aborted = true;
+        const chunk = toLegacyChunk(part);
+        if (chunk)
+            yield JSON.stringify(chunk);
+    }
+    // Nobody is listening after an abort.
+    if (failure && !aborted)
+        yield JSON.stringify(failure);
+}
+/** A saved reply, sent again: the request was a retry of an answered message. */
+function* replay(message, conversationId) {
+    yield { type: 'start', protocol: PROTOCOL_VERSION, conversationId, messageId: message.id };
+    let texts = 0;
+    for (const part of partsOf(message)) {
+        if (part.type === 'text' && part.text) {
+            const id = `t${++texts}`;
+            yield { type: 'text-start', id };
+            yield { type: 'text-delta', id, delta: part.text };
+            yield { type: 'text-end', id };
+        }
+        else if (part.type === 'source') {
+            const { sourceId, url, title, snippet } = part;
+            yield { type: 'source', sourceId, url, ...(title ? { title } : {}), ...(snippet ? { snippet } : {}) };
+        }
+        else if (part.type === 'lead-captured') {
+            yield { type: 'lead-captured', lead: part.lead };
+        }
+    }
+    yield { type: 'finish', reason: 'stop' };
+}
+/** The pre-chat answers to keep: all of them, or only the configured fields. */
+function allowedUserData(userData, fields) {
+    if (!userData)
+        return undefined;
+    const kept = fields ? Object.fromEntries(Object.entries(userData).filter(([key]) => fields.includes(key))) : userData;
+    return Object.keys(kept).length ? kept : undefined;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Once per process (per isolate on Workers), not once per handler. */
+let warnedMemoryStorage = false;
+let loggedBudgets = false;
+let loggedSecurity = false;
+let loggedLegacyFormat = false;
+const SCOPE_LABELS = { conversation: 'per conversation', ip: 'per IP per day', global: 'per day in total' };
+function amount(value, unit) {
+    const short = value >= 1_000_000 ? `${value / 1_000_000}M` : value >= 1_000 ? `${value / 1_000}k` : String(value);
+    return `${short} ${unit}`;
+}
+/** The startup line, so the limits in force are never a surprise. */
+export function describeBudgets(budgets, defaulted = []) {
+    const scopes = [
+        ['conversation', budgets.perConversation],
+        ['ip', budgets.perIpPerDay],
+        ['global', budgets.globalPerDay],
+    ];
+    const parts = [];
+    for (const [scope, limit] of scopes) {
+        if (!limit)
+            continue;
+        const caps = [
+            ...(limit.tokens !== undefined ? [amount(limit.tokens, 'tokens')] : []),
+            ...(limit.messages !== undefined ? [amount(limit.messages, 'replies')] : []),
+            ...(limit.usd !== undefined ? [`$${limit.usd}`] : []),
+        ];
+        parts.push(`${caps.join(' and ')} ${SCOPE_LABELS[scope]}${defaulted.includes(scope) ? ' (default)' : ''}`);
+    }
+    const noTotal = budgets.globalPerDay ? '' : ' No daily total is set; `budgets.globalPerDay` caps your whole bill.';
+    return `Budgets: ${parts.join(', ')}.${noTotal} Set \`budgets\` to change them, or \`budgets: false\` to turn them off.`;
+}
+/** Vercel, AWS Lambda, Netlify and Cloudflare Workers, where memory doesn't last. */
+function onServerless() {
+    const env = globalThis.process?.env ?? {};
+    if (env.VERCEL || env.AWS_LAMBDA_FUNCTION_NAME || env.NETLIFY || env.K_SERVICE)
+        return true;
+    return globalThis.navigator?.userAgent === 'Cloudflare-Workers';
+}
 async function awaitPendingWebhooks(pendingWebhooks) {
     if (pendingWebhooks.size > 0) {
         await Promise.allSettled(Array.from(pendingWebhooks));